dsh-graft-plugin

dsh plugin --profile web add dsh-graft-plugin

<picture>

<source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.png?v=2">

<img alt="graft" src="assets/banner-light.png?v=2" width="1012">

</picture>

<br>

dsh-graft-plugin

[English](README.md) | 中文

一个 DeepSeek Harness 插件，把 graft——一张预先构建的符号图（每个符号的 file:line 位置、谁调用了谁）——同时摆到你和模型面前。

它做四件事：

• 输入框里的徽章（chip）：说出当前会话实际在用哪个 graft 索引、它是否还与代码一致、这个仓库里 graft 已经省了多少 token。徽章的卡片上有一个 Build 按钮——重建索引，或者创建第一个索引。
• 给模型五个工具 — graft_ask、graft_grep、graft_callers、graft_skeleton、graft_map——按会话解析，所以一个 dsh 可以同时服务多个工作区，git worktree 也不例外，每个都有自己的图。
• /graft 构建或重建索引，模型改完文件后自动重建。
• graft viz 按钮：在 dsh 内置的右侧边栏（0.1.5+）打开图；如果你还在用 dsh-better-sidebar，就在那里打开；两者都没有时退到浏览器标签页。

安装

dsh plugin --profile web add dsh-graft-plugin
dsh --profile web

pnpm 10 及以后会默认拦截未批准包的 postinstall 脚本，而只要安装以非零退出，dsh 就会跳过写入插件的 bundle 行——依赖装上了，插件却隐形，dsh 还启动得干干净净，没有任何可搜索的报错。如果 add 以 ERR_PNPM_IGNORED_BUILDS 结尾，先批准再重跑：

cd ~/.dsh/profiles/web && pnpm approve-builds      # 勾选 dsh-graft-plugin
dsh plugin --profile web add dsh-graft-plugin      # 重跑，让 bundle 行写入

确认它挂载了——插件必须同时出现在 profile 的 package.json 的 dependencies 和 dsh.profile.bundles 里：

cd ~/.dsh/profiles/web && node -e "const p=require('./package.json');
  console.log(p.dependencies['dsh-graft-plugin'],
              p.dsh.profile.bundles.includes('dsh-graft-plugin'))"

这里的每个工具都要调用 graft CLI，所以 PATH 上必须有 @nanonets/graft：

npm install -g @nanonets/graft

postinstall 会在你的包管理器愿意运行生命周期脚本时替你装好——pnpm 10+ 默认拦截它们，所以在 pnpm 下请把上面这条命令当作必需步骤，而不是后备。若全局 npm 前缀需要提权，postinstall 会说明并打印那条需要手动执行的命令。

然后给仓库建一次索引：

cd <your repo>
graft build

桌面应用

桌面版 dsh 从自己的 Plugins 设置页安装插件——不用 CLI，不用 profile 目录：

1. 打开 Plugins（设置页左侧栏），点 Add plugin。

2. 把 GitHub 仓库地址粘进输入框（包名 dsh-graft-plugin 也可以）：

   https://github.com/adithyanraj03/dsh-graft-plugin

3. 点 Install。

对话框会切换到 Installed 确认页，插件同时出现在设置页底部的 Installed 列表里：

对话框也提示：已安装的插件目前不会自动更新——升级请先卸载再重装。graft CLI 的要求（npm install -g @nanonets/graft）不变。

侧边栏标签页

在 dsh 0.1.5 及以后，这个按钮会在 dsh 自己的右侧边栏里打开图——一个名为 Graft 的标签页，同时列在边栏引导页里，说明是 "The graft graph for this workspace"——再次点击会聚焦已打开的标签页。这条路径不需要安装任何东西：注册是软性的，所以没有右侧边栏的旧版 dsh 会退到已挂载的 dsh-better-sidebar，两者都没有时退到浏览器标签页。

如果你的 profile 还在用 dsh-better-sidebar，会优先尝试那条路径，行为和以前完全一样。从 0.3.0 起它是可选对等依赖（optional peer dependency）——dsh 不再替你下载，想要就自己加（在 dsh 0.1.5-rc.2 及以后它本来就挂不起来，多数 profile 可以跳过）：

dsh plugin --profile web add dsh-better-sidebar

兼容性。 dsh-better-sidebar 0.18.x 需要 @deepseek-ai/dsh-client-ui-primitives，而 dsh 在 0.1.5-rc.2 移除了它。在该版本及以后它挂不起来——那些 profile 正好由内置右侧边栏接管。本插件其余部分——徽章、工具、/graft、自动重建——都不受影响。

