第 15 章：Job 配置文件与轨迹加载

当评测规模从"一条命令"增长到"多 agent、多数据集、可复现实验"时，CLI flags 就不够用了。本章讲解 JobConfig——以 YAML 或 JSON 表达的全部 Job 配置，覆盖 job、retry、agents、user_agent、environment、verifier、datasets、tasks、metrics 九大字段组；随后介绍如何把历史轨迹加载进新的 agent 会话，以及用 --stream 实时观测运行中的 Job。

15.1 为什么用配置文件

harbor run -c "<config.yaml>" 直接加载配置文件。相对 flags 的三大优势：

• 一个文件支持多个 agents、多个 datasets、多个 tasks；
• 可提交版本控制，实验可复现；
• 与 CLI flags 可组合，flags 覆盖配置中的同名值。

最小示例：

# config.yaml
job_name: my-first-job
tasks:
  - path: ""
agents:
  - name: codex
    model_name: openai/gpt-6-astra
environment:
  type: docker

15.2 创建与校验配置

harbor job init ""             # 生成配置，接受与 harbor run 相同的 flags
harbor job init "" --full      # 生成包含所有字段的完整配置
harbor run --config "config.yaml" --print-config  # 查看解析后的配置
harbor job schema                           # 打印配置的 JSON Schema
harbor run --dry-run --config "config.yaml" # 校验配置、agent kwargs、凭据与任务来源，不真正运行

--dry-run 加上 --launch 则使用 Harbor Hub 的 schema 与校验规则。

15.3 顶层字段总览

所有顶层字段均可选，Harbor 按默认值行事：

字段	默认值	说明
job_name / jobs_dir	时间戳 / "jobs"	Job 名称（省略时用 YYYY-MM-DD__HH-MM-SS）/ 结果目录
n_attempts	1	每个"任务 × agent"组合的尝试次数
n_concurrent_trials	4	最大并发 Trial 数，至少为 1
debug / quiet	false	调试日志 / 抑制单 Trial 进度显示
retry	{}	重试与指数退避配置
environment	{}	所有 Trial 共享的环境 provider 配置
verifier	{}	所有 Trial 共享的 verifier 配置
agents	[{"name":"oracle"}]	被评测的 agent 列表
user_agent	null	可选的模拟用户 agent 与桥接配置
datasets / tasks	[]	展开为任务的数据集来源 / 单个任务来源
metrics	[]	追加到各数据集 metrics 之上的 Job 级指标
其他	[]	artifacts（Trial 后收集的环境路径）、extra_instruction_paths/extra_instructions（追加指令）、source_jobs（regrade 来源）

另有 5 个阶段级超时乘数：timeout_multiplier（全局，默认 1.0）及 agent_、verifier_、agent_setup_、environment_build_ 前缀的专属乘数（默认 null）；布尔项 install_only 为 true 时只跑 agent setup 并禁用验证。

15.4 完整示例

job_name: weekly-regression
jobs_dir: jobs
n_attempts: 3
n_concurrent_trials: 16

retry:
  max_retries: 3
  min_wait_sec: 1.0
  max_wait_sec: 60.0

agents:
  - name: claude-code
    model_name: anthropic/claude-sonnet-5
    n_concurrent: 4
    kwargs:
      reasoning_effort: high
  - name: codex
    model_name: openai/gpt-6-astra

environment:
  type: docker
  override_cpus: 4

datasets:
  - name: terminal-bench/core
    ref: v1.0

15.5 关键字段分组详解

agents

字段	说明
name / import_path	预集成 agent 名，或自定义 agent 的 module.path:ClassName
model_name	传给 agent 的模型标识
n_concurrent / concurrency_group	单 agent 并发上限（不得超过 n_concurrent_trials）/ 共享并发池，同组必须同值
load_trajectory / resume_trajectory	第一步前加载轨迹 / 多步任务步骤间恢复原生会话
override_timeout_sec / max_timeout_sec	替换 / 封顶 agent 超时
skills	本地技能目录、Git URL 或 org/name[@ref] 技能来源
kwargs / env	传给 agent 构造器的参数 / 仅 agent 阶段可见的环境变量
mcp_servers	提供给 agent 的 MCP 服务器列表

每个 mcp_servers[] 条目包含 name（必填）、transport（stdio/sse/streamable-http，默认 sse）、url（sse/http 类必填）、command 与 args（stdio 必填）。

retry

字段	默认值	说明
max_retries	0	最大重试次数
include_exceptions / exclude_exceptions	见下	可重试 / 永不重试的异常类名；排除优先于包含
wait_multiplier / min_wait_sec / max_wait_sec	1.0 / 1.0 / 60.0	指数退避乘数与间隔上下界

默认不可重试的异常包括 AgentTimeoutError、VerifierTimeoutError、RewardFileNotFoundError、RewardFileEmptyError、VerifierOutputParseError、ApiUsageLimitError、AgentSafetyRefusalError、AgentAuthenticationError、ModelNotFoundError。

environment 与 verifier

environment.type 默认 docker，可选 podman、daytona、e2b、modal 等数十种 provider。常用字段：force_build（强制重建）、delete（Trial 结束后删除环境，默认 true）、override_cpus/override_memory_mb/override_storage_mb/override_gpus（运行时覆盖资源）、env（沙箱内基线环境变量）、mounts（Docker Compose 长语法挂载，仅作用于 agent 环境）、kwargs（provider 专属参数）。资源与网络策略详见第 10、11 章。

verifier 字段组：override_timeout_sec、max_timeout_sec、include_logs/exclude_logs（reward 文件始终会下载）、env、import_path/kwargs（自定义 verifier）、disable（跳过验证；启用 install_only 时自动置 true）。

