LLM 输入一串消息，输出下一条消息。它不能读文件，不能调接口，也记不住上一次请求。所有“能力”都来自包在它外面的程序。

Harness 就是这层程序：维护对话历史、提供并执行工具、拼装上下文、保存会话、处理权限、发出事件。Claude Code、Codex CLI、pi 都是 harness。

agent 和 harness 不是两个并列的零件。harness 是包在模型外面、负责运行和控制的那层程序；agent 是把模型放进 harness、跑起来之后的整个系统。这层程序可以自己写，可以用 SDK，也可以交给厂商托管（第 3 章）。“Agent = 模型 + Harness”是工程上的简化说法：给模型套一层程序不一定就是 agent，还要看下一步由谁决定（下一节）。

沿用上面的 Spring + Tomcat 类比：harness 像 Tomcat 这样的容器，它不是被动的盒子，而是要管生命周期、拦截和状态；agent 像部署进去、正在运行的应用。不同的是，这个应用的规矩可以事先定好（业务规则、权限、怎样才算验收通过），但具体一步步怎么走没有写死，由模型每一轮当场决定。

两边各管一半：

两边靠一个循环接起来（第 4 章展开）：harness 把历史和工具清单发给模型 → 模型回一条消息，可能带着工具调用 → harness 执行工具，把结果追加到历史里 → 再发给模型，直到模型不再调用工具。循环是 harness 写的，每一圈往哪走由模型决定。

注意，“模型不再调用工具”只说明这一段跑完了，不等于任务做成了：模型可能是做完了，也可能是要问用户，或者已经走不下去了，做没做成要另外验证。harness 也可以中途让循环暂停（等人审批），或者因为轮数、预算、超时、用户取消把它终止（第 4 章）。

日常说法里这两个词常被混用。“Claude Code 是一个 agent”说的是它带着模型运行时的样子；“Claude Code 是一个 harness”说的是去掉模型后剩下的那份程序。讨论设计时最好分开问：失败是因为模型没想对，还是 harness 没让它看到该看的、没让它做到该做的？分开问是为了找对下手的地方，但不是说只有后一种才改得了：模型没想对，写 harness 的人往往也能缓解，比如把提示写清楚、补上缺的上下文、给它能算准的工具、加上校验，把报错清楚地反馈给它；这些都不够，再考虑换模型。问题出在哪一边，和该从哪一边改，不一定是同一边。

Anthropic 在《Building Effective Agents》里把 LLM 应用分成两类，这个划分被广泛引用：

工程判断的原则：能用 workflow 解决的就不要上 agent。agent 用在步骤不确定、需要探索和试错的任务上。实际系统常常是混合的：外层是固定流程，某个节点内部是一个 agent。

和上一节合起来看：workflow 和 agent 外面都有一层程序，区别在这层程序管到哪一步。workflow 的外层代码自己定好流程，只把模型当成一个函数来调用；agent 的外层只提供工具、循环和护栏，把流程交给模型。通常只有后一种被叫作 harness。

模型只能看到 harness 给它的东西、只能做 harness 允许的事。工具描述写得含糊、上下文塞满噪音、没有压缩策略、错误信息看不懂，再强的模型也会表现很差。同一个模型在不同 coding agent 里的基准分数可以差出一大截，差异全部来自 harness。

harness 要回答的，就是首页本质地图里那七个不变的问题。每个问题都来自模型的一条硬约束，后面每一章回答其中一两个：

1. 动手：模型只产出 token，输出怎么变成动作？（第 3、4、7 章）
2. 上下文：窗口有限还越长越差，每一轮放什么？（第 5、6、8 章）
3. 状态：模型无状态，上下文之外存什么、怎么接回来？（第 8、10 章）
4. 连接：外部系统和能力怎么接进来？（第 11、16 章）
5. 分工：工作怎么拆，流程由谁决定？（本章、第 9 章）
6. 验证：输出会自信地出错，怎么知道做对了？（第 2、15 章）
7. 防护：出错或被攻击时怎么控制损失？（第 12–14 章）

这七个问题从 2023 年到现在没有变过，变的是每个问题的解法放在哪里：提示词、harness 代码、开放标准、厂商 API，还是模型权重。

说对了一半。“变薄”的是 harness 里替模型思考的那部分；替模型做事、给模型把关的那部分不但没变薄，还在变厚。还有一部分既没消失也不在 harness 里了，而是转给了模型训练或厂商 API。

这三列背后有一个机制：能写成示范、或者能用程序判对错的行为，更有机会被训练进模型（第 2 章讲怎么训练进去），所以“替模型想”的那一列倾向于变薄。这是倾向，不是定律：哪段脚手架真能删，要在你的模型和任务上评测才知道。要真的碰外部世界、保存状态、承担责任的事，没法写进权重，所以“替模型做事”的那一列不会因为模型变强而消失。

几个佐证：

• 脚手架在被删。Claude Code 的负责人公开说过，每出一个新模型，团队都会审一遍 system prompt，删掉新模型已经不需要的提醒；他们把 Claude Code 描述为“尽可能薄的一层封装”，并预期很多脚手架会被练进模型。有团队报告过某个模型在上下文快满时会“赶工收尾”，于是加了“清空上下文 + 结构化交接”来绕开，到下一代模型这个毛病消失了，这段代码也就成了死代码。
• 但 harness 的分量没变小。Terminal-Bench 这类按“模型 + harness”组合打分的基准上，同一个模型换不同 harness，成绩可以差十几个百分点。
• 工程重心在转移。OpenAI 的 harness engineering 实验里，人几乎不写代码，工作量全花在让 agent 能自己验证、自己发现问题的环境上：文档结构、lint 规则、可观测性、测试。

对设计的启示：

1. 为下一代模型设计。针对当前模型缺陷的补丁，写的时候就预期它会被删。把它们放在扩展或配置里，而不是核心里。pi 把计划模式、子 agent 都放到扩展里，就是这个思路。
2. 用评测决定删什么。每换一个模型，关掉某个脚手架跑一遍评测（消融），没有收益就删（第 15 章）。
3. 把力气花在“变厚”的那一列。沙箱、状态、验证、评测，这些不会被模型取代，是长期的工程价值所在。
4. 警惕被厂商 API 锁定。交给厂商 API 的能力用起来省事，但会让 harness 和某一家绑定（第 5 章服务端压缩）。

预训练拿海量文本，遮住下一个 token 让模型猜，按它给正确答案的概率打分（交叉熵损失）、成批地调参数，在万亿级 token 上反复做。文本自带答案，不需要人标注。

agent 面对的几条硬约束，常被笼统地说成“因为模型只会猜下一个 token”。其实它们来源不同：有的来自训练目标，有的来自模型架构，有的来自推理接口和部署预算。下表说的是本书讨论的主流模型，即自回归（decoder-only）Transformer、通过无状态 API 调用的那一类：

分清来源，才能判断哪条约束会松动、怎么松动。服务端状态改变的是“谁来保存历史”，模型每次仍要从输入重新读起；更长的窗口放宽了上限，却没有消除越长越不准。

预训练出来的模型只会续写。问它“香港天气怎么样？用摄氏度”，它很可能续写出更多关于天气的问题，而不是输出一个天气查询的调用。让它听指令、会用工具，靠后训练。

后训练的论文里缩写很多：RLHF、RLAIF、RLVR、PPO、GRPO……它们分属两个互不相干的维度：

ChatGPT 最初用的是“人来比较 + PPO”，DeepSeek-R1-Zero 用的是“程序判对错 + GRPO”。两个维度可以任意组合。这是“看本质不看名字”的一个小例子：先找出维度，再把名字放进格子，五个缩写就只剩两个问题。

在数学题上，一次尝试（rollout）是一段解答。在 coding agent 上，一次尝试是一整条轨迹：读文件、改代码、跑测试……最后用隐藏测试或任务结束时的系统状态打分。

要跑这种训练，需要一个能真正执行工具的环境，也就是一个 harness。厂商通常用自家的 harness 来跑。这一点能解释后面好几章会遇到的现象：

