zoahdev/dsh-plugin-template

dsh-plugin-template

CI
License: MIT

English · 中文

一个极简、经过验证的 DeepSeek Harness 插件社区起点模板。Fork 它、重命名它，然后发布你自己的插件——并附带一个 CI，用来证明该插件确实可被调用，而不仅仅是可被加载。

社区模板——并非 DeepSeek 官方模板，不是安全审计，也不是生产就绪认证。
测试环境：dsh 0.1.0-rc.6 · Node 24 · pnpm 11

目录结构

├── package.json              # dsh.bundle 清单 + 构建脚本（prepare = git 安装时构建）
├── cordis.patch.yml          # 插件行：id、包名、配置
├── src/
│   ├── index.ts              # 插件入口：name / inject / Config / apply + 一个 hello 工具
│   └── version.ts            # 运行时守卫使用的无依赖 caret 范围匹配器
├── tests/
│   ├── index.spec.ts         # 注册、行为、取消（单元测试）
│   └── version.spec.ts       # 预发布版本范围行为矩阵（单元测试）
├── scripts/
│   ├── integration-test.mjs  # 安装打包后的 tarball，通过 apply() 注册 hello，
│   │                         # 执行真实 handler，断言结果
│   └── dsh-smoke.sh          # 全新 DSH profile 安装 + 配置检查 + web 启动（有界重试）
├── .github/workflows/ci.yml  # 构建 → 单元测试 → 打包 → 集成测试 → DSH 启动
└── README.md                 # 双语

依赖策略（请阅读）

- 测试环境：@deepseek-ai/dsh-tools 0.1.0-rc.6 和 @deepseek-ai/cordis ^4.0.1。
- peerDependencies 声明为 "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"。这是一个 caret 范围，而非固定版本：
- 它当前匹配 0.1.0-rc.6、0.1.x 的后续 RC（rc.7、rc.10……），以及发布后的 0.1.0 稳定版。
- 它不匹配 0.1.0-rc.5/更早的 RC，也不匹配 0.0.1-rc. 系列。
- devDependencies 使用相同的范围；提交的 pnpm-lock.yaml 为开发和 CI 固定了确切的测试版本（0.1.0-rc.6）。
- 已用 pnpm 11 实证验证：如果宿主中已包含较旧的 RC（例如 0.1.0-rc.3），pnpm 的默认配置会将该旧版本链接到插件的 peer 槽位，仅给出一个通用警告——没有错误，也不会自动升级。npm 则会以 ERESOLVE 大声报错。两种工具都不会自动升级宿主。

由于静默链接是最危险的情况，当解析到的 @deepseek-ai/dsh-tools 不满足 ^0.1.0-rc.6 时，插件本身会拒绝加载（apply() 中的运行时守卫，由 src/version.ts 支撑）。静默的不匹配会变成清晰、可操作的错误。

使用方式

git clone https://github.com/zoahdev/dsh-plugin-template.git my-plugin
cd my-plugin
pnpm install
pnpm test
pnpm packsh
dsh plugin --profile web add ./dsh-plugin-template-0.1.0.tgz
dsh web --port 4099

然后向你的 agent 提问：“使用 hello 工具向 Ada 问好。”

重命名清单

- package.json：name、description、keywords
- cordis.patch.yml：插件 id 和 name
- src/index.ts：export const name、工具的 name/description
- README.md：标题、链接、作者
- 为你的 GitHub 仓库添加 dsh-plugin 主题标签

使用 dsh-plugin-doctor 检查

重命名后，在本地运行社区健康检查器（克隆一次，随处复用）：
sh
git clone https://github.com/zoahdev/dsh-plugin-doctor.git
cd dsh-plugin-doctor && pnpm install && pnpm build
node lib/bin.js --full

它会验证 manifest、patch 有效性、入口点、构建、打包，以及全新 DSH profile 的安装——与本模板 CI 运行的检查相同。参见 zoahdev/dsh-plugin-doctor。

