harbor-framework/harbor

一句话定位： Terminal-Bench 官方团队（Laude Institute / Stanford）开源的 Agent 评测与优化执行框架——把任意 agent × 任意 benchmark 编译成统一的 Task/Agent/Environment/Trial/Job 五元组，在本地 Docker 或数千并发云沙箱上跑评测、生成 RL rollout。

GitHub: harbor-framework/harbor Stars: 5,330 | License: Apache-2.0 | Language: Python | 版本: 0.23.0 | 创建: 2025-08

为什么值得关注

1. 它是 Terminal-Bench 的官方 harness，不是第三方复刻

README 明确写 “Harbor is the official harness for Terminal-Bench-2.0”，数据集仓库在 laude-institute/harbor-datasets，与 terminal-bench 的榜单/任务同源。评测口径与基准维护方是同一批人，这消除了”跑分工具与被测基准脱节”这一常见问题。

2. Verifier 隔离是一等公民

task.toml 的 [verifier].environment_mode 支持 shared / separate；当 verifier 需要独立依赖、判分提示词或 API key 时，Harbor 会复制一份干净环境运行验证，agent 进程看不到评分逻辑。这恰好是 recursive-self-improvement 里”评估与监督必须在更新边界之外”这条铁律的工程化落地，也是 Terminal-Bench 显式追踪 reward hack 率的基础设施前提。

3. 评测规模是同一套代码从 4 并发拉到 1000+

同一个 harbor run 命令，--env 从本地 docker 换成 daytona/modal/e2b 等云沙箱，--n-concurrent 从 4 直接拉到 100+。评测、消融、扫参、RL rollout 生成共用一条命令面，不需要为规模另写调度层。

4. 覆盖矩阵足够宽，适合做跨 harness 研究

内置 40+ agent 适配（Claude Code / Codex / OpenHands / OpenClaw / opencode / Gemini CLI / Cursor CLI / Goose / Aider / mini-swe-agent / Terminus 等）、80 个数据集注册项、85 个 benchmark adapter、30+ 执行后端。想比较”同一模型换 harness 值多少分”，这是目前最省事的开箱工具箱。

5. 评测链路直接接到训练

docs/content/docs/training-workflows/ 下同时有 rl.mdx 与 sft.mdx，仓库 topics 明确包含 rl-environments。Harbor 不只是打分器，它在”跑评测 → 收 rollout → 喂 RL/SFT”这条链路上补上了环境侧的执行标准。

核心概念

概念	定义	载体
Task	一个评测单元	目录：instruction.md + task.toml + environment/ + tests/ + 可选 solution/
Agent	被测对象，实现 BaseAgent 的 setup()/run()	src/harbor/agents/，install agent + internal + utility 三类
Environment	任务执行沙箱	src/harbor/environments/，本地与云 provider
Trial	单次 agent × task 执行	产出轨迹（ATIF 格式）、token/成本/时长指标、verifier 结果
Job	一组 trial（多 agent × 多 task × 多 attempt）	并行调度单位，落盘为可分享的 job 目录

架构分层

harbor CLI (Typer)
  └── Job / Trial 编排（orchestrators, job_plan）
        ├── Environment 后端：docker | daytona | modal | e2b | runloop | gke |
        │                     openshift | apple_container | novita | blaxel | ...
        ├── Agent 适配：claude-code | codex | openhands | openclaw | opencode | ...
        ├── Verifier：pytest | Reward Kit | 自定义；shared / separate 环境
        └── 产出：trajectory.json（ATIF） + 指标 + 可回放 viewer

配套子包：harbor-rewardkit（判分）、harbor-langsmith（LangSmith 桥接）、harbor-atif2otel（轨迹转 OpenTelemetry）。

任务与判分

Task 是一份自包含的目录契约：

<task-name>/
├── instruction.md          # 给 agent 的自然语言任务
├── task.toml               # 超时/资源/网络模式/verifier 配置
├── environment/Dockerfile  # 容器定义
├── solution/solve.sh       # 参考解法（可选）
└── tests/test.sh           # 判分脚本，写 /logs/verifier/reward.txt

三条判分路线：

