Harbor 详解：RL 任务的“考场组织者”

为什么需要 Harbor

假设你要评测“Codex + gpt-6-astra 能不能在 Blender 里做好一个机械臂动画”，而且要跑 100 道题、每题 3 次。没有框架时，每个团队都要自己写一遍：

再加上并发控制、失败重试、超时、结果汇总、pass@k 统计、结果浏览器……Harbor 把这些都做成了标准件，还提供 harbor task migrate 把 Terminal-Bench 格式的任务迁移过来。

六个核心对象

另外两个常见名词：Dataset 是一组任务（通常对应一个基准，如 Terminal-Bench），可以发布到 Harbor Hub；Trajectory 轨迹是 agent 完整的对话和动作记录，标准格式叫 ATIF。

flowchart LR
  JC["JobConfig
tasks × agents × n_attempts"] --> J["Job"]
  J -->|"展开"| T["Trial"]
  TK["Task 目录
instruction · task.toml
environment/ · tests/"] --> T
  T -->|"1. start"| E["Agent Environment
沙箱"]
  T -->|"2. setup + run"| A["Agent"]
  A <-->|"exec / 读写文件"| E
  E -->|"3. 日志 · 轨迹 · artifacts"| T
  T -->|"4a. shared：同一沙箱"| V["Verifier
/tests/test.sh"]
  T -->|"4b. separate：上传 artifacts"| VE["Verifier Environment
全新沙箱"]
  VE --> V
  V -->|"reward.json / reward.txt"| R["TrialResult
result.json"]
  R --> J
  J -->|"Mean · pass@k"| JR["JobResult"]
    

Task：一道题长什么样

目录结构

my-task/
├── instruction.md        # 题面：给 agent 看的自然语言需求
├── task.toml             # 配置：超时、资源、网络、verifier 模式、artifacts…
├── environment/          # 沙箱定义：Dockerfile / docker-compose.yaml / 其他后端认识的格式
│   └── Dockerfile
├── solution/             # 可选：参考解，内置的 oracle agent 会运行 solve.sh
│   └── solve.sh
└── tests/                # 评分：入口固定为 test.sh（Windows 为 test.bat）
    ├── test.sh
    └── ...               # 任意辅助文件；可放 tests/Dockerfile 作为独立 verifier 镜像

还支持多步任务：把题拆进 steps/step-1/、steps/step-2/……每步有自己的题面、测试和参考解，可以设 min_reward 不达标就停止，trial 总分按 mean 或 final 汇总。我们的两个 repo 都没用到多步。

reward 契约：Harbor 只认这两个文件

这是 Harbor 和评分脚本之间唯一的接口：tests/test.sh 不管内部做什么，最后必须在沙箱里写出其中一个文件。

两者都存在时优先读 reward.json；文件缺失、为空、无法解析、出现 NaN/Infinity 都会抛专门的异常。最简单的 test.sh：

#!/bin/bash
set -euo pipefail
if pytest /tests/test_outputs.py; then
  echo 1 > /logs/verifier/reward.txt
else
  echo 0 > /logs/verifier/reward.txt
fi

task.toml 关键字段

完整字段很多，下表只列和我们相关的。原则是：能写进 environment/（如 Dockerfile）的就不写进 task.toml，只有缺乏约定或容易踩坑的才放在这里。

一次 Trial 的完整生命周期

这是 Harbor 最核心的部分，代码在 harbor/trial/trial.py（约 1900 行）。Trial.run() 的骨架非常简单：

self._init_result()
await self._emit(TrialEvent.START)
try:
    await self._prepare()        # 起沙箱、健康检查、安装 agent
    if not self.config.install_only:
        await self._run()        # 跑 agent → 收产物 → 跑 verifier
except Exception as exc:
    self._record_exception(exc)
    await self._close_bridge()
    await self._recover_outputs()  # 出错也尽量把日志和产物捞回来
finally:
    await self._finalize()       # 停沙箱、写 result.json、脱敏
return self.result

sequenceDiagram
  participant T as Trial
  participant E as Agent 沙箱
  participant A as Agent
  participant VE as Verifier 沙箱
  T->>T: 写 config.json，建 TrialResult
  T->>E: start(force_build)，健康检查
  T->>A: setup(E)：安装 CLI，写配置
  T->>A: run(instruction, E, context)，asyncio.wait_for 计时
  A->>E: exec 命令 / 读写文件（多轮）
  T->>E: 下载 agent 日志，转换成 ATIF trajectory.json
  T->>E: 收集 artifacts，写 manifest.json
  alt separate 模式
    T->>E: stop
    T->>VE: start，上传 artifacts 到原路径，上传 tests/
    T->>VE: 执行 /tests/test.sh
    VE-->>T: /logs/verifier/reward.json
    T->>VE: stop
  else shared 模式
    T->>E: 上传 tests/ 到 /tests，执行 test.sh
    E-->>T: /logs/verifier/reward.json
    T->>E: stop
  end
  T->>T: 写 result.json，用敏感值脱敏输出
    

Trial 输出目录

<trial_dir>/
├── agent/                 # agent 原生日志 + trajectory.json（ATIF）
├── verifier/
│   ├── test-stdout.txt
│   └── reward.json | reward.txt
├── artifacts/
│   ├── manifest.json      # 收集了什么、从哪来、是否成功；regrade 依赖它
│   └── ...
├── config.json            # 完整 TrialConfig，可用于复现
├── lock.json
├── result.json            # TrialResult
├── exception.txt          # 仅出错时
└── trial.log

TrialResult 主要字段：任务名与校验和、完整 config、agent_info（名称/版本/模型）、agent_result（token、费用）、verifier_result（rewards）、exception_info（类型、消息、traceback），以及环境准备、agent 安装、agent 执行、评分四段的起止时间。

超时、重试与钩子

• 四段超时：沙箱构建 build_timeout_sec、agent 安装（默认 360s）、agent 运行 [agent].timeout_sec、评分 [verifier].timeout_sec。实际值 = min(基础值, 上限) × 倍数，倍数可以全局或分阶段设置。
• 重试（0.24.0）：TrialQueue 每次重试都新建一个 Trial 并删除失败的 trial 目录，按 min(min_wait × multiplier^n, max_wait) 指数退避。默认 max_retries=0；超时、reward 解析失败、额度用尽、安全拒绝、认证失败、模型不存在默认不重试。
• 钩子：START、ENVIRONMENT_START、AGENT_START、AGENT_END、VERIFICATION_START、END、CANCEL，可用于接观测平台。

共享 verifier vs 独立 verifier

这是 Harbor 最重要的安全设计，也是我们 KUKA 案例用到的关键能力。

模式怎么判定（0.24.0）

独立 verifier 的镜像按优先级选：[verifier.environment].docker_image → tests/Dockerfile → 顶层 docker_image → environment/Dockerfile。前两种视为“测试已打进镜像”，不再上传 tests。

重评 regrade

只改了评分逻辑、不想重跑 agent 时：harbor trial regrade <trial> -p <新任务目录>。Harbor 复制原 trial 的 agent/ 和 artifacts/ 到新 trial，用空操作 agent 占位，只起一个独立 verifier 跑新测试，原 trial 不被修改。前提是新 verifier 必须是 separate 模式，且它需要的每个输入都在原 trial 的 manifest.json 里有记录。KUKA 从 0.4.3 到 0.4.4 的“统一重评”就是这个思路（具体由 repo 脚本实现）。

Environment：沙箱抽象

任何后端只要实现 BaseEnvironment 的这几个方法，就能接入 Harbor：

class MySandbox(BaseEnvironment):
    @staticmethod
    def type() -> str: return "my-sandbox"
    @property
    def capabilities(self) -> EnvironmentCapabilities: return EnvironmentCapabilities()
    def _validate_definition(self) -> None: ...          # 校验任务的 environment/ 是否符合要求
    async def start(self, force_build: bool) -> None: ...
    async def stop(self, delete: bool) -> None: ...
    async def exec(self, command, cwd=None, env=None, timeout_sec=None, user=None) -> ExecResult: ...
    async def upload_file(self, source_path, target_path) -> None: ...
    async def upload_dir(self, source_dir, target_dir) -> None: ...
    async def download_file(self, source_path, target_path) -> None: ...
    async def download_dir(self, source_dir, target_dir) -> None: ...

ExecResult 只有 stdout、stderr、return_code 三个字段。自定义后端不用改 Harbor 注册表，配置里写 import_path = "my_module:MySandbox"（命令行 -e my_module:MySandbox）即可，构造参数用 kwargs 传。

内置后端

0.24.0 注册了 31 种：docker、podman、apple-container、singularity、kata，以及云沙箱 daytona、e2b、modal、runloop、ec2、gke、ack、openshift、vercel、beam、blaxel、tensorlake、skypilot、hf-sandbox 等。云沙箱的 SDK 按需安装：pip install 'harbor[modal]'。

Docker 后端用 Docker Compose 统一处理单 Dockerfile、预构建镜像和多容器任务；镜像名由任务内容哈希生成。网络隔离：静态 no-network 就是 network_mode: none；需要按阶段切换或 allowlist 时，起一个带 NET_ADMIN 的出口控制 sidecar，任务容器共享它的网络命名空间，Harbor 等 sidecar 就绪后才放 agent 进来。

Agent：考生适配器

自定义 agent 实现四个方法：name()、version()、setup(environment)、run(instruction, environment, context)，并用 AgentCapabilities 如实声明是否支持 ATIF、恢复、MCP、skills 等。同样用 import_path 或 --agent module:Class 接入。

内置的“安装型” agent 怎么工作

其他内置 agent 还有 gemini-cli、cursor-cli、aider、goose、openhands、swe-agent、mini-swe-agent、opencode、qwen-coder、kimi-cli、devin 等，共 40 多个；用 harbor agent list 查看。

Trajectory：ATIF 统一轨迹格式

每种 agent 的原生日志格式都不同。ATIF（Agent Trajectory Interchange Format）把它们统一成一种 JSON，供结果浏览器展示、训练数据整理、或作为下一次会话的初始上下文。

{
  "schema_version": "ATIF-v1.7",
  "session_id": "session-123",
  "agent": { "name": "codex", "version": "0.163.0", "model_name": "openai/gpt-5.6-sol" },
  "steps": [
    { "step_id": 1, "source": "user",  "message": "Create hello.txt." },
    { "step_id": 2, "source": "agent", "message": "I'll create it.",
      "tool_calls": [{ "tool_call_id": "call-1", "function_name": "write_file",
                       "arguments": { "path": "hello.txt", "content": "Hello" } }],
      "observation": { "results": [{ "source_call_id": "call-1", "content": "File created" }] },
      "metrics": { "prompt_tokens": 1200, "completion_tokens": 80, "cost_usd": 0.004 } }
  ],
  "final_metrics": { "total_steps": 2 }
}

规则：step_id 从 1 连续；source 是 system / user / agent；只有 agent 步可以带模型名、推理内容、工具调用和 metrics；observation 必须引用同一步的 tool call ID。0.24.0 接受 v1.0 到 v1.8。

RewardKit：配套的判分工具包

Harbor 只规定“test.sh 最后写一个 reward 文件”，不管你怎么算分。RewardKit（harbor-rewardkit）是同团队维护的独立包，用来省掉判分样板代码。

• 程序化判据：在 tests/ 下写 Python 文件，用 @criterion 装饰函数（参数第一个是 workspace: Path，返回 bool / float / 带 score 的 dict），或调用 20 多个内置判据（rk.file_exists、rk.command_succeeds …）。
• Judge 判据：用 TOML 配置 LLM 或 agent 作为评委，支持 binary / likert 打分。
• 合分：每个 Python 文件或 judge TOML 产出一个分数；用 reward.toml 指定聚合方式：weighted-mean、weighted-sum、all-pass、any-pass、threshold、required-pass。子目录可以产出多维 reward。
• 隔离：会修改工作区的判据可设 isolated=True，用 overlayfs 只读挂载并丢弃改动；Worker 以全新无账号 UID 运行提交的代码，读不到 /tests、写不了 /logs/verifier。
• 输出：reward.json（分数）+ reward-details.json（逐条判据分数、评委理由、错误）。

KUKA 的真实 reward.toml，就是 Rule 80 / VL 20 的来源：

[[reward]]
name = "reward"
aggregation = "weighted-mean"
weights = { native = 0.8, visual = 0.2 }

Job：实验矩阵、并发与统计

• 展开：trial 总数 = 任务数 × agent 数 × n_attempts（默认 1）。
• 并发：n_concurrent_trials（默认 4）是全局上限，信号量包住整个 trial；每个 agent 还可以设 n_concurrent，只在 agent 运行阶段占用。
• 结果：JobResult 按 agent__model__dataset 分组统计完成/出错/重试数、metric、pass@k、token 与费用，并列出每种 reward 值和每种异常对应的 trial。
• 续跑：harbor job resume 从已有 job 目录继续未完成的 trial。

metric 与 pass@k 的实际算法

默认 metric 是 Mean：没有结果的 trial 记 0，多个 reward 键分别平均，缺键记 0。另有 max / min / sum 和自定义 uv 脚本。pass@k 用的是标准无偏估计（每题 n 次尝试、c 次成功）：

if n - c < k:
    return 1.0
product = 1.0
for i in range(k):
    product *= (n - c - i) / (n - i)
return 1.0 - product       # 再对所有任务取平均

CLI 速查

我们的两个 repo 怎么用 Harbor

区别在于“把多少事交给 Harbor”。可以这样比喻：Harbor 是统一的“导演”，在 blender_rl 里导演只管每一幕的开场和收场，在 KUKA 里导演负责完整的一场演出。

arkevo_blender_rl：Harbor 只管“一段会话”

flowchart TD
  W["solver/worker.py segment()"] -->|"临时小任务 + JobConfig"| J["harbor Job
1 任务 · 1 次 · 并发 1
verifier.disable = True"]
  J --> SE["SolverEnvironment
start 只检查 workspace 存在
exec 直接报错"]
  J --> SA["SolverAgent.run()"]
  SA -->|"confine.py：独立 UID + Landlock"| CLI["codex exec / claude
resume 同一 session"]
  CLI <-->|"MCP"| B["Blender 5.2.1
单卡 GPU · Xvfb"]
  SA -->|"逐行写"| LOG["Harbor logs_dir/agent.jsonl"]
  SA -->|"每秒检查"| CLK["budget.Clock
累计 4h 活跃时间"]
  J --> RES["harbor-result-NNNN.json"]
  LOG --> SEAL["seal.py：脱敏轨迹 + 冻结作品
→ submission_ready"]
  SEAL --> SC["仓库自己的异步打分器
Rule 70 + VLM 30"]
    

每个求解样本可能被拆成多个“segment”（进程被杀、API 中断后续跑）。每个 segment 都是一个独立的小 Harbor Job：

cfg = JobConfig.model_validate({'job_name': f'{job.name}-s{number:04d}',
    'jobs_dir': str(job / 'harbor'), 'n_concurrent_trials': 1, 'n_attempts': 1,
    'environment': {'import_path': 'arkevo_blender_rl.authoring.harbor_adapter:AuthorEnvironment'},
    'agents': [{'import_path': 'arkevo_blender_rl.authoring.harbor_adapter:AuthorAgent',
                'model_name': config['model']}],
    'verifier': {'disable': True}, 'tasks': [{'path': str(author_task)}]})

（上面是造题侧；求解侧同理，换成 SolverEnvironment / SolverAgent。）环境类是一个有意的“薄壳”：

class SolverEnvironment(BaseEnvironment):
    @property
    def capabilities(self): return EnvironmentCapabilities(gpus=True)
    @staticmethod
    def type(): return 'arkevo-native-solver'
    async def start(self,force_build=False):
        if not self.workspace.is_dir(): raise FileNotFoundError(self.workspace)
    async def exec(self,*args,**kwargs): raise RuntimeError('Use the isolated native solver runner')
    async def upload_file(self,*args,**kwargs): raise RuntimeError('Inputs staged by controller')

这里 Harbor 真正提供的是：trial 目录和日志目录（self.logs_dir）、一致的 config/result 记录，以及造题发布前用 harbor.models.task.config.TaskConfig 校验题包里的 task.toml。题包里的 task.toml 很小：

version = "1.0"          # 0.24.0 自动迁移为 schema_version
[agent]
timeout_sec = 43200
[verifier]
timeout_sec = 3600
[environment]
cpus = 4
memory_mb = 8192

arkevo_task_scaling（KUKA）：完整的 Harbor trial + 独立 verifier

flowchart TD
  R["run_harbor_kuka.py one()"] -->|"TrialConfig"| T["harbor Trial
每个 model × attempt 一个"]
  T --> SE["KukaLandlockEnvironment
solver 根文件系统模板
独立 UID · 两层 Landlock · PRoot"]
  T --> KA["KukaCliAgent
codex 0.155.1 / claude 2.1.278
无会话恢复"]
  KA <-->|"Bash / Python / Blender CLI"| SE
  SE -->|"artifacts: /workspace/output → submission"| T
  T --> VE["KukaLandlockEnvironment
verifier 根文件系统模板（全新）"]
  VE --> TS["/tests/test.sh
→ verify_kuka_submission.py"]
  TS --> P["Blender 4.0.2 原生 probe
+ 固定 7 张画面"]
  TS --> VL["视觉评委
claude-opus-5-5"]
  P --> RK["RewardKit
native 0.8 + visual 0.2"]
  VL --> RK
  RK -->|"封顶 + success 判定"| RW["/logs/verifier/reward.json"]
  RW --> T
  T --> REC["records.json → evaluation.py
avg@3 · pass@3"]
    

config = TrialConfig(task=TaskConfig(path=args.task.resolve()),
    trial_name=f'{model}-{attempt:02}', trials_dir=args.output/'trials',
    agent=agent, verifier=VerifierConfig(disable=args.phase == 'smoke'),
    environment=EnvironmentConfig(
        import_path='harbor_kuka_runtime:KukaLandlockEnvironment', delete=False))
trial = await Trial.create(config)
result = await trial.run()

KUKA 的 task.toml 明确用了独立 verifier 和 artifacts 交接：

schema_version = "1.3"
artifacts = [{ source = "/workspace/output", destination = "submission" }]
[task]
name = "arkevo/kuka-two-station"
[agent]
timeout_sec = 3610
user = "agent"
[environment]
docker_image = "kuka-solver-v043"      # 不是 Docker 镜像！是自定义后端选根文件系统模板的标签
workdir = "/workspace"
cpus = 4
memory_mb = 16384
[verifier]
environment_mode = "separate"
timeout_sec = 2400
user = "agent"
[verifier.environment]
docker_image = "kuka-verifier-v043"
workdir = "/workspace"

并排对比

职责划分：哪些是 Harbor 做的，哪些是仓库做的

踩过的坑与边界

• Bunker worker 上跑不了 Docker 后端：没有 Docker daemon/socket、cgroup v2 只读、不能创建用户命名空间，所以 KUKA 只能自己写 Landlock/UID/PRoot 后端。通用 Harbor–Bunker 适配器和 Linux + Docker 后端都还没验证。
• 内存保护误杀（KUKA 0.4.0）：自研后端把共享容器的文件缓存也算作内存压力，提前杀掉只用了 4–4.5 GiB 的 trial。0.4.1 改为按 UID 统计进程 RSS（上限 16 GiB）并扣掉可回收缓存，并发从 6 降到 2。这类监控是“发现就杀”，不是 cgroup 硬预留，所以没有向 Harbor 声明内存能力。
• Blender 在 PRoot 下偶发启动卡住：换新 UID 重试即可成功，根因未定位；后来只在可信初始化完成前允许重试，不能重放 solver 的工作。
• 两层超时要分清：blender_rl 的公平预算是累计活跃时间，Harbor 的 timeout_sec 只是墙钟兜底。解读“预算用尽”时要看仓库的 budget.json，不是 Harbor 的超时异常。
• blender_rl 的题包还没被 Harbor 独立跑过评分：两个组件里 Harbor verifier 都是关闭的，题包里的 tests/test.sh 能否在标准 Harbor 后端上直接运行，仍需单独验证。
• templates/harbor/ 故意不能运行：它的 test.sh 直接 exit 2。真实的 KUKA 题包由 package_kuka_harbor.py 生成。

术语表

延伸阅读

• Core concepts · Task overview · task.toml 字段
• Verifier · Separate verifier · Artifacts · Regrade
• Custom sandboxes · ATIF · RewardKit quick start
• 站内：blender_rl ② 求解 + runtime · KUKA 案例全流程 · 总览与系统耦合