本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。英文原文

發行回滾作業手冊

狀態：現行範圍：公開、現行狀態上次審閱：2026-09-03 負責人：AX Code 發行工程

本作業手冊說明如何撤回已發布的 stable（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 把 formula 提交推送到共用的 defai-digital/homebrew-tap 儲存庫。還原該提交，使 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 提供已恢復的版本，並在乾淨的執行器上乾淨安裝（install-matrix 冒煙工作流程會做這件事）。
確認全新安裝上的 ax-code --version 報告已恢復的版本，並通過 ax-code doctor。

7. 事後檢討

記錄哪些項目通過了發行閘門卻仍然帶著損壞出貨，並在下一次發行之前針對 .github/workflows/release.yml（驗證、冒煙覆蓋）提出修正。若任何步驟沒有照書面運作，請更新本作業手冊。