• pytest：默认模板，适合行为可断言的任务
• Reward Kit：把 tests/ 目录下的一组 criteria（Python 函数或 judge.toml LLM 裁判）聚合成 reward，默认写 reward.json
• 自定义：直接实现 BaseVerifier.verify() 返回 VerifierResult

reward 支持连续分而非仅 0/1，这是它能直接产出 RL 训练信号的前提。

支持的运行方式

维度	覆盖
执行后端	本地 Docker、Apple Container、Podman、Singularity、Kubernetes(GKE)、OpenShift、SSH，以及 Daytona / Modal / E2B / Runloop / Blaxel / Novita / Tensorlake / Runta / LangSmith 等云沙箱
Agent	40+ 内置适配，含 ACP 协议与 SDK 两条接入路径（installed/acp*.py、langgraph_runner.py、strands_runner.py 等）
数据集	80 个注册项：Terminal-Bench 2.0/2.1、SWE-bench Verified、Aider Polyglot、GAIA、HLE、GPQA、OSWorld、BFCL、LiveCodeBench 等
工作流	单次 run、参数 sweep、harbor exec map-reduce、regrade 重判、hosted 云端 job、Hub 榜单

两处容易被忽略的设计

harbor exec：把文件当任务源

harbor exec 被设计成 agentic map-reduce：把一批文件/目录/glob 编译成 Harbor task，跑 map 阶段，再可选做 reduce 聚合。适合”我有一千个仓库要审”这类非基准化场景——把一次性批处理纳入了同一套 task/artifact 契约。

仓库自带 skill，agent 可直接上手

skills/ 下有 6 个官方 Claude skill：create-task、create-adapter、harbor-exec、rewardkit、publish、upload-parity-experiments。其中 create-task 会引导完成 instruction 撰写、环境搭建、verifier 选型（pytest vs Reward Kit vs custom），并明确提醒”verifier 通常是最难的部分”。这是罕见的评测框架把自己封装成 agent skill的形态。

局限与注意

• 不是”更聪明的评测”：Harbor 解决的是执行、隔离、规模与可复现；任务质量仍取决于 adapter 与 verifier 设计，垃圾任务在云上只会更快地变成垃圾
• Python 3.12+，本地跑 Docker 是默认路径；云后端需要各自 API key 与配额
• 数据集与框架分仓：tasks 在 laude-institute/harbor-datasets，registry 用 commit id 锁定版本，跨版本对比时要注意任务集合变化
• schema 仍在演进：task.toml schema_version 已到 1.4，轨迹格式 ATIF 到 v1.8，早期版本虽兼容但字段语义有调整（CHANGELOG 有 breaking changes 专章）
• 规模有成本：千并发意味着千个容器；虽然适配了多家 sandbox，账单与配额管理仍是使用方责任

个人评价

如果要做 agent harness 的横向对比或自进化闭环，Harbor 值得直接作为基座而不是自己搭：

1. Verifier 隔离有现成开关，省掉最容易做错的一环
2. 换 harness 的成本从”重写调度”降到”换个 --agent”
3. 轨迹格式统一后，traces 才是真正可复用的燃料（呼应 agent-continual-learning 的”traces 是统一燃料”）
4. 对 recursive-self-improvement 这类研究，它同时提供了 evaluator 与 rollout 生成器两侧

主要保留意见是生态仍在快速迭代，长周期项目要跟 CHANGELOG 走。

资源

• 仓库：https://github.com/harbor-framework/harbor
• 官网与文档：https://harborframework.com/docs
• Cookbook：https://github.com/harbor-framework/harbor-cookbook
• 数据集仓库：https://github.com/laude-institute/harbor-datasets
• 引用 DOI：https://doi.org/10.5281/zenodo.20953922
• 本地 clone：~/6ai/opensources/harbor（v0.23.0）

相关页面

• terminal-bench — Harbor 是其官方 harness，榜单/任务同源
• recursive-self-improvement — verifier 隔离与评估在更新边界外的工程实现
• agent-continual-learning — 轨迹作为统一燃料，Harbor 提供标准化采集层
• meta-harness — 在 Terminal-Bench 上做 harness 自动优化的研究，评测基座即 Harbor
• swe-bench-verified、vibe-code-bench — 同为主要 agent 评测基准
• deepswe — verifier 测行为不测实现的设计对照