> 本页出自《Agent Harness 工程：从源码里读出的设计决策》，作者 王吕（公众号 Codeflow，wanglv93@gmail.com）。
> 修订版 1.1 · 2026-08-27。网页版：https://agent-harness.codeflow.cc/book/preface/ ；全书：https://agent-harness.codeflow.cc/ 。
> 引用或转述时请注明作者与出处。

# 序 · 如何读这本书

## 这本书是什么

我读了正文实际引用的 23 个 coding agent 实现，对每个都问同一组问题：循环怎么写，上下文怎么管，权限怎么拦，崩溃后怎么恢复。读完没有得到一套整齐划一的答案。面对同一个问题，各家常常因为运行环境、模型能力和产品边界不同而作出相反选择。这本书把这些分歧放到一起，每一章对应 agent 生命周期上的一个决策点，回答四件事：

1. 各家分别怎么做。对照表和代码题注标明实现位置，方便读者理解代码所在的上下文。
2. 分歧在哪，判断标准是什么。
3. 有哪些反面证据和失败模式。
4. 可以直接采用的最小实现是什么。

## 这本书不是什么

- **不是框架教程。** 它不教 LangGraph 或任何框架怎么用。
- **不是提示词技巧集。** 第 7 章讲 system prompt，但那一章开头就说明了：它的具体措辞是全书迁移性最差的内容。
- **不是论文综述。** 论文在这里是证据，不是组织线索。
- **不是产品评测。** 书里出现的 23 个项目没有排名，它们是同一个问题的 23 个答案。这里的 23 是正文实际引用的项目数；调研池共有 28 个，两者的关系见《涉及的项目》一节。

## 写给谁

**正在开发或调试 agent 的工程师。** 你有能力阅读源码，需要了解的是：其他项目面对相同设计选择时采用了什么方案，各自付出了什么代价。

如果你在找「AI agent 是什么」的入门材料，这本书不合适。

## 怎么读

### 全书分六个部分

17 章按一次 agent 运行的生命周期分成六个部分。每个部分前面有一页扉页，说明这一部分管生命周期的哪一段、读完能做什么，以及本部分各章之间的关系：

| 部 | 章 | 管什么 |
|---|---|---|
| 1 · 立论 | 1 | harness 值不值得投入，投在哪一层 |
| 2 · 循环 | 2–5 | 一次运行的控制流：循环、工具、插话、终止与恢复 |
| 3 · 上下文 | 6–10 | 每一轮往窗口里放什么：缓存、prompt、压缩、记忆、检索 |
| 4 · 三种边界 | 11–13 | 不可信输入的边界、子 agent 的边界、外部系统的边界 |
| 5 · 规模化 | 14–16 | 从一次运行到多人持续运行：恢复、多租户、交付流水线 |
| 6 · 验证 | 17 | 怎么知道前 16 章的改动是好是坏 |

**阅读顺序是「分部扉页 → 该部分各章」**。如果只关心某个工程问题，也可以从下一节的症状表直接进入对应章节。

### 如果你要从零造一个

按第 1 章 §1.5.1 的建造顺序读，它给了七个阶段和每个阶段的完成标志。**唯一一条无条件的建议是不要跳过第 1 阶段**（执行环境隔离，具体实施步骤在第 11 章 §11.5.1）——在给 agent 接上任何有副作用的工具之前先做隔离。

### 如果你已经有一个，想找问题

遇到具体问题时，可以按下表直接找到相关章节。

| 症状 | 去读 |
|---|---|
| 账单高得离谱 | 第 6 章（KV cache） |
| 不知道钱花在哪 | 第 6 章 §6.5.3（依次检查命中率、失效原因与成本归因） |
| 查不出是哪一轮出的错 | 第 14 章（事件日志） |
| 长会话失败 / 内容超过上下文窗口限制 | 第 8 章（压缩） |
| 同一个错误反复犯 | 第 3 章（工具错误信息）、第 5 章（doom loop） |
| 偶发的随机 400 | 第 2 章（孤儿 tool_call、附件位置） |
| 进程挂了任务重来 | 第 14 章（崩溃恢复） |
| 用户插话行为诡异 | 第 4 章 |
| 换模型之后变笨 | 第 7 章（按模型分化）、第 1 章（组件迁移性） |
| 找不到代码 | 第 10 章 |
| 记不住东西 | 第 9 章 |
| 担心被注入 | 第 11 章 |
| 想拆成多 agent | 第 12 章（多数任务不需要拆分） |
| 工具一多，模型就选错工具 | 第 3 章（工具描述与渐进披露） |
| 协议升级后功能静默失效 | 第 13 章（MCP 的 revision 与版本锁定） |
| 多人共用一套 agent，凭证与数据要隔离 | 第 15 章 |
| 想把 agent 接进 issue 与 CI | 第 16 章 |
| 不知道改动是好是坏 | 第 17 章 |

