Harbor Framework深度拆解：Agent评估的通用运行时

Harbor Framework深度拆解：Agent 评估的通用运行时

Terminal-Bench 2.0 的官方评测 Harness，从团队内部工具成长为事实上的行业标准。它最吸引人的不是评测本身，而是把评测、SFT 数据集生成、RL Rollout、可视化分析四件事放进了同一个框架里。

2025 年 11 月发布的 Terminal-Bench 2.0（Stanford + Laude Institute 联合出品）迅速成为代码 Agent 领域的金标准：89 道真实工程任务，v1.0 上超 50% 的模型在 v2 上的解算率直接被打回地板。而 Terminal-Bench 2.0 的官方 Harness 就是 Harbor Framework。

Harbor 的价值不只是"又一个评测工具"。它的定位是Agent 和 LLM 的完整生命周期运行时：
- 对研究者：一条命令在 SWE-Bench、Terminal-Bench、Aider Polyglot 等数据集上公平对比 18+ 个 Agent
- 对工程师：Daytona/Modal/E2B/Runloop/GKE 等 Provider 可以一键把并发从本地 4 拉到 100+ 环境
- 对训练团队：交互轨迹可直接导出 ATIF 格式生成 Rollout，从评测数据无缝进入 SFT / RL 训练管线
- 对项目 Owner：Harbor Hub 支持共享 Job、发布自定义 Task/Dataset、搭建私有 Leaderboard

版本号 v0.16.1，有正式的 Zenodo DOI（10.5281/zenodo.20953922）和 CITATION.cff，适合作为实验基础设施的稳定依赖。

本文提纲

三层解耦架构：Dataset × Agent × Model 完全正交
代码库结构：20+ 子模块的 Monorepo 组织方式
Agent 体系：内置 18+ Agent、External vs Installed 两种接入模式
环境与沙箱：9 种 Provider + Computer-Use 环境
作业编排：Trial 生命周期、Orchestrator、并行调度
可观测性：Trace 导出、Harbor Viewer、分析面板
生态：Hub 共享、Cookbook、Reward Kit、发布系统
快速上手：8 条常用命令速查

一、三层解耦架构：Dataset × Agent × Model 完全正交

绝大多数评测框架的问题是"绑定"——想换一个 Agent 就要改代码，想换一个 Benchmark 就要改 Harness。Harbor 的设计哲学是从根上拆成三层，彼此完全独立：

MERMAID_BLOCK_0

这意味着可以通过纯 CLI 参数完成任意组合：

# 例子 1：本地 Docker，Claude Code × Opus 4.1 × Terminal-Bench 2.0
harbor run --dataset terminal-bench@2.0 \
  --agent claude-code \
  --model anthropic/claude-opus-4-1 \
  --n-concurrent 4

# 例子 2：Daytona 云端，OpenHands × Gemini × SWE-Bench Lite
harbor run -d swe-bench@lite -a openhands -m google/gemini-3-flash \
  --env daytona --n-concurrent 100

# 例子 3：Modal GPU 环境，Aider × DeepSeek × Aider Polyglot
harbor run -d aider-polyglot@latest -a aider -m deepseek/deepseek-v4-pro \
  --env modal -c 64

不需要改任何代码，这是 Harbor 和大多数竞品最大的区别。

三层的职责边界

抽象层	职责	配置来源
Dataset	提供 instruction、环境定义、verifier 测试脚本	注册中心（公开）或本地 task/ 目录
Agent	读 instruction、操作环境、停止信号	实现 BaseAgent / BaseInstalledAgent
Model	通过 LiteLLM 调用、成本可计费、失败可重试	API Key + 模型名字符串
Environment	调度容器生命周期、隔离任务、复制产物	Provider 配置（docker / daytona / modal / ...）

额外还有两层：Orchestrator（负责 trial 并发调度、失败重试、超时终止）和 Verifier（读 /logs/verifier/reward.txt + 代码级 correctness check）。这两层是 Harbor 内部自动选择的，一般不需要用户介入。

二、代码库结构：20+ 子模块的 Monorepo 组织方式

