读懂 Harbor 前，先背下这 6 个词

很多新人直接读源码，卡在 Trial 和 Agent 分不清------一张图理清谁是哥谁是小弟。

标签：#Harbor #Agent开发 #AI评测 #LLM #TerminalBench

你兴冲冲打开 Harbor 文档，想看看「它到底怎么考我的 agent」。结果第一屏就撞上 Agent、Adapter、Dataset、Trial、Registry、ATIF 排成一排------每个词单看都认识，连起来全懵。

更坑的是，它们长得像亲戚，其实辈分差着代：Trial 和 Agent 不是一回事，Adapter 接的不是 agent，Registry 也不是考场。新人最容易在这里绕晕，然后放弃读源码、转去抄别人的命令。

所以这篇不扯原理、不跑 benchmark，就干一件事：先把这 6 个词钉死 。读完你再看 harbor run 的输出，会像看考场的记分牌一样清楚。

本文概念均对照官方 README 与 RFC（Harbor 当前 v0.16.1，出自 Terminal-Bench 原班作者，是 Terminal-Bench-2.0 的官方 harness）。

为什么要先搞懂这些词（省流版）

评测工具的文档之所以难读，不是因为逻辑复杂，而是它发明了一套「考场黑话」。这 6 个词就是黑话本。搞懂它们，你才能回答三个实际问题：

harbor run 输出里那一堆 trial，到底对应你考了几次？
为什么有的 benchmark 直接能跑、有的要先「接 adapter」？
跑完的轨迹文件，凭什么能被别的工具直接吃？

先把关系图立住，后面每个词都挂得上。

flowchart TB U["你（出题人）"] AG["Agent（考生，你带的）"] DS["Dataset（题库，你带的）"] AD["Adapter（题库的接线员）"] H["Harbor run（编排引擎）"] TR["Trial（一场考试，并行 N 场）"] SB["隔离沙箱（Docker / Modal / Daytona）"] TJ["Trajectory（ATIF 标准录像带）"] RG["Registry（题库出版社加目录）"] AN["analyze 与 view（回放与统计）"] U --> AG U --> DS DS --> AD AD --> H AG --> H H --> TR TR --> SB TR --> TJ TJ --> AN RG --> DS style U fill:#86909c,stroke:#86909c,color:#ffffff style AG fill:#e8ffea,stroke:#00b42a,color:#00875a style DS fill:#fff1f0,stroke:#f53f3f,color:#cf1322 style AD fill:#ffffff,stroke:#86909c,color:#1d2129 style H fill:#1e80ff,stroke:#1e80ff,color:#ffffff style TR fill:#e8f3ff,stroke:#1e80ff,color:#1d2129 style SB fill:#ffffff,stroke:#86909c,color:#1d2129 style TJ fill:#fff7e8,stroke:#ff7d00,color:#d25f00 style RG fill:#f2f3f5,stroke:#86909c,color:#1d2129 style AN fill:#e8ffea,stroke:#00b42a,color:#00875a

你带 Agent 和 Dataset 进来；Adapter 负责把 Dataset 接进 Harbor；harbor run 把每个任务开成一场 Trial，丢进隔离沙箱跑；Trial 跑完产出一份 ATIF 格式的 Trajectory（轨迹）；Registry 管题库的出版和目录；最后 analyze / view 消费这些轨迹。

Agent：考生

定义：被评测 / 优化的任意 AI agent------Claude Code、OpenHands、Codex CLI、Aider、自研都行。
类比：驾照考试里的考生。
CLI 佐证 ：harbor run --agent claude-code，agent 由你指定，Harbor 不锁写法。
常见误用：以为 Harbor「内置了一个 agent 帮你跑任务」。错。它是考场，考生得你自己带。这也正是 Ep1 那句「Harbor 是考场不是考官」在词汇层的落地。

Dataset：题库

定义：可运行评测的题目集 / 第三方基准，比如 terminal-bench@2.0、SWE-Bench、Aider Polyglot。
CLI 佐证 ：harbor run --dataset terminal-bench@2.0；想看有哪些题库直接 harbor datasets list。
常见误用 ：把 Dataset 和 Model 搞混--------dataset 是题、--model 才是 agent 背后那个大模型（如 anthropic/claude-opus-4-1）。两者都在 harbor run 里，但辈分不同：Dataset 是题，Model 是考生脑子里的「算力」。

Adapter：题库的「接线员」

定义：把某个外部 benchmark 接进 Harbor 执行引擎的那一小层胶水代码。仓库里 adapters/ 目录下就有具体实现（例如 research-code-bench adapter）。
类比：题库和考场之间的翻译 / 接线员。题库格式千奇百怪，Adapter 负责把它「翻译」成 Harbor 能跑的样子。
常见误用 ：以为是「agent 的适配器」。恰恰相反，它接的是题目那边。你换一个 agent（Claude Code → 自研），通常不用换 Adapter；你换一套题，才可能需要新的 Adapter。

Trial（≈ Run）：一场考试，会并行开很多场

