如何设计 Agent Harness：把大模型变为可自主工作的六大核心决策

原文来源：X 上的 Yarchi

你的 Agent 声称任务已经完成，但测试却从没真正跑过。它在前二十分钟表现敏锐，随后就忘了你在开头立下的规矩。你在每个会话里反复敲入同样的三条指令。你甚至无法离开屏幕，因为总有下一个审批等待你去点击确认。

换一个更好的模型解决不了这里的任何问题。所有这些问题都根植于包裹在模型外面的软件层：它被告知了什么、它保留了什么、允许它触碰什么，以及由谁来核验最终的结果。这个包装层就是 Harness（控制外架）。你其实已经拥有了一个 Harness，唯一的问题在于——是否有人真正设计过它。

什么是 Agent Harness

在模型与具体工作之间，横亘着六件事：

让它持续运转的循环（Loop）、它能调用的工具、留在它记忆中的内容、进程崩溃后能幸存的数据、允许它触碰的边界，以及由谁来裁定任务已经完成。

这其中有一半是随开箱自带的。你的供应商构建了循环机制、内置工具以及记忆处理方式，这些你改动不了多少。而另一半则属于你：你的指令文件、你的自动化测试、你的权限体系，以及你对“完成”的定义。无论你是否思考过，这一半都客观存在。你在对话框里反复输入的每一条规则，都是其中的一部分。

人们在 2026 年初开始把这一层称为“Harness”。在此之前它没有统一的称谓，这也是它为何被长期忽视、缺乏管理的主要原因。

真实生产案例

DoorDash 将其构建为一个平台。 每个 Agent 都在独立的一次性虚拟机中运行，启动时代码仓库、工具和凭证均已就绪。工作本身被编写为 YAML Playbook，将 Agent 步骤与常规脚本步骤混合编排。所有访问内部系统的操作都经过一个网关，该网关仅下发 Playbook 声明需要的工具，并记录每一次调用。他们单月运行了 130,000 个自动化任务，其中包括每周超过 25,000 次代码审查。

OpenAI 将其构建为一个代码仓库（Repository）。 根本没有平台。他们将代码仓库本身视作 Harness：指令文件保持在 100 行左右，作为指向真实文档目录的索引目录；架构规则通过自定义 Linter 强制执行，而不是写成模型可能跳过的自然语言文本。三名工程师借此在五个月内合并了约 1,500 个 Pull Request。

Anthropic 将其构建为角色拆分（Role Split）。 三个各司其职的 Agent：一个将单句话需求转化为规范文档（Spec）；一个负责编码实现；另一个在真实浏览器中操作运行生成的应用并打分验收。它们之间仅通过互相写入文件来进行通信。这种方式切实可行，但耗时 6 小时且花费 $200，而没有 Harness 的单次直接运行仅需 20 分钟和 $9。为了获得好得多的结果，付出了超过二十倍的成本——这是谁也没公开宣传的取舍代价。

三种截然不同的形态。它们的共同点是：没有一种是开箱即用的默认产物。

六大核心决策

这才是产生实际效益的部分。每一条都很简练：它是什么、具体该怎么做、它的价值何在，以及何时可以跳过。

1. 运行循环及其中止条件（The loop, and where it stops）

你的 Harness 将任务以及截至目前发生的所有上下文发送给模型。模型回复工具调用请求或最终文本消息。如果是工具请求，Harness 执行它，将执行结果追加到历史记录中，然后将全部内容再次发送给模型。重复此过程，直到模型停止请求工具。市场上每一款产品中的整个循环机制莫不如此。

该怎么做：

1. 设定硬性的迭代轮数上限（Turn Limit）。 不要问“任务会花多长时间”，而是问“在判定陷入死循环之前，你愿意接受它在同一个错误上打转多少次”。一般任务设为 20 到 30 轮；超过此限制意味着它迷失了方向，即使继续给它 50 轮也不会让它神奇地找到出路。

2. 区分“无法继续”与“已完成”。 当模型无计可施时，默认倾向于向用户汇报“已完成”，哪怕什么都没做成。必须拦截最终输出，要求它出示证明：测试通过的控制台输出、运行命令的退出码、生成的文件是否存在。如果没有证明，就拒绝终止并将原因打回给它。

3. 当它陷入循环时，不要只是把报错再次抛给它。 如果它尝试同一条命令失败了两次，第三次请向上下文注入一句强制要求：“你已经在这个步骤失败了两次，请换一种完全不同的方法，或者向人类求助。”这能打破大部分模型在修复失败时表现出的局部最优死锁。

4. 如果让其无人值守运行，请把每一轮交互都记录到事后可读的文件中。 你一定会需要它，而靠记忆去还原一个历时六小时的会话是完全不可能的。

有人曾手动审查了 50 个公开的 Agent 循环实现。其中只有 74% 声明了什么才算完成，只有 32% 在多次运行之间保留了任何记忆。这是清单上成本最低的改进项，也是最常被略过的一项。

