> ## 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.

# 汇总与分析结果

本页介绍运行目录中的 Benchmark 汇总和分析器汇总，帮助你选择要查看的文件，并理解其中的字段。

这两类结果回答的问题不同：

* Benchmark 汇总说明评测完成了多少任务、得到哪些指标，对应 `summary.md` 和 `.summary_counts.json`。
* 分析器汇总说明轨迹、错误或运行指标中发现了哪些现象，对应 `analysis_summary.json` 和 `analysis_summary.md`。分析结果用于诊断，不会改变 Benchmark 的判定。

这四个文件展示整个运行的汇总结果，而不是单个任务的原始记录。[`details/*.json`](/zh/user_guide/other_features/results/task_results) 保存已经写入磁盘的逐任务记录，也是重新汇总和重新分析时的输入；评测结束时首次生成的 Benchmark 汇总则使用本次运行收集到的结果。

## 文件一览

| 文件                      | 何时生成                                                                        | 适合查看的内容                                 |
| ----------------------- | --------------------------------------------------------------------------- | --------------------------------------- |
| `summary.md`            | 评测进入汇总阶段且 Benchmark 聚合成功；或者执行未启用 `--dry-run` 的 `agentcompass summary`       | 任务计数、Benchmark 指标和可选的分组明细               |
| `.summary_counts.json`  | 与 `summary.md` 由同一次 Benchmark 聚合生成                                          | 供程序读取的 `total`、`evaluated` 和 `error` 计数 |
| `analysis_summary.json` | 已启用分析且至少一个已保存任务包含可聚合的 `analysis_result`；或者 `agentcompass analysis` 产生了可聚合结果 | 分析器统计、分析错误计数、异常样本（bad case）文件索引和数据分布    |
| `analysis_summary.md`   | 与 `analysis_summary.json` 由同一次分析聚合生成                                        | 便于人工查看的总体、分类和分布分析                       |

运行尚未结束、在汇总前中断或 Benchmark 聚合失败时，`summary.md` 可能不存在。启用分析也不一定产生 `analysis_summary.*`：如果没有任务详情、没有尝试记录，或所有尝试都没有 `analysis_result`，AgentCompass 不会写入分析汇总。

同一组 Markdown 和 JSON 文件共享一次聚合结果，但会依次写入，不会同时完成。如果进程恰好在写入期间退出，目录中可能只留下其中一个文件。此时可重新运行对应的 `summary` 或 `analysis` 命令。

## Benchmark 汇总

### `summary.md`

`summary.md` 是 Benchmark 汇总的可读版本。你可以先用它确认任务计数，再查看 Benchmark 指标及可选明细。

文件依次包含以下部分：

| 部分                | 内容                                                 |
| ----------------- | -------------------------------------------------- |
| 标题                | 大写 Benchmark ID 和 `Evaluation Results`             |
| Model             | 本次运行记录的 model ID                                   |
| 通用计数              | `Total`、`Evaluated` 和 `Error`                      |
| `Metrics`         | Benchmark 返回的指标名称和值                                |
| `Details: <name>` | Benchmark 提供的可选分组或补充明细；能转换为表格时显示为表格，否则显示为 JSON 代码块 |

缩略结构如下：

```markdown theme={"system"}
# <BENCHMARK> Evaluation Results

**Model:** `<model>`

**Total:** <total>
**Evaluated:** <evaluated>
**Error:** <error>

## Metrics

| Metric | Value |
| --- | --- |
| <metric-name> | <value> |

## Details: <optional-detail-name>
...
```

Markdown 内容来自 Benchmark 聚合结果中的 `counts`、`metrics` 和 `details`。结果对象还包含 `schema_version`（结构版本）和 `extra`（Benchmark 提供的附加信息），但这两个字段不会写入 `summary.md`。

三个通用计数的含义如下：

