AI 的记忆（Memory）到底是什么？为什么它不等于"更大的上下文窗口"？这篇讲透记忆的四种类型、一个记忆系统真正在做的四件事，拆解五套经典架构（Generative Agents 的记忆流、MemGPT 的"LLM 操作系统"，以及 Voyager、MemoryBank、HippoRAG），对比 ChatGPT / Claude / Mem0 的真实实现，最后回答最难的两个问题：记什么、忘什么。附自查清单。

大模型有个容易被忽略的事实：它天生没有记忆。 每次调用，模型都从一张白纸开始，你这次说的话、上次聊的内容，它一概不记得——除非你把这些内容再一次塞进上下文窗口。你在 ChatGPT 里感受到的"它记得我"，不是模型的能力，而是外面套了一层记忆系统在替它记、替它取。

这篇讲的就是这层系统：它由什么构成、怎么工作、业界到底怎么做的。面向工程师和技术决策者，从概念到架构到实战，附照抄清单。它可以看作《上下文工程》那篇的续集——如果说上下文工程管的是"这一步窗口里放什么"，那记忆管的就是"跨越时间，什么值得被记住、又该在何时被想起"。

一、先厘清：记忆 ≠ 更大的上下文窗口

这是最常见的误解。很多人以为"上下文窗口从 8K 涨到 1M，记忆问题就解决了"。不对。

上下文窗口是工作台，记忆是仓库。区别有三：

• 持久性：上下文窗口是易失的，一次对话结束就清空；记忆要跨会话、跨天、跨月存在。
• 容量：窗口再大也有上限，而且越塞越满、信噪比越低效果越差（context rot，见《上下文工程》）；仓库理论上无限。
• 成本：窗口里的每个 token 每一步都要重新计算、重新收费；仓库里的信息静静躺着，只在需要时取一小部分进窗口。

所以记忆系统的核心任务，不是"把所有历史都留在窗口里"，而恰恰相反：把信息挪到窗口之外存起来，只在恰当的时机取回恰当的一小块。 一句话——

记忆的本质，是"用窗口外的存储，换窗口内的稀缺注意力"。

这也解释了为什么"无限长上下文"永远替代不了记忆：就算窗口能装下你一年的对话，模型也读不好那么长，成本更是天文数字。仓库和工作台，是两种东西。

二、人脑给的地图：记忆的几种类型

AI 记忆的分类，几乎照搬了认知科学对人类记忆的划分。记住这张图，后面所有架构都能对号入座。

短期记忆（Short-term / Working Memory）：当下任务用的"工作内存"，相当于电脑的 RAM。在 LLM 里，它基本就等于当前上下文窗口——正在进行的这轮对话、刚拿到的工具返回。易失、容量有限、速度快。

长期记忆（Long-term Memory）：跨会话保留的信息，相当于硬盘。它又细分为三种，这个区分很重要：

一个好用的判断法：情景记忆回答"发生过什么"，语义记忆回答"什么是真的"，程序记忆回答"该怎么做"。 大多数产品今天做得最扎实的是语义记忆（记住你的偏好和事实），情景记忆次之，程序记忆最难、也最前沿——它意味着 Agent 能从经验里"学会一套做法"并固化下来。

三、一个记忆系统真正在做的四件事

抛开花哨的名词，任何记忆系统都在循环做四件事。这四个动词，是你评估任何方案的骨架：

1）写入 / 编码（Encode）——从这次交互里，判断"哪些值得记"，并把它整理成一条可存储的记忆。难点是取舍：全记会污染未来，漏记会失忆。

2）存储（Store）——把记忆放进窗口外的载体：数据库、向量库、知识图谱或纯文件。这一步决定了后面怎么检索。

3）检索（Retrieve）——下次交互时，判断"这一次该想起哪几条"，把它们取进上下文窗口。取多了是噪声，取少了不够用。

4）更新 / 遗忘（Update / Forget）——记忆会过时、会冲突（"他去年住上海，今年搬北京了"）。系统要能修正旧记忆、淘汰无用记忆，而不是无脑堆积。

如果你读过《上下文工程》那篇会发现，这正是其中"写出（Write）"和"选取（Select）"两个操作在时间维度上的展开——写入=Write，检索=Select。记忆不是一个新东西，而是上下文工程沿着"时间轴"长出来的一条分支。

判断一个记忆系统好不好，别看它"能存多少"，看它这四步做得准不准——尤其是写入的取舍和遗忘的更新，这两步最难，也最能拉开差距。

四、几套必须知道的经典架构

记忆的经典设计不止一种。下面五个是理解一切记忆系统的骨架，每一个都钉死了一个不同的关键能力，看完你就有了一张完整的"能力地图"。

1. Generative Agents：记忆流 + 反思

2023 年斯坦福那篇著名的《Generative Agents》（让 25 个 AI 小人在虚拟小镇里自主生活）第一次把记忆架构讲得清清楚楚，至今仍是入门必读。它由三部分组成：

• 记忆流（Memory Stream）：一个不断追加的、用自然语言记录的经历清单。小人看到的、听到的、说过的、做过的，全都按时间顺序记下来。
• 检索（Retrieval）：不可能把整条流都塞进窗口，所以每次按当前情境打分挑选——分数是三个维度的加权和：相关性（与当前处境的语义相似度）、新近性（越久没想起分越低，按时间指数衰减）、重要性（写入时打的分，"吃了顿早饭"低、"和恋人分手"高）。
• 反思（Reflection）：最点睛的一步。Agent 定期回看最近的记忆，综合出更高层的结论（从零散互动里总结出"我好像挺喜欢隔壁的 Klaus"），再作为新记忆写回流里。反思让记忆从"流水账"升级为"洞察"。

记住这三个词——记忆流、按相关性/新近性/重要性检索、反思。后来几乎所有记忆系统，都是在这个骨架上做加减法。

2. MemGPT：把 LLM 当操作系统（分层 + 自编辑）

如果说 Generative Agents 给了"检索"的范式，那 2023 年的 MemGPT（论文副标题就叫 Towards LLMs as Operating Systems，现已并入开源框架 Letta）给了"分层管理"的范式。它的洞察很妙：上下文窗口就像操作系统的物理内存（RAM），窗口外的存储就像磁盘；操作系统靠"分页"换入换出制造"内存无限大"的错觉——LLM 也可以。

最关键的设计是：模型拥有"编辑自己记忆"的工具——核心记忆快满时，它自己决定把哪条挪去归档、把哪条调回核心。这就把"记忆管理"从人写死的规则，变成了模型自己的能力。这套"分层 + 自编辑"思路直接影响了产品级实现：比如 Anthropic 在 2025 年 9 月给 Claude 加的"记忆工具（memory tool）"——给模型一个专属文件目录，让它自己增删改查、跨会话沉淀知识；配合"上下文编辑（自动清理窗口里过期的工具调用）"，官方数据显示 100 轮网页搜索评测里削减 84% 的 token、比基线提升 39%。同一个骨架，产品化的样子。

3. 另外三个各钉一个关键点：Voyager、MemoryBank、HippoRAG

• Voyager——技能库就是"程序记忆"。 2023 年这个在《我的世界》里自主探索的智能体，让模型为每个新任务生成可执行代码，把跑通的程序按自然语言描述存进不断增长的"技能库"；下次遇到相似任务直接检索、组合旧技能，而不从头再想。这正是第二节说的程序记忆——存的不是"事实"，而是"会做的本事"。
• MemoryBank——给记忆装上"遗忘曲线"。 它把心理学的艾宾浩斯遗忘曲线搬进 AI：每条记忆有"强度"，被想起就加强、长期不碰就衰减，检索时综合语义相似度和这个"留存分"。它给第七节"忘什么"提供了优雅的机器答案——不是一刀切删除，而是像人一样自然淡忘、又能被唤醒。
• HippoRAG——照着海马体来建图。 它借用神经科学的"海马体索引理论"：把 LLM 当"新皮层"，另建一张知识图谱当"海马体索引"，检索时用类似 PageRank 的算法在图上联想。它是图记忆这条路线里最有理论野心的一支——擅长把散落的线索串联起来回答问题。

把五个放一起，就是一张记忆设计的"能力地图"：Generative Agents 管检索与反思、MemGPT 管分层调度、Voyager 管技能积累、MemoryBank 管遗忘、HippoRAG 管联想。 你缺哪块能力，就去看押注那块的设计。

五、产品里的记忆，长什么样

把架构落到你天天在用的产品上：

ChatGPT：两层记忆。一层是保存的记忆（Saved Memories）——一份你能查看、能删的显式事实清单（"我是素食主义者"），模型自动往里写；另一层是 2025 年 4 月上线的引用聊天历史（Reference Chat History）——不列清单，而是隐式地从你过往所有对话里抓取模式，让回答更贴合你。两层都能在设置里单独关掉，临时对话则不读也不写记忆。2026 年 OpenAI 又给它加了后台自动整理记忆的机制，让记忆随时间越来越准。

Claude：走的是上一节说的"文件式记忆工具 + 上下文编辑"路线，更偏开发者可控——记忆存在你自己的基础设施里，你完全掌握数据。

Gemini：Google 也给 Gemini 加了记忆——既能记住你在设置里保存的个人信息，也能选择性地参考你过往的对话来个性化回答，同样支持查看、编辑与关闭。

共同的产品哲学：记忆不是黑箱。让用户看得见、改得动、关得掉，正在成为标配——因为记忆一旦记错、记了不该记的，体验和信任的崩塌是双倍的。

六、工程落地：三条主流技术路线

真要自己做一套记忆系统，存储和检索这块，业界基本是三条路线（常常混用）：

路线一：全量 / 摘要（Full-context / Summary） 最朴素：把历史全部或摘要后塞回窗口。简单，但长了就撞上 context rot，又慢又贵。适合短周期、轻量场景。

路线二：向量检索（Vector / RAG-style） 把每条记忆转成向量存进向量库，用时按语义相似度检索最相关的几条。这是目前最主流的做法。开源框架 Mem0 是代表：它不存原始对话，而是用 LLM 从对话里抽取关键事实再存，检索时只取相关记忆。在业界常用的长程对话记忆基准 LOCOMO 上，Mem0 官方报告称其准确率比 OpenAI 的记忆方案高约 26%、延迟低约 91%、token 成本省约 90%——核心就赢在"只喂相关的一小撮，而不是全量历史"。

路线三：知识图谱（Graph） 把记忆存成"实体—关系"的图（张三—就职于—某公司）。擅长处理多跳推理和关系随时间变化（"他跳槽了"只需改一条边）。表达力强，但构建和维护成本高。

实务上没有银弹，成熟系统往往向量为主、图谱为辅、摘要兜底。

七、最难的两件事：记什么，忘什么

存储和检索是工程，真正的难点是两个判断题：

难题一：写什么？ 不是每句话都值得记。乱记会带来两种灾难：一是噪声——把无关琐事都记下来，未来检索时全是干扰；二是记忆污染（memory poisoning）——一个早期的错误结论被写进长期记忆，之后每次都被取回、一路将错就错，甚至成为被攻击的入口（有人专门研究往记忆里"投毒"）。所以写入必须有取舍、去重、和冲突检测。

难题二：忘什么？ 记忆会过时、会矛盾。用户去年说"我在读研"，今年毕业了；上个月喜欢的东西这个月厌了。一个只增不减的记忆库，迟早自相矛盾。好的系统需要更新（用新记忆覆盖旧的）、衰减（长期不用的自然淡出）、乃至主动遗忘（用户要求删除，这也是合规刚需）。

做记忆系统，"存"是入门，"取"是及格，"忘"才是高手。会遗忘的记忆才是活的记忆——否则你得到的不是一个越来越懂你的助手，而是一个背着一身过期偏见、越来越固执的包袱。

八、开发者想加记忆：别自己造轮子，先看这几个方案

好消息是，到 2026 年，"给 Agent 加记忆"已经不用从零写起——一批成熟的开源框架把上面的路线都封装好了。想动手的开发者，主流选择大致是这几个（都可自托管）：

选型别记参数，记这条主线：你最缺的是什么能力，就选押注那个能力的框架——要快就 Mem0，要处理"张三跳槽了"这种时序变化就 Zep/Graphiti，要一个能自己管理记忆的有状态 Agent 就 Letta。

而 2026 年最出圈的一个新项目，恰恰是对第七节"记什么、忘什么"给出了一个反向的答案——MemPalace。它由《生化危机》女主角 米拉·乔沃维奇（Milla Jovovich） 和工程师 Ben Sigman 合作、用 Claude Code 开发，MIT 开源，2026 年 4 月发布后两天就冲上 2 万多星。它的出发点是一句抱怨："我受够了 AI 替我决定该记住什么、然后把我真正需要的上下文丢掉。"

于是 MemPalace 反其道而行，借用古老的"记忆宫殿"记忆术：把对话逐字、不做摘要地存下来，再用空间隐喻组织成厅（wings，按人和项目）→ 房间（rooms，按主题）→ 抽屉（drawers，放原文），检索时能"分区"精确查找，而不是在一大团向量里瞎捞。它用混合检索（关键词加权 + 时间邻近），在 LongMemEval 基准上纯检索就拿到 96.6% 的 recall@5。存储后端可插拔（默认 ChromaDB，也支持 SQLite/Qdrant/pgvector），能对接 Claude Code、Cursor 等。

