代码图谱工具 mirelconstantin/dsh-codegraph-tools

dsh-codegraph-tools

CodeGraph 做成九个原生 DeepSeek Harness 工具。一次调用就能拿到代码库的符号、调用路径和影响范围，不用再靠 grep、glob 和读文件一点点爬。

安装

1. 安装 CodeGraph 命令行。 它是另一个项目，这个插件只是驱动它，并不把它打包进来：

npm i -g @colbymchenry/codegraph

2. 添加插件。 在 GUI 的 Add plugin 输入框里填：

dsh-codegraph-tools

或者在终端里执行，这里必须指定配置档名：

dsh plugin add dsh-codegraph-tools --profile desktop

其他方式

| 方式 | 命令 |
| 锁定版本 | dsh plugin add dsh-codegraph-tools@1.0.0 --profile desktop |
| 锁定 commit | dsh plugin add github:mirelconstantin/dsh-codegraph-tools#<sha> |
| Tarball | dsh plugin add ./dsh-codegraph-tools-1.0.0.tgz |
| 本地检出 | dsh plugin add /absolute/path/to/dsh-codegraph-tools |

就这些。第一次使用时，工具会自己建好项目索引——大仓库首次构建要花几分钟，之后每次调用都很快。不想付这个代价，就设 autoInit: false；这时工具会返回 not-initialized，并告诉你该用哪条命令来构建。

工具

| 工具 | 用途 |
| codegraph_explore | 一次调用回答关于这个代码库的问题：相关符号的源码、它们之间的调用路径，还有影响范围摘要。问「X 是怎么工作的」，从这里开始 |
| codegraph_search | 按名字找符号，拿到它的类型、文件和行号。读源码之前，先用它确认准确的名字 |
| codegraph_node | 读某个符号的源码，带行号，外加谁调用它、它调用谁。传文件路径则改为读该文件 |
| codegraph_callers | 改一个符号之前，先看谁调用它 |
| codegraph_callees | 看一个符号调用了谁，顺着一条调用路径往外跟 |
| codegraph_impact | 一个符号传递依赖上的全部下游。改代码之前调用 |
| codegraph_affected | 哪些测试文件依赖你刚改过的文件。改完之后调用，这样你只跑四个测试，而不是整套 |
| codegraph_files | 这个项目的索引里实际有什么 |
| codegraph_status | 项目有没有建索引、多大、什么时候建的。用 init: true 构建 |
每个工具都接受可选的 path。它默认指向会话的工作目录，其次指向 defaultRoot。

为什么这样设计

是受管子进程，不是 MCP 服务器。 codegraph serve --mcp 服务器持有按项目划分的写入锁，所以第二个客户端要么通过共享守护进程代理，要么拒绝启动——一个会重新加载插件的 harness 会在每个会话的整个生命周期里和这把锁较劲。于是改为每条命令运行一个受管子进程，走 harness 自己的 subprocess 接缝：argv 加 JSON，仅此而已。库方案也被否决了，因为它的 node:sqlite 路径要求宿主里的 Node >= 22.5。

被拒绝的查询绝不会从另一个项目得到回答。 status 会沿目录树向上查找索引，所以一个自己没有索引的项目会解析到祖先的图，并把它当成自己的来报告——一个看起来正确的错误答案。索引目录会和项目自己拥有的那个做比对，遇到外来的就报告，而不是采用。

过期的索引要用能刷新它的命令来刷新。 init 构建缺失的索引，别的什么都不做。sync 应用索引还没见过的变更。用错命令会静默地什么都不做，所以要根据项目已有的东西来选命令。

失败是一个值，不是异常。 抛出的错误到达模型时只是一个字符串，它无法据此分支。这里的每个失败都带一个冻结的 outcome——not-initialized、writer-locked、cli-missing、timed-out、no-results、bad-request、unknown——以及解决它的动作，系统提示词里的一节会教模型每个值是什么意思。

上游的八种行为，全部在 CodeGraph 1.6.2 上实测：

| 行为 | 忽略它会怎样 |
| 对未初始化的项目执行 status --json 退出码是 0 | 每个未初始化的项目看起来都像成功 |
| status 会沿目录树向上查找索引 | 查询从祖先的图得到回答 |
| 对已有索引的项目执行 init 会说 "Already initialized" 并退出 0 | 过期的索引永远得不到刷新 |
| 对没有索引的项目执行 sync 什么都不做 | init: true 会在 not-initialized 上无限循环 |
| 零匹配会以散文形式回答，退出码为 0 | 空答案被读成 CLI 坏了 |
| callers/callees 把被查询的符号放在 targets 下 | 工具返回的是你问的那个符号 |
| Windows 上的 npm shim 是 .cmd，spawn 拒绝它 | 每次调用都以 ENOENT 失败，而它「在我终端里是好的」 |
| Windows 会先解析子进程的 cwd，再解析它的可执行文件 | app.asar 路径会以 spawn <valid exe> ENOENT 失败 |

配置

每个默认值都在 src/config.js 里。cordis.patch.yml 只声明安装时覆盖的内容，而一个正在运行的宿主没听说过的键是加载失败，不是向前兼容的变更——所以往那里加一行时，必须同时加上它在 CONFIG_DEFAULTS 里的条目。

