1. 缘起

写这篇文章的起因是大家对 harness 概念理解有 gap。
我说某系统的表现主要由 harness 决定，
对方问，是不是那个 AGENTS.md 文件。

这类定义错位不是个例。2026 年上半年的几篇公开文章视角不同：

LangChain 讲组件清单，
Anthropic 讲多角色闭环，
OpenAI 讲执行环境改造。各家结论并不冲突，但缺少统一框架。

因此本文系统梳理一次：从最小组成推导，再逐层扩展，最后落到三类真实场景的选型。

2. harness 是什么

2.1 一句话：Agent = 模型 + harness

Agent 等于模型加 harness。本文所说的 harness，指模型之外、支撑 agent 运行的系统层，不含业务逻辑与交互界面。

这样划分的前提是，模型的核心能力是下一 token 预测，输入与输出都是 token 序列。

上下文装配、工具权限、终止条件、错误处理、状态恢复，没有一项由模型本身决定。

2.2 八类运行时组件

划分组件有两条依据：故障影响范围，以及替换成本。

flowchart TD
    subgraph H[harness]
      A[意图
目标 · 验收 · 预算] --> B[控制
循环 · 计划 · 终止]
      B --> C[上下文
提示 · 轨迹 · 压缩]
      B --> D[工具
契约 · 技能 · 权限]
      D --> E[环境
文件 · 沙箱 · 浏览器]
      C --> F[验证
测试 · 规则 · 人工确认]
      D --> F
      B --> G[状态
会话 · 事件日志 · 产物]
      D --> H1[观测
链路追踪 · 成本 · 时延]
    end
    M[模型] --> B
    E -.结果回写.-> C
    C -.-> H1
    D -.-> H1
    F -.-> H1
    G -.-> H1

组件与职责	缺失影响
意图：目标、验收、预算	无法判断终止条件
控制：循环、计划、终止判断	死循环，或过早终止
上下文：系统提示、工具定义、轨迹、压缩、检索	超出上下文窗口，关键信息无法进入
工具：契约、技能、权限	工具调用缺少约束，或权限失控
环境：文件、沙箱、浏览器、登录态	缺少执行载体，或越权执行
验证：测试、规则、人工确认、模型评审	错误无法被检出
状态：会话、事件日志、记忆、产物	无法恢复，故障无法追溯
观测：链路追踪、成本、时延	线上故障无法定位

两条判据对应到设计原则：

故障隔离。控制面（control plane，管理组件）故障不能影响正在运行的任务；配置和策略下发不能进入请求链路；验证组件故障时应默认拒绝（fail closed），不能默认放行；验证要能独立触发，不依赖控制面。
替换成本。模型接口、工具协议、会话事件格式是三处稳定契约；契约稳定后，替换模型、工具或宿主不需要修改调用方。

常见边界：

意图错误导致目标偏移，控制故障导致无法终止；
上下文超限可重建，状态丢失不可恢复；
验证在动作出口做拦截，观测负责事后分析。

2.3 状态与上下文的边界

状态采用事件溯源：每次状态变化记成事件，事件日志记录事实，上下文是单次模型调用时装配的输入。状态必须持久化，上下文可以重建。

三条约束：

工具调用先写事件日志，再执行；
上下文压缩只改单次调用的输入，不改事件日志；
上下文要可重建，检索结果、快照版本和时间戳都要持久化，否则重建结果会和当时不一致。

2.4 什么不算 harness

三样不属于 harness：模型权重与训练流程、业务逻辑、交互界面。

业务逻辑通过工具被调用；界面负责人工审批与中断，但不属于 harness。

另有四类横切关注点，不单独成类：租户与身份、配额与计费、审计、评测与回归。第 6.4 节会再提一次。

3. harness 的价值

固定模型、只替换 harness，同一评测集上的排名就可能反转。
arXiv 2605.23950《Stop Comparing LLM Agents Without Disclosing the Harness》（Yunbei Zhang 等）
在 3 个模型与 3 套 harness 的组合上比较：harness 选择带来的性能方差是模型选择的 7.8 倍，9 组配对比较中有 6 组排名反转。

成本差异更大：同一批 50 道编码题，单题 token 消耗最多相差 40 倍，通过率差距不到 8 个百分点。

组件消融也验证了这一点：把专用编辑工具换成 shell 命令后，SWE-agent 的得分下降 7.7 个百分点。

