Harness Engineering：模型之外的运行与控制系统

写在前面

大语言模型能力提升后，Artificial Intelligence（人工智能，AI）应用的主要问题正在发生变化。单次问答关注输出是否正确，工具调用关注参数和权限，Agent 任务还要处理循环、状态、环境、验证和恢复。任务持续时间越长、外部副作用越大，系统可靠性就越不能只依赖模型本身。

Harness 原意是挽具或控制装置。在 AI 应用中，可以将 Agent Harness 理解为模型之外的运行与控制系统：它为模型提供上下文、工具和工作空间，同时控制权限、预算、状态、验证、恢复和交付。Harness Engineering 则是围绕这套系统开展设计、评估、部署和持续改进的工程工作。

本文沿着责任演进分析 Harness，并回答五个问题：

一、模型应用的演进，本质是系统责任扩大

图中的四种形态彼此并不替代，它们反映的是系统责任逐步扩大。

1. 单次模型调用：责任集中在输入与输出

最简单的应用只有输入、模型和输出。系统需要解决提示词、输出格式、超时、重试、日志和内容安全等问题。模型不能直接改变外部环境，错误通常停留在文本层面，因此控制面相对较薄。

即使在这个阶段，生产系统也不能只保留一条模型调用语句。结构化输出校验、请求追踪、模型版本记录和失败重试已经属于最小 Harness，只是它们尚未形成明显的运行时层。

2. Function Calling：输出开始变成行动请求

Function Calling（函数调用）让模型输出工具名称和结构化参数，由应用程序执行真实操作。此时模型仍不直接调用函数，但它提出的行动请求可能读取数据库、发送消息或修改业务数据。

系统责任因此增加了四部分：工具选择是否合法、参数是否符合模式、调用者是否有权限、执行结果如何反馈给模型。工具报错也不能只返回堆栈信息，而应转换为模型能够理解且不泄露敏感信息的观察结果。

3. Agent Loop：一次调用变成闭环决策

ReAct 是 Reasoning and Acting（推理与行动）的组合方法。模型在推理、行动和环境反馈之间交替，直到任务完成或满足停止条件，而非一次给出最终答案。ReAct 论文发表于 2023 年 International Conference on Learning Representations（国际学习表征会议，ICLR），其价值在于把语言推理与外部环境交互放进同一条轨迹中。ReAct 论文

当系统进入 Agent Loop（智能体循环）后，必须回答新的工程问题：每一步允许做什么、工具失败后是否重试、连续多少步没有进展应停止、何时重新规划、一次任务最多消耗多少时间和成本。循环本身不复杂，可靠地控制循环才是难点。

4. 长期任务：会话、工作空间与交付成为系统对象

长任务不是简单地把 Agent Loop 多执行几次。任务可能跨越多个上下文窗口、进程和人工审批节点，还可能同时修改文件、启动服务和等待异步结果。此时系统必须维护可恢复的工作空间、显式进度、任务状态和独立验证证据。

因此，模型能力增强并没有消除工程系统。相反，模型获得的行动范围越大，Harness 承担的运行责任越多。

二、长任务案例：模型不变，失败模式仍然改变

Anthropic 在 2025 年发布的长任务 Harness 实践中，使用 Claude Agent Software Development Kit（软件开发工具包）和上下文压缩，让模型跨多个上下文窗口持续开发一个 Web 应用。直接循环执行时出现了四类典型问题：单次会话尝试完成过多内容、新会话不知道上一会话做了什么、看到局部成果后提前宣布完成、进入任务时没有检查工作区是否已经损坏。Anthropic 长任务实践

这个案例没有更换模型，主要变化是把任务重新组织为初始化和增量执行两个阶段。

1. 初始化阶段建立可恢复基线

Initializer 负责把模糊目标转换为后续会话可消费的工程状态。它创建环境启动脚本、进度文件、功能清单和初始 Git 提交。功能清单中的条目初始状态为未通过，只有经过验证后才能更新。

