Skip to main content
运行级输出按用途分开：Benchmark 指标文件描述评测表现；分析文件描述 trajectory、错误和诊断中发现的现象，不会改变 Benchmark 观测。

​
文件一览

文件何时生成适合查看的内容
summary.mdBenchmark 指标聚合成功。根据单次或多次尝试调整后的可读指标。
metrics.json与 summary.md 来自同一份指标报告。规范数值、逐序列计数、类别与层级。
analysis_summary.json至少一次已保存 attempt 包含可聚合的分析器输出。分析器统计、分析错误计数、异常样本文件索引和分布。
analysis_summary.md与 JSON 文件来自同一次分析聚合。便于阅读的总体、类别和分布分析。
运行在聚合前停止时，可能缺少部分或全部文件。Markdown 和 JSON 会分别写入，中断也可能留下不完整的文件组；此时重新执行对应的 summary 或 analysis 命令。

​
Benchmark 指标输出

两种 Benchmark 指标文件都来自同一份经过严格校验的指标报告，不会各自运行不同聚合器。

​
summary.md

需要直观了解结果时先读该文件。无论 k 取何值，Markdown 都先展示 Model、Total、Evaluated、Error 和 Metrics。顶部计数取自当前策略对应的主指标序列；其他序列可能采用不同的有效样本数，应以各指标行自己的计数为准。 k=1 时，Metrics 沿用原来的指标名和值两列表格，并在其后展示可用的类别或层级明细。k>1 时，只有指标区域会展开：摘要增加一行 attempt plan，Metrics 表格通过 Role 区分重点与辅助序列，并列出 reducer、实际运行级公式、数值及独立覆盖计数。完整的结构化明细仍保存在 metrics.json。 k>1 时，摘要不会再包含 first 或第 1 次尝试结果。使用 avg 策略时，二元主指标可以同时展示 avg@k 和 pass@k，而标量主指标自身只产生 avg@k；如果这个标量主指标的 Contract 还声明了二元辅助指标，每个二元辅助指标仍可产生自己的 avg@k 和 pass@k 序列。由于 pass 执行策略由主指标控制，该 Benchmark 仍不能选择 pass 执行策略，详见指标与聚合。

​
metrics.json

metrics.json 是供程序读取的权威数据源：
字段含义
k、strategy解析后的多次尝试计划。
aggregation实际运行级策略：micro_weighted、category_mean 或 category_hierarchy。
series[].series_id稳定的 <metric>.<reducer>@<k> 标识。
series[].kindbinary_success 或 scalar。
series[].roleBenchmark 主指标为 headline，其他指标为 auxiliary。
series[].aggregation生成该序列的实际公式，例如 micro_weighted、ratio_of_sums、sum 或 benchmark。
series[].value聚合值；无法精确计算时为 null。
series[].counts该序列独立的 total、evaluated、error 和 unavailable 任务计数。
series[].categories从类别键到自身 value、counts 和可选公式权重 aggregation_weight 的映射。
series[].hierarchy从层级路径到相同明细字段的映射，仅在显式层级聚合时填充。
series[].extra该公式可审计的输入，例如分子和分母指标 ID 及其合计值。
extraBenchmark 级结构化诊断，例如 rank 或 medal 对比明细。
这些计数不是运行级别名。读取某个序列时必须同时使用它旁边的计数；观测缺失会使不同指标或 reducer 的分母不同。evaluated + unavailable + invalidated = total，而 error 是独立诊断计数，可以与两者重叠。

​
分析汇总

分析器输出先存放在 attempts.<N>.analysis_result.<analyzer-family>，其聚合与 Benchmark Metric Contract 相互独立。

​
合并多次尝试

AgentCompass 不会选择通用的“最佳尝试”。对于同一任务和分析器系列，各次已保存 attempt 按以下规则合并：
  1. 任一 attempt 的 is_badcase 为 true，任务级结果即为 true。
  2. 对提供了数值分数的 attempt 计算分析器平均分。
  3. 最新的非空分析器 payload 提供分布所需的诊断字段。
  4. 同一任务在该分析器中最多计数一次。
合并多个分析器系列时，只要任一系列标记异常，该任务就是异常样本。合并后的 avg_score 会先为每个任务取可用分析器分数的最大值，再跨任务平均。

​
analysis_summary.json

字段内容
per_category_per_analyzer每个保留的类别与分析器组合对应一行统计。
per_category_overall每个类别一行，合并各分析器系列。
overall_per_analyzer每个分析器一行，合并各类别，并通过 items 列出异常样本详情文件。
overall合并全部类别和分析器后的统计。
distributions分析器声明的值频次或数值分布。
统计行使用以下字段：
字段含义
category任务类别；总体行使用 overall，无类别任务使用 (no category)。
analyzer分析器系列 ID；合并行使用 overall。
total当前范围内包含该分析结果的任务数。
badcase_count、badcase_ratio被标记为异常样本的任务数和占比。
error_count所选分析结果包含非空 error 的任务数。
avg_score可用分析器分数的平均值；没有分数时为 null。
items仅存在于 overall_per_analyzer，列出被该分析器标记的文件名。
分析器可以通过 value_counts 或 numeric_stats 声明分布字段。值频次保留出现最多的 50 个值；存在数值数据时，数值统计包含 count、min、mean、p50、p90、p95 和 max。 合并所有分析器时，badcase_count 表示至少被一个分析器标记的任务数，error_count 表示至少出现一个分析器错误的任务数，两者都不是各分析器对应计数之和。既没有发现异常样本也没有错误的异常检测分析器可以被省略；纯统计分析器和包含错误的分析器仍会保留。Markdown 版本展示包含 Total、Badcase、Error、Badcase Ratio 和 Avg Score 的总体与类别表及分布，但不会列出完整 items 索引。

​
生成或重新生成输出

agentcompass run 和 agentcompass launch 在聚合后生成 Benchmark 输出。agentcompass summary 会严格读取任务详情和已保存的尝试计划，再覆盖 summary.md 和 metrics.json，不会重新执行 attempt 或分析器。两条路径都会在 run_info.json.metric_artifacts 中记录文件来源和报告计划。 agentcompass analysis 可以更新逐 attempt 的 analysis_result 并重新生成两种分析汇总文件，不会重新运行 agent 或 Benchmark 验证器，也不会更新 Benchmark 指标输出。

​
安全共享结果

生成文件可能包含任务 ID、类别、分析器值或其他集成数据，也不会经过完整的内容安全或 Markdown 清理。共享前请先检查。

​
相关页面

最终 FATAL 设置 evaluation_failed=true。所有正式 value 均为空；reference_value 仅使用未失效题，没有有效观察时也为空。CLI 非零退出，失败 run 仍保留结果路径。