| 计数          | 含义                               |
| ----------- | -------------------------------- |
| `total`     | 本次聚合覆盖的任务总数                      |
| `evaluated` | 产生了可计入 Benchmark 指标结果的任务数        |
| `error`     | 被 Benchmark 聚合逻辑判定为执行错误或评测错误的任务数 |

不要假设 `evaluated + error = total`。Benchmark 还可能区分跳过、没有有效判定等状态，具体计数口径由对应 Benchmark 决定。指标名称、计算方式和数值范围也因 Benchmark 而异，请查阅对应的 [Benchmark 文档](/zh/user_guide/modules/benchmarks/overview)。

评测正常收尾时，AgentCompass 汇总本次运行收集到的任务结果，其中可能包含尚未写入详情文件的早期错误。单独执行 `agentcompass summary` 时，它会改为读取 `details/*.json`。两种结果通常一致；但如果任务在详情写入前就失败，重新汇总时没有对应详情，计数就可能不同。

### `.summary_counts.json`

`.summary_counts.json` 是三个通用计数的机器可读快照，不包含 Benchmark 指标或分组明细：

```json theme={"system"}
{
  "total": 100,
  "evaluated": 96,
  "error": 4
}
```

工具可以通过这个文件快速读取运行规模和错误数量，但它不能替代逐任务详情，也不能单独重建 `summary.md`。`agentcompass summary` 会重新读取 `details/*.json` 并执行 Benchmark 聚合，不会直接采用这里保存的旧计数。

## 分析器汇总

分析器的输出先保存在每次尝试的 `attempts.<index>.analysis_result.<analyzer-family>` 中，再按任务、类别和分析器系列汇总到运行级文件。

`<analyzer-family>` 通常是分析器 ID，也可以是多个分析器实现共用的系列 ID。下文表格中的 `analyzer` 字段均指这个 ID。

### `analysis_summary.json`

`analysis_summary.json` 适合程序读取，也包含 Markdown 版本未展示的异常样本文件索引。顶层字段如下：

| 字段                          | 内容                                        |
| --------------------------- | ----------------------------------------- |
| `per_category_per_analyzer` | 按类别和分析器分别统计，每个组合对应一行                      |
| `per_category_overall`      | 按类别统计，每行合并该类别中的所有分析器                      |
| `overall_per_analyzer`      | 按分析器统计，每行合并所有类别，并通过 `items` 列出对应的异常样本详情文件 |
| `overall`                   | 合并所有类别和分析器后的总体统计                          |
| `distributions`             | 分析器声明的值频次或数值分布，按分析器、类别和字段组织               |

前四个字段中的统计行使用相同的基本结构：

| 字段              | 含义                                                                 |
| --------------- | ------------------------------------------------------------------ |
| `category`      | 任务类别；总体行使用 `__overall__`，没有类别的任务使用 `(no category)`                 |
| `analyzer`      | 分析器系列 ID；合并所有分析器的行使用 `__overall__`                                 |
| `total`         | 当前统计范围内包含该分析结果的任务数                                                 |
| `badcase_count` | 其中 `is_badcase=true` 的任务数                                          |
| `error_count`   | 首选分析结果包含非空 `error` 的任务数                                            |
| `badcase_ratio` | `badcase_count / total`；没有任务时为 `0`                                 |
| `avg_score`     | 分析器提供数值 `score` 时的平均值；没有可用得分时为 `null`                              |
| `items`         | 仅出现在 `overall_per_analyzer` 中，列出被该分析器标记为异常样本的 `details/*.json` 文件名 |

缩略示例：