这一阶段解决三个问题。第一，后续会话不必重新猜测任务范围。第二，工作区有可比较的初始基线。第三，完成状态由外部清单和测试定义，而不是由模型的主观判断定义。

2. 执行阶段只推进可验证增量

每个新会话先读取当前目录、版本历史、进度文件和功能清单，再启动系统并执行基础端到端检查。确认现状后，只选择一个可完成、可测试的功能增量。任务完成时运行测试、提交修改并更新进度，为下一会话留下明确交接信息。

其执行逻辑可以概括为：

读取任务状态和版本历史
        ↓
恢复环境并检查当前基线
        ↓
选择一个尚未通过的功能
        ↓
实现最小增量并执行验证
        ↓
提交代码、更新进度和交接信息

3. 这个案例说明了什么

上下文压缩只能缓解 token 数量限制，不能自动产生可靠状态。模型看到的对话摘要不等于可恢复的工程现场，也不能证明任务已经完成。长任务需要把计划、进度、代码状态和验证结果外部化，让任何新会话都能重新定位。

这是一种具体工程实践，不是通用基准。它证明的不是某套文件名必须被照搬，而是四项更一般的原则：任务分解应可验证，状态应持久化，工作空间应可恢复，完成条件应由独立证据决定。

三、Harness 的定义与边界

当前业界对 Harness 尚无完全统一的定义。测试领域中的 Test Harness（测试支撑系统）负责准备环境、驱动被测对象并收集结果；Agent Harness 延续了同一思想，只是被驱动对象从确定性程序变成了概率模型。

本文采用如下工程定义：

Agent Harness 是位于模型之外、负责让模型在真实环境中持续行动，并对过程和结果实施约束与验证的运行系统。

这个定义包含四项不可缺少的责任。

1. 四层概念不能混为一谈

第一层是 Agent Harness，即实际运行和控制模型的系统。循环、工具、工作空间、状态、权限、验证和恢复都属于这一层。

第二层是 Harness Engineering，即设计和持续改进第一层的工程活动。它关注架构选择、故障分析、评测体系、发布流程和版本治理，本身并非运行时组件。

第三层是 Agent-first Operating Materials，可译为面向 Agent 的可用材料，包括 AGENTS.md、系统规范、技能说明、测试用例和运行记录。它们为 Harness 提供高质量上下文和约束，但材料本身不等于 Harness。

第四层是 Agent-first Organization，即围绕人机协作建立的角色、流程和治理方式。组织政策在被编码为权限规则、审批门或发布策略后，才有一部分进入运行系统。

2. Eval Harness 不是 Agent Harness

Eval 是 Evaluation（评估）的缩写。Eval Harness 负责批量运行样例、计算指标、比较版本和分析回归；Agent Harness 负责在线任务的运行与控制。两者可能共用工具、追踪和沙箱，但服务目标不同。

较合理的关系是：线上 Harness 产生可重放轨迹，Eval Harness 用这些轨迹构造测试集和回归评测；评测发现的问题再转化为线上权限、提示、工具或状态机改动。两者形成反馈闭环，而不是相互替代。

3. Agent Framework 也不等于 Harness

框架提供循环、消息、工具注册或多 Agent 编排等通用能力，Harness 是针对具体任务形成的完整运行系统。使用同一框架的两个项目，可能具有完全不同的权限模型、工作空间、状态协议和验证标准。

判断一个组件是否属于 Harness，不应看它使用了什么库，而应看它是否承担了运行、行动、状态或独立控制责任。

四、用分层模型定位系统责任

为了避免把所有外围代码都称为 Harness，可以使用 L0 到 L5 的分析框架。这个分层是本文用于工程分析的工作模型，不是行业标准。

L1 决定模型在当前步骤能看到什么。上下文不是越多越好，关键是让有限窗口中的信息具有足够高的决策价值。Anthropic 将这一工作称为 Context Engineering（上下文工程），强调在有限上下文内选择和组织对当前任务最有用的信息。Anthropic 上下文工程

