DSH bundle that registers 13 native codegraph_* tools wrapping the codegraph CLI, so agents bootstrap, maintain, and query a pre-indexed code knowledge graph (symbol query, explore, node trail, callers/callees, impact, affected tests) instead of grepping files.
Install
# from npm (prebuilt)
dsh plugin --profile web add @jiangzhenguo/dsh-codegraph
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:jiangzhenguo/dsh-codegraph
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
This plugin publishes its README in Chinese only.
让 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 工具同名,模型的使用心智与官方文档一致。
前置要求
已安装 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及更早版本升级,请一并更新插件。已安装
codegraphCLI 且其可执行文件在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 搜代码
插件不只是一个「把工具放出来」的包,它还会在系统提示词里注入一条高优先级指引
(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_exploreINSTEAD 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 等价物,也是上游验证过最有效的采用率手段:
- 插件监听
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 都是新的)只会注入一次,避免重复上下文。
- 可用配置
frontload: false整体关闭。 - 注入的是一条 user 消息,会在聊天列表里多显示一条——内容以
<codegraph_context note="Structural context from CodeGraph for this prompt — treat the returned source as already read; call codegraph_explore for more.">开头。这是 DSH 的机制决定的:agent.steer()只能投递消息,没有「不可见的上下文通道」,所以 frontload 的代价就是 聊天里多一条 steer 消息(本机 profile 已因此把它关掉,只保留工具与系统提示指引)。
配置
在组合层(如 cordis.patch.yml 的 insert 行)可为插件传配置:
- 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: true # 默认 true:结构化 prompt 自动前置注入;false 关闭
使用流程
- 在项目目录开一个新的 DSH 会话(cwd = 项目根)。
- 让模型先跑
codegraph_status:未初始化 → 跑codegraph_init。 - 之后用
codegraph_explore查代码(一次调用返回相关符号源码 + 调用链);surface: 'full'下还可用codegraph_query/codegraph_node/codegraph_callers/codegraph_callees/codegraph_impact做更细的查询。 - 改动代码后用
codegraph_sync,需要跑测试时用codegraph_affected(full)。
所有工具默认作用于调用方会话的 cwd;也可显式传 path 指向其他项目。
为什么会话级 MCP server 不理想(本插件为何存在)
codegraph 的官方 MCP server 在工作区未建立索引时暴露 0 个工具(并提示模型
“不要自己索引”)。本插件始终暴露工具——包括模型自举和维护索引所需的
init/index/sync——因此是比 MCP 更顺手的集成方式。
测试
test/run-plugin-test.mjs 是一个自带真实 codegraph CLI + 桩 cordis 服务的运行时测试
harness:加载本插件的 lib/index.js,挂载 tools/subprocess 服务,apply() 后逐一调用
工具的真实 execute。在装好插件的 profile 里运行:
CG_PROFILE_NM=<profile>/node_modules node test/run-plugin-test.mjs
覆盖:mount 不抛错、tool:codegraph 提示词注入(order 98 < 100,先于 grep/glob/read)、
默认 core surface 只注册 status/init/sync/explore 共 4 个工具、surface: 'full' 下
13 个工具全部注册并逐一真实执行(status→init→query→node→files 主流程、
sync/impact/affected)、frontload 前置注入(结构性 prompt 注入 <codegraph_context>、
同文重发去重、非结构性/未索引/自循环/rpc 来源静默跳过、frontload:false 不注册监听器)、
无执行器服务时 apply 不抛错(惰性解析,启动顺序安全)、
显式 path 覆盖、以及「无 cwd 且无 path 时报错」的错误路径。
跨 DSH 版本验证
harness 走 node_modules 解析真实的 @deepseek-ai/dsh-tools / @deepseek-ai/dsh-llm
(不是桩),因此「装上哪个 DSH 版本,就用哪个版本的参数校验、Config schema 与消息工厂
来跑插件」。这让测试套件本身成为跨版本闸门:
- 第 0 节 · 版本与安装门槛:打印实际解析到的
dsh-tools/dsh-llm版本, 并用createRequire按插件自己的路径复核(保证打印版本 == 插件真正加载的版本); 随后逐一断言 manifest 里每个@deepseek-ai/dsh*peer 范围都放行0.2.0/0.2.0-rc.2/0.2.5——即 0.2.0 安装门槛不会误杀本插件。 这一节专门用来锁死「peer 上限写成<0.2.0-0」这类回归。 - 第 4b 节 · ToolDefinition 契约:断言
name/description/parameters/output/execute齐备;output.render返回ContentBlock[]且对非法输入不抛错;presentCall返回 带card: 'terminal'标签的 view(0.2.0 起ToolCallView是'generic' | 'terminal' | 'diff'的可辨识联合,无标签对象不再合法);timeoutMs声明时为正数。 - 第 19 节 · 消息形状:断言 frontload 注入的消息带
source.kind === 'user'(0.2.0 的MessageSourceMap形状,监听器正是据此放行)、且被createUserMessage冻结。
CI(.github/workflows/test.yml)以 dsh 0.1.5-rc.3 与 dsh 0.2.0-rc.2 双版本矩阵运行同一套用例。
本地对指定版本跑:
# 直接跑(用仓库 node_modules 里的 peer)
node test/run-plugin-test.mjs
# 或指向某个 profile / 已安装 dsh 0.2.0 的 node_modules
CG_PROFILE_NM=<profile>/node_modules node test/run-plugin-test.mjs
说明:
callers/callees在本机codegraph@1.0.1上返回空数组是 CLI 侧数据/索引特性 (该版本的调用图边未解析到),与插件无关——插件忠实返回 CLI 的真实输出;impact已能 返回真实的受影响节点与边。
仓库结构
├── package.json # DSH bundle 声明(dsh.bundle.patch)+ @deepseek-ai/dsh-tools peerDependency
├── cordis.patch.yml # 组合层 patch(把本插件的 node half 插入 host 组合)
├── lib/index.js # 插件实现:注册 codegraph_* 工具(core 4 个 / full 13 个)
├── test/ # 运行时测试 harness(真实 CLI + 桩 cordis 服务)
└── plugin-host.js # (旧)会话级 host-only 动态版,仅作参考
许可
MIT
Links
More in this category
Tencent/WeKnora#dsh-weknora★ 37587
Four read-only tools over a WeKnora knowledge base: list knowledge bases, hybrid passage search, reassemble one document's chunks in order, and WeKnora's own cited RAG or ReAct-agent answer with a resumable session id.
DayuanJiang/next-ai-draw-io#dsh-plugin★ 37004
Draws draw.io diagrams in DeepSeek Harness through the next-ai-drawio MCP server: the link in the reply opens a live preview in the right sidebar, you can edit the diagram by hand, and each AI change is a version you can restore. Node.js 18+; npx downloads the MCP server on first use.
superdesigndev/treg★ 8181
Tool catalog for agents: search ~2,600 external endpoints (SEO and SERP, backlinks, social, people and company enrichment, ad libraries, scraping) by the task you want done, read each one's parameters and per-call price, then call it with the credential injected server-side. Ships the skill plus an MCP row that stays disabled until TREG_TOKEN is set.
T-Auto/dsh-ops★ 5867
Provides bash, PowerShell 7, and high-performance Rust tools for DSH on Windows to reduce token usage.
sixtysevenlf/dsh-blender-plugin★ 2153
Lets a DSH agent drive a local Blender over a direct TCP channel with 15 tools: viewport frames, custom-angle renders, Python execution, headless and job offload, transaction rollback, and a planning layer of 228 ops across 34 families.
helloHub1212/dsh-windows-mcp★ 1490
Bridges the CursorTouch/Windows-MCP desktop automation server into DSH through the official MCP client bridge, registering its screenshot, UI tree snapshot, mouse and keyboard input, clipboard, process and registry tools as mcp__windows__* tools for the model, and adds a windows_mcp_doctor diagnostic tool. Computer Use is off by default and is switched on from the plugin panel.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.