dsh-code-index
English | 中文
语义仓库索引 —— 一个 DeepSeek Harness(dsh)插件,为 agent 提供代码库地图:基于 tree-sitter 的符号索引、带排名的符号搜索,以及注入到系统提示词里的限量自动更新仓库地图。
填补了一个真实的生态缺口:检索 dsh-plugin 话题(2026-08)会发现 git/语音/浏览器/记忆类插件琳琅满目,但缺少原生、模型可用的代码索引 / 仓库地图能力——也就是 aider 的 repo-map 和 Cursor 的 @Codebase 为各自 agent 提供的同类能力。
模型能得到什么
| 工具 | 用途 |
|---|---|
code_index | 查看 / (重)建当前工作区的索引 |
code_symbols | 列出符号(函数、类、接口、类型、方法……),带 file:line——支持按名称、路径、类型、是否导出过滤 |
code_search | 排名检索:精确 > 前缀 > 子串,导出优先,带相关度分数与 file:line |
code_map | 限量排名仓库地图(按符号密度取核心文件 + 关键符号与行号) |
外加一个可选的自动注入系统提示词段(code-index:repo-map,序 60):默认工作区的精简排名地图,60 秒 TTL 自动刷新。将 autoInject: false 可关闭,只依赖 code_map 工具。
安装
需要 dsh(任意安装方式——npx、npm 或源码)与 Node ≥ 22。
# 从 npm(预编译)
npx @deepseek-ai/dsh plugin --profile web add dsh-code-index
# 或从包含本仓库检查副本的目录
npx @deepseek-ai/dsh plugin --profile web add ./dsh-code-index重启 Web UI(npx @deepseek-ai/dsh web)——启动日志会确认每个工具:
[dsh-code-index] plugin loaded
[dsh-code-index] registered tool: code_index
...不启动即可核对组合配置:dsh --profile web --dump-config。
使用
在工作区会话中,向 agent 提这类请求:
- "我们现在在哪个仓库?先跑 code_map。"
- "找出所有名字含
parse的函数及其位置。" - "列出 src/core 里的导出符号。"
- "重建代码索引。"
*索引*本身不需要 API key;模型当然要配置好才能调用这些工具。
示例(输入 → 输出)
用户提示:
> 我们现在在哪个仓库?先跑 code_map,然后找出 extractSymbols 定义在哪。
agent 依次调用工具:
code_map
# repo map
## src/extract.ts (14)
function extractSymbols(code, id) :121
function languageForFile(filePath) :37
...
code_search { query: "extractSymbols" }
export function extractSymbols(code, id) — src/extract.ts:121索引在首次使用时惰性构建;后续调用由磁盘缓存提供,并按 mtime 增量刷新。
配置
选项通过插件行的 config 在 profile 补丁中传入(缺省时使用默认值):
# $DSH_HOME/profiles/<name>/cordis.patch.yml —— 裸行按 id 覆盖。
- id: code-index
config:
excludeDirs: [generated, playground]
mapTopFiles: 30
mapMaxChars: 4000
autoInject: true| 键 | 默认 | 含义 |
|---|---|---|
excludeDirs | [] | 追加到内置排除列表(node_modules、.git、dist、build、out、coverage、.next、.nuxt、.cache、target、vendor……)之外的额外目录 |
mapTopFiles | 24 | 排名地图中的最大文件数 |
mapMaxChars | 3200 | 渲染地图的硬性字符上限 |
autoInject | true | 是否注册系统提示词段 |
支持的语言
TypeScript + JavaScript + Python(.ts .tsx .mts .cts .js .jsx .mjs .cjs .py .pyi),通过 tree-sitter WASM 解析——纯解析,无需原生编译。符号提供方的接缝(src/extract.ts + 语法文件)预留了后续接入其他语言/嵌入检索的位置。
工作原理
- 索引构建(
src/buildIndex.ts):递归扫描(应用排除规则),逐文件 tree-sitter 提取(src/extract.ts),JSON 缓存置于<repo>/.dsh-code-index/,按 mtime 增量刷新(只有被改动的文件才重新解析)。 - 搜索(
src/search.ts):纯打分——精确1/ 前缀0.8/ 子串0.5,导出加权,名称序平局裁决。 - 仓库地图(
src/repomap.ts):密度感知的文件打分(class/interface/function 加权,轻微反膨胀),取 Top-N 文件,每文件符号上限,硬截断。 - 工作区解析:每个工具解析会话 cwd(
agent.session.header.cwd)并向上查找最近的.git(有界——没有仓库标记的目录绝不会被索引)。
已知限制
- web-tree-sitter 固定为
^0.20.8—— 新版本期望 dylink 语法的 wasm,而tree-sitter-wasms提供静态构建;此组合在 Node ≥ 22/24 下验证可用。 - 自动注入段针对默认工作区(启动目录,与 headless/CLI 模式一致)。多工作区 Web UI 会话应使用
code_map/code_symbols(它们按会话 cwd 解析)。 - 局部变量也会被索引——召回优先于精确;
code_search的排名会压低它们。 - 开发者预览版 harness:上游 harness/插件 API 大概率有破坏性变更。
开发
pnpm install
pnpm test # vitest —— 提取器、扫描、缓存、搜索、仓库地图(35 项测试)
pnpm typecheck
pnpm build # tsup → dist/index.js(ESM,外部依赖)许可证
MIT。与 DeepSeek 无关;基于公开的 dsh 插件接口构建。