【Claude基础】多代理协作：Agent Teams 与编排模式

文章目录

- [1. 多代理协作的动机](#1. 多代理协作的动机)
- - [1.1 单代理的能力天花板](#1.1 单代理的能力天花板)
  - [1.2 专业化分工 vs 全能型代理](#1.2 专业化分工 vs 全能型代理)
  - [1.3 并行执行带来的效率提升](#1.3 并行执行带来的效率提升)
- [2. Agent Teams 并行审查模式](#2. Agent Teams 并行审查模式)
- - [2.1 架构：Team Lead + 多个专家代理](#2.1 架构：Team Lead + 多个专家代理)
  - [2.2 专家角色设计](#2.2 专家角色设计)
  - [2.3 Team Lead 的汇总与决策逻辑](#2.3 Team Lead 的汇总与决策逻辑)
- [PR 审查报告](#PR 审查报告)
- - 安全审查
  - 性能分析
  - 测试覆盖
  - 文档合规
  - 修复优先级
  - [2.4 运行流程](#2.4 运行流程)
- [3. /batch 大规模并行](#3. /batch 大规模并行)
- - [3.1 工作原理](#3.1 工作原理)
  - [3.2 适用场景](#3.2 适用场景)
  - [3.3 任务分割策略](#3.3 任务分割策略)
  - [3.4 结果汇总与冲突处理](#3.4 结果汇总与冲突处理)
- [4. isolation: worktree 实验隔离](#4. isolation: worktree 实验隔离)
- - [4.1 每个代理在独立 git 分支中工作](#4.1 每个代理在独立 git 分支中工作)
  - [4.2 完成后可审查或丢弃](#4.2 完成后可审查或丢弃)
  - [4.3 多个 worktree 代理并行的协调](#4.3 多个 worktree 代理并行的协调)
- [5. 事件驱动编排](#5. 事件驱动编排)
- - [5.1 TaskCompleted Hook --- 任务完成后触发后续](#5.1 TaskCompleted Hook — 任务完成后触发后续)
  - [5.2 TeammateIdle Hook --- 空闲代理接手新任务](#5.2 TeammateIdle Hook — 空闲代理接手新任务)
  - [5.3 构建 DAG 工作流](#5.3 构建 DAG 工作流)
  - [5.4 失败重试与降级策略](#5.4 失败重试与降级策略)
- [6. 后台代理](#6. 后台代理)
- - [6.1 background: true 非阻塞执行](#6.1 background: true 非阻塞执行)
  - [6.2 后台代理的状态监控](#6.2 后台代理的状态监控)
  - [6.3 结果收集与主线程合并](#6.3 结果收集与主线程合并)
- [7. 实战：构建一个多代理代码审查系统](#7. 实战：构建一个多代理代码审查系统)
- - [7.1 需求](#7.1 需求)
  - [7.2 代理定义文件](#7.2 代理定义文件)
  - [7.3 Hook 配置](#7.3 Hook 配置)
  - [7.4 触发方式](#7.4 触发方式)
- [8. 架构选型决策树](#8. 架构选型决策树)

1. 多代理协作的动机

1.1 单代理的能力天花板

上一篇讲了子代理，解决了上下文隔离和并行执行的问题。但子代理本质上还是"一个主脑 + 若干分身"的模式------主代理拆任务、派任务、收结果，所有决策权集中在一个地方。

这个模式在任务规模上去之后会撞墙。

想象一个场景：团队提交了一个 PR，需要做代码审查。审查不是一件事，而是一堆事：

安全审计：有没有 SQL 注入、XSS、敏感信息泄露？
性能分析：有没有 N+1 查询、不必要的内存分配、O(n²) 循环？
测试覆盖：新增代码的测试覆盖率够不够？有没有漏掉边界条件？
文档合规：API 变更有没有更新文档？Breaking changes 有没有标注？

让一个代理依次做这四件事，有两个问题。第一，它需要在同一个上下文窗口里装下安全知识库、性能分析规则、测试覆盖指标、文档规范------这些领域知识互相干扰。第二，串行执行意味着四倍时间。

子代理可以解决并行问题，但子代理是"通用分身"，没有专业化的角色定义。你需要的是一支各有专长的团队。

1.2 专业化分工 vs 全能型代理

工程领域有个基本原则：专用工具比万用工具好用。一把瑞士军刀什么都能干，但论切面包不如面包刀，论开瓶不如开瓶器。

代理也一样。一个"全能型"代理的系统提示词会很长，试图覆盖所有场景的指令最终会变成一堆相互矛盾的规则。而一个专注做安全审查的代理，提示词可以写得非常精确：只关注 OWASP Top 10，只用静态分析工具，输出格式统一为"漏洞等级 + 位置 + 修复建议"。

专业化带来的好处：

提示词更精准。2000 字的安全审查指令比 10000 字的"全面审查"指令效果好得多
工具集更小。安全代理只需要 Read、Grep、Bash（跑安全扫描工具），不需要 Write 权限
输出格式统一。每个专家代理输出固定格式的报告，方便汇总
可独立迭代。发现安全审查规则需要更新？改一个代理文件就行，不影响其他专家

1.3 并行执行带来的效率提升

假设四个审查任务各需要 3 分钟。串行执行 12 分钟，并行执行 3 分钟。当 PR 审查从"提交后等 15 分钟"变成"提交后 3 分钟就有结果"，整个团队的开发节奏会完全不一样。

这不是理论推演。Claude Code 的 Agent Teams 机制就是为这类场景设计的------多个专家代理并行工作，由一个 Team Lead 协调和汇总。

2. Agent Teams 并行审查模式

2.1 架构：Team Lead + 多个专家代理

Agent Teams 的基本架构很直观：

Team Lead 是一个特殊的代理，它的职责不是做具体审查，而是：

理解任务目标（比如"审查这个 PR"）
将任务分发给各个专家代理
等待所有专家返回结果
汇总分析，输出最终报告

每个专家代理有自己独立的上下文、工具集和提示词，专注做一件事。

2.2 专家角色设计

下面分别定义四个专家代理。先看安全审查员：

.claude/agents/security-reviewer.md：

markdown 复制代码

---
description: "安全审查专家，检测代码中的安全漏洞和风险"
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: claude-sonnet-4-20250514
---

你是一个资深安全审查员。你的任务是审查代码变更中的安全风险。

## 审查清单

1. **注入类漏洞**：SQL 注入、命令注入、LDAP 注入、XSS
2. **认证与授权**：硬编码凭证、缺少权限校验、会话管理缺陷
3. **敏感信息泄露**：日志中打印密码/token、错误信息暴露内部结构
4. **输入验证**：缺少类型检查、边界检查、格式验证
5. **依赖安全**：已知 CVE 的依赖版本

## 输出格式

对每个发现的问题，输出：

- **风险等级**：Critical / High / Medium / Low
- **文件位置**：文件路径 + 行号
- **问题描述**：一句话说明问题
- **修复建议**：具体怎么改

如果没发现问题，输出"未发现安全风险"。不要编造问题。

性能分析师 .claude/agents/performance-reviewer.md：

markdown 复制代码

---
description: "性能分析专家，检测代码中的性能问题和优化机会"
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: claude-sonnet-4-20250514
---

你是一个性能分析专家。专注于检测代码变更中的性能问题。

## 关注点

1. **数据库查询**：N+1 问题、缺少索引提示、全表扫描
2. **算法复杂度**：O(n²) 及以上的嵌套循环、可优化为 O(n log n) 的排序
3. **内存使用**：大数组一次性加载、缺少分页、未关闭的流/连接
4. **并发问题**：竞态条件、死锁风险、缺少适当的锁机制
5. **缓存机会**：重复计算、可缓存但未缓存的数据库查询

## 输出格式

- **影响程度**：High / Medium / Low
- **文件位置**：文件路径 + 行号
- **问题描述**：一句话说明
- **优化建议**：具体方案
- **预估改善**：定性描述（如"大数据量下响应时间可降低 50%"）

测试覆盖检查员和文档合规检查员的结构类似，不重复贴了。核心差异在于关注点和工具：测试代理会调用 Bash 跑覆盖率工具（如 pytest --cov、jest --coverage），文档代理主要用 Read 和 Grep 对比 API 接口变更与文档更新。

2.3 Team Lead 的汇总与决策逻辑

Team Lead 代理是整个团队的协调者：

.claude/agents/review-lead.md：

markdown 复制代码

---
description: "代码审查团队负责人，协调多个专家代理并汇总审查结果"
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - security-reviewer
  - performance-reviewer
  - test-coverage-reviewer
  - docs-compliance-reviewer
model: claude-opus-4-20250514
---

你是代码审查团队的负责人。收到 PR 审查请求后：

## 工作流程

1. 先用 `git diff` 了解变更范围和涉及的文件
2. 将审查任务**并行**分发给四个专家代理
3. 收集所有专家的报告
4. 综合分析，输出最终审查结论

## 汇总规则

- 任何专家报告了 Critical 级别问题 → 整体结论为 **Request Changes**
- 有 High 级别问题 → **Request Changes**，并说明具体需要修复的项
- 只有 Medium/Low 问题 → **Approve with Comments**
- 无问题 → **Approve**

## 输出格式

PR 审查报告

整体结论：[Approve / Approve with Comments / Request Changes]

安全审查

安全代理的报告摘要

性能分析

性能代理的报告摘要

测试覆盖

测试代理的报告摘要

文档合规

文档代理的报告摘要

修复优先级

$最紧急的问题$
$次紧急的问题$ ...

复制代码

注意 Team Lead 的 tools 列表里包含了四个专家代理的名字。这意味着 Team Lead 可以像调用工具一样调用这些代理------Claude Code 会自动处理代理的启动、通信和结果回传。

2.4 运行流程

实际使用的时候，你只需要对 Team Lead 说一句话：

复制代码

@review-lead 审查当前 PR 的所有变更

接下来会发生：

Team Lead 运行 git diff 获取变更文件列表
Team Lead 同时调用四个专家代理，把变更文件信息传给它们
四个专家代理在各自的上下文中并行工作
各专家完成后，结果自动返回给 Team Lead
Team Lead 汇总四份报告，按照预定义的规则生成最终结论

整个过程你只触发一次，剩下的全是自动的。

3. /batch 大规模并行

3.1 工作原理

Agent Teams 适合"多角度分析同一目标"的场景。但有另一类需求："对大量目标做同一种处理"。比如：

将 200 个组件从 Class Component 迁移到 Hooks
给项目里所有 REST 接口加上 OpenAPI 注释
批量修复某个 linting 规则的违规

这类任务用 /batch 命令。

/batch 的底层机制是：

将任务列表拆成多个子任务
为每个子任务创建一个独立的 git worktree
在每个 worktree 中启动一个代理，独立执行
所有代理完成后，汇总结果

关键点在于 git worktree。每个代理在自己的 worktree 里改代码，互相之间不会产生文件冲突。这跟多个人各自 clone 了一份代码然后各改各的是一个道理，只是 worktree 比完整 clone 轻量得多。

3.2 适用场景

/batch 最适合的场景有一个共同特征：任务之间相互独立。每个子任务不依赖其他子任务的结果，可以各自完成后再合并。

典型场景：

大规模重构 ：200 个文件需要把 moment.js 替换成 dayjs，每个文件的替换逻辑相似但细节不同
批量代码生成：根据 50 个数据模型定义自动生成 CRUD 接口
跨文件格式统一 ：把项目中所有的 console.log 替换为结构化日志
多语言翻译：将 i18n 资源文件同时翻译成 10 种语言

3.3 任务分割策略

怎么拆任务直接决定效率。三种常见策略：

按文件分割------最简单直接：

复制代码

/batch "将以下文件中的 moment() 调用替换为 dayjs()：{file_list}"

每个代理拿到一个文件列表的子集，各自处理。适合文件之间完全独立的场景。

按模块分割------保持模块内的一致性：

复制代码

/batch "重构以下模块的错误处理：auth模块、payment模块、notification模块"

每个代理处理一个完整模块。模块内的文件可能有依赖关系，放在一个代理里处理能保证一致性。

按功能分割------当不同文件需要不同处理逻辑时：

复制代码

/batch "任务1: 更新所有 Controller 的参数校验; 任务2: 更新所有 Service 的异常处理; 任务3: 更新所有 Repository 的连接池配置"

每个代理负责一类功能的修改，可能涉及多个文件，但处理逻辑一致。

3.4 结果汇总与冲突处理

/batch 完成后，每个 worktree 里的修改需要合并回主分支。这里有两种情况：

无冲突（大多数情况）：如果任务拆分合理------每个代理改不同的文件------合并就是简单的 fast-forward 或 clean merge。

有冲突 ：两个代理碰巧改了同一个文件（比如都往 index.ts 的 export 列表加了新内容）。这时候 Claude Code 会标记冲突，让你选择：

自动合并（让一个代理重新执行，基于另一个代理的结果）
手动解决
让 Team Lead 代理解决

实际操作中，通过合理的任务分割可以把冲突降到接近零。关键是确保每个子任务操作的文件范围不重叠。

4. isolation: worktree 实验隔离

4.1 每个代理在独立 git 分支中工作

在代理定义文件中设置 isolation: worktree，Claude Code 会为该代理创建一个独立的 git worktree：

markdown 复制代码

---
description: "实验性重构代理"
isolation: worktree
tools:
  - Read
  - Write
  - Edit
  - Bash
---

在独立分支中执行重构任务。完成后提交所有变更。

运行时发生的事情：

Claude Code 基于当前分支创建一个新分支（如 agent/refactor-experiment-a3f2）
创建一个指向该分支的 worktree 目录
代理在这个 worktree 里工作，所有文件修改都发生在这个隔离环境中
代理完成后，变更已经提交到新分支上
你可以审查这个分支，决定合并还是丢弃

4.2 完成后可审查或丢弃

worktree 隔离的核心价值是安全。代理的所有改动都在独立分支上，不会影响你的工作分支。

审查流程：

bash 复制代码

# 查看代理创建的分支
git log agent/refactor-experiment-a3f2

# 对比差异
git diff main..agent/refactor-experiment-a3f2

# 满意就合并
git merge agent/refactor-experiment-a3f2

# 不满意就删除
git branch -D agent/refactor-experiment-a3f2

这比"让 AI 直接改你的代码然后发现改坏了再 git stash/reset"安全得多。尤其是让代理做大范围重构的时候，worktree 隔离基本是必选项。

4.3 多个 worktree 代理并行的协调

可以同时启动多个 worktree 隔离的代理，每个在自己的分支上工作：

复制代码

代理 A → branch: agent/approach-a (用策略模式重构)
代理 B → branch: agent/approach-b (用责任链模式重构)
代理 C → branch: agent/approach-c (用事件驱动重构)

三个代理各自完成后，你可以对比三个分支的实现，挑最好的。这就像让三个工程师各自出方案，然后选最优解。

协调要点：

每个代理的 worktree 完全独立，不需要担心文件冲突
如果需要在代理之间共享信息（比如"代理 A 发现了一个 Bug，代理 B 也需要知道"），需要通过 Team Lead 中转
worktree 的创建和清理由 Claude Code 自动管理，你不需要手动操作 git worktree add/remove

5. 事件驱动编排

5.1 TaskCompleted Hook --- 任务完成后触发后续

Hooks（第 06 篇详细讲过）在多代理场景下变得更有用。最常用的是任务完成触发：

json 复制代码

{
  "hooks": {
    "TaskCompleted": [
      {
        "matcher": "security-review",
        "command": "node scripts/post-security-review.js"
      }
    ]
  }
}

当安全审查代理完成任务后，自动触发后续流程------比如将结果发送到 Slack、更新 Jira ticket、或者触发下一个代理。

这让你可以构建链式工作流：

复制代码

安全审查完成 → 触发性能分析 → 性能分析完成 → 触发测试检查 → 全部完成 → 发送通知

5.2 TeammateIdle Hook --- 空闲代理接手新任务

在 Agent Teams 模式下，各个专家代理的执行时间可能差异很大。安全审查可能 1 分钟就完了，性能分析需要 5 分钟。

TeammateIdle Hook 可以利用这个时间差：

json 复制代码

{
  "hooks": {
    "TeammateIdle": [
      {
        "command": "echo 'assign-next-task'"
      }
    ]
  }
}

安全代理做完自己的活之后，如果任务队列里还有待处理的工作（比如还有几个文件没人审查），空闲的代理可以接手。这是一种动态负载均衡。

5.3 构建 DAG 工作流

复杂的多代理流程往往不是简单的并行或串行，而是一个 DAG（有向无环图）。有些任务可以并行，有些必须等前置任务完成。

举个例子：

复制代码

         ┌──安全审查──┐
构建代码──┤            ├──生成报告──发送通知
         ├──性能分析──┤
         │            │
         └──测试覆盖──┘
                │
           代码格式化（依赖测试结果）

"构建代码"是第一步，必须先完成。然后安全审查、性能分析、测试覆盖可以并行。"代码格式化"依赖测试覆盖的结果（需要知道哪些文件有测试）。最终的报告生成需要等安全、性能、测试三个都完成。

用 Hooks 配置实现这个 DAG：

json 复制代码

{
  "hooks": {
    "TaskCompleted": [
      {
        "matcher": "build",
        "command": "claude-code agent start security-reviewer && claude-code agent start performance-reviewer && claude-code agent start test-coverage-reviewer"
      },
      {
        "matcher": "test-coverage-reviewer",
        "command": "claude-code agent start code-formatter"
      },
      {
        "matcher": "security-reviewer|performance-reviewer|code-formatter",
        "command": "node scripts/check-all-complete.js && claude-code agent start report-generator"
      }
    ]
  }
}

check-all-complete.js 负责检查所有前置任务是否都已完成。只有全部完成时才触发报告生成。

5.4 失败重试与降级策略

代理可能会失败------模型超时、工具执行出错、上下文溢出。多代理系统必须处理这些情况。

重试配置：

json 复制代码

{
  "hooks": {
    "TaskFailed": [
      {
        "matcher": ".*-reviewer",
        "command": "node scripts/retry-with-backoff.js --max-retries=3 --agent=$AGENT_NAME"
      }
    ]
  }
}

降级策略的思路：

重试：同一个代理重新执行，适合临时性错误（网络超时等）
降级：换用更小的模型重新执行（Opus 超时了换 Sonnet），或者缩小任务范围
跳过：标记该审查项为"未完成"，其他结果照常汇总。最终报告中注明哪些检查被跳过了
人工介入：发送通知让人来处理

一个简单的重试脚本逻辑：

javascript 复制代码

// scripts/retry-with-backoff.js
const maxRetries = parseInt(process.env.MAX_RETRIES || '3');
const agentName = process.env.AGENT_NAME;
let attempt = getAttemptCount(agentName);

if (attempt < maxRetries) {
  const delay = Math.pow(2, attempt) * 1000; // 指数退避
  setTimeout(() => {
    exec(`claude-code agent start ${agentName}`);
  }, delay);
  incrementAttemptCount(agentName);
} else {
  exec(`node scripts/notify-failure.js --agent=${agentName}`);
  markAsSkipped(agentName);
}

6. 后台代理

6.1 background: true 非阻塞执行

有些任务不需要你等结果。比如你让一个代理去跑完整的测试套件，这可能需要 10 分钟，你没必要干等着。

在代理定义中设置 background: true：

markdown 复制代码

---
description: "后台运行完整测试套件"
background: true
tools:
  - Read
  - Bash
---

运行项目的完整测试套件，收集覆盖率数据，生成报告。

或者在调用时指定后台运行：

复制代码

帮我在后台跑一下完整的测试套件，结果写到 test-report.md

后台代理启动后，控制立刻返回给你。你可以继续干别的事情------写代码、做其他审查、甚至启动更多的后台代理。

6.2 后台代理的状态监控

后台代理不是"放出去就不管了"。你可以随时查看状态：

复制代码

# 查看所有运行中的代理
/agents status

# 查看特定代理的进度
/agents status test-runner

状态信息包括：

当前执行阶段（如"正在运行 tests/unit/"）
已用时间
工具调用计数
最后一条日志

如果某个后台代理卡住了或者跑偏了，可以终止它：

复制代码

/agents stop test-runner

6.3 结果收集与主线程合并

后台代理完成后，结果的处理有几种方式：

写入文件 ：代理把结果写到指定文件中（如 test-report.md），你随时可以去看。

通知回调：通过 Hook 在代理完成时触发通知：

json 复制代码

{
  "hooks": {
    "TaskCompleted": [
      {
        "matcher": "background-test-runner",
        "command": "notify-send 'Test suite completed' || echo '\a'"
      }
    ]
  }
}

自动合并：如果后台代理在 worktree 里工作并产生了代码变更，完成后可以自动创建 PR 或合并到主分支。

实际使用中，我倾向于让后台代理把结果写入文件 + 发通知。这样既不会打断当前工作，又不会错过结果。

7. 实战：构建一个多代理代码审查系统

7.1 需求

构建一个自动化代码审查系统：

PR 提交后自动触发
三个专家（安全、性能、测试覆盖）并行审查
Team Lead 汇总结果
结果发送到 Slack

7.2 代理定义文件

第一个文件，安全审查代理 .claude/agents/sec-check.md：

markdown 复制代码

---
description: "安全审查专家"
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: claude-sonnet-4-20250514
---

审查 PR 变更中的安全风险。重点关注：

1. 用户输入是否经过验证和转义
2. 是否有硬编码的密钥、token、密码
3. SQL 查询是否使用参数化查询
4. 文件操作是否存在路径遍历风险
5. HTTP 响应是否设置了安全头

输出格式：JSON 数组，每个元素包含 severity、file、line、description、fix 字段。
无问题时输出空数组 []。

第二个文件，性能审查代理 .claude/agents/perf-check.md：

markdown 复制代码

---
description: "性能审查专家"
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: claude-sonnet-4-20250514
---

审查 PR 变更中的性能问题。重点关注：

1. 数据库查询效率（N+1、缺少索引、全表扫描）
2. 循环中的重复计算或 I/O 操作
3. 大数据量下的内存使用
4. 缺少缓存的重复请求
5. 可优化的算法复杂度

输出格式同安全审查：JSON 数组，字段为 severity、file、line、description、fix。

第三个文件，测试覆盖代理 .claude/agents/test-check.md：

markdown 复制代码

---
description: "测试覆盖审查专家"
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: claude-sonnet-4-20250514
---

审查 PR 新增/修改代码的测试覆盖情况。

1. 运行测试覆盖率工具，获取变更文件的覆盖率
2. 检查新增的公共方法是否有对应测试
3. 检查边界条件和异常路径是否有测试
4. 检查是否有只测试 happy path 的情况

输出格式：JSON 对象，包含 coverage_percent、uncovered_files（数组）、missing_tests（数组，每个元素有 file、method、reason 字段）。

第四个文件，Team Lead .claude/agents/review-team-lead.md：

markdown 复制代码

---
description: "代码审查团队负责人，协调安全/性能/测试三个审查专家"
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - sec-check
  - perf-check
  - test-check
model: claude-opus-4-20250514
---

你是代码审查的 Team Lead。

## 工作流程

1. 获取 PR 的变更文件列表：`git diff --name-only origin/main...HEAD`
2. **并行**启动三个专家代理，传入变更文件列表
3. 收集三份 JSON 格式的审查报告
4. 按以下规则汇总：

## 决策规则

- 存在 severity="critical" 的问题 → 结论为 BLOCK
- 存在 severity="high" 的问题 → 结论为 REQUEST_CHANGES
- 只有 medium/low 问题 → 结论为 APPROVE_WITH_COMMENTS
- 测试覆盖率低于 60% → 结论为 REQUEST_CHANGES
- 无问题且覆盖率 ≥ 80% → 结论为 APPROVE

## 输出

生成 Markdown 格式的审查报告，保存到 `.claude/review-report.md`。
同时输出一行摘要，格式为：`REVIEW_RESULT:<结论>|<问题总数>|<critical数>|<high数>`

7.3 Hook 配置

在项目的 .claude/settings.json 中配置 PR 审查触发：

json 复制代码

{
  "hooks": {
    "TaskCompleted": [
      {
        "matcher": "review-team-lead",
        "command": "bash .claude/scripts/post-review.sh"
      }
    ]
  }
}

通知脚本 .claude/scripts/post-review.sh：

bash 复制代码

#!/bin/bash

# 读取审查报告
REPORT=$(cat .claude/review-report.md)

# 解析审查结果摘要
RESULT_LINE=$(echo "$REPORT" | grep "REVIEW_RESULT:" | tail -1)
CONCLUSION=$(echo "$RESULT_LINE" | cut -d'|' -f1 | cut -d':' -f2)
TOTAL=$(echo "$RESULT_LINE" | cut -d'|' -f2)
CRITICAL=$(echo "$RESULT_LINE" | cut -d'|' -f3)
HIGH=$(echo "$RESULT_LINE" | cut -d'|' -f4)

# 根据结论设置颜色
case "$CONCLUSION" in
  "BLOCK") COLOR="#FF0000" ;;
  "REQUEST_CHANGES") COLOR="#FF9900" ;;
  "APPROVE_WITH_COMMENTS") COLOR="#FFFF00" ;;
  "APPROVE") COLOR="#00FF00" ;;
  *) COLOR="#808080" ;;
esac

# 发送 Slack 通知
curl -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d @- <<EOF
{
  "attachments": [
    {
      "color": "$COLOR",
      "title": "PR 审查完成：$CONCLUSION",
      "text": "发现 $TOTAL 个问题（$CRITICAL 个严重，$HIGH 个高危）",
      "fields": [
        {
          "title": "详细报告",
          "value": "查看 .claude/review-report.md",
          "short": true
        }
      ]
    }
  ]
}
EOF

# 如果是 BLOCK 或 REQUEST_CHANGES，在 PR 上添加 review comment
if [[ "$CONCLUSION" == "BLOCK" || "$CONCLUSION" == "REQUEST_CHANGES" ]]; then
  gh pr review --request-changes --body "$REPORT"
elif [[ "$CONCLUSION" == "APPROVE" ]]; then
  gh pr review --approve --body "自动审查通过。$REPORT"
else
  gh pr review --comment --body "$REPORT"
fi

7.4 触发方式

在 CI/CD 中配置（以 GitHub Actions 为例）：

yaml 复制代码

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Run AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
        run: |
          npx @anthropic-ai/claude-code --agent review-team-lead \
            --prompt "审查当前 PR 的所有变更" \
            --max-turns 30

整套系统的完整工作流：

开发者推送代码到 PR
GitHub Actions 触发
Claude Code 启动 review-team-lead 代理
Team Lead 并行启动三个专家代理
三个专家各自完成审查，返回 JSON 报告
Team Lead 汇总报告，生成 Markdown 文件
Hook 触发 post-review.sh 脚本
脚本将结果发到 Slack，并在 PR 上留下 review comment

从 PR 提交到审查完成，全程自动化，通常在 3-5 分钟内完成。

8. 架构选型决策树

最后整理一个决策框架，避免为了用多代理而用多代理：

复制代码

你的任务是什么？
│
├─ 简单的单一任务（改个 Bug、写个函数）
│  → 单代理就够了，不要折腾
│
├─ 需要多角度分析同一目标（代码审查、方案评估）
│  → Agent Teams
│  → 定义专家代理 + Team Lead
│  → 专家并行，Lead 汇总
│
├─ 需要对大量目标做相同处理（批量重构、批量生成）
│  → /batch
│  → 按文件/模块/功能分割任务
│  → worktree 隔离避免冲突
│
├─ 需要尝试多种方案然后选最优（架构重构、技术选型）
│  → worktree 隔离
│  → 多个代理各自实现一种方案
│  → 完成后对比选择
│
├─ 需要长时间运行的后台任务（完整测试、大规模分析）
│  → 后台代理（background: true）
│  → 结果写文件 + 通知回调
│
└─ 需要复杂的依赖关系和流程控制
   → 事件驱动编排
   → Hooks 构建 DAG 工作流
   → 失败重试 + 降级策略

几个原则：

不要过度设计。如果一个代理能搞定，别拆成三个。多代理引入了额外的协调成本、潜在的通信失败、更高的 token 消耗。只有当单代理确实不够用的时候才考虑多代理。

优先并行而非串行。如果多个任务之间没有依赖关系，就并行执行。串行编排只用于有明确先后依赖的场景。

隔离是默认选项。只要代理需要写文件，就考虑 worktree 隔离。直接在工作分支上让多个代理同时改代码，冲突几乎不可避免。

从小规模开始。先用两个代理验证流程，跑通了再扩展到更多。一上来就搞十个代理的 DAG 工作流，调试起来会很痛苦。

监控和日志不可少。多代理系统出了问题比单代理更难排查。确保每个代理的输出有日志，每个 Hook 的执行有记录。出问题的时候，你需要能追溯到是哪个代理在哪一步出的错。