徽章、工具、/graft 和自动重建在完全没有侧边栏时也都工作；按钮只是在两个都没有时退到浏览器标签页。

这个插件故意不自己插入 dsh-better-sidebar 行。那个包自己的 bundle 行带一个守卫：当已有另一个启用的行挂载同一个包时，它会自我禁用。第二条不同 id 的行会让这个守卫变成循环判断，输掉的那一边是你现有的边栏悄悄自我禁用。一条显式命令比这个风险值钱。

你会得到什么

徽章

待在输入框里模型名的旁边：

● graft · my-repo          in sync
◐ graft · my-repo          syncing
▲ graft · my-repo          stale

悬停（或点击）打开一张卡片：解析出的根目录、节点与边数、新鲜度、累计省下的 token，以及 graft viz 按钮。

卡片头部在状态胶囊旁边有一个 Build 按钮。在已有索引的仓库里，它跑的就是自动重建用的那套同步——graft 自己的 sync——并停在 "Building…" 直到胶囊显示 in sync，两分钟后放弃并给出原因。在还没有索引的工作区里，Build 会先用 dsh 自己的对话框确认（"Build graft index?" — Cancel / Build index；取消、Escape 或点框外都不会构建），然后跑一次纯离线的 graft build，在那里写出一个 graft/ 目录。

graft_* 工具运行期间，徽章的圆点会闪紫色。

徽章、卡片和可视化标签页全部用 dsh 自己的 --dsw-* 主题变量绘制，因此跟随当前主题——包括主题插件。

链接的 git worktree 拥有自己的图，绝不借用主检出（main checkout）的：卡片和边栏标签条都会标出它所属的主检出（git worktree of <repo>）。还没有图时，在 worktree 里 /graft 会从主检出播种出第一张图。

根目录是从会话自己的工作区解析的，不是从 dsh 的启动位置。这正是本插件存在、而不是用 graft mcp 服务器的原因：graft mcp 在启动时从自己的工作目录解析一次仓库，之后没有任何办法改指。从主目录启动时，它对你打开的每个工作区都回答"no graph found"。

可视化

graft viz 按钮把图作为一个标签页打开——在 0.1.5+ 的 dsh 内置右侧边栏里，或者在你仍在使用的 dsh-better-sidebar 里。上下文视图铺开整张图：

代码视图下钻到单个文件——它包含什么、依赖什么、被谁依赖：

工具

工具 · 回答什么

graft_ask · "X 是怎么工作的" / "Y 在哪"——带排序的命中，代码直接内联在精确的 file:line

graft_grep · 每一处出现，按所在符号分组（graft_ask 只给 top-N，会漏）

graft_callers · 谁调用一个符号、它调用谁，或改名前的完整爆炸半径

graft_skeleton · 一个文件的完整 API，约 200 token

graft_map · 在陌生目录树里定位方向

它们都不接受布尔参数，而是用字符串枚举——detail: "full" 而不是 full: true——对模型更好读，也绕开了一些 OpenAI 兼容服务器上的一个真实故障：设置了布尔值的工具调用会被发成字面的 <tool_call> 文本，永远不执行。

/graft

• /graft — 构建索引，已有则重建
• /graft status — 把徽章知道的东西打成文字
• /graft deep — 完整重建

自动重建

模型写入或编辑文件后，索引在后台重建，并做了防抖，长回合不会每次击键都重建。这里复用 graft 自己的 sync runner，而不是重新实现一遍，所以它不会和 graft build 的行为漂移。

配置

全部可选，全部写在 profile 的 cordis.patch.yml 里本插件的那一行上：

- id: graft-status
  name: 'dsh-graft-plugin'
  config:
    cwd: 'C:/path/to/repo'   # 固定到一个仓库，而不是按会话解析
    tools: false             # 去掉 graft_* 工具，保留徽章
    command: false           # 去掉 /graft
    promptSection: false     # 不再告诉模型使用 graft
    autoBuild: false         # 不再在编辑后重建（卡片上的 Build 按钮仍然可用）

系统要求

dsh · 状态

0.2.1-rc.2 · 测试套件针对 0.2.1-rc.2 的包全部通过——徽章、工具、/graft、自动重建和面向模型的指引；双形态 codec 在 0.1 和 0.2 宿主上都能加载

0.1.7-rc.2 · 在真实 profile 上测试过（0.3.0）——徽

…(truncated)