1. 缘起

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

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

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

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

这篇是专题篇，只展开模型之外的 harness。整体分层、提示词/RAG/微调、医疗场景见总览篇《Agent 架构的 7 层模型》。

2. harness 是什么

2.1 Agent = 模型 + harness

Agent 等于模型加 harness。本文所说的 harness，是模型之外的运行时与治理层，不是模型之外的一切。

harness 可以分成四块：

编排：任务契约、控制、上下文、工具、权限、验证和状态。
运行：进程、调度、队列和恢复。
执行环境：文件、命令、浏览器、网络、凭证和沙箱。
平台治理：多租户、网关、配额、审计、观测、评测、安全和配置版本。

为了讲组件，本文把编排、运行和执行环境合称运行时核心。2.2 的八类组件按任务链路排列，不按这四块分组。

四块不一定对应四个服务。Agent Platform 是承载多租户、网关、配额、观测和评测的平台层，不等于 Harness 本身。

模型权重与训练、业务系统、知识数据源、交互界面和组织流程都在 harness 外。

这样划分的前提是，模型的核心能力是下一 token 预测，输入与输出都是 token 序列。上下文装配、工具权限、终止条件、错误处理、状态恢复，没有一项由模型本身决定。

2.2 八类 harness 组件

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

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 状态、记忆与上下文

状态是当前任务的事实和进度，采用事件溯源：每次状态变化记成事件，事件日志记录事实。状态必须持久化，上下文可以重建。

记忆是跨任务保留的用户事实、偏好和领域经验。存储可以放在 harness 外，读写策略和装配在 harness 内。

上下文是单次模型调用时装配的输入。

三条约束：

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

工具调用前写的是意图和授权，不是执行结果。失败后用幂等键查询外部系统，不能只凭写前日志判断有没有发生。

2.4 什么不算 harness

不属于 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 组排名反转。

token 消耗差异也很大：同一批 50 道编码题，每题成功任务的 token 最多差 40 倍，配对通过率差 0 到 8 个百分点。

组件消融也说明编辑接口重要：在 SWE-bench Lite、GPT-4 Turbo 上，去掉专用编辑接口后，SWE-agent 从 18.0% 降到 10.3%。这是单项能力证据，不是 harness 整体效应。

两个厂商的公开案例方向一致，但都是自述数据。
Anthropic 用同一个模型对比 solo 和 full harness：solo 运行 20 分钟、花费 9 美元，full harness 运行 6 小时、花费 200 美元；后者输出明显更完整，原文没有给出「生产质量」的结论。
OpenAI 的 agent-first 实验在五个月内产出约一百万行代码，团队称耗时约为手写的十分之一。这不是受控的 harness 对比。

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

来源见第 9 节。

4. 常见 harness 的对比

4.1 五类 harness 形态

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

形态与典型产品	侧重点	常见短板
编码 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 采用按操作风险授权的权限模型：工作空间内的常规文件操作直接执行；涉及敏感路径、批量删除、脚本执行、网络访问时暂停并请求人工确认。

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 评测有两种切法：端到端结果决定能不能用，组件归因解释差异来自哪里。只做端到端，出了问题不知道怎么改；只做组件归因，容易局部最优、整体不可用。

评测的整体框架见《Agent 架构的 7 层模型》，这里只讲 harness 的评测。

7.1 端到端决定能不能用

在固定任务集上运行完整 harness，看任务成功率、单任务成本、时延和安全事件。判定标准固定，否则结果不可比。

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

7.2 组件归因的方法

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

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

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

7.3 从任务集到上线回归

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

8. harness 会变薄，但不会消失

我的判断是：模型变强后，规划、局部纠错这类工作会更多由模型完成，harness 会变薄。

但权限、执行环境、状态恢复、验证和审计仍在模型外，需要由系统提供。

组件会替换，这层责任不会消失。

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：定义、价值与选型