评测模式与产物

根据验证器需要访问的状态选择 none、reuse 或 fresh，并在任务 Environment 关闭前提取后续评测所需的产物。

​

三种模式

模式	evaluate() 收到的 env	生命周期	适用情况
none	None	执行和产物收集后关闭任务 Environment，再在 AgentCompass 进程中评测	精确匹配、结构化答案、进程内评测器
reuse	当前任务 EnvironmentSession	执行、产物收集和评测都完成后才关闭任务 Environment	验证器必须检查执行后的同一文件系统或服务状态
fresh	新建的评测 EnvironmentSession	提取产物并关闭任务 Environment，再打开独立评测 Environment	需要隔离测试、干净镜像或不同评测网络策略

三种模式下，runtime 都在环境存活期间执行声明的收集命令；没有命令就直接收集已有文件。收集流程使用解析后的路径和命令列表，默认继承 Benchmark 声明，也可由执行参数覆盖。execution.save_artifacts 控制本地保存，fresh 要求开启。产物准备与收集不决定分数。

​

设置默认值和逐任务覆盖

如果所有样本都使用同一种模式，请在 Benchmark 类上设置默认值：

class ExampleBenchmark(BaseBenchmark):
    evaluation_environment_mode = "reuse"

如果不同样本需要不同的验证方式，请在 TaskSpec 上分别设置：

TaskSpec(
    task_id=task_id,
    question=question,
    category=category,
    ground_truth=ground_truth,
    evaluation_environment_mode="fresh",
)

runtime 规划器按以下顺序解析模式：

RunRequest.environment.evaluation_environment_mode
  > TaskSpec.evaluation_environment_mode
  > Benchmark.resolve_evaluation_environment_mode(req)

这是创建初始 ExecutionPlan 时的选择顺序。随后启用的 Recipe 可以按自身契约调整计划；如果 Recipe 会修改评测 Environment，必须在实现和测试中明确哪些字段可以覆盖、哪些字段必须保留。排查实际生效的模式时，应查看 run_info.json 的 resolved_execution_plans，其中记录了 Recipe 调整后的计划。

​

none：进程内评分

none 适合只依赖 TaskSpec、PreparedTask 和 RunResult 的评测器。不要在这种模式下读取任务工作区：

async def evaluate(
    self,
    task: TaskSpec,
    prepared: PreparedTask,
    result: RunResult,
    req: RunRequest,
    plan: ExecutionPlan,
    env: EnvironmentSession | None = None,
) -> RunResult:
    _ = task, prepared, req, plan
    if env is not None:
        raise RuntimeError("none evaluation must not receive an Environment")
    return score_answer(result)

如果进程内评测器需要调用另一个 Model，应显式配置评审 Model，并记录其版本和推理参数；不要默认让被测 Model 为自己的结果评分。

​

reuse：检查当前任务 Environment

reuse 在任务 Environment 关闭前执行评测，因此验证器能看到 agent 最终留下的工作区：

class WorkspaceBenchmark(BaseBenchmark):
    evaluation_environment_mode = "reuse"

    async def evaluate(
        self,
        task: TaskSpec,
        prepared: PreparedTask,
        result: RunResult,
        req: RunRequest,
        plan: ExecutionPlan,
        env: EnvironmentSession | None = None,
    ) -> RunResult:
        _ = task, prepared, req, plan
        if env is None:
            raise RuntimeError("workspace verification requires reuse mode")
        verifier = await env.exec(
            ["python3", "/opt/verifier/check.py"],
            timeout=300,
        )
        return apply_verifier_result(result, verifier)

验证器路径和依赖必须存在于任务 Environment 中。评测阶段使用解析后的 evaluation_network_policy；不要假定执行阶段仍保留原有的网络权限。

完整的 reuse 生产实现可参考 terminalbench2.py。

​

fresh：准备、采集，再隔离验证

fresh 不会复制整个工作区。声明 verifier 所需的文件或目录后，公共 runtime 会在关闭 agent 环境前采集，并在 fresh 环境中的同一绝对路径恢复：

TaskSpec(
    task_id=task_id,
    question=question,
    category=category,
    ground_truth=ground_truth,
    evaluation_environment_mode="fresh",
    artifacts=["/app/submission.patch"],
)

如果 agent 已经写好这些文件，无需准备命令。需要生成文件时，通过 TaskSpec.artifact_collect 声明命令；Harbor 的 verifier.collect 会映射到同一入口。例如：

from agentcompass.runtime.artifacts import ArtifactCollectCommand

TaskSpec(
    task_id=task_id,
    question=question,
    category=category,
    ground_truth=ground_truth,
    evaluation_environment_mode="fresh",
    artifacts=["/app/submission.patch"],
    artifact_collect=[
        ArtifactCollectCommand("bash /opt/task/export-submission.sh", timeout_seconds=300),
    ],
)

评测器收到的环境中已经恢复了声明的文件，不要再次下载或上传：

async def evaluate(
    self,
    task: TaskSpec,
    prepared: PreparedTask,
    result: RunResult,
    req: RunRequest,
    plan: ExecutionPlan,
    env: EnvironmentSession | None = None,
) -> RunResult:
    if env is None:
        raise RuntimeError("isolated verification requires fresh mode")
    verifier = await env.exec(
        ["bash", "/opt/verifier/run.sh", "/app/submission.patch"],
        timeout=600,
    )
    return apply_verifier_result(result, verifier)

准备和采集分别使用独立执行预算。准备或传输失败会保留诊断信息，但不继续评分或生成可续跑 checkpoint；正常缺少提交文件则由 verifier 决定分数。大小限制、完整性校验及准备钩子的职责见共同契约。DeepSWE 是准备产物并使用公共传输的生产示例。

​

选择模式时检查

• 评分只依赖答案或内存对象时选 none，不要为简单评分额外创建 sandbox。
• 验证器必须看到 agent 修改后的原始文件系统时选 reuse，并确保验证器不会污染后续需要保留的结果。
• 验证器不应信任 agent 留下的依赖或进程时选 fresh，并明确传输的最小提交物。
• prepare_task()、artifact_collect 中执行的命令以及验证器命令都要设置明确的超时，并保证重试时可以安全重复。
• 评测失败与正常零分必须使用不同状态，具体映射见结果与聚合。