Extensibilité
Extensibilité de l’écosystème et garde-fous du compilateur
1. L’interface universelle WebAssembly (Wasm)
Pour garantir une symétrie architecturale dans tout l’écosystème, Aggrega utilise un contrat d’exécution standardisé qui s’applique uniformément à chaque socket Wasm du pipeline du compilateur.
L’interface YAML permettant d’invoquer n’importe quel plugin repose sur deux mots-clés choisis explicitement : function et with.
function: Aggrega embarque un runtime Wasm (la boîte à outils Extism au-dessus du moteur Wazero), qui exécute Wasm directement en mémoire, de sorte qu’aucun processus du système d’exploitation n’est lancé.functionnomme l’export que l’hôte Go invoque : une fonction explicitement exportée par le module Wasm.with: les entrées propres du plugin, tenues à l’écart desvaluesdu développeur et desparametersqu’une Release satisfait. Le mot-clé suit la convention de GitHub Actions (with:) ; lorsqu’un plugin déclare un JSON Schema pour ses entrées, l’hôte les valide par rapport à celui-ci avant l’exécution.
Les types de Plugins Wasm : Cette interface universelle function et with prend en charge chaque socket programmable du compilateur :
| Type de Plugin | Où il s’exécute | Objectif | Sortie attendue |
|---|---|---|---|
Provider (provider) | Rendu (génération) | Traduit l’IR finale en mémoire en fichiers physiques sérialisés en chaînes pour un format cible (Helm, Terraform, Compose). | Un tableau de fichiers sérialisés en chaînes. |
Étape de pipeline de FeatureRecipe (pipeline-step) | Le pipeline de plugins d’une Recipe ou d’une FeatureRecipe | Étapes séquentielles qui récupèrent des secrets ou injectent des sidecars dans des AST de base. | Des patches RFC 6902 sur l’ensemble de documents indexé par clé, plus des side_effects (émettre un nouveau document ou fichier), des diagnostics et des outputs qu’une étape ultérieure peut lire. L’entrée de l’étape porte cet ensemble de documents indexé par clé et l’entrée with rendue de l’étape. |
Governance (governance) | Avant l’expansion des annotations, construction de la topologie, analyse statique ou étape de rendu | Assure les rôles de gouvernance du pipeline de build. Avant l’expansion des annotations, il injecte des annotations sur les composants résolus, et lors de la construction de la topologie, il étiquette automatiquement les nœuds avec des labels de conformité ou d’environnement (un opérateur en active un pour l’un ou l’autre rôle). Lors de l’analyse statique ou de l’étape de rendu, il agit comme Loud Guardrail : il évalue les arêtes, les chemins et les labels du graphe — ou les artefacts rendus — par rapport aux frontières de sécurité. C’est le rôle auquel il est rattaché, et non son type, qui fixe ce qu’il peut émettre. | Avant l’expansion des annotations, des injections d’annotations. Lors de la construction de la topologie, un tableau de JSONPatch ciblant metadata.labels. Lors de l’analyse statique ou de l’étape de rendu, des verdicts de sévérité halt, warn ou info (une politique Rego les regroupe sous deny, warn et audit) ; un halt arrête le build. |
Linter (linter) | Hors bande | Vérifications FinOps ou d’hygiène facultatives (par ex. estimation des coûts cloud à partir de .infra) et discipline au moment de la publication. | Chaînes d’avertissement ou arrêts fatals. |
Extension de la CLI (cli) | Runtime (aggrega <command>) | Une commande de premier niveau prête à l’emploi, apportée par un plugin signé et exécuté en sandbox, sans aucun code Go par commande dans l’hôte. | Sortie standard et erreur standard diffusées en continu, plus le code de sortie de l’invité. |
Parser (parser) | À la demande, partout où un format étranger est lu | Transforme un texte source étranger (HCL, TOML, YAML, JSON, JSON avec commentaires) en un arbre JSON canonique. | tree plus diagnostics, et des spans de source facultatifs. |
Importer (importer) | À la demande, en dehors de tout build (aggrega import, l’éditeur et l’outil import de l’assistant) | Transforme une source étrangère d’infrastructure ou de définition d’agents (Langflow, Flowise, n8n, une configuration MCP, une application Compose, une application Dify, les agents déclarés d’un projet CrewAI, la configuration d’une application LangGraph, les configurations d’agents d’une application Google ADK, un agent déclaratif d’Agent Framework) en brouillons de fichiers de rédaction Aggrega, en annonçant les formats qu’il gère sous forme de capabilities import:<format>. | Des brouillons d’entités Aggregate / Component / Release, ou des références aux Components du catalogue qu’il réutilise, les décisions de mappage qui les sous-tendent, des diagnostics et les fichiers de scaffold à écrire. |
Le runtime hôte : une sandbox qui refuse les capabilities. Aggrega embarque l’hôte Wasm sous la forme de la boîte à outils Extism s’exécutant au-dessus du moteur Wazero ; le binaire hôte reste du pur Go sans dépendance à une chaîne d’outils native, de sorte que aggrega se compile proprement de manière croisée. Chaque socket s’exécute derrière un pare-feu de pureté AOT : l’hôte refuse d’accorder à un plugin toute capability d’accès à l’exécution — pas de réseau, pas de système de fichiers, pas d’horloge murale, pas d’environnement, pas d’E/S standard — de sorte qu’un appel qui en utiliserait une échoue, et qu’un plugin qui importe depuis une surface de l’hôte que l’hôte ne fournit pas est rejeté au chargement. Un plugin qui ne peut ni atteindre le réseau ni lire l’horloge ne peut pas rompre la garantie ahead-of-time du compilateur selon laquelle la même entrée produit la même sortie. Les runtimes de langage qui ont besoin de quelques imports de démarrage inoffensifs s’exécutent avec une configuration de ces imports qui refuse les capabilities : l’hôte fixe l’horloge observable, fournit une entropie réelle, rejette les E/S standard et n’accorde aucun accès au système de fichiers, aux arguments ni à l’environnement — de sorte qu’un plugin ne peut atteindre aucune capability de l’hôte qui varie d’un build à l’autre. L’entropie est délibérément laissée réelle plutôt que figée : la figer stabiliserait la graine de hachage interne et l’ordre d’itération des maps du runtime d’un langage invité, et masquerait ainsi un plugin dont la propre sortie n’est pas reproductible au lieu de laisser cela apparaître sous forme de sorties divergentes. Un plugin dont le résultat dépend de l’entropie présente un problème de déterminisme au niveau de la rédaction, et cette configuration est conçue pour le révéler plutôt que pour le masquer.
Développer pour l’hôte : le PDK. Les auteurs de plugins n’écrivent pas à la main l’ABI mémoire Wasm. Aggrega fournit un Plugin Development Kit en trois langages — Go, Rust et TypeScript —, de fines surcouches qui présentent l’entrée et la sortie typées de chaque socket afin que l’auteur écrive des fonctions ordinaires. L’interface function / with ci-dessus est ce qu’un Aggregate ou une FeatureRecipe utilise pour invoquer un plugin ; le PDK est ce sur quoi un auteur de plugin développe.
Où chaque socket s’exécute. Chaque socket s’exécute à travers le même hôte : le publishing linter sous aggrega lint ; les rôles de gouvernance, les providers de rendu et les étapes de pipeline des Recipe et des FeatureRecipe pendant aggrega build ; les parsers partout où un format étranger est lu ; les importateurs sous aggrega import ; et les plugins de CLI comme commandes de premier niveau. Voir État du langage pour l’état de préparation de chaque socket.
Quels plugins sont épinglés, et lesquels votre environnement choisit. Aggrega répartit les plugins selon qu’ils modifient ou non la sortie que vous livrez. Les plugins qui façonnent la sortie — les providers de rendu, les plugins de gouvernance rattachés dans un rôle de transformation (label-transform, annotation-transform) et les étapes de pipeline des FeatureRecipe et des Recipe — sont épinglés dans le lockfile de la release lorsque vous exécutez aggrega pull, et reproduits à l’identique, octet pour octet, par aggrega build et aggrega serve à partir de ce seul lockfile. Deux sortes ne sont pas épinglées, car un build lit chacune au même endroit à chaque fois : un provider de rendu servi depuis l’intérieur du binaire du compilateur, et un provider ou une étape de pipeline dont l’entité Plugin est rédigée dans l’un de vos propres répertoires de catalogue. Pour changer le plugin façonnant la sortie qui s’applique, vous refaites un pull ; une modification de la configuration de votre workspace après un pull ne change la sortie d’un build qu’au pull suivant. Les plugins de contrôle — policy et lint — jugent un build sans en modifier les octets ; ils sont donc mis en cache au pull (pour qu’un build puisse encore les exécuter hors ligne ; celui que porte le binaire du compilateur, ou celui rédigé dans votre propre répertoire de catalogue, est lu à cet endroit à la place) mais pas épinglés : le contrôle qui s’exécute est choisi par votre environnement au moment du build, de sorte qu’une répartition permissive en développement / stricte en CI est un choix de configuration ordinaire plutôt qu’un nouveau pull, et changer de contrôles ne modifie jamais la sortie qu’émet un build réussi. Les Plugins qui n’agissent que sur l’entrée de création, comme les importateurs et les extensions de la CLI, ne façonnent aucune sortie de build et ne sont ni épinglés ni inclus dans l’ensemble mis en cache par le build.
2. Pipelines de Plugin des FeatureRecipe
Les FeatureRecipes lient des intentions opérationnelles abstraites (comme l’attachement d’un proxy de sécurité ou l’injection d’un sidecar) à des pipelines de plugins WebAssembly (Wasm) versionnés. Ops déclare ce dont une Feature a besoin sur une cible de provider concrète ; le compilateur exécute le pipeline déclaré sur le graphe IR plat.
Ce lien entraîne trois conséquences pour l’écosystème :
- Découplage de l’évolution. Le vocabulaire de l’infrastructure s’enrichit grâce à des plugins Wasm externes sans nécessiter de nouvelle version du cœur du compilateur Aggrega. Les nouveaux providers, les nouveaux sidecars et les nouvelles intégrations de sécurité sont livrés sous forme de binaires Wasm indépendants reposant sur l’ABI Wasm stable.
- Versionnage sémantique. Les FeatureRecipes référencent les plugins Wasm par version — exacte (
:1.0.0) ou par une plage caret (:^1.0.0, la version la plus élevée compatible avec celle-ci). Avec la plage caret, Ops verrouille une version majeure tout en intégrant ses versions mineures et correctives chaque fois que le lockfile est résolu de nouveau avecaggrega pull --upgrade. - Déport de la complexité. La génération de CRD propres à un fournisseur ou un rendu complexe (objets de policy propres à un fournisseur, ressources de routage natives du provider) résident dans des plugins Wasm purs opérant sur le graphe IR plat, au lieu de transiter par des déclarations de schéma ou une logique de template au sein des définitions de composants.
Chaînage de pipelines — séparer les responsabilités entre plugins. Un pipeline de FeatureRecipe peut enchaîner plusieurs plugins Wasm de manière séquentielle, chacun recevant du compilateur le même contexte de nœud IR. Le schéma standard répartit la responsabilité de sorte qu’un seul plugin ne porte pas à la fois l’intention sémantique d’une fonctionnalité et le mécanisme physique d’interception du trafic d’un environnement cible particulier.
Une chaîne canonique de deux plugins se présente ainsi :
- Un plugin de configuration qui émet les règles sémantiques de la fonctionnalité (règles de policy de sécurité, motifs d’audit, seuils de limitation de débit). Il comprend l’intention de la fonctionnalité ; il ne comprend pas la structure d’interception du trafic de l’environnement cible.
- Un plugin de routage qui émet la configuration physique du mesh qui porte ces règles (CRD de passerelle, patchs d’injection de sidecar, règles de pare-feu). Il comprend la structure de l’environnement cible ; il ne comprend pas l’intention sémantique de la fonctionnalité.
Les deux plugins reçoivent successivement du compilateur le même contexte de nœud IR, de sorte qu’ils se composent proprement sans couplage direct entre eux. Le compilateur orchestre le pipeline ; les plugins portent la connaissance du domaine.
3. Interception du trafic : la cible HTTPRoute
Le modèle d’extensibilité d’Aggrega cible le standard HTTPRoute de la Kubernetes Gateway API comme artefact commun à tous les providers pour l’interception du trafic au niveau du mesh. La bibliothèque standard émet des objets HTTPRoute via la Feature core/http-route, dont la FeatureRecipe helm rend une route par composant rattaché ; les environnements cibles qui consomment la Gateway API traduisent HTTPRoute vers leurs structures natives.
4. Autonomie du Plugin : résolution des labels
Lorsque des plugins Wasm génèrent des ressources physiques à partir du graphe IR, les SRE doivent pouvoir remonter d’un Pod Kubernetes en cours d’exécution ou d’une ressource cloud jusqu’à l’intention sémantique du développeur dans l’Aggregate. Le modèle d’extensibilité d’Aggrega place entièrement cette traduction sous le contrôle de l’auteur du plugin Wasm.
Le compilateur transmet l’intégralité du dictionnaire labels du graphe IR au bac à sable Wasm, sans l’interpréter. L’auteur du plugin — Platform Ops — décide ensuite de la logique de correspondance : transmettre tous les labels tels quels, filtrer selon des préfixes de domaine précis (*.aggrega.ai/*) ou faire correspondre directement les labels du graphe aux schémas de balisage natifs du provider (en traduisant un label IR en tags AWS, en annotations Kubernetes ou en un mécanisme de métadonnées propre au cloud). Le compilateur n’impose aucune restriction sur la façon dont les artefacts générés sont balisés.
Cette autonomie maintient l’intelligence propre au domaine — quels labels comptent pour l’observabilité, lesquels correspondent aux conventions de balisage natives, lesquels sont internes à la plateforme — dans la couche des plugins Wasm, où l’écosystème évolue indépendamment du rythme de publication du compilateur Go.
5. Extensions de la CLI : commandes d’exécution
Les sockets ci-dessus s’exécutent à l’intérieur d’un build — le compilateur les appelle pendant qu’il analyse, transforme, valide et rend un Aggregate. Le socket des extensions de CLI est d’une autre nature : il s’exécute dans le terminal, en dehors de tout build, lorsqu’un opérateur tape aggrega <command>. C’est ainsi que la surface de commandes d’aggrega elle-même s’enrichit sans nouvelle version du cœur.
Ce qu’est une extension de CLI. Une extension de CLI est une commande aggrega <command> prête à l’emploi fournie par un plugin Wasm signé et exécuté en bac à sable. Elle adopte la même approche drop-in, avec la logique côté invité, que le socket de rendu : la logique métier réside entièrement dans l’invité, et l’hôte Go n’ajoute aucun code propre à chaque commande. Ajouter une nouvelle commande de premier niveau ne demande que trois éléments — un binaire .wasm, une entité Plugin déclarant pluginType: cli (voir Plugin) et un aggrega plugin add cli explicite. L’hôte découvre la commande à partir de l’autodescription du plugin installé ; aucune commande n’est compilée dans le binaire.
Pourquoi un socket d’exécution peut faire ce qu’un socket de build ne peut pas. Comme les sockets de compilation s’exécutent pendant un build, ils restent privés de capacités et déterministes : Aggrega est un compilateur ahead-of-time, et la même entrée doit toujours produire la même sortie (voir Invariants architecturaux). Un plugin de rendu ou de policy ne peut donc ni accéder au réseau, ni lire l’horloge, ni diffuser vers le terminal — tout ce qui varie d’une exécution à l’autre romprait cette garantie. Une extension de CLI s’exécute après cette frontière et en dehors d’elle, pilotée par une personne à une invite de commande plutôt que par le pipeline déterministe. C’est précisément pourquoi un plugin de CLI peut diffuser la sortie standard et l’erreur standard pendant son exécution et renvoyer un code de sortie de processus : il n’existe aucun artefact de build dont ces effets pourraient menacer la stabilité octet pour octet.
Installer, exécuter et découvrir. aggrega plugin add cli <query> recherche dans le registre configuré un plugin cli correspondant, le vérifie au regard de la politique de confiance du registre et l’installe comme commande de premier niveau — en affichant d’abord les capacités déclarées du plugin, afin que l’opérateur confirme exactement ce que la commande est autorisée à faire avant son installation. Une fois installée, aggrega <command> l’exécute comme n’importe quelle commande intégrée. Un plugin de CLI déclare ses commandes et leurs flags dans son autodescription describe(), et l’hôte affiche les flags de chaque commande dans aggrega help <command> exactement comme pour une commande intégrée, de sorte qu’un opérateur découvre les --flags d’une commande installée de la même manière. Pour trouver des commandes installables et du contenu de catalogue, aggrega search interroge l’index local des registres configurés — --kind plugin --plugin-type cli restreint les résultats aux plugins de CLI installables, et une recherche sans filtre couvre les entités du catalogue ; aggrega plugin list affiche ce qui est déjà installé. Les flags et les formes de sortie propres à chaque commande figurent sur ces pages de référence.
Le modèle de capacités. Une extension de CLI part d’un socle fixe que chaque commande reçoit sans déclaration ni demande de confirmation :
| Capacité du socle | Accordée |
|---|---|
| Arguments de ligne de commande en entrée | Toujours |
| Sortie standard et erreur standard diffusées en continu | Toujours |
| Code de sortie du processus en sortie | Toujours |
Tout ce qui dépasse le socle est désactivé par défaut. Un plugin qui a besoin de davantage déclare explicitement chaque capacité supplémentaire, et l’hôte ne l’accorde qu’après l’avoir présentée à l’installation pour que l’opérateur la confirme. Une classe de capacités ajoutée au-delà du socle — accès à l’environnement, au système de fichiers ou au réseau, saisie interactive — est accordée derrière le même contrôle de déclaration et de confirmation, de sorte qu’une commande ne peut jamais acquérir en silence une portée que l’opérateur n’a pas approuvée.
Les commandes intégrées l’emportent toujours. Un plugin installé ne peut jamais masquer une commande intégrée. Une protection des noms réservés, adossée à une liste de refus, protège les commandes intégrées et un ensemble de noms réservés aux commandes intégrées, et une collision est refusée à l’installation au lieu de pouvoir remplacer le comportement du cœur. La surface de commandes sur laquelle s’appuie un opérateur reste stable, quoi qu’on installe par-dessus.
6. Plugins d’analyse : lecture de formats étrangers
Le compilateur doit régulièrement lire du texte écrit dans un format dont il n’est pas l’auteur — un module Terraform en HCL, un fichier de configuration en TOML, un manifeste en YAML ou en JSON. Le socket des analyseurs fournit cette capacité de lecture sans enseigner un format particulier au cœur du compilateur. Un analyseur est un plugin sans état qui transforme un texte source étranger en un arbre JSON structuré : donnez-lui les octets d’un fichier HCL et il renvoie le même contenu sous forme d’un objet JSON que le reste du pipeline sait déjà parcourir. Toute partie du compilateur qui doit lire un format qu’elle n’analyse pas nativement demande un arbre analysé et travaille à partir de celui-ci.
Un format est une capacité, pas une fonctionnalité du compilateur. Un analyseur annonce les formats qu’il prend en charge sous forme de capacités — parse:hcl, parse:toml, etc. — et l’hôte résout un analyseur d’après le format demandé, l’exécute et renvoie l’arbre. C’est le même modèle drop-in, fondé sur les capacités annoncées, que suivent les providers de rendu et les plugins de CLI : le cœur du compilateur ne contient aucune liste intégrée de formats, de sorte qu’en ajouter un revient à livrer un nouveau plugin d’analyse, jamais une nouvelle version du cœur. Des analyseurs pour HCL, TOML, YAML, JSON et JSON avec commentaires sont livrés dans le binaire comme ensemble de départ ; une entreprise qui a besoin d’un autre format livre un plugin d’analyse qui l’annonce.
La sélection du format est déclarative, jamais devinée. L’hôte n’inspecte jamais le contenu d’un fichier pour décider de ce qu’il est. Il choisit un format à partir de signaux déclarés, selon un ordre de préférence fixe. Un provider de rendu peut déclarer le format de chaque fichier qu’il émet, et l’hôte préfère sans réserve ce format déclaré par le producteur — le provider qui a écrit les octets fait autorité sur la manière de les lire. Pour un fichier que le producteur n’a pas étiqueté, une table fixe des extensions de fichier sert de solution de repli — .tf sélectionne HCL, .toml sélectionne TOML, .yaml sélectionne YAML, .json sélectionne JSON. Choisir d’après un format déclaré ou une extension fixe garde l’analyse déterministe et lisible : la même entrée est toujours acheminée vers le même analyseur, et un opérateur peut savoir quel analyseur s’exécutera sans connaître les octets du fichier. La détection par le contenu ferait dépendre le choix de la charge utile, et Aggrega ne la pratique pas.
Un analyseur est purement syntaxique. La sortie est un arbre JSON accompagné de diagnostics et, en option, des emplacements source d’où provient chaque nœud. Un analyseur ne porte aucune signification Aggrega — il rend compte de ce que le texte dit structurellement, et de rien de ce qu’il signifie en tant que Component, Recipe ou autre entité. Transformer un arbre analysé en entités Aggrega est une préoccupation distincte qui se trouve ailleurs ; l’unique tâche de l’analyseur est une traduction fidèle de la syntaxe en JSON. Le sens de lecture est à sens unique dans le même esprit : un analyseur lit un format vers un arbre, il ne réécrit pas un format en sortie.
Un consommateur : une policy sur du HCL Terraform. Une policy de l’étape de rendu qui doit inspecter le Terraform produit par un build n’apprend pas elle-même le HCL. L’hôte analyse l’artefact HCL via le socket des analyseurs et transmet au plugin de policy l’arbre JSON qu’il lit déjà, de sorte que la policy raisonne sur des données structurées de la forme que reçoit tout autre socket. Les nouveaux lecteurs de formats étrangers se composent de la même façon — demander l’arbre à l’hôte, puis travailler en JSON — de sorte que la capacité du compilateur à comprendre un format s’accroît par l’ajout de plugins d’analyse plutôt que par l’accroissement du cœur.
7. Plugins d’import : ébauche de fichiers de création à partir de sources étrangères
Une équipe part rarement d’une page blanche. Son architecture d’agents existe souvent déjà ailleurs — un flow Langflow ou Flowise, un workflow n8n, une application Dify, les serveurs MCP avec lesquels un client est configuré, une application Compose, les agents que déclare la configuration d’un framework. Le socket des importateurs transforme cette source étrangère en un point de départ concret pour la création Aggrega : il lit la source et génère des ébauches d’entités Aggregate et Component et, à partir d’une configuration MCP, d’une application Compose ou de la configuration déclarée d’un framework, une ébauche de Release, qu’un auteur relit et termine, de sorte qu’une équipe transpose dans Aggrega ce qu’elle possède déjà au lieu de le réécrire à la main. Un importateur fait correspondre le sens — il lit ce qu’est un nœud source et propose l’entité Aggrega qui le représente, ou le laisse dans le flow que porte la plateforme ébauchée ; le compilateur transmet les entités émises de manière opaque, exactement comme il reste agnostique vis-à-vis de ce que produit tout plugin.
Un format est une capacité, pas une fonctionnalité du compilateur. Un importateur annonce les formats qu’il prend en charge sous forme de capacités — import:langflow, import:flowise, import:n8n, import:mcp, import:compose, import:dify, import:crewai, import:langgraph, import:google-adk, import:agent-framework, etc. — et l’hôte résout un importateur d’après le format demandé, l’exécute et récupère les entités qu’il a ébauchées. C’est le même modèle drop-in, fondé sur les capacités annoncées, que suit le socket des analyseurs avec parse:<format> : le cœur du compilateur ne contient aucune liste intégrée de formats importables, de sorte que prendre en charge un nouveau format revient à livrer un plugin d’import qui l’annonce, jamais une nouvelle version du cœur.
Un importateur lit via le socket des analyseurs ; il ne réanalyse pas. Un importateur a besoin de la forme structurée de sa source, mais il ne réimplémente pas la lecture d’un format que l’écosystème analyse déjà. Lorsqu’il a besoin de l’arbre, il demande à l’hôte d’exécuter l’analyseur correspondant — celui que le catalogue du workspace sert pour la syntaxe de la source ou, lorsque le catalogue n’en sert aucun, celui que porte le compilateur lui-même — via la même capacité d’analyse, servie par l’hôte, qu’utilise le reste du pipeline, et travaille à partir de l’arbre JSON renvoyé. La lecture (de la syntaxe à l’arbre) reste le travail de l’analyseur ; la correspondance (de l’arbre aux entités Aggrega) est celui de l’importateur. Les deux sockets se composent sans se dupliquer : un importateur ajoute l’intelligence de correspondance pour une source et s’appuie sur l’analyseur existant pour les octets.
Un format est reconnu d’après ce que déclare son importateur, jamais deviné. Un import peut nommer directement son format source. Lorsqu’il ne le fait pas, le format est reconnu à partir des signatures que chaque importateur déclare dans son autodescription et que son entité Plugin consigne : la syntaxe dans laquelle une source est lue, les noms de fichiers auxquels une signature s’applique, et les chemins que l’arbre analysé doit ou ne doit pas contenir. L’hôte ne connaît aucun format par lui-même. Il analyse la source via l’analyseur que le catalogue du workspace sert pour chaque syntaxe que nomme une signature — ou celui du compilateur lorsque le catalogue n’en sert aucun —, évalue les prédicats déclarés sur l’arbre renvoyé et lit la source comme étant au format du seul importateur dont la signature correspond. Les signatures déclarées tiennent la place qu’occupe une table fixe des extensions de fichier pour le socket des analyseurs, car les formats qu’un import lit peuvent partager une extension — un export Langflow, un export Flowise et un workflow n8n sont tous des fichiers JSON. Une source à laquelle aucune signature ne correspond est refusée, avec une demande du format et la liste des formats annoncés par les importateurs — ou, pour un répertoire, avec une demande de l’un de ses fichiers pris isolément ou d’un format dont l’importateur déclare des motifs de fichier, et la liste de ces seuls formats ; une source à laquelle correspondent les signatures de plus d’un format est refusée, avec la liste de ces formats. La reconnaissance ne lit rien d’autre que la source et n’accède à aucun réseau, de sorte que reconnaître un nouveau format est une déclaration que livre le nouvel importateur, jamais une modification de l’hôte. Les règles d’écriture d’une signature figurent sous Le socket des importateurs.
Un répertoire est lu à travers les fichiers que déclare son importateur. Une source est un fichier ou un répertoire. Un fichier est remis entier à l’importateur. Un répertoire est lu sous forme de sources nommées — exactement ceux de ses fichiers que sélectionnent les motifs de fichiers des signatures de l’importateur, chacun nommé par son chemin à l’intérieur du répertoire, dans un ordre trié — et aucun autre fichier du répertoire n’est ouvert ; un lien qui ferait sortir la lecture du répertoire est refusé avant toute lecture. Un importateur qui ne déclare aucun motif de fichier lit un seul fichier et refuse un répertoire, et un répertoire ne contenant aucun fichier que sélectionnent les motifs d’un importateur est également refusé. Les importateurs Langflow, Flowise, n8n, Dify et Agent Framework du compilateur n’en déclarent aucun, de sorte que chacun lit un seul fichier exporté de flow, de workflow ou d’application, ou un seul agent déclaratif ; son importateur MCP déclare les noms de fichiers des configurations de client MCP qu’il lit, de sorte que le répertoire d’un projet est lu à travers les configurations qu’il contient ; son importateur Compose déclare les noms de fichiers que Compose lit par défaut, de sorte que le répertoire d’un projet est lu à travers son fichier Compose et le fichier de surcharge que Compose fusionne par-dessus ; et son importateur CrewAI déclare les noms de fichiers sous lesquels un projet CrewAI déclare ses agents et ses tâches, de sorte que le répertoire d’un projet est lu à travers ces déclarations et que son programme n’est jamais lu ; et son importateur LangGraph déclare langgraph.json, de sorte que le répertoire d’une application est lu à travers sa seule configuration, son code et ses fichiers d’environnement n’étant jamais lus, un fichier d’environnement que nomme la configuration ne parvenant à l’importateur que là où le with.sources de son attachement le lui remet, et alors uniquement pour les noms des variables ; et son importateur Google ADK déclare root_agent.yaml, de sorte que le répertoire d’une application est lu à travers la seule configuration de son agent racine, les configurations que nomment ses sous-agents ne parvenant à l’importateur que là où le with.sources de son attachement les lui remet, et ni son code ni son fichier d’environnement n’étant jamais lus.
La correspondance est déterministe, notée par un indice de confiance et évaluée par rapport à votre propre catalogue. L’hôte remet à l’importateur une vue des Components que contient le propre catalogue du workspace — le catalogue dans lequel l’importateur a été sélectionné — les dossiers de catalogue du workspace ou, s’il n’en nomme aucun, l’instantané du catalogue que publie son registre par défaut — les Components d’un catalogue d’entreprise exactement comme ceux de la bibliothèque standard. La vue indique le nom, la version et les labels de chaque Component, les noms de clés que déclarent ses values et ses provides, et les sélecteurs de ses sockets, et jamais une valeur, une valeur par défaut ou un secret ; rien n’est récupéré pour la construire au-delà de cet instantané, et son ordre est fixe, de sorte qu’un catalogue donne une seule vue. Un importateur construit sur le package importer du PDK Go — dont les importateurs Langflow, Flowise, n8n et Compose du compilateur lui-même — évalue chaque nœud de la source par rapport à ces Components et à rien d’autre, avec un modèle de confiance déterministe sans modèle d’IA, et consigne la décision — les candidats évalués, le niveau de correspondance attribué et le choix effectué — sous forme d’indications révisables qu’un auteur peut lire et modifier. Un Component que le catalogue acquiert devient un candidat lors de l’import suivant, sans reconstruire d’importateur. Par défaut, il ne s’agit que d’indications : l’import propose, et l’auteur décide. Une correspondance à confiance élevée peut être écrite comme référence à un composant existant du catalogue au lieu d’un corps fraîchement ébauché, mais uniquement lorsque l’opérateur l’active explicitement — toujours comme une suggestion explicite et réversible que l’auteur valide, jamais comme une réécriture silencieuse. Comme la notation ne fait intervenir aucun modèle ni aucune consultation à l’exécution, la même source évaluée par rapport au même catalogue produit toujours les mêmes indications.
Un flow est ébauché sous la forme de la plateforme qui l’exécute. Un flow Langflow, un chatflow Flowise et un workflow n8n s’exécutent sur une plateforme, et par défaut un import ébauche cette plateforme plutôt que les nœuds du flow : une instance du Component de plateforme de la bibliothèque standard — core/ai-agent/langflow, core/ai-agent/flowise ou core/ai-agent/n8n — qui porte le flow tel qu’il a été exporté dans sa valeur flow_definition, que la plateforme charge au déploiement. Chaque partie du flow que prend un socket de la plateforme — sur les plateformes de la bibliothèque standard, un modèle, un serveur MCP ou un autre outil atteint via HTTP, et un vector store — devient un Component à part entière, référencé ou ébauché selon ce que décide la correspondance, et est raccordée à ce socket sous le uses de la plateforme. Ainsi, chaque appel que fait le flow à un modèle, à un outil ou à un store est une connexion que déclare l’Aggregate : un plugin de gouvernance qui juge le graphe la voit comme il voit toute autre arête, et l’allowlist d’egress de la bibliothèque standard, que le paramètre attach_egress_allowlist attache à la plateforme, ne permet à la plateforme de se connecter qu’à ce que ses connexions atteignent, à ses propres pods et au DNS du cluster. Lorsque le format le permet, l’ébauche écrit dans le flow porté ce qui permet au flow d’atteindre chaque partie par sa connexion. Tout autre nœud — un agent, une chaîne, un déclencheur — reste dans le flow porté et ne devient aucun Component, sa décision consignant les candidats par rapport auxquels il a été évalué. Une application Dify est ébauchée de la même manière, sous la forme que prend une installation complète : une entrée de l’installation Dify qu’assemble la bibliothèque standard, core/dify, qui porte l’application dans son paramètre app_definition, l’installation raccordant ses propres connexions. Le paramètre layout de l’attachement de l’importateur choisit l’ébauche : platform, la valeur par défaut, ou nodes, qui ébauche chaque nœud de la source comme un Component à part entière, chaque arête du flow comme une connexion uses, et ne porte aucun flow. La plateforme qui porte le flow expose quels nœuds deviennent des parties et où chacun est raccordé.
Un framework code-first est lu à travers sa configuration déclarée, jamais à travers son programme. CrewAI, LangGraph, Google ADK et Agent Framework conservent le comportement d’une application dans son programme et déclarent ses agents, ses graphes et ses modèles dans une configuration placée à côté. Leurs importateurs ne lisent que ces déclarations — les fichiers d’agents et de tâches d’un projet CrewAI, le langgraph.json d’une application LangGraph, les configurations d’agents d’une application Google ADK, un agent déclaratif Agent Framework — et ébauchent l’agent de la bibliothèque standard pour le framework autour d’un programme qu’ils n’ouvrent jamais, raccordé à ce que nomment les déclarations : le modèle que demande un agent, là où le socket model de l’agent l’accepte, et le datastore dans lequel un checkpointer LangGraph conserve l’état. Un serveur MCP que nomme un agent Agent Framework est atteint par le fournisseur du modèle, en tant qu’outil hébergé ; l’ébauche le nomme donc dans des commentaires et n’y raccorde rien. Le programme s’exécute dans l’image que nomme la Release. Ce que seul le programme exprime — la logique d’une tâche, un outil que définit son code, un agent que construit son code — est nommé dans les commentaires et les décisions de l’ébauche et ne devient aucun Component ; le transposer dans des fichiers de création est le travail de l’auteur, à la main ou avec un assistant d’IA qui rédige pour le compte de l’auteur via aggrega mcp, lequel lit la référence, génère et valide des entités.
Ce qu’une source indique sur la façon dont ses parties s’exécutent aboutit dans une ébauche de Release. Fournir les entrées opérationnelles revient à la Release ; les importateurs MCP, Compose, CrewAI, LangGraph, Google ADK et Agent Framework ébauchent donc une Release à côté de l’Aggregate, que nomme son spec.aggregate : la Release porte ce qu’indique la source — la ligne de commande ou l’adresse d’un serveur, l’image et le port d’un serveur générique, le point de terminaison d’un modèle — et, dans des commentaires au-dessus de chaque entrée, ce que la source indique sans qu’aucune clé du Component ébauché ne le prenne, comme les volumes d’un service ou l’environnement d’une configuration. Ce qu’aucune source n’indique — l’image qui exécute le programme d’un framework, l’identifiant que présente une connexion, le metadata.environment et le spec.manifest de la Release — est nommé dans un commentaire à l’endroit voulu, pour que l’opérateur le fournisse, et le build s’arrête en nommant celui de l’image, de l’environnement et du manifeste qui n’est pas encore défini. Une ébauche de plateforme n’écrit aucune Release : le commentaire au-dessus de l’instance de la plateforme nomme ce que fournit la Release — les entrées propres à la plateforme, comme l’image qu’elle exécute ou son compte propriétaire, l’adresse de chaque serveur MCP raccordé et l’identifiant que présente chaque connexion.
Une valeur d’identifiant que contient une source est reprise telle quelle, sauf si sa suppression est demandée. Un importateur repère chaque valeur de sa source susceptible de porter un identifiant, chacune d’une classe : ce que le format marque comme identifiant, un membre de la configuration d’un serveur MCP, ou une entrée que le format marque comme n’étant pas un identifiant mais qui peut tout de même en porter un, comme les en-têtes d’une requête. Par défaut, aucune n’est écrite vide : chaque valeur contenant quelque chose est reprise telle quelle — dans le flow ou l’application que porte la plateforme, ou dans l’ébauche de Release — et nommée dans un avertissement credential-carried par son emplacement — son nœud, serveur, service ou agent, et son champ — jamais par sa valeur, avec la valeur de paramètre qui l’écrit vide. Le paramètre empty_credentials active la suppression, une classe à la fois : marked écrit vide ce qu’un format marque comme identifiant ainsi que chaque membre de la configuration d’un serveur MCP, et all également les entrées marquées comme n’étant pas des identifiants, chaque valeur écrite vide étant signalée par credential-emptied. Ce que l’ébauche écrit pour qu’un flow atteigne sa connexion relève du câblage, écrit quel que soit le paramètre, et une connexion dans l’ébauche ne porte aucun identifiant : la Release attache celui que présente chaque connexion. Un fichier vers lequel une source se contente de pointer, comme un fichier d’environnement, n’est lu que pour les noms de ses variables, lorsqu’il est lu, et une ébauche faite nœud par nœud ne lit aucune valeur. Ce qui se trouve hors des emplacements qu’un importateur repère — le code d’un composant personnalisé, un prompt — revient à l’auteur, qui doit le relire avant de partager une ébauche, comme l’expose Valeurs d’identifiant que contient le flow.
La commande, l’éditeur et l’assistant exécutent une seule et même importation. aggrega import <file or directory> exécute une importation depuis le terminal ; l’éditeur exécute la même opération via la requête aggrega/import de sa session, et un assistant IA via l’outil import exposé par aggrega mcp. Tous trois sélectionnent l’importateur de la même manière, parmi les importateurs que contient le catalogue de l’espace de travail et les importateurs de base du compilateur : celui que désigne un rattachement plugins.importer, s’il en désigne un qui annonce le format, et sinon la version la plus élevée de l’unique importateur qui l’annonce — des importateurs de deux noms pour un même format, sans qu’aucun ne soit rattaché, arrêtent l’importation, qui les nomme tous les deux, comme l’expose Quel importateur transforme une source en brouillons. Tous trois rapportent les décisions de correspondance à côté des brouillons. La commande affiche sur la sortie d’erreur standard une ligne par nœud mis en correspondance, indiquant le Component ou le brouillon choisi pour lui, s’il est référencé ou généré en brouillon, le niveau de correspondance et, lorsque l’importateur a évalué un candidat, le score du meilleur candidat ; l’éditeur affiche les mêmes lignes, et le résultat de la session de l’éditeur ainsi que la réponse de l’assistant portent chaque décision en entier. Ainsi, un auteur voit où l’importation a deviné, quelle que soit la surface qui l’a exécutée, sans ouvrir les brouillons. --format indique explicitement le format de la source — par exemple langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk ou agent-framework — à la place de la reconnaissance. La commande dépose les entités et les éventuels fichiers d’échafaudage produits par l’importation sous la racine de l’espace de travail, ou sous le répertoire que désigne --output-dir ; --dry-run fait tout ce que fait la commande sauf écrire, en renvoyant les fichiers générés sous forme de contenu et en indiquant le fichier auquel chacun est destiné, afin qu’un auteur puisse relire l’échafaudage avant de valider quoi que ce soit dans l’arbre de travail.
Les importateurs du cœur. Les importateurs du cœur que livre le compilateur lisent ces formats, un importateur pour chacun :
- Langflow — un flow exporté depuis Langflow, ébauché sous la forme de la plateforme Langflow de la bibliothèque standard qui porte le flow, chacune de ses parties que prend un socket étant raccordée à ce socket.
- Flowise — un chatflow ou un agentflow exporté depuis Flowise, ébauché sous la forme de la plateforme Flowise de la bibliothèque standard qui le porte, chacune de ses parties que prend un socket étant raccordée à ce socket.
- n8n — un workflow exporté depuis n8n, ébauché sous la forme de la plateforme n8n de la bibliothèque standard qui le porte, chacune de ses parties que prend un socket étant raccordée à ce socket.
- Dify — une application exportée depuis Dify, ébauchée sous la forme de l’installation Dify qu’assemble la bibliothèque standard et qui porte l’application, les modèles, outils et bases de connaissances qu’elle nomme étant signalés comme configurés dans Dify.
- MCP — la configuration d’un client MCP ou la description d’un serveur d’un registre MCP, chaque serveur étant ébauché comme une instance de l’outil MCP de la bibliothèque standard, avec une
Releasequi porte la ligne de commande, l’adresse ou l’image de chaque serveur. - Compose — un format d’infrastructure, chaque service d’une application Compose étant ébauché comme le Component du catalogue auquel correspond son image — au moyen d’une table que porte l’importateur, générée à partir des Recipes et des Components Compose du catalogue standard lors de sa construction — ou comme un serveur générique exécutant son image, avec une
Releasequi porte l’image et le port de chaque serveur générique et, dans des commentaires, les ports, les volumes et l’environnement que déclare chaque service. - CrewAI — les agents qu’un projet CrewAI déclare dans ses fichiers de configuration, chacun ébauché comme l’agent CrewAI de la bibliothèque standard portant son rôle, son objectif et son histoire, et raccordé au modèle qu’il nomme, les tâches et les outils du projet étant signalés comme relevant de son programme, le programme lui-même n’étant jamais lu, avec une
Releasequi laisse à l’opérateur le soin de nommer l’image qui l’exécute. - LangGraph — les graphes que déclare la configuration d’une application LangGraph, chacun ébauché comme l’agent LangGraph de la bibliothèque standard portant le chemin d’import de son graphe et raccordé au datastore dans lequel son checkpointer conserve l’état, avec une
Releasequi indique, dans un commentaire, l’environnement que déclare la configuration, le code des graphes n’étant jamais lu. - Google ADK — les arbres d’agents que déclarent les configurations d’agents d’une application Google ADK, chacun ébauché comme l’agent ADK de la bibliothèque standard raccordé au modèle qu’il nomme lorsque ADK envoie les requêtes de ce modèle à l’API Gemini, un modèle atteint de toute autre manière — par une chaîne de modèle LiteLLM, par exemple — étant nommé dans un commentaire et sa connexion laissée à l’auteur, avec une
Releasequi laisse à l’opérateur le soin de nommer l’image qui exécute l’application, le code de l’application n’étant jamais lu. - Agent Framework — un agent déclaratif Agent Framework, ébauché comme l’agent Agent Framework de la bibliothèque standard raccordé au modèle OpenAI qu’il nomme, chaque serveur MCP qu’il nomme étant écrit dans des commentaires puisque le fournisseur du modèle l’atteint en tant qu’outil hébergé, avec une
Releasequi porte le point de terminaison du modèle et, dans un commentaire, l’adresse de chaque serveur, le code de l’application n’étant jamais lu.
Ce sont des plugins d’import comme les autres — l’intelligence de correspondance propre à chaque format réside en eux, non dans le cœur — construits à partir des sources du compilateur et publiés avec chaque version du compilateur, au numéro de cette version. Aucun n’est compilé dans le binaire : le binaire porte l’entité Plugin de chacun et l’empreinte de l’unique module qu’il accepte, de sorte que chacun sert son format dans chaque workspace sans entrée de catalogue. Le premier import qui a besoin d’un importateur absent de la machine le récupère depuis le registre par défaut du workspace, le lie à cette empreinte, le vérifie comme un pull vérifie un plugin qu’il récupère — sa signature selon la politique de confiance de ce registre, et les fonctions hôtes qu’il utilise — et le conserve dans le cache de contenu du workspace ; chaque import ultérieur le lit à cet endroit, sans accès au réseau pour lui. Un import n’épingle aucun importateur : rien d’autre n’est écrit pour lui — aucune entrée de lockfile ni aucun enregistrement de plugins de confiance — et aucun pull ne le met en cache ni aucun build ne le lit. Un module dont la vérification échoue est refusé, et rien n’est conservé. Lorsque le module ne peut pas être récupéré — le workspace est hors ligne, son registre est injoignable ou le registre ne le contient pas —, l’import s’arrête en nommant l’importateur, sa version et ce qui place son module sur la machine. Le choix reste celui du workspace : un importateur que son catalogue contient sous un autre nom pour l’un de ces formats s’exécute là où un attachement plugins.importer le nomme, et un importateur de même nom et de même version qu’un importateur du cœur s’exécute à sa place.
Amorcer et faire grandir un catalogue
Un catalogue n’a pas à être construit à partir de rien. L’essentiel du travail d’amorçage de Recipes et de plugins pour un nouvel environnement relève de l’échafaudage et de la réutilisation plutôt que de l’écriture à la main de chaque binaire.
Importer une source externe en brouillons de fichiers d’authoring. aggrega import <file or directory> lit une source déclarative de définition d’agents — un flow Langflow ou Flowise, un workflow n8n, ou la configuration d’un client MCP ou la description d’un serveur d’un registre MCP —, une application Compose, une application Dify, les agents que déclare un projet CrewAI, les graphes que déclare la configuration d’une application LangGraph, les agents que déclarent les configurations d’agents d’une application Google ADK, ou un agent déclaratif Agent Framework, et génère un premier brouillon de YAML Aggregate et Component, et, à partir d’une source MCP, Compose, CrewAI, LangGraph, Google ADK ou Agent Framework, une Release en brouillon, qu’un auteur relit et termine, afin qu’une équipe reprenne ce qu’elle possède déjà au lieu de le réécrire à la main. Pour chaque nœud d’un flow, et chaque service d’une application Compose, il attribue un score aux Components du catalogue propre à l’espace de travail — celui d’un catalogue d’entreprise autant que celui de la bibliothèque standard — à l’aide d’un modèle de confiance déterministe et sans modèle, et consigne la décision — les candidats évalués, le niveau attribué et le choix effectué — sous forme d’indications vérifiables, que la commande, l’éditeur et l’assistant rapportent tous ; une correspondance de confiance élevée peut être écrite comme référence au catalogue lorsque l’opérateur l’active, toujours comme une suggestion explicite et réversible que l’auteur valide plutôt que comme une réécriture silencieuse. Chaque Component qu’un catalogue gagne est un candidat que la prochaine importation évalue. L’intelligence de correspondance propre à chaque format réside dans un plugin importateur : les importateurs Langflow, Flowise, n8n, MCP, Compose, Dify, CrewAI, LangGraph, Google ADK et Agent Framework du compilateur servent ces formats dans chaque espace de travail, récupérés et vérifiés à la première utilisation, et un catalogue ajoute un format en contenant un plugin importateur qui l’annonce. Une source de type répertoire est lue à travers les motifs de fichiers que déclare son importateur ; les importateurs Langflow, Flowise, n8n, Dify et Agent Framework n’en déclarent aucun, et chacun lit un seul fichier exporté ou agent déclaratif, tandis que l’importateur MCP lit les configurations client que contient un répertoire, l’importateur Compose ses fichiers Compose, fusionnés comme Compose les fusionne, l’importateur CrewAI les déclarations d’un projet, jamais son programme, l’importateur LangGraph la configuration d’une application, jamais son code ni un fichier d’environnement — dont il ne lit les noms que lorsque son rattachement lui remet le fichier —, et l’importateur Google ADK la configuration de l’agent racine d’une application, jamais son code ni son fichier d’environnement, les configurations de ses sous-agents étant lues lorsque son rattachement les lui remet — une configuration qu’ADK déclare expérimentale, dont les agents utilisent par défaut un modèle Gemini et atteignent par leur nom les modèles d’autres fournisseurs au moyen de classes propres à ADK, ou au moyen d’une chaîne de modèle LiteLLM.
L’essentiel du travail sur les plugins relève des modèles, pas du code compilé. Une grande part des fonctionnalités se contente d’injecter un sidecar statique, une variable d’environnement ou un label — un simple JSONPatch sans logique conditionnelle. Un seul plugin patcher configurable, écrit une fois pour prendre un modèle JSONPatch déclaratif comme entrée with, peut couvrir ce cas courant sans binaire compilé propre à chaque fonctionnalité : l’auteur écrit un modèle, et pour de nombreuses cibles de type CRD, un modèle valuesMapping (faisant souvent référence à des fragments partagés dans une entrée de MappingLibrary) suffit à lui seul. Les plugins PDK écrits sur mesure sont destinés au reste, réellement conditionnel.
S’appuyer sur des outils établis. Lorsqu’ils écrivent une nouvelle logique de plugin, les auteurs peuvent consulter les formes de sortie publiquement documentées d’outils open source établis — la structure des CRD, des patchs ou des modèles que ces outils sont connus pour émettre — comme référence pour la forme cible qu’un nouveau plugin doit produire, tout en respectant la licence de chaque projet. Les webhooks d’injection de sidecars, les bibliothèques de constructions de plus haut niveau, les générateurs de CRD pour opérateurs et les catalogues de traits ou de composition publient tous des structures de sortie très proches de ce qu’une FeatureRecipe ou un plugin comparable doit émettre. L’objectif est de respecter un contrat de sortie bien compris, non de copier l’implémentation d’un projet.