> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 结果与复用

AgentCompass 会为已完成的 attempt 写入 checkpoint，在任务完成后以原子方式写入任务详情，最后把详情聚合为请求级指标。复用始终把兼容数据物化到新预留的运行目录，绝不会修改来源运行。

主要实现是 `src/agentcompass/runtime/results/store.py` 中的 `RunStore`。详情整理位于 `detail.py`，摘要构造位于 `summary.py`，渲染位于 `render.py`，attempt checkpoint 位于 `runtime/attempts/`，经过校验的指标类型位于 `runtime/metrics/`。

## 结果目录

`RunStore` 按启动入口预留目录。单次 `run` 使用：

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

`launch` 中的命名请求使用：

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

组件 ID 和请求名称会规范化为安全目录名。Launch 会验证规范化后的请求输出命名空间互不冲突，即使显式运行 ID 不同也不允许共享命名空间；不同命名空间可以使用相同运行 ID。

显式运行 ID 对应的目录不能已经存在。未指定时，存储模块会生成基于时间戳的 ID，并在需要时递增，以预留唯一目录。

| 产物 | 用途 |
| - | - |
| `run_info.json` | schema 标识、脱敏后的请求、终态、逐 attempt 的已解析计划、复用源和指标产物来源 |
| `params.json` | 供结果工具使用的精简、脱敏后的 Benchmark、Model、execution attempts 与输出标识 |
| `details/<state>/<task-id>--<sha256>/task.json` | 任务共享信息、尝试计划和 attempt 到目录的映射，例如 `"1": "attempt-1"` |
| `details/<state>/<task-id>--<sha256>/attempt-<n>/result.json` | 单次 attempt 结果及 retry 次数；任务摘要在读取时计算 |
| `details/<state>/<task-id>--<sha256>/attempt-<n>/checkpoint.json` | 临时调度状态及 agent 完成后的评测恢复快照 |
| `details/<state>/<task-id>--<sha256>/attempt-<n>/retries/` | Retry 诊断及旧执行产物，不计入指标 |
| `metrics.json` | 权威且经过校验的 `MetricReport` |
| `summary.md` | 同一报告的精简可读形式 |
| `analysis_summary.json` 与 `analysis_summary.md` | 可选的 Analyzer 聚合 |

临时文件创建在目标文件旁，并通过原子替换写入，不需要长期存在的 staging 目录。疑似敏感的配置会递归脱敏；指标观测、ground truth 和 final answer 属于评测事实，不受配置键脱敏影响。

