Agents CLI 实战：把多种 AI 编程 Agent 变成可控的项目工作流
团队同时使用 Claude Code、Codex 和 Gemini CLI 时，真正难管的通常不是某一次提示词，而是工程边界：不同成员装了不同版本；MCP 服务要重复配置；一次任务里的研究、实现和测试又缺少可追踪的依赖关系。
Agents CLI 是 phnx-labs 的 Apache-2.0 开源工具链。它不替代模型或原有 CLI，而是调用它们已有的认证和运行时，在项目级别统一版本、资源和调度。仓库当前以 TypeScript 开发；安装包是 @phnx-labs/agents-cli。因此，是否走订阅或 API key 取决于被调用的原生 Agent，而不是由 Agents CLI 另行决定。
先把“可复现”放在模型之前
从 npm 安装后，命令可使用完整的 agents 或短别名 ag。项目中先固定需要的 Agent 版本：
npm install -g @phnx-labs/agents-cli # 在当前项目写入版本约束 agents use claude@2.0.65 -p agents use codex@0.116.0 -p
上述操作会在项目根目录创建 agents.yaml。把它提交到仓库，比在 README 里写“请安装最新版”可靠得多：同一项目的调用会被路由到约定版本。
# agents.yaml agents: claude: "2.0.65" codex: "0.116.0"
版本固定不是保证模型输出完全一致，而是避免 CLI 的工具调用、配置路径或行为随着升级悄悄变化。升级工具本身时，官方文档使用的是 agents upgrade，而不是 agents update。
一份项目配置，交给多个运行时
多 Agent 工作流的第二个问题是配置漂移。Agents CLI 可以一次安装 MCP 资源，并列出当前注册状态：
# 以官方示例中的 Notion MCP 为例 agents install mcp:com.notion/mcp agents mcp list
工具的设计目标是把共享资源同步给兼容的 Agent 运行时。对于项目说明，它还可以把一份 AGENTS.md 同步到不同工具所期待的位置，例如 Claude Code 的 CLAUDE.md、Gemini CLI 的 GEMINI.md 和 Cursor 的 .cursorrules。这不意味着所有 Agent 的能力或配置格式完全相同；上线前仍应分别检查权限范围，尤其是文件写入和外部 MCP 的访问权限。
用管道明确交接，而不是让所有 Agent 同时改代码
最小的跨模型协作可以是串行链路。前一个命令的标准输出成为后一个命令的输入，因此每一段都应要求产出简洁、可验证的交接信息：
agents run claude "审查本周合并的 PR，列出可复现的风险" \ | agents run codex "为其中最重要的三个风险编写回归测试"
这种方式适合“审查 → 测试”之类的线性任务。不要把它误当成自动合并机制：测试 Agent 生成的改动仍需要在本地运行测试、检查 diff，并通过团队既有的代码审查流程。
当单个运行时受限时，可以显式设置后备链路：
agents run claude "重构认证模块，并说明变更范围" \ --mode edit --fallback codex,gemini
--fallback 的价值是让任务在原 Agent 触发限额时交给后续候选；它不保证不同模型对同一任务产生等价实现。若机器上为同一 Agent 配置了多个登录账户，--strategy balanced 会在可用版本间分散运行负载。请先确认这符合各服务的账户和使用条款。
有依赖的并行任务，用 Teams 表达出来
真正需要并行时，关键不是多开几个终端，而是写清谁依赖谁。Teams 用名字和 --after 表达依赖，队友在隔离的 worktree 中以脱离终端的方式运行：
agents teams create auth-feature agents teams add auth-feature claude "调研可用的认证库" --name researcher agents teams add auth-feature codex "起草迁移方案" --name migrator --after researcher agents teams add auth-feature claude "为迁移结果编写测试" --name tester --after migrator agents teams start auth-feature agents teams status auth-feature
teams status 用于检查执行状态和改动摘要，teams logs 可查看某个队友的日志；任务结束后使用 agents teams disband 清理团队。这里的“并行”只会启动依赖已经满足的任务，因而适合把研究、实现、验证拆成边界明确的小步骤。若两个任务会改同一批文件，仍应改成串行，或先划分目录和接口，避免 worktree 合并时才暴露冲突。
把任务契约写在启动之前
Teams 解决的是调度和隔离，不会自动替团队补齐任务定义。一个容易复用的做法是：为每位队友在提示词中写清输入、允许修改的范围、交付物和验收命令。例如研究者只输出候选库、许可证和兼容性依据；迁移者只修改指定目录并提交迁移说明；测试者只新增或调整测试，最后报告实际执行过的命令与结果。这样，后继任务读到的是可以检查的材料，而不是一段难以复用的对话摘要。
在建队之前，先在干净工作区运行一次项目原有的测试、静态检查和格式化命令，并把基线结果记入任务说明。若基线已经失败，测试 Agent 新报告的失败就不应被直接归因到它的改动。任务完成后同样分两层验收：先查看 agents teams status auth-feature 给出的摘要，再切回主工作区检查每个 worktree 的 diff、冲突和测试结果。调度器能让任务保持隔离，但不能替你判断依赖升级、生成文件或迁移脚本是否适合合并。
另一个常见失误是把“模型可以后备”与“任务可以安全接力”混为一谈。--fallback codex,gemini 适合在首选运行时不可用时维持任务推进；但后备 Agent 接手前，仍需要从提示词、Git 状态和前一段输出中获得足够上下文。对于会写入代码的任务，建议把目标分成小而可验证的提交：先生成计划或审查结果，再实现一个边界明确的改动，最后独立运行测试。不要在没有人工观察的情况下，把长管道直接连接到自动发布、删除资源或生产环境变更。
何时不该上 Teams
小修复、单文件文案调整或一条已经非常明确的测试失败，通常由一个 Agent 加人工复核更快。Teams 的价值来自相互独立、可并行且能明确表达依赖的工作；如果所有队友都要改同一个中心模块，worktree 只会把冲突推迟到合并阶段。此时先让一个 Agent 梳理接口和拆分方案，再按目录、模块或测试层划分后续任务，往往比盲目并行更省时间。
对外部 MCP 也应采用最小授权：只安装完成当前任务需要的资源，分别确认各原生 Agent 实际获得的权限，并避免把生产凭据塞进共享项目文件。Agents CLI 可以同步配置，但权限语义仍由各运行时和 MCP 服务端决定；“安装成功”不是“可以无审查地执行任意操作”的同义词。
采用建议
把 Agents CLI 当作编程 Agent 的项目级运行控制层，而不是一键完成开发的承诺。一个稳妥的落地顺序是：先用 agents.yaml 固定一个小项目的版本；再同步必要的 MCP 和项目说明；最后从“审查 → 测试”的两段管道开始。只有在交付物、目录边界和验收命令都写清楚后，再引入 Teams。
这样，模型可以各自发挥长处，但版本、配置、依赖和人工验收仍留在工程流程中可见、可审计的位置。开始时不妨只挑一个低风险仓库和两名队友，连续跑几次同样的“调研—实现—测试”链路，记录等待时间、冲突来源和人工返工点；确认任务边界真的稳定后，再扩大到更多运行时或更复杂的依赖图。把并行度当作需要测量的工程参数，而不是默认越高越好；每次扩容都应以可复现的质量指标为前提。