Harness 工程：把 AI Agent 放进可验证的工作回路

最近看 AI Agent、评估框架和长任务应用时，我反复遇到一个词：harness。直译成“线束”不太贴切，在软件工程语境里它更接近“测试/执行/评估支架”：把一个复杂系统放进受控环境里，给它输入、工具、约束、观察点和评价标准，然后反复运行、记录和改进。

对大模型应用来说，harness 工程不只是写几个测试用例。它更像是在回答一个问题：当模型不再只是一次性补全文本，而是要调用工具、跨步骤执行任务、和外部系统交互时，我们怎样知道它有没有真的完成任务，又怎样在失败后定位问题？

Harness 到底包住了什么

传统测试里，harness 常常负责搭起被测对象的运行环境。到了 LLM 和 Agent 场景，它包住的东西更多：

• 任务定义：模型到底要完成什么，成功标准是什么。
• 上下文装配：给模型哪些资料、工具说明、历史状态。
• 执行控制：允许哪些工具调用，最多运行多少步，何时停止。
• 观测记录：每一步 prompt、模型输出、工具调用、错误和中间状态。
• 评估判定：用规则、模型评分、人工复核或混合方式判断结果。
• 反馈闭环：把失败样例变成测试集、约束、提示词改进或系统改造。

所以我理解的 harness 工程，本质上是在模型外面建立一个“可重复、可观测、可评价”的工作回路。

为什么 Agent 更需要 harness

如果只是一次性问答，错误通常体现在最终回答里；但 Agent 的错误经常藏在过程里。

它可能第一步理解错任务，第二步调用错工具，第三步基于错误结果继续推理，最后给出一个看似完整但实际偏离目标的答案。只看最终输出，很难知道问题发生在哪里。

Harness 的价值就在于把过程拆开：每一步输入是什么，模型为什么选这个动作，工具返回了什么，状态如何变化，最后判断是否成功。这样系统就不再是“模型黑箱 + 最终答案”，而是一个可以回放的执行轨迹。

这也是为什么长任务应用、代码执行、浏览器代理、数据分析代理会天然需要 harness。任务越长，越不能只相信最终文本；系统必须保留足够的证据，让人和程序都能检查它。

一个基本的 harness 回路

我把 harness 回路拆成五层来看。

第一层是任务层。任务层要避免含糊描述，比如“帮我分析一下”通常不够。更好的任务定义会包括输入、目标、约束、交付物和失败条件。

第二层是执行层。执行层决定模型能做什么：能否搜索、能否读文件、能否写文件、能否调用 API、能否运行代码。这里的关键不是工具越多越好，而是工具权限要和任务边界匹配。

第三层是状态层。Agent 做长任务时，状态不是自然存在的，需要工程上保存：当前计划、已完成步骤、未解决问题、工具输出、错误信息、重试次数。这一点和普通 prompt engineering 的区别很大。

第四层是评估层。评估可以是确定性的，例如 JSON schema 是否符合、测试是否通过、文件是否存在；也可以是半确定性的，例如 LLM-as-judge、人工抽检、rubric 打分。真正可靠的 harness 往往混合使用这些方法。

第五层是反馈层。评估不是终点，评估结果要回到系统设计里：失败样例进入回归集，模糊指令变成更明确的任务模板，危险工具加权限门槛，常见错误加前置校验。

Evaluation harness 和运行 harness 的区别

我之前容易把 harness 理解成 evaluation harness，也就是“评测脚手架”。但现在看，它至少有两类。

第一类是 evaluation harness。它的核心目标是比较模型、提示词或系统版本。它关心数据集、指标、评测一致性、样例覆盖、统计显著性。OpenAI Evals 这类框架就很典型：定义样例，运行模型，计算结果，用来判断改动是否真的变好。

第二类是 runtime harness。它的核心目标是让一个 Agent 在真实任务里可控地运行。它关心工具权限、步骤限制、状态恢复、错误处理、人工确认和审计记录。比如一个能读写代码库的 Agent，就不能只靠最终答案判断成功，而需要记录它改了哪些文件、跑了哪些测试、失败时停在哪一步。

两者会重叠。一个好的 runtime harness 会把真实失败样例沉淀到 evaluation harness；一个好的 evaluation harness 也会反过来约束 runtime harness 的设计。

Harness 工程的难点

第一个难点是任务规格。很多失败不是模型能力不足，而是任务没有被定义成可评价的形式。如果成功标准无法检查，harness 只能记录过程，不能判断结果。

第二个难点是非确定性。模型输出会波动，外部网页会变化，工具调用会失败，网络和依赖也会引入噪声。因此 harness 需要区分“模型错误”和“环境错误”，否则评估结果会很混乱。

第三个难点是观测成本。记录太少，失败无法复盘；记录太多，日志噪声又会淹没关键信息。比较合理的做法是分层记录：状态文件记录摘要，日志记录步骤，必要时保存原始工具输出。

第四个难点是安全边界。Agent 一旦能写文件、发请求、发布内容，就必须有明确的门槛。比如自动博客流水线里，发布前 dry-run 和显式确认就是 harness 的一部分，不是附加功能。

我对 harness 工程的理解

Harness 工程的核心不是“让模型更聪明”，而是“让模型的工作可被约束、观察、评价和恢复”。

一个没有 harness 的 Agent 工作流，很容易变成一次性魔法：成功时看起来很厉害，失败时不知道为什么。一个有 harness 的工作流，即使模型偶尔失败，也能告诉我们失败在哪一步、哪些输入导致失败、下一次应该从哪里恢复。

这也是我觉得 harness 工程会越来越重要的原因。随着模型进入更长链路的任务，工程重点会从“怎么写一个好 prompt”转向“怎么设计一个可靠的执行系统”。Prompt 仍然重要，但它只是 harness 里的一个组件。

对我自己的博客自动化流程来说，这个思路也很直接：爬取、写作、配图、发布都不是孤立步骤，而是一个可观测的流水线。每一步都要有输入输出协议、状态记录、失败恢复和发布门槛。这样自动化才不是把风险藏起来，而是把风险暴露出来并控制住。

小结

Harness 工程可以理解为 AI 应用的“工程化外骨骼”：它不替代模型能力，但让模型能力进入一个稳定的工作结构。

我会把它总结成四句话：

• 任务要可定义。
• 过程要可观察。
• 结果要可评价。
• 失败要可恢复。

如果一个 Agent 系统能做到这四点，它就不只是一个会回答问题的模型接口，而是一个更接近真实软件系统的工程组件。