定义：一次「单个任务 × 单个 agent × 单个模型」的完整运行记录。Dataset 有 100 道题，跑一场就是 100 个 Trial。
CLI 佐证 ：--n-concurrent 4 控制同时开几场------本地 4 场，上云 --env daytona 能开到 100 场并行。
常见误用 ：
- ① 和 Run 混用。源码里 Trial 正逐步改名为 Run（你能看到字段 number_of_trials → number_of_runs 的迁移），读到老代码别慌，两者说的是一回事。
- ② 以为 Trial 是「一次评测」------不，一个 Trial 只是「一道题的一次作答」，一次评测 = 一堆 Trial 的汇总。

Registry：题库的「出版社 + 目录」

定义：存储 task、dataset manifest、指标等元信息的注册库。你 harbor publish 把题交上去，别人 harbor download / harbor sync 拉下来。
CLI 佐证 ：围绕它的是 harbor publish / harbor download / harbor sync 这类「发行」命令。
常见误用：把它当成沙箱 / 考场。Registry 管的是「题的元信息」，真正跑题的是 Trial + 沙箱。一个管出版，一个管考试，别串台。

ATIF：轨迹的「通用制式」

定义：Agent Trajectory Interchange Format，Harbor 记录 agent 每一步行为的标准化轨迹格式（RFC 里能看到 ATIF v1.7 这类版本演进）。
它的价值（Harbor 拉开差距的点） ：轨迹是可移植的------Opik、LangSmith、你自己的 RL 训练管线都能直接吃，不被框架绑架。这正好接上 Ep1 那句「分数稀疏，轨迹才是金矿」。
常见误用：以为 ATIF 里存的是分数。错，它存的是「过程录像」，分数（pass / fail）是判卷脚本另给的。ATIF 只管把过程记标准了。

关系收口：

哥：出题人+ Harbor 编排引擎（run）。
小弟：Trial 是被 run 生出来的；Registry 只记账（题库目录）；ATIF 只是轨迹的「文件格式」，连实体都算不上，只是个制式约定。
一句话带走 ：你带人和题，Harbor 开考，Trial 是每一场的答卷，ATIF 是把答卷录成标准带，Registry 管题库的出版。 下次 harbor run 刷出一排 trial，你一眼就懂那是几场考试、卷子从哪来。

上手：把 6 个词落到命令上

下面这些命令来自官方 README，每条都能在上面的图里找到位置：

bash 复制代码

# 看 run 的真实参数面（版本漂移快，以你本机为准）
harbor run --help

# 看有哪些题库（Dataset 的落地点）
harbor datasets list

# 真跑一场：带 agent + 题 + 模型，本地 4 场并行
export ANTHROPIC_API_KEY=<YOUR-KEY>
harbor run --dataset terminal-bench@2.0 \
  --agent claude-code \
  --model anthropic/claude-opus-4-1 \
  --n-concurrent 4

每条命令对应图里的哪一步：

--agent ＝带考生（Agent）
--dataset ＝带题库（Dataset，经 Adapter 接入）
--n-concurrent 4 ＝同时开 4 场 Trial
跑完进 Registry 的题中、出 ATIF 轨迹、等你去 analyze

⚠️ 版本漂移提醒（和 Ep1 一致） ：Harbor 演进极快（当前 v0.16.1），网上旧博文命令参差。任何命令先 harbor run --help 看一眼你装的那版真实参数，别照抄。

3句话

Agent 是考生、Dataset 是题库、Adapter 是题库接线员------三者辈分不同，别串。
Trial 是一道考题的一次作答，一次评测 = 一堆 Trial；ATIF 是把这些作答录成的标准带，不是分数。
Registry 管题库出版、Harbor run 管开考，真正拉开差距的是 ATIF 让轨迹可移植。

🗺️ 本专栏路线图（建议收藏慢慢看）：

Ep1 开篇（已发）：Harbor 是啥、解决什么、应用场景、竞品对比、一次评测怎么跑；
Ep2 核心词汇表（本文）：Agent、Adapter、Dataset、Trial、Registry、ATIF，谁是牢哥谁是小弟；
Ep3 跑通第一个 benchmark ：以 Terminal-Bench-2.0 为例，真刀真枪 harbor run 一场；
Ep4 自定义题目 + 判卷脚本：把「你的题、你的判卷」接进考场；
Ep5 轨迹分析 + RL 数据生产：从录像里挖金矿，喂给你的训练管线。

下篇（Ep3）预告 ：《3 条命令跑通你的第一个 benchmark》------以 Terminal-Bench-2.0 为例，真刀真枪 harbor run 一场，把这篇的 6 个词全部跑活。

实测环境：macOS / harbor 2026-08 当前版（v0.16.1，来源官方 README 与 RFC）；文中命令与概念均对照官方文档，版本漂移请以你本地 harbor --help 为准。

如果这篇帮你把 Harbor 的「黑话」理顺了，点赞 + 收藏不迷路 🌟，有问题直接评论区见，想看下一篇也留言告诉我，催更我写得更快。