DSH plugin 发布到 npm：git 安装的构建坑、发包前检查与 pnpm publish 流程

把 DSH plugin 发布到 npm 的核心价值是「分发预构建代码」：npm 上装到的是已经编译好的产物，用户安装时不触发任何构建脚本、不需要 allowBuilds 授权；而 git 安装拉的是源码，缺 prepare 就缺 lib/，装完即坏。 无论你叫它 DSH插件 还是 DeepSeek插件，发布要遵守的约束完全一致。

先说坑：DSH plugin 从 git 安装拿到的是源码

git 安装不会运行你的 build 脚本，TypeScript 包到手时没有 lib/ 输出。 官方把这个坑讲得很直白，修法分两侧（来源）：

1. 作者侧提供 prepare 脚本：pnpm 在 git 安装后执行它，从源码构建发布入口，且必须自包含——不能假设存在同级 monorepo 检出这类 dev-only 上下文。
2. 用户侧放行构建：pnpm ≥10 默认拒绝执行 git 依赖的 prepare，第一次 dsh plugin --profile demo add github:you/hello-plugin 会失败；dsh 会指出修法，把 pnpm 打印的包键写进 profile 的 pnpm-workspace.yaml，预期重新 add 即可装上：

allowBuilds:
  dsh-hello-plugin: true

必须把这条授权当回事：它等于「允许该包在你机器上安装期执行代码」，不受 agent 沙箱约束。只放行你信任源码的包，并钉住 commit（github:you/hello-plugin#<sha>），否则后续一次推送就可能悄悄换掉真正运行的代码。

为什么 DSH plugin 发 npm 更省事

发 npm 把「构建」从用户机器搬到了你的发布流程里。 官方给出的两条「不需要任何构建权限」的分发路径是：

用户侧只要 dsh plugin add <包名> 就能装到预构建代码。这就是「为什么推荐发 npm」的全部理由——不是名气问题，是安装期少一步授权、少一类故障。

DSH plugin 发包前检查清单

五项缺一不可，缺了的表现是「装上了不生效」而不是清晰报错。

1. main（或 exports）指向构建后的入口——不是 src/；
2. type: module；
3. files 包含入口与 cordis.patch.yml——漏掉 patch 文件，配置层就不会被安装；
4. dsh.bundle.patch 指向 patch 文件——漏掉它，包只会作为普通依赖装上，不激活任何层；
5. version 已按语义化版本递增——npm 不允许覆盖已发布版本。

先本地 dsh plugin add ./hello-plugin 装通再发包，打包结构与层顺序见 打包成 bundle。

DSH plugin 发布到 npm 的流程

流程本身很短，风险都在上一步的检查里。 典型顺序：

1. 构建发布产物：pnpm run build，预期 lib/ 是最新的。
2. 本地按安装路径自测：在干净 profile 里执行 dsh plugin --profile demo add ./，预期插件能加载、行为生效。
3. 发布：pnpm publish。

两个容易忽略的点：① 作用域包（@your-scope/xxx）首次发布要显式声明公开，否则默认私有；② 发布后建议打一个对应的 git tag，让「用户装的版本」与「你仓库的提交」能对上——排查线上问题时这一步省时间。

备选：DSH plugin 用 pnpm pack 出 tarball

内网分发或想先小范围试用时，用 tarball 代替 npm。 官方给出的方式：

1. 作者侧打包：pnpm pack，预期产出 dsh-hello-plugin-0.1.0.tgz。
2. 用户侧安装：dsh plugin add ./hello-plugin-0.1.0.tgz，预期装到构建后产物。

tarball 同样是构建后产物，因此同样不需要构建权限；代价是没有版本索引，升级要靠重新发文件。

DSH plugin 发布后验证

验证必须在干净环境里做，否则你验证的是「本机已有依赖」而不是「包本身完整」。

1. 换一个 profile（或用干净机器）：dsh plugin --profile fresh add <包名>；
2. 不启动先看层：dsh --profile fresh --dump-config，确认出现该 bundle 的层；
3. 启动并观察插件日志；
4. 需要收录进插件目录时，再走 发布到插件中心，装好后可在 DSH Plugin Hub 的已安装列表核对。

如果装完报「找不到入口」，先查 main 指向的文件在不在 files 里——这是发 npm 最常见的翻车点，本地能跑是因为本地有 src/，发布包里没有。环境层的问题（Node 版本、pnpm）见 开发环境搭建。