> ## 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 会为它创建独立的运行目录。除了任务详情和汇总结果，该目录还包含以下运行记录： ```text theme={"system"} / ├── run_info.json ├── params.json ├── progress.json ├── progress.jsonl └── run.log ``` `run_info.json` 记录请求配置、指标产物溯源和最终状态，`params.json` 保存结果写入与重新汇总所需的精简参数。`progress.json` 提供最新进度快照，`progress.jsonl` 保留完整事件序列，日志则记录便于阅读的执行消息和异常。 ## 文件何时生成 | 文件 | 创建与更新时间 | | - | - | | `run.log` | 预留运行目录时创建，并从此时开始接收日志。 | | `run_info.json` | 在加载任务前创建，并在写入解析后执行计划、指标产物和请求最终状态时更新。 | | `progress.json`、`progress.jsonl` | 发出第一个进度事件时创建。之后的每个事件都会更新快照并追加到事件流。 | | `params.json` | 评测运行中保存任务详情时创建或重写；成功生成最终汇总后再次重写，即使所选任务集为空也会生成。 | 并非每次调用都会留下这些文件。CLI 和 SDK 会先在运行目录外检查请求；如果此时失败，不会创建运行目录。`agentcompass launch --dry-run` 也不会创建输出。 运行目录建立后再发生准备错误，通常已经有日志和 `run_info.json`；如果错误能够正常收尾，还会写入最终状态和 `run_finished` 事件。进程被强制终止时，最终状态、最后几个进度事件或 `params.json` 可能尚未写入。 ## `run_info.json` `run_info.json` 记录本次评测使用的请求配置、当前指标产物由哪份计划生成，以及请求最终如何结束。它在任务加载前创建，并在运行过程中持续更新。 ### 顶层字段 | 字段 | 说明 | | - | - | | `schema_version` | 运行记录的精确 schema，当前值为 `agentcompass.run_info.v3`。 | | `run_id` | 本次请求最终使用的运行 ID。 | | `started_at` | 创建这份记录的时间，采用带时区的 ISO 8601 格式。它不是 AgentCompass 进程或整个编排的启动时间。 | | `request` | 按配置优先级合并 CLI、配置文件或 SDK 参数后得到的请求。此时尚未针对具体任务应用 Recipe。 | | `metric_artifacts` | 生成 `summary.md` 和 `metrics.json` 后出现，记录它们的生成来源和精确报告计划。 | | `reused_from` | 解析到复用来源运行时出现，记录来源运行的 `run_id`、`path` 或两者；即使最终没有任务被复用，也可能存在。 | | `resolved_execution_plans` | 至少一个任务尝试完成计划解析后出现，按任务 ID 和尝试编号记录计划摘要。 | | `status` | 请求的最终状态：`completed`、`failed`、`cancelled` 或 `timed_out`。请求尚未正常收尾时可能不存在。 | | `finished_at` | 写入最终状态的时间，采用带时区的 ISO 8601 格式。 | | `error` | 请求因错误结束时记录错误信息；成功完成时不出现。 | 当前 run-info v3 使用结构化 issues。旧 v2 结果只在读取边界转换；分类未知的旧失败不能复用为新协议有效评分，不修改历史目录。 ### `request` 的结构 `request` 按 model、Benchmark、Harness、Environment、执行控制、runtime、输出和元数据分区。各组件的 `params` 是开放对象，具体字段由所选组件决定。 | 字段路径 | 说明 | | - | - | | `model.id` | 被评测 model 的 ID。 | | `model.base_url` | model API 的基础地址；未设置时可以为空。 | | `model.api_key` | model API 凭据。写入文件时会按敏感字段规则脱敏，不能从该值还原原始密钥。 | | `model.api_protocol` | Model API 协议名称或有序协议列表。`auto` 与未指定都会在构建请求时归一化为空字符串，因此文件中不会保留字面值 `auto`。 | | `model.params` | 传给 model 客户端的请求或生成参数。 | | `benchmark.id` | 所选 Benchmark 的组件 ID。 | | `benchmark.params` | 合并配置与请求覆盖后得到的 Benchmark 专属参数。 | | `harness.id` | 所选 Harness 的组件 ID。 | | `harness.params` | 合并配置与请求覆盖后得到的 Harness 专属参数。 | | `environment.id` | 所选 Environment 的组件 ID。 | | `environment.params` | 合并配置与请求覆盖后得到的 Environment 专属参数。逐任务 Recipe 对它的修改尚未包含在内。 | | `environment.network_policy` | Environment 准备阶段使用的网络策略。 | | `environment.run_network_policy` | Harness 或任务执行阶段使用的可选网络策略；没有单独设置时可以省略。 | | `environment.verifier_network_policy` | Benchmark 评分阶段使用的可选网络策略；没有单独设置时可以省略。 | | `execution.task_concurrency` | 实际 attempt 执行的最大并发数，包括 retry。 | | `execution.attempts` | 精确的多次尝试计划，包含 `k` 和 `strategy`。 | | `execution.enabled_recipes` | 可参与匹配的 Recipe ID 列表；空列表表示不限制候选 Recipe。 | | `execution.keep_environment` | 任务结束后是否保留 Environment，供调试检查。 | | `execution.enable_analysis` | 是否在评测过程中同时运行分析器。 | | `execution.analysis_params` | 分析器选择、分析 model 以及各分析器的专属设置。 | | `execution.max_retries` | 每个评测尝试内部最多允许的 runtime 重试次数。 | | `execution.retry_pattern_list` | 匹配 ERROR message／code 的正则；null 和 \[] 都只重试 FATAL。 | | `runtime.reuse` | 按当前 issues、pattern 和重试预算政策逐 attempt 复用兼容结果。 | | `runtime.reuse_run_id` | 明确指定复用来源的运行 ID。留空时，AgentCompass 可以查找最近的兼容运行。 | | `runtime.checkpoint_resume` | 待执行的 fresh 评测是否可以从 agent 正常完成后的 checkpoint 继续。有效默认值为 `true`。 | | `output.run_name` | 结果根目录下的可选命名空间。 | | `output.run_id` | 当前运行最终使用的目录 ID。 | | `metadata.config_path` | 构建请求时加载的配置文件。一个文件记录为路径字符串；多个文件记录为包含全部路径的 JSON 数组字符串；没有加载配置文件时不出现。 | | `metadata.recipe_dirs` | 构建请求时加载的外部 Recipe 目录列表；没有时不出现。 | 网络策略对象包含 `network_mode`（网络访问模式）和 `allowed_hosts`（允许访问的 host 列表）。写入 JSON 时，值为 `null` 的字段、空对象和空列表会被移除，因此 `allowed_hosts` 为空时不一定出现在文件中。 `request` 不是原始命令行的副本，也不包含 `results_dir`、整个请求的超时、日志级别或 Environment provider 并发限制等进程级设置。要核对这些内容，请同时查看调用命令、配置和日志。组件专属字段见 [Model](/zh/user_guide/modules/models/overview)、[Benchmark](/zh/user_guide/modules/benchmarks/overview)、[Harness](/zh/user_guide/modules/harnesses/overview) 和 [Environment](/zh/user_guide/modules/environments/overview) 文档。 `reused_from` 出现时包含以下字段： | 字段 | 说明 | | - | - | | `run_id` | 复用来源的运行 ID。 | | `path` | 复用来源运行目录的路径。 | ### 复用校验 复用要求运行 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 都会替换这份溯源记录： ```json theme={"system"} { "metric_artifacts": { "generated_at": "", "source": "evaluation", "report": { "k": 3, "strategy": "avg", "aggregation": "micro_weighted" } } } ``` 正常运行收尾时 `source` 为 `evaluation`，以非 dry-run 方式执行 `agentcompass summary` 后为 `summary`。重新汇总还会记录脱敏后的 `benchmark_params_override` 对象；未传入覆盖时为空对象。`report` 将三个文件与生成它们的精确 attempt 计划和运行级聚合绑定，不会取代原始 `request`。 ### `resolved_execution_plans` 的结构 `resolved_execution_plans` 记录每次任务尝试解析得到的 Environment、网络策略和 Recipe。其结构如下： ```json theme={"system"} { "resolved_execution_plans": { "": { "attempts": { "1": { "environment": { "id": "", "network_policy": { "network_mode": "public", "allowed_hosts": [] } }, "evaluation_environment": null, "run_network_policy": { "network_mode": "public", "allowed_hosts": [] }, "verifier_network_policy": { "network_mode": "public", "allowed_hosts": [] }, "applied_recipes": [] } } } } } ``` | 字段或键 | 说明 | | - | - | | `` | Benchmark 提供的任务 ID。 | | `attempts` | 该任务的计划记录，以尝试编号为键；编号从 `1` 开始。 | | `environment` | 计划用于执行任务的 Environment，只记录组件 ID 和准备阶段网络策略。 | | `evaluation_environment` | 计划用于评分的独立 Environment，只记录组件 ID 和准备阶段网络策略；不需要独立评分环境时为 `null`。 | | `run_network_policy` | 计划在 Harness 或任务执行阶段使用的网络策略。 | | `verifier_network_policy` | 计划在 Benchmark 评分阶段使用的网络策略。 | | `applied_recipes` | 本次尝试实际匹配的 Recipe ID 列表。 | 计划摘要在解析完成后、打开 Environment 前写入，因此只能说明本次尝试计划使用什么，不能证明 Environment 已成功创建。它也不包含 Recipe 解析后的完整镜像、快照、工作目录、资源或 Environment provider 参数。 未在当前请求中重新执行的复用任务或 attempt 不会新增解析后计划记录。任务详情通过 `attempt_plan` 保存指标尝试计划；Environment 和 Recipe 计划仍位于来源运行的 `run_info.json`。 ## 评测恢复记录 ```text theme={"system"} /details//--/ ├── task.json └── attempt-/ ├── result.json ├── checkpoint.json └── artifacts/ ``` `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-` 目录，更新引用后再发布结果；任务在 `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.id` | 用于结果路径、显示和恢复的 model ID。 | | `model.params` | model 请求参数的持久化副本。 | | `model.base_url` | 非空时保存的 model API 基础地址。 | | `model.api_key` | 非空时保存的脱敏凭据占位值，不能还原原始密钥。 | | `model.api_protocol` | 非空时保存的 Model API 协议名称或协议列表。 | | `benchmark.id` | 用于确定汇总方式的 Benchmark ID。 | | `benchmark.params` | 保存任务详情和重新生成汇总所需的有效 Benchmark 参数。 | | `execution` | 已保存的执行控制，包括严格重新生成汇总所需的完整 `attempts` 计划。 | | `output.run_name` | 非空时保存的结果命名空间。 | | `output.run_id` | 当前运行最终使用的目录 ID。 | `model`、`benchmark`、`execution` 和 `output` 下未设置的直属字段会被省略；嵌套 `params` 中的空字符串等值仍可能保留。`params.json` 不包含 Harness、Environment、复用设置、元数据或完整的 Recipe 解析结果，因此不能用它还原本次评测的完整配置。 重新生成汇总时，AgentCompass 优先读取 `run_info.json.request`，再用 `params.json` 补充其中缺失的内容。两个文件的用途如下： | 文件 | 范围 | 主要用途 | | - | - | - | | `run_info.json` | 较完整的合并后请求、复用来源、有限的执行计划摘要和请求最终状态 | 核对一次运行如何发起以及如何结束 | | `params.json` | Model、Benchmark、execution 和输出字段的精简子集 | 支持结果写入，并为重新汇总保存精确尝试计划 | ## `progress.json` `progress.json` 保存最新的运行状态和任务计数。每次产生进度事件时，AgentCompass 都会用最新状态替换这份快照，因此状态页或脚本可以定期读取它。 | 字段 | 说明 | | - | - | | `run_id` | 本次请求的运行 ID。 | | `model`、`benchmark`、`harness`、`environment` | 本次请求所选组件的 ID。 | | `status` | 当前运行状态。文件在第一个事件后才创建，因此通常从 `running` 开始，随后可能变为 `summarizing` 和请求的最终状态。内部初始值 `created` 通常不会写入文件。 | | `total_tasks` | Benchmark 选择后的任务总数。 | | `reused_tasks` | 从来源运行复用的任务数。 | | `pending_tasks` | 运行期间尚未开始的任务数，每次出现 `task_started` 时递减。请求结束时按 `total_tasks - finished_tasks` 重算，因此届时也包含已经开始但没有结束的任务。 | | `running_tasks` | 已开始但尚未发出 `task_finished` 的任务数。 | | `finished_tasks` | 已复用或已发出 `task_finished` 的任务数。 | | `completed_tasks` | 发出 `task_finished` 且被记为 `completed` 的任务数，加上复用任务数。 | | `failed_tasks` | `task_finished` 事件记录为 `failed` 的任务数。这是执行进度状态，不是 Benchmark 观测未成功的任务数。 | | `error_tasks` | 最终问题中最高级别为 `error` 的已结束任务数。这些任务仍计入 `completed_tasks`，此处只是按级别给出其中的错误数量。 | | `warning_tasks` | 最终问题中最高级别为 `warning` 的已结束任务数。同样计入 `completed_tasks`。 | | `skipped_tasks` | 发出 `task_finished` 且状态明确为 `skipped` 的任务数。复用任务虽然不重新执行，但计入 `completed_tasks`，不会计入这里。 | | `attempts_started`、`attempts_finished` | 已开始和已结束的评测尝试数。一次尝试内部的 runtime 重试不会增加这两个计数。 | | `partials_saved` | 已成功保存的任务级部分结果数。 | | `current_phase_counts` | 按当前阶段统计活动任务数量的对象；请求结束时清空。 | | `active_tasks` | 以任务 ID 为键，记录每个活动任务当前状态的对象；请求结束时清空。 | | `elapsed_seconds` | 从进度跟踪器创建到最新事件的秒数，保留三位小数。 | | `updated_at` | 最新事件的 Unix 时间戳，单位为秒。 | 每个 `active_tasks.` 对象都包含 `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`。 ### 每个事件都包含的字段 | 字段 | 说明 | | - | - | | `run_id` | 运行 ID。 | | `event` | 事件名称。 | | `timestamp` | 事件发出时的 Unix 时间戳，单位为秒。 | | `task_id`、`category` | 事件所属的任务及其类别；运行级事件为 `null`。 | | `attempt` | 事件所属的评测尝试编号，从 `1` 开始；不属于具体尝试时为 `null`。 | | `phase` | 事件记录的当前阶段；不适用时为 `null`。 | | `status` | 该事件记录的状态；不适用时为 `null`。 | | `payload` | 该事件特有的附加数据；没有附加数据时为空对象。 | | `orchestration_id` | 所属编排的 ID；没有编排上下文时为 `null`。 | | `request_key` | 该请求在编排中的唯一调度键；没有编排上下文时为 `null`。 | | `request_name` | 编排配置中声明的请求名称；没有编排上下文时为 `null`。 | | `request_index` | 该请求在编排配置中的位置，从 `0` 开始；没有编排上下文时为 `null`。 | 上述字段始终序列化；没有值时写入 `null`，`payload` 始终为对象。 ### 事件及其附加字段 | `event` | 事件字段和 `payload` | 含义 | | - | - | - | | `run_started` | `payload`: `model`、`benchmark`、`harness`、`environment` | 请求开始加载任务。 | | `tasks_loaded` | `payload.total_tasks` | 完成任务加载与筛选。 | | `reuse_loaded` | `payload.reused_tasks`、`payload.tasks_to_run`、`payload.reused_severity_counts` | 完成复用结果加载，并确定仍需执行的任务数；`reused_severity_counts` 按最高问题级别统计复用任务。 | | `task_started` | `task_id`、`category`；`payload.index`、`payload.total` | 任务开始调度执行。 | | `phase_changed` | `task_id`、`category`，可选 `attempt`；`phase` | 任务进入新阶段。 | | `attempt_started` | `task_id`、`category`、`attempt` | 开始一次评测尝试。 | | `execution_plan_resolved` | `task_id`、`category`、`attempt`，`phase: "plan"`；`payload` 为解析后计划摘要 | 完成本次尝试的计划解析；内容与写入 `run_info.json` 的摘要一致。 | | `attempt_retry` | `task_id`、`category`、`attempt`；`payload.retry`、`max_retries`、`stage`、`scope`、`matched_pattern`、`retry_detail` | 当前结果已被保存为重试诊断文件，并将按命中的规则重新执行。 | | `attempt_finished` | `task_id`、`category`、`attempt`；`status` 为 `completed` 或 `failed` | 一次评测尝试处理结束。这里的 `completed` 只表示处理流程返回，不表示答案正确。 | | `partial_saved` | `task_id`、`category` | 任务级结果已持久化。 | | `task_finished` | `task_id`、`category`；`status` 为 `completed`、`failed` 或 `skipped`；`payload.index`、`payload.total`、`payload.severity` | 任务结束调度执行；`payload.severity` 为该任务最终问题的最高级别（`fatal`、`error`、`warning`），无问题时为空字符串。 | | `summary_started` | 无附加字段 | 开始聚合最终汇总。 | | `run_finished` | `status` 为 `completed`、`failed`、`cancelled` 或 `timed_out`；携带错误信息时可含 `payload.error` | 请求进入终态。 | `task_started` 和对应的 `task_finished` 使用相同的 `payload.index` 与 `payload.total`。它们表示调度任务时使用的序号和总数，不是任务标识；请始终使用 `task_id` 识别任务。多评测编排通常保留任务在原始所选列表中的位置，因此复用后编号可能不连续；单评测请求则可能重新编号剩余任务。 `attempt_retry.payload` 中各字段的含义如下： | 字段 | 说明 | | - | - | | `retry` | 当前评测尝试内部已经使用的重试次数，从 `1` 开始。 | | `max_retries` | 当前评测尝试最多允许的 runtime 重试次数。 | | `stage` | 检测到错误的执行阶段。 | | `scope` | 重试范围。`attempt` 表示重新执行整个评测尝试，`evaluate` 表示只重新评分或验证。 | | `matched_pattern` | 命中的 ERROR 正则，或表示 FATAL 无条件重试的 `fatal`。 | | `retry_detail` | 保存被丢弃结果和错误信息的诊断文件路径。 | `phase_changed.phase` 的当前取值如下： | 阶段 | 含义 | | - | - | | `plan` | 解析任务级执行计划和 Recipe。 | | `open_environment` | 创建运行 Environment。 | | `prepare_task` | 在 Environment 中准备任务材料。 | | `start_harness` | 启动 Harness 会话。 | | `run_harness` | 由 Harness 执行 agent。 | | `run_task` | 由无需 Harness 的 Benchmark 直接执行推理。 | | `collect_artifacts` | 在独立 deadline 内执行声明的提交命令。没有命令时跳过；payload 包含命令数和 `source: declared_commands`。 | | `download_artifacts` | 下载显式路径或默认目录选定的产物；进度 payload 包含当前操作、已完成字节和剩余预算。 | | `recover_evaluation` | 在创建 fresh verifier Environment 前校验 checkpoint 及本地产物。 | | `save_evaluation_checkpoint` | 原子保存正常 agent 运行的上下文，并引用本次 attempt 的产物。 | | `evaluate_environment` | 为需要独立验证 Environment 的 Benchmark 创建验证环境。 | | `evaluate` | 执行评分或验证。 | | `save_partial` | 保存任务级结果。 | | `analyze` | 重新分析已有结果时更新分析结果。只会出现在该流程中。 | 任务并发执行时，不同任务的事件会交错。请使用 `task_id` 和 `attempt` 筛选单个任务；不要假设所有任务都会经历相同阶段，也不要根据不同任务的相邻事件推断依赖关系。 运行 [`agentcompass analysis`](/zh/user_guide/using_agentcompass/cli/analysis) 时，AgentCompass 会先清除目标结果目录中原有的两个 progress 文件，再记录本次分析事件。未使用 `--override` 时，目标是新建的结果副本，不会修改来源目录。 重新分析会沿用原请求的 `run_id`，但不会重建 `run_info.json`、`params.json` 或运行目录日志。这些文件仍然描述最初的评测请求。 ## `run.log` 每个 `run` 或 `launch` 请求将框架日志写入 `run.log`；再次打开同一运行目录时追加写入，不覆盖已有内容。 日志从运行目录建立后开始记录，早于 `run_info.json` 的创建和后续运行检查。CLI 或 SDK 在此之前产生的输出不会补写到该文件中。 每行日志采用以下结构： ```text theme={"system"} HH:MM:SS LEVEL logger-name message ``` * `--file-log-level` 控制运行目录日志的最低级别，默认为 `DEBUG`；`--log-level` 只控制终端输出。 * 第三方 logger 默认只保留 `WARNING` 及以上消息，即使文件级别为 `DEBUG`。 * 日志包含 AgentCompass 和已接入组件主动记录的消息，但不保证包含每条 shell 命令、provider 响应或第三方库内部事件。 * 日志不是结构化结果，也不会参与汇总、复用或重新分析。 `run_info.json` 和 `params.json` 会根据敏感字段名隐藏已识别的凭证，并移除参数对象中以下划线开头的运行时字段。该处理不是通用的敏感信息扫描，也不适用于日志。 自定义字段、自由文本、progress 事件和日志仍可能包含路径、URL、任务数据、provider 信息或堆栈跟踪。共享运行目录前，请检查并移除其中的敏感内容。 ## 排查运行失败 遇到运行失败时，按以下顺序检查可以逐步缩小范围： 1. 查看 `progress.json`，确认请求状态和各类任务数量；请求仍在运行时，还可查看当前活动阶段。 2. 按 `task_id` 检查 `progress.jsonl`，还原失败任务的最后阶段、尝试和重试路径。请求进入终态后，快照会清空活动任务，最后阶段应从事件流查找。 3. 查看 `run_info.json`，核对合并后请求、复用来源以及该尝试的 Recipe 与网络策略摘要。 4. 如果问题出现在结果保存或重新汇总阶段，再检查 `params.json`。 5. 最后在 `run.log` 中按任务 ID、阶段或异常类型查找详细消息和堆栈。 progress 文件用于观察运行过程。写入失败只会产生警告，不会中止评测，因此文件可能滞后或不完整。进程被强制终止时，`run_info.json` 和 progress 文件也可能停留在不同状态。判断最终评测结果时，请以已经保存的任务详情和汇总为准。 任务级结果字段见[任务结果](/zh/user_guide/other_features/results/task_results)，聚合指标见[汇总与分析结果](/zh/user_guide/other_features/results/summary_analysis)。日志级别和进度显示参数见[运行控制](/zh/user_guide/using_agentcompass/run_controls#日志与进度)。 ## 当前格式版本 每类记录只支持一个版本。它们标识不同的数据结构，不是同一个读取器兼容的多个历史版本。 | 记录 | 支持的 schema | | - | - | | 运行信息 | `agentcompass.run_info.v3` | | 任务索引及共享字段 | `agentcompass.task.v3` | | attempt checkpoint 外层 | `agentcompass.attempt_checkpoint.v1` | | 评测完成记录 | `agentcompass.evaluation_checkpoint.v4` | | 产物清单 | `1` | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.