> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 任务结果

`details/` 下的每个 JSON 文件记录一个 Benchmark 任务的结果，本文称为“任务详情文件”。其中包含最终答案、评分、轨迹、错误以及该任务的多次评测尝试。如果触发 runtime 重试，本次被丢弃的执行结果还会单独写入 `retry_details/`，用于确认重试原因。

阅读这些文件前，需要区分两个概念：

* `attempt` 是一次独立的评测尝试，数量由 `k` 控制，并计入最终任务结果。
* `retry` 是同一次评测尝试发生可恢复错误后的重新执行，不会新增 `attempt`，也不直接参与 Benchmark 指标计算。

`k` 和 `avgk` 的配置与聚合方式见 [Benchmark 共享字段](/zh/user_guide/modules/benchmarks/overview#共享-benchmark-字段)。

| 文件                                           | 何时生成                       | 保存内容                                      |
| -------------------------------------------- | -------------------------- | ----------------------------------------- |
| `details/<task-id>[_<category>].json`        | 任务已经形成详情，且没有执行或评分错误        | 最终答案、评分、轨迹和各次评测尝试。答案错误或任务被跳过时也可能使用这个文件名。  |
| `details/_error_<task-id>[_<category>].json` | 至少一次已记录的评测尝试出现执行或评分错误      | 与普通详情相同的任务信息；`_error_` 前缀用于提示其中包含错误。      |
| `retry_details/*.json`                       | runtime 判断当前错误可以重试，且仍有重试次数 | 本次被丢弃的结果和触发重试的错误。文件名还会记录评测尝试编号、重试编号和失败阶段。 |

只有任务带有类别时，文件名才会包含 `category`。任务 ID、类别和阶段名称中的 `/` 与 `:` 会替换为 `_`。常规运行将多次评测尝试写入同一个详情文件的 `attempts`。

<Warning>
  文件名只会执行上述替换，并不会进行完整的路径安全处理。自定义组件应生成可信且稳定的任务 ID、类别和阶段名称，不要包含反斜杠、控制字符或目录片段。还应确保 `task_id` 与 `category` 的组合在替换 `/`、`:` 后仍然唯一，否则不同任务可能写入同一路径。
</Warning>

## 任务详情文件

普通详情与 `_error_` 详情使用相同的 JSON 结构。顶层字段描述整个任务，`attempts` 则保存每次评测尝试的具体结果。字段内容取决于所选 Benchmark、Harness 和分析器，因此部分值可以为 `null`，可选字段也可能不出现。

如果任务在形成可保存的结果前就已失败，可能不会生成对应的任务详情文件。不过，评测结束时的首次汇总使用本次运行收集到的结果，因此仍可能将该任务计为错误。首次汇总与重新汇总的区别见[汇总与分析结果](/zh/user_guide/other_features/results/summary_analysis#summarymd)。

```json theme={"system"}
{
  "task_id": "<task-id>",
  "category": "<category>",
  "correct": true,
  "solved_at": 1,
  "attempts_tried": 1,
  "k": 1,
  "retry_count": 2,
  "retry_counts": {
    "1": 2
  },
  "attempts": {
    "1": {
      "correct": true,
      "final_answer": "<answer>",
      "ground_truth": "<reference-answer>",
      "trajectory": {},
      "status": "completed",
      "score": 1.0,
      "error": "",
      "artifacts": {},
      "extra": {},
      "analysis_result": {},
      "meta": {
        "resolved_execution_plan": {}
      }
    }
  }
}
```

### 任务级字段

| 字段               | 含义                                                                                                                      |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `task_id`        | Benchmark 提供的任务标识。AgentCompass 使用它识别汇总与复用中的任务。                                                                          |
| `category`       | Benchmark 提供的可选任务类别。常规 runtime 对无类别任务写入空字符串；兼容的外部或旧结果也可能省略该字段或写为 `null`。                                                |
| `correct`        | 是否至少有一次已记录的评测尝试通过评分或验证。使用非空 `avgk_value` 时不写入该字段。                                                                       |
| `solved_at`      | 第一次通过评分或验证的评测尝试编号，从 `1` 开始；没有尝试通过时为 `null`。使用非空 `avgk_value` 时不写入该字段。                                                   |
| `attempts_tried` | 实际记录到 `attempts` 的评测尝试数。未启用 `avgk` 时，首次成功后可以提前停止，因此该值可能小于 `k`。                                                          |
| `k`              | 该任务允许执行的最大评测尝试数。                                                                                                        |
| `max_score`      | 上游适配器提供的可选任务满分；未提供时不出现。                                                                                                 |
| `avgk_value`     | 可选的预计算任务级 `avg@k` 值，主要用于兼容外部生成的结果。该值非空时，顶层不再使用 `correct` 和 `solved_at`，汇总也会优先读取它。常规运行不写入该字段，而是根据 `attempts` 计算 `avg@k`。 |
| `retry_count`    | 所有评测尝试中实际触发的 runtime 重试总数。                                                                                              |
| `retry_counts`   | 各评测尝试触发的重试次数，键为字符串形式的评测尝试编号。该映射是稀疏的，没有触发重试的尝试不写入键。                                                                      |
| `attempts`       | 按字符串编号保存的评测尝试映射，例如 `"1"`、`"2"`。每个值使用下表中的尝试级结构。                                                                          |

任务详情没有顶层 `status` 或 `score`；执行状态和得分分别记录在每次评测尝试中。评测结束时生成的首次汇总使用当前运行收集的结果；之后单独执行 `agentcompass summary`，则会读取已保存的详情文件并重新计算。

### 尝试级字段

排查单次评测尝试时，可以先查看 `status` 和 `error` 判断执行是否有效，再通过 `correct` 和 `score` 确认评分结果。`trajectory`、`artifacts`、`extra` 和 `meta` 提供进一步的过程与诊断信息。

| 字段                | 含义                                                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `correct`         | 本次评测尝试是否通过 Benchmark 的评分或验证。                                                                                          |
| `final_answer`    | model 或 agent 生成的最终答案，可以是文本、补丁，也可以是 Benchmark 定义的结构化 JSON。                                                            |
| `ground_truth`    | Benchmark 提供的参考答案。使用隐藏验证器的任务可以为 `null`。                                                                               |
| `trajectory`      | Harness 按 AgentCompass 标准轨迹结构生成的记录；没有轨迹时为 `null`。具体结构见[轨迹字段](#轨迹字段)。                                                  |
| `status`          | 本次评测尝试的执行状态，取值见[状态值](#状态值)。                                                                                           |
| `score`           | 本次评测尝试的 Benchmark 得分；只提供通过/不通过结果时可以为 `null`。                                                                          |
| `max_score`       | 本次评测尝试的可选满分；未提供时不出现。                                                                                                  |
| `error`           | 执行或评分阶段产生的错误。通常为空字符串或 `null`；失败时可以包含堆栈信息。                                                                             |
| `artifacts`       | Benchmark 或 Harness 收集的附加产物内容或索引，结构由具体集成定义。                                                                           |
| `extra`           | Benchmark 或 Harness 写入的附加结构化信息，字段不保证跨 Benchmark 一致。                                                                   |
| `analysis_result` | 随评测执行的分析器输出，按分析器系列保存。具体结构见[分析结果](#分析结果)。                                                                              |
| `meta`            | runtime 或具体集成写入的补充信息。除 `resolved_execution_plan` 外，还可能包含 `plan`、`extra`、`harness_metrics`、`status`、`scoring` 等组件专属字段。 |

不要将 Harness 的内部 `metrics` 视为稳定的尝试级字段。Benchmark 或 Harness 如需保留集成专属指标，通常会将其写入 `meta.harness_metrics`、`extra` 或 `artifacts`。`meta.resolved_execution_plan` 只是一份精简摘要，`meta` 中的其他组件字段可能包含更完整的配置或诊断信息。

### 状态值

| `status`                  | 含义                       |
| ------------------------- | ------------------------ |
| `completed`               | 执行和评分已产生有效结果，不表示答案一定正确。  |
| `run_error`               | 任务执行阶段失败。                |
| `eval_error`              | 评分或验证阶段失败。               |
| `run_error_or_eval_error` | 任务执行和评分均失败，或无法只归入其中一个阶段。 |
| `skipped`                 | 本次评测尝试被跳过。               |

### 轨迹字段

`ACTF_v1.0` 是 AgentCompass 自定义的轨迹结构版本，用于统一表示不同 Harness 产生的 agent 执行记录。它不是 model provider 或第三方 agent 框架定义的协议。

`trajectory` 使用该结构按执行顺序记录 model 输入与输出、工具调用、Environment 观察结果、耗时和 token 统计。各字段是否有值取决于 Harness；Harness 不生成轨迹时，`trajectory` 为 `null`。

| 字段               | 含义                                      |
| ---------------- | --------------------------------------- |
| `schema_version` | AgentCompass 轨迹结构版本，当前默认值为 `ACTF_v1.0`。 |
| `steps`          | 交互步骤数组，顺序即执行顺序。                         |
| `started_at`     | 整条轨迹的开始时间。                              |
| `finished_at`    | 整条轨迹的结束时间。                              |

每个 `steps[]` 元素包含：

| 字段                                    | 含义                            |
| ------------------------------------- | ----------------------------- |
| `step_id`                             | 轨迹内的步骤编号。                     |
| `system_prompt`                       | 该步骤使用的 system prompt。         |
| `user_content`                        | 发送给 model 的用户内容或后续输入。         |
| `tools`                               | 该步骤记录的工具信息；具体内容由 Harness 决定。  |
| `assistant_content.content`           | assistant 在该步骤生成的可见内容。        |
| `assistant_content.reasoning_content` | Harness 提供的可选推理内容。            |
| `assistant_content.tool_calls`        | assistant 在该步骤发起的工具调用。        |
| `observation`                         | 工具或 Environment 操作返回的观察结果。    |
| `metric.prompt_tokens_len`            | 该步骤的输入 token 数；无法统计时为 `null`。 |
| `metric.completion_tokens_len`        | 该步骤的输出 token 数；无法统计时为 `null`。 |
| `metric.llm_infer_ms`                 | model 推理耗时，单位为毫秒。             |
| `metric.env_action_ms`                | Environment 操作耗时，单位为毫秒。       |
| `metric.stop_reason`                  | 本次 model 响应停止的原因。             |
| `started_at`                          | 该步骤的开始时间。                     |
| `finished_at`                         | 该步骤的结束时间。                     |

### 解析后执行计划

`attempts.<N>.meta.resolved_execution_plan` 记录本次评测尝试解析得到的 Environment、网络策略和 [Recipe](/zh/user_guide/other_features/recipes)。这份摘要在打开 Environment 前生成，因此只能说明计划已经解析，不能证明 Environment 创建成功，也不会包含 Environment 的完整配置。

| 字段                        | 含义                                                                                             |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| `environment`             | 计划用于执行任务的 Environment。包含 `id`，以及启动 Environment、准备 Benchmark 和准备 Harness 时使用的 `network_policy`。 |
| `evaluation_environment`  | 计划单独用于评分的 Environment。包含 `id` 和创建该 Environment 时使用的 `network_policy`；未配置时可以为 `null`。           |
| `run_network_policy`      | Harness 或 Benchmark 执行 model 与工具操作时使用的网络策略。                                                    |
| `verifier_network_policy` | Benchmark 评分或验证阶段使用的网络策略。                                                                      |
| `applied_recipes`         | 本次任务实际应用的 Recipe ID 列表。                                                                        |

上述 `network_policy` 对象包含 `network_mode` 和 `allowed_hosts`：`network_mode` 表示网络模式，`allowed_hosts` 列出允许访问的 host。各项策略的含义见[网络策略](/zh/user_guide/modules/environments/configuration/network)。

### 分析结果

启用 [`agentcompass analysis`](/zh/user_guide/using_agentcompass/cli/analysis#随评测运行) 后，`analysis_result` 会按分析器系列保存每次评测尝试的分析结果。分析成功时可以包含下列字段；分析失败时可能只写入其中一部分：

| 字段           | 含义                                                  |
| ------------ | --------------------------------------------------- |
| `is_badcase` | 分析器是否将本次结果判定为异常样本（bad case）；只生成统计信息的分析器可以返回 `null`。 |
| `details`    | 分析器生成的结构化说明对象；没有附加说明时通常为空对象。                        |
| `score`      | 分析器提供的可选分数。                                         |
| `error`      | 分析器自身的错误信息；没有错误时通常不出现。                              |
| `extra`      | 分析器提供的可选附加数据。                                       |

如果某个已选分析器在执行 `analysis()` 时抛错，对应系列通常会写入 `is_badcase: false` 和 `error`，但省略 `details`。该错误不会覆盖 Benchmark 已经产生的 `status`、`correct` 或 `score`。如果错误发生在分析器创建、匹配或前置条件检查阶段，该系列可能不会出现在 `analysis_result` 中；此时可通过日志确认原因。

## 错误详情文件

`_error_` 前缀用于标记包含执行或评分错误的任务详情。只要任一已记录的评测尝试满足以下条件，就会使用该前缀：

* `status` 为 `run_error`、`eval_error` 或 `run_error_or_eval_error`；
* `error` 字段非空。

为兼容不同集成提供的结果结构，`meta.status` 为 `error` 时也会使用该前缀。

`_error_` 不表示答案错误，而表示任务详情中存在执行或评分错误，因此该文件不能用于复用。如果多次评测尝试中同时存在 `completed` 和错误状态，只要有一次满足上述条件，整个任务详情仍使用 `_error_` 前缀。对于 `status` 为 `completed`、`correct` 为 `false` 的任务，则使用普通详情文件名。

使用 [`--reuse`](/zh/user_guide/using_agentcompass/run_controls#继续中断的运行) 时，AgentCompass 只复用普通详情。只有 `_error_` 详情的任务会在新运行中重新执行，来源运行不会被修改。如果目标目录随后成功写入该任务的普通详情，对应的旧错误详情会被移除。

## 重试详情文件

只有错误匹配重试规则并且仍有重试额度时，runtime 才会重新执行并写入重试详情。因此，没有重试详情并不代表任务没有失败：未触发重试的最终失败通常保存在 `_error_` 任务详情中；如果失败时还没有形成可保存的结果，也可能没有任何详情文件。重试规则和额度见[只重试瞬时失败](/zh/user_guide/using_agentcompass/run_controls#只重试瞬时失败)。

```json theme={"system"}
{
  "schema_version": "agentcompass.retry.v1",
  "task_id": "<task-id>",
  "category": "<category>",
  "attempt": 1,
  "retry": 1,
  "max_retries": 2,
  "stage": "evaluate",
  "scope": "evaluate",
  "matched_pattern": "<matched-regex>",
  "error": "<error-message>",
  "discarded_result": {}
}
```

| 字段                 | 含义                                                                        |
| ------------------ | ------------------------------------------------------------------------- |
| `schema_version`   | 重试详情结构版本，当前值为 `agentcompass.retry.v1`。                                    |
| `task_id`          | 发生重试的 Benchmark 任务 ID。                                                    |
| `category`         | 任务的可选类别。                                                                  |
| `attempt`          | 重试所属的评测尝试编号，从 `1` 开始。                                                     |
| `retry`            | 当前评测尝试内的重试编号，从 `1` 开始；进入下一次评测尝试后重新计数。                                     |
| `max_retries`      | 每次评测尝试可使用的最大 runtime 重试次数。                                                |
| `stage`            | 触发重试时所在的生命周期阶段，常见值见下表。                                                    |
| `scope`            | 重试重新执行的范围，取值为 `attempt` 或 `evaluate`。                                     |
| `matched_pattern`  | 与错误文本匹配的第一条正则表达式。未配置重试表达式时，任意非空错误均可匹配，并记录为 `<default:any-error>`。         |
| `error`            | 触发重试的错误文本；异常场景通常包含堆栈信息。                                                   |
| `discarded_result` | 本次重试丢弃的结果快照，并附带 `meta.resolved_execution_plan`。尚未产生结果时，runtime 会构造一份错误结果。 |

`discarded_result` 只用于排障，会尽量保留被丢弃结果中的信息，因此字段可能多于 `details/*.json` 中的评测尝试。它通常包含上文已经说明的 `status`、`correct`、`score`、`final_answer`、`ground_truth`、`trajectory`、`error`、`artifacts`、`extra` 和 `meta`，还可能包含以下字段：

| 字段         | 含义                                                 |
| ---------- | -------------------------------------------------- |
| `task_id`  | 被丢弃结果对应的任务 ID。                                     |
| `category` | 被丢弃结果对应的可选任务类别。                                    |
| `metrics`  | Harness 返回的原始指标映射，仅供诊断；它不是普通任务详情中的稳定字段。            |
| 其他字段       | Benchmark 或 Harness 返回字典结果时可以保留自身的附加字段，其结构由对应集成定义。 |

查看 `scope` 可以判断重试会重新执行哪些工作：

| `scope`    | 行为                    |
| ---------- | --------------------- |
| `attempt`  | 重新开始当前整次评测尝试。         |
| `evaluate` | 仅重新执行评分或验证阶段，不新增评测尝试。 |

查看 `stage` 可以定位最先失败的阶段：

| `stage`                | 阶段                            |
| ---------------------- | ----------------------------- |
| `plan`                 | 尚未进入更具体的任务阶段。                 |
| `open_environment`     | 创建任务执行 Environment。           |
| `prepare_task`         | 准备 Benchmark 输入和工作区。          |
| `run_task`             | 运行不使用 Harness 的 Benchmark 任务。 |
| `start_harness`        | 启动 Harness 会话。                |
| `run_harness`          | 通过 Harness 执行任务。              |
| `collect_artifacts`    | 收集任务产物。                       |
| `evaluate_environment` | 创建单独的评分 Environment。          |
| `evaluate`             | 执行评分或验证。                      |
| `attempt`              | 无法归入更具体阶段时使用的兜底值。             |

## 处理敏感内容

写入任务详情和重试详情前，AgentCompass 会递归脱敏能够识别的凭据字段。但答案、prompt、观察结果、错误堆栈和集成附加数据仍可能包含任务内容或其他敏感文本。请像保护日志一样保护这些文件，并在公开运行目录前检查其中的内容。

`details/*.json` 会用于汇总，普通详情还可用于复用；`retry_details/*.json` 只用于排障。需要修正评测配置或结果时，请重新运行任务，不要直接修改这些文件。

## 相关页面

* [结果概览](/zh/user_guide/other_features/results)
* [运行信息与排障](/zh/user_guide/other_features/results/run_records)
* [汇总与分析结果](/zh/user_guide/other_features/results/summary_analysis)
* [运行控制](/zh/user_guide/using_agentcompass/run_controls)
* [`agentcompass analysis`](/zh/user_guide/using_agentcompass/cli/analysis)
* [网络策略](/zh/user_guide/modules/environments/configuration/network)