release-bumper

Release Bumper

如果斜杠或美元符号调用已将这些说明添加到对话中，请直接遵循。在这种情况下，不要再通过技能工具调用此技能。

发布一个或多个软件包，包括版本升级、更新日志条目、提交和标签。

非演练调用即授权执行此工作流规定的仓库本地版本编辑、更新日志、提交和带注释的标签。在 Agent 推导出发布计划后，不要再添加通用确认环节。只有当尚未解决的软件包选择或依赖范围策略会改变发布集合或方案时，才需要询问。GitHub 发布创建仍属于独立的外部写入操作，遵循下文规定。

参数

• packages：可选的软件包名称或目录。在单软件包仓库中省略。
• version：可选的显式 semver。仅对用户选定的一个软件包有效。
• --beta：创建或递增 -beta.X 预发布版本。
• --dry-run：预览，不修改文件、不提交，也不打标签。

辅助工具接口

从此 SKILL.md 解析 <skill-dir>。将辅助工具的标准输出保留为 JSON，诊断信息输出到标准错误。

bun run "<skill-dir>/scripts/plan-release.ts" \
  [--cwd <repo>] [--beta] [--dry-run] [--version <semver>] \
  [--package <name-or-dir>]...

只读发现输出的 schemaVersion 为 2。它会报告软件包标识、每个软件包的完整 changedFiles、工作区依赖关系和声明的范围、上一个标签的信息、选定的目标以及工作区状态。changeHints 是基于文件名的导航提示，明确不具权威性。切勿使用它们判断发布相关性或更新日志是否应纳入。

Agent 决定所有稳定版补丁／次要／主要版本后，将发现 JSON 写入临时文件并运行：

uv run "<skill-dir>/scripts/finalize-release-plan.py" \
  --discovery <discovery.json> \
  [--version <package>=<semver>]...

最终处理器会执行 beta 版和显式版本转换、稳定版预发布版本晋升、npm 范围满足性检查、简单依赖范围建议和依赖排序。它会将复杂范围、peer 范围、依赖循环以及未由 Agent 提供稳定版本的软件包报告为尚未解决的决策。如果某个未满足的依赖关系新增了依赖方，请为该软件包选择发布版本，并使用另一个 --version 赋值重新运行。最终处理器绝不会自行选择常规发布幅度或依赖策略。

对于写入的每份稳定版更新日志，都要验证其确定性结构：

uv run "<skill-dir>/scripts/validate-changelog.py" \
  --file <CHANGELOG.md> --version <semver> --date <YYYY-MM-DD> [--tag <tag>]

此检查会验证预期的发布版本和日期、标题／类别顺序、允许的类别、列表结构以及发布链接标签。它不会评判重要性、措辞或语义类别。

工作流

1. 直接将用户参数映射到发现流程并运行。退出码 2 表示目标不是可发布的 Git／软件包仓库。退出码 64 表示输入无效。遇到任一情况即停止。

2. 要求 workingTree.clean。不要将无关工作纳入此次发布。

3. 确定未知或有歧义的软件包选择。用户明确指定版本时，只能发布单个软件包。如果目标的 previousTags 版本低于其清单文件中的版本，则该版本已在未打标签的情况下发布，且报告的基准已过时：在其发布提交上创建缺失的附注标签（例如 docs: release <version>），遵循已观察到的标签惯例，将其纳入推送命令，然后重新运行发现流程。仅在无法确定发布提交时才询问。

4. 检查每个目标的完整 changedFiles，以及与其上一个标签之间的净差异。判断保留下来的更改是否值得发布。根据具体情况，运行时环境、重构、文档、测试和工具都可能相关。不得仅凭文件名作判断。

5. 对于每个未明确指定版本的相关稳定版目标，根据面向使用者的更改选择补丁、次要或主要版本。对于 Beta 版发布，让终结器计算机械式版本变更。

6. 运行终结器。检查未满足的工作区依赖边。仅当策略适用时，才接受它对简单依赖范围的建议。明确选择对等依赖和复杂范围的策略。添加依赖方及其由 Agent 选择的发布版本，然后重新运行，直到软件包集合和依赖顺序均已确定。

