插件开发模版 elonnzhang/dsh-plugin-template

dsh-plugin-template

DeepSeek Harness（dsh）插件开发模版。提供两套可直接复制的起点、一套构建方式，以及把插件加载进 dsh 的完整路径。

模版里的每一处 API 都对照 npm 上已发布的 @deepseek-ai/ 包类型核对过，并通过了本仓库的 typecheck → build → smoke 三步验证。

两套模版

| | packages/minimal | packages/full |
| 定位 | 一个插件的最小可用形态 | 逐项演示 harness 的全部主要扩展点 |
| 代码量 | 1 个文件 | 8 个文件，按扩展点分文件 |
| 覆盖 | name / inject / Config / apply + 一个工具 | 见下方清单 |
| 适合 | 加一个工具、写个小钩子 | 做一整套能力，或当作 API 速查 |

full 覆盖的扩展点：

- 配置 — Schemastery schema、默认值、加载时校验（src/config.ts）
- 类型化事件 — 声明合并 + emit / waterfall 两种分发模式（src/events.ts）
- 能力分层 — Service Definition / Provider / Consumer 三角色（src/capability.ts）
- 模型工具 — 嵌套参数 schema、规范值、Native 渲染器、UI 卡片、超时、并发分类（src/tool-echo.ts）
- 长任务 — ctx.jobs 后台任务句柄、前台/后台双分支、取消语义（src/tool-watch.ts）
- 执行策略与观测 — tools/pre-execute、ctx.tools.guard()、tools/post-execute、tools/result（src/hooks.ts）
- 系统提示词 — ctx.systemPrompt.section() 与 order 约定（src/prompt.ts）
- 斜杠命令 — ctx.commands.register()，面向人而非模型（src/command.ts）
- 生命周期 — ctx.effect() 手动清理、ctx.plugin() 子插件组合（src/index.ts、src/hooks.ts）

前置条件

- Node.js ^22.19.0 || >=24.0.0
- pnpm（本仓库用 pnpm workspace 管理两个模版包）
- dsh CLI —— 仅在加载插件时需要；构建和类型检查不需要它

跑通

pnpm install
pnpm run check # typecheck + build + smoke

check 通过意味着两个模版都能编译、产物可加载、Config schema 能求值出默认值。

接着挂进 dsh 看效果：

pnpm run dev:web # 生成开发 overlay 并用它启动 Web UI

在对话框里输入 Use the greet tool to greet Ada.，模型会调用 greet 工具。

插件契约

一个 dsh 插件就是一个导出 apply 的模块。框架加载时调用 apply(ctx, config)，你通过 ctx 注册能力：

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin' // 插件标识
export const inject = ['tools'] // 依赖的服务；apply 运行时它们必然就绪

export function apply(ctx: Context) {
// 在这里注册能力 }

四条要点：

- 注册是可逆的副作用。 通过 ctx 注册的一切 —— 工具、事件监听、提示词段、命令 ——在插件卸载或热替换时自动撤销。需要手动清理的资源用 ctx.effect() 返回清理函数。
- inject 表达加载顺序。 声明的服务未就绪时插件停在 PENDING，这是合法状态而非错误：它不打印任何东西，所以「插件没反应」的第一个排查方向就是 fiber 状态。
- 可选依赖不写进 inject。 在使用点用 ctx.get('logger') 查询，缺失时降级。
- 不要硬编码可调参数。 凡是不同部署可能取不同值的，都必须是 Config 字段。
检验标准：能否只改 cordis.patch.yml 就改变它，而不动代码？

插件也可以写成对象形式（export default { name, inject, apply }）或类形式（extends Service，用于对外提供服务）。函数形式覆盖大多数场景。

构建

两个模版都用 tsdown 从 src/ 直接产出 lib/index.js + lib/index.d.ts：

pnpm run build # 两个包
pnpm --filter dsh-plugin-full run dev # watch 模式

构建器只用 tsdown 一个。为什么不是 tsup（官方已停止维护）或 Vite（library mode 不会自动 external dependencies / peerDependencies），对照见 docs/build.md。

一条不能违反的规则：@deepseek-ai/cordis 与 @deepseek-ai/dsh- 必须 external。
它们声明为 peerDependencies，运行时由 dsh 安装本身提供。打进产物会出现第二份 Context / Service 基类，插件与宿主无法互通。

细节（产物约定、prepare 脚本、为什么 tsc 只做 --noEmit）见 docs/build.md。

加载到 dsh

三种方式，按开发阶段选：

| 方式 | 命令 | 何时用 |
| 安装进 profile | dsh plugin --profile demo add ./packages/full | 最接近用户真实环境，验收用 |
| --patch overlay 指向产物 | dsh web --patch ./dev/cordis.dev.local.yml | 日常开发；配合 tsdown --watch |
| --patch overlay 指向源码 | 同上，overlay 里写 src/index.ts | 需要源码 checkout 的 dsh（能加载 TS） |

完整说明 —— 配置层顺序、patch 语法、--dump-config 调试、HMR 行为、profile 与组合包的区别 ——见 docs/load-into-dsh.md。

开始你自己的插件

每个模版目录都是自包含的（自带 package.json / tsconfig.json / tsdown.config.ts，不 extends 仓库根配置），复制出去就能独立成仓库：

cp -r packages/minimal ~/my-dsh-plugin
cd ~/my-dsh-plugin && pnpm install && pnpm run build

复制后要改的地方：

1. package.json 的 name（也是 patch 行引用它的名字）、description、version
2. cordis.patch.yml 里的 id 与 name（name 必须等于包名）
3. src/index.ts 的 export const name
4. 工具名、Config 字段

如果打算通过 dsh plugin add github:you/repo 分发，插件包必须位于仓库根目录 ——
git 安装拉取的是仓库根，而不是某个子目录。所以请把复制出去的目录作为新仓库的根。

目录结构

dsh-plugin-template/
├── packages/
│ ├── minimal/ # 最小化模版（自包含，可直接复制） │ └── full/ # 全能力模版（自包含，可直接复制） ├── dev/ # 开发用 --patch overlay（生成物被 gitignore） ├── scripts/ │ ├── dev-patch.mjs # 生成带绝对路径的开发 overlay │ └── smoke.mjs # 加载产物、校验插件契约 └── docs/ ├── build.md # 构建方式 ├── load-into-dsh.md # 加载到 dsh ├── api-cheatsheet.md # 扩展点速查 └── publish.md # 发布与分发

上游文档

本模版是对 harness 官方文档的可运行提炼。深入阅读：

- 插件入门 → docs/user/develop/basic/（第一个插件、工具、配置、打包安装）
- 框架机制 → docs/user/develop/framework/（服务与依赖、事件系统）
- 能力分层 → docs/user/develop/practice/
- 工具约定的真源 → docs/cookbook/adding-a-tool.md
- 扩展形态汇总 → docs/cookbook/extension-cookbook.md
- Cordis 框架 → docs/cordis-primer.md、docs/cordis-tutorial/
- CLI 行为（层优先级、flag、profile）→ apps/cli/reference/README.md
- 每个服务/事件的生成参考 → docs/subsystems/*.md 的 cordis-surface 区块