> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-367.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Harbor

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

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

## 数据集结构

task 可以来自行为与 `harbor run -p` 相同的 `dataset_path`，也可以来自 [job 配置](#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 版本一致。

```yaml theme={null}
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](#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 插件](#安装-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 镜像里：

```bash wrap theme={null}
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，镜像版本就仍然是固定的：

```toml theme={null}
[environment]
docker_image = "registry.example.com/mirror/my-dataset:my-task@sha256:<digest>"
```

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

## 参数

通过 `--benchmark-params '{...}'` 传入 JSON 对象，也可以写在 `--config` YAML 的 `benchmark.params` 段中。合并优先级见 [Benchmark 概览](/zh/user_guide/modules/benchmarks/overview)。

<div style={{overflowX:'auto'}}>
  <table style={{minWidth:'1040px', width:'100%'}}>
    <colgroup>
      <col width="20%" />

      <col width="14%" />

      <col width="14%" />

      <col width="52%" />
    </colgroup>

    <thead>
      <tr><th style={{whiteSpace:'nowrap'}}>参数</th><th style={{whiteSpace:'nowrap'}}>类型</th><th style={{whiteSpace:'nowrap'}}>默认值</th><th>说明</th></tr>
    </thead>

    <tbody>
      <tr><td style={{whiteSpace:'nowrap'}}><code>dataset\_path</code></td><td>string</td><td>无</td><td>本地 Harbor 数据集目录，作用与 <code>harbor run -p</code> 相同。除非 <code>job\_config</code> 列出了 <code>datasets</code> 或 <code>tasks</code>，否则必填。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>job\_config</code></td><td>string 或 object</td><td>无</td><td>Harbor job 配置，可以是 YAML/JSON 路径或内联内容。见 <a href="#job-配置">Job 配置</a>。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>dataset\_name</code></td><td>string</td><td>无</td><td>数据集名称。它会替换结果目录名中的 Benchmark id，使不同数据集的结果分开存放；也会记录在每个 task 中。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>judge\_model</code></td><td>object</td><td>无</td><td>judge 模型配置 <code>{"{id, base_url, api_key, api_protocol, params}"}</code>，与其他使用 judge 的 Benchmark 相同。只有 <code>id</code> 必填；未设置的 <code>base\_url</code>、<code>api\_key</code>、<code>api\_protocol</code> 沿用被测模型的值。补全后的配置以 JSON 形式放在环境变量 <code>AGENTCOMPASS\_JUDGE\_MODEL</code> 中提供给 verifier。它覆盖 task 的 <code>\[verifier.env]</code>，又会被 job 级 <code>verifier.env</code> 覆盖。</td></tr>
    </tbody>
  </table>
</div>

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

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

```text theme={null}
<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`。

## 运行示例

```bash wrap theme={null}
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` 中写明自己的预构建镜像：

```bash wrap theme={null}
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"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.