L2 决定模型能够做什么。Model Context Protocol（模型上下文协议，MCP）可以标准化模型与数据源、工具之间的连接，但协议只解决接入形式，不自动解决身份、权限、副作用和业务语义。MCP 官方介绍

SWE-agent 提出的 Agent-Computer Interface（智能体-计算机接口，ACI）进一步说明，工具接口需要针对模型的使用方式设计。文件浏览、搜索、编辑和测试接口的粒度、返回格式和错误信息会直接影响任务效果。该工作发表于 2024 年 Conference on Neural Information Processing Systems（神经信息处理系统大会，NeurIPS）。SWE-agent 论文

L3 处理时间跨度。只要任务可能跨会话、等待异步结果或在失败后继续，就需要显式状态机和恢复协议。

L4 处理可信交付。模型认为完成不等于系统已经完成。测试、状态断言、策略检查和人工审批必须在模型之外给出判断。

L5 规定最终责任归属。组织制度不能全部写进代码，但高风险操作的审批要求、数据边界和发布权限应下沉到可执行控制中。

五、从任务生命周期识别 Harness 问题

按生命周期分析，比按框架功能罗列更容易发现系统缺口。一个任务可以分为启动前、执行中、跨会话运行和完成交付四个阶段。

1. 启动前：先建立任务契约和环境基线

启动前最常见的问题是目标可读但不可验证。任务只描述要做什么，没有完成条件、禁止事项和验收方法。模型会自行补齐缺失信息，随后很难区分合理推断与需求偏移。

任务契约至少应包含输入、预期产物、完成条件、权限范围、成本限制和失败处置。进入已有工作区时，还要读取目录、版本历史、进度记录并运行基线检查。只有先确认系统处于什么状态，后续修改才可解释。

上下文装配也发生在这一阶段。把全部文档一次放入上下文会挤压有效信息，较好的方式是先提供结构和索引，再根据当前步骤逐层展开。这就是 Progressive Disclosure（渐进式披露）：先告诉模型有什么，再按需加载细节。

2. 执行中：控制工具、副作用和无进展循环

工具接口首先要让模型容易选对。名称应体现目的，参数应有明确类型和边界，错误信息应说明失败原因以及下一步可采取的行动。一个功能强大但语义模糊的通用工具，往往不如多个边界清楚的小工具稳定。

涉及写入时，重试必须考虑幂等性。幂等是指同一操作执行一次或多次，最终效果保持一致。网络超时并不代表服务端没有执行；如果系统直接重放发送、支付或写入操作，可能产生重复副作用。此时需要请求标识、状态查询、事务、回滚或补偿机制。

Agent 还可能进入无进展循环：反复搜索相同信息、修改后恢复、持续调用失败工具。Harness 应记录状态变化，并设置步骤、时间和成本预算。当连续若干步没有产生新证据或状态变化时，应触发重新规划、切换工具或人工升级，而不是继续消耗资源。

高风险行动需要策略门。只读查询、可逆写入、外部发布和不可逆操作应采用不同权限。OpenAI 的 Agent 工程指南也强调，护栏需要与认证、授权和访问控制共同构成分层防御，高风险动作应保留人工监督。OpenAI Agent 构建指南

3. 跨会话运行：把连续性从对话迁移到状态

长任务中，对话历史不是可靠的唯一状态源。需要持久化的内容包括当前目标、已完成步骤、未解决问题、关键决策、工作区版本、验证结果和下一步建议。

检查点应能回答三个问题：系统当前在哪里，为什么处于这个状态，失败后从哪里恢复。只保存一段自然语言摘要通常不够，还需要可重放事件、版本提交、产物快照和结构化状态。

服务化场景还会出现并发、取消和异步消息。每次运行需要唯一标识，外部事件需要关联到具体会话和任务，后台任务需要可查询状态。否则模型可能消费过期结果，或在用户取消后继续产生副作用。

4. 完成交付：用外部证据定义完成

