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'（见下文「配置」）。

提供的工具

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

前置要求

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

   本版验证基线：DSH 0.2.1-alpha.3 与 @deepseek-ai/schemastery@3.18.5-alpha.2。 DSH peer 范围从该基线起至 <0.3.0-0；使用当前官方的 defineTool、 tools.register()、systemPrompt.section()、createUserMessage、 workingDirectory.get(session)、loader/volatile-update 和 ConfigForm 接口。 旧版 0.1.x / 早期 0.2.0 运行时不在本版验证与安装范围内。 DSH 插件管理器会先校验 peer 范围，不满足时拒绝安装。

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

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

安装与首次使用

1. 先完成前置要求中的 CodeGraph CLI 安装，并确认 codegraph --version 可运行。

2. 优先在 Nano AI 市场中找到「CodeGraph 代码图谱」，阅读权限与兼容性后安装 1.3.4。也可以在 DSH 官方插件管理器使用本版固定安装地址：

   https://nano-ai.cn/v1/plugins/dsh-codegraph/versions/1.3.4/install.tgz

3. 安装到当前使用的 profile。按结果提示重启 DSH；在项目目录打开会话，调用 codegraph_status。

4. 尚无索引时按需调用 codegraph_init，然后使用 codegraph_explore。修改源码后调用 codegraph_sync。首次探索成功时应返回项目相关源码与调用链。

关于 npm 同名包

公开 npm 上的 dsh-codegraph@0.1.3 属于不同维护来源，不是本市场的 1.3.4。不要用同名包替换本版，也不要把包名相同视为归档、维护者或版本来源相同。外部 CLI @colbymchenry/codegraph 是独立依赖，需要另外安装。

卸载

dsh plugin --profile web remove dsh-codegraph

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

插件不只是一个「把工具放出来」的包，它还会在系统提示词里注入一条高优先级指引 （tool:codegraph，order: 98），让模型在搜索/探索代码时优先用 codegraph_* 而不是 grep / glob / read：

• DSH 内置文件工具的指引集中在 order 100–104（read=100、write=101、edit=102、 glob=103、grep=104）。本插件的指引放在 98，落在它们之前，因此模型先看到 “优先用 codegraph_* 搜代码”。
• 指引措辞采用上游官方 MCP server instructions 的同款策略（软性 "Prefer" 会被模型忽略， 实测会退回 grep/bash 反射路径）：命令式（MUST use codegraph_explore INSTEAD of grep/glob/read）+ 反模式清单（不要先 grep「找文件」、不要用 grep 复核 codegraph 结果——它来自完整 AST 解析）+ 未索引项目的硬停止规则（不自行初始化时，本会话 不再调用 codegraph 工具，索引与否是用户的决定）。
• 指引只点名 core surface 的 4 个工具：codegraph_status 确认索引 → 未初始化则 codegraph_init → 之后用 codegraph_explore 一次拿到相关符号的逐行源码 + 调用链， 改完代码用 codegraph_sync。

也就是说：装上即生效，无需每个会话单独配置——其他会话也一样会优先走 codegraph 来完成代码搜索。

结构化 prompt 自动前置注入（frontload，默认关闭）

提示词指引仍是「软性」的——模型可能忽略它（上游实测如此）。因此本插件实现了上游 UserPromptSubmit prompt-hook 的 DSH 等价物，也是上游验证过最有效的采用率手段：

• 默认关闭（frontload: false）：注入的 <codegraph_context> 以密集原文形式 驻留上下文窗口直至会话结束（上游残留上下文实测约 +82% token 残留），因此只在 明确需要时开启——可在组合层配置或直接在 DSH 设置界面打开。
• 插件监听 agent/inbox/inserted 事件；当一条真实用户 prompt 进入 agent 的 next-turn 收件箱时，按置信度分级门控：
  • 高置信：prompt 含结构性关键词（中/英：「调用 / 流程 / 原理 / 重构 / 影响 / 依赖 / how does / who calls / refactor / trace …」）→ 直接触发；
  • 中置信：prompt 含代码形态 token（文件名 / camelCase / PascalCase / snake_case） → 先用 codegraph query 对照索引验证 token 是真实符号才触发；
  • 其余 prompt（如「fix this typo」）零开销静默跳过。