```json theme={"system"}
{
  "per_category_per_analyzer": [
    {
      "category": "coding",
      "analyzer": "ExceptionAnalyzer",
      "total": 12,
      "badcase_count": 2,
      "error_count": 0,
      "badcase_ratio": 0.1667,
      "avg_score": null
    }
  ],
  "per_category_overall": [
    {
      "category": "coding",
      "analyzer": "__overall__",
      "total": 12,
      "badcase_count": 2,
      "error_count": 0,
      "badcase_ratio": 0.1667,
      "avg_score": null
    }
  ],
  "overall_per_analyzer": [
    {
      "category": "__overall__",
      "analyzer": "ExceptionAnalyzer",
      "total": 20,
      "badcase_count": 3,
      "error_count": 1,
      "badcase_ratio": 0.15,
      "avg_score": null,
      "items": ["task-a.json", "_error_task-b.json"]
    }
  ],
  "overall": [
    {
      "category": "__overall__",
      "analyzer": "__overall__",
      "total": 20,
      "badcase_count": 3,
      "error_count": 1,
      "badcase_ratio": 0.15,
      "avg_score": null
    }
  ],
  "distributions": {}
}
```

#### 多次尝试如何合并

同一任务包含多次尝试时，AgentCompass 按以下规则得到该任务的分析结果：

1. 优先采用 `solved_at` 指向的尝试；如果没有成功尝试，则采用最后一次已保存的尝试。
2. 随后检查其他尝试。如果某个分析器返回 `is_badcase=true`，该分析器的任务级判定会设为 `true`；只有首选尝试没有该分析器时，才会连同该次结果的 `score` 和 `details` 一并补入。其他尝试中的 `false` 或 `null` 不会补入。
3. 同一任务在同一分析器的统计中最多计数一次。

合并所有分析器时，`badcase_count` 表示至少被一个分析器标记的任务数，`error_count` 表示至少出现一个分析器错误的任务数，因此两者都不是各分析器对应计数的总和。计算合并行的 `avg_score` 时，每个任务贡献其所有可用分析器得分中的最大值。

汇总还会省略部分没有有效内容的行：

* 如果一个用于检查异常样本的分析器在整个运行中既没有发现异常样本也没有报告错误，该分析器不会出现在汇总中；只提供统计、不返回 `is_badcase` 的分析器，以及包含错误的分析器仍会保留。
* 对于已经保留的分析器，如果某类别有布尔判定但结果全部为 `false` 且没有错误，该类别行不会显示；如果该类别完全没有该分析器的结果，当前结构可能仍保留一行 `total: 0`。

#### `distributions`

分析器可以通过 `distribution_fields` 声明需要汇总哪些结果字段。结果按 `distributions.<analyzer-id>.<category>.<field>` 组织，支持两种方式：

| 方式              | JSON 内容                                                                |
| --------------- | ---------------------------------------------------------------------- |
| `value_counts`  | `total` 表示收集到的值数量，`distribution` 保存频次最高的最多 50 个值及其计数；如果字段值是列表，每个元素分别计数 |
| `numeric_stats` | `count` 表示收集到的数值数量，并提供 `min`、`mean`、`p50`、`p90`、`p95` 和 `max`          |

跨类别统计使用 `__overall__` 作为类别键，没有类别的任务使用空字符串。对于已保留且声明了相应分布字段的分析器，`value_counts` 即使没有收集到值，也会显示 `total: 0` 和空的 `distribution`；`numeric_stats` 只有在收集到数值后才会出现。

<Note>
  同一次运行中的任务应统一使用类别：要么每条详情都有非空 `category`，要么全部不使用类别。自定义 Benchmark 如果混用这两种任务，分析汇总可能无法生成。
</Note>

### `analysis_summary.md`

`analysis_summary.md` 是同一次分析聚合生成的可读版本，依次包含：

1. Benchmark 和 model 标题；
2. `Overall` 表，按分析器显示 `Total`、`Badcase`、`Error`、`Badcase Ratio` 和 `Avg Score`，并包含合并所有分析器的 `__overall__` 行；
3. 每个任务类别的同结构表和 `__overall__` 行；
4. 存在分布数据时显示的 `Distributions` 部分，其中包含数值统计表和值频次表。