两个厂商的公开案例方向一致，但都是自述数据。
在模型和 SDK 不变、仅替换 harness 的条件下，Anthropic 从「无法达到生产质量」变为可交付；
OpenAI 在五个月内产出约一百万行代码，自评为手工编写的十分之一。

这些数字只能用于相对排序，不能用于成本预算：缺少单价与维护人力数据。证据也全部来自编码任务，办公与业务场景缺少同量级公开数据。

来源见第 9 节。

4. 常见 harness 的对比

4.1 五类形态

五类形态的侧重点不同：编码侧重执行环境与验证，办公侧重平台集成，业务侧重治理。下表是形态归纳，不是厂商分类。

形态与典型产品	侧重点	常见短板
编码 CLI：Claude Code、Codex、Gemini CLI、Aider、OpenCode、Amp	执行环境与验证信号，缩短反馈回路	通常不提供多租户、计费与审计
编码 GUI：IDE 插件与桌面应用	交互层与编辑接口	底层复用同一套 CLI 运行时
开源 agent 框架：LangGraph、OpenHands、Goose	提供编排原语，运行时自行搭建	状态与可观测性需自行集成，默认缺少治理
办公 agent：Anthropic 的 Cowork、WorkBuddy、千问办公、钉钉、飞书	平台提供凭证管理、交互入口与工具集成	验证信号弱，安全性依赖隔离与权限模型
业务自建：服务端 agent	治理：权限、幂等、审计、预算	缺少成熟组件，需自行实现

4.2 三项设计选择

不同 harness 的差异集中在三项设计：文件编辑方式、上下文压缩策略、权限模型。

文件编辑方式：模型如何把修改结果交给系统。常见做法有返回完整文件、返回 diff 补丁、按行号定位修改。三种做法都要处理格式解析失败和修改冲突。
上下文压缩策略：长任务超出上下文窗口后保留什么。常见做法有保留最近对话、保留相关片段、压缩成结构化摘要。
权限模型：工具调用在什么条件下放行，以及是否需要人工批准。可以按操作风险授权，也可以按组织权限授权并复用企业角色与权限。

选择依据：

文件编辑方式：看文件大小和模型的格式能力。小文件用完整文件，大文件用 diff 或行号定位。
上下文压缩：看任务长度和早期约束的重要性。长任务要把关键约束写进摘要。
权限模型：看动作风险和现有权限体系。高风险动作逐项确认；企业已有统一角色时按组织权限授权；两者可以叠加。

腾讯 WorkBuddy 采用按操作风险授权的权限模型：工作空间内的常规文件操作直接执行；涉及敏感路径、批量删除、脚本执行、网络访问时暂停并请求人工确认。

官方理由是脚本内容本身不足以判断实际影响。

4.3 已形成的共识

工具数量应尽量少，职责不应重叠。工具描述要明确适用与不适用场景。
把规则写成可执行的检查，模型就能在失败后直接修正。OpenAI 将架构约束实现为自定义 linter 以及目录和依赖结构的测试，并在报错信息中给出修复指引。
三处契约需要稳定：模型接口、工具协议、会话事件格式。

5. harness 的最小集合

5.1 最小闭环：循环、工具、执行环境、终止条件

最小实现包括一个循环、一组工具、一个执行环境，以及最容易被忽略的终止条件。只有循环而没有终止条件，系统会很快失控。

while not should_stop:
    context = assemble_context()
    response = call_model(context)
    if response.type == "tool_call":
        result = execute_tool(response)
        context = append_tool_result(context, result)
    check_budget_steps_and_goal()

另一个容易被忽略的部分是工具结果如何写回上下文，也就是 tool result 的序列化格式。它决定下一轮上下文收到的是原始结果、摘要还是结构化错误对象。

这一结构是工具调用循环（tool-calling loop）的最小形态，也常被归入 ReAct 式循环，即推理与行动交替进行。另一种更简化的做法是 Ralph loop：将目标文件反复注入 agent 上下文，循环直到目标达成。

终止条件还需要独立于模型的硬性终止机制。Claude Code 的 Stop hook（停止钩子）会拦截模型的停止请求；连续拦截八次后强制结束。上限只能通过环境变量调高，计数在每次工具调用后清零。

5.2 第一版可以简化实现的三类

在单用户、可重跑的场景里，以下三类出错后的后果可逆，第一版可以简化实现。

组件	最小实现	前提条件
意图：目标、验收与预算	单句目标 + 单条验收条件 + 固定预算上限	目标错误可重新描述
验证：判定方式	仅规则校验	规则缺失可增量补充
状态：持久化位置	单文件事件日志	状态丢失可重跑

