Harbor 适配器开发完整指南：如何为 Agent 评测框架新增基准适配器并通过全部测试

Harbor 适配器开发完整指南：如何为 Agent 评测框架新增基准适配器并通过全部测试

【免费下载链接】harborFramework for evaluating and improving agents项目地址: https://gitcode.com/gh_mirrors/harbor17/harbor

Harbor 是一个用于评估和改进 AI Agent的开源框架，支持在统一的 Docker 沙箱中运行各类 Agent 并量化其得分。为 Harbor 社区贡献一个 Agent 适配器（Adapter），就是把任意一个现有的 AI 基准测试（Benchmark）翻译成 Harbor 标准任务格式，让它能被 Agent 在隔离环境中稳定评测。本指南面向新手贡献者，带你走通从搭建脚手架、Oracle 验证到 Parity（对等性）实验的完整测试流程，让你的 PR 一次通过审核。

为什么需要 Agent 适配器？

Harbor 的核心运行模型是：每个任务 =指令 + 容器环境 + 验证测试 + 参考解。适配器的职责就是自动化地把上游基准的每个任务生成为这套标准结构：

一个真实的最小任务示例见 examples/tasks/describe-image/，包含指令、环境与图片资源，值得动手前通读一遍。

贡献前必读：Harbor 社区三大规则

在写第一行代码之前，先了解 CONTRIBUTING.md 中的社区契约，这能帮你少走弯路：

1. 黄金法则：你必须理解自己贡献的代码。可以使用编码 Agent，但你要能亲自讲清楚设计过程与取舍；
2. 沟通规范：Issue 与 PR 描述由人负责"初稿 + 终稿"，中间过程可借助 AI；
3. 集成门槛较低：对 Agent 与基准集成比较开放，但要求至少有一位真实用户提出过需求（如留下评论作为证据）。

如需变更核心接口或 Harbor 数据格式，先在 rfcs/ 目录提交一份简洁的 RFC 并发起讨论。

准备工作：Fork 仓库并搭建脚手架

git clone https://gitcode.com/gh_mirrors/harbor17/harbor cd harbor git checkout -b my-benchmark-adapter harbor adapter init my-benchmark --name "My Benchmark"

harbor adapter init会在adapters/my-benchmark/下生成一个src布局的 Python 包，包含pyproject.toml、README.md、adapter_metadata.json、parity_experiment.json、参考运行配置run_my-benchmark.yaml，以及src/my_benchmark/下的adapter.py、main.py和task-template/模板目录。

官方把完整流程拆成9 个步骤，人类可读版教程在 docs/content/docs/datasets/adapters-human.mdx，AI Agent 实现的权威规格在 docs/content/docs/datasets/adapters.mdx。

第 1~2 步：理解基准并完成适配器代码

理解基准时，对每个任务明确四个要素：指令描述、环境依赖、测试方式（确定性单测 / LLM-as-a-Judge）、参考解是否存在。

实现代码时，核心工作是补全adapter.py（解析基准数据、生成任务目录）与main.py（CLI 入口，必须支持--output-dir、--limit、--overwrite、--task-ids四个参数）。几个高频踩坑点：

• 每个task.toml必须含[task].name，且命名需在多次运行间保持稳定（小写、特殊字符转连字符），否则无法注册或导致注册表摘要抖动；
• tests/test.sh失败时返回非零退出码，成功时把奖励值（0~1 的数值）写入/logs/verifier/reward.txt；
• 生成的README.md会被下游自动化脚本机器解析，不要增删、改名或重排模板章节，额外说明一律放 Notes 段落。

按你的基准形态选择参考适配器来对照实现：

以 adapters/simpleqa/ 为例，其 adapter.py、main.py 与task-template/是结构非常干净的完整样板。

第 3 步：Oracle 验证——必须 100% 通过

Oracle 验证是适配器正确性的第一道闸门：用 oracle agent 跑全部任务，任何一条失败都说明适配或环境有 bug。

# 单任务调试 harbor trial start -p datasets/my-benchmark/<task-id> -a oracle # 全数据集验证 harbor run -c adapters/my-benchmark/run_my-benchmark.yaml

配置文件的写法可参考 adapters/simpleqa/run_simpleqa.yaml：默认启用 oracle agent，其他 Agent（codex、claude-code 等）以注释形式列出，方便一键切换。

全部通过后，提交标题为[WIP] Adapter: my-benchmark的 PR，并附上 100% 通过的终端截图。如果上游基准自带的 Oracle 解有 bug，优先在上游仓库提 Issue/PR 修复，再在适配器 README 中记录。

第 4~5 步：规划并执行 Parity 对等性实验

Parity（对等性）是适配器能否被接收的决定性测试：在完全相同的 Agent、模型、提示词与配置下，Harbor 侧与原始基准侧的得分区间必须重叠。

执行前先与核心团队约定 Agent、模型与运行次数（API 成本由团队承担），再按固定节奏对称推进：

1. 5~10 个任务的 sanity 检查（两侧）；
2. 完整跑 1 轮（两侧）；
3. 扩展至每侧 3 轮。

⚠️ 千万不要让一侧跑完 3 轮而另一侧还没开始——一旦发现适配 bug，不对称的运行成本将全部浪费。

调试不重叠的得分时，官方提供了 8 步 Debug Playbook（先看日志排错误 → 检查 Agent 轨迹 → 逐任务重叠分析 → 区分随机噪声与系统性错误……），完整表格见 adapters.mdx 第 5 步。

第 6~7 步：记录结果并上传

实验完成后，在适配器目录填写两个结构化文件：

• parity_experiment.json：每条目记录 agent（带版本）、model、日期、每侧运行次数与逐次得分，original/harbor字段必须报告为均值 ± 样本 SEM格式（注意是标准误，不是标准差）；
• adapter_metadata.json：记录构建者、基准规模、parity 采样率、新增 Agent、parity 成本等。

可对照 adapters/simpleqa/parity_experiment.json 与 adapters/simpleqa/adapter_metadata.json 的现成写法。随后将原始结果按目录规范上传到社区 parity 数据集仓库。

第 8~9 步：注册数据集并提交审核

1. 用适配器把完整数据集生成到harbor-datasets仓库的datasets/<adapter-name>/下；
2. 运行harbor init选择 dataset 生成dataset.toml，填写描述、作者与致谢；
3. 发布前用harbor run -p <本地数据集路径>验证可运行（-d注册表方式要等发布后才能用）；
4. 提交 PR 并请求维护者审核；
5. 发布后执行harbor run -d <org>/<adapter-name>做最终确认。

命名规则：数据集与任务 ID 均为<org>/<name>形式，<org>优先取基准的归属组织；每个任务name在数据集内唯一且跨运行稳定。最后将 PR 标题从[WIP]改为[Ready for Review] Adapter: <adapter_name>，附上完整 README 即可进入评审。

常见问题自检清单 ✅

此外，仓库内置的 skills/create-adapter/SKILL.md 是一份"适配器脚手架技能"文档，完整列出了工作流、高危陷阱与失败模式排查表，是新人最快的上手清单；如需校验适配器格式，可参考 scripts/validate_adapter.py。

写在最后

为 Harbor 贡献 Agent 适配器的核心心法只有三句话：先生成标准任务、再让 Oracle 拿满分、最后用对称的 Parity 实验证明"两边量的是同一件事"。按 9 步流程稳扎稳打，你的基准就会正式进入 Harbor 注册表，被全球开发者用来评测下一代 Agent。动手试试吧！

【免费下载链接】harborFramework for evaluating and improving agents项目地址: https://gitcode.com/gh_mirrors/harbor17/harbor