Version 1.0.0-alpha.1dernière version
Chapitre 2.18
Le modèle d'extension
Les six façons d'étendre Nexus, d'un simple paramètre jusqu'à un pack métier, les limites de chacune, et comment les niveaux de confiance et d'isolation déterminent où votre code s'exécute. À lire avant d'ouvrir le kit de développement logiciel (SDK).
Cette page a été traduite par l'IA à partir de l'original en anglais. En cas de doute, la page en anglais fait foi. Lire cette page en anglais

La première chose que j'ai conçue sur Nexus chez Corrán Orbital n'était pas un plugin. Notre équipe de dynamique de vol voulait que l'assistant réponde à la question « quels passages au-dessus des stations au sol perdons-nous si l'antenne du Svalbard est arrêtée pour maintenance ? » selon le même format à chaque fois, avec le tableau des passages en premier et le coût en minutes de contact en dessous. J'ai passé une demi-journée à lire la documentation du kit de développement logiciel (SDK) avant qu'un collègue ne me fasse remarquer que ce dont j'avais besoin était une compétence (skill) : un dossier contenant un SKILL.md, téléversé dans le Skills Engine et publié une fois ses tests réussis et après l'approbation d'un réviseur. Cela a pris quarante minutes.
Deux plugins et un pack métier plus tard, c'est toujours le premier conseil que je donne. Nexus offre six façons de l'étendre, réparties sur une échelle d'effort. Les échelons les plus économiques font plus que ce que l'on imagine, et les plus coûteux impliquent des obligations faciles à sous-estimer. Ce chapitre présente cette échelle. Choisissez l'échelon le plus bas qui répond à votre besoin. Les chapitres suivants approfondissent chacun d'eux : chapitre 2.19, Les règles dont hérite chaque extension ; chapitre 2.20, Les compétences ; chapitre 2.21, Le SDK de plugin ; chapitre 2.22, L'environnement d'exécution des plugins ; et chapitre 2.23, Les packs métier.
Les six briques de base
Les voici dans l'ordre où vous devriez les envisager.
- Paramètres et politiques. Il s'agit de valeurs qu'un administrateur définit dans la console pour l'organisation, une unité ou une personne, dans les limites autorisées par la licence. Vous n'écrivez aucun code.
- Compétences du Skills Engine. Un paquet
SKILL.mdcontenant des instructions et les outils que la compétence peut appeler, accompagné de fichiers et de scripts facultatifs. L'assistant, les agents, les flux de travail et les boutons d'IA (intelligence artificielle) présents sur les écrans exécutent tous les mêmes compétences, tout comme votre IDE (environnement de développement intégré). - Plugins. Votre propre code, déclaré par un manifeste et compilé avec les outils du SDK. Un plugin se décline en trois niveaux :
skills-only,ui-onlyoufull-service. - Packs métier. Les vues (lenses) et les modèles d'un secteur d'activité, ses compétences et son modèle de connaissances, ses connecteurs et ses écrans mobiles, concédés sous licence comme un tout. Adverant en fournit dix ; vous pouvez concevoir les vôtres.
- Vues (Lenses). Ce qu'un rôle voit au sein d'un pack ou d'une plateforme. Une vue restreint une vue de base et ne l'élargit jamais.
- Connexions MCP et connecteurs. Les outils du Model Context Protocol (MCP) qu'un plugin publie ou auxquels un outil de codage par l'IA se connecte, ainsi que les connecteurs en lecture seule qui importent des enregistrements depuis les systèmes que vous exploitez déjà.
Deux termes prêtent souvent à confusion, permettez-moi donc de les clarifier dès maintenant. Une compétence du Skills Engine est un paquet SKILL.md dans la bibliothèque. Une compétence de manifeste est une entrée typée dans le tableau skills[] d'un plugin, compilée dans le registre des compétences de la plateforme et exécutée via UNO, le moteur de flux de travail. Toutes deux sont appelées « compétences » à l'écran. Elles sont écrites et gouvernées différemment, et cette documentation précise toujours de laquelle il s'agit.
Ce que chacune peut faire, et ce qu'elle ne peut pas faire
Le tableau en donne la version résumée. J'ai inclus la colonne « Ce qu'elle ne peut pas faire » à dessein : chaque limite est une propriété de la conception, et chacune d'entre elles m'a évité bien des problèmes.
| Brique de base | Ce qu'elle peut faire | Ce qu'elle ne peut pas faire | Qui la crée |
|---|---|---|---|
| Paramètre ou politique | Modifier le comportement d'une fonctionnalité à n'importe quel niveau, de l'organisation jusqu'à l'individu ; verrouiller une valeur ; la déléguer à un niveau inférieur ; exiger l'approbation d'une deuxième personne lors d'une modification | Ajouter un écran ou une route, stocker une nouvelle table ou lancer un nouveau type de tâche | Un administrateur, dans la console |
| Compétence du Skills Engine | Fournir à l'assistant, aux agents, aux flux de travail et aux boutons d'IA une méthode reproductible pour accomplir une tâche, avec ses propres instructions et cas de test | Détenir un identifiant d'accès ; appeler un outil en dehors de la liste d'autorisation de la personne qui l'exécute (SKILL_CANNOT_WIDEN_TOOLS) ; être mise en production sans ses tests et son approbation |
Toute personne disposant des droits, dans l'outil de création ou depuis son IDE |
Plugin, skills-only |
Publier des compétences de manifeste qui s'exécutent sur la plateforme : rappels d'hôte (callbacks), tâches mises en file d'attente, traitements par lots sur une liste et, au niveau de confiance core ou verified, des compétences adossées à un modèle |
Servir ses propres pages | Un développeur, avec le SDK |
Plugin, ui-only |
Ajouter une interface frontend au sein du shell | Stocker ses propres données ou exécuter des calculs | Un développeur, avec le SDK |
Plugin, full-service |
Son propre backend et frontend, un schéma Postgres, une table de routage avec des droits, ainsi que des compétences et des outils MCP | Appeler un fournisseur de modèle ; détenir une clé de modèle ; lire les lignes d'une autre organisation sauf par le biais d'une autorisation enregistrée ; exécuter des calculs en dehors du répartiteur UNO | Un développeur, avec le SDK |
| Pack métier | Apporter les vues et les modèles d'un secteur d'activité, ses compétences et ses flux de travail, un modèle de connaissances, une carte des preuves et des écrans mobiles aux unités choisies par un administrateur | Modifier le shell ou ses composants, ou les règles d'écriture ; fonctionner sans être couvert par la licence de l'organisation | Adverant, ou vos propres développeurs sur l'édition Enterprise |
| Vue (Lens) | Choisir les cartes et les champs qu'un rôle voit au sein d'un pack ou d'une plateforme, ainsi que les actions proposées | Afficher quoi que ce soit que sa vue de base masque (LENS_CANNOT_WIDEN) ; modifier ce qu'un rôle est autorisé à faire |
L'auteur d'un pack la conçoit ; un administrateur l'attribue par unité |
| Outils MCP et connecteurs | Exposer les outils d'un plugin aux agents et aux outils de codage ; lire des enregistrements depuis un système de gestion des polices ou une archive de télémétrie vers le modèle de connaissances | Écrire en retour dans le système source via un connecteur ; agir au-delà des permissions propres à la personne connectée | Un développeur déclare les outils MCP ; un administrateur configure les connecteurs |
Quelques-unes de ces cellules méritent une phrase supplémentaire.
Les paramètres constituent un cadre structurel, et chaque plugin utilise le même. Un plugin qui déclare un bloc settings dans son manifeste bénéficie des niveaux (plateforme, organisation, pack, unité, groupe, dépôt, personne), des verrouillages et de la délégation, d'un journal des modifications et de l'approbation par une deuxième personne, le tout sans avoir à créer de table de paramètres. C'est pourquoi l'échelon le plus économique suffit souvent : si le comportement souhaité existe déjà et nécessite seulement une valeur différente pour l'unité de Rotterdam, il s'agit d'un paramètre.
Une compétence du Skills Engine s'exécute au nom de la personne. Elle ne détient jamais de clé, ne peut accéder qu'aux outils figurant dans la liste d'autorisation de la personne qui l'exécute et ne lit que ce que cette personne est autorisée à ouvrir. Une compétence qui ajoute un outil d'écriture est bloquée jusqu'à ce que deux personnes l'approuvent, puis passe en production en mode fantôme (shadow), puis en mode canari, et enfin pour tout le monde.
Un plugin skills-only constitue l'échelon intermédiaire. Vous en avez besoin lorsque le traitement repose sur du code qui vous appartient : un calcul déterministe, un processus de file d'attente, une distribution (fan-out) sur une liste. La plateforme appelle votre code ; votre code n'appelle jamais de modèle.
Un plugin full-service est un petit produit à part entière. Il possède un schéma Postgres, une table de routage avec un registre des droits, un frontend, un ensemble de rôles de base de données et toutes les obligations d'isolation décrites au chapitre 2.19, Les règles dont hérite chaque extension. C'est la bonne solution plus souvent qu'on ne le craint, et la mauvaise plus souvent qu'on ne l'espère.
De laquelle ai-je besoin ?
Commencez par le haut de ce tableau et arrêtez-vous à la première ligne qui correspond à votre besoin.
| Vous souhaitez… | Utilisez | Pourquoi pas une solution plus légère |
|---|---|---|
| Modifier une valeur ou une limite, ou définir qui peut faire quoi | Un paramètre ou une politique | Il n'existe rien de plus léger |
| Faire en sorte que l'assistant exécute une tâche toujours de la même manière | Une compétence du Skills Engine | Un paramètre ne peut pas contenir d'instructions |
| Placer un « bouton d'IA » sur un écran pour exécuter cette tâche | Une compétence du Skills Engine liée au bouton | Un bouton n'exécute que des compétences ; il n'y a rien à développer |
| Permettre à un outil de codage par l'IA d'accéder à Nexus | Une connexion MCP via le Workbench | Rien à écrire ; la personne se connecte via son navigateur |
| Lire des enregistrements depuis un système existant vers le modèle de connaissances | Un connecteur en lecture seule | Un connecteur n'écrit rien en retour, il ne comporte donc aucun risque lié à l'écriture |
| Exécuter du code déterministe qui vous appartient selon la planification de la plateforme | Un plugin skills-only avec une compétence host_callback ou plugin_queue |
Une compétence du Skills Engine ne peut pas exécuter votre code |
| Ajouter un ou deux écrans au sein du shell | Un plugin ui-only |
Seuls les plugins ajoutent des écrans |
| Conserver vos propres enregistrements derrière vos propres routes et droits | Un plugin full-service |
Seul ce niveau possède un schéma |
| Offrir à un rôle une vue plus restreinte des écrans d'un secteur d'activité | Une vue sur un pack existant | Une vue est composée de données, pas de code |
| Apporter le modèle de connaissances et les vues d'un secteur d'activité, avec des écrans mobiles, à plusieurs unités | Un pack métier | Un plugin seul n'a ni vues ni contrôle de licence |
Chez Corrán Orbital, la question de la planification des passages est restée une compétence du Skills Engine. La propagation d'orbite qu'elle nécessite est devenue un plugin skills-only doté d'une compétence host_callback, car le calcul numérique nous appartient et doit fournir deux fois la même réponse. Notre comité d'examen des anomalies est devenu un plugin full-service, car il conserve ses propres enregistrements sur qui a examiné quel écart de télémétrie et sur ce qui a été décidé. Le pack est venu en dernier, lorsqu'une deuxième unité a demandé la même chose.
Comment les éléments se combinent
Les briques de base s'assemblent de bas en haut. Un pack métier en est l'exemple le plus clair, car il regroupe les autres briques en y ajoutant un contrôle de licence :
- un modèle de connaissances, c'est-à-dire les types d'éléments propres au secteur d'activité et leurs liens, souvent construit sur un modèle de base issu d'un autre pack ;
- des vues, une par rôle, chacune restreignant une vue de base ;
- des modèles et des flux de travail, ainsi que les compétences du Skills Engine qu'ils appellent ;
- des plugins là où le pack a besoin de son propre code ;
- des connecteurs en lecture seule vers les systèmes qui détiennent déjà les enregistrements ;
- une surcouche mobile qui définit quelles cartes et quelles étapes de saisie apparaissent sur les téléphones ;
- et les droits d'accès (entitlement) : les groupes de fonctionnalités que la licence doit inclure avant que quoi que ce soit ne s'active.
Rien de tout cela ne relève d'une infrastructure propre à chaque application. Le pack n'embarque aucun code d'isolation propre, aucun client de modèle et aucune vérification de licence : il hérite de ceux de la plateforme. C'est le sujet du chapitre suivant, et c'est la raison pour laquelle l'auteur d'un pack dans une banque et celui dans un port écrivent la même quantité de code de sécurité, c'est-à-dire aucune.
Niveaux de confiance
Chaque plugin déclare un niveau trust dans son manifeste. La confiance n'est pas un contrôle que le SDK peut contourner. Il s'agit de métadonnées consultatives que la plateforme lit pour décider du degré d'isolation dans lequel s'exécutent les contributions d'un plugin et des données les plus sensibles que ses compétences peuvent manipuler. Les contrôles actifs (classification et résidence des données, exportation et dépenses) restent exactement là où ils sont.
| Confiance | À qui il s'adresse | Posture d'isolation | Plafond de classification |
|---|---|---|---|
core |
Code interne livré avec la plateforme | none : même origine, aucune isolation supplémentaire |
restricted |
verified |
Un tiers vérifié, un éditeur certifié | Surface same-origin, compétences intermédiées |
restricted |
community |
Un tiers non vérifié ; la valeur par défaut pour un nouveau plugin | Surface sandboxed, compétences intermédiées |
tenant |
untrusted |
Tout élément provenant d'une source inconnue | strict : surface en bac à sable (sandbox), compétences intermédiées uniquement, aucune confiance de l'hôte |
public |
Deux règles découlent de ce tableau, et create-nexus-plugin validate applique les deux avant toute compilation.
Premièrement, le classification d'une compétence ne peut pas dépasser le plafond de son plugin. Les classifications sont hiérarchisées dans l'ordre public, puis tenant, puis restricted. Un plugin community qui déclare une compétence restricted échoue à la compilation.
Deuxièmement, seuls les plugins core et verified peuvent déclarer des compétences qui accèdent à l'AI Provider Router. Il s'agit des niveaux tool_using et llm_only. Un plugin community ou untrusted intermédie les traitements déterministes (host_callback, plugin_queue, et map sur ceux-ci) et demande à la plateforme d'effectuer tout ce qui nécessite un modèle. Mon premier plugin était de niveau community, et j'ai perdu un après-midi à essayer de déclarer une compétence de résumé llm_only avant de comprendre que ce refus était voulu par la conception.
Si vous omettez trust, le SDK traite le plugin comme community. Un champ omis ne peut jamais entraîner une élévation de privilèges.
Niveaux d'isolation 1 à 4
Indépendamment du niveau de confiance, le bloc runtime du manifeste indique comment le plugin s'exécute. isolationLevel est un entier compris entre 1 et 4, et le mode d'exécution en découle. Vous ne choisissez pas les deux indépendamment : le validateur déduit l'un de l'autre et refuse un manifeste dont la paire est incohérente.
isolationLevel |
executionMode |
Ce que cela signifie |
|---|---|---|
| 1 | external_https |
Le plugin s'exécute en dehors de l'installation et est joint via HTTPS |
| 2 | mcp_container |
Un conteneur qui expose des outils MCP |
| 3 | hardened_docker |
Un conteneur durci dans les propres pods du plugin ; la valeur par défaut du modèle |
| 4 | firecracker |
Une microVM, la séparation la plus forte |
"runtime": {
"nodeVersion": "20",
"executionMode": "hardened_docker",
"isolationLevel": 3,
"entrypoint": "dist/server.js",
"healthCheck": "/health"
}entrypoint est obligatoire. Les points d'entrée sont des artefacts livrés et ne sont jamais récupérés à l'exécution : le SDK ne dispose d'aucun chemin d'importation dynamique ou de chargement à distance, de sorte que la confiance est consignée et vérifiée une seule fois, puis figée, sans jamais être téléchargée.
Ce à quoi vous vous engagez à chaque échelon
Chaque échelon au-dessus des paramètres a un coût de maintien. Voici ce que chacun vous coûte.
- Une compétence du Skills Engine nécessite des cas de test, un réviseur qui n'est pas vous, et un historique des versions sur lequel vous serez interrogé en cas de dysfonctionnement. Les mêmes octets ne sont jamais publiés deux fois (
CONTENT_HASH_ALREADY_PUBLISHED), de sorte que « simplement la téléverser à nouveau » ne résout rien. - Un plugin nécessite un manifeste dont la table de routage correspond aux routes que votre code enregistre, dans les deux sens. Une route qui existe mais n'est pas déclarée constitue un défaut de conformité, tout comme une route déclarée que le code n'enregistre jamais.
- Un plugin
full-servicepossède un schéma avec cinq rôles de base de données, une sécurité au niveau des lignes (row-level security) imposée sur chaque table, et un démarrage qui refuse d'écouter tant que la base de données n'a pas prouvé que la barrière d'isolation est en place. Il réénonce également les trois lois de la plateforme dans son manifeste, mot pour mot. - Un pack métier est soumis à une licence. Il s'active une unité à la fois, par le biais d'un pilote, et la licence de l'organisation doit l'inclure. Ce n'est pas vous qui décidez si un client en dispose.
- Une vue ne peut que restreindre. Si un rôle a besoin de voir davantage d'éléments, c'est la vue de base qui doit changer, ce qui implique d'en discuter avec le responsable de cette base.
Aucun de ces coûts n'est négociable par application : c'est le compromis. Vous renoncez à une certaine liberté sur le premier plugin et vous la récupérez sur tous les suivants.
CONNECTION_SCOPE_EXCEEDED.Outils et connexions MCP
Le protocole MCP apparaît à trois endroits, et il est facile de les confondre.
Un plugin peut publier des outils MCP en les déclarant dans mcpTools[] : un name, une description et un inputSchema. La seule règle ajoutée par le validateur est qu'un inputSchema ne peut pas utiliser un oneOf, allOf ou anyOf de premier niveau, car un combinateur à la racine du schéma fait échouer avec une erreur 400 chaque client MCP qui importe l'outil. Un plugin au isolationLevel 2 s'exécute en tant que mcp_container.
La bibliothèque du Skills Engine est accessible via MCP. Claude Code et les agents utilisent treize outils MCP pour trouver et associer des compétences, les exécuter et enregistrer l'exécution, ainsi que pour les créer, les importer ou les synchroniser ; chaque appel s'exécute au nom de la personne qui l'a lancé, dans les limites de sa liste d'autorisation.
Enfin, un outil de codage par l'IA se connecte via le Workbench : une adresse par installation, une connexion via le navigateur de la personne, un laissez-passer d'une heure au lieu d'une clé stockée, et uniquement les outils que cette personne coche. Le chapitre 2.26, Développer avec des outils de codage par l'IA, détaille ce fonctionnement.
Les connecteurs sont des voisins plus discrets. Le modèle de connaissances d'un pack métier est alimenté par des connecteurs en lecture seule reliés à des systèmes tels que la gestion des polices ou un système de gestion des sinistres, chacun disposant d'une planification et d'un bouton de test. Rien n'est écrit en retour dans la source.
De votre branche jusqu'aux écrans des utilisateurs
Quel que soit l'échelon où vous vous trouvez, le chemin vers la production est le même. Chaque version passe de votre espace de développement à l'environnement de préproduction (staging), puis à une unité pilote, et enfin à toutes les unités, et chaque étape comporte des contrôles : des tests, un manifeste dont les portées ne se sont pas élargies, une exécution à blanc sur une copie masquée, et des réviseurs désignés qui ne sont pas l'auteur. Une promotion qui tente de sauter une étape est refusée avec GATE_CANNOT_BE_SKIPPED. Chaque environnement conserve la version précédente pendant 30 jours, et la restauration d'une unité à l'état antérieur est une modification soumise à révision qui prend environ une minute.
Le déploiement lui-même passe uniquement par les canaux de publication de l'installation. Les unités choisissent leur canal, et leur administrateur approuve chaque passage. Vous voyez les volumes et les taux d'erreur par unité sur la page Canaux et installations, mais jamais ce que quiconque a fait avec votre extension. Le chapitre 2.28, Publier votre extension, couvre le volet publication de bout en bout.
Note sur les éditions
La majeure partie de cette échelle existe dans les deux éditions. L'édition Community dispose des paramètres et des compétences du Skills Engine, des plugins de tous niveaux et des mêmes parcours de référence sur un serveur unique, avec le code hébergé sur votre propre serveur Git. L'édition Enterprise ajoute la promotion depuis l'espace de développement vers la préproduction puis vers une unité pilote avec ses contrôles, ainsi que des clusters d'éditeurs et des copies masquées des données de production. Elle ajoute également votre propre catalogue privé et les packs métier. Le chapitre 2.25, Développer pour chaque édition, en présente les détails.
Le chapitre suivant est celui qu'il faut lire avant d'écrire la moindre ligne de code. Il laisse peu de place aux choix mais détaille de nombreuses règles, et ces règles sont les mêmes pour la première extension comme pour la millième.



