如何发布一个 DeepSeek-Harness 插件(npm 对比 GitHub)并被发现

发布一个 DeepSeek-Harness(dsh)插件,意味着让它能通过 dsh plugin --profile <name> add <specifier> 被安装——要么发布成预构建的 npm 包,要么发布成 GitHub 仓库——然后让它能被人找到,因为 dsh 并没有运营一个插件市场或提交表单。本文覆盖这两半:该发布什么,以及它是怎么被发现的。

npm 对比 GitHub:真正的区别是谁来跑构建

两者都是官方支持的安装源,机制也完全一样——dsh plugin add 只是转发给 pnpm。真正对你的用户有影响的区别是构建发生在哪里:

发布到 npm,你在发布时构建一次,发布出编译好的产物。从 npm 安装的用户永远不会跑你的构建流程。
只发布到 GitHub(目前更常见的路径,因为这是一个年轻、快速演进的生态)时,pnpm 拉取的是源码而不是产物——你的 prepare 脚本必须在每次安装时都跑一遍,而这恰好是触发 pnpm 10+ allowBuilds 安全提示的原因。

两者都不算"错",但 npm 之所以是官方推荐的路径,恰恰是因为它彻底把一个安全决策从你的用户手里拿掉了。

发布到 npm

在 npm publish / pnpm publish 之前,确保你 package.json 的 files 数组真的包含了 dsh 在运行时需要的一切——不只是编译好的入口文件,还有 cordis.patch.yml:

{
  "name": "dsh-hello-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "lib/index.js",
  "files": ["lib", "cordis.patch.yml"],
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" }
  }
}

把 cordis.patch.yml 漏在 files 之外是一个真实存在的常见错误——包能正常安装,dsh.bundle.patch 在你本地的源码树里也能正常解析,但这个文件根本不在发布出去的 tarball 里,所以对任何真正从 registry 安装的人来说都会 404。发布前用 pnpm pack 跑一遍并检查生成的 .tgz——里面应该同时包含你编译好的代码和 patch 文件,你的 Config schema 或插件逻辑依赖的东西一个都不该缺。

因为这种方式发布出去的包已经带了构建产物,你通常不需要 prepare 脚本——那是专门给通过 GitHub 分发的源码用的,pnpm 需要在 checkout 之后编译它。如果你还是选择同时把源码和预构建产物都发布到 npm,留着 prepare 也没坏处,但真正让 npm 路径跳过构建权限提示的,不是 prepare,而是在 files 里发布了编译好的 lib/。

通过 GitHub 发布

如果你还没准备好管理 npm 发布,一个打好 tag 的 GitHub 仓库本身就能当安装源用——dsh plugin --profile <name> add github:owner/repo。这里的权衡是:

用户拉取的是源码而不是产物,所以你的仓库需要一个能正常工作的 prepare 脚本,在安装后自动把 src/ 编译到 lib/(或者你 main 字段指向的任何地方)。
第一次有人安装它时,pnpm 10+ 会默认拦截这个 prepare 脚本,并要求用户显式在他们 profile 的 pnpm-workspace.yaml 里加上 allowBuilds: { your-package: true }——这是一个真实存在的摩擦点,dsh 文档把它定性为一个真正的安全决策,而不是走个流程:这是"允许在安装期、脱离任何 agent 沙箱的情况下,在你的机器上执行这个包的代码"。这个提示的用户侧体验,见《从 GitHub 安装 DeepSeek-Harness 插件》。
鼓励用户锁定一个具体 commit(github:owner/repo#<sha>),而不是跟踪某个分支——不锁定的话,之后对你默认分支的一次推送,就会在下次有人重装或更新时,悄悄改变实际运行的代码。

两条路径本身没有谁更"正规"——整个生态里不少真实、被广泛使用的插件都只发布在 GitHub 上。但如果用户反馈了构建摩擦或者信任方面的顾虑,把预构建产物发布到 npm 是最直接的解法。

版本管理:没有独立的 dsh 版本体系

插件的版本管理就是普通的 pnpm/npm semver——dsh 没有在其上叠加自己的发布或兼容性体系。dsh plugin --profile <name> update 对你 profile 的依赖执行的是 pnpm update 语义;除了 npm 和 Git 本身已经提供的东西(package.json 里的版本范围,或者 GitHub 安装用的 commit SHA)之外,没有 dsh 专属的 changelog 格式或版本锁定机制。

真正有助于被采用的 README 惯例

没有强制的 README 格式规范,但整个生态里已经形成的惯例——也是包括 FindHarness 在内的大多数爬虫和目录站会期待看到的——是在文档靠前的位置放一条可以直接复制粘贴、用户所需的完整安装命令:

dsh plugin --profile web add your-package-name
# or, for a GitHub-only release:
dsh plugin --profile web add github:owner/repo

如果可以的话,尽量避免在这段示例里用 <profile> 这种占位符——web 是每个用户默认就有的那个 profile。

发现机制到底是怎么运作的

除了 npm 和 GitHub 本身,dsh 没有官方的插件市场、提交表单或 registry,所以"被发现"归结为两个具体、低成本的步骤:

给你的仓库打上 GitHub topic dsh-plugin。 这是官方 README 明确点名的唯一发现机制——也是基于 topic 搜索的工具首先会去找的信号。这个 topic 在实践中到底有多噪、以及为什么光靠这个标签不足以让一个工具信任你是真插件,见《如何找到 DeepSeek-Harness 插件》。
被收录进 awesome-dsh-plugin/awesome-dsh-plugin,目前维护最活跃的社区索引——它接受按既定的 - [owner/repo](url) - 一句话描述 格式提交 PR 新增条目。

为什么 `dsh.bundle.patch` 字段才是真正验证你的东西

任何人都能轻易给自己的仓库打上一个 GitHub topic——这并不能证明一个仓库是一个真实、能正常工作的 dsh 插件,而不是一个只是在 README 里提到 dsh 的项目。真正有功能意义的信号,还是本系列文章里反复出现的那个 dsh.bundle.patch 字段:一个想把真插件和噪声区分开的目录站,可以检查一个候选仓库的 package.json(对于发布到 npm 的包)是不是真的声明了它。这正是 FindHarness 自己的 /plugins 目录在社区精选的 awesome-dsh-plugin 列表之上采用的验证方式——与其说是一个提交表单,不如说是正确发布这个字段、并被收录进会被检查的数据源之后自然产生的结果。同一套验证逻辑在安装者那一侧是什么样,见《如何在安装前审查一个 DeepSeek-Harness 插件》。

如何发布一个 DeepSeek-Harness 插件(npm 对比 GitHub)并被发现

npm 对比 GitHub:真正的区别是谁来跑构建

发布到 npm

通过 GitHub 发布

版本管理:没有独立的 dsh 版本体系

真正有助于被采用的 README 惯例

发现机制到底是怎么运作的

为什么 `dsh.bundle.patch` 字段才是真正验证你的东西

FAQ

我必须发布到 npm 才能被收录吗?

发布所需的最低限度 `package.json` 是什么样?

我也应该加一个 `dsh-plugin` 的 npm keyword 吗?

我怎么知道发布出去的包在一次干净安装下真的能用?

下一步