dsh-publish-gate — 帮你发布 DSH 插件的一键三连门禁

这个插件是给插件作者用的：你写完一个 DSH 插件，想发 GitHub + npm + 插件市场，它帮你把发布前该查的全部查一遍，再给你照抄的命令清单。

发布一个 DSH 插件有七步，每一步都有一个直到你付出代价才说话的坑：files 忘了 lib/ 于是发出去一个空包、PowerShell 写下的 BOM 让 JSON.parse 报一个不提 BOM 的错、patch 的 insert 行缩进错了于是插件装上了但永远不加载、裸包名让 granular token 收到一个既不说 token 也不说 scope 的 403。这个插件把整条链路的每个静默坑变成一条确定性检查。

十个 agent 工具：全量门禁、运行时注册检查、发后校验、patch 专项、市场条目校验、版本推进、多插件体检、发布命令清单、本地开发链路诊断。

门禁分三层：清单层看 package.json / patch / 入口源码，产物层真的跑一遍 npm pack --dry-run 看 npm 到底会发出什么，运行时层在独立子进程里 import() 入口并 apply(ctx) 一遍，看它到底注册了什么。

自检：看不见的 finding

severity 不是 error/warn/info 的 finding 会被所有计数器忽略，等于规则从没触发过。publish_gate 现在会把这类 finding 提升成一条 internal-bad-severity 的 error，测试里还有一条源码扫描盯着 F(...) 的第二个参数。这条网加上当天就抓到了我自己的同一个错误。

测试层：门禁真的会跑一遍你的测试

tests-fail / tests-timeout / tests-not-run 三条规则会以 node --test 在插件目录里真跑一次（不经过 npm test，因为脚本内容由作者决定、可能 shell 出去）。子进程会去掉继承来的 NODE_TEST_CONTEXT——否则当门禁本身跑在 node --test 里时，子进程进入 test-child 模式、一个摘要都不打印，看起来像"没有测试"。

典型用法（写完插件后）

我写好了一个新插件 X，帮我发出去
→ agent 先调 publish_gate(X) 查所有静默坑（清单 + 产物 + 运行时三层）
→ 有 blocker 就修，修完再跑
→ 全绿后调 publish_gate_commands(X, {version}) 拿 GitHub/npm/市场三步的命令，照抄执行
→ 发完调 publish_gate_verify(X) 确认 registry 上那包的 shasum 和你本地这份一致

安装

dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate

重启 DSH 后生效。只读：这个插件从不写你的插件目录。

Agent 工具

检查清单

会真的挡住发布的（error）

值得在发布前知道的（warn / info）

npm-scope-mismatch（登录的账号不是包 scope 的所有者，PUT 会 403，而错误里既不说 token 也不说 scope——我为一个 403 花了一小时）、unscoped-name（granular token 的 403）、repo-missing、patch-name-unresolvable（junction 放错层级）、inject-unused-service（inject 里写了个拼错的服务名，cordis 一直等它，插件静默不激活）、no-publish-config-access（scoped 包没写 publishConfig.access，只是提醒，因为命令里本来就带 --access public）、publish-config-registry（publishConfig.registry 指到内网 registry，版本发到别人装不到的地方）、no-readme / readme-no-install / readme-no-profile、license-mismatch、no-tests / no-test-files / no-test-script、no-engines、bad-repo-url、no-git / no-gitignore、readme-path-missing（README 里点名的仓库内文件路径已经不存在了，照着敲就是 ENOENT）、readme-tool-undocumented（README 没提这个工具）/ readme-test-count（README 写的测试数和真实数不一致）、changelog-missing-version（要发的这个版本号在 CHANGELOG 里没有对应标题，npm 照样发，发布说明就永远落后一版）、changelog-no-versions（CHANGELOG 里没有版本标题，读者对不上自己装的那版）、no-changelog（只是提醒）、changelog-not-shipped（CHANGELOG 在本地但没进 tarball——npm 只强制带 README 和 LICENSE，你一直更新的那份文件在 registry 页面上看不见），以及市场条目的 market-* 全系列。

产物层：npm 到底会发出什么

清单层只看 files 字段，而 npm 有它自己的规矩（main / exports 指向的文件强制入包、README/LICENSE/package.json 强制入包）。所以这一层真的跑一遍 npm pack --dry-run --json --ignore-scripts，读它返回的文件清单和体积。

运行时层：apply 之后到底注册了什么

前两层都是读文件，读不出「装上能不能用」。这一层在独立子进程里 import() 入口、用假 ctx 调一次 apply(ctx)，把 ctx.tools.register 收到的每一条拿回来检查。20 秒超时，你的插件代码不在宿主进程里跑。

