Harness 工程：构建可靠 LLM 智能体的外围系统之道

编者摘要：模型本身不是智能体，需靠 harness（运行时与控制机制）连接能力与行动，即 agent system ≈ model + harness + environment。

工具接口是重点：接口设计决定任务难度（ACI）；工具是模型输入的一部分，应少而精、返回高信号结果、错误结构化；MCP 只是互操作层，不构成完整 agent 循环。

上下文工程：活动上下文由 harness 决定，宜用渐进式披露而非堆料；持久历史≠活动上下文；压缩是有损的。

安全：审批控制决策、遏制控制可达能力（凭据留在沙箱外、硬边界兜底）；观察有来源，需防提示注入，skill 按第三方代码审查。

可靠性：验证应锚定可观察状态而非自报完成；自动重试按幂等性分级；长运行与并发会继承持久性、一致性问题；委托子代理由任务分解驱动，勿默认「更多更好」。

评估：measured performance = F (model, harness, environment, task, grader)，环境 /harness 变化可独立改变结果。

工程原则：能用机械强制就不靠模型服从；每个 harness 组件都是对当前模型局限的假设，模型升级后需重新检验，避免累积过时层。

一句话：harness 工程即把各类失败模式变成可观察、可测试的系统属性。

这份手册的最大价值是把「智能体质量」从「模型多强」里剥离出来，反复证明：在不改模型权重的情况下，harness 的设计（接口形态、上下文策略、工具数量与结果、审批 / 遏制边界、验证机制、预算、恢复、子代理取舍）能显著改变系统表现。因此工程上的可操作原则可归纳为：①工具宁少而精、返回高信号、错误结构化；②上下文用渐进披露而非堆料；③能用机械强制就不用散文或靠模型服从；④完成要锚定可观察状态而非自报；⑤重试要按幂等性分级；⑥每个 harness 组件都是「对当前模型局限的假设」，模型升级后要重新检验。

附录 《理解 Harness 工程（Understanding Harness Engineering）》

一份面向 AI 工程师 / 开发者、讲解智能体「外围支撑系统层」的技术手册。作者 @techNmak，属于 "Understanding AI" 系列专题。下面是结构化详细总结。

一、命题与全书主线

一句话主旨：一个能力强大的语言模型本身并不是一个能工作的智能体（agent）。在模型周围必须有一套机制来决定「模型看到什么、能调用哪些动作、如何执行、如何返回观察、如何保持状态、如何授权、如何从失败恢复、是否需要下一步、任务是否真的成功」—— 这套机制就是 agent harness（智能体支架 / 运行框架）。

核心心智模型（全书第 3、43 章反复强调）：

agent system ≈ model + harness + environment

关键术语界定（本书自用划分，非行业标准）：

• Agent harness
  ：紧贴模型、让其能多步行动的运行时与控制机制。
• Harness engineering
  ：更广的工程学科 —— 设计接口、上下文策略、状态、执行环境、控制、反馈、恢复、验证等让智能体工作可靠的一切。

各厂商用词不一：Microsoft 用 harness 指「把模型变成智能体的运行时脚手架」；Anthropic 把「持久会话 / 运行模型 - 工具循环的 harness / 执行代码的 sandbox」分开；OpenAI 更广义地指「环境、反馈环、仓库结构、约束、可观测性等脚手架」。

二、最小智能体循环（第 2 章）

用四个演化对象描述一个 harness：

• s_t
  = 第 t 步之前的工作 / 持久状态
• c_t = G(s_t)
  = 为下一次模型调用选定的上下文
• a_t = M(c_t)
  = 模型输出（可能含动作请求）
• o_t = E(a_t)
  = 环境执行动作后产生的观察
• s_(t+1) = U(s_t, a_t, o_t)
  = harness 更新状态

循环过程：任务 → 组装活动上下文 → 模型调用 → 判断「最终答案 or 动作请求」→ 策略 / 审批 / 工具路由 → 环境执行 → 观察 + 状态更新 → 再调用模型。理论前身是 ReAct（推理与动作交错），但现代 harness 无需暴露 / 持久化私有推理轨迹，只保留「行动 — 观察 — 更新 — 继续」的耐久系统思想。

