【学习笔记】Harness Engineering，模型之外的一切-7/16

很多 AI Agent 项目做不稳时，团队第一反应还是换模型。

模型不够聪明。

模型不够会写代码。

模型不会遵守指令。

模型上下文不够长。

这些判断不一定错。

但它们经常不是根因。

真正的问题可能是：

模型没有合适的工具。 工具输出不可验证。 任务状态没有外置。 失败以后不能恢复。 权限边界太粗。 没有测试闭环。 没有日志和 trace。 人类只在最后看结果。

这时候继续调 prompt，或者继续塞上下文，收益会越来越低。

因为问题已经从：

模型怎么想？

变成了：

模型在什么环境里行动？

这就是 Harness Engineering。

一、Harness 到底是什么

Harness 这个词直译不太好。可以把它理解成“驾驭层”。不是模型本身。

而是模型外部的一整套运行环境：

Tools State Feedback Constraints Verification Observability Human Oversight

模型负责推理，Harness 负责让推理变成可控行动。如果没有 Harness，Agent 很容易变成一个会说、会猜、也会乱动的黑盒。如果 Harness 设计得好，同一个模型会表现得更稳定。

它知道能用什么工具。知道哪些动作要先问。知道当前任务进度在哪里。知道怎么验证自己做完了。知道失败以后如何恢复。

这就是为什么 AI 工程化进入第七篇之后，重点要从 Context 转向 Harness。

Context Engineering 解决的是：

每一步模型该看什么？

Harness Engineering 解决的是：

每一步模型能做什么、怎么做、做完怎么验证？

二、为什么强模型也需要 Harness

一个常见误解是：

模型越强，工程越不重要。

现实通常相反。模型越强，越需要边界。因为它能做的事更多。能读更多文件，能调用更多工具，能持续执行更长任务，能对外部系统产生真实副作用。能力变强以后，风险也变大。

以前模型只能生成一段建议。现在 Agent 可以：

修改代码 运行命令 访问数据库 调用云 API 提交 PR 发送消息 触发部署

这些动作一旦进入生产环境，就不能只靠“模型应该懂”。

你需要一套系统告诉它：

什么能做？ 什么不能做？ 做之前要不要确认？ 做完以后怎么验？ 失败以后怎么回滚？ 过程怎么留痕？

这就是 Harness 的价值。

三、Harness 的五个核心模块

我建议先用一个简单公式理解：

Harness = Tooling + State + Feedback + Constraints + Observability

这不是唯一分类，但足够实用。

3.1 Tooling：模型的手

工具决定 Agent 能做什么。没有工具，模型只是回答问题。有了工具，模型可以行动。

但工具不是越多越好。工具太粗，模型会乱用。工具太细，模型会被调用步骤拖垮。工具描述不清，模型会选错。工具输出不可读，模型会误判。

所以工具设计是 Harness 里最容易被低估的一环。

第八篇会专门讲工具设计，这里先记住一句话：

工具不是 API wrapper。 工具是 Agent 的行动接口。

3.2 State：模型的任务记忆

第六篇我们讲过，长任务不能只靠上下文窗口。

状态要外置。

比如：

progress.md decisions.md open-issues.md verification.md artifacts/

这些文件不是文档装饰，它们是任务恢复点。当上下文压缩、会话中断、子 Agent 切换、工具失败时，Agent 能从状态文件继续执行，而不是从头猜。

一个没有状态层的长任务 Agent，就像没有硬盘的进程。一旦上下文丢了，任务也丢了。

3.3 Feedback：行动后的反馈

Agent 做完一步以后，不能只继续生成下一步。它要看到反馈，反馈可以是确定性的：

unit test typecheck lint build schema validation diff check

也可以是推理型的：

reviewer agent LLM judge human review policy check

没有反馈，Agent 很容易进入“看起来完成”的状态。

它会写完代码，会总结改动，会说任务完成，但测试没跑，边界没验，副作用没查。

这不是完成。这是自动化幻觉。

3.4 Constraints：行动边界

约束不是为了让 Agent 变笨。约束是为了让 Agent 能安全地做更多事。

常见约束包括：

只读模式 工作区写权限 命令 allowlist 网络访问开关 敏感文件保护 高风险动作审批 预算上限 时间上限 生产资源隔离

没有约束，团队只能把 Agent 当玩具。有了约束，团队才敢让它进入真实流程。

3.5 Observability：看见循环

传统应用里，我们看日志、指标、trace。Agent 系统也一样。

但 Agent trace 需要记录的不只是错误堆栈。

还要记录：

输入目标 选入上下文 工具调用 工具输出 中间决策 权限审批 成本和延迟 验证结果 人类反馈

如果看不见这些，你就无法回答：

