Pourquoi votre chargeur de plug-in enfreint la norme sans que vous le sachiez
Une règle du schéma JSON, apparemment anodine — additionalProperties: false — perturbe discrètement la compatibilité des plug-ins entre différents clients. La spécification Agent Plugins 1.0.0 impose une validation stricte pour plugin.json, mais une clause mal comprise génère des échecs silencieux qui n’apparaissent que des mois plus tard.
La clause négligée dans la spécification
La spécification, en son §5.2, précise explicitement que les clients doivent ignorer les champs de niveau supérieur inconnus et poursuivre le chargement du plug-in, à condition que le reste du manifeste soit valide. Pourtant, de nombreux chargeurs traitent toute violation de schéma comme fatale, ce qui contredit directement cette règle. Cette divergence signifie qu’un plug-in fonctionnel dans un client peut échouer silencieusement dans un autre, souvent sans message d’erreur clair. Le problème n’est pas seulement théorique : des cas concrets illustrent son impact. Par exemple, le chargeur des Agent Plugins de Codex acceptait autrefois n’importe quel répertoire contenant un plugin.json, mais lorsque des champs inconnus apparaissaient, les crochets cessaient purement de s’exécuter. Pendant ce temps, oh-my-pi rejetait les plug-ins dotés de clés de frontmatter supplémentaires, réduisant les compétences d’un plug-in de 33 à 3. Il ne s’agit pas de bugs dans les plug-ins eux-mêmes, mais dans la manière dont les clients interprètent la spécification.
Le manque de tests de conformité
La plupart des outils de validation vérifient si un plug-in que vous avez écrit est correct, et non si un client gère correctement les plug-ins. Cette distinction est cruciale. Un client qui rejette les champs inconnus échoue à la spécification, mais ce comportement passe souvent inaperçu lors des tests, car il ne génère pas d’erreurs — seulement des rejets silencieux de plug-ins. L’auteur à l’origine de cette observation a conçu un kit de conformité pour combler cette lacune. Il associe un répertoire de plug-in réel avec le rapport de chargement exact qu’un client conforme devrait produire. Par exemple, une fixture nommée AP-5.2-UNKNOWN-FIELD inclut un plugin.json canonique avec un champ inconnu et s’attend à ce que le client le signale tout en chargeant le plug-in. Les clients qui rejettent immédiatement échouent à ce test, révélant une non-conformité qui passerait autrement inaperçue.
Pourquoi est-ce important
Ce n’est pas qu’une bizarrerie de conformité marginale : c’est un risque de fragmentation pour l’écosystème Agent Plugins. Lorsque les clients se comportent différemment, les plug-ins deviennent fragiles, échouant silencieusement pour les utilisateurs sans cause claire. Pour les développeurs, cela signifie que les tests ne suffisent plus ; valider votre plug-in contre leur client fait désormais partie du processus. Les enjeux sont encore plus élevés pour les écosystèmes ouverts : une règle mal comprise peut éroder la confiance et freiner l’adoption. La bonne nouvelle ? Corriger cela est simple : mettre à jour les chargeurs pour ignorer les champs inconnus selon le §5.2, et adopter des tests de conformité avant la publication. La mauvaise nouvelle ? Le premier signe de problème peut provenir d’un utilisateur frustré, et non de vos journaux.
Source : DEV Community. Synthèse éditoriale assistée par IA — TechnoExpress.