外观
Harness 解剖:一个 Agent 运行时由哪些部件组成,哪里会坏
一句话定义:Harness 是模型之外、把一次预测变成一段可完成工作的全部装置——循环、工具、上下文、权限、状态、扩展点。它的工程量不在正常路径,而在模型编造动作、谎报完成、陷入循环时的恢复路径。
六个决定
Harness(也叫 agent scaffolding)替模型做六个它自己做不了的决定:
| 决定 | 要回答什么 |
|---|---|
| 轮次 | 再调一次模型、压缩上下文,还是停下 |
| 工具 | 有哪些动作、怎么描述、结果以什么形状回来 |
| 上下文 | 每次请求装什么,什么该扔掉 |
| 权限 | 这次调用是允许、询问,还是拒绝 |
| 状态 | 请求、会话、进程结束之后,什么还能留下 |
| 扩展 | 外部工具、技能、策略从哪里接进来 |
模型需要这六个决定,原因很朴素:它无状态、窗口有限、不能执行动作——只输出文本,总得有东西去跑。
为什么值得单独研究:成本差 40 倍,通过率差 0–8 点
《The Scaffold Effect in Coding Agents》(Sentient Labs)把 Qwen 3.6 Plus 和 MiniMax M2.5 分别放进 Goose、OpenCode、OpenHands-SDK 三套开源 harness,跑 Terminal-Bench Pro 的 50 题分层子集:
- 同一模型换 harness,每个解出任务的 token 消耗最多差 40 倍;
- 同模型配对比较,通过率差只有 0–8 个百分点,多数 95% 置信区间包含零;
- 失败指纹跟着 harness 走,不跟模型走:Goose 以 REASON 为主,OpenHands-SDK 是 VERIFY / MAX_TURNS,OpenCode 是 idle-loop / TIME。
这个结果把讨论的重心挪了位置:与其问"哪个模型更强",更该问"哪个模型–harness 组合在给定 token 与延迟预算下通过率最高"。榜单上的每一行,其实是模型、日期、配置和 harness 的混合体。
另外三组常被引用的证据:
| 来源 | 改动 | 结果 |
|---|---|---|
| LangChain | 只换 harness | Terminal-Bench 2.0 上差 13.7 个百分点 |
| Vercel | 删掉 80% 的工具 | 成功率 80% → 100% |
| SWE-agent 消融 | 去掉文件编辑器 / 加上 lint | −8 点 / +3 点(模型不变) |
四种形态:循环在谁手里
同名不同物,判断顺序是"循环在谁手里 → 状态存在谁那里 → 换掉它要重写多少"。
| 形态 | 循环归谁 | 代表 | 代价 |
|---|---|---|---|
| Harness | 产品自己持有,用户配置与操控 | Claude Agent SDK(把 Claude Code CLI 起成子进程) | 只能用自家模型;定制从配置层开始 |
| SDK | 开发者自己写 | Vercel AI SDK(统一 provider,循环手写或用 stopWhen) | 状态、持久化、审批都要自己接 |
| Framework | 框架以显式状态机持有 | OpenAI Agents SDK(Runner、handoff、guardrail、max_turns、RunState) | 要接受框架的抽象与生命周期 |
| Hosted runtime | 服务商持有 | OpenAI Agents API、Anthropic Managed Agents | 锁定最深;租户数据落在对方容器里 |
四种形态里,持久化和审批的位置差别最大:SDK 通常把 UIMessage[] 留给开发者,框架用可序列化的 RunState,托管运行时则把会话、沙箱、压缩都收走,只留控制和评测给调用方。
循环:六步与一个严格契约
一次迭代的六步:
- 组装请求:系统提示词、工具、指令文件、记忆、对话;
- 模型返回文本或工具调用;
- 检查权限:允许、询问、拒绝;
- 在沙箱里执行被允许的调用;
- 把结果作为观察追加进去,再调一次模型;
- 对话超过可用窗口时压缩。
真正难的是第 5 步的配对契约。工具调用响应带 stop_reason: tool_use 和若干带 id、name、input 的块;宿主必须返回引用同一个 id 的 tool_result。少一个,下一次请求可能直接被 API 拒绝。并行批次让这件事更容易出错:一个工具失败会取消同批的其他调用,留下一批没有结果的孤儿调用。
修补方式是确定的:在下一次模型请求之前,为每个孤儿调用合成一条错误结果。Claude Code 这么做,OpenHarness 也在这条路上踩过坑。
有人估算过 Claude Code 的代码构成:正常路径大约 200 行,剩下 1,500 行恢复逻辑才是真正的产品。 这个数字未经官方确认,但它准确描述了这类系统的成本结构。
怎么停下来
停止不是看一个字段就够的:
- 停止原因有
end_turn、tool_use、max_tokens三种; - 生产循环通常看内容而不是看标签:只要消息里有工具调用,就执行并继续,哪怕标签写着
end_turn——有 harness 观察到 Opus 在end_turn下仍然发出工具调用; - 停止原因真正用于截断:
max_tokens的消息可能带着被切断的调用,这些调用应当全部失败并要求重发,而不是执行半截参数。
harness 自己设的停法有三类:轮次上限(OpenAI Agents SDK 默认 10,超了抛 MaxTurnsExceeded;Vercel 的 ToolLoopAgent 默认 20;Claude Agent SDK 默认不设,设了返回 error_max_turns)、上下文溢出、以及 stop hook 或用户中断。
"做完了"和"在等人"必须分开。 没有工具调用可能是任务完成,也可能只是把控制权交回用户。两种做法:把完成做成显式动作(Cline 的 attempt_completion),或者用一个小的判定模型判"未达成 / 已达成 / 不可能"(Claude Code 的 /goal)。
死循环的典型成因不是模型笨,而是工具在状态没变时返回"再试一次"。检测靠对"工具名 + 参数"签名计数:
| 实现 | 阈值 |
|---|---|
| OpenCode | 连续 3 次完全相同 |
| Crush | 10 步窗口内超过 5 次 |
| OpenClaw | 30 条历史,10 次警告、20 次严重、30 次同调用无进展则熔断 |
阈值在早停与浪费之间取舍。OpenClaw 的熔断默认关闭,压缩重试之后只剩一层较窄的保护。
工具就是提示词
工具描述直接塑造行为。 Claude Code 把 git commit 与 PR 的规则写进 Bash 工具的描述里,社区统计约 1,558 token;Pi 反过来,把系统提示词和工具定义一起压在 1,000 token 以内,不要内置 MCP、子 agent、权限弹窗、计划模式。一个第三方测试里,4,675 token 的提示词在 8 项测试上 80% 准确,128 token 的提示词 100%——这组数字不能直接推广,但足以说明"写得更详细"不等于"效果更好",工具描述的重量是模型相关的。
提示词缓存让工具集不能随便动。 Anthropic 的缓存对 tools、system、messages 做累积哈希,改工具定义(名字、描述、参数)会让整个缓存失效,而缓存读只要基础输入价的 0.1×。所以生产 harness 一般不做"按任务裁剪工具",而是发一个稳定超集、固定顺序,把模式变化做成工具(例如 EnterPlanMode)。需要省上下文时用延迟加载:defer_loading: true 加一个搜索工具,取到的定义内联追加、保持前缀不变;搜索工具本身不能延迟。
工具结果的设计决定了下一轮会不会被误导:
- 副作用要幂等:Temporal 按 run 加 activity id 去重,Inngest 把
step.run()的结果存下来重放; - 状态不会变时别返回"再试一次";
- 在边界归一:vLLM 记录过 Llama 系模型把数组序列化成字符串的问题;
- 截断要标注:OpenClaw 保留 Bash stderr 的 64 KiB 尾部,并报告丢了多少字节;
- 形状要眼熟:越接近后训练时见过的格式,模型越省力。
编辑工具是一个独立话题。 Aider 在 89 个 Python 重构任务上,把 SEARCH/REPLACE 块(约 20%)换成 unified diff(约 61%),"懒编码"从 12/89 降到 4/89。多匹配时必须大声失败并返回匹配数,而不是悄悄改第一处。
权限与沙箱:写在模型忘不掉的地方
规则必须在代码里执行。 Pulumi 的说法很直接:提示词护栏会随上下文变长而退化,所以保护要放在模型忘不掉的地方。Claude Code 的六种模式(plan、default、acceptEdits、auto、dontAsk、bypassPermissions)解析为 allow / ask / deny,deny 和 ask 压过 allow,deny 即使在 bypass 下也生效。
一个容易踩的坑:在 Claude Agent SDK 里,allowed_tools 约束不了 bypassPermissions,只有 disallowedTools 能拦。另一个是执行时不再复查——Vercel AI SDK 的 issue #8653 记录过,被 activeTools 过滤掉的工具仍按全量执行。
沙箱经常只盖住 shell。 很多 coding harness 的文件工具跑在进程内,根本不在沙箱里。凭证必须留在外面:Anthropic 的做法是每会话发一个限定范围的 token,真凭证留在宿主 keychain;出口默认拒绝,参考 harness 只放行 api.anthropic.com:443,OpenClaw 的 Docker 默认 network: "none"。token 过期要优雅停机,不能 fail-open。沙箱是一次性的,所以持久状态必须在子进程启动前从外部存储或 SessionStore 注入。
审批要绑定到具体操作。 OpenClaw 存下 argv、工作目录、agent、session 和环境哈希,命令一变就拒;Vercel 可以对工具名、call id 和参数做 HMAC 签名。超时要拒绝:OpenClaw 等 30 分钟,然后走默认拒绝;找不到审批人时立即拒绝。
审批疲劳是真实的。 有观测显示,人对危险命令的发现率从会话早期的约 17% 掉到 50 条审批之后的约 5%。Anthropic 报告自己的批准率从 93% 升到 97%,但在它的实验里,危险命令被人工发现的概率是 13.6%,自动模式分类器是 89%。结论不是"不要人审",而是把人留给高代价、可批量、可预览的决定,并且把授权范围本身当作边界。
上下文:在窗口满之前动手
"上下文腐烂"是可测的。 NoLiMa 用几乎没有字面重合的问题测 13 个宣称 128K 以上窗口的模型:到 32K 时,11 个模型掉到自己短上下文基线的一半以下;表现最好的 GPT-4o 也从 99.3% 掉到 69.7%。压缩必须在宣称上限之前触发。
压缩触发的三种算法:
| 方式 | 代表 | 做法 |
|---|---|---|
| 绝对缓冲 | Claude Code、OpenCode、Pi | 剩固定 token 数时触发 |
| 比例 | Goose 0.8、Gemini CLI 0.5 | 按窗口比例 |
| 混合 | OpenClaw | 预留 20,000 token,小窗口向 0.5 退化——否则小模型会在第一个 token 就压缩 |
Claude Code 的微压缩是确定性的:把旧工具结果正文换成 [Tool result cleared],保留最近 3 条,累计 20,000 个可清理 token 后触发。
遮蔽(masking)和摘要(summarization)的差别比想象中小。 在 150 条 SWE-Bench Verified 轨迹上,遮蔽解出 54.8%,每条 $0.61;摘要 53.8%,每条 $0.64。只有在预算最紧时,摘要才明显赢过 FIFO 截断(AppWorld 上 72.8% 对 42.2%)。可行的默认是分层:先遮蔽,空间不够再摘要。
压缩之后,只有被重新注入的东西还活着:指令文件、自动记忆、最近改过的文件。其余要靠外部产物——init 脚本、进度日志、功能状态、git 历史。Anthropic 自己也承认,压缩"并不总能把手头清晰的指令完整传给下一个 agent"。
记忆、反思与自我改进
记忆分四类,各有各的失效方式:
| 类型 | 何时进入上下文 | 主要问题 |
|---|---|---|
| 指令文件 | 每次请求都加载 | AGENTS.md 没有正式规范,嵌套文件行为各家不一 |
| Agent 笔记 | 按需检索 | 检索失败就等于没有 |
| 会话状态 | 恢复时读回,通常是 JSONL / SQLite | 往往也是唯一的审计日志 |
| 压缩存活策略 | 压缩后重新注入 | 决定了前面三类里什么能活下来 |
推的记忆每轮都花上下文,拉的记忆要花一次检索决策和延迟。 OpenClaw 用子 agent 检索,给 15 秒预算,超时就走熔断跳过;常驻意图用关键词匹配、冷却、触发预算和过期时间,匹配路径里没有模型调用。它的长期记忆预载两天日记,上限 2,800 字符,并明确标注为不可信的工作区笔记;写入落在用户能检查、能编辑、能忘记的文件里。
反思有三层,失败面各不相同:
- 整合:从笔记和轨迹重写记忆,失败会丢事实;
- 自审:把一次运行和纠正变成经验或技能,失败会教错流程;
- 自我改进:改 harness 本身,失败会动到每一道护栏。
OpenClaw 的后台整合任务("做梦")每天凌晨三点跑:轻层回看 2 天,REM 层 7 天,深层只在 minScore 0.75、minRecallCount 3、minUniqueQueries 3 时提升,按 14 天半衰期计权,30 天外的条目忽略;一次重写如果丢掉超过 25% 的旧条目就拒绝,退回追加模式,并保留改写前的副本。
自我改进的风险更集中。OpenClaw 的技能工坊要求 agent 先提交提案,由人执行应用命令;上海 AI Lab 的 Self-Harness 让 agent 根据失败运行改自己的 harness;Rust 写的 exo 让 agent 改完自己重新编译,但只验证 cargo build 退出码为 0,没有测试和评测。共同护栏是三条:保留改写前的镜像、限制删除比例、把提案者和拍板者分开。 这些反思是否真的改善了后续运行,在现有材料里没有被测过。
成本:限流必须在模型外
OpenClaw 没有任何"按花费停机"的机制,它的文档写得很明白:token 预算是会话目标护栏,不是账单上限。三个 SDK 里只有 Claude Agent SDK 带 maxBudgetUsd,而且最终花费可能超出一个完整 API 调用。
失控的样本很有说服力:Alexandre Agius 的 agent 在 12 小时里开了 204 个 PR,产生 509 次连续构建失败,花掉约 $900,原因是每次都是无状态的五分钟调用。修法是一组原子计数器:每个应用只允许一个并发运行、每天 5 个 PR、每天 $10,触碰 3 次后熔断。
心跳也会烧钱:OpenClaw 把连续空闲超时限制在 5 次;有一次心跳在 60 秒内产生 761–1,384 次付费 Anthropic 调用,单次事故 $20–30。网关侧的限流往往滞后,因为成本是在请求完成之后才记账的。真正该看的指标是 cost per solved task,不是单次请求价格。
委派:主要理由是上下文
子 agent 的第一价值不是并行,而是干净的上下文:Claude Code 的子 agent 从约 500 token 开始,而不是继承 45,000 token 的无关对话;fork 出来的子 agent 继承父前缀,换的是缓存命中。继承方式差别很大:Claude 子 agent 只返回最后一条消息;OpenAI Agents SDK 的 handoff 转发完整历史并转移回复所有权。
多 agent 是否更好,证据是打架的:
- Anthropic 报告其多 agent 研究系统比单 agent 的 Opus 4 高 90.2%,且 token 用量解释了 80% 的方差;
- 一项等预算研究发现,把思考 token 控制住之后,单 agent 持平或更好;
- 一项 260 组配置的研究发现,当一个 agent 的准确率已经超过 45% 时,多加 agent 是负收益。
上限也很具体:Claude Code 允许 20 个并发子 agent;OpenClaw 默认 8 个并发、每个 agent 5 个子 agent、深度 1,并且拿掉了子 agent 的消息、调度和跨会话发送能力。
持久与主动:队列、检查点与心跳
持久化的标准形状是队列 + worker + checkpoint store。OpenClaw 的入口队列负责存储、认领、完成和墓碑,按消息 ID 去重;Temporal 重放事件历史,Inngest 从失败步骤恢复,Restate 从日志前缀重启。恢复预算防的是崩溃循环:OpenClaw 允许 3 次计费尝试,之后把会话墓碑化,子 agent 只有 2 次。
流式要分两条车道:权威的持久状态和瞬时的进度。重连顺序是订阅、读历史、用单调序号去重;观众离开应该 detach 而不是 cancel,取消要有独立的鉴权端点。
webhook 是指针,不是内容。 OpenAI Agents API 的五个签名事件里,action required 不带细节,handler 必须回查会话;idle 表示可以接输入,不是成功;failed 也不报告每一次失败的轮次。收到 webhook 先持久化入队,再返回 200。
心跳默认 30 分钟一次,提示词刻意很窄(不要从旧对话推断或重复任务),多数心跳应当静默结束。自动化是持久化的 cron 任务,保障包括最小 30 秒间隔、60 秒内超过 5 次唤醒就顺延、退避从 30 秒到 60 分钟、连续 10 次失败后禁用。
评测:固定模型,报每解一题的成本
OpenTelemetry 的 GenAI 约定仍是 stability: development,OpenInference、MLflow、OpenLLMetry 各定义各的 span。最低要求是每次工具调用都有记录:至少一个 execute_tool span,带工具名和 call id,再加参数、结果、耗时和权限决定。
评测的口径比工具更重要:必须固定模型,否则测的是混合体;榜单行要标注 harness 与配置;同时报通过率和 cost per solved task;基准版本要写清——Terminal-Bench 2.1 修了 2.0 里 89 题中的 28 题,tau-squared 在 v1.0.1 以下的结果不可比。
Birgitta Böckeler 把 harness 的装置分成两类,值得当作检查表:
| 计算型 | 推断型 | |
|---|---|---|
| 引导(前馈) | 权限规则、AGENTS.md、延迟工具加载 | 两段式 Bash 分类器、规划子 agent |
| 传感(反馈) | 死循环检测、测试、类型检查、唯一性失败 | 基准、LLM 评审 |
传感器依赖"可 harness 性":有类型系统才谈得上类型检查,有清晰模块边界才谈得上架构约束。harness 在最难造的地方最需要。
Harness engineering 这个说法是怎么来的
2026 年初,四篇文章把它推成一个独立词:Mitchell Hashimoto(2 月 5 日)、Ryan Lopopolo(2 月 11 日)、Birgitta Böckeler(2 月 17 日)、Vivek Trivedy(3 月 11 日)。
两种嵌套方式并存:Böckeler 与 LangChain 把它放在上下文工程之内——"今天的 harness 很大程度上是好的上下文工程的投递机制";Wikipedia 则把它放在提示词工程与上下文工程之上,指整个运行环境的设计。
一个有用的判断标准:被包裹的组件是非确定的。正因为它会编造动作、谎报完成,harness 才必须能在这些情况下恢复;确定性的组件不需要这样一层。
模型也在反过来适应 harness。今天的 agent 产品在后训练时把 harness 放进循环,模型因此学会了特定的工具名、schema 和结果格式;这也意味着改工具逻辑可能让表现变差,自定义 harness 应尽量让形状贴近训练分布。2026 年的两项工作把影响做成了双向:Self-Harness 让 agent 改自己的 harness;UIUC、伯克利与 Chroma 的 Harness-1(200 亿参数)则靠重设计检索环境,而不是放大模型来提升效果。
开工前先回答
- 工具集是稳定超集、固定顺序吗?稀有工具走延迟加载吗?
- 每个孤儿工具调用都能拿到一条错误结果吗?
- 由内容决定是否继续吗?
stop_reason只用来标截断吗?完成是显式动作吗? - 死循环签名计数器默认开着吗?
- 权限在代码里执行吗?deny 优先吗?执行时还复查吗?
- 文件工具在不在沙箱里?凭证在不在沙箱外?
- 持久状态在文件或记录里,而不只在对话或沙箱里吗?
- 花费上限是外部计数器,按 run、job、天分别计数吗?
- 审批绑定到具体动作吗?能批量、能预览、超时拒绝吗?
- 每个引导都配了传感器吗?评测固定模型、报了 cost per solved task 吗?
边界
- 这是一篇综述,数字分别来自论文、工程博客和社区测量,口径不一,均未复现。
- 大量默认值(工具集、阈值、心跳间隔)随版本变化,引用时要带版本或日期。
- 例子集中在 coding agent 与少数开源 harness,非编码场景要重新换算,不能照搬阈值。
- 部分关键数字是单一来源或社区估算,例如 1,558 token 的工具描述、27,169 token 的空目录脚手架、200 行与 1,500 行的代码比例。
参考资料
- 原文:What Is an Agent Harness? Parts, Architecture, and What to Know Before Building One
- The Scaffold Effect in Coding Agents
- NoLiMa: Long-Context Evaluation Beyond Literal Matching
- Anthropic:Tool search tool
关联词条
- Harness(智能体执行框架)(concept)—— 定义与为什么重要的锚点
- 从一次 LLM 调用到完整 Harness(concept)—— 能力栈如何一层层长出来
- 工具按需加载:把工具目录从系统提示词里挪出去(pattern)—— 工具暴露与缓存前缀的成本账
- 监督比你聪明的 Agent:六个动作与 Lint 倒金字塔(pattern)—— 把校验做成可执行的传感
- Always-on Agent 的三个设计共识(pattern)—— 循环之外的持久化、恢复与授权
- 返回 核心概念