Harbor

harbor Benchmark 用来运行 Harbor task 格式的本地数据集。指定数据集目录或传入 Harbor job 配置后，AgentCompass 会加载每个 task、启动对应镜像、通过所选 Harness 运行 agent，再用 task 自己的 Harbor verifier 打分。不需要为每个数据集单独写适配代码。

验证流程按 Harbor 自带的 Verifier 实现，同一个 task 在这里和 harbor run 下的得分一致。唯一的区别是失败 task 参与平均的方式，见分数。

​

数据集结构

task 可以来自行为与 harbor run -p 相同的 dataset_path，也可以来自 job 配置中的 datasets 和 tasks。数据集目录中所有被 Harbor 识别为 task 的子目录都会加入，其他子目录会被跳过。

每个 task 目录需要有 task.toml、instruction.md 和 environment/ 目录。除非禁用验证，否则即使用 verifier 类替代默认 verifier，也需要有 tests/test.sh，与 Harbor 一致。Harbor 的 environment/、solution/ 等文件可以保留。AgentCompass 不会构建 environment/Dockerfile，也不会执行 environment/ 下的其他文件。

​

运行流程

1. 镜像和工作目录。 每个 task 使用自己的 environment.docker_image。--env-params 里的 setup.image 会替换本次运行中所有 task 的镜像。task 没有 docker_image 且未设置 setup.image 时，运行会在启动任何环境之前失败。工作目录取 environment.workdir，没有设置时取 environment/Dockerfile 最后一个字面量 WORKDIR；但镜像被 setup.image 替换时不再使用 Dockerfile 的值。
2. 就绪检查。 task 声明了 [environment.healthcheck] 时，会按 Harbor 的 Docker 式重试规则反复执行，直到通过，然后才启动 agent。
3. Agent。 agent 收到 instruction.md。超时取 task 的 agent.timeout_sec，并像 Harbor 一样由 job 配置调整。run_timeout_multiplier 等执行参数会在此基础上继续生效。
4. 验证。 先清空 /tests 和 /logs/verifier，把 task 的 tests/ 上传到 /tests。然后给 /tests/test.sh 加上可执行权限并直接执行，由 shebang 决定解释器。stdout 和 stderr 合并写入 /logs/verifier/test-stdout.txt。
5. 读取 reward。 忽略 test.sh 的退出码。先读 /logs/verifier/reward.json，没有再读 reward.txt。reward.json 里的每个值都必须是有限数值。

如果 task 设置了 [verifier] environment_mode = "separate" 或 [verifier.environment]，会在一个新环境中验证。agent 环境里的 /logs/artifacts 和声明的 [[artifacts]] 会先恢复到新环境中。

​

分数

主指标 score 按 Harbor 的主 reward 规则取值：

reward 内容	score
含有 reward	取该值
只有一个 key，例如 {"accuracy": 0.8}	取该值（0.8）
多个 key，且都不叫 reward	没有分数：task 正常完成，但不产生 score

所有 reward key 都保存在 task 结果的 extra.eval_raw_data.rewards 中。reward 文件缺失、为空或不是数值时，记为评测错误。

Harbor 计算平均分时把失败的 trial 按 0 计入，AgentCompass 只对评测成功的 task 求平均。与 Harbor 的结果对账时，需要同时看错误数。

​

Job 配置

job_config 接收 Harbor job 配置，也就是传给 harbor run -c 的文件。可以传入 YAML 或 JSON 文件路径，也可以直接内联传入同等内容。已安装的 Harbor 包会用自己的 JobConfig 模型进行验证，因此可用的配置结构始终与当前 Harbor 版本一致。

datasets:
  - path: /path/to/harbor-dataset
    task_names: ["web-*"]
    exclude_task_names: ["web-flaky-*"]
timeout_multiplier: 1.5
verifier:
  import_path: my_verifier:MyVerifier
  env:
    JUDGE_MODEL: my-judge-model
environment:
  override_cpus: 4

