AI Harness Engineering¶
概述¶
2026 年 5 月 13 日，arxiv 上发表了一篇论文 AI Harness Engineering: A Runtime Substrate for Foundation-Model Software Agents，论文的核心阐述了一个观点：
软件工程 Agent 的能力，不应该只归因于模型本身，而应该看成
模型 + Harness + 软件环境这个组合系统的能力。
论文把 AI Harness Engineering 定义为：围绕 foundation-model software agents 的一个 runtime substrate，负责管理上下文、工具、项目记忆、任务状态、可观测性、失败归因、验证、权限和维护状态，让模型潜在的代码能力转化为可审计的软件工程行为。
解决的问题¶
基础模型已经很会生成代码、修改文件、解释代码、写测试、调用工具，但在真实软件开发任务中，自治软件工程 Agent 仍然不可靠。
作者认为不能将 Agent 失败的主要原因归咎于模型能力不够，这种解释不完整。软件工程师是一个长期、状态化、工具介导、反馈驱动的活动，需要上下文管理、项目记忆、工具接口、执行轨迹、验证信号、权限、回滚和维护纪律；这些支持在人类开发环境中很多是隐形的，但对于模型来说必须显式暴露、结构化和记录。
核心公式可以压缩为：
中心命题¶
自治软件工程能力不是模型单独的属性，而是 Model-Harness-Environment system 结合的涌现属性。
Model提供潜在的编码、推理、规划和指令跟随能力；Environment system提供仓库、测试、工具、日志、构建系统和依赖；Harness位于二者之间，调解 Agent 如何观察项目、采取行动、接收反馈并证明任务完成。
Harness 的理解¶
这里 Harness 不是：
Harness 是一个复合体，更接近：
Agent Runtime + Context Manager + Tool Layer + Memory + Trace + Verification + Permission + Maintenance Control
AI Development 场景下的 Harness 设计¶
组件职责¶
论文将 AI Development Harness 拆成 11 个组件职责：
1. Task interface
明确任务目标、需求、约束、成功标准。
缺失时：目标不清、做错任务。
2. Context manager
选择并暴露和任务相关的项目内容。
缺失时：看错文件、漏掉约束。
3. Tool registry
声明可用工具、允许命令和使用协议。
缺失时：工具调用失败、不安全命令、重复超时。
4. Project memory
提供 Agent 可读的架构、测试、已知失败知识。
缺失时：重复探索、修错架构层。
5. Task state
维护假设、已检查文件、开放问题、下一步。
缺失时：任务漂移、重复工作、执行不连贯。
6. Observability layer
暴露日志、trace、输出、运行时错误。
缺失时：成功不可验证、失败不可诊断。
7. Failure attribution
区分观察结果、期望行为、诊断结论。
缺失时：失败后随机打补丁。
8. Verification protocol
将任务需求映射为确定性证据。
缺失时：未验证的成功、虚假的信心。
9. Permission boundary
限制高风险动作，暴露审批门。
缺失时：不安全或无效的执行 episode。
10. Entropy auditor
检测 Agent 引入的维护负担。
缺失时：文档过期、依赖膨胀、代码残留。
11. Intervention logger
记录人类协助以及这种协助是否可避免。
缺失时：人类支撑被隐藏，系统自治能力被高估。
Harness 设计原则¶
论文提出 Harness 应满足五个设计原则：
- 运行时资源必须显式化，不能假设 Agent 自己能推断上下文、工具、项目记忆、验证证据、人类注意力、权限边界和维护状态；
- Harness 的中介行为必须可追踪，包括 Agent 如何选择上下文、调用工具、尝试验证、从失败恢复以及何时需要人工介入；
- 任务完成必须绑定到需求级证据，而不是自然语言自称“我完成了”；
- 失败后应该先归因再恢复，不能一失败就乱改；
- 维护熵必须纳入循环，不能把文档滞后、依赖频繁变动、生成物残留、测试效力减弱、边界违规等长期隐患排除在 Agent loop 之外
四级 Harness 阶梯¶
论文提出了一个四级 Controlled Harness Ladder：
H0：Minimal baseline
Agent 只拿到任务描述和仓库文件。
没有工具注册表，没有项目记忆，没有验证协议。
H1：Tool harness
在 H0 基础上增加工具注册表、测试命令注册表、工具使用协议。
作用是让行动面显式化、可追踪。
H2：Context–memory harness
在 H1 基础上增加 Agent 可读的项目记忆、架构说明、测试约定、已知失败、任务状态文件、上下文选择协议。
作用是让上下文和项目知识显式化、可追踪。
H3：Observability–verification harness
在 H2 基础上增加确定性行为检查、bug 复现协议、失败归因协议、验证协议、验证报告模板。
作用是把“完成任务”变成一个证据对象，而不是一句自我声明。
论文特别强调 H3 的验证流程：
1. Reproduce
先复现失败，观察实际输出与期望输出。
2. Attribute
对失败进行归因，判断问题属于哪一类、发生在哪一层。
3. Fix
根据归因结果做有针对性的修复。
4. Verify
用确定性检查验证修复行为和保留行为。
5. Report
输出验证报告，说明证据和限制。
泛化¶
论文是以 AI development 场景作为论述起点的，其中涉及到的架构设计并不能原封不动的搬到所有 Agent 场景。
核心¶
我们可以将论文抽象成一个通用公式：
如果是邮件 Agent，就是：
如果是数据分析 Agent，就是：
如果是客服 Agent，就是：
职责¶
1. Task Interface：任务接口¶
通用 Agent 里是：
例如邮件 Agent：
2. Context Manager：上下文管理¶
通用 Agent 里是：
例如客服 Agent 需要上下文：
3. Tool Registry：工具注册表¶
泛化后的实践要求：工具必须有 schema、权限、风险等级、超时、重试、审计。不能模型想调什么工具就调什么工具。正确的做法：
通用 Agent 里是：
4. Memory：记忆¶
通用 Agent 里：
例如销售 Agent：
5. Task State：任务状态¶
通用 Agent 里是：
例如工单 Agent：
6. Observability：可观测性¶
通用 Agent 里是：
任何 Agent 场景都应该有事件追踪：
7. Failure Attribution：失败归因¶
通用 Agent 里是：
不能无诊断地盲重试/盲改，要先归因再重试。
8. Verification Protocol：验证协议¶
对于不同场景的 Agent，需要针对其功能设计特有的验证协议。
例如邮件 Agent：
9. Permission Boundary：权限边界¶
通用 Agent 里是：
例如邮件 Agent 里：
10. Entropy Auditor：熵审计¶
泛化后的 Entropy Auditor 检查：
通用 Agent 里是：
例如邮件 Agent 的熵：
11. Intervention Logger：人工介入记录¶
这个记录用来区分：
- Agent 真正自主完成
- Agent 靠人类不断纠偏完成
是评估 Agent 能力的关键要素。
通用 Agent 里是：
提炼¶
对于论文中提到的 Harness 职责，可以提炼成下面 11 个模块：
T: Task Contract 任务契约
C: Context 上下文
T: Tools 工具
M: Memory 记忆
S: State 状态
F: Failure Attribution 失败归因
V: Verification 验证
P: Permission / Policy 权限与策略
O: Observability 可观测性
E: Entropy Audit 熵审计
I: Intervention 人工介入
完整结构：
每做一个 Agent，都问这 11 个问题：
1. Task：
任务目标和成功标准是什么？
2. Context：
Agent 需要看什么？不能看什么？上下文来源如何记录？
3. Tools：
Agent 能调用哪些工具？参数如何校验？失败如何处理？
4. Memory：
Agent 在执行时应该知道的记忆是哪些？
5. State：
任务状态如何保存？能不能暂停、恢复、取消？
6. Attribution：
失败的原因是什么？
7. Verification：
凭什么证明任务完成？证据是什么？
8. Permission
哪些动作低风险？哪些需要审批？哪些禁止？
9. Observability：
如何追踪模型调用、工具调用、上下文、成本和错误？
10. Entropy：
Agent 是否制造长期混乱、副作用、错误记忆或脏数据？
11. Intervention：
人类何时介入？介入是否被记录？下次能否减少介入？
总结¶
Harness 最早不是由 AI 圈提出，而是软件测试里的 test harness；它最初用于隔离、驱动和验证软件模块。
后来 AI 评测领域把它扩展为 evaluation harness，用于标准化评测模型。
再后来 coding agent 需要工具、状态、权限、反馈、测试和可观测性，于是 harness 被扩展为模型外部的运行控制层。
OpenAI 的 Codex 实践把 “Harness Engineering” 作为方法论推到台前。
arXiv 的论文是对 foundation-model software agents 的 runtime substrate 进行形式化。
从 arXiv 论文中可以抽取出一套工程认知：