Harness 到底是什么#

Harness 直译是“挽具”或“线束”，在软件工程里通常指包裹、驱动和观察某个组件的一层基础设施。它不是模型，也不只是一个测试脚本，而是一套让模型可以被重复运行、比较、约束和评估的机制。

在 LLM 场景中，Harness 常见有三种形态：

1. 评测 Harness：准备数据集，运行模型，记录输出，再用规则、人工或另一个模型评分。
2. Agent Harness：管理多轮对话、工具调用、状态、重试、审批、预算和终止条件。
3. 生产 Harness：把模型接入真实服务，负责路由、缓存、限流、观测、故障转移和成本控制。

这三类 Harness 可以共用一套任务定义和日志格式。理想状态下，线上失败的一次真实任务，可以脱敏后直接回放到评测 Harness 中；评测发现的回归，也可以在灰度环境里验证。

什么是 Harness Engineering#

如果说 prompt engineering 是把一句话说得更清楚，context engineering 是把相关信息放到模型面前，那么 Harness Engineering 更像是在设计一整个“可工作的环境”。它关心的不只是模型收到什么 prompt，还关心模型能看见哪些事实、可以调用哪些工具、每一步如何验证、失败后怎样恢复，以及什么条件才算真正完成。

这个词并不是某个唯一的开源框架或严格标准。它更像一种工程方法：把原本依赖人脑记忆、口头约定和人工检查的部分，逐步变成 Agent 能够读取的文档、可调用的工具、可执行的约束和可观察的反馈回路。OpenAI 在介绍 Codex 实践时把它概括为：人负责引导，Agent 负责执行；工程师的重点从直接写代码，转向设计环境、表达意图和建立反馈循环。OpenAI 的 Harness Engineering 文章 也展示了这一方法在真实软件项目中的具体做法。

1
人类目标
2
  ↓
3
任务契约与验收标准
4
  ↓
5
上下文、文件、日志和业务状态
6
  ↓
7
模型推理与工具调用
8
  ↓
9
沙箱或受控环境中的实际执行
10
  ↓
11
测试、观测、评审和结果校验
12
  ↓
13
完成、重试、修正或请求人工判断

为什么长任务特别需要 Harness#

让模型回答一个问题，和让 Agent 连续工作几个小时，是两种完全不同的工程问题。短任务主要考验模型能不能理解指令；长任务还会受到上下文窗口、环境状态、工具可靠性和中间产物质量的影响。

一个没有设计过 Harness 的长任务，通常会出现几类反复发生的失败：

这里有一个很重要的判断：如果同一种错误在不同任务中反复出现，就不要只要求模型“下次注意”。应该把经验沉淀为一个新的系统能力，例如 schema、lint、测试、初始化脚本、文档索引或权限规则。这样修复才会对后续所有任务生效。

Harness Engineering 的四个支柱#

参考业界对长时间运行 Agent 的实践，可以把 Harness Engineering 进一步归纳成四个相互配合的支柱。

1
project/
2
├── AGENTS.md              # 项目地图、边界和常用命令
3
├── docs/
4
│   ├── decisions/         # 架构决策和重要取舍
5
│   └── plans/             # 可验收的任务计划
6
├── .agent/
7
│   ├── progress.md        # 最近几轮做了什么
8
│   ├── known-issues.md    # 已知问题和复现方式
9
│   └── feature-list.json  # 功能状态和验收结果
10
└── scripts/init.sh        # 初始化开发环境

1
planned → implementing → checking → passed
2
                 │             │
3
                 └─ blocked ←──┘

三个公开实践带来的启发#

1
用户目标
2
  ↓
3
Planner：拆成规格和验收标准
4
  ↓
5
Generator：实现一个可运行增量
6
  ↓
7
Evaluator：执行测试并检查结果
8
  ├─ 不通过：返回具体反馈，进入下一轮
9
  └─ 通过：记录证据，进入下一个功能

Harness 的成熟度，可以这样判断#

可以用四个阶段快速判断一个项目目前处于什么水平：

大多数团队不需要直接追求 L4。能从 L0 走到 L2，已经足以解决“换个 prompt 看起来好了一点”这类不可复现的问题；从 L2 到 L3，则是 Harness 真正产生复利的阶段。

一份可落地的 Harness 检查清单#

开始一个 Agent 项目时，可以先逐项回答下面的问题：

• Agent 是否有一个明确、短小、可导航的入口文档？
• 任务是否有机器可读的完成标准，而不只是“效果好一点”？
• 每个工具是否有 schema、权限边界、错误类型和幂等策略？
• Agent 是否可以在隔离环境中启动应用、运行测试和读取日志？
• 任务是否有最大步数、token、时间、金额和重试预算？
• 每次运行是否记录模型、prompt、数据集、工具版本和完整轨迹？
• 失败时能否区分模型、上下文、工具、环境和验收规则的问题？
• 修复一个失败后，是否新增了测试、文档、lint 或其他保护机制？
• 是否定期清理重复代码、过时文档、失效配置和无主任务？
• 高风险动作是否需要人工审批，且能完整审计？

