agent-harness

Agent Harness

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

契约

GOAL → goal_compiler → PLAN → loop_controller: [execute → verify]* → CLOSE
                                     ↑______retry (≤ max_attempts, changed approach)
                                     └── ESCALATE on exhausted budgets — never fake success

三个层级，全部采用 JSON：按领域提交的 清单（有哪些技能／工具／检查项）、按目标制定的 计划（有哪些任务、要进行哪些验证、“完成”的定义是什么），以及按运行生成的 状态文件（唯一真实来源；新会话只需读取该文件即可恢复）。

快速开始

# 0. Pick the domain manifest (18 committed under assets/harnesses/, e.g. engineering-team.json)
ls assets/harnesses/

# 1. Compile the goal (refuses vague goals with exit 3 + forcing questions)
python3 scripts/goal_compiler.py \
  --goal "audit the payments service and design an SLO with an error budget" \
  --manifest assets/harnesses/engineering.json --out plan.json

# 2. Initialize the loop state
python3 scripts/loop_controller.py init --plan plan.json --state .agent-harness/state.json

# 3. Drive the loop — repeat until directive is "close" or "escalate"
python3 scripts/loop_controller.py next --state .agent-harness/state.json
#    → {"action": "execute", "task": "T1", ...}: open the task's skill (SKILL.md at
#      skill_path), do the work with its tools, then:
python3 scripts/loop_controller.py record --state .agent-harness/state.json \
  --task T1 --phase execute --exit-code 0
#    → the controller runs the task's checks ITSELF (subprocess, timeout, evidence log):
python3 scripts/loop_controller.py verify --state .agent-harness/state.json --task T1 --cwd <repo-root>

# 4. Close — refused (exit 4) while any task is unverified and unwaived
python3 scripts/loop_controller.py close --state .agent-harness/state.json

技能变更后重新生成清单（差异稳定，可由 CI 检查）：

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

硬性规则

1. 绝不裁定自己的验证结果。 verify 会通过子进程运行检查；通过的 record --phase verify 若未带 --evidence，会被拒绝（退出码 6）。你无权宣布任务已验证。
2. 绝不修改用于评判你的关卡。 检查命令来自清单／计划。修改检查项以使其通过，属于奖励操纵式失败模式（参见 references/verification_discipline.md）——这与 autoresearch-agent 的锁定评估器遵循相同的不变量。
3. 一次只做一个任务，写入操作串行执行。 可以并行阅读和评判，但绝不能让两个任务同时写入同一项产物（references/agentic_loop_canon.md）。
4. 重试意味着改变方法。 相同命令＋相同输入＝相同失败。重试指令已说明这一点；请遵守。
5. 预算耗尽是终止状态，不是建议。 max_attempts_per_task → 升级处理（退出码 2）；max_loop_iterations → 升级处理（退出码 5）。预算耗尽绝不能报告为成功——由人工豁免（close --waive T3 --reason "..."），而不是由你来做。
6. 新鲜上下文胜过长上下文。 每条 next 指令都应能由新会话仅凭计划和状态文件执行。对于长期运行的目标：每次迭代都在独立会话中针对持久化状态运行。
7. 状态存放在 .agent-harness/ 中——绝不能放在 .agenthub/、.autoresearch/ 或 docs/TC/ 中（这些目录属于相关技能）。
8. 计划和状态文件是信任边界。 verify 会通过 shell 执行每个任务的检查命令；只对你或 goal_compiler.py 生成的计划／状态文件运行 harness，绝不要对来自不可信输入的文件运行（参见 references/verification_discipline.md）。

编译前必答问题（编译前提问；每轮一个，并附推荐答案）

#	问题	推荐答案	原因（规范）
1	哪一个可观测结果意味着完成？	一个命名产物，以及一个对其运行后退出码为 0 的命令	验证器法则：优先投入精力确保可验证性
2	适用哪个领域 harness？	技能名称与交付物相符的领域；若有两个，则按顺序运行两个循环	编排器－工作者：范围明确的目标胜过庞大目标
3	哪些内容绝不能更改？	列出禁止触碰的路径；将它们写入目标文本，以便编译器生成的计划继承这些约束	边界是子 Agent 规格的一部分
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 中的演示循环显示：验证失败会消耗一次尝试；只有在验证通过且有证据后，循环才会关闭。

相关技能

• workflow-builder：为 Claude Code 的 Workflow 工具编写确定性的 .js 脚本。不用于目标到关闭的循环状态（本技能）。
• agenthub：在 git 工作树中，让 N 个并行 Agent 竞争完成同一个任务。在需要竞争尝试的 harness 任务中使用它。
• autoresearch-agent：针对锁定的评估器优化单个文件的指标。当任务的 done_when 是“指标有所提升”时使用它。
• tc-tracker：记录每次代码变更的生命周期。用于变更记录；harness 状态文件针对每个目标，而非每次变更。
• loop-library：通过对话发现并审查已发布的循环配方。本技能负责执行这些术语规范。
• ship-gate / self-eval / spec-driven-workflow：作为任务 verification[] 中的关闭时检查接入。

参见 references/domain_harness_design.md，了解三层架构、复用映射，以及如何提升某个领域的 harness 质量。