dsh-hello-plugin：DSH 插件最小骨架

前言¶

在开发 DeepSeek Harness（DSH）插件时，最常遇到的问题是：不清楚一个插件到底需要哪些文件，每个文件负责什么。这会导致装上后「没反应」，或者热重载时撞名。下面介绍一个最小可用的 DSH 插件，它向宿主注册一个 hello_plugin 工具，同时把「一个 dsh 插件到底需要哪些文件、每个文件负责什么」压缩到能一眼看完的程度。

这是什么¶

名称：dsh-hello-plugin
维护者：mrkeyoe
仓库：mrkeyoe/dsh-hello-plugin
定位：一个最小可用的 DSH 插件示例，展示必需文件与职责；可作为编写新插件的骨架

核心功能¶

注册一个宿主工具：hello_plugin
零运行时依赖（@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");
}

三个容易踩的点：

必须把注册动作放进 ctx.effect(...)。直接 ctx.tools.register 也能跑，但插件卸载或该行被 disable 后工具不会注销，热重载会撞名。
inject 声明什么，apply 里才能直接用 ctx.<service>。想要别的服务（settings、webServer、llm），加进 inject 数组。
工具要有 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` 块

适用场景与注意¶

适合想要快速上手 DSH 插件开发、需要明确文件结构示例的开发者
插件以当前 dsh 进程权限运行；安装前应检查源码与许可证

短结尾¶

这个示例把一个 DSH 插件所需的文件与职责压缩到最少，直接照着改就能起步。仓库地址：https://github.com/mrkeyoe/dsh-hello-plugin