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 首先要把用户目标变成可执行任务。
text
用户说：
"帮我修一下登录 bug。"
Harness 要补全：
- 哪个仓库？
- 哪个分支？
- 允许改哪些文件？
- 成功标准是什么？
- 必须跑哪些测试？
- 最终输出什么？任务规格越清楚，agent 越不容易跑偏。
text
模糊目标：
"优化一下系统。"
更好的任务规格：
"定位 /api/login 最近 24 小时 500 错误的根因；
只允许修改 src/auth 和 tests/auth；
必须新增回归测试；
最终输出 diff、测试结果和风险说明。"模块 2：上下文装配
Harness 要决定模型每一步看什么。
text
+----------------------+
| Context Builder |
+----------------------+
| 输入：任务、文件、日志、历史、工具结果 |
| 输出：这一轮模型该看到的上下文 |
+----------------------+例如修 bug 时，context builder 可能会放入：
text
- 用户目标
- 相关代码
- 错误日志
- 最近 commit
- 测试失败输出
- 项目约束
- 已尝试方案它也要排除：
text
- 无关文件
- 过期文档
- 不该暴露的密钥
- 可能诱导模型越权的恶意内容模块 3：工具注册与工具策略
Harness 要管工具，不只是把工具丢给模型。
text
Tool Registry:
- read_file
- edit_file
- run_tests
- search_code
- query_database
- send_slack_message
- create_pull_request但更重要的是工具策略：
text
read_file -> 自动允许
run_tests -> 自动允许
edit_file -> 仅允许工作区文件
query_database -> 只读，只能查测试库
send_email -> 必须人工确认
delete_file -> 默认禁止Anthropic 在构建有效 agents 的文章中也强调，工具和工作流的组合应从简单模式开始，只有在需要更强灵活性时才增加 agent 自主性。
模块 4：Agent Loop
Agent loop 是 Harness 的心脏。
text
while not done:
observe current state
decide next action
call tool or ask user
receive result
update state
verify progressASCII 图：
text
┌──────────────┐
│ 观察当前状态 │
└──────┬───────┘
v
┌──────────────┐
│ 决定下一步 │
└──────┬───────┘
v
┌──────────────┐
│ 调用工具/行动 │
└──────┬───────┘
v
┌──────────────┐
│ 接收结果 │
└──────┬───────┘
v
┌──────────────┐
│ 更新状态 │
└──────┬───────┘
v
┌──────────────┐
│ 验证是否完成 │
└───┬───────┬──┘
│否 │是
v v
继续 输出结果OpenAI 的 Codex 文章明确把 Codex harness 的核心描述为 agent loop 和执行逻辑；Codex App Server 文章还提到 harness 会支撑流式进度、工具使用、审批和 diff 等 agent 体验。
模块 5：状态与记忆
Agent 做长任务时，必须知道自己做到哪一步。
text
State:
- 当前计划
- 已读文件
- 已调用工具
- 已失败命令
- 已修改文件
- 待验证事项
- 最终输出要求没有状态管理时，agent 容易：
text
- 重复做同一件事
- 忘记之前失败过
- 改了文件但忘记跑测试
- 跑了测试但忘记总结结果所以 Harness 通常要维护一个"任务账本"。
text
+----------------------+
| Task Ledger / 任务账本 |
+----------------------+
| [x] 读取 README |
| [x] 找到 login 代码 |
| [x] 运行测试，失败 |
| [x] 修改 session 释放 |
| [ ] 运行回归测试 |
| [ ] 输出风险说明 |
+----------------------+模块 6：执行环境与沙箱
如果 agent 能运行命令、改文件、联网，就必须控制执行环境。
text
Sandbox / 沙箱要限制：
- 能访问哪些文件
- 能不能联网
- 能不能安装依赖
- 能不能读环境变量
- 能不能访问生产服务
- 命令最长运行多久
- 消耗多少 CPU / 内存 / tokenOpenAI 在 2026 年 Agents SDK 更新中提到更强的 agent loop harness、原生 sandbox execution，以及把 harness 和 compute 分离以获得安全性、持久性和扩展性。
直白说：
text
没有沙箱的 agent 像一个拿到公司电脑管理员权限的实习生。
有沙箱的 agent 像一个只能在指定实验室操作的实习生。模块 7：权限与人工审批
Harness 要区分低风险和高风险动作。
text
+----------------------+----------------+
| 动作 | 策略 |
+----------------------+----------------+
| 读取本地项目文件 | 自动允许 |
| 运行单元测试 | 自动允许 |
| 修改工作区代码 | 允许，但记录 diff |
| 查询测试数据库 | 只读允许 |
| 查询生产数据库 | 默认禁止 |
| 发送 Slack 消息 | 需要确认 |
| 创建 PR | 需要确认 |
| 删除文件 | 高风险确认/禁止 |
| 付款/转账/发合同 | 禁止或强审批 |
+----------------------+----------------+这部分不是"让模型更会推理"，而是"防止模型做不该做的事"。
模块 8：可观测性
Harness 要记录 agent 的行动轨迹。
text
Observability:
- 模型每一步想做什么
- 调用了哪个工具
- 参数是什么
- 工具返回什么
- 哪一步失败
- 为什么重试
- 最终结果基于哪些证据图：
text
Agent 行动
|
v
+------------------+
| Trace / 轨迹日志 |
+------------------+
|
+--> 调试
+--> 审计
+--> 失败归因
+--> 性能评估
+--> 后续改进OpenAI 关于内部 coding agents 监控的文章提到，监控系统会记录和分析 agent 的行动，并对可疑或有问题行为自动报警，用于快速处置安全问题和改进 safeguards。
模块 9：验证与验收
这是 Harness 和普通 agent demo 的最大差别之一。
普通 demo 可能只看：
text
模型说它完成了。Harness 要看：
text
证据显示它完成了。例如 coding agent 的验证：
text
- 单元测试是否通过
- 回归测试是否通过
- lint 是否通过
- diff 是否只改了允许文件
- 是否新增测试
- 是否引入安全风险
- 是否违反项目规范
text
Agent 输出：
"我修好了。"
|
v
Harness 验证：
- pytest 通过？
- diff 合理？
- 日志消失？
- 没改无关文件？
|
v
通过 -> 接受
失败 -> 回到 agent loop好 Harness 的判断标准
一个好 harness 不只是"能跑"，而是要满足这些标准：
text
+------------------------------------------------+
| 好 Harness 的标准 |
+------------------------------------------------+
| 1. 任务清楚 |
| 2. 上下文准确 |
| 3. 工具合适 |
| 4. 权限最小化 |
| 5. 高风险动作可审批 |
| 6. 执行过程可观察 |
| 7. 失败原因可归因 |
| 8. 最终结果可验证 |
| 9. 成本和时间可控 |
| 10. 可以持续改进 |
+------------------------------------------------+坏 harness 的样子：
text
- 把一堆工具全给模型
- 权限无限大
- 没有日志
- 没有测试
- 没有停止条件
- 模型说完成就算完成好 harness 的样子：
text
- 工具按任务分层开放
- 敏感动作要确认
- 每一步有 trace
- 最终必须通过验证
- 失败能回滚或重试
- 人能看懂它做了什么总结
用一个"大脑 + 身体 + 规章制度"的图记住
+----------------+
| LLM |
| 大脑 |
+-------+--------+
|
v
+------------------------------------------------+
| Agent |
| 会计划、会调用工具、会观察结果 |
+----------------------+-------------------------+
|
v
+------------------------------------------------+
| Harness |
| |
| 给任务 给资料 给工具 给流程 |
| 管权限 管状态 管日志 管验证 |
| 管沙箱 管审批 管失败 管改进 |
+------------------------------------------------+
|
v
+------------------------------------------------+
| 外部环境 |
| 文件、代码、数据库、浏览器、API、CI、Slack、MCP |
+------------------------------------------------+