上下文与可观测性不能省。上下文缺少预算控制，长会话必然超出上下文窗口，导致不可用；缺少可观测性，线上故障无法定位。

5.3 扩展性：哪些现在就要定

这里的扩展性，指新增功能时不需要修改既有设计。

多租户场景下，四项需要在第一版确定：租户数据隔离、任务中断后的状态恢复、工具网关、工具执行沙箱。

工具网关统一处理鉴权、配额和审计；工具执行沙箱隔离工具的运行环境。

这四项如果延后确定，存储模型、接口协议和工具执行边界都要返工。

规划器（负责任务拆解与计划）与记忆可以延后实现。记忆可以延后，但事件日志必须从第一版开始记录。单用户编码场景不必在第一版实现这四项。

6. 选型：编码、办公、业务

6.1 三种场景的前提

越接近业务场景，成熟方案越少，自研比例越高。
差异来自四个维度：动作执行位置、用户规模、验证信号成本、错误可恢复性。

验证信号指判断结果对错的成本。成本越低，越容易自动迭代。

场景与执行位置	用户规模	验证信号	错误可恢复性
编码：本地文件系统	单用户	编译与测试，低成本且客观	可重试
办公：外部系统	小团队	人工审核，规模扩大后补充规则	多数可撤销
业务：有副作用的接口	大量用户	缺少低成本验证信号，依赖事前规则与事中拦截	不可重试，可能造成资损或合规事故

6.2 编码：验证信号成本最低

编码场景四个前提都成立：本地文件系统、单用户、编译测试低成本、错误可重试。
因此可以支持长时间运行、失败重试、自动上下文压缩，以及派生子 agent 并行探索。

OpenAI 的案例表明，长任务能否持续主要取决于执行环境改造，循环实现反而次要。
资源有限时，至少要做到任务隔离、测试可执行、错误信息结构化。
单用户编码场景下，多租户、计费、审计和跨实例状态恢复可以延后。

6.3 办公：动作发生在外部系统

办公场景的主要难点是系统集成与权限边界，不是模型能力。
邮件、日历、文档、IM、审批等业务系统由平台或客户 IT 管理，不属于 harness；agent 只是调用方。

验证信号弱，正确性主要依赖人工审核，因此产品优先保证过程可见与可中断。

飞书等平台将凭证管理、事件订阅与回调接入、文档与日历工具封装为标准能力；权限边界、审批流和业务分发仍需自研。

办公场景比编码多三项要求：按组织架构授权；支持定时与常驻任务；补齐权限、审批和审计。安全性主要依赖隔离与权限控制。

6.4 业务：风险与责任最高

办公场景由人工作为最终保障：过程可见、可及时中断，错误大多可撤销。业务场景没有这层保障。

到了业务场景，四个前提全部反转：用户规模大；动作变为下单、扣款、改库存等有副作用的写操作；缺少低成本验证信号；错误不可重试。

因此需要补齐治理能力：最小权限、幂等键与重试保护、执行前策略拦截、预算硬限制、状态回放、独立审批通道。

四类横切能力——多租户与身份、配额与计费、审计、评测与回归——都是硬性要求。

还有两处指标反转：编码场景可以接受分钟级延迟换取正确率，业务场景要求数百毫秒级首 token 延迟（TTFT）；业务还必须为无人值守场景设计降级策略。

6.5 三种场景的组件实现程度

组件在三种场景中的实现程度	编码 agent	办公 agent	业务 agent
意图：目标粒度	任务描述与验收测试	任务模板、交付格式与目标受众	结构化目标、检查项与审批条件
控制：自治程度	支持长任务，测试与预算作为保障	按计划执行，可随时中断	步数、token、时延硬限制
上下文：装配内容	任务、代码、测试输出	组织知识、历史文档、权限信息	记忆、客户画像、合规约束
工具：暴露范围	读文件、改代码、执行命令	邮件、日历、文档、IM 等外部系统	仅暴露必需接口，统一经工具网关
环境：执行位置	本地或容器沙箱	独立沙箱与登录态隔离	由客户环境决定，通常要求数据不出域
验证：判定方式	编译、测试与静态检查	人工审核，规模扩大后补充规则	事前规则、事中拦截、事后审计
状态：持久化方式	本地文件与 Git	平台会话与任务记录	事件日志，可重建可回放
观测：采集粒度	命令、文件变更、测试输出	操作记录、用量、失败原因	全链路审计，按租户留存