三、harness 到底控制什么（第 3–4 章）

harness 可能决定：哪些指令 / 状态进入上下文、哪些工具可见、工具 schema 如何表示、是否允许调用、是否需人工审批、工具如何执行、结果如何转化、历史如何持久化、上下文如何压缩、何时建子代理、错误如何返回、重试策略、何种预算终止运行、接受完成前需要哪些证据、如何记录轨迹 / 指标、中断后如何恢复。

术语区分表（第 4 章）：

关键洞察：这些组件故障方式不同、信任假设不同，所以概念上必须分开（如 Anthropic 的 Managed Agents 明确分离 session = 追加式日志、harness = 调模型 + 路由工具、sandbox = 跑代码 / 改文件）。

四、工具接口设计（第 5–11 章）

这是全书最重的实操部分，核心结论：

1. 模型不是和「电脑」交互，而是和一个接口交互
   SWE-agent 提出 ACI（Agent-Computer Interface）：把「面向人类开发的接口」视为实验变量，围绕智能体行为重新设计。原论文：SWE-bench pass@1 12.5%、HumanEvalFix 87.7%（历史结果，非普适声明）。
2. 分析工具的四个属性
   Affordance（能做什么）、Contract（模型如何请求）、Observation（返回什么）、Feedback（结果是否让下一步更易做对）。原始 shell 钳制面（affordance）大但选择 / 转义 / 推断代价高；结构化 patch 工具钳制小但意图表达和验证更易。接口结构本身构成任务的「有效难度」。
3. 工具是模型输入的一部分
   （在调用前就影响推理）。成本分解：C_tool = C_selection + C_observation（选对工具 + 参数的难度 vs 消化返回结果的上下文负担）。后端 API 很优雅但描述与其它工具重叠、结果往上下文倒垃圾 → 对智能体就是差工具。
4. 更多工具会让决策更难
   工具数量不是能力的单调度量。search/find/lookup/query/grep/retrieve六个近重叠工具会造成歧义决策点。生产规则：宁少而精、用命名空间分隔、用代表性任务评测而非美学取舍。
5. 工具结果应返回「高信号上下文」
   低层 API 返回几百个字段，人类程序可廉价忽略，模型必须用上下文预算消化。应过滤 / 分页 / 提供精简与详细两种模式。评判标准不止「正确」，还要问：是否给足下次决策所需信息？是否省略无关载荷？是否保留后续所需 ID？截断是否说明如何取更多？格式是否易解读？
6. 工具错误也是观察
   Error.这类不透明结果让模型瞎猜；更实用的是给出 status/reason/requested_branch/available_branches/side_effects/retryable这类结构化错误（OpenAI Agents SDK 的 toolErrorFormatter、return_error_to_model；Anthropic 建议可行动的校验错误而非裸 traceback）。可恢复的失败应给模型足够信息选择更好的下一步，同时不假装失败的操作成功。
7. MCP 是互操作层，不是完整 agent 循环
   MCP 标准化 AI 应用与外部能力间的接口（servers 提供 prompts/resources/tools）。但它本身不决定：循环如何调度、活动上下文如何选择、任务如何判定完成、哪些动作需审批、副作用如何重试、沙箱如何供给、多 agent 如何协调、整体如何评估。Tasks 是可选异步扩展（tasks/get/update/cancel，建议持久化 task ID 以便崩溃后恢复轮询），且其成熟度标签在各 first-party 文档中相互矛盾（experimental /not official / Draft）。安全心智模型：互操作能力接口 ≠ 完整 agent 架构。

五、上下文工程（第 12–15 章）

• 活动上下文是 harness 的决策
  每个模型调用只见有限上下文。naive「把可能有用的一切都塞进去」迟早失败 ——①容量有限；②即使容量大，相关性也重要，无关材料与有用证据竞争注意力，让决策更难。Anthropic 对策：just-in-time 检索、token 高效工具、压缩、结构化记忆、子代理。
