61 plugins admis en 65 minutes : ce que vérifie vraiment une passe groupée sur le catalogue


Vous avez écrit un plugin Hermes, il marche bien, et vous voulez que d’autres personnes puissent l’installer en une seule commande. Vous ouvrez donc la doc, vous y lisez qu’il suffit d’ouvrir une PR qui ajoute un plugin-catalog/<name>.yaml, et vous atterrissez sur la page des pull requests du dépôt — où, entre deux et trois heures du matin, les merges défilent comme une cascade. Une soixantaine, toutes des entrées de plugins.

Votre première réaction est sans doute que tout ça a l’air arbitraire et que votre PR va se noyer. La seconde : est-ce que quelqu’un a vraiment lu tout ça ?

Les deux questions ont des réponses précises, et ces réponses sont écrites noir sur blanc dans les règles d’admission du dépôt.

61 entrées en une heure, c’est le design, pas un emballement

Commençons par les faits. Entre 02:14 et 03:19 UTC le 8 novembre, NousResearch/hermes-agent a fusionné 61 entrées de catalogue de plugins. Les labels sont uniformes : toutes portent ci-reviewed, la plupart comp/plugins, une minorité type/feature avec P3.

Personne n’a cliqué sur merge au hasard toute la nuit. La règle d’admission 5 autorise exactement deux voies :

  1. le propriétaire du dépôt du plugin, ou un contributeur majeur, soumet l’entrée ;
  2. les maintainers ajoutent des entrées par lots, à l’issue d’une passe revue sur les plugins de la communauté — avec, pour chaque entrée, une épingle validée et scannée au commit épinglé.

L’admission par lots est donc une façon de travailler officielle. Ce qui est mis en lot, c’est la cadence des PR, pas la densité des contrôles. Chaque entrée passe la même porte.

Un point à connaître en plus : être intégré par une passe ne retire pas le contrôle à l’auteur. Une PR émanant du propriétaire pour ajuster ou retirer son entrée est acceptée sur demande, et les bumps de SHA ultérieurs (règle 4) restent des PR du propriétaire ou des maintainers.

Ce que chaque entrée traverse pendant une passe

Si vous ne voulez que la checklist, la voici. La commande que lancent les reviewers et la CI est exactement celle que vous pouvez lancer en local :

hermes plugins validate /path/to/your-plugin --install-deps

Ce qu’elle vérifie n’est pas si le plugin démarre, mais une liste de choses faciles à oublier :

  • le manifeste plugin.yaml et la validité de requires_hermes ;
  • que le plugin se charge réellement — au commit épinglé ;
  • que les capabilities que vous déclarez (tools, hooks, middleware, env) correspondent à ce que le plugin enregistre — ce contrôle échoue au lieu d’avertir, car une dérive silencieuse des capacités est traitée comme un problème de sécurité ;
  • config_schema et requires_env ;
  • que les dépendances Python se résolvent dans les contraintes du cœur d’Hermes ;
  • le scanner de sécurité à l’installation (dangerous bloque ; caution devient un avertissement qu’un reviewer lit) ;
  • les contrôles desktop surface et no core override.

Ces deux derniers portent les valeurs les plus strictes du catalogue et méritent leur propre paragraphe. Les plugins desktop ne peuvent utiliser que le SDK — pas de patch du renderer ni des prototypes du navigateur. Aucun plugin ne peut surcharger le cœur d’Hermes à l’exécution — pas de AIAgent.<method> = ..., pas de sys.modules[...], pas d’écriture dans les tables d’un module du cœur. La doc en donne la raison sans détour : deux plugins qui patchent la même couture se cassent mutuellement en silence, et chaque version du cœur peut casser les deux.

L’état d’esprit le moins coûteux pour un auteur est donc : arrêtez de contourner, demandez un hook. S’il manque une capacité, ouvrez une issue. Le projet dit clairement qu’il préfère ajouter une couture plutôt que référencer un patch.

Deux cas limites dans cette vague qui montrent la vraie friction

Une passe groupée, ce n’est pas juste le bouton merge. Elle racle des angles que vous ne voyez jamais autrement. Cette vague en a compté deux.