• 编辑格式和模型绑定。GPT 系列熟悉 apply_patch，Claude 熟悉 str_replace，因为训练时用的就是它们（第 7 章）。
• 同一个模型在训练时用惯的那类 harness 里往往表现更好，换一个接口不熟悉的 harness 可能差一截（第 1 章）。是否真的更好，要在同一模型、同一任务下评测。
• 推理块要原样回传。模型是在“思考、调工具、带着思考继续”的轨迹上练出来的，中途丢掉思考，它就不在熟悉的状态里了（第 3 章）。
• 基准检查最终状态。Terminal-Bench、SWE-bench 检查任务做完后机器或仓库的状态，和训练用的奖励是同一类东西（第 15 章）。

题目：时薪 12 美元，干了 50 分钟，挣多少？假如奖励只核对最后的数字：

奖励只看结果，错误的过程也会被加强。训练得足够久，模型会学会利用验证器的盲区（reward hacking），比如让测试通过却没修好问题，甚至去改测试本身。

这个教训贯穿三个地方：训练时的奖励、评测时的判分（第 15 章）、agent 运行时的自我检查（第 9 章）。它们本质上是同一个验证器用在不同时间点。验证器写得越全，三处都越可靠。

把上面合起来，就得到首页的那条经验规律：能写成示范的（SFT）、能用程序判对错的（RLVR），更有机会被训练进模型。这是倾向，不是定律：能判对错不代表模型容易试出对的答案，奖励可能有漏洞（见上一节），学会示范也不代表能可靠泛化，练不练还要看数据和成本。已经发生的例子：

• ReAct 的 Thought/Action 文本模板 → 主流推理模型把“想、做、看”练进了权重，显式模板不再是必需（第 4 章）。
• 强制更新待办清单、防止“谎称完成”的提醒 → Claude Code 团队报告，在他们的新模型上某个这类机制已经不需要（第 9 章）。这是一家在自家模型上的观察；换了模型或任务，是否还需要，要用评测确认。
• 多 agent 的协调：Kimi K2.5 用强化学习只训练协调者、子 agent 保持不动，让模型自己决定什么时候拆分、派给谁。分工这件事也开始被训练进去。

练不进模型的是沙箱、权限、状态持久化、审计、成本控制。它们不是模型的“行为”，而是环境；验证环境本身还是奖励的来源。

• 模型不执行任何东西。它按训练学到的格式输出工具名和 JSON 参数，执行的是 harness。
• 无状态。每次请求都把完整历史重发，“记忆”是 harness 拼出来的。
• 模型靠名字和描述选工具。描述写得不清，就会选错或填错参数。

• 流式事件：响应以 SSE 逐块到达，统一成 text_delta、thinking_delta、toolcall_delta、toolcall_end 等事件。
• 流式中的工具参数是半截 JSON。界面想提前显示“正在写入 X 文件”，就要做“尽力而为”的增量解析；真正执行必须等 toolcall_end 拿到完整参数，并经过 schema 校验。
• 参数不合法（缺字段、类型错、调了不存在的工具）时，不要抛异常中断任务，把错误作为 isError 的工具结果返回，模型通常下一轮就能改对。
• 推理块要原样回传。推理模型在调用工具前会先输出思考内容（Anthropic 是带签名的 thinking 块，OpenAI 是可加密的 reasoning item）。在工具调用的往返中，harness 必须把这些块原样放回下一次请求，否则模型会丢掉推理过程，有的厂商会直接拒绝请求。这也是“跨厂商切换”难的根源（见下）。
• 思考预算是一个参数。现在的模型大多可以调思考强度（effort / thinking budget）。harness 可以按任务难度设置：简单的格式化用低档，排查疑难问题用高档。它影响成本、延迟，有时还影响缓存键（第 6 章）。

• 约束解码（constrained sampling）：部分厂商支持在解码时强制输出符合 JSON Schema，参数就不会不合法。代价是不是所有模型都支持，schema 也有限制（例如要求 additionalProperties: false）。
• 跨厂商切换：同一个会话中途换模型（比如主模型故障降级），历史消息要能被另一家理解。难点在各家私有的内容块，比如推理过程（thinking）。

无状态 API 还是有状态 API。上面讲的都是无状态调用：每次把完整历史发过去。厂商也提供了有状态的选择，比如 OpenAI 的 Responses API 可以只传 previous_response_id，历史存在服务端；还可以直接用服务端工具（网页搜索、代码执行），工具在厂商那边执行完再把结果交给模型。这等于把一部分 harness 搬到了厂商那里。

