Terminal-Bench 2.0 提交复盘：从跑分、轨迹清理到 Hugging Face PR

更新时间：2026/04/28
文章定位：一次真实 leaderboard submission 的工程复盘。
提交结果：Wecode GPT-5.5 PR #164

这次提交的对象是：

• Agent：Wecode
• Model：GPT-5.5
• Benchmark：Terminal-Bench 2.0
• Submission path：submissions/terminal-bench/2.0/Wecode__GPT-5.5/
• PR：https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard/discussions/164

最终数据

这次本地 run 的核心统计是：

本地校验结果：

metadata_valid True
job_dirs 1
trial_count 445
unique_tasks 89
min_trials_per_task 5
max_trials_per_task 5
successful_trials 373
missing_required_fields 0
passing_missing_trajectory 0
json_bad 0
reward_hacking_hits 0
errors 0

1. 跑分不是只看一个 mean

最容易先算的是 accuracy：

accuracy = passing_trials / total_trials
         = 373 / 445
         = 0.8382022472
         = 83.8%

但 leaderboard 上通常还会显示一个 ± 误差范围。这里要特别小心：这个 ± 不是方差，也不是标准差本身，而是 95% confidence interval 的 half-width，也就是置信区间半宽度。

这次我按 leaderboard 前端逻辑核对到的计算方式是：

stderr = sqrt(mean(per_task_sample_variance) / total_trials)
ci_half_width = 1.96 * stderr * 100

本次 run：

stderr = 0.0092654059
ci_half_width = 1.96 * 0.0092654059 * 100
              = 1.816
              ≈ ± 1.8

所以数学上它表达的是：如果把这次 benchmark 当作一次抽样估计，leaderboard 用这个半宽度表达 score 的不确定性。它不是“方差”；方差是平方量纲，不能直接拿来写成 ± 1.8%。

2. metadata.yaml 要和真实提交对齐

官方 repo 的 README 要求每个 submission root 下必须有 metadata.yaml。我没有凭感觉写字段，而是对照了现有真实提交，例如：

• Simple-Codex__GPT-5.3-Codex
• grok-cli__grok-4.20-0309-reasoning
• pilot-real__claude-opus-4-6

最终使用的 metadata：

agent_url: https://pixboostai.com/
agent_display_name: "Wecode"
agent_org_display_name: "Gradence"

models:
  - model_name: gpt-5.5
    model_provider: openai
    model_display_name: "GPT-5.5"
    model_org_display_name: "OpenAI"

这里有一个坑：trajectory 里有一个内部字段类似 model_provider: wecode，但 leaderboard metadata 里的 model_provider 是模型提供商，不是 agent wrapper 的名字。所以这里应当填 openai，展示组织填 OpenAI。

3. 最大的目录坑：必须多包一层 job folder

我一开始把文件夹整理成了这样：

Wecode__GPT-5.5/
  metadata.yaml
  config.json
  result.json
  fix-code-vulnerability__qpPHMAd/
    result.json
    agent/
  gcode-to-text__P48eGu2/
  ...

看起来很合理，但不符合官方 importer 的结构。官方 importer 会把 submission root 下“带有 config.json 的目录”识别成 job directory。所以上面的扁平结构会让 445 个 trial 目录都被误识别成 job，然后每个 job 下面又找不到 trial，直接失败。

失败形态大概是：

official_job_dirs_detected 445
official_trial_count 0
official_unique_tasks 0
official_errors 446
jobs_with_no_nested_trials 445

正确结构是：

Wecode__GPT-5.5/
  metadata.yaml
  wecode-tb2-4-26-5/
    config.json
    result.json
    fix-code-vulnerability__qpPHMAd/
      result.json
      agent/
        trajectory.json
    gcode-to-text__P48eGu2/
    ...

整理后再跑校验，就变成：

job_dirs 1 ['wecode-tb2-4-26-5']
trial_count 445
unique_tasks 89
min_trials_per_task 5
max_trials_per_task 5
errors 0

工程经验：不要只看目录“人眼合理不合理”，要按 importer 的实际函数理解它怎么发现 job 和 trial。

4. trajectory 不能随便删

Terminal-Bench 的 leaderboard integrity update 强调了 trajectory 的重要性。尤其是 passing trials，trajectory 是审计 agent 行为的重要证据。

这次本地有：

trajectory_count 445
passing 373
passing_missing_trajectory 0

所以这里的原则是：

• 不要为了“瘦身”删除 passing trial 的 `agent/trajectory.json`。
• 如果要处理敏感内容，应做字段级清理，并保证 JSON 仍然可解析。
• 清理后重新检查所有 passing trial 是否仍然有 trajectory。

