harbor-cli

Harbor CLI 参考

Harbor CLI 用于管理完整的评测生命周期：创建任务、运行 Agent、查看结果。使用 uv tool install harbor 安装。全局选项：--version / -v。

有关每条命令的完整标志表（包括类型和默认值），请阅读 references/flags.md。

快速参考

命令	说明
harbor run	运行评测（harbor jobs start 的别名）
harbor jobs start	启动评测作业
harbor jobs resume	恢复中断的作业
harbor jobs summarize	为作业生成 AI 故障摘要
harbor trials start	运行单次试验（用于调试）
harbor trials summarize	为单次试验生成 AI 摘要
harbor datasets list	列出可用数据集
harbor datasets download	下载数据集
harbor adapters init	搭建新的基准测试适配器
harbor adapters review	对适配器进行结构检查和 AI 审查
harbor tasks init	搭建新任务
harbor tasks check	对任务进行 AI 质量评估
harbor tasks start-env	以交互方式启动任务环境
harbor tasks debug	分析任务中失败的试验
harbor tasks migrate	将 Terminal-Bench 任务转换为 Harbor 任务
harbor view	在网页 UI 中浏览作业/试验结果
harbor sweeps run	连续运行多轮评测
harbor traces export	以 ATIF 格式导出轨迹数据
harbor cache clean	清理 Docker 镜像和缓存目录
harbor admin	管理命令（隐藏）

harbor run / harbor jobs start

主要命令。harbor run 是 harbor jobs start 的别名。

默认值： Agent = oracle，n-concurrent = 1，环境 = docker，输出目录 = ./jobs。

基本标志：

标志	简写	说明
--path	-p	任务目录的本地路径
--dataset	-d	注册表中的数据集（例如，[email protected]）
--config	-c	作业配置 YAML/JSON 文件
--agent	-a	Agent 名称（默认值：oracle）。可重复使用
--model	-m	模型标识符。可重复使用
--n-concurrent	-n	并发试验数（默认值：1）
--env	-e	环境后端（默认值：docker）
--jobs-dir	-o	输出目录（默认值：./jobs）
--agent-env	--ae	向 Agent 传递环境变量：KEY=VALUE。可重复使用
--agent-kwarg	--ak	Agent 参数：key=value。可重复使用
--task-name	-t	按 glob 模式包含任务。可重复使用
--exclude-task-name	-x	按 glob 排除任务。可重复使用
--n-tasks	-l	要运行的最大任务数
--quiet	-q	不显示试验进度
--debug		启用调试日志
--dry-run		打印配置并退出
--disable-verification		跳过测试
--no-cache		跳过 Docker 构建缓存
--artifact		试验结束后从环境下载路径。可重复使用
--timeout-multiplier		缩放所有超时时间（默认值：1.0）

有关环境参数（--ek）、环境环境变量（--ee）、验证器参数（--vk）、编排器参数（--ok）、Agent 镜像、重试配置、轨迹导出以及各阶段超时倍数的其他标志，请参阅 references/flags.md。

示例

# Run local task with oracle (validates solution + tests)
harbor run -p ./my-task

# Run with a real agent
harbor run -p ./my-task -a claude-code -m anthropic/claude-sonnet-4-1

# Dataset evaluation with concurrency
harbor run -d [email protected] -a claude-code -m anthropic/claude-sonnet-4-1 -n 8

# Cloud environment
harbor run -d my-dataset -a claude-code -m anthropic/claude-sonnet-4-1 -e daytona

# From config file
harbor run -c eval-config.yaml

# Pass API key to agent
harbor run -p ./my-task -a claude-code -m anthropic/claude-sonnet-4-1 \
  --ae ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY

# Run subset of tasks
harbor run -d [email protected] -a claude-code -m anthropic/claude-sonnet-4-1 \
  -t "bash-*" -l 10

# Dry run
harbor run -d [email protected] -a claude-code -m anthropic/claude-sonnet-4-1 --dry-run

harbor jobs resume

恢复中断或未完成的作业。

harbor jobs resume -p ./jobs/my-job-2025-01-15
harbor jobs resume -p ./jobs/my-job -f AgentTimeoutError

标志	简写	说明
--job-path	-p	包含 config.json 的作业目录路径（必填）
--filter-error-type	-f	恢复前移除与此错误类型匹配的试验。可重复使用。默认值：CancelledError

harbor jobs summarize

