agi-cli 实战：把多种 AI 编程 Agent 组织成可验证的项目工作流
团队同时使用 Claude Code、Codex 等编程 Agent 时，真正难管理的往往不是某一条提示词，而是工程边界：成员各自安装了不同版本，MCP 服务需要重复配置，研究、实现和测试之间又缺乏可追踪的交接关系。结果是同一个任务在不同机器上表现不同；即使最终代码能跑，也很难解释究竟由哪个版本、哪份规则和哪一次执行产生。
agi-cli 是 phnx-labs 维护的 Apache-2.0 许可 TypeScript 工具。它将原有 Agent CLI 作为运行时来调度，而不是替代模型或另行出售模型调用；官方说明明确指出，运行时可以沿用原生 CLI 已有的订阅或 API key。它的重点是把版本、共享资源、任务依赖和运行结果放回项目可观察的工程流程。
先固定运行版本，再讨论提示词复现
同一个 Agent CLI 升级后，工具调用行为、配置目录或参数支持都可能变化。agi-cli 可以在项目根目录写入 agents.yaml，让 shim 根据该文件把调用路由到约定的版本。下面的版本号是官方 README 用来演示格式的示例；实际项目应根据自己验证过的组合选择版本。
npm install -g @phnx-labs/agents-cli agents use claude@2.0.65 -p agents use codex@0.116.0 -p
得到的文件可以和代码一起提交：
agents: claude: "2.0.65" codex: "0.116.0"
这并不承诺模型输出逐字一致。模型服务、上下文和提示词仍会改变结果；它解决的是另一层问题：团队不必靠口头约定“装最新版”，而能先统一 CLI 版本和每个版本隔离的配置环境。需要升级 agi-cli 本身时使用 agents upgrade；官方特别区分了它与用于更新已安装 Agent harness 的 agents update，两者不应混用。
版本固定也需要配套一份小型升级记录。每次准备改动 agents.yaml 时，先在独立分支执行目标 harness 的最小冒烟任务：读取仓库、生成一个不落盘的分析结果，再确认 MCP、规则和登录状态仍可用。随后记录旧版、新版、验证命令、结果与回退方式。这里的重点不是把每次升级变成繁琐审批，而是避免版本文件被修改后，团队才在真实改动中发现某个 CLI 的参数、配置迁移或认证行为已改变。出现异常时，先把 agents.yaml 回退到已验证版本，并保留失败输出作为后续排查依据；不要让多个 Agent 同时在未确认的运行时上继续写入。
一份共享资源，分别落到原生配置格式
配置漂移常发生在 MCP、规则和技能上。每名开发者手动在多个客户端注册相同服务，最终很难确认谁漏了权限、谁使用了旧地址。agi-cli 的设计是将资源安装到统一位置，再同步为各 Agent 能识别的原生格式。例如，官方 README 给出的 Notion MCP 安装和查看方式如下：
agents install mcp:com.notion/mcp agents mcp list
同样的思路可用于项目说明。以一份 AGENTS.md 作为规范来源时，agi-cli 会将它同步到 Claude Code 的 CLAUDE.md、Antigravity 的 AGENTS.md 和 Cursor 的 .cursorrules。这里的“同步”不代表所有客户端的权限语义完全一样：尤其是文件写入、网络访问和外部 MCP，仍要逐个检查实际生效的权限。共享说明应只写团队愿意公开提交的规则，生产令牌和私密环境变量不应进入项目文件。
串行交接：把上一步输出变成可检查输入
多 Agent 协作不等于同时开更多终端。对于“先找风险、再补测试”这类线性任务，先让前一个 Agent 输出简短、可验证的交接材料，再把它传给后一个 Agent，通常比并行编辑更稳定：
agents run claude "审查本周合并的 PR，列出可复现的风险" \ | agents run codex "为其中最重要的三个风险编写回归测试"
管道的优势是交接点明确，但它不是自动合并机制。测试 Agent 生成的改动仍应在本地运行测试、检查 diff，并经过团队原有的代码审查。若首选 Agent 因限额不可用，可以显式给出后备运行时：
agents run claude "重构认证模块，并说明变更范围" \ --mode edit --fallback codex,antigravity
--fallback 只处理运行时不可用时的调度，不保证不同模型给出等价实现。后备 Agent 接手前仍需要足够上下文；因此提示词最好包含目标、允许修改的目录、不可触碰的接口、交付物格式和验收命令。把这些约束写进任务，比把长对话摘要交给下一个 Agent 更容易审查。
并行任务先画依赖图，再启动 Teams
当研究、实现和测试可以拆到不同工作树时，Teams 用名称和 --after 描述先后关系。官方示例中的基本流程如下：
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 只启动依赖已经完成的队友；每位队友在独立 worktree 中以 detached 方式运行。agents teams status 适合回答谁正在执行、谁已留下摘要，agents teams logs 可查看某个队友的日志，必要时可加 --full 获取完整输出。它们提供的是调度层证据，不是代码正确性的证明。
一个可靠的验收顺序是：启动前在干净工作区记录测试、静态检查和格式化的基线；执行后先检查状态摘要和每个 worktree 的 diff，再在对应工作树复跑验收命令。若基线已有失败，就不能把后续同一失败直接归咎于 Agent。只有确认文件边界、冲突和测试结果后，才应将工作树中的改动合并回主分支。
并行的边界，比并行度更重要
Teams 很适合职责独立的工作，例如研究者只输出候选库、许可证和兼容性依据，迁移者只修改指定目录，测试者只提交测试与实际执行结果。若两个任务都会改同一个中心模块，worktree 只是把冲突推迟到合并阶段；此时应先让一个任务梳理接口，再按目录、模块或测试层分配后续工作。
一个实用的任务契约可以写成四项：输入是分支、问题单和基线结果；修改范围是允许写入的目录与禁止触碰的文件；交付物是 diff、设计说明或测试报告；验收则是可复制执行的命令。这样的约束还应明确失败路径：依赖安装失败时是否允许改锁文件、测试不稳定时是否只报告而不重试、发现安全风险时是否停止修改并升级给人工。没有这些边界，多个 Agent 即使各自“完成”，也可能给主分支带来难以定位的隐性变化。
并行之前还要检查任务之间的数据依赖。一个 Agent 如果需要消费另一个 Agent 新生成的接口、迁移文件或测试夹具，就应该用 --after 串行化，而不是赌两个 worktree 最后能无冲突合并。反过来，文档校对、只读调研和互不重叠目录的测试补充通常更适合并行。把这种判断写在任务定义里，能把并发从“多开几个模型”变成可审计的调度选择。
外部 MCP 也应遵循最小授权原则：只安装当前任务需要的资源，分别确认每个原生 Agent 获得的权限，并避免把生产凭据写入共享文件。agi-cli 能集中处理版本和资源同步，但无法替团队判断依赖升级、数据删除或生产变更是否安全。对会写入代码的链路，更稳妥的做法是将目标拆成小的可验证提交：先计划或审查，再实现边界清晰的改动，最后由独立步骤运行测试。
采用建议
把 agi-cli 看作项目级运行控制层，而不是“一键完成开发”的承诺。可以从一个低风险仓库开始：先提交 agents.yaml 固定少量 Agent 版本；再同步必要的项目说明和 MCP；随后只运行一条“审查 → 测试”的串行链路。确认交付物、目录边界和验收命令都稳定后，再把存在明确依赖的任务交给 Teams。
这样，模型各自的能力可以保留，而版本、配置、依赖和人工验收仍留在工程流程中可见、可追踪的位置。真正值得度量的不是同时启动了多少 Agent，而是等待时间、工作树冲突、测试通过率和人工返工量是否随协作方式改善。