Créer un Adapter

Amorcer un nouvel adapter de benchmark dans le repository Harbor. Cette skill scaffolde le répertoire de l'adapter avec harbor adapter init puis défère au tutorial de l'adapter pour chaque décision d'implémentation.

Référence faisant autorité

Le tutorial de l'adapter est la spécification faisant autorité pour cette skill. Lisez-le en entier avant toute action au-delà du scaffolding :

docs/content/docs/datasets/adapters.mdx

Ce chemin est relatif à la racine du repo Harbor (prérequis de la skill — voir ci-dessous). Le tutorial contient :

• Les structures de répertoires requises pour les tasks générées et le package du code de l'adapter.
• Le processus étape par étape (étapes 1-9) couvrant l'analyse de benchmark, la vérification d'oracle, les expériences de parité, l'enregistrement du dataset et la soumission.
• Les schémas pour task.toml, parity_experiment.json, adapter_metadata.json et dataset.toml.
• Le critère de correspondance en parité, la checklist préalable et le playbook de débogage.
• Les règles de format README (analysées automatiquement ; les déviations cassent l'automatisation).

Ne substituez pas les connaissances antérieures au contenu de ce fichier. Traitez-le comme le contrat.

Prérequis

• Harbor CLI est installé et disponible sur PATH (harbor --version réussit).
• Le répertoire de travail est la racine du repository Harbor.
• Le checkout Harbor est à jour : exécutez git fetch origin && git status et tirez main si vous êtes en retard. Les checkouts obsolètes manquent les corrections récentes d'adapter et d'agent et sont une source courante d'échecs de parité spurieux plus tard.

Workflow

1. Lire le tutorial

Avant toute action système de fichiers ou CLI, lisez docs/content/docs/datasets/adapters.mdx en entier. Accordez une attention particulière à :

• Required Directory Structures — le contrat pour les layouts de task et d'adapter générés.
• Step 1. Understand the Original Benchmark — ce qu'il faut identifier en amont avant de coder.
• Step 8. Register the Dataset → Naming rules — les exigences du champ name et du format <org>/<task>.

2. Rassembler le contexte de benchmark auprès de l'utilisateur

Collectez ce qui suit avant le scaffolding. Si l'utilisateur n'a pas fourni un élément, demandez avant de procéder — ces entrées façonnent le scaffold et les étapes du tutorial qui suivent.

3. Créer la branche de l'adapter

Selon l'étape 2 du tutorial, travaillez sur une branche dédiée :

git checkout -b <adapter-name>-adapter

4. Exécuter le scaffold

Préférez la forme non-interactive quand les deux noms sont connus :

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

Sinon, exécutez harbor adapter init de manière interactive et laissez le CLI vous inviter.

Sortie attendue : un nouveau répertoire à adapters/<adapter-name>/ contenant pyproject.toml, README.md, src/<adapter_name>/ et les fichiers de task template sous src/<adapter_name>/task-template/. Vérifiez que le répertoire existe avant de continuer.

5. Transférer au tutorial

Continuez à partir de « Step 1. Understand the Original Benchmark » dans le tutorial. N'inventez pas de structure, de noms de champs ou de workflow au-delà de ce que le guide spécifie.

Pièges prioritaires (chacun est documenté dans le tutorial, mais ce sont les défaillances les plus courantes dans la construction d'adapter — soulevez-les de manière proactive au fur et à mesure que vous progressez dans les étapes) :

• Chaque task.toml généré doit contenir un champ name sous [task]. main.py est responsable de dériver un nom sanitisé, unique et sûr pour le registry pour chaque task. Les tasks sans un name ne peuvent pas être enregistrées. Voir la table « Naming rules » du tutorial.
• Les noms de task doivent être stables entre les exécutions d'adapter. Les noms instables changeant les digests du registry lors de la republication. Si l'amont manque d'identifiants stables, créez un schéma déterministe (p. ex., {dataset}-1, {dataset}-2) à partir d'un tri reproductible.
• version = "1.0" dans task.toml est la version du schéma — laissez-le intact. Les versions de dataset sont des tags de temps de publication demandés dans la description de la PR, pas un champ dans task.toml ou dataset.toml.
• main.py doit supporter --output-dir, --limit, --overwrite et --task-ids. Ces flags sont requis pour les exécutions reproductibles et le débogage au niveau de la task.
• Le README.md généré est analysé par l'automatisation en aval. Remplissez chaque section exactement comme le template le définit ; mettez le contexte supplémentaire dans la section Notes ou dans les champs notes de parity_experiment.json / adapter_metadata.json. N'ajoutez pas, renommez, réorganisez ou supprimez de sections.
• N'exécutez pas les expériences de parité unilatéralement. L'étape 4 du tutorial requiert une coordination d'équipe sur les agents, les modèles et le nombre d'exécutions avant d'engager les coûts API. Complétez d'abord les vérifications de santé et exécutez les runs complets symétriquement des deux côtés.

Adapters de référence par scénario

Quand des questions d'implémentation se posent, pointez vers un adapter existant correspondant à la forme du benchmark :

Ce que cette skill ne fait PAS

• Implémenter adapter.py, main.py ou aucun fichier de task-template. Ce travail revient au contributeur, guidé par le tutorial.
• Exécuter la vérification d'oracle ou les expériences de parité. Celles-ci requièrent l'intention explicite de l'utilisateur et, pour la parité, la coordination d'équipe.
• Publier le dataset ou ouvrir des PRs. Ce sont des étapes ultérieures du tutorial.

Modes de défaillance