2. 暴露给它的工具菜单（The tools it can see）

模型看不到你的系统。它看到的只是一份函数描述菜单，就模型而言，这份菜单就是它的整个世界。关于这份菜单，有两点值得高度重视。

该怎么做：

1. 停止在初始阶段就加载所有工具。 如果你连接了数个 MCP 服务器，每一轮对话中，所有工具的描述都会被硬塞进上下文，无论当前任务是否需要它们。解决方法是将工具以文件形式保存在磁盘上，让 Agent 仅在需要时按需读取。Anthropic 曾发布过一个实践案例：工具 Token 从 150,000 锐减至 2,000。

2. 重写错误提示信息。 大多数工具失败时返回的是面向人类的句子：“invalid request（无效请求）”。这对模型毫无帮助，导致它开始瞎猜，而且通常猜错。应当返回结构化错误：哪个字段有误、有效值应当长什么样，以及下一步可以尝试什么。西门子（Siemens）对此做过严谨测试，任务完成率提升了 37 到 40 个百分点，且每次成功消耗的 Token 减少了约一半。

3. 精简工具菜单。 去检查一下你的 Agent 当前拥有多少工具的访问权。凡是一个月内没见它用过的，果断移除。两个名称相似、容易混淆的工具带来的危害，远大于缺失一个工具。

4. 如果你构建自定义工具，需特别注意： 工具的命名与分组方式会显著改变模型的行为。前缀和后缀绝非纯粹的表面修饰。

如果你只是在一个代码仓库上运行单个 Agent 并仅使用内置工具，可以跳过此项。节省 Token 是实在的，但这还不是你的核心瓶颈。

3. 上下文记忆的留存（What stays in memory）

模型对你任务的所有了解都存放在一个缓冲区内。当缓冲区满载时，较早的内容会被总结并丢弃。你无法挑选丢弃什么，模型也不会通知你丢弃已经发生。

该怎么做：

1. 不要填满它。 在百万 Token 级别的模型上，用到 300,000 到 400,000 Token 就应该停下来。超过这个水位，其失败表现不再像单纯的困惑，而开始表现为粗心大意——比如删掉本该保留的配置文件。

2. 有目的地主动修剪，并在你指定的节点进行。 不要任由自动上下文压缩（Auto-compaction）在任务中途触发，而应将工作结构化为阶段：调研、输出规范文档、制定方案、执行落地。每个阶段都在干净的全新窗口中启动，仅携带上一阶段产出的文档。你在各阶段之间审阅文档。速度虽慢，但可靠性高得多。

3. 固定关键规则（Pin the rules）。 将事实与规则区分开来。事实可以被总结压缩，规则绝不可以：严禁改动生产环境、严禁提交密钥、此 API 契约已冻结。把这些写入文件，让 Agent 在每次重置后重新读取，并在系统提示词中重复强调。双重保险，有意为之。

4. 当它开始一味顺从你时，立即重启。 如果模型连续接受了你的五个建议而没有任何质疑或推敲，这个会话就已经废了。前面的环节必定混入了错误，而后续的一切都在将其当作既定事实对待。请开启全新的窗口。

一项研究测量了 Agent 违反既定策略规则的频率，发现全量可见时违规率为零，压缩后升至 30%，在表现最差的模型上甚至高达 59%。而当规则在总结过程中得以保留时，违规率保持为零。固定规则彻底解决了这一问题。该论文为单作者且未经同行评审，因此可将其视作强线索而非定论。无论如何，落地该方案只需半个下午。

4. 崩溃后幸存的数据（What survives a crash）

你的 Agent 注定会在任务中途崩溃。窗口填满、进程崩溃、或者你合上了笔记本电脑。凡是仅存在于对话上下文中的东西，瞬间化为乌有。

该怎么做： 在仓库中维护四个文件，并要求 Agent 始终保持更新：

1. SPEC.md：你要构建的内容。由你编写，Agent 绝不可编辑。这是防止目标在长周期运行中发生漂移的锚点。

2. PLAN.md：执行步骤，每步都带有明确的验收标准。不要写“改进错误处理”，而应写“带有缺失 id 的 /orders 请求返回带消息的 400 状态码，且断言此行为的测试通过”。

3. PROGRESS.md：已完成项、下一项、尝试过但失败的方案。这是全新启动的 Agent 首先读取的文件。

4. DECISIONS.md：仅追加（Append-only）。记录做出的每一项决策及其缘由。没有它，后续会话就会反复争论你两小时前就已经敲定的决定。

随后，要求 Agent 在每次有效的变更后进行 Git Commit。规范书写小颗粒度的 Commit Message。回滚变成了 git revert，审查变成了检视 Diff，你无需自行开发检查点系统，就能免费获得完整的版本历史。

如果你在构建包含许多独立特性的系统，再加第五个文件：一个纯 JSON 列表，标记每个特性的通过或失败状态。这是最廉价的进度跟踪器，Agent 自己就能维护。

如果它不在文件中，它就不存在。