Un : huit entrées dont les dépôts d’auteur refusent les push des maintainers. La CI du catalogue doit cloner le dépôt de l’auteur et lancer la validation au commit épinglé. Certains dépôts protègent leurs branches ou restreignent les permissions, si bien qu’un maintainer ne peut pas y pousser — même une branche marqueur. Une PR dédiée (#150957) liste ces huit entrées pour qu’elles soient traitées à part. La leçon est collaborative, pas technique : si vous voulez que votre plugin soit intégré proprement, ne verrouillez pas l’automatisation des maintainers hors de votre dépôt.

Deux : le scan d’archive de la règle 17 a pris des fichiers de données pour des payloads. La règle 17 interdit les payloads exécutables non scannables, ce qui se traduit par un scan des archives du plugin. Une entrée de cette vague (dike) épingle un tarball de corpus de données : 34k fichiers .json, deux fichiers .ttl et des fichiers de contexte .jsonld. Le scanner ne reconnaissait ni .jsonld ni .ttl : il a donc classé le corpus comme payload non scannable, et l’entrée a échoué à la validation de la source épinglée.

Le correctif (commit 11b2b4414f) raisonne à partir des principes : JSON-LD et Turtle sont des sérialisations RDF en texte brut, aussi relisibles que les .json et .xml déjà présents dans la liste des sources — ce ne sont pas des payloads. La formulation vaut la lecture, parce qu’elle résume l’attitude derrière les règles : l’essentiel est de pouvoir relire, pas de paraître propre.

Si vous voulez être référencé, ces sept points comptent plus que votre code

Dans l’ordre du document, les raisons pour lesquelles une entrée revient sont presque toujours des questions de préparation, pas un manque d’ingéniosité.

Un : épinglez un SHA de commit complet de 40 caractères. Les branches, les tags et les SHA courts sont rejetés par le loader. L’installation clone votre dépôt et checkout exactement ce commit — c’est tout le modèle de confiance.

Deux : ne livrez pas d’auto-updater. La règle 3 interdit les plugins qui récupèrent et remplacent leurs propres fichiers (vérification de mises à jour intégrée à l’app, téléchargeurs de releases signées, chargeurs distants de plugin.js). Un auto-updater signifie qu’une copie installée peut passer à un commit que personne n’a relu. Envie de mettre à jour ? Ouvrez une PR de bump de SHA ; les utilisateurs lancent hermes plugins update <name>.

Trois : les capacités déclarées doivent correspondre à la réalité. Sur-déclarer est du gaspillage, sous-déclarer est un problème de sécurité, et sur ce point il n’y a pas de négociation.

Quatre : utilisez les surfaces publiques, ne patchez pas. Hooks, middleware, ctx.register_*, profils de provider, SDK Desktop — c’est la liste. Demandez ce qui manque au lieu de contourner.

Cinq : les identifiants passent par Hermes. La règle 11 est détaillée là-dessus : les secrets déclarés dans requires_env et config_schema se lisent avec agent.secret_scope.get_secret(NAME) (qui respecte le profil actif — une lecture directe via os.environ peut récupérer la clé d’un autre profil en multiplexage) ; les clients OAuth tiers se déclarent sous oauth: dans plugin.yaml et s’authentifient avec hermes auth add <plugin>:<id> ; un plugin ne lit jamais les fichiers .env, auth.json, l’état de connexion d’un autre outil, ni un keychain.

Six : déclarez les comportements risqués. La règle 13 demande ce qu’un utilisateur voudrait savoir avant d’installer : appels réseau, lectures hors des données propres au plugin, commandes shell, processus d’arrière-plan de longue durée, identifiants stockés — dans la description de la PR et dans le README. La télémétrie doit être opt-in. Les reviewers en font des lignes de divulgation sur l’entrée. Se faire prendre coûte plus cher que de l’écrire d’avance.

Sept : requires_hermes doit être honnête. C’est un plancher SemVer (">=0.21.5"), pas une date, et jamais plus récent que la version courante. C’est aussi appliqué : l’installation par nom depuis le catalogue refuse sur un Hermes qu’il rejette, et hermes plugins update maintient un plugin installé sur son épingle actuelle tant qu’Hermes n’est pas mis à jour.

Ce que le référencement vous apporte

Pour les utilisateurs, la valeur tient en une phrase : installer par nom, au commit qu’un maintainer a lu. Les points d’entrée :

hermes plugins search <keyword>
hermes plugins browse
hermes plugins show <name>
hermes plugins install <name>
hermes plugins capabilities <name>

show affiche les détails de l’entrée (y compris les événements qu’elle émet et écoute), et capabilities compare les permissions déclarées à celles effectivement accordées — à regarder avant d’installer plutôt qu’à découvrir après.

Le modèle de confiance du catalogue lui-même (revue humaine, épingles SHA, blocklist removed.yaml) est décrit dans l’introduction au catalogue ; les motifs de rejet les plus pointilleux à la porte CI (entrées renommées, subdir qui s’échappe du clone épinglé, sha désignant un objet tag) ont leur propre étude de cas dans cet article sur la porte CI. Celui-ci ajoute la troisième pièce : l’admission par lots comme façon de travailler, et ce que cela implique si vous êtes l’auteur.

Statut

Cette vague a été fusionnée sur main le 8 novembre et ne fait pas partie de la v0.23.0 — mais les entrées de catalogue sont des fichiers de données, donc elles ne sont pas liées à la cadence des releases : tant que votre Hermes atteint le catalogue, les nouvelles entrées peuvent être cherchées et installées (la réussite d’une installation dépend du requires_hermes de l’entrée et de votre version).

Si vous préparez votre propre entrée, la référence hermes plugins du site liste toute la surface des sous-commandes — ne mémorisez pas seulement install.