或者使用开箱即用的 GitHub Action（无需克隆，无需构建）：
yaml
- uses: zoahdev/dsh-plugin-doctor-action@v1
with:
path: .

本模板的 CI 已在 doctor 任务中运行它。

CI

.github/workflows/ci.yml 按顺序运行（在 ubuntu 上的 test-and-load 任务）：

1. 干净检出
2. pnpm install --frozen-lockfile
3. pnpm typecheck
4. pnpm run build
5. pnpm test（单元测试）
6. pnpm pack
7. 打包集成 + 真实工具调用 —— scripts/integration-test.mjs 将实际的 tarball 安装到全新项目中，加载已安装的 bundle，通过真实的 apply() / ctx.tools.register 路径注册 hello，执行真实 handler，并断言 Hello, Ada!
8. 在 windows-latest 上的 dsh-smoke 任务：scripts/dsh-smoke.sh 将 tarball 安装到全新的 DSH_HOME，在 --dump-config 中验证插件行，以 30 秒有界重试启动 dsh web，并清理后台进程

上游说明：dsh web（0.1.0-rc.6 npm CLI）目前在 GitHub Actions ubuntu-latest 上无法启动，因为已发布包中缺少 @deepseek-ai/dsh-subprocess-local 原生 pty.node linux-x64 预构建产物。这就是启动冒烟测试在 Windows 上运行的原因（预构建产物在该平台随包发布）。上游追踪于 discussion #1686 —— 这是上游打包问题，而非模板问题。

发布清单

- [ ] pnpm typecheck 和 pnpm build 通过
- [ ] pnpm test 通过
- [ ] pnpm pack 生成 tarball
- [ ] 打包后的插件可在全新 profile 中加载（集成 + 冒烟脚本通过）
- [ ] hello 运行时调用通过并断言结果（集成脚本）
- [ ] README 双语，包含安装、配置、示例和故障排除
- [ ] 仓库主题标签：dsh-plugin
- [ ] 打一个 release 标签（例如 v0.1.0）并附带打包的 tarball
- [ ] 可选：pnpm publish 发布到 npm

健康检查说明

本模板的 CI 在范围内验证：

- manifest / 包有效性（结构、prepare、入口、文件）
- 依赖兼容性（运行时 peer 版本守卫）
- 打包产物可加载性（全新 profile 安装 + --dump-config）
- DSH 启动（web 服务返回 HTTP 200）
- 工具实际可调用性（真实的 hello 处理器执行，并对其结果进行断言）

它不声称：生产就绪、安全审计或 DeepSeek 官方背书。这是一个社区模板。在官方 dsh plugin check 出现之前（见 RFC #1629），此 CI 是最接近的可重复等价方案。

故障排查

npm：ERESOLVE peer 依赖冲突

宿主已安装了较旧的 RC，不满足 ^0.1.0-rc.6。

1. 将宿主升级到已测试版本或更新版本：

sh
pnpm dlx @deepseek-ai/dsh --version   # 必须输出 0.1.0-rc.6 或更高版本

2. 重新安装插件，使其链接到升级后的宿主：

sh
pnpm dlx @deepseek-ai/dsh plugin --profile web add

3. 不要用 --legacy-peer-deps 来消除错误——如果链接的版本仍然不兼容，插件的运行时守卫会拒绝加载。

pnpm：安装成功但插件之后加载失败

pnpm 的默认配置可能会静默地将较旧的 RC 链接到插件的 peer 槽位（已验证：0.1.0-rc.3 链接到 ^0.1.0-rc.6，仅给出通用警告）。随后插件会拒绝加载，并显示：
text
dsh-plugin-template: resolved @deepseek-ai/dsh-tools 0.1.0-rc.3, but this template is tested with ^0.1.0-rc.6. ...