MemPalace 的价值不只在于"一个女明星写了个爆款开源项目"，而在于它把第七节那个哲学分歧摆上了台面：记忆到底该由 AI 替你自动裁剪，还是由你自己保留全部、掌控结构？ 前者省心，后者可控——这没有标准答案，但它提醒你："让 AI 决定记什么"本身，就是一个需要你亲自拍板的设计决策。

九、照抄即用：记忆系统自查清单

• 我分清了**短期记忆（窗口内）和长期记忆（窗口外）**吗？没把"更大的窗口"当成记忆的答案吧？
• 长期记忆里，语义 / 情景 / 程序三类，我需要哪几种？各用什么存？
• 写入有取舍吗？还是把所有对话无脑全存？有没有去重和冲突检测？
• 检索是按相关性/新近性/重要性打分挑选，还是全量塞回窗口？
• 有没有更新和遗忘机制？旧的、错的、过期的记忆会被修正或淘汰吗？
• 用户能看见、修改、删除、关闭自己的记忆吗（体验 + 合规）？
• 存储选型对了吗——向量够不够，需不需要图谱处理关系与时序？
• 有没有防记忆污染？错误结论被写进长期记忆后会不会一路带偏？
• 有没有像 MemGPT 那样考虑分层，或像 Generative Agents 那样加反思，让记忆从流水账升级为洞察？

模型会越来越聪明，窗口会越来越大。但只要"注意力有限、信息会过时"这两条还成立，能不能记住你、并且在对的时候想起对的事，就永远是一套需要认真设计的系统，而不是模型白送的能力。

参考

• Packer et al.，MemGPT: Towards LLMs as Operating Systems（2023；现为开源框架 Letta）
• Park et al.，Generative Agents: Interactive Simulacra of Human Behavior（2023，记忆流 / 检索 / 反思）
• Wang et al.，Voyager: An Open-Ended Embodied Agent with Large Language Models（2023，技能库 / 程序记忆）
• Zhong et al.，MemoryBank: Enhancing LLMs with Long-Term Memory（2023，艾宾浩斯遗忘曲线）
• Gutiérrez et al.，HippoRAG: Neurobiologically Inspired Long-Term Memory for LLMs（2024，海马体索引 / 图记忆）
• Mem0，Building Production-Ready AI Agents with Scalable Long-Term Memory（2025，LOCOMO 基准）；开源仓库 mem0ai/mem0
• 开源记忆框架：Zep / Graphiti、Letta、Cognee、LangMem
• MemPalace，GitHub 仓库（2026，米拉·乔沃维奇 + Ben Sigman，"记忆宫殿"式）；Forbes 报道
• Anthropic / Claude，Managing context on the Claude Developer Platform（2025，memory tool + context editing）
• OpenAI，Memory and new controls for ChatGPT 与 Reference chat history（2025）
• Memory in the Age of AI Agents: A Survey（2025，综述与论文清单）

上下文工程（Context Engineering）：决定 AI Agent 上限的不是模型，而是你喂给它的上下文。讲透四大操作——写出/选取/压缩/隔离，RAG 还是长上下文、记忆、KV-cache 优化，附实战与自查清单。

做 Agent 的人迟早会撞上这堵墙：prompt 已经调到极致，效果还是不稳。问题往往不在那句话，而在模型每一步到底看到了什么。这篇讲的就是这件事——怎么管理模型的"视野"。面向工程师与技术决策者，从概念到实战，附照抄清单。

一、一个反直觉的事实

很多人调 Agent 的路径是这样的：效果不好 → 改 prompt → 还是不好 → 继续堆 prompt → 把所有可能用到的资料、历史、工具说明一股脑塞进去 → 效果反而更差。

问题往往不在 prompt 写得好不好，而在模型这一步看到的那段上下文是否对。

2025 年开始，业界有了一个共识性的词来命名这件事。Karpathy 把它讲得最直白：

"上下文工程"胜过"提示工程"。人们一提到 prompt，想到的往往是日常里随手给模型的一句简短指令；可在任何工业级的 LLM 应用里，上下文工程才是真功夫——它是一门精细的艺术与科学：在上下文窗口里，为下一步恰到好处地填入正确的信息。

「+1 for "context engineering" over "prompt engineering". People associate prompts with short task descriptions you'd give an LLM in your day-to-day use. When in every industrial-strength LLM app, context engineering is the delicate art and science of filling the context window with just the right information for the next step.」

Shopify 的 CEO Tobi Lütke 也公开表达过同样的偏好——他更喜欢"上下文工程"胜过"提示工程"，因为它更准确地描述了那项核心技能："为任务提供全部上下文，让大模型能合理地把事做成"（"the art of providing all the context for the task to be plausibly solvable by the LLM"）。

一句话区分：

提示工程：写好一段相对静态的指令。 上下文工程：在一个多步骤、不断变化的 Agent 循环里，动态地决定每一步往有限的上下文窗口里放什么、不放什么。

提示工程是上下文工程的一个子集。当任务从"一问一答"变成"自主跑几十步、调一堆工具、读一堆返回结果"时，主战场就从"那句话"转移到了"那整个窗口"。

二、为什么上下文是稀缺资源

直觉上，上下文窗口越大越好，1M token 听起来什么都装得下。但实践里，上下文是最稀缺的资源，原因有三：

1）注意力是有限的，且会"中间失忆"。 经典研究《Lost in the Middle》早就发现：把关键信息放在长上下文的中间，模型经常视而不见——它对开头和结尾敏感，对中段迟钝。后来 Chroma 等团队用更系统的实验把这个现象命名为 context rot（上下文腐坏）：随着上下文变长，模型在同一任务上的表现会持续、平滑地下降，哪怕"大海捞针"测试还显示它"找得到"。能找到 ≠ 能用好。

2）无关信息会主动干扰。 上下文里多塞的每一段无关内容，都是在和正确答案抢注意力。常见三种病症：

• 干扰（distraction）：被无关历史带偏；
• 污染（poisoning）：一个早期的错误结论留在上下文里，后面一路将错就错；
• 冲突（clash）：塞进去的资料彼此矛盾，模型无所适从。

3）成本和延迟随 token 线性增长。 每多一个 token，都要花钱、花时间。一个把上下文堆到满的 Agent，又慢又贵又不准。

结论很反直觉，但极其重要：

上下文不是越多越好，而是"信噪比"越高越好。上下文工程的本质，是在每一步只留下"刚好够用"的高信号信息。

三、上下文里到底有什么

先把"上下文"拆开。模型推理时看到的，远不止用户那句话，而是一整个被拼装出来的窗口：

上下文工程，就是对这张表里每一格做"加什么、减什么、留多久"的决策。其中最容易失控的是"工具返回结果"——一次网页抓取、一次数据库查询，就可能糊上几千 token。

四、四种基本操作：写出、选取、压缩、隔离

LangChain 把上下文工程的全部手段，归纳成四类操作。这是目前最好用的一张心智地图：

1. Write —— 写出（把信息存在窗口之外）

不是所有东西都得待在上下文里。把中间结论、计划、笔记写到窗口外部，需要时再取回：

• 草稿区（scratchpad）：当前任务内的临时笔记，让模型记住"我已经做到第几步、得出了什么"。
• 记忆（memory）：跨任务、跨会话的持久信息（用户偏好、项目约定）。

2. Select —— 选取（只在需要时取回相关的那一点）

这是 RAG（检索增强） 的本质，也是工具选择、示例选择的本质：

• 不把整个知识库塞进去，而是按当前问题检索出最相关的几段；
• 工具太多时，先用一层检索筛出"这一步可能用到的几个工具"，而不是把上百个工具定义全摆上；
• 连 few-shot 示例都可以按相似度动态挑选。

3. Compress —— 压缩（用更少的 token 表达同样的信息）

上下文快满时，不是粗暴截断，而是压缩：

• 摘要 / compaction：把前面几十轮对话总结成一段"目前进展纪要"，丢掉原始过程、保留结论和未决事项；
• 裁剪：按规则删掉最老、最不相关的部分。

4. Isolate —— 隔离（把上下文拆到多个独立空间）

把一个大任务拆给多个子 Agent，每个子 Agent 拿一个干净的、专属的上下文窗口去做子任务，只把"浓缩后的结论"返回给主 Agent。主 Agent 的窗口因此始终清爽。沙箱、独立运行环境也属于这一类——把可能产生海量输出的操作隔离在外。

记住这四个动词——写出、选取、压缩、隔离——你就有了应对几乎所有上下文问题的工具箱。

接下来几节，挑出这套框架里最常被追问、也最容易做错的几处，逐个深入。

五、RAG 还是长上下文？2026 年的答案

长上下文窗口刚出现时，很多人断言"RAG 要死了——既然能把整本书塞进去，何必检索？"两年过去，结论清晰了：长上下文没有杀死 RAG，反而让两者各归其位。

• 长上下文的软肋就是第二节说的 context rot：塞得越满，越容易中间失忆、越慢越贵。把 50 万 token 全灌进去，不等于模型真的"读懂"了 50 万 token。
• RAG 的价值恰恰是把"50 万里相关的 5 千"挑出来，喂高信号、低噪声的上下文——这正是上下文工程想要的。

实务上的选择：

更前沿的做法是 agentic retrieval（智能体式检索）：不再是"一次检索、拿结果就走"，而是让 Agent 自己多轮搜索、自己判断"够不够、要不要再查一次"，把检索变成一个有反馈的循环。

六、记忆：让 Agent 跨会话变聪明

记忆是上下文工程里专门处理"时间"的部分，分两层：

• 短期记忆：单次会话/任务内的连续性，主要靠第四节的 compaction 和 scratchpad 维持。
• 长期记忆：跨会话保留的信息——用户是谁、偏好什么、项目有哪些约定。你在 ChatGPT、Claude 里看到的"记住了你的偏好"，背后就是一套写入（什么值得记）+ 取回（这次该想起什么） 的机制。

记忆的难点从来不是"存"，而是两个判断：

1. 写什么：不是所有对话都值得记，乱记会污染未来的上下文；
2. 取回什么：这一次该想起哪几条，取多了又是噪声。

说到底，记忆系统就是"Write + Select"这两个操作在时间维度上的应用。

七、一条最容易被忽略的实务：让上下文对缓存友好

前面几节都在谈"放什么、不放什么"，还有一条几乎直接决定成本的路径常被忽略——KV-cache（提示缓存）。

模型处理上下文时，会把前缀算成一份可复用的中间状态（KV-cache）。只要这一轮的上下文前缀和上一轮完全一致，这部分就能直接命中缓存、不必重算——又快又省（命中的 token 通常只按原价的几分之一计费）。在多步 Agent 里，每一步都带着几乎相同的系统提示和历史，缓存命中率几乎直接决定了账单和延迟。业界甚至有一句话："KV-cache 命中率，是生产级 Agent 最重要的单项指标。"

由此引出几条和"信噪比"同等重要的构造原则：

• 稳定的放前面，易变的放后面。 系统提示、工具定义这些每轮不变的内容固定在最前，保证前缀稳定。
• 只追加，不改写。 新信息往尾部追加；一旦回头去改前面的内容（哪怕只动一个时间戳），其后的缓存会全部失效。
• 压缩要挑时机。 compaction、裁剪会改写前缀、使缓存失效，所以别太频繁触发，挑划算的点一次性做。

一句话：上下文工程不只决定"模型看得准不准"，也直接决定"这套系统跑得贵不贵"。

八、实战：两个最常用的模式

模式一：Compaction（上下文压缩续跑）。 这是长任务的命脉。以 Claude Code 为例，当上下文窗口快满时，它不会直接断档，而是自动把前面的工作总结成一段紧凑纪要（改了哪些文件、当前状态、下一步要做什么），然后用这段纪要"接着跑"。要点是：总结要保留"未决事项和关键决策"，丢掉"原始过程"。压缩没做好，Agent 就会"失忆"，反复做已经做过的事。

模式二：Sub-agent 上下文隔离。 主 Agent 负责编排，遇到一个重活（比如"把这 20 个文件逐个读一遍找出 bug"），就派一个子 Agent 去做。子 Agent 在自己干净的窗口里读完 20 个文件、得出结论，只把一句话结论返回给主 Agent。主 Agent 的窗口完全不会被那 20 个文件的内容淹没。这正是"隔离"的威力——也是多 Agent 系统最被低估的好处：它本质上是一种上下文管理手段，而不只是"并行干活"。

九、它和这些概念是什么关系

上下文工程周围围着一圈容易混淆的词。不必死记，按"关系的类型"理一遍，边界自然就清楚了：

① 上下游——MCP 在下面供料，Harness 在外面兜底。

• MCP（模型上下文协议）：解决"能接什么"，用一套统一协议把外部工具和数据源标准化地接进来，是上下文的"来源"。
• Harness（智能体的工程外壳）：模型权重之外、决定智能能否稳定落地的全部工程（工具、状态、验证、上下文管理……）。上下文管理只是其中一个子系统，却往往是最先翻车的那一个。

