多 Agent 协作流水线——从单打独斗到团队作战

暗黑小白

319人浏览 · 2026-06-29 16:25:26

暗黑小白 · 2026-06-29 16:25:26 发布

核心论点：单个 Agent 擅长写代码，但不会审查自己的代码、不会给自己写测试、不会从架构角度审视自己的设计。把编码任务拆成多个角色，让 Agent 各司其职，质量提升远超"多调几轮"。

单 Agent 的天花板

用 Craft 模式让 AI 写一个功能，它会很认真地写——但有些问题它绝对不会发现：

AI 写的代码：
  ✅ 功能正确——能跑
  ❌ 把所有逻辑写在一个 200 行函数里——但你项目的规范是 service 层拆分
  ❌ 没写测试——因为它以为"写完代码"就是完成任务
  ❌ 数据库查询 N+1——功能正确但性能有问题
  ❌ 异常处理不一致——有的吞异常，有的裸抛

这些问题不是 AI"不会"，而是单 Agent 模式下，没有角色负责检查这些问题。就像一个人写代码——他自己不会发现自己拼错变量名，需要 Code Review。

为什么不直接让一个 Agent 做完所有事？

看完上面的天花板，自然会问：把 5 个角色的职责全写到一个 Agent 的 prompt 里，不就解决了吗？

答案：不行。三个根本原因。

原因一：视角盲区无法消除

让一个 Agent 同时扮演架构师、coder、测试、审查员——等于让一个人同时当运动员和裁判。心理上不可能，AI 也一样。

实际表现：

写了 N+1 查询 → 同一个 Agent 扮演的"reviewer"视角大概率也发现不了，因为它刚从"coder"视角看过同一段代码
没写测试 → “test-generator"视角不会主动跳出来补，因为任务的主要目标是"实现功能”
把所有逻辑写进一个 500 行函数 → "architect"视角被"coder"视角压制——代码已经写出来了，它倾向于合理化现有实现

原因二：Prompt 冲突导致行为不可预测

5 个角色的约束是互相矛盾的：

角色	核心行为	冲突点
architecture-designer	不出代码，只出设计	和 coder"写代码"矛盾
python-coder	快速实现，基于现有组件扩展	和 reviewer"严格挑刺"矛盾
test-generator	专注边界和异常	和 coder"专注正常路径"矛盾
code-reviewer	挑刺，拒绝妥协	和所有角色都矛盾

塞在一起的结果是平庸——每个角色维度都做 60 分，没有一个是 90 分。就像一个五项全能运动员，每项都还行，但没一项能进决赛。

原因三：上下文污染

流水线每个阶段有独立上下文：

architecture-designer：需求文档 + 架构规范
        ↓ （只传设计文档，不传需求）
python-coder：设计文档 + 依赖文件
        ↓ （只传代码，不传设计意图）
code-reviewer：实现代码 + 规范

独立上下文的巧妙之处：reviewer 看不到设计意图，只能按客观标准审查。如果 reviewer 看到了"为什么这么设计"，就容易原谅实现偏差。

合并成一个 Agent 后，所有上下文混在一起——reviewer 看到了设计意图就开了"后门"，coder 看到了审查标准反而束手束脚写出过度防御的代码。

什么时候"单 Agent 全能"是合理的？

两种场景：

原型验证 / PoC——速度优先，质量其次。一个 Agent 快速出结果比走完整流水线更快
极小改动——改一行配置、加一个字段，不需要分工

这两种正好对应下文"用法 2：精简流水线"——不是所有情况都需要完整流水线，但所有情况也不需要一个 Agent 扮演所有角色。

多 Agent 流水线的设计思路

把编码过程拆成独立角色，每个角色只做自己擅长的事。关键不是"多调几次 AI"，而是上下文隔离——每个阶段只看到上一个阶段的输出，不携带上游信息：

阶段	输入	输出	上下文隔离的价值
architecture-designer	需求文档 + 架构规范	设计文档	不携带实现细节
python-coder	设计文档 + 依赖文件	实现代码	不携带设计争议和备选方案
test-generator	实现代码 + 验收标准	测试代码	不携带实现过程中的妥协
code-reviewer	实现代码 + 规范	审查报告	不携带"为什么这么设计"的解释
performance-optimizer	代码 + 性能数据	优化方案	不携带功能需求（只看性能）

这不是"多调几次 AI"的简单叠加，而是分工 + 上下文隔离带来的质量跃迁。

五个核心 Agent 的职责边界

你们项目已配置的 Agent（.codebuddy/agents/）：