### 如果你只读两章

**第 6 章和第 17 章。**

第 6 章（KV cache）是全书密度最高的一章，而且它的结论会直接影响调用成本。第 17 章（评测）是采用其余 16 章建议的前提：没有回归集，就无法知道一次改动在修复目标问题的同时破坏了哪些已有能力。

### 书末有什么

后记包含五部分：A 术语表、B 项目索引、C 参考文献、D 本书没有覆盖的内容，以及 E 资料截止日期。术语表按词找定义，项目索引按项目找证据来源，参考文献给出正文所引论文、规范和公开材料的完整信息。

**本书不做传统主题索引**，用后记 A 的术语表、后记 B 的项目索引和前面的「按症状找章节」表替代。

### 每章的固定结构

每章正文分为五段，顺序固定。前三段的标题按各章内容拟定，但承担的职责不变：

1. 解决什么问题（大白话，不用术语）
2. 各家怎么做（源码对照，标题多作「源码对照：……」）
3. 判断标准（把选择变成可以直接检查的条件）
4. **反面证据与失败模式**
5. 可以直接采用的最小实现

六章采用了与常规不同的证据组合。第 12 章（要不要拆 agent）主要对照论文，第 13 章（协议）主要对照规范文本，第 16 章（接进交付流水线）主要对照公开实践与产品资料，第 17 章（评测）主要对照评测方法。这四章仍逐条给出论文名与 arXiv 号、规范 revision 或公开材料日期；源码只作辅助证据。它们的问题无法单靠源码回答，强行套用源码对照反而会造成误导。

另外两章只有部分结论由源码支持。第 9 章（记忆）的写路径与读路径来自源码，但量化结论出自对话助手与通用 agent 的记忆基准，不是 coding agent 基准。这些数字只能用来判断量级和方向，不能用来预测你自己系统上的绝对分数（该章 §9.1）。

第 15 章（多租户）的每项具体机制都有源码出处，但没有一个项目完整实现了本书组合出的方案。该章对照了 17 个项目的源码，并未考察一套已经投入生产的完整系统。这些源码只能证明「有人这样做过」，不能证明整套组合已经过验证。因此，整体架构的置信度低于其中的单项机制（该章 §15.1，完整说明见 §15.4 反面证据三）。

第 17 章可供逐项比较的公开评测方法主要来自 Anthropic 的《Demystifying evals for AI agents》（2026-01-09，厂商自述）。其余证据包括两篇 harness 自动改进论文、一篇评测随机性论文、四份讨论基准质量与可复现性的工作，以及两个源码不变性测试。该章的证据范围比其他章窄，§17.1 和 §17.4 分别说明了适用边界。

各章第 4 段集中讨论反面证据与失败模式。这里不仅列实现缺陷，也会说明前文建议在哪些条件下不成立。阅读时间有限时，应优先阅读这一段，再决定是否采用第 5 段的实现。

## 资料范围与时效

本书采用的项目源码材料截止到 **2026-08-17**；部分规范、论文与安全公告核对到 2026-08-18。正文中的版本号、价格、限额、项目状态和具体常量都可能在出版后变化，使用前应以当前源码与官方文档为准。

写作期间，我有两次在重新核对后改写了结论。第 6 章最初判断 openclaw 不把时间放进 prompt，后来确认日期与时区仍在，只是位于缓存边界之后；写第 13 章的约四周里，MCP 从 `2025-11-25` 更新到 `2026-07-28`，协议级会话与 SSE 续传也被移除。**本书记录的是资料截止日期之前的工程状态，后续版本可能已经变化。**

## 诚实边界

下面这些限制会影响正文结论的适用范围，因此放在前言，不留到附录再说。

**一 · 本书的证据是「设计正确性」证据，不是「效果」证据。**

书里记录的是各家源码怎么写、注释怎么解释它们为什么这么写。**这不等于「这样写效果好多少」。** 除了少数厂商自报的数字和论文实测，没有本书自己做的对照实验。

**二 · 缺生产运营数据。** 没有失败复盘、没有成本实测、没有长周期稳定性数据。

**三 · 缺国内第一方的公开工程叙述。** 多 agent 那一轮素材调研（2026-07-22）里，国内大厂的第一方工程博客只拿到 1 篇（见第 12 章 §12.4 反面证据二），其余各章也没有补上。国内团队的第一方材料，本书主要是从源码读的（kimi-code、MiMo-Code）。**所以本书的公开工程叙述几乎全部来自英文世界的实践。**

**四 · 样本有偏。** 调研池 28 个项目里 27 个能拿到源码，Claude Code 只能靠公开材料。闭源商业 agent（Devin、Cursor 服务端）同样只能靠公开材料推断，而它们恰恰是规模最大的那一批。

