跳转至

发布 REA

推送到 main 会自动打开或刷新一个 Release Please PR，其中包含下一个版本和变更日志。请查看其迁移说明，并等待其当前的 CI 检查通过。将该 PR 合并到 main 后会自动开始发布。

Release 工作流会在创建标签之前验证合并后的发布元数据和祖先关系。npm 和 MCP Registry 发布使用 Release Please 返回的、经审查的精确合并 SHA。在任一 registry 发布之前，release 运行会在该精确修订版上执行完整 CI 资格验证，包括覆盖率、可移植提供器以及每个原生软件包宿主。之后推送到 main 的提交无法更改或取消该证明。

资格验证通过后，一个具有只读 repository/actions 权限的单独 runner 会恢复保留的 tarball 和验证器运行时。它将那个精确归档安装到空前缀中，然后测试 CLI 帮助/发现以及真实 stdio MCP catalog/session 契约。安装会在协议截止时间开始之前完成，并禁用依赖生命周期脚本。只有演练成功，才会启用具备 npm 发布权限的作业。发布者仅下载原始合格归档和清单，使用 Node 内置模块验证它们的 source/run/attempt、版本、Node 标识和流式摘要，然后对官方 registry 调用 npm publish --ignore-scripts。一个共享的内置 registry 读取器会在每次发布尝试时重新检查现有字节和标签，包括部分发布后的重试。它不会安装应用依赖、恢复验证器代码或执行软件包 canary。固定的 Node/npm、Actions 和 runner 仍然是受信任的工具链输入。两个作业都不会重建或重新打包该归档。

这次演练在 Linux release runner 上检查软件包消费情况；资格验证则保留其更广泛的原生宿主和真实提供器检查。

发布之前，npm 查找失败和格式错误的元数据会使作业停止。现有版本必须与合格 tarball 的 SHA-512 以及预期的 latest/next dist-tag 匹配，才能被重用。发布绝不会覆盖现有版本，也不会静默更改 dist-tag。发布后，仅在传播窗口内确认 registry 中不存在时才重试。内容或标签不匹配会立即失败。另一个单独的发布后作业使用只读 repository/actions 权限验证 registry 字节和标签，然后从 npm 安装并重复相同的 CLI/MCP 检查；它还会从较旧的稳定版本执行一次真实更新。对于 next 上的预发布版本，该更新器仍以稳定版 latest 为目标，与公开的 update 命令行为一致。MCP 发布依赖于该验证作业的成功。演练、发布以及两个 registry 验证/发布作业都不会继承远程缓存凭据。

资格验证会在 manifest schema v2 中记录解析后的 latest/next 通道。演练验证其精确的 SemVer 映射；最小化发布者直接使用合格的通道，无需第二个版本解析器。只有只读恢复接受现有的 schema-v1 工件，并保留其原始字节和 source/run 标识。新的发布需要 schema v2。

必需的 reverse-tools lane 会运行全新的覆盖率和两项变异预检。完整的变异扫描会按计划或手动触发单独运行，且不会阻塞发布；请参阅测试指南。普通的 main 推送以及已关闭且未合并的 PR 无法发布软件包。请同时检查两个发布作业和已发布软件包 canary；仅凭合并的 PR 或 GitHub 标签并不能证明发布已完成。在部分发布后，请在原始运行中重试失败的作业。

恢复已发布的 npm 发布版本

重新运行作业会使用其原始工作流和源修订版。当验证器或发布工作流需要代码修复时，请先将该修复合入 main，然后使用单独的恢复工作流，而不是重复创建发布：

gh workflow run release-recovery.yml --ref main \
  -f version=6.5.0 -f release_run_id=38564502044