1. 将宿主升级到 0.1.0-rc.6 或更高版本并重新安装（与上述两条命令相同）。
2. 可选加固：在项目/profile 的 .npmrc 中启用 strict-peer-dependencies=true，这样 pnpm 会大声失败，而不是静默链接不兼容的 peer。

你验证了更新的 RC，并希望推进模板

修改 src/index.ts 中的 TESTED_PEER_RANGE，更新 package.json（peer + dev），重新生成 pnpm-lock.yaml（pnpm install），并更新本 README 中的“Tested with”一行——这四项需一起修改。

许可证

MIT © 2026 zoahdev

中文

dsh-plugin-template 是一个最小、经过验证的 DeepSeek Harness 社区插件起点：fork 后改名即可发布，CI 不只证明“能加载”，而是证明“工具真的能被调用”。

社区模板——不是 DeepSeek 官方模板，不代表安全审计或生产就绪认证。
已验证版本：dsh 0.1.0-rc.6 · Node 24 · pnpm 11

包含内容
text
├── package.json              # dsh.bundle manifest + 构建脚本（prepare 支持 git 安装）
├── cordis.patch.yml          # 插件行：id、包名、config
├── src/
│   ├── index.ts              # 插件入口 + 一个 hello 工具 + 运行时版本守卫
│   └── version.ts            # 无依赖的 caret 范围匹配器（守卫使用）
├── tests/
│   ├── index.spec.ts         # 注册、行为、取消（单元测试）
│   └── version.spec.ts       # prerelease 范围行为矩阵（单元测试）
├── scripts/
│   ├── integration-test.mjs  # 安装打包产物 → apply() 注册 hello → 执行真实 handler → 断言
│   └── dsh-smoke.sh          # 全新 DSH profile 安装 + 配置校验 + web 启动（限时重试）
├── .github/workflows/ci.yml  # build → 单元测试 → pack → 集成 → DSH 启动
└── README.md                 # 双语
依赖策略（请读这一段）

- 已验证：@deepseek-ai/dsh-tools 0.1.0-rc.6、@deepseek-ai/cordis ^4.0.1。
- peerDependencies 声明 "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"。这是 caret 范围，不是 pin：
- 目前匹配 0.1.0-rc.6、后续 0.1.x 的 RC（rc.7、rc.10…），以及未来发布的 0.1.0 稳定版。
- 不匹配 0.1.0-rc.5 及更早 RC，也不匹配 0.0.1-rc. 版本线。
- devDependencies 使用同一范围；提交的 pnpm-lock.yaml 把开发与 CI 固定到已验证的确切版本（0.1.0-rc.6）。
- pnpm 11 实测：宿主已存在旧 RC（如 0.1.0-rc.3）时，pnpm 默认配置会把旧版本链进插件的 peer 槽，只给一条泛泛的警告——不报错、不自动升级。npm 则会以 ERESOLVE 响亮失败。两个工具都不会帮你"优雅升级"宿主。

因为静默链接才是真正的坑：插件在 apply() 里加了运行时版本守卫（src/version.ts 支撑），解析到的 @deepseek-ai/dsh-tools 不满足 ^0.1.0-rc.6 就直接拒绝加载——把静默不兼容变成清晰、可操作的报错。

使用
sh
git clone https://github.com/zoahdev/dsh-plugin-template.git my-plugin
cd my-plugin
pnpm install
pnpm test
pnpm pack
dsh plugin --profile web add ./dsh-plugin-template-0.1.0.tgz
dsh web --port 4099

然后让 agent："Use the hello tool to greet Ada."

改名清单

- package.json：name / description / keywords
- cordis.patch.yml：插件 id 与 name
- src/index.ts：export const name、工具名与描述
- README.md：标题、链接、作者
- GitHub 仓库加 dsh-plugin 话题

用 dsh-plugin-doctor 体检

改完名后，用社区健康检查器本地验证（克隆一次，随处复用）：
sh
git clone https://github.com/zoahdev/dsh-plugin-doctor.git
cd dsh-plugin-doctor && pnpm install && pnpm build
node lib/bin.js --full