如果这些问题大部分都答不上来，继续更换模型往往不是最优先的工作。先补齐 Harness 的可见性、可执行性和可验证性，通常能比单纯升级模型更快地改善真实任务成功率。

Harness Engineering 和 Prompt Engineering 的区别#

两者并不冲突，但解决的问题不同：

如果 Agent 第一次算错了一个字段，调整 prompt 可能有帮助；如果它反复读错同一种数据结构，更好的做法是给边界加 schema 校验；如果它经常修改错文件，就应该改善仓库地图、工作区隔离和验证命令。Harness Engineering 的思路是：当同一类失败重复出现时，优先增加一个系统能力，让它以后更难重复发生。

这也是它和“多写几句系统提示词”的区别。文档告诉 Agent 应该怎么做，代码和 CI 则负责判断它有没有做到。能机械验证的规则，不应该只停留在自然语言里。

三个关键概念：可见、可执行、可验证#

架构约束：约束边界，不规定每一行代码#

Harness Engineering 并不意味着把每个实现细节都写成 prompt。更有效的方式是规定不可违反的 invariant：数据在边界解析，领域层不能越级依赖，敏感操作必须经过权限检查，所有关键流程都要有结构化日志。

在这些边界之内，Agent 可以自行选择具体实现。这样既能保持架构一致，也不会因为过度规定而限制模型解决问题的空间。边界最好由 linter、结构化测试、类型系统和 CI 机械执行，而不是依赖评审者每次手工提醒。

一个常见的分层例子是：Types → Config → Repository → Service → Runtime → UI。业务代码只能沿固定方向依赖，认证、连接器、遥测和 feature flag 等横切能力统一从 Providers 接入。这个设计的重点不是层名，而是让依赖方向可读、可测、可拒绝。

从一次失败中改进 Harness#

可以用下面的循环处理失败：

1
记录失败轨迹
2
  ↓
3
判断失败属于模型、上下文、工具、环境还是验收规则
4
  ↓
5
为这类失败增加一个具体能力
6
  ↓
7
把能力写成文档、代码、测试或 CI 约束
8
  ↓
9
把原失败样本加入回归集
10
  ↓
11
重新运行并观察质量、延迟和成本

例如，Agent 总是把“已取消订单”当作“已完成订单”：

• 只改 prompt：告诉它再仔细一点，通常只能缓解一次。
• 改进上下文：提供订单状态的枚举和状态转换图。
• 改进工具：让 API 返回类型化状态，并拒绝非法状态转换。
• 改进验证：增加一条回归用例，检查最终动作与订单状态是否匹配。

最后一种处理方式才真正提升了 Harness，因为它让下一次运行具备了新的保护能力。

为什么 Agent 越强，Harness 越重要#

弱模型通常卡在不会做；强模型更多卡在做得太多、做得太快，或者在错误方向上持续推进。模型能力提升后，工具权限、上下文质量、架构边界和反馈速度的重要性都会增加。

如果一个 Agent 每小时可以完成几十个修改，人工逐行检查就会成为瓶颈。此时需要把常规判断迁移到自动化检查，把人类经验沉淀成规则，把 UI、日志、指标和测试结果变成 Agent 可读取的证据。人类仍然负责目标、优先级和高风险决策，但不必把时间花在重复检查每个低风险细节上。

OpenAI 的实践还提到，Agent 生成速度提高后，技术债会像垃圾一样持续堆积，因此需要定期扫描偏离、更新质量等级、提交小型重构，让“清理”成为系统的一部分，而不是等到项目失控后集中返工。这是 Harness Engineering 很容易被忽略的一面：它不仅负责让 Agent 做得更快，也负责让系统长期保持可理解。

如何从零开始做 Harness Engineering#

不需要一开始就搭建复杂的多 Agent 平台，可以按下面的顺序推进：

1. 选一个边界清楚的真实任务，写出成功和失败的例子。
2. 固定任务输入、模型、prompt、工具版本和验收规则，建立可重跑的基线。
3. 给 Agent 一个最小但完整的环境：清晰的仓库地图、必要工具、隔离工作区和一条验证命令。
4. 记录每一步轨迹，区分模型错误、工具错误、环境错误和规则错误。
5. 把重复失败转化成 schema、测试、lint、文档或权限约束。
6. 每次优化都同时观察任务成功率、P95 延迟、单任务成本和人工介入率。

做到这一步，Harness 就不再是模型外面的一层胶水，而是一个会随着失败样本持续进化的工程系统。

LLM 性能不止一个数字#

