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 区块