| 键 | 默认值 | 含义 |
| cliPath | '' | 可执行文件的绝对路径。留空则使用 PATH 上的那个 |
| defaultRoot | '' | 调用和会话都没指定项目时使用的项目 |
| autoInit | true | 构建或刷新索引，而不是只读取索引 |
| staleAfterHours | 24 | 索引超过这个时长，首次查询前先重新同步 |
| queryTimeoutMs | 90000 | 单次查询的时间预算 |
| initTimeoutMs | 600000 | 单次索引构建的时间预算 |
| versionTimeoutMs | 90000 | 探测和 status 的时间预算，索引很大时会慢 |
| shutdownTimeoutMs | 2000 | 子进程还在跑时，等多久再杀掉 |
| defaultMaxChars | 20000 | 结果预算，除非调用自己指定 |
| defaultMaxResults | 20 | 搜索条数，除非调用自己指定 |
| defaultDepth | 2 | codegraph_impact 默认走几跳 |
| statusTtlMs | 1800000 | 一次成功的 status 结果复用多久 |

这些超时是实测出来的，不是猜的。在一个 509 个文件的根目录上（不是 git 仓库），status --json 冷启动约 14.8s，热启动约 1.1s，而 query --json 约 0.6s。status 是其他所有工具首先要等的命令，所以它的预算给得宽。

在配置档里启用

dsh plugin add 会帮你改 dependencies 和 dsh.profile.bundles。要手动链接本地 checkout：

// profiles/<name>/package.json
"dependencies": { "dsh-codegraph-tools": "link:/absolute/path/to/dsh-codegraph-tools" },
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "dsh-codegraph-tools"] } }

然后重启 DSH 一次。运行中的宿主持有启动时读到的配置档清单，所以 DSH 运行时改 package.json 不会让 bundle 变得可解析。

在 Windows 上，配置档的 node_modules/dsh-codegraph-tools 必须是指向插件目录的junction，否则改动到不了配置档。Git Bash 的 ln -s 会创建副本；请用 PowerShell 的 New-Item -ItemType Junction。

系统提示词段落是个服务商，不是静态字符串。它按每次组装求值，如果预设或子代理的 toolFilter 移除了这些工具，它就不贡献任何内容，所以模型永远不会被告知去用自己看不到的工具。

文件

package.json 包本身及其 dsh bundle 声明 cordis.patch.yml 三行 loader 及其配置 src/index.js 服务入口（提供 codeGraph） src/config.js 所有默认值、类型和解析步骤 src/engine.js 命令行接缝：每条命令一个受管子进程 src/runtime.js 哪个项目、有没有索引，以及各种答案 src/tools.js 工具定义及其渲染器 src/prompt.js 系统提示词段落文本及其可见性门控 src/util.js 配置校验器、文本截断、小型格式化器 src/entry-tools.js tools 行 src/entry-prompt.js prompt 行 scripts/check-plugin.mjs 插件契约，对着假上下文跑 scripts/check-patch.mjs 打包产物：每一行、每个导出、每个 files 条目和图标 scripts/live.mjs 同一套引擎，对着真实命令行跑

验证

npm test # 两道关卡：先插件契约，再打包产物
node scripts/check-plugin.mjs # 插件契约，对着假上下文跑
node scripts/check-patch.mjs # 每一行补丁、每个导出、每个 files 条目和图标
node scripts/live.mjs <project> # 真实命令行，走已发布的引擎

check-plugin.mjs 断言的是加载时 harness 会做什么，手工挂载的测试做不到这一点：确认没有默认导出（加载器会拆开 .default，悄悄丢掉 inject、name 和 Config，让所有依赖行永远停在 PENDING），确认注册是副作用，确认提示词段落通过 ctx.get 读注册表、绝不碰 ctx.tools 属性，确认 spill 定位符不会被截断，确认祖先索引会被拒绝。

它还钉住了六个曾经真实出现过的回归：关系工具读 targets，把查询的符号当成自己的结果返回；explore 把每个已作答的查询都报成未索引，因为它自己的源码里引用了未索引的措辞；一次过期的刷新跑了 init，什么也没做；索引缺失时跑了 sync，始终没建起来；files 把目录传给了 --pattern，返回空；一次超时被归类成 cli-missing，而这条提示会叫模型去重装一个本来能用的命令行。

live.mjs 端到端驱动真实命令行，只要几秒前建好的索引答不出自己项目里的符号，就判失败。

每次 push 和 pull request，CI 都会在 Linux 和 Windows 上跑这两道关卡。

说明

- 索引是缓存，过期的缓存会撒谎。 两道防线兜住这点：staleAfterHours 会重新同步超过时间窗的索引，pendingChanges 会抓住比时间窗新、但已经过期的索引。
- 每个项目只允许一个写入者。 codegraph daemon 持有锁。工具会报 writer-locked，并指向 codegraph daemon 或 codegraph unlock，而不是重试。
- 遥测是上游的，关不关由用户决定。 这里不发任何数据，也不读上游的设置。
- 让图根目录保持为源码树。 索引成本要付两次：建的时候一次，之后每次命令重新遍历、报告待处理变更时再一次。用 codegraph.json 的 exclude 列表排除数据目录，让每个项目保留自己的索引。

License

本打包产物采用 MIT 协议 —— 见 LICENSE。CodeGraph 采用 MIT 协议，© Colby Chenry，这里把它当作已安装的命令行来驱动，没有内联或再分发；NOTICE 载明了这一署名。