> ## 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.

# 评测故障排查

缩小失败范围、定位生命周期阶段、检查证据并采取正确的修复措施。

排查 AgentCompass 失败时，应先将问题缩小到一个任务，并识别最先失败的生命周期阶段。不要一次修改多个限制或组件，否则可能掩盖根因，也会让恢复后的结果无法与预期评测直接比较。

## 从最小复现开始

保持与失败运行相同的 Model、Benchmark、Harness、Environment 和组件参数，但只选择一个失败任务、关闭重试并保留详细日志：

```bash theme={"system"}
export MODEL_NAME=""

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env <environment> \
  --benchmark-params '{"sample_ids":["<failed-task-id>"]}' \
  --task-concurrency 1 \
  --max-retries 0 \
  --log-level INFO \
  --file-log-level DEBUG
```

只有需要检查 sandbox 内文件或进程时才添加 `--keep-environment`。确认实际问题是缺少可选依赖前，不要启用自动依赖安装。

## 定位最先失败的阶段

在持久化运行日志中搜索任务 ID 和最后一个已启动阶段。正常顺序如下：

| 阶段或日志                     | 失败归属                                         |
| ------------------------- | -------------------------------------------- |
| 任务加载或选择                   | Benchmark 参数、数据集访问、缓存或可选 Benchmark 依赖        |
| `Execution plan building` | Benchmark/Harness/Environment 兼容性或 Recipe 输入 |
| Environment 准备            | provider 凭证、镜像、快照、配额、资源请求、网络初始化或启动超时         |
| 材料准备                      | Benchmark 工作区布局、输入文件或任务元数据                   |
| Harness 准备                | Harness 依赖、可执行文件安装、凭证或准备网络访问                 |
| `run_harness` / 推理        | model 端点、agent 循环、工具执行、运行网络策略或 Harness 超时    |
| 产物收集                      | 预期输出路径、文件下载或工作区权限                            |
| 评测 / 验证                   | 测试、验证器依赖、验证器超时、评委 model 或 evaluation 网络策略    |
| 分析                        | 分析器依赖、分析器 model 或可选后处理；已测量任务结果可能仍可使用         |

最先出现的失败通常比后续清理警告更有价值。例如，model 身份验证错误之后出现的 Environment 关闭警告并不是根因。

## 检查运行证据

运行目录包含不同层次的证据：