这次 trajectory 是 ATIF-v1.6。清理 system prompt 时，我保留了 trajectory 文件本身，只移除 system/base prompt 内容。

5. system prompt 清理：别留 redaction 文案

这次我先扫描了所有 agent/trajectory.json，清理内容包括：

• 显式 system_prompt 字段
• base_instructions_present: true
• 嵌在 JSON 字符串里的 system_prompt
• 残留的 AGENTS.md instructions / <INSTRUCTIONS>

第一轮清理后，我曾经把残留字段替换成：

[REDACTED: base/system instructions removed]

后来发现这不是最干净的做法。最终改成空字符串 ""，避免在提交内容中出现新的解释性文本。

最终扫描结果：

redaction_marker 0
system_prompt 0
AGENTS_INSTRUCTIONS 0
base_instr_true 0
json_bad 0
passing_missing_trajectory 0

这个步骤的 knowhow 是：清理敏感字段时，不能只 grep 一次。因为 system prompt 可能出现在结构化字段、嵌套对象、甚至 JSON-ish 字符串里。最好做结构化 JSON traversal，再做全文关键字扫描。

6. reward-hacking 字符串扫描

官方 importer 会扫描 agent/* 文件里是否出现某些敏感字符串，例如和 benchmark/repo/站点直接相关的内容。这类检测是为了防止 agent 在任务中访问 benchmark 网站、题库或公开答案。

本次本地扫描结果：

reward_hacking_hits 0

我的建议是提交前至少扫这几类：

harborframework
harbor-framework
laude-institute
tbench.ai

注意，这不是为了“绕过检测”，而是为了确认 agent 轨迹中没有违规访问 benchmark 资源的证据。

7. 上传前清理无关文件

macOS 会产生 .DS_Store。这类文件对 benchmark 没有任何价值，提交前应该删掉。

本次上传前发现两个：

Wecode__GPT-5.5/.DS_Store
Wecode__GPT-5.5/wecode-tb2-4-26-5/adaptive-rejection-sampler__d5SfNmE/.DS_Store

删除后再确认：

ds_store_files 0

这是小事，但这种小事会影响 reviewer 对提交质量的判断。

8. 用 PR 提交，而不是直接推 main

官方 README 写得很清楚：fork / branch / PR。使用 Hugging Face CLI 时，可以用 --create-pr：

hf upload harborframework/terminal-bench-2-leaderboard \
  /Users/jakefan/Wecode__GPT-5.5 \
  submissions/terminal-bench/2.0/Wecode__GPT-5.5 \
  --repo-type dataset \
  --create-pr \
  --commit-message "Add Wecode GPT-5.5 Terminal-Bench 2.0 submission"

本次生成的 PR：

https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard/discussions/164

上传后我又做了远端抽查，确认这些关键文件都返回 HTTP 200：

• metadata.yaml
• wecode-tb2-4-26-5/config.json
• wecode-tb2-4-26-5/result.json
• wecode-tb2-4-26-5/fix-code-vulnerability__qpPHMAd/result.json
• wecode-tb2-4-26-5/fix-code-vulnerability__qpPHMAd/agent/trajectory.json

上传日志里出现了：

Skipped 446 file(s) in commit (ignored by gitignore file).

这类日志不能直接忽略。至少要抽查远端关键文件，确认 result.json、config.json、trajectory.json 这些提交必要文件没有被过滤掉。

9. 我会沉淀成固定 checklist 的部分

10. 最后一点：benchmark 提交也是工程任务

这次最明显的感受是：benchmark submission 不是“把结果文件传上去”这么简单。

它更像一个小型 release：

• 数据要可复算
• 目录要符合 importer
• metadata 要和实际 agent / model 对齐
• trajectory 要保留审计价值
• 敏感字段要清理干净
• 远端 PR 要能被官方 bot 复现验证

如果没有这些工程动作，一个 83.8% 的结果也只是本地文件夹里的数字。只有当它能被官方 pipeline 接收、验证、审计，才算真正进入 leaderboard 的提交流程。

参考链接

• Terminal-Bench 2.0 leaderboard：https://www.tbench.ai/leaderboard/terminal-bench/2.0
• 官方 submission repo：https://huggingface.co/datasets/harborframework/terminal-bench-2-leaderboard
• 官方 submission 目录：submissions/terminal-bench/2.0
• 本次 Wecode GPT-5.5 PR：PR #164
• Leaderboard integrity update：https://www.tbench.ai/news/leaderboard-integrity-update