1
总成本 = 输入 token × 输入单价
2
       + 缓存写入 token × 缓存写入单价
3
       + 缓存命中 token × 缓存单价
4
       + 输出 token × 输出单价
5
       + 工具调用成本
6
       + 重试成本

为什么需要 Harness#

没有 Harness 时，模型效果往往靠“我刚刚试了一下，感觉不错”来判断。这种判断无法回答几个关键问题：

• 换一个模型后，是真的变好了，还是只是碰巧答对了几道题？
• prompt 改了以后，质量提升是否牺牲了延迟和成本？
• 工具调用失败时，系统会重试、降级，还是直接编造结果？
• 任务在并发 1 时很快，在并发 50 时是否已经排队超时？
• 上下文变长后，模型是否仍然能找到关键事实？
• 某次版本升级带来的提升，能否在下周重跑并得到相近结果？

Harness 的价值，是把一次性的体验变成可重复的实验，把黑盒输出变成可追踪的任务轨迹。

一个实用的评测 Harness 应该记录什么#

每次运行至少需要一个稳定的 task_id，并记录以下信息：

1
{
2
  "task_id": "support-0042",
3
  "dataset_version": "2026-09-07",
4
  "model": "model-id",
5
  "prompt_version": "support-v12",
6
  "reasoning_effort": "medium",
7
  "input_tokens": 1830,
8
  "output_tokens": 412,
9
  "ttft_ms": 620,
10
  "latency_ms": 4830,
11
  "tool_calls": 2,
12
  "retries": 0,
13
  "status": "passed",
14
  "grader_scores": {
15
    "task_success": 1,
16
    "citation_accuracy": 1,
17
    "format_valid": 1
18
  }
19
}

这里的重点不是字段名称，而是把模型版本、prompt 版本、数据集版本、运行参数和结果绑定在一起。否则出现回归时，往往只能看到“昨天 87 分，今天 82 分”，却不知道是模型变了、题目变了、工具变了，还是评分器变了。

Harness 的基本运行流程#

一个最小可用的评测流程大致如下：

1
读取数据集
2
  ↓
3
创建隔离的任务上下文
4
  ↓
5
运行模型和工具调用
6
  ↓
7
记录每一步输入、输出、耗时和 token
8
  ↓
9
检查 schema、规则和安全约束
10
  ↓
11
执行任务级评分
12
  ↓
13
汇总质量、延迟、成本和失败原因
14
  ↓
15
与基线版本比较

运行器要有明确的终止条件，例如最大步数、最大 token、最大金额、最长时间和允许的工具集合。对于会修改外部系统的 Agent，评测环境还应该使用 mock、沙箱或只读账号，避免为了测试模型而发送真实邮件、删除数据或创建订单。

评测时最容易踩的坑#

如何把性能优化落到 Harness 上#

性能优化不应该只盯着换模型，还可以从 Harness 下手：

1. 减少无效上下文：只保留任务需要的历史和检索结果，必要时做摘要或 compaction。
2. 缩短关键路径：能并行的工具调用不要串行等待；把不影响最终答案的工作放到后台。
3. 使用缓存：稳定的系统提示、工具 schema 和公共资料适合做 prompt cache，但要记录命中率和缓存成本。
4. 设置模型路由：简单分类、格式转换交给低成本模型，复杂推理再升级到高能力模型。
5. 限制重试：只对明确的临时错误重试，给每个任务设置预算和退避策略。
6. 控制输出长度：要求模型先给结构化结论，再按需展开，避免无意义的长篇解释。
7. 保留失败样本：不要只保存成功案例。失败轨迹才是改 prompt、改工具和改流程最有价值的素材。

最后：性能是系统属性#

LLM 性能不是模型排行榜上的一个分数，也不是接口返回里的一个 tokens-per-second。对用户来说，真正重要的是：任务多久完成、结果是否可信、失败时是否可控，以及这次完成需要付出多少成本。

模型决定能力上限，Harness 决定能力能否稳定释放。没有 Harness，模型升级只能靠感觉；有了 Harness，才可以把质量、延迟、成本和安全放在同一张表里比较，也才能知道一次优化到底改善了什么、牺牲了什么。

如果要从今天开始做，最小步骤并不复杂：先选一组真实任务，固定数据集和 prompt 版本，记录每次运行的完整轨迹，再同时看任务成功率、P95 延迟、单任务成本和失败类型。等这四个指标稳定下来，再谈更大的模型、更复杂的 Agent 或更高的并发，判断会可靠得多。

参考资料#

• Harness Engineering 深度解析：AI Agent 时代的工程范式革命（知乎，参考文章）
• Harness engineering: leveraging Codex in an agent-first world（OpenAI）
• Unrolling the Codex agent loop（OpenAI）
• Effective harnesses for long-running agents（Anthropic）
• Harness design for long-running application development（Anthropic）