指标与聚合

AgentCompass 使用同一套指标流水线处理二元、标量和混合型 Benchmark：Benchmark 声明每次尝试测量什么，运行配置决定如何执行和归约多次尝试，结果报告则为每个指标序列分别保存数值与覆盖计数。

attempt.metrics → Metric Contract → Attempt Strategy → Metric Reducer → 任务级数值 → Benchmark 聚合 → MetricReport

​

配置多次尝试

多次尝试属于执行控制，不是 Benchmark 参数。可以使用 CLI 参数，也可以在配置文件的 execution.attempts 下设置：

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --k 3 \
  --attempt-strategy avg

execution:
  attempts:
    k: 3
    strategy: avg

字段	默认值	含义
k	1	每个任务最多执行多少次相互独立的评测尝试。
strategy	avg	内置 avg 完整收集多次观测；内置 pass 在 Benchmark 的二元主指标首次成功后停止。

​

理解 Metric Contract

每个 Benchmark 都会声明一个 Metric Contract，为 attempts.<N>.metrics 中的每个键指定类型：

类型	单次尝试的值	支持的多次尝试 reducer
binary_success	JSON true 或 false	avg@k 和 pass@k
scalar	有限 JSON 数字	仅 avg@k

binary_success 表示由 Benchmark 明确定义的“成功 / 不成功”条件，例如验证器是否通过；不能因为某个数字字段当前恰好只出现 0 和 1，就把它当作二元成功指标。标量表示数量或程度，也可以表达部分分。

每个 Contract 必须声明且只能声明一个主指标。二元主指标统一使用 correct，标量主指标统一使用 score，这两个 ID 不能作为辅助指标；Benchmark 特有的 reward、f2p 等名称只能作为辅助指标。混合型 Benchmark 可以同时声明二元和标量观测，但执行策略始终由它固定的主指标决定。

AgentCompass 会在任务开始前检查 Contract。如果标量主指标的 Benchmark 选择 strategy: pass，即使 k=1 预检也会报错，因为普通数值分数没有“成功”语义。只有主指标为 correct 的 Benchmark 才能使用 pass。

​

确认会产生哪些指标序列

计划	执行方式	能够精确输出的序列
k=1	执行一次。	所有已声明指标的原生值。
k>1、strategy=avg	完成全部 k 次尝试。	所有兼容二元或标量指标的 avg@k，以及所有二元指标的 pass@k。
k>1、strategy=pass	二元主指标首次成功后停止，否则执行到第 k 次。	仅主指标的 pass@k。

k>1 时不再展示第 1 次尝试或 first 指标。二元主指标采用 avg 策略时，其 avg@k 和 pass@k 都属于重点结果；Contract 中的其他指标会作为辅助序列保留在完整报告中。

各 reducer 的定义如下：

• native@1：唯一一次有效观测的值。
• avg@k：恰好 k 个有效观测的算术平均值；二元指标中 true 记为 1，false 记为 0。
• pass@k：任一有效二元观测为 true 时立即得到 1；只有 k 个观测均有效且均为 false 时才能得到 0。

​

明确处理缺失尝试

缺失、失败、跳过或不含该指标的尝试不会被静默转换为 0 或 false。

• avg@k 只有在 k 个观测全部有效时才有值。
• 一旦已有成功观测，pass@k=1 就是精确结果，即使后续尝试无需执行。
• 只有 k 个有效观测全部为 false 时，pass@k=0 才是精确结果。

因此，每个序列都有独立的 total、evaluated、error 和 unavailable 任务计数。同一运行中的两个序列可能使用不同分母，因为一次尝试可能包含其中一个指标，却没有另一个。读取 metrics.json 时，应同时查看数值与这些计数。

对无法精确计算的序列，error 表示至少一次必需 attempt 缺失或出错；unavailable 表示所有计划 attempt 都已记录且没有错误，但该指标的有效观测数仍不足。

​

执行、重试与复用

execution.task_concurrency 是单次运行唯一的并发上限，统计的是实际执行的 attempt（包括 retry），不会把同一任务的全部 k 次尝试合并成一个并发槽位。通过 agentcompass run 启用的内联 analysis 也共享这个上限；独立的 agentcompass analysis 命令按自身的 task concurrency 调度。

使用 strategy: avg 时，只有 Benchmark 和 Harness 都声明各次尝试的状态相互隔离，同一任务的多次尝试才可以并发；否则 AgentCompass 会串行执行它们。用户仍然只需设置一个并发参数。

retry 只属于当前逻辑 attempt。第 3 次尝试触发 retry 时，已经完成的第 1、2 次尝试不会重新执行。AgentCompass 会分别保存每个终态 attempt 的 checkpoint，因此中断后的运行或配置兼容的 --reuse 运行可以从缺失的 (task, attempt) 继续。任务详情保留总 retry_count 和逐 attempt 的 retry_counts；retry 执行本身不会增加指标观测。

​

聚合任务与类别

多次尝试 reducer 与 Benchmark 聚合器解决的是两个不同问题：reducer 负责合并同一任务的 k 次观测；得到任务级数值后，runtime 再调用 Benchmark.aggregate_metrics() 应用该 Benchmark 的官方跨任务定义。

默认 Benchmark 实现会为每个序列分别应用以下共享策略：

设置	运行级计算方式
micro_weighted	平均有效任务值，每个任务权重相同。
category_mean	平均有效类别均值，每个类别权重相同。
非空 category_hierarchy	使用显式聚合树，并优先于 aggregation_mode。

每个类别和层级节点都会保存与总体结果相同的四种序列专属计数。缺失子节点使用 value: null，不会借用其他序列的计数。层级节点采用 unweighted、显式 weighted 或 weighted_by_count 时，只在有有效值的子节点之间重新归一化。

如果官方结果不是任务级数值的平均值，Benchmark 会覆盖默认 hook。例如，SciCode 的子问题准确率是 正确子问题总数 / 子问题总数，DeepResearch FACT 按已检查引用数加权引用准确率，GDPVal 使用语料总得分除以总分上限，Frontier Engineering 则根据参考表派生 medal 与 rank 结果。这些公式在选定的任务级 reducer 之后执行，因此能够同时处理 native@1 和完整的 avg@k 观测。

metrics.json 中的每个序列都会通过 aggregation 记录实际公式：共享序列使用 micro_weighted、category_mean 或 category_hierarchy，自定义序列可以使用 ratio_of_sums、sum 或 benchmark。公式输入与合计值放在 series[].extra，rank 对比等较大的 Benchmark 专属诊断放在报告级 extra；如果类别或层级公式使用的分母不是有效任务数，相应节点还会通过 aggregation_weight 明确记录实际权重。

​

查看输出

聚合成功后会写入两种互补文件：

文件	用途
summary.md	所有 k 共享任务计数与 Metrics 结构；k=1 使用原来的指标表，k>1 在指标区域补充尝试计划、序列角色、公式和独立计数。
metrics.json	规范的指标报告，包含全部重点及辅助序列、计数、类别和层级节点。

CLI 也会输出重点指标。工具和审计应读取 metrics.json，不要从 Markdown 中解析数据。单次尝试的观测见任务结果，完整输出布局见汇总与分析。