第 16 课：多代理编排 — 并行、视角与隔离

所属阶段：第三阶段「工作流实战」（第 12-20 课） 前置条件：第 15 课（会话管理） 本课收获：能设计多 Agent 协作方案，理解并行与顺序的判断标准

---

一、本课概述

前面 15 课都在讲"一个 Agent 做一件事"。但现实中的复杂任务，往往需要多个 Agent 协作才能高效完成。

想象一个场景：你提交了一段代码，需要同时做安全审查、性能审查和类型检查。如果顺序执行，要等三倍时间。如果并行执行，三个 Agent 同时工作，只需等最慢的那个。

本课回答三个问题：

1. 什么时候并行，什么时候顺序？ --- 判断标准和决策树
2. 怎么编排多 Agent？ --- 四种编排模式
3. 如何避免 Agent 之间互相干扰？ --- 上下文隔离和 Git Worktree

学完本课，你将能设计合理的多 Agent 协作方案，避免常见的编排陷阱。

---

二、并行 vs 顺序 --- 判断标准

2.1 核心规则

无依赖 → 并行
有依赖 → 顺序

这条规则看似简单，但判断"是否有依赖"需要仔细分析。

2.2 判断依赖的三个问题

对于任意两个任务 A 和 B，问自己三个问题：

1. B 是否需要 A 的输出？ --- 如果是，顺序执行
2. A 和 B 是否修改同一个文件？ --- 如果是，顺序执行
3. B 的决策是否取决于 A 的结果？ --- 如果是，顺序执行

三个问题全部回答"否"，才能并行。

2.3 实例分析

场景一：代码提交后的审查（可并行）

安全审查 ──┐
            │
性能审查 ──┼── 互不依赖，可并行
            │
类型检查 ──┘

理由：
✓ 安全审查不需要性能审查的输出
✓ 三者都只读不写（不修改文件）
✓ 三者的判断互相独立

场景二：功能开发流程（必须顺序）

规划 → 实现 → 审查

理由：
✗ 实现需要规划的输出（实施步骤）
✗ 审查需要实现的输出（代码变更）
✗ 后续步骤的决策依赖前一步的结果

场景三：多语言构建检查（可并行）

Go build ────┐
              │
Rust build ──┼── 不同语言的构建互不影响
              │
Node build ──┘

场景四：前后端开发（部分并行）

API 设计（顺序 --- 先定接口）
    │
    ├── 前端开发 ──┐
    │              ├── 并行（依赖同一接口，但修改不同文件）
    └── 后端开发 ──┘
            │
        集成测试（顺序 --- 需要前后端都完成）

2.4 决策流程图

┌─────────────────────────┐
│  有 N 个任务需要完成      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  任意两个任务之间         │
│  是否存在数据依赖？       │
└────┬──────────┬─────────┘
     │          │
    Yes         No
     │          │
     ▼          ▼
┌──────────┐  ┌──────────────┐
│ 顺序执行  │  │是否修改同一文件？│
└──────────┘  └──┬───────┬───┘
                 │       │
                Yes      No
                 │       │
                 ▼       ▼
           ┌──────────┐ ┌──────────┐
           │ 顺序执行  │ │ 并行执行  │
           └──────────┘ └──────────┘

---

三、四种编排模式

ECC 提供了从简单到复杂的四种编排模式：

3.1 模式一：单 Agent

用户 → Agent → 输出

适用：简单任务，一个专家就够
示例：/code-review → code-reviewer Agent → 审查报告

这是最基础的模式，前面所有课程都在用。

3.2 模式二：并行 Agent（/multi-execute）

用户 → 编排层 ─┬→ Agent A ─┐
               ├→ Agent B ─┤→ 汇总 → 输出
               └→ Agent C ─┘

适用：多个独立任务可以同时做
命令：/multi-execute

实际调用方式：

# 并行执行三个审查任务
Launch 3 agents in parallel:
1. Agent 1: Security analysis of auth module
2. Agent 2: Performance review of cache system
3. Agent 3: Type checking of utilities

关键约束：并行的 Agent 必须互不依赖，否则结果不可靠。

3.3 模式三：多模型协作（/multi-plan）

用户 → 主 Agent (Claude) ─┬→ Codex 分析 ─┐
                           │              ├→ 融合 → 计划
                           └→ Gemini 分析 ┘

适用：需要多个 AI 模型的不同视角
命令：/multi-plan

/multi-plan 的核心协议：

• 语言协议：与工具/模型交互用英文，与用户交流用用户的语言
• 代码主权：外部模型（Codex/Gemini）没有文件写权限，所有修改由 Claude 执行
• 脏原型重构：外部模型的输出视为"脏原型"，必须重构为生产级代码
• 止损机制：当前阶段输出验证通过前不进入下一阶段

3.4 模式四：级联执行（/orchestrate）

用户 → 编排层 → Agent A → Agent B → Agent C → 输出
                   │         ▲
                   └─────────┘
                   A 的输出是 B 的输入