• 渐进式披露（progressive disclosure）
  OpenAI Codex-first 实验发现巨型指令文件占上下文、难维护、难机械校验，改为「短入口文档 + 指向仓库内结构化真值」。三步：给足定向信息 → 让深信息可被发现 → 任务需要时才加载细节。Agent Skills是现代一例（可复用的指令 + 可选脚本 / 资源包，按需发现加载）；与 tool 不同，skill 主接口是可复用的「指导」，而非可调用动作。⚠️ 2026 预印本在 SkillsBench/SWE-Skills-Bench 上确认 307 例 skill 引发失败（125 功能性失败 + 182 效率回退）——skill 应被评测而非假设有益，且其来源是安全关切（见第 22 章）。
• 持久历史 ≠ 活动上下文
  （两种状态面）：持久历史可留在模型调用之外，活动上下文也可含从未存入持久会话的临时物（当前用户消息、实时工具 schema、运行时元数据）。原则：持久可用 ≠ 每次推理自动包含；包含于某次推理 ≠ 被持久存储。
• 压缩（compaction）是有损的
  C(H) ≠ H。压缩是把上下文「变换」，不等于删除持久历史。工程问题：哪些信息可摘要、哪些必须保持可直接恢复、agent 之后如何取回被省略的细节。

六、案例实证：harness 改变会改变 agent 质量（第 16 章）

Anthropic 2026 年 4 月 Claude Code 事后复盘：API 与推理层未变，仅三个产品层改动就改变了用户体验质量：

• 某些模型的默认 reasoning-effort 被降低（后因反馈回滚）；
• 一个「空闲后清除旧推理」的会话优化有 bug，在后续轮次重复清除，让 Claude 显得健忘、重复；
• 一条为减少冗长而加的 system prompt 指令使 Opus 4.6/4.7 在某个宽评估上掉 3%，被回滚。

架构性结论：提示构造、推理设置、上下文保留、工具接口等运行时决策，本身就是已部署 agent 系统的行为的一部分。

七、工作状态与执行环境（第 17–19 章）

• 结构化工作状态
  长任务受益于显式工件（todo、issue、功能状态文件、进度笔记、测试结果、git 提交、清单、生成计划、输出清单）。这些不是隐藏的模型记忆，而是外部可检视、可编辑、可版本化、可恢复的任务状态表示。
• 执行环境
  一旦 agent 能产生副作用，执行环境就成为架构的一部分。沙箱可提供：文件系统、shell、已装包、挂载数据、网络、浏览器 / 电脑控制、端口、快照、资源限制。环境同时决定能力与故障模式——harness 工程不能止于提示设计。
• 沙箱是隔离边界，不是编排器
  沙箱回答「进程能碰哪些文件 / 跑哪些命令 / 能否出网 / 可见哪些凭据 / 容器内保留什么状态」；harness 回答「模型下一步看什么 / 该执行哪个工具 / 是否需审批 / 返回什么 / 是否继续 / 失败后怎么办」。两者可原型共置，但应分开推理；把控制面放在不受信任执行之外，可保护会话状态、审计日志、凭据和策略免遭沙箱内模型生成代码的攻击。

八、安全：审批 vs 遏制 vs 凭据（第 20–22 章）

• 审批 ≠ 完整安全架构
  审批适合「后果应保持人工掌控」的动作（删生产数据、发外部通信、转账、提权、发布）。但频繁弹窗导致审批疲劳（Anthropic 遥测中 Claude Code 权限弹窗约 93% 被批准 —— 厂商特定数据）。红队例子：2026 年 2 月受控演练中，经用户投递的恶意提示在 25 次重试里 24 次成功外泄凭据，最终是环境级文件系统与出口边界守住了防线。审批控制决策，遏制控制可达能力。
• 凭据留在不受信任执行之外
  凭据可通过受控代理 / 资源特定机制使用，而非直接暴露给生成代码。原则：从未进入沙箱的资源，无法从沙箱内被直接读取—— 这比「告诉模型别碰密钥」更强的边界：一个是指令，另一个改变可达状态空间。
