8 种 AI 设计模式的 24 份官方文档阅读地图

上一篇留下的那个坑

在上一篇里，我写过一段“可能得罪人”的话： 别盯着某一个视频教程一个一个刷，去仔细研读官方文档。这是最快让你真正掌握一门技术的方式，没有之一。因为它是唯一一份不会为了讲得顺而替你省略边界的资料。

当时留了两个待办：每种模式该读哪些官方文档，以及怎么给模式做验收。这篇先兑现第一个。

说起来讽刺。这句话我自己是踩过坑才认的：早年间为了赶进度，我照着一个系列视频搭过一套服务，跑通了，上线了，然后在一次并发高峰里崩得莫名其妙。后来翻官方文档，发现那件事人家在Limitations那一节用两行字写得很清楚，只是那两行字，视频里没有，因为视频只负责让你跑通。

视频的价值是让你相信这件事能做，文档的价值是告诉你这件事什么时候会不行。 前者给你信心，后者救你的命。 一、先讲方法：官方文档该怎么读 1.1 文档的价值密度，是倒挂的

绝大多数技术文档都是同一个结构，而这个结构的价值分布，和读者的停留时间是完全相反的。

它们不会出现在标题里，不会加粗，往往躲在页面最底部、一个折叠面板里，或者一句看起来很客气的 "Note" 后面。但它们才是那份文档存在的真正理由，写文档的人，最怕你误用的地方，就写在那儿。 1.2 四遍读法

我自己用的顺序，和文档的排版顺序不一样：

大多数人只做第 1 遍，一部分人做到第 2 遍，几乎没人做第 4 遍，而第 4 遍是唯一能防止你在生产环境里翻车的那一步。 1.3 三处必须做标记的地方

读文档时，遇到这三种表述，立刻停下来做标记： 所有 MUST / MUST NOT / SHOULD（RFC 2119 语义） 这不是修辞。协议文档里这些词有严格定义，MUST NOT 的意思是 你这么干就是错的，不是不建议这么干。 所有 "we recommend" / "consider" 后面的那个从句 官方文档的措辞非常克制。当它终于说「我们建议」时，后面那半句通常是踩过坑才写上去的。比如 Anthropic 那句 "we recommend extensive testing in sandboxed environments, along with the appropriate guardrails"翻译一下是：这玩意儿会失控，你必须把它关进笼子里。 所有 Error codes 表 错误码表是文档的「病例库」。每一个错误码背后，都是一类真实发生过的失败。读错误码表，等于提前把所有可能的坑过一遍。 二、24 份一手资料总览【仅供参考，有其他好的资料欢迎评论区共享】

下表是完整清单，仅供参考。「资料类型」列是我建议你采用的分类方式：概念（C）/ 接口（A）/ 边界（B），三者缺一不可。