| 产物                                                                                           | 检查内容                                               |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [`run_info.json`](/zh/user_guide/other_features/results/run_records)                         | 脱敏后的运行请求、复用来源、运行终态，以及按任务和尝试保存的执行计划摘要               |
| [`params.json`](/zh/user_guide/other_features/results/run_records)                           | 用于持久化和恢复摘要的 Benchmark、model 与输出标识子集                |
| [`logs/*.log`](/zh/user_guide/other_features/results/run_records)                            | 达到文件日志级别的阶段消息、错误和堆栈跟踪；具体命令或 provider 响应只在组件主动记录时出现 |
| [`progress.jsonl`](/zh/user_guide/other_features/results/run_records)                        | 有序任务和阶段事件，包括重试与复用事件                                |
| [`progress.json`](/zh/user_guide/other_features/results/run_records)                         | 当前汇总计数和最新运行状态                                      |
| [`details/<task-id>.json`](/zh/user_guide/other_features/results/task_results)               | 尝试、解析后执行计划、预测、轨迹、指标、验证结果和分析器输出                     |
| [`details/_error_<task-id>.json`](/zh/user_guide/other_features/results/task_results#错误详情文件) | 至少包含一次无效执行、因而不会被复用的任务结果                            |
| [`retry_details/*.json`](/zh/user_guide/other_features/results/task_results#重试详情文件)          | 重试被消耗的原因和被丢弃的结果                                    |
| [`summary.md`](/zh/user_guide/other_features/results/summary_analysis)                       | 运行级计数和 Benchmark 聚合指标；运行终态应查看 `run_info.json`      |

请直接检查对应文件。请求他人复现问题时，应保留 `run_info.json`、`params.json`、相关详情文件和日志。

## 常见失败

| 现象                                        | 可能原因                                     | 正确处理方式                                                         |
| ----------------------------------------- | ---------------------------------------- | -------------------------------------------------------------- |
| `Unused Tokens` 后出现 `command not found`   | 命令续行符 `\` 后存在空格。                         | 删除反斜杠后的全部字符并重新运行。                                              |
| JSON 解析或未知选项错误                            | JSON 参数格式错误，或组件字段被当作顶层 CLI 参数传入。         | 检查引用，并查看 `agentcompass run --help` 和组件结构。                      |
| `OptionalDependencyError`                 | 运行 AgentCompass 的 host Python 缺少声明的可选依赖。 | 执行提示中的 `uv` 或 `pip` 命令；只为可信组件启用自动安装。                           |
| Harness 不支持 Environment 或协议               | 所选组合不兼容。                                 | 使用 Benchmark 推荐 Harness，以及 Harness 页面声明的协议。                    |
| 通用 Daytona 或 Modal sandbox 无法运行 Benchmark | Benchmark 需要预构建任务镜像、快照或工作区布局。            | 让兼容 Recipe 推断，或在自定义运行中有意覆盖镜像/快照。                               |
| Docker 守护进程权限拒绝                           | 当前用户无法访问 `/var/run/docker.sock`。         | 启动 Docker 并配置守护进程权限；适用时使用 provider 的 `use_sudo_docker`。        |
| 镜像拉取或清单文件错误                               | 注册表身份验证、架构或镜像名称错误。                       | 登录注册表、确认镜像，并在需要时设置兼容平台。                                        |
| model 端点返回 `401` / `403`                  | 凭证或端点授权错误。                               | 检查 `MODEL_API_KEY`、基础 URL、model 访问权限和 provider 专属标头。           |
| `404` 或 model 未找到                         | model ID 或端点路径错误。                        | 查询端点 model 列表，并确认基础 URL 是否需要 `/v1`。                            |
| `429`、限流或延迟持续升高                           | model 并发或请求/词元速率超过容量。                    | 降低任务并发数和 Environment 打开 QPS，只重试瞬时响应。                           |
| Jina Reader 返回 `401`、`402`、`403` 或 `429`  | Jina 凭证无效、未授权或配额耗尽。                      | 检查 `JINA_API_KEY` 和配额；搜索 Harness 首个致命状态会记录为 `ERROR`，后续重复项会被抑制。 |
| 普通终端日志中没有某次搜索 `visit` 尝试                  | 每次 Jina 和摘要器重试只记录为 `DEBUG`，只有重试耗尽才警告。    | 查看持久化 DEBUG 日志，再判断工具是否重试。                                      |
| model 请求只在 sandbox 内失败                    | 运行网络允许列表缺少 model 端点。                     | 添加准确的 model 端点 host，或改用本地 Harness 执行模式。                        |
| 隔离模式下 Harness 安装失败                        | 准备网络受限，或镜像中没有 Harness。                   | 保持准备阶段为 `public`、将软件包 host 加入允许列表，或使用预构建镜像。                    |
| agent 命令超时                                | Harness 命令或运行过程限制到期。                     | 确认命令确实仍在推进后，修改对应 Harness 字段。                                   |
| 运行过程完成后验证器超时                              | Benchmark 验证器限制到期。                       | 修改 Benchmark 验证器设置，而不是 Harness 命令超时。                           |
| 仍有任务时整体运行结束                               | `--timeout-seconds` 小于完整运行所需时间。          | 增加整体运行预算或减少任务集。                                                |
| 成本跟踪拒绝未知 model ID                         | Harness 成本数据库未映射自定义 model 名称。            | 只有不需要成本核算时，才使用该 Harness 文档中的忽略错误模式。                            |
| 已完成任务意外重新运行                               | 复用未启用、来源文件缺失或带错误前缀，或任务 id/文件名不匹配。        | 检查复用来源、任务 ID、类别和详情文件名。                                         |
| `launch` 拒绝重复 Benchmark/model 请求的隐式复用     | 多个请求共享结果层级，“最新匹配运行”存在歧义。                 | 为每个受影响请求显式设置 `runtime.reuse_run_id`，或关闭复用。                     |
| 提高日志级别后终端仍很嘈杂                             | 依赖在 AgentCompass 日志记录之前或之外配置了自己的日志记录器。   | 保留文件日志、识别日志记录器名称，并使用集成文档声明的日志详细程度控制项。                          |

## 检查最终配置

当某个值看似未生效时，对比合并后的配置和组件结构：

```bash theme={"system"}
agentcompass config show \
  --benchmark <benchmark> \
  --harness <harness> \
  --env <environment>

agentcompass config docs benchmark <benchmark>
agentcompass config docs harness <harness>
agentcompass config docs env <environment>
```

随后检查每个任务的执行计划摘要。Recipe 在普通配置层之后运行，可以适配镜像、工作区、资源和网络策略；当前结果文件中的摘要记录 Environment、网络策略和已应用的 Recipe，但不包含全部 provider 参数。排查镜像、资源或工作区时，还应结合组件配置和运行日志。

## provider 检查

在调试 AgentCompass 内部实现前，先运行 provider 最小独立检查：

| provider       | 推荐检查                                                           |
| -------------- | -------------------------------------------------------------- |
| Docker         | `docker version`、`docker info` 和 `docker run --rm hello-world` |
| Daytona        | 在 Daytona 控制台检查密钥、目标、配额和失败 sandbox。                            |
| Modal          | 运行 `modal token info`，并在 Modal 控制台检查 AgentCompass 应用和 sandbox。 |
| `host_process` | 检查当前工作目录、可执行文件路径、文件权限和必要本地服务。                                  |

provider 凭证验证成功，并不代表特定镜像或资源请求一定成功。独立检查后仍需保留单任务 AgentCompass 冒烟测试，因为它还会验证 Recipe、工作区、Harness 准备和验证。

## 选择重试、复用或重启

| 场景                                  | 操作                          |
| ----------------------------------- | --------------------------- |
| 设置未变时出现临时 API 或 sandbox 失败          | 使用窄范围重试模式重试任务。              |
| 大规模运行被中断，但已有有效的已完成任务详情              | 手动确认所有测量设置一致后再使用 `--reuse`。 |
| Model、Benchmark、Harness、网络策略或评分设置错误 | 启动新运行，不要合并到旧结果。             |
| 确定性任务失败                             | 除非集成本身损坏，否则保留为测量失败。         |
| 运行后修复了集成缺陷                          | 重新运行受影响任务，并记录代码版本和复用流程。     |

重试和复用语义见[运行控制](/zh/user_guide/using_agentcompass/run_controls)，分阶段网络排查见[网络策略](/zh/user_guide/modules/environments/configuration/network)。

## 提交可复现问题单

提交问题单时请包含：

* AgentCompass 版本和 Python 版本；
* 操作系统和 Environment provider；
* Model 协议、Benchmark、Harness 和任务 ID；
* 已移除密钥的完整命令；
* 相关组件参数，以及是否应用了 Recipe；
* 最先失败的阶段和文件日志中的完整堆栈跟踪；
* 脱敏后的 `run_info.json`、`params.json` 和任务详情；
* 并发为 `1` 且关闭重试后是否仍可复现。

不要上传 API 密钥、provider 令牌、私有基础 URL、代理凭证或专有任务数据。