Estensibilità
Estensibilità dell’ecosistema e guardrail del compilatore
1. L’interfaccia universale WebAssembly (Wasm)
Per garantire la simmetria architetturale in tutto l’ecosistema, Aggrega utilizza un contratto di esecuzione standardizzato che si applica in modo uniforme a ogni socket Wasm nella pipeline del compilatore.
L’interfaccia YAML per invocare qualsiasi plugin si basa su due parole chiave scelte esplicitamente: function e with.
function: Aggrega incorpora un runtime Wasm (il toolkit Extism sopra il motore Wazero) ed esegue Wasm direttamente in memoria, quindi non viene avviato alcun processo del sistema operativo.functionnomina l’export che l’host Go invoca: una funzione esportata esplicitamente dal modulo Wasm.with: gli input propri del plugin, tenuti separati daivaluesdello sviluppatore e daiparametersche una Release soddisfa. La parola chiave segue la convenzione di GitHub Actions (with:); quando un plugin dichiara un JSON Schema per i suoi input, l’host li convalida rispetto a esso prima dell’esecuzione.
I tipi di Plugins Wasm: Questa interfaccia universale function e with supporta ogni socket programmabile del compilatore:
| Tipo di Plugin | Dove viene eseguito | Scopo | Output atteso |
|---|---|---|---|
Provider (provider) | Rendering (generazione) | Traduce l’IR finale in memoria in file fisici serializzati come stringhe per un formato di destinazione (Helm, Terraform, Compose). | Un array di file serializzati come stringhe. |
Passo della pipeline della FeatureRecipe (pipeline-step) | La pipeline di plugin di una Recipe o di una FeatureRecipe | Passi sequenziali che recuperano segreti o iniettano sidecar negli AST di base. | patches RFC 6902 sull’insieme di documenti indicizzato per chiave, più side_effects (emettere un nuovo documento o file), diagnostics e outputs che un passo successivo può leggere. L’input del passo porta quell’insieme di documenti indicizzato per chiave e l’input with renderizzato del passo. |
Governance (governance) | Prima dell’espansione delle annotazioni, costruzione della topologia, analisi statica o fase di rendering | Svolge i ruoli di governance della pipeline di build. Prima dell’espansione delle annotazioni inietta annotazioni sui componenti risolti, e durante la costruzione della topologia etichetta automaticamente i nodi con label di conformità o ambientali (un operatore ne abilita uno per l’uno o l’altro ruolo). Durante l’analisi statica o la fase di rendering agisce come Loud Guardrail: valuta archi, percorsi e label del grafo — o gli artefatti renderizzati — rispetto ai confini di sicurezza. Il ruolo a cui è collegato, non il suo tipo, determina ciò che può emettere. | Prima dell’espansione delle annotazioni, iniezioni di annotazioni. Durante la costruzione della topologia, un array di JSONPatch che puntano a metadata.labels. Durante l’analisi statica o la fase di rendering, verdetti di severità halt, warn o info (una policy Rego li raccoglie sotto deny, warn e audit); un halt arresta la build. |
Linter (linter) | Fuori banda | Controlli FinOps o di igiene facoltativi (ad es. stima dei costi cloud da .infra) e disciplina al momento della pubblicazione. | Stringhe di avviso o arresti fatali. |
Estensione della CLI (cli) | Runtime (aggrega <command>) | Un comando di primo livello aggiungibile senza modifiche, fornito da un plugin firmato ed eseguito in sandbox, senza alcun codice Go per comando nell’host. | Output standard ed errore standard in streaming, più il codice di uscita del guest. |
Parser (parser) | Su richiesta, ovunque venga letto un formato esterno | Trasforma un testo sorgente esterno (HCL, TOML, YAML, JSON, JSON con commenti) in un albero JSON canonico. | tree più diagnostics, e spans di sorgente facoltativi. |
Importer (importer) | Su richiesta, al di fuori di qualsiasi build (aggrega import, l’editor e lo strumento import dell’assistente) | Trasforma una sorgente esterna di infrastruttura o di definizione di agenti (Langflow, Flowise, n8n, una configurazione MCP, un’applicazione Compose, un’applicazione Dify, gli agenti dichiarati di un progetto CrewAI, la configurazione di un’applicazione LangGraph, le configurazioni degli agenti di un’applicazione Google ADK, un agente dichiarativo di Agent Framework) in file di authoring Aggrega in bozza, pubblicizzando i formati che gestisce come capability import:<format>. | Entità Aggregate / Component / Release in bozza, o riferimenti ai Components del catalogo che riutilizza, le decisioni di mappatura alla loro base, la diagnostica e i file di scaffold da scrivere. |
Il runtime host: una sandbox che nega le capability. Aggrega incorpora l’host Wasm come il toolkit Extism in esecuzione sopra il motore Wazero; il binario host resta puro Go senza alcuna dipendenza da toolchain native, quindi aggrega esegue la cross-compilazione senza problemi. Ogni socket viene eseguito dietro un firewall di purezza AOT: l’host rifiuta di concedere a un plugin qualsiasi capability di accesso al runtime — niente rete, niente filesystem, niente orologio di sistema, niente ambiente, niente I/O standard — quindi una chiamata che ne userebbe una fallisce, e un plugin che importa da una superficie dell’host che l’host non fornisce viene rifiutato al caricamento. Un plugin che non può raggiungere la rete o leggere l’orologio non può violare la garanzia ahead-of-time del compilatore che lo stesso input produca lo stesso output. I runtime di linguaggio che necessitano di alcuni import di avvio innocui vengono eseguiti con una configurazione di tali import che nega le capability: l’host fissa l’orologio osservabile, fornisce entropia reale, scarta l’I/O standard e non concede alcun accesso a filesystem, argomenti o ambiente — quindi un plugin non può raggiungere alcuna capability dell’host che vari tra le build. L’entropia è lasciata deliberatamente reale anziché fissata: fissarla stabilizzerebbe il seed di hash interno e l’ordine di iterazione delle mappe del runtime di un linguaggio guest, e nasconderebbe così un plugin il cui output non è riproducibile invece di lasciare che ciò emerga come output differente. Un plugin il cui risultato dipende dall’entropia ha un problema di determinismo a livello di authoring, e questa configurazione è costruita per rivelarlo anziché mascherarlo.
Scrivere per l’host: il PDK. Gli autori di plugin non scrivono a mano l’ABI di memoria Wasm. Aggrega fornisce un Plugin Development Kit in tre linguaggi — Go, Rust e TypeScript — wrapper leggeri che presentano l’input e l’output tipizzati di ogni socket, così che l’autore scriva funzioni ordinarie. L’interfaccia function / with descritta sopra è ciò che un Aggregate o una FeatureRecipe usa per invocare un plugin; il PDK è ciò su cui un autore di plugin costruisce.
Dove viene eseguito ogni socket. Ogni socket viene eseguito attraverso lo stesso host: il publishing linter con aggrega lint; i ruoli di governance, i provider di rendering e gli step di pipeline delle Recipe e delle FeatureRecipe durante aggrega build; i parser ovunque venga letto un formato esterno; gli importatori con aggrega import; e i plugin della CLI come comandi di primo livello. Vedi Stato del linguaggio per lo stato di prontezza di ogni socket.
Quali plugin sono fissati e quali sceglie il tuo ambiente. Aggrega divide i plugin in base al fatto che modifichino o meno l’output che distribuisci. I plugin che plasmano l’output — i provider di rendering, i plugin di governance collegati in un ruolo di trasformazione (label-transform, annotation-transform) e gli step di pipeline delle FeatureRecipe e delle Recipe — vengono fissati nel lockfile della release quando esegui aggrega pull, e riprodotti identici byte per byte da aggrega build e aggrega serve a partire da quel solo lockfile. Due tipi non vengono fissati, perché una build legge ciascuno dallo stesso luogo ogni volta: un provider di rendering servito dall’interno del binario del compilatore, e un provider o uno step di pipeline la cui entità Plugin è scritta in una delle tue directory di catalogo. Per cambiare quale plugin che plasma l’output si applica, rifai il pull; una modifica alla configurazione del workspace dopo un pull non sposta l’output di una build fino al pull successivo. I plugin di controllo — policy e lint — giudicano una build senza modificarne i byte, quindi vengono messi in cache al pull (così una build può ancora eseguirli offline; uno che il binario del compilatore porta con sé, o uno scritto nella tua directory di catalogo, viene invece letto da lì) ma non fissati: quale controllo viene eseguito lo sceglie il tuo ambiente al momento della build, quindi una suddivisione permissiva in sviluppo / rigorosa in CI è una normale scelta di configurazione anziché un nuovo pull, e cambiare controlli non modifica mai l’output che una build riuscita emette. I Plugins che agiscono solo sull’input di authoring, come gli importatori e le estensioni della CLI, non plasmano alcun output di build e non sono né fissati né parte dell’insieme messo in cache dalla build.
2. Pipeline di Plugin per FeatureRecipe
Le FeatureRecipes legano intenti operativi astratti (come l’aggancio di un proxy di sicurezza o l’iniezione di un sidecar) a pipeline di plugin WebAssembly (Wasm) versionate. Ops dichiara di cosa ha bisogno una Feature su un target di provider concreto; il compilatore esegue la pipeline dichiarata sul grafo IR piatto.
Questo legame comporta tre conseguenze per l’ecosistema:
- Evoluzione disaccoppiata. Il vocabolario dell’infrastruttura cresce tramite plugin Wasm esterni senza richiedere una release del core del compilatore Aggrega. Nuovi provider, nuovi sidecar e nuove integrazioni di sicurezza vengono distribuiti come binari Wasm indipendenti sulla ABI Wasm stabile.
- Versionamento semantico. Le FeatureRecipes fanno riferimento ai plugin Wasm per versione — esatta (
:1.0.0) o un intervallo con caret (:^1.0.0, la versione più alta compatibile con essa). Con l’intervallo con caret, Ops blocca una versione major pur recependone le release minor e patch ogni volta che il lockfile viene risolto di nuovo conaggrega pull --upgrade. - Scaricare la complessità. La generazione di CRD specifiche di un vendor o il rendering complesso (oggetti di policy specifici di un vendor, risorse di routing native del provider) risiedono in plugin Wasm puri che operano sul grafo IR piatto, invece di passare attraverso dichiarazioni di schema o logica di template all’interno delle definizioni dei componenti.
Concatenazione di pipeline — separare le responsabilità tra plugin. Una pipeline di FeatureRecipe può concatenare più plugin Wasm in sequenza, ciascuno dei quali riceve dal compilatore lo stesso contesto del nodo IR. Lo schema standard suddivide la responsabilità in modo che un singolo plugin non porti sia l’intento semantico di una funzionalità sia il meccanismo fisico di intercettazione del traffico di uno specifico ambiente di destinazione.
Una catena canonica di due plugin si presenta così:
- Un plugin di configurazione che emette le regole semantiche della funzionalità (regole di policy di sicurezza, pattern di audit, soglie di rate limit). Comprende l’intento della funzionalità; non comprende il tessuto di intercettazione del traffico dell’ambiente di destinazione.
- Un plugin di routing che emette la configurazione fisica della mesh che trasporta quelle regole (CRD del gateway, patch di iniezione dei sidecar, regole del firewall). Comprende il tessuto dell’ambiente di destinazione; non comprende l’intento semantico della funzionalità.
Entrambi i plugin ricevono in sequenza dal compilatore lo stesso contesto del nodo IR, quindi si compongono in modo pulito senza un accoppiamento diretto tra loro. Il compilatore orchestra la pipeline; i plugin portano la conoscenza del dominio.
3. Intercettazione del traffico: il target HTTPRoute
Il modello di estensibilità di Aggrega punta allo standard HTTPRoute della Kubernetes Gateway API come artefatto trasversale ai provider per l’intercettazione del traffico a livello di mesh. La libreria standard emette oggetti HTTPRoute tramite la Feature core/http-route, la cui FeatureRecipe helm renderizza una route per ogni componente collegato; gli ambienti di destinazione che consumano la Gateway API traducono HTTPRoute nei propri tessuti nativi.
4. Autonomia del Plugin: risoluzione delle etichette
Quando i plugin Wasm generano risorse fisiche dal grafo IR, gli SRE devono poter ricondurre un Pod Kubernetes in esecuzione o una risorsa cloud all’intento semantico dello sviluppatore nell’Aggregate. Il modello di estensibilità di Aggrega colloca questa traduzione interamente sotto il controllo dell’autore del plugin Wasm.
Il compilatore passa l’intero dizionario labels del grafo IR nella sandbox Wasm senza interpretarlo. Da lì l’autore del plugin — Platform Ops — decide la logica di mappatura: passare tutte le etichette alla lettera, filtrare per specifici prefissi di dominio (*.aggrega.ai/*) oppure mappare le etichette del grafo direttamente sugli schemi di tagging nativi del provider (traducendo un’etichetta IR in tags AWS, annotations Kubernetes o un meccanismo di metadati specifico del cloud). Il compilatore non impone alcuna restrizione su come vengono taggati gli artefatti generati.
Questa autonomia mantiene l’intelligenza specifica del dominio — quali etichette contano per l’osservabilità, quali corrispondono alle convenzioni di tagging native, quali sono interne alla piattaforma — all’interno del livello dei plugin Wasm, dove l’ecosistema evolve indipendentemente dalla cadenza di rilascio del compilatore Go.
5. Estensioni della CLI: comandi a runtime
I socket descritti sopra vengono eseguiti all’interno di una build — il compilatore li invoca mentre esegue il parsing, la mutazione, la validazione e il rendering di un Aggregate. Il socket delle estensioni CLI è di natura diversa: viene eseguito al terminale, al di fuori di qualsiasi build, quando un operatore digita aggrega <command>. È il modo in cui la superficie dei comandi di aggrega stessa cresce senza una release del core.
Che cos’è un’estensione CLI. Un’estensione CLI è un aggrega <command> pronto all’uso fornito da un plugin Wasm firmato ed eseguito in sandbox. Adotta la stessa impostazione drop-in, di proprietà del guest, del socket di rendering: la logica di dominio risiede interamente nel guest, e l’host Go non aggiunge alcun codice per singolo comando. Aggiungere un nuovo comando di primo livello richiede solo tre cose — un binario .wasm, un’entità Plugin che dichiari pluginType: cli (vedi Plugin) e un esplicito aggrega plugin add cli. L’host scopre il comando dall’auto-descrizione del plugin installato; nessun comando è compilato nel binario.
Perché un socket di runtime può fare ciò che un socket di build non può. Poiché i socket di compilazione vengono eseguiti durante una build, restano privi di capability e deterministici: Aggrega è un compilatore ahead-of-time, e lo stesso input deve sempre produrre lo stesso output (vedi Invarianti architetturali). Un plugin di rendering o di policy non può quindi raggiungere la rete, leggere l’orologio o scrivere in streaming sul terminale — qualsiasi cosa vari tra un’esecuzione e l’altra infrangerebbe tale garanzia. Un’estensione CLI viene eseguita dopo e al di fuori di quel confine, guidata da una persona a un prompt anziché dalla pipeline deterministica. È proprio per questo che un plugin CLI può trasmettere in streaming lo standard output e lo standard error durante l’esecuzione e restituire un codice di uscita del processo: non esiste alcun artefatto di build la cui stabilità byte per byte questi effetti potrebbero minacciare.
Installare, eseguire e scoprire. aggrega plugin add cli <query> cerca nel registry configurato un plugin cli corrispondente, lo verifica rispetto alla trust policy del registry e lo installa come comando di primo livello — stampando prima le capability dichiarate dal plugin, così che l’operatore confermi esattamente ciò che il comando può fare prima che venga installato. Una volta installato, aggrega <command> lo esegue come qualsiasi comando integrato. Un plugin CLI dichiara i propri comandi e i relativi flag nella sua auto-descrizione describe(), e l’host mostra i flag di ciascun comando in aggrega help <command> esattamente come fa per un comando integrato, così un operatore scopre i --flags di un comando installato allo stesso modo. Per trovare comandi installabili e contenuti del catalogo, aggrega search interroga l’indice locale dei registry configurati — --kind plugin --plugin-type cli restringe i risultati ai plugin CLI installabili, e una ricerca senza filtri copre le entità del catalogo; aggrega plugin list mostra ciò che è già installato. I flag e le forme di output di ciascun comando si trovano in quelle pagine di riferimento.
Il modello delle capability. Un’estensione CLI parte da una baseline fissa che ogni comando riceve senza alcuna dichiarazione e senza alcuna richiesta di conferma:
| Capability di base | Concessa |
|---|---|
| Argomenti della riga di comando in ingresso | Sempre |
| Standard output e standard error in streaming | Sempre |
| Codice di uscita del processo in uscita | Sempre |
Tutto ciò che va oltre la baseline è disattivato per impostazione predefinita. Un plugin che ha bisogno di altro dichiara esplicitamente ogni capability aggiuntiva, e l’host la concede solo dopo averla mostrata al momento dell’installazione perché l’operatore la confermi. Una classe di capability aggiunta oltre la baseline — accesso all’ambiente, al filesystem o alla rete, input interattivo — viene concessa dietro lo stesso controllo di dichiarazione e conferma, così che un comando non possa mai acquisire silenziosamente una portata che l’operatore non ha approvato.
I comandi integrati hanno sempre la precedenza. Un plugin installato non può mai oscurare un comando integrato. Una protezione dei nomi riservati basata su una denylist tutela i comandi integrati e un insieme di nomi riservati ai comandi integrati, e una collisione viene rifiutata all’installazione anziché poter sovrascrivere il comportamento del core. La superficie dei comandi su cui un operatore fa affidamento resta stabile, qualunque cosa vi sia installata sopra.
6. Plugins parser: lettura di formati esterni
Il compilatore ha regolarmente bisogno di leggere testo scritto in un formato di cui non è autore — un modulo Terraform in HCL, un file di configurazione in TOML, un manifesto in YAML o JSON. Il socket dei parser fornisce questa capacità di lettura senza insegnare al core del compilatore alcun formato specifico. Un parser è un plugin senza stato che trasforma un testo sorgente esterno in un albero JSON strutturato: gli si passano i byte di un file HCL e restituisce lo stesso contenuto come oggetto JSON che il resto della pipeline sa già come percorrere. Qualsiasi parte del compilatore che debba leggere un formato che non analizza nativamente chiede un albero analizzato e lavora a partire da quello.
Un formato è una capability, non una funzionalità del compilatore. Un parser dichiara i formati che gestisce come capability — parse:hcl, parse:toml e così via — e l’host risolve un parser in base al formato richiesto, lo esegue e restituisce l’albero. È lo stesso modello drop-in, basato sulle capability dichiarate, adottato dai provider di rendering e dai plugin CLI: il core del compilatore non contiene alcun elenco integrato di formati, quindi aggiungerne uno significa distribuire un nuovo plugin parser, mai una release del core. I parser per HCL, TOML, YAML, JSON e JSON con commenti sono inclusi nel binario come set iniziale; un’azienda che ha bisogno di un altro formato distribuisce un plugin parser che lo dichiari.
La selezione del formato è dichiarativa, mai indovinata. L’host non ispeziona mai il contenuto di un file per decidere che cosa sia. Sceglie un formato tramite segnali dichiarati, in un ordine di preferenza fisso. Un provider di rendering può dichiarare il formato di ciascun file che emette, e l’host preferisce senz’altro quel formato dichiarato dal produttore — il provider che ha scritto i byte è l’autorità su come leggerli. Per un file che il produttore non ha etichettato, il ripiego è una mappa fissa delle estensioni dei file — .tf seleziona HCL, .toml seleziona TOML, .yaml seleziona YAML, .json seleziona JSON. Scegliere in base a un formato dichiarato o a un’estensione fissa mantiene il parsing deterministico e leggibile: lo stesso input viene sempre instradato allo stesso parser, e un operatore può capire quale parser verrà eseguito senza conoscere i byte contenuti nel file. Lo sniffing del contenuto renderebbe la scelta dipendente dal payload, e Aggrega non lo fa.
Un parser è puramente sintattico. L’output è un albero JSON più la diagnostica e, facoltativamente, le posizioni nel sorgente da cui proviene ciascun nodo. Un parser non porta alcun significato di Aggrega — riporta ciò che il testo dice strutturalmente, nulla di ciò che significa come Component, Recipe o qualsiasi altra entità. Trasformare un albero analizzato in entità Aggrega è una questione separata che risiede altrove; l’unico compito del parser è una traduzione fedele dalla sintassi a JSON. La direzione di lettura è a senso unico nello stesso spirito: un parser legge un formato in un albero, non riscrive un formato in uscita.
Un consumatore: policy sull’HCL di Terraform. Una policy della fase di rendering che deve ispezionare il Terraform prodotto da una build non impara essa stessa l’HCL. L’host analizza l’artefatto HCL tramite il socket dei parser e consegna al plugin di policy l’albero JSON che già legge, così la policy ragiona su dati strutturati nella forma che ogni altro socket riceve. I nuovi lettori di formati esterni si compongono allo stesso modo — chiedere all’host l’albero, poi lavorare in JSON — così la capacità del compilatore di comprendere un formato cresce aggiungendo plugin parser anziché facendo crescere il core.
7. Plugins importatori: bozze di file di authoring da sorgenti esterne
Un team raramente parte da una pagina bianca. La sua architettura di agenti spesso esiste già altrove — un flow Langflow o Flowise, un workflow n8n, un’applicazione Dify, i server MCP con cui è configurato un client, un’applicazione Compose, gli agenti dichiarati dalla configurazione di un framework. Il socket degli importatori trasforma quella sorgente esterna in un punto di partenza concreto per l’authoring Aggrega: legge la sorgente e genera entità Aggregate e Component in prima bozza e, da una configurazione MCP, da un’applicazione Compose o dalla configurazione dichiarata di un framework, una bozza di Release, che un autore rivede e completa, così un team porta avanti in Aggrega ciò che ha già invece di riscriverlo a mano. Un importatore mappa il significato — legge che cosa è un nodo della sorgente e propone l’entità Aggrega che lo rappresenta, oppure lo lascia all’interno del flow che la piattaforma in bozza trasporta; il compilatore inoltra le entità emesse in modo opaco, esattamente come resta agnostico rispetto a ciò che qualsiasi plugin produce.
Un formato è una capability, non una funzionalità del compilatore. Un importatore dichiara i formati che gestisce come capability — import:langflow, import:flowise, import:n8n, import:mcp, import:compose, import:dify, import:crewai, import:langgraph, import:google-adk, import:agent-framework e così via — e l’host risolve un importatore in base al formato richiesto, lo esegue e riprende le entità che ha messo in bozza. È lo stesso modello drop-in, basato sulle capability dichiarate, che il socket dei parser adotta con parse:<format>: il core del compilatore non contiene alcun elenco integrato di formati importabili, quindi supportarne uno nuovo significa distribuire un plugin importatore che lo dichiari, mai una release del core.
Un importatore legge tramite il socket dei parser; non rifà il parsing. Un importatore ha bisogno della forma strutturata della propria sorgente, ma non reimplementa la lettura di un formato che l’ecosistema già analizza. Quando ha bisogno dell’albero, chiede all’host di eseguire il parser corrispondente — quello che il catalogo del workspace serve per la sintassi della sorgente o, dove il catalogo non ne serve alcuno, quello che il compilatore stesso porta con sé — tramite la stessa capability di parsing mediata dall’host che usa il resto della pipeline, e lavora a partire dall’albero JSON restituito. La lettura (dalla sintassi all’albero) resta compito del parser; la mappatura (dall’albero alle entità Aggrega) è compito dell’importatore. I due socket si compongono senza duplicarsi: un importatore aggiunge l’intelligenza di mappatura per una sorgente e si appoggia al parser esistente per i byte.
Un formato viene riconosciuto da ciò che il suo importatore dichiara, mai indovinato. Un’importazione può nominare direttamente il proprio formato sorgente. Dove non lo fa, il formato viene riconosciuto dalle firme che ciascun importatore dichiara nella propria auto-descrizione e che la sua entità Plugin registra: la sintassi in cui viene letta una sorgente, i nomi di file a cui si applica una firma e i percorsi che l’albero analizzato deve o non deve contenere. L’host non conosce alcun formato proprio. Analizza la sorgente tramite il parser che il catalogo del workspace serve per ciascuna sintassi nominata da una firma — o quello del compilatore, dove il catalogo non ne serve alcuno — valuta i predicati dichiarati sull’albero restituito e legge la sorgente come il formato dell’unico importatore la cui firma corrisponde. Le firme dichiarate prendono il posto che una mappa fissa delle estensioni dei file occupa per il socket dei parser, perché i formati che un’importazione legge possono condividere un’estensione — un export Langflow, un export Flowise e un workflow n8n sono tutti file JSON. Una sorgente a cui non corrisponde alcuna firma viene rifiutata, chiedendo il formato e nominando i formati dichiarati dagli importatori — oppure, per una directory, chiedendo uno dei suoi file preso da solo o un formato il cui importatore dichiara pattern di file, nominando solo questi; una sorgente a cui corrispondono firme di più formati viene rifiutata, nominandoli. Il riconoscimento non legge altro che la sorgente e non raggiunge alcuna rete, quindi riconoscere un nuovo formato è una dichiarazione che il nuovo importatore distribuisce, mai una modifica all’host. Le regole per scrivere una firma si trovano in Il socket degli importatori.
Una directory viene letta attraverso i file che il suo importatore dichiara. Una sorgente è un file o una directory. Un file viene passato all’importatore per intero. Una directory viene letta in sorgenti con nome — esattamente i suoi file selezionati dai pattern di file delle firme dell’importatore, ciascuno nominato con il proprio percorso all’interno della directory, in ordine — e nessun altro file della directory viene aperto; un link che porterebbe la lettura fuori dalla directory viene rifiutato prima che venga letto alcunché. Un importatore che non dichiara pattern di file legge un solo file e rifiuta una directory, e anche una directory che non contiene alcun file selezionato dai pattern di un importatore viene rifiutata. Gli importatori Langflow, Flowise, n8n, Dify e Agent Framework del compilatore non ne dichiarano alcuno, quindi ciascuno legge un solo file esportato di flow, workflow o applicazione, oppure un solo agente dichiarativo; il suo importatore MCP dichiara i nomi di file delle configurazioni client MCP che legge, quindi la directory di un progetto viene letta attraverso le configurazioni che contiene; il suo importatore Compose dichiara i nomi di file che Compose legge per impostazione predefinita, quindi la directory di un progetto viene letta attraverso il suo file Compose e il file di override che Compose vi unisce sopra; e il suo importatore CrewAI dichiara i nomi di file sotto cui un progetto CrewAI dichiara i propri agenti e task, quindi la directory di un progetto viene letta attraverso quelle dichiarazioni e il suo programma non viene mai letto; e il suo importatore LangGraph dichiara langgraph.json, quindi la directory di un’applicazione viene letta solo attraverso la sua configurazione, senza mai leggerne il codice né i file di ambiente, e un file di ambiente nominato dalla configurazione raggiunge l’importatore solo dove il with.sources del suo aggancio glielo consegna, e allora solo per i nomi delle variabili; e il suo importatore Google ADK dichiara root_agent.yaml, quindi la directory di un’applicazione viene letta solo attraverso la configurazione del suo agente radice, le configurazioni nominate dai suoi sotto-agenti raggiungono l’importatore solo dove il with.sources del suo aggancio gliele consegna, e né il suo codice né il suo file di ambiente vengono mai letti.
La mappatura è deterministica, dotata di punteggio di confidenza e valutata rispetto al tuo catalogo. L’host consegna all’importatore una vista dei Components contenuti nel catalogo del workspace — il catalogo da cui l’importatore è stato selezionato — le cartelle di catalogo del workspace o, se non ne indica nessuna, lo snapshot del catalogo pubblicato dal suo registry predefinito — i Components di un catalogo aziendale esattamente come quelli della libreria standard. La vista riporta il nome, la versione e le etichette di ciascun Component, i nomi delle chiavi che i suoi values e provides dichiarano e i selettori dei suoi socket, e mai un valore, un default o un segreto; nulla viene recuperato per costruirla oltre a quello snapshot, e il suo ordine è fisso, quindi un catalogo produce una sola vista. Un importatore costruito sul package importer del PDK Go — tra cui gli importatori Langflow, Flowise, n8n e Compose del compilatore stesso — valuta ciascun nodo della sorgente rispetto a quei Components e a nient’altro, con un modello di confidenza deterministico e privo di modelli di IA, e registra la decisione — i candidati valutati, il livello di corrispondenza assegnato e la scelta compiuta — come suggerimenti revisionabili che un autore può leggere e modificare. Un Component che il catalogo acquisisce è un candidato alla successiva importazione, senza ricostruire alcun importatore. L’impostazione predefinita è solo suggerimenti: l’importazione propone e l’autore decide. Una corrispondenza ad alta confidenza può essere scritta come riferimento a un componente esistente del catalogo anziché come corpo appena messo in bozza, ma solo quando l’operatore lo abilita esplicitamente — sempre come suggerimento esplicito e reversibile su cui l’autore decide, mai come riscrittura silenziosa. Poiché il punteggio non usa alcun modello né alcuna ricerca a runtime, la stessa sorgente valutata rispetto allo stesso catalogo produce sempre gli stessi suggerimenti.
Un flow viene messo in bozza come la piattaforma che lo esegue. Un flow Langflow, un chatflow Flowise e un workflow n8n vengono eseguiti su una piattaforma, e per impostazione predefinita un’importazione mette in bozza quella piattaforma anziché i nodi del flow: un’istanza del Component di piattaforma della libreria standard — core/ai-agent/langflow, core/ai-agent/flowise o core/ai-agent/n8n — che trasporta il flow così come è stato esportato nel suo valore flow_definition, che la piattaforma carica al deploy. Ogni parte del flow accettata da un socket della piattaforma — sulle piattaforme della libreria standard, un modello, un server MCP o un altro strumento raggiunto via HTTP, e un vector store — diventa un Component a sé, referenziato o messo in bozza secondo quanto decide la mappatura, e viene collegata a quel socket sotto uses della piattaforma. Così ogni chiamata che il flow fa a un modello, a uno strumento o a uno store è una connessione dichiarata dall’Aggregate: un plugin di governance che giudica il grafo la vede come vede qualsiasi altro arco, e l’allowlist di egress della libreria standard, che l’impostazione attach_egress_allowlist aggancia alla piattaforma, consente alla piattaforma di connettersi solo a ciò che le sue connessioni raggiungono, ai propri pod e al DNS del cluster. Dove il formato lo consente, la bozza scrive nel flow trasportato ciò che fa sì che il flow raggiunga ciascuna parte attraverso la sua connessione. Ogni altro nodo — un agente, una chain, un trigger — resta all’interno del flow trasportato e non diventa alcun Component, e la sua decisione registra i candidati rispetto a cui è stato valutato. Un’applicazione Dify viene messa in bozza allo stesso modo, nella forma che assume un’intera installazione: una voce dell’installazione Dify che la libreria standard assembla, core/dify, che trasporta l’applicazione nel suo parametro app_definition, con l’installazione che collega le proprie connessioni. L’impostazione layout dell’aggancio dell’importatore sceglie la bozza: platform, il default, oppure nodes, che mette in bozza ogni nodo della sorgente come Component a sé, ogni arco del flow come una connessione uses, e non trasporta alcun flow. La piattaforma che trasporta il flow illustra quali nodi diventano parti e dove ciascuno viene collegato.
Un framework code-first viene letto attraverso la sua configurazione dichiarata, mai attraverso il suo programma. CrewAI, LangGraph, Google ADK e Agent Framework mantengono il comportamento di un’applicazione nel suo programma e ne dichiarano agenti, grafi e modelli in una configurazione accanto a esso. I loro importatori leggono solo quelle dichiarazioni — i file di agenti e task di un progetto CrewAI, il langgraph.json di un’applicazione LangGraph, le configurazioni degli agenti di un’applicazione Google ADK, un agente dichiarativo di Agent Framework — e mettono in bozza l’agente della libreria standard per il framework attorno a un programma che non aprono mai, collegato a ciò che le dichiarazioni nominano: il modello richiesto da un agente, dove il socket model dell’agente lo accetta, e il datastore in cui un checkpointer LangGraph conserva lo stato. A raggiungere un server MCP nominato da un agente Agent Framework è il provider del modello, come strumento ospitato, quindi la bozza lo nomina nei commenti e non vi collega nulla. Il programma viene eseguito nell’immagine nominata dalla Release. Ciò che solo il programma dice — la logica di un task, uno strumento definito dal suo codice, un agente costruito dal suo codice — viene nominato nei commenti e nelle decisioni della bozza e non diventa alcun Component; portarlo nei file di authoring è compito dell’autore, a mano o con un assistente IA che scrive per conto dell’autore tramite aggrega mcp, che legge il riferimento e genera e valida le entità.
Ciò che una sorgente afferma su come vengono eseguite le sue parti finisce in una bozza di Release. Gli input operativi spetta alla Release fornirli, quindi gli importatori MCP, Compose, CrewAI, LangGraph, Google ADK e Agent Framework mettono in bozza una Release accanto all’Aggregate, il cui spec.aggregate lo nomina: la Release riporta ciò che la sorgente afferma — la riga di comando o l’indirizzo di un server, l’immagine e la porta di un server generico, l’endpoint di un modello — e, nei commenti sopra ciascuna voce, ciò che la sorgente afferma ma che nessuna chiave del Component in bozza accoglie, come i volumi di un servizio o l’ambiente di una configurazione. Ciò che nessuna sorgente afferma — l’immagine che esegue il programma di un framework, la credenziale che una connessione presenta, i metadata.environment e spec.manifest della Release — viene nominato in un commento là dove va inserito, perché l’operatore lo fornisca, e la build si arresta nominando quale tra immagine, ambiente e manifesto non è ancora impostato. Una bozza di piattaforma non scrive alcuna Release: il commento sopra l’istanza della piattaforma nomina ciò che la Release fornisce — gli input propri della piattaforma, come l’immagine che esegue o il suo account proprietario, l’indirizzo di ciascun server MCP collegato e la credenziale che ciascuna connessione presenta.
Un valore di credenziale contenuto in una sorgente viene riportato così com’è, a meno che non se ne chieda la rimozione. Un importatore individua ogni valore della propria sorgente che può contenere una credenziale, ciascuno di una classe: ciò che il formato marca come credenziale, un membro della configurazione di un server MCP, oppure un input che il formato marca come non credenziale ma che può comunque contenerne una, come gli header di una richiesta. Per impostazione predefinita nessuno viene scritto vuoto: ogni valore che contiene qualcosa viene riportato così com’è — nel flow o nell’applicazione trasportati dalla piattaforma, o nella bozza di Release — e nominato in un avviso credential-carried in base a dove si trova — il suo nodo, server, servizio o agente, e il suo campo — mai in base al suo valore, insieme al valore dell’impostazione che lo scrive vuoto. L’impostazione empty_credentials attiva la rimozione, una classe alla volta: marked scrive vuoto ciò che un formato marca come credenziale e ogni membro della configurazione di un server MCP, e all anche gli input marcati come non credenziali, e ciascun valore scritto vuoto viene segnalato con credential-emptied. Ciò che la bozza scrive affinché un flow raggiunga la propria connessione è cablaggio, scritto qualunque cosa dica l’impostazione, e una connessione nella bozza non porta alcuna credenziale: la Release aggancia quella che ciascuna connessione presenta. Un file a cui una sorgente si limita a puntare, come un file di ambiente, viene letto solo per i nomi delle sue variabili, dove viene letto, e una bozza costruita nodo per nodo non legge alcun valore. Ciò che si trova al di fuori dei punti che un importatore individua — il codice di un componente personalizzato, un prompt — spetta all’autore rivederlo prima di condividere una bozza, come illustrato in Valori di credenziale contenuti nel flow.
Il comando, l’editor e l’assistente eseguono un’unica importazione. aggrega import <file or directory> esegue un’importazione dal terminale; l’editor esegue la stessa operazione tramite la richiesta aggrega/import della sua sessione, e un assistente AI tramite lo strumento import messo a disposizione da aggrega mcp. Tutti e tre selezionano l’importatore nello stesso modo, tra gli importatori contenuti nel catalogo del workspace e gli importatori core del compilatore: quello indicato da un’associazione plugins.importer, se ne indica uno che dichiara il formato, e altrimenti la versione più alta dell’unico importatore che lo dichiara — importatori con due nomi diversi per uno stesso formato, senza che nessuno dei due sia associato, interrompono l’importazione, che li nomina entrambi, come illustra Quale importatore trasforma una sorgente in bozze. Tutti e tre riportano le decisioni di mappatura accanto alle bozze. Il comando stampa su standard error una riga per ogni nodo mappato, indicando il Component o la bozza scelti per esso, se è referenziato o generato come bozza, il livello di corrispondenza e, dove l’importatore ha valutato un candidato, il punteggio del candidato migliore; l’editor mostra le stesse righe, e il risultato della sessione dell’editor e la risposta dell’assistente riportano ogni decisione per intero. Così un autore vede dove l’importazione ha tirato a indovinare, su qualunque superficie l’abbia eseguita, senza aprire le bozze. --format indica esplicitamente il formato della sorgente — ad esempio langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk o agent-framework — al posto del riconoscimento. Il comando scrive le entità ed eventuali file di scaffold prodotti dall’importazione sotto la radice del workspace, oppure sotto la directory indicata da --output-dir; --dry-run fa tutto ciò che fa il comando tranne scrivere, restituendo i file generati come contenuto e indicando il file a cui ciascuno è destinato, così un autore può rivedere lo scaffold prima di introdurre qualsiasi cosa nell’albero di lavoro.
Gli importatori core. Gli importatori core distribuiti con il compilatore leggono questi formati, un importatore per ciascuno:
- Langflow — un flow esportato da Langflow, messo in bozza come la piattaforma Langflow della libreria standard che trasporta il flow, con ciascuna sua parte accettata da un socket collegata a quel socket.
- Flowise — un chatflow o un agentflow esportato da Flowise, messo in bozza come la piattaforma Flowise della libreria standard che lo trasporta, con ciascuna sua parte accettata da un socket collegata a quel socket.
- n8n — un workflow esportato da n8n, messo in bozza come la piattaforma n8n della libreria standard che lo trasporta, con ciascuna sua parte accettata da un socket collegata a quel socket.
- Dify — un’applicazione esportata da Dify, messa in bozza come l’installazione Dify assemblata dalla libreria standard che trasporta l’applicazione, con i modelli, gli strumenti e le knowledge base che nomina segnalati come configurati all’interno di Dify.
- MCP — la configurazione di un client MCP o la descrizione di un server di un registry MCP, con ciascun server messo in bozza come istanza dello strumento MCP della libreria standard, e una
Releaseche riporta la riga di comando, l’indirizzo o l’immagine di ciascun server. - Compose — un formato di infrastruttura, con ciascun servizio di un’applicazione Compose messo in bozza come il Component del catalogo a cui corrisponde la sua immagine — tramite una tabella che l’importatore porta con sé, generata dalle Recipes e dai Components Compose del catalogo standard al momento della sua build — oppure come un server generico che esegue la sua immagine, con una
Releaseche riporta l’immagine e la porta di ciascun server generico e, nei commenti, le porte, i volumi e l’ambiente dichiarati da ciascun servizio. - CrewAI — gli agenti che un progetto CrewAI dichiara nei propri file di configurazione, ciascuno messo in bozza come l’agente CrewAI della libreria standard che riporta il suo ruolo, il suo obiettivo e la sua backstory ed è collegato al modello che nomina, con i task e gli strumenti del progetto segnalati come appartenenti al suo programma, il programma stesso mai letto, e una
Releaseche lascia all’operatore il compito di nominare l’immagine che lo esegue. - LangGraph — i grafi dichiarati dalla configurazione di un’applicazione LangGraph, ciascuno messo in bozza come l’agente LangGraph della libreria standard che riporta il percorso di import del suo grafo ed è collegato al datastore in cui il suo checkpointer conserva lo stato, con una
Releaseche indica, in un commento, l’ambiente dichiarato dalla configurazione, e il codice dei grafi mai letto. - Google ADK — gli alberi di agenti dichiarati dalle configurazioni degli agenti di un’applicazione Google ADK, ciascuno messo in bozza come l’agente ADK della libreria standard collegato al modello che nomina dove ADK invia le richieste di quel modello all’API di Gemini, mentre un modello raggiunto in qualsiasi altro modo — tramite una stringa di modello LiteLLM, per esempio — viene nominato in un commento e il suo collegamento è lasciato all’autore, con una
Releaseche lascia all’operatore il compito di nominare l’immagine che esegue l’applicazione, e il codice dell’applicazione mai letto. - Agent Framework — un agente dichiarativo di Agent Framework, messo in bozza come l’agente Agent Framework della libreria standard collegato al modello OpenAI che nomina, con ciascun server MCP che nomina scritto nei commenti, poiché il provider del modello lo raggiunge come strumento ospitato, e con una
Releaseche riporta l’endpoint del modello e, in un commento, l’indirizzo di ciascun server, e il codice dell’applicazione mai letto.
Sono plugin importatori come tutti gli altri — l’intelligenza di mappatura specifica di ciascun formato risiede in essi, non nel core — costruiti dai sorgenti del compilatore e pubblicati con ogni release del compilatore alla versione di quella release. Nessuno è compilato nel binario: il binario porta l’entità Plugin di ciascuno e il digest dell’unico modulo che accetta, così ciascuno serve il proprio formato in ogni workspace senza alcuna voce di catalogo. La prima importazione che ne richiede uno non presente sulla macchina lo recupera dal registry predefinito del workspace, lo vincola a quel digest, lo verifica come un pull verifica un plugin che recupera — la sua firma secondo la trust policy di quel registry e le funzioni host che usa — e lo conserva nella cache dei contenuti del workspace; ogni importazione successiva lo legge da lì, senza accedere alla rete per esso. Un’importazione non fissa alcun importatore: per esso non viene scritto nient’altro — nessuna voce nel lockfile e nessun record di plugin attendibili — e nessun pull lo mette in cache e nessuna build lo legge. Un modulo che non supera la verifica viene rifiutato, e non viene conservato nulla. Dove il modulo non può essere recuperato — il workspace è offline, il suo registry non è raggiungibile o il registry non lo contiene — l’importazione si arresta, nominando l’importatore, la sua versione e ciò che porta il suo modulo sulla macchina. La scelta resta del workspace: un importatore che il suo catalogo contiene sotto un altro nome per uno di questi formati viene eseguito dove un aggancio plugins.importer lo nomina, e uno con lo stesso nome e la stessa versione di un importatore core viene eseguito al suo posto.
Avviare e far crescere un catalogo
Un catalogo non deve essere costruito da zero. La maggior parte del lavoro per popolare Recipes e plugin per un nuovo ambiente consiste in scaffolding e riuso, piuttosto che nello scrivere a mano ogni binario.
Importare una sorgente esterna in file di authoring in bozza. aggrega import <file or directory> legge una sorgente dichiarativa di definizione di agenti — un flow Langflow o Flowise, un workflow n8n, oppure la configurazione di un client MCP o la descrizione di un server di un registry MCP — un’applicazione Compose, un’applicazione Dify, gli agenti che un progetto CrewAI dichiara, i grafi che la configurazione di un’applicazione LangGraph dichiara, gli agenti che le configurazioni degli agenti di un’applicazione Google ADK dichiarano, o un agente dichiarativo Agent Framework, e genera YAML Aggregate e Component in prima bozza, e da una sorgente MCP, Compose, CrewAI, LangGraph, Google ADK o Agent Framework una Release in bozza, che un autore rivede e completa, così un team porta avanti ciò che ha già invece di riscriverlo a mano. Per ogni nodo di un flow, e per ogni servizio di un’applicazione Compose, assegna un punteggio ai Components del catalogo del workspace stesso — quello di un catalogo aziendale non meno di quello della libreria standard — con un modello di confidenza deterministico e senza modelli, e registra la decisione — i candidati valutati, il livello assegnato e la scelta fatta — come suggerimenti revisionabili, che il comando, l’editor e l’assistente riportano tutti; una corrispondenza ad alta confidenza può essere scritta come riferimento al catalogo quando l’operatore lo abilita, sempre come suggerimento esplicito e reversibile che l’autore approva, mai come riscrittura silenziosa. Ogni Component che un catalogo acquisisce è un candidato che l’importazione successiva valuta. L’intelligenza di mappatura specifica del formato risiede in un plugin importatore: gli importatori Langflow, Flowise, n8n, MCP, Compose, Dify, CrewAI, LangGraph, Google ADK e Agent Framework del compilatore servono quei formati in ogni workspace, scaricati e verificati al primo utilizzo, e un catalogo aggiunge un formato contenendo un plugin importatore che lo dichiara. Una sorgente directory viene letta tramite i pattern di file che il suo importatore dichiara; gli importatori Langflow, Flowise, n8n, Dify e Agent Framework non ne dichiarano nessuno, e ciascuno legge un unico file esportato o agente dichiarativo, mentre l’importatore MCP legge le configurazioni client contenute in una directory, l’importatore Compose i suoi file Compose, uniti come li unisce Compose, l’importatore CrewAI le dichiarazioni di un progetto, mai il suo programma, l’importatore LangGraph la configurazione di un’applicazione, mai il suo codice né un file di ambiente — di cui legge i nomi solo quando la sua associazione gli consegna il file — e l’importatore Google ADK la configurazione dell’agente radice di un’applicazione, mai il suo codice né il suo file di ambiente, con le configurazioni dei sotto-agenti lette quando la sua associazione gliele consegna — una configurazione che ADK dichiara sperimentale, i cui agenti usano per impostazione predefinita un modello Gemini e raggiungono per nome i modelli di altri provider tramite classi proprie di ADK, oppure tramite una stringa di modello LiteLLM.
La maggior parte del lavoro sui plugin è fatta di template, non di codice compilato. Una larga parte delle funzionalità si limita a iniettare un sidecar statico, una variabile d’ambiente o una label — un semplice JSONPatch senza logica condizionale. Un unico plugin patcher configurabile, scritto una volta sola per accettare un template JSONPatch dichiarativo come input with, può coprire quel caso comune senza un binario compilato dedicato per ogni funzionalità: l’autore scrive un template, e per molti target in stile CRD basta da solo un template valuesMapping (che spesso fa riferimento a frammenti condivisi in una voce di MappingLibrary). I plugin PDK scritti ad hoc servono per il resto, quello davvero condizionale.
Fare riferimento a strumenti affermati. Quando scrivono nuova logica di plugin, gli autori possono consultare le forme di output documentate pubblicamente di strumenti open source affermati — la struttura dei CRD, delle patch o dei template che quegli strumenti notoriamente emettono — come riferimento per la forma di destinazione che un nuovo plugin deve produrre, rispettando la licenza di ciascun progetto. I webhook di iniezione di sidecar, le librerie di costrutti di livello superiore, i generatori di CRD per operator e i cataloghi di trait o di composizione pubblicano tutti strutture di output che corrispondono da vicino a ciò che una FeatureRecipe o un plugin comparabile deve emettere. L’obiettivo è rispettare un contratto di output ben compreso, non copiare l’implementazione di alcun progetto.