本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。英文原文

发布回滚运行手册

状态：生效范围：公开、当前状态最近审阅：2026-09-03 负责人：AX Code 发布工程

本运行手册说明如何撤回已发布的稳定（latest 渠道）AX Code CLI 发布并恢复上一个版本。预发布（beta 渠道）不触及 Homebrew tap 或 winget，因此回滚它们只需要下面的 GitHub 发布步骤。

功能性缺陷优先向前热修（发布 vX.Y.Z+1）。仅在发布完整性失败时回滚：损坏或签名错误的产物、损坏的安装器、渠道或标签错误（例如把预发布标签发布到 latest），或没有快速修复的严重回归。

1. 冻结渠道

暂停进一步的发布和 postpublish_only 恢复，直到回滚完成。发布工作流拒绝替换已发布版本上的资源，因此并发的重新运行不能覆盖正在回滚的状态。

2. 重新指向 GitHub 发布

把有问题的发布标为预发布，使 latest 解析到上一个标签，并在发布说明被覆盖时恢复先前的说明：

gh release edit "vX.Y.Z" --repo defai-digital/ax-code --prerelease
gh release edit "vX.Y.(Z-1)" --repo defai-digital/ax-code --latest

如果有问题的发布的资源已损坏或签名错误，也删除它们，以免安装器取到：

gh release delete-asset "vX.Y.Z" "<asset-name>" --repo defai-digital/ax-code

在其产物调查完成之前，不要删除发布对象本身；已签名的资源和工作流日志是事后分析的证据。

3. 还原 Homebrew tap

bash .github/scripts/update-homebrew.sh 向共享的 defai-digital/homebrew-tap 仓库推送了一次 formula 提交。还原该提交，使 brew upgrade ax-code 再次提供上一个版本。原先的 defai-digital/homebrew-ax-code 仓库只包含迁移元数据；不要恢复它的 formula：

git -C homebrew-tap revert --no-edit <formula-commit>

之后用 Homebrew 冒烟作业（.github/workflows/install-matrix-smoke.yml）对照恢复的版本验证收敛。

4. 还原 winget 清单

Winget 清单由维护者从附加在 GitHub 发布上的清单 ZIP 提交到 microsoft/winget-pkgs。如果有问题的版本已被接受，打开一个 PR 还原那些清单文件。如果仍在审阅中，关闭该 PR。发布上的 --clobber 上传只替换附加的 ZIP，从不替换已发布的包。

5. 沟通

在发布讨论和任何支持频道发布简短说明：受影响的版本、恢复的版本，以及重新安装说明：

Homebrew：brew update && brew upgrade ax-code（或 brew uninstall ax-code && brew install ax-code）。
Windows 或其他：从上一发布页面重新运行固定的安装器；签名不匹配时安装器失败关闭，并引导一个固定的、经过 SHA-256 检查的 minisign。

6. 核验恢复后的状态

确认 GitHub 的 latest 发布指向先前的标签，且每个资源都能核验：

gh release download "vX.Y.(Z-1)" --repo defai-digital/ax-code -p '*.zip' -p '*.minisig'
minisign -V -p docs/release/ax-minisign.pub -m ax-code-darwin-arm64.zip -x ax-code-darwin-arm64.zip.minisig

确认 Homebrew formula 提供恢复的版本，并在干净的运行器上干净安装（安装矩阵冒烟工作流会做这件事）。
确认在全新安装上 ax-code --version 报告恢复的版本，并通过 ax-code doctor。

7. 事后分析

记录哪些检查通过了发布门控却仍然发出了损坏的版本，并在下一次发布之前针对 .github/workflows/release.yml（校验、冒烟覆盖）提交修复。如果任何步骤没有按所写的方式生效，请更新本运行手册。