create-adapter

创建适配器

在 Harbor 仓库中初始化一个新的基准测试适配器。此技能会使用 harbor adapter init 搭建适配器目录，之后所有实现决策均以适配器教程为准。

权威参考

适配器教程是此技能的权威规范。开始任何超出搭建脚手架范围的操作前，请完整阅读教程：

adapters/ADAPTER_CONTRIBUTING.md

该路径相对于 Harbor 仓库根目录（这是技能的前提条件——见下文）。教程包含：

• 生成的任务和适配器代码包所需的目录结构。
• 分步流程（步骤 1–9），涵盖基准测试分析、oracle 验证、parity 实验、数据集注册和提交。
• task.toml、parity_experiment.json、adapter_metadata.json 和 dataset.toml 的架构。
• parity 匹配标准、预检清单和调试指南。
• README 格式规则（由机器解析；偏离规则会导致自动化失效）。

不要用已有知识替代该文件的内容。请将其视为必须遵守的规范。

前提条件

• 已安装 Harbor CLI，且可通过 PATH 使用（harbor --version 执行成功）。
• 当前工作目录是 Harbor 仓库根目录。
• Harbor 检出版本是最新的：运行 git fetch origin && git status，如果落后则拉取 main。过时的检出版本会缺少近期的适配器和 Agent 修复，之后也常会导致虚假的 parity 失败。

工作流

1. 阅读教程

执行任何文件系统或 CLI 操作前，请完整阅读 adapters/ADAPTER_CONTRIBUTING.md。尤其要留意：

• 必需的目录结构 — 生成的任务和适配器布局规范。
• 步骤 1. 了解原始基准测试 — 编码前需要从上游确认的信息。
• 步骤 8. 注册数据集 → 命名规则 — name 字段和 <org>/<task> 格式要求。

2. 向用户收集基准测试背景信息

搭建脚手架前收集以下信息。如果用户尚未提供某项，请先询问，再继续操作——这些输入会影响脚手架以及后续教程步骤。

字段	重要性
适配器名称	使用小写字母，以连字符分隔。必须与基准测试的常用标识符一致（例如 swe-bench、aider-polyglot）。此名称将用作 adapters/ 下的目录名，并在转换下划线后用作 Python 包名。
易读名称	通过 --name 传入；会显示在生成的 README 中。
上游仓库 URL	教程步骤 1（基准测试分析）需要此信息，之后也会用于 original_parity_repo 字段。
是否有 oracle 解决方案？	如果基准测试提供参考解决方案，请使用这些方案。如果没有，必须由大模型生成 oracle 解决方案（教程步骤 3 →“没有 oracle 解决方案的基准测试”）。
Agent 场景	适用步骤 4 中的哪种场景：(1) 现有兼容 Agent；(2) 分叉并添加大模型 Agent；或 (3) 自定义 Agent。这会影响 parity 计划。

3. 创建适配器分支

根据教程步骤 2，在专用分支上开展工作：

git checkout -b <adapter-name>-adapter

4. 运行脚手架命令

如果两种名称都已确定，优先使用非交互形式：

harbor adapter init <adapter-name> --name "<Human-Readable Name>"

否则以交互方式运行 harbor adapter init，并根据 CLI 提示操作。

预期输出：新建目录 adapters/<adapter-name>/，其中包含 pyproject.toml、README.md、src/<adapter_name>/，以及 src/<adapter_name>/task-template/ 下的模板任务文件。继续操作前，请确认该目录存在。

5. 转到教程

从教程中的“Step 1. Understand the Original Benchmark”继续。不要虚构指南未说明的结构、字段名称或工作流。

高优先级注意事项（教程中均有说明，但这些是构建适配器时最常见的失败原因，请在逐步操作时主动留意）：

• 每个生成的 task.toml 都必须在 [task] 下包含 name 字段。main.py 负责为每个任务生成经过清理、唯一且符合注册要求的名称。没有 name 的任务无法注册。请参阅教程中的“Naming rules”表格。
• 适配器每次运行时，任务名称都必须保持稳定。名称不稳定会导致重新发布时注册表摘要频繁变化。如果上游没有稳定标识符，请根据可复现的排序生成确定性命名方案（例如 {dataset}-1、{dataset}-2）。
• 在 task.toml 顶部使用 schema_version = "1.4"。分别通过 task.toml 中的 [task].version 和 dataset.toml 中的 [dataset].version 设置包版本。若需要任何注册表标签，请在 PR 描述中提出。
• main.py 必须支持 --output-dir、--limit、--overwrite 和 --task-ids。这些标志是实现可复现运行和任务级调试所必需的。
• 下游自动化会解析生成的 README.md。请严格按照模板填写每个章节；额外背景信息请放在 Notes 章节，或 parity_experiment.json / adapter_metadata.json 的 notes 字段中。不要添加、重命名、重新排序或删除章节。
• 不要自行运行 parity 实验。教程 Step 4 要求先与团队协调 Agent、模型和运行次数，再产生 API 费用。请先完成健全性检查，并在双方对称地执行完整运行。

按场景分类的参考适配器

遇到实现问题时，请参照与基准形态相符的现有适配器：

场景	示例适配器	使用时机
已有兼容的 Agent	adapters/adebench/	上游已支持 Claude-Code / Codex / OpenHands / Gemini-CLI
Fork 上游并添加大模型 Agent	adapters/evoeval/	基于大模型的基准，没有兼容 Harbor 的 Agent
自定义 Agent，独立数据集	adapters/bixbench/、adapters/financeagent/	自定义交互语义；financeagent 还演示了 LLM-as-a-Judge
就地使用自定义 Agent	adapters/medagentbench/	自定义 HTTPAgent，没有独立数据集
多 Agent 工作流	adapters/cooperbench/	多个 Agent 通过消息传递 / sidecar 协作
GPU 任务	adapters/featurebench/	全面的 Docker + Modal GPU 示例

此技能不负责的事项

• 实现 adapter.py、main.py 或任何任务模板文件。这些由贡献者根据教程完成。
• 运行 oracle 验证或 parity 实验。这些操作需要用户明确提出；parity 实验还需要团队协调。
• 发布数据集或创建 PR。这些是教程后续步骤。

故障模式

症状	可能原因	处理方式
harbor: command not found	未安装 Harbor CLI	使用 uv tool install harbor 或仓库的开发环境设置进行安装。
harbor adapter init 因名称验证错误而失败	适配器名称包含无效字符	使用小写字母和连字符分隔的名称重新运行。
脚手架创建成功，但不存在 adapters/<name>/	从仓库根目录之外运行	切换到 Harbor 仓库根目录，然后重新运行。
Oracle 在本地通过，但之后 parity 无故失败	Harbor 检出版本过旧	运行 git fetch origin && git status；如果落后于 main，则拉取更新。