• 观察有来源（provenance）
  web 页、邮件、issue、文档、DB 记录、MCP 资源、加载的 skill、工具结果、子代理报告、存储记忆都可能含敌意 / 误导指令。o_i = (content, source, trust, time, permissions)。字符串因成为 token 而平等，但来源与权威不同。已证实风险：被批准的域名可通过合法 API 做数据外泄（Anthropic 把出口白名单当作能力授予而非简单目的地过滤）；子代理输出可造成信任升级（父代理误以为它比原始工具输出更安全）。AgentDojo（NeurIPS 2024：97 个真实任务、629 个安全用例，覆盖邮件 / 银行 / 旅行 / 消息）正是为「工具返回数据可含对抗指令」而建。Skills 信任边界：skill 可含指令与代码，应仅用可信来源或严格审计；Microsoft 把 skill 当第三方代码处理，load_skill/read_skill_resource/run_skill_script默认需审批。

九、停止、预算与验证（第 23–27 章）

• 停止条件是 harness 的一部分
  可能包括模型返回最终输出、可验证任务谓词满足、需要人工输入、护栏阻断、工具终态失败、资源预算耗尽、取消请求。completion ≠ termination（task complete ≠ turn budget exhausted）。停止可意味着成功 / 策略阻断 / 超时 / 预算耗尽 / 失败 / 人工交接，不应折叠成一个泛化的「done」。
• 预算限制自主性
  B = (turns, tokens, time, cost, tools, concurrency)。自主性既受权限约束也受资源约束；预算把「继续试」从无界行为变成可操作策略，也让失败更易分类（超时 ≠ 达到已验证成功条件）。
• 验证 ≠ 自报完成
  「bug 修好了」是声明，不是证据。更强证据：原复现不再失败、回归测试通过、端到端跑通、受影响状态如预期改变。τ-bench 用最终数据库状态与标注目标状态比对而非信任会话声明，并引入 pass^k测多次尝试的一致性。原则：可行时，完成应锚定到模型自身断言之外的可观察状态；确定性属性用确定性验证，主观属性用独立评估者 / 人。
• 确定性强制 vs 模型判断
  能用机械判定就用机械判定（JSON 是否合法、金额是否超阈值、路径是否越界、依赖边是否被禁、是否超工具预算）；真正需要解释才用模型 / 人（搜索相关性、看哪个文件、是否满足意图）。OpenAI 提供 input/output/tool guardrails；Anthropic 主张能强制可达性硬边界就用环境边界；Codex-first 把架构规则从散文搬进 linter 与结构测试。模型不必记住系统能廉价强制执行的规则。
• 生成者与评估者是不同角色
  产出答案与评判答案是两种操作。模型级评分器本身是另一个易错组件，其可靠性也需要被评测；存在确定性检查时它们更强。

十、反馈环与长运行（第 28–32 章）

• 反馈环给 agent 外部证据
  行动→观察后果→修正。有用反馈：编译输出、单测 / 集成测试、截图、浏览器状态、日志、指标、trace、DB 内容、API 响应。能改变状态却不暴露结果的工具 = 弱反馈环。Harness 设计的一部分就是让相关真值可查询。
• 长运行继承持久性问题
  5 秒的工具调用易失败重试；数小时 / 数天则不同 ——harness 崩溃、worker 消失、沙箱被回收、网络断开、用户暂停、审批数小时后才到。Google Agent Executor围绕事件日志、快照、恢复、分布式执行设计（google/ax 仍标为概念 / 协议打磨中）；Anthropic Managed Agents 用 harness 外部的持久会话，崩溃后可从会话日志重启恢复。
• 恢复需要控制状态 + 世界状态
  create_ticket(...)远端已建单、网络断开收不到响应 → 重启后知道「本想调用」但不知道「外部副作用是否已提交」，盲目重跑会重复建单。请求的动作 ≠ 已执行的动作 ≠ 已观察的结果 ≠ 已提交的任务状态，这些迁移不一定原子失败。持久事件日志记得「请求过、观察到什么」，但不自动让每个副作用可安全重复。
• 幂等性对重试至关重要
  f(f(s)) = f(s)。set_ticket_status(id,"closed")可设计成幂等；charge_card/send_email/create_order天然不安全重复。可靠系统需要：幂等键、唯一操作 ID、去重记录、事务写、重试前先读检查、工具特定重试策略（RFC 9110 同源概念）。自动重试是工具特定策略，不是通用恢复策略。
