Harness 是什么？

AI Harness Engineering 关心的是整个运行系统，而不是某一句 prompt。
它统一设计整个运行系统：上下文、工具、状态、权限、日志、验证、失败恢复。

这个词目前最明确的使用场景是 coding agent / 编程智能体。OpenAI 在 Codex 文章里说，Codex harness 提供支撑 Codex 体验的核心 agent loop 和执行逻辑；OpenAI 另一篇 “Harness engineering” 文章则讨论了在 agent-first 软件开发中，工程师如何调整代码库、知识、架构和审查方式来让 Codex agents 更有效地工作。

AI Harness Engineering = 设计模型外面的“运行支架”，让 AI Agent 能在真实环境里按规则做事，并且能被控制、观察、验证和改进。

一个 Agent 可能会计划、调用工具、改文件、查数据库、发消息。
Harness 要回答的是：
它能看什么？
它能做什么？
它做到哪一步了？
它做错了怎么办？
它什么时候必须停？
它的结果怎么验收？
它的每一步能不能追溯？

Harness 和其他相关概念的区别

+----------------------+--------------------------------+
| 概念                 | 解决的问题                       |
+----------------------+--------------------------------+
| Prompt               | 怎么把任务说清楚                   |
| Context              | 模型应该看哪些资料                 |
| Tool                 | 模型能调用哪些动作                 |
| MCP                  | 工具/数据如何标准化接入             |
| Skill                | 某类任务的流程如何复用              |
| Agent                | 如何围绕目标循环行动                |
| Harness              | 整套 agent 系统如何可靠运行         |
+----------------------+--------------------------------+

设计一个Harness

模块 1：任务规格

Harness 首先要把用户目标变成可执行任务。

用户说：
“帮我修一下登录 bug。”

Harness 要补全：
- 哪个仓库？
- 哪个分支？
- 允许改哪些文件？
- 成功标准是什么？
- 必须跑哪些测试？
- 最终输出什么？

任务规格越清楚，agent 越不容易跑偏。

模糊目标：
“优化一下系统。”

更好的任务规格：
“定位 /api/login 最近 24 小时 500 错误的根因；
只允许修改 src/auth 和 tests/auth；
必须新增回归测试；
最终输出 diff、测试结果和风险说明。”

模块 2：上下文装配

Harness 要决定模型每一步看什么。

+----------------------+
| Context Builder      |
+----------------------+
| 输入：任务、文件、日志、历史、工具结果 |
| 输出：这一轮模型该看到的上下文        |
+----------------------+

例如修 bug 时，context builder 可能会放入：

- 用户目标
- 相关代码
- 错误日志
- 最近 commit
- 测试失败输出
- 项目约束
- 已尝试方案

它也要排除：

- 无关文件
- 过期文档
- 不该暴露的密钥
- 可能诱导模型越权的恶意内容

模块 3：工具注册与工具策略

Harness 要管工具，不只是把工具丢给模型。

Tool Registry:
- read_file
- edit_file
- run_tests
- search_code
- query_database
- send_slack_message
- create_pull_request

但更重要的是工具策略：

read_file       -> 自动允许
run_tests       -> 自动允许
edit_file       -> 仅允许工作区文件
query_database  -> 只读，只能查测试库
send_email      -> 必须人工确认
delete_file     -> 默认禁止

Anthropic 在构建有效 agents 的文章中也强调，工具和工作流的组合应从简单模式开始，只有在需要更强灵活性时才增加 agent 自主性。

模块 4：Agent Loop

Agent loop 是 Harness 的心脏。

while not done:
    observe current state
    decide next action
    call tool or ask user
    receive result
    update state
    verify progress

ASCII 图：

┌──────────────┐
│ 观察当前状态  │
└──────┬───────┘
       v
┌──────────────┐
│ 决定下一步    │
└──────┬───────┘
       v
┌──────────────┐
│ 调用工具/行动 │
└──────┬───────┘
       v
┌──────────────┐
│ 接收结果      │
└──────┬───────┘
       v
┌──────────────┐
│ 更新状态      │
└──────┬───────┘
       v
┌──────────────┐
│ 验证是否完成  │
└───┬───────┬──┘
    │否     │是
    v       v
  继续    输出结果

OpenAI 的 Codex 文章明确把 Codex harness 的核心描述为 agent loop 和执行逻辑；Codex App Server 文章还提到 harness 会支撑流式进度、工具使用、审批和 diff 等 agent 体验。

模块 5：状态与记忆

Agent 做长任务时，必须知道自己做到哪一步。

State:
- 当前计划
- 已读文件
- 已调用工具
- 已失败命令
- 已修改文件
- 待验证事项
- 最终输出要求

没有状态管理时，agent 容易：

- 重复做同一件事
- 忘记之前失败过
- 改了文件但忘记跑测试
- 跑了测试但忘记总结结果

所以 Harness 通常要维护一个“任务账本”。

