Blog · 指南
什么才是 好的 DeepSeek Harness 插件
2026 年 8 月 17 日 · dshbase
我们运营着 dshbase——一个 DeepSeek Harness 社区插件目录。到目前为止，我们已经在 dsh 0.1.0-rc.6 上实测安装并启动验证了 1700+ 个插件，其中约 1400+ 个标为「已验证」。也就是说，同一类错误我们见了一遍又一遍，同一类好习惯也能让插件「开箱即用」。这篇清单，是写给想让自己的插件进第一梯队的作者的。
1. 带上 bundle 清单——否则你根本不会被加载
最最常见的「静默失败」：插件装上了，但 agent 永远不激活它。原因几乎都是缺 bundle 清单。DSH 插件不只是个 npm 包——它还需要 cordis.patch.yml（或 cordis.yml）加一个 dsh.bundle 入口，Cordis 加载器才知道要挂载它。没有它，dsh plugin add 会把你的插件当成普通依赖，然后悄悄无视。
自己测一下：dsh plugin add <你的插件>，再 dsh --profile <name> --dump-config。如果配置树里看不到你的插件入口，就是清单写错了。
2. 发 ESM，别发 CommonJS
@deepseek-ai/dsh-tools 这类核心包是 ESM-only。一个编译成 CommonJS 的插件去 import 它们，会直接 ERR_REQUIRE_ESM 挂掉。在 package.json 里写 "type": "module"，构建输出 ESM。这是目录里最高频的硬失败之一。
3. 管好你的版本 pin（dist-tag 陷阱）
@deepseek-ai/* 下几乎每个包的 latest 标签都指向一个坏的 0.0.1-rc.x，而能用的 0.1.0-rc.6 只挂在 next 标签上。如果你的插件声明了 >=0.1.0 这种区间，按 semver 预发布 0.1.0-rc.6 并不满足它，pnpm 就会报「No matching version found」。peer 依赖要对准实际发布的版本，并显式针对 0.1.0-rc.6 测试。
4. 声明你的 Cordis 契约
Cordis 对依赖很严格。插件读到的每个服务都必须声明：
inject: [...]——读了服务却没声明，会抛cannot get property "X" without inject。- 用
using/inject声明你需要的服务——否则加载器会让你的 entry 一直waiting for service: X，永远不启动。 - 别撞 loader entry ID——
code-runtime归 bundle 所有，重复注册会报「duplicate loader entry id」。
5. 老实交代你的运行时形态
DSH 在同一底座上有两个并列 surface：headless（一次性 CLI，dsh --profile x "任务"）和 web（带 webServer、storage、workspace 的完整 GUI 服务）。如果你的插件是 GUI 插件、需要这些服务，请说清楚——headless-only 测试会显示 waiting for service: webServer，一个粗心的测试者就会判定它「坏了」。需要外部账号的插件同理（xAI 登录、GitHub Packages 鉴权、付费 API）——在 README 里写明，别藏着。
6. 让安装可复现
- 别依赖只在你自己 monorepo 里存在的
workspace:引用。 - 别带一个在干净环境里会失败的
prepare构建脚本。 - 用了 native 依赖（
node-pty、koffi、protobufjs）就声明出来，让 pnpm 的allowBuilds能编译它们。
7. 「优秀」的门槛——不止「能跑」
上面这些能让你到「装得上、激活得了」。优秀的插件还要更进一步：
- 只做好一件事。 一个专一的插件，胜过二十个半成品工具的大杂烩。
- README 给出精确的安装命令，再加一句「装完会发生什么」。
- 有演示。 UI 插件一张截图胜过千言万语——而它同时也是最快的验证证据。
- 有 LICENSE，并打上
dsh-pluginGitHub topic，让别人搜得到你。 - 有测试说明。 你自己怎么知道它能用？写下来，这也会成为我们的验证信号。
如何拿到「已验证」标签
在目录里，我们验证力所能及的：全新 profile 安装 + 启动测试。但有些插件确实需要完整 web 运行时、外部账号、或特定构建环境——这些我们标 未验证，而不是瞎猜。
如果你的插件属于这类，你可以自己补上这最后一环。在你的插件页（或直接点这里）用「提交验证证据」模板开个 issue，附上插件在 dsh 里实际运行的截图或日志，我们审核后即翻成 已验证。标签就在那儿等着你拿——我们只需要一份真实可查的证据。
相关：一切皆插件 vs 插件疲劳 · 我们如何从蹭标签里甄别真插件。