Composio 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本篇指南基于 Composio 仓库中.agents/skills/cli-command/references/design.md编写系统讲解composio/cli命令面的设计准则stdout/stderr 双流契约、ui.output()的机器输出边界、TTY 感知的交互策略、环境变量配置体系与退出码语义。读完本文你将掌握在 Composio 中新增或审查 CLI 命令时应当遵循的完整设计规范并能对照 ts/packages/cli 的源码理解每条规则背后的实现原理。一、设计原则把人看的和机器读的彻底分开Composio CLI 的第一条设计原则是 Unix 传统中数据与装饰分离的严格化stdout 只承载数据stderr 只承载人类可读的装饰信息。这是整个命令面设计的基石其余规则几乎都由此派生。具体落到实现上规范要求ui.output()是唯一的机器数据出口——只有脚本需要捕获的值API Key、版本号、工具列表等才通过它写入 stdout保持 quiet / piped 模式干净——当 stdout 被重定向到管道或文件时终端上不能出现任何多余字符污染数据优先使用 flags 而非模糊的位置参数——命令的可读性与自文档性优先统一使用约定俗成的 flags——当命令形态需要时一致地使用--json、--dry-run、--force、--no-input、--no-browser避免每个命令各自发明一套绝不通过 flags 接收 secrets——API Key 等敏感信息不能出现在命令行参数中进程列表可见只能走交互输入或环境变量。在 ts/packages/cli/AGENTS.md 的 Output Conventions 一节中这一原则被进一步细化为三条独立契约canPromptstdin.isTTY stderr.isTTY、机器输出!stdout.isTTY与canDecoratestderr.isTTY。三者的关键约束是管道piping永远不能改变提示或认证行为——composio login | tee应当与人工登录完全等价同样重定向 stdin 或 stderr 也绝不能导致数据泄漏到可见的 stdout 终端上。二、帮助与错误把失败也当作产品体验的一部分规范对帮助文本与错误处理提出了明确的要求帮助文本就是用户体验Help text is user experience。每个命令的帮助应当以简洁的描述开头并紧跟常见用法示例让用户在不读源码的情况下就能完成 90% 的操作。预期错误要给出下一步行动。当用户输错了 flag、缺少参数或鉴权失败时错误信息不仅要说明发生了什么还要告诉用户下一个命令或修复方法是什么。例如在 cli-main.ts 中当出现ValidationError时CLI 会解析出Received unknown argument之类的具体错误并追加诸如Tip: --xxx requires a value, e.g. --xxx value的修复提示同时打印对应命令的帮助文本。意外错误要保留调试细节。未预期的异常不应当被吞掉或只显示一行笼统信息而是通过仓库自有的effect-errors/机制source-mapped 堆栈、Effect span 时间线、格式化输出呈现方便上报与定位。在 cli-main.ts 中可以看到最终兜底的Effect.catchAll会调用captureErrors/prettyPrintFromCapturedErrors输出错误详情并设置退出码 1。三、交互性只在人类在场时提问Composio CLI 的交互策略是严格 TTY 感知的统一使用clack/prompts且必须经过现有的 CLI UI 抽象层——即TerminalUI服务src/services/terminal-ui.ts而不是在命令里直接调用 Clack仅当 stdin 是 TTY 时才发起提示——自动化环境CI、管道、脚本没有键盘也不该被挂起非交互模式应当以可操作的错误信息失败而不是挂起等待——--no-input或非 TTY 场景下命令要么使用默认值继续要么明确报错并给出修复路径。在 terminal-ui.ts 中TerminalCapabilities把canPrompt定义为stdinIsTTY stderrIsTTYstdin 必须能接收输入同时 stderr 必须能显示 Clack 提示框。值得注意的是stdout 是否 TTY 完全不参与提示决策——这保证了composio login | tee场景下提示与认证流程不变。当提示不可用时ui.confirm直接返回defaultValue默认trueui.select返回第一个选项的值保证脚本流程不被阻塞。四、配置与状态环境变量、用户态与项目作用域三层体系规范明确了 CLI 的配置读取与状态存放规则这是最容易踩坑的部分4.1 环境变量COMPOSIO_前缀与豁免例外运行时配置通过effect/Config从环境变量读取相关代码在 src/services/config.ts 与 src/cli-config.ts常规键采用大写蛇形命名upper snake case并以COMPOSIO_为前缀读取时前缀会被剥离。例如设置COMPOSIO_USER_API_KEYxxx代码中通过Config.string(USER_API_KEY)读取例外情况DEBUG_OVERRIDE_*和FORCE_*两类变量原样读取、不做前缀映射见 src/constants.ts 中的APP_ENV_CONFIG_KEY_PREFIX与DEBUG_OVERRIDE_ENV_CONFIG_KEY_PREFIX以及 config.ts 的extendConfigProvider实现。这种前缀剥离设计的好处是代码内部只关心短键名而环境变量命名空间由COMPOSIO_统一隔离避免与用户机器的其他环境变量冲突。4.2 用户态~/.composio/user-config.json持久化的用户 / 认证状态存放在~/.composio/user-config.json对应 constants.ts 中的USER_CONFIG_FILE_NAME其值来自composio/core的USER_DATA_FILE_NAME。关键的合并规则是ComposioUserContext服务会把环境变量叠加在存储文件之上且环境变量优先——同一个键只要环境变量存在就以环境变量为准覆盖文件中的旧值。这样既支持纯环境变量驱动的无状态部署也支持交互式登录后的持久化复用。用户态的实现位于 src/services/user-context.tsAPI Key 还会优先写入系统 keyringmacOS Keychain / Linux Secret Service经由composio/cli-keyring仅在 keyring 不可用时回退为明文存储。4.3 项目作用域项目本地.composio/目录与全局用户态相对项目级数据project-scoped data使用项目本地的.composio/目录constants.ts 中PROJECT_COMPOSIO_DIR .composio其中包含project.json项目配置与.env项目级环境覆盖。这套全局用户态 项目本地态的分层让同一个 CLI 可以在多个项目间切换而不互相污染。五、退出码只有 0 和 1中断不算失败退出码语义是脚本化集成的契约规范给出的规则非常明确成功退出0失败退出非零1中断interrupt如 CtrlC 触发的信号不视为失败——被中断的命令不应被当作错误处理也不应污染后续的自动化判断不存在独立的无效用法invalid usage退出码——不要自行发明2之类的特殊码。上述逻辑落在 src/cli-main.ts 的teardown中当Exit是失败且Cause不仅仅是中断时才返回1否则返回0同时尊重composio run这类代理进程通过process.exitCode上报的状态。整个 CLI 通过BunRuntime.runMain({ teardown })接入该清理逻辑。这条规则的意义在于任何依赖退出码做条件判断的脚本都可以放心地依据0/ 非0二值语义编写无需区分用法错误与运行失败。六、源码佐证从规范到实现的关键路径为了便于在仓库中按图索骥下表汇总了上述规范对应的核心实现文件规范主题核心实现命令面与整体架构ts/packages/cli/AGENTS.md含完整命令清单与分层结构输出流契约 / TerminalUIsrc/services/terminal-ui.tsTerminalCapabilities、ui.output()的stdoutIsTTY判断环境变量配置读取src/services/config.tsConfigProvider.fromEnv 前缀映射、src/cli-config.tsshowBuiltIns: false、isCaseSensitive: true前缀与常量定义src/constants.tsCOMPOSIO_/DEBUG_OVERRIDE_前缀、缓存文件名、项目目录退出码 / 中断语义src/cli-main.tsteardown、BunRuntime.runMain、错误兜底输出用户态合并src/services/user-context.tsComposioUserContext、keyring 回退引导装配src/bin.tsEffect 层组合与根命令启动此外规范指向两份辅助材料命令的实现范式Command.makeEffect.gen、Effect 平台边界、必跑的pnpm typecheck与pnpm --filter composio/cli test见 .agents/skills/cli-command/references/implementation.md而 Effect 与 Clack 的只读源码位于 ts/vendor 目录供实现时对照查阅。七、实战建议新增命令时的自检清单将本规范浓缩为一份可执行的检查清单供在ts/packages/cli/src/commands/下新增命令或审查既有命令时逐条核对数据出口该命令是否产生脚本应捕获的值是 → 用ui.output(value)写 stdout配合ui.log.*/ui.note()做 stderr 装饰否 → 只做装饰不写 stdout流契约绝不向 stderr 写数据、向 stdout 写装饰绝不根据 stdout 的 TTY 状态分支程序行为如认证路径flags 一致性需要时使用--json/--dry-run/--force/--no-input/--no-browser避免自定义别名secretsAPI Key 等敏感输入走环境变量或交互提示绝不通过 flag 传递帮助文本以简洁描述 常见示例开头错误处理预期错误给出发生了什么 下一步命令意外错误保留调试细节交互提示必须经由TerminalUI抽象非 TTY 下不挂起回退默认值或报可操作错误配置运行时配置走effect/ConfigCOMPOSIO_前缀用户态存~/.composio/user-config.json项目态存项目本地.composio/退出码成功0、失败1中断不算失败不引入额外的无效用法码。遵循这份规范Composio CLI 的每个命令都能同时服务好两类读者终端前的人类用户与管道另一端的脚本——这也是该设计文档作为cli-commandskill 核心参考见 .agents/skills/cli-command/SKILL.md被反复引用的原因。【免费下载链接】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），仅供参考