为作业中的试验生成 AI 驱动的失败摘要。

harbor jobs summarize ./jobs/my-job
harbor jobs summarize ./jobs/my-job -m sonnet --all --overwrite

标志	简写	说明
job_path		作业目录或其父目录的路径（位置参数）
--model	-m	模型：haiku、sonnet、opus（默认：haiku）
--n-concurrent	-n	最大并发查询数（默认：5）
--all / --failed		分析全部试验或仅分析失败的试验（默认：--failed）
--overwrite		覆盖现有的 summary.md 文件

harbor trials start

运行单个试验。适用于调试和任务开发。

**与 harbor jobs start 的主要区别：**环境标志为 --environment-type（而非 --env），输出写入 --trials-dir（默认：./trials）。

标志	简写	说明
--path	-p	本地任务目录的路径
--config	-c	试验配置 YAML/JSON
--agent	-a	Agent 名称（默认：oracle）
--model	-m	Agent 使用的模型
--environment-type	-e	环境类型（默认：docker）
--trials-dir		输出目录（默认：./trials）
--agent-env	--ae	Agent 的环境变量：KEY=VALUE。可重复使用
--agent-kwarg	--ak	Agent 参数：key=value。可重复使用
--no-cleanup		试验结束后保留环境
--no-verify		跳过测试运行

完整标志列表（任务参数、Git 选项等）见 references/flags.md。

# Test with oracle (validates solution + tests)
harbor trials start -p ./my-task

# Test with real agent
harbor trials start -p ./my-task -a claude-code -m anthropic/claude-sonnet-4-1

# Keep container for inspection
harbor trials start -p ./my-task -a claude-code -m anthropic/claude-sonnet-4-1 --no-cleanup

oracle Agent 会在环境中运行 solution/solve.sh，随后验证器运行 tests/test.sh。如果 oracle 未获得 1.0 的奖励，则说明你的测试或解决方案存在问题。

harbor trials summarize

harbor trials summarize ./trials/my-trial
harbor trials summarize ./trials/my-trial -m sonnet --overwrite

标志	简写	说明
trial_path		试验目录的路径（位置参数）
--model	-m	模型：haiku、sonnet、opus（默认：haiku）
--overwrite		覆盖现有的 summary.md

harbor datasets

harbor datasets list

harbor datasets list
harbor datasets list --registry-url https://custom-registry.example.com
harbor datasets list --registry-path ./local-registry.json

--registry-url 和 --registry-path 标志不能同时使用。默认使用 Harbor 的公共注册表。

harbor datasets download

harbor datasets download [email protected]
harbor datasets download [email protected] -o ./my-tasks --overwrite

标志	简写	说明
DATASET		名称或 name@version（位置参数）
--output-dir	-o	下载目录（默认：~/.cache/harbor/tasks）
--overwrite		即使已有缓存也重新下载

harbor adapters

harbor adapters init

harbor adapters init my-benchmark

交互式向导会提示输入基准名称、适配器 ID、类名、描述、源 URL 和许可证。它会使用模板文件创建适配器目录。

harbor adapters review

harbor adapters review -p adapters/my-benchmark
harbor adapters review -p adapters/my-benchmark --skip-ai -o report.md

harbor tasks

harbor tasks init

harbor tasks init my-task
harbor tasks init my-task -p ./custom-tasks

标志	简写	说明
name		任务名称（位置参数）
--tasks-dir	-p	输出目录（默认：.）
--no-pytest		在 test.sh 中跳过 pytest
--no-solution		跳过 solution 目录
--include-canary-strings		添加反作弊金丝雀字符串
--include-standard-metadata		在 task.toml 中添加完整元数据模板

harbor tasks check

基于评分标准进行 AI 驱动的质量评估。

harbor tasks check ./my-task
harbor tasks check ./my-task -m opus -o results.json
harbor tasks check ./my-task -r custom-rubric.toml

标志	简写	说明
task		任务名称或路径（位置参数）
--model	-m	模型：sonnet、opus、haiku（默认：sonnet）
--output-path	-o	将 JSON 结果写入此处
--rubric_path	-r	自定义评分标准（.toml、.yaml、.yml、.json）

harbor tasks start-env

以交互方式启动任务环境，供手动检查。

harbor tasks start-env -p ./my-task
harbor tasks start-env -p ./my-task -e daytona
harbor tasks start-env -p ./my-task --agent claude-code -m anthropic/claude-sonnet-4-1