② 子集——提示工程和 RAG，都是它的一部分，不是它本身。

• 提示工程：上下文工程的前身和子集。任务从"一问一答"变成"自主跑几十步"，主战场就从"写好那句话"扩大到了"管好整个窗口"。
• RAG（检索增强）：只是"选取"这一类操作里的一个具体手段，负责"按需把相关知识取进来"。它是上下文工程的子集，不是同义词——把两者画等号，就漏掉了写出、压缩、隔离另外三大类。

③ 替代路线——上下文工程 vs 微调。

给模型注入知识和能力，有两条根本不同的路：把它喂进上下文（in-context，本文讲的全部），还是训进权重（in-weights，即微调 fine-tuning）。

• 知识更新快、要带来源、要随时增删 → 走上下文（RAG / 长上下文）；
• 要固化一种稳定的风格、格式或专有能力，且数据足够 → 考虑微调。

多数成熟系统两者并用：微调定"底色"，上下文工程喂"当下这件事"。

一句话收束：上下文工程决定模型每一步的"视野"——提示工程、RAG 是它的局部，微调是它的另一条路，MCP 在下面供料，Harness 在外面兜底。

十、照抄即用：上下文自查清单

• 我能说清模型在每一步看到的上下文里，到底有哪些成分吗？
• 工具返回结果有没有做"瘦身"（只留结论、截断超长输出）？还是原样塞回去？
• 上下文里有没有"已经没用的历史"？有没有定期压缩/裁剪？
• 长任务有没有 compaction 机制？压缩时保留了未决事项和关键决策吗？
• 知识检索是"全量塞入"还是"按需检索"？检索结果带不带来源？
• 工具/示例是不是"全量摆上"？能不能按当前步骤动态筛选？
• 有没有把重活拆给子 Agent，用独立窗口隔离它产生的海量中间信息？
• 上下文是不是"稳定内容在前、只在尾部追加"，以尽量命中 KV-cache、压住成本？
• 我有没有在"上下文越长越好"和"信噪比越高越好"之间，站对了队？

模型会越来越聪明，上下文窗口会越来越大。但只要"注意力有限、信息有噪声"这两条还成立，决定 Agent 上限的，就永远不只是模型本身，而是你喂给它的那段上下文。

参考

• Andrej Karpathy，关于 "context engineering" 的推文（2025）
• LangChain，Context Engineering for Agents（Write / Select / Compress / Isolate 框架）
• Anthropic，Effective context engineering for AI agents
• Chroma，Context Rot: How Increasing Input Tokens Impacts LLM Performance（2025）
• Liu et al.(arxiv)，Lost in the Middle: How Language Models Use Long Contexts（2023）

"如果你手里只有一把锤子，就会把所有东西都看成钉子。" —— 亚伯拉罕·马斯洛（查理·芒格爱引此语，并称之为"拿锤人综合症"）

人类历史上最聪明的一批大脑，分散在不同的学科里：哲学家锤炼了两千多年的提问技术，数学家发明了最严密的推理工具，物理学家最擅长把复杂世界简化成可计算的模型，心理学家则专门研究我们的大脑会在哪里出错。

问题在于，这些方法散落在各自的领域里，很少有人把它们放进同一个工具箱。芒格把这叫做"多元思维模型"（Latticework of Mental Models）：你不需要成为每个领域的专家，但需要掌握每个领域最重要的那几个模型，并知道在什么时候用哪一个。

这篇文章做的就是这件事——从哲学、数学、物理学、心理学、经济学、生物学、工程学里，各取最重要的几个思考方法，然后按照一次完整思考的六个阶段把它们串起来：

定义问题 → 拆解建模 → 推理探索 → 验证纠错 → 决策行动 → 复盘迭代

任何一次认真的思考——无论是做技术选型、写一篇文章，还是决定要不要搬去另一座城市——大体都会经过这六步。每一步，都有某个学科替你打磨好了趁手的工具。

文章先交代这套阶段划分的家谱（它不是我发明的，它有一百多年的传承），然后逐一介绍每个阶段的工具——每件都附谱系注：它从哪里来、地基有多牢，其中好几件的地基至今还是哲学上的未解之题，知道这一点会让你用得更清醒。

在出发前，先回到开头那把锤子。锤子问题的解法从来不是拥有更多的锤子——工具越多，慌乱时退回熟悉那把的概率反而越高——而是一张索引，告诉你什么时候该伸手拿哪一件。六个阶段，就是那张索引。

第零章：这套框架本身从哪里来

诚实地交代家谱：六阶段不是思维的自然规律，而是一个规范性模型——它描述的是"应该怎么想"，不是大脑实际怎么运作（大脑是并行的、跳跃的、被情绪驱动的）。这个模型有一条清晰的传承线：

• **杜威《我们如何思维》（1910）**提出反思性思维五步：感到困难 → 界定问题 → 提出假设 → 推理 → 检验。这是本文阶段一到四的直接祖先。杜威最重要的洞察是把"感到困难"和"界定问题"拆成两步——你最初感到的从来不是问题本身，只是症状。
• **波利亚《怎样解题》（1945）**给数学解题的四步：理解题目 → 制订计划 → 执行 → 回顾。"回顾"是阶段六的来源之一。
• PDCA 循环、OODA 循环、设计思维等二十世纪的工程与管理变体，共同贡献了一件事：把"行动"纳入思考的循环，而不是当作思考的终点。

把这些方案全部蒸馏到底，内核只剩一个算法：生成—检验—保留。波普尔称之为"猜想与反驳"，心理学家唐纳德·坎贝尔称之为"盲变异与选择性保留"，进化论是它的无意识版本——后文你会看到，第三、四、六阶段就是这个内核本身，第一、二阶段是杜威加上的问题构造前端，第五阶段是决策论加上的行动后端。

第五阶段的插入处，藏着整个框架里最硬的一条分界线，它的依据来自休谟：实然推不出应然。从阶段四到阶段五，思考发生了范畴切换——前面四个阶段问"什么是真的"（认知理性），第五阶段问"在稀缺约束下该做什么"（实践理性）。验证做得再完美，也不会自动告诉你该选哪个，因为"该"必须引入价值和约束。其他几条阶段边界都是渐变的，唯独这一条是断崖。

最后一句提醒：阶段是螺旋而非直线，走到后面发现前面错了，就退回去重走——文末的使用说明会再回到这一点。

第一阶段：定义问题 —— 哲学的领地

有一句被广泛归到爱因斯坦名下、但其实查无实据的话：如果给我一小时拯救世界，我会花五十五分钟弄清楚问题是什么。无论它出自谁口，道理都不假——绝大多数低质量的思考，败在第一步：解了一个错误的问题。

1. 苏格拉底诘问法：把模糊的词钉死

哲学贡献的第一个工具，是苏格拉底在雅典街头用了一辈子的方法：对每一个关键概念连续追问"你说的 X 到底是什么意思？"

"我想做一个更好的产品"——什么叫"更好"？对谁更好？用什么衡量？"团队效率太低了"——"效率"指交付速度、单位产出还是返工率？你会发现，很多争论吵了三小时，其实双方说的根本不是同一个东西。概念没钉死之前，一切讨论都是空转。

谱系：柏拉图对话录中的"诘问法"（elenchus），公元前五世纪。它暗含一个预设——概念都有可定义的本质；两千多年后维特根斯坦用"家族相似"反驳：多数日常概念（比如"游戏"）根本没有统一定义。所以钉概念时求的不是完美定义，而是"本次讨论内大家用同一个定义"。

2. 第一性原理：把问题拆回不可再拆的事实

这个词源自亚里士多德，因马斯克而流行：不要从"大家都这么做"出发推理（类比思维），而要从"哪些事实是物理上确定为真的"出发，重新往上搭。

经典案例是电池：类比思维说"电池历史上一直很贵，所以未来也贵"；第一性原理问"电池由哪些原料构成？这些原料在市场上值多少钱？"——答案是材料成本只占售价的一小部分，剩下的都是可以被重新设计的环节。

谱系：亚里士多德《形而上学》中的 ἀρχή（本原）；《后分析篇》主张一切证明最终要落在不证自明的起点上——这是知识论中"基础主义"的源头，笛卡尔的普遍怀疑是同一个动作。但地基并不如听起来牢固：古希腊怀疑论的"阿格里帕三难"指出，任何辩护链要么无穷回溯、要么循环、要么武断地停下。实践中我们选择第三种，所以要记住：你的"事实清单"本身也可错。

3. 问题的转译：你真正要解决的是什么？

哲学训练里还有一个朴素但锋利的习惯：区分表层问题和底层问题。电梯太慢，表层方案是换电梯；但底层问题可能是"等待让人烦躁"，于是在电梯旁装一面镜子，抱怨就消失了。在动手之前，多问一句："这个问题，是什么更大问题的症状？"

谱系：杜威《我们如何思维》把"感到困难"与"界定问题"分为两个独立步骤，正是承认两者经常不一致；设计思维把这一步制度化为"问题重构"（reframing）。

本阶段输出：一句话写清楚"我要解决的问题是 _，判断解决与否的标准是 _"。写不出来，就不要进入下一阶段。

第二阶段：拆解与建模 —— 数学和物理的看家本领

问题定义清楚后，它通常还是太大、太复杂。第二阶段的任务是：把它变小、变简单、变得可以下手。

4. 抽象与分治：数学家的两板斧

抽象，是丢掉无关细节、只保留问题骨架的能力。数学家不关心是七个苹果还是七头牛，只关心"7"。面对复杂问题时先问：去掉所有表面信息后，这个问题的结构是什么？它像不像某个我已经会解的问题？

分治（Divide and Conquer），是把一个解不动的大问题切成几个能解的小问题。关键在于切口要"正交"——子问题之间尽量互不纠缠，否则切了等于没切。

谱系：抽象自欧几里得以来就是数学的本体。分治的经典表述是笛卡尔《谈谈方法》（1637）第二条规则——"把所考察的每个难题分成尽可能多的小部分，直到可以妥善解决为止"，三百年后成为算法设计的支柱。

5. 理想化模型：物理学家的"无摩擦斜面"

物理学的核心方法不是数学，而是敢于简化。伽利略研究落体时假设没有空气阻力，力学里全是"质点""刚体""理想气体"——全是现实中不存在的东西，但正是这些"错误"的模型让问题变得可解。

实践版本是：先建一个粗糙但能算的模型，再逐步加回被忽略的因素。 先假设用户都是理性的、网络永远不抖动、需求不会变，把主干逻辑跑通；然后一项一项放回现实的复杂性，看哪一项真正改变了结论。

谱系：伽利略的理想斜面是近代科学的起点——他第一个意识到"先研究不存在的简化世界"比直接面对混乱的现实更有效。统计学家乔治·博克斯的总结后来成了行规："所有模型都是错的，但有些是有用的。"

6. 费米估算与量纲检查：快速逼近数量级

费米能用"芝加哥有多少调音师"这类问题训练学生：把一个无从下手的量，拆成几个可以粗略估计的因子相乘。误差会互相抵消，结果往往能对到数量级。很多决策不需要精确答案，只需要知道是 10 还是 10000。

配套的工具是量纲分析：算完之后检查单位对不对、数量级合不合理。一个"每天新增 300 万用户"的估算，乘上 365 天就会暴露荒谬。这是成本几乎为零的纠错手段。

谱系：估算法以费米命名；量纲分析的源头是傅里叶，经瑞利发扬，由白金汉 π 定理（1914）系统化——物理方程两边量纲必须一致，这条朴素的约束强到有时能直接猜出公式的形状。

本阶段输出：一个简化的模型或拆解图——哪些因素被保留，哪些被暂时忽略，心里有数。

第三阶段：推理与探索 —— 演绎、归纳与思想实验

模型建好了，现在要在模型上推理，生成候选答案。

7. 演绎、归纳与溯因：三种推理引擎

逻辑学区分了三种推理：演绎（从一般到特殊，前提为真则结论必真）、归纳（从样本总结规律，结论只是大概率）、溯因（从结果倒推最可能的原因——医生诊断、工程师排查 bug 用的都是它；候选解释打架时，先举奥卡姆剃刀：优先采信假设最少的那个）。

关键不是会用哪一种，而是清楚自己此刻在用哪一种。把归纳出来的经验当成演绎般的铁律（"前三次都是缓存问题，这次一定也是"），是排查问题时最常见的陷阱。

谱系：演绎源自亚里士多德的三段论，1879 年由弗雷格彻底形式化；溯因由皮尔士在十九世纪末命名，哈曼后来称之为"最佳解释推理"——但"最佳解释凭什么更可能为真"至今没有公认答案；奥卡姆剃刀以十四世纪经院哲学家奥卡姆的威廉命名，"如无必要，勿增实体"这句流行表述其实是后人的提炼。归纳的地基则是哲学史上最著名的一次塌方：休谟（1748）证明，"过去如此，所以未来也将如此"无法被非循环地证成——你只能用归纳本身来为归纳辩护。这就是"归纳问题"。其后的主要应答——康德的先验范畴、波普尔的证伪主义（第 11 节）、贝叶斯主义（第 15 节）——后文都会遇到，而古德曼 1955 年的"绿蓝悖论"证明问题比休谟说的还深。连演绎也不能幸免：刘易斯·卡罗尔的《乌龟对阿喀琉斯说了什么》（1895）表明，推理规则本身无法靠推理证成。我们使用这三台引擎，但没有一台的地基是焊死的。

