dsh-codegraph

让 DSH 会话直接使用 CodeGraph （@colbymchenry/codegraph）的预索引代码知识图谱能力。

这是一个可一键安装的 DSH 插件（bundle）：它把 codegraph CLI 包装成 模型可见的原生工具，模型在分析代码时无需 grep/读大量文件，直接按符号、 按区域、按调用链查询索引，并能自举并维护索引（init/index/sync）。

工具面（surface）：借鉴上游项目「codegraph_explore 是唯一稳定赢得模型调用的工具」 的实测结论（其官方 MCP server 默认只暴露 explore），本插件默认只注册 4 个核心工具 （codegraph_status / codegraph_init / codegraph_sync / codegraph_explore）， 保持模型工具列表精简、引导集中。需要全部 13 个工具时，在组合层配置 surface: 'full'（见下文「配置」）。

提供的工具

工具	对应 CLI	用途
codegraph_status	status --json	索引状态（是否已初始化、版本、文件/节点/边数、待同步变更、建议重建等）
codegraph_init	init	初始化项目并建立初始索引（.codegraph/）
codegraph_index	index	全量（重）索引；status 建议 reindex 时用
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	改动若干源文件后应运行哪些测试文件

工具名与 CodeGraph 官方 MCP 工具同名，模型的使用心智与官方文档一致。

前置要求

1. 已安装 DSH（本插件为 DSH bundle，随 DSH web 应用装载）。

   支持的 DSH 版本：0.1.x 与 0.2.x（含 0.2.0），两条线共用同一份代码。 插件使用的接口在本插件所覆盖的范围内跨版本稳定：defineTool（name/description/ parameters/output/execute/presentCall/timeoutMs）、tools.register()、 systemPrompt.section()、createUserMessage、ctx.get('subprocess' | 'shell')， 以及 agent/inbox/inserted 事件 + agent.steer()。

   ⚠️ 安装门槛在 peerDependencies 上，不在代码里。 DSH 0.2.0 起会在安装前校验本包 peerDependencies 中每个 @deepseek-ai/dsh* 范围：若当前 DSH 版本不满足 semver.satisfies(v, range, { includePrerelease: true })，dsh plugin add 会直接拒绝安装 （报 incompatible-version）。因此本插件的上限是 <0.3.0-0 而非 <0.2.0-0—— 后者会把所有 0.2.x 预发布版一并排除。若从 1.1.0 及更早版本升级，请一并更新插件。

2. 已安装 codegraph CLI 且其可执行文件在 PATH 上（插件在运行时按名字 codegraph 解析可执行文件）：

   npm i -g @colbymchenry/codegraph     # 或按官方 install.sh / npm thin shim 安装
   codegraph --version                  # 确认可用（≥ 1.0）
   

一键安装

在 DSH 应用的 web profile 中安装（一条命令，无需手动改任何配置文件）：

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 层栈（cordis.patch.yml 里那一条 insert 就是它的 组合层，不需要你手动加）；
• 重启 DSH 应用后，任意会话里模型即可看到 codegraph_* 工具（默认 core 面 4 个）。

其他 profile：把 --profile web 换成 --profile tui 等即可。

从 npm 安装

本包已发布到 npm（@jiangzhenguo/dsh-codegraph， 无 scope 的 dsh-codegraph 名字已被他人占用），用包名替换 github: 源即可：

dsh plugin --profile web add @jiangzhenguo/dsh-codegraph

卸载

# 从 npm 安装的
dsh plugin --profile web remove @jiangzhenguo/dsh-codegraph

# 从 GitHub 安装的
dsh plugin --profile web remove dsh-codegraph

一装上就会优先调用 codegraph 搜代码

…