插件开发工具箱 CkEFFAF/dsh-plugin-devkit

DSH Plugin DevKit

用于开发 DeepSeek Harness（DSH）插件的工具集：一个可以在实时会话里查询的运行时检查器、一个用于测试的隔离启动器、无需浏览器的宿主契约测试，以及面向客户端半边（client half）的槽位预览。

状态： 四个模块全部实现。547 个单元测试，外加六项真机检查 —— 跑在真实的 cordis 运行时、真实的 DSH 启动，以及真实的一次模型轮次上。已在 DSH 0.1.5-rc.2 上验证。

社区项目。 本 DevKit 由社区维护，与 DeepSeek AI 无隶属关系，也不由其背书或提供支持。
「DeepSeek Harness」「DSH」指它所面向的上游平台。

快速开始

四个工具都在同一个 npm 包里。把运行时检查器挂进 DSH profile：

dsh plugin --profile web add @effaf/dsh-plugin-devkit

dsh plugin 会在 profile 目录里执行 pnpm，然后对账 dsh.profile.bundles ——
由于该包声明了 dsh.bundle.patch，它会自动加入层栈。重启 DSH 后 /debug health 即可回答。

三条 CLI 也在同一个包里，全局装一次就都在 PATH 上：

npm install -g @effaf/dsh-plugin-devkit # debug-boot、dsh-plugin-test、dsh-plugin-preview

要在自己的插件代码里用某个模块，直接引子路径：

import { createFakeContext } from '@effaf/dsh-plugin-devkit/fake-host'
import { noPending } from '@effaf/dsh-plugin-devkit/assertions'

不用 npm、直接从仓库来：

git clone https://github.com/CkEFFAF/dsh-plugin-devkit.git
cd dsh-plugin-devkit
npm install
dsh plugin --profile web add "$PWD"

为什么不用 npm install git+https://…？ npm 直到 10.5 才支持 git 子目录；更早的版本会静默安装整个仓库根目录，而不是你指定的那个包 —— 你拿到的是一个没有入口点、也不报错的文件夹。
安装已发布的包，或克隆后按路径安装，则在任何版本上都可用。已在 npm 10.1 + node 22 上验证。

环境要求

DSH 0.1.5-rc.2 —— 本 DevKit 开发与验证所针对的版本，四个包都用 engines.dsh 声明。
DevKit 只通过公开接缝接触宿主（ctx.debugger、/debug、CLI 退出码、JSON 报告），所以相近的版本通常可用，但其他版本未经测试。

Node 22 或更高。dsh-plugin-preview 可选地使用系统 Edge/Chrome 截图、使用 esbuild 打包；两者都在运行时探测，缺失时会明确报告，绝不会自行下载。

各模块的用途

四个模块都在同一个包里：@effaf/dsh-plugin-devkit。

| 模块 | 做什么 | 需要了解 |
| dsh-debugger | 观察一个实时组合：有界时间线、/debug 命令，以及可编程的 ctx.debugger | ctx.debugger、/debug |
| dsh-debug-boot | 启动隔离的 DSH profile，让真机检查永远不碰你的日常环境 | debug-boot CLI |
| dsh-plugin-test | 不开浏览器断言宿主行为：假 Cordis 宿主 + JSON 报告 | dsh-plugin-test CLI |
| dsh-plugin-preview | 把客户端半边挂进假槽位外壳，按官方主题尺寸近似渲染 | dsh-plugin-preview CLI |

dsh-debugger 是运行时检查器，不是源码级单步调试器 —— 需要断点请用 NODE_OPTIONS=--inspect 配合编辑器 attach（DevKit 自己的 /debug health 也会提醒你）。

它能做什么

- 问一个正在运行的组合现在什么状态。 /debug health 给一句结论； /debug plugins --not-active 点名一个从未激活的插件，以及它在等哪个服务； /debug services 显示谁提供了什么。
- 把一次调用从头追到尾。 /debug trace 返回共享同一 correlation id 的全部记录 ——一次工具调用就是 pre-execute → execute → result，带耗时。
- 看见模型轮次，而不只是工具调用。 纯文本的一轮也会留下一条 llm/stream 记录，含 provider、model、消息计数，并关联到它所属的 session。
- 在副本上复现故障。 debug-boot 从随包模板派生一个一次性 profile，真机检查永远不碰你的日常实例。
- 不开浏览器就证明插件的宿主契约。 dsh-plugin-test 把插件挂到假 Cordis 宿主上，返回稳定 schema 的 JSON 报告。
- 看看客户端半边。 dsh-plugin-preview 把它渲染进假槽位，按官方主题尺寸近似显示， light/dark × narrow/wide 四种变体。

以上全部都能在你已经打开的那个会话里查询 —— 不用 attach DevTools，不用开第二个窗口。

与同类工具的差异

DSH 自带若干检查面，社区也做了不少工具。它们回答的是不同的问题，本 DevKit 的设计目标是与它们并排，而不是取代它们。

对比 DSH 自带的检查面