标志	简写	描述
--path	-p	任务目录路径
--env	-e	环境类型（默认：docker）
--all	-a	包含解决方案和测试（默认：true）
--interactive / --non-interactive	-i	交互式 Shell（默认：true）
--agent		要在环境中安装的 Agent
--model	-m	Agent 使用的模型

完整标志列表见 references/flags.md。

harbor tasks debug

使用 AI 分析任务失败的试验。

harbor tasks debug my-task-id -m sonnet
harbor tasks debug my-task-id --job-id my-job --jobs-dir ./jobs

标志	简写	描述
task_id		任务 ID（位置参数）
--model	-m	分析所用的模型
--job-id		要分析的特定作业
--jobs-dir		包含作业的目录

harbor tasks migrate

将 Terminal-Bench 任务转换为 Harbor 格式。

harbor tasks migrate -i ./old-tasks -o ./harbor-tasks
harbor tasks migrate -i ./old-tasks -o ./harbor-tasks --cpus 2 --memory-mb 4096

标志	简写	描述
--input	-i	Terminal-Bench 任务目录或其父目录
--output	-o	输出目录
--cpus		覆盖所有任务的 CPU 数量
--memory-mb		覆盖内存（MB）
--storage-mb		覆盖存储空间（MB）
--gpus		覆盖 GPU 数量

harbor view

在 Web UI 中浏览作业/试验结果。

harbor view ./jobs/my-job
harbor view ./jobs --port 9000
harbor view ./jobs --dev

标志	简写	描述
folder		包含轨迹的目录（位置参数）
--port	-p	端口或端口范围（默认：8080-8089）
--host		绑定主机（默认：127.0.0.1）
--dev		热重载开发模式
--build		强制重新构建查看器
--no-build		跳过自动构建

显示作业摘要、各试验的奖励值、Agent 轨迹和测试输出。

harbor sweeps run

连续运行多轮扫描。每轮扫描都会剔除至少有一次成功的任务，将精力集中在其余失败任务上。

harbor sweeps run -c sweep-config.yaml
harbor sweeps run -c sweep-config.yaml --max-sweeps 5 --trials-per-task 3
harbor sweeps run -c sweep-config.yaml --hint "Try grep to find the file first"

标志	简写	描述
--config	-c	作业配置文件（YAML/JSON）
--max-sweeps		最大扫描轮数（默认：3）
--trials-per-task		每轮扫描中每个任务的试验次数（默认：2）
--hint		传递给 Agent kwargs 的提示字符串
--hints-file		将任务名称映射到提示的 JSON 文件
--push / --no-push		将导出的数据集推送到 HF Hub

其他导出标志见 references/flags.md。

harbor traces export

将 ATIF 轨迹导出为训练数据集。

harbor traces export -p ./jobs/my-job
harbor traces export -p ./trials --filter success --push --repo my-org/traces
harbor traces export -p ./jobs/my-job --sharegpt --episodes last

标志	简写	描述
--path	-p	试验目录或包含试验的根目录路径
--recursive / --no-recursive		递归搜索（默认：递归）
--episodes		每个试验导出 all 或 last（默认：all）
--filter		success、failure 或 all（默认：all）
--sharegpt / --no-sharegpt		ShareGPT 格式的对话
--push / --no-push		推送到 Hugging Face Hub
--repo		HF 仓库 ID（org/name）

其他标志（--subagents、--instruction-metadata、--verifier-metadata、--verbose）见 references/flags.md。

harbor cache clean

移除 Harbor Docker 镜像和 ~/.cache/harbor。

harbor cache clean
harbor cache clean --force
harbor cache clean --dry
harbor cache clean --no-docker      # Only clean ~/.cache/harbor
harbor cache clean --no-cache-dir   # Only clean Docker images

标志	简写	描述
--force	-f	跳过确认
--dry		预览但不删除
--no-docker		跳过移除 Docker 镜像
--no-cache-dir		跳过移除 ~/.cache/harbor

harbor admin upload-images

构建任务 Docker 镜像并推送到容器注册表。对于预构建镜像工作流，会使用 docker_image 更新 task.toml。此命令不会显示在 harbor --help 中，但功能完整可用。

harbor admin upload-images -r my-registry.io --tag 20260317
harbor admin upload-images -r my-registry.io --dry-run -f "bash-*"