8. 反证法与极端情形：数学家的探针

反证法：先假设结论不成立，看会推出什么荒谬。日常版本是"假设这个方案是错的，那它最可能错在哪？"——这比正面论证更容易暴露盲点。

极端情形检验：把参数推到 0、推到无穷大，看结论还成立吗。"如果用户量是现在的 1000 倍，这个架构会先在哪里崩？""如果只剩一个人维护，这套流程还能转吗？"极端值是最便宜的压力测试。

谱系：已知最早的反证法杰作，是毕达哥拉斯学派对"√2 是无理数"的证明；它依赖的矛盾律被亚里士多德称为"一切原理中最确实的"。一个值得知道的例外：直觉主义数学家（布劳威尔）拒绝其中一类用法——不允许从"不存在会导出矛盾"直接断言"存在"。日常思考用不到这条戒律，但它提醒我们：连反证法的边界都曾被认真争论过。

9. 思想实验与对称性：物理学家的想象力

爱因斯坦追着光跑，得出相对论；麦克斯韦养了一只分拣分子的"妖"。思想实验是在头脑中搭建实验室，用想象力运行现实中做不了的实验。 决策中的对应物是哲学家罗尔斯的"无知之幕"：假如你不知道自己会是这个规则下的哪一方，你还会制定这个规则吗？

物理学还贡献了对称与守恒的直觉：变化中寻找不变量。系统再复杂，总有些东西是守恒的——预算总量、总时间、信任。"这个方案号称三方共赢，那成本守恒地转移到谁头上了？"

谱系：思想实验的第一个杰作就出自伽利略——"重物落得更快"可以纯靠想象推出矛盾（把大小两块石头绑在一起，按亚里士多德的理论会同时推出更快和更慢）；"思想实验"（Gedankenexperiment）一词由物理学家奥斯特创造，经马赫之手才成为自觉的方法论；它的认识论地位至今有争论，诺顿认为思想实验只是化了妆的论证。"无知之幕"出自罗尔斯《正义论》（1971）。守恒直觉的地基则是全文工具里最硬的——诺特定理（1918）：每一个连续对称性严格对应一个守恒量（时间平移对称 ⇒ 能量守恒）。它是被证明的定理，不是启发式；把守恒用到预算和信任上当然只是类比，但这个类比的母版极其可靠。

10. 逆向思维：反过来想，总是反过来想

数学家雅可比的名言"反过来想，总是反过来想"（Invert, always invert），被芒格奉为终身信条。与其问"怎样让项目成功"，不如先问"怎样能确保它失败"——然后把清单上的每一条都避开。失败的路径远比成功的路径清晰可枚举。

芒格自己最著名的一次示范，是 1986 年在哈佛西湖学校的毕业演讲：别人讲如何获得幸福，他通篇讲"如何保证自己过上悲惨的一生"——嫉妒、怨恨、反复无常、不从别人的教训中学习、遭遇挫折就一蹶不振。把每一条反过来执行，就是答案。

谱系：雅可比说的本是数学实践——许多问题从反面看结构更简单，这背后是数学中无处不在的对偶性；芒格把它从数学搬进了生活与投资。

本阶段输出：不止一个候选方案。只有一个选项的时候，你其实没有在思考，只是在服从。

第四阶段：验证与纠错 —— 科学方法与心理学的主场

到这里你手上已经有了几个看起来不错的候选答案。第四阶段的全部要义是：你的大脑此刻最想做的事是证明自己是对的，而你要逼它做相反的事。

11. 可证伪性：波普尔的分界线

科学哲学家波普尔指出，科学与非科学的分界不在于"能否被证实"，而在于"能否被证伪"。一个怎么样都对的理论（"这都是命运的安排"）不传递任何信息。

实践方法：为你的结论写下证伪条件——"如果观察到 X，我就承认这个判断错了"。写不出 X 的判断，不叫判断，叫信仰。然后，主动去找 X，而不是等它撞上来。

波普尔本人的顿悟就来自一次真实对照：1919 年爱丁顿率队远征观测日全食，检验广义相对论预言的星光偏折——爱因斯坦把脖子伸进了铡刀，数据不符理论就死；而同时代的弗洛伊德学说，在波普尔看来无论病人怎么表现都能自圆其说。一边敢于被杀死，一边永远正确，分界线由此画下。

谱系：波普尔《科学发现的逻辑》（1934）。值得知道它的动机：波普尔全盘接受了休谟对归纳的判决（见第 7 节），然后釜底抽薪——科学根本不靠归纳，理论永远只是猜想，科学的全部理性就在于高效地淘汰错误猜想。后续的重要修正是迪昂—蒯因论旨：单个假设永远无法被孤立证伪，你总可以把锅甩给辅助假设（"是仪器坏了"）；拉卡托斯由此区分"进步的"与"退化的"研究纲领——一个靠不断打补丁才活着的信念，就是退化的。给自己的信念做这个检查，相当残忍，也相当有效。

12. 确认偏误与系统 1/系统 2：知道大脑会在哪里骗你

心理学家卡尼曼把思维分成两套系统：系统 1 快速、自动、靠直觉；系统 2 缓慢、费力、讲逻辑。麻烦在于系统 1 永远在线，并且擅长伪装成理性——你以为自己在推理，其实在为直觉找借口。

最危险的几个偏误值得点名：确认偏误（只看见支持自己的证据）、锚定效应（第一个数字绑架后续判断）、损失厌恶（损失的痛苦约是同等收益快乐的两倍，所以人会死守沉没成本）、幸存者偏差（二战时军方想给返航轰炸机上弹孔密集的部位加装甲，统计学家沃尔德指出该加固的恰恰是没有弹孔的部位——那些地方中弹的飞机没能飞回来）。纠错的第一步不是"更努力地客观"，而是承认自己此刻大概率正在偏，然后用流程对冲——比如强制写下反方观点，或者找一个真敢说话的人当红队。

谱系：卡尼曼与特沃斯基 1970 年代开创"启发式与偏差"研究纲领（《思考，快与慢》是其大众版总结）；再深一层是西蒙 1950 年代的"有限理性"：偏差不是大脑的 bug，是有限算力下的工程妥协。要听反方：吉仁泽论证许多启发式在真实环境中是"生态理性"的，比完整计算更快也常常更准；"损失厌恶约两倍"的普适性在近年文献中也有争议。结论：偏差清单是路标，不是判决书。

13. 相关不等于因果：一起出现，不代表谁导致谁

上一节的偏误是大脑主动骗你，这一节的陷阱藏在数据里：两个变量总是一起涨落，不代表其中一个导致了另一个。 冰淇淋销量和溺水人数高度正相关，但不是冰淇淋让人淹死——背后是"夏天"这个共同原因（混淆变量）。看到相关，至少有四种可能并存：A 导致 B、B 导致 A、第三个因素 C 同时推动两者、纯属巧合。

实践纪律：行动之前先找混淆变量，问一句"有没有一个 C 同时驱动了两边"；能做随机对照实验（把样本随机分成两组）就做，做不了就把结论的可信度降一档。一个隐蔽的变种是辛普森悖论——同一份数据，分组看和合并看可以得出完全相反的结论。

谱系：休谟早就指出我们从未"看见"因果，只看见恒常的先后相继（又是第 7 节那个归纳问题的源头）；把因果推断变成可操作工具的是统计学——费希尔的随机对照实验（1920 年代）与朱迪亚·珀尔的因果图和 do-演算（1990 年代）。"相关不蕴含因果"人人会背，难的从来是识别出那个具体的混淆变量。

14. 外部视角与基础概率：先看同类，再看自己

预测一件事会怎么收场，有两条路。内部视角盯着这件事本身的细节推演："我们团队强、计划周密，三个月能上线。" 外部视角先问一句："同类的事，通常是什么结局？"——类似规模的项目，有多少按时上线？延期的中位数是多少？人天然偏爱内部视角，而它系统性地过度乐观，这就是规划谬误：几乎每个大工程都超期超预算，因为每个团队都觉得"我们不一样"。

纠错动作只有一个：任何预测，先给它找一个参照类，拿这群同类的真实分布当锚，再根据本案的特殊性做有限调整。基础概率是你的起点，不是可以略过的背景板。

卡尼曼讲过自己的亲历：他带队编一本教材，组内乐观估计两年完成；他追问一位资深成员"你见过的同类项目平均花多久、有多少半途夭折"，答案是七到十年、约四成流产。他们没把这个外部数据当回事，结果用了八年——明知基础概率，仍败给了内部视角。

谱系：卡尼曼与洛瓦洛 1993 年区分"外部视角 vs 内部视角"；其操作化是参照类预测（reference class forecasting），弗吕夫别格用它系统改进大型基建的成本预估，已被多国政府写进规范。它和下一节的贝叶斯是一体两面：外部视角给你一个像样的先验，贝叶斯告诉你拿到新证据后该把它移动多少。

15. 贝叶斯更新：把信念当概率来维护

贝叶斯定理的日常版本是：信念不是非黑即白的开关，而是随证据滑动的概率。 拿到新证据时问三个问题：我原来的把握是多少（先验）？如果我是对的，看到这个证据的可能性多大？如果我是错的呢？

凯恩斯（据传）说过："事实变了，我的想法就跟着变。你呢，先生？"贝叶斯主义者的美德不是立场坚定，而是更新得快、且更新的幅度恰如其分——不因一个反例全盘推翻，也不无视十个反例岿然不动。

这套朴素的算法找到过飞机残骸：2009 年法航 447 航班坠入大西洋，两年搜索一无所获；2011 年搜索方请来贝叶斯搜索专家，把此前每一次失败都当作证据，更新海底各区域藏有残骸的概率分布，新一轮搜索开始一周内就找到了机身。同样的方法在 1968 年定位过沉没的"天蝎号"核潜艇。

谱系：贝叶斯（1763 年遗作）与拉普拉斯。它有两个罕见地硬的证成：Cox 定理证明，满足几条合理性公理的"可信度"运算必然就是概率论；德·菲内蒂的"荷兰赌"论证则证明，不按概率公理行事的人，可以被构造出一组稳赚不赔的赌局收割。换句话说：拒绝贝叶斯更新不只是固执，是可以被定价的固执。

16. 事前验尸：在失败发生前开追悼会

心理学家加里·克莱因发明的 Premortem（事前验尸）：在方案启动前，全员假设"现在是一年后，这个项目已经惨败"，然后每个人写下失败的原因。这个简单的换框，能把"提出担忧"从扫兴变成任务，挖出平时没人敢说的风险。一个人也能用：给一年后的自己写一封失败信。

克莱因在原文里记了一例：一家财富 50 强级别的公司启动一个十亿美元级的可持续发展项目，事前验尸会上，一位高管写下的死因是——力挺它的 CEO 一退休，项目就会失去靠山。这种话在动员会上没人敢说，在"追悼会"上脱口而出。

谱系：克莱因 2007 年发表于《哈佛商业评论》；其实验基础是 1989 年的"前瞻性后见之明"研究——让人假设结果已经发生，对原因的想象会具体生动得多。

本阶段输出：一份证伪条件清单 + 一份事前验尸报告。你的方案被自己攻击过之后还站得住，才有资格进入决策。

第五阶段：决策与行动 —— 经济学与工程学接管

验证过的方案可能仍有好几个，而资源只有一份。第五阶段从"求真"切换到"权衡"——还记得第零章里休谟那条断崖吗？就是从这里跨过去的。

17. 机会成本与边际思维：经济学的两块基石

机会成本：一个选择的真实成本，不是你付出了什么，而是你因此放弃的最好的那个选项。"这件事值不值得做"是个伪问题，真问题是"这件事比我能做的其他事更值得吗"。

边际思维：决策永远看增量，不看总量。不要问"要不要做营销"，要问"多投这一块钱营销，能多换回多少"。与之配套的是对沉没成本的铁律：已经花掉的钱、投入的感情、写完的代码，与未来的决策无关——尽管损失厌恶会拼命让你觉得有关。

斩断沉没成本最著名的一刀发生在 1985 年的英特尔。存储器是公司起家的业务，被日本厂商打得节节败退，却谁也下不了手。格鲁夫问摩尔："如果董事会把我们换掉，新来的 CEO 会怎么做？"摩尔答："退出存储器。"格鲁夫说："那为什么我们不自己走出这扇门，再走回来，亲手去做？"新 CEO 不背旧账——这个思想动作的全部内容，就是把沉没成本清零。英特尔从此转向处理器。

谱系：1870 年代的"边际革命"——杰文斯、门格尔、瓦尔拉斯几乎同时独立提出，经济学从此从"价值由什么决定"转向"增量如何比较"；机会成本由维塞尔命名。地基是稀缺性公理：只要资源有限，选择就必然意味着放弃。