| # | 模式 | 一手资料 | 类型 | 优先读哪几节 | | --- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | ---- | ------------------------------------------------------------------- | | 1 | Tool-Augmented | OpenAI Function Calling | C+A | Tool calling 流程、toolchoice 语义、Parallel tool calls | | 1 | Tool-Augmented | OpenAI Structured Outputs | A+B | Strict mode 的 schema 限制、支持/不支持的类型清单 | | 1 | Tool-Augmented | MCP Specification | C+B | Tools 章节的 annotations（readOnly / destructive / idempotent） | | 2 | ReAct | ReAct 论文（arXiv 2210.03629） | C+B | Limitations 一节：错误累积、稀疏奖励 | | 2 | ReAct | LangChain Agents 概念 | C | 它对「Agent 可靠性」的坦白 | | 2 | ReAct | LangGraph Low Level 概念 | A+B | recursionlimit、节点终止条件 | | 3 | RAG Agent | LangChain RAG 概念 | C | Retrieval 章节：查询变换、路由、重排的适用条件 | | 3 | RAG Agent | LlamaIndex 文档 | C+A | Chunking 策略、Node parser、Response synthesis | | 3 | RAG Agent | Qdrant 文档 | A+B | HNSW 参数与召回率的权衡、量化带来的精度损失 | | 4 | Memory | LangGraph Memory 概念 | C+B | 短期 vs 长期记忆的语义边界、写入时机 | | 4 | Memory | LangChain Memory 概念 | C | 记忆的读写策略分类 | | 4 | Memory | Redis 向量检索文档 | A+B | 索引类型、过滤条件、内存开销 | | 5 | Plan-and-Execute | LangGraph Plan-and-Execute 教程 | C+A | re-plan 的触发条件、步骤粒度 | | 5 | Plan-and-Execute | Plan-and-Solve 论文（arXiv 2305.04091） | C+B | 与 ReAct 的对比实验、失败案例分析 | | 5 | Plan-and-Execute | LangGraph How-to 指南 | A | 子图、分支、状态传递 | | 6 | Reflection | LangGraph Reflection 教程 | C+A | 反思循环的结构、终止判据 | | 6 | Reflection | Reflexion 论文（arXiv 2303.11366） | C+B | 反思失效的案例分析 | | 6 | Reflection | Anthropic《Building Effective Agents》 | C+B | Evaluator-Optimizer 的适用前提 | | 7 | Multi-Agent | LangGraph Multi-Agent 概念 | C+A | Handoffs 语义、四种拓扑的适用条件 | | 7 | Multi-Agent | Anthropic《Building Effective Agents》 | B | When (and when not) to use agents | | 7 | Multi-Agent | Anthropic 多智能体研究系统 | B | 真实成本数据、协调开销 | | 8 | Autonomous Loop | LangGraph Persistence 概念 | A+B | Checkpoint 语义、Time travel（回放） | | 8 | Autonomous Loop | LangGraph Human-in-the-loop | A+B | interrupt 语义、审批点设计 | | 8 | Autonomous Loop | OpenAI Agents SDK 文档 | A+B | Guardrails 与 Handoffs、最大轮次 | 标注 加粗 的，就是那份文档里最容易被跳过、但最值钱的章节。下面逐个展开。 三、逐个模式：读什么 · 按什么顺序 · 哪几节最值钱 插一句：这个是我一贯的学习方式，也在之前的文章中提过：https://cloud.tencent.com/developer/article/2718893 通用的阅读顺序是一个三段式，别跳步： 3.1 Tool-Augmented（工具增强）

最容易被跳过、但最值钱的三节： toolchoice 的取值语义（auto / required / none / 指定某个工具） 绝大多数人只用默认的 auto。但 auto 的含义是「模型可以不调用任何工具」——这意味着你的 Agent 在某一轮可能什么都不做，然后直接编一个答案。这是「工具调用了但没生效」这类诡异 bug 的头号来源。 Structured Outputs 的 Strict mode 限制 这一节通常在页面下半部分：开启 strict: true 后，schema 会被要求 additionalProperties: false、所有字段进 required、可选字段必须用 ["string", "null"] 这种 union 写法。很多人卡在这里，然后关掉 strict 了事——但你关掉的不只是校验，还有「模型一定按 schema 输出」这个保证。 MCP Tools 章节的 annotations MCP 规范给工具定义了 readOnlyHint、destructiveHint、idempotentHint 这类注解。这是唯一一处由协议层（而不是你自己）来声明「这个工具会不会造成破坏」的地方。做权限白名单、做人工审批点，都应该以它为依据，而不是靠你在 Prompt 里写「小心点」。 一句话：工具增强的难点从来不是怎么调，是怎么保证它不乱调。官方文档里关于这部分的篇幅，比调用本身多得多。 3.2 ReAct（推理行动协同）

最值钱的三节： 论文里的 Limitations 一节 论文的价值不在方法，在作者诚实列出的失败模式：推理与行动耦合导致的错误累积、长链条中的幻觉传播、以及稀疏奖励下的训练困难。你在工程里遇到的跑着跑着就跑偏了，论文里早有描述。 LangGraph 的 recursionlimit 这是个默认值很小的参数，写在配置章节里，很容易被当成性能调优项。它的真实身份是你唯一的护栏，ReAct 一旦进入循环，没有它就跑不完。 LangChain 对 Agent 可靠性的坦白 概念文档里明确提到 Agent 比固定链路更难预测、更慢、更贵。一个框架主动说自己不建议，这句话的含金量高于一百篇教程。 3.3 RAG Agent（检索增强）