Harbor 是一个 Python Monorepo（主包在 src/harbor/），附带 apps/viewer（Next.js 结果查看器）和 docs-mintlify/（官方文档站）。

主包内的 20+ 子模块：

子目录	功能	关键文件
agents/	Agent 工厂 + 实现	`base.py`（BaseAgent / BaseInstalledAgent 抽象）、`factory.py`、`terminus_2/`（自研旗舰）、`installed/`（18+ 内置）、`oracle.py`（测试基线）
cli/	Typer 命令行	`main.py` 入口；子命令：`jobs/trials/tasks/datasets/traces/sweeps/adapters/view/cache/analyze/publish/annotator/quality_checker`
environments/	10 种环境 Provider	`base.py`（BaseEnvironment 抽象）、`docker/`、`daytona.py`、`modal.py`、`e2b.py`、`runloop.py`、`gke.py`、`openshift.py`、`novita.py`、`apple_container.py` + computer-use env
models/	Pydantic 数据模型	下分 `agent/` `job/` `task/` `trial/` `metric/` `package/` `trajectories/` `verifier/` `registry/` — 所有内部/外部接口的契约
orchestrators/	Trial 并发调度	顺序/并行/云队列式 orchestrator
verifier/	任务验证系统	脚本化 + 代码级验证；支持 pass/fail 奖励、得分式奖励
analyze/	LLM 驱动的分析后端	失败原因分类、策略对比、结果洞察
storage/	Supabase 存储后端	结果、Trajectory、Job 元数据的持久化
publisher/	Task/Dataset 包发布	Harbor Hub 的注册与上传下载
auth/	OAuth 回调服务器	Harbor Hub 登录流程
llms/	LiteLLM 集成	统一模型调用、cost tracking
dataset/	Dataset 处理 + 缓存	Registry、本地文件系统 fallback
db/	内部数据库类型	Storage 层使用
inspect/	检查工具	调试用的内部诊断
annotator/	标注工具	人工标注任务结果、修正 verifier 判断
quality_checker/	质量验证	Task 上传前的完整性校验
template-adapter / template-metric / template-task	三个模板目录	Wizard 命令用来自动生成新项目
admin/	管理员子命令	Hub 管理
adapter_wizard.py	交互式 Wizard	生成 benchmark adapter
cache.py / download.py / sync.py	数据管理	缓存、下载、Hub 同步

工程质量观察：所有内部接口都有 Pydantic 模型契约（models/ 目录的覆盖面非常广），不是靠 dict 瞎传；CLI 拆成独立文件而不是 1000 行的 main.py；三种 Agent/Adapter/Task 模板目录说明作者有意识地降低新贡献者的接入门槛。

三、Agent 体系：内置 18+ Agent、External vs Installed 两种接入模式

18+ 个内置 Agent

Harbor 内置实现了目前市面上几乎所有主流代码 Agent：

类别	Agent 名字
旗舰自建	Terminus-2（Harbor 团队自研）
CLI 类 Agent	Claude Code、Codex CLI（Cline）、Gemini CLI、Goose、Cursor CLI、Kimi Code CLI、Copilot CLI、Rovo Dev CLI、Trae Agent
IDE 衍生	Cline CLI、Continue CLI
Web Agent	OpenHands、Mini-SWE-Agent
TUI/本地工具型	Aider
可扩展/DSPy 生态	DspyRlm Agent + 插件机制
GUI / Computer-Use	Computer-1 Agent（use-computer API、Anthropic/OpenAI 多 Provider）
基线 / 测试	Oracle Agent、NOP Agent

两种接入模式：External vs Installed

这是 Harbor Agent 架构的核心抽象。

MERMAID_BLOCK_1

模式	基类	Agent 跑在哪里	典型适用场景
External	`BaseAgent`	宿主机器或独立进程，通过 `environment.exec(command=...)` 控制容器	Agent 本身需要 GPU / 重依赖（如 OpenHands、自建推理服务）
Installed	`BaseInstalledAgent`	在容器内部被 `pip install` / `apt-get`，然后 headless 执行指令	纯 CLI、安装快、对宿主无依赖的 Agent（Claude Code、Aider、Codex CLI）