18. 期望值与不对称性：和不确定性共处

理性决策的骨架是期望值：收益 × 概率。但真正的高手还看分布的形状——塔勒布称之为不对称性：下行有限、上行巨大的事（写作、开源、社交中的善意）值得反复做；上行有限、下行致命的事（加杠杆、单点依赖、灰色地带）一次都嫌多。永远不要冒会被踢出局的风险，不管期望值多漂亮。

反面教材是长期资本管理公司（LTCM）：合伙人名单上有两位诺贝尔经济学奖得主，每笔套利的期望值都为正，于是加上约 25 倍杠杆反复下注。1998 年俄罗斯国债违约，一次尾部事件就把它彻底踢出了局，最后由美联储出面组织救助。每一步的期望值都对，错的是他们在玩一个不允许输一次的游戏。

谱系：1654 年帕斯卡与费马为分赌金问题通信，概率论由此诞生；冯·诺伊曼与摩根斯坦 1944 年完成期望效用的公理化。裸期望值的毛病很早就暴露了——伯努利 1738 年的圣彼得堡悖论；而"别冒出局风险"的现代数学依据是遍历性问题（物理学家彼得斯）：时间平均不等于集合平均，一个期望值为正的赌局，对必须连续下注的个体可以是毁灭性的。塔勒布说的就是这个。

19. 激励与博弈：对面也有人

机会成本和期望值都默认你在和"自然"打交道——成本和概率不会因为你的选择而改变。但多数真实决策的对面，坐着会预判你、回应你的人。这时要加两道检查。一是激励：判断一个人或机构会怎么做，看它的激励结构，远比听它的承诺可靠——芒格的版本是"给我看激励，我就给你看结果"。二是对手的最优应对：把别人的反应算进方案里——"我降价，对手会不会跟？跟了之后我还赚吗？"一个不考虑回应的计划，是写给静止世界的。

激励压倒口号的教科书案例是 2016 年的富国银行：总部给柜员定下"每位客户交叉销售八个产品"的硬指标并与薪酬挂钩，于是员工在客户不知情的情况下开出了约三百五十万个虚假账户。每个人都在对激励做理性应对，加总起来是一场灾难——口号说的是服务客户，激励奖的是开户数量，员工听激励的。这就是古德哈特定律：一个指标一旦被当成考核目标，它就会被人们冲着数字去优化，从此不再是它原本想衡量的那件事。

谱系：博弈论与第 18 节的期望效用出自同一本书——冯·诺伊曼与摩根斯坦《博弈论与经济行为》（1944）；纳什 1950 年的均衡概念把它推广到非零和情形。"看激励"的学术版是机制设计理论（赫维茨、马斯金、迈尔森，2007 年诺贝尔经济学奖）：干脆把激励当成可以被设计的对象。

20. 可逆与不可逆：贝索斯的两扇门

贝索斯把决策分成两类：双向门（错了可以退回来）和单向门（走过去就回不了头）。双向门决策应该快、便宜、授权给最近的人——此时拖延的成本远高于犯错；单向门决策才值得慢下来，把前四个阶段的工具全部用一遍。多数人的问题是用单向门的谨慎对待双向门，又用双向门的草率走过单向门。

亚马逊自己的单向门样本是 2005 年的 Prime：财务模型怎么算都算不平，而"免费两日达"一旦送出就几乎收不回来——从用户手里拿走既有的福利，代价远大于从未给过——贝索斯让团队反复推演后才拍板。与之对照，亚马逊网站上每天运行的几百个界面实验是标准的双向门：数据难看，当天下线。

谱系：贝索斯 2015 年度致股东信。学术对应物是西蒙的"满意化"（satisficing）：有限理性者的最优策略不是事事求最优，而是按决策的重要性分配认知预算。

21. 工程师的妥协艺术：没有最优，只有取舍

工程学贡献的核心世界观是：所有设计都是取舍（trade-off），快、好、便宜只能选两个。配套的方法是最小可行产品（MVP）：当分析无法继续降低不确定性时，停止分析，用最小的成本把方案推进现实，让现实接管验证——做，本身就是一种更高带宽的思考。

两个教科书案例都收录在《精益创业》里。Dropbox 的产品还没法公开使用时，创始人休斯顿先放出一段三分钟的演示视频，一夜之间候补名单从五千人涨到七万五千人——一行代码没多写，需求已经验证。Zappos 的创始人则先跑去附近鞋店把鞋拍照上架，有人下单他再原价买来寄出，用零库存证明了"有人愿意在网上买鞋"。

谱系：MVP 由埃里克·莱斯《精益创业》（2011）普及，但它的哲学根源要老得多——皮尔士和杜威的实用主义：观念的意义就在它的实际效果里，行动不是探究的结束，而是探究的一部分。

本阶段输出：一个明确的决定 + 它的机会成本 + 它是哪种门 + 最小的第一步。

第六阶段：复盘与迭代 —— 控制论与进化论收尾

行动不是思考的终点，而是下一轮思考的输入。

22. 反馈回路：控制论的核心

维纳的控制论把一切智能行为归结为反馈：输出被测量、与目标比较、误差被送回去修正输入。导弹是这么追上飞机的，恒温器是这么稳住温度的，人是这么学会骑车的。

推论很实际：系统的进步速度，取决于反馈回路的速度和保真度。 反馈周期一年（年度绩效）的系统，进化速度注定不如反馈周期一天（每日复盘）的系统。改进一件事最有杠杆的方式，往往不是更努力，而是缩短它的反馈回路。

谱系：维纳《控制论》（1948）；更早的数学化是麦克斯韦 1868 年的《论调速器》——为分析瓦特蒸汽机的离心调速器而写，被视为控制理论的第一篇论文。

23. 变异—选择—保留：进化论的算法

达尔文给出的或许是有史以来最强大的问题求解算法，它不需要任何智能就能造出眼睛和大脑：产生变异 → 环境选择 → 保留胜者 → 重复。

应用到个人和组织：保持小成本的多样化尝试（变异），用真实世界的反馈而非内部意见来筛选（选择），把验证过的做法固化成习惯和流程（保留）。注意三者缺一不可——只变异不保留是瞎折腾，只保留不变异是僵化。

商业史上最完整的一次三拍合奏是便利贴：3M 的化学家席尔弗发明了一种"失败"的弱胶水，怎么都粘不牢（变异）；几年后同事弗莱用它给唱诗班的赞美诗集做书签，发现"粘得住又撕得下来不留痕"正是无数人需要的（选择）；3M 把它固化成常设产品线，畅销至今（保留）。变异从哪来也有答案——3M 允许员工拿 15% 的工时做自选项目：组织无法设计出变异本身，但可以设计让变异得以发生的环境。

谱系：达尔文《物种起源》（1859）；坎贝尔 1960 年将其推广为"盲变异与选择性保留"——一切知识增长的普适算法。注意它与第 11 节波普尔的"猜想与反驳"是同构的：猜想即变异，反驳即选择。这不是巧合——这就是第零章说的那台发动机，整个六阶段框架深处运转的是同一个算法。

24. 元认知与刻意练习：对思考本身进行思考

心理学的收尾礼物是元认知：监控自己思考过程的能力。复盘时不仅问"结果对不对"，更要问"我当时的思考过程对不对"——好决策可能有坏运气，坏决策也可能有好结果，扑克牌手安妮·杜克称混淆这两者为 "resulting"，这是复盘中最隐蔽的错误。杜克的书开篇就是真实判例：2015 年超级碗最后 26 秒，海鹰队在一码线上选择传球而非地面冲锋，被对方拦截，痛失冠军，主教练卡罗尔被骂作"史上最蠢决策"；但按当时的时间、剩余暂停和该类传球约 1%—2% 的被拦截率算，传球是站得住的选择——人们只是用结果给过程定了罪。与它孪生的陷阱是均值回归：极端的结果之后大概率跟着更平庸的结果，这是纯粹的统计现象——把爆发后的回落归因于"自己松懈了"，把低谷后的回升归因于"整改有效"，复盘就成了给噪声编故事。

刻意练习的研究则提醒：单纯的重复不产生进步，带着明确目标、聚焦弱点、获取即时反馈的重复才会。思考方法本身也是技能，同样适用这条定律。

谱系：元认知由弗拉维尔 1976 年命名；均值回归由高尔顿（1886）在身高遗传研究中发现；刻意练习是埃里克松 1993 年的研究纲领——"一万小时定律"是格拉德威尔的简化转述，埃里克松本人并不认账；后续元分析（麦克纳马拉，2014）表明刻意练习能解释的成绩差异比流行说法小得多。方向有效，幅度别神化。"resulting"出自安妮·杜克《对赌》（2018）。

本阶段输出：写下来。没有写下来的复盘，两周后就会被记忆篡改成"我早就料到了"（后见之明偏差，心理学的最后一击）。

全图：一张速查表

三点使用说明：

第一，阶段是螺旋而非直线。 验证阶段发现问题定义错了，就退回第一阶段——这不是失败，这恰恰是流程在起作用。真实的思考是在六个阶段之间反复横跳的。

第二，不是每次都要走全程。 双向门的小决策，用直觉加一个快速的"反过来想"就够了；单向门的大决策，才值得把六个阶段完整走一遍。而面对单向门时，最有杠杆的一步往往是先把它转译成一个双向门问题——"要不要花一年写一本书"，先变成"把其中一章写成文章发出去，有没有陌生人愿意读、愿意转"，后者用一个周末的最小实验就能开始回答。对工具的选择本身，就是一种判断力。

第三，工具不会自动生效。 知道确认偏误的人照样确认偏误，背熟沉没成本的人照样舍不得割肉。这些方法只有变成写下来的清单和固定的流程——决策前强制写证伪条件、项目前强制开事前验尸会——才能在你最需要它们、也最不想用它们的时刻起作用。

芒格说，他这一生不过是"手里拿着几个大观念，耐心等待"。这个工具箱里的二十四件工具，每一件背后都站着一个学科上百年甚至上千年的打磨——有些工具的地基至今还在哲学家手里返修，但这不妨碍它们好用，正如你不需要等量子引力完工才使用牛顿力学。你不需要发明新的思考方法，你只需要在对的阶段，伸手拿对的那一件。

模型越来越聪明，为什么 Agent 还是动不动就翻车？答案不在模型里，而在模型外面那一圈工程系统——harness。本文从概念讲到实战，附带可直接照抄的检查清单。

一、先看一个反直觉的事实

同一个 Claude / Codex 模型，同一道任务，换两套"外壳"，成功率能从 20% 跳到接近 100%——模型一个字没改。

这是 learn-harness-engineering 课程（见底部参考文档）里反复出现的实测结论：一个 TypeScript/React 项目，只给模型一个 README 时成功率约 20%；把"规则、状态、验证"这套外壳补齐后，成功率逼近 100%。没有换模型，只换了 harness。

OpenAI 的案例更极端（2026 年 2 月，Ryan Lopopolo）：一支小队从 2025 年 8 月底的空仓库起步，约五个月里 0 行人工代码，每一行都由 Codex 生成，最终产出约 100 万行代码（含应用逻辑、基础设施、工具链与文档）、1500 个合并的 PR，团队从 3 人涨到 7 人、人均吞吐反而上升到 每人每天 3.5 个 PR。这群人几乎没碰业务代码，他们在干一件事——设计让模型可靠产出代码的环境。据他们估算，整体只花了手写代码约 1/10 的时间。

这件事现在有了名字：Harness Engineering（脚手架工程 / 框架工程）。

一句话定义：

Agent = Model + Harness。 模型负责"聪明"，harness 负责"可靠"。

二、什么是 Harness？

最常见的误解：以为 harness 就是一个写得好的 system prompt，或者一个 CLAUDE.md 文件。错。

各家给的定义高度一致，核心都是同一句话：

Harness = 模型权重之外，所有决定"智能能落地多少"的工程基础设施。 （LangChain 的说法："every piece of code, configuration, and execution logic that isn't the model itself."）

它包括但远不止 prompt：工具的定义与执行、文件系统与沙箱、状态持久化、验证机制、上下文管理、子智能体编排、确定性的钩子/中间件（compaction、续跑、lint 拦截等不靠模型自觉、由代码强制执行的环节）、可观测性……

打个最贴切的比方：

把 Agent 当成一个今天入职的资深工程师。 他很聪明，但对你的代码库一无所知。他需要：项目文档、跑得起来的环境、能用的工具、知道"完成"的标准、以及交班记录。 这些东西的总和，就是 harness。你给的脚手架越完整，这个"新人"发挥出的能力就越接近他的真实水平。

关键洞察：今天 Agent 失败，多数不是"不够聪明"，而是"看不到 / 跑不动 / 不知道何时算完"——这些全是 harness 问题，不是模型问题。 这就是所谓的 capability–execution gap（能力与执行的鸿沟）。

三、Harness 的五个子系统

把一个完整的 harness 拆开，可以收敛成五个子系统。下面这套五分法综合自三处：WalkingLabs 的 learn-harness-engineering 课程、LangChain 的组件全景、以及 Anthropic 的长任务实践。建议按下面这张表逐项自查：

