第 14 章：运行 Job——harbor run 全指南
第 14 章：运行 Job——harbor run 全指南
Job 是 Harbor 的核心执行单元：一组 Trial 的编排容器，而每个 Trial 就是某个 agent 对某个任务的一次完整尝试。本章系统讲解
harbor run的全部常用 flags，按"任务来源、agent、沙箱、并发、过滤、输出"分组拆解，并说明这些 flags 底层如何汇成一个JobConfig。读完本章，你应当能针对任意评测场景拼出正确的harbor run命令。
14.1 Job 概念回顾
回忆第 1 章的核心概念：Task 是一个自带环境、指令、解法与验证器的评测单元；Trial 是"某个 agent 用某个模型在某个沙箱里做一次这个任务"的完整执行记录；Job 则是把一批 Trial 组织起来统一调度的编排单元。
harbor run 做的事情可以概括为一条流水线：
flowchart LR
A[harbor run] --> B[解析任务来源 -p/-d/-t/--repo]
B --> C[展开 Trial 列表 任务 x agent x attempts]
C --> D[并发调度 -n]
D --> E[agent 阶段]
E --> F[verifier 阶段]
F --> G[写入 jobs_dir -o/--job-name]理解这条流水线后，所有 flags 的作用位置就一目了然：它们分别控制流水线某一段的行为。
14.2 指定任务与数据集（-p / -d / -t）
Harbor 支持多种任务来源，每种来源对应一组 flags：
| 来源 | Flags | 说明 |
|---|---|---|
| 本地数据集 | -p <path/to/dataset> |
目录下包含多个任务 |
| 本地单任务 | -p <path/to/task> |
直接指向一个任务目录 |
| Harbor Hub 数据集 | -d <org/dataset>@<ref> |
从 Hub 拉取，@ref 可选 |
| Harbor Hub 任务 | -t <org/task>@<ref> |
从 Hub 拉取单个任务 |
| 自定义 registry | --registry-path 或 --registry-url |
搭配 -d 使用 |
| Git 仓库 | --repo <org/repo-name> 搭配 -p |
从 Git 仓库读取任务 |
对应示例命令：
# 本地数据集
harbor run -p "path/to/dataset" -a "agent" -m "model"
# 本地单任务
harbor run -p "path/to/task" -a "agent" -m "model"
# Harbor Hub 数据集与任务
harbor run -d "org/dataset@ref" -a "agent" -m "model"
harbor run -t "org/task@ref" -a "agent" -m "model"
# 自定义 registry（本地文件或 URL）
harbor run -d "dataset@version" --registry-path "path/to/registry.json" -a "agent" -m "model"
harbor run -d "dataset@version" --registry-url "url/to/registry.json" -a "agent" -m "model"
# Git 仓库中的任务
harbor run --repo "org/repo-name" -p "path/to/tasks" -a "agent" -m "model"自定义 registry 与 Git 仓库的细节分别见文档 Registries 与 Git repos 页面。
14.3 选择 Agent 与模型（-a / -m / --ak）
-a 选择预集成的 agent（如 oracle、claude-code、codex），-m 指定模型名。模型名通常带 provider 前缀，例如 anthropic/claude-haiku-4-5。运行 harbor run --help 可以查看所有可用 agent。
harbor run -a "agent" -m "model" --ak reasoning_effort=high--ak（agent kwargs）把集成特定的参数透传给 agent 构造器，上例即设置 reasoning_effort=high。自定义 agent 通过 import_path 接入，见第 9 章。
14.4 沙箱环境（-e）
-e 选择沙箱 provider，默认 docker，还支持 daytona、modal 等几十种预集成环境（见第 10 章）。相关 flags 还包括：
harbor run -p "path" -a "agent" -m "model" \
-e "sandbox" --allow-agent-host "host" --override-memory-mb "memory-mb"-e：指定沙箱类型；--allow-agent-host：在 agent 阶段的网络白名单中额外放行某个主机；--override-memory-mb：运行时覆盖任务声明的内存限制。
这些 flags 与 JobConfig 中 environment 字段的 CLI 入口一一对应。
14.5 并发与重试（-n / -k / -r）
harbor run -p "path" -a "agent" -m "model" \
-n "concurrent" -k "attempts" -r "retries"-n：最大并发 Trial 数，控制吞吐与成本的关键旋钮；-k：每个"任务 × agent"组合的尝试次数（n_attempts），统计 pass@k 时常用；-r：最大重试次数（max_retries），用于吸收偶发的超时与网络错误。
14.6 任务过滤（-l / -i / -x）
跑大数据集前先"切一小块"验证，是标准工作流：
harbor run -p "path" -a "agent" -m "model" \
-l "max-tasks" -i "some-*-glob-pattern" -x "some-name"-l：最多跑多少个任务；-i：按 glob 模式包含匹配的任务名；-x：排除指定名称的任务。
14.7 输出位置（-o / --job-name）
harbor run -p "path" -a "agent" -m "model" \
-o "jobs-dir" --job-name "job-name"-o 指定结果根目录（默认 jobs/），--job-name 指定本次 Job 的名称；省略时 Harbor 用当前时间 YYYY-MM-DD__HH-MM-SS 作为名称。
14.8 模拟用户（--user-agent / --user-model）
多轮交互任务需要一个"扮演用户"的 agent：
harbor run -p "path" -a "agent" -m "model" \
--user-agent "user-agent" --user-model "user-model"详见第 20 章的 Simulate a user 专题。
14.9 从 flags 到 JobConfig
CLI flags 只是语法糖：harbor run 在底层把所有 flags 组装成一个 JobConfig 对象再交给 runner。两种方式可以查看它：
# 运行前打印解析后的配置
harbor run --print-config ...
# 运行后查看落盘配置
cat /config.json 如果只想生成配置而不运行，用 harbor job init。已有的配置文件还可以与 CLI flags 组合，flags 覆盖配置中的同名值——这非常适合"一份基础配置 + 每次微调"的工作流：
harbor run -c "config.yaml" -m "another/model"对经常重复的评测设置，官方建议把配置保存并纳入版本控制（详见第 15 章）。
14.10 在 Harbor Hub 上运行（--launch）
加上 --launch，Job 会被托管到 Harbor Hub 云端执行：
harbor auth login
harbor run -d "org/name" -a "agent" -m "model" \
-n "concurrent" --one-off-secret "name=value" --launchHub 会负责：云端编排 Trial、执行每个 provider 的并发上限、在级联失败（如用量耗尽）时暂停、对限流做退避。之后你可以随时通过 UI 或 CLI 回来调试、触发重试、分享结果或监控进度。--one-off-secret 用于注入一次性密钥。
本章小结
- Job 是一组 Trial 的编排单元，Trial 是 agent 对任务的一次尝试，
harbor run是启动 Job 的唯一入口。 - 任务来源有六类：本地数据集/任务（
-p）、Hub 数据集/任务（-d/-t）、自定义 registry、Git 仓库（--repo）。 -a选 agent、-m选模型、--ak透传 agent 专属参数；harbor run --help可列出全部可用 agent。-n控制并发、-k控制尝试次数、-r控制重试，三者共同决定成本与统计口径。-l/-i/-x用于在正式评测前切小样本调试。- 所有 flags 底层都会汇成
JobConfig，可用--print-config或config.json查看与复用。 --launch把 Job 交给 Harbor Hub 云端托管，适合大规模、需要限流保护的评测。