Impeccable 发布流程完整解析release.mjs 六道守卫与 npm prepack 换装技巧【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccableImpeccable 是一套让 AI 编码代理更懂设计的项目它的发布流程由 scripts/release.mjs 和 npm prepack 生命周期钩子共同守护。这篇文章带你完整看懂它如何用 330 行脚本管住三个独立版本化的组件又如何用两行prepack/postpack脚本让 npm 包换一套 README 出门。一、为什么这个发布流程值得学大多数仓库的发布靠人肉记步骤打 tag、写 release notes、传安装包、发 npm……少一步就出事故。Impeccable 的答案是把发布规则写进脚本让脚本拒绝一切不合规的发布。核心设计只有两条 三个组件skill / cli / extension独立版本号一个脚本统管 任何前置条件不满足脚本直接fail退出宁可发不出去也不能发错先看整体分工组件版本来源Tag 前缀发布去向Skill.claude-plugin/plugin.jsonskill-vGitHub Release dist/universal.zipCLIpackage.jsoncli-vnpm 注册表Extensionextension/manifest.jsonext-vChrome Web Store / AMO这套配置集中在 scripts/release.mjs 的COMPONENTS对象里每个组件声明自己的 manifest 路径、tag 前缀、构建命令和发布产物。二、一条命令触发发布release.mjs 怎么用发布者的全部操作只有两步——升版本号并写好 changelog然后# 先预演不产生任何副作用 node scripts/release.mjs skill --dry-run # 确认无误后正式发布 bun run release:skill对应的 npm script 定义在 package.json 中release:skill、release:cli、release:ext三个入口最终都指向同一个release.mjs。三、六道守卫脚本如何拒绝危险发布release.mjs的价值不在发布本身git taggh release create三行命令就够而在发布之前的层层拦截。按执行顺序共六道关卡1. 版本号必须一致Skill 的版本同时写在plugin.json和marketplace.json两处脚本会校验两者一致否则报 disagree. Bump both.防止两个 manifest 版本漂移。2. 工作区必须干净→ Checking working tree is clean ✓ clean有未提交改动直接退出并列出脏文件。这是最基础也最救命的一道。3. 构建产物必须与源码零漂移对 skill 和 extension脚本会重新跑一遍构建bun run build:release/bun run build:extension再检查 git 状态。如果重新生成的产物和已提交的文件有 diff说明提交的是旧产物发布被拒。这一步堵住了一个经典事故改了源码忘了重新构建线上拿到的 zip 是过期的。4. HEAD 必须已推送本地 commit 了但没git push拒。tag 会指向远端不存在的提交后续git checkout skill-v1.2.3的人必然踩坑。5. tag 不能被占用本地和git ls-remote远端都查一遍skill-v1.2.3只要在任何一端存在过就拒绝重复发布——版本号只许发一次。6. changelog 必须存在、且结构合法发布说明不是手写的而是从 changelog 页面里自动提取对应版本的条目按v1.2.3/CLI v1.2.3/Extension v1.2.3三种前缀定位转成 Markdown 作为 Release Notes。脚本对条目的解析相当较真见 scripts/release.mjs 中的注释搜索范围限定在本版本的/article之前否则会把下一版的说明当成这一版的发出去——代码注释里记录了这曾真实发生过所有 v4.0.x 的 skill 发布都带着 v4.0.0 的说明出门没有任何东西报错取该条目内所有ul classcf-items列表而非第一个避免长版本被分组后漏发列表没开始和没闭合给出不同的报错信息因为两者的修复方式不同最后还有一道产物校验dist/universal.zip等文件必须真实存在缺一即拒。四、发布之后自动生成的推文与版本漂移检查通过全部守卫后脚本执行打 tag → 推 tag →gh release create附带产物文件然后做两件贴心事自动生成推文草稿从 changelog 每条strong加粗导语中提取亮点贪心填入 280 字符限额附上发布链接直接打印出来供复制。实现见 scripts/release.mjsskill 专属的在线版本校验npx impeccable update的更新源是官网而非 GitHub Release脚本会请求官网的 version API如果线上版本落后于刚发布的版本就大声警告记得重新部署官网——又一次是对真实事故4.0.0 发布后更新用户被卡在旧版的补救CLI 组件则输出下一步提示npm publishextension 输出上传到应用商店的指引。五、npm prepack 技巧两行命令完成 README 换装这是本篇最值得偷师的一个技巧。问题背景仓库里的README.md是面向 GitHub 用户的完整版项目全景、设计理念但impeccable包发布到 npm 后用户看到的是npm 包页面他们更需要 CLI 用法、安装命令、退出码说明——所以另写了一份 README.npm.mdnpm 有个隐藏机制npm pack/npm publish前会自动执行prepack钩子。Impeccable 用它做了一次文件换装全部代码就两行定义在 package.jsonprepack: cp README.md README.repo.md cp README.npm.md README.md, postpack: cp README.repo.md README.md rm README.repo.md执行时序拆解prepack先把原 README 备份为README.repo.md再把 npm 版顶到README.md的位置npm 打包此时 tarball 里装进去的就是README.npm.md的内容postpack打包结束把原版 README 换回来删掉备份——工作区恢复原样效果仓库里永远只有一份 READMEnpm 包却带着另一份 README 出门且整个换装过程对 git 零污染postpack保证了换回来。 这个技巧适用于任何仓库文档 ≠ 包文档的场景monorepo 中的子包、私有 API 与公开 README 分离、不同渠道的发布说明……只要是发布物需要换个面孔prepack/postpack 就是最轻量的方案。六、发布脚本怎么测试用 --dry-run 搭沙盒一个只保护改状态动作的脚本测试它本身就有悖直觉——你总不能真的打 tag 发布一遍来做测试。tests/release.test.mjs 的解法很干净在临时目录git init一个一次性仓库配一个本地 bare 仓库当origin把release.mjs原样拷进去以维护者的方式 spawn 执行全程使用--dry-run所有变更类步骤打 tag、push、gh release create、构建被跳过并打印[dry-run]前缀但所有守卫逻辑照常完整运行于是 12 个测试精确覆盖了每一种拒绝路径脏工作区、未推送的 HEAD、本地 tag 已存在、远端 tag 已存在、两个 manifest 版本不一致、changelog 缺条目、产物缺失外加正向路径Markdown 转换正确性、推文不超 280 字符。--dry-run模式让预演发布成为了一等公民——这也是 AGENTS.md 里明确推荐给每位维护者的习惯正式发布前先 dry-run 一遍。七、核心要点速览机制解决的问题关键文件单脚本多组件三组件独立版本化tag 前缀防混淆release.mjs六道前置守卫拒绝脏树、未推送、旧产物、重复 tag、缺 changelog、缺产物release.mjschangelog 自动提取发布说明零手写且有结构校验防串版release.mjs--dry-run全量守卫可预演且可测试release.test.mjsprepack/postpack 换装npm 包携带专属 README仓库文件零改动package.json发布流程的本质不是自动化而是把每一次事故的教训变成一条fail。读懂release.mjs里的注释你看到的不只是代码而是一本用真实事故写成的发布安全手册。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考