一点说明（各家划分并不完全一致）：learn-harness-engineering 课程原本的五件套是 Instructions / State / Verification / Scope / Session Lifecycle——把"会话生命周期"单列为一项。本文改用更贴近 LangChain/Anthropic 的切法：把"工具与环境"（两家都重点强调，且最直接决定 Agent 能否跑得起来）提为核心一项，而把"会话生命周期"并入第四节的长任务方法（初始化/执行分离、干净重启）。子系统怎么命名、归到几项都不重要，别漏项才重要。

                ┌─ Instructions  指令：项目是什么、约束是什么
                ├─ Tools/Env     工具与环境：能做什么、跑得起来
   Harness ─────┼─ State         状态：上次进行到哪了
                ├─ Scope         边界：这次只做一件事，做到什么算完
                └─ Verification  验证：怎么自证做对了

下面逐个拆。

1. Instructions：把"新人须知"写进仓库

原则不是"写得越多越好"，而是 progressive disclosure（渐进式披露）：一个 100 行左右的核心指令文件，说清楚项目是什么、技术栈、首次运行命令、不可违反的约束、文档入口。细节按需链接出去，而不是一次性糊一篇百科全书给模型——后者只会稀释注意力。

核心铁律：仓库即唯一事实来源（repo as the system of record）。 Agent 不能像人一样转头问同事，凡是它需要的东西，必须在仓库里看得到。

2. Tools / Environment：少给约束，多给能力

• 工具权限遵循 最小权限，而不是一律禁掉——限制过严，Agent 就只能靠猜测。
• 环境要自描述、可复现：依赖文件、运行时版本、容器配置都齐了，Agent 才能一键起服务。Anthropic 的实践里专门有个 init.sh 负责拉起开发环境。
• 一个被低估的能力：给 Agent 一个能跑 bash / 执行代码的沙箱。比起预置一堆窄工具，"能自己写代码并运行"才是通用自治的关键——它能自己验证、自己排错。

3. State：像倒班工人一样交接

长任务跨越多个上下文窗口，每个新会话都是一张白纸。Anthropic 把这比作"轮班的工程师之间没有交接文档"。

解法是把状态落盘：

• 进度文件（claude-progress.txt / PROGRESS.md）记录：做完了什么、正在做什么、卡在哪。
• 用 git 提交和提交信息留下可追溯的痕迹。
• 每个会话开始先读进度和 git log，结束前更新进度。

效果：有 harness 时，Agent 能精确地"从上次断点接着干"；没有时，它要么重做，要么每次从头开始。

4. Scope：一次只做一件事

Agent 的通病是贪多——一次想实现过多功能，结果哪个都没做完。

Anthropic 的做法很直接：把任务拆成 200+ 条颗粒度极细的 feature list，每条标注 pass/fail，用 JSON 而不是 Markdown（JSON 结构化，模型更不容易擅自改写）。每个会话只做一个 feature，做完、测过、提交、更新进度，再进下一个。

5. Verification：把"好不好"变成"过没过"

这是投入最低、回报最高的子系统，也是最容易被忽略的。

模型有两个致命倾向：

1. 过早宣布胜利——没测就说"做完了"。
2. 自我表扬——让它评价自己的产出，它几乎总说"很棒"，哪怕在人看来一塌糊涂。

对策：

• 在文档里显式列出验证命令（test / lint / typecheck），让 Agent 每次都能跑。
• 对 Web 应用，要求用浏览器自动化（如 Puppeteer MCP）做端到端验证，而不是"看起来对就行"。Anthropic 实测这一条让"功能真的可用"的准确率大幅提升。
• 把主观质量变成可打分的客观标准。Anthropic 做前端时，把"好不好看"这种主观判断拆成四个可评维度：design quality、originality、craft、functionality，再用 few-shot 例子校准评审者。

四、长任务的进阶方法

短任务把上面五件事做好就够了。但当任务要跑几个小时、跨几十个上下文窗口时，还需要三个进阶模式。

1. 初始化 Agent 与执行 Agent 分离

Anthropic 的长任务 harness 是双角色架构：

• Initializer Agent（初始化）：第一个会话搭地基——写 init.sh、建进度文件、做首次 git 提交、生成那份 200+ 条的 feature list。
• Coding Agent（执行）：后续每个会话遵循固定流程——读进度 → 先跑 E2E 冒烟测试 → 完成一个 feature → 提交 → 更新进度，离场时必须留下可合并的干净状态。

2. 生成与评估分离（Generator / Evaluator）

不要让同一个 Agent 既当运动员又当裁判。独立的生成者和评估者能破解"自我表扬"。评估者只在任务超出"单个模型独自能可靠完成"的范围时才值得加——任务很简单时，这套开销反而是浪费。

Anthropic 的经典对照实验：一句话 prompt 让做个复古游戏。

• 单个 Agent 独自跑（solo run）：$9、20 分钟，产出一个跑不起来的应用。
• 三 Agent harness（规划+生成+评估）：$200、6 小时，产出一个能玩、UI 精致的游戏。

质量差距撑得起这笔投入——前提是任务确实难。

3. 上下文重置 优于 上下文压缩

当模型感到"token 快用完了"会出现 context anxiety（上下文焦虑）——提前匆忙收尾。直觉做法是把历史**压缩（compaction）**塞进新窗口；但 Anthropic 发现，直接清空上下文、配合结构化的交接产物（progress 文件 + feature list）重新开始，效果反而更好。这也呼应 LangChain 说的 "Ralph Loop"：在干净的新窗口里重新注入 prompt，对抗 context rot（上下文腐烂）。

五、案例深读：OpenAI 的 100 万行代码是怎么撑住的

OpenAI 这篇《Harness Engineering: Leveraging Codex in an Agent-First World》是目前最翔实的实战记录。把它拆开看，几乎每条经验都能对应回前面的五个子系统——但有几个点足够反直觉，值得单独讲。

1. 工程师的角色变了：不写代码，造环境

早期进展比预期慢，原因不是 Codex 不行，而是环境欠规约——Agent 缺工具、缺抽象、缺内部结构。于是工程师的核心工作变成一句话："缺了什么能力，怎么把它做得对 Agent 既可见又可强制？"

出问题时，修法几乎从不是"让模型再努力一点"，而是回头补 harness。人只在更高的抽象层工作：排优先级、把用户反馈翻译成验收标准、验证结果。连修复也是让 Codex 自己写。

2. 给地图，别给一千页手册

他们一开始也试过"一个大 AGENTS.md"，失败得很典型：

• 上下文是稀缺资源——大文件把任务、代码、相关文档全挤出去了；
• 全是重点 = 没有重点——Agent 退化成局部模式匹配；
• 瞬间腐烂——很快堆满过期规则、无人维护；
• 难以校验——一整块大文件没法做机械检查（覆盖率、新鲜度、交叉链接）。

改法：把 AGENTS.md 当目录（table of contents），不当百科全书。 一个约 100 行的 AGENTS.md 只做"地图"，真正的事实来源放在结构化的 docs/ 目录里——设计文档、执行计划（active/completed/技术债追踪）、生成的 DB schema、产品规格、*-llms.txt 参考资料等。计划是一等公民：小改动用临时轻量计划，复杂工作落成签入仓库的执行计划，带进度和决策日志。

这就是 渐进式披露：Agent 从一个小而稳的入口进入，再被"教"去哪里找下一步。而且机械强制——专门的 linter 和 CI 校验知识库是否最新、是否交叉链接；还有个**"doc-gardening"（文档园丁）Agent** 定期扫描过期文档、自动提修复 PR。

3. 一句最该记住的话：Agent 看不见的，就等于不存在

From the agent's point of view, anything it can't access in-context while running effectively doesn't exist.

那条对齐了团队架构的 Slack 讨论？如果 Agent 检索不到，它就跟"三个月后入职的新人不知道"一样不存在。结论：不断把上下文塞进仓库——代码、markdown、schema、可执行计划，这些才是 Agent 唯一看得见的东西。

由此推出一组反直觉取舍：优先选 Agent 能完全内化的依赖和抽象。所谓"无聊"的技术因为 API 稳定、可组合、在训练集里出现多，反而更好被模型建模。有时候自己重写一个子集，比绕开一个不透明的上游库更划算——他们没用通用的 p-limit，而是手写了个 map-with-concurrency，深度集成自家 OpenTelemetry、100% 覆盖、行为完全可控。

4. 让应用本身对 Agent 可读（这是吞吐的真瓶颈）

代码吞吐上来后，瓶颈变成人的 QA 能力。对策是把 UI、日志、指标直接做得对 Codex 可见：

• 每个 git worktree 能独立启动一份应用实例，一个改动配一个实例；
• 把 Chrome DevTools Protocol 接进 Agent 运行时，做了 DOM 快照、截图、导航的 skill——Codex 能自己复现 bug、验证修复、对 UI 行为推理；
• 给每个 worktree 配临时的可观测性栈，Codex 用 LogQL 查日志、PromQL 查指标。于是 "保证服务启动 800ms 内完成"、"这四条关键链路里没有 span 超过 2 秒" 这种 prompt 变得可执行。

效果：单个 Codex run 经常连续干 6 小时以上（通常在人睡觉的时候）。

5. 强制不变量，而非微观管理

文档撑不住一个全自动生成的代码库的连贯性，架构约束才行。他们的口号是 "enforce invariants, not micromanage implementations"：

• 要求"在边界处解析数据形状"，但不规定怎么做（模型自己爱用 Zod，没人指定）；
• 整个应用建在刚性分层架构上：每个业务域固定分层（Types → Config → Repo → Service → Runtime → UI），依赖方向严格校验，横切关注点（鉴权、连接器、遥测、特性开关）只能从单一的 Providers 接口进入；
• 全部用 自定义 linter（当然也是 Codex 写的）和结构化测试机械强制；自定义 lint 的报错信息直接把修复指引注入 Agent 上下文。

一句点睛：这种架构本来是公司几百个工程师才需要的；有了 Agent，它成了一开始就得有的前提——约束正是"快而不失序"的前提。 原则是 "中心强制边界，局部允许自治"：严格守住边界、正确性、可复现；边界之内，给 Agent 充分自由。代码不总符合人类审美，只要正确、可维护、对未来的 Agent 可读，就达标。

6. 吞吐量改变了合并哲学

当 Agent 吞吐远超人的注意力时，很多传统工程规范反而有害：仓库几乎没有阻塞性的合并门禁，PR 短命，测试 flake 用"重跑一次"解决而非无限期阻塞。因为在这种系统里，纠错很便宜，等待很贵。——这在低吞吐环境下是不负责任的，在这里却往往是对的。

往深一层，这背后是整套工程实践的经济学内核：token、算力、Agent 工时都不再稀缺，唯一真正稀缺的，是"需要人同步介入"的那点注意力。 于是几乎所有工程决策都收敛到同一个目标——把人的同步注意力省到极致。合并门禁的取舍、QA 瓶颈的破解、后台自动清理，本质上都是在省这一项。看懂了这条，前面那些反直觉的取舍就都顺理成章了。

7. 熵与垃圾回收：把人的品味"编码一次，永久强制"

全自动也带来新问题：Codex 会复刻仓库里已有的模式，包括其中不好的，于是必然漂移。

他们一开始靠人手清——每周五（20% 的工时）专门清理 "AI slop"，根本不 scale。 真正的解法是把 golden principles（黄金法则） 编码进仓库，配一套周期性清理流程：

• 优先用共享工具包，把不变量收敛在一处，而不是到处手写零散的 helper；
• 不"YOLO-style"地探数据——而是在边界处校验、或用带类型的 SDK，避免 Agent 建在猜出来的数据形状上；
• 一组后台 Codex 任务定期扫描偏差、更新质量评分、提定向重构 PR——大多能一分钟内 review 完、自动合并。

这套机制像垃圾回收。技术债是高息贷款：持续小额偿还，永远好过让它复利滚大再痛苦集中还。 人的品味只需被捕捉一次，之后在每一行代码上被持续强制。

8. 自治的临界点

随着测试、验证、review、反馈处理、恢复都被编码进系统，这个仓库最近跨过了一道门槛：给一句话 prompt，Codex 能端到端地——校验当前状态 → 复现 bug → 录一段失败视频 → 实现修复 → 驱动应用验证 → 再录一段修复后的视频 → 开 PR → 回应人和 Agent 的反馈 → 检测并修复构建失败 → 只在需要判断时才升级给人 → 合并。

但他们明确提醒：这高度依赖该仓库特定的结构与工具投入，不要假设能直接泛化——至少现在还不能。

一句话收束这一节：人的纪律没有消失，只是从代码本身转移到了脚手架上。

六、方案对比：到底要做到哪一档？

按投入由轻到重，分三档：

• A. 裸 prompt —— 只给一个 README，什么都不补。
• B. 单 Agent + 五子系统 —— 补齐第三节那五项；一个 Agent，可跨会话。
• C. 多 Agent 全套 —— B 之上再叠第四节的进阶方法（初始化/执行分离、生成/评估分离、上下文重置）。

怎么选，看一个问题：这个任务，一个 Agent 在一个会话里能不能干完？