选择现有版本及其原始的自动 Release 运行。恢复要求该运行成功通过精确源码 CI 门禁，并且具备成功的 npm 写入或 registry 字节验证。它会识别较早的发布者作业或单独的发布后作业中的验证。它使用现有的发布标签、原始合格 tarball 和验证器运行时；过期或缺失的工件会中止恢复。归档的 source、版本、原始 run/attempt 和 Node 版本必须匹配，并且其 SHA-512 必须等于 npm 发布的完整性值。修正后的控制器会针对该已发布运行时，运行公开 CLI、MCP catalog/session 以及先前版本更新 canary。安装会在 MCP 握手开始之前完成；依赖生命周期脚本会被禁用，与已安装软件包验证器中的做法一致。

只有在验证成功之后，恢复才会将已发布的 server.json 发布到 MCP Registry。它不会创建标签或 GitHub Releases，不会发布 npm 字节，也不会更改 dist-tags。两条发布路径共享同一个 MCP 发布者：分页 registry 查找会保留相同的活动版本，拒绝冲突/非活动元数据，并在查找出错时失败。原始失败运行仍作为历史失败保留；恢复运行记录新的验证以及剩余的 registry 发布。手动冻结分支发布不在该恢复路径范围内。

对于需要独立冻结应用程序检查点的发布，请使用下面的可选手动路径。该路径保留明确的 prepare 和 publish 阶段。

自动 main 提案和手动检查点准备使用 scripts/release-proposal.mjs，并搭配固定的 release-please 依赖。控制器仅在调用时应用 patches/release-please+17.3.0.patch；正常的依赖安装和已发布软件包安装不会应用该补丁。对于使用默认 changelog、默认或 always-bump-minor 版本控制、无路径排除且无显式插件的单个根 Node 包，该补丁避免了提交文件回填、关联的 PR 文件列表和路径拆分。其他配置保留上游文件归属工作流。提交历史和关联的 PR 元数据仍来自 GitHub：发布说明需要这些提交，BEGIN_COMMIT_OVERRIDE 需要已合并 PR 的正文。被跳过的文件列表仍保持未知，而不会被报告为空。控制器根据完整选定的 Git 历史来确定提交搜索范围；若缺少已知的发布边界，则会在创建提案之前失败。

History-page 的读取操作会在现有的五次重试预算和指数退避范围内重试 GitHub 的标准内部 GraphQL 响应错误。每次重试使用相同的游标；权限错误、验证错误和混合错误会立即失败。重试耗尽后，准备工作会在提案写入之前停止。控制器不会重新启动提案创建，也不会重试变更操作。内部 GraphQL 错误并不代表 API 配额已耗尽，也不能证明查询大小导致了失败。发布操作继续通过固定的 release-please action 进行。

升级 release-please 时，请审查上游 manifest 实现，刷新版本化补丁，并运行发布提案和工作流边界测试。版本不匹配，或补丁既无法干净地应用、又与已应用的补丁不匹配时，将失败关闭。

贡献者感知的发布说明

使用 rea-changelog-update 技能 将机器人草稿转换为分组的 Highlights、Changes 和 Fixes，并附上内联的 Thanks @... 致谢。npm run release:notes -- inventory 收集完整的选定 Git 范围和分页的 GitHub PR/作者/关闭 issue 的元数据；record --summary 为公开说明生成紧凑的溯源链接，而 record 生成完整记录以供审查。即使某贡献同时出现在 highlights、details 和 migrations 中，也只致谢一次；省略维护者 @morluto 的自致谢。将完整的作者元数据保存在 inventory 中，而不是在发布正文中复制一份致谢台账。check 验证致谢信息和可选的 PR 正文一致性，render 写入经过验证的发布章节。在不带必需选项的情况下运行子命令可查看其用法。GitHub 读取需要经过身份验证的 gh；record/check/render 可离线工作，使用已保存的 inventory 和完整的本地 Git 历史。