• 触发后在会话 cwd 向上找最近的 .codegraph/ 索引根（找不到 = 未索引 = 静默跳过， 是否索引是用户的决定，插件不擅自 init），预跑 codegraph_explore，把结果以 <codegraph_context> 包裹 steer 进当前 turn（上限 12000 字符）。
• 于是「模型反射性 grep/read 要找的东西已经在上下文里了」——context 先于工具调用到达。
• 绝不弄坏用户 prompt：所有失败路径（无索引、门控未命中、CLI 报错）都是静默 no-op； 注入内容带标记，不会触发自身循环（steer 落在 next-step 边界，监听器只看 next-turn）。
• 去重：同文 prompt 在 10 分钟内重复进入收件箱（GUI 重发排队消息、step 被拒后重新 入队——每次消息 id 都是新的）只会注入一次，避免重复上下文。

DSH 设置界面可配置（无需重启）

插件通过宿主 Config schema 中的 volatile 字段暴露三项运行时配置（DSH 设置 → 插件 → CodeGraph 行的配置页），解析层级为 用户覆盖 > 组合层配置 > schema 默认值：

设置变更即时生效：插件响应官方 loader/volatile-update，拆掉旧的提示词 section、工具面 与 frontload 监听器后按新值重挂。浏览器半通过 configForms.get("dsh-codegraph") 读取宿主 投影，在 plugins.row.config slot 中渲染表单；仅保存时调用官方 ConfigForm 写入接口。 取消勾选保存为显式 false；“重置”移除用户覆盖并预览组合层继承值。所有订阅和样式均随插件卸载清理。

配置（组合层）

在组合层（如 cordis.patch.yml 的 insert 行）可为插件传配置（作为用户设置的 base 层）：

- insert:
    - id: dsh-codegraph
      name: dsh-codegraph
      require: dsh-codegraph
      config:
        guideSearch: true    # 默认 true：注入上述系统提示指引；false 只注册工具
        surface: core        # 默认 core：只注册 status/init/sync/explore 共 4 个工具；
                             # 设为 full 注册全部 13 个
        frontload: false     # 默认 false：结构化 prompt 自动前置注入；true 开启
        codegraphPath: ''    # 默认 ''：从 PATH 解析 codegraph；填绝对路径则直接用那个可执行文件
        codegraphArgs: []    # 默认 []：每次调用都前置的额外 CLI 参数，如 ['--no-color', '--threads', '4']

codegraphPath / codegraphArgs 是部署侧（组合层）选项，不出现在设置卡片里： 它们决定「用哪个 codegraph、带什么参数」，属于机器环境而非用户偏好。codegraphPath 指向不存在的文件时会明确报错（而不是静默失败），方便定位装歪的 CLI。

使用流程

1. 在项目目录开一个新的 DSH 会话（cwd = 项目根）。
2. 让模型先跑 codegraph_status：未初始化 → 跑 codegraph_init。
3. 之后用 codegraph_explore 查代码（一次调用返回相关符号源码 + 调用链）； surface: 'full' 下还可用 codegraph_query / codegraph_node / codegraph_callers / codegraph_callees / codegraph_impact 做更细的查询。
4. 改动代码后用 codegraph_sync，需要跑测试时用 codegraph_affected（full）。

所有工具默认作用于调用方会话的当前工作目录（优先使用官方 workingDirectory.get(session)， 因此会跟随会话中的目录切换）；也可显式传 path 指向其他项目。

为什么会话级 MCP server 不理想（本插件为何存在）

codegraph 的官方 MCP server 在工作区未建立索引时暴露 0 个工具（并提示模型 “不要自己索引”）。本插件始终暴露工具——包括模型自举和维护索引所需的 init/index/sync——因此是比 MCP 更顺手的集成方式。

在 codegraph@1.0.1 中，callers / callees 可能因 CLI 索引数据返回空数组。

仓库结构

├── package.json        # DSH bundle 声明（dsh.bundle.patch + dsh.client）+ peerDependencies
├── cordis.patch.yml    # 组合层 patch（把本插件的 node half 插入 host 组合）
├── lib/index.js        # 插件实现：注册 codegraph_* 工具（core 4 个 / full 13 个）+ volatile Config
├── client/client.js    # 浏览器半：设置页「插件 → 可配置插件」里的 CodeGraph 卡片
├── test/               # 运行时测试 harness（自带 CLI 桩，keyless 可跑）
└── plugin-host.js      # （旧）会话级 host-only 动态版，仅作参考

1.3.4 变更

• 对齐官方当前工作目录服务，目录切换后工具及 frontload 使用新目录。
• 修复设置页关闭选项无法持久化、重置未预览继承值的问题，补齐订阅与样式清理。
• 核对 CLI 执行边界与 DSH 预发布版 peer 范围，补充回归验证。
• 更新当前仓库安装方式与官方 volatile Config / ConfigForm 接口说明。

许可

MIT