入口按 exports["."] → main → lib/index.js 的顺序解析。**早先写死 lib/index.js，拿三十一个真实已装插件一测，二十个报"入口抛异常"——其中两个的入口是 index.mjs，根本没有 lib/。**误报比漏报更贵：一个满屏假错误的门禁，第二次就没人跑了。

浏览器半边：侧栏面板到底会不会出现

清单层只检查「声明了 client 平台就得有 exports["./client"]」，可这一步过了之后还能坏很多次。而且它坏得很安静：宿主半边照样跑、工具照样能用，只是侧栏里什么都没有——看起来像 UI bug，其实是打包/注册 bug。

所以这一层真的把那个 bundle 在一个子进程里跑一遍：造一个假的 window.__ModuleLoader__、假的 require('react')，再给一个 ctx——effect / inject 会立刻执行回调，其余服务（sidebarRightTabs、slots…）每被调用一次就记一条。

市场层：提交之前就能知道会不会被打回

本地全绿之后，发布还会在提交门禁那儿停一次。停的原因通常只有三种，而且三种都能提前查：

代码卫生

lib-debugger（error）、lib-console-log（每个文件一条，带次数；浏览器半边豁免——那里 console.log 是调试通道，不是宿主日志残渣）、lib-hardcoded-path（C:\Users\... 硬编码）、lib-url-pathname（new URL(...).pathname 在中文路径上会百分号编码，得用 fileURLToPath）、node-too-old（engines.node 写着 >=18，lib/ 里却用了 Object.groupBy（21）或 Promise.withResolvers（22）。npm 对 engines 只是警告，照样装上，然后在 import 那一刻抛——用户看到的是「插件坏了」，不是版本不匹配）。字符串和注释里的同名文字不算。

依赖真实性：lib/ 里 import 的东西，消费者那边真的会装上吗

npm install 装一个包时只装它的 dependencies，永远不装 devDependencies。所以在你自己仓库里 import 'x' 能跑（依赖树是完整的），到了用户那边 ERR_MODULE_NOT_FOUND——插件装上了，然后加载失败，用户看到的是「这个插件坏了」。

内置模块（node:fs、fs/promises）、相对路径、以及浏览器半边从宿主 require 拿到的 react 都不算。工具描述里那句 require("react") 是散文，也不是依赖——这条规则最早就是被它自己误报出来的。

构建产物：src/ 和 lib/ 谁更新

有 src/ 的插件（TypeScript 源码 + 构建出来的 lib/）最容易在这件事上翻车，而且两种翻车的表现一模一样——发出去的字节没人跑过：

两条都只是 warn：有可能你就是要发手改的产物（我干过）。但发之前你得知道自己在发什么。

可追溯性：一周后你还能指出线上那包是哪份代码吗

发布是字节唯一一次离开你机器的时刻。如果这些字节既不在任何 commit 里、也没有 tag，那么一周后——包括你自己在内——没人说得清 registry 上那包是从哪份源码来的。

这不是假想：我发过一版 1.2.7 到 npm，仓库的 GitHub release 还停在 1.2.6，市场条目指向旧 tarball，维护者直接打回。

都是 warn：本地试发、私有包、发完再补 tag 都合理。但「发完之后指不出是哪份代码」这件事，事后补不回来。

本地开发：宿主跑的到底是不是你刚改的代码

发布之前总有一段时间，插件只在你自己机器上跑。这段路比发布更容易踩空：宿主只加载 <profile>/node_modules 下的包，所以你改的是 E:\...\dsh-x，跑的是 profile 里那个入口——它可能是一个 junction、一份早就不再同步的拷贝，或者根本没有。这三种情况在宿主那边长得一模一样：插件不出现，没有报错，日志里也没有一行。

publish_gate_link 只读 profile 自己的三个文件回答这件事，不联网、不调包管理器、不写任何东西。

链接的三种形态是分开报的：Node 对 junction 和目录符号链接都只说 isSymbolicLink() === true，只有 realpathSync(p) !== p 才说明它是 junction；普通目录则是拷贝。mklink /J 建 junction 不需要管理员权限，符号链接需要。

工作流：

1. 改完 lib/，跑 publish_gate_link(dir)
2. link-not-installed        → 建 junction（finding 的 fix 里就是能直接粘的命令）
3. link-target-missing       → 删掉旧入口，重建 junction
   link-stale-copy           → 同上；拷贝不会跟着工作区变
4. patch-entry-top-level     → 把那一行挪进 "- insert:" 块
5. pnpm-store-conflict       → 别用 pnpm，用 mklink

profile 参数可以看别的 profile（默认 ~/.dsh/profiles/desktop）。测试永远用临时 profile，不碰真的那个。

没有做的：它不替你建链接、不改 profile 的 patch——和门禁其余部分一样只读，每条 finding 都带 fix 文案，动手是你的决定。

更新之前：这个新版本装上会不会坏