5. 允许触碰的权限边界（What it's allowed to touch）

运行在你笔记本上的 Agent 拥有你的 SSH 密钥、你的 VPN 会话，以及你已登录的每一个 CLI 工具。它不需要具备主观恶意，事情就可能变糟——上下文里只要混入一个被投毒的网页就足够了。

该怎么做：

1. 在操作系统层面设立两道防线。 限制它能写入的目录，并将其网络访问通过带有允许域名白名单的代理进行路由。在操作系统级而非 Agent 内部进行限制，这样它派生出的任何子进程都能被覆盖。一个调用脚本、脚本再调用 curl 的 Agent 可以轻易绕过应用内限制，但绕不过系统级边界。

2. 停止信任审批弹窗（Approval prompts）。 人们会盲目点击批准 93% 的弹窗。一个你总是直接点过的弹窗根本不是安全控制，而是你给自己设置的绊脚石。仅将弹窗用于你真正愿意停下来核实的少数关键事项，其余一律交由边界控制。

3. 如果多个人针对共享系统运行 Agent，在这些系统前放置一个统一网关。 它仅发放任务声明需要的工具，并记录每一次调用。这些审计日志能让事故变得可排查，而不是一头雾水。

4. 绝不在沙箱中放置长期凭据。 使用限定在单次任务范围内的短期 Token。如果 Agent 能读到一个密钥，就默认该密钥已经存在于某处的上下文窗口中。

Anthropic 报告称，在内部引入完善的沙箱隔离后，权限提示弹窗减少了 84%。这才是真正的论据：它不仅更安全，而且远没那么恼人，这才是它能真正坚持落实的原因。

6. 由谁来裁定任务完成（Who says it's done）

编写代码的 Agent，是判断代码是否正常工作的最差人选。它给自己打分，而且打分总是极其宽容。

该怎么做：

1. 在独立的会话中进行审查。 全新的窗口，没有任何编写该代码的上下文记忆。使用同一个模型也没问题，核心在于它没有携带产生 Bug 时的主观推导偏执。

2. 让它真正运行起来。 对于 Web 应用，在真实浏览器中操作它；对于 CLI 工具，实际执行命令。仅仅读取 Diff 并宣称它正确不是验证，而是在同一个猜测上给出的第二份主观意见。

3. 基于你过去踩过的真实坑构建评测集（Eval set）。 20 到 50 个任务就足够起步。必须是来自你仓库中亲眼见过 Agent 搞砸的真实任务。

4. 每个任务运行三次，并以最差的那次作为评判基准。 这比听起来更关键。单次尝试 75% 的成功率，意味着三次尝试全部通过的概率只有 42%。Agent 具备非确定性，单次绿灯几乎说明不了任何问题。

5. 警惕自信满满的错误答案。 Agent 典型的失败方式不是崩溃报错，而是在遇到错误时，条理清晰地写下一大段漂亮的说辞解释为什么这个错误无关紧要。在一项生产环境研究中，约 70% 的此类问题是由人工观察捕获的，而非自动化测试。在错误处理附近的日志中，Grep 搜索那些“解释形状”的说辞文本。

目前尚无公开的重试策略数据。重试多少次、退避时长如何设置、是就地重试还是彻底重启清理。每个人都有见解，但没人有确凿数据。如果你发现自己在参数微调上耗费数日，要明白你正在探索真正的无人区。

周末速成版（The weekend version）

如果你只打算构建五件事，请严格按以下顺序推进：

1. 一份 100 行以内的指令文件。 作为进入真实文档目录的索引，而不是百科全书。冗长的指令文件会被粗略扫视，就像冗长的邮件一样。

2. 凡是坏过两次的东西，就写成 Linter。 不是写一段恳请模型配合的自然语言段落，而是一条能直接中断构建的规则。见到真实故障时就添加一个；当更好的模型使其不再必要时再删掉。

3. 四个文件。 SPEC、PLAN、PROGRESS、DECISIONS。加上每次有效变更后的 Git Commit。

4. 固定绝不能被总结冲掉的规则。 安全底线、政策约束与硬性限制。

5. 二十个任务，每个运行三次，按最差结果评定。

除此之外的一切，都属于后续优化。

总结

你无法选择“不要 Harness”。你此刻就已经拥有一个 Harness，它就是随着时间推移积累下来的各种产物：凌晨两点添加的各种临时融通手段、粘贴到配置里然后被遗忘的规则、以及因为点击比阅读更快而被顺手通过的权限弹窗。其中的决策早已做出，只是并非由你主动设计。

而且这一切不是免费的。Anthropic 自己带有完整 Harness 的运行成本是无 Harness 运行的二十倍以上。这才是你在动工前需要回答的真正问题：Harness 的价值在于承接那些你原本根本无法脱手的工作，而绝非用于帮你省下二十分钟琐碎时间的任务。

从终止规则与四个持久化文件开始。这两项只需半个下午。而且它们能平稳跨越下一代模型的迭代发布，而这里的大多数其他东西都做不到这一点。