cli-forge-publish

cli-forge 发布

当符合要求的生成式 CLI 技能需要采用标准发布自动化、准备新版本，或执行配套的 GitHub Release + 多包 npm 发布流程时，使用此阶段。

目的

管理生成式 cli-forge 技能的发布流水线。

此阶段负责引导启动和生产发布流程：

• 主包及所有平台包必须执行的本地 prepublish 步骤
• 后续 semantic-release 事件中配套的 原生仓库 GitHub Release + 按平台拆分的 npm 发布

一次生产发布会生成：

• git 标签 v<version> + GitHub Release（每个目标平台均包含归档文件和 sha256）
• 6 个按平台划分的 npm 包（<pkg>-darwin-arm64 / -darwin-x64 / -linux-arm64 / -linux-x64 / -win32-arm64 / -win32-x64），包含原生二进制文件
• 1 个主 npm 包（JS 垫片，optionalDependencies 固定为相同版本）
• CHANGELOG.md 条目 + chore(release): <version> [skip ci] 提交

所有 npm 包会在一次 semantic-release 运行中发布，并与 git 标签 + GitHub Release 使用相同版本。包总数为 1 + config.targets.length（默认值：7）。

规范参考

• ./instructions/release/skill-release-runbook.md
• ./planning-brief.md
• ./shared-planning-brief.md
• ./contracts/release-receipt.yml.tpl
• ./templates/

入口检查

#	检查	来源
1	validation-report.yml 存在、内容为最新，且 result == compliant 或 warning	Validate
2	已明确目标仓库路径	Router / User
3	已明确所请求的发布模式	Router / User
4	已明确 npm 包命名约定、CLI 名称和 scope 决策	User

scope 决策是此阶段的必需输入。请收集主包名称，以及主包和平台包各自的 scope 策略。主包和平台包可以使用不同的 scope，但平台包名称仍必须由主包名称主体加上 -<target-suffix> 构成。

必需输入

• 验证结果及来源快照（若结果为 non_compliant、过时或来源不匹配，则拒绝发布）
• 发布模式：report_only、dry_run、prepublish 或 live_release
• 源项目路径
• cliName — CLI 二进制文件名称
• mainPackageName — 主 npm 包名称（如使用 scope，则包含 scope 前缀）
• mainNpmScope — 未使用 scope 时为 null，否则为主包的 scope 字符串
• platformNpmScope — 平台包未使用 scope 时为 null，否则为单独的 scope 字符串
• sourceRepository — GitHub 上的 owner/repo

工作流

1. 阅读 ./planning-brief.md，了解发布专用的规划约束。
2. 接收传入的 validation-report.yml。如果验证失败，则拒绝继续；不要在此处重新运行验证。
3. 在执行任何发布模式操作之前，验证验证结果是否仍然有效：
   • 将当前的 .cli-forge/design-contract.yml、 .cli-forge/cli-plan.yml、基线回执（scaffold-receipt.yml 或 takeover-receipt.yml）以及可选的 extend-receipt.yml，与 validation-report.yml 中记录的来源快照进行比较
   • 对于接管并采用的基线，要求报告来源与当前采用的契约及回执集完全匹配；不要仅依赖汇总验证结果
   • 如果任何必需的基线构件缺失、回执不同，或接管记录的契约／基线在验证后被重写，则停止并返回 Validate
4. 如果尚未收集，请向用户索取上文列出的输入。如果模式为 report_only，则跳至步骤 7。
5. 如果技能项目缺少发布自动化构件，则通过将 ./templates/ 的内容复制到项目根目录来采用这些构件，同时将安装安全的 dot-* 资源别名还原为实际的点号前缀目标路径（dot-releaserc.json -> .releaserc.json、 dot-github/ -> .github/、npm/platforms/dot-gitkeep -> .gitkeep）。采用的构件包不包含 Scaffold 阶段的源模板（*.tpl）。
6. 使用已收集的输入填写 release/config.json 和 npm/main/package.json。release/config.json 必须明确记录 mainPackageName、mainNpmScope 和 platformNpmScope。
7. 验证目标代码库具备以下条件：
   • 在 GitHub 托管的运行器上启用了 GitHub Actions，并设置了 id-token: write
   • 已在 npmjs.com 为主包及 6 个平台包中的每个包配置 npm 可信发布，且每个条目都指向 release.yml
8. 按照 ./instructions/release/skill-release-runbook.md 中定义的模式路径操作：
   • report_only：仅审查就绪情况。读取配置和代码库状态，报告阻碍事项及后续操作。不要复制文件、填写占位符，也不要以任何方式修改代码库。
   • dry_run：在本地运行 npm run release:rehearse。此操作会构建每个目标、同步平台包，并对每个包运行 npm publish --dry-run。不会创建标签或 GitHub Release，也不会实际发布到 npm。
   • prepublish：在本地运行 npm run release:prepublish。此操作会使用专用的 bootstrap 预发布版本，为每个平台包和主包进行真实的公开 npm 引导发布。如果缺少本地身份验证，则暂停并进行交互式 npm login，向用户显示验证 URL，并仅在用户完成浏览器验证后继续。
   • live_release：推送到 main（或使用 workflow_dispatch），由目标代码库中从安装安全构件包资源 dot-github/workflows/release.yml 还原的 .github/workflows/release.yml 驱动端到端流程。在已为配置的包集完成 prepublish bootstrap 之前，不要继续执行 live_release。
9. 根据 ./contracts/release-receipt.yml.tpl 中的模板生成 .cli-forge/release-receipt.yml。

输出

• 已验证的 prepublish bootstrap，包含 1 个主 npm 包 + N 个平台 npm 包（如果执行 prepublish）
• 已验证的 GitHub Release，包含归档文件和校验和（如果执行 live_release）
• 以相同生产版本发布的 1 个主 npm 包 + N 个平台 npm 包（如果执行 live_release）
• 已更新的 CHANGELOG.md 和提交到 main 的发布提交
• .cli-forge/release-receipt.yml

退出门槛

#	检查项
1	已执行所请求的模式
2	对于 report_only：未向目标仓库写入任何文件
3	对于 dry_run / prepublish / live_release：已采用并填充资源包
4	对于 prepublish：bootstrap npm 预发布已完成，且未创建标签或 GitHub Release
5	对于 live_release：版本、标签、主包和平台包一致
6	已生成 release-receipt.yml

防护规则

• 所有 npm 包（主包和平台包）都必须使用 semantic-release 选定的版本。两个发布脚本通过在 semantic-release 钩子中使用 ${nextRelease.version} 来确保这一点。
• bootstrap 预发布步骤必须使用专用的预发布版本，例如 0.0.0-prepublish.N。这不是正式发布。
• 主包和平台包之间只能在作用域上有所不同。不要引入任意的平台专属包基础名称。
• 不要绕过过期验证。如果代码库自上次验证报告以来发生了变更，请返回 Validate。
• 对于接管并采用的仓库，新鲜度检查必须根据当前契约和收据集验证来源，而不能只依据 validation-report.yml 的汇总状态或时间戳。
• 不要手动提升 npm/main/package.json#version、手动编辑 CHANGELOG.md 中的发布条目，也不要在 semantic-release 之外创建标签。
• 交互式 npm login 指引仅适用于本地 prepublish。生产 CI 发布必须继续依赖可信发布。
• 不要在目标仓库中留下 dot-* 别名名称。这些名称仅存在于此技能包中，以便 .agents 安装程序保留资源。
• 资源包的 npm/platforms/ 目录会在发布时生成。除了 .gitkeep 占位文件外，不要将生成的平台包目录提交到源代码管理。

下一步

这是最后阶段。