• 好处：少传数据、少写代码，服务端工具开箱即用。
• 代价：状态在别人手里，换厂商、审计、离线回放、合规都变难。coding agent 这类需要分支、恢复、跨厂商降级的场景，主流做法仍是客户端保存全部状态。pi 也是这样。

调用模型 → 有工具调用就执行并回填 → 再调用模型 → 直到不再调用工具。这就是 ReAct（Reason + Act，2022）思路的工程实现。“一次模型回复 + 它引出的工具执行”叫一个 turn。

不再调用工具时有两种情况：任务完成，或者需要用户补充信息（缺关键参数、所有方案都走不通、要做不可逆的操作）。停下来问人是循环的正常出口，不是失败。逐步点击模拟器，观察代码、事件和 messages 的变化：

只有 while 循环的版本离生产很远。下面标注的 9 处才是真正的工程量：

模型每一轮看到的上下文，可以拆成五个槽位。harness 的工作就是每一轮从这五处挑选内容、拼成一次请求。后面讲的各种技巧，都是在决定某个槽位放什么、放多少：

工具结果通常是增长最快的部分。为什么不能全都塞进去：

• 硬上限：超过上下文窗口，请求直接失败。
• 成本：每个 turn 都重发全部历史，单次输入随轮数线性增长，整个任务的总输入近似平方增长。
• 效果：上下文越长，模型对中间信息的利用越差，指令遵循也变弱（常被称为 context rot、lost in the middle）。

此外还有几条被生产环境反复验证过的经验，出自 Manus 团队 2025 年的总结，后来被很多 harness 采纳：

• 保留失败记录。报错、失败的尝试不要从上下文里删掉。模型看到“这条路走不通”，才不会重复犯错。
• 复述目标。长任务里让 agent 维护一份 todo 文件并不断更新，相当于把目标反复写到上下文末尾，对抗“中间信息被遗忘”。
• 文件系统是外部上下文。大块内容写进文件，上下文里只留路径；需要时再读。只要路径还在，压缩就是可恢复的。
• 避免示例导致的惯性。上下文里一连串格式相同的操作会让模型机械模仿。适当加入一些变化。

pi 的 system prompt 由 system-prompt.ts 按命名 section 拼装。下面的拼装器使用源码里的真实文本（docs 段已省略），勾选看变化：

• 规则跟着工具走：每个工具贡献一句说明和若干使用准则；没有 grep / find / ls 时自动加一条“用 bash 查找文件”。
• 按 section 增量更新：会话里记录的是 section；之后某段变化（如新装 skill），只追加这一段的补丁，保持前缀稳定（第 6 章）。

压缩正在转到厂商 API。pi 自己实现压缩，但从 2025 年下半年起，厂商陆续提供了托管方案：

取舍和第 3 章的“有状态 API”一样：托管省事，但牺牲可移植性和可审计性。需要跨厂商降级、需要审计的平台，通常仍然自己做，或者两种都支持、按模型选择。

主流厂商都支持前缀缓存：如果这次请求的开头和之前某次完全一致，这部分的计算（Transformer 的 KV cache）可以复用，价格通常只有正常输入的一小部分，首 token 延迟也明显下降。缓存有生存时间（TTL），过期就失效。

为什么只能缓存前缀：模型的注意力只回看前面的 token（第 2 章），所以开头那段算出的中间结果和后面写了什么无关，可以原样复用；但只要前面改了一个字，它后面的所有结果都要重算。“只追加、不改开头”这条设计约束，就是从这里来的。

agent 的历史不断追加，天然适合前缀缓存：第 N 轮请求的前缀就是第 N−1 轮的全部内容。长会话里，缓存往往是最省钱的一项。