将最终确定的 inventory 保存在发布分支的 docs/releases/VERSION.contributions.json 中。明确审查未知身份以及被还原/向后移植的工作；GitHub 元数据并不能证明面向用户的主张的质量。保留现有的 breaking-change 章节和检查点检查。贡献 inventory 是经过审查的快照，而非签名证明；离线检查器验证的是本地范围覆盖和致谢一致性，而不是独立验证 GitHub 的作者身份。

在编辑活动中的 PR 之前，添加 rea:release-notes-finalized 标签，以防止常规的 main 推送提案覆盖编辑定稿的说明。等待任何正在运行的提案完成。该保护机制仅适用于 main 推送自动化；不要在已定稿的说明上运行手动检查点准备。移除标签以恢复机器人重新生成。该标签不会冻结基础分支：新的基础提交需要重新进行 inventory 检查和重新审查说明。

同时更新发布分支的 CHANGELOG.md 和 PR 正文，并保留 Release Please 周围的元数据。在创建发布之前，工作流会在存在 inventory 时对其进行检查，要求其目标等于已审查合并提交的第一个父提交，并将新获取的 PR 正文与 changelog 进行比较。在任何标签或发布之前，它会拒绝发布元数据路径之外的更改以及过期的致谢记录。同时审查允许的元数据路径内的差异，尤其是包依赖和脚本。没有 inventory 的现有候选者保留其当前的检查。合并仍然会启动发布；编辑说明本身并不会授权合并或发布。

检查器支持内联的 Release Please PR 正文，最长可达 GitHub 的 65,536 字符限制，包括周围的页眉/页脚。使用溢出链接的 PR 正文需要单独的集成，并且会明确失败；致谢信息绝不会被静默截断。

1. 为手动检查点选择来源

使用 Release Please 提议的下一个次要版本，包括包含 breaking changes 的发布。记录完整的源 SHA，并在该提交处创建 release/VERSION。所选版本必须与 Release Please 提议的版本一致，才能进行发布。

选择手动路径时，保持自动的 main 发布 PR 不合并。从 main 中选择应用提交，创建冻结分支，并使用以下步骤准备其自己的发布 PR。合并 main 发布 PR 将改为启动自动发布。在手动发布完成且其元数据已同步回 main 之后，关闭已被取代的 main PR。

release/VERSION 还为工作流设置了期望版本。使用精确的 SemVer，例如 release/6.1.0 或 release/6.1.0-rc.1，不要包含构建元数据。检查点验证器会在创建标签之前，拒绝其包、lockfile、manifest、注册表元数据或 changelog 与该版本不一致的候选者。

兼容性与版本选择

在发布候选者之前，审查其 changelog 中的 breaking changes 以及正在准备的发布的迁移说明。6.1 到 6.2 迁移指南 记录了该发布的变化；它是历史参考，而不是后续发布的兼容性检查清单。

REA 使用 Release Please 的 always-bump-minor 策略：每个发布都会递增 minor 版本并重置 patch 版本，包括包含 breaking changes 的发布。例如，6.0.0 之后的下一个发布是 6.1.0。版本号使用 SemVer 格式，但 minor 版本递增并不承诺向后兼容性。升级前请审查 changelog 的 breaking-change 章节和迁移说明。

受支持的公开接口面包括有文档记录的 CLI 命令/选项、MCP 工具名称及输入/结果契约、已保存的证据格式和受支持的运行时要求。在添加 ! 或 BREAKING CHANGE 脚注之前，PR 必须指出一个先前有效的调用或配置将会失败或改变含义，解释为什么无法保持兼容性，并提供其迁移方案。优先选择可选新增、兼容性适配器和有文档记录的弃用期。保留 breaking 标记，以便机器人在不递增 major 版本的情况下包含迁移说明。维护者在合并前审查这一影响；机器人只解析标记，无法推断兼容性。

例如，添加一个可选的检查工具属于次要变更。拒绝此前公共契约接受的相对 MCP 路径属于破坏性变更；拒绝现有契约已禁止的输入则属于修复。仅更改版本号并不能恢复兼容性。