完成条件必须与模型自述分离。代码任务可以使用测试、静态检查和端到端验证；数据任务可以使用模式、数量、范围和一致性断言；内容发布可以检查必填字段、链接、敏感信息和审批状态。

验证失败后，系统应把可诊断证据反馈给模型，包括失败步骤、预期状态、实际状态和相关日志。验证器不应为了让结果通过而自动放宽标准。无法自动判定的高风险任务，应升级给人工，而不是让模型反复自我确认。

六、从问题反推六类责任模块

图中的六类模块不是固定产品清单，而是对常见工程责任的归纳。具体系统可以合并实现，但不能遗漏相应责任。

1. 模型交互与输出控制

这一模块负责模型选择、提示和上下文入口、结构化输出以及调用结果解析。它要隔离不同模型在消息格式、工具调用和上下文长度上的差异，并保留模型版本、参数和输入摘要，便于复现问题。

模型路由不应只按价格选择。简单分类可以使用低成本模型，复杂规划可以使用强模型，高风险判断还需要独立验证。路由条件应可观察、可回归，而不是隐藏在提示词中的经验判断。

2. 编排与行动循环

这一模块把模型决策转换为受控步骤。最小实现包括观察、决策、行动、反馈和停止；复杂任务还需要任务分解、子任务依赖、并发控制和多 Agent 交接。

状态机比无限循环更适合生产环境。每个状态应定义允许的行动、进入条件、退出条件和异常转移。停止条件既包括成功，也包括预算耗尽、无进展、权限不足和验证失败。

3. 工具、Skills 与 Workspace

工具是模型行动的接口，可以通过 MCP 或 Application Programming Interface（应用程序编程接口，API）接入。Skills 是可复用的任务方法和操作约束，Workspace 是文件、进程和中间产物所在的工作环境。三者共同决定模型能够怎样改变外部世界。

Shell、文件和浏览器等高能力工具应放入沙箱，并限制目录、网络和凭据范围。需要写入真实系统时，优先提供领域工具，而不是开放通用命令。领域工具可以把业务校验、审计和幂等逻辑封装在模型之外。

4. 会话、状态与记忆

会话记录回答模型刚才看到了什么；任务状态回答系统现在做到哪里；记忆回答哪些信息值得跨任务保留。三者用途不同，不能把全部历史都塞进长期记忆。

可靠状态应以结构化字段为主，自然语言交接为辅。长期记忆还需要来源、时间、置信度和失效机制，避免旧结论在环境变化后继续影响决策。

5. 服务化与消息边界

当 Agent 从本地脚本变成在线服务，就需要处理请求身份、消息队列、流式输出、并发、取消、超时和后台任务。用户看到的回答流与系统内部的工具事件应分离，敏感参数不能直接暴露到前端。

每次运行应有稳定的 Run Identifier（运行标识，Run ID），并关联会话、用户、模型调用、工具调用和验证事件。这样才能在异步系统中回答某个结果由哪次运行、哪组输入和哪个版本产生。

6. 可观测、验证与 Eval

日志说明发生了什么，Trace（调用追踪）说明步骤如何连接，测试说明结果是否满足确定性条件，Eval 说明系统在一组任务上的整体表现。四者不能相互替代。

生产问题应能够回放为评测样例。一次失败至少要保留输入、上下文版本、模型与参数、工具轨迹、环境摘要和验证结果。修复后将该样例加入回归集，才能防止同类问题在后续版本中重新出现。

身份、权限、成本、安全、审计和版本治理贯穿六类模块，不适合被放进某个孤立组件。只在工具层做权限检查，而不限制上下文中的敏感数据和最终输出，仍然不是完整控制。

七、Harness 不是越厚越好

过薄的 Harness 无法控制复杂任务，过厚的 Harness 会增加延迟、成本和维护负担。设计前可以沿五个维度评估：任务持续时间、不可逆副作用、路径动态性、结果可验证性和失败代价。

1. 短任务、低风险