• 稳定内容在前：system prompt、工具定义放最前面，且不要放当前时间、随机 ID。
• 只追加不修改：中途改动前面的任何一条消息、增删工具，之后的缓存全部失效。
• 压缩的隐性成本：压缩替换了历史，之后的请求通常无法再复用旧历史的缓存，从摘要开始的部分一般要重新计算；system prompt、工具定义这些没变的开头仍可命中。实际命中范围还取决于缓存断点和有效期。
• 路由粘性：同一会话的请求尽量发往同一厂商、同一区域、同一缓存键（会话 ID）。
• 屏蔽工具而不是删除工具：某个阶段不想让模型用某些工具时，删掉它们的定义会改动前缀。Manus 的做法是工具定义保持不变，在解码时限制可选的工具（或用提示告诉模型当前不可用）。pi 用追加 system 消息表达工具变化，也是为了不改前缀。
• 工具顺序要确定：工具列表每次序列化的顺序必须一样。从 Map 或远程服务拿到的工具列表要先排序。

缓存会过期。如果用户思考了 6 分钟才回复，而缓存 TTL 是 5 分钟，下一次请求就要按全价重新计算整个前缀。一个思路是在快过期时发一个极小的请求“续期”，但续期本身也花钱。值不值得，要算期望收益。

工具是模型的 API。SWE-agent 论文（2024）把它叫作 ACI（Agent-Computer Interface），Anthropic 在《Building Effective Agents》里沿用了这个说法。它值得像设计对外 API 一样用心：

• 少而通用：coding agent 有 read、write、edit、bash 就能做几乎所有事。工具越多越容易选错，定义本身也占上下文。
• 描述写给模型：做什么、什么时候用、什么时候不用、参数含义。
• 错误是反馈：告诉模型错在哪、怎么改。
• 防呆：让模型不容易犯错。
• 控制输出体积：默认截断，告诉模型完整输出在哪。
• 标注副作用：只读、破坏性、幂等、是否与外部世界交互，供权限系统参考。

用行号修改会遇到“行号漂移”：第一处修改增加了 3 行，第二处的行号就错了。用“旧文本 → 新文本”替换，位置由内容决定，不受影响。但它有两个新问题：模型复述的旧文本和文件不完全一致（空格、引号），以及旧文本在文件中出现多次。试试 pi 的处理方式：

编辑格式和模型是绑定的。厂商会在自家 harness 的工具上做强化学习，于是模型对某种编辑格式特别熟练：OpenAI 建议 GPT 系列和 Codex 模型使用 apply_patch（一种类 diff 的补丁格式），Anthropic 的模型则针对 str_replace 式的文本编辑工具训练过。同一个模型换一种它不熟悉的编辑格式，出错率会明显上升。

所以支持多厂商的 harness 要考虑按模型选工具格式，而不是全部用一种。这是第 2 章“harness 也是训练环境”带来的直接后果。

同一件事，可以通过精度不同的几种接口去做。比如“把图表导出成 PNG”：

原则：能用更精确的接口，就不用更模糊的。GUI 留给没有任何接口的软件。也有项目反过来，给只有界面的软件自动生成一层命令行，让 agent 能走 CLI。无论走哪种接口，最后都要检查结果：退出码、输出、生成的文件，或者再截一张图确认。

按时间跨度看，会话记忆和长期记忆之间还夹着一层：只属于这个任务、但要跨会话保留的进度，比如交接摘要、todo 清单、功能清单。用户说“接着做我的作业”，靠的就是它。第 9 章的长时任务主要靠这一层。

长期记忆的写入比读取更难：

• 谁来写：模型自动写容易积累错误，人工确认又太慢。常见折中是模型提议、人确认，或只允许写入特定文件。
• 记忆污染：被注入的恶意内容如果写进长期记忆，会影响之后所有会话。写入前要校验来源。
• 过期与冲突：项目约定会变，记忆要能更新和失效。更正一条旧记录时，新记录要带上来源、更新时间和“取代了哪条”，否则两条矛盾的记录会并存，模型不知道信哪个。
• 存储方式不决定检索方式：同一份文本笔记，可以用关键词搜（适合 ID、日期），也可以用向量搜（适合换了说法的问题），或者两者混合。先用文件存，检索方式以后可以换。
• 定期整理：原始历史越积越多。有的 agent 会定期把历史对话压成几条持久的事实和偏好，写进记忆文件，原始记录留着备查。

二者可以结合：把检索包装成一个工具（search_docs），由模型决定查不查、查几次、换不换关键词，这叫 agentic RAG。RAG 自身的常见优化：混合检索（BM25 + 向量）、rerank、查询改写、按文档结构切块。