datasets 与 tasks

两者都支持本地路径、Hub 名称、registry 与 Git 来源，且约束相同：每个来源只能选一种形态。

字段	适用	说明
path	两者	本地目录；配 repo 时为仓库内隐式数据集路径
name	两者	Hub 上的 org/name，或自定义 registry 的裸名
ref / version	两者 / registry	Hub 的 tag/digest；registry 的版本（二者不可同设）
registry_url / registry_path	datasets	自定义 registry.json 的 URL / 路径
repo	datasets	Git 仓库简写或 URL，可带 @ref
task_names / exclude_task_names / n_tasks	datasets	glob 包含 / 排除任务名 / 过滤后的任务数上限
git_url / git_commit_id	tasks	Git 任务仓库与固定 commit
source	tasks	可选的来源标签，用于分组任务与指标

user_agent：模拟用户

user_agent 支持全部 agents[] 字段，另有：

• user_persona_path：定义模拟用户人设的文件路径；
• user_prompt_template_path：模拟用户使用的 Jinja2 提示词模板；
• bridge（配置 user_agent 时必填）：连接模拟用户与主 agent 的桥接器，当前仅支持 kind = "acp"，可选 prompt_path 与 kwargs。

metrics

Job 级 metrics[] 中的 type 字段支持 "sum"、"min"、"max"、"mean"、"uv-script"，默认 "mean"。

15.6 轨迹加载

Harbor 可以把一次历史运行轨迹装进新的 agent 会话。有两种加载视角、两种轨迹格式：

视角	配置方式	格式	支持 agent
Task 级	指令目录下的 trajectory.json	仅 ATIF	claude-code、codex
Run 级（Job 或 Trial）	--load-trajectory 或 agents[].load_trajectory	ATIF 与 native	claude-code、codex

Task 级：把名为 trajectory.json 的 ATIF 文件放在 instruction.md 同目录（多步任务放在第一步目录），agent 支持 ATIF 加载时 Harbor 自动装入。

Run 级：通过 CLI 或配置指定，且覆盖 Task 级加载。.json 后缀选择 ATIF 加载器，其他后缀选择 agent 的 native 加载器。以 native 轨迹为例：

harbor run \
  -p examples/tasks/hello-load-native-trajectory \
  -a claude-code -m opus -e daytona \
  --load-trajectory examples/tasks/hello-load-native-trajectory/environment/d7d4e19e-608d-44ef-b166-cd050ef274ba.jsonl

把 --load-trajectory 的路径换成某个 trajectory.json 即为 Run 级 ATIF 加载；写进配置文件则等价于 {"agents": [{"name": "codex", "load_trajectory": "path/to/trajectory.json"}]}。

native 与 ATIF 的差别：native 轨迹是 agent 专属的 .jsonl 会话文件（无损耗，但要求同一 agent；claude-code 存于 agent/sessions/projects/-app/<session-id>.jsonl，codex 存于 agent/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl，移动文件时须保留文件名）；ATIF 轨迹存于 agent/trajectory.json，是可移植格式——Harbor 会把它转换为目标 agent 的原生格式，因此 A agent 的轨迹可以"喂"给 B agent 当起点，转换保留受支持的消息、工具调用与结果，但可能省略 agent 专属细节。

三点注意：load_trajectory 不能与模拟 user_agent 组合；agent 通过 capabilities.load_native_trajectory 与 capabilities.load_atif_trajectory 声明能力，不支持的格式、缺失文件、非法 ATIF 会在启动前失败；加载只恢复会话内容，不恢复沙箱文件。多步任务中加载发生在第一步之前，配合 --resume-trajectory 时会话序列为 (load, resume, resume, ...)，否则为 (load, fresh, fresh, ...)。

15.7 --stream：实时观测运行中的 Job

加 --stream 可以在 Job 运行时观察 agent 行为、查看沙箱文件；另开终端启动查看器：

harbor run -t terminal-bench/build-cython-ext \
  -a claude-code -m anthropic/claude-sonnet-5 -e docker --stream

harbor view jobs   # 在另一个终端运行

• Trajectory 标签页：随着新步骤到达，实时跟随 agent 的动作、命令与结果；
• Stream 标签页：实时浏览沙箱文件与生成的产物，沙箱就绪后自动连接。

当前支持 Claude Code 与 Codex，沙箱支持 Daytona、Modal、Smol Machines、Tensorlake 或本地 Docker。浏览器与查看器需在同一台机器运行；Daytona 场景下凭据要对两者都可用。再加 --no-delete 可在运行结束后保留沙箱——调试时非常有用，但别忘了事后删除。

本章小结

• 配置文件支持多 agent、多数据集与版本控制；harbor run -c 加载，flags 可覆盖配置值。
• harbor job init 生成配置、harbor job schema 打印 JSON Schema、--dry-run 与 --print-config 用于不运行的校验。
• 顶层字段分九组：job、retry、agents、user_agent、environment、verifier、datasets、tasks、metrics，全部可选且有默认值。
• n_concurrent_trials 是全局并发上限，agents[].n_concurrent 不得超过它；重试通过异常类名精细控制。
• 轨迹加载有 Task 级（ATIF-only）与 Run 级（ATIF + native，覆盖 Task 级）两种视角；native 无损耗但绑定 agent，ATIF 可跨 agent 移植。
• 加载只恢复会话内容而不恢复沙箱文件，且不能与 user_agent 组合。
• --stream 配合 harbor view 提供 Trajectory 与 Stream 两个实时观测面板，--no-delete 便于事后调试。

延伸阅读

• Configs
• Loading trajectories
• Stream
• ATIF