Harbor 评测任务失败时如何区分基础设施故障与模型能力问题？

Harbor 评测任务失败时如何区分基础设施故障与模型能力问题？

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

当你在 Terminal Bench 之类的 Harbor 沙箱基准上跑 Deep Agents 评测时，一次 trial 失败并不能直接说明"模型不行"——沙箱崩溃、OOM 被杀、超时都属于基础设施故障，混进结果里会污染你对模型能力的判断。deepagents 的评测套件（libs/evals）内置了一套失败分类机制：FailureCategory把失败分为capability（模型产出了错误答案或不完整解）与infra_oom、infra_timeout、infra_sandbox三类基础设施故障，另有unknown兜底；scripts/analyze.py会对整个 jobs 目录扫描、逐 trial 分类并打印统计摘要。本文的任务就是：跑完一轮 Harbor 评测后，用这套工具把失败 trial 归好类，决定哪些该重跑、哪些才算真正需要关注的行为回归。

先跑通一轮 Harbor 评测并保留 jobs 目录

失败分类的对象是 Harbor 落盘的 jobs 目录，所以前提是你已经按 Harbor 集成说明 完成配置。在libs/evals/下：

# 安装依赖并配置 API key uv sync export ANTHROPIC_API_KEY="sk-ant-..." # 供 Claude 模型使用 export LANGSMITH_API_KEY="lsv2_..." # 供 LangSmith tracing 使用 export LANGSMITH_TRACING=true # 把当前 checkout 的 Deep Agents 相关包暂存进 .local_deps，供沙箱安装 make stage-harbor-local-deps

之后任选一种方式执行任务，注意保留--jobs-dir指定的目录（下文分析脚本的输入就是它）：

# Makefile 快捷方式：Docker 本地沙箱，串行执行 make run-terminal-bench-docker MODEL=anthropic:claude-opus-4-8 # 或直接调用 harbor，任务写入 harbor-jobs/terminal-bench uv run harbor run \ --agent langgraph \ --agent-kwarg project_path=deepagents_harbor/langgraph_project \ --agent-kwarg config=langgraph.json \ --agent-kwarg graph=dcode \ --agent-env 'ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}' \ --dataset terminal-bench/terminal-bench-2 \ --model "$MODEL" \ -n 1 \ --jobs-dir harbor-jobs/terminal-bench \ --env docker

--env决定沙箱后端：docker（本地容器）、langsmith（带托管 tracing 的 LangSmith 沙箱）、daytona、modal、runloop均可选，Makefile 为每种后端都提供了对应的run-terminal-bench-*目标。$MODEL需替换为你要评测的provider:model规格，与--agent-env传入的 API key 对应。

每个 trial 目录里有哪些判定依据

分析脚本对每个 trial 子目录读取三类文件（见 analyze.py 中analyze_trial的逻辑）：

• agent/trajectory.json— ATIF 格式的完整轨迹，退出码从其中的 observation 结果里提取；
• verifier/reward.txt— 内容为1表示通过；
• exception.txt— 若存在，trial 直接判为 FAILED，其文本内容参与模式匹配。

状态判定规则是：exception.txt存在、或 reward 为 False 即 FAILED；reward 为 True 即 COMPLETED；两者都没有则 PENDING（尚未跑完）。只有 FAILED 的 trial 会被进一步分类。

运行失败分类分析

在libs/evals/下把 jobs 目录传给分析脚本：

uv run python scripts/analyze.py harbor-jobs/terminal-bench --summary-only

--summary-only只打印统计摘要，跳过逐 trial 的 LLM 深度分析，不需要额外的模型调用；如果之后要对个别失败 trial 做轨迹级根因分析，再加上--output-dir <目录>去掉--summary-only，脚本会用 Deep Agent 逐个读取失败轨迹（含任务说明与参考solve.sh对比），把分析报告写成{trial_id}.md落到指定目录，此时需要当前环境已配置可用的模型 API key。

摘要输出里与"基础设施 vs 能力"直接相关的部分形如：

================================================================ FAILURE CLASSIFICATION ================================================================ Infrastructure failures: 2 infra_oom: 1 infra_timeout: 1 Capability failures: 3 Unknown: 0 Success rate (excluding infra failures): ...

（文档示例，具体数值随你的运行结果变化。）每个 FAILED trial 的明细行会带上分类标签，例如✗ FAILED [infra_oom]，并附轨迹路径、reward 文件路径、exception.txt末尾 100 字符片段和工具使用统计，便于你逐个核对分类是否正确。

分类规则：先看退出码，再看异常文本

分类逻辑集中在 failure.py 的classify_failure中，优先级明确：

1. 退出码（最可靠信号）：从轨迹 observation 中提取非零退出码，137（128 + SIGKILL，通常是 Linux OOM killer）判为INFRA_OOM；124（GNU coreutilstimeout约定）判为INFRA_TIMEOUT。注意脚本只解析 observation 结果里的退出码，避免误匹配模型生成的讨论性文本。
2. 异常文本模式匹配（仅限exception.txt）：
   • OOM 特征：oomkilled、out of memory、cannot allocate memory、memory allocation failed、signal 9、sigkill、exit code 137；
   • 超时特征：timed out、deadline exceeded、exit code 124；
   • 沙箱/网络特征：sandbox crashed、sandbox error、connection refused、connection reset、broken pipe、network unreachable、no route to host、exec failed等。 匹配刻意不扫描轨迹内容，防止模型输出里的这些词造成误报。
3. 有异常但没有基础设施特征→UNKNOWN；
4. 无异常、无基础设施退出码→CAPABILITY，即模型答错、解法不完整或逻辑错误。

FailureCategory.is_infrastructure属性把前三类 infra 标记统一区分出来，摘要里 "Success rate (excluding infra failures)" 就是按它算出的、剔除基础设施故障后的成功率。

分类之后的处理路径

• 基础设施故障：重跑或先修复环境，不要把它们报成行为回归。这是 评测工作流说明 给出的明确原则："Interpret a failed Harbor trial before treating it as model evidence... Rerun or repair infrastructure failures rather than reporting them as a behavioral regression." 例如infra_oom提示沙箱内存不够，infra_timeout提示任务超时，infra_sandbox对应沙箱崩溃或网络问题，修复方向各不相同。
• 能力故障：这才是对模型行为的证据。可结合 LangSmith 查看该 trial 的完整轨迹（LLM 调用、工具调用、reward 反馈都在其中），或用上面--output-dir的逐 trial 分析做根因定位；CONTRIBUTING 中还列了常见的能力型失败模式（规划不足、工具误用、缺少增量测试等）供对照。
• unknown：存在异常文本但没有任何可匹配的基础设施特征，需要人工看exception.txt片段再定性。

边界与限制

分类只依据退出码和exception.txt两个来源，如果你的环境里 OOM/超时表现不落到这两处（例如被 Harbor 侧吞掉），该 trial 会归入unknown而不是被误判为能力问题。反过来，capability判定也不等于"模型一定错了"，它只表示没有发现基础设施信号，具体错在哪仍需看轨迹。做跨运行对比时保持模型、SDK 版本与任务配置一致，避免把配置差异误读为能力差异。

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents