前言¶
让智能体读懂一个陌生代码库，常见做法是 grep 关键词、glob 找文件、再逐个 read——一轮下来工具调用十几次，上下文塞满文件片段，还不一定命中真正的调用链。
CodeGraph（@colbymchenry/codegraph）的思路不同：先把项目索引成代码知识图谱，之后按符号、按区域、按调用链查询，一次调用就能拿到相关符号的逐行源码和调用路径。问题是，CLI 工具模型自己调不到，得有人把它包装成模型可见的原生工具。
本文介绍的 dsh-codegraph 就是做这件事的 DSH 插件。
这是什么¶
jiangzhenguo/dsh-codegraph 是一个可一键安装的 DSH 插件（bundle），把 codegraph CLI 包装成 13 个 codegraph_* 原生工具，让 DSH 会话直接查询预索引代码知识图谱，并支持自举和维护索引（init/index/sync）。当前版本 1.1.0，许可证 MIT。
提供的工具¶
13 个工具与 codegraph CLI 命令一一对应，工具名与 CodeGraph 官方 MCP 工具同名：
| 工具 | 对应 CLI | 用途 |
|---|---|---|
codegraph_status |
status --json |
索引状态（是否已初始化、文件/节点/边数、待同步变更等） |
codegraph_init |
init |
初始化项目并建立初始索引（.codegraph/） |
codegraph_index |
index |
全量（重）索引 |
codegraph_sync |
sync |
增量同步索引 |
codegraph_uninit |
uninit -f |
删除项目索引 |
codegraph_query |
query --json |
按名称/子串搜索符号，返回结构化 JSON |
codegraph_node |
node |
单个符号源码 + 调用/被调用轨迹 |
codegraph_explore |
explore |
自然语言探索一块代码区域，返回相关文件源码与调用路径 |
codegraph_files |
files --json |
索引内的项目文件结构 |
codegraph_callers |
callers --json |
谁调用了某个符号 |
codegraph_callees |
callees --json |
某个符号调用了什么 |
codegraph_impact |
impact --json |
改动某个符号会波及哪些代码 |
codegraph_affected |
affected --json |
改动若干源文件后应运行哪些测试文件 |
默认只注册 4 个核心工具：codegraph_status / codegraph_init / codegraph_sync / codegraph_explore。这个裁剪借鉴了上游项目的实测结论——codegraph_explore 是唯一稳定赢得模型调用的工具，官方 MCP server 默认也只暴露 explore。工具列表精简，引导才集中。需要全部 13 个工具时，配置 surface: 'full'。
装上即生效的提示词引导¶
只把工具放出来还不够，模型可能仍走 grep 反射路径。插件会在系统提示词注入一条高优先级指引（tool:codegraph，order: 98），而 DSH 内置文件工具的指引集中在 order 100–104（read=100、write=101、edit=102、glob=103、grep=104）。指引放在 98，先于它们被模型看到。
指引内容采用上游验证过的策略：命令式措辞（MUST use codegraph_explore INSTEAD of grep/glob/read）、反模式清单（不要先 grep「找文件」，不要用 grep 复核 codegraph 结果——它来自完整 AST 解析），以及未索引项目的硬停止规则：不自行初始化时，本会话不再调用 codegraph 工具，索引与否是用户的决定。
frontload：把上下文先送进当前 turn¶
提示词指引仍是软性的。所以插件实现了 frontload 前置注入——上游实测最有效的采用率手段：
- 插件监听
agent/inbox/inserted事件，当真实用户 prompt 进入 agent 的 next-turn 收件箱时做置信度分级门控：含结构性关键词（如「调用 / 重构 / 依赖 / how does / who calls / refactor / trace」）直接触发；含代码形态 token（文件名、camelCase、PascalCase、snake_case）则先用codegraph query对照索引验证是真实符号才触发；其余 prompt 零开销静默跳过。 - 触发后在会话 cwd 向上找最近的
.codegraph/索引根，找不到就静默跳过——插件不擅自 init。 - 预跑
codegraph_explore，把结果以<codegraph_context>包裹注入当前 turn，上限 12000 字符。模型反射性要 grep/read 的内容已经在上下文里了。
安全性上有三条保证：所有失败路径（无索引、门控未命中、CLI 报错）都是静默 no-op，不会弄坏用户 prompt；注入内容带标记，不会触发自身循环；同文 prompt 在 10 分钟内重复进入收件箱（GUI 重发、step 被拒后重新入队）只注入一次。可用 frontload: false 整体关闭。
和会话级 MCP server 的区别¶
codegraph 官方 MCP server 在工作区未建立索引时暴露 0 个工具，并提示模型不要自己索引。本插件始终暴露工具，包括模型自举和维护索引所需的 init/index/sync，这是它选择 bundle 形态而非 MCP 的原因。
安装与启用¶
前置要求两项：已安装 DSH（本插件为 DSH bundle，随 DSH web 应用装载）；codegraph CLI 在 PATH 上且版本 ≥ 1.0：
npm i -g @colbymchenry/codegraph
codegraph --version # 确认可用（≥ 1.0）
然后在目标 profile（这里是 web）一条命令安装：
dsh plugin --profile web add github:jiangzhenguo/dsh-codegraph
这条命令做了什么：dsh plugin 在 profile 目录里跑 pnpm add github:jiangzhenguo/dsh-codegraph；因为本包的 package.json 声明了 dsh.bundle.patch，DSH 的 plugin 管理器会把它自动加入 profile 的 dsh.profile.bundles 层栈，不需要手动改配置。重启 DSH 应用后，任意会话里模型即可看到 codegraph_* 工具（默认 core 面 4 个）。其他 profile 换成 --profile tui 等即可。README 另提到，若已发布到 npm，可用包名替换命令开头的 github:。
卸载：
dsh plugin --profile web remove dsh-codegraph
配置在组合层（如 cordis.patch.yml 的 insert 行）传入：
- insert:
- id: dsh-codegraph
name: dsh-codegraph
require: dsh-codegraph
config:
guideSearch: true # 默认 true：注入系统提示指引；false 只注册工具
surface: core # 默认 core（4 个工具）；设为 full 注册全部 13 个
frontload: true # 默认 true：结构化 prompt 自动前置注入
典型用法¶
- 在项目目录（cwd = 项目根）开一个新的 DSH 会话。
- 让模型先跑
codegraph_status：未初始化则跑codegraph_init。 - 之后用
codegraph_explore查代码，一次调用返回相关符号源码 + 调用链；surface: 'full'下还可用codegraph_query/codegraph_node/codegraph_callers/codegraph_callees/codegraph_impact做更细的查询。 - 改动代码后用
codegraph_sync，需要跑测试时用codegraph_affected（full surface）。
所有工具默认作用于调用方会话的 cwd，也可显式传 path 指向其他项目。
插件自带运行时测试 harness（test/run-plugin-test.mjs，真实 codegraph CLI + 桩 cordis 服务），覆盖提示词注入顺序、core/full surface 的工具注册、frontload 的注入与去重等路径。在装好插件的 profile 里运行：
CG_PROFILE_NM=<profile>/node_modules node test/run-plugin-test.mjs
适用场景与注意¶
适合的项目形态：代码库较大、模型频繁需要按调用链理解代码的 DSH 用户；重构、改名前想确认波及面，或改动后想确定该跑哪些测试的场景。前提是愿意为项目建立并维护 .codegraph/ 索引。
几个值得知道的点：
- 在本机
codegraph@1.0.1上，callers/callees返回空数组是 CLI 侧的数据/索引特性（该版本调用图边未解析到），插件忠实返回 CLI 真实输出；impact已能返回真实的受影响节点与边。 - 未索引项目时插件不会擅自
init，是否索引由用户决定，指引里含对应的硬停止规则。 - frontload 的所有失败路径均为静默 no-op，不影响普通 prompt 的处理。
安全提示：插件以当前 dsh 进程的权限运行，安装前建议检查其源码与许可证（本项目为 MIT），确认可接受再装入常用 profile。
结尾¶
dsh-codegraph 把「预索引、按调用链查代码」这条路径接进了 DSH：默认 4 个核心工具保持工具面精简，order 98 的提示词指引和 frontload 前置注入负责让模型真的用起来，而不是多挂几个无人问津的工具。
- 目录页：https://www.skillhub.cn/plugins/jiangzhenguo/dsh-codegraph
- GitHub：https://github.com/jiangzhenguo/dsh-codegraph