实现程度由反馈成本与错误代价决定：反馈成本越低、错误越可逆，组件可以越简单。
同一能力在不同场景中的优先级相反：编码优化长任务，业务优化响应时延。
可跨场景复用的是机制，不是循环实现。工具协议、基于事件日志的状态重建、策略集中管理、可挂起可恢复的审批通道、上下文硬预算，这五项可以复用。

6.6 成熟方案、开源组件与自研

编码与办公场景已有成熟方案。这里的成熟方案指模型、运行时、工具集成和部署界面已封装，而不是只调用模型 API。

业务场景只有零散组件，主体需要自研。

采用成熟方案：满足 6.1 四个前提的编码场景可以直接采用；办公场景同样有成熟方案，例如飞书、钉钉、WorkBuddy。
采用开源组件或标准协议：工具协议采用 MCP（当前规范版本 2026-07-28），执行环境采用容器或微虚拟机，模型通过各家 API 接入。
自研：基于事件日志的状态恢复、工具网关、验证与拦截链路、多租户与计量。

工作主要集中在后两类。成熟方案接入后，仍需适配自有契约。

7. harness 评测

harness 评测分两层：端到端结果决定能不能用，组件评测解释差异来自哪里。只做端到端，出了问题不知道怎么改；只做组件评测，容易局部最优、整体不可用。

7.1 端到端决定能不能用

在固定任务集上运行完整 harness，看任务成功率、单任务成本、时延和安全事件。任务集覆盖正常、边界、长任务和失败案例；判定标准固定，否则结果不可比。

如果只保留一个指标，用任务成功率。成本和时延是约束，安全事件一票否决。

7.2 归因不只有消融

端到端结果变差时，需要进一步定位原因。常见做法有三种，解决的问题不同：

消融：移除或替换一个组件，看端到端指标变化。回答「这个组件有没有用」。
对照：固定模型换 harness，或固定 harness 换模型。回答「差异来自 harness 还是模型」。
横向对比：同一任务集跑多套 harness，比较成功率、成本和失败模式。回答「哪套更适合这个场景」。

三种方法都只解释差异，不能代替端到端结果。

7.3 一套能落地的流程

建任务集：从真实请求抽样，覆盖正常、边界、长任务和失败案例。
定判定标准：能用测试或规则判定的自动判定；不能的用人工或模型评审，并抽检一致性。
重复运行：同一任务跑多次，记录成功率、token、时延、工具调用次数和失败原因。
单变量对比：一次只改一个变量，固定模型、工具和环境。
上线回归：离线评测过线后灰度，配置版本化、可回滚。

8. harness 会消失吗

不会。模型越强，harness 越薄，但不会消失。

agent 要落地，就得处理模型之外的事：工具权限、执行环境、状态恢复、验证和审计。这些不是模型能力，模型再强也要由系统提供。

变的是组件，不变的是这层责任。

9. 参考

只列正文直接引用的来源。

LangChain：The Anatomy of an Agent Harness · 「Agent = Model + Harness」的定义与组件清单 · 厂商官方，2026-03-10
Anthropic：Harness design for long-running application development · 长任务 harness、可评分标准与组件精简 · 厂商自述，2026-03-24
OpenAI：Harness engineering · 执行环境改造、自定义 linter 与结构测试 · 厂商官方，2026-02-11
arXiv 2605.23950：Stop Comparing LLM Agents Without Disclosing the Harness · Yunbei Zhang 等；方差分解 18.48 对 2.37，比值 7.80 · 论文，2026-05-07
arXiv 2607.22585：The Scaffold Effect in Coding Agents · 单题 token 最多差 40 倍，通过率差 0 到 8 个百分点 · 论文，2026-06-08
arXiv 2405.15793：SWE-agent · 编辑接口消融；SWE-bench Lite 子集，GPT-4 Turbo，基线 18.0% · 论文，2024-05
Claude Code：Hooks 参考 · Stop hook、连续续跑上限、计数在工具调用后清零 · 官方文档，抓取于 2026-10-17
Model Context Protocol 规范 · 工具协议规范，当前版本 2026-07-28 · 官方规范
腾讯 WorkBuddy 帮助中心 / 飞书开放平台：Lark Agent 集成能力总览 · 权限模式、定时任务、凭证与事件接入 · 厂商官方，2026-10

HiSEN

harness：定义、价值与选型