最值钱的三节： 查询变换（Query Transformation）的适用条件 文档会告诉你 HyDE、multi-query、step-back 这些方法，但最关键的是它们各自的适用前提。很多人照抄了 multi-query，结果召回一堆同质化片段，效果反而变差，因为文档里写了它适合「查询表述模糊」的场景，不适合「术语精确」的场景。 分块（Chunking）策略那一节 看起来最无聊的一节，实际上决定了你这套 RAG 的天花板。文档会列出固定长度 / 语义 / 按文档结构等切法的取舍，而不是告诉你用哪种最好，因为本来就没有最好。 向量库的 HNSW 参数与量化说明 efsearch、m 这些参数，以及量化（scalar / product quantization）带来的召回率损失。这一节直接决定你的「检索准确率」到底是 95% 还是 78%。大部分人从来没读过，然后怪模型有幻觉。 一句话：RAG 的问题 90% 不在生成端，在检索端。而检索端的所有秘密，都在向量库文档的性能调优章节里，不在任何教程里。 3.4 Memory-Augmented（记忆增强）

读什么：LangGraph Memory 概念 → LangChain Memory 概念 → Redis 向量检索文档

最值钱的三节： 短期记忆 vs 长期记忆的语义边界 LangGraph 文档把记忆分成线程内（thread-scoped，靠 checkpoint）和跨线程（cross-thread，靠 store）两类。这两类的写入时机、隔离级别、失效策略完全不同。混用的后果就是：A 用户的偏好出现在 B 用户的对话里。 threadid 的隔离语义 一行配置，写在快速开始里，几乎没人注意。它是你唯一的数据隔离开关。 记忆写入时机（hot path vs background） 文档会讨论在主链路上同步写记忆和后台异步写的差别。这不只是性能问题，同步写入会让用户感知到延迟，异步写入会让当前轮次读不到刚发生的事。文档中讲得很清楚，大部分教程基本不提。 3.5 Plan-and-Execute（规划执行）

最值钱的三节： re-plan 的触发条件与次数上限 教程里会告诉你执行失败时重新规划，但不会替你定上限。这必须由你写死。没有上限的 re-plan = 无限循环 + 无限账单。 步骤粒度 规划得太粗，等于没规划；规划得太细，每一步的通信开销会淹没收益。文档里对任务分解的讨论通常附在 agentic patterns 章节，值得逐句读。 子任务失败如何回传 这是文档里最容易被忽略的工程细节：子任务失败了，失败信息以什么形式回到 planner？是原始报错，还是结构化摘要？这个设计决定了你的系统能不能自我修复。 3.6 Reflection（反思改进）

最值钱的三节： Anthropic 写的适用前提，这一节价值最高 原文的判断标准有两条：当人类能清楚表达反馈时，LLM 的输出能被显著改善，且 LLM 自己也能提供这种反馈。 这两条是反思模式的准入门槛。 不满足第一条的领域（比如主观审美、无明确标准的写作），加反思就是纯烧钱。 反思轮次的上限与终止判据 与 re-plan 同理，必须写死。而且什么时候算改好了这个判据，必须是一个可判定的标准，不能是模型觉得可以了。 Reflexion 论文里的失效案例 论文不只是讲方法好用，也讲什么时候不好用：反思会引入新的错误，且在没有外部反馈（如测试结果）时，反思容易陷入自我确认。 3.7 Multi-Agent（多智能体协作）

最值钱的三节： Anthropic 那节「When (and when not) to use agents」 全篇最该抄进笔记本的一节。它明确说了：能用单次调用 + 检索 + 上下文示例解决的，就别上 agentic 系统。这是官方文档里少见的、明确劝退的段落。 LangGraph 的 Handoffs 语义 Command(goto=..., graph=Command.PARENT) 这套导航机制，看起来是 API 细节，实际上是多智能体系统里「谁说了算」的根本设计。读不懂这一节，搭出来的多智能体必然互相踢皮球。 Anthropic 多智能体研究系统的真实成本数据 这篇工程博客最值钱的是它公开的数字：多智能体系统的 token 消耗是普通对话的数倍到十几倍。这是你在方案评审会上说服别人的最好弹药。 3.8 Autonomous Loop（自主循环）

最值钱的三节： 停止条件（Stopping Conditions） Anthropic 与各家文档都强调：自主循环必须设置停止条件（最大迭代次数、超时、预算上限）。这是这个模式的唯一安全装置，不是可选项。 Checkpoint 与 Time travel（回放） 这一节决定了你的系统出事之后能不能查。没有 checkpoint 的自主循环 = 一次不可复现的事故。可回放是上生产的前提，不是加分项。 interrupt 与审批点 Human-in-the-loop 文档讲的不是「要不要人参与」，而是在系统里哪个位置留出人参与的插槽。这一节是 Harness 层（见上一篇 L3）设计的直接依据。 一句话：所有关于自主循环的官方文档，读起来都像一份风险告知书。如果你读完之后只记住了怎么让它一直跑，那说明你读错地方了。

