专题 76：Agent 设计模式地图

一句话导读：这不是新增一个功能 step，而是把 Google Cloud 的 Agent 设计模式，逐一落到我们的 claude-learn 教学版和真实 Claude Code 源码上，搞清楚哪些我们已经实现了骨架，哪些只实现了雏形，哪些是生产版才有的纵深。

---

一、这篇文章在讲什么

前面我们读了一篇中文整理：《Agent 选型不用愁——Google 官方 12 种设计模式指南》。它的来源是 Google Cloud Architecture Center 的文档 Choose a design pattern for your agentic AI system (opens new window)，核心问题是：

我的 Agent 系统，到底该用哪种设计模式？

这篇专题做三件事：

1. 用人话解释 12 种 Agent 设计模式。
2. 对照我们自己的 claude-learn：哪些 step 实现了这些模式。
3. 对照真实 Claude Code 源码：生产版是怎么把这些模式做扎实的。

先给结论：

claude-learn 的主线：
  单 Agent
  + ReAct 工具循环
  + Human-in-the-Loop 权限
  + TodoWrite 任务追踪
  + 简化子 Agent / AgentBatch

Claude Code 的主线：
  单 Agent + ReAct 生产级状态机
  + 权限 / compact / fallback / stop hook / token continuation
  + TodoWrite / TaskUpdate
  + AgentTool / verification agent
  + coordinator / swarm / bridge / MCP

所以我们不是没实现这些模式，而是实现了教学骨架；Claude Code 实现的是生产级 runtime。

---

二、先分清：这些模式不是互斥的

很多人第一次看 ReAct、Loop、Iterative Refinement 会困惑：

这不都是边想边做边改吗？

对，它们确实经常叠在一起。但它们关注的问题不同：

模式	关注点	一句话
ReAct	下一步怎么决策	想一步、调工具、看结果、再想
Loop	怎么重复、什么时候停	重复执行，直到满足退出条件
Iterative Refinement	结果怎么变好	每轮根据反馈改进产物
Review & Critique	谁来挑错	生成者做，审查者砍

放在一次修 bug 任务里：

Loop:
  最多跑 N 轮

ReAct:
  每轮决定 Read / Grep / Edit / Bash 哪个工具该用

Iterative Refinement:
  根据测试失败继续修，让代码越来越接近正确

Review & Critique:
  最后拉一个 verification agent 独立验证

我们的 claude-learn/step75/QueryEngine.ts 用一个循环托住前三者：

for (let round = 0; round < maxRounds; round++) {
  const result = yield* streamTurn(...)

  this.messages.push(assistantMsg(result.contentBlocks))

  if (result.toolCalls.length === 0) return

  // 执行工具
  // 把 tool_result 放回 messages
}

这段从不同角度看：

• 叫 ReAct：因为模型每轮决定 Action，工具结果作为 Observation。
• 叫 Loop：因为它有 maxRounds 退出上限。
• 叫 Iterative Refinement：当任务是写代码、跑测试、修错误时，每轮都在改进产物。

---

三、12 种模式总览

#	模式	是什么	我们的代码	Claude Code 源码
1	单 Agent	一个模型 + 一组工具 + 一段系统提示词	step17 起，step30 引擎化	src/QueryEngine.ts、src/query.ts、src/tools.ts
2	顺序模式	A 输出给 B，再给 C	部分由 commands / skills / 主流程承担	slash commands、固定工作流、部分 tool prompt
3	并行模式	多个独立任务同时跑	step18、step39 AgentBatch	toolOrchestration.ts、StreamingToolExecutor.ts
4	Loop	重复直到退出条件	maxRounds、budget	maxTurns、transition、token continuation
5	Review & Critique	生成者 + 审查者	有 AgentTool 基础，未强制闭环	built-in verification agent
6	Iterative Refinement	根据反馈反复改进	QueryEngine + TodoWrite + 测试输出	TodoWrite / TaskUpdate + verifier nudge
7	Coordinator	中央 Agent 分派任务	AgentBatch 雏形	src/coordinator/
8	Hierarchical	多层任务分解	未完整实现	coordinator + AgentTool + Task 工具可组合
9	Swarm	多 Agent 团队互相通信	未完整实现	src/utils/swarm/、Team 工具
10	ReAct	Thought / Action / Observation	step17 核心	query.ts 主循环
11	Human-in-the-Loop	高风险动作等人批准	step19、step57、step67	useCanUseTool、permissions、permission UI
12	自定义逻辑	自己写编排和分支	commands、skills、plugins	commands、skills、plugins、MCP