• 能，且做完即弃 → A
• 要持续迭代、跨多会话 → B（绝大多数情况）
• 一个 Agent 独自搞不定（几小时、跨几十个窗口、质量要求高）→ C

结论：

• 绝大多数团队的最优解是 B——投入产出比最高，是性价比最佳点。不要一上来就叠加多 Agent。
• C 只在任务"超出单个模型独自能力"时才划算：几小时以上、跨多窗口、质量要求高（如完整应用、复杂重构）。它总评不比 B 高，是因为简单任务里那套开销纯属浪费——复杂度要匹配任务难度。
• A 只适合一次性、用完即弃的探索。 任何要持续迭代的东西，停在 A 都会反复付出返工代价。

一个反复被验证的纪律：模型升级后，回头把 harness 逐件做消融测试（ablation）。 Anthropic 在 Opus 4.6 上就发现，模型变强后原来的"sprint 契约"机制可以整个删掉，质量不降、token 大降。Harness 不是只增不减——模型补上的能力，harness 就该减负。

七、照抄即用：Harness 自查清单

落地时，对着这张表勾一遍：

• Instructions
  • 有一个 ≤100 行的 AGENTS.md / CLAUDE.md，写清项目、技术栈、首次运行命令、红线约束
  • 细节走链接，不堆成百科全书
  • Agent 需要的一切都在仓库里（repo = 唯一事实来源）
• Tools / Environment
  • 依赖、运行时版本、容器配置齐全，可一键起环境（init.sh）
  • 给了能跑 bash / 执行代码的沙箱
  • 权限按最小权限给，而不是一刀切禁
• State
  • 有进度文件，记录"做完/在做/卡住"
  • 会话开始读进度+git log，结束前更新
  • 用 git 提交留痕
• Scope
  • 任务拆成机器可读的 feature list（建议 JSON）
  • 每会话只做一个 feature
• Verification
  • 文档里显式列出 test / lint / typecheck 命令
  • Web 应用有端到端验证（浏览器自动化）
  • 主观质量已拆成可打分的客观维度
• 长任务额外项
  • 初始化与执行 Agent 分离
  • 生成与评估分离（任务够难才上）
  • 用上下文重置 + 交接产物，而非一味压缩

八、为什么这件事会长期重要

有人会问：模型不是越来越强吗，等它足够聪明，harness 不就没用了？

恰恰相反。LangChain 和 OpenAI 的判断一致：模型越强，harness 的重心只是从"打补丁填模型的坑"转向"为智能优化系统"——但它不会消失。 就像今天模型早已不傻，prompt engineering 依然重要一样。

还有一层更硬的耦合常被忽略：今天的强模型，是和 harness 一起被训练出来的。 LangChain 指出，Claude Code 这类产品在后训练阶段就把"模型 + harness"放进同一个回路联调，模型被专门优化以适配它训练时的那套外壳。这也解释了一个反直觉现象——把一个强模型塞进一个陌生的 harness，往往跑不出它的真实水平。 模型与 harness 是共同进化的关系，不是谁迟早取代谁。

OpenAI 那句话点破了行业的转向：

在 agent-first 的世界里，工程师的主要工作不再是写代码，而是设计让 Agent 可靠产出的环境。

模型是发动机，harness 是底盘、传动和仪表盘。光有发动机，跑不远，也不安全。

附：参考文档

• LangChain — The Anatomy of an Agent Harness：Agent = Model + Harness 的组件全景。
• Anthropic — Effective harnesses for long-running agents：初始化 Agent、feature list、自验证的实战。
• Anthropic — Harness design for long-running apps：生成/评估分离、上下文重置、可打分质量。
• OpenAI — Harness Engineering: Leveraging Codex in an Agent-First World：100 万行代码与黄金法则。
• WalkingLabs — learn-harness-engineering（在线讲义）：12 讲 + 6 个动手项目的系统课程（五子系统框架的来源）。
• WalkingLabs — awesome-harness-engineering：资源合集（上下文、评估、护栏、编排、Benchmark）。

面向工程师与技术决策者的入门指南。从概念到实战，配套 Python SDK 示例。

一、为什么会有 MCP？

在 MCP 出现之前，把一个 AI 应用接入外部系统大致是这样一种状态：

• 想让模型查数据库？写一套 function calling 的 schema、写 handler、写权限校验。
• 想让模型读文件？再写一遍。
• 同一个"查 GitHub Issue"的能力，Claude 桌面端、Cursor、VS Code、自研 Agent，各写一遍。
• 工具多了之后，prompt 维护成本急剧上升，跨应用复用几乎为零。

这就是典型的 M × N 集成问题：M 个 AI 应用 × N 个数据源/工具 = M × N 套对接代码。

MCP（Model Context Protocol，模型上下文协议） 是 Anthropic 牵头、目前已成为事实标准的开放协议，目标是把这个 M × N 收敛为 M + N：

• 数据源/工具方只需要实现一次 MCP 服务端；
• AI 应用方只需要实现一次 MCP 客户端；
• 任意客户端都能即插即用地连接任意服务端。

官方一句话比喻：MCP 之于 AI 应用，相当于 USB-C 之于电子设备——一个统一的接口，连接万物。

二、一图总览

                          ┌─ Tools       (模型调用，有副作用)
              Server ─────┼─ Resources   (应用读取，只读上下文)
             /            └─ Prompts     (用户触发，工作流模板)
            /
        Client
       /
  Host
       \                  ┌─ Sampling    (Server 反向请求 LLM)
        Client ───────────┼─ Elicitation (Server 反向问用户)
             \            ├─ Roots       (Client 告知工作目录)
              \           └─ Logging     (Server 输出日志)
               Server

         数据层：JSON-RPC 2.0
         传输层：stdio（本地） / Streamable HTTP（远程，支持 OAuth）

• 传输层：Client 与 Server 之间用 JSON-RPC 2.0 通信，承载在 stdio 或 Streamable HTTP 之上。
• Server 原语：Server 主动暴露给 Host 使用的能力，分别面向模型（Tools）、应用（Resources）、用户（Prompts）三类不同的"决策者"。
• Client 原语：Client 暴露给 Server 反向调用的能力，让 Server 在不直接依赖 LLM/UI 的前提下也能完成 agentic 工作流。

三、三个最容易混淆的角色：Host / Client / Server

这是入门 MCP 时最容易绕晕的地方。它们三者的关系是这样的：

注意右下角 Server C 同时连接了两个 Client——远程 Server 通常服务多个 Client，而本地 stdio Server 一般是 1:1。

一个常见误解：以为 "Server" 一定是远程服务。错。Server 指的是协议角色，不是部署形态。 通过 stdio 启动的本地子进程同样是 Server。

四、协议的两层：数据层 + 传输层

MCP 的协议设计干净地分成了两层，便于在不同场景复用。

1. 数据层（Data Layer）

基于 JSON-RPC 2.0，定义消息的结构与语义。包含：

• 生命周期管理：连接建立、能力协商、连接关闭
• 服务端能力：tools、resources、prompts
• 客户端能力：sampling、elicitation、logging、roots
• 通知机制：列表变更、进度更新等

2. 传输层（Transport Layer）

负责把数据层的 JSON 消息从一端送到另一端。MCP 目前定义了两种官方传输：

旧版协议中还有一个独立的 SSE 传输，新规范已合并到 Streamable HTTP，新写代码请直接选 Streamable HTTP。

五、服务端三大原语：Tools / Resources / Prompts

这是日常开发中接触最频繁的部分。三者非常容易混淆，但它们的设计意图完全不同——关键差异在于"谁来决定调用"。

我喜欢这样记忆：

Tools 是动词，Resources 是名词，Prompts 是工作流。

Tools：模型主动调用

# 模型看到用户说"查下旧金山天气"，自己决定调用这个工具
@mcp.tool()
def get_weather(city: str) -> str:
    """获取某个城市的当前天气"""
    return fetch_weather_api(city)

相关方法：tools/list（发现）、tools/call（执行）。

Resources：应用按需读取

# 应用决定是否要把这段 README 塞给模型作为上下文
@mcp.resource("file:///{path}")
def read_file(path: str) -> str:
    return open(path).read()

每个资源有一个 URI（如 file:///README.md、postgres://mydb/schema），支持模板化（weather://forecast/{city}）。相关方法：resources/list、resources/templates/list、resources/read、resources/subscribe。

Tools vs Resources：完整链路与选型

光看"控制权"不够直观，对比一下两者的完整数据流：

Tools 的链路（模型回合内触发）：

1. Host 启动 → 调 tools/list 拿 schema
2. Host 把 schema 注入 LLM 调用的 tools 字段
3. 用户发消息 → LLM 推理 → 输出 tool_use 块
4. Host 截获 → 路由到对应 Server → 发 tools/call
5. Server 执行（跑 SQL、调 API）→ 返回 content
6. Host 把 content 作为 tool_result 拼回对话
7. LLM 继续生成（可能再触发下一轮，循环 3-6）

Resources 的链路（对话回合之外注入）：

1. Host 启动 → 调 resources/list 和 resources/templates/list
2. Host 把资源在 UI 上呈现（文件树 / @ 补全 / 自动建议）
3. 资源进入对话上下文的三种触发方式：
   a. 用户手动 @ 引用
   b. 应用启发式自动塞入
   c. 桥接为 Tool 让模型自主调用（下面详述）
4. Host 调 resources/read(uri) → Server 返回 contents
5. Host 把 contents 作为 user 消息的一部分发给 LLM
6. LLM 收到时是"已经在上下文里"的事实

一句话区分：

Tools 在 LLM 回合内被模型主动拉取；Resources 在 LLM 回合外被应用主动推入。

"数据但需要计算"选哪个？ 判断顺序：

1. 有副作用？ 有 → 必须 Tool（哪怕只是埋点）。
2. 要让模型自主决定调用？ → Tool。
3. 要让用户/应用预先选好作为上下文塞入？ → Resource Template。
4. 客户端生态考量：现状是 Tools 在所有 Host 上都支持，Resources 的 UI 支持差异较大。很多 Server 会把同一能力同时暴露为 Tool 和 Resource——Tool 兜底兼容，Resource 给支持的 Host 用更优雅的呈现。

Resources 也能由 LLM 驱动吗？ 协议层并未禁止——"应用控制"是设计意图而非技术约束。常见的做法是 Resource-as-Tool 桥接：Host 在 LLM 的工具列表里额外注入两个合成工具：

{ "name": "list_resources", "description": "列出所有可用 MCP 资源", ... }
{ "name": "read_resource",  "description": "按 URI 读取资源",        ... }

LLM 决定调用 read_resource(uri="postgres://schema/users") → Host 转发为 resources/read。形式是 Tool，本质是 LLM 在驱动 Resource。Claude Code 默认就这么做。

"应用启发式塞入"具体是什么？ 几个真实场景：

• IDE 类 Host 的上下文注入：每次发消息时自动塞入当前光标所在文件、最近编辑过的几个文件、.cursorrules / CLAUDE.md 等约定配置。
• 项目初始化自动加载：打开项目时自动读 README.md、package.json、.env.example 作为 system context。
• 语义检索自动召回：对 user message 做 embedding，对所有 resources 做向量检索，Top-K 命中自动拼入。
• 订阅式实时同步：用户改了文件 → Server 推 notifications/resources/updated → Host 把新内容刷进下一轮上下文。

这些都不需要用户和模型显式发起，由 Host 用一套规则决定。

Prompts：用户显式触发

@mcp.prompt()
def plan_vacation(destination: str, days: int) -> str:
    """生成一次度假规划"""
    return f"请帮我规划一次为期 {days} 天的 {destination} 之旅..."

在 Claude Desktop、Claude Code、Cursor 这类应用中，Prompt 通常表现为 / 命令或命令面板里的快捷入口。

关于 Prompts 有三个常被混淆的点需要澄清：

1. "只能由用户触发"是 UX 约定，不是协议铁律。 协议层没限制谁调 prompts/get，任何持有 session 的一方都能触发。"user-controlled" 是规范给 Host 的 UX 建议，意在让用户感知到自己在主动发起，避免模型偷偷调用模板。自研 Agent 完全可以在某个 workflow 节点上自动 prompts/get，技术上没人会拦。

2. 返回值不只是字符串。 prompts/get 真正返回的是一个 messages 数组：

{
  "messages": [
    { "role": "user",      "content": { "type": "text",  "text": "..." } },
    { "role": "assistant", "content": { "type": "text",  "text": "..." } },
    { "role": "user",      "content": { "type": "image", "data": "base64...", "mimeType": "image/png" } },
    { "role": "user",      "content": { "type": "resource", "resource": { "uri": "...", "text": "..." } } }
  ]
}

可以构造多轮 few-shot 示例、包含图片/音频的多模态 prompt、嵌入资源引用。FastMCP 里 @mcp.prompt() 返回字符串只是便利封装——它会被自动包装成单条 user 消息。要更复杂的结构，显式返回 list[Message]：

from mcp.server.fastmcp.prompts import base