两种模式代码最小接入示例：

# --- External Agent 骨架 ---
from harbor.agents.base import BaseAgent, AgentContext
from harbor.environments.base import BaseEnvironment

class MyAgent(BaseAgent):
    @staticmethod
    def name() -> str: return "my-agent"
    def version(self) -> str | None: return "0.1.0"

    async def setup(self, env: BaseEnvironment) -> None:
        """宿主端准备：启动本地推理服务、加载模型等"""

    async def run(self, instruction: str, env: BaseEnvironment, ctx: AgentContext) -> None:
        """读 instruction，通过 env.exec 操作容器"""
        await env.exec(f"echo '{instruction}'", as_user="agent")

# --- Installed Agent 骨架 ---
from harbor.agents.installed.base import BaseInstalledAgent, with_prompt_template

class MyInstalledAgent(BaseInstalledAgent):
    @staticmethod
    def name() -> str: return "my-installed-agent"

    async def install(self, env: BaseEnvironment) -> None:
        await self.exec_as_root(env, "pip install my-agent-package")

    @with_prompt_template
    async def run(self, instruction: str, env: BaseEnvironment, ctx) -> None:
        await self.exec_as_agent(
            env,
            f"my-agent-cli --instruction '{instruction}'",
            timeout_secs=3600
        )

MCP Server 集成

Harbor 在 Agent 层原生支持 MCP Server 注入：对任何 Installed Agent，可在 task.toml 里指定一组 MCP 服务，运行时把 MCP_SERVERS_* 环境变量、credentials、allowed hosts 等注入容器。这意味着评测一个 Agent 时，可以同时控制"它能访问哪些 MCP 工具"作为变量，做消融实验。

四、环境与沙箱：9 种 Provider + Computer-Use 环境

Harbor 的环境体系是它能撑住"千环境并行"的基础。

9 种 Provider

Provider	类型	典型并发上限	适用场景
Docker	本地	4-32（取决机器资源）	本地开发调试
Daytona	云沙箱	100+	官方推荐、稳定、便宜
Modal	云（带 GPU 选项）	64+	需要 GPU 的任务、长任务
E2B	云沙箱	100+	沙箱原生生态
Runloop	云沙箱	100+	高频并发
Novita Sandbox	云沙箱	100+	高性价比
GKE	自建 K8s	自定义	企业内网合规需求
Red Hat OpenShift	自建	自定义	强合规 / FedRAMP
Apple Container	macOS 原生	1-4	iOS/macOS 开发任务

每一个 Provider 都实现同一个 BaseEnvironment 接口：exec / exec_as_root / exec_as_agent / copy_to / copy_from / snapshot / teardown / check_alive。对外行为完全一致。

Computer-Use 环境

除了普通终端容器，Harbor 还有专门的 Computer-Use Environment：启动带桌面环境的容器，Agent 通过 Anthropic/OpenAI 的 computer use API 进行真实 GUI 操作（点击、拖拽、键盘输入），并能截图、做视觉 OCR。这是 Harbor 相对 Terminal-Bench v1 的重大扩展——评测范围从"纯终端任务"扩展到了桌面应用、浏览器交互、IDE GUI 操作等。

五、作业编排：Trial 生命周期、Orchestrator、并行调度

Harbor 的作业抽象是四层递进：

MERMAID_BLOCK_2

Trial 生命周期

QUEUED：Job 启动后，所有 trial 入队
SCHEDULED：Orchestrator 为 trial 分配一个 environment slot
SETUP：容器启动、Agent install（Installed 模式）、task.toml 资源复制到沙箱
RUNNING：Agent.run(instruction) 开始执行；同时开启 watchdog 计时器
TIMEOUT / CRASH / ERROR / DONE：终端状态分支
- TIMEOUT：超过 --timeout-minutes 强制杀
- CRASH：Agent 进程异常退出
- ERROR：环境层面的失败（网络、API 额度耗尽等），可选重试
- DONE：Agent 正常退出
VERIFY：Verifier 读取 /logs/verifier/reward.txt、运行 tests/ 下脚本
COMMITTED：结果写入 Storage（Supabase / 本地 JSONL）；Trajectory 写入 ATIF 格式文件
TEARDOWN：容器销毁、资源释放

