> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 指标与聚合

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

```text theme={"system"}
attempt.metrics → Metric Contract → Attempt Strategy → Metric Reducer → 任务级数值 → Benchmark 聚合 → MetricReport
```

## 配置多次尝试

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

```bash theme={"system"}
agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --k 3 \
  --attempt-strategy avg
```

```yaml theme={"system"}
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`](/zh/user_guide/other_features/results/summary_analysis#metricsjson) 时，应同时查看数值与这些计数。

对无法精确计算的序列，`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 中解析数据。单次尝试的观测见[任务结果](/zh/user_guide/other_features/results/task_results)，完整输出布局见[汇总与分析](/zh/user_guide/other_features/results/summary_analysis)。