评测故障排查

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

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

​

从最小复现开始

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

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 或验证器网络策略
分析	分析器依赖、分析器 model 或可选后处理；已测量任务结果可能仍可使用

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

​

检查运行证据

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

产物	检查内容
run_info.json	脱敏后的运行请求、复用来源、运行终态，以及按任务和尝试保存的执行计划摘要
params.json	用于持久化和恢复摘要的 Benchmark、model 与输出标识子集
logs/*.log	达到文件日志级别的阶段消息、错误和堆栈跟踪；具体命令或 provider 响应只在组件主动记录时出现
progress.jsonl	有序任务和阶段事件，包括重试与复用事件
progress.json	当前汇总计数和最新运行状态
details/<task-id>.json	尝试、解析后执行计划、预测、轨迹、指标、验证结果和分析器输出
details/_error_<task-id>.json	至少包含一次无效执行、因而不会被复用的任务结果
retry_details/*.json	重试被消耗的原因和被丢弃的结果
summary.md	运行级计数和 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 日志记录之前或之外配置了自己的日志记录器。	保留文件日志、识别日志记录器名称，并使用集成文档声明的日志详细程度控制项。

​

检查最终配置

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

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、网络策略或评分设置错误	启动新运行，不要合并到旧结果。
确定性任务失败	除非集成本身损坏，否则保留为测量失败。
运行后修复了集成缺陷	重新运行受影响任务，并记录代码版本和复用流程。

重试和复用语义见运行控制，分阶段网络排查见网络策略。

​

提交可复现问题单

提交问题单时请包含：

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

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