实现概览

实现 Benchmark 前，先确定由谁执行 agent、在哪里评测，以及如何聚合结果。

Benchmark 没有一套适用于所有场景的固定模板。大多数集成把执行交给 Harness；只有上游交互循环本身就是评测定义的一部分时，Benchmark 才接管执行。评分既可以在 AgentCompass 进程中完成，也可以在任务 Environment 或独立的评测 Environment 中完成。

​

第一步：确定由谁执行

这一步决定由 Harness 还是 Benchmark 执行 agent 循环：

场景	实现类型	谁实现执行阶段的 run_task()	命令中的 Harness
已有 Harness 可以执行准备后的任务	BaseBenchmark	Harness	已注册的 Harness ID
上游 Benchmark 定义了不可复用的专属交互循环	HarnessFreeBenchmark	Benchmark	none

HarnessFreeBenchmark 是 BaseBenchmark 的子类，两者共享任务加载、准备、产物收集、评测和聚合契约，只是在执行阶段由不同组件负责。优先使用 Harness 驱动；只有上游交互协议本身属于 Benchmark 定义时，才使用 Benchmark 驱动。

​

第二步：选择评测位置

这一步决定 evaluate() 在哪里运行，不受第一步选择的影响：

评测器需要什么	evaluation_environment_mode	evaluate() 收到的 env
只根据答案或已收集的数据评分	none	None
检查任务执行后的同一工作区或进程状态	reuse	仍然存活的任务 Environment
在隔离的 Environment 中运行验证器	fresh	新建的评测 Environment

BaseBenchmark 和 HarnessFreeBenchmark 都可以使用这三种模式。collect_artifacts() 不是第四种模式，而是一个可按需覆盖的生命周期方法，用于在任务 Environment 关闭前提取提交物。采用 fresh 且评分依赖任务工作区时，通常需要覆盖该方法。具体实现见评测模式与产物。

​

第三步：选择聚合方式

这一步决定如何把各次任务尝试的判定汇总为请求级指标，但不会改变由谁执行或在哪里评测：

结果形态	aggregate_metrics()
官方结果是 Contract 中任务级 reduction 的均值	继承 BaseBenchmark 的默认聚合
官方结果使用比值之和、总和、排名、奖牌或其他语料级公式	覆盖并返回 MetricReport

具体结果字段和聚合实现见结果与聚合。无论最终组合是什么，都先阅读共同契约，确定任务字段、可见性边界和逐任务计划。

​

共享生命周期

每次请求先加载并选择任务，之后再为每个任务和每次尝试执行以下步骤：

load_tasks
  → select_tasks
  → build_plan
  → 打开任务 Environment
  → prepare_task
  → Harness.run_task 或 Benchmark.run_task
  → collect_artifacts
  → evaluate
  → 持久化尝试结果
  → aggregate_metrics

调用 collect_artifacts() 时，任务 Environment 始终仍在运行。evaluate() 的执行位置由评测模式决定；所有任务完成后，aggregate_metrics() 再读取持久化结构并完成汇总。

​

方法分工

方法	实现要求或默认行为	责任
load_tasks()	必须实现	将固定版本的数据集转换为 TaskSpec
select_tasks()	默认实现	对已加载任务应用通用选择逻辑；只有特殊选择语义才覆盖
build_plan()	默认实现	为一次任务尝试解析类型化的 Benchmark 状态
prepare_task()	必须实现	在任务 Environment 中准备 Harness 或 Benchmark 执行输入
collect_artifacts()	默认空实现	在关闭任务 Environment 前提取提交物
evaluate()	必须实现	保留执行状态，并把已声明观测写入 RunResult.metrics
aggregate_metrics()	默认 Contract 驱动聚合	将任务级 reduction 转换为 MetricReport
run_task()	仅 HarnessFreeBenchmark 必须实现	执行由 Benchmark 负责的推理或交互循环

实现完成后，按文档更新补充用户入口，再按验证与对齐验证真实数据、Environment 和官方结果。