企业知识库问答绕不开 RAG。一条管线依次是：收集 → 清洗去重 → 切块 → 建索引 → 检索 → 排序 → 生成答案。常见问题几乎都出在中间几步：

有些问题不是找一段话就能回答的，比如“想做 AI 研究，该按什么顺序选课？”答案要把“数学 → 机器学习 → NLP”几段关系串起来。这时可以在文本块之外再建一张实体关系图，检索时沿关系找，这就是 GraphRAG。代价是建图要大量调用模型抽取实体，抽错了还会引入不存在的关系，内容更新时要同步改图。

RAG 怎么评测（召回率、排序质量、答案是否有出处、出处是否最新）放在第 15 章。

这几个词常被当成五样不同的东西，其实回答的是同一个问题：什么内容、什么时候放进上下文。区别只落在四个维度上：

下次再冒出一个“X 按需加载”的新词，先填这四列，就知道它和哪个老词只差一格。

• 规划：先产出计划再执行，可审查、不易跑偏。
• 自我验证：改完跑测试、调完查结果。给 agent 一个能验证结果的手段，往往是提升成功率最有效的一步。
• 多 agent：主 agent 把子任务交给独立上下文的子 agent，子 agent 只返回结论。

多 agent 的收益是上下文隔离和并行；代价是 token 成倍增长、子 agent 间信息不共享导致决策冲突、调试和评测更难。改同一模块代码这种强耦合任务，单 agent 往往更好。

拆开以后，问题出在“合”的时候。三类最常见的失败和对策：

第三类最说明问题：子任务各自的验证都通过了，整体还是错的。所以判断完成的验证器要放在“合”的那一层（第 15 章）。

任务跑几个小时，往往要经历多次压缩甚至多次全新会话。每个新会话就像换班的工程师，不记得上一班干了什么。Anthropic 2025 年底的《Effective harnesses for long-running agents》给出了一套被广泛借鉴的做法：

• 初始化 agent 只跑一次：把需求拆成一份功能清单（feature_list.json，每项标记通过 / 未通过），写好启动脚本 init.sh，建立进度日志，做第一次 git 提交。
• 后续每个会话固定流程：读进度日志和 git log → 跑启动脚本确认程序还能用 → 挑一个未通过的功能实现 → 端到端测试（用浏览器自动化像用户一样点） → 更新清单和日志 → 提交。
• 功能清单用 JSON 而不是 Markdown：原文的解释是模型不太会随意改写或覆盖 JSON 文件，而 Markdown 容易被“顺手整理”。
• 针对的失败模式：过早宣布完成、留下半成品状态、没测就标记完成、新会话不知道怎么启动项目。

这套做法的本质是：把记忆从上下文搬到文件和 git 里，每个会话都能从磁盘重建现场。它和第 10 章的“事件日志恢复”是同一思路在更高一层的应用。

并行的 agent 用 git worktree 隔离。同时跑多个 agent 改同一个仓库时，各自一个 worktree（同一仓库的多个工作目录），互不干扰，最后各自提交或合并。这已是 Claude Code、Codex 等工具的常见做法。

agent 做完一件事，能不能下次做得更好？不改权重也可以：把这次学到的东西写回 skill 或记忆文件，下次加载时就用上了。比如一个做幻灯片的 skill，某次渲染后发现图片压住了标题，就给 SKILL.md 加一条“图片放在标题下方，每次修改后重新渲染检查”。

有的项目把这类更新分成三种：修复现有 skill、从现有 skill 派生出适合新任务的版本、从一次成功的过程里新捕获一个 skill。做 skill 检索的项目则用 BM25 先召回候选、再用向量重排，从上百个 skill 里挑出合适的那个。

这件事的本质是第 ⑥ 个问题“验证”：同一个验证信号，用在不同的地方。

写回文件的风险和长期记忆一样：错误经验会污染以后所有任务，被注入的内容也可能借此长期驻留（第 13 章）。工程上的做法：每次更新都留版本；更新要在另一个任务上验证有效才保留，避免只对这一次有用；来路不明的 skill 先审再用。