---

四、模式 1：单 Agent

单 Agent 是最重要的起点。它不是“只能聊天”，而是：

一个主模型
  + 一套工具
  + 一份系统提示词
  + 一个消息历史
  + 一个工具调用循环

在我们项目里，单 Agent 从 step17 开始成型：

• step11：定义 Tool 接口和注册表
• step12-16：Bash / Read / Write / Glob / Grep
• step17：模型自动发起 tool call
• step30：抽出 QueryEngine

真实 Claude Code 里，单 Agent 的入口更重：

• src/QueryEngine.ts 管 conversation 生命周期、SDK 消息、状态持久化、权限 denial、memory、cost。
• src/query.ts 管真正的模型请求循环。
• src/tools.ts 组装可用工具池。

关键点：单 Agent 不是低级模式，它是地基。 Claude Code 的大多数日常能力，都是这个主 Agent 通过 ReAct 工具循环完成的。

---

五、模式 10：ReAct

ReAct 是 Claude Code 的心跳。

Thought:
  我需要知道什么？

Action:
  调用 Read / Grep / Bash / Edit / TodoWrite

Observation:
  工具结果回到上下文

Thought:
  基于结果决定下一步

我们的实现非常直观：

const result = yield* streamTurn(...)
this.messages.push(assistantMsg(result.contentBlocks))

if (result.toolCalls.length === 0) return

// 执行工具
this.messages.push(toolResultMsg(resultBlocks))

Claude Code 的实现也是这个形状，但多了生产细节：

• 支持模型流式输出时提前执行工具：StreamingToolExecutor
• 支持工具结果 summary：generateToolUseSummary
• 支持工具结果预算裁剪：applyToolResultBudget
• 支持工具执行期间用户中断
• 支持工具缺失时补 synthetic tool_result

也就是说，我们实现了 ReAct 的语义闭环；Claude Code 实现了 ReAct 的工程闭环。

---

六、模式 4：Loop

Loop 不是“模型聪明”，而是“控制结构可靠”。

我们这里的 Loop 很简单：

const maxRounds = this.opts.maxRounds ?? 25

for (let round = 0; round < maxRounds; round++) {
  ...
}

yield { type: "max_rounds", limit: maxRounds }

它解决两个问题：

1. 多步工具调用可以继续跑。
2. 如果模型一直调工具不收尾，不会无限烧钱。

Claude Code 的 Loop 更像状态机。它不只是 next turn，还会记录为什么继续：

next_turn
reactive_compact_retry
max_output_tokens_escalate
token_budget_continuation
stop_hook_blocking
collapse_drain_retry

这就是生产版和教学版的差异：
教学版只回答“循环几次”；生产版还要回答“为什么继续、怎么恢复、这次继续会不会污染上下文”。

---

七、模式 6：Iterative Refinement

迭代优化不是一个类，而是一种行为：

生成一个版本
检查问题
根据反馈修改
再检查
再修改
直到达标

在编码 Agent 里，它最常见：

写补丁
跑测试
测试失败
读错误
修补丁
再跑测试
通过
总结

我们的实现靠三样东西：

1. QueryEngine 多轮工具循环。
2. 工具结果回填到 messages。
3. TodoWrite 把任务状态显式化。

claude-learn/step75/tools/todo.ts 里，TodoWrite 要求模型传完整 todo 数组，并保持一个 in_progress：

[ ] 定位问题
[ ] 修改代码
[ ] 运行测试
[ ] 根据测试结果继续修

Claude Code 的 TodoWriteTool 更进一步：当 3 个以上任务全部完成，但没有 verification 任务时，它可能给模型一个 nudge：

你刚完成了 3+ 个任务，但没有验证步骤。
最终总结前，先 spawn verification agent。

这点我们没有实现。我们只是让模型“能追踪迭代”；Claude Code 会在关键收尾时“推它去验证”。

---

八、模式 5：Review & Critique

Review & Critique 解决的是：主 Agent 容易自我感觉良好。

典型结构：

Implementer:
  写代码、改文件、跑测试

Reviewer / Verifier:
  不改文件，只验证，专门找问题

