> ## 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 每完成一个任务就写入明细，再将这些明细聚合为请求级指标与摘要。复用会把不含运行或评测错误的任务明细复制到新运行，无论答案正确与否。复用过程不会写入源目录，也不是在源目录上“续跑”。

主要实现是 `src/agentcompass/runtime/results/store.py` 中的 `RunStore`，明细结构整理逻辑位于 `detail.py`，聚合逻辑位于 `summary.py`，经过校验的指标类型位于 `src/agentcompass/runtime/metrics/`。

## 结果目录与持久化边界

`RunStore` 预留以下目录结构：

```text theme={"system"}
<results_dir>/<可选 output.run_name 层级>/<benchmark id>/<model id>/<run id>/
```

用户控制的 `output.run_name`、Model ID 和运行 ID 部分会在使用前规范化；Benchmark 目录使用已选中的注册 Benchmark ID。显式 `run_id` 对应的目录不能已经存在；未指定时，存储模块会生成基于时间戳的 ID，并在需要时递增，以原子方式预留唯一目录。

核心产物如下：

| 产物                                              | 用途                                       | 写入方                                                                       |
| ----------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
| `run_info.json`                                 | 数据结构版本、开始/结束状态、脱敏后的完整请求、逐任务/尝试的已解析计划、复用源 | `write_run_info`、`record_resolved_execution_plan`、`write_terminal_status` |
| `params.json`                                   | 供结果工具使用的精简、脱敏后的 Benchmark、Model 与输出标识    | `_write_params_record`                                                    |
| `details/<task>[_<category>].json`              | 可计入统计的已完成任务记录                            | `save_partial_result`                                                     |
| `details/_error_<task>[_<category>].json`       | 包含运行或评测错误的任务记录                           | `save_partial_result`                                                     |
| `retry_details/*.json`                          | 被丢弃的 runtime 重试诊断，绝不属于可计数的任务集合           | `save_retry_detail`                                                       |
| `summary.md`                                    | 供人阅读的请求指标                                | `save_results`                                                            |
| `.summary_counts.json`                          | 用于渲染摘要的机器可读计数                            | `save_results`                                                            |
| `analysis_summary.md` 与 `analysis_summary.json` | 可选分析器聚合                                  | `save_analysis_summary`                                                   |

进度报告器与 runtime 日志注册表会把进度和日志路径加入返回的 `paths` 映射。

`RunRequest.to_task_payload` 序列化完整的执行请求，并在 `metadata` 非空时包含它；`run_info.json` 保存脱敏后的序列化数据。`RunRequest.to_persistence_params` 只提供存储与复用所需的 Benchmark、Model、输出、复用和元数据值，`params.json` 再将其压缩为脱敏后的 Benchmark、Model 与输出数据。Harness、Environment 和执行设置应查看 `run_info.json.request`。

疑似敏感的字段和值会在持久化边界被替换。已解析的计划使用明确的字段白名单视图，而不是转储完整的 `ExecutionPlan`。增加持久化字段时，既要确认它对可复现性确有必要，也要确认嵌套凭证不会随之泄漏。

## 结果层级

不要把所有结果都当成 `RunResult`。各层的生成方、职责和持久化位置如下：

`RunResult` 定义在 `src/agentcompass/runtime/models/` 下的 `result.py`。

