Schema della configurazione del workspace di Aggrega
Riferimento generato. Non modificarlo a mano — rigeneralo a partire dal JSON Schema pubblicato.
Id dello schema: https://aggrega.ai/schemas/aggrega-config-v1beta1.schema.json
File di configurazione per workspace consumato dalla CLI aggrega. Si trova in .aggrega-config.yaml. Il blocco workspace è il marcatore della radice: la sua presenza contrassegna la radice del workspace, e contiene solo directory di catalogo. Ogni altra chiave è un’impostazione e si trova al primo livello, in queste classi — da dove il contenuto viene recuperato, fissato e messo in cache (selezione del registry, offline, comportamento di auto-pull e di fissaggio, posizioni e limiti di dimensione delle cache degli artefatti e dei moduli compilati), come ci si fida del contenuto (firma e comportamento della verifica delle firme), con quale rigore viene giudicato l’authoring (regolazioni di lint per regola, rigore sulle deprecazioni e l’indicazione della release di authoring), quali plugin Wasm sono associati all’intero workspace (governance, linter, importer e legami di rendering del provider per destinazione) e come viene eseguita la CLI (concorrenza, servizio e limiti di espulsione della cache di analisi del daemon). Le proprietà qui sotto sono l’elenco completo e autorevole; questo riepilogo nomina le classi anziché le chiavi, così l’aggiunta di una chiave non può renderlo falso. Forma piatta di primo livello, nessun involucro apiVersion/kind, distinta dal contenuto del catalogo. Disciplina di evoluzione dello schema: aggiungere una nuova chiave di primo livello è un incremento SemVer-MINOR (additivo); rimuovere o spostare una chiave, o restringere un vincolo, è una rottura SemVer-MAJOR.
Tipo di primo livello: object
Proprietà
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
workspace | object | no | Marcatore della radice del workspace. La sua sola presenza contrassegna la directory come radice del workspace; porta solo le directory di catalogo che definiscono la radice — quelle proprie del workspace e quelle che una Release riceve come proprie. Ogni impostazione che non definisce la radice si trova al primo livello anziché qui. Scrivi workspace: {} per contrassegnare una radice senza directory di catalogo vendorizzate. |
default_registry | string | no | Registry OCI predefinito su cui vengono pubblicate le entità e da cui vengono risolte le dipendenze quando un’entità non nomina esplicitamente un registry: aggrega push pubblica lì e aggrega pull recupera da lì. Il valore predefinito è hub.aggrega.ai. Scrivi il name di una voce sotto registries, che allora sta per l’host di quella voce; l’host stesso; oppure l’host seguito da / e da un percorso di repository, come ghcr.io/acme o harbor.example.com/platform. Un nome viene confrontato per primo: un valore che è il name di una voce è l’host di quella voce, anche dove è scritto anche come un host, così la pubblicazione, il pull, la verifica delle firme e ogni impostazione di fiducia per registry usano quell’unico host; un valore con cui sono nominate due voci viene rifiutato come ambiguo, e un nome seguito da un percorso viene rifiutato, perché un nome sta per l’host di una voce e non per una posizione al di sotto di esso. Qualsiasi altro valore deve essere un host, scritto nella grafia con cui è conservata la sua policy di fiducia: un nome host in minuscolo che contiene un punto (registry.example.com), localhost, un singolo nome seguito da una porta (registry:5000), un indirizzo IPv4 o un indirizzo IPv6 tra parentesi quadre ([::1]), ciascuno con un :port opzionale e senza schema, credenziali, spazi o lettere maiuscole — seguito facoltativamente da un percorso di repository: uno o più segmenti di lettere minuscole e cifre uniti da /, che all’interno di un segmento possono essere separati da ., _, __ o trattini, senza tag, digest né / finale. Il percorso è dove le cose vengono pubblicate e recuperate: ogni entità pubblicata tramite il registry predefinito viene pubblicata sotto <host>/<path>/, e ogni entità risolta tramite esso viene recuperata da lì, così ciò che l’uno pubblica l’altro lo trova. Non fa mai parte del modo in cui ci si fida di un registry: la voce di registries la cui policy si applica, un login, un requisito di firma e le identità attendibili vengono tutti trovati in base al solo host. La porta 443 su un host raggiunto tramite HTTPS è la porta predefinita di quell’host, e scriverla viene rifiutato, indicando la grafia da scrivere senza di essa; localhost e gli altri indirizzi di loopback vengono raggiunti tramite HTTP semplice, quindi lì 443 è una porta ordinaria e viene mantenuta. Un valore vuoto non nomina alcun registry predefinito. Il valore viene giudicato quando la configurazione viene caricata anziché da questo schema, perché la voce a cui un nome fa riferimento può essere dichiarata in un altro file di configurazione: viene letto dopo ogni file di configurazione e dopo la variabile d’ambiente AGGREGA_DEFAULT_REGISTRY, e rifiutato con le stesse parole chiunque dei due l’abbia impostato, nominando quel file o la variabile. Il flag --registry che nomina la destinazione di una pubblicazione per una singola invocazione viene confrontato con i nomi delle voci allo stesso modo; qualsiasi altro valore che porta può essere un riferimento, e l’host che quel riferimento nomina è tenuto alla stessa grafia ed è dove arriva la pubblicazione, senza percorso di repository. L’host viene giudicato solo in base alla sua grafia: non viene verificato se il nome si risolve, né se lì risponde un registry. Predefinito: "hub.aggrega.ai" |
offline | booleana | no | Quando è true, la build non contatta alcun registry; vengono consultati solo gli artefatti in cache e il contenuto di catalogo vendorizzato. Il valore predefinito è false. Predefinito: false |
auto_pull | booleana | no | Quando è false (valore predefinito), aggrega build è in sola lettura: non scrive mai fissaggi delle sorgenti, e un file di lock per release mancante o incompleto arresta la build in modo esplicito con una diagnostica che indica di eseguire prima aggrega pull --release <release>. Quando è true, aggrega build esegue un passo di pull all’interno del processo prima della build — risolvendo le dipendenze della Release nel file di lock e nella cache — così una prima build rispetto a una Release non richiede un passo di pull esplicito. La stessa adesione per una singola build è disponibile dalla riga di comando come aggrega build --auto-pull; pull resta l’unico a scrivere il file di lock. offline: true non disattiva il passo di pull: questo viene eseguito su ciò che la macchina già contiene — la cache e le directory di catalogo locali — senza raggiungere un registry, e un riferimento che nessuna delle due contiene arresta la build con il rifiuto proprio del pull che nomina quel riferimento. Predefinito: false |
pin_sources_at_pull | booleana | no | Quando è false (valore predefinito), un pull non registra alcun fissaggio accanto a un’entità: su una Recipe o una FeatureRecipe in una delle directory di catalogo di questo workspace che la Release usa nella build, si arresta quando l’entity.lock accanto all’entità non registra un fissaggio per ogni input che l’entità legge — un source: remoto le cui coordinate sono scritte per intero, un file che una voce di artifacts importa, oppure ogni file di un source: locale accanto all’entità — nominando l’entità, ogni input e la sua classe, e aggrega pin come il passo che li registra. Il fissaggio è il passo dell’autore dell’entità, quindi un’entità che nessuno ha fissato non è ancora pronta per essere consumata. Quando è true, ogni pull in questo workspace esegue invece quel passo, sulle stesse entità, scrivendo gli stessi byte di entity.lock che scrive aggrega pin; è così che un workspace che consuma entità che qualcun altro non ha fissato ne registra i fissaggi una sola volta anziché arrestarsi. Una build che riempie il proprio file di lock è un pull e segue questa impostazione. aggrega pull --pin-sources esegue il fissaggio per una singola invocazione e --pin-sources=false si arresta per una singola invocazione, qualunque cosa dica questa impostazione. Un’entità risolta dalla cache anziché da una directory di catalogo non ha dove scrivere un lock e non viene mai fissata né trattenuta da un pull. Predefinito: false |
pin_sources_at_push | booleana | no | Quando è true, ogni aggrega push in questo workspace esegue il passo di fissaggio dell’autore dell’entità sull’entità che pubblica prima di impacchettarla, così l’entity.lock che il passo scrive accanto all’entità fa parte di ciò che viene pubblicato; quando è false (valore predefinito), il push non esegue alcun passo di fissaggio e rifiuta una Recipe o una FeatureRecipe il cui entity.lock non registra ogni fissaggio che quel passo registrerebbe, nominando aggrega pin. Il passo scrive accanto all’entità, quindi viene eseguito solo dove l’entità ha una collocazione scrivibile, che un push ha sempre: pubblica un’entità nominata dal suo documento. aggrega push --pin-sources esegue il fissaggio per una singola invocazione e --pin-sources=false no, qualunque cosa dica questa impostazione. È lo stesso passo che esegue aggrega pin, e scrive gli stessi byte. Predefinito: false |
artifact_cache_dir | string | no | Directory locale della cache di artefatti/contenuti (pull dai registry, manifest OCI, fixture compilate). Il valore predefinito è .aggrega/cache. Per convenzione dovrebbe essere esclusa tramite gitignore. Il percorso viene interpretato in modo relativo alla radice del workspace, da qualunque punto venga eseguito il comando; un valore assoluto viene rifiutato quando la configurazione viene caricata, perché ogni lettore di questa impostazione lo risolve rispetto a quella radice e un percorso assoluto nominerebbe una posizione che non raggiungono mai. La cache può trovarsi all’interno di una directory di catalogo — quella predefinita vi si trova, poiché una directory di catalogo è comunemente la radice del workspace — ma non deve ESSERE una directory di catalogo: una scansione del catalogo salta la cache, quindi un valore che nomina una directory di catalogo lascia fuori dalla scansione l’intero contenuto di quella directory. Un valore che nomina la radice del workspace stessa (., o qualsiasi grafia che si riduce a essa) viene rifiutato quando la configurazione viene caricata, esattamente per questo motivo. Un valore che nomina qualsiasi altra directory di catalogo non viene rifiutato: si carica senza errori e la scansione poi non trova nulla in quella directory, quindi tenere la cache fuori dalle directory elencate in workspace.catalog_dirs è un controllo che spetta a te. Distinta da parse_cache, che limita la cache di analisi in memoria del daemon, e da compiled_module_cache, che limita l’archivio dei moduli compilati condiviso dall’intera macchina. Predefinito: ".aggrega/cache" |
skip_signature_verification | booleana | no | Rinuncia globale e ben visibile alla verifica delle firme. Quando è true, la verifica delle firme è disattivata su ogni registry, compresa la baseline obbligatoria dell’hub. Pensata per scenari di emergenza (break-glass) e di sviluppo; non è mai silenziosa — ovunque un pull avrebbe controllato una firma, avvisa che la verifica è stata disattivata globalmente. Il valore predefinito è false. Predefinito: false |
build | object | no | Regolazioni di rigore in fase di build e indicazioni per l’authoring. authoring_release fornisce all’LSP un’indicazione current Release per le diagnostiche inline; halt_on_deprecated_severity controlla come la build reagisce al consumo di entità deprecate; yaml_indent imposta la larghezza dell’indentazione di ogni artefatto YAML renderizzato. |
plugins | object | no | Associazioni dei plugin Wasm a livello di workspace. Ogni socket (governance, linter, importer) accetta un array di riferimenti a plugin; la build invoca la funzione di ingresso documentata di ciascun plugin secondo il contratto del suo socket. L’elenco providers lega le capacità ai plugin di rendering del provider che le servono. |
lint | object | no | Regolazioni di rigore per regola. |
parse_cache | object | no | Limiti di espulsione della cache di analisi del daemon. Entrambi i limiti si applicano contemporaneamente — il ciclo di espulsione LRU viene eseguito dopo ogni inserimento nella cache e rimuove le voci usate meno di recente finché sia il numero di voci sia il totale dei byte rientrano nei limiti. Zero su uno dei due significa unbounded on that axis, utile negli scenari di CI in cui la cache vive solo per una singola invocazione. Distinti da artifact_cache_dir, che è la cache dei contenuti su disco. |
compiled_module_cache | object | no | Limite di dimensione per la cache su disco dei moduli compilati, l’archivio di codice macchina che il compilatore riusa così che un plugin Wasm venga compilato una volta per macchina anziché una volta per build. È condivisa tra tutti i workspace della macchina, quindi questa chiave va nel file di configurazione globale quando vuoi un’unica risposta per l’intera macchina. Il limite viene applicato una volta per invocazione, prima che venga caricato qualsiasi plugin, rimuovendo voci intere a partire da quelle compilate da più tempo finché ciò che resta vi rientra — mai mentre una build sta compilando. Rimuovere una voce costa una ricompilazione successiva e nient’altro, quindi abbassare il limite è sicuro. aggrega cache status riporta la dimensione attuale dell’archivio, e aggrega cache evict --max-size lo riduce su richiesta a un limite indicato sulla riga di comando. Distinta da artifact_cache_dir (contenuto scaricato dai registry) e da parse_cache (la cache di analisi in memoria del daemon). |
concurrency | object | no | Impostazioni di concorrenza per lo smistamento delle richieste del daemon. Il daemon legge le richieste da un unico flusso stdin ed esegue ciascuna tramite un pool di worker che svuota una coda di richieste limitata; le risposte vengono emesse nell’ordine di arrivo delle richieste, indipendentemente dall’ordine di completamento. |
serve | object | no | Impostazioni di comportamento del daemon (aggrega serve) per il compilatore come servizio consumato dalle integrazioni con gli IDE. |
mcp | object | no | Impostazioni per il server Model Context Protocol (aggrega mcp). transport sceglie come si raggiunge il server — tramite lo standard input e lo standard output del processo, oppure tramite HTTP — e viene letto qualunque delle due scelga. Anche announce_tools viene letto su entrambi i trasporti, perché quali strumenti vengono offerti a un client è una proprietà del server e non del modo in cui un client lo ha raggiunto. Ogni altra chiave configura il listener che il trasporto HTTP avvia e non viene usata mentre il server comunica tramite standard input e standard output — listen compreso, che lì viene letto solo perché il server possa dire, in una riga sul suo flusso di errore, che l’indirizzo non viene usato. Ogni chiave qui sotto indica di quale si tratta. Distinto da serve, che configura il daemon di backend dell’editor. |
registries | RegistryConfig[] | no | Impostazioni per registry e policy di fiducia delle firme, indicizzate per host del registry. Un registry non elencato qui usa i valori predefiniti: una firma presente viene verificata e una firma assente viene tollerata, tranne che per hub.aggrega.ai, la cui baseline incorporata impone una firma verificata anche senza alcuna voce esplicita. Una voce esplicita per un host sostituisce la baseline di quell’host. Predefinito: [] |
signing | SigningConfig | no | Blocco di firma di primo livello, valido per tutti i registry: gli URL dei servizi keyless, un percorso opzionale della chiave per la firma con chiave e la posizione di fiducia valida per tutti i registry (required e kinds). Un blocco signing per registry sostituisce i valori predefiniti degli endpoint per quell’host e porta la stessa posizione required/kinds con ambito limitato a quell’host — un nome, un compito, l’ambito dato dalla collocazione. La policy required/kinds di primo livello si compone in modo monotono lungo la cascata delle configurazioni. Sicurezza: questo blocco non contiene materiale segreto — il token di identità OIDC non è mai un campo di configurazione (viene fornito a runtime tramite flag o tramite l’ambiente OIDC circostante) e key_path è il percorso di un file di chiave, mai byte di chiave inline. |
Non sono consentite proprietà aggiuntive.
aggrega-config.workspace
Marcatore della radice del workspace. La sua sola presenza contrassegna la directory come radice del workspace; porta solo le directory di catalogo che definiscono la radice — quelle proprie del workspace e quelle che una Release riceve come proprie. Ogni impostazione che non definisce la radice si trova al primo livello anziché qui. Scrivi workspace: {} per contrassegnare una radice senza directory di catalogo vendorizzate.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
catalog_dirs | string[] | no | Directory di catalogo opzionali da cui questo workspace legge le entità locali, consultate prima di ripiegare sul registry. Ogni voce è un percorso del filesystem, risolto in modo relativo al file che la dichiara. L’elenco è uno stack di ricerca ordinato in cui vince il primo: la directory elencata per prima che dichiara un’identità ne è proprietaria, e la stessa identità in una directory successiva viene oscurata. Viene letta anche la directory catalog alla radice del workspace, dopo ogni voce elencata e solo quando esiste — a meno che una voce elencata non la contenga già, nel qual caso viene letta come parte di quella voce — così elencare una directory si aggiunge a ciò che il workspace leggeva già anziché sostituirlo. Omettere questa chiave e scriverla come elenco vuoto sono affermazioni diverse: se è omessa, il workspace legge comunque catalog; se è scritta come [], non legge alcun catalogo locale, ed è così che un workspace dice di non averne. Una Release che riceve directory di catalogo proprie sotto releases legge quelle al posto di questo elenco. Con ambito della radice: le directory di catalogo locali appartengono a questa radice del workspace, quindi si trovano sul marcatore della radice anziché al primo livello. |
catalog_dirs_append | string[] | no | Aggiunta opzionale, solo in coda, all’elenco catalog_dirs effettivo. A ogni livello di precedenza le voci indicate qui vengono concatenate all’elenco di base risolto, consentendo alle configurazioni del workspace e globali di comporre le directory di catalogo anziché oscurarle. Interazione allo stesso livello: quando a un livello sono specificati sia catalog_dirs sia catalog_dirs_append, il valore risolto a quel livello è l’elenco di base seguito dall’elenco da accodare. Predefinito: [] |
releases | mappa di ReleaseCatalogConfig | no | Directory di catalogo opzionali proprie di una Release, per un workspace che tiene affiancate diverse varianti di catalogo e compila ogni Release rispetto a una di esse. Ogni chiave è un file di Release, scritto come percorso relativo al file che la dichiara; ogni valore porta catalog_dirs e catalog_dirs_append con il significato che hanno in questo blocco, con ambito limitato a quell’unica Release. Una Release nominata qui legge il proprio catalog_dirs al posto dell’elenco di questo blocco, seguito dal proprio catalog_dirs_append; una voce che omette catalog_dirs mantiene l’elenco di questo blocco e vi aggiunge dopo il proprio catalog_dirs_append. L’ordine di ricerca, la directory catalog alla radice del workspace e il significato di un elenco vuoto sono gli stessi dell’elenco proprio di questo blocco, e una Release che questa mappa non nomina legge l’elenco di questo blocco esattamente come prima. La Release legge queste directory in qualunque modo venga compilata — da un terminale, da un editor tramite aggrega serve o tramite aggrega mcp — e una directory --catalog viene comunque cercata prima di esse per una singola invocazione. Una voce che nomina un file inesistente viene rifiutata quando la configurazione viene caricata, nominando la voce e il file, così rinominare una Release non può cambiare in silenzio il catalogo rispetto a cui viene compilata. Tra i file di configurazione la voce di ciascuna Release si compone come le chiavi proprie di questo blocco: il catalog_dirs di un file più vicino per quella Release sostituisce quello di un file più lontano, e il catalog_dirs_append di ogni file per essa viene aggiunto nell’ordine della cascata. AGGREGA_CATALOG_DIRS imposta l’elenco di questo blocco e non raggiunge alcuna voce di qui. Un’operazione che non riguarda una singola Release — un lint o una validazione dell’intero catalogo, la ricerca di un’entità per nome o l’elenco delle entità del workspace in un editor — legge l’elenco di questo blocco e non questi. |
Non sono consentite proprietà aggiuntive.
aggrega-config.build
Regolazioni di rigore in fase di build e indicazioni per l’authoring. authoring_release fornisce all’LSP un’indicazione current Release per le diagnostiche inline; halt_on_deprecated_severity controlla come la build reagisce al consumo di entità deprecate; yaml_indent imposta la larghezza dell’indentazione di ogni artefatto YAML renderizzato.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
authoring_release | string | no | Percorso di un file YAML di Release che l’LSP tratta come contesto current Release per le diagnostiche inline. Opzionale. |
yaml_indent | integer | no | Larghezza dell’indentazione (in spazi) di ogni artefatto YAML renderizzato — file docker-compose, template e valori dei chart Helm e manifest di Kubernetes. Il valore predefinito è 2, la larghezza convenzionale per quei formati. Minimo: 2. Massimo: 9. Predefinito: 2 |
halt_on_deprecated_severity | string (enum) | no | Severità, nell’insieme ordinato warning < error < retracted, pari o superiore alla quale un marcatore di deprecazione registrato arresta la build. Governa entrambi i luoghi in cui viene registrato un marcatore: il file di lock, per tutto ciò che una build riproduce byte per byte, e il registro di fiducia dei plugin accanto a esso, per un plugin associato in un ruolo che restituisce un verdetto di accettazione o rifiuto — un’associazione plugins.governance a ir-verdict o render-verdict, e ogni associazione plugins.linter. Una regolazione, una regola, entrambi gli archivi. Per impostazione predefinita non è impostata, e non impostata significa che nessun marcatore registrato provoca un arresto: un marcatore viene registrato su una versione che hai già fissato, così una build riuscita una volta continua a riuscire. Notifica e risoluzione sono due assi separati e nessuno dei due è questa regolazione. Ogni superficie che legge l’uno o l’altro registro riporta ogni riferimento deprecato che fissa e ogni plugin attendibile che porta un marcatore — a ogni severità — nominandolo, con la sua severità e il suo messaggio: aggrega build, aggrega validate --release, aggrega lint --release, il daemon rivolto all’editor e gli strumenti build, describe e validate nativi per l’IA. Quindi alzare questa soglia non riduce mai ciò che ti viene comunicato. Questa regolazione governa solo la build: arresta aggrega build (e lo strumento build nativo per l’IA, che è la stessa operazione), mentre le superfici di segnalazione nominano il marcatore e proseguono. Solo un marcatore retracted influisce sulla versione in cui si risolve un riferimento, e lo fa quando aggrega pull sceglie una versione, non in fase di build. Valori consentiti: "warning", "error", "retracted" |
Non sono consentite proprietà aggiuntive.
aggrega-config.plugins
Associazioni dei plugin Wasm a livello di workspace. Ogni socket (governance, linter, importer) accetta un array di riferimenti a plugin; la build invoca la funzione di ingresso documentata di ciascun plugin secondo il contratto del suo socket. L’elenco providers lega le capacità ai plugin di rendering del provider che le servono.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
governance | PluginRef[] | no | I plugin del socket governance. Ogni voce nomina il role della pipeline a cui è associata (annotation-transform, label-transform, ir-verdict o render-verdict); il ruolo stabilisce sia ciò che il plugin può emettere sia la sua funzione di ingresso predefinita (annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). Predefinito: [] |
governance_append | PluginRef[] | no | Aggiunta, solo in coda, all’elenco governance effettivo. Le voci indicate qui vengono concatenate all’elenco di base risolto a ogni livello di precedenza, consentendo alle configurazioni del workspace e globali di comporre le associazioni governance anziché oscurarle. Predefinito: [] |
linter | PluginRef[] | no | I plugin del socket linter. Funzione di ingresso predefinita: lint_rules. Le esportazioni di un plugin linter devono iniziare con lint_, quindi function: su una di queste voci nomina un’esportazione con quel prefisso. Predefinito: [] |
linter_append | PluginRef[] | no | Aggiunta, solo in coda, all’elenco linter effettivo. Stessa semantica di composizione senza oscuramento di governance_append. Predefinito: [] |
importer | FixedEntryPluginRef[] | no | I plugin del socket importer. Il socket chiama la funzione di ingresso import; un’associazione non ne nomina una. Predefinito: [] |
importer_append | FixedEntryPluginRef[] | no | Aggiunta, solo in coda, all’elenco importer effettivo. Stessa semantica di composizione senza oscuramento di governance_append. Predefinito: [] |
providers | FixedEntryPluginRef[] | no | Selezioni del provider per capacità. Ogni voce lega una capacità del provider (il nome semplice della capacità che una Recipe lega tramite spec.capability, ad es. helm o compose) all’identità semplice del plugin di rendering del provider che la serve (l’identità dell’entità Plugin, cioè i suoi metadata.pluginType e metadata.name uniti da una barra, ad es. provider/helm), con un :version finale opzionale nelle stesse tre forme di un fissaggio di versione (semplice, esatta :1.0.0, o intervallo compatibile con la major :^1.0.0). Questa è la superficie di disambiguazione e di override per un catalogo federato in cui più di un plugin di provider serve la stessa capacità: il legame seleziona il plugin di quale editore esegue il rendering di quella capacità. Quando una capacità è servita da esattamente un plugin di provider non serve alcuna voce. In tutto l’elenco composto è consentita esattamente una voce per capacità; una capacità duplicata arresta la risoluzione in modo esplicito. La risoluzione avviene al pull: il pull registra il legame risolto nel file di lock per Release, e la build legge il file di lock — una modifica qui dopo un pull non viene adottata fino al pull successivo, quindi l’output della build è invariante rispetto a essa (output deterministico). Ogni build e ogni validazione di una Release controlla inoltre ogni voce di qui, che una Recipe richieda o meno la sua capacità: una voce che nomina un plugin contenuto nella build che non serve la capacità della voce provoca un arresto, nominando ciò che quel plugin serve e una grafia a una modifica di distanza quando ce n’è una; una voce che nomina una capacità e nessun plugin, dove nessun plugin di provider letto dalla build serve quella capacità, viene segnalata come avviso anziché provocare un arresto, perché il plugin che la serve potrebbe essere uno che legge solo un’altra Release; e una voce per una capacità che un plugin serve ma che questa Release non richiede mai è lecita e non viene segnalata affatto, poiché le voci sono scritte per l’intero workspace e una build riguarda una sola Release. Una capability che contiene i due punti viene rifiutata quando la configurazione viene caricata: lo spec.capability di una Recipe viene letto come la capacità fino all’ultimo segno di due punti e un fissaggio di versione dopo di esso, quindi nessuna Recipe potrebbe raggiungere una voce del genere. Una voce mancante per una capacità servita senza ambiguità non è un errore; una voce mancante per una capacità servita in modo ambiguo arresta il pull in modo esplicito, elencando i plugin candidati. La coesistenza delle versioni è preservata: il legame seleziona il repository del plugin per capacità, e il fissaggio di versione in spec.capability proprio di ciascuna Recipe seleziona la versione all’interno di quel repository, così due Recipes che fissano versioni diverse di uno stesso provider continuano a coesistere. Predefinito: [] |
providers_append | FixedEntryPluginRef[] | no | Aggiunta, solo in coda, all’elenco providers effettivo. Le voci indicate qui vengono concatenate all’elenco di base risolto a ogni livello di precedenza, consentendo alle configurazioni del workspace e globali di comporre i legami del provider anziché oscurarli. Stessa semantica di composizione senza oscuramento di governance_append. La regola di una voce per capacità si applica all’elenco composto, quindi una voce accodata che nomina una capacità già legata da un livello inferiore arresta la risoluzione in modo esplicito. Predefinito: [] |
cli | CLIPluginRef[] | no | I plugin di estensione della CLI installati come comandi aggrega di primo livello. Ogni voce fissa un plugin della CLI tramite il suo riferimento all’artefatto risolto e fissato a una versione e il digest del contenuto dei byte del guest in cui quel riferimento si è risolto al momento dell’installazione. A differenza dei quattro elenchi di socket trasversali, il cui elenco di base viene sostituito per intero lungo la cascata delle configurazioni, l’elenco della CLI si compone: un plugin della CLI nella configurazione globale registra i propri comandi in ogni workspace, uno in una configurazione del workspace si registra solo in quel progetto, ed entrambi si registrano insieme — quindi non ha bisogno di un compagno _append. I nomi dei comandi e l’aiuto che ciascun plugin fornisce provengono dall’autodescrizione del plugin stesso, letta dalla cache di describe su disco indicizzata per digest (il caricamento del guest è il ripiego quando la cache è fredda); l’elenco porta solo il fissaggio. All’invocazione del comando i byte risolti vengono sottoposti di nuovo a hash e confrontati con digest; una mancata corrispondenza arresta il comando in modo esplicito e indica di rifare il fissaggio, così un plugin i cui byte sono cambiati da quando è stato fissato non viene mai eseguito inosservato. Predefinito: [] |
Non sono consentite proprietà aggiuntive.
aggrega-config.lint
Regolazioni di rigore per regola.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
publishing_discipline | object | no | Interruttori validi per l’intero workspace sull’insieme di regole del linter di pubblicazione. I flag allow_* allentano singoli controlli dissuasivi. L’immutabilità degli artefatti non è configurabile qui: aggrega push rifiuta incondizionatamente di sovrascrivere una versione pubblicata. |
Non sono consentite proprietà aggiuntive.
aggrega-config.lint.publishing_discipline
Interruttori validi per l’intero workspace sull’insieme di regole del linter di pubblicazione. I flag allow_* allentano singoli controlli dissuasivi. L’immutabilità degli artefatti non è configurabile qui: aggrega push rifiuta incondizionatamente di sovrascrivere una versione pubblicata.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
allow_dynamic_refs | booleana | no | Quando è true, il linter di pubblicazione accetta i costrutti JSON Schema $dynamicRef / $dynamicAnchor nel contenuto del catalogo. Il valore predefinito è false; questi costrutti sono sconsigliati perché rendono non locale la composizione degli schemi in fase di compilazione. Predefinito: false |
allow_id_overrides | booleana | no | Quando è true, il linter di pubblicazione accetta override di $id sui sottoschemi all’interno del contenuto di schema di un’entità. Il valore predefinito è false; gli override di $id infrangono la convenzione di un identificatore canonico per schema su cui si basano sia il resolver sia il validatore JSON Schema. Predefinito: false |
allow_direct_x_aggrega_extensions | booleana | no | Quando è true, il controllo dissuasivo in fase di build accetta le parole chiave x-aggrega-selector e x-aggrega-inject scritte direttamente nel contenuto dello schema. Il valore predefinito è false; il percorso di authoring consigliato è usesSchema (per i socket di dipendenza) o featuresSchema (per i legami delle credenziali), che il compilatore compone in quelle parole chiave. Predefinito: false |
allow_aggrega_ai_prefix | booleana | no | Quando è true, il linter di pubblicazione accetta chiavi di annotazione che usano i namespace riservati aggrega.ai/ e feature.aggrega.ai/ al di fuori dei loro contesti canonici. La regola dei prefissi riservati controlla i metadata.annotations delle entità di catalogo: il prefisso semplice aggrega.ai/ è nativo della piattaforma (le chiavi di annotazione ben note sono esenti indipendentemente da questo flag); il prefisso feature.aggrega.ai/ è canonico solo sul tipo Feature. Il valore predefinito è false. Gli operatori lo impostano quando gli strumenti aziendali devono legittimamente usare un prefisso riservato; allenta entrambi i prefissi insieme. Predefinito: false |
allow_nonstandard_names | booleana | no | Quando è true, il linter di pubblicazione accetta nomi di entità di catalogo che non seguono le convenzioni di denominazione documentate del progetto. Il valore predefinito è false; una denominazione coerente è portante per il resolver, per la selezione tramite etichette e per l’ergonomia di chi revisiona. Predefinito: false |
allow_category_mismatches | booleana | no | Quando è true, il linter di pubblicazione sopprime la regola category-matches-directory. La convenzione del catalogo standard richiede che i Components sotto core/false |
allow_undeclared_recipe_provides | booleana | no | Quando è true, il linter di pubblicazione sopprime la regola provides-declared-by-component. Quella regola segnala ogni chiave che una Recipe pubblica in spec.provides e che il Component nominato dal suo spec.implements non dichiara nel pilastro provides del proprio spec.schema. Le due sono superfici separate: ciò che una Recipe pubblica è il valore che un consumatore riceve, mentre ciò che il Component dichiara è il contratto di output rispetto a cui viene controllato un riferimento inject from: — quindi una chiave pubblicata senza essere dichiarata provoca l’arresto di un tale riferimento. Per il resto, una Recipe che pubblica più di quanto dichiara il suo Component viene accettata in fase di build, ed è per questo che la segnalazione è consultiva anziché un rifiuto di pubblicazione. Il valore predefinito è false. Predefinito: false |
allow_connection_credential_mismatches | booleana | no | Quando è true, il linter di pubblicazione sopprime la regola connection-credential-matches-target-key, che aggrega lint --release esegue sulla Release che nomina: la Release, l’Aggregate che essa distribuisce e i Components usati dalle istanze di quell’Aggregate. Per ogni connessione la cui destinazione dichiara la chiave che richiede ai propri chiamanti, la regola confronta ciò a cui fanno riferimento le due estremità: la credenziale che la connessione presenta e la chiave che la destinazione tiene nel proprio slot. Segnala due estremità che nominano secret diversi e una chiave dichiarata a una sola estremità, e non cita mai nessuno dei due. Nessuna delle due estremità può vedere le associazioni dell’altra, quindi le due concordano solo per disciplina di authoring — di solito un unico parametro che alimenta entrambe — e una build le accetta in entrambi i casi, ed è per questo che la segnalazione è consultiva. Un workspace le cui due estremità differiscono deliberatamente vi rinuncia qui. Il valore predefinito è false. Predefinito: false |
Non sono consentite proprietà aggiuntive.
aggrega-config.parse_cache
Limiti di espulsione della cache di analisi del daemon. Entrambi i limiti si applicano contemporaneamente — il ciclo di espulsione LRU viene eseguito dopo ogni inserimento nella cache e rimuove le voci usate meno di recente finché sia il numero di voci sia il totale dei byte rientrano nei limiti. Zero su uno dei due significa unbounded on that axis, utile negli scenari di CI in cui la cache vive solo per una singola invocazione. Distinti da artifact_cache_dir, che è la cache dei contenuti su disco.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
max_entries | integer | no | Limite al numero di analisi in cache. Il valore predefinito è 1000. 0 disattiva l’asse del numero di voci (nessuna espulsione attivata dal numero di voci). Minimo: 0. Predefinito: 1000 |
max_bytes | integer | no | Limite alla dimensione cumulativa, in byte, dei documenti che la cache contiene. Il valore predefinito è 100000000 (100 MB). 0 disattiva l’asse dei byte (nessuna espulsione attivata dal totale dei byte). Minimo: 0. Predefinito: 100000000 |
Non sono consentite proprietà aggiuntive.
aggrega-config.compiled_module_cache
Limite di dimensione per la cache su disco dei moduli compilati, l’archivio di codice macchina che il compilatore riusa così che un plugin Wasm venga compilato una volta per macchina anziché una volta per build. È condivisa tra tutti i workspace della macchina, quindi questa chiave va nel file di configurazione globale quando vuoi un’unica risposta per l’intera macchina. Il limite viene applicato una volta per invocazione, prima che venga caricato qualsiasi plugin, rimuovendo voci intere a partire da quelle compilate da più tempo finché ciò che resta vi rientra — mai mentre una build sta compilando. Rimuovere una voce costa una ricompilazione successiva e nient’altro, quindi abbassare il limite è sicuro. aggrega cache status riporta la dimensione attuale dell’archivio, e aggrega cache evict --max-size lo riduce su richiesta a un limite indicato sulla riga di comando. Distinta da artifact_cache_dir (contenuto scaricato dai registry) e da parse_cache (la cache di analisi in memoria del daemon).
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
max_bytes | integer | no | Limite ai byte che la cache dei moduli compilati occupa su disco. Il valore predefinito è 53687091200 (50 GiB), un tetto che ferma una crescita illimitata anziché un budget pensato per farsi sentire — un singolo plugin compilato arriva a centinaia di megabyte, quindi una macchina che compila molte versioni di plugin accumula gigabyte. Impostalo al di sopra di ciò che compila una singola build: il limite viene applicato prima che una build compili qualsiasi cosa, quindi un limite inferiore all’insieme di lavoro di una singola build fa sì che ogni build scarti e ricompili gli stessi moduli, e l’archivio smette di far risparmiare alcunché. Poiché il limite viene applicato per primo e la build scrive poi ciò che compila, tra una build e l’altra l’archivio può trovarsi al di sopra del limite; viene ridotto di nuovo all’inizio della build successiva. 0 disattiva il limite (l’archivio cresce senza limiti e nulla viene mai rimosso automaticamente). Poiché l’archivio è un’unica directory condivisa da tutti i workspace, questo limite non è per progetto nemmeno quando lo porta il file proprio di un progetto: il valore si risolve come ogni altra chiave, con il file più vicino che prevale, ma l’archivio ha comunque una sola dimensione. Il limite in vigore è quello dell’ultima build, quindi due progetti che lo impostano in modo diverso hanno effetto entrambi a turno, e un limite basso in uno scarta il codice macchina compilato dall’altro. Impostarlo una volta nel file di configurazione globale è ciò che dà all’intera macchina un’unica risposta. aggrega config show --origin indica il file da cui proviene il valore effettivo di ciascuna impostazione. Minimo: 0. Predefinito: 53687091200 |
Non sono consentite proprietà aggiuntive.
aggrega-config.concurrency
Impostazioni di concorrenza per lo smistamento delle richieste del daemon. Il daemon legge le richieste da un unico flusso stdin ed esegue ciascuna tramite un pool di worker che svuota una coda di richieste limitata; le risposte vengono emesse nell’ordine di arrivo delle richieste, indipendentemente dall’ordine di completamento.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
pool_size | integer | no | Numero di worker che servono la coda di richieste. Il valore predefinito è 4, che smista fino a quattro richieste contemporaneamente; impostalo a 1 per eseguire le richieste in serie nell’ordine di arrivo. Un valore inferiore a 1 viene portato a 1 all’avvio del daemon. Minimo: 1. Predefinito: 4 |
Non sono consentite proprietà aggiuntive.
aggrega-config.serve
Impostazioni di comportamento del daemon (aggrega serve) per il compilatore come servizio consumato dalle integrazioni con gli IDE.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
build_on_inspect | booleana | no | Indica se il daemon esegue la fase di rendering degli artefatti durante l’ispezione di un grafo IR, così che le segnalazioni consultive che aggrega build solleva durante il rendering compaiano anche come problemi dell’editor. Non aggiunge nessuno dei controlli su cui una build si arresta. In nessuno dei due casi viene scritto nulla su disco — nessun artefatto renderizzato, nessuna directory di output, nessun file di lock — e la fase di rendering non modifica mai il grafo, quindi, dove l’ispezione risponde con un grafo, è lo stesso grafo in entrambi i casi. Il valore predefinito è false, in linea con aggrega inspect: il comando da terminale non raggiunge la fase di rendering durante l’ispezione di un grafo, quindi non solleva nemmeno lui alcuna segnalazione di questo tipo, e un’ispezione nell’editor che non ne solleva nessuna ti mostra la stessa cosa che mostra il terminale. Impostalo a true per chiedere all’editor quel livello aggiuntivo. Predefinito: false |
lint_on_validate | booleana | no | Indica se il daemon esegue il controllo delle convenzioni di pubblicazione durante la validazione di un’entità di catalogo, così che le segnalazioni che aggrega lint riporta su quell’entità compaiano anche come problemi dell’editor. Le segnalazioni sono consultive: un documento che le riceve viene comunque validato, e la sua Release viene comunque risolta e renderizzata. Viene eseguito solo il controllo che legge il contenuto locale — nessun registry viene consultato, nulla viene recuperato e nulla viene scritto — e viene valutato sul buffer che l’editor tiene aperto anziché sul file su disco, così un nome che correggi smette di essere segnalato prima che tu salvi. Il valore predefinito è false: una sessione dell’editor riporta se un documento è corretto e non dice nulla sul fatto che un’entità sia pubblicabile, finché non chiedi quel secondo livello. Impostalo a true per chiederlo. Indipendentemente da questa chiave, un editor può sempre chiedere il controllo in modo diretto, ed è anche così che si raggiunge il confronto, prima della pubblicazione, con la versione pubblicata in precedenza. Predefinito: false |
Non sono consentite proprietà aggiuntive.
aggrega-config.mcp
Impostazioni per il server Model Context Protocol (aggrega mcp). transport sceglie come si raggiunge il server — tramite lo standard input e lo standard output del processo, oppure tramite HTTP — e viene letto qualunque delle due scelga. Anche announce_tools viene letto su entrambi i trasporti, perché quali strumenti vengono offerti a un client è una proprietà del server e non del modo in cui un client lo ha raggiunto. Ogni altra chiave configura il listener che il trasporto HTTP avvia e non viene usata mentre il server comunica tramite standard input e standard output — listen compreso, che lì viene letto solo perché il server possa dire, in una riga sul suo flusso di errore, che l’indirizzo non viene usato. Ogni chiave qui sotto indica di quale si tratta. Distinto da serve, che configura il daemon di backend dell’editor.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
transport | string (enum) | no | Come si raggiunge il server: stdio parla il protocollo tramite lo standard input e lo standard output del processo, ed è così che lo raggiunge un client che avvia il comando come sottoprocesso; http lo serve su HTTP all’indirizzo che listen nomina, e su HTTPS dove tls nomina un certificato e una chiave. aggrega mcp --transport stdio|http sovrascrive questa chiave per una singola invocazione. Il valore predefinito è stdio, quindi un workspace che non nomina mai un trasporto viene servito tramite standard input e standard output, qualunque altra cosa contenga questo blocco — un listener si avvia solo dove viene scelto http, qui o sulla riga di comando. Qualsiasi altro valore viene rifiutato quando la configurazione viene caricata. Imposta http nella configurazione di un server che i chiamanti raggiungono tramite la rete, e lascia la chiave non impostata dove è un client ad avviare il server: con stdio scelto, un indirizzo in listen non viene usato, e il server lo dice in una riga sul suo flusso di errore. Valori consentiti: "stdio", "http" Predefinito: "stdio" |
listen | string | no | Indirizzo a cui il listener si lega quando viene scelto il trasporto HTTP. Nomina dove ascoltare e non sceglie nulla: la scelta del trasporto spetta a transport, e con stdio scelto questa chiave non viene usata. Sono accettate due forme: host:port per un indirizzo TCP, e unix: seguito da un percorso del filesystem per un socket di dominio Unix. aggrega mcp --listen <address> sovrascrive questa chiave per una singola invocazione. Il valore predefinito è vuoto, e il trasporto HTTP ha bisogno di un indirizzo dall’uno o dall’altro: senza nessuno dei due, un avvio che lo sceglie viene rifiutato prima di qualsiasi bind. Un indirizzo in chiaro — raggiunto senza certificato e chiave sotto tls — è accettato solo su un indirizzo di loopback (127.0.0.1, ::1, o localhost che si risolve in uno di questi) o su un socket Unix, che è la forma usata da un server quando un proxy posto davanti termina TLS; qualsiasi altro indirizzo viene rifiutato prima di qualsiasi bind, nominando mcp.tls.cert_file e mcp.tls.key_file. Le stesse due forme sono le sole accettate, con o senza certificato, dove è impostato authorization.trusted_proxy, perché un header può essere considerato attendibile come credenziale solo dove nient’altro che il proxy può impostarlo. Predefinito: "" |
tls | object | no | Certificato e chiave per terminare TLS all’interno del processo che serve. Imposta entrambi per servire HTTPS direttamente dal listener che listen nomina. Lasciali entrambi non impostati per servire in chiaro, il che limita listen a un indirizzo di loopback o a un socket Unix — la forma da usare quando un proxy posto davanti detiene il certificato. Entrambe le chiavi sono percorsi di file su disco; nessuna delle due contiene materiale di chiave inline. |
allowed_origins | string[] | no | Origini accettate nell’header Origin di una richiesta. Una richiesta il cui header Origin nomina un’origine che questo elenco non contiene viene rifiutata con 403; una richiesta che nomina un’origine elencata, o che non porta alcun header Origin, viene servita. Una voce viene confrontata con l’header in modo esatto, quindi ciascuna si scrive nel modo in cui un browser invia un’origine: uno schema in minuscolo, ://, un host in minuscolo — un nome, un indirizzo IPv4 o un indirizzo IPv6 tra parentesi quadre — e : con la porta dove non è quella predefinita dello schema, senza nulla dopo. Ad esempio https://app.example.com o http://localhost:3000. Una voce in qualsiasi altra forma non potrebbe mai essere uguale a ciò che invia un browser, quindi viene rifiutata quando il file di configurazione viene caricato, nominando il file e la voce: una con una / finale o un percorso (https://app.example.com/), una senza schema (app.example.com), e una che contiene una lettera maiuscola o uno spazio. Il valore predefinito è vuoto, quindi nessuna origine viene accettata e viene servito solo un chiamante che non invia alcun header Origin. Un client basato su browser ha quindi bisogno che la sua origine sia elencata qui; un client che non è un browser non invia un header del genere e non ha bisogno di alcuna voce. Ogni voce corrisponde al pattern ^[a-z][a-z0-9+.-]*://(?:[a-z0-9._-]+|\[[0-9a-f:.]+\])(?::[0-9]{1,5})?$. Predefinito: [] |
limits | object | no | Limiti che il listener HTTP applica al traffico che accetta, così che un singolo chiamante non possa esaurire il processo che serve. Limitano quanto può essere grande una singola richiesta, quante richieste vengono eseguite contemporaneamente e con quale rapidità un chiamante può inviarle. Nessuno di essi può essere disattivato. |
authorization | object | no | Ciò che questo server dichiara sui bearer token che i suoi chiamanti presentano: quale server di autorizzazione li emette, l’indirizzo che questo server pubblica per sé come la risorsa per cui sono emessi, facoltativamente un file da cui leggere le chiavi di verifica di quel server, e facoltativamente gli header che imposta un proxy posto davanti quando è invece quel proxy a validare i token. issuer e resource sono obbligatori ogni volta che viene scelto il trasporto HTTP, e senza di essi un listener viene rifiutato prima di qualsiasi bind; un server che comunica tramite standard input e standard output non legge nessuna di queste chiavi. Entrambi sono pubblicati nel documento di metadati OAuth della risorsa protetta che il listener serve, che è l’unica risposta che un chiamante HTTP riceve senza che gli venga chiesta alcuna credenziale, perché un client lo legge per scoprire dove ottenere un token. Questo blocco non contiene materiale segreto: un token viene presentato da un chiamante sulla richiesta che effettua e non è mai un campo di configurazione, e jwks_file nomina chiavi pubbliche di verifica anziché qualcosa che firma. |
deny_reach | string (enum)[] | no | Tipi di portata che questo server non offre, qualunque cosa dica il token di un chiamante. Ogni operazione dichiara fin dove arrivano i propri effetti — none per una che legge o renderizza e non lascia nulla dietro di sé, workspace per una che scrive all’interno del workspace servito da questo processo, registry per una che pubblica, firma o ritira, e machine per una che modifica ciò che condividono tutti i workspace dell’host — e nominare un tipo qui ritira da questo server ogni strumento di quel tipo. Uno strumento ritirato è assente dall’elenco degli strumenti e da ciò che describe-capabilities risponde, per ogni chiamante, e chiamarlo comunque viene rifiutato nominando questa impostazione, perché nessuno scope potrebbe ammetterlo. Il valore predefinito è vuoto, quindi il server offre tutto ciò che gli scope dei suoi chiamanti ammettono. È un limite che il server impone a sé stesso, in aggiunta al limite per chiamante fissato dagli scope: un server che serve letture e nient’altro nomina qui i tre tipi che scrivono e allora non può pubblicare nemmeno per un chiamante il cui token porta ogni scope. Nominare machine è accettato e non cambia nulla — nessuno strumento di quel tipo viene mai offerto su HTTP, il che è una proprietà del trasporto anziché un’impostazione. Letto all’avvio del listener: un valore al di fuori dei quattro viene rifiutato quando la configurazione viene caricata, e modificarlo richiede un riavvio. Non viene letto affatto mentre il server comunica tramite standard input e standard output, dove il chiamante è la persona che ha avviato il processo. Valori consentiti per ogni voce: "none", "workspace", "registry", "machine". Predefinito: [] |
announce_tools | string[] | no | Strumenti che questo server annuncia, nominati esattamente come li riporta l’elenco degli strumenti. Se ometti la chiave, viene annunciato ogni strumento offerto da questo server, ed è ciò che si aspetta un client che segue il protocollo: recupera l’intero elenco degli strumenti e decide da sé quanta parte di esso presentare a un modello. Se scrivi un elenco, vengono annunciati esattamente quegli strumenti — uno lasciato fuori è assente dall’elenco degli strumenti, assente da ciò che describe-capabilities risponde, e rifiutato quando viene chiamato per nome, nominando questa impostazione. Se scrivi un elenco vuoto, non viene annunciato nulla. Impostala dove il client all’altro capo limita quanti strumenti registrerà — alcuni client applicano quel limite a tutti i server a cui sono connessi contemporaneamente — e nomina gli strumenti di cui quel client ha bisogno. Restringe ciò che viene annunciato e nient’altro: non può ampliare deny_reach, che ritira una capacità del tutto, né gli scope che porta il token di un chiamante. Uno strumento nominato qui di un tipo che deny_reach ritira resta fuori dall’elenco degli strumenti e viene rifiutato quando viene chiamato, nominando quell’impostazione; uno nominato qui che gli scope del chiamante non ammettono viene comunque elencato, e una sua chiamata viene rifiutata nominando lo scope che lo ammetterebbe. Ogni nome deve essere uno di quelli che questo binario offre: un nome a cui non risponde alcuno strumento viene rifiutato all’avvio del server, perché altrimenti chi ha chiesto una superficie più ristretta se ne vedrebbe servire una diversa senza che nulla lo segnali. Un nome della famiglia cli-, che esegue un comando aggrega in un processo separato, è accettato su entrambi i trasporti e su HTTP non annuncia nulla, perché lì nessuno strumento del genere viene offerto ad alcun chiamante. Letto su entrambi i trasporti all’avvio del server, quindi l’insieme annunciato è fisso per tutta la vita del processo e modificarlo richiede un riavvio. |
health | object | no | Dove un supervisore chiede se questo processo è attivo e se è pronto a rispondere a una chiamata. I due controlli ricevono risposta su un indirizzo proprio e mai sull’indirizzo che listen nomina: ogni richiesta all’endpoint porta un bearer token, quindi una probe a cui si rispondesse lì darebbe a qualunque cosa possa raggiungere l’endpoint una lettura non autenticata del processo insieme a un modo gratuito per farlo lavorare. L’endpoint risponde a /healthz e /readyz con lo stesso 404 che dà a ogni percorso che non serve, con un token come senza. |
Non sono consentite proprietà aggiuntive.
aggrega-config.mcp.tls
Certificato e chiave per terminare TLS all’interno del processo che serve. Imposta entrambi per servire HTTPS direttamente dal listener che listen nomina. Lasciali entrambi non impostati per servire in chiaro, il che limita listen a un indirizzo di loopback o a un socket Unix — la forma da usare quando un proxy posto davanti detiene il certificato. Entrambe le chiavi sono percorsi di file su disco; nessuna delle due contiene materiale di chiave inline.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
cert_file | string | no | Percorso della catena di certificati PEM che il listener presenta, letto all’avvio del processo. Si imposta insieme a key_file. Il valore predefinito è vuoto, quindi il listener serve in chiaro e listen è limitato a un indirizzo di loopback o a un socket Unix. Predefinito: "" |
key_file | string | no | Percorso della chiave privata PEM per il certificato in cert_file, letto all’avvio del processo. Si imposta insieme a quell’impostazione. Un percorso di un file, mai materiale di chiave inline. Il valore predefinito è vuoto, quindi il listener serve in chiaro e listen è limitato a un indirizzo di loopback o a un socket Unix. Predefinito: "" |
Non sono consentite proprietà aggiuntive.
aggrega-config.mcp.limits
Limiti che il listener HTTP applica al traffico che accetta, così che un singolo chiamante non possa esaurire il processo che serve. Limitano quanto può essere grande una singola richiesta, quante richieste vengono eseguite contemporaneamente e con quale rapidità un chiamante può inviarle. Nessuno di essi può essere disattivato.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
max_body_bytes | integer | no | Dimensione massima, in byte, del corpo di una richiesta che il listener accetta. Una richiesta il cui corpo la supera viene rifiutata con 413, e il corpo non viene letto oltre il limite. Il valore predefinito è 4194304 (4 MiB), ben al di sopra di una chiamata a uno strumento che porta un intero documento di authoring e ben al di sotto di ciò che permetterebbe a un singolo chiamante di occupare una quota significativa della memoria del processo. Il minimo è 1, quindi non esiste alcun valore che disattivi il limite; alzalo dove i chiamanti inviano legittimamente documenti più grandi. Minimo: 1. Predefinito: 4194304 |
max_concurrent_requests | integer | no | Quante richieste il listener esegue contemporaneamente. Una richiesta che arriva mentre ce ne sono già altrettante in corso viene rifiutata con 503 anziché messa in coda, così a un chiamante viene detto di riprovare invece di attendere dietro a un lavoro che non può vedere. Il valore predefinito è 16, che lascia spazio a diverse chiamate a strumenti simultanee mantenendo reattivo un host piccolo; alzalo su un host più grande. Il minimo è 1, quindi non esiste alcun valore che disattivi il limite. Minimo: 1. Predefinito: 16 |
requests_per_minute | integer | no | Quante richieste un singolo chiamante può inviare in un minuto. Il conteggio è per chiamante anziché per server — rispetto al soggetto che il token del chiamante nomina, o rispetto all’identità asserita da un proxy attendibile — così un chiamante molto attivo non può consumare la quota di un altro. Un chiamante può inviarne questo numero in una raffica; la quota poi si ricarica in modo costante, al ritmo di una richiesta in più ogni 60 / requests_per_minute secondi, e una richiesta che arriva quando la quota è esaurita viene rifiutata con 429. Il valore predefinito è 120, cioè due al secondo in modo sostenuto: molto al di sopra di ciò che invia un assistente che lavora su un workspace, e comunque un limite per un client finito in un ciclo. Il minimo è 1, quindi non esiste alcun valore che disattivi il limite. Minimo: 1. Predefinito: 120 |
Non sono consentite proprietà aggiuntive.
aggrega-config.mcp.authorization
Ciò che questo server dichiara sui bearer token che i suoi chiamanti presentano: quale server di autorizzazione li emette, l’indirizzo che questo server pubblica per sé come la risorsa per cui sono emessi, facoltativamente un file da cui leggere le chiavi di verifica di quel server, e facoltativamente gli header che imposta un proxy posto davanti quando è invece quel proxy a validare i token. issuer e resource sono obbligatori ogni volta che viene scelto il trasporto HTTP, e senza di essi un listener viene rifiutato prima di qualsiasi bind; un server che comunica tramite standard input e standard output non legge nessuna di queste chiavi. Entrambi sono pubblicati nel documento di metadati OAuth della risorsa protetta che il listener serve, che è l’unica risposta che un chiamante HTTP riceve senza che gli venga chiesta alcuna credenziale, perché un client lo legge per scoprire dove ottenere un token. Questo blocco non contiene materiale segreto: un token viene presentato da un chiamante sulla richiesta che effettua e non è mai un campo di configurazione, e jwks_file nomina chiavi pubbliche di verifica anziché qualcosa che firma.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
issuer | string | no | Indirizzo del server di autorizzazione che emette i token accettati da questo listener, scritto come quel server dichiara il proprio identificatore di emittente — ad esempio https://login.example.com. Viene pubblicato nell’elenco authorization_servers del documento di metadati della risorsa protetta, ed è così che un client apprende dove ottenere un token per questo listener. Il valore predefinito è vuoto, che non è un valore utilizzabile: un listener viene rifiutato prima di qualsiasi bind a meno che questa chiave non contenga un indirizzo completo, schema e host compresi. È un indirizzo https a meno che il server di autorizzazione non sia in esecuzione su questa macchina: http semplice è accettato solo per un host di loopback, come localhost, 127.0.0.1 o ::1, e un emittente http semplice su qualsiasi altro host viene rifiutato prima di qualsiasi bind, nominando questa chiave e chiedendo un indirizzo https. Questo vale sia che le chiavi vengano lette dall’emittente o da jwks_file, sia che un trusted_proxy posto davanti controlli i token, perché ogni client viene indirizzato all’emittente per ottenere il proprio token. Predefinito: "" |
resource | string | no | Indirizzo che questo server pubblica per sé, così come lo raggiunge un chiamante — ad esempio https://mcp.example.com/mcp. Scrivi l’indirizzo che i chiamanti usano effettivamente, compreso l’host che presenta un proxy posto davanti, perché questo è l’identificatore che un client consegna al server di autorizzazione quando chiede un token per questo server, e viene pubblicato invariato come campo resource del documento di metadati della risorsa protetta. Il punto in cui quel documento viene servito deriva da esso, inserendo /.well-known/oauth-protected-resource tra l’host e il percorso: un server pubblicato come https://mcp.example.com/mcp lo serve in https://mcp.example.com/.well-known/oauth-protected-resource/mcp, e anche in quel percorso well-known senza nulla dopo, che è dove un client cerca in seconda battuta. Un token viene accettato solo dove questo indirizzo è tra le audience che nomina. Il valore predefinito è vuoto, che non è un valore utilizzabile: un listener viene rifiutato prima di qualsiasi bind a meno che questa chiave non contenga un indirizzo completo, schema e host compresi. Predefinito: "" |
jwks_file | string | no | Percorso di un file che contiene il JSON Web Key Set rispetto a cui vengono verificati i token accettati da questo server, letto all’avvio del processo. Il valore predefinito è vuoto, che è il caso abituale: le chiavi vengono lette dal server di autorizzazione stesso, chiedendo a issuer dove le pubblica e recuperandole dall’indirizzo che indica, e vengono rilette una volta quando arriva un token firmato con un identificatore di chiave che il set detenuto non contiene. Imposta questa chiave dove il workspace è offline, nel qual caso senza di essa un listener viene rifiutato prima di qualsiasi bind, perché un workspace offline non effettua richieste di rete e non c’è altro modo di ottenere le chiavi; il file contiene allora le sole chiavi accettate, e il server di autorizzazione non viene mai contattato. Il file contiene chiavi pubbliche di verifica e mai nulla che firmi. Un percorso relativo si risolve rispetto alla directory del file di configurazione che lo ha dichiarato. Predefinito: "" |
trusted_proxy | object | no | Legge chi è un chiamante dagli header che imposta un proxy posto davanti, invece di validare qui un bearer token. Impostalo solo dove valgono entrambe le condizioni: un proxy posto davanti valida i token da sé, e nient’altro che quel proxy può raggiungere il listener: con questa chiave impostata, listen deve essere un indirizzo di loopback o un socket Unix, e qualsiasi altro indirizzo viene rifiutato prima di qualsiasi bind, nominando entrambe le impostazioni. Un header è attendibile esattamente quanto l’insieme dei chiamanti che possono impostarlo, e su un indirizzo raggiungibile dalla rete ogni chiamante può impostare qualsiasi header voglia, quindi un listener in questa modalità su un indirizzo del genere permetterebbe a ogni chiamante di dichiararsi chiunque. Con questa chiave impostata non viene letto alcun token — né dall’header Authorization, né da altrove, e non viene recuperato alcun set di chiavi —, l’identità del chiamante è il valore di principal_header, una richiesta che non porta quell’header riceve risposta 401, e i due header nominati qui sono gli unici letti. Se la ometti, come avviene per impostazione predefinita, questo server valida da sé i bearer token. |
Non sono consentite proprietà aggiuntive.
aggrega-config.mcp.authorization.trusted_proxy
Legge chi è un chiamante dagli header che imposta un proxy posto davanti, invece di validare qui un bearer token. Impostalo solo dove valgono entrambe le condizioni: un proxy posto davanti valida i token da sé, e nient’altro che quel proxy può raggiungere il listener: con questa chiave impostata, listen deve essere un indirizzo di loopback o un socket Unix, e qualsiasi altro indirizzo viene rifiutato prima di qualsiasi bind, nominando entrambe le impostazioni. Un header è attendibile esattamente quanto l’insieme dei chiamanti che possono impostarlo, e su un indirizzo raggiungibile dalla rete ogni chiamante può impostare qualsiasi header voglia, quindi un listener in questa modalità su un indirizzo del genere permetterebbe a ogni chiamante di dichiararsi chiunque. Con questa chiave impostata non viene letto alcun token — né dall’header Authorization, né da altrove, e non viene recuperato alcun set di chiavi —, l’identità del chiamante è il valore di principal_header, una richiesta che non porta quell’header riceve risposta 401, e i due header nominati qui sono gli unici letti. Se la ometti, come avviene per impostazione predefinita, questo server valida da sé i bearer token.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
principal_header | string | sì | Header in cui il proxy posto davanti inserisce l’identità del chiamante — ad esempio X-Forwarded-User. Si scrive come nome di header HTTP: lettere, cifre e trattini, e gli altri caratteri che un nome di header può contenere (!#$%&'*+.^_|~ e il backtick), senza spazi, due punti o altri separatori. Un nome in qualsiasi altra forma viene rifiutato quando il file di configurazione viene caricato, nominando il file e la chiave, perché nessuna richiesta può portare un header del genere. Anche uno vuoto viene rifiutato: lascerebbe questo server a controllare i token da sé mentre il blocco dice che lo fa un proxy posto davanti. Per lasciare disattivata questa modalità, ometti trusted_proxy. Il valore dell’header viene preso esattamente come è scritto e non viene confrontato con nulla, così come il soggetto di un token che questo server valida da sé viene registrato e non confrontato con nulla. In questa modalità è l’intera credenziale, quindi è obbligatorio ogni volta che trusted_proxy è impostato, e una richiesta che arriva senza di esso riceve risposta 401. Pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$. |
scopes_header | string | no | Header in cui il proxy posto davanti inserisce gli scope concessi al chiamante, separati da spazi — ad esempio X-Forwarded-Scopes. Si scrive come nome di header HTTP, nella stessa forma di principal_header, oppure si lascia vuoto. Un nome in qualsiasi altra forma viene rifiutato quando il file di configurazione viene caricato, nominando il file e la chiave, perché nessuna richiesta può portare un header del genere e a nessun chiamante verrebbe mai concesso uno scope. Il valore predefinito è vuoto, che non asserisce alcuno scope per nessun chiamante. Comunque si chiami, non viene letto alcun header diverso da questo e da principal_header. Pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]*$. Predefinito: "" |
Non sono consentite proprietà aggiuntive.
aggrega-config.mcp.health
Dove un supervisore chiede se questo processo è attivo e se è pronto a rispondere a una chiamata. I due controlli ricevono risposta su un indirizzo proprio e mai sull’indirizzo che listen nomina: ogni richiesta all’endpoint porta un bearer token, quindi una probe a cui si rispondesse lì darebbe a qualunque cosa possa raggiungere l’endpoint una lettura non autenticata del processo insieme a un modo gratuito per farlo lavorare. L’endpoint risponde a /healthz e /readyz con lo stesso 404 che dà a ogni percorso che non serve, con un token come senza.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
listen | string | no | Indirizzo su cui ricevono risposta i controlli di attività e di prontezza, nelle stesse due forme che accetta listen: host:port, oppure unix: seguito da un percorso del filesystem. Il valore predefinito è vuoto, quindi non viene avviato alcun secondo listener e nessuno dei due controlli riceve risposta da nessuna parte. Con un indirizzo impostato, GET /healthz riceve risposta 200 dal momento in cui il processo è in esecuzione, e GET /readyz riceve risposta 503 finché il workspace non è stato risolto e l’endpoint non ha eseguito il bind, e 200 da quel momento in poi — che è la distinzione di cui ha bisogno un supervisore, poiché un processo attivo non è ancora un processo in grado di rispondere a una chiamata. Ogni risposta è un codice di stato con corpo vuoto, non viene chiesto alcun token e non viene letto alcun header; qualsiasi altro percorso su questo indirizzo è 404, e qualsiasi altro metodo su questi due è 405. A differenza di listen, questo indirizzo non è limitato al loopback o a un socket Unix e nessun indirizzo viene rifiutato per esso: puntalo su uno di questi, che è lo scopo per cui esiste, e tieni presente che qualunque cosa possa raggiungere l’indirizzo che scegli può leggere quelle due risposte. Predefinito: "" |
Non sono consentite proprietà aggiuntive.
Definizioni
ReleaseCatalogConfig
Le directory di catalogo proprie di una Release: le stesse due chiavi che porta il blocco workspace, con ambito limitato a quella Release.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
catalog_dirs | string[] | no | Directory di catalogo da cui questa Release legge le entità locali al posto del catalog_dirs del workspace, ciascuna risolta in modo relativo al file che la dichiara. Lo stesso stack di ricerca ordinato in cui vince il primo dell’elenco del workspace, con la directory catalog alla radice del workspace letta dopo di esso quando quella directory esiste e nessuna voce elencata la contiene già. Se la chiave è omessa, la Release mantiene l’elenco del workspace; se è scritta come [], non viene letto alcun catalogo locale. |
catalog_dirs_append | string[] | no | Directory di catalogo aggiunte dopo l’elenco di questa Release — il suo catalog_dirs dove la voce ne scrive uno, altrimenti quello del workspace — ciascuna risolta in modo relativo al file che la dichiara. Predefinito: [] |
Non sono consentite proprietà aggiuntive.
RegistryConfig
Impostazioni e policy di fiducia delle firme con ambito limitato a un singolo host di registry OCI.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
host | string | sì | L’host del registry a cui si applicano queste impostazioni (ad es. hub.aggrega.ai). Viene confrontato con l’host del registry della destinazione del push/pull, quindi si scrive nella grafia in cui avviene quel confronto: un nome host in minuscolo che contiene un punto, localhost, un singolo nome seguito da una porta (registry:5000), un indirizzo IPv4 o un indirizzo IPv6 tra parentesi quadre, ciascuno con un :port opzionale — senza schema, percorso, credenziali, spazi o lettere maiuscole. La porta 443 su un host raggiunto tramite HTTPS è la porta predefinita di quell’host, e scriverla viene rifiutato quando la configurazione viene caricata, nominando l’host da scrivere senza di essa, perché una voce scritta in quel modo non sarebbe mai quella trovata; localhost e gli altri indirizzi di loopback vengono raggiunti tramite HTTP semplice, quindi lì 443 è una porta ordinaria e viene mantenuta. aggrega registry add e aggrega config init --registry indicizzano la voce sotto l’host nominato dal loro argomento e rifiutano un host non scritto in questo modo. L’host viene giudicato solo in base alla sua grafia: non viene verificato se il nome si risolve, né se lì risponde un registry. Pattern: ^(?:(?:(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?|localhost|(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:\.(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}|\[(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:|(?:[0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}|(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}|(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}|(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}|[0-9a-f]{1,4}:(?::[0-9a-f]{1,4}){1,6}|:(?:(?::[0-9a-f]{1,4}){1,7}|:))\])(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?|[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?:(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))$. |
name | string | no | Alias descrittivo opzionale per questo registry. L’host è l’identità; name è un selettore di comodo che si risolve nell’host di questa voce ovunque venga nominato un registry (ad esempio --registry, o default_registry). Un alias deve essere univoco tra le voci. |
trusted_identities | TrustedIdentity[] | no | Insieme OR di identità di firma keyless accettate per gli artefatti recuperati tramite pull da questo registry. Una firma viene verificata quando il suo certificato corrisponde a una qualsiasi delle voci. Usato dal percorso di verifica keyless. Predefinito: [] |
trusted_deprecation_identities | TrustedIdentity[] | no | Insieme OR di identità keyless accettate in aggiunta per firmare un marcatore di deprecazione retroattivo per un artefatto recuperato tramite pull da questo registry. Un marcatore di deprecazione viene rispettato quando la sua firma corrisponde al firmatario dell’artefatto originale OR a una qualsiasi voce di qui — così il proprietario di un registry o un team di sicurezza può ritirare un artefatto che l’editore originale non è più in grado di raggiungere, senza che gli si debba affidare la firma degli artefatti stessi. Usato solo dal percorso di rilevamento delle deprecazioni; non amplia mai l’insieme di fiducia per le firme degli artefatti. Predefinito: [] |
public_key | string | no | Chiave pubblica fissata, compatibile con cosign, per un registry in modalità con chiave, scritta inline come blocco PEM: il testo da una riga -----BEGIN PUBLIC KEY----- (o -----BEGIN RSA PUBLIC KEY-----) alla corrispondente riga -----END, così come aggrega registry add --key la copia da un file di chiave. Quando è impostata, le firme di questo registry vengono verificate offline rispetto a questa chiave anziché rispetto a identità keyless. Un valore che non contiene alcuna riga -----BEGIN … PUBLIC KEY----- viene rifiutato quando il file di configurazione viene caricato, nominando il file e la voce, e lo stesso vale per una chiave privata incollata qui per errore. La riga può trovarsi in qualsiasi punto del valore, perché la chiave viene letta dal blocco PEM che il valore contiene e qualsiasi testo prima di quel blocco viene ignorato. Qui viene controllata solo quella riga: se il blocco contiene una chiave decodificabile si scopre quando una firma di questo registry viene verificata rispetto a essa. Il valore è dichiarato sensibile (x-aggrega-sensitive), quindi un valore rifiutato — soprattutto una chiave privata scelta per errore — non viene mai citato: il rifiuto nomina il file, la voce e il vincolo che il valore non ha rispettato — il pattern qui sopra, o il tipo string — e mostra <redacted> dove sarebbe il valore. Una chiave pubblica che si carica viene letta e mostrata così come è scritta. Pattern: -----BEGIN [A-Z ]*PUBLIC KEY-----. |
trusted_root | string | no | Percorso opzionale di un bundle della radice di fiducia Sigstore fissato, per la verifica keyless in ambienti isolati dalla rete. Quando è impostato, l’ancora di fiducia keyless viene caricata da questo file senza rete; quando è vuoto, la radice di fiducia public-good viene recuperata e messa in cache. |
advisory | booleana | no | Quando è true, un errore di verifica della firma per questo registry viene declassato ad avviso anziché arrestare il pull. La verifica viene comunque eseguita e l’errore viene riportato; il pull prosegue. Il valore predefinito è false. Predefinito: false |
skip_signature_verification | booleana | no | Rinuncia di emergenza (break-glass) per host alla verifica delle firme — lo stesso interruttore skip_signature_verification di quello globale, con ambito limitato a questo host dalla sua collocazione. Non scavalca la policy signing.required di primo livello: una firma richiesta dall’organizzazione viene comunque verificata su questo host indipendentemente da questo interruttore; solo l’interruttore globale può disattivarla. Impostarlo insieme a un signing.required per registry sullo stesso host è consentito, e combina una firma richiesta al push con la verifica saltata al pull: sul lato della verifica prevale il salto, poiché una posizione che richiede la firma definita per host (a differenza di quella di primo livello) non è immune al salto per host. Il valore predefinito è false. Predefinito: false |
signing | SigningConfig | no | Il blocco di firma di questo registry: gli URL dei servizi keyless, un percorso opzionale della chiave per la firma con chiave e la posizione di fiducia per host. I campi degli endpoint sovrascrivono il blocco signing globale per i push verso questo host; un flag della CLI li sovrascrive entrambi. required e kinds si leggono dalla collocazione — sotto una voce di registry limitano l’unica posizione di fiducia a questo host (pubblicare un artefatto non firmato che rientra nell’ambito viene rifiutato, e consumarne uno non firmato viene rifiutato), lo stesso concetto che il blocco signing di primo livello porta per tutti i registry. |
Non sono consentite proprietà aggiuntive.
SigningConfig
Un blocco di firma: gli URL dei servizi keyless, un riferimento opzionale a un file di chiave per la firma con chiave e la posizione di fiducia (required e kinds). Collocato al primo livello si applica a tutti i registry; collocato sotto una voce di registries[] si applica a quell’host — ogni campo ricava il proprio ambito dalla collocazione. required è un’unica posizione di fiducia che copre entrambe le direzioni (un push non firmato che rientra nell’ambito viene rifiutato e un pull non firmato che rientra nell’ambito viene rifiutato). Sicurezza: non contiene materiale segreto — il token di identità OIDC non è mai un campo di configurazione (è di breve durata e viene fornito a runtime), e key_path è il percorso di un file di chiave, mai byte di chiave inline. Questo rispecchia l’asimmetria del lato della verifica: lì è consentita una public_key inline, ma il lato della firma porta solo il percorso di una chiave. Un server aggrega mcp raggiunto tramite HTTP non consulta alcun key_path in nessuna delle due collocazioni, quindi la firma con chiave non è raggiungibile tramite un listener di questo tipo: una chiamata a cui risponde firma solo con un token di identità che quella chiamata porta con sé.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
fulcio_url | string | no | URL dell’autorità di certificazione Fulcio per la firma keyless. Se non è impostato, viene usata l’istanza public-good di Fulcio. Si scrive come URL https assoluto: https://, un host e facoltativamente una porta e un percorso, senza spazi — ad esempio https://fulcio.sigstore.dev. Un valore di qualsiasi altra forma, come uno senza schema (fulcio.example.com) o uno che inizia con http://, viene rifiutato quando il file di configurazione viene caricato, nominando il file e la chiave. Il file viene controllato prima che qualsiasi altra cosa venga applicata sopra di esso, quindi lo stesso endpoint fornito da AGGREGA_SIGNING_FULCIO_URL, dal flag --fulcio-url o in una richiesta di pubblicazione da un editor o da un assistente non è tenuto a questa forma. Pattern: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
rekor_url | string | no | URL del transparency log di Rekor per la firma keyless. Se non è impostato, viene usata l’istanza public-good di Rekor. Si scrive come URL https assoluto: https://, un host e facoltativamente una porta e un percorso, senza spazi — ad esempio https://rekor.sigstore.dev. Un valore di qualsiasi altra forma, come uno senza schema (rekor.example.com) o uno che inizia con http://, viene rifiutato quando il file di configurazione viene caricato, nominando il file e la chiave. Il file viene controllato prima che qualsiasi altra cosa venga applicata sopra di esso, quindi lo stesso endpoint fornito da AGGREGA_SIGNING_REKOR_URL, dal flag --rekor-url o in una richiesta di pubblicazione da un editor o da un assistente non è tenuto a questa forma. Pattern: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
timestamp_url | string | no | URL dell’autorità di timestamp RFC3161 per la firma keyless. Non ha un valore predefinito: se non è impostato, non viene contattata alcuna autorità di timestamp, e l’ora attendibile di una firma keyless proviene dalla sua voce nel transparency log. Si scrive come URL https assoluto: https://, un host e facoltativamente una porta e un percorso, senza spazi — ad esempio https://tsa.example.com/api/v1/timestamp. Un valore di qualsiasi altra forma, come uno senza schema (tsa.example.com) o uno che inizia con http://, viene rifiutato quando il file di configurazione viene caricato, nominando il file e la chiave. Il file viene controllato prima che qualsiasi altra cosa venga applicata sopra di esso, quindi lo stesso endpoint fornito da AGGREGA_SIGNING_TIMESTAMP_URL, dal flag --timestamp-url o in una richiesta di pubblicazione da un editor o da un assistente non è tenuto a questa forma. Pattern: ^https://[^\s/?#]+(?:[/?#]\S*)?$. |
key_path | string | no | Percorso di un file PEM con una propria chiave privata ECDSA P-256 per la firma con chiave offline. Un percorso di un file, mai materiale di chiave inline. Se non è impostato, viene usato il percorso keyless. Un server aggrega mcp raggiunto tramite HTTP non consulta mai questa chiave, ovunque sia impostata — nel blocco signing di primo livello, in quello di una voce di registry o tramite AGGREGA_SIGNING_KEY_PATH: una chiamata a cui un listener di questo tipo risponde firma solo con un token di identità che la chiamata stessa porta con sé, oppure viene rifiutata. Un server raggiunto tramite lo standard input e lo standard output firma con essa come fa un terminale. |
required | booleana | no | L’unica posizione di fiducia per l’ambito di questo blocco: quando è true, pubblicare un tipo di artefatto che rientra nell’ambito richiede una firma (un push non firmato che rientra nell’ambito viene rifiutato), e consumarne uno richiede una firma (un pull non firmato che rientra nell’ambito viene rifiutato). L’ambito è dato dalla collocazione — sul blocco signing di primo livello copre ogni registry; sotto il blocco signing di una voce di registries[] copre quell’unico host. Un nome, un compito, entrambi gli ambiti. La policy di primo livello si compone in modo monotono lungo la cascata delle configurazioni — qualsiasi livello che la imposta a true la rende effettivamente true, e nessun livello di precedenza inferiore può disattivarla di nuovo — quindi non può essere rimossa con una normale modifica della configurazione. Il valore predefinito è false. Predefinito: false |
kinds | string[] | no | Limita required a tipi di artefatto specifici. Un elenco vuoto o una singola voce all significa ogni tipo firmabile; altrimenti la posizione si applica esattamente ai tipi elencati, corrispondenti al valore kind: dell’entità (ad es. Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate, Plugin). Sul blocco signing di primo livello si compone come un’unione lungo la cascata — un livello può allargare l’ambito ma mai restringerlo. L’ambito è dato dalla collocazione, come per required. Predefinito: [] |
Non sono consentite proprietà aggiuntive.
TrustedIdentity
Un’identità di firma keyless accettabile: un soggetto del certificato (l’identità OIDC) associato all’emittente OIDC che l’ha garantita.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
identity | string | no | Nome alternativo del soggetto esatto del certificato — l’identità OIDC incorporata nel certificato di firma di breve durata (ad es. l’email di un maintainer o l’URI di un workflow di CI). |
identity_regexp | string | no | Espressione regolare confrontata con il soggetto del certificato, usata al posto di un identity esatto (ad es. per accettare qualsiasi workflow di un’organizzazione). |
issuer | string | sì | URL dell’emittente OIDC che ha emesso il token di identità (ad es. https://accounts.google.com o https://token.actions.githubusercontent.com). |
Non sono consentite proprietà aggiuntive.
PluginRef
Riferimento a un plugin Wasm associato a un socket di cui l’associazione può nominare la funzione di ingresso — gli elenchi governance e linter. I socket il cui punto di ingresso è fisso usano invece FixedEntryPluginRef, che porta questi stessi campi senza function. uri e capability insieme selezionano il plugin: solo uri è un’associazione diretta (il plugin con quell’identità viene associato così com’è — la via dei socket trasversali, poiché i loro plugin non dichiarano capacità servite); solo capability risolve il plugin che serve quella capacità (il nome semplice della capacità che una Recipe lega tramite spec.capability, ad es. helm); entrambi insieme disambiguano — capability nomina cosa risolvere e uri seleziona il plugin di quale editore la serve, tramite l’identità semplice di quel plugin, in un catalogo federato in cui più di un plugin serve la capacità. function sostituisce la funzione di ingresso predefinita del socket; quando è omesso, si applica il valore predefinito documentato del socket — su una voce governance quel valore predefinito deriva da role. role nomina il ruolo di associazione governance ed è letto solo su una voce governance. with porta input opzionali al momento dell’associazione che il plugin legge.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
uri | string | no | Identificatore del Plugin: l’identità semplice di un’entità Plugin — il percorso <pluginType>/<name>, ad es. governance/redact o provider/helm — un percorso del filesystem locale o un alias di registry. Opzionale: una voce può invece selezionare il plugin tramite capability. Un :version finale opzionale fissa la versione nelle stesse tre forme di qualsiasi fissaggio di versione (semplice, esatta :1.0.0, o intervallo compatibile con la major :^1.0.0). |
role | string (enum) | no | Il ruolo della pipeline a cui è legata un’associazione governance, letto solo su una voce governance: annotation-transform inietta annotazioni sui componenti risolti prima dell’espansione delle annotazioni, così le iniezioni legate diventano associazioni di Feature; label-transform assegna automaticamente etichette ai nodi del grafo di topologia durante la costruzione della topologia; ir-verdict emette un verdetto di accettazione o rifiuto sul grafo IR durante l’analisi statica; render-verdict emette un verdetto sugli artefatti renderizzati durante il rendering. È il ruolo — non il tipo dichiarato del plugin — a stabilire ciò che il plugin può emettere: l’output di un ruolo di verdetto può essere letto solo come un verdetto, mai applicato come una modifica; l’output di un ruolo di trasformazione è confinato dall’host al proprio aspetto (annotazioni o etichette). Seleziona inoltre la funzione di ingresso predefinita (annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). Valori consentiti: "annotation-transform", "label-transform", "ir-verdict", "render-verdict" |
capability | string | no | La capacità del provider per cui questa voce seleziona un plugin — il nome semplice della capacità che una Recipe lega tramite spec.capability (ad es. helm, compose). Opzionale: una voce può invece associare un plugin direttamente tramite uri. I legami del provider la usano per selezionare il plugin di quale editore serve una capacità in un catalogo federato; i socket trasversali la lasciano vuota e associano tramite uri. |
function | string | no | Override opzionale della funzione di ingresso predefinita del socket. Quando è omesso, si applica il valore predefinito documentato del socket (governance annotation-transform → transform_annotations, governance label-transform → mutate, governance ir-verdict → verdict_ir, governance render-verdict → verdict_render, linter → lint_rules). L’override può nominare qualsiasi esportazione che il plugin dichiara, e l’esportazione che nomina deve restituire la forma di output che quel socket legge: la build si arresta quando quell’output porta un campo di primo livello che la forma non dichiara, nominando l’esportazione chiamata e il campo inatteso. Il controllo legge quali nomi di campo di primo livello sono presenti, non quali sono assenti né cosa è annidato al di sotto, quindi non è una validazione completa dell’output. |
with | PluginRefWith | no | Input opzionali al momento dell’associazione che il plugin legge. Entrambi i membri sono opzionali e agnostici rispetto al socket, quindi qualsiasi socket può riusare questa superficie. |
Non sono consentite proprietà aggiuntive.
FixedEntryPluginRef
Riferimento a un plugin Wasm associato a un socket il cui punto di ingresso è fisso anziché nominato dall’associazione — l’elenco importer e i legami providers. Porta gli stessi campi di PluginRef senza function: il socket importer chiama l’unica funzione di ingresso che il contratto del suo socket nomina, e un provider guida un insieme fisso di esportazioni indicizzate per fase anziché un unico punto di ingresso selezionabile, quindi in nessuno dei due elenchi c’è un punto di ingresso che function possa nominare e lì la chiave non è accettata. uri e capability insieme selezionano il plugin: solo uri è un’associazione diretta (il plugin con quell’identità viene associato così com’è — la via del socket importer, poiché i suoi plugin non dichiarano capacità servite); solo capability risolve il plugin che serve quella capacità (il nome semplice della capacità che una Recipe lega tramite spec.capability, ad es. helm); entrambi insieme disambiguano — capability nomina cosa risolvere e uri seleziona il plugin di quale editore la serve, tramite l’identità semplice di quel plugin, in un catalogo federato in cui più di un plugin serve la capacità. role è accettato qui ma non viene letto in nessuno dei due elenchi serviti da questa forma: il ruolo di associazione governance che nomina viene letto su una voce governance, che usa PluginRef, quindi un ruolo impostato su una di queste voci non ha effetto. with porta input opzionali al momento dell’associazione che il plugin legge; un legame del provider prende invece la propria configurazione di rendering dalla Recipe, quindi with: su un legame viene rifiutato al caricamento.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
uri | string | no | Identificatore del Plugin: l’identità semplice di un’entità Plugin — il percorso <pluginType>/<name>, ad es. governance/redact o provider/helm — un percorso del filesystem locale o un alias di registry. Opzionale: una voce può invece selezionare il plugin tramite capability. Un :version finale opzionale fissa la versione nelle stesse tre forme di qualsiasi fissaggio di versione (semplice, esatta :1.0.0, o intervallo compatibile con la major :^1.0.0). |
role | string (enum) | no | Il ruolo di associazione governance. Nessuno dei due elenchi che usano questa forma lo legge — il ruolo viene letto su una voce governance, e quelle voci usano PluginRef — quindi un ruolo impostato qui viene accettato e non ha effetto. I valori ammessi sono i quattro ruoli governance, e ciò che ciascuno significa è descritto in PluginRef. Valori consentiti: "annotation-transform", "label-transform", "ir-verdict", "render-verdict" |
capability | string | no | La capacità del provider per cui questa voce seleziona un plugin — il nome semplice della capacità che una Recipe lega tramite spec.capability (ad es. helm, compose). Opzionale: una voce può invece associare un plugin direttamente tramite uri. I legami del provider la usano per selezionare il plugin di quale editore serve una capacità in un catalogo federato; i socket trasversali la lasciano vuota e associano tramite uri. |
with | PluginRefWith | no | Input opzionali al momento dell’associazione che il plugin legge. Entrambi i membri sono opzionali e agnostici rispetto al socket, quindi qualsiasi socket può riusare questa superficie. |
Non sono consentite proprietà aggiuntive.
CLIPluginRef
Un plugin di estensione della CLI fissato, installato come comando aggrega di primo livello: il riferimento all’artefatto risolto e fissato a una versione che il comando risolve ed esegue, e il digest del contenuto dei byte del guest in cui quel riferimento si è risolto al momento dell’installazione. Insieme fissano esattamente quali byte esegue il comando; il digest indicizza inoltre la cache di describe che fornisce i nomi e l’aiuto del comando senza caricare il guest.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
uri | string | sì | Il riferimento all’artefatto risolto e fissato a una versione che il comando risolve ed esegue, ad es. oci://hub.aggrega.ai/plugin/cli/<name>:1.2.0, fissato all’installazione. |
digest | string | sì | Il digest del contenuto dei byte .wasm del guest in cui il riferimento si è risolto all’installazione, scritto come sha256: seguito dalle 64 cifre esadecimali minuscole dello SHA-256 dei byte — la grafia che registra aggrega plugin add cli, e la grafia in cui vengono confrontati i byte risolti. Un digest in qualsiasi altra grafia — esadecimale semplice senza il prefisso sha256:, lettere maiuscole o una lunghezza diversa — non potrebbe mai essergli uguale, quindi viene rifiutato quando il file di configurazione viene caricato, nominando il file e la voce. Fissa i byte esatti che il comando esegue — una risoluzione successiva i cui byte producono un hash diverso arresta il comando — ed è la chiave nella cache di describe che produce l’aiuto del comando senza caricare il guest. Pattern: ^sha256:[0-9a-f]{64}$. |
Non sono consentite proprietà aggiuntive.
PluginRefWith
Input opzionali al momento dell’associazione che un plugin legge. Entrambi i membri sono opzionali e la superficie è generica, quindi qualsiasi socket può riusarla.
| Proprietà | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
sources | string[] | no | Percorsi di file di definizione che l’host legge in fase di compilazione e passa al plugin. Ogni voce è un percorso del filesystem risolto rispetto alla directory del file di configurazione che la dichiara. |
settings | object | no | Oggetto di impostazioni in forma libera passato al plugin così com’è. L’host non interpreta la sua forma; è il plugin a definire le chiavi che legge. |
Non sono consentite proprietà aggiuntive.