Plugin
Un Plugin è un plugin WebAssembly indirizzato per contenuto: un artefatto .wasm ospitato su OCI, fissato tramite digest sha256, che dichiara il tipo di socket che implementa, la versione ABI a cui è destinato, un puntatore opzionale alla firma e un blocco runtime opzionale. L’entità è la superficie di authoring e di metadati di un plugin; la risoluzione delle dipendenze fissa l’artefatto tramite digest e la politica di fiducia per registry ne verifica la firma al pull. Il compilatore non interpreta il comportamento del plugin — instrada il riferimento fissato; il runtime WebAssembly esegue i byte.
Questa pagina descrive campo per campo la superficie di authoring del catalogo per Plugin. Per il flusso di lavoro completo dell’autore — cos’è un plugin, l’autodescrizione describe(), il ciclo di vita publish→pull→build, la firma e il versionamento — consulta la guida per sviluppatori di plugin Wasm. Per i punti di socket a cui un plugin si collega e le loro forme di input/output, consulta il contratto dei plugin Wasm.
Il ruolo del Plugin
Un Plugin lega un’identità logica di plugin a un artefatto .wasm concreto e ai metadati di capacità e di runtime di cui l’host ha bisogno per caricarlo ed eseguirlo in sicurezza. Uno step di pipeline o un socket di plugin fa riferimento all’entità tramite il suo URI; l’entità contiene le capacità dichiarate, i limiti di runtime e il puntatore alla firma, mentre il digest del contenuto risolto si trova nel lockfile della release. La posizione del .wasm deriva dall’identità del plugin — la coordinata indirizzabile plugin/<pluginType>/<name>, a sua volta composta da metadata.pluginType e dal metadata.name semplice, più il registry configurato — e non è un campo scritto dall’autore. L’indirezione attraverso l’entità è obbligatoria — un riferimento diretto a un .wasm o a un artefatto viene rifiutato al caricamento perché nessuna entità gli corrisponde.
Le dichiarazioni di un Plugin sono raggruppate per tipo di socket, ed è da questo raggruppamento che inizia la lettura dell’entità:
- Un blocco per tipo di socket —
spec.provider,spec.pipelineStep,spec.parser,spec.importer. Un plugin contiene l’unico blocco indicato dal suometadata.pluginType, e ogni blocco contiene un elencocapabilities:— registrato a partire daldescribe()del plugin stesso daaggrega plugin gen-catalog— il cui significato appartiene soltanto a quel blocco: l’elenco di un provider nomina le capacità che serve, quello di uno step di pipeline nomina le capacità dei provider con cui il suo step è compatibile, e quelli di un parser e di un importatore nominano formati sorgente, scrittiparse:<format>eimport:<format>. È il contenimento a portare il significato — non si può raggiungere una voce di capacità senza aver prima letto il blocco che dice di che tipo di dichiarazione si tratta. - Un blocco provider contiene più del suo elenco —
spec.providerdichiara anche come il plugin traduce il tipo Workload, quali annotazioni native della piattaforma legge e il suo contratto di comportamento di rendering (spec.provider.contract: tipi di input, assemblaggio dei boundary, delimitatori degli artefatti, riutilizzo delle istanze). Questi descrivono il comportamento di rendering anziché una dimensione servita, ed è per questo che stanno accanto all’elenco delle capacità del provider anziché al suo interno. - Un socket trasversale non dichiara capacità — un plugin
linter,governanceoclinon contiene nessuno dei quattro blocchi, perché non serve alcuna dimensione di rendering né alcun formato sorgente.
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: # capabilities is recorded by `aggrega plugin gen-catalog` from the plugin's describe(); an author may narrow it. capabilities: - helm - compose signature: type: sigstore-cosign runtime: maxMemoryPages: 256 timeoutMs: 5000 # hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it. exports: - name: fetch operates: emit scope: own selector: external-secret resources for the bound credentialmetadata
Metadati standard del catalogo. name, version e pluginType sono obbligatori; version è una Semantic Version rigorosa (ad es. 1.2.0). I campi opzionali — description, maintainers, license, repository, home, keywords — seguono la stessa forma di ogni entità di catalogo, e metadata non accetta altre chiavi. Una versione pubblicata è immutabile: ripubblicare una versione esistente viene rifiutato al controllo di pubblicazione.
metadata.name è semplice — non porta alcun prefisso di socket. La coordinata indirizzabile del plugin plugin/<pluginType>/<name> deriva da metadata.pluginType e dal metadata.name semplice; non viene scritta nel nome.
metadata.pluginType
Il tipo di socket che questo plugin implementa. Si trova nel blocco di indirizzamento accanto a name e version perché fa parte dell’identità del plugin: fornisce il segmento <pluginType> della coordinata derivata plugin/<pluginType>/<name>. Un plugin implementa esattamente un tipo di socket, scelto dalla tassonomia dei tipi di plugin che il runtime riconosce:
provider— esegue il rendering dei nodi IR in artefatti nativi del provider.linter— ispeziona il contenuto scritto e genera diagnostiche.pipeline-step— uno step nellapipeline:di una FeatureRecipe o di una Recipe che applica patch all’insieme dei documenti renderizzati.governance— svolge i ruoli di governance della pipeline di build. Durante la costruzione della topologia applica automaticamente label ai nodi del grafo della topologia, restituendo documenti JSON Patch che l’host applica a una proiezione del grafo limitata alle sole label. Durante l’analisi statica o la fase di rendering valuta il grafo IR o gli artefatti renderizzati e restituisce un verdetto di accettazione/rifiuto; una regola non rispettata interrompe la build. Il ruolo a cui è collegato, non il suo tipo, determina ciò che può emettere.parser— analizza un formato sorgente esterno (HCL, TOML, YAML, JSON, …) in un albero JSON strutturato, così un consumatore che deve leggere un formato che il compilatore non analizza nativamente lavora su un albero analizzato anziché sul testo grezzo.importer— trasforma una sorgente esterna di infrastruttura o di definizione di agenti in bozze di file di authoring Aggrega, dichiarando i formati che gestisce come capacitàimport:<format>.cli— fornisce un sottocomando di runtimeaggrega <cmd>che un operatore invoca dalla riga di comando. Un socket di runtime, distinto dai socket di rendering e di pipeline del momento della compilazione.
Obbligatorio.
spec.abiVersion
La versione ABI host/guest a cui il plugin è destinato. v1beta1 è il valore accettato; una nuova revisione dell’ABI ne aggiunge uno. Obbligatorio.
Dichiarare le capacità: un blocco per tipo di socket
Una capacità è ciò che un consumatore chiede a un plugin — una capacità di rendering che una Recipe richiede, o un formato sorgente che una build deve leggere. Le capacità di un plugin sono registrate all’interno del blocco che appartiene al suo tipo di socket, quindi è il blocco in cui si trova l’elenco a determinare il significato delle sue voci:
metadata.pluginType | Dove sono dichiarate le sue capacità | Cosa nomina una voce |
|---|---|---|
provider | spec.provider.capabilities | Una capacità di rendering che questo plugin serve, come helm o compose. |
pipeline-step | spec.pipelineStep.capabilities | Un provider con il cui output renderizzato è compatibile lo step di questo plugin. |
parser | spec.parser.capabilities | Un formato sorgente che questo plugin legge, scritto parse:<format>. |
importer | spec.importer.capabilities | Un formato sorgente esterno da cui questo plugin genera bozze di entità, scritto import:<format>. |
linter, governance, cli | — | Nulla. Questi socket non servono alcuna capacità, quindi non contengono nessuno dei quattro blocchi. |
Un plugin implementa esattamente un tipo di socket, quindi la sua entità contiene un solo blocco. L’elenco è il resoconto del plugin stesso: aggrega plugin gen-catalog legge il describe() del plugin e scrive nel blocco ogni capacità che esso riporta. Un autore può restringere l’elenco prima della pubblicazione, omettendo una capacità che il plugin riporta ma che l’entità pubblicata non dovrebbe offrire; aggrega validate <entity> --plugin <file.wasm> e aggrega push accettano un elenco ristretto e stampano un avviso che nomina ogni capacità riportata dal plugin che l’elenco omette. Nessuno dei due accetta un elenco che nomina una capacità che il plugin non riporta: entrambi lo rifiutano, nominando ogni capacità di questo tipo e le capacità che il plugin riporta effettivamente, così un elenco pubblicato non offre mai più di quanto il plugin fornisca. Un’entità pipeline-step il cui plugin riporta helm e helm-chart, e che elenca anche compose, viene rifiutata così:
[E0080] entity "probe-step:1.0.0-rc.1" lists capabilities ["compose"], which the plugin's describe() does not report (it reports ["helm" "helm-chart"]); remove them from the list, which may name only capabilities the plugin reports: wasm: entity contract claim does not match plugin describe()Un consumatore risolve esattamente rispetto a ciò che è elencato.
spec.provider
Il blocco del socket provider per un plugin pluginType: provider: le capacità che serve, come traduce il tipo Workload aggrega.ai/v1beta1 di proprietà della piattaforma, quali annotazioni native della piattaforma legge e il suo contratto di comportamento di rendering. Il blocco è presente su ogni plugin di rendering per provider e assente su ogni altro tipo di plugin. Un provider che esegue il rendering solo di contenuti sourced o di artefatti, senza sintesi di Workload, porta comunque il blocco: vi dichiara le sue capacità e il suo contratto, e semplicemente omette workloadSchema.
spec.provider.capabilities
Le capacità che questo provider serve — nomi di capacità come helm o compose — di cui produce la forma di output. Un provider è generico tra gli artefatti che condividono la forma di output di una capacità, non tra tutte le capacità, quindi l’elenco nomina le capacità che il plugin stesso riporta: aggrega plugin gen-catalog lo registra dal describe() del plugin, e un autore può restringerlo prima della pubblicazione. Le voci mantengono l’ordine in cui sono registrate.
Il target di provider richiesto da una Recipe (spec.capability: helm) si risolve nel plugin provider il cui elenco contiene quel target. Quando più di un plugin provider elenca lo stesso target, sceglie il workspace: la selezione plugins.providers nella configurazione del workspace indica quale plugin usare, viene risolta da aggrega pull e registrata nel lockfile. Senza selezione e con esattamente un candidato, si usa quel candidato; senza selezione e con più di un candidato, la build si arresta e nomina ogni candidato. L’ambiguità si risolve per workspace nel punto d’uso anziché con una regola di unicità valida per tutto il catalogo. Un elenco vuoto o assente non dichiara alcuna capacità, quindi il plugin non serve alcun target.
Un nome di capacità qui non contiene due punti. Lo spec.capability di una Recipe viene letto come la capacità fino agli ultimi due punti, seguita da un pin di versione, quindi un nome che li contenga non potrebbe mai essere richiesto; un plugin il cui describe() riporta un nome del genere viene rifiutato al caricamento, e da esso non viene generata alcuna entità da pubblicare. Lo stesso vale per le capacità di provider elencate da un plugin pipeline-step. I due punti in parse:<format> di un parser e in import:<format> di un importer fanno parte di quei nomi e restano.
spec.provider.workloadSchema
Una dichiarazione JSON Schema 2020-12 che documenta come questo provider traduce il tipo Workload aggrega.ai/v1beta1 in manifest nativi del provider. Per convenzione è dichiarata su un provider che esegue la sintesi: un provider del genere dichiara workloadSchema come contratto di traduzione documentato, descrivendo quali campi del Workload il provider consuma, quali insiemi chiusi accetta ciascun campo di tipo enum e quali vincoli di intervallo si applicano.
Il corpo viene compilato in JSON Schema 2020-12 quando il Plugin viene caricato — un guardrail strutturale che rifiuta uno schema malformato al caricamento anziché al rendering. Se una Recipe workload: sia supportata è determinato dalla capacità di sintesi del provider associato, non dalla presenza di questo campo: una Recipe in modalità sintetizzata associata a un provider che non è in grado di eseguire la sintesi si arresta in modo esplicito al momento del rendering. Il catalogo della libreria standard mantiene workloadSchema allineato alla capacità del provider. Il campo è il contratto documentato; nient’altro lo legge. I corpi dei Workload stessi sono validati rispetto allo schema Workload incorporato di proprietà della piattaforma, non rispetto a questo campo per provider.
spec.provider.wellKnownAnnotations
Un array ordinato che enumera le chiavi di annotazione well-known native della piattaforma — quelle sotto il namespace riservato aggrega.ai/ — che questo provider legge, insieme al comportamento applicato quando ciascuna è assente. Ogni voce porta una key (l’annotazione letta dal provider, ad es. aggrega.ai/namespace), un purpose (ciò che l’annotazione controlla quando è presente), un defaultBehavior facoltativo (ciò che il provider fa quando l’annotazione è assente) e uno scope facoltativo che elenca dove il provider legge la chiave — sourced, synthesized o artifactsStandalone, i tipi di input della Recipe, oppure boundary per una chiave letta una volta per confine. key e purpose sono obbligatori; le voci mantengono l’ordine dell’autore.
Il campo è la dichiarazione di supporto del provider, e il compilatore lo legge in due modi. Una voce il cui scope nomina un tipo di input che il contract.inputKinds dello stesso blocco non dichiara contraddice quella dichiarazione, e il Plugin viene rifiutato, con l’indicazione della chiave e dello scope. Inoltre, quando una build esegue il rendering tramite questo provider, un’annotazione aggrega.ai/ che nessuna voce copre su alcun tipo di input dichiarato dal rendering produce un avviso che nomina la chiave, il provider e quei tipi di input; il valore passa comunque inalterato e la build non si arresta. Se il campo è assente, non dichiara nulla, e per questo provider non viene emesso alcun avviso del genere. La validazione dello schema controlla solo la forma di ciascuna voce (la chiave si trova sotto il namespace aggrega.ai/, purpose è presente); è distinta dal controllo a runtime che regola l’associazione di un valore nel namespace riservato.
metadata: pluginType: providerspec: abiVersion: v1beta1 provider: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm workloadSchema: | # how the Workload kind translates to this provider's native output ... wellKnownAnnotations: - key: aggrega.ai/namespace purpose: Overrides the target namespace the provider renders into. defaultBehavior: Renders into the boundary's default namespace.Gli insiemi di annotazioni per provider e il contenuto di workloadSchema forniti dai provider della libreria standard sono documentati in ../providers/well-known-annotations.md, ../providers/helm.md, ../providers/helm-chart.md e ../providers/compose.md.
spec.provider.readsNoWellKnownAnnotations
Dichiara che questo provider non legge nessuna delle chiavi di annotazione well-known native della piattaforma. È una dichiarazione di supporto che non copre alcuna chiave, e dice qualcosa che omettere sia questo campo sia wellKnownAnnotations non dice: una dichiarazione assente è silenzio, mentre questa è l’affermazione del provider stesso di non leggere nulla sotto il namespace riservato aggrega.ai/. Una build che esegue il rendering tramite un provider del genere emette un avviso per ogni annotazione aggrega.ai/ che raggiunge il rendering, nominando la chiave, il provider e i tipi di input dichiarati dal rendering; il valore passa comunque inalterato e la build non si arresta.
Si può scrivere solo true, quindi omettere il campo resta l’unico modo per non dire nulla. Non può essere scritto insieme a wellKnownAnnotations: un provider che legge alcune delle chiavi elenca invece quelle chiavi lì. Entrambi i rifiuti sono a livello di schema, quindi il Plugin viene rifiutato quando viene letto.
spec: provider: capabilities: - terraform readsNoWellKnownAnnotations: trueIl provider terraform della libreria standard lo dichiara; ../providers/terraform.md spiega cosa significa per una Release il cui rendering passa attraverso di esso.
spec.provider.contract
Il contratto di comportamento di rendering in fase di compilazione autodichiarato da un plugin di rendering per provider: i tipi di input di cui esegue il rendering, come assembla l’output per nodo di un gruppo di dispatch, la coppia di delimitatori di template che applica ai file di artefatto importati, se un’unica istanza caricata può servire ogni attraversamento, se rispetta le voci di omissione e se accetta i file che una Recipe contribuisce all’output condiviso del suo confine. Si trova accanto a capabilities nello stesso blocco ma risponde a una domanda diversa: l’elenco delle capacità dice quali capacità serve questo plugin, mentre il contratto dice come ne esegue il rendering. aggrega plugin gen-catalog lo registra dall’autodichiarazione describe() del plugin stesso, e l’host lo confronta con tale autodichiarazione alla pubblicazione e al caricamento; una discrepanza causa l’arresto. Se assente, non dichiara alcun contratto di comportamento di rendering, e il controllo incrociato confronta solo le dichiarazioni per export. Tutti i campi sono facoltativi.
| Campo | Effetto |
|---|---|
inputKinds | Quali dei tre tipi di input della Recipe il plugin renderizza, ciascuno una dichiarazione booleana indipendente: sourced (un insieme di file sorgente — un chart, un modulo, un file compose), synthesized (un Workload sintetizzato) e artifactsStandalone (un nodo autonomo che porta documenti di artefatto importati e nessuna sorgente né workload). L’host verifica il tipo di input di un nodo rispetto a questo insieme. |
boundaryAssembly | Come il plugin combina l’output di rendering per nodo di un gruppo di dispatch: none scrive l’output di ogni nodo direttamente nel percorso di dispatch; merge fonde i frammenti per nodo in un unico documento; nest colloca l’output di ogni nodo nella propria posizione all’interno di una struttura ombrello. Se assente, non porta alcuna dichiarazione di assemblaggio. |
artifactDelimiters | La coppia di delimitatori di template Go che il plugin applica ai file di artefatto importati, come left e right. Se assente, vale la coppia predefinita {{/}}; un plugin la cui sintassi di destinazione collide con quella coppia dichiara una coppia alternativa (per esempio [[/]]). |
reusableInstance | Se un’unica istanza caricata del plugin può servire ogni attraversamento di rendering, assemblaggio e validazione di una build anziché un’istanza nuova per ogni attraversamento. Si dichiara true solo quando il plugin non mantiene stato tra un attraversamento e l’altro, così che una singola istanza produca un output identico byte per byte, sia che venga riutilizzata sia che venga caricata da zero. Se assente (false), viene caricata un’istanza nuova per ogni attraversamento, isolando un plugin che per costruzione mantiene stato. aggrega build --verify-determinism dimostra che l’output di un plugin riutilizzabile è stabile eseguendo il rendering di ogni nodo due volte e arrestandosi a qualsiasi differenza. |
omits | Se il plugin rispetta le voci di omissione — voci che nominano unità renderizzate da escludere dall’output di un nodo: esclude da ciò che renderizza ogni unità a cui corrisponde una voce, e riporta quante unità ha trovato ciascuna voce. Il valore registra la dichiarazione riportata dal describe() del plugin, quindi true è corretto solo per un plugin che la riporta, e un valore diverso da quanto riportato causa l’arresto. Se assente (false), non dichiara alcun supporto del genere. |
boundaryArtifacts | Se la destinazione del plugin accetta i file che una Recipe contribuisce all’output condiviso del confine in cui il plugin esegue il rendering, sotto lo spec.boundary.artifacts della Recipe: il compilatore scrive ciascuno di questi file una sola volta, accanto a ciò che il plugin assembla per il confine, e la destinazione lo legge come parte di quell’output. Il valore registra la dichiarazione riportata dal describe() del plugin, e un valore diverso da quanto riportato causa l’arresto. Se assente (false), non dichiara alcun supporto del genere, e una Recipe che dichiara il blocco per questo plugin viene rifiutata prima di qualsiasi rendering. |
metadata: pluginType: providerspec: provider: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm-chart contract: inputKinds: sourced: true synthesized: false artifactsStandalone: false boundaryAssembly: nest artifactDelimiters: left: "[[" right: "]]" reusableInstance: truespec.pipelineStep
Il blocco pipeline-step per un plugin pluginType: pipeline-step. Il suo unico campo, capabilities, nomina i provider il cui output renderizzato lo step del plugin sa trasformare — nomi di capacità come helm o compose. Uno step è scritto per la forma di output di un provider alla volta, quindi l’elenco nomina i provider che il plugin stesso riporta; le voci mantengono l’ordine in cui sono registrate. Il blocco è presente solo sui plugin pipeline-step.
Il blocco è la registrazione, leggibile dal catalogo, di quella dichiarazione: aggrega plugin gen-catalog la registra dall’autodichiarazione describe() del plugin stesso, e un autore può restringerla prima della pubblicazione. Il controllo legge la stessa dichiarazione dal plugin: quando uno step tocca uno scope, la build si arresta a meno che il provider che esegue il rendering dei documenti di quello scope sia tra quelli dichiarati dal plugin. Un elenco vuoto o assente non dichiara alcuna compatibilità, quindi nessuno scope ammette lo step.
metadata: pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm - composespec.parser
Il blocco parser per un plugin pluginType: parser. Il suo unico campo, capabilities, nomina i formati sorgente che il plugin trasforma in un albero strutturato canonico, ciascuno scritto parse:<format>. Il prefisso fa parte della voce, quindi un plugin che legge più formati elenca una voce per formato. aggrega plugin gen-catalog registra l’elenco dal describe() del plugin stesso, un autore può restringerlo prima della pubblicazione, e le voci mantengono l’ordine in cui sono registrate. Il blocco è presente solo sui plugin parser.
Un formato richiesto si risolve nel parser il cui elenco contiene la voce corrispondente. Un formato che nessun parser annuncia arresta la build, e un formato annunciato da più di un plugin parser si arresta come ambiguo, nominando i candidati — non esiste un fallback, perché un parser non ha un valore predefinito a configurazione zero su cui ripiegare. Un elenco vuoto o assente non dichiara alcun formato, quindi il plugin non analizza nulla.
metadata: pluginType: parserspec: abiVersion: v1beta1 parser: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - parse:hcl - parse:tomlspec.importer
Il blocco importer per un plugin pluginType: importer. Il suo campo capabilities nomina i formati sorgente esterni che il plugin trasforma in bozze di file di authoring Aggrega, ciascuno scritto import:<format>. Il prefisso fa parte della voce, quindi un plugin che gestisce più formati elenca una voce per formato. aggrega plugin gen-catalog registra l’elenco dal describe() del plugin stesso, un autore può restringerlo prima della pubblicazione, e le voci mantengono l’ordine in cui sono registrate. Il blocco è presente solo sui plugin importer.
Un formato di importazione richiesto si risolve nell’importer il cui elenco contiene la voce corrispondente. Un formato che nessun importer annuncia arresta l’importazione, e un formato annunciato da più di un plugin importer si arresta come ambiguo, nominando i candidati, a meno che una voce plugins.importer nella configurazione del workspace non colleghi uno di essi, che è allora quello che viene eseguito. Un elenco vuoto o assente non dichiara alcun formato, quindi il plugin non importa nulla.
Il suo campo detect registra le firme da cui viene riconosciuta una sorgente di quei formati quando un’importazione non nomina alcun formato. È gestito dalla macchina, come le registrazioni delle funzioni host e dei comandi: deriva da ciò che riporta il describe() del plugin quando l’entità viene generata dal plugin, nell’ordine in cui il plugin dichiara le firme, e un autore non lo scrive. Ogni firma nomina:
syntax— il formato sintattico in cui viene analizzata la sorgente, il formato che un plugin parser annuncia comeparse:<syntax>, ad esempiojsonoyaml.files— pattern facoltativi di nomi di file, confrontati con la parte finale del nome della sorgente: un pattern di un solo segmento con il nome del file stesso, uno di più segmenti separati da barre con altrettanti segmenti finali del suo percorso, quindi.vscode/mcp.jsoncorrisponde a un file chiamatomcp.jsonin una directory chiamata.vscode.*,?e[...]corrispondono all’interno di un segmento. Se assente, la firma si applica a una sorgente costituita da un solo file, comunque si chiami, e a nessun file di una directory. I pattern delle firme di un importer sono anche ciò che decide quali file di una directory gli passaaggrega import.match— i predicati che l’albero analizzato deve soddisfare, tutti quanti. Ciascuno ha unpath, chiavi unite da punti a partire dalla radice dell’albero, in cui un segmento numerico intero seleziona una posizione di array; unis, uno trapresent,absent,object,array,string,numbereboolean; e facoltativamenteequals, una stringa che il valore deve essere, oppureprefix, una stringa con cui deve iniziare — al massimo uno dei due.
Quando un’importazione non nomina alcun formato, le firme di ogni importer contenuto nel catalogo del workspace — tutte le versioni incluse — e degli importer di base del compilatore vengono confrontate con la sorgente. La sorgente viene analizzata una volta per ciascuna sintassi in cui la legge una firma applicabile al suo nome, tramite il parser che il catalogo del workspace fornisce per quella sintassi — oppure, per una sintassi per cui il catalogo non fornisce alcun parser, quello incluso nel compilatore stesso — e una sorgente che non si analizza in una sintassi non corrisponde ad alcuna firma che la nomina. Una directory viene confrontata attraverso i suoi file: ogni firma viene provata sui file della directory selezionati dai suoi pattern, in ordine di nome, e una firma che non dichiara alcun pattern non si applica a nessuno di essi. Una sorgente a cui corrisponde una firma viene riconosciuta come ogni formato annunciato dal suo importer. Se viene riconosciuto esattamente un formato, la sorgente viene letta in quel formato. Una sorgente a cui non corrisponde alcuna firma viene rifiutata, con la richiesta del formato e l’indicazione dei formati annunciati dagli importer — oppure, per una directory, con la richiesta di uno dei suoi file preso da solo o di un formato il cui importer dichiara pattern di file, indicando solo questi; una sorgente riconosciuta come più di un formato viene rifiutata nominandoli, con la condizione More than one importer recognises the source (Più di un importer riconosce la sorgente). Quindi un importer che annuncia più di un formato vede rifiutata come ambigua ogni sorgente a cui corrispondono le sue firme, e un importer le cui sorgenti devono essere riconosciute serve un solo formato.
Dove l’entità registra detect, questo deve essere uguale a ciò che riporta il describe() del plugin, firma per firma e nello stesso ordine: il caricamento dell’importer rifiuta un plugin il cui resoconto differisce, nominando importer.detect, e così fa anche la sua pubblicazione. Un’entità che non registra detect non dichiara nulla e non viene confrontata, quindi carica qualsiasi firma riportata dal describe() del suo plugin, e i formati del suo importer sono allora raggiungibili solo nominandoli.
metadata: pluginType: importerspec: abiVersion: v1beta1 importer: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - import:langflow detect: - syntax: json match: - path: data.nodes is: arrayspec.signature
Un puntatore descrittivo facoltativo alla firma allegata del plugin. Il blocco è solo documentazione — registra dove si trova la firma e come è stata prodotta, per chi legge il catalogo; di per sé non ammette il plugin. Il controllo che la fa rispettare è la policy di fiducia per registry applicata al pull: una firma viene recuperata come referrer OCI, verificata rispetto alle identità attendibili o alla chiave fissata del registry, e registrata come fatto verificato nel lockfile. Un registry che richiede le firme arresta il pull quando una firma richiesta è mancante, non attendibile o non valida.
type— lo schema di firma.sigstore-cosignè lo schema supportato. Obbligatorio quando il blocco è presente.signatureRef— il riferimento referrer OCI del bundle di firma allegato, per documentazione e individuazione. Assente quando la firma viene individuata tramite l’enumerazione dei referrer al pull anziché fissata qui.publicKeyRef— un puntatore alla chiave pubblica con cui è stata prodotta la firma, per una firma con chiave. L’assenza indica una firma keyless (basata su identità OIDC), verificata rispetto alle identità attendibili del registry.
spec.runtime
Vincoli di esecuzione facoltativi che l’host applica durante il caricamento e l’esecuzione del plugin. L’accesso alla rete in uscita non è un campo di authoring: un plugin non raggiunge mai la rete in fase di build — il confine ahead-of-time — quindi qui non esiste un campo di allowlist degli host. Il contenuto remoto di cui un plugin ha bisogno arriva attraverso il canale di input esterno mediato dall’host e fissato per digest, registrato nel lockfile della Release, mai tramite un accesso di rete ambientale; la guida per sviluppatori documenta il wrapper di fetch e la disciplina del pinning.
| Campo | Effetto |
|---|---|
maxMemoryPages | Limita la memoria lineare del plugin in pagine Wasm (64 KiB per pagina). Zero o assente applica il limite predefinito della piattaforma, quindi un caricamento non è mai illimitato; un collegamento che ha bisogno di più memoria aumenta questo valore. |
timeoutMs | Limita per quanto tempo il codice del plugin stesso può essere eseguito durante una chiamata, in millisecondi, senza contare il tempo trascorso all’interno delle funzioni host che chiama. Su Linux la misura è il tempo di processore, quindi il tempo trascorso in attesa di un processore su una macchina carica non conta; su altri sistemi è il tempo reale trascorso. La prima chiamata a un plugin appena caricato conta anche l’avvio del plugin stesso. Zero o assente applica il limite predefinito della piattaforma, quindi una chiamata non è mai impossibile da annullare; un collegamento che viene eseguito più a lungo aumenta questo valore. |
hostFunctions | I nomi delle funzioni host che il plugin importa. Derivato dalla macchina e di sola lettura — non scriverlo: aggrega plugin sync legge le funzioni host dalla sezione di import del .wasm e registra questo campo, la pubblicazione rifiuta una registrazione che differisce dal binario, e il valore riflette il binario pubblicato, validato rispetto all’allowlist curata. L’host registra esattamente questo insieme, dando a ciascun plugin la superficie host con privilegi minimi di cui il suo binario ha bisogno; il pull ricava di nuovo il valore registrato e lo verifica rispetto al binario. Per vedere in anteprima il valore prima della pubblicazione, esegui aggrega inspect --plugin <file.wasm>. |
configKV | Configurazione specifica del Plugin che il runtime passa al plugin all’avvio, come coppie chiave/valore da stringa a stringa. Le voci mantengono l’ordine dell’autore, così che la registrazione emessa sia identica byte per byte tra un’esecuzione e l’altra. Se assente, resta in vigore la configurazione vuota predefinita del runtime. |
spec.exports
Gli export offerti dal plugin, ciascuno con la sua capacità dichiarata, come elenco ordinato che mantiene l’ordine dell’autore. Un export è un punto di ingresso con nome a cui l’host esegue il dispatch (per esempio render_node, lint_naming, step); il blocco di capacità per export indica cosa fa quell’export, così come aggrega plugin gen-catalog lo registra dall’autodichiarazione describe() del plugin, e l’host lo confronta con tale autodichiarazione alla pubblicazione e al caricamento. Se assente, non dichiara alcuna superficie di export scritta dall’autore.
| Campo | Effetto |
|---|---|
name | Il nome ABI dell’export — il nome a cui l’host esegue il dispatch. Obbligatorio per ogni voce. |
operates | L’operazione di pipeline che l’export esegue: patch (modifica un documento renderizzato esistente) o emit (aggiunge un nuovo documento). L’host confronta il valore con l’autodichiarazione del plugin; è una dichiarazione di capacità validata, non un selettore di dispatch — l’operazione che uno step esegue è portata dal risultato restituito dal guest. Se assente, non porta alcuna dichiarazione di operazione. |
scope | La radice dei documenti su cui opera l’export: own (i documenti renderizzati del nodo stesso) o host (i documenti del componente a cui è collegata una FeatureRecipe con ambito di componente). L’host legge lo scope dichiarato prima dello step per far rispettare la compatibilità di provider rispetto al provider che esegue il rendering di quello scope. Se assente, il valore predefinito è own. |
selector | Una descrizione libera e leggibile da persone di ciò su cui agisce l’export (per esempio workloads carrying a pod template). Documentazione per chi legge il catalogo e per la superficie di ispezione; il compilatore non la interpreta. |
spec.commands
I verbi di primo livello aggrega <command> che un plugin cli aggiunge, come elenco ordinato che conserva l’ordine dichiarato dall’auto-dichiarazione describe() del plugin. Gestito dalla macchina e di sola lettura — non scriverlo a mano. aggrega plugin sync legge la superficie dei comandi dall’auto-dichiarazione describe() del plugin e la registra qui, così i comandi che un plugin CLI installa sono leggibili dall’entità senza caricare il .wasm. Un plugin non cli non aggiunge comandi e registra un elenco vuoto. L’host installa esattamente questo insieme; un insieme registrato che diverge dall’auto-dichiarazione describe() del plugin interrompe il caricamento, e la pubblicazione rifiuta un insieme non sincronizzato con il binario e indica all’autore di registrarlo di nuovo. Per risincronizzare il record dopo aver modificato il plugin, esegui aggrega plugin sync.
Ogni voce di comando contiene:
| Campo | Effetto |
|---|---|
name | Il verbo del comando che l’host registra — il token aggrega <name> che un operatore invoca, e il discriminante che l’host passa al plugin al momento dell’invocazione, così che un singolo plugin che fornisce più comandi possa instradare in base al comando chiamato. Obbligatorio per ogni voce. |
description | Il testo di aiuto breve, su una riga, del comando, mostrato nell’elenco dei comandi e nell’output dell’aiuto. Solo documentazione; l’host non agisce in base a esso. |
flags | I flag del comando, nell’ordine dichiarato. Ogni voce registra un flag sul comando, così aggrega help <command> lo mostra come il flag di un comando nativo. Un comando senza flag lo lascia vuoto. |
Ogni voce di flags dichiara un flag:
| Campo | Effetto |
|---|---|
name | Il nome lungo del flag — il token --name che un operatore passa sulla riga di comando. Obbligatorio per ogni voce. |
shorthand | L’alias breve facoltativo del flag — la forma -x che un operatore può passare al posto del nome lungo — come singola lettera o cifra ASCII. Se assente, il flag non ha alias breve. |
description | Il testo di aiuto su una riga del flag, mostrato nell’output dell’aiuto del comando. Documentazione facoltativa; l’host non la convalida né agisce in base a essa. |
type | Il tipo di valore del flag — string, bool o int — e il tipo di flag con cui l’aiuto lo mostra. Se assente, viene mostrato come flag di tipo stringa. |
default | Il valore predefinito del flag quando l’operatore non lo passa, espresso come stringa. Per un flag bool o int è un valore di quel tipo. Se assente, il flag non dichiara alcun valore predefinito. |
Un plugin CLI dichiara i propri comandi e i relativi flag in describe(); l’host registra esattamente quella superficie e mostra i flag di ogni comando in aggrega help <command> nello stesso modo in cui mostra i flag di un comando nativo.
L’host controlla ogni flag dichiarato da un plugin quando ne aggiunge i comandi, e un plugin le cui dichiarazioni non superano il controllo viene saltato anziché aggiunto: nessuno dei suoi comandi viene registrato, un avviso indica il plugin, il comando, il flag e cosa non va, e ogni altro comando — nativo o di un altro plugin — continua a funzionare. Una dichiarazione non supera il controllo quando:
- un flag non ha nome, oppure un comando dichiara lo stesso nome due volte;
- un’abbreviazione è qualcosa di diverso da una singola lettera o cifra ASCII, oppure un comando dichiara la stessa abbreviazione per due flag;
- un nome o un’abbreviazione riutilizza un flag che ogni comando
aggregapossiede già —--help, il suo-h, e i flag globali come--offlinee--config; - un tipo è qualcosa di diverso da
string,booloint; - un valore predefinito non è interpretabile come il tipo del flag —
maybeper unbool,threeper unint.
La forma a carattere singolo di shorthand e i tre valori di type fanno parte anche dello schema di questa entità, quindi un’entità Plugin che registra qualsiasi altro valore viene rifiutata al caricamento del catalogo. Che un nome o un’abbreviazione compaia una sola volta per comando, che nessuno riutilizzi un flag presente in ogni comando e che un valore predefinito sia interpretabile come il suo tipo viene controllato solo dall’host. Il controllo verifica se l’host può dichiarare un flag per l’aiuto così come è scritto; non vede se il plugin legge i flag che dichiara, perché il plugin interpreta da sé i propri argomenti.
metadata: pluginType: clispec: abiVersion: v1beta1 # commands is recorded by `aggrega plugin sync` from the plugin's describe() — do not author it. commands: - name: greet description: Print a friendly greeting flags: - name: name shorthand: n description: Who to greet type: string default: worldIspezionare un Plugin
aggrega inspect <path-to-Plugin.yaml> mostra un file Plugin: la sua identità e il tipo di socket, le capacità dichiarate dal suo blocco, la tabella delle capacità per export nell’ordine dell’autore, i vincoli di runtime e — con --detail — il puntatore alla firma e le chiavi di configurazione di runtime. Un Plugin è indirizzabile tramite percorso di file, oppure tramite la sua coordinata <pluginType>/<name> nel catalogo. Vedi ../cli/aggrega-inspect.md.
Riferimenti incrociati
- Guida per sviluppatori di plugin Wasm — il flusso di lavoro completo dell’autore:
describe(), dichiarazioni di capacità, limiti di runtime, ciclo di vita, firma, versionamento. - Contratto dei plugin Wasm — i punti di socket a cui un plugin si collega e le forme dei loro input e output.
entities/featurerecipe.md— la superficiepipeline:della FeatureRecipe che fa riferimento a un plugin tramite URI di entità.cli/aggrega-lint.md— il linter di pubblicazione, i criteri di incremento della versione e l’applicazione dell’immutabilità che regolano la pubblicazione di unPlugin.