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

# 结果概览

评测请求开始写入输出后，会将任务结果、运行记录、汇总指标和日志保存在同一个运行目录中。本页介绍目录结构，并帮助你根据查看目的找到对应文件。后续页面分别说明各类产物，以及任务结果如何形成聚合指标。

如果评测在创建运行目录前就未通过预检，或者执行的是 `launch --dry-run`，则不会生成结果目录。

## 目录布局

结果目录由启动命令决定。`agentcompass run` 使用：

```text theme={"system"}
<results_dir>/[<run_name>/]<model>_<benchmark>_<harness>/<run_id>/
```

`agentcompass launch` 使用：

```text theme={"system"}
<results_dir>/[<output.run_name>/]<requests[].name>/<run_id>/
```

组合的组件 ID 和请求名称会规范化为安全目录名。结果根目录默认为 `results`。每个请求名称为 launch 请求划分独立的输出命名空间，因此即使 Model 和 Benchmark 相同，不同请求也可以使用相同运行 ID。

一次完整运行通常会在其运行目录中生成以下目录和文件：

```text theme={"system"}
<run-directory>/
  details/
    normal/
      <readable-task-id>--<sha256>/
        task.json
        attempt-<n>/
          result.json
          checkpoint.json
          artifacts/
    error/
    fatal/
    running/
  run.log
  run_info.json
  params.json
  progress.json
  progress.jsonl
  summary.md
  metrics.json
  analysis_summary.json
  analysis_summary.md
```

未设置 `run-name` 时，路径中不会包含这一层。任务目录按所有 attempt 最终问题的最高等级分组：任一 attempt 以 fatal 结束时放入 `fatal/`；否则任一 attempt 含 error 时放入 `error/`；其余放入 `normal/`，仅含 warning 的结果也在其中。尚未完成的任务位于 `running/`，写入任务结果时再移动到对应分组，不计为结果。每个 attempt 拥有自己的 `checkpoint.json`；只有需要保留 retry 诊断或旧执行产物时才创建 `retries/`。只有存在可汇总的分析结果时才会生成分析摘要。如果评测在预检、任务执行或汇总阶段提前结束，目录中可能只有已经写入的部分文件。

## Legacy

原先的布局将每个任务的完整结果保存为一个文件，checkpoint、retry 诊断和日志分别放在独立目录。以下对比省略了指标、进度等未改变的运行级文件；`<task-key>` 表示可读 task ID 加完整 SHA-256 后缀。

原先的目录结构：

```text theme={"system"}
<run-directory>/
  details/
    <task-key>.json
    _error_<task-key>.json
  checkpoints/
    <hash-prefix>/<sha256>/attempt-<n>.json
  retry_details/
    <retry-record>.json
  logs/
    <timestamp>.log
  run_info.json
```

当前的目录结构：

```text theme={"system"}
<run-directory>/
  details/
    <normal|error|fatal|running>/
      <task-key>/
        task.json
        attempt-<n>/
          result.json
          checkpoint.json
          artifacts/
          retries/
  run.log
  run_info.json
```

原先一个任务文件包含全部 attempts，出现运行或评测错误时使用带 `_error_` 前缀的文件名。现在 `task.json` 保存任务共享信息和 `"1": "attempt-1"` 这类映射，各 attempt 独立保存结果、checkpoint、采集产物和 retry 记录。问题记录在结果内容中，状态目录按最终问题的最高等级对任务分组。不含状态目录的中间版本 `details/<task-key>/` 布局仍可读取。可选目录仅在需要时生成。

## Reuse 支持情况