7. 对于试运行，报告按顺序排列的软件包／版本计划、范围编辑、变更日志／标签／提交操作，以及由 Agent 决定跳过的项目。停止，不执行写入。

8. 对于稳定版发布，阅读 references/common-changelog.md，并根据限定范围内的净差异撰写面向使用者的条目。条目的选择、措辞、重要性和类别由 Agent 决定。Beta 版发布不更新变更日志。

9. 更新清单文件和已接受的依赖范围。使用单次 Shell 调用循环检查所有变更日志，并报告每项结果，以验证每份稳定版变更日志。

10. 使用仓库中范围最窄的既定命令格式化一次。

11. 按依赖方在前的顺序提交并打标签。每个软件包使用一个提交和一个附注标签：

    • 单个软件包的提交：docs: release <version>。
    • Monorepo 提交：docs: release <package> <version>。
    • 单个软件包的标签：遵循已观察到的 v<version> 或纯语义版本惯例。
    • Monorepo 标签：遵循已观察到的软件包标签惯例；默认使用 <package-dir>@<version>。

12. 不要推送。成功后，建议使用精确的 git push origin <tag>... 命令，其中只包含本次执行创建的标签。不要使用 --tags。

13. 最终报告前，检查一次 .github/workflows/，同时核对本步骤和第 14 步的标准。本步骤中，查找会根据推送的标签创建或发布 GitHub Release 的有效工作流。release.yml 之类的文件名只能作为线索，不能作为证据。同一轮检查中，使用 $cli-gh 只读运行 gh release list，并确认仓库是否一直有维护中的 GitHub Release 发布记录。如果有，则根据以下规则，询问用户是否为每个新标签创建 GitHub Release，等待用户批准后再操作：

    • 推送的标签为 1 至 3 个，且存在适用的发布 CI：不要提议手动创建 Release。此时，推送标签应触发 CI。
    • 不存在适用的发布 CI：提议通过 $cli-gh 使用 gh release create 为每个新标签创建一个 Release。
    • 将同时推送超过 3 个标签：即使存在发布 CI，也提议通过 $cli-gh 使用 gh release create 为每个标签创建一个 Release，因为超过此阈值后，GitHub 不会创建标签推送事件。参见 GitHub 的推送事件限制。 未经用户批准，绝不创建 GitHub release。如果无法核实发布历史，请报告为未知，并且不要提供写入操作。

14. 在最终报告前，还要使用步骤 13 中唯一一次对 .github/workflows/ 的检查，查找是否存在会在推送标签时运行、设置 id-token: write，并运行 npm stage publish（暂存发布）或 npm publish（直接发布）的活动工作流。文件名只是线索，并非证据。如果存在此类工作流：

    • 报告推送推荐标签会触发 npm 发布。
    • 对于暂存发布，报告每个版本在维护者使用 2FA 批准之前都不会发布。维护者可以运行 npm stage approve <stage-id>，或使用 npmjs.com 上的 Staged Packages 选项卡。
    • 推荐的推送命令每次最多包含三个标签，因为超过此数量时，GitHub 不会创建标签推送事件。请参阅步骤 13 中有关推送事件限制的链接。
    • 绝不运行 npm publish、npm stage approve 或 npm stage reject。

安全与完成

辅助工具失败表示输入格式错误、违反不变量或验证失败。尚未解决的 Agent 决策是 JSON 中的数据，并非辅助工具失败。发现和试运行均为只读。在确定最终稳定版软件包集合之前，不要写入变更日志；如果发现步骤报告了观测到的事实，不要据此推断标签约定。

完成试运行需要基于发现结果、经 Agent 审核的操作预览，且写入次数为零。完成发布需要已验证的清单和稳定版变更日志、格式化、按依赖顺序为每个软件包创建一个提交和一个附注标签，并报告创建的提交/标签、由 Agent 决定跳过的项目、精确的标签推送命令（可多条）、任何适用的 GitHub release 提案，以及任何 CI npm 发布通知。

请按实际情况使用 ### ⛔ Release stopped — working tree is not clean、### ⚠️ Release decision required、### 🔎 Release preview — no files, commits, or tags written 或 ### 🏁 Release complete。辅助工具 JSON、版本、哈希、标签、命令和变更日志文本必须保持原样，不得添加修饰。