市场里的更新插件（dsh-market、dsh-update-checker、dsh-onekey-update、dsh-plugin-auto-update、dsh-plugin-steward …）做得都很好，但它们回答的是装完之后的问题：装上了、起不来、回滚。回滚能救回来，代价是这一次更新白做，而且坏的那一下已经发生了。

publish_gate_update 把顺序倒过来：下载 → 解包到临时目录 → 跑门禁的产物层和运行时层 → 再决定要不要装。

publish_gate_update({ name: "@liustack/modlens" })
→ current 0.1.0, latest 3.27.3
→ tarball: 239840 bytes
→ [warn] client-double-load: ./dsh/client.js 二次求值会重复注册工厂

它跑的是门禁已有的那几层，所以答案是逐条可追的：

• 入口能不能 import（entry-import-failed / entry-missing）
• apply() 能不能注册工具（tool-none-registered、tool-missing-execute）
• tarball 里有没有代码（files-omits-lib）、补丁在不在（files-omits-patch）
• 参数传错会不会抛（tool-input-throws，加 fuzz: true）
• 浏览器半边会不会加载、会不会重复注册（client-*）

只在 checkout 里才成立的规则（git / 市场条目 / 测试目录 / 本地链接 / 打包体积）被过滤掉——解包出来的目录没有 .git、没有 README 契约、没有 test/，跑那些只会把真正的结论埋掉。

三条自己的规则：

它不替你装、不替你更新——和门禁其余部分一样只读。想知道该不该更新，然后自己去 dsh plugin add，或者交给已有的更新插件去做。

一个真实的例子

对一个刚从别人那儿接手、准备发布的插件跑 publish_gate：

✗ package.json starts with a UTF-8 BOM  [utf8-bom]
    A byte-order mark makes JSON.parse throw `Unexpected token` and npm publish
    fail with a parse error that never names the BOM.
✗ files does not include "lib"  [files-omits-lib]
    The published tarball will contain no code.
✗ cordis.patch.yml has no insert row  [no-insert-row]
    A patch with only overrides never mounts your plugin. This file has 1
    top-level `- id:` row — those patch entries that already exist in the tree,
    they do not add one.
✗ lib/index.js calls require() inside an ESM module  [require-in-esm]
4 blocker(s) — fix before publishing

这四条里有两条是发布四个插件时真实踩到的。

设计取舍

• 三层，按代价排序：清单层最便宜、先跑；产物层要起一个 npm（约 1–2 秒）；运行时层要起一个 node 子进程。前一层没过的错误通常值得先修，但三层都会跑完——一次给全，比来回问好。
• 浏览器半边单独一层，不并进运行时层：宿主半边的失败会抛错、会有日志；浏览器半边的失败是「什么都没发生」。两者的排查路径完全不同，所以各起一个子进程、各有一组规则、各自能单独跳过（skipTools / skipClient）。
• 产物层用 npm pack --dry-run，不用自己推 files 规则：npm 的入包规则（main / exports 强制入包、README/LICENSE 强制入包、.npmignore 优先级）比自己实现的准。唯一的代价是它需要这台机器上有 npm，所以跑不起来时降级成 pack-unavailable 而不是报错。
• 运行时层真的执行插件代码：这是唯一能回答「装上能不能用」的办法。代价是 apply() 会跑，所以：假 ctx 是 Proxy 不落盘、20 秒硬超时、skipTools 一键跳过。
• --ignore-scripts：dry run 不跑 prepack，否则检查会触发一次构建。代价是清单可能和真实产物不同，所以有 pack-script-build 把这件事说出来。
• 发完那几十秒不算失败：npm 收下包会先回 202，然后六十秒到几分钟里这个版本在 registry 上根本不存在。这个插件自己的 0.8.1 实测是四分钟才出现。所以 publish_gate_verify 加了 waitMs 轮询；一轮等不到就返回 pending: true——那是「还没轮到」，不是「没发成功」。单次最多等 90 秒，因为宿主 120 秒就掐掉工具调用，剩下的只能再跑一次。
• publish_gate_verify 比 shasum，不比版本号：版本号相同而字节不同（发了又改、或本地根本没发）是最常见的自欺。npm pack --dry-run 的 shasum 和 registry 的 dist.shasum 是同一套算法，所以这个比较是精确的。
• 只读：修不修由你定，每条 finding 都带 fix 文案。门禁的职责是把话说清楚，不是替你做决定——所以没有 --fix。
• 确定性：全部规则是文件内容、子进程或 registry/GitHub API 检查，没有 LLM 调用——一条规则答错，你可以直接看规则。
• 自举：这个插件的测试把九个已发布插件当 fixture，断言它们在门禁下零 blocker；规则如果有任何误报倾向，测试先炸。

开发

node --test                      # 137 个单测
node test/integration.test.mjs   # 32 条集成断言（9 个真实插件作 fixture）

License

MIT