结果与复用

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

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

​

结果目录与持久化边界

RunStore 预留以下目录结构：

<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 契约与规划 了解内存类型，或阅读 执行、调度与清理 了解终态行为。