例如，在为 5.0.0 选择一个已审查的提交之后：

git fetch origin main
git branch release/5.0.0 SOURCE_SHA
git push origin release/5.0.0

将 SOURCE_SHA 替换为所选定的完整提交 SHA。检查点必须包含此发布工作流以及对发布分支的 CI 支持。对于较旧的检查点，请先仅向后移植发布基础设施并记录该额外提交。不要将后续实现变更合并到发布分支中，也不要将候选版本变基到持续移动的 main 上。

2. 准备 bot PR

从 main 运行工作流定义，并单独选择冻结的源码：

gh workflow run release.yml --ref main \
  -f release_branch=release/5.0.0 -f phase=prepare

Release Please 会以该分支为目标，准备其版本、变更日志和注册表元数据。该工作流使用可选的 RELEASE_PLEASE_TOKEN 仓库密钥，否则使用内置的 GITHUB_TOKEN。专用的 GitHub App 或个人访问令牌可以自动启动 PR CI。使用内置令牌时，opened、synchronize 和 reopened PR 事件所创建的运行需要具有写入权限的维护者来批准。请参阅 GitHub 的工作流触发文档。

生成步骤会对产品目录进行标准化。准备阶段无法创建 GitHub release 或发布软件包。请在标准化后记录最终的 bot PR head，然后从 PR 页面批准该 head 被阻止的运行。对 bot 分支的更新可能会创建新的需批准运行；批准较旧的 head 并不能验证已标准化的候选版本。请等待最终 head 的 CI。

验证器会读取从已发布基线标签到所选检查点的实际祖先范围，包括可见的 first-parent Conventional Commits 以及 GitHub 默认合并消息中的 PR 标题。报告会同时保留原始合并主题和提取出的 Conventional Commit 标题。这在将侧分支发布合并回更新的 main 之后尤为重要：Release Please 按时间顺序的历史截断可能会遗漏未发布的主线提交。在 always-bump-minor 下，未发布的破坏性变更标记允许进行次要版本递增，但仍需在新版本的破坏性变更迁移章节中提供引用。使用默认策略的检查点仍保留主要版本递增要求。其他被遗漏的条目会报告以供审查。旧版本发布中的历史说明无法满足新版本的迁移检查。此审计仅核查所声明的标记和引用；它并不证明 API 兼容性或迁移说明的质量。

如果准备阶段报告了不匹配或遗漏的破坏性变更，请检查记录的祖先报告，修正 release PR 的版本工件和说明，重新生成文档，并审查/测试其最终 head。不要在手动修正后反复执行准备操作。在 Release Please 可以创建标签之前，发布阶段会再次独立检查合并后的候选版本。

审查候选版本的版本号、说明、生成的元数据和软件包内容。等待候选版本的 CI 以及相关的真实提供商检查。常规的本地迭代需要有针对性的检查；CI 负责完整的确定性覆盖和平台通道。如果某个工件或真实提供商检查不可用，请在决定发布前报告该限制。

将已审查的 PR 以匹配的 head SHA 合并到 release/5.0.0 中。后续的 main 提交不会改变此候选版本。必要的发布修复应放在发布分支上，且必须经过审查和测试，并建立新的记录检查点。

3. 发布已审查的合并

release PR 合并之后：

gh workflow run release.yml --ref release/5.0.0 \
  -f release_branch=release/5.0.0 -f phase=publish

发布阶段会根据已合并的 bot PR 创建 release，而不会准备或更新另一个 PR。npm 和 MCP Registry 任务都会检出 Release Please 的确切 release SHA。它们不会构建当前 main 的最新提交或可变分支。稳定版本发布到 npm 的 latest 标签；预发布版本发布到 next 标签，因此默认情况下它们无法替换稳定安装。发布调度从冻结的发布分支运行，因此 npm 的 provenance（来源证明）会记录实际的发布提交。在 Release Please 创建标签之前，该工作流只接受 prepare 或 publish，并要求所选分支的最新提交等于调度 SHA。Registry 任务仅在 publish 期间运行。标签存在后，如果该标签的 SHA 与调度 SHA 不匹配，两个 registry 的发布都会停止。关于 GitHub 工作流引用和提交 SHA 的使用，请参阅 npm 的 provenance 实现。

