🤖 第 11 章：多代理协作与编排 ------ 从"单兵作战"到"集团军协同"
章节定位 ：这是个人开发者迈向系统架构师 的关键一步。当任务复杂度超过单个 AI 的上下文窗口或专业深度时，单一代理会显得力不从心。本章将教你如何将庞大的工程拆解，指挥一支由前端专家、后端大师、测试工程师组成的"AI 特工队"，通过精密的编排完成复杂系统构建。
🎯 学习目标
完成本章后，你将能够：
- ✅ 判断何时需要从单代理模式 切换到多代理模式（复杂度阈值分析）。
- ✅ 设计并配置角色化子代理（Frontend, Backend, QA），实现专业分工。
- ✅ 掌握主代理（Orchestrator）的编排策略：任务拆解、分发、合并与冲突解决。
- ✅ 了解如何使用 Agent SDK 编程化定义代理行为，构建高度定制化的自动化工作流。
- ✅ 建立多代理间的通信协议 与共享上下文机制，避免信息孤岛。
11.1 从单代理到多代理：为何以及何时需要分工
⚖️ 单代理的局限性
虽然 Claude Code 很强大，但在面对以下场景时会遇到瓶颈：
- 上下文爆炸：全栈项目涉及 HTML/CSS/JS/SQL/DevOps，单个会话的上下文窗口难以容纳所有细节，导致"遗忘"或"幻觉"。
- 角色冲突：让同一个 AI 既写快速迭代的原型代码，又做严谨的安全审计，往往顾此失彼。
- 并行效率低：单代理只能串行工作。修改后端接口后，必须等它写完才能开始改前端，无法并行推进。
- 自我审查盲区：自己写的代码自己查，很难发现逻辑漏洞（盲点）。
🚦 何时启动多代理？
| 场景特征 | 建议模式 | 理由 |
|---|---|---|
| 简单脚本/单文件修改 | 单代理 | overhead 小，响应快。 |
| 全栈新功能开发 (含 DB/API/UI) | 多代理 | 需前后端并行，且技术栈差异大。 |
| 大型重构 (如 Monolith 转 Microservices) | 多代理 | 需分模块独立攻坚，最后集成。 |
| 高安全要求 (金融/支付核心) | 多代理 | 需"开发者"与"审计员"角色分离，互相制衡。 |
| 复杂调试 (跨服务链路追踪) | 多代理 | 需不同领域的专家分别排查各自服务。 |
🏗️ 多代理架构模型
我们将采用 **Hub-and-Spoke **(中心辐射) 模型：
- **Orchestrator **(主代理)：项目经理。负责理解需求、拆解任务、分配给子代理、汇总结果、解决冲突。
- **Specialists **(子代理)：领域专家。只关注自己的职责范围（如只写 React 组件，或只写 SQL）。
- **Shared Memory **(共享记忆)：所有代理读写的项目上下文、API 定义文档、数据库 Schema。
11.2 子代理实战：为 Web 应用创建前端、后端、测试子代理
我们将通过配置不同的 System Prompts 和 Skills/MCP Tools 来塑造三个专用子代理。
(注：在实际 CLI 操作中，可以通过开启多个终端窗口运行不同配置的 claude 实例，或通过 Agent SDK 编程调用。此处以逻辑配置为例)
👨💻 子代理 A：前端专家 (Frontend Agent)
- 核心人设：UI/UX 设计师 + React/Vue 专家。
- System Prompt : "你是一名资深前端工程师。专注于组件化开发、响应式布局和用户体验。
- 技术栈：React 18, TailwindCSS, TypeScript。
- 约束：严禁直接操作 DOM，必须使用 Hooks。所有 API 调用必须通过
src/services/api.ts封装。 - 输入：后端提供的 API 接口定义 (OpenAPI/Swagger)。
- 输出：可运行的 UI 组件代码及 Storybook 故事。"
- 专属工具 ：
npm run dev(本地预览)lint:css(样式检查)mock-data-generator(生成前端 Mock 数据)
👨🔧 子代理 B：后端大师 (Backend Agent)
- 核心人设：系统架构师 + 数据库专家。
- System Prompt : "你是一名后端架构师。专注于高并发、数据一致性和安全性。
- 技术栈：Python FastAPI, PostgreSQL, Redis。
- 约束：所有数据库操作必须使用异步 ORM (SQLAlchemy)。必须包含输入验证 (Pydantic) 和错误处理。
- 输入：业务需求描述。
- 输出：RESTful API 代码、数据库迁移脚本 (Alembic)、API 文档。"
- 专属工具 ：
db-migrate(执行迁移)pytest(运行单元测试)security-scan(漏洞扫描)
🕵️ 子代理 C：测试工程师 (QA Agent)
- 核心人设：破坏性测试专家 + 自动化测试开发者。
- System Prompt : "你是一名挑剔的 QA 工程师。你的目标是找出代码中的 Bug 和边界情况。
- 技术栈：Playwright (E2E), Jest (Unit)。
- 约束：不编写业务逻辑代码，只编写测试用例和修复建议。
- 输入：前端组件代码 + 后端 API 定义。
- 输出：覆盖率报告、失败的测试用例、具体的修复 Patch。"
- 专属工具 ：
run-e2e-tests(浏览器自动化测试)coverage-report(生成覆盖率热力图)
11.3 主代理编排艺术：设计高效的多代理工作流
主代理（Orchestrator）是大脑。它的核心任务不是写代码，而是流程控制。
🔄 标准编排工作流 (The Orchestration Loop)
阶段 1：需求分析与拆解 (Decomposition)
用户指令 ："开发一个用户积分商城功能，包括积分查询、兑换商品、订单记录。"
主代理行动：
- 分析需求，识别出三个子任务：
- Task A (后端): 设计积分表、兑换逻辑 API。
- Task B (前端): 商城页面、兑换弹窗、订单列表。
- Task C (测试): 积分扣减一致性测试、并发兑换测试。
- 生成 API 契约草案 (作为前后端协作的桥梁)。
阶段 2：并行分发 (Dispatch)
主代理行动：
- 唤醒 后端代理："这是 API 契约，请实现积分查询和兑换接口，并更新 Swagger 文档。"
- 唤醒 前端代理 ："这是 API 契约，请基于此开发商城页面，使用 Mock 数据先行开发。"
(此时两个代理并行工作，互不阻塞)
阶段 3：集成与对齐 (Integration & Alignment)
主代理行动：
- 等待双方完成。
- 对比后端生成的真实 API 与前端使用的 Mock 定义。
- 冲突检测 ：如果发现字段名不一致（如
user_idvsuserId），主代理立即介入，指定统一标准，并要求相应代理修正。
阶段 4：质量验收 (Verification)
主代理行动：
- 唤醒 测试代理："前后端已集成，请运行 E2E 测试，重点检查积分扣减是否准确。"
- 收集测试报告。
- 若有失败，将错误日志分发给对应的开发代理（前端或后端）进行修复。
- 循环直到测试全部通过。
阶段 5：最终交付 (Delivery)
主代理行动：
- 汇总所有代码变更。
- 生成最终的 Commit Message 和部署说明。
- 向用户汇报："积分商城功能已开发完毕，测试通过率 100%。"
💡 关键技巧：共享上下文管理
- API 契约即真理 ：主代理维护一份实时的
api-contract.md。任何一方的修改必须先更新此文件，经主代理确认后，另一方才能同步。 - 状态看板 ：主代理维护一个
task-status.md，记录每个子任务的进度（Todo, In Progress, Blocked, Done），防止重复劳动。
11.4 使用 Agent SDK 编程化构建代理：进入更高级的定制化领域
对于极其复杂的流程，纯自然语言的"主代理"可能不够稳定。此时需要使用 Anthropic Agent SDK (或类似框架) 进行代码级编排。
🛠️ 为什么需要代码编排？
- 确定性控制：代码可以强制规定执行顺序、重试次数、超时处理。
- 结构化数据交换：代理间传递 JSON 对象而非自然语言，减少歧义。
- 外部系统集成：轻松连接 Jira, Slack, CI/CD 流水线。
🚀 实战示例：构建一个自动化的"功能工厂"
假设我们要用 Python 编写一个脚本，自动协调三个 AI 实例完成功能开发。
python
# orchestrator.py
import asyncio
from agent_sdk import Agent, Tool
# 定义子代理
frontend_agent = Agent(
name="FrontendDev",
system_prompt="你是 React 专家...",
tools=[Tool("npm_run"), Tool("lint")]
)
backend_agent = Agent(
name="BackendDev",
system_prompt="你是 FastAPI 专家...",
tools=[Tool("db_migrate"), Tool("pytest")]
)
qa_agent = Agent(
name="QAEngineer",
system_prompt="你是测试专家...",
tools=[Tool("run_e2e")]
)
async def develop_feature(feature_desc: str):
print(f"🚀 开始开发功能：{feature_desc}")
# 1. 规划阶段
plan = await frontend_agent.chat(f"基于需求 {feature_desc}，定义前后端接口契约。")
api_contract = extract_contract(plan)
# 2. 并行开发
print("⚙️ 前后端并行开发中...")
task_fe = asyncio.create_task(frontend_agent.chat(f"基于契约 {api_contract} 开发前端"))
task_be = asyncio.create_task(backend_agent.chat(f"基于契约 {api_contract} 开发后端"))
fe_result, be_result = await asyncio.gather(task_fe, task_be)
# 3. 集成与测试
print("🧪 运行自动化测试...")
test_report = await qa_agent.chat(f"集成已完成，请测试。前端：{fe_result}, 后端：{be_result}")
if "FAILED" in test_report:
print("❌ 测试失败，触发修复循环...")
# 这里可以加入自动修复逻辑，将错误反馈给对应代理
return await fix_and_retry(test_report, frontend_agent, backend_agent)
else:
print("✅ 功能开发成功！")
return {"status": "success", "report": test_report}
# 运行编排器
if __name__ == "__main__":
asyncio.run(develop_feature("用户积分兑换功能"))🔑 核心能力解析
- Asyncio 并发：利用 Python 的异步特性，让多个 Agent 同时工作，大幅缩短总耗时。
- 结构化输出解析 ：
extract_contract函数可以从 AI 的自然语言回复中提取标准的 JSON 接口定义，确保传递给下一个 Agent 的是机器可读的数据。 - 闭环反馈：测试失败自动触发修复流程，形成 DevOps 闭环。
🧪 动手练习：组建你的 AI 特种部队
练习 1：手动模拟多代理协作
- 打开三个终端窗口。
- 分别启动三个
claude会话，并通过/memory add或初始 Prompt 设定它们的角色（前端、后端、测试）。 - 你自己担任"主代理"：
- 在窗口 1 告诉后端："设计一个获取天气的 API"。
- 复制 API 定义到窗口 2，告诉前端："基于此 API 做一个展示页面"。
- 复制两边代码到窗口 3，告诉测试："找出潜在 Bug"。
- 体验信息在不同角色间流转的过程，记录遇到的沟通障碍（如字段名不一致）。
练习 2：编写简单的编排脚本
- 使用 Python (或 Node.js) 安装 Agent SDK。
- 编写一个脚本，定义两个 Agent：
- Agent A：负责生成一个随机故事的提纲。
- Agent B：负责根据提纲扩写成完整故事。
- 让脚本自动执行：调用 A -> 获取输出 -> 传给 B -> 输出最终结果。
- 进阶：让 B 评价故事质量，如果低于 80 分，自动让 A 重新生成提纲（循环）。
练习 3：设计 API 契约驱动工作流
- 创建一个共享文件
contract.md。 - 让"后端代理"先写入 API 定义。
- 编写一个检查脚本（或让主代理检查）：只有当
contract.md更新后，才允许"前端代理"开始工作。 - 模拟一次"后端修改了字段类型"的场景，观察前端代理如何反应并调整代码。
❓ 常见陷阱与解答 (FAQ)
| 问题 | 原因分析 | 解决方案 |
|---|---|---|
| 子代理各行其是 | 缺乏统一的"接口契约"，各自臆造数据结构。 | 强制实施 Contract-First 策略。主代理必须先锁定 API 定义，子代理才能动工。 |
| 死循环争论 | 前端怪后端接口不对，后端怪前端参数错了。 | 主代理必须拥有最终裁决权。当出现分歧，主代理应依据需求文档强行指定标准，禁止无休止辩论。 |
| 上下文不一致 | 子代理不知道其他代理的最新修改。 | 建立 Shared Memory 机制。每次子代理完成任务，必须将关键变更（如新字段、新路由）写入共享文档，供他人读取。 |
| 成本失控 | 多个 Agent 同时运行，Token 消耗翻倍。 | 限制子代理的上下文窗口；仅在必要时唤醒特定代理；使用较小的模型处理简单子任务。 |
📝 本章小结
- 分工产生效能：多代理模式通过角色专业化，解决了全栈开发的上下文瓶颈和质量盲区。
- 编排是核心：主代理（Orchestrator）的价值在于拆解、分发、对齐和验收，而非具体编码。
- 契约即法律：在多代理协作中，明确的 API 契约和共享文档是避免混乱的唯一基石。
- 代码化编排是未来：利用 Agent SDK 将工作流代码化，可实现高度自动化、可重试、可监控的生产级 AI 流水线。
🚀 下一步预告 ：
掌握了多代理协作后，我们将进入 第 12 章：命令行高级参考，深入挖掘 CLI 的底层参数、脚本化调用技巧以及在 CI/CD 流水线中的无缝集成，让你的 AI 工作流真正融入工程化体系！