@mcp.prompt()
def debug_session(error: str) -> list[base.Message]:
    return [
        base.UserMessage("我遇到了这个错误："),
        base.UserMessage(error),
        base.AssistantMessage("我来帮你分析。先确认几个问题..."),
    ]

3. Prompts ≠ 简化版 Skills。 这两者经常被混为一谈，但解决的是完全不同维度的问题：

更准确的类比：

Prompts 像 IDE 的 Code Snippet 或 Notion 的 Template：用户选 → 自动填模板。 Skills 像 Unix 的 man page + 可执行脚本：模型自己读说明书 → 决定要不要用 → 可能还执行其中代码。

一句话：Prompts 是"用户能用的模板"，Skills 是"模型能学的技能"。

六、客户端原语：让 Server 反过来"调用"Client

服务端不只是被动响应，它也可以主动向客户端请求某些能力。客户端原语有四个：

Sampling 的精妙之处：Server 想用 LLM 但不想自己花钱、不想绑定模型供应商，于是把"调用 LLM"的工作反向托管给 Client。Client 已经有 LLM 访问能力（用户已经付费/授权了），所以让 Client 出钱出力，并且用户可在中途审核 prompt 和返回内容——这天然就是 human-in-the-loop。

七、生命周期：一次完整的握手

理解了角色和原语，我们用 JSON-RPC 看一次最小完整流程，便于将来抓包调试时不抓瞎。

Step 1. 初始化握手

// Client → Server
{
  "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "elicitation": {} },
    "clientInfo": { "name": "example-client", "version": "1.0.0" }
  }
}

// Server → Client
{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": {}
    },
    "serverInfo": { "name": "example-server", "version": "1.0.0" }
  }
}

// Client → Server（通知，无 id 无返回值）
{ "jsonrpc": "2.0", "method": "notifications/initialized" }

这里有几个关键点：

1. 协议版本协商：双方必须使用兼容的版本，否则连接终止。
2. 能力声明：Server 在 capabilities 里显式列出自己支持的原语——本例中只声明了 tools 和 resources，意味着这个 Server 不支持 prompts，Client 也就不会调用 prompts/* 相关方法。声明了 tools.listChanged: true 的服务端，将来工具列表变更时会主动发 notifications/tools/list_changed。
3. {} 不是空对象：它表示"我支持这个能力，但没有可配置选项"——是声明的最小形式。

Step 2. 发现工具

// Client → Server
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

Step 3. 调用工具

// Client → Server
{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {
    "name": "weather_current",
    "arguments": { "location": "San Francisco", "units": "imperial" }
  }
}

Step 4. 服务端主动通知

// Server → Client（工具列表变更，无需响应）
{ "jsonrpc": "2.0", "method": "notifications/tools/list_changed" }

八、Python SDK 实战

接下来全部用 Python 官方 SDK（mcp）演示。

1. 安装

推荐使用 uv：

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

也可以用 pip：

pip install "mcp[cli]"

2. 最简服务端：Tools + Resources + Prompts 全家桶

server.py：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Demo")

# ---- Tool：模型主动调用，会产生副作用 ----
@mcp.tool()
def add(a: int, b: int) -> int:
    """两数相加"""
    return a + b

# ---- Resource：应用按需读取 ----
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """根据名字生成个性化问候"""
    return f"Hello, {name}!"

# ---- Prompt：用户显式触发 ----
@mcp.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
    """生成不同风格的问候 prompt 模板"""
    styles = {
        "friendly": "请写一段温暖、友好的问候",
        "formal":   "请写一段正式的问候",
        "casual":   "请写一段轻松随意的问候",
    }
    return f"{styles[style]}，对象是名叫 {name} 的人。"

if __name__ == "__main__":
    mcp.run()  # 默认 stdio 传输

启动方式三选一：

# 调试：MCP Inspector 提供 Web UI
uv run mcp dev server.py

# 安装进 Claude Desktop
uv run mcp install server.py

# 切换为 HTTP 传输（生产推荐）
# 在代码里改成 mcp.run(transport="streamable-http")

3. 结构化输出：用 Pydantic 自动生成 Schema

FastMCP 会从类型注解自动生成 JSON Schema，模型侧会更容易理解返回数据：

from pydantic import BaseModel, Field
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Weather")

class WeatherData(BaseModel):
    temperature: float = Field(description="摄氏度")
    humidity: float = Field(description="百分比")
    condition: str = Field(description="天气状况，如 sunny / cloudy")

@mcp.tool()
def get_weather(city: str) -> WeatherData:
    """获取指定城市的天气信息（结构化返回）"""
    return WeatherData(temperature=22.5, humidity=45.0, condition="sunny")

4. Context 注入：日志、进度、Sampling、Elicitation

向 tool 加一个 Context 参数，FastMCP 会自动注入。借助它可以做日志、进度、反向调用 LLM、向用户索取信息：

from mcp.server.fastmcp import Context, FastMCP
from mcp.types import SamplingMessage, TextContent

mcp = FastMCP("Advanced")

# 进度上报 + 日志
@mcp.tool()
async def long_task(name: str, ctx: Context, steps: int = 5) -> str:
    await ctx.info(f"开始执行任务：{name}")
    for i in range(steps):
        await ctx.report_progress(
            progress=(i + 1) / steps,
            total=1.0,
            message=f"步骤 {i+1}/{steps}",
        )
    return f"任务 {name} 完成"

# Sampling：反向请求 Client 的 LLM
@mcp.tool()
async def summarize(topic: str, ctx: Context) -> str:
    """让 Host 的 LLM 帮我总结一下"""
    result = await ctx.session.create_message(
        messages=[
            SamplingMessage(
                role="user",
                content=TextContent(type="text", text=f"请用一句话总结 {topic}"),
            )
        ],
        max_tokens=100,
    )
    return result.content.text if result.content.type == "text" else str(result.content)

5. 生命周期管理：启动时建连接，关闭时清理

需要在启动时初始化数据库连接池等长生命周期资源时，使用 lifespan：

from dataclasses import dataclass
from contextlib import asynccontextmanager
from mcp.server.fastmcp import Context, FastMCP

@dataclass
class AppContext:
    db: "Database"

@asynccontextmanager
async def app_lifespan(server: FastMCP):
    db = await Database.connect()
    try:
        yield AppContext(db=db)
    finally:
        await db.close()

mcp = FastMCP("MyApp", lifespan=app_lifespan)

@mcp.tool()
def query(sql: str, ctx: Context) -> str:
    app_ctx: AppContext = ctx.request_context.lifespan_context
    return app_ctx.db.execute(sql)

6. 客户端：stdio 连接本地 Server

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(
        command="uv",
        args=["run", "server.py"],
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            print("Tools:", [t.name for t in tools.tools])

            result = await session.call_tool("add", arguments={"a": 5, "b": 3})
            print("Result:", result.content[0].text)

asyncio.run(main())

7. 客户端：Streamable HTTP 连接远程 Server

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("http://localhost:8000/mcp") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print("Tools:", [t.name for t in tools.tools])

asyncio.run(main())

九、在 Claude Code 中的具体映射

理论讲完了，看一下三大原语在真实 Host 里到底长什么样。以 Claude Code 为例：

Tools → mcp__<server>__<tool> 工具

服务端的每个 tool 都被改名后注入模型的 tool 列表。例如装了 github MCP server，模型看到的工具叫 mcp__github__create_issue。

特殊机制 Tool Search（默认开启）：tool 定义不是一次性塞进 context window，模型先看到一个 ToolSearch 工具，按需查找。所以装 20 个 Server 也不会撑爆上下文。可以用 alwaysLoad: true 把高频 Server 强制常驻。

Resources → @ 引用 + 桥接 Tool 双路并存

Claude Code 对 Resources 的支持正好印证上一节的讨论——应用驱动和模型驱动同时存在：

路径 A：用户主动 @ 引用

Can you analyze @github:issue://123 and suggest a fix?
Compare @postgres:schema://users with @docs:file://database/user-model

输入 @ 触发自动补全，从所有连接的 Server 列出可用资源，支持模糊搜索。被引用的资源自动作为 attachment 拉进上下文。

路径 B：模型主动调用（桥接为 Tool）

官方文档原话：

"Claude Code automatically provides tools to list and read MCP resources when servers support them"

Claude Code 自动把 resources/list 和 resources/read 包装成内置工具暴露给模型——模型可以自主决定要不要去翻资源。

Prompts → /mcp__<server>__<prompt> Slash 命令

Server 定义的每个 prompt 都映射成一个 slash 命令：

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high

• 参数按 prompt 的 schema 解析，空格分隔；
• 服务端和 prompt 名里的空格被规范化为下划线；
• Prompt 返回的 messages 数组直接拼进对话。

客户端原语支持情况

• Elicitation：自动弹交互对话框（form 模式或 URL 模式），可用 hook 自动应答。
• Roots：Server 启动时设置 CLAUDE_PROJECT_DIR 环境变量，Server 也可以调 roots/list 查询当前工作目录。

对 Server 作者的启示

不同客户端对 MCP 原语的支持程度差异很大。如果你的 Server 想兼容性最大化：

• 必须支持 Tools——这是目前所有 MCP 客户端都支持的最大公约数。
• 重要能力建议双重暴露：既写成 Tool 兜底，也写成 Resource Template 给支持的 Host 用更优雅的方式呈现。比如查询类的接口，既提供 query_user(id) Tool，又暴露 user://{id} Resource Template。
• Prompts 锦上添花：对于支持 Prompts 的 Host，它能显著提升用户在常见工作流上的体验。

十、MCP vs Function Calling vs 自研插件协议

这是公司内部分享时最常被问的问题之一。

一个粗略的判断准则：

• 能力只服务于一个 AI 应用、几乎不会被复用 → Function Calling 足够。
• 能力会被多个 AI 应用消费（团队多个产品 + 第三方工具如 Claude Desktop / Cursor）→ 优先选 MCP。
• 需要给用户/模型暴露资源和工作流模板，而不只是函数 → MCP 的 Resources / Prompts 是 Function Calling 没有的。

十一、什么时候不用 MCP

凡是建议，必有反例。下面几种情况，强行套 MCP 反而增加复杂度：

1. 只是 Prompt 工程：没有外部系统交互，纯粹是 prompt 调优，不需要 MCP。
2. 极致低延迟的同进程调用：MCP 即使是 stdio，也有 JSON-RPC 序列化开销，对延迟敏感的场景直接函数调用更划算。
3. 能力跟应用强耦合、永远不会复用：自己造一套 function calling 更轻量。
4. 跨语言、跨进程的 RPC 通用诉求：那不是 MCP 的目标，请用 gRPC / OpenAPI。

十二、生产实践中的几点建议

实际使用 MCP 时，下面几条是踩过坑后总结的：

1. 工具名要带命名空间

不要叫 search，叫 github_search_issues、jira_search_tickets。多个 Server 同时连接时，模型才能准确路由。

2. description 写给模型看，不是写给人看

工具描述会直接进入模型上下文，措辞会显著影响调用准确率。要写清楚：做什么、何时该用、何时不该用、输入约束。

3. 危险操作必须 Elicitation

写库、发消息、扣款……这类有副作用的操作，主动调用 elicitation/create 让用户确认，而不是相信"模型不会乱来"。

4. Streamable HTTP 配合 OAuth

远程 Server 不要再用 Bearer Token 写死在配置里。OAuth 是规范推荐的鉴权方式，配合 roots 限定 Server 的工作范围。

5. 善用 listChanged 通知

工具集随业务动态变化（如新接入一个数据源）时，发 notifications/tools/list_changed，Client 会立即刷新，无需重启。

6. 开发期用 MCP Inspector

uv run mcp dev server.py

会启一个 Web UI，可视化地查看 tools/resources/prompts、手动调用、看 JSON-RPC 报文，比靠 print 调试快十倍。

十三、参考文档

• 官方文档首页：https://modelcontextprotocol.io/docs/
• 架构概览：https://modelcontextprotocol.io/docs/learn/architecture
• 服务端概念（Tools / Resources / Prompts）：https://modelcontextprotocol.io/docs/learn/server-concepts
• 客户端概念（Sampling / Elicitation / Roots）：https://modelcontextprotocol.io/docs/learn/client-concepts
• 最新规范：https://modelcontextprotocol.io/specification/latest
• Python SDK：https://github.com/modelcontextprotocol/python-sdk
• 官方参考 Server 仓库：https://github.com/modelcontextprotocol/servers
• MCP Inspector（调试利器）：https://github.com/modelcontextprotocol/inspector

结语

MCP 在 2024 年底问世，到今天已经被 Claude、ChatGPT、VS Code、Cursor 等主流 AI 应用普遍支持，成为 AI 工具生态的事实标准。

它的设计哲学很简单：

协议归协议，模型归模型。 MCP 不规定你怎么用 LLM、怎么管理上下文，它只规定"AI 应用如何与外部系统通信"这一件事，并把它做到了足够通用与足够干净。

对工程师而言，理解 MCP 的回报很高：写一次 Server，便能被生态里的所有 Host 复用；写一次 Client，便能即插即用任意社区 Server。在 AI 应用碎片化加剧的今天，MCP 是少数能跨厂商、跨产品沉淀工程价值的协议层。