> ## Documentation Index > Fetch the complete documentation index at: https://agent-compass.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` 加上可执行权限，与 Harbor 一样在 bash 中直接执行：首行有效的 shebang 决定解释器，首行不是 shebang 的脚本（例如 shebang 上方有 canary 注释）由 bash 执行。镜像中没有 bash 时改用 `sh`。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` 中。 verifier 运行结束却没有留下有效 reward（reward 文件缺失、为空或不是数值）时，与 Harbor 一样按失败计分：`score` 为 `0`，`passed` 为 `false`，并记录 WARNING `verifier_result_invalid`。该 task 仍计入分母。 如果是评测环境本身出了问题（例如读取 reward 或执行 `test.sh` 时沙箱命令、文件传输失败），则记为 FATAL：有重试预算时会重试；重试后仍失败，该 task 失效，整次运行没有正式分数。verifier 代码里其他意外异常记为 ERROR，该次尝试没有分数。完整 traceback 保存在 `artifacts.execution_diagnostics` 中。各严重级别的含义见[错误处理](/zh/user_guide/using_agentcompass/error_handling)。 ### 通过率与 pass at k 只有当每个 trial 的 reward 都只有一个 key 且值为 `0` 或 `1` 时，Harbor 才计算 pass\@k。AgentCompass 对每次尝试应用相同规则：这样的 reward 还会产生二值指标 `passed`，显示为 Pass Rate；有多个 reward key 或值为小数时，只产生 `score`。 | reward 内容 | `score` | `passed` | | - | - | - | | `{"reward": 1}` | `1.0` | `true` | | `{"accuracy": 0}` | `0.0` | `false` | | `{"reward": 0.5}` | `0.5` | 无 | | `{"reward": 1, "accuracy": 0.8}` | `1.0` | 无 | 每个 task 只运行一次时，主指标是 `score`，`passed` 一同报告。用 `avg` 策略运行多次即可得到 pass\@k： ```bash theme={"system"} --k 3 --attempt-strategy avg ``` 此时 `metrics.json` 的主指标是 `score` 的 avg\@3，另外报告 `passed` 的 avg\@3 和 pass\@3。只要某个 task 有一次尝试的 `passed` 为 true，它在 pass\@3 中就算通过。对于 reward 只有通过/不通过的数据集，这与 Harbor 在每个 task 运行三个 trial 时的 pass\@3 相同。 如需让通过/不通过成为主指标，请把 `primary_metric` 设为 `passed`。此时通过结果作为主指标 `correct`（Pass Rate）报告，Harbor 的主 reward 作为 `reward`（Score）报告。这也会启用 `pass` 策略，即某个 task 一旦有一次尝试通过就停止后续尝试： ```bash wrap theme={"system"} agentcompass run \ harbor \ mini_swe_agent \ "$MODEL_NAME" \ --env docker \ --benchmark-params '{ "dataset_path": "/path/to/harbor-dataset", "primary_metric": "passed" }' \ --k 3 \ --attempt-strategy pass \ --model-base-url "$MODEL_BASE_URL" \ --model-api-key "$MODEL_API_KEY" \ --model-api-protocol openai-chat ``` `pass` 策略只报告 `correct` 的 pass\@3，并省去通过之后的尝试。在 `primary_metric` 为 `passed` 时使用 `--attempt-strategy avg`，则会同时把 `correct` 的 avg\@3 和 pass\@3 作为主指标报告。只有当数据集的 verifier reward 是通过/不通过时才应使用 `passed`：小数 reward 没有通过结果，这样的 task 没有主指标值。 没有留下有效 reward 的尝试与 Harbor 一样按未通过计入 pass\@k。AgentCompass 与 Harbor 有两点不同。第一，评测环境故障在 AgentCompass 中是 FATAL：该次尝试会被重试，重试后仍失败则整个 task 失效，而不是按 `0` 计入；对比前请确认运行没有失效的 task。第二，只要有一个 trial 的 reward 是小数，Harbor 就不为整个 job 计算 pass\@k，而 AgentCompass 按 task 判断。详见 [指标与聚合](/zh/user_guide/other_features/results/metrics_aggregation)。 ## Job 配置 `job_config` 接收 Harbor job 配置，也就是传给 `harbor run -c` 的文件。可以传入 YAML 或 JSON 文件路径，也可以直接内联传入同等内容。已安装的 Harbor 包会用自己的 `JobConfig` 模型进行验证，因此可用的配置结构始终与当前 Harbor 版本一致。各字段及其含义见 [Harbor job 配置](https://docs.harborframework.com/jobs/configs)；本节只说明 AgentCompass 如何应用它们。 配置像 Harbor 一样分层，优先级从高到低依次为： 1. 本次运行自己的 `--env-params` 和 `--execution-params`，相当于 Harbor 的命令行参数。 2. job 配置，相当于 Harbor 的 job 文件。 3. task 的 `task.toml`。 环境变量也按这个顺序覆盖。例如，`--env-params` 的 `evaluation_env_variables` 中设置的 verifier 变量会覆盖 job 配置 `verifier.env` 中的同名变量，后者又会覆盖 task 的 `[verifier.env]`。 AgentCompass 会应用 job 配置中的以下字段： | 部分 | 应用的字段 | | - | - | | `datasets` | `path`、`task_names`、`exclude_task_names`、`n_tasks` | | `tasks` | `path` | | `verifier` | 全部字段，见 [Verifier](#verifier) | | `agents[0]` | `override_timeout_sec`、`max_timeout_sec`、`env` | | `environment` | `override_cpus`、`override_memory_mb`、`override_storage_mb`、`override_gpus`、`env` | | 超时 | `timeout_multiplier`、`agent_timeout_multiplier`、`verifier_timeout_multiplier`、`environment_build_timeout_multiplier` | | 其他 | `artifacts`、`extra_instruction_paths` | `dataset_path` 中的 task 会与 `datasets`、`tasks` 中的 task 合并，task 目录名在其中必须唯一。 部分字段会改变结果的含义，因此 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 和执行参数决定。`datasets` 和 `tasks` 中的下载选项 `overwrite`、`download_dir` 和 `source` 会被直接忽略。 ### Verifier job 配置中的 `verifier` 段为本次运行的所有 task 配置验证，各字段见 [Harbor job 配置](https://docs.harborframework.com/jobs/configs#verifier)。其中 `env` 覆盖 task 的 `[verifier.env]`；设置 `disable` 后，task 完成但没有分数。 如需不写 job 配置就设置 verifier 的环境变量，请使用 Environment 的 `evaluation_env_variables`。它们只作用于验证命令，同时覆盖 task 的 `[verifier.env]` 和 job 配置的 `verifier.env`，其中的 `${NAME}` 引用从宿主机解析： ```bash theme={"system"} --env-params '{ "evaluation_env_variables": { "EVAL_MODEL": "your-judge-model", "EVAL_BASE_URL": "https://your-judge-endpoint/v1", "EVAL_API_KEY": "${JUDGE_API_KEY}" } }' ``` 设置 `import_path` 后，会用一个 Harbor `BaseVerifier` 类替代 `tests/test.sh`；该类必须能在运行 AgentCompass 的进程中导入（见[安装 verifier 插件](#安装-verifier-插件)）。 导入的 verifier 会拿到三样东西：对应 task 目录的 Harbor `Task`；位于运行输出目录 `harbor-trials///` 下的 `TrialPaths`；以及一个环境适配器，它会在 AgentCompass 沙箱中执行 verifier 发出的命令。 与 Harbor 一样，verifier 类本身运行在宿主机上。它发出的命令（例如执行 `tests/test.sh`）通过适配器在沙箱中执行；读取 reward 之前，它会把 `/logs/verifier` 下载到自己的 `TrialPaths`。宿主机上的步骤（例如调用 LLM judge）需要宿主机能访问网络，与沙箱的网络策略无关。 ### 安装 verifier 插件 与 Harbor 一样，提供 `import_path` 的包需要自行安装，装到运行 AgentCompass 的 Python 环境中，而不是 task 镜像里： ```bash wrap theme={"system"} 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={"system"} [environment] docker_image = "registry.example.com/mirror/my-dataset:my-task@sha256:" ``` 请修改数据集的副本，而不是上游仓库本身，以便保留原来的镜像名。 ## 参数 通过 `--benchmark-params '{...}'` 传入 JSON 对象，也可以写在 `--config` YAML 的 `benchmark.params` 段中。合并优先级见 [Benchmark 概览](/zh/user_guide/modules/benchmarks/overview)。
参数类型默认值说明
`dataset_path`string无本地 Harbor 数据集目录，作用与 `harbor run -p` 相同。除非 `job_config` 列出了 `datasets` 或 `tasks`，否则必填。
`job_config`string 或 object无Harbor job 配置，可以是 YAML/JSON 路径或内联内容。见 [Job 配置](#job-配置)。
`dataset_name`string无数据集名称。它会接在结果目录名中的 Benchmark id 之后，使不同数据集的结果分开存放；也会记录在每个 task 中。
`primary_metric`string`"score"`主指标：`score` 为 Harbor 的主 reward；`passed` 为单个 `0`/`1` reward 的通过结果，以 `correct` 报告。设为 `passed` 时还会启用 `pass` 尝试策略。见 [通过率与 pass at k](#通过率与-pass-at-k)。
`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={"system"} /_harbor_my-dataset_// ``` 复用功能只在同一个目录中查找以往的运行，因此只会复用 `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={"system"} 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 配置文件驱动的运行。job 配置的 `verifier` 段可以指定已安装的 verifier 类，并在 `env` 中设置它读取的变量，例如 LLM judge 的地址，见 [Verifier](#verifier)。每个 task 在 `docker_image` 中写明自己的预构建镜像： ```bash wrap theme={"system"} agentcompass run \ harbor \ openclaw \ "$MODEL_NAME" \ --env docker \ --benchmark-params '{"job_config": "/path/to/job.yaml"}' \ --model-base-url "$MODEL_BASE_URL" \ --model-api-key "$MODEL_API_KEY" ``` ### 把 SWE Atlas 作为 Harbor 数据集运行 [SWE Atlas](https://github.com/scaleapi/SWE-Atlas) 的每个榜单都是一个 Harbor 数据集，因此 `harbor` 可以直接运行本地克隆。下面的示例用 mini-SWE-agent 和该榜单的官方 SWE Atlas 配置运行 Codebase QnA 榜单，并像官方榜单一样每个 task 运行三次，报告 pass\@3。SWE Atlas 的评分脚本从 `EVAL_MODEL`、`EVAL_BASE_URL` 和 `EVAL_API_KEY` 读取 judge 配置，通用 Benchmark 并不知道这些变量，因此需要用 `evaluation_env_variables` 为验证命令设置： ```bash wrap theme={"system"} git clone https://github.com/scaleapi/SWE-Atlas.git agentcompass run \ harbor \ mini_swe_agent \ "$MODEL_NAME" \ --env docker \ --benchmark-params '{ "dataset_path": "SWE-Atlas/data/qa", "dataset_name": "swe_atlas_qa", "primary_metric": "passed" }' \ --harness-params '{"config_file": "SWE-Atlas/run_config/mswea/qa.yaml"}' \ --env-params '{ "setup": {"workdir": "/app"}, "evaluation_env_variables": { "EVAL_MODEL": "your-judge-model", "EVAL_BASE_URL": "https://your-judge-endpoint/v1", "EVAL_API_KEY": "${JUDGE_API_KEY}" } }' \ --k 3 \ --attempt-strategy avg \ --model-base-url "$MODEL_BASE_URL" \ --model-api-key "$MODEL_API_KEY" \ --model-api-protocol openai-chat ``` `metrics.json` 会报告用于与榜单对比的 `correct` pass\@3，以及三次尝试的平均解决率 `correct` avg\@3，见 [通过率与 pass at k](#通过率与-pass-at-k)。去掉 `--k 3` 和 `--attempt-strategy` 即每个 task 只运行一次。每个 task 都声明了 16 个 CPU 和 16 GiB 内存；如果 Docker 主机较小，请在 `--env-params` 中设置 `resources`。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.