看懂 Agent
词会过时，问题不会
这几年 agent 领域造了很多词：function calling、RAG、MCP、Skills、tool search、context engineering、harness engineering……它们看起来各不相同，大多却在回答同一组问题。这组问题来自当前主流模型及其调用方式的几条工程约束。约束还在，问题就还在。
这本手册从后端工程的视角来讲 coding agent：先把这组问题讲清楚，再逐章拆开，并对照开源 coding agent pi 的实现，看一个真实系统怎么回答每一个问题。读完的目标是：下一个新词出来时，你能很快判断它主要在回答哪个老问题、换了哪一个维度；放不进去的，再当作真正的新东西细看。
- 推荐路线
- 第一遍先跑通闭环：1 → 3 → 4 → 5 → 7，再回头读 第 2 章看能力从哪来。第 9 章的长任务、第 10 章的状态恢复、第 14 章的可靠性讲的是同一条线（怎么跨故障接着干），建议连读。
- 先读这页
- 下面的“怎么学”和“本质地图”是全书的骨架。每章开头标着它 回答 哪几个问题，点一下回到地图里对应的那一行。
- 三层深度
- 每章的小节标了 基础 进阶 深入。第一遍只看基础，第二遍补进阶，深入部分对着源码读。
- 名词卡
- 每个关键名词第一次出现时有一张可展开的 词 卡。先看“本质”一行：它属于哪个问题、方案在哪一层；下面是它的来历和现状。状态分为 正流行 已成标配 已练进模型 稳定 仍在演变 已淘汰。
- 前瞻
- 每章末尾的紫色 前瞻 框把“现在是什么样”和“接下来会怎么变”分开标注：已有证据 描述现状，有一手资料或多家产品实践支持（不代表它会一直成立）；作者判断 根据现有迹象做的推测；有争议 业内仍有分歧，或证据还不够。
- 先答再看
- 每章末尾的问答默认折叠。先自己讲一遍，再展开对照要点和“再深一步”。
怎么学：变化很快时，抓住不变的东西
新词出得比人学得快，追着词学会越学越乱；先抓住约束和问题，新词就只是老问题的新解法。
1先学约束，再学方案
主流模型（以及调用它们的方式）有几条硬约束。它们的来源不同，有的来自训练目标，有的来自架构，有的来自推理接口和部署预算（第 2 章）。agent 里的大多数技巧，都在应对其中一条或几条。每条约束都会逼出一个工程问题，下表左边是问题，右边是逼出它的约束：
| 要回答的问题 | 来自哪条约束 |
|---|---|
| ① 动手 模型的输出怎么变成动作？ | 模型只产出 token，自己什么也不执行 |
| ② 上下文 每一轮放什么进上下文？ | 窗口有限，内容越长用得越差，每个 token 都要付钱 |
| ③ 状态 上下文之外存什么，怎么接回来？ | 模型无状态，每次请求都从零读起 |
| ④ 连接 外部系统和能力怎么接进来？ | 模型看不到训练之外的系统和数据 |
| ⑤ 分工 工作怎么拆，流程由谁决定？ | 一个上下文装不下所有东西，一条循环串行又太慢 |
| ⑥ 验证 怎么知道做对了？ | 输出是概率性的，会自信地出错 |
| ⑦ 防护 出错或被攻击时怎么控制损失？ | 模型无法可靠区分指令和数据；模型和外部服务都会失败 |
约束一松动，就能预测哪些方案会变。窗口从几千涨到百万 token，“塞不下”这个问题弱了，于是有人说“RAG 已死”；但“越长越不准”和“按 token 付钱”没变，所以上下文还是要调度，只是压缩来得更晚。反过来，看到一个新技巧，先找它在应对哪条约束。找不到的，可能只是换了个说法，也可能真是新问题，值得细看。
2七个问题，一张地图
上表的七个问题，就是下面本质地图的七行。地图最上面还有一行 ⓪“总称”，放的是 agent、harness engineering 这类给整件事起名字的词。七个问题是导航用的分类，不是严格的划分：有的词同时碰到好几个问题，地图只把它放在最主要的那一行。第一次看地图，只看每行的“区分只看”：同一行里的词，差别大多落在这一个维度上。比如第 ② 行，RAG、AGENTS.md、Skills、tool search 的差别只在“放进来的是什么、常驻还是按需、谁去找”。
3方案放在哪里
同一个问题的解法，常落在下面五个位置。越往后，越不需要你自己写：
注意这五个位置不是同一把尺子上的刻度：提示词、harness 代码、模型权重说的是由什么来实现；开放标准、厂商 API 说的是按谁的约定交付。一个方案常同时占几格，比如一个 Skill 的格式由开放标准规定，内容是提示文本和脚本，由 harness 负责加载。地图和名词卡上的“方案在”只标它最有区分度的那一格，把它当作观察角度，而不是分类答案。
很多“新东西”是老方案换了位置。ReAct 的“想、做、看”被训练进了推理模型，提示词模板不再是必需；压缩从 harness 代码搬进了厂商 API；各家的规则文件统一成了 AGENTS.md；各家的“技能目录”统一成了 Skills 规范。常见的方向有两种：交出去（交给厂商或模型来做）和统一（各家的私有做法变成同一个标准）。
4什么会被练进模型
模型怎么学会新本事，第 2 章会细讲。这里先给一条经验规律，用来判断方向，不能当定律用：
| 更可能练进模型 | 留在模型外 |
|---|---|
| 输出格式：工具调用、编辑格式 | 执行：沙箱、进程、文件读写 |
| 推理和工具调用交织、何时停 | 状态：会话日志、检查点、git |
| 规划、自我检查的习惯 | 权限、审计、合规 |
| 协调子 agent（已有厂商在尝试） | 成本和配额 |
| 为弱模型写的提醒和模板 | 验证环境本身：测试、浏览器。它们是奖励的来源，不会被练进模型 |
所以看到一个新技巧，先问一句：它是在替模型想，还是在替模型做事？前者的寿命往往取决于下一代模型（删不删由评测决定），后者长期有效。这就是第 1 章“harness 会变薄吗”的答案的来源。
5新词三问
- 它回答七个问题里的哪一个？
- 它把方案放在哪里？上一代方案在哪里？
- 和同一行里最像它的那个词相比，它换了哪个维度？
① 属于第 ② 个问题：上下文里放什么。② 放在开放标准里（一个文件夹加一份 SKILL.md），由 harness 加载。③ 同一行里最像它的是 AGENTS.md 和 tool search：和 AGENTS.md 只差“常驻还是按需”，和 tool search 主要差在“装的是做事方法还是工具定义”，以及怎么被找到：skill 的名字和描述常驻上下文，tool search 通常要先搜索才看得到工具。
答完三问，Skills 剩下要学的只有文件格式。
① 属于第 ① 个问题：输出怎么变成动作。② 放在 harness（或厂商 API）里。③ 相对 function calling（一轮回复列出一个或几个调用，每个结果都回到模型），动作变成“一段程序”：调用之间的循环、条件和结果加工由代码完成，好处体现在上下文上：中间结果不经过模型。
6按保质期分配时间
约束和问题
无状态、上下文有限、错误要回填、边界在模型外、循环的结构。
精学：能脱稿讲，能手写。
模式和取舍
压缩策略、子 agent 用法、MCP 还是 CLI、长任务怎么交接。
理解为什么，知道在什么条件下会翻转。
API 和参数
某家的 beta 字段、默认阈值、规范某一版的字段、pi 的常量。
用到再查。手册里 pi 源码默认折叠，就是这个原因。
7怎么跟上
- 新词先定位，不急着学。用三问把它放进地图；过一两个月还有人在用，再细看。
- 关注约束的变化，而不是产品发布。窗口、价格、延迟、模型能完成多长的任务（第 15 章的时间跨度）变了，方案才会跟着变。
- 读一手资料。论文、厂商的工程博客、规范的变更记录、源码。二手综述常常把新词当新问题讲。
- 自己做消融。某个技巧对现在的模型还有没有用，关掉它跑一遍评测就知道（第 15 章）。
本质地图
每个词按它主要回答的问题归到一行（跨几个问题的词只放在最主要的一行），后面一句话说它的本质。切到“按年份”可以看原来的造词年表。点章节号跳到讲它的地方。