| 层级     | 生成方                                                       | 关键契约与去向                                                                                                                    |
| ------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 原始执行结果 | `BaseHarness.run_task` 或 `HarnessFreeBenchmark.run_task`  | `RunResult` 记录 `status`、`final_answer`、`trajectory`、`artifacts`、用量指标和运行错误；尚未形成 Benchmark 权威评分                              |
| 产物补全结果 | `Benchmark.collect_artifacts`                             | 在任务 Environment 释放前补充下载或规范化后的产物，不聚合请求指标                                                                                    |
| 已评测尝试  | `Benchmark.evaluate`                                      | 填写权威的 `correct`、`score`、评测错误和 Benchmark 专属字段；持久化前可附加 `analysis_result` 与脱敏的 `meta.resolved_execution_plan`                 |
| 任务明细   | `_run_attempts` 与 `build_detail_record`                   | 以 `"1"`、`"2"` 等键保存尝试，并记录任务标识、类别、`k`、`attempts_tried`、首次答对尝试、任务正确性和重试计数；`build_detail_record` 将字段限制为支持的持久化结构，再写入 `details/` |
| 请求结果   | `summarize_results` 与 `UnifiedEvaluationRuntime.finalize` | 聚合新旧明细并返回 `metadata`、已校验的 `metrics`、内存 `summary`、`paths` 和 `applied_recipes`；易读版本写入 `summary.md`                           |
| 编排结果   | `Orchestrator`                                            | 每个请求对应包含终态、错误和可用路径的 `RequestOutcome`；整体由 `OrchestrationResult` 保存编排标识、状态、时间戳和有序结果映射                                        |

`save_partial_result` 会立即以原子方式写入任务明细。它递归脱敏密钥，使用暂存文件与 `fsync`，防止并发写入覆盖已有正常结果，并在后续成功时移除过期的 `_error_` 文件。

`Benchmark.aggregate_metrics` 返回的请求指标必须通过 `MetricResult` 校验：包含 `schema_version`、`metrics` 中至少一个有限数值，以及 `counts.total`、`counts.evaluated`、`counts.error` 和可选的 `details`、`extra`。这些请求级对象都不是任务 `RunResult`。

## 结果复用

**选择来源。** `RunRuntimeSpec` 包含 `reuse` 与 `reuse_run_id`，非空 `reuse_run_id` 会自动启用复用。

在任何编排请求预留输出目录前，`Orchestrator._preflight` 都会调用 `UnifiedEvaluationRuntime.freeze_reuse_source`，避免隐式查找误选同一次编排先前创建的运行目录。

源查找遵循以下规则：

* 设置 `reuse_run_id` 时，使用当前运行名称、Benchmark 和 Model 根目录下的对应目录，不存在则失败；
* `reuse=True` 且未指定 ID 时，选择该根目录下包含 `run_info.json` 的最新目录；
* 隐式复用找不到源时，该请求会禁用复用并作为新运行继续；
* 多个 `launch` 请求共用同一 Benchmark 与 Model 时，系统无法确定隐式复用源，应为每个请求指定明确的源 ID。

这里的“根目录”范围很重要：隐式源选择只匹配结果命名空间、Benchmark ID 和 Model ID，不比较完整的 Benchmark、Harness、Environment、Model 参数或评测器配置。跨配置复用前应检查 `run_info.json`，或明确指定已知来源。

**物化任务明细。** `RunStore.materialize_reused_details` 始终以新预留的运行目录为目标：

1. 为当前选中的每个 `task_id` 查找正常明细文件，优先使用包含对应类别的文件名；
2. 将源文件硬链接到新的 `details/`，无法链接时回退到 `shutil.copy2`；
3. 忽略缺失的任务和全部 `_error_` 文件；
4. 使用 `load_partial_results` 加载已放入新目录的正常明细；
5. 只调度新运行中没有正常明细的任务 ID。

错误文件会被明确忽略：失败任务会重新运行，缺失任务也会正常运行。复用的非错误明细与新生成的明细会按当前选中的任务列表排序，并在收尾时一起聚合。

复用成功后，`run_info.json.reused_from` 记录源运行 ID 与路径，源运行保持不变。

## 兼容性规则

持久化的明细文件会被复用、用于重新生成摘要、分析以及供外部工具读取。修改时应遵循：

* 数据集每次加载都保持 `task_id` 稳定；
* 尽量以新增方式扩展尝试字段，并提供兼容默认值；
* 保持正常文件与 `_error_` 文件名的语义；
* 将重试诊断留在 `details/` 之外；
* 既测试写入新运行，也测试读取已有运行目录；
* 让 `MetricResult.counts` 与实际分母保持一致；
* 保留原子写入与递归脱敏。

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