* 运行 schema 受支持、Benchmark ID 和 attempt 计划相同的运行可以使用 `--reuse`，并需通过[任务/attempt 及产物校验](/zh/user_guide/other_features/results/run_records#reuse-identity)。缺少或保留历史 fingerprint 字段均不影响复用。
* 不支持的运行 schema 仍需重新运行，不能靠重命名目录或移动文件迁移。
* runtime 结果读取、复用、重新汇总和离线分析使用当前 `task.json` 加独立 attempt 的目录结构，也读取不含状态目录的 `details/<task-key>/`；不支持旧版扁平详情或更早的索引布局，也不会自动升级已有目录。
* 复用总是写入新的运行目录。作为最终结果复制的任务直接放入对应状态目录；需要重试 attempt 的任务放在 `running/`，完成后再移动。

## 从哪里开始

| 需要查看的内容 | 页面 | 主要产物 |
| - | - | - |
| 在浏览器中浏览运行的指标、任务和轨迹 | [`agentcompass view`](/zh/user_guide/using_agentcompass/cli/view) | 整个运行目录 |
| 查看单个任务的答案、观测、错误、轨迹或 retry 记录 | [任务结果](/zh/user_guide/other_features/results/task_results) | `details/*/*/task.json` + `details/*/*/*/result.json`、`details/*/*/*/retries/*.json` |
| 理解多次尝试、任务和类别如何形成聚合指标 | [指标与聚合](/zh/user_guide/other_features/results/metrics_aggregation) | `details/*/*/task.json` + `details/*/*/*/result.json`、`metrics.json` |
| 查看整个运行的汇总指标或评测后的分析结果 | [汇总与分析](/zh/user_guide/other_features/results/summary_analysis) | `summary.md`、`metrics.json`、`analysis_summary.*` |
| 确认本次运行使用的请求、最终状态和执行进度，或根据日志排查问题 | [运行信息与排障](/zh/user_guide/other_features/results/run_records) | `run_info.json`、`params.json`、`progress.json`、`progress.jsonl`、`run.log` |

`details/<state>/<task-key>/task.json` 保存任务共享信息和 attempt ID 映射，各 attempt 的 `result.json` 保存自身结果；读取时组合这些文件并汇总 retry 次数，不再生成 task 层结果文件。`metrics.json` 是规范的运行级报告，`summary.md` 是对应的可读展示：`k=1` 保留原来的指标布局，`k>1` 展示多次尝试计划和序列。之后单独执行 `agentcompass summary` 时，会重新读取详情和已保存的尝试计划。启用分析后，每次 attempt 的分析输出会写入 `analysis_result`，再单独形成运行级分析摘要。进度文件、日志、checkpoint 和 attempt `retries/` 用于观察、恢复与排查；retry 诊断不直接参与 Benchmark 指标计算。

## 数据、缓存与输出目录

Benchmark 数据与评测结果保存在不同目录中。配置路径时，可以根据下表判断应使用哪项设置：

| 设置 | 默认值 | 作用 |
| - | - | - |
| `runtime.data_dir` / `--data-dir` | `data` | 保存下载的数据集、缓存以及准备完成的 Benchmark 数据。这些内容不属于运行结果。 |
| `runtime.results_dir` / `--results-dir` | `results` | 设置所有运行结果共同使用的根目录。 |
| `--run-name` | 空 | 在结果根目录下增加一层可选的命名空间，便于对多组运行进行分类。 |
| `--run-id` | 自动生成 | 指定本次运行的目录 ID。同一路径下不能使用已经存在的 ID。 |

在配置文件中，使用 `runtime.data_dir` 和 `runtime.results_dir` 设置根目录；运行单个评测请求时，也可以通过对应的 CLI 选项传入。`run-name` 和 `run-id` 属于每个请求的输出设置，因此在多评测编排文件中需要写入相应请求的 `output`。详情见 [`agentcompass run`](/zh/user_guide/using_agentcompass/cli/run#输出与复用) 和 [`agentcompass launch`](/zh/user_guide/using_agentcompass/cli/launch#字段说明)。

## 相关页面

* [运行控制](/zh/user_guide/using_agentcompass/run_controls)
* [`agentcompass summary`](/zh/user_guide/using_agentcompass/cli/summary)
* [`agentcompass analysis`](/zh/user_guide/using_agentcompass/cli/analysis)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.