单次生成和只读问答通常只需要输出格式、超时、基础日志和内容检查。强行加入复杂规划、长期记忆和多 Agent 协作，收益很低，还会引入新的失败路径。

2. 长任务、低风险

研究汇总、批量分析和离线代码检查不会立即产生高风险副作用，但需要进度、检查点、成本控制和恢复。重点是保持任务连续性，并防止长时间无进展。

3. 短任务、高风险

一次外部写入即使步骤很少，也需要身份、最小权限、参数校验、幂等、审批和结果验证。风险由副作用决定，不由对话轮数决定。

4. 长任务、高风险

持续行动并跨多个系统的任务需要最完整的 Harness：显式状态机、检查点、恢复、审计、策略门、独立评测和人工升级。此类任务的目标不应是完全取消人工，而是让人工只介入高价值判断和异常处置。

Anthropic 在 Agent 构建建议中区分了预定义路径的 Workflow（工作流）和由模型动态决定过程的 Agent，并建议从简单方案开始，只有在复杂度确实带来业务价值时再增加自主性。Anthropic Agent 构建建议

八、Harness Engineering 的实施顺序

Harness 建设不宜从选框架开始。更稳定的顺序是先分析失败，再确定责任，最后选择实现。

第一步：定义任务契约

明确输入、产物、完成条件、允许的工具、数据边界、预算和人工升级条件。任何无法验证的目标都应继续拆解，直到能够观察结果。

第二步：列出真实副作用

区分只读、可逆写入、外部发布和不可逆操作。为每类行动定义身份、权限、审批、幂等和回滚要求。工具注册成功只代表可以调用，不代表可以安全使用。

第三步：设计状态与恢复

画出任务状态机，标明正常转移、异常转移和终止状态。确定哪些状态需要持久化，检查点包含什么，进程中断后如何恢复，跨会话如何交接。

第四步：建立独立验证

把完成标准转化为测试、状态断言、策略检查或人工确认。验证应独立于生成过程，避免同一个模型既提交答案又自行降低验收标准。

第五步：补齐可观测性

统一运行标识，串联模型、工具、状态和验证事件。先保证失败可定位，再扩展复杂编排。没有可观测性的优化通常只能得到偶然成功，无法形成稳定改进。

第六步：用失败样例驱动迭代

将线上失败转成 Eval 数据，判断问题来自模型、上下文、工具、状态、权限还是验证。只有定位到责任层，才能决定是更换模型、调整提示，还是修改 Harness。

OpenAI 在其 Harness Engineering 实践中也强调，面向 Agent 的代码库需要短而明确的入口文档、可检索的版本化知识、可执行的结构约束和持续集成检查。Continuous Integration（持续集成，CI）在这里不仅验证代码，也用于确保知识和架构规则没有随代码演进而失效。OpenAI Harness Engineering

九、工程结论

Harness Engineering 的核心不是给模型增加更多工具，而是把概率性决策放进一个可控制、可恢复、可验证的系统。模型负责生成、判断和规划；Harness 负责限定行动空间、维护任务状态、管理真实副作用并提供完成证据。

从工程角度看，可以保留四条判断标准。

第一，模型能力问题和系统控制问题必须分开诊断。模型不知道答案可以更换模型或补充上下文；重复写入、状态丢失和错误交付属于 Harness 问题。

第二，长任务的关键不是保留更多对话，而是建立显式状态、工作区基线、检查点和交接协议。

第三，工具接入只是行动能力的起点。权限、幂等、沙箱、错误反馈和审计决定工具能否进入生产环境。

第四，Harness 厚度应与任务跨度和失败风险匹配。简单任务保持简单，高风险任务增加独立控制，复杂度必须有明确收益。

当 AI 应用从回答问题走向完成任务，系统设计的重心也随之变化：不再只研究怎样让模型给出更好的下一句话，而是研究怎样让它在真实环境中持续做出可接受的下一步，并在失败时留下能够恢复和改进的证据。