主要标志：--tasks-dir / -t（默认值：tasks）、--registry / -r（必填）、--tag（默认值：今天的 YYYYMMDD）、--dry-run、--filter / -f、--push/--no-push（默认推送）、--delete/--no-delete、--parallel / -n（默认值：1）、--update-config/--no-update-config、--override-config/--no-override-config。完整详情请参阅 references/flags.md。

支持的 Agent

Agent	CLI 值	备注
Oracle	oracle	运行 solution/solve.sh。默认 Agent
Nop	nop	不执行任何操作（基线）
Claude Code	claude-code	需要 ANTHROPIC_API_KEY
Aider	aider
Codex	codex
Cline CLI	cline-cli	模型格式：provider:model-id
Cursor CLI	cursor-cli
Gemini CLI	gemini-cli	需要 GOOGLE_API_KEY 或 GEMINI_API_KEY
Goose	goose	模型格式：provider/model_name
Mini SWE-agent	mini-swe-agent
SWE-agent	swe-agent
OpenCode	opencode
OpenHands	openhands	需要 LLM_API_KEY 和 LLM_MODEL
OpenHands SDK	openhands-sdk
Qwen Coder	qwen-coder
Terminus	terminus	Harbor 内置 Agent
Terminus 1	terminus-1
Terminus 2	terminus-2

环境后端

后端	CLI 值	描述
Docker	docker	默认值。本地容器
Daytona	daytona	支持 Docker-in-Docker 的云沙盒
E2B	e2b	E2B 云沙盒
GKE	gke	Google Kubernetes Engine
Modal	modal	支持 GPU 的无服务器环境
Runloop	runloop	Runloop 云环境

注意：harbor run 使用 --env / -e。harbor trials start 使用 --environment-type / -e。

常见工作流

创建并测试新任务

harbor tasks init my-task
# Edit: task.toml, instruction.md, Dockerfile, tests/test.sh, solution/solve.sh
harbor tasks check ./my-task
harbor trials start -p ./my-task                    # oracle validates tests
harbor trials start -p ./my-task -a claude-code -m anthropic/claude-sonnet-4-1
harbor view ./trials

运行基准评估

harbor datasets list
harbor datasets download [email protected]
harbor run -d [email protected] -a claude-code -m anthropic/claude-sonnet-4-1 -n 8
harbor view ./jobs
harbor traces export -p ./jobs/my-job --push --repo my-org/traces

调试失败的任务

harbor tasks start-env -p ./my-task         # interactive shell in the container
# Inside: bash /tests/test.sh && bash /solution/solve.sh
harbor tasks debug my-task-id -m sonnet     # AI analysis of failures
harbor trials start -p ./my-task            # re-test with oracle

恢复失败的作业

harbor jobs resume -p ./jobs/my-job-2025-01-15
harbor jobs resume -p ./jobs/my-job -f AgentTimeoutError
harbor jobs summarize ./jobs/my-job

常见问题

API 密钥： 大多数 Agent 需要通过 --ae 传入密钥。Claude Code 需要 ANTHROPIC_API_KEY，OpenHands 需要 LLM_API_KEY，Goose 需要特定提供商的密钥。如果 Agent 立即失败，请检查密钥。

Docker 必须处于运行状态。 Harbor 使用 Docker 创建沙盒环境。大量并发试验可能导致网络资源耗尽并引发故障——运行 harbor cache clean 会有所帮助。

模型名称格式因 Agent 而异。 Claude Code 使用 anthropic/claude-sonnet-4-1，Cline CLI 使用 provider:model-id（例如 openrouter:anthropic/claude-opus-4.5），Goose 使用 provider/model_name。关于模型格式的 ValueError 通常表示格式不适用于该 Agent。

--env 与 --environment-type： harbor run 使用 --env / -e。harbor trials start 使用 --environment-type / -e。两者的短标志相同，长标志不同。

默认 Agent 是 oracle。 忘记指定 -a 会使用 oracle Agent，它只会运行 solve.sh。这适用于任务验证，但不适用于实际评估。

调试时使用 --no-cleanup。 将此标志传给 harbor trials start，可在试验失败后让容器继续运行，以便检查容器。

重试默认会跳过常见错误。 --retry-exclude 的默认值为 AgentTimeoutError、VerifierTimeoutError、RewardFileNotFoundError、RewardFileEmptyError、VerifierOutputParseError。这些错误通常表示任务存在问题，而非暂时性故障。