前言¶
在 DeepSeek Harness（DSH）里做代码相关任务时，Agent 往往只能靠 grep、glob 猜关键词，尤其在「用中文描述行为、答案藏在英文标识符里」的场景，容易反复试探仍定位失败。社区插件 dsh-coderag（维护者 VermilionPasvikin）以 MCP 服务器形态提供只读的代码库检索：建索引、按自然语言或标识符查符号，返回文件路径、行号与符号名，供 Agent 再按行读原文。下面介绍它的能力、安装步骤与使用注意。
这是什么¶
dsh-coderag 是给 DSH 用的代码库检索引擎，默认不联网、不采集遥测；只读代码，不改仓库。插件通过 Cordis patch 向 Agent 暴露 4 个固定 MCP 工具（DSH 侧名称带 mcp__coderag__ 前缀）：
| 工具 | 作用 |
|---|---|
code_search |
按自然语言或标识符检索，返回文件路径、行号、符号名 |
code_outline |
单文件的符号大纲 |
code_index |
建立或刷新索引，立即返回 taskId，后台执行 |
index_status |
查看索引状态与跳过统计 |
索引落在工作区 <工作区>/.coderag/index.sqlite3，采用 SQLite FTS5、中文 bigram，并用 tree-sitter 按函数/类/接口等边界分块；支持增量索引。检索使用 BM25，同一批命中按源码顺序输出，便于模型按行号读文件。索引未就绪、无结果或后端不可用时，会返回结构化 status，避免 Agent 把「没查到」误当成「不存在」。
当前发布版本为 2.1.1（仅 GitHub tag/release，无 PyPI/npm 包）。SkillHub 分类为「联网工具」；项目自述侧重本地索引与检索。
核心功能（已文档说明的部分）¶
- 索引与安全：三层过滤（内置密钥黑名单、
.gitignore/.coderagignore、内容级正则），命中 chunk 不入库，跳过原因对模型可见（skipped: {count, reasons}）。 - 检索策略：召回精度递进（全词元 → 仅标识符 → 含 CJK bigram）；纯标点/过短符号查询会提示改用
grep，避免全表扫描。 - 异步与预算：
code_index立即返回、后台建索引（规避工具调用约 60 秒超时）；单次检索有 token 预算，超出部分会报告省略条数。 - 实测对比（README 口径）：在 DSH 源码副本上 13 个「找代码」任务、各 3 次会话的对比中，仅多挂本插件 patch 的一组任务成功率由约 28.2% 升至约 82.1%；「用中文问、答案在英文代码里」的定位/跨文件类尝试改善明显，直查标识符类未变差。样本偏检索型题目，不宜直接外推为全量提问的提升幅度；详见仓库
eval/runs/报告。
安装与启用¶
前置：Python 3.10–3.12、已安装 DSH、Git。README 注明 macOS、Windows 10 已实测；Linux 尚未实测，项目不声称支持 Linux。
安装需克隆仓库（cordis.patch.yml 在仓库内），不能使用 pip install dsh-coderag 或 npm i dsh-coderag。
macOS / Linux（POSIX）¶
先进入希望存放仓库的目录，再执行：
cd ~
git clone https://github.com/VermilionPasvikin/dsh-coderag.git
cd dsh-coderag
bash scripts/install.sh
自检引擎（不涉及 DSH）：
"$CODERAG_PYTHON" -m dsh_coderag doctor
"$CODERAG_PYTHON" -m dsh_coderag index /path/to/repo
"$CODERAG_PYTHON" -m dsh_coderag search "用户令牌在哪里校验" --root /path/to/repo
挂到 DSH 的 web profile 并确认：
./scripts/dsh plugin --profile web add .
./scripts/dsh --profile web --dump-config | grep -A2 '== dsh-coderag'
期望输出中出现 # == dsh-coderag 与 id: mcp-coderag。启动：
./scripts/dsh --profile web
受限网络可在安装依赖时使用：CODERAG_PIP_ARGS="--index-url <镜像>" bash scripts/install.sh。
Windows（PowerShell）¶
需使用真实 Python 3.10–3.12（可用 py -0p 查看），并确认当前使用的 DSH profile（桌面版多为 desktop）。克隆、安装与验证示例：
git clone https://github.com/VermilionPasvikin/dsh-coderag.git
Set-Location dsh-coderag
& $py -m pip install .
& $py -m dsh_coderag doctor
$repo = "C:\path\to\your\repo"
& $py -m dsh_coderag index $repo
& $py -m dsh_coderag search "用户令牌在哪里校验" --root $repo
将 CODERAG_PYTHON 写入 profile 的 cordis.patch.yml 更可靠（桌面版快捷方式通常继承不到终端环境变量）。修改 profile 前需完全退出 DeepSeek Harness 桌面版，否则 dsh plugin add 可能被拒绝。再用本机 dsh.cmd 或全局 dsh：
& $dsh plugin --profile $profile add .
详细 Windows 路径与 ZIP 离线解压说明见 GitHub README。
典型用法¶
- Agent 侧：在工作区对话中先触发
code_index（或 CLI 预建索引），用index_status确认就绪，再用code_search查行为描述或符号；需要单文件结构时用code_outline。 - CLI 侧（调试或与 DSH 无关的批处理）：
dsh_coderag index <repo>、dsh_coderag search "<query>" --root <repo>，与 MCP 共用同一套索引目录。
大仓库首次索引在后台进行；文件数超过上限时会显式失败并报告实际数量。
适用场景与注意¶
适合：中大型仓库里「描述行为找实现」「跨文件跟链路」、中英文混查检索；希望减少 Agent 盲目 grep 的会话。
务必阅读的安全声明（README 原文要点）：安装本插件等于授予其与当前 DSH 进程相近的本机权限；DSH 的 read-only / workspace-write / danger-full-access 不约束插件。请只在信任的仓库与本机上安装，安装前阅读源码与 MIT 许可证。
插件默认不联网；索引与查询均在本地完成。
结尾¶
dsh-coderag 把「语义 + 结构」检索做成 DSH 可调用的 MCP 工具，与 grep 互补：复杂定位交给检索，精确符号仍可直接查。目录与详情可在 SkillHub 与 GitHub 查看：
- 目录页：https://www.skillhub.cn/plugins/VermilionPasvikin/dsh-coderag
- 仓库：https://github.com/VermilionPasvikin/dsh-coderag
