release

brooks-lint — 发布

目标版本来自用户请求（例如 1.4.0）。如果为空，先询问维护者需要进行哪种 semver 版本升级，再进行任何操作。

接受该版本前，请先阅读待办记录。 运行 npm run changelog:audit，检查实际尚未发布的内容——版本升级取决于整个范围，而不是触发发布的那项更改。如果该范围包含一项功能或一个新平台，而维护者要求发布补丁版本，请停止并说明原因：v1.5.1 曾经发布，随后被删除并重新发布为 v1.6.0，因为有二十个未发布的提交（包括一个新平台）被一并纳入了补丁版本。

按顺序执行以下步骤。bump-version.mjs 从 package.json 读取版本，且不会修改变更日志——因此，版本修改和 CHANGELOG 条目必须手动完成；该脚本只会将版本同步到各个清单文件以及所有包含版本号的文本文件。

1. 设置唯一真实来源。 npm version <version> --no-git-tag-version （必须带上 --no-git-tag-version 标记——直接运行 npm version 会创建自己的提交和标签，与第 5 步的手动提交冲突）。

2. 同步版本。 npm run bump — 将版本写入 .claude-plugin/plugin.json、.claude-plugin/marketplace.json、 .codex-plugin/plugin.json、gemini-extension.json，以及 scripts/version-refs.mjs 发现的所有包含版本号的文本文件（六个 README 徽章和 action uses: 固定版本、文档首页的 JSON-LD softwareVersion，以及 docs/github-action-example.yml）。此处不要维护清单——以脚本中的清单为准。

3. 编写变更日志。 在 CHANGELOG.md 顶部添加一个新章节，按类别（Added / Fixed / Changed）概述自上一个发布标签以来的提交。标题必须是 ## [<version>] - YYYY-MM-DD — npm run validate 会解析这一精确格式，若只写 ## <version> 则会失败。 3a. 审查整个范围——检查每个提交，不得抽查。 运行：

   npm run changelog:audit
   

   该脚本会从上一个发布标签推导提交范围，应用仅有的三项豁免（发布版本升级、其分支提交已单独列出的合并提交，以及 star-history 刷新——仅修改图表自身两个文件的机器人提交），并将其余内容打印为检查清单。 逐项检查：每一行都必须对应你刚写的一个条目，或说明为何无需列入。 没有其他豁免——没有用户可见变化的内部加固也应列入条目；外部贡献者提交的、面向维护者的修复也应列入，并附上 @handle 致谢。提交中的 Changelog: trailer 会作为标记显示；该提交对应的条目就是你现在要编写的内容。

   如果脚本能够确认存在遗漏（范围内的拉取请求，其 #N 未在该章节中引用），它会以非零状态退出。同一检查也会在发布进行期间由 npm run validate 执行，因此不能跳过；validate 停止检查时也会打印一行说明。其余检查清单依赖判断，脚本不会强制执行。审计通过并不能证明变更日志完整：章节中任意位置出现一个裸 #N 就能通过门槛；通过 rebase 合并的 PR 没有可供匹配的内容；而纳入发布版本升级本身的任何内容都不会接受审计。请参阅 AGENTS.md 中的 Release Process。

4. 验证。 运行 npm run validate——如果任何清单、任何包含版本号的文本文件或 CHANGELOG 条目不同步，该命令就会失败。修复后重新运行，直到检查通过。 然后运行 npm test。

5. 提交并推送。 暂存 npm run bump 重写的所有内容以及 CHANGELOG.md——查看 git status，不要手动指定文件，因为包含版本号的文件集合是在磁盘上发现的，不止一个 README；使用符合规范的提交消息（chore(release): bump version to <version>）；推送到 main（该仓库直接推送到 main，不创建 PR）。 5a. 同步发布相关内容并确认审批。 对照发布状态检查全部六份 README 翻译、CHANGELOG、插件清单、网站和安装指南。运行 npm run github:metadata -- --apply，然后运行 --check，以同步 About、主页、主题和受管理的标签。保留无关标签。遵守明确的发布暂停要求；准备工作已完成且 CI 全绿并不代表已获批准。已撤回的 npm 版本不可重复使用，即使 GitHub 标签已删除也不行。 5b. 等待远程 CI 验证准确的发布提交。 推送后，解析 git rev-parse HEAD，找到 headSha 与该提交匹配的 Validate 工作流运行，并使用 gh run watch <run-id> --exit-status 等待其完成。检查每个矩阵任务。运行缺失、排队中、已取消或失败，都不算通过。本地检查不能替代此门禁。在此准确提交对应的运行成功完成之前，不要创建 GitHub release，也不要发布到 npm。 如果 CI 失败，诊断问题并提交修复，然后等待新提交的 CI 运行。

6. 打标签并发布。 只有远程门禁通过后，才创建 GitHub release： gh release create v<version> --title "v<version>" --notes "<changelog section>"。

完成后，报告发布的版本和 GitHub release URL。