Main Agent:
  根据 verifier 的 FAIL/PARTIAL/PASS 决定是否继续修

Claude Code 里有内置 verification agent。它的提示词非常强硬：

• 不能修改项目文件
• 必须运行命令
• 必须提供实际输出
• 必须以 VERDICT: PASS / FAIL / PARTIAL 结束
• 要做 adversarial probe，不只是 happy path

这就是 Review & Critique 的生产版。

我们有什么？

• step38：AgentTool，可以 fork 子 QueryEngine。
• step39：AgentBatch，可以并发跑多个子任务。

但我们没有：

• 内置 verification 专用 agent。
• 禁止 reviewer 修改项目的工具白名单。
• Todo 完成后自动提醒调用 verifier。
• verifier verdict 驱动主 Agent 继续修。

所以我们目前是“有搭建 reviewer 的基础设施”，还不是完整 Review & Critique 模式。

---

九、模式 3：并行模式

并行模式处理的是独立子任务：

任务 A：分析情感
任务 B：提取关键词
任务 C：判断紧急程度
任务 D：分类

并行执行，最后汇总

我们有两层并行：

第一层是 step18：同一轮多个工具调用用 Promise.all 跑。
第二层是 step39：AgentBatch 做 fan-out + 汇总。

但真实 Claude Code 更谨慎。它不会粗暴地把所有工具都 Promise.all：

• toolOrchestration.ts 会判断工具是否 concurrency-safe。
• 只读工具可以并行。
• 非只读工具串行。
• StreamingToolExecutor 可以在 tool_use 流出来时就开始执行。
• Bash 出错时，可以取消兄弟 Bash 工具，避免无意义执行。

这就是一个重要原则：

并行不是越多越好。生产级并行必须知道哪些动作可以安全并发，哪些必须串行。

我们的实现是“并行语义演示”；Claude Code 是“并行调度器”。

---

十、模式 2：顺序模式

顺序模式最朴素：

A -> B -> C

如果流程固定，不应该让模型自由发挥。

比如：

读取配置
校验 schema
生成报告
写入文件

这类任务在我们项目里更多体现在 commands、skills、固定工具逻辑，而不是 QueryEngine 自己。比如 step35 的 command registry、step41 的 skills，都可以承载固定流程。

Claude Code 里也类似：大量 slash command、hook、skill、workflow 不是让模型每次重新发明流程，而是把固定工程流程写进代码或提示文件。

这点很重要：

能硬编码的稳定流程，不要交给模型编排。

---

十一、模式 7：Coordinator

Coordinator 是“中央调度者”：

用户给大任务
Coordinator 判断任务类型
分派给不同专业 Agent
收集结果
综合输出

我们 step39 的 AgentBatch 只像一个简化 fan-out，不是真正 coordinator。它不会动态判断谁该做什么，只是执行模型传进来的任务数组。

Claude Code 有明确的 src/coordinator/。里面的 coordinator prompt 会告诉主 Agent：

• 你是 coordinator
• 你负责拆任务、派 worker
• worker 做具体执行
• 你负责综合和决策

这比 AgentBatch 高一层：
AgentBatch 是“工具级并发”；Coordinator 是“角色级调度”。

---

十二、模式 8：Hierarchical

Hierarchical 是多层 coordinator：

Root Agent
  -> Area Agent A
      -> Worker A1
      -> Worker A2
  -> Area Agent B
      -> Worker B1
      -> Worker B2

我们没有完整实现。
Claude Code 也不是把它做成一个单独的 HierarchicalMode，而是可以通过 coordinator + AgentTool + Task 工具组合出来。

这种模式适合超复杂任务，但代价很高：

• 上下文切分难
• 调试难
• 成本高
• 任务分解错了会层层放大

这也是为什么我们学习路线不应该先从它开始。

---

十三、模式 9：Swarm

Swarm 是最“野”的模式：

多个 Agent 彼此通信
共享发现
互相挑战
持续收敛

我们没有完整 Swarm。step39 的 AgentBatch 只是：

主 Agent -> 并行派发 N 个子 Agent -> 汇总

没有：

• 子 Agent 互相发消息
• 持久团队状态
• 领导者 / worker 生命周期
• 权限同步
• 跨进程协调

Claude Code 里有 src/utils/swarm/、TeamCreateTool、SendMessageTool、Task*Tool 等相关能力。它更像一个“团队系统”，而不是一次性 fan-out。