除了这五个核心 Agent，还有 api-designer（API 接口设计）和 database-designer（数据库表结构设计）两个可选 Agent。它们通常插入在 architecture-designer 和 python-coder 之间，用于新模块的 API 契约和数据模型设计。详见 API 与数据库设计篇。

architecture-designer：出设计，不出代码

输入：功能需求
输出：模块划分、接口定义、数据流、调用关系
不做：写具体实现代码

什么时候调用：

新模块/新功能（不知道文件怎么拆）
涉及两个以上模块的改造（需要明确模块间契约）
技术选型（向量库选 Milvus 还是 Chroma？）

真实案例：退款确认功能——输入一句需求，architecture-designer 拆出 4 个模块（退款申请/订单验证/付款回调/状态同步），定义退款状态机（申请→审批→退款中→已完成/已拒绝）和各模块间异步消息契约。如果不先出设计，coder 大概率用一个 500 行的 refund_service.py 处理所有事——发邮件、调支付接口、更新订单状态全塞进去，后面加一个退款原因字段就崩。

python-coder：实现，不做决策

输入：设计文档 + 相关依赖文件（@ 引用）
输出：按设计实现的可运行代码
不做：自行决定模块拆分、技术选型、接口定义

关键约束：coder 必须拿到 design 之后再动手。如果直接丢需求给 coder——“写个 A/B 实验系统”——它会同时做设计和实现，质量不可控。

调用方式：关键是带上设计文档作为上下文——没有设计文档，coder 会同时做设计和实现，质量不可控。将 architecture-designer 输出的设计文档通过 @ 引用喂给 coder，让它只做填空。

test-generator：补测试，不改功能代码

输入：已实现的代码文件
输出：单元测试 + 集成测试（pytest 格式）
不做：修改功能代码（除非发现明显的边界 bug）

什么时候调用：

每个新模块写完时
每次重构后（确保行为不变）
CI 覆盖率低于目标值时

真实案例：

@ …/experiment_service.py
给 assign() 和 record() 写单元测试，覆盖：
- 正常分流（A/B 概率均等）
- 边界：同一 user 多次 assign 返回相同 variant
- 异常：指标记录时实验已关闭
- 并发：两个请求同时 assign

test-generator 经常能发现 coder 没处理的边界情况——比如 user_id 为 None、实验状态异常等。

code-reviewer：审查，不改代码。

输入：已实现的代码文件
输出：审查报告（问题分级 + 修改建议）
不做：自动修改代码

审查维度：

维度	检查什么	严重程度
代码规范	命名、类型注解、日志方式	低
设计模式	是否违反已有架构约定	中
安全漏洞	SQL 注入、未校验输入	高
性能问题	N+1 查询、无索引、大循环	中
复用问题	是否有重复实现已有组件	中
异常处理	吞异常、裸抛、不一致	高

为什么必须独立审查：coder 自己审查自己的代码，和你不找别人 Code Review 自己合并 PR 一样——心理盲区。同样的代码，换个 Agent 身份再看，能发现完全不同的问题。

performance-optimizer（可选）：专项优化

输入：代码+性能数据（慢查询日志、profile 结果、压测报告）
输出：优化方案 + 改动

只有性能出现问题时才调用。日常开发不需要走这个 Agent。

流水线的三种用法

用法 1：标准新功能（完整流水线）

1. architecture-designer → 出设计
2. 你审核设计
3. python-coder → 按设计实现
4. test-generator → 补测试
5. code-reviewer → 审查
6. 你修复审查发现的问题（或让 coder 修）

耗时：5-8 轮对话，适合中等以上功能。

用法 2：小改动（精简流水线）

1. python-coder → 修改 1-2 个文件
2. code-reviewer → 审查

耗时：2-3 轮对话，适合修 bug、加字段、小重构。

用法 3：问题驱动（反向流水线）

1. code-reviewer → 审查现有代码，给问题清单
2. 你选要修哪些
3. python-coder → 逐一修复
4. test-generator → 补回归测试

适合接手别人的代码或技术债清理。

Team 模式：并行协作

Team 模式是 CodeBuddy 的一种特殊运行模式，不同于 Ask/Craft/Plan 的对话模式。它适用于上面"三种用法"都搞不定的场景——当任务可以并行分解时，用 Team 模式让多个 Agent 实例同时工作，而不是串行跑完整流水线。

如果任务可以并行分解，用 CodeBuddy 的 Team 模式让多个 Agent 同时工作：

任务：同时改造 MCP Server 和 A2A 层的错误处理

