## Harness 到底是什么

Harness 可以翻译成“运行支架”“执行框架”或“宿主系统”。在 AI 工程语境里，它不是某个固定产品名，而是一类系统角色：把模型或 Agent 接入真实世界，并负责整个任务的运行、约束、状态和反馈。

一个简单定义是：

> Harness 是承载 Agent 工作的工程控制层。它把用户目标、上下文、模型、工具、权限、状态、运行时、审计和评估组合成一条可持续执行的任务链。

如果把 Agent 看成正在解决问题的执行者，Harness 就是它的工作台、操作规程、门禁系统、工具柜、记录仪和应急机制。

模型本身可以生成答案，也可以表达“我想调用某个工具”。但读取哪份文件、是否允许写数据库、怎样执行命令、失败后要不要重试、任务中断后从哪里恢复，都需要外围系统来完成。这个外围系统就是 Harness。

## 为什么只有模型还不够

把模型接进一个聊天框，可以得到问答产品；把模型放进 Harness，才可能得到能持续完成真实任务的 Agent 系统。

真实任务通常具有以下特征：

- 输入不完整，需要主动查找上下文。
- 过程包含多步决策，后一步依赖前一步结果。
- 需要调用文件、终端、数据库、浏览器或外部服务。
- 某些动作只读，某些动作会产生外部影响。
- 工具可能超时、失败或返回含糊结果。
- 任务可能跨越很长时间，甚至在中途被打断。
- 最终结果不能只靠一句“已完成”，还需要证据。

这些问题不是单靠提示词可以解决的。提示词能够告诉模型应该谨慎，但无法代替真正的鉴权、沙箱、超时、幂等、状态持久化和审计日志。

Harness 的意义，就是把“模型可能会做对”变成“系统能够稳定地把事情做成”。

## 一次完整运行发生了什么

一个典型 Harness 会反复执行下面这条链路：

1. 接收用户目标，判断这次请求授权了什么。
2. 装配任务所需的规则、历史、文件和环境信息。
3. 调用模型，让 Agent 判断下一步动作。
4. 解析模型输出，识别回复、工具调用或任务结束信号。
5. 在执行前检查权限、参数、风险和审批条件。
6. 调用真实工具，并收集结构化结果。
7. 把结果送回 Agent，让它继续判断。
8. 保存进度、变更和证据。
9. 达到停止条件后验证结果，再向用户交付。

这不是一个简单的死循环，而是一台受约束的状态机。每一步都应该有明确输入、输出、失败语义和停止条件。

如果第 5 步缺失，Agent 可能越权；如果第 8 步缺失，中断后只能重来；如果第 9 步缺失，系统很容易把“调用过工具”误当成“任务已完成”。

## Harness 的八个核心部分

### 任务入口与契约

Harness 首先要把自然语言请求转成可执行的任务契约，包括：

- 用户真正想得到的结果。
- 当前请求允许的操作范围。
- 不能触碰的边界。
- 完成标准与必须提供的证据。
- 哪些歧义可以合理假设，哪些必须询问。

这一步决定系统的自主程度。回答问题、修改本地代码、发送邮件和删除云端数据，显然不应该共享同一套授权规则。

好的 Harness 会区分“分析”“修改”“外部写入”和“破坏性操作”，并让权限随任务而变化。

### 上下文引擎

模型能否做出正确判断，很大程度上取决于 Harness 提供了什么上下文。

上下文引擎负责：

- 找到与任务相关的文件、规范和历史记录。
- 控制内容的新鲜度、优先级和长度。
- 避免把无关资料全部塞进上下文。
- 在长任务中压缩旧信息，同时保留关键决策。
- 明确区分用户输入、系统规则、工具结果和推断。

上下文不是越多越好。过期信息、重复规则和无关日志会增加噪声，甚至让 Agent 忽略真正重要的约束。

### Agent Loop

Agent Loop 是 Harness 中最接近“智能主体”的部分。它负责让模型在观察、判断、行动和再观察之间循环。

一个稳健的 Loop 至少需要处理：

- 本轮是直接回答，还是调用工具。
- 工具结果是否改变了原有计划。
- 是否需要继续探索或验证。
- 是否已经满足完成标准。
- 是否陷入重复调用或无效尝试。
- 是否应该请求用户介入。

Loop 不是越长越好。没有预算和停止条件的循环，常见结果是成本上涨、重复劳动或越做越偏。

