Harbor Framework：Agent 评测工程指南

本书基于 Harbor Framework 官方文档（docs.harborframework.com）整理撰写，覆盖核心概念、Task 规范、Agent 与沙箱体系、RewardKit 评分框架及实战教程。

关于这本书

这是一本 Agent 评测的工程指南。它围绕 Harbor——一个开源的 Agent 评测框架——展开，从评测为什么需要工程化讲起，带你掌握 Harbor 的八大核心概念（Task、Dataset、Agent、Sandbox、Verifier、Trial、Job、Trajectory），再深入 Task 规范、沙箱协议、ATIF 轨迹格式与 RewardKit 评分框架，最终通过一个完整任务的实战把全部知识串联起来。

这本书的读者是：正在开发或使用 AI Agent（尤其是 coding agent）、希望把"凭感觉聊天"升级为"可复现、可量化、可对比"的系统化评测的工程师与研究者。读完这本书，你不仅能用一条 harbor run 命令跑起 42 个预集成 Agent 在数十种沙箱上的评测，还能亲手定义任务、编写 Verifier、设计 LLM Judge、发布数据集，并读懂每一条 Trial 背后的轨迹数据。

一句话论点

当 Agent 越来越强，"怎么证明它真的强"就成了工程问题。Harbor 用 Task 把评测打包成软件包，用 Sandbox 保证环境可复现，用 Verifier 把结果变成可量化的 Reward，用 ATIF 让轨迹可交换——评测不再是手工作坊，而是一条可组装的流水线。

全书结构（18 章八个部分）

全书分为八个部分：第一部分建立全景认知（认识 Harbor 与快速上手）；第二部分深入 Task 核心（任务解剖、task.toml、环境、指令、Verifier、多步任务）；第三部分讲数据集组织；第四、五部分覆盖 Agent 与沙箱两大生态（预集成与自定义、ATIF 轨迹格式、ASP 协议）；第六部分讲 Job 的运行与配置；第七部分深入 RewardKit 评分框架；第八部分用一个完整任务实战收尾。

章节导航

第一部分：开篇（第 1 章）

• 第 1 章 认识 Harbor——把 Agent 评测变成可复现的工程：评测痛点、八大核心概念总览、安装与 hello-world 快速开始

第二部分：Task 核心（第 2-7 章）

• 第 2 章 任务解剖——一个 Task 由什么构成：目录结构、reward 落盘约定、一个 Trial 的完整生命周期
• 第 3 章 task.toml——任务配置全字段参考：schema 1.3 全字段逐段讲解，从 [task] 到 [environment]
• 第 4 章 任务环境——environment 目录与工具注入：Dockerfile 定制、MCP servers、skills_dir 与特殊路径
• 第 5 章 指令与解答——instruction.md 与 Oracle Solution：指令设计原则、canary 反污染、Oracle 验证任务可解
• 第 6 章 Verifier——从 test.sh 到 Reward：test.sh 执行机制、reward.txt/json 输出约定与确定性要求
• 第 7 章 多步任务——steps、早停与恢复：steps 目录、聚合策略、min_reward 早停与断点恢复

第三部分：数据集（第 8 章）

• 第 8 章 数据集——本地、Hub 与 Git 仓库：三种数据集来源、dataset.toml 操作、registry 注册与发布

第四部分：Agent 生态（第 9-11 章）

• 第 9 章 预集成 Agent——开箱即用的 42 个被测对象：--ak/--ae 指定方式、代表 Agent 详解与能力矩阵
• 第 10 章 自定义 Agent——BaseAgent 与 BaseInstalledAgent：两条自定义路径、注册方式与轨迹对接
• 第 11 章 ATIF——Agent 轨迹交换格式：v1.7 schema 逐字段讲解、Pydantic 模型与 validator 校验

第五部分：沙箱与协议（第 12-13 章）

• 第 12 章 沙箱——本地与远程执行环境：4 种本地 + 27 种远程沙箱、BaseEnvironment 接口逐方法详解
• 第 13 章 ASP——Agent Sandbox Protocol：解耦"大脑与双手"、.asp.json 契约与 SSH transport

第六部分：Job 编排（第 14-15 章）

• 第 14 章 运行 Job——harbor run 全指南：全套 CLI flags 分组讲解与示例命令
• 第 15 章 Job 配置文件与轨迹加载：JobConfig schema、native 与 ATIF 轨迹加载、--stream 实时观测

第七部分：RewardKit（第 16-17 章）

• 第 16 章 RewardKit 入门——声明式打分：@criterion 装饰器、reward.toml 聚合、内置 criteria 与隔离防护
• 第 17 章 LLM Judge——用模型给模型打分：judge TOML 完整参考、JEV judge 与主观任务评测设计

第八部分：实战（第 18 章）

• 第 18 章 实战——从零创建一个完整任务：11 步走通 ssh-key-pair 任务，把全书知识串成一张检查清单