第 1 章：认识 Harbor——把 Agent 评测变成可复现的工程
第 1 章：认识 Harbor——把 Agent 评测变成可复现的工程
当越来越多的团队开始认真评估 coding agent 的真实能力，"写个脚本跑一跑"的做法很快就暴露出天花板：环境不一致、打分随意、结果无法复现。本章介绍 Harbor 框架的定位与 8 个核心概念，并带你完成安装、跑通第一个 Job，为后续章节的任务编写打下基础。
Agent 评测为什么需要一个框架
假设你要评测某个 agent 解决 bug 的能力，最常见的做法是：找几个题目、写个循环调 API、再手工看看输出对不对。这套流程在小规模下勉强可用，但很快会撞上几个问题：
- 环境不一致：Agent 在谁的本机上跑？装了哪些依赖？同一次评测换台机器结果就变了。
- 打分不客观：人工看输出没法规模化，临时写的判定脚本又容易与题目耦合，换个 agent、换个题目就要重写。
- 结果不可复现：跑完只留下几行日志，没人说得出当时的模型版本、指令原文和执行过程。
- 无法并行与聚合：几十道题串行跑一晚上，跑完还要自己汇总分数。
Harbor 针对的正是这些结构性问题：它把"一个评测"拆解成任务（Task）、执行（Trial/Job）、判分（Verifier）、记录（Trajectory）几个正交的组件，各自有明确的格式约定，从而让每次评测都像运行一次有版本管理的测试——独立、隔离、可复现。
Harbor 是什么
Harbor 是一个专注于 agent 评测的框架，以 Python 包的形式发布在 PyPI 上。它的设计可以概括为三点：
- 任务即目录：每个任务是一个自包含的文件夹（指令 + 环境 + 测试），不依赖 Harbor 本身，任何支持该格式的框架都可以直接使用。
- 执行即 Job：通过
harbor run把"数据集 × agent × 模型"组合起来批量执行，底层自动并行生成并运行 Trial。 - 结果即产物：每个 Trial 产出奖励（reward）和轨迹（trajectory），本地即可用 Web 界面查看，也可上传到 Harbor Hub 分享与复现。
8 大核心概念总览
Harbor 的全部工作流都围绕 8 个概念展开，理解了它们，后面的章节几乎不需要新词汇。
Task（任务）
任务定义了一条或多条指令（instruction）、一个沙箱环境（sandbox environment）和一个判分器（verifier）。任务以目录形式实现，遵循 Harbor 任务格式——这是全书的主角，第 2 章起逐层拆解。
Dataset（数据集）
数据集是任务的集合，通常对应一个 benchmark，例如 Terminal-Bench 或 SWE-Bench Verified。数据集可以选择通过 Harbor Hub 分发。
Agent（智能体）
Agent 是完成任务的那段程序。Harbor 内置了一批预集成 agent（如 Codex、Claude Code），也支持通过 BaseAgent 接口接入自定义 agent。
Sandbox（沙箱）
沙箱是运行任务的隔离环境。Harbor 默认使用 Docker，同时预集成了 Daytona、Modal 等云沙箱；实现 BaseEnvironment 接口即可接入其他运行时。
Verifier（判分器）
Verifier 负责评估 agent 的工作成果，并产出该任务的 reward。它通常表现为任务目录中的测试脚本，是保证"打分客观"的关键组件。
Trial（单次尝试）
一个 Trial 是"某个 agent 对某个任务的一次完整尝试"，包含启动环境、执行指令、判分全过程。它是 Harbor 中最小的评测单元。
Job（评测作业）
Job 是一组 Trial 的集合，用于评测 agent 和模型。一个 Job 可以自由组合数据集、agent、任务和模型；框架在底层生成 Trial 并并行运行。
Trajectory（轨迹）
Trajectory 记录 agent 与用户在完成任务过程中的对话与动作历史，是理解和调试 agent 行为最有用的工具。Harbor 的标准轨迹格式是 ATIF，轨迹还可以在后续的 agent 会话中重新加载。
一次 Job 的执行流
这 8 个概念在一次真实运行中的关系如下图所示：Job 从 Dataset 取出 Task，让 Agent 在 Sandbox 中执行指令，Verifier 打分形成一次 Trial，全部 Trial 汇总为 Job 结果，而 Agent 的执行过程则沉淀为 Trajectory。
flowchart LR
DS["Dataset 数据集"] --> T["Task 任务"]
T --> SB["Agent in Sandbox（沙箱中执行指令）"]
SB --> V["Verifier 打分"]
V --> TR["Trial 单次尝试"]
TR --> J["Job 汇总结果"]
J --> TJ["Trajectory 轨迹"]安装 Harbor
Harbor 推荐 uv 安装，也可以使用 pip。先安装 uv，然后：
uv tool install harbor如果你更习惯 pip：
pip install harbor升级到新版本时，先卸载再重装即可：
uv tool uninstall harbor
uv tool install harbor框架每天会把最新 main 分支的 dev 版本发布到 PyPI。多数用户用不到 nightly 构建，但如果想尝鲜，可以用预发布标记安装（不影响已装好的稳定版）：
uv tool install --prerelease explicit 'harbor>=0.dev0'pip install --pre harborHarbor 默认用 Docker 作为沙箱运行时，所以本机需要先安装 Docker。如果打算使用云沙箱（例如 Modal），需要额外安装对应依赖：
uv tool install "harbor[modal]"pip install "harbor[modal]"快速开始：跑通第一个 Job
安装完成后，用一条命令运行你的第一个 Job。下面的命令会拉取 hello-world/hello-world 任务，用 Codex agent 配合 openai/gpt-5.6-luna 模型来解它：
OPENAI_API_KEY="" \
harbor run -t hello-world/hello-world \
-a codex -m openai/gpt-5.6-luna 几个要点：
- 默认情况下 agent 在 Docker 沙箱中运行；想改用 Modal、Daytona 等云沙箱，加
--env（或-e）参数。 - 加
--launch标志可以直接把 Job 跑在 Harbor Hub 上，本机不出力。 - 运行结束后，结果落在
./jobs目录下。
Harbor 自带一个本地 Web 查看器，用于检查每个 Trial 的过程与得分：
harbor view ./jobs想把自己的结果分享给别人，可以上传到 Harbor Hub——收到的人可以拿到该 Job 的完整配置并复现结果。Terminal-Bench 官网就是一个公开发布评测结果、实现全程可审计的例子：
harbor upload "./jobs/" 本章小结
- 手工评测的四大痛点：环境不一致、打分不客观、结果不可复现、无法并行聚合，Harbor 用组件化设计逐一化解。
- Harbor 以 Python 包发布，推荐
uv tool install harbor安装，也可用pip install harbor。 - 默认沙箱是 Docker；云沙箱如 Modal 需要安装 extra 依赖，例如
harbor[modal]。 - 8 大核心概念：Task、Dataset、Agent、Sandbox、Verifier、Trial、Job、Trajectory。
- Trial 是最小评测单元：一次 agent 对一个任务的尝试；Job 是一批 Trial 的集合，底层自动并行。
harbor run -t <task> -a <agent> -m <model>是最常用的运行入口，--env切换沙箱，--launch上云。harbor view ./jobs打开本地结果查看器，harbor upload把结果分享到 Harbor Hub。- Trajectory 记录 agent 的对话与动作历史，标准格式为 ATIF，可用于调试与复放。