Composio CLI 发布全流程实战Build CLI Binaries 工作流、Beta 构建与 Stable 晋升指南【免费下载链接】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 仓库中驱动独立composio二进制与安装器的 GitHub Release 流程展开系统讲解如何通过build-cli-binaries.yml工作流完成自动 Beta 构建、手动 Beta 发布、Stable 晋升、发布后资产与安装验证以及失败发布恢复。读完本文你将掌握何时该走 Beta 路径、何时该晋升 Stable、为什么 CLI 包绝不允许创建 Changeset、如何用gh命令核对候选版本并安全派发promote-stable以及如何判断一次发布是否真正完成。本文基于仓库内.agents/skills/cli-release/SKILL.md及其配套手册 .agents/skills/cli-release/references/release-workflow.md 整理并结合 build-cli-binaries.yml 及 .github/scripts/cli-release 下的脚本实现进行源码级佐证。发布契约四条不可逾越的规则在接触任何命令之前先理解 CLI 发布流程的约束。这些规则决定了整个工作流的形态绝不添加针对composio/cli或composio/cli-local-tools的 Changeset。这两个包在 .changeset/config.json 的ignore列表中Changesets 会忽略它们一旦有人为它们添加.changeset/*.md条目会卡死ts.release.yml的 TypeScript SDK 发布列车具体机制见下文Changeset 规则一节。合并到next分支且触碰 CLI 路径的提交 一次自动 Beta 构建。Beta 经过测试后通过promote-stable工作流动作走正常 Stable 发布路径晋升。永远不要通过改动私有 CLI 的package.json来选择二进制版本。仓库中ts/packages/cli/package.json的版本字段是开发期哨兵值0.0.0-development见 ts/packages/cli/package.json它不参与版本选择。若需要有意的 minor 或 major 版本先构建一个显式指定版本的 Beta再晋升这个经过测试的 Beta。在采取动作前立即从 GitHub 解析 Beta 标签和工作流状态绝不凭记忆虚构或复用过期的候选版本。Stable 晋升是生产写入操作如果用户没有指名确切的 Beta 标签必须先展示解析出的候选版本并取得明确确认再派发。发布流程的最后一步要求全程跟进从派发成功到资产验证、安装测试全部通过之前都不算完成。执行五步法按以下步骤执行一次 CLI 发布归类请求判断本次请求属于自动 Beta、手动 Beta、Stable 晋升还是失败恢复。只读预检运行手册中的只读预检命令确定确切的源提交source commit与发布标签release tag。派发并观察只派发被请求的那个工作流动作build-beta或promote-stable并将返回的 run 观察到结束。验证发布与下游检查按手册核对已发布的 Release 与下游检查项。汇报结果报告已发布的标签、源 Beta 或提交、工作流 URL、资产状态、安装测试结果以及任何遗留的后续事项。真相源谁来定义发布行为手册明确列出了五个真相源文件它们共同构成了 CLI 发布的权威定义真相源职责.github/workflows/build-cli-binaries.yml拥有 Beta 与 Stable 的 GitHub Release 构建.github/scripts/cli-release/resolve-release-target.sh决定标签与源提交.github/scripts/cli-release/verify-assets.sh定义必需的资产集合.github/workflows/cli.test-installation.yml发布后验证安装器.changeset/config.json忽略composio/cli与composio/cli-local-tools两个包需要特别澄清ts.release.yml是 TypeScript SDK/npm 发布列车它不是CLI 二进制发布的正常路径。CLI 二进制走的是build-cli-binaries.yml。从源码看resolve-release-target.sh是版本决策的核心它对 push 事件、build-beta派发、promote-stable派发三种模式分别输出release_tag、release_version、prerelease、make_latest等元数据见 resolve-release-target.sh供后续 build 与 release 作业消费。选择路径四种场景一张表目标路径结果发布一个普通 CLI 变更将审阅通过的 PR 合并到nextpush 自动构建滚动 Beta从某个分支构建 Beta在该分支派发build-beta从该分支提交构建预发布版本发布 Stable CLI在某个已测试的 Beta 标签上派发晋升该 Beta 的源提交被重新构建并以 Stable 标签发布恢复失败的晋升检查 draft 后重跑或重新派发同一 Beta未发布的 draft 可以被恢复并替换其资产一个值得展开的细节私有 CLI 的package.json使用开发期哨兵值永远不参与选择二进制版本。如果发布负责人需要有意的 minor 或 major 版本正确做法是派发一个显式版本号的 Beta验证它然后晋升这个确切的 Beta——而不是去改package.json。版本决策的源码细节resolve-release-target.sh中有两个容易被忽视的实现细节直接关系到发布正确性按真实 semver 顺序取最新 Stable脚本明确注释指出词法排序在此处是错误的——composio/cli0.2.9在词法上排在0.2.10之后一旦 patch 进入两位数last就会选中旧版本导致 Beta 版本倒退。因此它把版本三元组解析成数字并做数值排序见 resolve-release-target.sh。滚动 Beta 标签格式无显式版本时Beta 基础版本为最新 Stable 的 patch1标签形如composio/cliversion-beta.RUN_NUMBER其中RUN_NUMBER保证每次运行唯一见 resolve-release-target.sh。显式版本必须满足major.minor.patch格式且必须高于最新 Stable否则脚本直接报错退出。Changeset 规则为什么 CLI 包被 Changesets 忽略规则只要composio/cli和composio/cli-local-tools还留在 .changeset/config.json 的ignore列表中就永远不要为它们创建.changeset/*.md条目。原因这是仓库中的真实故障模式为被忽略的包添加 Changeset 会让changesets/action进入版本 PR 模式但changeset version不会产生任何提交。于是 action 报错No commits between next and changeset-release/next阻塞无关的 SDK 发布。这个故障机制在 ts/scripts/validate-changesets.mjs 中有完整的实现与报错文案印证脚本读取.changeset/config.json的ignore列表逐一检查待处理 changesets 的 release 目标一旦发现指向被忽略包就抛出错误并说明上述机制见 validate-changesets.mjs。如果 CLI 变更需要面向用户的说明直接更新 ts/packages/cli/CHANGELOG.md。该文件以 Unreleased 小节维护未发布变更如升级命令的 spinner、下载进度、归档瘦身等补丁说明见 ts/packages/cli/CHANGELOG.md。交接前运行此守卫命令pnpm validate:changesets检查候选版本只用 GitHub 实时状态不要从本地 tag 或记忆中的版本挑选 Beta。使用实时 GitHub 状态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))对选中的候选版本要求它是已发布的预发布published prerelease并检查其提交与资产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且以下六个资产全部处于uploaded状态composio-linux-x64.zipcomposio-linux-aarch64.zipcomposio-darwin-x64.zipcomposio-darwin-aarch64.zipcomposio-skill.zipchecksums.txt这六项清单在 verify-assets.sh 中定义脚本注释明确要求它与build-cli-binaries.yml的四平台构建矩阵保持同步。为什么必须检查state uploaded而非仅仅存在于资产列表verify-assets.sh的注释给出了答案资产可能出现在列表中但仍在处理中state ! uploaded这正是发布对外提供 404 的确切原因。脚本还采用单次快照方式查询——分别查询名称和状态会打开一个 time-of-check/time-of-use 间隙见 verify-assets.sh。接着按目标提交找到 Beta 的工作流运行要求其全绿包括可复用的安装测试作业TARGET_COMMITreplace-with-targetCommitish gh run list \ --repo $REPOSITORY \ --workflow build-cli-binaries.yml \ --commit $TARGET_COMMIT \ --limit 10关键确认点如果用户要求 Stable 发布但没有指名 Beta展示解析出的候选版本停下来等待确认再派发。Stable 晋升是生产写入不能擅自执行。构建手动 Beta仅当用户明确要求构建 Beta 时才使用此路径。所选 ref 同时提供工作流定义与源提交。省略version得到常规的 next-patch Beta提供确切的major.minor.patch基础版本则用于有意的 minor 或 major 发布。SOURCE_BRANCHreplace-with-branch gh workflow run build-cli-binaries.yml \ --repo $REPOSITORY \ --ref $SOURCE_BRANCH \ --raw-field actionbuild-beta对于有意的 minor 或 major提供比最新 Stable 更新的版本gh workflow run build-cli-binaries.yml \ --repo $REPOSITORY \ --ref $SOURCE_BRANCH \ --raw-field actionbuild-beta \ --raw-field version0.3.0将返回的 run 观察到发布与安装测试结束。记住Beta 不是 Stable 发布它只是候选。工作流侧的参数定义build-cli-binaries.yml的workflow_dispatch输入定义了上述两个参数见 build-cli-binaries.ymlactionbuild-beta或promote-stable默认build-beta。version可选 semver 基础版本如0.3.0省略时取最新 Stable 的下一个 patch。派发时resolve-release-target.sh会校验显式版本必须匹配^[0-9]\.[0-9]\.[0-9]$且必须高于最新 Stable无版本时自动计算 next-patch见 resolve-release-target.sh。晋升 Beta 到 Stable首先从 Beta 标签推导 Stable 标签——去掉 beta 后缀STABLE_TAG${BETA_TAG%%-beta.*} gh release view $STABLE_TAG --repo $REPOSITORY --json tagName,isDraft,isPrerelease,publishedAt三种情况三种处理Stable 标签不存在晋升可以进行。它是 draft晋升可以恢复它。它已发布停止。永远不要覆盖已发布的 Release。然后在Beta 标签上派发工作流。所选 ref 提供不可变的源提交工作流会校验它确实与 Beta 发布匹配再重新构建gh workflow run build-cli-binaries.yml \ --repo $REPOSITORY \ --ref $BETA_TAG \ --raw-field actionpromote-stable晋升的源码级校验链resolve-release-target.sh对promote-stable施加了一系列硬性校验见 resolve-release-target.sh值得逐一理解ref 必须是 tagREF_TYPE ! tag时直接报错——promote-stable必须用--ref beta-tag派发。标签格式所选 ref 必须匹配composio/cliversion-beta.number正则。Beta 必须是预发布通过 GitHub API 查询该标签对应的 Release要求prerelease true。禁止重复晋升已发布的 Stable用gh release view检查 Stable 标签注释说明 REST/releases/tags/{tag}对 draft 返回 404因此用gh release view解析 draft 并暴露isDraft。若 Stable 已存在且是 draft允许恢复已发布则报错退出。提交一致性Beta release 的target_commitish必须等于当前派发所用的COMMIT_SHA否则报错——这保证了晋升确实来自被测试过的那个提交。使用返回的 URL如果有否则识别新的派发核对其创建时间与 actor然后观察它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-status晋升路径上的三道发布安全门build-cli-binaries.yml的 release 作业围绕先 draft、后发布设计了三道闸门见 build-cli-binaries.yml矩阵全绿才进发布路径构建矩阵fail-fast: false——单条腿失败不会取消兄弟任务而是让所有平台失败同时暴露更重要的是release 作业只在needs.build.result success时运行而该结果要求每一个矩阵腿都通过因此局部平台集永远无法到达发布路径见 build-cli-binaries.yml。先建 draft 再发布create-or-resume-draft.sh以--draft创建 Release 并挂载全部资产。draft 不触发release: published事件也不会进入/releases/latest重定向因此任何匿名消费者install.sh、重定向在资产挂载并验证完成之前都观察不到这个发布见 create-or-resume-draft.sh。发布是唯一的暴露步骤gh release edit $RELEASE_TAG --draftfalse --latest$MAKE_LATEST是最后一个动作。脚本注释提醒不要在同一调用中编辑正文——已知的 GitHub PATCH 竞态会丢失与 draft 翻转同次调用中的正文修改而 release notes 在 draft 创建时已生成。此外还有按标签串行化release 作业的 concurrency 组以解析出的标签为键cli-release-${{ needs.prepare.outputs.release_tag }}cancel-in-progress: false。两个快速 push 或重跑竞态时串行输家会在create-or-resume-draft.sh的 already published 守卫处响亮失败——那个红 ❌ 是设计使然见 build-cli-binaries.yml。验证完成四个条件缺一不可在满足以下全部条件之前不要宣布发布完成Build CLI Binaries工作流成功完成。Stable Release 已发布isDraft: false且isPrerelease: false。六个规范资产全部存在且处于 uploaded 状态。工作流的安装测试矩阵通过。gh release view $STABLE_TAG \ --repo $REPOSITORY \ --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \ --jq {tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}汇报内容应包含Stable 标签、被晋升的 Beta、目标提交、工作流 URL、资产数量与状态、安装结果。安装测试发布后的独立验证build-cli-binaries.yml在发布成功后通过uses: ./.github/workflows/cli.test-installation.yml调用可复用安装测试工作流见 build-cli-binaries.yml传入刚发布的标签作为版本。这条test-installation作业独立于 build/release 链专门验证安装器在发布之后依然可用。失败恢复五种场景的处置方案失败场景处置方案构建矩阵失败不应发布任何 Release。修复源码、产出新 Beta、晋升该候选版本存在 draft 但发布未完成检查失败原因然后重跑或重新派发同一 Beta。draft 资产可安全地用--clobber替换重复运行提示 Release 已发布这是故意的安全失败。核实已发布的 Release 并停止重复运行发布后安装测试失败不要改动已发布的标签。通过新 Beta 与下一个 Stable patch 向前修复TS 发布提示 release PR 无提交移除指向被忽略 CLI 包的待处理 Changeset把说明保留到 CLI changelog运行pnpm validate:changesets让下一次 push 重试 SDK 发布列车前两种场景对应create-or-resume-draft.sh的两条分支检测到已存在 draft 时用gh release upload ... --clobber重传资产幂等恢复检测到标签已发布时输出错误并退出拒绝改动线上发布见 create-or-resume-draft.sh。发布产物形态安装方式与配套资产发布产物的消费端是安装器与 CLI 升级逻辑。工作流中的create-install-instructions作业会生成一份 INSTALL.md展示三类安装方式快速安装curl -fsSL https://composio.dev/install | sh安装器会自动把 CLI 目录加入 zsh/bash/fish 的PATH重复运行不会产生重复条目。跳过 shell 配置COMPOSIO_INSTALL_SHELLnone适合 CI 与 Docker 场景也可显式指定COMPOSIO_INSTALL_SHELLzsh|bash|fish。指定版本安装sh -s -- release_tag。手动安装时注意CLI 会加载可执行文件旁边随附的支持文件不要只把嵌套的composio文件单独移走。安装后可用composio install --shell zsh|bash|fish把 CLI 永久加入PATH。仓库根目录的 install.sh 与 install/ 目录是安装器的实现本体它们同样被列为build-cli-binaries.ymlpush 触发路径的一部分——改动安装器会触发一轮新的 CLI 构建见 build-cli-binaries.yml。归档配套校验升级兼容性的守护发布构建中还有一个容易被忽略的校验——verify-archive-companions.sh检查每个发布归档的 codex-acp 适配器布局见 verify-archive-companions.sh四个平台路径必须齐全缺失任一路径会破坏 2026-08-18 之前发布的 CLI 的composio upgrade——旧客户端会按全部四个 codex-acp 路径验证下载的包缺一个就拒绝。只在本平台路径放真实字节归档只携带本机平台可执行的 codex-acp 二进制其余三个平台是空占位符。这避免了几百 MB 永远无法执行的死重下载。该脚本注释说明这些打包规则还有单测覆盖而此闸门是唯一检查真实归档的地方防止打包管线改动悄悄回归见 verify-archive-companions.sh。发布后的维护提醒工作流中还有一个continue-on-error的软检查烘焙的 toolkit slugs 新鲜度。composio execute会根据烘焙的 toolkit slugs 决定本地解析 toolkit 还是付费进行 catalog 拉取——过期的列表不会出错只会变慢。若ts/packages/cli/src/generated/toolkit-slugs.ts中的刷新时间超过 14 天工作流会输出 warning提示运行 CLI - Update Toolkit Slugs 工作流刷新见 build-cli-binaries.yml。这类软警告不阻塞发布但属于发布负责人应知晓的后续事项。小结Composio CLI 的发布体系可以概括为一句话一切发布都是 Beta 的产物Stable 只晋升、从不重写。合并到next自动产生滚动 Beta有意的版本变更通过显式版本 Beta 表达Stable 晋升严格绑定被测试过的 Beta 提交并以draft 先行、资产验证、最后翻转发布的顺序对外暴露任何失败都优先向前修复而非回改线上标签。遵循 .agents/skills/cli-release/references/release-workflow.md 中的路径选择表、候选检查命令与完成验证清单配合pnpm validate:changesets守卫即可安全、可审计地完成一次 CLI 发布。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考