任务目录使用可读 task ID 和完整 SHA-256 后缀。写入任务结果前 `<state>` 为 `running`，之后按所有 attempt 最终问题的最高等级取 `fatal`、`error` 或 `normal`，仅含 warning 的结果属于 `normal`。移动任务时会同步改写 attempt 记录中相对运行目录的产物路径。复用写入新的运行目录，需要重试 attempt 的任务放在 `running/`。新输出没有 task 层 `result.json`，也不使用错误文件名前缀。共享字段保存在 `task.json`，各 attempt 独立保存结果。attempt 映射必须使用 `attempt-<n>`。旧目录结构和复用支持情况见 [Legacy](/zh/user_guide/other_features/results/overview#legacy)。

## 结果层级

每一层结果都有明确的生成方和职责：

| 层级 | 生成方 | 契约 |
| - | - | - |
| 原始执行结果 | `BaseHarness.run_task` 或 `HarnessFreeBenchmark.run_task` | `RunResult` 记录状态、答案、轨迹、产物、Harness telemetry 和执行错误，此时还没有 Benchmark 权威判定 |
| 已评测 attempt | `Benchmark.evaluate` | 保留执行结果，把 Contract 声明的观测写入 `RunResult.metrics`，并记录评测错误或 Benchmark 证据 |
| Attempt checkpoint | attempt scheduler | 独立保存一个终态 attempt，使同一任务的其他 attempts 可以续跑而无需重新执行它 |
| 任务详情 | `build_detail_record` | 以严格结构保存任务标识、类别、ground truth、`attempt_plan`、retry 计数和 attempt 映射 |
| 请求指标报告 | reducer 与 `Benchmark.aggregate_metrics` | 先按任务合并 attempts，再应用官方跨任务公式，并返回经过校验的 `MetricReport` |
| 请求展示 | `RunStore.save_results` | 写入 `metrics.json` 和 `summary.md`；`report.html` 已停用 |
| 编排结果 | `Orchestrator` | 记录每个命名请求的终态、错误和可用路径 |

每个持久化 attempt 始终包含 `status`、`metrics`、`final_answer`、`trajectory`、`error`、`artifacts`、`analysis_result` 以及 `meta.benchmark`/`meta.harness`。可选命名空间的内容可以为空，但字段本身会保留。各 attempt 的 `result.json` 保存自身 `retry_count`；逻辑任务的总数和 `retry_counts` 在读取时计算。

`MetricReport` 保存解析后的 attempt 计划及指标序列。计数满足 `evaluated + unavailable + invalidated = total`，`error` 是可重叠的诊断。ERROR 可保留有效观察；最终 FATAL 使整题所有指标失效、设置 `evaluation_failed=true`，所有正式 `value` 均为空。`reference_value` 仅使用有效题并明确覆盖范围；缺失观察不自动补零。

## Resume 与 Reuse

Resume 和 reuse 使用相同的持久化记录，但来源选择不同：

* Resume 读取当前运行目录中已有的详情与 attempt checkpoints。
* Reuse 通过 `reuse_run_id` 或同一输出命名空间中的最新运行解析另一个来源，验证兼容性后，再把可用详情和 checkpoints 复制到新的运行目录。

已有结果目录不会移动或重命名。自动复用只搜索当前输出层级，不会回退到旧 Benchmark/Model 目录层级。

复用前，存储模块要求 Benchmark ID 和 `execution.attempts` 计划相同。任务按 task ID 匹配，checkpoint 按 attempt 序号匹配；不比较请求参数或任务输入指纹，因此待执行的 fresh 评测可以使用更新后的评测设置。完整结果仍沿用现有复用行为。

当前 run-info v3 使用结构化 issues。旧 v2 结果只在读取边界转换；分类未知的旧失败不能复用为新协议有效评分，不修改历史目录。

完整、兼容且不含错误的详情会整体复制。含运行或评测错误的详情不会整体复用，其 `k` 次尝试计划会重新调度。fresh 模式的 attempt 如果有 agent 正常完成后的记录，可以从产物恢复评测；否则重新执行 agent。

如果中断的来源任务尚无完整详情，则分别物化兼容的 attempt checkpoint。例如，`k=3` 在中断前完成了 attempt 1 和 2，resume 或 reuse 只会调度 attempt 3，再用三次结果生成最终详情。同一次 attempt 内的 runtime retry 也不会重做已经完成的同任务 attempt。

被物化 attempt 的已解析执行计划也会复制到目标 `run_info.json`，使新运行保持自包含。Benchmark ID、attempt plan 或 task/attempt 身份不兼容，或需要读取的详情、checkpoint 格式无效时，会明确失败，而不会被静默转换。

## 修改检查项

* 每个选中任务的 `task_id` 必须稳定、非空且唯一。
* attempt 观测写入 `metrics`，Benchmark 证据写入 `meta.benchmark`，Harness 诊断写入 `meta.harness.telemetry`。
* 保留原子写入、任务/attempt 身份校验、产物完整性校验、retry 隔离和逐 attempt checkpoint。
* 同时验证全新运行和中断后的 `k>1` 运行。
* 保持每个 `MetricSeries.counts` 与该 series 的实际分母一致。

继续阅读 [runtime 契约与规划](/zh/developer_guide/architecture/contracts) 了解内存类型，或阅读 [执行、调度与清理](/zh/developer_guide/architecture/execution_lifecycle) 了解 attempt 与 retry 行为。


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