结果与聚合

RunResult 应同时记录执行状态和 Benchmark 判定；所有任务完成后，再将任务级结果汇总为合法的 MetricResult。

​

不要混淆状态与分数

情况	status	correct	score	error
执行和评测成功，答案正确	COMPLETED	True	官方分数	空
执行和评测成功，答案错误或合法零分	COMPLETED	False 或官方定义值	0.0 或官方零分	空
Harness 或 Benchmark 执行失败	RUN_ERROR	False 或 None	通常为 None	执行错误
执行成功，但验证器崩溃、超时或输出无效	EVAL_ERROR	False 或 None	通常为 None	评测错误
执行和评测都失败	ERROR	False 或 None	通常为 None	两类错误

测试没有通过不一定是 EVAL_ERROR。例如验证器约定退出码 1 表示合法测试失败时，它是一个正常零分；只有验证器无法完成评分时才是评测错误。必须以固定版本的官方验证器契约为准。

​

保留已有执行结果

评测时优先使用 dataclasses.replace()，以免遗漏 Harness 已写入的轨迹、产物、Model 输出或 meta：

from dataclasses import replace

from agentcompass.runtime import RunResult, TaskStatus


def apply_verifier_result(result: RunResult, verifier) -> RunResult:
    eval_error = (
        verifier.timed_out or verifier.returncode not in {0, 1}
    )
    if eval_error:
        detail = (verifier.stderr or verifier.stdout).strip()
        status = (
            TaskStatus.ERROR
            if result.status == TaskStatus.RUN_ERROR
            else TaskStatus.EVAL_ERROR
        )
        error = "\n".join(
            part for part in [result.error, detail] if part
        )
        return replace(
            result,
            status=status,
            correct=False,
            score=None,
            error=error or "verifier failed",
        )

    if result.status != TaskStatus.COMPLETED or result.error:
        return replace(result, correct=False, score=None)

    passed = verifier.returncode == 0
    return replace(
        result,
        correct=passed,
        score=1.0 if passed else 0.0,
        metrics={**result.metrics, "pass": float(passed)},
    )

不要为了让聚合继续运行而把错误状态改成 COMPLETED，也不要用非空 error 表示普通错误答案。评测证据过大时，应保存截断后的摘要或文件产物，避免在多个字段中重复写入完整的验证器日志。

​

使用默认二元聚合

BaseBenchmark.aggregate_metrics() 默认调用 aggregate_binary_metrics()，适合每次尝试都给出布尔 correct 的 Benchmark。它生成 accuracy，并根据配置处理类别、k 以及 avg@k 或 pass@k。

普通二元 Benchmark 不需要覆盖该方法：

class ExampleExactMatchBenchmark(BaseBenchmark):
    # load_tasks(), prepare_task(), evaluate() ...
    pass

默认聚合读取持久化后的结果字典，而不是内存中的 RunResult 对象。自定义实现不要假定字段总在顶层；包含多次尝试的结果可能位于 result["attempts"] 中。

​

聚合连续分数

如果官方主指标是连续值，请使用共享辅助函数，并明确指标名称和缺失分数的处理方式：

from typing import Any

from agentcompass.runtime import RunRequest
from agentcompass.runtime.metrics import MetricResult, aggregate_score_metrics


def aggregate_metrics(
    self,
    results: list[dict[str, Any]],
    req: RunRequest,
    config: Any,
) -> MetricResult:
    _ = req
    return aggregate_score_metrics(
        results,
        metric_name="mean_reward",
        score_key="score",
        missing_score_value=0.0,
        config=config,
    )

missing_score_value=0.0 会把缺失分数计为零。如果官方规则排除基础设施错误或使用不同分母，就不能直接采用这个默认值；应先按官方规则选择尝试和分母，再构造 MetricResult，并在 counts 中保留总数、已评测数和错误数。

​

合并多个主指标

如果需要同时报告准确率和平均分，可以组合多个共享辅助函数：

from agentcompass.runtime.metrics import (
    aggregate_binary_metrics,
    aggregate_score_metrics,
    merge_metric_results,
)


def aggregate_metrics(self, results, req, config):
    _ = req
    accuracy = aggregate_binary_metrics(results, config=config)
    reward = aggregate_score_metrics(
        results,
        metric_name="mean_reward",
        config=config,
    )
    return merge_metric_results(accuracy, reward)

只有两个聚合使用相同的任务集合和分母时，才能直接合并。如果涉及类别加权、分层类别、不同的尝试选择规则或多个官方分母，应显式实现相应逻辑，并在 details 中说明。

​

MetricResult 的最低要求

自定义聚合必须返回 MetricResult：

字段	要求
metrics	至少一个名称非空、数值有限的主指标
counts.total	进入本次聚合的任务总数
counts.evaluated	成功得到官方分数的任务数，且不得超过 total
counts.error	包含执行或评测错误的任务数，且不得超过 total
details	可选的类别、层级或子指标结构
extra	可选的数据集版本、评测器版本等复现信息

自定义逻辑应通过 attempt_payload() 读取尝试数据，并返回新的字典或结果，避免直接修改 runtime 传入的持久化结构。共享辅助函数的实现位于 runtime/metrics。

​

聚合前检查

• 正确答案、错误答案、合法零分、执行失败和评测失败分别生成预期状态。
• correct、score 与官方主指标含义一致，不用 score == 0 推断评测器崩溃。
• 多次尝试的选择规则、k 语义和失败分母与官方实现一致。
• 类别汇总不会丢失无分数任务或把一个任务重复计入多个互斥类别。
• MetricResult 可以序列化，所有指标为有限数字，计数满足边界约束。