完整的资格验证会构建捆绑的 Windows 控件，并验证打包工件在其原生主机上的运行情况。Linux x64 验证器在其工作区清理完成后，会保留它安装并测试过的确切 tarball。npm 任务会从同一工作流运行中下载该归档，并检查其源代码 SHA、运行身份/尝试次数、软件包和 Node 版本、主机身份以及 SHA-256。它会在不重新构建或重新打包的情况下发布该归档。重新运行失败的发布者任务可以复用同一运行中先前成功的尝试。该工作流随后会验证已发布的 CLI、按能力范围划分的 MCP 目录以及隔离的软件包更新路径，然后再发布 MCP Registry 元数据。

请分别记录以下结果：

  • GitHub release 和标签，包括解析后的提交 SHA。
  • npm 的确切版本和完整性，且已通过已发布软件包的 canary 检查。
  • MCP Registry 的确切服务器版本以及与之匹配的 npm 软件包版本。

仅凭 GitHub 标签并不能确立 npm 或 MCP Registry 的发布。

4. 将元数据同步回 main

手动检查点同步是完成该版本发布的一部分。在切出下一个检查点之前完成它；否则 main 会保留之前的发布基线，并可能再次提议已发布的版本。

发布后，从发布分支向 main 打开一个 PR。保留 main 后续的实现更改，并根据合并后的契约以已发布的包版本重新生成被忽略的构建输出。合并前，检查 GitHub 是否允许合并提交：

gh api repos/morluto/rea --jq .allow_merge_commit

如果禁用，维护者必须安排一条经批准的、保留祖先关系的合并路径，才能完成同步。Squash 和 rebase 合并不会把已发布的标签放入 main 的祖先链中。不要用它们替代此步骤。审查并测试这个同步 PR，然后使用一个合并提交，使发布标签保留在 main 的祖先链中。保持已发布的标签不变。

同步必须包含 .release-please-manifest.json、package.json、package-lock.json 中的两个根版本、CHANGELOG.md、server.json 以及带版本号的文档示例。针对合并后的树运行 npm run docs:generate、npm run docs:check 和发布配置测试。合并后，验证已发布标签是 main 的祖先：

git fetch origin main --tags
git merge-base --is-ancestor rea-agents-5.0.0 origin/main

在合并同步 PR 之前，关闭已被取代的 main 提案。该合并推送到 main 后，会基于更新后的基线为下一个版本打开一个提案。未来的版本可以使用自动的 main PR，或重复手动检查点流程；自动提案不会移动冻结的分支。

准备阶段会在候选检出上生成并验证目录、可移植一致性投影和打包技能，而不提交它们。检查点验证器将受跟踪的版本权威绑定到源 SHA；生成的目录和包检查用于验证派生表示。任何生成元数据的工作流都不会向功能分支或发布分支推送后续提交。

部分发布与重试

重试前，检查失败的任务和公共注册表状态。当 npm 已经发布时，npm 任务会验证该确切版本，而不是再次发布它。请在原始发布运行中重新运行失败的任务，以保持其发布 SHA 和输出不变。如果只有 MCP 发布失败，在确认 npm canary 成功后重试该任务。

如果分支尖端在调度后发生移动，则会在 Release Please 创建标签之前失败。不要调度一个新的发布阶段来修复已创建的发布：Release Please 不会再次创建相同的发布。不要以移动标签、删除发布或取消发布 npm 的方式重试。有缺陷的公共包需要经过审查的修正和新版本。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 rea2/rea