智能体测试框架

agent-harness

分类通用

作者Alireza Rezvani

许可MIT

评分4.20/5

使用7.3K

Agent Harness

你是一名 harness 操作员，而非英雄。决定工作何时完成的是循环机制，而非你的乐观态度。你的职责是：将目标编译为带有检查项的任务，一次执行一个任务，由控制器裁定验证结果，并在状态机指示停止时停止。

契约

code

目标 (GOAL) → goal_compiler → 计划 (PLAN) → loop_controller: [执行 → 验证]* → 关闭 (CLOSE)
                                     ↑______重试 (≤ 最大尝试次数, 改变方法)
                                     └── 预算耗尽时升级 (ESCALATE) —— 绝不伪造成功

三层结构，全部为 JSON：每个领域提交的 manifest（定义存在哪些技能/工具/检查）、每个目标的 plan（定义哪些任务、哪些验证、什么才算“完成”），以及每次运行的 state file（唯一事实来源；新会话仅凭此文件即可恢复）。

快速上手

bash

# 0. 选择领域 manifest (assets/harnesses/ 下有 18 个提交的文件，例如 engineering-team.json)
ls assets/harnesses/
1. 编译目标 (若目标模糊，将以 exit 3 退出并强制提问)
python3 scripts/goal_compiler.py \
  --goal "审计支付服务并设计带有错误预算的 SLO" \
  --manifest assets/harnesses/engineering.json --out plan.json
2. 初始化循环状态
python3 scripts/loop_controller.py init --plan plan.json --state .agent-harness/state.json
3. 驱动循环 —— 重复执行直到指令为 "close" 或 "escalate"
python3 scripts/loop_controller.py next --state .agent-harness/state.json
   → {"action": "execute", "task": "T1", ...}: 打开任务对应的技能文件 (skill_path 下的 SKILL.md)，使用其工具完成工作，然后：
python3 scripts/loop_controller.py record --state .agent-harness/state.json \
  --task T1 --phase execute --exit-code 0
   → 控制器将自行运行任务的检查项 (子进程, 超时, 证据日志):
python3 scripts/loop_controller.py verify --state .agent-harness/state.json --task T1 --cwd <repo-root>
4. 关闭 —— 若有任何任务未验证且未放弃，则拒绝关闭 (exit 4)
python3 scripts/loop_controller.py close --state .agent-harness/state.json

在技能变更后重新生成 manifest (diff 稳定，可由 CI 检查)：

bash

python3 scripts/harness_manifest_builder.py --domain engineering-team \
  --repo-root <repo-root> --out-dir assets/harnesses --no-timestamp

硬性规则

1. 绝不自行裁定验证结果。 verify 通过子进程运行检查；如果没有 --evidence 而直接提交 record --phase verify 将被拒绝 (exit 6)。你无权宣布任务已验证。
2. 绝不修改用于评判你的门禁。 检查命令必须来自 manifest 或 plan。
修改检查项以使其通过属于“奖励黑客”（reward-hacking）失效模式（参见 references/verification_discipline.md）——这与 autoresearch-agent 的锁定评估器具有相同的不变性。
3. 一次仅执行一个任务，写入需串行化。 读取和判定可以并行，但绝不能有两个任务同时写入同一个产出物（参见 references/agentic_loop_canon.md）。
4. 重试意味着改变方法。 相同的命令 + 相同的输入 = 相同的失败。重试指令已明确要求如此，请务必遵守。
5. 预算是终止状态，而非建议。 max_attempts_per_task $\rightarrow$ 上报（exit 2）；max_loop_iterations $\rightarrow$ 上报（exit 5）。预算耗尽绝不能报告为成功——只有人类可以豁免（close --waive T3 --reason "..."），你不能。
6. 新鲜上下文优于长上下文。 每个 next 指令都必须能由一个仅读取计划（plan）和状态（state）文件的全新会话执行。对于长期目标：每次迭代都应作为独立会话针对持久化状态运行。
7. 状态存储在 .agent-harness/ 中 —— 绝不要放在 .agenthub/、.autoresearch/ 或 docs/TC/ 中（这些属于兄弟技能）。
8. 计划和状态文件是信任边界。 verify 会 shell 执行每个任务的检查命令；仅在由你或 goal_compiler.py 生成的计划/状态文件上运行 harness，绝不要在不可信的输入文件上运行（参见 references/verification_discipline.md）。

强制性问题（在编译前询问；每轮一个，并附带推荐答案）

| # | 问题 | 推荐答案 | 原因 (规范) |
|---|---|---|---|
| 1 | 哪个单一的可观察结果意味着“完成”？ | 一个具名产出物 + 一个对其执行且返回 0 的命令 | 验证者定律：优先投资于可验证性 |
| 2 | 适用哪个领域 harness？ | 产出物所属技能的领域；若涉及两个，则运行两个顺序循环 | 编排者-执行者模式：范围明确的目标优于宏大目标 |
| 3 | 什么绝对不能更改？ | 列出不可触碰的路径；将其放入目标文本中，以便编译器的计划能继承这些限制 | 边界是子代理规范的一部分 |
| 4 | 谁负责审核上报，响应速度如何？ | 指定的负责人；设计上上报会阻塞循环 | “需要审批”是一个终止状态，而非干扰项 |
| 5 | 迭代预算是多少？ | 默认 12 次循环迭代 / 每个任务 3 次尝试；增加预算必须提供理由 | 限额是运行时错误，而非建议 (类似 OpenAI SDK 的 max_turns) |

退出码（机械化分支处理）

| 代码 | 工具 | 含义 |
|---|---|---|
| 0 | 所有 | 正常 / 已发出指令 |
| 2 | loop_controller | 需要上报 —— 人类必须审核证据日志 |
| 3 | goal_compiler | 目标过于模糊 —— 请回答强制性问题并重新编译 |
| 4 | goal_compiler / loop_controller | 未匹配到技能 / 拒绝关闭（存在未验证任务） |
| 5 | loop_controller | 达到全局迭代上限 |
| 6 | loop_controller | 无效转换（在已验证任务上记录、缺失证据、未知任务） |

可验证的成功标准

python3 scripts/harness_manifest_builder.py --sample、scripts/goal_compiler.py --sample 和 scripts/loop_controller.py --sample 均返回 0。

模糊目标（--goal "make it better"）返回 3 并打印强制性问题。

在包含未验证任务的状态上执行 loop_controller.py close 返回 4。

loop_controller.py --sample 中的演示循环显示：验证失败会消耗一次尝试，且只有在验证通过并提供证据后循环才会关闭。

智能体测试框架

Agent Harness

契约

快速上手

1. 编译目标 (若目标模糊，将以 exit 3 退出并强制提问)

2. 初始化循环状态

3. 驱动循环 —— 重复执行直到指令为 "close" 或 "escalate"

→ {"action": "execute", "task": "T1", ...}: 打开任务对应的技能文件 (skill_path 下的 SKILL.md)，使用其工具完成工作，然后：

→ 控制器将自行运行任务的检查项 (子进程, 超时, 证据日志):

4. 关闭 —— 若有任何任务未验证且未放弃，则拒绝关闭 (exit 4)

硬性规则

强制性问题（在编译前询问；每轮一个，并附带推荐答案）

退出码（机械化分支处理）

可验证的成功标准

相关技能

扫码进交流群