Team 创建 → 分配：
  ├── python-coder-1：改造 mcp_server.py 的错误处理
  ├── python-coder-2：改造 a2a_routers.py 的错误处理
  └── code-reviewer：审查两者的改动（等 coder 完成后）

Team 模式的优点在于并行——两个 coder 同时改互不影响的文件，总耗时是单 Agent 串行的一半。

踩坑与解法：如果两个并行任务确实都碰了同一个文件（比如一个改 order_service.create() 的校验逻辑，另一个改它的支付流程），用 git worktree 给每个 Agent 一个独立的工作目录：

git worktree add ../agent-a main      # Agent A 的工作区
git worktree add ../agent-b main      # Agent B 的工作区

两个 Agent 各自在自己的 worktree 里改，互不干扰。改完后 git merge 回主分支——即使有冲突，也是在合并阶段统一处理，而不是两个 Agent 在同一个文件上互相覆盖。

worktree 是 Team 模式的安全垫，不是替代品。Team 模式负责「同时跑多个 Agent」，worktree 负责「让它们不互相踩脚」。

如何选择：Team 模式 vs 编排 Agent

判断标准很简单——看任务之间有没有共享的输出目标：

场景	用哪个	原因
同时改 `mcp_server.py` 和 `a2a_routers.py` 的错误处理	Team	两个文件互不依赖，改完各交各的
同时加「退款」和「优惠券叠加」两个功能	Team	功能独立，不碰同一段逻辑
实现「退款」功能（设计→编码→测试→审查）	编排	后一步依赖前一步的输出
改了 `order_service.py` 后要更新 `test_order.py`	编排	test 必须等 code 完才能写

一个判断捷径：如果两个任务可以给两个不同的人同时做且不互相等——用 Team。如果必须第一个人做完第二个人才能开始——用编排。

编排 Agent：让流水线自己跑

前面三种用法都是你手动调用每个 Agent——先调 architecture-designer，审核设计，再调 coder，再调 test-generator……每步都要你切换。

当你走熟了"用法 1"的标准流水线后，可以创建一个编排 Agent（orchestrator），它的唯一职责是按顺序调度子 Agent：

你：实现退款确认功能

编排 Agent：
  1. 调用 architecture-designer → 输出设计文档
  2. 展示设计文档，等你确认
  3. 调用 python-coder（带设计文档 + 依赖文件）
  4. 调用 test-generator（带实现代码）
  5. 调用 code-reviewer（带实现代码）
  6. 汇总审查报告，指出需要你修复的问题

编排 Agent 的价值不是省掉那几次手动调用，而是：

你不会漏步骤——比如写完代码忘了调 test-generator
上下文传递不出错——不用每次手动 @ 引用上一个 Agent 的输出
审核点自动插入——设计和最终审查这两个关键点，编排 Agent 会停下来等你确认

流水线的维护

Agent 定义文件本身也是一种 Rule——它告诉 AI 在以某个角色身份工作时应该遵守什么约束。所以它的维护和 03 篇讲的 Rules 维护是同一件事。

Agent 定义是 .codebuddy/agents/ 下的 markdown 文件，和 Rules 一样需要维护：

每个 Agent 定义里引用相关的 Rules（自动继承规范）
coder 型 Agent 必须声明"基于现有组件扩展"
reviewer 型 Agent 必须声明审查维度

什么时候需要更新 Agent 定义：

发现某类问题反复出现（比如 coder 又写了 N+1）→ 在 coder Agent 定义里加一条约束
项目规范更新（比如换了日志框架）→ 更新对应 Agent 引用的 Rules
某个 Agent 的输出质量下降 → 检查它的输入是否受控，必要时加「不做」声明

核心要点

单个 Agent 的能力有天花板——它不会审查自己、不会给自己写测试。 多 Agent 流水线用角色分工解决了这个问题。
不要把多个角色合并到一个 Agent 的 prompt 里。 视角盲区、Prompt 冲突、上下文污染会让每个角色都做不好，“全能"变"全不能”。
每个 Agent 的输入必须受控。 architecture-designer 只拿需求，coder 只拿设计文档，reviewer 只拿代码和规范。输入不受控，上下文隔离就失效了。
design → code → test → review 是标准流水线，但不是每次都全跑。 小改动用精简版，技术债用反向流水线。
Agent 定义需要持续维护——发现反复出现的问题，及时加到对应 Agent 的约束里。
Team 模式适用于并行任务——两个无依赖的改动可以同时跑 coder，省一半时间。