| | 本 DevKit | dsh-experimental-inspector | dsh-tool-cordis | Plugins 设置页 |
| 从哪用 | 聊天会话（/debug）与 CLI | Chrome DevTools 经 CDP 连接 | 模型工具调用 | Web 设置页 |
| 实时组合（fiber 状态、pending/failed 根因） | 有 —— 直接点名在等哪个服务 | Elements 面板里的 Cordis 树 | 有 | 只读的 loader 清单 |
| 工具 / 命令 / LLM 时间线，按 callId 关联 | 有，有界并计数 | Console + Network 面板 | 无 | 无 |
| 采集负载里的密钥 | 进缓冲前就已脱敏 | 不脱敏（官方文档明示） | 不适用 | 不适用 |
| 能否改变组合 | 不能 —— 纯旁观 | 不直接改，但 CDP 授予任意求值 | 能 —— 创建并运行临时包 | 不能 |
| 获取方式 | 公开、MIT、单个 npm 包（@effaf/dsh-plugin-devkit） | 私有、实验性、不随发布 | 随 DSH 发布，需自行挂载 | 随 profile 自带 |

对比社区插件

下表的描述都引自各项目自己的仓库与 npm 页面。

| 项目 | 它是什么 | 本 DevKit 的差别 |
| dsh-doctor | 「Deterministic diagnostics and recovery for DeepSeek Harness」—— WebUI 里的本机救援服务，外加 CLI（scan、boot、recover、checkpoint、rollback） | Doctor 会修：把配置重置回健康检查点、对齐依赖、再验证启动。本 DevKit 只观察和报告 —— 有界时间线、pending/failed 根因、工具与 LLM 关联 —— 绝不写你的组合。 |
| dsh-sseye | 「DeepSeek Harness 里的 LLM 调试控制台 —— 捕获每一次模型调用、看全内容、重放任何一次」 | 重叠最大：两者都挂 llm/stream waterfall。sseye 捕获完整 LLM 负载并能重放或改写调用；本 DevKit 只记标量、在入库前脱敏，覆盖的是整个组合而不只是模型调用。 |
| @ddtcorex/dsh-maestro-devkit | 「DeepSeek Harness 通用开发工具箱 —— 可视化审查、HMR、样式检查器、Cordis/Govard/Skills 开发」—— 已在 npm 弃用：「Retired: duplicated DSH core, CDP, Supervisor, Govard, and skill capabilities without completing a demonstrated workflow」 | 现存最接近「同类 DevKit」的东西，而且已停止维护。本项目的承诺更窄：四个小工具，以及离线的槽位预览，而不是实时 HMR 与样式检查。 |

这些差异换来了什么：

- 四个工具，一个仓库。 观察实时组合、隔离启动、测宿主契约、预览客户端半边 ——上面每一个替代品都只覆盖其中一件事。
- 它不会弄坏被观察的对象。 waterfall 探针原样返回 next() 的引用 —— 返回副本会搞坏整个组合的生成，因此有一个针对真实 LlmRuntime 的检查把它钉住。
- 密钥在入库前脱敏，而不是显示时才处理 —— 泄漏的 key 根本进不了缓冲。
- 证据不会悄悄消失。 缓冲有界、溢出被计数，JSON 报告带 summary.overflowed / recordsDropped，因此「丢了证据」的一次运行不可能被读成干净的通过。
- 它测的是契约，不是 mock。 假宿主镜像 normalizeDefinition 与真实的
execute(agent, line, …) 签名 —— 这正是它抓到「单测全绿、真机上却什么都不做」那类插件的原因。
- 隔离是硬规则。 真机检查跑在派生 profile 上；永不激活的插件被报成 plugin-pending （退出码 7）并点名它在等的服务，而不是甩一段 loader 堆栈。
- 边界明说，不暗示。 不承诺像素级一致，截图只拍不比，任何东西都不经过检查器代理。

别人走得更远的地方，如实说：

- dsh-sseye 捕获完整的请求与响应 —— system prompt、tool schema、每一个流式分片、真实端点 ——并且能重放或改写一次调用。本 DevKit 只记标量。
- dsh-doctor 能动手：把坏掉的 profile 回滚到最近一次健康检查点，之后还会再次验证启动。
本项目不写你的环境。
- dsh-doctor 与 dsh-sseye 都用裸包名发布，也是更成熟的项目 —— dsh-doctor 单月就有数百次
npm 下载。本 DevKit 发的是 @effaf/dsh-plugin-devkit，名字带 scope 而不是裸名，
下载量也从零开始。

它刻意不做的事： 源码级单步（那是 NODE_OPTIONS=--inspect 的活）、插件市场或安装 UI、 agent 轨迹工作台；也从不对自己注入 tools。

工作流

1. 针对假宿主跑契约测试 —— 不需要浏览器，不需要服务器。
node --test tests/.test.mjs
dsh-plugin-test tests/cases.mjs --plugin .

2. 看看你的客户端半边长什么样。
dsh-plugin-preview --slot tool.view.mine --client ./client.mjs --serve

3. 挂上你的插件，启动一个隔离实例。
debug-boot --plugin ./index.mjs --port 8080

