Composio CLI 發(fā)布工作流全指南從自動 Beta、穩(wěn)定版提升到失敗恢復的 GitHub Releases 實戰(zhàn)【免費下載鏈接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.項目地址: https://gitcode.com/GitHub_Trending/co/composio導讀本文基于 Composio 倉庫中的 CLI Release Workflow 手冊配屬.agents/skills/cli-release/SKILL.md技能完整講解獨立composio命令行二進制與安裝器所依托的 GitHub Release 發(fā)布體系如何區(qū)分自動 Beta、手動 Beta、穩(wěn)定版提升與失敗恢復四條路徑如何用ghCLI 預檢候選 Beta、核對資產與安裝測試以及發(fā)布被中斷或失敗時如何安全恢復。讀完本文你將掌握一套可直接執(zhí)行的發(fā)布操作手冊并理解 build-cli-binaries.yml、resolve-release-target.sh、verify-assets.sh 等底層腳本的判定邏輯與設計動機。Sources Of Truth誰在真正掌控 CLI 發(fā)布CLI 二進制發(fā)布不依賴 npm 或 Changesets而是由一組 GitHub Actions 工作流與腳本共同構成唯一事實來源sources of truth事實來源職責build-cli-binaries.yml擁有 Beta 與 Stable 兩類 GitHub Release 的構建與發(fā)布resolve-release-target.sh決定發(fā)布 tag 與源 commit三種模式push 滾動 Beta、build-beta 派發(fā)、promote-stable 提升verify-assets.sh定義并要求六個規(guī)范資產全部uploadedcli.test-installation.yml發(fā)布后跨平臺驗證安裝器與 shell 集成.changeset/config.json將composio/cli與composio/cli-local-tools加入ignore列表使其脫離 Changesets 發(fā)布軌道特別要注意ts.release.yml是 TypeScript SDK/npm 的發(fā)布列車不是CLI 二進制的常規(guī)發(fā)布路徑。CLI 包在 ts/packages/cli/package.json 中被標記為 private版本號為開發(fā)哨兵值0.0.0-development永遠不通過 Changesets 發(fā)布到 npm二進制資產只掛在 GitHub Release 上install.sh 與composio upgrade從 Releases 下載composio upgrade --beta則解析最新的 CLI 預發(fā)布版本。Choose The Path先歸類需求再選擇發(fā)布路徑動手前必須先判斷本次請求屬于哪一類因為不同目標的入口、結果與驗證方式完全不同目標路徑結果發(fā)布一個普通 CLI 變更將已評審的 PR 合并到nextpush 自動構建滾動 Betarolling beta從某分支構建 Beta在該分支派發(fā)build-beta從該分支 commit 構建預發(fā)布版本發(fā)布穩(wěn)定版 CLI在已有且經(jīng)過測試的 Beta tag 上派發(fā)提升promotionBeta 的源 commit 被重建并以穩(wěn)定 tag 發(fā)布恢復失敗的提升檢查 draft 后重跑或重新派發(fā)同一個 Beta未發(fā)布的 draft 可被恢復并替換資產build-cli-binaries.yml的 push 觸發(fā)條件限定了 CLI 相關路徑ts/packages/cli/**、ts/packages/cli-local-tools/**、install.sh、install/**、mise.toml等也就是說只有真正改動 CLI 的合并才會觸發(fā)自動 Beta。手動派發(fā)則通過workflow_dispatch的action輸入build-beta或promote-stable與可選version輸入來控制。一個關鍵約束來自 resolve-release-target.sh私有 CLI 的package.json使用開發(fā)哨兵版本號永遠不會被用來選擇二進制版本。如果發(fā)布負責人需要一次有意的 minor 或 major 版本正確做法是派發(fā)一個顯式指定版本號的 Beta → 完整驗證 → 再提升那個確切的 Beta。Changeset Rule永遠不要為被忽略的 CLI 包創(chuàng)建 Changesetcomposio/cli和composio/cli-local-tools位于 .changeset/config.json 的ignore列表中因此嚴禁為它們創(chuàng)建.changeset/*.md條目。一旦有人創(chuàng)建了指向被忽略包的 Changeset會觸發(fā)一個非常隱蔽的連鎖故障changesets/action進入 version-PR 模式但changeset version對被忽略的包不會產生任何 commitaction 最終以No commits between next and changeset-release/next失敗并阻塞無關的 SDK 發(fā)布。這一點在 ts/scripts/validate-changesets.mjs 的實現(xiàn)中有直接印證findIgnoredChangesetReleases會掃描所有待處理的 Changeset凡命中config.ignore中包名的直接拋出異常錯誤信息明確說明“被忽略包的 Changeset 會讓 release job 在打開空 PR 時失敗”。正確的替代做法是如果 CLI 變更需要面向用戶的說明直接編輯 ts/packages/cli/CHANGELOG.md。交接前必須運行守衛(wèi)命令pnpm validate:changesets該命令定義在根 package.json 中對應ts/scripts/validate-changesets.mjs同時 test/release-workflow.test.ts 會校驗.changeset/config.json的 ignore 列表、工作流與腳本之間的一致性防止這些約束悄然漂移。Inspect Candidates基于實時 GitHub 狀態(tài)挑選 Beta選擇候選 Beta 時必須使用 GitHub 的實時狀態(tài)絕不從本地 tag 或記憶中的版本挑選因為發(fā)布狀態(tài)隨時可能變化。先列出最近 100 個 Release過濾出已發(fā)布的composio/cli預發(fā)布版本REPOSITORYComposioHQ/composio gh release list \ --repo $REPOSITORY \ --limit 100 \ --json tagName,isPrerelease,isDraft,publishedAt \ --jq .[] | select(.tagName | startswith(composio/cli)) | select(.isPrerelease and (.isDraft | not))對選中的候選要求它必須是已發(fā)布的預發(fā)布版本而非 draft然后檢查其 commit 與資產BETA_TAGcomposio/cli0.0.0-beta.000 gh release view $BETA_TAG \ --repo $REPOSITORY \ --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \ --jq {tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}合格的 Beta 必須滿足isDraft: false、isPrerelease: true且以下六個規(guī)范資產全部處于uploaded狀態(tài)這六項與 verify-assets.sh 中的expected列表完全一一對應并與構建矩陣的四個平臺保持一致composio-linux-x64.zipcomposio-linux-aarch64.zipcomposio-darwin-x64.zipcomposio-darwin-aarch64.zipcomposio-skill.zip隨版本打包的 skills 包checksums.txt由 generate-checksums.ts 對dist/binaries下所有 zip 生成的校驗和資產狀態(tài)為何如此重要verify-assets.sh 的注釋點明了原因一個資產可以出現(xiàn)在列表里但仍在處理中state ! uploaded這正是發(fā)布后出現(xiàn) 404 的典型成因。所以該腳本采用有界重試默認VERIFY_ATTEMPTS10次、每次間隔VERIFY_SLEEP_SECONDS15秒且單次快照同時查詢名稱與狀態(tài)避免“檢查與使用之間的時間窗口”。找到 Beta 后按其目標 commit 定位工作流運行記錄并要求其全綠包括可復用的安裝測試作業(yè)TARGET_COMMITreplace-with-targetCommitish gh run list \ --repo $REPOSITORY \ --workflow build-cli-binaries.yml \ --commit $TARGET_COMMIT \ --limit 10權限確認點如果用戶只要求“發(fā)布穩(wěn)定版”但沒有點名具體 Beta tag那么你應該先展示解析出的候選并在派發(fā)前停下征得明確確認——穩(wěn)定版提升是一次生產環(huán)境的寫入操作。Build A Manual Beta顯式版本與非版本化 Beta只有當用戶明確要求構建 Beta 時才走這條路。選中的 ref 同時提供工作流定義與源 commit這正是“該 ref 上定義的工作流構建該 ref 的代碼”的原因。常規(guī)的 next-patch Beta省略versionSOURCE_BRANCHreplace-with-branch gh workflow run build-cli-binaries.yml \ --repo $REPOSITORY \ --ref $SOURCE_BRANCH \ --raw-field actionbuild-beta有意的 minor 或 major 版本必須比最新穩(wěn)定版更新例如 0.3.0gh workflow run build-cli-binaries.yml \ --repo $REPOSITORY \ --ref $SOURCE_BRANCH \ --raw-field actionbuild-beta \ --raw-field version0.3.0版本校驗邏輯在 resolve-release-target.sh 中version必須匹配major.minor.patch且必須大于最新穩(wěn)定版version_is_greater按數(shù)值比較而非字典序——注釋明確解釋了為何字典序會在 patch 超過 9 時出錯。不傳版本時next_beta_base_version取最新穩(wěn)定版并patch 1作為基礎版本最終 tag 形如composio/cliversion-beta.RUN_NUMBERRUN_NUMBER 保證唯一性。派發(fā)后要持續(xù)觀察運行直到發(fā)布與安裝測試結束。請牢記Beta 不是穩(wěn)定版它不觸發(fā)/releases/latest重定向也不能被匿名用戶通過install.sh無參數(shù)安裝獲取除非顯式傳 tag。Promote A Beta To Stable從測試過的 Beta 提升穩(wěn)定版穩(wěn)定版 tag 通過去除 Beta 后綴推導${BETA_TAG%%-beta.*}例如composio/cli0.3.0-beta.123→composio/cli0.3.0。先確認目標穩(wěn)定 tag 的現(xiàn)狀STABLE_TAG${BETA_TAG%%-beta.*} gh release view $STABLE_TAG --repo $REPOSITORY --json tagName,isDraft,isPrerelease,publishedAt按結果分三種情況穩(wěn)定 tag 不存在可以繼續(xù)提升穩(wěn)定 tag 是 draft可以恢復該 draft見下文失敗恢復穩(wěn)定 tag 已發(fā)布立即停止絕不覆蓋已發(fā)布的 Release。然后在 Beta tag 上派發(fā)工作流——選中的 ref 提供不可變的源 commit工作流會先驗證它與該 Beta Release 的目標 commit 一致再重新構建gh workflow run build-cli-binaries.yml \ --repo $REPOSITORY \ --ref $BETA_TAG \ --raw-field actionpromote-stable此處--ref傳入的是 tag 而非分支。若命令返回了 URL 則直接使用否則通過以下方式定位新派發(fā)核對其創(chuàng)建時間與 actor 后再持續(xù)觀察gh run list \ --repo $REPOSITORY \ --workflow build-cli-binaries.yml \ --event workflow_dispatch \ --commit $TARGET_COMMIT \ --limit 5 gh run watch RUN_ID --repo $REPOSITORY --compact --exit-statuspromote-stable的底層防御在 resolve-release-target.sh 中層層把關必須派發(fā)在tag上REF_TYPE tag否則報錯退出該 tag 必須匹配composio/cliversion-beta.number格式通過 GitHub API 校驗該 tag 的 Release 確實是 prerelease若穩(wěn)定 tag 已是 draft 則允許恢復gh release view能按名稱解析 draft若已發(fā)布則拒絕REST 的/releases/tags/{tag}對 draft 返回 404因此用gh release view判斷isDraft校驗target_commitish與當前COMMIT_SHA完全一致——這保證了“穩(wěn)定版對應的二進制就是被測試過的那個 Beta 的源碼構建產物”。Verify Completion發(fā)布完成的五重驗證不要在任何一步缺失時宣布發(fā)布完成全部滿足才算完成Build CLI Binaries工作流成功結束穩(wěn)定 Release 已發(fā)布isDraft: false且isPrerelease: false六個規(guī)范資產全部存在且uploaded工作流的安裝測試矩陣通過隱含提升來源的 Beta 本身是通過全部驗證的。用一條命令核對最終狀態(tài)gh release view $STABLE_TAG \ --repo $REPOSITORY \ --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \ --jq {tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}匯報內容應包含穩(wěn)定 tag、被提升的 Beta、目標 commit、工作流 URL、資產數(shù)量與狀態(tài)、安裝測試結果。值得展開的是發(fā)布管線內部的“先 draft 后 publish”設計見 build-cli-binaries.yml 與 create-or-resume-draft.shRelease 先以draft形式創(chuàng)建并附帶全部資產——draft 不會觸發(fā)release: published事件也不會被/releases/latest重定向命中因此任何匿名消費者install.sh、重定向都不可能在任何資產掛載并驗證完成之前觀察到這個發(fā)布隨后verify-assets.sh作為“響亮失敗門”把關最后一步才用gh release edit --draftfalse --latest...將其翻轉為已發(fā)布。此外release作業(yè)對同一個 tag 使用 job 級并發(fā)組cli-release-${{ needs.prepare.outputs.release_tag }}做串行化防止兩次快速 push 或重跑交錯上傳資產。發(fā)布后的安裝驗證由 cli.test-installation.yml 承擔它作為可復用工作流被build-cli-binaries.yml以workflow_call方式調用在多平臺矩陣Ubuntu x64 / Ubuntu ARM64、macOS Intel / Apple Silicon覆蓋 bash 與 zsh上真實執(zhí)行install.sh驗證 bundle 與入口符號鏈接、composio --version執(zhí)行、shell 啟動文件中的托管 PATH 塊要求恰好一個 managed block保證冪等、自定義安裝目錄、卸載與錯誤處理等。這也是為什么發(fā)布負責人必須等到安裝測試矩陣通過才能收工。Failure Recovery發(fā)布失敗的分場景恢復手冊失敗場景處理方式構建矩陣失敗任何 Release 都不應發(fā)布。修復源碼產出新的 Beta再提升該候選存在 draft 但發(fā)布未完成檢查失敗原因后重跑或重新派發(fā)同一個 Beta。draft 的資產可用--clobber安全替換見 create-or-resume-draft.sh 的冪等恢復邏輯重復運行提示已發(fā)布這是有意的安全失敗。核實已發(fā)布的 Release 后停止重復運行。其機制是按 tag 串行化后先運行的已發(fā)布后運行的撞上already published守衛(wèi)并響亮地報錯而不是悄悄覆蓋線上 Release發(fā)布后安裝失敗不要改動已發(fā)布的 tag。通過新的 Beta 與下一個穩(wěn)定 patch 向前修復TS 發(fā)布提示 release PR 無提交刪除指向被忽略 CLI 包的待處理 Changeset將其說明保留在 CLI 的 CHANGELOG 中運行pnpm validate:changesets讓下一次 push 重試 SDK 發(fā)布列車恢復操作的核心原則與源碼守衛(wèi)完全一致draft 是“可恢復的中間狀態(tài)”已發(fā)布 tag 是“不可變的事實”。resolve-release-target.sh的promote-stable分支允許恢復 draft打印resuming (assets will be re-uploaded)但遇到已發(fā)布 tag 直接exit 1create-or-resume-draft.sh同樣只有兩種情況會安全繼續(xù)——draft 存在clobber 重傳或 Release 完全不存在新建其余一律報錯。理解這層設計后遇到“紅色 ?”不應盲目重試而應先確認 tag 的真實狀態(tài)。小結一次發(fā)布的生命周期把整套流程串起來一次規(guī)范的 CLI 發(fā)布是這樣的閉環(huán)合并 PR 到next僅 CLI 相關路徑→ 自動構建滾動 Beta基于 GitHub 實時狀態(tài)挑選并驗證候選 Beta六個資產uploaded、工作流與安裝測試全綠若需要顯式版本派發(fā)build-beta并攜帶version輸入在通過驗證的 Beta tag 上派發(fā)promote-stable由腳本守衛(wèi)完成 commit 一致性校驗與“不覆蓋已發(fā)布 tag”的保護先 draft 建 Release、校驗資產、再翻轉為發(fā)布最后等待安裝測試矩陣通過匯報穩(wěn)定 tag、來源 Beta、目標 commit、工作流 URL、資產狀態(tài)與安裝結果若任何環(huán)節(jié)失敗按失敗場景表恢復且永遠“向前修復”而不是改動已發(fā)布的 tag。需要再次強調的是這套 CLI 二進制發(fā)布體系與 TypeScript SDK 的 Changesets 發(fā)布是兩套并行軌道CLI 包被 .changeset/config.json 顯式 ignore其版本號由 GitHub Release tagcomposio/cliversion[-beta.n]唯一權威決定而不是由package.json或 Changeset 決定。理解這條邊界是安全操作 Composio CLI 發(fā)布的起點?！久赓M下載鏈接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.項目地址: https://gitcode.com/GitHub_Trending/co/composio創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考