### 工具网关

工具网关连接模型意图与真实执行环境，是 Harness 最重要的边界之一。

它需要保证：

- 工具名称和用途没有歧义。
- 参数有明确类型、必填项和范围。
- 返回结果结构稳定，并说明错误语义。
- 只向当前任务暴露必要工具。
- 写操作与读操作有清晰区别。
- 凭据由系统保管，不进入模型可见文本。
- 工具失败时提供可行动的信息，而不是模糊报错。

Agent 决定调用哪个工具，Harness 决定这个调用是否有效、是否允许以及怎样执行。

### 策略与安全层

安全不能只写在提示词里。Harness 必须把关键边界做成强制机制。

常见控制包括：

- 身份认证与最小权限。
- 文件系统和网络沙箱。
- 外部写入前的审批。
- 敏感字段过滤与凭据隔离。
- 命令、路径和目标对象校验。
- 速率、成本和并发限制。
- 高风险任务的人工接管。
- 对不可逆动作提供明确后果说明。

策略层的目标不是让 Agent 什么都不能做，而是让它在授权范围内顺畅行动，在越界之前可靠停下。

### 状态与持久化

长任务一定会遇到中断、重试和恢复。Harness 因此需要管理多种状态：

- 会话历史与当前任务阶段。
- 已完成的工具调用及其结果。
- 文件或数据的变更记录。
- 尚未完成的计划与待办。
- 检查点、幂等键和重试次数。
- 用户审批与拒绝记录。

状态设计要回答两个问题：重新运行时哪些动作可以安全重复，哪些动作必须确认之前是否已经成功。

发送通知、创建订单、发布文章等外部写入，都应该使用幂等机制。否则一次网络超时就可能造成重复操作。

### 可观察性与用户控制

一个不可观察的 Harness，很难被信任，也很难调试。

系统至少应该记录：

- 每个阶段的开始、结束和耗时。
- 模型选择了什么动作。
- 调用了哪些工具，结果是否成功。
- 哪条策略允许或阻止了操作。
- 发生了多少次重试和回退。
- 最终结果由哪些证据支持。

对用户而言，可观察性还意味着能看到简洁进度，能取消任务，能在关键节点审批，也能在 Agent 走偏时及时纠正。

内部日志可以详细，用户界面则应该聚焦目标、重要动作、风险和结果，避免把冗长推理过程直接倾倒出来。

### 验证与评估

Harness 的最后一层不是“输出答案”，而是验证任务是否真的完成。

例如：

- 修改代码后是否运行了相关测试。
- 生成文件后是否检查了格式与可读性。
- 发布内容前是否通过规范校验。
- 写入外部系统后是否获得成功回执。
- 多个子任务的结果是否完整合并。
- 最终回复是否包含必要链接、证据和限制。

离线评估同样重要。团队需要用代表性任务测量完成率、工具成功率、误操作率、人工接管率、延迟和成本，而不是只观察几次令人惊艳的演示。

## Harness 不是哪些东西

### 不是模型

模型提供推理与生成能力，Harness 提供运行环境和工程控制。更换模型可能提高判断质量，却不会自动带来权限、审计、幂等和恢复能力。

### 不只是 Agent SDK

SDK 可以帮助实现工具调用、会话或编排，但 Harness 还包括业务权限、基础设施、产品交互、运维和评估。使用某个 SDK，不代表已经拥有生产级 Harness。

### 不只是工作流引擎

传统工作流通常提前规定每一步；Agent Harness 允许模型根据中间结果动态选择动作。两者可以结合：确定性步骤交给工作流，真正需要语义判断的部分交给 Agent。

### 不只是聊天界面

界面只是用户与系统沟通的入口。即使没有聊天框，后台自动化、代码代理和研究任务同样需要 Harness。

## 常见故障与对应机制

| 故障 | 表面现象 | Harness 应提供的机制 |
| --- | --- | --- |
| 上下文缺失 | Agent 自信地做出错误假设 | 检索、优先级、新鲜度与缺口检测 |
| 工具描述含糊 | 选错工具或参数反复失败 | 窄职责、强类型参数与稳定错误结构 |
| 权限过大 | 普通任务触发高风险动作 | 最小权限、审批与沙箱 |
| 外部写入重复 | 超时重试后创建两份数据 | 幂等键、调用记录与结果查询 |
| 循环失控 | 重复搜索、反复修改 | 步数预算、重复检测与停止条件 |
| 过早结束 | 只执行动作，没有验证结果 | 完成标准、验证器与证据要求 |
| 中断丢失 | 长任务重启后全部重做 | 检查点、持久状态与恢复协议 |
| 无法复盘 | 失败后不知道发生了什么 | 结构化日志、调用链和状态快照 |