**五 · 各章的建议合起来可能互相干扰。** AHE 论文（*Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses*, Lin et al., arXiv:2604.25850）的消融实验显示，三个正收益组件单独换入的增益之和是 +11.1 pp，而全量方案只有 +7.3 pp（第 1 章 §1.4、第 17 章 §17.4）。请用第 17 章的方法在自己的回归集上测试组件组合，再决定保留哪些建议。

**六 · 你对自己改动的回归效果几乎没有判断力。** AHE 的实测：修复预测的精确率是随机的约 5 倍，**回归预测只有约 2 倍**。这是第五条的直接后果，也是为什么第 17 章存在。

**七 · 本书有三项重要结论依赖 AHE 论文。** 第五、六条引用的数字都来自 AHE，而该论文只报告了 Terminal-Bench 2 这一个基准上的一次运行，本书没有独立复现（第 1 章 §1.4 已明确说明）。受影响的结论包括：第 7 章要求具体 system prompt 措辞在迁移前重新验证；第 9 章认为记忆组件的迁移收益最高；第 17 章以回归预测准确率只有随机基线约 2 倍作为建立评测的依据。**如果 AHE 的结果无法复现，这三项结论都需要重新评估。**

## 证据分级

正文使用下列标记说明每条论断的证据级别：

| 级 | 类型 | 表述方式 |
|---|---|---|
| A | 源码实证 | 标明源码文件与具体位置 |
| B | 代码注释里的自述 | 引原文，注明「注释称」 |
| C | 官方文档 | 附文档名与基准日期 |
| D | 论文实测 | 附论文英文名与作者 |
| E | 厂商自述 | **明写「厂商自述」，不当事实** |
| F | 本书推断 | 明写「推断」，给出推理链 |

表 0-1 的证据等级同时限制结论的措辞。E 级的厂商自述只能说明厂商公开报告了什么，不能写成已经由源码或独立实验确认的事实。

第 16 章的证据以厂商自述为主，我在那一章的反面证据里逐条标注了每个数字的性质。该章证据级别最高的一项是 METR 的随机对照试验，也是表中唯一报告负面结果的研究。因此，厂商公布的采用率和产出量只用于说明采用规模，不能替代有对照组的效率研究。

## 涉及的项目

调研的项目池有 28 个。**其中 23 个在正文中留下了实际引用**，按被引章数排列（下面是两张两列表并排，先读左半张，再读右半张）：

| 项目 | 出现章数 | 项目 | 出现章数 |
|---|---|---|---|
| opencode | 10 | kimi-code | 6 |
| pi-mono | 9 | codex | 6 |
| Claude Code | 7 | oh-my-pi | 6 |
| openclaw | 8 | hermes-agent | 5 |
| codebuff | 7 | cindy、craft-agents-oss | 各 4 |
| MiMo-Code | 7 | aider、buzz、cloudflare-os、grok-build、OpenMinis | 各 3 |
| Roomote | 7 | cline、crush | 各 2 |
| goose | 7 | prime-agent | 1 |
| kilocode | 6 | | |

**另外 5 个在调研池中但正文未引用**：`better-harness`、`deepseek-harness`、`flue`、`herdr`、`loopx`。列出它们是为了说明调研范围，而不是暗示它们为本书提供了证据——**读过不等于用上了**，把没用上的项目也算进「本书基于 N 个项目」是一种常见的虚报，这里避免。

它们的名字仍会在第 6、7、15 章的普查口径注里出现——普查名单要写全才可核验——但没有为本书的任何一条结论提供证据。表 0-2 的「出现章数」采用同一口径：只数提供证据的引用，普查名单里的点名与章末基准块的 commit 行不计入。

正文里还会出现几个更小的数字：第 6、7 章的 21，第 10 章的 12，第 15 章的 17。**它们是专项普查覆盖的项目数，不是「本书基于 N 个项目」**，与这里的 28 和 23 都不是同一个集合。正文会在相应位置注明调查范围、日期和统计方法。

Claude Code 是闭源产品。本书对它的描述依据 Anthropic 的官方文档与工程博客，以及对其公开行为的观察，正文没有它的 `file:line` 引用；相关结论的证据级别是厂商自述与本书观察，不是源码实证，应按这一边界理解。

## 最后

这些项目每天都在改，而这本书记录的是资料截止日之前的实现。把它当作设计决策的比较框架，不要把任何具体版本号、常量或产品状态当作永久事实。你的源码、你的运行数据和当前官方文档，比书中的快照更新。

---

作者 王吕 · 《Agent Harness 工程：从源码里读出的设计决策》 · https://agent-harness.codeflow.cc/book/preface/