run_info.json 记录请求配置、指标产物溯源和最终状态，params.json 保存结果写入与重新汇总所需的精简参数。progress.json 提供最新进度快照，progress.jsonl 保留完整事件序列，日志则记录便于阅读的执行消息和异常。
文件何时生成
并非每次调用都会留下这些文件。CLI 和 SDK 会先在运行目录外检查请求；如果此时失败，不会创建运行目录。
agentcompass launch --dry-run 也不会创建输出。
运行目录建立后再发生准备错误，通常已经有日志和 run_info.json；如果错误能够正常收尾，还会写入最终状态和 run_finished 事件。进程被强制终止时，最终状态、最后几个进度事件或 params.json 可能尚未写入。
run_info.json
run_info.json 记录本次评测使用的请求配置、当前指标产物由哪份计划生成，以及请求最终如何结束。它在任务加载前创建，并在运行过程中持续更新。
顶层字段
当前 run-info v3 使用结构化 issues。旧 v2 结果只在读取边界转换；分类未知的旧失败不能复用为新协议有效评分，不修改历史目录。
request 的结构
request 按 model、Benchmark、Harness、Environment、执行控制、runtime、输出和元数据分区。各组件的 params 是开放对象，具体字段由所选组件决定。
网络策略对象包含
network_mode（网络访问模式）和 allowed_hosts（允许访问的 host 列表）。写入 JSON 时，值为 null 的字段、空对象和空列表会被移除，因此 allowed_hosts 为空时不一定出现在文件中。
request 不是原始命令行的副本，也不包含 results_dir、整个请求的超时、日志级别或 Environment provider 并发限制等进程级设置。要核对这些内容，请同时查看调用命令、配置和日志。组件专属字段见 Model、Benchmark、Harness 和 Environment 文档。
reused_from 出现时包含以下字段：
复用校验
复用要求运行 schema 受支持、Benchmark ID 相同，以及execution.attempts 计划相同。任务和 checkpoint 按 task ID 与 attempt 序号匹配。类别标签、完整任务输入、Model 参数、Harness 设置、Environment 设置和 Recipe 配置不要求与来源运行一致。
新记录不再写入 execution_fingerprints 和 task_fingerprints。旧记录中的这些字段会被忽略，缺少它们不会阻止复用或重新汇总。脱敏请求和解析后的执行计划仍用于溯源。
选择复用意味着使用已保存的 agent 输出和 prepared 任务上下文。待执行的 fresh 评测使用当前请求重新构建执行计划，包括当前的评测超时、资源和环境变量。完整结果仍优先复用，不会因为参数变化而重新评测。
Checkpoint 恢复校验任务/attempt 身份、agent 正常完成状态、fresh 评测模式、产物覆盖范围及文件完整性。已保存的产物声明可以多于当前 verifier 所需，声明顺序和采集设置不必一致。当前新增但从未采集的产物声明无法恢复；已记录的 missing 或 excluded 输出保留原有语义。
metric_artifacts 的结构
每次写入 Benchmark 指标文件时，AgentCompass 都会替换这份溯源记录：
source 为 evaluation，以非 dry-run 方式执行 agentcompass summary 后为 summary。重新汇总还会记录脱敏后的 benchmark_params_override 对象；未传入覆盖时为空对象。report 将三个文件与生成它们的精确 attempt 计划和运行级聚合绑定，不会取代原始 request。
resolved_execution_plans 的结构
resolved_execution_plans 记录每次任务尝试解析得到的 Environment、网络策略和 Recipe。其结构如下：
计划摘要在解析完成后、打开 Environment 前写入，因此只能说明本次尝试计划使用什么，不能证明 Environment 已成功创建。它也不包含 Recipe 解析后的完整镜像、快照、工作目录、资源或 Environment provider 参数。
未在当前请求中重新执行的复用任务或 attempt 不会新增解析后计划记录。任务详情通过
attempt_plan 保存指标尝试计划；Environment 和 Recipe 计划仍位于来源运行的 run_info.json。
评测恢复记录
task.json 保存任务共享信息、尝试计划及逻辑 attempt 序号与目录名的映射，例如 "1": "attempt-1"。各 attempt 的 result.json 保存自身结果和 retry 次数；任务摘要和总 retry 次数在读取时计算，不再生成 task 层 result.json。评测 checkpoint 只记录 agent 完成状态和已有产物引用。
checkpoint.json 使用 agentcompass.attempt_checkpoint.v1 schema。evaluation 部分保存任务/attempt 身份、agent 完成状态、来源 run 和评测模式，以及产物清单，引用结果使用的同一份 artifacts/，不再自动额外生成 ZIP。scheduler 部分保存终态调度状态，在 task 结果可靠保存后清理；下载过程中还可以保存 artifact_transfer 诊断记录。元数据更新使用原子写入。
恢复时先验证任务和 attempt 身份、产物声明、文件大小及校验和，再把产物上传到 fresh verifier。跨 run 复用保留逻辑 attempt 序号，将校验后的产物复制到目标的 attempt-<n> 目录，更新引用后再发布结果；任务在 running/ 与状态目录之间移动时，产物引用会同步更新，因此目标 run 不依赖来源目录继续存在。
默认产物限制仍为 16 GiB、100,000 个条目，每次操作最长 600 秒，文件保留原始字节。同一 attempt 重新执行时，旧本地产物会移入该 attempt 的 retries/ 下，避免旧文件混入新提交。不会自动创建 attempt 层日志目录。
evaluation checkpoint v4 保存已分类的 RunResult、PreparedTask、网络策略和产物 manifest。none／fresh 每轮评分使用隔离副本。旧 v3 记录仍可读取；缺少已分类快照时，跨 run 复制会说明原因并走正常执行。
Benchmark 通过 prepare_evaluation()，根据当前任务和计划重建评测上下文。SWE-bench 从保存的产物中读取 patch；恢复评测不依赖或校验 trajectory。依赖额外内存状态的 Benchmark 需要实现基于产物的恢复，否则重新执行 agent。必需输入缺失时也会重新执行。完整成功结果仍直接复用，不重新评测。
params.json
params.json 只保存写入任务详情和重新生成汇总所需的参数。AgentCompass 会在保存任务详情或生成最终汇总时重写该文件；如果请求在这两步之前失败，文件可能不存在。单独执行 agentcompass summary 不会重写已有的 params.json，但会更新指标文件以及 run_info.json 中的溯源记录。
model、benchmark、execution 和 output 下未设置的直属字段会被省略；嵌套 params 中的空字符串等值仍可能保留。params.json 不包含 Harness、Environment、复用设置、元数据或完整的 Recipe 解析结果，因此不能用它还原本次评测的完整配置。
重新生成汇总时，AgentCompass 优先读取 run_info.json.request，再用 params.json 补充其中缺失的内容。两个文件的用途如下：
progress.json
progress.json 保存最新的运行状态和任务计数。每次产生进度事件时，AgentCompass 都会用最新状态替换这份快照，因此状态页或脚本可以定期读取它。
每个
active_tasks.<task-id> 对象都包含 category、phase、attempt 和 updated_at。任务已启动但尚未进入具体阶段时，phase 为 running；没有类别或尝试编号时，对应字段为 null。
任务的最高问题级别按 fatal > error > warning 判定，每个已结束任务只计入一个级别。fatal 对应 failed_tasks，error 与 warning 分别对应 error_tasks 和 warning_tasks，并同时包含在 completed_tasks 中。
completed_tasks 表示执行流程正常结束，不表示 Benchmark 判定正确。Benchmark 观测和聚合值应以任务详情及规范的 metrics.json 为准。progress.jsonl
progress.jsonl 保存完整的进度事件流。每行是一个 JSON 对象，并按事件发出顺序追加。需要还原某个任务经历的阶段、尝试和重试时，应读取这个文件，而不是只看最新快照。
CLI 的 --progress auto|plain|none 和 SDK 的 progress="auto"|"plain"|"none" 只控制终端中的实时显示，不会关闭 progress.json 或 progress.jsonl。通过 SDK 提供自定义进度报告器时，是否生成文件由该报告器的输出配置决定。
下面字段中的“编排”是指一次 launch 调度多个评测请求。单独运行一个请求时，相关编排字段为 null。
每个事件都包含的字段
上述字段始终序列化；没有值时写入
null，payload 始终为对象。
事件及其附加字段
task_started 和对应的 task_finished 使用相同的 payload.index 与 payload.total。它们表示调度任务时使用的序号和总数，不是任务标识；请始终使用 task_id 识别任务。多评测编排通常保留任务在原始所选列表中的位置，因此复用后编号可能不连续；单评测请求则可能重新编号剩余任务。
attempt_retry.payload 中各字段的含义如下：
phase_changed.phase 的当前取值如下：
任务并发执行时，不同任务的事件会交错。请使用
task_id 和 attempt 筛选单个任务；不要假设所有任务都会经历相同阶段，也不要根据不同任务的相邻事件推断依赖关系。
运行 agentcompass analysis 时，AgentCompass 会先清除目标结果目录中原有的两个 progress 文件，再记录本次分析事件。未使用 --override 时，目标是新建的结果副本，不会修改来源目录。
重新分析会沿用原请求的 run_id，但不会重建 run_info.json、params.json 或运行目录日志。这些文件仍然描述最初的评测请求。
run.log
每个 run 或 launch 请求将框架日志写入 run.log；再次打开同一运行目录时追加写入，不覆盖已有内容。
日志从运行目录建立后开始记录，早于 run_info.json 的创建和后续运行检查。CLI 或 SDK 在此之前产生的输出不会补写到该文件中。
每行日志采用以下结构：
--file-log-level控制运行目录日志的最低级别，默认为DEBUG；--log-level只控制终端输出。- 第三方 logger 默认只保留
WARNING及以上消息，即使文件级别为DEBUG。 - 日志包含 AgentCompass 和已接入组件主动记录的消息，但不保证包含每条 shell 命令、provider 响应或第三方库内部事件。
- 日志不是结构化结果，也不会参与汇总、复用或重新分析。
run_info.json 和 params.json 会根据敏感字段名隐藏已识别的凭证，并移除参数对象中以下划线开头的运行时字段。该处理不是通用的敏感信息扫描，也不适用于日志。
自定义字段、自由文本、progress 事件和日志仍可能包含路径、URL、任务数据、provider 信息或堆栈跟踪。共享运行目录前，请检查并移除其中的敏感内容。
排查运行失败
遇到运行失败时，按以下顺序检查可以逐步缩小范围：- 查看
progress.json，确认请求状态和各类任务数量；请求仍在运行时，还可查看当前活动阶段。 - 按
task_id检查progress.jsonl，还原失败任务的最后阶段、尝试和重试路径。请求进入终态后，快照会清空活动任务，最后阶段应从事件流查找。 - 查看
run_info.json，核对合并后请求、复用来源以及该尝试的 Recipe 与网络策略摘要。 - 如果问题出现在结果保存或重新汇总阶段，再检查
params.json。 - 最后在
run.log中按任务 ID、阶段或异常类型查找详细消息和堆栈。
run_info.json 和 progress 文件也可能停留在不同状态。判断最终评测结果时，请以已经保存的任务详情和汇总为准。
任务级结果字段见任务结果，聚合指标见汇总与分析结果。日志级别和进度显示参数见运行控制。