10-Multi-Agent 实战：PM+架构师+开发+审查

Multi-Agent 实战：四个 Agent 协作完成一个项目

你让一个 Agent 既当 PM、又当架构师、还要写代码、还要自审——它的 Prompt 会越来越长，输出越来越差。Multi-Agent 的思路很简单：让每个 Agent 只做一件事，做到极致，然后像团队一样协作。这篇文章用真实的可运行代码，演示 PM + Architect + Coder + Reviewer 四个 Agent 如何通力完成一个项目。

单 Agent 的天花板

给单个 Agent 一个复杂任务试试：

“开发一个用户管理系统，支持注册、登录、查询用户信息”

它需要同时：

• 理解需求（PM 视角）
• 设计架构（架构师视角）
• 写代码实现（开发视角）
• 检查质量（Review 视角）

结果呢？Prompt 越来越长，上下文互相污染，逻辑越来越混乱。这是单 Agent 的三个天花板：

Multi-Agent 的答案：分工。

单 Agent: Multi-Agent: ┌──────────────────────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ 一个 Agent │ │ PM │→│Arch │→│Coder │→│Review│ │ 既当PM又当架构师 │ → │ 需求 │ │ 架构 │ │ 代码 │ │ 审查 │ │ 又写代码又自审 │ │ 拆解 │ │ 设计 │ │ 实现 │ │ 把关 │ └──────────────────────┘ └──────┘ └──────┘ └──────┘ └──┬───┘ ↑ │ └── 打回 ─┘

四个 Agent，四种职责

PM Agent —— 只做需求拆解

角色定位：技术项目经理 输入：用户自然语言需求 输出：结构化的任务列表（P0/P1/P2）+ 验收标准 核心约束：不设计架构，不写代码。只产出任务列表。

System Prompt 的关键指令：

"你是技术项目经理。你的唯一职责是将用户需求拆解为结构化的开发任务列表。 按优先级排序：P0（核心）、P1（重要）、P2（锦上添花）。 只拆解需求，不设计架构、不写代码。 如果需求不明确，标注【待澄清】但不自行假设。"

Architect Agent —— 只做架构设计

角色定位：系统架构师 输入：PM 的任务列表 输出：架构文档（技术选型 + 数据模型 + API 定义 + 代码结构） 核心约束：不写具体实现代码。严格基于 PM 的任务列表，不超范围。

Coder Agent —— 只写代码

角色定位：资深开发者 输入：架构文档 + 任务列表 输出：可运行的完整代码 核心约束：严格遵循架构设计。有疑问标注 [疑问]，但不自行修改架构。 如果 Reviewer 给了修改意见，基于意见修改。

Reviewer Agent —— 只审不写

角色定位：代码审查员 输入：需求 + 架构 + 代码 输出：审查决策（approved / revise）+ 评分 + 具体问题清单 核心约束：不自己改代码，只指出问题。 如果问题在架构层 → 退回 Architect 重新设计 如果问题在代码层 → 退回 Coder 修改

职责边界一览

State：Multi-Agent 的"项目交接单"

四个 Agent 怎么通信？不是直接互相发消息——它们都通过 State 交接。

State 是一个 TypedDict，每个 Agent 完成工作后把自己的产出写进去，下一个 Agent 从这里读。就像一个项目交接单：

classTeamState(TypedDict):messages:Annotated[list,add_messages]# 完整对话历史（追加）next_agent:str# Supervisor 决定下一个派谁requirement:str# 用户原始需求task_breakdown:str# PM 产出architecture:str# Architect 产出code:str# Coder 产出review_result:str# Reviewer: "approved" / "revise"review_feedback:str# Reviewer 修改意见back_to_architect:bool# 是否需要退回架构revision_count:int# 修改次数（防无限循环）

看一个完整的 State 演进过程：

初始： { requirement: "用户管理系统", task_breakdown: "", architecture: "", code: "" } PM 完成后： { ..., task_breakdown: "## 任务列表\n### P0\n1. 注册API (POST /register)...", ... } Architect 完成后： { ..., architecture: "## 技术选型\n- FastAPI\n- SQLite\n## 数据模型\n...", ... } Coder 完成后： { ..., code: "from fastapi import FastAPI\napp = FastAPI()\n...", ... } Reviewer 完成后： { ..., review_result: "approved", review_feedback: "代码质量良好" }

