1. 从单兵作战到团队协作我为什么开始折腾 AI 开发团队最早用 Codex 那会儿我跟大多数人一样把它当成一个高级点的代码补全——写个函数、补个测试、解释一段报错用完就关。直到有一次我接了个需求把一个老项目的 REST 接口全量迁移到新的数据层涉及十几个模块、上百个文件。我照旧把任务拆成一条条 prompt 丢给 Codex结果它每次只能看到我贴进去的那一小段上下文改完 A 文件不知道 B 文件里还有同样的调用来回返工了三四轮我人快疯了。那次之后我才真正意识到单个 AI 会话的瓶颈不在模型能力而在上下文边界和任务编排。一个真实的开发任务从来不是写一个函数这么简单它包含需求理解、方案设计、编码、测试、审查、集成这一整条链路而每一步需要的上下文、工具、验证方式都不一样。你让一个会话从头扛到尾它必然在某个环节掉链子。这就是我开始研究AI 开发团队的起点。所谓 AI 开发团队说白了就是把一个大任务拆给多个各司其职的 AI 角色让它们像一个小型工程团队一样协作有人负责规划、有人负责写代码、有人负责审查、有人负责跑测试。而 Codex Team Runtime 这套东西本质上就是给这些角色提供一个能共享状态、能调用工具、能互相传递产物的运行环境。这篇文章是我写完前六篇实践记录之后的复盘。前六篇里我分别聊过角色划分、MCP 工具接入、上下文管理、任务编排、错误恢复和成本控制这一篇不再重复那些细节而是把整套东西拉通来看哪些设计是真的有用哪些是我一开始想当然、后来被现实打脸的以及如果你现在想自己搭一套应该从哪儿下手。适合读这篇的人有三类一是已经在用 Codex 或类似工具、但还停留在单会话问答阶段的开发者二是想给自己的项目引入 AI Agent 协作、但不知道从哪切的中小团队技术负责人三是对 MCP、Agent Runtime 这些概念听过但没实操过、想找个真实案例对照学习的人。我不会讲太多抽象理论主要讲我踩过的坑和最后跑通的方案。2. 整体架构设计一个 AI 开发团队到底由什么组成2.1 角色划分不是拍脑袋而是照着真实工程流程来我一开始设计角色的时候犯过一个典型错误按技术栈分比如前端 Agent后端 Agent数据库 Agent。跑了两天就发现不对劲——前端 Agent 写完组件不知道该不该等后端接口后端 Agent 改完 schema前端那边完全不知情两边各写各的集成的时候全是冲突。后来我改成按工程阶段分角色一下就顺了。目前我稳定在用的角色有这么几个Planner规划者只做一件事把用户的一句话需求拆成可执行的任务列表每个任务标注输入、输出、依赖关系。它不写代码。Coder编码者接收单个任务产出代码变更。它能看到 Planner 给的上下文但看不到其他 Coder 的中间产物避免互相干扰。Reviewer审查者对 Coder 的产出做静态审查重点看边界条件、错误处理、是否违反项目约定。Tester测试者负责跑测试、补测试用例把失败信息结构化后回传给 Coder。Integrator集成者负责把多个 Coder 的产物合并处理冲突跑全量验证。这个划分的逻辑是每个角色的输入输出边界清晰且对应真实团队里的一个岗位。Planner 对应 Tech LeadCoder 对应开发Reviewer 对应 Code ReviewTester 对应 QAIntegrator 对应 Release Engineer。你不需要发明新流程直接复用你团队里已经跑通的协作模式就行。提示角色数量不是越多越好。我试过拆出七个角色结果光是角色间的消息传递就占了大量 token收益还不如五个角色。五个是我实测下来的甜点。2.2 Runtime 的核心职责状态、工具、消息三件事很多人把 Runtime 理解成跑 Agent 的容器这个理解太窄了。我踩过坑之后总结Runtime 真正要解决的是三件事第一是状态管理。每个 Agent 都有自己的上下文但团队协作需要共享一部分状态——比如当前任务列表、已完成的任务、已知的项目约定。Runtime 要提供一个共享状态层让 Agent 能读写但又不能让它随便污染别人的私有上下文。第二是工具调用。这就是 MCP 出场的地方。Coder 需要读文件、写文件、跑命令Reviewer 需要读 diffTester 需要跑测试框架。这些能力如果每个 Agent 自己实现一遍维护成本爆炸。MCP 协议的价值就在于把工具能力标准化成一个个 serverAgent 通过统一协议调用换工具不用改 Agent 逻辑。第三是消息传递。Agent 之间怎么通信是直接调用还是通过消息队列我一开始用直接函数调用简单是简单但一旦某个 Agent 卡住整个流程就死锁。后来改成基于事件的消息传递每个 Agent 订阅自己关心的事件Runtime 负责路由鲁棒性好了很多。2.3 为什么选 Codex 作为核心而不是自己训模型有人问我既然要搭团队为什么不自己微调一个模型我的答案很直接在工程协作这个场景里模型能力早就不是瓶颈了编排能力才是。我用 Codex 是因为它在代码理解和工具调用上的稳定性够好而且它的接口设计天然适合被 Runtime 调度。自己训模型你得先解决数据、算力、评测三座大山等训出来编排层的问题一个都没少。更重要的是Codex 这类工具的价值在于它已经被大量真实代码验证过你知道它在什么情况下会犯错、犯什么错。这种可预期的失败模式对搭团队至关重要——你可以针对性地加 Reviewer 和 Tester 去兜底。一个你完全不了解脾气的新模型反而更难编排。3. 核心细节拆解MCP 工具层与上下文管理3.1 MCP 接入的实操要点与常见坑MCP 这块我踩的坑最多单独拎出来讲。MCP 本质是一个协议让 Agent 能用统一的方式调用外部工具。听起来很美但实操里有一堆细节。首先是server 的粒度。我一开始把文件操作做成一个大 server里面塞了读、写、删、移动、搜索十几个工具。结果 Agent 调用的时候经常选错工具比如想读文件却调了搜索。后来我拆成三个 serverfs-read只读、fs-write只写、fs-search只搜每个 server 工具少而精Agent 选错的概率大幅下降。其次是工具描述的质量。MCP 工具的 description 字段直接决定 Agent 会不会用对。我见过太多人把 description 写成读取文件这种描述 Agent 根本没法判断什么时候该用。好的描述应该包含这个工具做什么、什么场景用、参数含义、返回什么、有什么限制。比如我现在的fs-read描述是这样的读取指定路径的文件内容。 适用场景需要查看文件现有内容以决定如何修改时。 不适用需要查找文件时请用 fs-search。 参数 path相对于项目根目录的路径必须存在。 返回文件全文超过 5000 行会截断并提示。这段描述写完之后Agent 用错工具的情况基本消失了。第三个坑是超时和重试。MCP 调用是跨进程的网络抖动、server 崩溃都可能发生。我一开始没做超时结果一个 server 卡死整个团队流程停摆半小时。后来给每个 MCP 调用加了 30 秒超时和最多 2 次重试并且重试时把错误信息回传给 Agent让它自己决定是换个方式还是放弃。注意MCP server 的启动顺序也有讲究。如果 Coder 依赖 fs-write而 fs-write server 还没起来Coder 第一次调用就会失败。我的做法是 Runtime 启动时先做一次健康检查所有依赖的 server 都 ready 了再放 Agent 跑。3.2 上下文管理怎么让 Agent 既知道全局又不被淹没上下文管理是 AI 团队里最容易被低估的部分。单个会话的时候你把所有东西塞进去就行但团队协作时每个 Agent 需要的上下文不一样塞多了浪费 token 还干扰判断塞少了它又做不对事。我的做法是分层上下文全局层项目结构、技术栈、编码约定、当前任务列表。所有 Agent 都能看到但只读。角色层每个角色专属的指令和示例。比如 Reviewer 的上下文里有审查清单Coder 的上下文里有代码风格示例。任务层当前这个任务的具体输入包括相关文件内容、上游产物、依赖状态。会话层Agent 自己的历史对话只对它自己可见。关键设计是任务层上下文要精准裁剪。Planner 拆任务的时候会标注每个任务涉及哪些文件Runtime 只把这些文件的内容注入 Coder 的上下文而不是把整个项目塞进去。我实测下来这样能把单次调用的 token 消耗降低 60% 以上而且 Agent 的准确率反而更高——因为干扰信息少了。还有一个细节上下文要带版本号。如果 Coder 读的是文件 v1写完代码后文件已经被别人改成 v2 了那它的产出就是基于过期信息的。我的做法是每次注入文件内容时记录 hashCoder 提交产物时 Runtime 校验 hash不一致就打回重做。这个机制救了我好几次尤其是在多个 Coder 并行改同一批文件的时候。3.3 任务编排串行、并行与依赖处理任务编排的核心问题是哪些任务能并行哪些必须串行。我一开始图省事全部串行跑结果一个中等规模的重构任务跑了四十多分钟慢得让人抓狂。后来改成能并行就并行速度快了但引入了新的问题——并行任务之间的冲突。我的解决方案是基于文件依赖的编排。Planner 拆任务时会标注每个任务读哪些文件、写哪些文件。Runtime 据此构建依赖图两个任务如果写的文件有交集必须串行。两个任务如果只读不写或者写的文件完全不重叠可以并行。有明确数据依赖的比如 B 任务需要 A 任务的输出必须串行。这个规则听起来简单但实现起来要处理不少边界情况。比如读文件和写文件的冲突——A 任务读 config.jsonB 任务写 config.json这俩能不能并行我的答案是不能因为 A 读到的可能是 B 写之前或写之后的内容不确定。所以我的规则是只要读写集合有交集就串行。并行度也不是越高越好。我试过同时跑 8 个 Coder结果 MCP server 被打爆而且合并冲突多到 Integrator 处理不过来。现在我把并行度控制在 3 到 4 个兼顾速度和稳定性。4. 实操过程从零搭一套能跑的 AI 开发团队4.1 环境准备与依赖清单先说环境。我用的是 Linux 开发机Python 3.11Node 20。核心依赖不多但每个都要装对版本不然 MCP 连接会出各种诡异问题。组件版本用途备注Python3.11Runtime 主逻辑3.10 以下 asyncio 有坑Node.js20 LTS部分 MCP server有些 server 是 npm 包Codex CLI最新稳定版核心 Agent 引擎装完先跑一次自检MCP SDK对应语言版本工具协议实现版本要和 server 对齐Git2.30产物版本管理用于 diff 和回滚装完之后第一件事是跑通一个最小 MCP 调用。别急着搭团队先写一个最简单的 fs-read server让 Codex 调一次确认整条链路通了。我见过太多人一上来就搭五个角色结果卡在 MCP 连接上连问题出在哪都定位不到。提示Codex CLI 装完后如果报找不到 runtime 组件八成是环境变量没配好。先确认 CLI 能独立跑起来再接入 Runtime。4.2 最小可用团队三个角色的起步方案如果你现在就想动手我建议从三个角色起步Planner、Coder、Reviewer。Tester 和 Integrator 先不加等这三个跑顺了再扩。具体流程是这样的你输入一句需求比如给用户模块加一个软删除功能。Planner 接收需求输出任务列表每个任务包含任务描述、涉及文件、预期产出。Runtime 按依赖关系调度把第一个任务发给 Coder。Coder 产出代码变更以 diff 形式。Reviewer 审查 diff输出通过或打回 原因。通过则进入下一个任务打回则回到 Coder 重做。这个流程跑通之后你会发现两个问题一是 Coder 经常产出看起来对但跑不起来的代码二是 Reviewer 有时候会漏掉明显问题。这两个问题分别靠加 Tester 和优化 Reviewer 的审查清单来解决但那是下一步的事。先把主干跑通比什么都重要。4.3 关键配置任务队列与状态存储Runtime 的状态存储我用了最简单的方案SQLite 文件系统。任务队列、任务状态、产物 hash 全存 SQLite实际的代码 diff 存文件系统。为什么不用 Redis 或者更重的方案因为这个场景的并发量根本用不上SQLite 足够而且零运维出问题直接看文件。任务表的结构大概是这样CREATE TABLE tasks ( id TEXT PRIMARY KEY, description TEXT, status TEXT, -- pending/running/done/failed depends_on TEXT, -- JSON 数组存依赖的任务 id read_files TEXT, -- JSON 数组 write_files TEXT, -- JSON 数组 artifact_path TEXT, -- 产物文件路径 created_at INTEGER, updated_at INTEGER );调度逻辑就是一个循环找出所有statuspending且依赖都done的任务按并行度上限取前 N 个标记为running分发给对应的 Agent。Agent 完成后更新状态。失败的任务标记failed并触发重试或人工介入。这个设计的好处是状态完全可观测。任何时候你都能查数据库知道每个任务卡在哪而不是面对一堆日志猜。我调试的时候80% 的问题看一眼任务表就定位到了。4.4 一次完整任务的执行记录拿我最近做的一个真实任务举例给一个 Flask 项目加 API 限流。Planner 拆出四个任务一是调研现有中间件结构二是实现限流装饰器三是给三个核心接口加上装饰器四是补测试。任务一和任务二可以并行任务三依赖任务二任务四依赖任务三。Runtime 先并行跑任务一和任务二。任务一是个只读任务Coder 读完代码输出一份结构说明。任务二产出限流装饰器的实现。两个都完成后Reviewer 分别审查任务二的装饰器被打回一次——原因是没处理 Redis 连接失败的情况。Coder 补上异常处理后通过。任务三依赖任务二串行执行。Coder 给三个接口加装饰器Reviewer 通过。任务四补测试Tester 跑了一遍发现一个边界用例失败——限流窗口边界上的计数不对。回传给 Coder改完再跑通过。整个流程跑了大概十二分钟中间打回两次。如果是我自己写估计要一个多小时而且大概率会漏掉那个边界用例。这就是 AI 团队的价值不是它写得比我好而是它不会像我一样在赶进度时跳过审查和测试。5. 常见问题与排查技巧实录5.1 Agent 卡死或无限循环怎么办这是最常见的问题。表现是某个任务一直running日志里 Agent 反复调用同一个工具或者反复输出相似内容。原因通常有三个一是任务描述太模糊Agent 不知道该做到什么程度算完成二是工具调用一直失败Agent 在重试三是 Agent 陷入了改一点、审查打回、再改一点的死循环。排查顺序先看任务描述再看工具调用日志最后看审查记录。我遇到的大部分卡死都是第一种——Planner 拆任务时描述太粗比如优化性能Coder 根本不知道优化到什么指标算完。解决办法是给 Planner 的 prompt 里强制要求每个任务必须有可验证的完成标准。如果是死循环我会设置一个最大重试次数比如同一个任务被打回超过 3 次就标记为failed并通知我人工介入。硬扛着让它自己绕出来往往浪费大量 token 还绕不出来。5.2 产物冲突与合并失败的处理多个 Coder 并行改代码合并冲突是必然的。我的处理策略分三层第一层是预防。前面说的基于文件依赖的编排已经能避免大部分冲突。写同一批文件的任务会被强制串行。第二层是检测。Integrator 合并前会做一次三方 diff如果发现冲突不直接合并而是把冲突信息结构化后回传给相关 Coder让它们各自调整。第三层是兜底。如果自动调整失败Integrator 会把冲突标记出来暂停流程等我人工处理。我一般不轻易让 AI 自动解决复杂冲突因为代码冲突背后往往是设计分歧AI 硬合出来的结果可能逻辑上就是错的。提示给每个 Coder 的产物打上任务 id 和时间戳合并时按时间戳排序能减少不少无谓的冲突。5.3 成本失控的预警与优化AI 团队跑起来之后token 消耗是单会话的好几倍因为每个角色都要读上下文、每个任务都要审查。我第一个月账单出来的时候吓了一跳。优化手段我试过几个有效的有这些上下文裁剪前面说的精准注入效果最明显直接砍掉一半以上消耗。审查分级不是所有产出都要全量审查。小改动走轻量审查只看 diff大改动才走全量审查。缓存复用项目结构、编码约定这类不变的内容缓存起来不重复注入。模型分级Planner 和 Reviewer 用强模型Coder 和 Tester 用性价比高的模型。实测下来质量没明显下降成本降了三成。我现在的做法是给每个任务设 token 预算超预算就告警。这样能及时发现异常任务而不是等到月底看账单。5.4 常见问题速查表现象可能原因排查动作解决方式任务一直 running描述模糊/工具失败/死循环看描述、工具日志、审查记录补完成标准/修工具/设重试上限合并冲突频繁并行任务写同一文件看任务依赖图强制串行/调整拆分粒度token 消耗异常上下文过大/重复注入看单任务 token 统计裁剪上下文/加缓存Agent 选错工具工具描述不清看工具调用记录优化 description/拆分 server产物基于过期文件上下文版本不一致校验文件 hash加版本校验/打回重做MCP 调用超时server 卡死/网络抖动看 server 健康状态加超时重试/健康检查6. 六篇之后的反思哪些设计经得起考验6.1 真正有用的三个设计回头看这六篇的实践我认为最有价值的设计有三个。第一是角色按工程阶段划分而不是按技术栈。这个决定让整个协作流程变得自然因为每个角色的职责和真实团队里的岗位一一对应你不需要发明新的协作模式直接复用已有的工程实践就行。第二是 MCP 工具层的标准化。把工具能力从 Agent 逻辑里剥离出来好处是工具可以独立演进、独立测试、独立替换。我后来换过好几次文件操作和测试框架的实现Agent 逻辑一行没改。第三是基于文件依赖的任务编排。这个设计直接决定了并行度和冲突率是整套系统能不能跑顺的关键。它不复杂但需要 Planner 拆任务时足够细致把读写集合标清楚。6.2 被现实打脸的三个想当然也有几个我一开始觉得很好、后来发现不行的设计。一是让 Agent 自己决定用什么工具。我一开始不给工具使用建议让 Agent 自由发挥。结果它经常用错工具或者用低效的方式完成任务。后来我在角色 prompt 里明确写了什么场景用什么工具准确率才上来。Agent 不是人它不会从经验里总结最佳实践你得直接告诉它。二是审查越严格越好。我一度把 Reviewer 的审查清单列了二十多条结果它每条都查小改动也要审半天而且经常因为一些无关紧要的风格问题打回。后来我把清单精简到八条核心项只查真正影响正确性和可维护性的问题效率和质量都上来了。三是并行度越高越快。前面提过我试过 8 个并行结果 MCP 被打爆、冲突爆炸。并行度是有上限的超过之后收益递减甚至为负。3 到 4 个是我实测的甜点。6.3 如果你现在想上手我的建议最后给几条实操建议都是我自己踩坑换来的。别一上来就追求全自动。我现在的流程里Planner 拆完任务我会人工过一遍Reviewer 打回超过两次我会看一眼。完全放手让 AI 跑出问题的概率远高于你想象。AI 团队是放大器不是替代品你的判断力仍然是核心。从一个小项目开始。别拿你最重要的项目练手。找个边缘的、出问题也不影响业务的模块把整套流程跑通再逐步扩大范围。把状态和日志做扎实。我前面强调 SQLite 和可观测性是因为调试 AI 团队比调试普通代码难得多——你看不到它的思路只能看它的输入输出。状态表、工具调用日志、审查记录这三样做扎实排查问题能省你一半时间。接受它会犯错。我现在的团队流程里打回重做是常态不是异常。关键不是让它一次做对而是让错误能被及时发现、快速修正。这个心态转变之后我用起来轻松多了。这套东西我还在持续迭代最近在试的是给 Reviewer 加一个历史问题库让它能参考过去打回过的案例。效果还在观察等跑一段时间再来写第七篇。