> ## 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 run` 和 `agentcompass launch` 使用同一组运行控制来管理调度、容错和评测产物。`execution.task_concurrency` 是实际 attempt 执行唯一的并发设置，不会再区分任务并发与 attempt 并发两个参数。 本页说明各项控制的作用和使用建议。配置文件的写法与覆盖顺序见 [`agentcompass config`](/zh/user_guide/using_agentcompass/cli/config)，完整的单请求参数签名见 [`agentcompass run`](/zh/user_guide/using_agentcompass/cli/run#参数参考)，多请求编排及其 CLI 覆盖见 [`agentcompass launch`](/zh/user_guide/using_agentcompass/cli/launch#运行前验证)。 | 目标 | 主要参数 | | - | - | | 控制 attempt 并发和 provider 容量 | `--task-concurrency`、`--provider-limit`、`--env-open-qps` | | 限制评测执行阶段的运行时间 | `--timeout-seconds` | | 处理可恢复的瞬时失败 | `--max-retries`、`--retry-pattern-list` | | 组织结果并复用已完成任务 | `--results-dir`、`--run-name`、`--run-id`、`--reuse` | | 保留现场和诊断信息 | `--keep-environment`、`--progress`、`--log-level`、`--file-log-level` | ## 安全扩展并发 这里的 [provider](/zh/user_guide/modules/environments/overview#选择-provider) 是创建和管理 Environment 的执行后端，例如 Docker、Daytona 或 Modal。 | 控制项 | 作用范围 | | - | - | | `--task-concurrency` | 同时执行的实际 attempt 数，包括 retry；安全时也包括同一任务的不同 `k` 次 attempt。 | | `--provider-limit ` | 同一 provider 同时承载的实际 attempt 执行数；`0` 表示不限制。 | | `--env-open-qps ` | 同一 provider 每秒新建 Environment 的速率；`0` 表示不限制启动速率。 | 有效 attempt 并发受 `task_concurrency` 和当前 provider 限制中较小者约束；`env-open-qps` 只控制 Environment 的启动节奏。使用 `strategy: avg` 时，同一任务的多次 attempt 共享该并发池，且只有 Benchmark 和 Harness 都声明状态隔离时才会重叠执行，否则保持串行。model 端点容量、provider 配额以及本地 CPU 和内存还可能进一步降低实际并发。单个 sandbox 的 CPU 和内存限制属于 Environment 参数，区别见[理解作用范围](/zh/user_guide/modules/environments/configuration/resource_limits#理解作用范围)。 ### CLI 写法 CLI 中可为不同 provider 重复传入后两项。多个评测请求使用不同 Environment 时，可以统一限制各 provider 的容量： ```bash theme={"system"} agentcompass launch evaluations.yaml \ --task-concurrency 32 \ --provider-limit docker=8 \ --provider-limit modal=24 \ --env-open-qps modal=4 ``` 单次 `agentcompass run` 只需为该请求实际使用的 provider 设置限制。 ### 配置文件写法 在 [`--config` 配置文件](/zh/user_guide/using_agentcompass/cli/config)中，provider 限制使用映射表示，不重复书写 YAML 键： ```yaml theme={"system"} runtime: provider_limits: docker: 8 modal: 24 env_open_qps: modal: 4 execution: task_concurrency: 32 ``` 上例是普通运行配置。`launch` 编排文件将共享的 `task_concurrency` 放在顶层，provider 映射仍放在 `runtime` 下，详见 [`agentcompass launch`](/zh/user_guide/using_agentcompass/cli/launch#字段说明)。 调整并发时，先选择少量有代表性的 Benchmark 任务，将任务并发设为 `1` 完成验证，再以 `2` 或 `4` 逐步增加。观察 Environment 启动延迟、model 延迟、错误率和内存用量；错误开始增多时，回退到最后一个稳定值。 ## 设置合适的超时 使用 `--timeout-seconds` 限制整个运行，通过 `--execution-params` 设置各个任务阶段的预算。Environment 启动、单条命令和单次模型请求还可有自己的时限；多个限制重叠时，先到的时限生效。 ### 整体时限与组件时限
层级参数位置控制范围
评测总时限CLI：--timeout-seconds \<秒数>一次 run 中的全部任务共享该时限；一次 launch 中的全部请求也共享该时限。计时从组件预检完成后开始，覆盖任务加载、准备、执行、分析和汇总。到期后取消未完成工作并进入资源清理。默认值为 360000 秒（100 小时）。显式设置为 0 时不设置评测总时限；这不会影响下面的组件专属超时。
Environment 创建JSON 字段：setup.build\_timeout\_seconds
通过 --env-params 传入		适用于 Daytona、Modal 等提供该字段的 Environment。每次创建 sandbox 都单独计时；超时只会使本次创建失败，不限制已创建 sandbox 中的后续操作。
Harness 专属JSON 字段：由 Harness 定义
通过 --harness-params 传入		控制范围由具体字段决定。command\_timeout 限制单条命令，request\_timeout 限制单次服务请求。任务阶段 deadline 使用公共 execution 字段。
Benchmark 专属JSON 字段：由 Benchmark 定义
通过 --benchmark-params 传入		控制范围由具体字段决定。例如，PinchBench 的 judge\_timeout\_seconds 限制单次评委 model 请求。
### 每个任务的阶段 deadline 通过 `run --execution-params`、YAML 的 `execution` 或 SDK 的 `execution_params` 设置阶段超时。使用 `launch` 时，配置放在 `defaults.execution` 或 `requests[].execution` 下。 下图展示包含 Harness 和独立评测环境的单次 attempt 的阶段预算，不表示任务整个生命周期的总时限。阶段按从左到右的顺序执行，列宽不代表实际耗时。部分阶段可能跳过；下载和恢复是否执行，取决于评测模式及产物配置。 单次任务尝试的超时覆盖范围：agent 执行、收集输出并构建 RunResult、嵌套的产物准备限制、分别计时的整批下载与恢复，以及评测。 灰色列表示不受图中六项超时配置直接约束的阶段：环境初始化、关闭 Harness、评测环境初始化和清理。这些阶段仍可能受到其他 Environment 或底层操作超时的限制。 | 字段 | 默认值 | 作用范围 | | - | - | - | | `run_timeout_seconds` | `null` | Harness 整次 `execute_task()` 调用；无 Harness 时为 Benchmark 的 `run_task()`。 | | `evaluation_timeout_seconds` | `null` | Benchmark 的每次 `evaluate()` 调用。 | | `timeout_multiplier` | `1.0` | 执行和评测的公共倍率。 | | `run_timeout_multiplier` | `null` | 替换执行阶段的公共倍率。 | | `evaluation_timeout_multiplier` | `null` | 替换评测阶段的公共倍率。 | | `harness_result_timeout_seconds` | `60` | 收集输出并构建 `RunResult`。 | | `artifact_collect_timeout_seconds` | `null` | 整组产物准备命令的总预算；`null` 表示不设整组时限。 | | `artifact_collect[].timeout_seconds` | `60` | 每条产物准备命令的预算。 | | `artifact_limits.timeout_seconds` | `600` | 每次整批产物下载或恢复的预算。 | 时间预算单位均为秒。执行预算包括 `execute_task()` 内部的准备操作、模型请求和工具执行。调用之前的环境／session 初始化，以及调用之后的结果收集，分别计时。评测预算从评测环境就绪、产物恢复完成后开始计时。 执行和评测的覆盖值未填写或为 `null` 时，依次继承 Benchmark 计划默认值、task 默认值；执行阶段还可回退到 Harness 默认值。所有来源均未提供预算时，该阶段不设时限。 最终预算为 `基础秒数 × 有效倍率`。设置阶段专属倍率时，它替换 `timeout_multiplier`；为 `null` 时使用公共倍率，两者不会相乘。倍率只影响执行和评测；结果收集、产物准备、下载和恢复仍使用各自的预算。没有基础预算时，倍率也不会产生时限。 ```bash theme={"system"} agentcompass run terminal_bench_2 claude_code "$MODEL_NAME" \ --env docker \ --execution-params '{ "run_timeout_seconds": 3600, "evaluation_timeout_seconds": 600, "timeout_multiplier": 2, "evaluation_timeout_multiplier": 1 }' ``` 上例为每次 attempt 分配 7,200 秒执行预算和 600 秒评测预算。超时后，runtime 记录失败，并尝试适用的结果收集和清理；收集到部分答案不会清除超时状态，也不保证继续评测。这些预算不会延长 sandbox 生命周期或外层 `--timeout-seconds` 总时限。 ### 收集输出并构建 RunResult `harness_result_timeout_seconds` 限制 Harness 在执行成功、报错或超时后进行的 `collect_result()` 调用。它读取日志、已保存状态和提交文件，提取答案，将轨迹、状态及诊断信息整理为 `RunResult`，供持久化、分析和评测使用。部分 Harness 还会在此阶段写出轨迹文件。 结果收集可能在执行结束后继续进行 sandbox 文件读写，因此使用独立预算；它不运行 agent，也不发起新的模型请求。收集完成后关闭 Harness session，再在仍可用的任务 sandbox 中准备和下载产物。无 Harness 的 Benchmark 跳过此钩子；收集失败会与原始执行错误一并记录。 ### 产物准备与传输 准备命令按序执行，同时受两层限制：整组共享 `artifact_collect_timeout_seconds`，每条命令有自己的 `timeout_seconds`，先到的时限生效。例如三条命令各限 60 秒、整组限 100 秒时，单条最多使用 60 秒，整组合计最多使用 100 秒。整组预算为 `null` 时，只保留单条命令限制。 一次整批下载中的所有声明文件共享 `artifact_limits.timeout_seconds`；后续恢复使用相同预算重新计时。按默认值，一次下载最多使用 600 秒，恢复另有 600 秒。 ### 配置运行后预算 以下 YAML 为构建 `RunResult` 分配 120 秒、整组准备分配 100 秒、每次整批传输分配 1,800 秒，同时继承声明路径、命令及单条命令限制： ```yaml theme={"system"} execution: harness_result_timeout_seconds: 120 artifact_collect_timeout_seconds: 100 artifact_limits: timeout_seconds: 1800 ``` 要取消整组准备时限，同时保留单条命令限制，可覆盖为 `null`： ```bash theme={"system"} agentcompass run "$MODEL_NAME" \ --execution-params '{"artifact_collect_timeout_seconds":null}' ``` CLI 和 SDK 映射在 YAML 上合并：未填写的字段继承，提供的列表替换原列表。专用 CLI 选项优先于 `--execution-params` 中的对应字段。SDK 的 `build_run_request()`、`run_evaluation()` 和 `async_run_evaluation()` 均接受 `execution_params`。 ### 根据超时位置选择参数 | 超时位置 | 应检查的控制项 | | - | - | | agent 推理或工具循环 | `run_timeout_seconds` 及其倍率，同时检查是否存在更短的模型请求或命令时限。 | | 收集日志、答案或轨迹 | `harness_result_timeout_seconds`。 | | 准备提交产物 | 单条命令的 `timeout_seconds` 和整组的 `artifact_collect_timeout_seconds`。 | | 整批下载或恢复 | `artifact_limits.timeout_seconds`。 | | Benchmark 评分 | `evaluation_timeout_seconds` 及其倍率，同时检查较短的评委请求时限。 | ## 配置产物 通过 `execution` 配置需要保存的产物、准备方式，以及评测时是否恢复产物。准备和传输时限见[超时设置](#产物准备与传输)。 ### 保存与恢复产物 对于已启用产物收集且有声明路径的 Benchmark，评测模式决定传输行为： | 评测模式 | `save_artifacts` 默认值 | 整批下载 | 整批恢复 | | - | - | - | - | | `fresh`：新建评测环境 | `true`，必须保存 | 保存声明产物。 | 在评测开始前恢复到新环境。 | | `reuse`：复用执行环境 | `false` | 仅在 `save_artifacts=true` 时执行。 | 跳过，直接使用原环境中的文件。 | | `none`：无评测环境 | `false` | 仅在 `save_artifacts=true` 时执行。 | 跳过。 | `save_artifacts` 未填写或为 `null` 时使用对应模式的默认值。跳过的传输不消耗传输预算；关闭下载后，已声明的准备命令和 Harness 结果收集仍会执行。保存产物只保留本地文件，需要保留 sandbox 时使用 `keep_environment`。 每次采集或恢复的产物大小／数量默认限制为 16 GiB 和 100,000 个条目，可通过 `artifact_limits` 下的 `max_mb`、`max_files` 调整。`max_mb` 限制整个产物列表的累计大小，也限制每个传输归档（含归档开销）；1 MB 按 1,048,576 字节计算。 准备或传输失败会保留已校验文件及执行诊断，但跳过该次 attempt 的评分和可续跑 checkpoint 创建。进度记录提供操作名称、已完成字节及剩余预算。 ### 覆盖产物路径和准备命令 Benchmark 声明提供默认路径和命令。在 `execution` 下可分别覆盖： | 字段 | 未填写或 `null` | 提供列表 | | - | - | - | | `artifacts` | 继承声明路径。 | 替换额外路径，仍保留 `/logs/artifacts/`；`[]` 表示只收集该目录。 | | `artifact_collect` | 继承准备命令。 | 替换按序执行的命令列表；`[]` 清空命令。 | 替换列表中应包含仍需保留的原始路径或命令。这些覆盖要求 Benchmark 支持产物收集，详见[提交产物与回放](/zh/developer_guide/extensions/benchmark/code_implementation/shared_contracts#提交产物与回放)。 `source` 使用 sandbox 内的绝对路径，`destination` 使用本地相对路径。命令在 Environment 默认 workdir 中执行；依赖任务 workspace 时，使用绝对路径或显式 `cd`。 ```bash theme={"system"} agentcompass run deepswe claude_code "$MODEL_NAME" \ --env docker \ --model-base-url "$MODEL_BASE_URL" \ --model-api-key "$MODEL_API_KEY" \ --execution-params '{ "save_artifacts": true, "artifacts": [ {"source": "/app/submission", "destination": "submission", "exclude": ["*.tmp"]}, {"source": "/app/result.json", "destination": "result.json"} ], "artifact_collect": [ {"command": "mkdir -p /app/submission && printf example > /app/submission/note.txt", "timeout_seconds": 60} ] }' ``` 此示例将准备命令替换为一条创建演示文件的命令，并将 `/app/submission` 保存到该 attempt 的本地 `artifacts/submission/`，排除 `*.tmp`；`/app/result.json` 保存为 `artifacts/result.json`。源路径不存在时记录缺失，不会使收集失败。独立环境评测会将文件恢复到原始 `source` 路径。 ## 只重试瞬时失败 `--max-retries` 设置每个逻辑 attempt 内的最大 retry 次数。例如，`--max-retries 2` 表示该 attempt 初始执行失败后最多再替换执行两次；retry 不会增加新的指标 attempt。 `--retry-pattern-list` 分别匹配每条 ERROR 的 message 和 code；null 和 \[] 都只重试 FATAL。FATAL 有共享预算必重试，WARNING 不触发重试。 只对再次执行可能恢复的临时错误启用重试，例如网络连接中断、临时服务异常或 sandbox 超时： ```bash theme={"system"} agentcompass run "$MODEL_NAME" \ --env \ --max-retries 2 \ --retry-pattern-list '["(?i)connection.*reset","(?i)temporar","(?i)sandbox.*timeout"]' ``` Judge 无效 JSON、缺失凭证和 Environment 故障属于 FATAL。默认预算为 0；可用 --max-retries 2 容忍瞬时故障。最终 FATAL 使 run 失败且不发布正式分数。 retry 只重启当前逻辑 attempt；允许时也可以只重做其评测阶段。已经完成的同任务 attempt 会保留 checkpoint：第 3 次 attempt 发生 retry 时不会重做第 1、2 次。最终详情通过 `retry_count` 和 `retry_counts` 记录次数，被丢弃的执行保存在 `retry_details/` 供诊断。 ## 输出与复用 ### 命名新运行 对于 `agentcompass run`，三个参数分别对应结果路径的不同层级： ```text theme={"system"} /[/]__// ``` * `--results-dir` 设置结果根目录，默认为 `results`。 * `--run-name` 添加可选的实验分组目录。 * `--run-id` 设置本次运行的目录名；不指定时使用当前时间戳。 Model、Benchmark 和 Harness ID 会规范化为安全名称，再用下划线拼成单个目录名。`agentcompass launch` 则使用每个请求规范化后的 `name` 代替这个组合目录名： ```text theme={"system"} /[/]// ``` 请求命名和冲突检查详见 [`agentcompass launch`](/zh/user_guide/using_agentcompass/cli/launch#映射规则)。 下面的命令使用 `ablation` 区分实验组，并将本次运行固定命名为 `baseline`： ```bash theme={"system"} agentcompass run "$MODEL_NAME" \ --env \ --run-name ablation \ --run-id baseline ``` 在默认结果根目录下，对应路径为： ```text theme={"system"} results/ablation/__/baseline/ ``` 完整目录和文件结构见[理解评测结果](/zh/user_guide/other_features/results/overview)。 ### 继续中断的运行 `--reuse` 用于基于已有运行继续评测。AgentCompass 按任务 ID 复用完整、兼容且不含错误的详情，也可以为未完成的多次尝试任务恢复有效的终态 attempt checkpoint： ```bash theme={"system"} agentcompass run "$MODEL_NAME" \ --env \ --reuse ``` 不传值时，`--reuse` 会选择以下层级中的最新运行： ```text theme={"system"} /[/]__/ ``` 传递运行 ID 可以选择该层级下的确切来源： ```bash theme={"system"} agentcompass run "$MODEL_NAME" \ --env \ --reuse 20260806_120000 ``` `run` 只会在相同结果根目录、可选 run-name 前缀及 Model/Benchmark/Harness 组合目录中查找；`launch` 则在按请求名称划分的输出命名空间中查找。已有目录保持原样，自动复用不会搜索旧 Benchmark/Model 目录层级。 来源运行必须使用受支持的运行 schema、相同的 Benchmark ID 和 attempt 计划。可复用数据按 task ID 与 attempt 序号匹配，不要求请求参数和任务输入完全一致。继续待执行的 fresh 评测时，可以修改评测超时、资源或环境变量。新运行记录来源，并保留复用的详情或 checkpoint；详见[复用校验](/zh/user_guide/other_features/results/run_records#reuse-identity)。 复用按逻辑 attempt 使用当前任务计划判断。完整的 WARNING 结果、当前 pattern 未命中的 ERROR 结果可复用；FATAL 或命中的 ERROR 按当前重试政策处理，使用新 run 的共享预算，历史次数不扣减新预算。零预算不会把失败改成成功。只有评分输入完整的 none/fresh 评测失败可恢复评分；reuse 模式重新执行整个 attempt。 ### 从已保存产物继续评测 推理和必要收集完成且无 FATAL 后，none/fresh 保存 v4 checkpoint，包含已分类推理与输入快照、身份、来源、网络策略和产物完整性。允许具有完整输入的 ERROR 结果恢复；fresh 恢复产物，none 校验声明的本地输入路径与摘要。传输不完整或包含不可序列化运行对象时不恢复。 | 源状态 | 默认 `--reuse` 行为 | | - | - | | 完整结果，无 FATAL 且 ERROR 未命中 | 复用结果与有效得分。 | | 评测需重试，none/fresh 快照完整 | 使用当前预算恢复评分输入；fresh 新建 verifier。 | | 输入不完整、checkpoint 不支持或 reuse 模式 | 调度必要的 attempt 执行。 | | 多 attempt 任务被中断 | 保留可复用终态，只恢复待完成工作。 | 新 run 复制已校验的 checkpoint 和采集产物。恢复时校验 task/attempt 身份、来源兼容性、网络策略与输入完整性，使用当前计划及保存输入的新副本。driver 文件依赖必须仍存在且摘要一致；恢复不重建运行中的进程或旧 sandbox。 要关闭待执行任务的自动 checkpoint 恢复，在 `agentcompass run` 中添加 `--no-checkpoint-resume`，在 Python SDK 中传入 `checkpoint_resume=False`，或配置： ```yaml theme={"system"} runtime: checkpoint_resume: false ``` 多请求编排可设置 `defaults.runtime.checkpoint_resume` 或 `requests[].runtime.checkpoint_resume`，有效默认值为 `true`。此选项不会强制重新评测已完成结果，不会关闭终态 attempt 的调度 checkpoint，也不会阻止保存新的 checkpoint。 ## 保留 Environment 以便调试 当失败需要直接检查任务或验证器 sandbox 时，添加 `--keep-environment`： ```bash theme={"system"} agentcompass run "$MODEL_NAME" \ --env \ --keep-environment ``` AgentCompass 将跳过对本次运行所创建 Environment 的 provider 清理。重试和多任务运行可能留下多个资源，之后需要使用 provider 工具手动释放；Harness 会话仍会正常关闭。 ## 日志与进度 | 参数 | 默认值 | 可选值 | 作用 | | - | - | - | - | | `--progress ` | `auto` | `auto`、`plain`、`none` | 控制终端进度显示：`auto` 仅在交互式终端中显示动态进度，`plain` 输出适合 CI 或重定向日志的文本进度，`none` 不显示终端进度。 | | `--log-level ` | `INFO` | `DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL` | 设置控制台的最低日志级别。 | | `--file-log-level ` | `DEBUG` | `DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL` | 设置保存到结果目录的运行日志最低级别。 | `--progress` 只控制终端显示；无论选择哪种模式，AgentCompass 都会照常保存进度、日志和任务结果。保存位置见[结果](/zh/user_guide/other_features/results/overview#目录布局)。 ## 环境变量作用域 所有变量作用域统一通过 `--env-params` 配置（SDK 使用 `environment_params`，YAML 放在 `environments` 下所选 provider 中）。`env_variables` 提供公共启动/命令变量，`run_env_variables` 用于 agent 安装/执行，`evaluation_env_variables` 用于评测命令。`evaluation_environment_env_variables` 独立覆盖 fresh verifier 启动变量，要求 fresh 模式；旧 Harness `env` 输入会报错。 ```bash theme={"system"} agentcompass run "$MODEL_NAME" \ --env docker \ --env-params '{"evaluation_environment_mode":"fresh","env_variables":{"LANG":"C.UTF-8"},"run_env_variables":{"AGENT_MODE":"test"},"evaluation_environment_env_variables":{"VERIFIER_MODE":"offline"},"evaluation_env_variables":{"GRADER_KEY":"${GRADER_KEY}"}}' ``` 原 `execution.download_artifacts` 配置项已替换为 `execution.save_artifacts`；旧配置键会被拒绝。 ## 错误处理与计分有效性 `RunResult.issues` 是唯一的执行错误契约。每条问题包含 `severity`（`fatal`、`error`、`warning`）、`phase`（`setup`、`run`、`collect`、`evaluate`、`cleanup`）、稳定的 `code` 和脱敏 `message`。`RunResult.error` 已移除；完整脱敏 traceback 与异常链保存在 `artifacts.execution_diagnostics`。 FATAL 表示准备、Environment、外部工具服务、模型鉴权／配额／服务端或 Judge 故障。Judge 超时、无效 JSON 和缺少必需评分字段同样是 FATAL。模型 API 或 Harness 超时、模型无有效输出属于 ERROR。模型交付缺失、普通 verifier reward 文件缺失或解析失败、清理失败属于 WARNING；已有明确受信准备失败证据时，即使没有 reward 仍保留 FATAL。 ERROR 不覆盖 Benchmark 的有效得分。普通 verifier reward 异常仍按有效 fail／0 观察处理；上述 Judge 协议错误是 FATAL 例外。runtime 不会仅根据 status 为缺失观察补零。 `execution.max_retries` 默认 **0**，是每个逻辑 attempt 各阶段共享的额外重试预算。FATAL 有预算必重试；ERROR 仅在配置的正则匹配其 `message` 或 `code` 时重试；WARNING 不触发重试。`null` 和 `[]` 均表示只重试 FATAL。需要容忍瞬时服务故障时可设 `execution.max_retries=2`；零预算下，一次未解决的 FATAL 就会使 run 失败。pattern 不再匹配完整 traceback、拼接的多条 issue 或脱敏凭证，旧配置应迁移到稳定 code 或保留的诊断特征。 预算与 pattern 均取自当前任务解析后的 plan。`none` 和 `fresh` 只重试评测，并使用隔离的推理快照；`fresh` 每轮新建评测 Environment。`reuse` 重跑整个 attempt。跨 run 恢复使用新预算，旧次数只保留为历史。重试已解决的问题留在历史中，不进入最终 issues。 任一逻辑 attempt 最终仍有 FATAL，该题所有指标失效，即使另一个 attempt 成功也不能计分。`MetricReport.evaluation_failed` 为 true，所有正式 `value` 为 null，可用值写入明确标注的 `reference_value`。参考分从分子、分母和权重中排除整道失效题；没有有效题时两者都为 null。run 状态为 `failed`，CLI 非零退出，SDK 失败消息包含结果路径；编排中的其他请求继续执行。 计数满足 `evaluated + unavailable + invalidated = total`；`error` 是独立诊断计数。attempt coverage 对包含最终 ERROR／FATAL 的逻辑 attempt 去重计数，WARNING 和已解决的重试历史不计入。合法 `pass@k` 提前停止不算缺失 attempt。 当前 task 和 run-info schema 为 v3，evaluation checkpoint 为 v4，保存已分类的推理与准备输入快照、网络策略和产物完整性信息。旧 v2 结果只在读取边界依据可靠结构化证据转换；仅自由文本的旧失败保持历史分类未知，进入新计分前需重新执行，仍可作为历史结果浏览。旧 checkpoint 缺少已分类快照时，跨 run 复制会给出原因并恢复正常执行。新格式缺少 `issues` 或仍有结果级 `error` 都是格式错误。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.