它验证 manifest、patch 合法性、入口、build、pack 和全新 DSH profile 安装——和本模板 CI 跑的是同一套检查。见 zoahdev/dsh-plugin-doctor。

CI

.github/workflows/ci.yml 依序执行：

1. clean checkout
2. pnpm install --frozen-lockfile
3. pnpm typecheck
4. pnpm run build
5. pnpm test（单元）
6. pnpm pack
7. 打包产物集成 + 真实工具调用——scripts/integration-test.mjs 把实际 tarball 装进全新项目，加载已安装产物，通过真实的 apply() / ctx.tools.register 注册 hello，执行真实 handler，断言 Hello, Ada!
8. dsh-smoke job（windows-latest）：scripts/dsh-smoke.sh 在全新 DSH_HOME 安装 tarball，校验 --dump-config 里的插件行，30 秒限时重试启动 dsh web，并清理后台进程

上游说明：dsh web（0.1.0-rc.6 npm CLI）在 GitHub Actions ubuntu-latest 上无法启动，因为发布包里缺少 @deepseek-ai/dsh-subprocess-local 的 pty.node linux-x64 预编译模块。所以启动冒烟放在 Windows（预编译随包提供）上跑。这是上游打包问题，不是模板问题。

发布清单

- [ ] pnpm typecheck 与 pnpm build 通过
- [ ] pnpm test 通过
- [ ] pnpm pack 产出 tarball
- [ ] 打包产物能在全新 profile 加载（集成 + 冒烟脚本通过）
- [ ] hello 运行时调用通过并有明确断言（集成脚本）
- [ ] README 双语：安装、配置、示例、故障排查
- [ ] 仓库话题 dsh-plugin
- [ ] 打 Release（如 v0.1.0）并附 tarball
- [ ] 可选：pnpm publish 发 npm

健康检查说明

本模板 CI 验证的范围：

- manifest / 包结构有效性（prepare、入口、files）
- 依赖兼容性（运行时 peer 版本守卫）
- bundle 可加载（全新 profile 安装 + --dump-config）
- DSH 可启动（web 返回 HTTP 200）
- 工具真实可调用（真实 hello handler 执行并断言结果）

不声称：生产就绪、安全审计、官方背书。这是社区模板。在官方 dsh plugin check 出现之前（见 RFC #1629），这套 CI 是可重复执行的最接近等价物。

故障排查

npm：ERESOLVE peer 依赖冲突

宿主已有不满足 ^0.1.0-rc.6 的旧 RC。

1. 把宿主升到已验证版本或更新：

sh
pnpm dlx @deepseek-ai/dsh --version   # 必须打印 0.1.0-rc.6 或更新

2. 重新安装插件，让它链接到升级后的宿主：

pnpm dlx @deepseek-ai/dsh plugin --profile web add

3. 不要用 --legacy-peer-deps 压掉错误——就算压掉，运行时守卫也会在版本不对时拒绝加载。

pnpm：安装成功但插件加载失败

pnpm 默认配置可能把旧 RC 静默链进插件的 peer 槽（已实测：0.1.0-rc.3 被链给 ^0.1.0-rc.6，只有泛泛警告）。随后插件拒绝加载，报错形如：

dsh-plugin-template: resolved @deepseek-ai/dsh-tools 0.1.0-rc.3, but this template is tested with ^0.1.0-rc.6. ...

1. 把宿主升到 0.1.0-rc.6 或更新，然后重装（同上两条命令）。
2. 可选加固：在项目/profile 的 .npmrc 里加 strict-peer-dependencies=true，让 pnpm 响亮失败，而不是静默链接不兼容版本。

你验证了更新的 RC，想把模板推进

同步改四处：src/index.ts 的 TESTED_PEER_RANGE、package.json（peer + dev）、pnpm-lock.yaml（重新 pnpm install）、README 的“已验证版本”行。

许可证

MIT © 2026 zoahdev