第04章｜量体裁衣：从 Sub-Agents 到 Multi-Agent 的工程指南
学习目标：掌握多 Agent 系统的架构设计模式，学会根据任务特点选择合适的编排策略，构建可靠的生产级多智能体系统。
4.1 Multi-Agent 系统概述
从单兵到军团
Sub-Agent 是"一个助手"，Multi-Agent 是"一支团队"。工程化的关键在于：如何让这支团队高效协作。
单 Agent：
用户 → Claude → 结果
Multi-Agent 系统：
用户 → 协调者 Agent
↓
┌─────────┼─────────┐
↓ ↓ ↓
Agent A Agent B Agent C
（分析） （实现） （测试）
↓ ↓ ↓
└─────────┼─────────┘
↓
汇总结果 → 用户Multi-Agent 的核心价值
| 价值 | 说明 |
|---|---|
| 并行加速 | 多任务同时执行，总时间 ≈ 最长子任务时间 |
| 专业分工 | 每个 Agent 专注特定领域，质量更高 |
| 上下文隔离 | 子任务细节不污染主上下文 |
| 可扩展性 | 任务增加时，增加 Agent 而非扩大单个 Agent |
| 容错性 | 单个 Agent 失败不影响整体 |
4.2 四种编排模式
模式1：主从模式（Orchestrator-Worker）
最常见的模式，一个主 Agent 协调多个工作 Agent。
┌─────────────────────────────────────────────────────┐
│ 主从模式 │
│ │
│ ┌──────────────────┐ │
│ │ Orchestrator │ ← 接收用户任务 │
│ │ （协调者） │ ← 拆分任务 │
│ │ │ ← 汇总结果 │
│ └──────┬───────────┘ │
│ │ 派发任务 │
│ ┌───────────┼───────────┐ │
│ ↓ ↓ ↓ │
│ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │Worker│ │Worker│ │Worker│ ← 执行具体任务 │
│ │ A │ │ B │ │ C │ │
│ └──────┘ └──────┘ └──────┘ │
└─────────────────────────────────────────────────────┘适用场景：
-
任务可以明确拆分
-
子任务相对独立
-
需要统一汇总结果
实战案例：全栈功能开发
用户：为我们的电商系统添加"商品收藏"功能
Orchestrator 分析并派发：
Worker A（数据库层）：
任务：设计并创建 favorites 表，添加必要索引
输出：migration 文件路径Worker B（后端 API 层）：
任务：实现收藏/取消收藏/获取收藏列表 API
依赖：Worker A 完成后执行
输出：API 文件路径Worker C（前端层）：
任务：实现收藏按钮组件和收藏列表页面
依赖：Worker B 完成后执行
输出：组件文件路径Worker D（测试层）：
任务：为 API 编写集成测试
依赖：Worker B 完成后执行
输出：测试文件路径Orchestrator 汇总：
验证所有文件已创建
运行测试确认功能正常
生成 PR 描述
模式2：流水线模式（Pipeline）
任务按顺序流转，每个 Agent 处理上一个 Agent 的输出。
┌─────────────────────────────────────────────────────┐
│ 流水线模式 │
│ │
│ 输入 → [Agent A] → [Agent B] → [Agent C] → 输出 │
│ 分析需求 生成代码 审查代码 │
│ │
│ 每个 Agent 的输出是下一个 Agent 的输入 │
└─────────────────────────────────────────────────────┘适用场景：
-
任务有明确的处理阶段
-
每个阶段依赖上一阶段的结果
-
需要逐步精炼输出质量
实战案例：代码审查流水线
阶段1 - 需求分析 Agent：
输入：用户需求描述
处理：分析需求，生成技术规格文档
输出：tech_spec.md阶段2 - 代码生成 Agent：
输入：tech_spec.md
处理：根据规格生成代码
输出：src/ 下的代码文件阶段3 - 代码审查 Agent：
输入：生成的代码文件
处理：检查代码质量、安全性、规范性
输出：review_comments.md阶段4 - 修复 Agent：
输入：代码文件 + review_comments.md
处理：根据审查意见修复问题
输出：修复后的代码文件阶段5 - 测试 Agent：
输入：最终代码文件
处理：运行测试，验证功能
输出：test_report.md
模式3：并行扇出模式（Fan-Out）
一个任务同时分发给多个 Agent，收集所有结果后合并。
┌─────────────────────────────────────────────────────┐
│ 并行扇出模式 │
│ │
│ ┌──────────────┐ │
│ │ 分发 Agent │ │
│ └──────┬───────┘ │
│ ┌───────────┼───────────┐ │
│ ↓ ↓ ↓ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │Agent A │ │Agent B │ │Agent C │ │
│ │（方案1）│ │（方案2）│ │（方案3）│ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ └───────────┼───────────┘ │
│ ↓ │
│ ┌──────────────┐ │
│ │ 汇总 Agent │ ← 选择最优方案 │
│ └──────────────┘ │
└─────────────────────────────────────────────────────┘适用场景：
-
需要探索多种方案
-
对同一问题需要多角度分析
-
需要投票或共识机制
实战案例：多方案技术选型
用户：我们需要为项目选择一个消息队列方案
分发 Agent 同时派发3个子 Agent：
Agent A - 评估 RabbitMQ：
分析：性能、可靠性、运维复杂度、社区支持
输出：rabbitmq_evaluation.jsonAgent B - 评估 Kafka：
分析：性能、可靠性、运维复杂度、社区支持
输出：kafka_evaluation.jsonAgent C - 评估 Redis Streams：
分析：性能、可靠性、运维复杂度、社区支持
输出：redis_streams_evaluation.json汇总 Agent：
对比三个方案的评估结果
根据项目需求（高吞吐、低延迟、易运维）打分
推荐最优方案并说明理由
输出：tech_selection_report.md
模式4：反馈循环模式（Feedback Loop）
Agent 之间形成反馈循环，迭代优化直到满足质量标准。
┌─────────────────────────────────────────────────────┐
│ 反馈循环模式 │
│ │
│ ┌──────────┐ 生成 ┌──────────┐ │
│ │ 生成 │ ─────────→ │ 验证 │ │
│ │ Agent │ │ Agent │ │
│ │ │ ←───────── │ │ │
│ └──────────┘ 反馈 └──────────┘ │
│ │
│ 循环直到：验证通过 或 达到最大迭代次数 │
└─────────────────────────────────────────────────────┘适用场景：
-
需要高质量输出
-
有明确的验收标准
-
允许多次迭代
实战案例：测试驱动开发
迭代1：
生成 Agent：根据需求生成代码
验证 Agent：运行测试 → 3个测试失败
反馈：将失败的测试用例和错误信息返回给生成 Agent迭代2：
生成 Agent：根据反馈修复代码
验证 Agent：运行测试 → 1个测试失败
反馈：将剩余失败的测试返回迭代3：
生成 Agent：修复最后一个问题
验证 Agent：运行测试 → 全部通过 ✅
循环结束，输出最终代码
4.3 任务拆分策略
拆分原则
好的任务拆分应满足：
1. 独立性（Independence）
每个子任务尽量不依赖其他子任务的中间结果
2. 完整性（Completeness）
所有子任务合并后覆盖完整的原始任务
3. 明确性（Clarity）
每个子任务的边界清晰，不重叠
4. 可验证性（Verifiability）
每个子任务有明确的完成标准拆分维度
按功能模块拆分
大任务：重构整个项目的错误处理
拆分：
子任务A：重构 API 层的错误处理
子任务B：重构 Service 层的错误处理
子任务C：重构 Repository 层的错误处理
子任务D：更新错误处理文档按文件类型拆分
大任务：为项目添加完整的类型注解
拆分：
子任务A：为 models/ 下的文件添加类型注解
子任务B：为 services/ 下的文件添加类型注解
子任务C：为 api/ 下的文件添加类型注解
子任务D：运行 mypy 验证类型正确性按处理阶段拆分
大任务：从零实现用户认证系统
拆分（有依赖关系，串行执行）：
阶段1：设计数据模型
阶段2：实现数据访问层
阶段3：实现业务逻辑层
阶段4：实现 API 接口
阶段5：编写测试
阶段6：更新 API 文档4.4 Agent 间通信机制
通过文件传递信息
最简单可靠的通信方式：子 Agent 将结果写入文件，主 Agent 读取。
# 子 Agent A 的输出
写入文件：/tmp/agent_a_result.json
{
"status": "success",
"findings": [
{"file": "auth.py", "line": 42, "issue": "弱密码策略"},
{"file": "auth.py", "line": 87, "issue": "JWT 过期时间过长"}
],
"summary": "发现2个安全问题"
}
# 主 Agent 读取
读取文件：/tmp/agent_a_result.json
处理结果并汇总通过返回值传递信息
子 Agent 直接在任务完成时返回结构化数据：
主 Agent 派发任务时要求：
"完成分析后，以如下 JSON 格式返回结果：
{
'status': 'success' | 'failed',
'result': {...},
'error': '错误信息（如果失败）'
}"通过共享工作目录
多个 Agent 共享同一个工作目录，通过文件系统协作：
工作目录结构：
.claude-workspace/
├── tasks/
│ ├── task_001.json ← 主 Agent 写入任务
│ ├── task_002.json
│ └── task_003.json
├── results/
│ ├── result_001.json ← 子 Agent 写入结果
│ ├── result_002.json
│ └── result_003.json
└── status/
├── agent_a.status ← Agent 状态文件
├── agent_b.status
└── agent_c.status4.5 错误处理与容错设计
子 Agent 失败处理策略
策略1：重试（Retry）
子 Agent 失败 → 等待1秒 → 重新派发相同任务
适用：偶发性失败（网络问题、临时错误）
最大重试次数：3次
策略2：降级（Fallback）
子 Agent A 失败 → 改用更简单的方法完成任务
适用：有备选方案的场景
策略3：跳过（Skip）
子 Agent 失败 → 记录错误 → 继续其他任务
适用：非关键子任务
策略4：中止（Abort）
子 Agent 失败 → 停止所有任务 → 报告错误
适用：关键任务失败，继续无意义实战：带容错的多 Agent 系统
主 Agent 执行逻辑（伪代码）：
results = {}
errors = {}
# 并行派发任务
for task_id, task in tasks.items():
try:
result = spawn_agent(task, timeout=120)
results[task_id] = result
except TimeoutError:
# 超时：重试一次
try:
result = spawn_agent(task, timeout=180)
results[task_id] = result
except:
errors[task_id] = "超时失败"
except Exception as e:
errors[task_id] = str(e)
# 汇总
if errors:
print(f"警告：{len(errors)} 个子任务失败")
print(f"失败任务：{errors}")
print(f"成功完成：{len(results)} 个子任务")
generate_report(results, errors)4.6 性能优化
Token 成本优化
优化1：精简子 Agent 的上下文
❌ 给子 Agent 传递整个项目的所有信息
✅ 只传递完成任务所需的最小信息
优化2：合理设置并行度
❌ 同时派发100个子 Agent
✅ 控制并发数量（建议3-5个）
优化3：复用子 Agent 结果
❌ 多个子 Agent 重复读取同一文件
✅ 主 Agent 预先读取，通过任务描述传递内容
优化4：使用 Prompt Caching
✅ 相同的 System Prompt 在多个子 Agent 间共享缓存执行时间优化
优化1：识别关键路径
分析任务依赖图，找出最长的依赖链
优先执行关键路径上的任务
优化2：提前启动
不等所有准备工作完成，尽早启动可以开始的子任务
优化3：合理设置超时
为每个子 Agent 设置合理的超时时间
避免一个慢任务阻塞整个流程4.7 实战案例：完整的 Multi-Agent 开发流水线
需求
用户说："帮我实现一个完整的用户注册功能，包括后端 API、数据库迁移、单元测试和 API 文档。"
架构设计
┌─────────────────────────────────────────────────────────┐
│ 用户注册功能开发流水线 │
│ │
│ 用户输入 │
│ ↓ │
│ [Orchestrator] 分析需求，制定计划 │
│ ↓ │
│ 阶段1（串行）： │
│ [Agent-Schema] 设计数据模型和 API 规格 │
│ ↓ │
│ 阶段2（并行）： │
│ ┌──────────────┬──────────────┬──────────────┐ │
│ │[Agent-DB] │[Agent-API] │[Agent-Doc] │ │
│ │创建数据库迁移 │实现 API 接口 │生成 API 文档 │ │
│ └──────┬───────┴──────┬───────┴──────┬───────┘ │
│ └──────────────┼──────────────┘ │
│ ↓ │
│ 阶段3（串行）： │
│ [Agent-Test] 编写并运行单元测试 │
│ ↓ │
│ [Agent-Verify] 验证所有功能正常 │
│ ↓ │
│ [Orchestrator] 汇总结果，生成完成报告 │
└─────────────────────────────────────────────────────────┘各 Agent 任务描述
Agent-Schema（阶段1）：
任务：为用户注册功能设计数据模型和 API 规格
请完成：
1. 设计 User 数据模型（字段：id, email, password_hash,
created_at, is_active）
2. 设计注册 API 规格（请求/响应格式）
3. 将设计结果写入 docs/register_spec.json
输出格式：
{
"model": {...},
"api": {
"endpoint": "POST /api/v1/auth/register",
"request": {...},
"response": {...},
"errors": [...]
}
}Agent-DB（阶段2，并行）：
任务：根据 docs/register_spec.json 创建数据库迁移文件
请完成：
1. 读取 docs/register_spec.json 中的数据模型定义
2. 创建 Alembic 迁移文件
3. 确保包含必要的索引（email 字段唯一索引）
4. 将迁移文件路径写入 docs/register_spec.json 的
migration_file 字段Agent-API（阶段2，并行）：
任务：根据 docs/register_spec.json 实现注册 API
请完成：
1. 读取 docs/register_spec.json 中的 API 规格
2. 在 src/api/auth.py 中实现注册路由
3. 在 src/services/auth_service.py 中实现注册业务逻辑
4. 在 src/repositories/user_repository.py 中实现数据访问
5. 使用 bcrypt 哈希密码
6. 遵循项目三层架构规范Agent-Test（阶段3）：
任务：为注册功能编写单元测试
请完成：
1. 读取 src/services/auth_service.py
2. 为每个公共方法编写单元测试
3. Mock 所有外部依赖（数据库、邮件服务）
4. 测试正常流程和异常流程
5. 运行测试并确保全部通过
6. 将测试文件保存到 tests/unit/test_auth_service.py执行结果
✅ Agent-Schema：完成数据模型和 API 规格设计（耗时 45s）
✅ Agent-DB：创建迁移文件 migrations/20260621_add_users.py（耗时 30s）
✅ Agent-API：实现注册 API（耗时 60s）
✅ Agent-Doc：生成 API 文档 docs/api/register.md（耗时 25s）
✅ Agent-Test：编写并通过 12 个单元测试（耗时 50s）
✅ Agent-Verify：所有功能验证通过
总耗时：约 3 分钟（并行执行节省约 40% 时间）
生成文件：6 个
测试覆盖率：92%4.8 本章小结
| 核心概念 | 要点 |
|---|---|
| 四种编排模式 | 主从、流水线、并行扇出、反馈循环 |
| 任务拆分原则 | 独立性、完整性、明确性、可验证性 |
| 通信机制 | 文件传递、返回值、共享工作目录 |
| 容错设计 | 重试、降级、跳过、中止 |
| 性能优化 | 精简上下文、控制并发、复用结果 |
🧪 动手练习
练习1：设计一个 Multi-Agent 系统
为以下需求设计 Multi-Agent 架构：
需求：对一个 Node.js 项目进行全面的依赖安全审计，
检查所有 npm 包的已知漏洞，生成修复建议报告
请设计：
1. 需要哪些 Agent？
2. 每个 Agent 的职责是什么？
3. 执行顺序（串行/并行）？
4. Agent 间如何传递信息？练习2：实现简单的流水线
bash
# 创建一个两阶段流水线：
# 阶段1：分析代码，找出所有 TODO 注释
# 阶段2：为每个 TODO 生成实现建议
claude -p "
第一步：读取 src/ 目录下所有文件，找出所有 TODO 注释，
保存到 todos.json（格式：[{file, line, content}]）
第二步：读取 todos.json，为每个 TODO 生成具体的实现建议，
保存到 todo_suggestions.md
"⬅️ 上一章：第03章 - Sub-Agents 核心概念
➡️ 下一章：第05章 - 构建只读型安全审计子代理