失败重试有一个很实用的设计：ERROR（基础设施问题）自动重入队列；TIMEOUT / CRASH 根据策略可选重试；VERIFY 失败不再重试。

Orchestrator

内置三种 orchestrator：
- Sequential（调试用）：一次跑一个 trial
- Concurrent-local（本地默认）：按 --n-concurrent 用 asyncio 限流并发
- Queue-based（云端推荐）：把 trial 派发到 Daytona / Modal 等远端队列，利用 Provider 原生的弹性

六、可观测性：Trace 导出、Harbor Viewer、分析面板

ATIF 轨迹导出

Harbor 支持把每次 trial 的完整交互导出为 ATIF（Agent-Trajectory-Interchange-Format） 格式：

trajectory.atif.json：包含每一步的 instruction → tool call → execution → result → verifier signal
可选打包：harbor traces export --fmt sft 直接转成 supervised fine-tune 需要的对话格式
RL rollout：harbor traces export --fmt rl-reward-labeled 把 reward 贴在每一个 step 上，可直接喂给 GRPO / PPO Trainer

这就是 Harbor "评测 → 训练"闭环的核心机制——不需要再写一套 separate 的 rollout 代码，同一次评测执行既是 benchmark score，也是训练数据。

Harbor Viewer

Harbor 附带一个 Next.js 实现的可视化 Viewer（apps/viewer/），功能点：

Job 总览：成功率柱状图、每个 task 的通过热力图
Trial 详情：完整回放 shell session、Agent 的 prompt、每一步的 cost、token、latency
对比模式：选中多个 Job 并排对比，找出"哪个 Prompt 改动能让 score +5%"
失败聚类：内置 LLM 分析后端对失败的 trial 做原因分类（工具调用错误 / 环境问题 / 规划失误 / 验证脚本问题）

七、生态：Hub 共享、Cookbook、Reward Kit、发布系统

Harbor Hub

Harbor Hub 是一个公开/私有的任务、数据集、适配器注册中心：

任何人可以通过 harbor publish task ./my-task-dir 发布一个 Task
数据集可以按 dataset@version 引用，发布后版本号不可变（immutable）
同一个团队可搭建私有 Hub（自托管 Supabase + Harbor auth server）
Job 分享：harbor hub share my-job 会产出一个链接，对方 harbor hub import <url> 就能复现完全相同的试验

Harbor Cookbook

独立仓库 harbor-cookbook 提供端到端示例：

如何创建自定义 Benchmark Adapter（SWE-Bench、Aider Polyglot、Terminal-Bench v1 迁移）
如何接一个全新 Agent（External / Installed 两套完整例子）
如何从 Terminal-Bench 数据生成 SFT Dataset
如何在 Modal 上跑 1000+ 并发的超参数搜索（Sweep）
如何搭建内部 Leaderboard

Reward Kit

Reward Kit 提供可复用的 reward 函数库：

Reward 函数	用法
RewardBinary	verifier 返回 0 或 1（pass/fail）
RewardScore	0-1 连续分数
RewardPartial	根据通过的测试子集比例给分（SWE-Bench 风格）
RewardCostPenalty	对 API cost 进行惩罚加权
RewardTimePenalty	长超时 trial 额外扣分
RewardComposite	线性组合多个 reward

八、快速上手：8 条常用命令速查

# 1. 安装
uv tool install harbor      # 推荐
pip install harbor          # 备选

# 2. 列出所有已注册 Dataset
harbor datasets list

# 3. 跑一个最小可复现实验（本地 Docker 4 并发）
export ANTHROPIC_API_KEY=<YOUR-KEY>
harbor run -d terminal-bench@2.0 -a claude-code \
  -m anthropic/claude-opus-4-1 -c 4