Markdown 文件不会列出 `overall_per_analyzer[].items` 中的全部详情文件名。如果需要按分析器定位异常样本，请读取 `analysis_summary.json`。

## 生成和重新生成结果

### 随评测生成

[`agentcompass run`](/zh/user_guide/using_agentcompass/cli/run) 和 [`agentcompass launch`](/zh/user_guide/using_agentcompass/cli/launch) 会在每个评测请求成功完成 Benchmark 聚合后写入 `summary.md` 和 `.summary_counts.json`。如果启用了分析且存在可聚合结果，还会写入 `analysis_summary.json` 和 `analysis_summary.md`。

### 重新生成 Benchmark 汇总

[`agentcompass summary`](/zh/user_guide/using_agentcompass/cli/summary) 读取已有的 `details/*.json`、运行元数据和恢复出的 Benchmark 配置，默认原地覆盖 `summary.md` 与 `.summary_counts.json`。它不会运行 agent、Benchmark 验证器或分析器，也不会修改任务详情。

使用 [`agentcompass summary --dry-run`](/zh/user_guide/using_agentcompass/cli/summary#预览摘要) 时，命令只在终端输出 Markdown，不修改运行目录中的文件。

### 重新运行分析器

[`agentcompass analysis`](/zh/user_guide/using_agentcompass/cli/analysis#重新分析已有结果) 从已保存的尝试字段、规范化轨迹及其步骤指标和错误中恢复输入，并对每个可读取的尝试运行分析器。有新输出时，命令会更新 `analysis_result`，然后生成两种分析汇总文件。

该命令不会重新运行 agent 或 Benchmark 验证器，也不会重新计算 `summary.md`。如果分析器跳过某次尝试，或分析流程在产生新结果前失败，原有的 `analysis_result` 可能保留。

默认情况下，`agentcompass analysis` 会复制输入运行，并把结果写入带时间戳的同级目录。使用 `--output` 可以指定副本位置；只有使用 `--override` 才会在原目录中更新分析字段和汇总。

重新分析会从已保存字段重建分析输入，但无法还原所有评测时的上下文，例如轨迹步骤中的工具定义、`meta` 和每次尝试的解析后计划。依赖这些信息的分析器可能得到与随评测运行时不同的结果。

<Note>
  如果本次分析没有产生可聚合结果，AgentCompass 不会删除目标目录中已有的 `analysis_summary.*`。因此，仅凭文件存在不能判断它是否在本次分析中更新。通过 [`--benchmark-params` 中的 `sample_ids`](/zh/user_guide/using_agentcompass/cli/analysis#参数) 只会限制重新运行分析器的任务；生成最终汇总时仍会扫描目标目录中的全部详情，并可能纳入未选任务原有的 `analysis_result`。
</Note>

Benchmark 汇总和分析器汇总彼此独立。使用不同聚合参数重新生成 `summary.md` 不会重新运行分析器；重新分析也不会更新 Benchmark 指标。

## 使用和共享时的注意事项

<Warning>
  这四个文件不会再经过统一脱敏，也不会对所有 Markdown 内容进行完整转义。Benchmark 的自由文本 `details`、分析器分布值、类别和 `items` 中的详情文件名可能包含任务标识或敏感内容，也可能影响 Markdown 结构。共享前请检查文件内容；对于不可信结果，不要使用允许原始 HTML 的渲染器直接打开。
</Warning>

这四个文件均为生成产物。需要修正结果时，请重新运行任务，或调整 Benchmark 聚合逻辑或分析器配置后重新生成；不要直接编辑这些汇总文件。

## 相关页面

* [结果概览](/zh/user_guide/other_features/results)
* [任务结果](/zh/user_guide/other_features/results/task_results)
* [`agentcompass summary`](/zh/user_guide/using_agentcompass/cli/summary)
* [`agentcompass analysis`](/zh/user_guide/using_agentcompass/cli/analysis)
* [Benchmark](/zh/user_guide/modules/benchmarks/overview)