这张表也说明了一个关键事实：很多看似“模型不够聪明”的问题，其实是 Harness 没有给出清晰工具、可靠反馈或正确边界。

## 怎样从原型走向生产

### 第一阶段：先跑通最小闭环

从一个目标、一个模型和少量只读工具开始。确保 Agent 能收到工具结果，并能根据结果决定继续或停止。

此时重点验证任务是否真的需要动态决策，不要过早加入复杂编排。

### 第二阶段：把工具做窄做稳

为每个工具定义单一职责、结构化参数、稳定返回和明确错误。删除重复或用途重叠的工具，只暴露当前任务需要的能力。

### 第三阶段：加入真实安全边界

把只读与写入分开，为外部写入、危险操作和范围扩张设置审批。凭据留在执行层，不能拼进提示词或日志。

### 第四阶段：让任务可恢复

保存关键状态和调用结果，为写操作增加幂等键，为长任务增加检查点、取消和恢复机制。

### 第五阶段：用评估驱动迭代

建立代表真实业务的任务集。每次调整模型、提示词、工具或调度策略后，比较成功率、延迟、成本和风险指标。

没有评估的 Harness 优化，很容易只是在为某个演示案例打补丁。

## 一份最小生产检查清单

准备让 Agent 执行真实任务之前，至少确认：

- 任务授权范围清楚。
- 上下文来源可信且可追踪。
- 工具描述和返回结构明确。
- 默认采用最小权限。
- 外部写入有审批或明确授权。
- 敏感凭据不进入模型上下文。
- 调用设置超时、取消和有限重试。
- 写操作支持幂等或重复检测。
- 循环有步数、成本和停止上限。
- 长任务有检查点和恢复方案。
- 最终结果有验证步骤和证据。
- 日志足以复盘，但不会泄露敏感信息。
- 用户可以看到进度并随时接管。
- 关键场景有持续运行的评估集。

如果这些问题大多没有答案，系统还处于 Agent Demo 阶段，而不是可托付真实工作的 Agent 产品。

## 最后理解 Harness

Harness 的核心价值可以浓缩成一句话：

> 它把模型的判断，转化为受约束、可执行、可恢复、可验证的现实动作。

模型决定系统可能有多聪明，提示词决定它倾向怎样行动，工具决定它能做什么，而 Harness 决定这一切能否长期稳定地协同工作。

真正成熟的 AI 工程，不只是不断追求更强模型，也是在建设更清晰的上下文、更可靠的工具、更严格的权限、更耐用的状态和更可信的验证体系。Harness 正是承载这些能力的地方。

## 参考资料

OpenAI 的官方模型指导强调，应明确工具路由、并发与重试上限、停止条件、授权边界、所需证据和最终验证。这些原则与 Harness 的工程职责高度一致：[OpenAI Model guidance](https://developers.openai.com/api/docs/guides/latest-model)。

## 系列延伸阅读：Harness 的八个核心部分

如果你想进一步理解 Harness 的内部结构，可以按下面的顺序阅读八篇专题文章。它们分别从“明确任务”讲到“验证结果”，共同组成一条完整的 Agent 运行链路：

1. [Harness 核心之一：任务入口与契约——先定义什么叫完成](https://www.ittt.cc/articles/24)
2. [Harness 核心之二：上下文引擎——给 Agent 正确的信息](https://www.ittt.cc/articles/25)
3. [Harness 核心之三：Agent Loop——让每一轮都有真实进展](https://www.ittt.cc/articles/26)
4. [Harness 核心之四：工具网关——把模型意图变成安全操作](https://www.ittt.cc/articles/27)
5. [Harness 核心之五：策略与安全层——让 Agent 在边界内行动](https://www.ittt.cc/articles/28)
6. [Harness 核心之六：状态与持久化——让任务可以安全恢复](https://www.ittt.cc/articles/29)
7. [Harness 核心之七：可观察性与用户控制——让过程看得见](https://www.ittt.cc/articles/30)
8. [Harness 核心之八：验证与评估——不要相信“我完成了”](https://www.ittt.cc/articles/31)