# 4. Daytona 云端高并发（100 并发拉满整个 Benchmark）
export DAYTONA_API_KEY=<YOUR-KEY>
harbor run -d terminal-bench@2.0 -a claude-code \
  -m anthropic/claude-opus-4-1 --env daytona -c 100

# 5. 给 Agent 注入额外环境变量（如 AWS Key）
harbor run -d terminal-bench@2.0 -a aider \
  -m deepseek/deepseek-v4-pro \
  --ae AWS_ACCESS_KEY_ID=$AWS_KEY \
  --ae AWS_REGION=us-east-1

# 6. 参数扫描（Sweep）：不同 Prompt 模板 × 不同 Temperature
harbor sweeps run --config sweeps/prompt-tuning.toml

# 7. 把跑完的 Job 导出 SFT 数据和 RL rollout
harbor traces export --job my-job-id --fmt sft    -o sft.jsonl
harbor traces export --job my-job-id --fmt rl     -o rl-rollouts.jsonl

# 8. 打开结果 Viewer
harbor view --job my-job-id

容易踩的坑：
- Docker 模式默认本地环境，并发 >8 时本机 CPU/MEM 容易爆 → 此时切 Daytona
- Installed Agent 在 Apple Silicon Mac 上跑 x86 Docker 镜像可能极慢 → 用 --platform 或直接 Daytona
- 结果不一致？先确认 --seed 一致 + dataset 版本号明确（不要写 terminal-bench@latest）
- API 成本意外偏高？用 harbor analyze cost --job <id> 事后复盘每个 trial 的 token/cost

作者: itech001
来源: 公众号：AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

本文首发于 AI人工智能时代，转载请注明出处。

posted @ 2026-08-27 22:52 iTech 阅读(36) 评论(0) 收藏举报

刷新页面返回顶部

iTech's Blog

公众号：AI人工智能时代（the-ai-era）更多精彩 AI 内容关注主页：www.theaiera.top

Harbor Framework深度拆解：Agent评估的通用运行时

Harbor Framework深度拆解：Agent 评估的通用运行时

本文提纲

一、三层解耦架构：Dataset × Agent × Model 完全正交

三层的职责边界

二、代码库结构：20+ 子模块的 Monorepo 组织方式

三、Agent 体系：内置 18+ Agent、External vs Installed 两种接入模式

18+ 个内置 Agent

两种接入模式：External vs Installed

MCP Server 集成

四、环境与沙箱：9 种 Provider + Computer-Use 环境

9 种 Provider

Computer-Use 环境

五、作业编排：Trial 生命周期、Orchestrator、并行调度

Trial 生命周期

Orchestrator

六、可观测性：Trace 导出、Harbor Viewer、分析面板

ATIF 轨迹导出

Harbor Viewer

七、生态：Hub 共享、Cookbook、Reward Kit、发布系统

Harbor Hub

Harbor Cookbook

Reward Kit

八、快速上手：8 条常用命令速查

公告

iTech's Blog

公众号：AI人工智能时代（the-ai-era） 更多精彩 AI 内容关注主页：www.theaiera.top

Harbor Framework深度拆解：Agent评估的通用运行时

Harbor Framework深度拆解：Agent 评估的通用运行时

本文提纲

一、三层解耦架构：Dataset × Agent × Model 完全正交

三层的职责边界

二、代码库结构：20+ 子模块的 Monorepo 组织方式

三、Agent 体系：内置 18+ Agent、External vs Installed 两种接入模式

18+ 个内置 Agent

两种接入模式：External vs Installed

MCP Server 集成

四、环境与沙箱：9 种 Provider + Computer-Use 环境

9 种 Provider

Computer-Use 环境

五、作业编排：Trial 生命周期、Orchestrator、并行调度

Trial 生命周期

Orchestrator

六、可观测性：Trace 导出、Harbor Viewer、分析面板

ATIF 轨迹导出

Harbor Viewer

七、生态：Hub 共享、Cookbook、Reward Kit、发布系统

Harbor Hub

Harbor Cookbook

Reward Kit

八、快速上手：8 条常用命令速查

公告

公众号：AI人工智能时代（the-ai-era）更多精彩 AI 内容关注主页：www.theaiera.top