• 并发造成一致性问题
  更新提交顺序、两 worker 互相覆盖、同抢一个任务、哪个事件流权威、冲突副作用如何检测。多 agent 并发既是提示问题，也是状态一致性问题（Google Agent Executor 明确点名会话一致性）。

十一、子代理与评估（第 33、37–38 章）

• 子代理是 harness 的选择
  委托可提升吞吐，但带来重复工作、假设不一致、通信开销、更高 token 成本、错误传播、共享状态冲突。Google Research 评测 180 个配置：集中式协调使 Finance-Agent 相对单 agent 基线 +80.9%，而每个多 agent 变体在顺序型 PlanCraft 任务上性能下降 39–70%。委托应由任务分解驱动，而非「更多 agent 天生更好」。
• agent harness vs evaluation harness
  一个让模型运作，一个度量整体性能。measured performance = F(model, harness, environment, task, grader)—— 改 harness 或环境可以在不改权重的情况下改变结果。τ-bench（比数据库终态 + 重复可靠性）、ToolSandbox（有状态工具、工具间隐式依赖、任意轨迹的中间 / 最终里程碑）都让「只产出看似合理对话」更难拿分。
• 环境能改变基准分
  Anthropic 在 Terminal-Bench 2.0 上实验改变计算资源，最强与最弱配置相差 6 个百分点（p<0.01）；1x→~3x 时基础设施失败大幅下降但成功分数仍在统计噪声内（p=0.40）；>~3x 后资源开始让新策略可行。建议对低于 3 个百分点且未说明资源方法学的榜单位置保持怀疑。正确结论不是「更多内存让模型更聪明」，而是「agentic 基准可以度量模型行为与运行时资源的交互」。

十二、harness 假设会过期（第 39 章）

Harness 常含针对已知模型行为的工作绕过，但不应假设永久有效：

• 为 Claude Sonnet 4.5 会在上下文接近上限时提前收尾而加的 context-reset 机制，换成 Opus 4.5 后成为死重（行为变了）。
• 一次 RetroForge 对比：单 Opus 4.5 跑 20 分钟 /$9；完整 harness 跑 6 小时 /$200（质量明显更好但贵 20 倍 +）。Opus 4.6 后又去掉了更多脚手架；planner 仍有价值，evaluator 变成任务相关（模型能力边缘时最有用）——这些都是任务特定实验，不是普适成本比。

强设计原则：每个 harness 组件都是「对当前局限的一个假设」，应同时证明其质量提升与执行成本；模型变了就重新检验假设，否则 harness 会累积过时层，增加延迟、token 成本、复杂度与新故障模式。

十三、常见失败模式（第 40 章，12 类）

Harness 工程在很大程度上就是把这些宽泛失败类别变成可观察、可测试的系统属性。

十四、常见误解（第 41 章，12 条）

「harness = 系统提示」「harness = 沙箱」「MCP=agent」「上下文窗口 = 记忆」「压缩保留完整对话」「更多工具总是更好」「有人工审批就任意执行安全」「工具失败就重试」「agent 说完成就完成」「更多 agent 更好」「更好的模型让所有旧 harness 改进都有用」「skill 只是无害的提示模板」——全部不成立（要点见上文各节，尤其 skill 应被当作带来源的代码 / 配置来审查、沙箱化、审批门控）。

十五、生产心智模型（第 42–43 章）

评估一个 agent 系统时自问 15 个问题：模型实际收到什么？谁控制循环？哪些动作可用？动作在哪执行？什么能跨 turn / 崩溃存活？哪些规则被机械强制？错误如何表示？哪些动作可安全重试？agent 如何获取真值？什么证明完成？永不成功时如何停止？中断后发生什么？不受信观察能否携带指令？子代理如何协调？harness 如何被评测？——答不出这些的系统也许能跑 demo，但在生产里很难推理。

完整心智模型（第 43 章）：持久会话 / 任务状态 → HARNESS（上下文选择・模型循环・工具路由・策略 / 审批・验证・重试 / 恢复・预算）→ MODEL → 工具 / MCP / 沙箱（文件・API・浏览器）→ 任务；硬边界 = 权限・凭据・文件系统・网络・schema・预算；反馈 = 测试・UI 状态・日志・指标・trace・结果・评分器。