设计原则：按角色分区，渐进填充，空字段表示该阶段未执行。

Supervisor：动态调度的"项目经理"

有了四个 Agent 和一个共享 State，还需要一个调度者——Supervisor。它不是 PM Agent（那是需求拆解的角色），Supervisor 是一个状态机引擎，每一步根据 State 决定下一步派谁：

SUPERVISOR_SYSTEM="""你是项目经理（Supervisor），协调 4 个专家 Agent。 决策规则（按优先级）： 1. 无任务列表 → 派 pm 2. 有任务列表、无架构 → 派 architect 3. 有架构、无代码 → 派 coder 4. 有代码、未审查 → 派 reviewer 5. reviewer 要求修改且 revision_count < 3 → 派 coder（或 architect） 6. reviewer 通过 或 revision_count >= 3 → FINISH 输出 JSON: {"next": "pm"|"architect"|"coder"|"reviewer"|"FINISH"}"""

LangGraph 图结构：

┌──────────────┐ │ Supervisor │ │ (动态路由) │ └──────┬───────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ PM │ │Architect │ │ Coder │ │ 需求拆解 │ │ 架构设计 │ │ 代码实现 │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ └──────────────────┴──────────────────┤ │ ▼ ┌──────────┐ │ Reviewer │ │ 代码审查 │ └────┬─────┘ │ ┌─────────┼─────────┐ │ │ 通过 / >3次 打回修改 │ │ ▼ ▼ END Coder/Architect

每个 Agent 完成后都回到 Supervisor，Supervisor 重新评估 State，决定下一步。这比固定流水线的优势是：Reviewer 打回后可以自动回到 Coder，修改后再次审查，直到通过或达到上限。

一个完整的协作实录

用户需求: "开发一个用户管理系统，支持注册、登录、查询个人信息" ═══ Round 1 ═══ 🧭 Supervisor → pm（还没有任务列表） 📋 PM 产出: P0: 1. 用户注册(POST /register) 2. 用户登录(POST /login) 3. 查询信息(GET /me) P1: 4. JWT 认证 5. 输入校验 验收标准: 3 个 API 可运行，有基本错误处理 ═══ Round 2 ═══ 🧭 Supervisor → architect（有任务列表，无架构） 🏗️ Architect 产出: 框架: FastAPI | 存储: SQLite + SQLAlchemy | 认证: JWT 结构: router → service → model 三层 ═══ Round 3 ═══ 🧭 Supervisor → coder（有架构，无代码） 💻 Coder 产出: 完整 Python 代码 ~100 行: FastAPI app + User model + 三个端点 + JWT ═══ Round 4 ═══ 🧭 Supervisor → reviewer（有代码，未审查） 🔍 Reviewer 审查: 评分: 6/10 → revise 问题: register 端点密码未 hash，存在安全风险 登录逻辑缺少密码验证步骤 ═══ Round 5 ═══ 🧭 Supervisor → coder（打回修改，revision_count=0） 💻 Coder 修改: 添加 passlib 密码 hash + 登录验证逻辑 ═══ Round 6 ═══ 🧭 Supervisor → reviewer（修改后，重新审查） 🔍 Reviewer 审查: 评分: 9/10 → approved ✅ 反馈: 所有问题已修复，代码质量良好 ═══ Round 7 ═══ 🧭 Supervisor → FINISH ✅ 最终产出: 可运行的完整代码 + 架构文档 + 任务清单

这就是 Multi-Agent 的价值——不是更快，而是更好。每个角色专注自己的领域，互相审查、互相纠正。一个人既当裁判又当运动员出不了质量，但四个各司其职的专业 Agent 可以。

冲突解决：三层机制

Multi-Agent 必然会有冲突——Reviewer 觉得代码不行，Coder 觉得审查太苛刻，Architect 设计超范围了……怎么解决？