+----------------------+
| Task Ledger / 任务账本 |
+----------------------+
| [x] 读取 README       |
| [x] 找到 login 代码    |
| [x] 运行测试，失败      |
| [x] 修改 session 释放  |
| [ ] 运行回归测试       |
| [ ] 输出风险说明       |
+----------------------+

模块 6：执行环境与沙箱

如果 agent 能运行命令、改文件、联网，就必须控制执行环境。

Sandbox / 沙箱要限制：
- 能访问哪些文件
- 能不能联网
- 能不能安装依赖
- 能不能读环境变量
- 能不能访问生产服务
- 命令最长运行多久
- 消耗多少 CPU / 内存 / token

OpenAI 在 2026 年 Agents SDK 更新中提到更强的 agent loop harness、原生 sandbox execution，以及把 harness 和 compute 分离以获得安全性、持久性和扩展性。

直白说：

没有沙箱的 agent 像一个拿到公司电脑管理员权限的实习生。
有沙箱的 agent 像一个只能在指定实验室操作的实习生。

模块 7：权限与人工审批

Harness 要区分低风险和高风险动作。

+----------------------+----------------+
| 动作                 | 策略             |
+----------------------+----------------+
| 读取本地项目文件       | 自动允许          |
| 运行单元测试           | 自动允许          |
| 修改工作区代码         | 允许，但记录 diff  |
| 查询测试数据库         | 只读允许          |
| 查询生产数据库         | 默认禁止          |
| 发送 Slack 消息        | 需要确认          |
| 创建 PR              | 需要确认          |
| 删除文件              | 高风险确认/禁止    |
| 付款/转账/发合同       | 禁止或强审批       |
+----------------------+----------------+

这部分不是“让模型更会推理”，而是“防止模型做不该做的事”。

模块 8：可观测性

Harness 要记录 agent 的行动轨迹。

Observability:
- 模型每一步想做什么
- 调用了哪个工具
- 参数是什么
- 工具返回什么
- 哪一步失败
- 为什么重试
- 最终结果基于哪些证据

图：

Agent 行动
   |
   v
+------------------+
| Trace / 轨迹日志  |
+------------------+
   |
   +--> 调试
   +--> 审计
   +--> 失败归因
   +--> 性能评估
   +--> 后续改进

OpenAI 关于内部 coding agents 监控的文章提到，监控系统会记录和分析 agent 的行动，并对可疑或有问题行为自动报警，用于快速处置安全问题和改进 safeguards。

模块 9：验证与验收

这是 Harness 和普通 agent demo 的最大差别之一。

普通 demo 可能只看：

模型说它完成了。

Harness 要看：

证据显示它完成了。

例如 coding agent 的验证：

- 单元测试是否通过
- 回归测试是否通过
- lint 是否通过
- diff 是否只改了允许文件
- 是否新增测试
- 是否引入安全风险
- 是否违反项目规范

Agent 输出：
“我修好了。”
       |
       v
Harness 验证：
- pytest 通过？
- diff 合理？
- 日志消失？
- 没改无关文件？
       |
       v
通过 -> 接受
失败 -> 回到 agent loop

好 Harness 的判断标准

一个好 harness 不只是“能跑”，而是要满足这些标准：

+------------------------------------------------+
| 好 Harness 的标准                               |
+------------------------------------------------+
| 1. 任务清楚                                     |
| 2. 上下文准确                                   |
| 3. 工具合适                                     |
| 4. 权限最小化                                   |
| 5. 高风险动作可审批                              |
| 6. 执行过程可观察                                |
| 7. 失败原因可归因                                |
| 8. 最终结果可验证                                |
| 9. 成本和时间可控                                |
| 10. 可以持续改进                                |
+------------------------------------------------+

坏 harness 的样子：

- 把一堆工具全给模型
- 权限无限大
- 没有日志
- 没有测试
- 没有停止条件
- 模型说完成就算完成

好 harness 的样子：

- 工具按任务分层开放
- 敏感动作要确认
- 每一步有 trace
- 最终必须通过验证
- 失败能回滚或重试
- 人能看懂它做了什么

总结

用一个“大脑 + 身体 + 规章制度”的图记住

                +----------------+
                |      LLM       |
                |     大脑        |
                +-------+--------+
                        |
                        v
+------------------------------------------------+
|                  Agent                         |
|        会计划、会调用工具、会观察结果               |
+----------------------+-------------------------+
                       |
                       v
+------------------------------------------------+
|                  Harness                       |
|                                                |
|  给任务     给资料     给工具     给流程           |
|  管权限     管状态     管日志     管验证           |
|  管沙箱     管审批     管失败     管改进           |
+------------------------------------------------+
                       |
                       v
+------------------------------------------------+
|                外部环境                         |
|  文件、代码、数据库、浏览器、API、CI、Slack、MCP     |
+------------------------------------------------+