设计说明:git 源安装为什么必须带预构建产物(dist 入库)

关联 issue:#92 git 源安装失败:仓库未提供 dist 预构建产物,且 pnpm 默认拦截构建脚本(allowBuilds) 状态:v0.2.17 起随 dist 入库生效,本文记录决策依据,防止未来被"清理"回去。

问题

从 git 源安装(插件商店展示的形式,如 dsh plugin add github:Tyan66666/billion-context-dsh)在 pnpm 11 上必然失败,报 nothing installable: the plugin(s) need a build step (blocked by default, see allowBuilds) or ship no prebuilt artifacts。而商店条目里该插件的一键安装命令恰恰就是这个 git 形式。

根因(三个,叠加)

1. dist/ 未入库——.gitignore 排除了 dist/,而 package.json 的 main/types/exports/files 全指向 dist。git clone 下来没有任何可运行产物(只有 npm 发布版的 tarball 里才有)。
2. 没有任何 prepare 脚本——pnpm 对 git 依赖只运行 prepare 来构建;本仓库只有 build 脚本,所以即使放行构建也产不出 dist。
3. pnpm ≥10/11 默认拦截依赖构建脚本——pnpm 11 用 allowBuilds 替换了旧的 onlyBuiltDependencies 系列,依赖的构建脚本默认一律不放行。

为什么"让用户手动放行"救不了

• 对 git 托管包,allowBuilds 的 key 必须是"包名@git+URL#完整 commit hash"的 depPath 形式,按包名的 key(billion-context-dsh: true)不匹配,而且依赖的 commit 一变 key 就得跟着换(pnpm#12367、pnpm#12294)。这条路在 pnpm 11 上基本不可用。
• 就算放行,包里没有 prepare 脚本,dist 也构建不出来(根因 2)。

决策:提交 dist/ 入库,并且保持零构建脚本

提交 dist/(与 npm pack 产物完全一致的一组文件),git 源安装变成纯文件安装:pnpm 拉下来即含可运行的 dist/,没有任何构建脚本可拦,allowBuilds 机制无从触发。

候选方案的取舍:

方案	结果
提交 dist/(采用)	任意 git 形式(github:#<tag>、商店条目)开箱即用;不依赖用户配置
GitHub Release 附 tgz、安装指向 tarball URL	也能开箱即用,但改不了商店里已有的 github: 安装命令;手动 git 安装仍失败
加 prepare 脚本	适得其反:pnpm 11 会先拦 prepare 再报错,把本来(有 dist 时)能成功的安装搞挂;放行又要维护 commit-hash key

配套约束(防止契约被无声破坏):

• 永远不要给这个包加 prepare/preinstall/install/postinstall 脚本——见上表第三行;tests/package-artifacts.test.ts 守护这条契约。
• CI 定期校验 dist/ 与源码一致(.github/workflows/ci.yml 的 "Check committed dist matches the source" 步骤,git status --porcelain -- dist;每日定时 + dist-bot 自身提交后运行,PR 构建不再执行该检查)——防止入库产物过期,git 安装装到旧代码;日常新鲜度由 dist-bot 在每次合并后维护(见下一条)。
• dist/ 由 dist-bot 在合并后自动维护,PR 分支不携带构建产物,开发者完全零接触:.github/workflows/dist-bot.yml 监听 main 的 push,在可能改变构建产物的合并(src/**、package.json、package-lock.json、tsup.config.ts)落地后自动重建,产物有变化时把一份新鲜 dist/ 以 github-actions[bot] 身份直接提交到 main——这需要 main 的分支保护关闭 enforce_admins,bot 用 secret DIST_BOT_TOKEN(维护者的 fine-grained PAT,管理员凭证)推送;人类仍一律走 PR。CI 的漂移检查("Check committed dist matches the source")不再是 PR 闸门,改为每日定时 + bot 自身提交后校验 main 产物,兜底 bot 失效;合并到 bot 提交落地之间(约一两分钟)main 上的 dist 为上一版。发布 PR 合并后同理:gh release create 打 tag 前等 bot 提交落地,使 #<tag> 安装与对应 npm 版本完全一致。
• 建议用户安装时带 #<tag>;不带 ref 则装默认分支的最新构建(可能与最近一次发布有少量滞后)。