Configurazione
Da dove aggrega legge le proprie impostazioni, e in quale file mettere un’impostazione.
Il caso semplice
Due file, e alla maggior parte dei progetti non serve altro.
Un file nel tuo progetto, chiamato .aggrega-config.yaml, che si trova nella radice del progetto. Contiene il modo in cui questo progetto esegue la build: quali directory contengono contenuto di catalogo incluso nel progetto, quali plugin eseguono il rendering di quali target, quali regole di lint sono allentate, dove va la cache locale. Viene sottoposto a commit, così un collega che clona il progetto ne esegue la build allo stesso modo.
Il suo blocco workspace: è ciò che contrassegna la directory come radice del progetto:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: - ./catalogauto_pull: trueIl blocco contiene solo le directory di catalogo che definiscono la radice; ogni altra impostazione si trova al livello superiore accanto a esso. Un progetto che non include contenuto di catalogo scrive comunque il blocco, vuoto — workspace: {} — perché è la presenza del blocco a fare da contrassegno.
Un file globale sulla tua macchina, in ~/.config/aggrega/config.yaml — su Windows, in aggrega\config.yaml all’interno della directory indicata dalla variabile d’ambiente APPDATA. Ogni workspace su quella macchina si risolve attraverso di esso, e contiene impostazioni che appartengono alla macchina anziché a un singolo progetto — i registry da cui esegui il pull e la policy di fiducia delle firme per ciascuno, quanto può crescere lo store dei moduli compilati, e qualsiasi plugin di estensione dei comandi che hai installato. Queste restano le stesse ovunque tu stia lavorando, quindi lo scopo è dichiararle una volta sola. Viene caricato automaticamente quando è presente, e non si rompe nulla quando non c’è.
registries: - host: hub.aggrega.ai signing: required: trueaggrega config init scrive quel file globale per te, registrando un registry insieme alla policy di fiducia delle firme che esso pubblicizza, e indica dove si trova il file sulla tua macchina e dove sono conservate le cache a livello di macchina. aggrega config show stampa ciò che si applica in questo momento, e aggrega config show --origin indica quale file — o quale variabile d’ambiente — ha deciso ciascuna impostazione.
I segreti non sono configurazione. Una password di registry e un token di identità per la firma non sono mai campi in nessuno dei due file; vengono forniti tramite variabile d’ambiente o flag nel momento in cui servono. Vedi environment-variables.md.
Da dove vengono lette le entità locali
Un progetto che mantiene un proprio contenuto di catalogo — un Component, una Feature, una Recipe, uno dei tipi di libreria — ha due modi per dire dove si trova quel contenuto, e il primo non richiede alcuna configurazione.
Una directory catalog nella radice del progetto viene letta che qualcosa la nomini o meno. Metti un’entità sotto <project>/catalog/ e ogni comando che carica un catalogo la legge, anche in un progetto il cui blocco workspace: è vuoto. Una directory di catalogo viene letta ricorsivamente, quindi come disponi le sottodirectory al suo interno spetta a te.
Vengono lette anche le directory elencate sotto workspace.catalog_dirs, e vengono lette per prime. L’elenco è uno stack di ricerca ordinato: la prima directory che dichiara un’identità la possiede, e la stessa identità in una directory successiva viene oscurata. catalog viene letta dopo tutto ciò che è elencato — a meno che una directory elencata non la contenga già, nel qual caso viene letta come parte di quella directory — quindi elencare una directory si aggiunge a ciò che avevi anziché sostituirlo. Un --catalog <dir> ripetibile sulla riga di comando viene letto prima di entrambi, e un percorso relativo fornito lì si risolve rispetto alla directory da cui hai eseguito il comando, poiché nessun file di configurazione lo ha dichiarato. Una directory nominata più di una volta — sulla riga di comando e nell’elenco, o due volte nell’elenco — viene letta una volta, nel punto in cui è stata nominata per la prima volta, così nulla al suo interno viene segnalato come oscurato da sé stesso: un oscuramento è sempre due file diversi che dichiarano una stessa identità. Due grafie di una stessa directory, un percorso verso di essa attraverso un link e — su un file system che ignora le maiuscole — una grafia con maiuscole diverse nominano tutti quell’unica directory. Una directory all’interno di un’altra directory elencata viene comunque letta come voce a sé. Un progetto che mantiene una variante di catalogo per Release può invece dare a ciascuna Release un proprio elenco — vedi Dare a una Release le proprie directory di catalogo.
Elencare una directory è il modo in cui un progetto legge entità mantenute al di fuori di esso. Una directory elencata può trovarsi ovunque — un checkout affiancato, una directory condivisa con altri progetti — e viene letta dove si trova, anche quando è essa stessa un link simbolico. Nient’altro arriva così lontano: un link all’interno del progetto che porta altrove non viene seguito, e un documento che nomina un file esterno al progetto tramite un percorso viene rifiutato, quindi un’entità mantenuta altrove si raggiunge elencando la directory che la contiene e nominando l’entità con il suo nome. Una directory elencata esterna al progetto è una radice a sé, quindi nemmeno un link sotto di essa che ne esce viene letto. Il confine del workspace enuncia la regola completa.
Una directory elencata deve essere una directory. Un percorso elencato in cui non esiste nulla, o in cui si trova un file o un link che non porta da nessuna parte, viene rifiutato prima che venga letto o scritto qualsiasi cosa da ogni comando che legge il catalogo — un pull, una build, una validazione, un’ispezione, un lint, e le stesse operazioni avviate dall’editor tramite aggrega serve o da un assistente tramite aggrega mcp — così una build non viene mai eseguita su meno cataloghi di quelli che hai elencato. Il rifiuto nomina la voce così come è scritta, il percorso in cui si è risolta, il file di configurazione e la riga che la elenca, e l’elenco in cui si trova:
<project>/.aggrega-config.yaml:4: the `workspace.catalog_dirs` entry "../shared/aggrega-catalog" names <directory>, which does not exist; create that directory, or remove the entry: workspace configuration is invalidCrea la directory, oppure rimuovi la voce: una copia di un progetto presa senza un checkout affiancato che esso elenca rimuove quella voce, e risolve da un registry ciò che il checkout avrebbe fornito. Lo stesso vale per una directory elencata dalla voce propria di una Release, per una aggiunta da un file di configurazione di proprietà della tua pipeline o dal file globale, e per una portata da AGGREGA_CATALOG_DIRS, che il rifiuto nomina al posto di un file. La configurazione stessa viene comunque caricata, quindi un comando che non legge alcun catalogo viene comunque eseguito. Una directory --catalog che non esiste è stata digitata per un solo comando, e aggrega build la rifiuta, nominando la directory. Una directory elencata che esiste ma non può essere letta viene rifiutata dai comandi che caricano l’intero catalogo, che la nominano.
Scrivere l’elenco vuoto dice che questo progetto non ha alcun catalogo locale, ed è l’unica grafia che impedisce anche la lettura di catalog:
# <project>/.aggrega-config.yamlworkspace: catalog_dirs: []Omettere la chiave è un’affermazione diversa: un elenco omesso è il caso ordinario, e catalog viene comunque letta.
Una build, un pull, una validazione o un aggrega inspect che non trova alcuna entità con un nome che hai usato dice da dove questo progetto legge le entità locali e cosa cambiare perché quella che hai nominato venga letta. Non dice nulla del genere dove hai scritto l’elenco vuoto — non leggere alcun catalogo locale è ciò che hai dichiarato lì, e suggerire di cambiarlo significherebbe contraddirti. Né lo dice dove il documento che dichiara quel nome è stato letto e rifiutato: quel documento si trova già dove il catalogo legge, quindi il rapporto nomina invece ciò che il documento viola, la riga e il vincolo, e spostarlo non risolverebbe nulla. Un documento così malformato che il nome che dichiara non può nemmeno essere letto non può essere associato al nome che hai usato, quindi l’indicazione viene comunque data — e dove quel documento dichiara un apiVersion di Aggrega, una build, un pull o una validazione di una Release lo nomina accanto all’indicazione, con il motivo indicato dal parser stesso, poiché potrebbe essere il file da aprire. Un errore che ha trovato l’entità e non ha potuto accettarla — un registry che ora serve byte diversi sotto una versione che il tuo lockfile fissa, un file che l’entità porta con sé e che non può essere letto — non è nemmeno un’entità mancante, e riporta solo il proprio rimedio.
Se un pull o un push fissa un’entità
Una Recipe o una FeatureRecipe porta i pin per gli input che legge — un source: remoto scritto per intero, un file che una voce artifacts importa, i file di un source: accanto a essa — nell’entity.lock accanto a essa, e registrarli è il passo dell’autore dell’entità, aggrega pin. Per impostazione predefinita né pull né push esegue quel passo: un pull si arresta su un’entità che il suo lock non fissa, e un push si rifiuta di pubblicarla. Due chiavi, una per comando, rendono la sua esecuzione il comportamento predefinito di quel comando:
# <project>/.aggrega-config.yamlworkspace: {}pin_sources_at_pull: truepin_sources_at_push: trueOgni chiave governa il proprio comando e nient’altro, e il --pin-sources di ciascun comando sovrascrive la sua chiave in entrambe le direzioni — --pin-sources=false disattiva il passo per un’esecuzione in un progetto configurato per fissare. Una build che riempie il proprio lockfile è un pull e segue pin_sources_at_pull. Queste chiavi appartengono al file del progetto anziché a quello globale: se i pull di un progetto registrano i pin è la policy di quel progetto, e un collega che lo clona dovrebbe ottenere la stessa risposta. pin_sources_at_pull è anche il modo in cui un progetto che consuma il catalogo non fissato di qualcun altro registra quei pin una volta sola anziché arrestarsi a ogni pull.
Quale plugin esegue il rendering di una capability
Una Recipe nomina la capability attraverso cui esegue il rendering — capability: helm — e un plugin che serve quella capability ne esegue il rendering. Dove esattamente un plugin serve una capability, non serve configurare nulla. Dove più di uno la serve, una voce plugins.providers dice quale, tramite l’identità del plugin:
# <project>/.aggrega-config.yamlworkspace: {}plugins: providers: - capability: helm uri: provider/helmUn pull risolve la voce e registra il plugin che ha scelto nel lockfile della Release, e una build esegue il rendering attraverso ciò che il lockfile registra, quindi una modifica qui ha effetto al pull successivo.
Il campo uri nomina il plugin tramite la sua identità, provider/<name>, mai tramite il luogo in cui è pubblicato. aggrega plugin add provider <query> --capability <capability> scrive la voce in questa forma, senza versione: la voce seleziona quale plugin serve la capacità, la versione è quella che la Recipe fissa oppure la più alta disponibile, e il lockfile registra quella scelta dal pull. Un plugin che il compilatore porta al proprio interno viene servito alla versione del compilatore stesso, quindi una versione scritta su una voce per uno di questi si risolve solo quando è quella versione. Una voce il cui uri è una posizione di registry — oci://hub.aggrega.ai/plugin/provider/helm — non nomina l’identità di alcun plugin, e viene rifiutata quando il file viene caricato, nominando la voce e la forma da scrivere.
Le voci sono scritte una volta per l’intero progetto, mentre una build riguarda una sola Release, quindi una voce per una capability che questa Release non richiede mai è lecita — un’altra Release del progetto la legge — e non viene segnalata in alcun modo. Ciò che ogni build e ogni aggrega validate --release controllano è ogni voce, che una Recipe ne richieda o meno la capability, in base a ciò che la voce nomina:
- Una voce che nomina un plugin il cui plugin non serve la sua capability arresta la build e fa fallire la validazione. Un pull risolve ogni voce che nomina un plugin, e rifiuta quella che non riesce a risolvere, quindi una volta che una voce è passata per un pull la build ne possiede il plugin e sa cosa serve; una voce che nomina un plugin che la build non possiede ancora viene giudicata una volta che un pull lo ha recuperato. Il messaggio nomina la voce, il plugin, ciò che quel plugin serve effettivamente, e una grafia a una modifica di distanza quando ce n’è una — la forma che assume un refuso come
hlemperhelm. - Una voce che nomina solo una capability non servita da alcun plugin letto dalla build è un avviso, e la build prosegue. Il plugin che la serve potrebbe essere letto solo da un’altra Release, che questa build non può vedere, e una voce che non nomina alcun plugin non seleziona nulla che la risoluzione della capability non selezionerebbe senza di essa.
Una capability qui non contiene mai i due punti, e una che li contiene viene rifiutata al caricamento del file. Il capability: di una Recipe viene letto come la capability fino agli ultimi due punti e un pin di versione dopo di essi, quindi una voce con chiave helm:1.0.0 non potrebbe mai essere trovata. Fissa invece la versione sul plugin — uri: provider/helm:1.0.0 — o nella Recipe.
Quale importer trasforma una sorgente in bozze
aggrega import passa una sorgente all’importer che pubblicizza il formato della sorgente — uno nel tuo catalogo o uno degli importer core del compilatore, import:langflow per un flusso Langflow. Dove esattamente un importer lo pubblicizza, non serve configurare nulla. Una voce plugins.importer collega un importer nominandolo nel suo uri, tramite la sua identità e versione, e gli passa ciò che porta sotto with:
# <project>/.aggrega-config.yamlworkspace: {}plugins: importer: - uri: importer/agent-flows:1.2.0 with: settings: target_namespace: paymentsaggrega plugin add importer scrive l’uri esattamente in quella forma. La versione è esatta — :1.2.0 — o un intervallo — :^1.2.0 per la versione più alta pari o superiore a essa all’interno della stessa major. Scrivi l’una o l’altro: in questo elenco un uri senza due punti viene letto come un percorso del filesystem, come descrive Dove punta un percorso relativo, e non nomina alcun importer.
Ciò che fa una voce dipende dal fatto che l’importer che nomina pubblicizzi o meno il formato richiesto da un’importazione:
- Lo pubblicizza: quell’importer è quello che viene eseguito, alla versione che l’
urinomina, per quanti altri importer del catalogo pubblicizzino anche il formato, e gli vengono passatiwith.sourcesewith.settingsdella voce. Una voce è il modo in cui un workspace il cui catalogo federa gli importer di due publisher per uno stesso formato dice quale dei due usa. - Non lo pubblicizza — nomina un importer di un altro formato, un plugin di un altro tipo, o nulla che il tuo catalogo contenga o che il compilatore porti con sé: la voce non ha alcun ruolo in quell’importazione. Non sceglie nulla, e il suo
withnon viene passato a nessun importer. Le impostazioni di una voce raggiungono solo l’importer che nomina, quindi un workspace che collega un importer per formato configura ciascuno senza che le impostazioni dell’uno raggiungano l’altro.
Dove più di un importer pubblicizza il formato e nessuno di essi è collegato singolarmente — nessuno lo è, oppure le voci ne nominano due — l’importazione viene rifiutata, nominando gli importer tra cui non è riuscita a scegliere. Una voce che nomina un importer che pubblicizza il formato, a una versione che nessuna sua versione nel catalogo soddisfa — una versione esatta che il catalogo non contiene, o un intervallo in cui non ricade nessuna delle sue versioni — viene anch’essa rifiutata, nominando la versione, anziché eseguire un’altra versione al suo posto; una versione che non è affatto una versione, come :latest, viene rifiutata come malformata. Un’entità Plugin di uno degli importer core del compilatore senza alcun modulo accanto nella sua cartella del catalogo non è candidata: alla versione propria del compilatore viene eseguito al suo posto l’importer core, e a qualsiasi altra versione l’entità resta candidata solo dove una voce nomina esattamente quella versione o nessun importer con quel nome che possa essere eseguito pubblicizza il formato, come descrive Quale viene eseguito accanto ai tuoi importatori.
Ogni importer viene collegato da una sola voce. Due voci che nominano uno stesso importer — la stessa identità, a una versione o a due — vengono rifiutate al caricamento della configurazione, qualunque comando la legga, nominando entrambe le voci e i file in cui sono state scritte. La regola si estende a ogni file che contribuisce all’elenco: una voce nel file globale, una nel file di un progetto, una sotto importer_append e una nel .aggrega-config-append-ci.yaml di una pipeline contano tutte, quindi spostare un importer a una nuova versione significa cambiare la versione sulla sua unica voce. aggrega plugin add importer fa esattamente questo quando l’elenco plugins.importer del file che scrive nomina già l’importer: sposta quella voce alla versione che ha risolto, mantenendo la posizione della voce e il suo with, anziché aggiungerne una seconda. Non legge nessun altro elenco, quindi un importer collegato sotto importer_append, o nel .aggrega-config-append-ci.yaml di una pipeline, viene collegato una seconda volta dal comando e la coppia viene rifiutata al caricamento della configurazione; cambia la versione su una voce del genere dove è scritta. Una voce il cui uri è un percorso del filesystem non nomina alcun importer e non viene confrontata, e gli elenchi plugins.governance e plugins.linter non sono soggetti alla regola: un plugin può esservi collegato più di una volta, ogni volta con il proprio with.
I parser attraverso cui legge un’importazione non richiedono alcuna voce. Un importer legge la propria sorgente — e un’importazione che non nomina alcun formato la riconosce — attraverso un parser per la sintassi della sorgente: quello che il tuo catalogo serve per quella sintassi e, per una sintassi per cui il tuo catalogo non serve alcun parser, quello che il compilatore stesso porta con sé, JSON tra questi. Così un workspace il cui catalogo non contiene alcun parser importa un flusso Langflow o Flowise senza nulla di configurato. Nessun elenco collega un parser: un parser che il tuo catalogo serve per una sintassi è quello usato, e due con nomi diversi che servono una stessa sintassi vengono rifiutati, come descrive A parse or import format is advertised by more than one plugin (Un formato di parsing o di importazione è pubblicizzato da più di un plugin).
Partire da zero
Un aggrega appena installato non ha nessuno dei due file, e questo è uno stato funzionante anziché guasto: ogni impostazione ricade sul proprio valore predefinito integrato e i comandi vengono eseguiti. Ciò che manca è un registry da cui eseguire il pull del contenuto di catalogo, insieme alla policy di fiducia che dice quali firme accettare — che è esattamente ciò che scrive aggrega config init.
Non devi saperlo in anticipo. Un comando che legge la propria configurazione e non trova alcun file da nessuna parte lo dice una volta, su standard error, e indica aggrega config init come il modo per crearne uno. È un consiglio anziché un errore: lo standard output non viene toccato, non ti viene chiesto nulla, e lo stato di uscita è quello che il comando avrebbe riportato comunque. Viene scritto solo quando lo standard error è un terminale, così ti raggiunge alla tastiera e non si accumula mai nel log di una pipeline. Una volta che uno dei due file esiste — quello del tuo progetto o quello globale — smette di comparire.
Per inizializzare il file globale con l’hub ufficiale e la policy di fiducia che quell’hub pubblicizza:
aggrega config initPassa --registry <host> per inizializzarne uno diverso, --workspace per scrivere la voce nel file di questo progetto anziché in quello globale, e --dry-run per vedere il contenuto che scriverebbe senza creare nulla. aggrega-config.md descrive il comando per intero.
Come si scrive un host di registry
Ogni registries[].host nomina un host di registry. Lo fa anche default_registry — facoltativamente seguito da un percorso di repository — a meno che non nomini invece una di quelle voci (vedi sotto). Un host si scrive come l’host stesso, nell’unica grafia sotto cui è conservata la policy di fiducia del registry:
- un nome host in minuscolo contenente un punto, come
registry.example.com; localhost, oppure un nome singolo seguito da una porta, comeregistry:5000;- un indirizzo IPv4 come
127.0.0.1, o un indirizzo IPv6 tra parentesi quadre come[::1];
ciascuno con un :port facoltativo, e nient’altro — nessuno schema, nessun percorso, nessuna credenziale, nessuno spazio e nessuna lettera maiuscola. Un nome singolo senza porta non è un host di registry, perché quella è la forma del primo segmento del nome di un’entità di catalogo — il core in core/web-api — e i due non devono mai essere scambiati l’uno per l’altro.
# <project>/.aggrega-config.yamlworkspace: {}default_registry: registry.example.comregistries: - host: registry.example.com signing: required: trueLa grafia fa parte della policy. Una voce registries si applica all’host che il suo host: nomina, e il requisito di firma integrato dell’hub ufficiale si applica a hub.aggrega.ai, quindi un host scritto in qualsiasi altro modo raggiungerebbe il registry giusto e mancherebbe la policy scritta per esso. Viene invece rifiutato al caricamento della configurazione, e il rifiuto nomina la grafia da scrivere: HUB.AGGREGA.AI e https://registry.example.com vengono rifiutati nominando hub.aggrega.ai e registry.example.com, e così anche registry.example.com/charts come registries[].host, che non porta alcun percorso. La porta 443 è la porta predefinita di un host raggiunto tramite HTTPS, quindi hub.aggrega.ai:443 viene rifiutato allo stesso modo, nominando hub.aggrega.ai. localhost e gli altri indirizzi di loopback vengono invece raggiunti tramite HTTP semplice, dove 443 è una porta ordinaria, quindi localhost:443 viene accettato così come è scritto. Un default_registry vuoto non nomina alcun registry predefinito.
default_registry può portare un percorso di repository. Molti registry conservano ogni repository sotto un proprietario o un progetto — ghcr.io/<owner>, <host>/<project> su Harbor — e un registry predefinito su uno di essi si scrive come l’host seguito da quel percorso:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: ghcr.io/acmeregistries: - host: ghcr.io signing: required: trueIl percorso è dove le cose vengono pubblicate e recuperate. Attraverso questo valore predefinito, aggrega push pubblica core/api-server versione 1.0.0 in ghcr.io/acme/component/core/api-server:1.0.0, e un pull che risolve core/api-server lo recupera dallo stesso posto, quindi una firma allegata al momento della pubblicazione viene trovata anche lì. Il percorso è un percorso di repository nella grammatica di distribuzione OCI: uno o più segmenti di lettere minuscole e cifre uniti da /, che possono essere separati all’interno di un segmento da ., _, __ o trattini, senza tag, digest o / finale.
Il percorso non fa mai parte del modo in cui ci si fida del registry. La voce registries la cui policy si applica, la credenziale che aggrega login memorizza, il requisito di firma e le identità fidate vengono tutti trovati in base al solo host, quindi la voce per ghcr.io sopra governa ghcr.io/acme e ogni altro percorso su quell’host, e nessuna grafia di un percorso può scavalcarla; lo stesso host: di una voce non porta alcun percorso. Un host scritto in un’altra grafia prima di un percorso viene rifiutato nominando la posizione da scrivere — GHCR.io/acme e https://ghcr.io/acme nominano ghcr.io/acme — e ciò che segue l’host, quando non è un percorso di repository, viene rifiutato nominando l’host che segue.
default_registry può invece nominare una voce. Scritto come il name: di una voce sotto registries, sta per l’host: di quella voce. La pubblicazione, il pull, la verifica delle firme e ogni impostazione di fiducia per registry usano allora quell’host, e nessun contenuto viene recuperato da un host scritto come il nome:
# <project>/.aggrega-config.yamlworkspace: {}default_registry: localregistries: - name: local host: 127.0.0.1:5000Un nome viene confrontato prima di una grafia di host, come fa il flag --registry, quindi un valore che è il name: di una voce sta per quella voce anche dove è scritto anche come un host. Un nome portato da due voci viene rifiutato come ambiguo, nominando entrambi gli host. La voce può trovarsi in uno qualsiasi dei due file — il default_registry di un progetto può nominare una voce dichiarata dal file globale — perché il nome viene letto una volta, rispetto alle voci in vigore dopo che ogni file e l’ambiente sono stati letti. Un valore che non è né il nome di una voce né un host di registry — da solo o seguito da un percorso di repository — viene rifiutato, e il rifiuto dice che l’una o l’altra cosa lo correggono. Anche un nome seguito da un percorso, come local/acme, viene rifiutato: un nome sta per l’host della sua voce e non per una posizione sotto di esso, quindi il rifiuto nomina invece le due grafie da scrivere — local, oppure l’host della voce seguito dal percorso, 127.0.0.1:5000/acme. Rimuovere una voce con aggrega registry remove lascia default_registry così come è scritto, quindi un valore predefinito che nominava la voce rimossa da quel momento non nomina nulla e viene rifiutato finché non viene riscritto.
Ogni livello è soggetto alla stessa grafia. Un valore viene rifiutato con le stesse parole sia che provenga da un file di configurazione, da AGGREGA_DEFAULT_REGISTRY, o dal flag --registry che nomina la destinazione di un aggrega push o di un aggrega push-artifact. Quel flag nomina un host, e la pubblicazione che dirige arriva a quell’host senza percorso di repository: un percorso appartiene a default_registry. Anche aggrega registry add e aggrega config init --registry vi sottopongono l’host che ricevono; accettano inoltre un riferimento al suo posto, e registrano la voce sotto l’host che il riferimento nomina. Un rifiuto proveniente da un file nomina il file e la chiave; uno proveniente dall’ambiente nomina la variabile. Lo schema enuncia la forma dell’host come pattern su registries[].host e non ne enuncia alcuna su default_registry, il cui valore può essere il nome di qualsiasi voce — quindi un editor che legge solo lo schema non segnala un valore predefinito digitato male, ed è il caricamento della configurazione a rifiutarlo.
Un host viene giudicato solo dalla sua grafia, e così anche un percorso. Se il nome si risolve, se un registry risponde lì, o se il percorso esiste su di esso, non viene verificato al caricamento della configurazione.
Cosa sovrascrive cosa
CLI flag > environment variable > configuration file > built-in defaultUn flag è il segnale più esplicito che esista e vince senza condizioni. Una variabile d’ambiente sovrascrive il file sottoposto a commit, ed è ciò che permette a una pipeline di cambiare un’impostazione senza modificare un file tracciato. Una variabile non impostata — o impostata su una stringa vuota — ricade sul livello sottostante anziché azzerare un valore configurato. Tra i due file, il file del tuo progetto vince su quello globale.
Un flag vince per essere stato digitato, non per il valore che porta, e per un’impostazione vero-o-falso questa è la differenza tra un livello superiore utilizzabile e nessuno. --offline attiva la modalità per un’esecuzione; --offline=false la disattiva per un’esecuzione dove un file sottoposto a commit o una variabile esportata l’ha attivata. Un livello che leggesse solo il valore non potrebbe distinguere «disattivato» da «non menzionato», quindi ogni comando sembrerebbe aver chiesto il valore predefinito del flag e non ci sarebbe alcun modo di revocare un’impostazione configurata.
Questo è l’intero modello per un singolo progetto su una singola macchina. Tutto ciò che segue esiste per i progetti che lo superano.
Oltre i due file
Questi meccanismi sono pensati per forme più grandi — un monorepo di progetti correlati, una pipeline che contribuisce impostazioni proprie, un catalogo condiviso che diversi progetti estendono. Ricorri a uno di essi quando hai il problema che risolve.
Più di un file di configurazione all’interno di un progetto
Ogni .aggrega-config.yaml dalla radice del progetto fino alla directory in cui viene eseguito il comando contribuisce, e un file più vicino sovrascrive uno più lontano. Così un sottoprogetto può avere un proprio file che adatta ciò che la radice ha dichiarato, senza ripeterlo.
Solo un file che contiene un blocco workspace: contrassegna una radice. Un file senza di esso contribuisce comunque con le proprie impostazioni — semplicemente non trasforma la propria directory in una radice di progetto, ed è ciò che impedisce al file di impostazioni di un sottoprogetto di ridefinire dove inizia il progetto.
Passare --workspace-root cambia anche questo, oltre a saltare la scoperta: il file di configurazione proprio della radice nominata è l’unico raccolto, quindi i file nelle directory sottostanti non contribuiscono. Ciò mantiene uguale la configurazione di una radice fissata ovunque venga eseguito il comando.
Ogni file raccolto in questo modo viene letto dall’interno del progetto. Uno che è un link simbolico che porta fuori dal progetto — o che si trova in una directory raggiunta tramite un link del genere — non viene letto, e ogni comando che legge la configurazione si arresta su di esso, nominando il link, anziché configurare il progetto a partire dai file rimanenti; lo stesso vale per il file di una pipeline, più sotto. I pochi comandi che non la leggono mai, come aggrega version e aggrega help, vengono eseguiti con un avviso che nomina il link. Il language server dell’editor e gli strumenti di un assistente leggono la configurazione allo stesso modo, e si avviano comunque su un progetto del genere in modo che possa essere elencato: i loro elenchi di Release e di entità rispondono, letti senza nulla di configurato, e nominano il file tra i link non letti, mentre ogni altra richiesta che la configurazione decide si arresta su di esso, nominando il link. Una configurazione mantenuta fuori dal progetto viene letta nominandola come file globale, come descrive Nominare esplicitamente il file globale. Vedi Il confine del workspace.
Estendere un elenco anziché sostituirlo
Un’impostazione a elenco si comporta come ogni altra impostazione: il valore del file più vicino sostituisce quello del file più lontano. Quando vuoi aggiungere a ciò che un file esterno ha dichiarato anziché ridichiararlo, usa il compagno di accodamento accanto a essa:
| impostazione a elenco | il suo compagno di accodamento |
|---|---|
workspace.catalog_dirs | catalog_dirs_append |
plugins.governance | governance_append |
plugins.linter | linter_append |
plugins.importer | importer_append |
plugins.providers | providers_append |
Le voci sotto un compagno vengono concatenate all’elenco risolto a ogni livello anziché oscurarlo, così un sottoprogetto aggiunge un linter a ciò che la radice ha già dichiarato:
# <project>/services/api/.aggrega-config.yamlplugins: linter_append: - uri: ./lint/api-rules.wasmDove un file imposta sia l’elenco di base sia il suo compagno, il valore di quel file è l’elenco di base seguito dalle voci accodate.
Il blocco workspace: è l’eccezione riguardo a dove si può scrivere un compagno. Un file che contiene quel blocco contrassegna la propria directory come radice del progetto, quindi il file di un sottoprogetto che scrivesse workspace.catalog_dirs_append avvierebbe un proprio progetto anziché aggiungere a quello che lo racchiude. Il compagno della directory di catalogo si compone tra il tuo file globale e il file radice del progetto.
L’elenco plugins.cli si compone da solo tra i file e non ha compagno: un’estensione di comando dichiarata nel file globale registra il proprio comando in ogni progetto, una dichiarata in un progetto lo registra solo lì, ed entrambe lo registrano insieme. Ogni voce fissa un plugin: l’uri che risolve e il digest dei byte che aggrega plugin add cli ha verificato, scritto sha256: seguito da 64 cifre esadecimali minuscole. Un digest in qualsiasi altra grafia non potrebbe mai essere uguale al digest che risulta dall’hash dei byte risolti, quindi viene rifiutato al caricamento del file, nominando il file e la voce.
Dare a una Release le proprie directory di catalogo
Un progetto può mantenere diverse varianti di catalogo affiancate — una per target, ciascuna contenente le Recipes che eseguono il rendering degli stessi Components per un provider diverso — e compilare ciascuna Release rispetto a una di esse. Nomina ciascuna Release sotto workspace.releases e assegnale le proprie catalog_dirs:
# <project>/.aggrega-config.yamlworkspace: releases: release-compose.yaml: catalog_dirs: - ./catalog-compose release-helm.yaml: catalog_dirs: - ./catalog-helmOgni chiave è un file di Release, scritto in modo relativo al file di configurazione che lo nomina. Una chiave — come build.authoring_release — può nominare una Release mantenuta fuori dal progetto, e nominarla qui è il modo in cui un progetto la raggiunge: un link all’interno del progetto che porta a essa viene letto anziché ignorato, come descrive Il confine del workspace. Le due chiavi sotto di essa significano ciò che significano nel blocco workspace:, limitate a quella sola Release:
catalog_dirssostituisce l’elenco del workspace per quella Release. L’ordine di ricerca, la directorycatalogletta dopo di esso e ciò che dice un elenco vuoto sono gli stessi dell’elenco proprio del workspace.catalog_dirs_appendviene letto dopo l’elenco della Release. Una voce che scrive solocatalog_dirs_appendmantiene l’elenco del workspace e vi aggiunge.
Una Release che la mappa non nomina legge il workspace.catalog_dirs proprio del workspace. Una Release che la mappa nomina legge le proprie directory comunque venga compilata — aggrega build o aggrega pull in un terminale, l’editor tramite aggrega serve, un assistente tramite aggrega mcp — quindi a nessuno di essi serve un flag per trovare il proprio catalogo. Un --catalog <dir> sulla riga di comando viene comunque cercato prima delle directory della Release, per quella singola invocazione. E una ricerca che non trova alcuna entità con un nome che hai usato indica la voce di quella Release come il punto in cui elencare la directory che la contiene.
Una voce che nomina un file che non esiste viene rifiutata al caricamento della configurazione, nominando la voce e il file. Rinominare una Release arresta quindi ogni comando finché la voce non viene rinominata insieme a essa, anziché lasciare che la Release venga compilata rispetto all’elenco del workspace senza che nulla lo segnali. Una directory elencata da una voce deve essere una directory, come deve esserlo una nominata dall’elenco del workspace: una che non lo è viene rifiutata da ogni comando che legge il catalogo di quella Release, nominando la voce e la sua riga.
Ciò che non riguarda una singola Release legge ancora l’elenco del workspace: un lint o una validazione dell’intero catalogo, la ricerca di un’entità per nome, un Aggregate ispezionato da solo e l’elenco delle entità del workspace in un editor. AGGREGA_CATALOG_DIRS imposta l’elenco del workspace e non raggiunge alcuna voce qui, e un file di configurazione di proprietà della tua pipeline non legge affatto la mappa.
Un file di configurazione di proprietà della tua pipeline
Un file chiamato .aggrega-config-append-ci.yaml può trovarsi accanto al file scritto a mano in qualsiasi directory visitata dalla scansione. È un file separato così che una pipeline automatizzata possa possederlo e sovrascriverlo per intero senza mai toccare ciò che ha scritto una persona.
È solo additivo. Le sue voci per le cinque impostazioni a elenco sopra vengono concatenate agli elenchi risolti; non può rimuovere nulla né sovrascrivere uno scalare. Una chiave scalare o di mappa scritta al suo interno non ha alcun significato additivo, quindi viene ignorata e nominata in un avviso anziché applicata in silenzio. Non contrassegna mai nemmeno una radice di progetto, quindi inserirne uno in una directory aggiunge collegamenti senza spostare il punto in cui inizia il progetto.
Dove punta un percorso relativo
Un percorso relativo del filesystem viene risolto rispetto alla directory del file che lo ha dichiarato — non rispetto alla radice del progetto, e non rispetto alla directory da cui hai eseguito il comando. Questa è la regola che vale la pena leggere due volte, perché un percorso che sembra relativo al progetto si risolve altrove e la build riesce comunque, su contenuti che non intendevi.
Si applica a workspace.catalog_dirs, ai file di Release indicati come chiavi sotto workspace.releases e alle directory che ciascuna voce elenca, ai percorsi del filesystem locale su un collegamento plugins.governance o plugins.linter — un uri che nomina un file .wasm su disco, e ogni voce sotto il with.sources di quel collegamento — e a ogni voce sotto il with.sources di un collegamento plugins.importer. In tutti e tre gli elenchi un uri senza due punti che non nomina alcun registry — importer/agent-flows così come ./lint/api-rules.wasm — è un percorso del genere, mentre un uri che nomina un plugin tramite la sua identità porta la versione dopo i due punti, importer/agent-flows:1.2.0, e viene lasciato esattamente come è scritto. L’uri di un collegamento di importer nomina l’importer che collega, come descrive Quale importer trasforma una sorgente in bozze; un’importazione non legge alcun modulo da un percorso scritto lì. La regola si applica anche alle voci sotto i compagni di accodamento, e ciascuna di esse si ancora al proprio file dichiarante anziché al file in cui la fusione si trova a terminare. E si applica a mcp.tls.cert_file, mcp.tls.key_file e mcp.authorization.jwks_file, così un file accanto a quello che lo nomina viene trovato ovunque venga avviato il server.
Quindi, dato questo layout:
myproject/├── .aggrega-config.yaml└── services/ ├── .aggrega-config.yaml └── catalog/e ./catalog scritto nel file radice, il percorso nomina myproject/catalog. Scritto in services/.aggrega-config.yaml, lo stesso identico testo nomina myproject/services/catalog. Un percorso assoluto viene lasciato esattamente come è scritto, e così anche un riferimento di registry come oci://hub.aggrega.ai/plugins/helm:1.0.0.
Queste impostazioni deliberatamente non seguono questa regola, perché non hanno un file dichiarante a cui ancorarsi o perché ogni loro lettore le risolve altrove:
artifact_cache_dirviene interpretato in modo relativo alla radice del progetto, ovunque venga eseguito il comando, così la cache è un’unica directory anziché una per ogni posizione di invocazione. Un valore assoluto viene rifiutato al caricamento della configurazione.AGGREGA_CATALOG_DIRSproviene dall’ambiente e non ha alcun file dichiarante, quindi fornisci percorsi assoluti al suo interno.mcp.listenviene preso esattamente come è scritto, e ciò include il percorso del filesystem nella sua formaunix:<path>. Lo stesso indirizzo arriva anche daaggrega mcp --listen, che non ha alcun file dichiarante, quindi ancorare solo la grafia configurata farebbe sì che una stessa stringa nomini due posti diversi a seconda della sua provenienza. Dai al socket un percorso assoluto.
Un’impostazione il cui store è condiviso
Quasi ogni impostazione governa qualcosa che appartiene al progetto su cui stai lavorando — attraverso quali directory risolve il contenuto di catalogo, quali plugin eseguono il rendering dei suoi target, con quanta severità viene giudicato il suo contenuto, quanto possono crescere le cache in memoria del daemon. Un valore nel file di un progetto governa ciò che è proprio di quel progetto, e non c’è nulla a cui prestare attenzione.
compiled_module_cache.max_bytes è l’unica eccezione, perché ciò che limita non è per progetto. Il codice compilato dei plugin è conservato in un’unica directory che ogni progetto sulla tua macchina riutilizza, così un dato plugin viene compilato una volta anziché una volta per progetto. Il limite stesso si risolve come qualsiasi altra impostazione — scrivilo nel file di un progetto e quel valore vince per quel progetto — ma lo store ha comunque una sola dimensione, e la dimensione in vigore è quella della build più recente. Due progetti che lo limitano in modo diverso hanno effetto entrambi a turno, e il limite più basso scarta codice compilato che l’altro progetto ha pagato.
Mettilo quindi nel file globale quando vuoi un’unica risposta per tutto ciò di cui esegui la build, e mantienilo al di sopra di ciò che una singola build compila. aggrega cache status riporta ciò che lo store contiene attualmente, e aggrega config show --origin ti dice da quale file proviene effettivamente il limite sotto cui stai eseguendo.
Impostazioni per un server raggiunto da altre persone
aggrega mcp parla il Model Context Protocol. Sulla tua macchina un client lo avvia come sottoprocesso e comunica con esso tramite standard input e output, che è il comportamento predefinito, e le uniche impostazioni che quella forma legge sono mcp.transport, lasciata a quel valore predefinito, e mcp.announce_tools. Il resto del blocco mcp è per l’altra forma, che mcp.transport: http sceglie: un unico processo di lunga durata su un host, raggiunto tramite HTTP da chiamanti che non sono alla sua tastiera.
# <project>/.aggrega-config.yamlmcp: transport: http listen: 127.0.0.1:7777 authorization: issuer: https://login.example.com resource: https://mcp.example.com/mcp allowed_origins: - https://studio.example.com limits: max_concurrent_requests: 32 deny_reach: - registry announce_tools: - list-entities - get-schema - validate - build health: listen: 127.0.0.1:7778mcp.transport è ciò che sceglie il trasporto. http avvia un listener; stdio, il valore predefinito, comunica tramite standard input e output, che è ciò che si aspetta un client sottoprocesso. Qualsiasi altro valore viene rifiutato al caricamento di questo file. aggrega mcp --transport <stdio|http> fa lo stesso per una singola invocazione e vince sulla chiave, nel modo in cui ogni flag vince su ogni file.
mcp.listen nomina dove si collega quel listener, e non sceglie nulla. Dagli un indirizzo host:port o un socket unix:<path>; aggrega mcp --listen <address> vince su di esso per una singola invocazione. Con http scelto e nessun indirizzo da nessuno dei due, l’avvio viene rifiutato prima che qualcosa si colleghi. Con stdio scelto, un --listen digitato viene rifiutato, e un indirizzo che solo questa chiave nomina resta inutilizzato — il server lo dice in una riga sul proprio flusso di errore, nominando questo file e mcp.transport: http. Quindi un server raggiunto da altre persone imposta entrambe le chiavi, come sopra, e un client avviato da una directory coperta da quel file raggiunge comunque il server tramite i propri flussi. Un percorso unix: viene preso come è scritto anziché ancorato — vedi Dove punta un percorso relativo.
mcp.tls.cert_file e mcp.tls.key_file mettono il TLS nel processo. Imposta entrambi e il listener serve HTTPS da sé. Omettili entrambi e serve testo in chiaro, accettato solo su loopback o su un socket Unix — la forma che usi quando un proxy posto davanti detiene il certificato e inoltra al processo. Un listener in chiaro su qualsiasi altro indirizzo viene rifiutato prima che qualcosa si colleghi, nominando queste due chiavi, e così anche uno dei due impostato senza l’altro. Entrambi sono percorsi del filesystem e seguono la regola sopra: uno relativo si risolve rispetto alla directory del file che lo ha dichiarato, così un certificato sottoposto a commit accanto a quel file viene trovato ovunque venga avviato il server. Scrivili assoluti dove il certificato è gestito fuori dal progetto.
mcp.authorization.issuer e mcp.authorization.resource dicono chi emette i token che i chiamanti presentano e come si chiama questo server in quanto risorsa per cui vengono emessi. Entrambi sono obbligatori ogni volta che si sceglie il trasporto http, e senza di essi un listener viene rifiutato prima che qualcosa si metta in ascolto, perché a ogni richiesta all’endpoint si risponde con una challenge bearer-token, e una challenge che non indica dove andare è una a cui un client non può dare seguito. Scrivi indirizzi completi, schema e host inclusi: l’issuer esattamente come quel server di autorizzazione dichiara il proprio identificatore, e la risorsa come l’indirizzo che i tuoi chiamanti raggiungono davvero — l’host che presenta un proxy posto davanti, dove ce n’è uno, anziché l’indirizzo su cui si mette in ascolto questo processo. Entrambi sono pubblicati, senza che venga chiesta alcuna credenziale, nel documento di metadati OAuth della risorsa protetta servito dal listener, ed è lì che un client cerca dove ottenere un token. Nessuno dei due contiene nulla di segreto: un token arriva con la richiesta che lo presenta e non viene mai scritto in un file di configurazione. L’issuer è un indirizzo https a meno che il server di autorizzazione non giri su questa macchina — localhost, 127.0.0.1 o ::1 — e un listener che indica un issuer http in chiaro su qualsiasi altro host viene rifiutato prima che qualcosa si metta in ascolto, in qualunque modo legga le sue chiavi e i suoi chiamanti: ogni client viene mandato all’issuer per ottenere il proprio token, quindi su http in chiaro il suo codice di autorizzazione e il suo token attraverserebbero la rete senza protezione, e dove anche le chiavi vengono lette da lì, chiunque si trovi su quel percorso potrebbe sostituirle.
mcp.authorization.jwks_file indica un file che contiene le chiavi rispetto a cui vengono verificati i token, invece di leggerle dal server di autorizzazione. Se lo ometti, il server legge i metadati di quel server al suo indirizzo well-known e segue il jwks_uri pubblicato lì, che è ciò che fa un workspace con accesso alla rete. Quell’indirizzo delle chiavi è soggetto alla stessa regola dell’issuer, e così ogni indirizzo verso cui una delle due letture viene reindirizzata: uno che è http in chiaro su un altro host non viene mai interrogato, e a un token che ha bisogno di quelle chiavi si risponde 503 finché il server di autorizzazione non pubblica i propri metadati e le proprie chiavi su https. Se lo imposti, il server di autorizzazione non viene mai contattato — che è ciò di cui ha bisogno un workspace che dichiara offline: true, e un workspace del genere viene rifiutato prima che il suo listener si metta in ascolto a meno che questa chiave non indichi un file. È un percorso e segue la regola sopra: uno relativo si risolve rispetto alla directory del file che lo ha dichiarato, quindi un set di chiavi committato accanto a quel file viene trovato ovunque si avvii il server. Il file contiene chiavi pubbliche di verifica, che sono ciò che un server di autorizzazione pubblica — niente che firmi, e niente di segreto.
mcp.allowed_origins viene consultato solo quando una richiesta porta un header Origin, il che in pratica significa che l’ha inviata un browser. Elenca lì le origini che servi; una richiesta che ne indica una non elencata viene rifiutata, e una richiesta senza tale header viene servita comunque. Un client che non è un browser non invia tale header e non ha bisogno di alcuna voce. Una voce viene confrontata esattamente con l’header, quindi scrivila come la invia un browser: uno schema in minuscolo, ://, un host in minuscolo, e : con la porta solo dove la porta non è quella predefinita dello schema — https://studio.example.com, oppure http://localhost:3000 per una pagina servita sulla tua macchina — senza percorso e senza / finale. Una voce in qualsiasi altra forma non potrebbe mai corrispondere, e viene rifiutata quando questo file viene caricato, con il nome della voce.
mcp.limits limita ciò che un singolo chiamante può chiedere — quanto può essere grande il corpo di una singola richiesta, quante richieste vengono eseguite contemporaneamente e quante un chiamante può inviarne in un minuto. Tutti e tre sono sempre in vigore; nessuno ha un valore che lo rimuova. Il terzo, requests_per_minute, viene conteggiato separatamente per ogni chiamante, quindi un chiamante che invia molte richieste non costa nulla a un altro.
mcp.authorization.trusted_proxy ricava il chiamante da un proxy posto davanti invece di verificare un token qui. Imposta principal_header sull’header che quel proxy usa per dire chi è il chiamante e, facoltativamente, scopes_header su uno che porta gli scope di quel chiamante. Entrambi sono nomi di header HTTP, come X-Forwarded-User — lettere, cifre, trattini e i pochi altri caratteri che un nome di header può contenere, senza spazi né due punti — e un nome in qualsiasi altra forma viene rifiutato quando questo file viene caricato, con il nome della chiave, perché nessuna richiesta potrebbe portarlo. In quella modalità non viene letto alcun token, e una richiesta senza l’header del principal viene rifiutata. Poiché l’header è allora l’intera credenziale, è affidabile solo dove nient’altro può impostarlo: il processo viene rifiutato prima di mettersi in ascolto a meno che mcp.listen non sia loopback o un socket Unix. Se ometti il blocco, questo server verifica i token da sé, che è il comportamento predefinito; un blocco il cui principal_header è vuoto viene rifiutato anziché essere letto come quel comportamento predefinito.
mcp.deny_reach ritira un tipo di portata da questo deployment. Ogni operazione che il server esegue dichiara fin dove arrivano i propri effetti — none per una che legge o esegue il rendering 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 cambia ciò che tutti i workspace sull’host condividono. Indicare qui un tipo ritira ogni strumento che lo raggiunge: lo strumento è assente dall’elenco degli strumenti di ogni chiamante, qualunque cosa porti il token di quel chiamante, e una chiamata a esso viene rifiutata con il nome di questa impostazione. Ciò ne fa il limite del deployment anziché del chiamante, e nessuna credenziale lo rimuove — un server destinato a servire letture e nient’altro elenca qui i tre tipi che scrivono e poi non può pubblicare nemmeno per un chiamante il cui token porta ogni scope. Se lo ometti, che è il comportamento predefinito, questo deployment offre tutto ciò che gli scope dei suoi chiamanti ammettono. Un valore che non è uno dei quattro viene rifiutato quando questo file viene caricato, anziché essere ignorato. Nulla del tipo machine viene offerto su HTTP, qualunque cosa dica questa impostazione, quindi indicarlo è accettato e non cambia nulla; aggrega-mcp.md descrive i tipi e gli scope che li ammettono.
mcp.announce_tools restringe ciò che il server annuncia, ed è un limite diverso dalla chiave precedente. Indica gli strumenti che questo server annuncia, scritti come li riporta l’elenco degli strumenti, ed esattamente quelli vengono annunciati: uno omesso è assente dall’elenco degli strumenti di ogni chiamante e, se viene comunque chiamato per nome, viene rifiutato con il nome di questa impostazione. Se ometti la chiave — il comportamento predefinito — viene annunciato ogni strumento che il server offre; se scrivi un elenco vuoto non ne viene annunciato nessuno, quindi quelle due scritture sono affermazioni diverse e nessun valore predefinito viene inserito al posto tuo. Ciò che la distingue da deny_reach è ciò che ciascuna toglie. deny_reach toglie una capacità: le operazioni di un tipo ritirato non sono affatto offerte qui e nessuna credenziale ne riporta una. announce_tools toglie solo un annuncio — gli strumenti che omette sono capacità che il server ha ancora — e ciò a cui risponde è un client che limita quanti strumenti registrerà, a volte su tutti i server a cui è connesso contemporaneamente. Dove sono impostate entrambe prevale il ritiro, quindi uno strumento di un tipo ritirato resta assente comunque questa chiave lo indichi. Un nome a cui non risponde alcuno strumento ferma il server prima che serva qualsiasi cosa, elencando gli strumenti che ha, anziché lasciarti con una superficie più ristretta di quella che hai chiesto. A differenza delle altre chiavi qui, che configurano il listener avviato dal trasporto http, viene letta qualunque sia il trasporto che il server parla, perché il client per cui esiste un restringimento è di solito quello che ha avviato il processo tramite il proprio standard input e output; aggrega-mcp.md descrive il resto.
mcp.health.listen mette i controlli di liveness e readiness su un indirizzo proprio. Assegnale un indirizzo in una delle due forme di mcp.listen e lì un secondo listener risponde a GET /healthz — 200 dal momento in cui il processo è in esecuzione — e a GET /readyz — 503 finché il workspace non è stato risolto e l’endpoint non è in ascolto, 200 da quel momento in poi, ed è ciò che permette a un bilanciatore di trattenere il traffico finché il processo non può effettivamente rispondere a una chiamata. Se la ometti, nessuno dei due controlli riceve risposta da nessuna parte. Non ricevono mai risposta sull’indirizzo indicato da mcp.listen, che dà loro il 404 che dà a ogni percorso che non serve: una sonda lì sarebbe una lettura non autenticata di un listener che rifiuta tutto il resto. A differenza di mcp.listen questo indirizzo non è vincolato e nessun indirizzo viene rifiutato per esso — puntalo su loopback o su un socket Unix, che è ciò che raggiunge un supervisore accanto a questo processo, e tieni presente che qualunque cosa possa raggiungere l’indirizzo che scegli può leggere quelle due risposte.
schema/other/aggrega-config.md riporta ciascuna di queste chiavi insieme al suo valore predefinito, dove ne ha uno.
Gli altri modi in cui si riconosce la radice di un progetto
--workspace-root <path>, o il suo corrispettivo AGGREGA_WORKSPACE_ROOT, indica direttamente la radice e salta la scoperta. La cartella che indica deve esistere: un percorso che non indica nulla, o che indica un file, viene rifiutato prima che il comando faccia qualsiasi altra cosa, e il rifiuto nomina quale dei due ha fornito il valore e lo cita così come è stato dato. Altrimenti la scoperta risale dalla directory di lavoro, e i tipi di ancora si classificano l’uno rispetto all’altro anziché per vicinanza:
- Un
.aggrega-config.yamlche contiene un bloccoworkspace:prevale senz’altro, a qualunque profondità si trovi. La risalita continua a salire per cercarne uno anche dopo aver superato un marcatore del tipo sottostante, quindi una radice marcata esplicitamente più in alto batte sempre un marcatore incidentale più in basso. - In mancanza di questo, il più vicino di questi marcatori ancora la radice, e all’interno di una stessa directory si classificano in quest’ordine: una directory
.aggrega/, poi unaggregate*.yaml, poi unrelease*.yaml, poi unmanifest*.yaml. - Se tutto fallisce, si usa la directory di lavoro — i comandi vengono eseguiti anziché rifiutarsi di partire. Un comando il cui risultato dipende dal workspace — uno che legge o scrive i documenti del workspace, legge o riempie la sua cache degli artefatti, o lo serve — avvisa una volta sullo standard error:
warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Un comando il cui risultato non dipende da quale cartella sia la radice non dice nulla, anche quando legge la configurazione: tra questiaggrega version,aggrega config show,aggrega plugin list,aggrega registry list,aggrega explaineaggrega login.aggrega config capture, il cui compito è scrivere il file di configurazione del workspace stesso, non scrive nulla in una cartella del genere ed esce con un errore che lo dice.
In una cartella del genere non viene scritto nulla in una cache degli artifact. Una directory .aggrega/ è essa stessa uno dei marcatori sopra, quindi una cache scritta lì renderebbe la cartella un workspace solo perché un tempo vi è stato scaricato qualcosa. Un comando il cui lavoro riempie la cache — aggrega pull, una build che risolve prima le proprie dipendenze, aggrega registry update, l’aggiunta di un plugin di estensione dei comandi da un registry — viene rifiutato prima di scaricare qualsiasi cosa, indicando la cartella e le due alternative: indicare il workspace con --workspace-root o AGGREGA_WORKSPACE_ROOT, oppure dare alla cartella un .aggrega-config.yaml che contiene un blocco workspace:. aggrega pin, e aggrega push di una Recipe o di una FeatureRecipe, vincolato ai pin che registra l’entity.lock accanto a essa, riempiono la cache solo con le sorgenti remote che l’entità scrive per intero, che il pinning di una di esse o il confronto del suo pin scarica: vengono rifiutati allo stesso modo dove scaricherebbero una tale sorgente, prima di scaricarla. Un’entità senza una tale sorgente — nessuna sorgente, una locale, o una le cui coordinate vengono compilate da ogni Release — viene fissata o pubblicata lì come altrove. Una build lì non viene rifiutata, ma un input esterno che il suo lockfile fissa e che la cache non contiene più non viene scaricato di nuovo per ripararlo: al rendering viene comunicata la stessa frase al posto di quell’input, nel modo in cui gli viene comunicata quella della postura offline, e il rendering la segnala. Dove artifact_cache_dir collochi la cache non cambia nulla qui, perché la directory viene unita a qualunque radice sia stata trovata. I comandi che si limitano a leggere rispondono comunque.
Quest’ultimo ripiego ha un’eccezione. Quando nulla ha indicato la radice e la directory di lavoro non ancora nulla, un comando che riguarda una Release o un documento di entità e che indica quel file con un percorso assoluto scopre di nuovo la radice, risalendo dalla cartella in cui si trova il file, e usa ciò che trova: il workspace a cui appartiene il file o, in mancanza di tutto, quella cartella. Il file è quello che --release indica su aggrega build e aggrega pull; la Release data a aggrega validate, aggrega lint e aggrega inspect, oppure il file che viene loro dato; e il documento dato a aggrega pin, aggrega push e aggrega edit-document. Così la Release di un progetto compilata dall’esterno del progetto legge la configurazione del progetto stesso, come fa quando il comando viene eseguito al suo interno, e gli avvisi di configurazione che il comando stampa sono quelli di quel workspace. Dove nemmeno la cartella del file ancora nulla, quella cartella è quella indicata dall’avviso del comando e quella in cui non viene scritta alcuna cache. Un percorso relativo viene letto rispetto alla directory in cui esegui il comando e non cambia nulla, e una radice indicata, o una directory di lavoro che si trova essa stessa all’interno di un workspace, viene usata così com’è. Il server dell’assistente applica la stessa regola a una chiamata che indica la propria Release o il proprio documento con un percorso assoluto.
Marcare la radice con un blocco workspace: è la scelta esplicita e quella da preferire; i marcatori di file e di directory permettono comunque di compilare un progetto che non ne ha dichiarato uno.
Indicare esplicitamente il file globale
Il livello globale si risolve in quest’ordine:
--config <path>, la forma per singola invocazione.- La variabile d’ambiente
AGGREGA_CONFIG. - La posizione predefinita: su Windows
aggrega\config.yamlall’interno della directory indicata dalla variabile d’ambienteAPPDATA, e altroveaggrega/config.yamlall’interno della directory indicata daXDG_CONFIG_HOME, con ripiego su~/.config/aggrega/config.yaml.
Le prime due indicano un file esplicito, quindi un percorso che non esiste è un errore esplicito anziché un ripiego silenzioso — hai chiesto un file preciso. Un comando che legge la propria configurazione si ferma con una frase che termina con il percorso, così puoi copiarlo. aggrega config init è l’eccezione, perché creare quel file è il suo scopo: crea il file indicato e lo dice. La posizione predefinita viene caricata quando il file c’è e viene ignorata in silenzio quando non c’è. Qualunque file venga risolto, i file del tuo progetto continuano a sovrapporsi a esso.
Quando nessuna di queste si risolve — nessun file è indicato e le variabili da cui si legge la posizione predefinita non sono impostate — un comando che scrive il file globale si ferma e indica cosa impostare. Variabili d’ambiente elenca, per piattaforma, le variabili da cui si legge ciascuna posizione.
Quella scelta seleziona anche dove scrive un comando che scrive la configurazione. Un comando eseguito con --config <path> legge la propria configurazione da quel file e applica la propria modifica a quello stesso file, quindi ciò che un comando scrive è ciò che il successivo rilegge.
In quale dei due file un comando scrive per impostazione predefinita dipende dalla natura dell’impostazione: gli strumenti a livello di macchina, come un registry, vanno nel file globale, mentre le impostazioni che partecipano alla build, come un binding di provider o un collegamento a un socket, vanno nel file committato del progetto, così viaggiano con il progetto. Passa --global o --workspace per cambiare la destinazione, e il comando stampa il file in cui ha scritto.
Vedi anche
- aggrega-config.md — i comandi
aggrega configche inizializzano, ispezionano e congelano la configurazione. - environment-variables.md — ogni variabile con prefisso
AGGREGA_, e dove si forniscono i segreti. - global-flags.md —
--config,--workspace-roote gli altri flag che ogni sottocomando accetta. - schema/other/aggrega-config.md — ogni chiave di configurazione, il suo tipo e il suo valore predefinito.
- aggrega-cache.md — cosa contiene effettivamente
artifact_cache_dir. - workspace-boundary.md — quali percorsi restano all’interno del workspace, e come le directory e i file che questa configurazione indica arrivano al di fuori di esso.
- aggrega-mcp.md — il server che il blocco
mcpconfigura.