配置像 Harbor 一样分层，优先级从低到高依次为：

1. task 的 task.toml。
2. job 配置，相当于 Harbor 的 job 文件。
3. 本次运行自己的 --env-params 和 --execution-params，相当于 Harbor 的命令行参数。

AgentCompass 会应用 job 配置中的以下字段：

字段	作用
datasets[].path、task_names、exclude_task_names、n_tasks	从本地数据集中选择 task。与 Harbor 一样，task_names 没有匹配项时会报错。
tasks[].path	添加一个本地 task 目录。
verifier	配置验证，见 Verifier。
agents[0].override_timeout_sec、max_timeout_sec	替换 task 的 agent.timeout_sec，或给它设上限。
agents[0].env	agent 阶段使用的环境变量。
environment.override_cpus、override_memory_mb、override_storage_mb、override_gpus	替换 task 的资源配置。
environment.env	整个 task 使用的环境变量，覆盖 task 的 [environment.env]。
timeout_multiplier、agent_timeout_multiplier、verifier_timeout_multiplier、environment_build_timeout_multiplier	与 Harbor 一样，对相应的超时时间应用倍数。
artifacts	agent 完成后收集的文件，在 task 的 [[artifacts]] 之外追加。
extra_instruction_paths	将指定文件的文本追加到每条指令。

部分字段会改变结果的含义，因此 AgentCompass 会在启动任何环境之前拒绝这些配置：

• n_attempts 不是 1。请改用执行参数 k。
• agents 中有多个条目。一次运行只使用一个 Harness。
• datasets 或 tasks 指向 registry、包或 Git 源，而不是本地路径。
• install_only: true。

对于其他所有已声明但未应用的字段，AgentCompass 会报告后继续运行，包括 agents[].name 和 model_name、environment.type、n_concurrent_trials 和 retry。这些设置分别由本次运行自己的 Harness、Model、--env provider 和执行参数决定。

​

Verifier

verifier 段为本次运行的所有 task 配置验证：

字段	作用
import_path	用于替代 tests/test.sh 的 Harbor BaseVerifier 类，格式为 module:Class。该类必须能在运行 AgentCompass 的进程中导入，见安装 verifier 插件。
kwargs	传给该类的关键字参数。
env	verifier 的环境变量，覆盖 task 的 [verifier.env]。
override_timeout_sec / max_timeout_sec	替换 task 的 verifier.timeout_sec，或给它设上限。Harbor 默认 600 秒。
include_logs / exclude_logs	与 Harbor 一样传给 verifier。
disable	跳过验证，task 完成但没有分数。

导入的 verifier 会拿到三样东西：对应 task 目录的 Harbor Task；位于运行输出目录 harbor-trials/<task_id>/<uuid>/ 下的 TrialPaths；以及一个环境适配器，它会在 AgentCompass 沙箱中执行 verifier 发出的命令。

与 Harbor 一样，verifier 类本身运行在宿主机上。它发出的命令（例如执行 tests/test.sh）通过适配器在沙箱中执行；读取 reward 之前，它会把 /logs/verifier 下载到自己的 TrialPaths。宿主机上的步骤（例如调用 LLM judge）需要宿主机能访问网络，与沙箱的网络策略无关。

​

安装 verifier 插件

与 Harbor 一样，提供 import_path 的包需要自行安装，装到运行 AgentCompass 的 Python 环境中，而不是 task 镜像里：

uv pip install --python "$(command -v python3)" /path/to/verifier-project

verifier 类在加载 task 时导入。包没有安装，或者类不是 Harbor BaseVerifier 的子类，都会在启动任何环境之前让运行失败。默认的 tests/test.sh verifier 不需要任何宿主机包。

Harbor 不支持按 task 配置 import_path。如果数据集里不同 task 的打分方式不同，可以写在各自的 tests/test.sh 里，或者用一个读取各 task 自身文件来决定打分方式的 verifier 类。两种都做不到的数据集，需要拆成多次运行。

