插件骨架模板 mrkeyoe/dsh-hello-plugin

dsh-hello-plugin

一个最小可用的 DeepSeek Harness（dsh）插件：向宿主注册 hello_plugin 工具。
它不堆砌玩具 demo，而是把「一个 dsh 插件到底需要哪些文件、每个文件负责什么」压缩到能一眼看完的程度 —— 抄这份骨架改名即可起步。

- 零运行时依赖（@deepseek-ai/dsh-tools 由宿主提供）
- 单一职责：一个工具、一个 effect、一处配置
- 附离线冒烟测试，不用启动 DSH 就能验证接线是否正确

目录结构

dsh-hello-plugin/
├── package.json # 插件身份 + dsh.bundle.patch 声明 ├── cordis.patch.yml # 向 bundle 插入加载行（id / name / config） ├── lib/index.js # 宿主入口：export name / inject / apply ├── test/smoke.mjs # 离线冒烟测试（node test/smoke.mjs） ├── README.md ├── CHANGELOG.md ├── LICENSE └── .gitignore

四个必需文件各自的职责

| 文件 | 必需性 | 作用 | 缺了会怎样 |
| package.json | 必需 | 包身份、main 入口、dsh.bundle.patch 指向 patch 文件 | 无法被 profile 当作 bundle 解析 |
| cordis.patch.yml | 必需 | 往 loader 树里插入一行 id + name，config 即 apply 收到的第二个参数 | 包被安装但永远不会加载 —— 表现为「装了没反应」 |
| lib/index.js | 必需 | Cordis 插件本体：export const name / export const inject / export function apply(ctx, config) | 加载行报错或插件空转 |
| LICENSE | 强烈建议 | npm / GitHub 上别人能否合法复用 | 法务上等同于「保留所有权利」 |

README.md、CHANGELOG.md、test/ 不是加载所必需，但没有它们的仓库没人敢用。

契约要点

export const name = "dsh-hello-plugin"; // 与 package.json 的 name 保持一致
export const inject = ["tools"]; // 依赖的服务；全部就绪后 apply 才会被调用
export function apply(ctx, config) { // config 来自 cordis.patch.yml 的 config 块
ctx.effect(() => { // effect 内的东西在插件卸载时自动释放
const dispose = ctx.tools.register(tool);
return () => dispose();
}, "label");
}

三个容易踩的点：

1. 必须把注册动作放进 ctx.effect(...)。直接 ctx.tools.register 也能跑，但插件卸载或该行被 disable 后工具不会注销，热重载会撞名。
2. inject 声明什么，apply 里才能直接用 ctx.<service>。想要别的服务（settings、webServer、llm），加进 inject 数组。
3. 工具要有 output.schema 和 render。缺 render 时返回值会以原始 JSON 落到对话里；render 应直接返回 ContentBlock[]（[{ type: "text", text }]），不要返回裸字符串。

本地开发

离线验证接线（无需 DSH 运行）
node test/smoke.mjs

或
npm test

冒烟测试会在 node_modules/ 里造一个 @deepseek-ai/dsh-tools 的 identity stub —— 该包由宿主运行时提供，普通 node 解析不到。所以它证明的是接线正确，不是宿主行为正确。

装进自己的 DSH 验证

1. 链接进当前 profile（以桌面版为例，路径按实际 profile 调整）
cd ~/.dsh/profiles/desktop
npm install --no-save /path/to/dsh-hello-plugin

2. 把包名登记进 package.json 的 dsh.profile.bundles 以及在 dependencies 里加一行 "dsh-hello-plugin": "file:/path/to/dsh-hello-plugin"

3. 重启 DSH，然后在会话里让 agent 调用 hello_plugin

装好后 hello_plugin 会出现在工具列表里；cordis.patch.yml 的 config.greeting 改一行、重启，问候语就跟着变。

配置

| 键 | 默认值 | 说明 |
| greeting | 你好 | 问候语前缀，来自 cordis.patch.yml 中该行的 config 块 |

License

MIT