Swarm 的风险也最大：通信爆炸、循环不收敛、成本失控。所以生产系统里一般不会轻易从 Swarm 起步。

---

十四、模式 11：Human-in-the-Loop

Human-in-the-Loop 是 Claude Code 特别核心的部分。

在我们项目里，它从 step19 开始：

模型想执行 Bash / Write
系统问用户
用户允许或拒绝
工具才执行

后面 step57 加了权限规则，step67 把权限请求搬到 WebSocket：

permission_request
permission_response

Claude Code 的生产版更完整：

• useCanUseTool 承担权限询问。
• utils/permissions 管 allow / deny / mode / rule。
• Bash 有专门的风险分类和命令匹配。
• MCP / channel / remote bridge 也有权限语义。

这不是 UI 小功能，而是 Agent runtime 的安全底座。

---

十五、模式 12：自定义逻辑

自定义逻辑就是：

前面 11 种都不够，就自己写编排。

我们已经有几个扩展入口：

• step35：commands
• step36：hooks
• step41：skills
• step52：plugins
• step47-51：MCP

Claude Code 也是这样：

• slash commands 提供固定命令
• skills 提供按需加载的专门工作流
• plugins 扩展工具 / 命令 / hooks
• MCP 接外部系统

这类能力的意义是：不要把所有复杂性都塞进主 Agent prompt。稳定流程应该外置成工具、命令、skill 或插件。

---

十六、我们到底实现了什么，没实现什么

能力	claude-learn	Claude Code
ReAct 主循环	已实现骨架	生产级 query 状态机
Loop 上限	maxRounds	maxTurns + transition + 恢复分支
工具并行	Promise.all	concurrency-safe 分批 + streaming executor
TodoWrite	基础任务清单	scoped todo + verification nudge
Iterative Refinement	行为可自然发生	有验证提醒、任务系统、诊断、压缩保护
Review & Critique	有 AgentTool 基础	内置 verification agent
Coordinator	AgentBatch 雏形	src/coordinator/
Swarm	未完整实现	src/utils/swarm/ + Team 工具
Human-in-the-Loop	权限询问 + 规则 + WebSocket	完整 permission runtime
自定义逻辑	commands / skills / plugins / MCP	更完整生态

最准确的总结：

claude-learn:
  把模式做成可读、可运行、可理解的最小形状。

Claude Code:
  把模式做成能承受真实用户、真实文件系统、真实中断、真实成本的 runtime。

---

十七、面试追问

Q：ReAct、Loop、Iterative Refinement 到底是不是一回事？
A：不是。ReAct 是决策结构，Loop 是控制结构，Iterative Refinement 是任务目标。它们常常共用同一段循环代码，但语义层不同。

Q：为什么不一开始就做多 Agent？
A：因为多 Agent 会放大三个成本：推理费用、上下文工程、调试复杂度。单 Agent + 好工具 + 好权限，已经能覆盖大多数任务。

Q：我们项目为什么没有单独写 IterativeRefinementEngine？
A：没必要。迭代优化不是基础设施名字，而是 QueryEngine 循环在“写代码、跑测试、修错误”这类任务上的表现。

Q：Claude Code 的 verification agent 算不算 Review & Critique？
A：算，而且是很硬的版本。它不仅“评价”，还被提示词强制运行命令、输出证据、给 verdict，并且禁止改项目文件。

Q：AgentBatch 算不算 Swarm？
A：不算。AgentBatch 是一次性 fan-out + 汇总；Swarm 是多 Agent 长生命周期通信和协作。

---

十八、一句话总结

Agent 设计模式不是菜单，不是“选一个就完事”。真实系统通常是叠加的：

单 Agent 打底
+ ReAct 工具循环
+ Loop 上限和恢复
+ TodoWrite 驱动迭代优化
+ Human-in-the-Loop 管权限
+ Verification agent 做独立审查
+ 必要时再上 Coordinator / Swarm

我们已经写出了这套体系的教学骨架；下一步如果要继续逼近 Claude Code，最值得补的不是更多花哨 UI，而是：

1. verification agent 闭环；
2. concurrency-safe 工具调度；
3. query transition 状态机；
4. session 持久化与恢复；
5. compact / fallback / stop hook 的生产级恢复路径。