写 DSH 插件 3 个坑：npm 签名发布，省掉长期 token

DSH 插件生态现在 1700+ 个（dsh-plugin topic 实拉 2026-10-30），但「能看」和「能装」是两回事。社区维护的 dshbase 目录把 122 个收录插件逐个检测 npm 发布状态，发现 17 个真正发了 npm 包，再把这 17 个全部实测——安装、激活、启动三关——最后只有 10 个完全验证通过。剩下 7 个，各有各的翻车姿势：有装上了但激活崩宿主的，有激活正常但宿主重启拉不起来的。今天把作者侧的 3 个坑写清楚：bundle 声明、npm 签名发布、多帧日志读取。看懂这 3 个，你自己发的插件就不再是下一个被目录标灰的。

来财IP · AI行业每日情报

一、坑 1：dsh.bundle 没写 = 装个寂寞

npm 包发得再漂亮，dsh plugin add 一拉报「No valid bundle」，原因就一个：package.json 里没有 dsh.bundle 字段。dshbase 做检测时机器替你干的就是这件事——逐个拉 npm 包，检查 manifest 里有没有有效的 dsh.bundle 声明，没有的直接标灰，理由写「不能装、缺声明」。

这里有个反直觉的细节：很多插件仓库里 dsh.bundle 是有的，但指向的 ./dist/index.js 在 npm 包里没有被打进去——npm 的 files 字段没包含 dist/，包发出来就是个空壳。装上去自然报「bundle 不存在」。所以自查不能只看 package.json，要 npm pack 实际解包看 dist/ 在不在。这一条，就是 dshbase 每天跑 compat-check 帮你挡掉的那类「看起来能装、实际装个寂寞」的包。

来财IP · AI行业每日情报

10 月 18 的 Discussion 里有一条实问：一个作者发布时忘加 --provenance，包发出去了但没挂签名，dshbase 的 trusted-publishing 检测直接标它「未验证」，下游装了也不进绿名单。后来社区把它列进「已修复」清单——加上 provenance 重新发布，第二天 compat-check 就全绿了。这就是签名发布和绿标之间的直接关系。

二、坑 2：长期 token 发布 = 埋一颗雷

老方法是 CI 里塞一个 npm 长期 token（//registry.npmjs.org/:_authToken=xxx 写进 GitHub Secrets），跑 npm publish。这个 token 在 secrets 里一躺就是好几个月：泄露了没人知道、换 token 得手动改 Secrets 重跑、多维护者协作时更是灾难——你轮换一次，所有人的 CI 全挂。

新方法 npm 官方 2024 年起支持，DSH 生态 10 月已经落地：GitHub Actions OIDC + Sigstore provenance。dshbase 目录里标「Trusted Publishing ✅」的插件（比如社区两个 OCR 插件 @maxwell-feng/dsh-windows-ocr 和 dsh-tesseract-ocr），走的都是这条路。

CI 里配 @actions/github@v4 + npm 的 provenance 支持，长期 token 直接退役。10 月还在用老 token 发插件的，现在应该迁移——迁移一次，以后再也不用操心 token 轮换这件事。

来财IP · AI行业每日情报

三、坑 3：会话日志是多帧 zstd，单帧 API 读不全

要给 DSH 写「读会话历史出日报」这类插件（社区里 dsh-report-studio 就是干这个的），会撞上一个格式坑：会话日志是 zstd 压缩的，而且是多帧结构——长会话会切成多帧连续存，不是单一压缩块。

写插件读日志的，最低版本要求 rc.4，读日志用流式多帧 API，别图省事用单帧 decompress。这条坑专门被列进踩坑合集的第 6 坑（叫「多帧 zstd」），因为它是唯一「代码不报错、结果就是错的」那类——单帧 API 读多帧日志，前半段正常，后半段悄悄丢了，你根本不知道日报缺了内容。

四、10 分钟起步：把一个插件发出去的 3 步

不想从零搭，最短路径就是 3 步，每步对着 1 个坑做。