第一层：角色边界预防（90% 的冲突在此消除）

每个 Agent 的 System Prompt 明确定义"你只能做什么，不能做什么"：

PM: "只拆解需求。不涉及技术选型。" Arch: "严格基于 PM 的任务列表设计。有模糊标注【待澄清】，不要假设。" Coder: "严格遵循架构。有疑问标注 [疑问]，但不要自行修改架构。" Review: "只指出问题，不自己改代码。审查维度：需求覆盖、架构一致、代码质量、安全性。"

第二层：Reviewer 仲裁（9% 的冲突在此裁决）

Reviewer 是最终的质量把关者。它需要判断问题出在哪一层：

{"decision":"revise","back_to_architect":false,// false → 退回 Coder 修改"feedback":"密码未 hash，请添加 passlib"}// 如果是架构问题：{"decision":"revise","back_to_architect":true,// true → 退回 Architect 重新设计"feedback":"SQLite 不适合高并发场景，建议换 PostgreSQL"}

第三层：Stop-the-World（1% 的僵局强制解除）

如果修改次数达到上限（3 次），强制通过，终止循环。不能再改了，避免 Reviewer 和 Coder 无休止拉锯。

# Supervisor 决策中的硬编码保护ifstate["revision_count"]>=3:return"FINISH"# 强制结束，即使 reviewer 还不满意

构建图的核心代码

整个 Multi-Agent 系统用 LangGraph 的图来编排。核心代码非常简洁：

defbuild_team_graph():builder=StateGraph(TeamState)# 添加 5 个节点builder.add_node("supervisor",supervisor_node)builder.add_node("pm",pm_node)builder.add_node("architect",architect_node)builder.add_node("coder",coder_node)builder.add_node("reviewer",reviewer_node)# START → Supervisorbuilder.add_edge(START,"supervisor")# Supervisor → 条件路由到各 Agentbuilder.add_conditional_edges("supervisor",router,{"pm":"pm","architect":"architect","coder":"coder","reviewer":"reviewer","FINISH":END,})# 所有 Agent 完成后 → 回到 Supervisor（这是关键！）builder.add_edge("pm","supervisor")builder.add_edge("architect","supervisor")builder.add_edge("coder","supervisor")builder.add_edge("reviewer","supervisor")returnbuilder.compile()# 一次调用，跑完所有协作循环result=graph.invoke(initial_state)

注意最关键的一行：builder.add_edge("reviewer", "supervisor")——Reviewer 完成后回到 Supervisor，Supervisor 根据 revision_count 和 review_result 决定是 FINISH 还是继续循环。这就是 LangChain 管道做不到的事情。

设计决策：几个关键问题

问：为什么要分 Architect 和 Coder？

如果合并——LLM 容易跳过架构设计直接写代码，最后代码结构混乱。"架构设计"这个步骤需要独立的视角。

问：为什么 Reviewer 不能改代码？

保持审查者视角独立。“裁判不能下场踢球”——如果 Reviewer 自己改代码，它就不再是客观的审查者。

问：多少个 Agent 合适？

经验法则：Agent 数 = 项目中"需要不同 System Prompt 的角色数"。不要为了多而多。

常见陷阱与最佳实践

最佳实践：先跑通顺序流（PM→Arch→Coder→Review），再引入 Supervisor 动态路由。

总结

Multi-Agent 不是银弹，但它解决了一个真实的问题：LLM 在处理复杂任务时，单一视角是不够的。

四个核心设计决策：

1. 单一职责—— 每个 Agent 只做一件事，System Prompt 短而精准
2. 共享 State—— 不直接发消息，通过 State 交接，可追溯可调试
3. Supervisor 动态路由—— 不写死流程，用条件边让图自己决定下一步
4. 三层冲突解决—— 角色边界预防 → Reviewer 仲裁 → Stop-the-World 兜底

去 github.com/barryness/cc-ai-learning 的010-multi-agent-learning/跑python multi_agent_demo.py "你自己的需求"，亲眼看看四个 Agent 是怎么一轮轮协作直到 Reviewer 亮绿灯的。