task 的 [verifier.env] 和 [environment.env]，以及 job 配置各 env 映射中的环境变量模板 ${NAME} 和 ${NAME:-default}，都会从宿主机环境解析。变量缺失且没有默认值时，task 失败，与 Harbor 一致。

​

使用镜像副本

task.toml 中的 environment.docker_image 是每个 task 唯一的镜像来源。如果所用的 Environment provider 无法访问数据集原来的镜像仓库，请把镜像复制到它能访问的仓库，再把每个 task 的 docker_image 改成副本地址。保留 digest，镜像版本就仍然是固定的：

[environment]
docker_image = "registry.example.com/mirror/my-dataset:my-task@sha256:<digest>"

请修改数据集的副本，而不是上游仓库本身，以便保留原来的镜像名。

​

参数

通过 --benchmark-params '{...}' 传入 JSON 对象，也可以写在 --config YAML 的 benchmark.params 段中。合并优先级见 Benchmark 概览。

参数	类型	默认值	说明
dataset_path	string	无	本地 Harbor 数据集目录，作用与 harbor run -p 相同。除非 job_config 列出了 datasets 或 tasks，否则必填。
job_config	string 或 object	无	Harbor job 配置，可以是 YAML/JSON 路径或内联内容。见 Job 配置。
dataset_name	string	无	数据集名称。它会替换结果目录名中的 Benchmark id，使不同数据集的结果分开存放；也会记录在每个 task 中。
judge_model	object	无	judge 模型配置 ，与其他使用 judge 的 Benchmark 相同。只有 id 必填；未设置的 base_url、api_key、api_protocol 沿用被测模型的值。补全后的配置以 JSON 形式放在环境变量 AGENTCOMPASS_JUDGE_MODEL 中提供给 verifier。它覆盖 task 的 [verifier.env]，又会被 job 级 verifier.env 覆盖。

sample_ids 从解析出的 task 中按目录名精确选择；指定的名字不存在时直接报错。所有数据集和 task 中的 task 目录名必须唯一。Metric Contract 把标量 score 声明为主指标，k>1 时请使用 avg。见指标与聚合。

单独运行时，结果目录按模型、Benchmark 和 Harness 命名。所有 Harbor 数据集都使用同一个 Benchmark id harbor，所以请设置 dataset_name，让各数据集的结果分开存放。例如设置 "dataset_name": "my-dataset" 后，结果写到：

<results_dir>/<model>_my-dataset_<harness>/<run_id>/

复用功能只在同一个目录中查找以往的运行，因此只会复用 dataset_name 相同的结果。

​

暂不支持

• 多步 task（[[steps]]）：加载时直接报错。
• 构建 environment/Dockerfile 或 environment/docker-compose.yaml：每个 task 都需要在 environment.docker_image 中写明预构建镜像。只提供 Dockerfile 的数据集，需要先自行构建并推送镜像，再给每个 task 加上 docker_image。
• 以 agent.user / verifier.user 指定的用户运行 agent 或 verifier：命令以镜像的默认用户执行，loader 会把这两个字段报告为未映射。
• 通过 oracle harness 运行 solution/solve.sh。

​

运行示例

agentcompass run \
  harbor \
  openhands \
  "$MODEL_NAME" \
  --env docker \
  --benchmark-params '{
    "dataset_path": "/path/to/harbor-dataset",
    "sample_ids": ["hello-world"]
  }' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat

由 Harbor job 配置文件驱动、使用已安装的 verifier 类和 LLM judge 打分的运行。每个 task 在 docker_image 中写明自己的预构建镜像：

agentcompass run \
  harbor \
  openclaw \
  "$MODEL_NAME" \
  --env docker \
  --benchmark-params '{
    "job_config": "/path/to/job.yaml",
    "judge_model": {
      "id": "your-judge-model",
      "base_url": "https://your-judge-endpoint/v1",
      "api_key": "${JUDGE_API_KEY}",
      "api_protocol": "openai-chat"
    }
  }' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"