第 1 步：初始化工程，对坑 1。 用社区 dsh-plugin-starter 一条命令生成工程（bundle 声明、ESM type、依赖清单都已经配好），加 --verify 冒烟。别手写 package.json——手写的翻车点全在 files 字段漏 dist/。生成完 npm pack 解包看一眼，确认 dsh.bundle 指向的文件在包里有，坑 1 闭环。

第 2 步：CI 换签名发布，对坑 2。 GitHub Actions 里：@actions/github@v4 做 OIDC 登录，npm 仓库设置里开 Trusted Publishing，发布命令改成 npm publish --provenance。旧的 token 从 Secrets 里删掉，以后 CI 里再没有长期凭据。

第 3 步：读日志的用多帧 API，对坑 3。 如果你的插件要读会话历史（出日报、做周报、做交接文档），把日志读取封装成流式多帧 zstd，别用单帧 decompress。最低版本钉 rc.4。

3 步走完，再上 dshbase 的 3 关（安装 / 激活 / 启动）自测一遍，全绿就提交目录收录。

五、3 关验收 + 免费 CI 看门人

dshbase 的实测口径是 3 关：安装关（dsh plugin add 无错）、激活关（启用后不崩宿主）、启动关（宿主重启后自动拉起正常）。那 10 个通过的，全是 3 关全绿。

发布日当天还能多做一件事：把你的插件提交进 dshbase 目录。目录不收钱、不卡你——给仓库加 dsh-plugin topic 就会被收录，然后它开始每天对你的包跑 compat-check（fresh-profile 安装验证），结果写回你的仓库。等于免费请了个 7x24 的 CI 看门人。目录里那 10 个全验通的插件，有几个就是被 compat-check 盯出问题后自己修好的——绿标不是荣誉，是「每天都被机器装一遍还没死」的证据。

六、3 个坑的成本账

3 个坑的共同特点是「翻车时不报错」——静默错。这类错最贵，因为发现要等下游用错的数据做了决策。发布前 30 分钟自查一遍，比事后追 1 周 bug 便宜得多。

3 个坑里有 2 个在 10 月的实问里真的翻过车：一个作者忘加 --provenance，包发出去没挂签名，被 dshbase 标「未验证」，下游装了也不进绿名单；另一个插件的 package.json 声明了 dsh.bundle，但 files 漏了 dist/，装上去直接报「bundle 不存在」。都是发布前 30 分钟 npm pack 看一眼就能挡掉的——静默错里最便宜的防法，就是把「看起来能装」和「真的能装」这两件事分开验。

七、这对你的业务意味着什么

插件生态 1700+ 听着热闹，真正能进生产的是过了 3 关的那批。招商、招商团队用 DSH 做自动化前，先查你要装的插件在 dshbase 里是「绿」还是「灰」；自己写插件的，按 3 个坑自查一遍再发——bundle 声明、签名发布、多帧日志，哪条缺了下游就哪条翻车。生态的「能用率」不是官方说的，是这一批社区实测跑出来的，你选型的时候也该把它当一手数据看。

八、给 3 类读者的速查：你现在该干哪一步

3 个坑 + 3 类读者，都是 30 分钟能做完的事。做完了，你在这个生态里的位置就从「等出事了才知道」变成「事先就知道」。

九、数据口径声明

• DSH 主仓：Star 266886、0 open issue（GitHub API 2026-10-31 一手核验）。
• 插件生态 1700+ 为 dsh-plugin topic 实拉 2026-10-30 口径；dshbase 目录「122 收录 / 17 可装 / 10 全验通」为社区 Discussion #1012 一手数据。
• Trusted Publishing 为 npm 官方机制（OIDC + Sigstore provenance），DSH 生态 10 月已有多插件落地。
• 多帧 zstd 坑源社区教程 Discussion #961 踩坑合集第 6 坑。

关注后，下一篇自动追更：「DSH 插件 1700+ 怎么筛：绿灰标判据 + 3 关实测清单」。 关注后台回复「插件」，领 DSH 插件发布 3 坑自查清单（bundle 声明 / OIDC 签名 CI / 多帧日志读法）。

免责声明：本文数据均来自公开渠道，仅供信息参考，不构成任何投资或使用建议