为什么它选了这个工具？ 为什么它忽略了那段上下文？ 为什么它重复执行同一步？ 为什么成本突然升高？ 为什么它说完成但实际没完成？

看不见 Agent 的循环，就无法调试 Agent。

3.6 Guide 和 Sensor

Martin Fowler 对 Harness 有一个很有用的拆法。

可以把 Harness 分成两类东西：

Guide：行动前引导 Sensor：行动后感知

Guide 是让 Agent 少走错路。

比如：

项目说明 架构规则 工具描述 权限提示 任务模板 代码风格约束

Sensor 是让 Agent 及时知道自己有没有错。

比如：

测试 lint 构建 性能检查 安全扫描 人工 review LLM judge 日志和 trace

很多团队只做 Guide。写很长的项目说明。写很细的 prompt。写一堆“请不要做错”的规则。

但没有 Sensor。结果是 Agent 看起来很懂规则，却没有办法知道自己是否真的满足规则。

更成熟的做法是：

少一点空泛 Guide，多一点可执行 Sensor。

不要只告诉 Agent：

请写高质量代码。

而要给它：

运行 pnpm test 运行 pnpm typecheck 检查 public API diff 输出未验证项 失败时停止并报告

前者是愿望，后者是 Harness。

四、一个真实的失败模式

假设你让 Agent 做一个看似简单的任务：

把登录接口增加验证码校验。

没有 Harness 的情况下，它可能会这样做：

读几个相关文件 修改后端接口 改前端表单 写一段总结 告诉你完成了

听起来不错。

但问题可能藏在后面：

没有检查旧客户端兼容性 没有更新错误码文档 没有补测试 没有验证验证码过期策略 没有处理重放攻击 没有检查风控日志 没有确认灰度开关

这不是因为模型一定不聪明。而是环境没有告诉它完整的完成标准。

一个更好的 Harness 会把任务包起来：

任务模板：安全相关接口改动 上下文：认证架构、错误码规范、风控日志位置 工具：测试、类型检查、API diff、日志查询 约束：不得修改 .env，不得直接改生产配置 验证：单测、集成测试、旧客户端兼容检查 人工审批：验证码策略和灰度开关 输出：已验证项、未验证项、风险清单

这时 Agent 仍然可能犯错，但它犯错的空间变小了。更重要的是，错误更容易被发现。

五、Harness 不是框架

还有一个误区：

用了 Agent 框架，就有 Harness 了。

不一定。框架提供的是基础设施。Harness 是你围绕具体任务设计出来的运行环境。

框架可以帮你管理：

tool calls turns sessions handoffs guardrails tracing

但它不知道你的业务边界。不知道哪些文件不能改。不知道哪条测试最关键。

不知道哪个 API 是向后兼容红线。不知道哪类动作必须找人审批。这些都要你自己定义。

所以 Harness Engineering 不是“选一个框架”。它是把工具、状态、验证、权限和观测围绕任务装配起来。

六、实战 Checklist

如果你要把一个 Agent 任务生产化，可以先问这十个问题。

1. 这个任务的成功标准是什么？ 2. Agent 需要哪些工具才能完成？ 3. 每个工具的输入输出是否清晰？ 4. 哪些状态必须外置保存？ 5. 哪些动作必须只读？ 6. 哪些动作需要人工审批？ 7. 做完以后用什么验证？ 8. 验证失败时怎么恢复？ 9. 整个过程如何记录 trace？ 10. 成本、时间和重试有没有上限？

如果这些问题答不上来，不要急着上多 Agent。也不要急着接生产系统。先把 Harness 补上。

七、最后

从第一篇到第六篇，我们一直在讲模型“看到什么”。

Prompt 决定一次调用怎么表达任务。

Context 决定多步任务里每一步看到什么信息。

到 Harness Engineering，问题变成：

模型在什么环境里行动？

这一步很关键。

因为生产级 AI 系统的可靠性，越来越多来自模型外部：

工具是否好用 状态是否可恢复 验证是否可靠 权限是否清晰 观测是否完整 人类是否在正确位置介入

未来 AI 工程师最重要的能力，不是把 prompt 写得更玄。而是设计一套让 Agent 能安全做事、做完能自证、失败能恢复的运行环境。

下一篇，我们拆 Harness 里最具体、也最容易出问题的一层：

工具设计。

因为 Agent 的手，比它的大脑更容易出问题。

参考资料：

• OpenAI: Harness Engineering
• Martin Fowler: Harness Engineering for Coding Agent Users
• Anthropic: Effective Harnesses for Long-Running Agents
• Anthropic: Building Effective Agents
• OpenAI Agents SDK Documentation

参考文献：

Harness Engineering，模型之外的一切