ConnexionPlanifier un briefing

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

16 minutes de lecture

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.

  1. 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.
  2. Compétences du Skills Engine. Un paquet SKILL.md contenant 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é).
  3. 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-only ou full-service.
  4. 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.
  5. 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.
  6. 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.

Démarrer un nouveau projet
Démarrer un nouveau projet
Démarrer un nouveau projet propose six parcours de référence, un par type d'extension. Chacun crée un dépôt à partir d'un modèle versionné avec un manifeste qui déclare ses besoins, et configure des tests, un espace de développement et des branches de données.

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.
Dessinez une pile de bandes horizontales. En bas, « Fonctionnalités principales de Nexus » (assistant, fichiers, mémoire, tâches) et à côté « Répartiteur UNO » et « AI Provider Router ». Au-dessus, une bande « Plugins » avec deux boîtes, « skills-only » et « full-service », et une bande « Compétences du Skills Engine ». Au-dessus de celles-ci, une large boîte « Pack métier » contenant quatre boîtes plus petites : « Modèle de connaissances », « Vues », « Modèles et flux de travail », « Surcouche mobile ». À gauche du pack, une boîte « Connecteurs en lecture seule » avec une flèche pointant vers « Modèle de connaissances ». Tout en haut, trois boîtes d'unités (« Rotterdam », « Felixstowe », « Siège social ») avec des flèches descendant du pack et portant la mention « vue attribuée par rôle ». Un cadenas sur le bord du pack porte la mention « licence : domain_packs ».
Comment un pack métier regroupe les autres briques de base.

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.

Packs métier
Packs métier
La page Packs métier répertorie les dix packs en précisant les prérequis et l'emplacement d'exécution de chacun. Un pack non couvert par la licence reste affiché en grisé, avec mention de ce qu'il nécessiterait.

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-service possè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.

Installer un plugin tiers
Installer un plugin tiers
L'installation d'un plugin tiers fonctionne comme les permissions d'une application. Chaque portée déclarée dans son manifeste est accordée ou refusée par unité, et tout appel portant sur un élément non déclaré est refusé avec 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.

Plugins et synchronisation MCP
Plugins et synchronisation MCP
La page Plugins et synchronisation MCP indique quels plugins apportent des compétences, quelles synchronisations ont été entièrement refusées, ainsi que les treize outils MCP que Claude Code et les agents utilisent pour accéder à la bibliothèque.

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.