dsh-code-ctx：给 AI agent 的代码库上下文引擎

前言¶

DeepSeek Harness（DSH）采用「一切皆插件」的架构，开发者可以在运行时扩展宿主能力。在编写 AI agent 时，常见瓶颈不是模型推理速度，而是「该读哪些文件」：读全仓库会撑爆上下文，只看当前文件又容易漏掉关键依赖。dsh-code-ctx 插件把「读哪些文件」从 O(全仓库) 降到 O(top-k)，让 agent 在有限上下文内精准定位目标代码。

插件简介¶

dsh-code-ctx 是一个 DSH 插件，归类为「记忆」，由维护者 y2187218823 开发。它为 AI agent 提供代码库上下文检索能力：给定一句自然语言查询，返回最相关的文件与函数。它同时注册成 agent 工具、提供斜杠命令与 HTTP 接口，无需额外编写逻辑即可集成到 DSH 工作流。

核心功能¶

• 代码检索：接收自然语言查询，返回 top-k 个最相关文件（默认 8 个）。检索采用 BM25 + 符号名加权 + 依赖图扩散三个信号。
• Agent 工具：在 DSH agent 中可直接调用 repo_search，agent 可根据判断自行触发。
• 斜杠命令：在终端输入 /ctx <问题> 即可手动查询。
• HTTP 接口：提供 RESTful 查询与重建接口，方便外部系统集成。
• 索引管理：支持 /ctx build 强制重建索引，以及 POST /dsh-code-ctx/index 接口。

安装与启用¶

在 PowerShell 中执行以下命令安装插件：

dsh plugin --profile desktop add file:D:/path/to/code-ctx

安装后重启 DSH，插件自动生效。

配置索引根目录¶

索引根目录按优先级解析：

1. 请求参数 ?root=
2. 环境变量 DSH_CODE_CTX_ROOT
3. $DSH_HOME/code-ctx/config.json 的 {"root": "..."}
4. 宿主进程 cwd

重要：桌面版宿主的 cwd 通常不是你的项目目录，索引会是空的。务必配置第 3 条，例如在 code-ctx/config.json 中指定 "root": "/path/to/your/project"。

典型用法¶

1. 在 agent 中调用¶

在 DSH agent 的配置或对话中，可以直接调用 repo_search 工具：

repo_search("notify session 过滤")
  → src/host/notify-events.ts:53-60   shouldNotifySession   (22.07)  [bm25 + 符号名 + 路径]
  → src/host/notify-events.ts:91-123  reduceNotifyFrame     (16.20)  [bm25 + 符号名 + 依赖图]

agent 会根据工具返回的文件与函数，决定是否读取相关代码块。

2. 使用斜杠命令¶

在终端中输入：

/ctx websocket hmr

返回与查询相关的文件与函数。

3. HTTP 查询¶

GET /dsh-code-ctx/search?q=websocket+hmr

返回 JSON 格式的检索结果。

4. 索引状态与重建¶

查看当前索引状态：

GET /dsh-code-ctx/stats

强制重建索引：

/ctx build

或通过 HTTP 接口：

POST /dsh-code-ctx/index

5. 离线 CLI 使用（可选）¶

插件提供 CLI 工具，可完全脱离 DSH 使用：

node bin/cli.js index <仓库路径> --out .code-ctx/demo.json
node bin/cli.js search "websocket hmr" --index .code-ctx/demo.json --top 8

工作原理¶

检索流程分为索引与查询两步：

1. 索引阶段：遍历文件 → 按符号切块 → 词元统计 + 依赖图 → 索引
2. 查询阶段：查询 → BM25 → 符号名/路径加权 → 依赖图扩散 → 排序去重

三个信号叠加：
- BM25：代码内容语义
- 符号名加权：函数/类名精确匹配优先
- 依赖图扩散：正向 import + 反向被 import 带出相关文件

设计决策与已知局限¶

• 不做向量检索（默认）：实测加入 all-MiniLM-L6-v2 只提升约 3.3 个百分点，代价是索引时间增加、依赖体积膨胀，且权重过高会冲掉精确标识符匹配。向量只能作为辅助。
• 测试/类型声明降权：避免 .d.ts 或测试文件因关键词多而挤占真实实现文件。
• 排除构建产物：lib/、dist/、build/、out/ 等目录在索引时排除，避免同一函数在多个产物中重复出现。
• 评测口径：以 commit message 为查询、以「这次改了哪些文件」为标准答案。在 vite 项目 110 条 commit 上测试，hit@8 达 0.809，即 top-8 命中一个真实改动文件的概率为 81%。
• 已知局限：正则切块在字符串/注释中的花括号处理有限，超长函数可能切歪；零词面重叠的语义查询召回有限；当前不支持增量索引，每次全量重建；评测存在系统性偏差（commit message 与用户措辞分布不同）。

适用场景与注意¶

• 适合需要精准定位代码文件的 DSH agent 开发场景，尤其是多文件项目。
• 插件以 DSH 进程权限运行，安装前应检查源码与许可证（MIT）。
• 建议为桌面版配置 config.json 中的 root 字段，避免索引为空。

小结¶

dsh-code-ctx 通过 BM25 + 符号名 + 依赖图三重信号，将代码检索从 O(全仓库) 降到 O(top-k)，让 AI agent 在有限上下文中快速锁定目标文件与函数。对于需要处理复杂代码库的 DSH 用户，这是一个实用且可控的上下文增强工具。

更多信息¶

• 插件目录页：https://www.skillhub.cn/plugins/y2187218823/dsh-code-ctx
• GitHub 仓库：https://github.com/y2187218823/dsh-code-ctx