--- 四、跨模式的 5 份【通用必修】

不管你最终用哪几个模式，这 5 份建议完整读一遍：

| 资料 | 为什么必须读 | 重点章节 | | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Anthropic《Building Effective Agents》 | 一份由模型厂商系统讲什么时候不该用 agent的文档 | When (and when not) to use agents / Appendix 2: Prompt Engineering your Tools | | MCP 规范 | 工具与上下文的协议层事实标准，决定了你的工具层能不能被替换 | Tools / Resources / Sampling / 所有 MUST 条目 | | LangGraph Low Level 概念 | 状态机视角下 agent 的底层抽象，看懂它就不怕换框架 | Nodes / Edges / State / recursionlimit | | ReAct 论文 + Reflexion 论文 | 两种最重要推理范式的原始出处，含作者自述的失败模式 | 两篇的 Limitations / Failure cases 章节 | | OpenAI Agents SDK 文档 | 一份把 guardrails、handoffs、tracing 产品化的参考实现 | Guardrails / Handoffs / Tracing |

读这 5 份的共同收获是：你会开始用边界而不是能力来描述一个技术。 这是从使用者到架构师的分水岭。

--- 五、阅读计划 AI 拉平了技术门槛，抬高了融合的价值。但对资深技术者，最终只问一句：你要可落地的工程，还是 demo？

| 周次 | 主题 | 读什么 | 产出（必须落到纸面） | | ---------- | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- | | Week 1 | 建立世界观 | Anthropic《Building Effective Agents》全文 + MCP 规范 Introduction | 一页纸：我对agent的定义，以及三条不该用的判断标准 | | Week 2 | 打通水电煤 | Tool-Augmented 三份 + RAG 三份 | 一张表：每个参数的取值 → 实际行为变化 | | Week 3 | 攻克推理链 | ReAct + Plan-and-Execute + Reflection 的资料与论文 | 三张失败模式卡片：每种模式列举 ≥3 个已知会炸的场景 | | Week 4 | 打通治理 | Memory + Multi-Agent + Autonomous Loop 的资料 | 一份清单：我的 Harness 层需要哪些硬约束（轮次/预算/沙箱/审批/回放） | 六、自检：你真的读懂了吗 6.1 速查：三类高价值章节的识别口诀

| 类别 | 长什么样 | 典型关键词 | 你必须回答的问题 | | -------------------------- | ---------------------------- | --------------------------------------------------- | -------------------------------- | | 边界 Boundaries | 定义这个能力管到哪儿为止 | Scope / Definitions / Overview | 它不负责什么？ | | 限制 Limitations | 明确列出做不到的事 | Limitations / Constraints / Not supported / Caveats | 哪几条限制会打到我的场景？ | | 失败模式 Failure Modes | 描述出错时的行为 | Error codes / Troubleshooting / Failure cases | 它失败时是静默失败还是报错？ |

第三条最关键。静默失败是 AI 系统最大的敌人模型不会抛异常，它只会给你一个看起来很像样的答案。 6.2 十条自检

读完一份文档，能回答以下十个问题里的八个，才算真的读过： 这个能力的官方定义是什么？用自己的话说一遍。 它明确不负责什么？ 它的默认参数是什么？哪个默认值最危险？ 它失败时是抛错还是静默降级？ 它的错误码有哪几个？最常见的那个是什么？ 它对并发 / 幂等 / 顺序有没有保证？ 它的成本模型是什么？什么操作最贵？ 它的隔离边界在哪（用户 / 会话 / 租户）？ 文档里出现 MUST NOT 的地方有几处，分别是什么？ 如果明天要换掉它，我需要改哪些代码？

第 10 条是上一篇讲的可替换性测试：它同时也是检验你有没有读懂一份文档的最好标尺。答不出第 10 条，说明你只是在用，不是在懂。 七、结尾

这一篇从头到尾只讲了一件事：官方文档里，最值钱的内容往往最不像重点。

而这件事的底层逻辑，和我在这个系列里反复讲的是同一条： 架构能力的来源，不是你会调多少个 API，是你清楚地知道每个 API 在哪里会失效。

所以别再问有没有讲 XX 的好视频了。去读文档，读到第 4 遍，读到能把错误码表记下来。那是最慢的路，也是最快的路。