适用：复杂工作流，多个阶段有依赖
命令：/orchestrate
技能：dmux-workflows + autonomous-agent-harness

级联执行是最复杂的模式，适用于：

• 长时间运行的自动化任务
• 需要治理和调度的循环任务
• 多阶段有依赖的工作流

3.5 模式对比表

模式	复杂度	Agent 数	依赖关系	典型场景
单 Agent	低	1	无	简单任务
并行 Agent	中	2-4	无依赖	多维度审查
多模型协作	高	2-3 AI	无依赖	方案比较
级联执行	最高	多个	有依赖	完整工作流

---

四、多视角分析

4.1 五种角色

ECC 的 agents.md 推荐用 5 种角色审查同一段代码，每种角色关注不同维度：

角色	关注点	典型发现
事实审查员	代码是否正确实现了需求	逻辑错误、边界错误、遗漏需求
高级工程师	代码质量和可维护性	过度复杂、重复代码、命名不当
安全专家	安全漏洞和攻击面	注入风险、密钥泄露、权限绕过
一致性审查员	与项目现有模式的一致性	风格偏离、模式混用、约定违反
冗余检查员	不必要的代码和依赖	死代码、未使用的导入、冗余计算

4.2 为什么需要多视角

单一视角的审查有盲区。每个角色都有自己的"关注偏差"：

安全专家可能不关注代码可读性
高级工程师可能忽视安全漏洞
事实审查员可能忽视性能问题

5 种角色的审查加在一起，形成全方位的覆盖。

4.3 实战用法

# 对 auth.js 进行多视角审查
Launch 5 sub-agents with different perspectives:

1. Factual Reviewer:
   Check if auth.js correctly implements OAuth 2.0 PKCE flow
   per the RFC 7636 specification.

2. Senior Engineer:
   Review code quality: function sizes, naming, error handling,
   immutability patterns.

3. Security Expert:
   Analyze for token leakage, timing attacks, CSRF,
   improper token storage.

4. Consistency Reviewer:
   Compare with existing auth patterns in the codebase.
   Check if middleware and error handling match project conventions.

5. Redundancy Checker:
   Find unused imports, dead code paths, duplicate validation logic.

---

五、子代理上下文丢失问题

这是多 Agent 编排中最常见的失败原因。

5.1 问题本质

主代理（完整上下文）
  │
  ├── 知道项目结构
  ├── 知道讨论历史
  ├── 知道用户需求
  └── 知道前面的决策

子代理（空白上下文）
  │
  ├── 不知道项目结构  ← 问题！
  ├── 不知道讨论历史  ← 问题！
  ├── 不知道用户需求  ← 需要手动传递
  └── 不知道前面的决策 ← 问题！

主代理有完整的对话上下文，但子代理是从零开始的。如果你只给子代理一句话的指令，它会"盲人摸象" --- 基于不完整的信息做出决策。

5.2 常见失败模式

主代理："让子代理审查 auth 模块的安全性"
子代理：只读了 auth.js 就给出结论
        ← 没有读 middleware.js 中的权限检查
        ← 没有读 .env.example 中的密钥配置
        ← 结论不完整甚至错误

最危险的失败：主代理盲目接受子代理的不完整结果。

5.3 解决方案：迭代检索模式

主代理 → 子代理（初始指令 + 必要上下文）
              │
              ▼
         子代理执行
              │
              ▼
         主代理审查结果
              │
              ├── 结果完整且正确 → 接受
              │
              └── 结果不完整 → 追问（最多 3 次）
                    │
                    ▼
              "你漏看了 middleware.js，
               请补充审查这个文件的
               权限检查逻辑"
                    │
                    ▼
              子代理补充分析
                    │
                    ▼
              主代理再次审查
              ...（最多 3 次循环）

三条铁律：

1. 给足上下文 --- 给子代理的指令必须包含足够的项目上下文（相关文件路径、技术栈、已有决策）
2. 验证结果 --- 不要盲目接受子代理的输出，主代理必须审查完整性
3. 限制循环 --- 追问最多 3 次。如果 3 次仍不完整，说明任务拆分不当，需要重新设计

---

六、Git Worktree 隔离

6.1 问题：多 Agent 修改同一仓库

当多个 Agent 并行工作且都需要修改文件时，会出现冲突：

Agent A 修改 auth.js 的第 50 行
Agent B 修改 auth.js 的第 52 行
→ 冲突！

6.2 解决方案：Git Worktree

Git Worktree 允许同一个仓库创建多个独立的工作目录，每个目录有自己的文件系统但共享 Git 历史：

project/                    ← 主工作区（Agent A）
project-worktree-b/         ← 独立工作区（Agent B）
project-worktree-c/         ← 独立工作区（Agent C）

三个目录各自独立修改文件
互不干扰
最后通过 Git 合并

6.3 操作流程