4. 在那个会话里： /debug health 一切都在活动吗？
/debug plugins --name mine
/debug plugins --not-active
/debug events --category tool -v
/debug trace

dsh-plugin-test

import { noPending, serviceActive, noSecrets } from 'dsh-plugin-test'

// The runner mounts this on its host before running your cases.
export const plugin = { name: 'my-plugin', apply }

export const cases = [
{
name: 'my service is provided',
run: ({ ctx, plugin: mine }) => {
if (!ctx.get('mine')) throw new Error('not provided')
},
},
{ name: 'nothing is stuck pending', run: ({ debugger: d }) => noPending(d) },
]

run 收到 { ctx, debugger, host, plugin, pluginError }。它可以什么都不返回（视为成功）、返回 true，或返回断言辅助函数的返回值 —— 失败时抛错是通常写法，报告会原样带上你自己的消息。

退出码：0 全部通过，1 有用例失败，2 用法错误，3 模块或插件加载失败。
报告是稳定 schema 的 JSON，含 summary.overflowed 与 recordsDropped，因此「证据被丢弃」的一次运行不可能被读成干净的通过。

dsh-plugin-preview

你的客户端半边导出 mount(el, { fixture, slot, scheme, viewport })，或一个同签名的默认导出函数。
页面会渲染 light/dark × narrow/wide 四种变体，并定义官方 --dsw-alias- token 名，因此按这些名字写的 CSS 能正常解析。

边写边看。
dsh-plugin-preview --slot tool.view.mine --client ./client.mjs --serve

一个可以直接打开的独立 HTML 文件。
dsh-plugin-preview --slot tool.view.mine --client ./client.mjs --inline-client --out page.html

每个变体一张 PNG，供你自己做截图 diff。
dsh-plugin-preview --slot tool.view.mine --client ./client.mjs --serve --shot ./shots

--serve 与 --inline-client 是两条不同的路径，原因来自实测：内联模块（blob:/data:）既解析不了裸模块名，也解析不了相对路径，所以引用 react 的客户端会先用 esbuild 打平 ——如果 esbuild 不存在，工具会拒绝，而不是写出一个静默显示占位内容的页面。

它不承诺像素级一致。 尺寸是近似值，页面自己也这么写；布局回归需要在真实外壳上做截图 diff。
--shot 只负责截图，不负责比对。

仓库结构

| 路径 | 内容 |
| packages/ | 本包的四个模块 |
| skills/plugin-devkit/ | 描述本产品不变量的 agent skill |

跑测试

npm test # 547 个测试

node --test "packages/dsh-debugger/tests/.test.mjs" # 232
node --test "packages/dsh-debug-boot/tests/.test.mjs" # 178
node --test "packages/dsh-plugin-test/tests/.test.mjs" # 74
node --test "packages/dsh-plugin-preview/tests/.test.mjs" # 63

先腾出 8080 端口。 debug-boot 的 CLI 测试会断言一次成功启动；如果有个在跑的 debug-boot 实例仍占着 8080，其中十二个测试会以 port-in-use 失败。

需要真机的检查

这些不属于 npm test —— 它们需要 DSH 检出目录或一台真实服务器。在你的 DSH 检出目录里运行：

cd /path/to/deepseek-harness
node --import tsx/esm /path/to/dsh-plugin-devkit/packages/dsh-debugger/tests/real-cordis.mjs
node --import tsx/esm /path/to/dsh-plugin-devkit/packages/dsh-plugin-test/tests/real-process.mjs
node --import tsx/esm /path/to/dsh-plugin-devkit/packages/dsh-debugger/tests/real-registration.mjs
node --import tsx/esm /path/to/dsh-plugin-devkit/packages/dsh-debugger/tests/real-llm-probe.mjs
node --import tsx/esm /path/to/dsh-plugin-devkit/packages/dsh-plugin-test/tests/real-fake-audit.mjs

| 检查 | 预期 |
| real-cordis.mjs | 14/14 |
| real-process.mjs | 15/15 |
| real-registration.mjs | 8/8 |
| real-llm-probe.mjs | 6/6 |
| real-fake-audit.mjs | 20/20 surfaces AGREE |

以及隔离启动 smoke：它会在一台真实服务器上起 8099，并为自己准备一个一次性的 DSH_HOME：

node packages/dsh-debug-boot/tests/real-boot.mjs # 6/6

开工前值得知道的两个坑

0 字节的 $DSH_HOME/cordis.patch.yml 会让每次启动都失败。 DSH 会拒绝空的 patch 列表，所以连 dsh --profile rescue --dump-config 也一样失败 —— 与本项目无关。
空文件不等于空数组：内容必须是 []。

一个永不激活的插件会让整个启动停住。 如果你的插件 inject 了组合里没有提供的服务， DSH 会拒绝启动，/debug 也就永远跑不起来 —— 于是检查器无法解释这件事。
debug-boot 识别这种情况，并以 plugin-pending（退出码 7）报告，同时点名它在等哪个服务。

许可证

MIT —— 见 LICENSE。