# 1. 为每个 Agent 创建独立的 worktree
git worktree add ../project-agent-b -b feature/agent-b
git worktree add ../project-agent-c -b feature/agent-c

# 2. 每个 Agent 在自己的 worktree 中工作
# Agent A: 在 project/ 中工作
# Agent B: 在 project-agent-b/ 中工作
# Agent C: 在 project-agent-c/ 中工作

# 3. 工作完成后合并
git merge feature/agent-b
git merge feature/agent-c

# 4. 清理 worktree
git worktree remove ../project-agent-b
git worktree remove ../project-agent-c

6.4 并行数量建议

推荐最大并行数：3-4 个 Agent

理由：
- 每个 worktree 占用磁盘空间
- 每个 Agent 消耗上下文窗口
- 合并冲突随并行数指数增长
- 超过 4 个后管理成本 > 并行收益

并行数	管理难度	合并风险	建议
2	低	低	推荐
3	中	中	适合有经验者
4	高	高	最大推荐值
>4	极高	极高	不推荐

6.5 Worktree vs 分支

普通分支：
  切换分支需要 checkout → 文件系统变化 → Agent 上下文混乱

Git Worktree：
  每个 Agent 有独立目录 → 同时存在 → 不需要切换 → 互不干扰

Worktree 是并行 Agent 的最佳实践，因为它在文件系统级别实现了隔离。

---

七、编排设计模式

7.1 钻石模式

最常见的多 Agent 编排模式：

        ┌── Agent A ──┐
        │             │
输入 ───┼── Agent B ──┼── 汇总 → 输出
        │             │
        └── Agent C ──┘

前面一个分发节点、中间并行执行、后面一个汇总节点。适用于多维度审查、多方案评估。

7.2 管道模式

输入 → Agent A → Agent B → Agent C → 输出

每个 Agent 处理一个阶段，输出传给下一个。适用于有明确顺序的工作流（如 Plan → TDD → Review）。

7.3 混合模式

输入 → Plan Agent → ┬─ Dev Agent A ──┬─ Review Agent → 输出
                     │                │
                     └─ Dev Agent B ──┘

先顺序（规划），再并行（开发），再顺序（审查）。这是现实中最常见的模式。

---

八、本课练习

练习 1：并行判断（10 分钟）

判断以下 5 组任务能否并行执行，说明理由：

1. 审查 CSS 样式 + 审查 API 安全性
2. 修改数据库 Schema + 修改 ORM 模型
3. 为 Go 模块写测试 + 为 Python 模块写测试
4. 重构函数 A + 重构调用函数 A 的函数 B
5. 翻译中文文档 + 翻译日文文档

练习 2：设计编排方案（20 分钟）

设计以下 3 个场景的多 Agent 编排方案。要求画出编排图并说明：

• 哪些步骤可以并行
• 为什么不能改为顺序执行
• 每个 Agent 的模型选择

场景 A：一个电商网站需要同时审查前端（React）、后端（Node.js）和数据库（PostgreSQL）的代码变更

场景 B：一个开源库发布新版本，需要同时更新 npm/PyPI/crates.io 的发布文件、更新 CHANGELOG、更新文档

场景 C：一个安全事件响应，需要同时扫描所有微服务的密钥泄露、检查所有 API 端点的认证、审计所有数据库的访问日志

练习 3：子代理指令设计（15 分钟）

为以下子代理任务设计指令。要求指令中包含足够的上下文信息，避免子代理上下文丢失：

任务 ：让一个子代理审查 src/auth/oauth.js 的安全性

写出你会传给子代理的完整指令（不只是"审查这个文件的安全性"）。

练习 4（选做）：Git Worktree 实践

在一个测试仓库中：

1. 创建两个 Worktree
2. 在每个 Worktree 中修改不同的文件
3. 合并两个 Worktree 的变更
4. 清理 Worktree

记录整个过程和遇到的问题。

---

九、本课小结

你应该记住的	内容
并行判断标准	无数据依赖 + 不修改同一文件 + 决策独立 → 并行
四种编排模式	单 Agent、并行 Agent、多模型协作、级联执行
多视角分析	5 种角色：事实审查、高级工程师、安全专家、一致性、冗余
上下文丢失	子代理无上下文 → 必须手动传递 + 迭代验证（最多 3 次）
Git Worktree	每个 Agent 独立工作区，推荐最大 3-4 个并行
最危险的失败	盲目接受子代理的不完整结果

---

十、下节预告

第 17 课：Hook 事件链 --- 自动化的骨架

多 Agent 编排是手动触发的协作，但 ECC 还有一种自动触发的协作机制 --- Hook 事件链。下节课我们将深入 7 种 Hook 事件类型，理解 PreToolUse / PostToolUse / SessionStart / SessionEnd / PreCompact / Stop 各自的触发时机和实际用途。

预习建议 ：阅读 rules/common/hooks.md，并查看 .claude/settings.json 中的 Hook 配置。