Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

aggrega cache

Ispeziona e mantiene le cache su disco

Sinossi

aggrega cache

Descrizione

Inspect and maintain the caches the compiler populates.
status lists cache contents, one element per line, then a summary line.
prune reclaims artifact-cache entries no workspace lockfile references.
evict trims the compiled-module cache to a size cap, oldest first.
clear wipes every cache, including the compiled-module store.

Sottocomandi

ComandoDescrizione
aggrega cache clearCancella ogni cache, inclusi i moduli compilati
aggrega cache evictRiduce la cache dei moduli compilati entro un limite di dimensione, a partire dai più vecchi
aggrega cache pruneRimuove le voci della cache degli artifact a cui nessun lockfile fa riferimento
aggrega cache statusElenca il contenuto della cache e un riepilogo totale

Descrizione di aggrega cache clear

Wipe every cache: the workspace artifact cache (entities, source artifacts,
external inputs) and the caches every project on the machine shares (compiled
modules, plugin descriptors, documentation bundles, and the cli plugins added
where no workspace was found). This is the total-wipe verb; unlike prune it
reclaims the compiled-module cache and the documentation bundles as well.
Cleared caches repopulate on the next build, and the documentation bundle on
the next read of the documentation; a cli plugin cleared from the cache is
fetched again by adding it again.
Because the wipe is irreversible, clear asks for confirmation before removing
anything. Pass --yes to skip the prompt for non-interactive use; without --yes
on a non-interactive stdin it refuses rather than blocking on a prompt no one
can answer.

Flag di aggrega cache clear

FlagPredefinitoDescrizione
--yesfalsesalta la richiesta di conferma (per l’uso non interattivo/CI)

Descrizione di aggrega cache evict

Trim the compiled-module cache to a size cap by removing the
least-recently-compiled modules first, until the cache total is at or below
--max-size. The compiled-module cache is machine-global: every provider guest is
compiled once and reused across every project on the machine, so over time it can
dominate on-disk cache use.
Unlike prune (which reclaims artifact-cache entries no lockfile references) and
clear (which wipes every cache), evict is size-bounded and touches only the
compiled-module cache. Evicted modules recompile on demand on the next build, so
eviction loses no irrecoverable state.
--max-size is required and accepts a binary-unit size in the same vocabulary the
status summary prints — for example 5GiB, "4.5 GiB", or 512MiB — or a bare
integer byte count. The unit suffix is case-insensitive and an optional space
may separate the number from the unit.
This verb is the on-demand trim, at a cap you give it once. The cache is also
held to a standing cap without being asked: every invocation that loads a plugin
applies the `compiled_module_cache.max_bytes` setting (53687091200 bytes, 50 GiB,
by default) before it compiles anything, using this same removal order. Use this
verb to reclaim space now or below the standing cap; change the setting to move
the standing cap itself. When the cache already fits the cap, evict reports a
no-op and removes nothing.

Flag di aggrega cache evict

FlagPredefinitoDescrizione
--max-size—limite di dimensione per la cache dei moduli compilati (ad es. 5GiB, 512MiB o un numero di byte); obbligatorio

Descrizione di aggrega cache prune

Remove cache entries whose content digest no workspace lockfile references,
retaining every referenced entry. The reference set is the union of the
digests pinned across every lockfile (*.lock) in the workspace, together with
the digests the configuration's plugins.cli list pins, so a cli plugin you
added keeps the bytes it runs from.
Prune acts on the caches whose entries carry a content digest — the workspace
artifact cache (entities, source artifacts, external inputs), the
plugin-describe cache and the cli-plugin cache, which holds the cli plugins
added where no workspace was found — and on the compiled-module cache by reference: a compiled
plugin module is reclaimed when no lockfile still references the plugin it
belongs to, and the shared runtime module every plugin depends on is reclaimed
once the last plugin referring to it is pruned. A compiled module that cannot be
traced back to a plugin is retained rather than removed on a guess; that
remainder is reclaimed by "aggrega cache evict" or "aggrega cache clear".
Prune needs a pulled workspace: it fails when no lockfile is present.

Descrizione di aggrega cache status

List the contents of every cache, one element per line, followed by a
summary line of the form "N elements, <human size>". The listing is
deterministic: identical cache state produces byte-identical output.

Che cos’è la cache, e che cosa non è

La cache degli artifact in artifact_cache_dir (.aggrega/cache per impostazione predefinita) contiene ciò che un fetch vi ha messo: entità del catalogo e artifact sorgente, ciascuno memorizzato sotto il proprio tipo e la coordinata e la versione con cui è stato recuperato, e garantito da un digest registrato nel lockfile. Non è una directory di catalogo, e una scansione del catalogo la salta — quindi il contenuto presente nella cache viene letto come dipendenza, tramite il pin che lo garantisce, e mai come un’entità scritta da te.

La conseguenza in cui è più probabile imbattersi. Se la cache contiene un’entità che nessun lockfile fissa con un pin, quell’entità è invisibile a una build, e una build che ne ha bisogno si arresta dicendo che non è stata trovata. L’arresto nomina l’entità, quindi il pin mancante è identificabile dal messaggio.

Quando l’entità è una SchemaLibrary raggiunta da un $ref:, ogni comando che segnala il riferimento come non risolto fa seguire alla segnalazione una riga remediation: che indica ogni libreria contenuta nella cache che nessuna voce di lockfile fissa e nessuna directory del catalogo fornisce, e l’azione che funziona per quel comando:

  • aggrega build e aggrega validate --release <release> leggono il lockfile della Release, quindi la riga indica aggrega pull --release <release> per risolvere la libreria e registrarne la voce.
  • aggrega validate senza argomenti, e aggrega validate <entity-path> con o senza --release, leggono le librerie solo dalle directory del catalogo e non leggono alcun lockfile, quindi nessuna voce registrata cambia il loro verdetto. La riga lo dice, e indica aggrega pull --release <release> seguito da aggrega validate --release <release>, che verifica la Release rispetto a ciò che il suo lockfile fissa.
  • aggrega pull, e aggrega build --auto-pull, in modalità offline non possono né recuperare la libreria né registrarne una voce, quindi la riga dice di eseguire aggrega pull --release <release> dove si può raggiungere un registry. Con la connessione, un pull che non trova la libreria in nessuna directory del catalogo e in nessun registry che legge non ha alcuna voce da registrare.

Ognuna di quelle righe offre anche l’altra strada: scrivere la libreria in una directory del catalogo.

Che cosa eseguire. aggrega pull --release <release> risolve l’entità e ne registra il digest, dopodiché la stessa build la trova. Se l’entità è tua anziché una dipendenza, scrivila invece in una directory elencata in workspace.catalog_dirs — una scansione legge quella. aggrega cache prune elimina le voci a cui nessun lockfile fa riferimento, che è la metà di riordino della stessa regola.

Per il layout della cache, il contratto di artifact_cache_dir e il motivo per cui un artifact di risoluzione deliberatamente non è leggibile come contenuto scritto da un autore, vedi architecture/13-catalog-and-registry.md.

Quali cache appartengono a questo progetto e quali alla macchina

Non tutte le cache su cui agiscono questi comandi sono limitate al progetto in cui ti trovi, e la differenza decide fin dove arriva un recupero di spazio.

Solo tue. La cache degli artifact in artifact_cache_dir — le entità, gli artifact sorgente e gli input esterni con pin che questo progetto ha risolto, e gli snapshot del catalogo pubblicato che un’importazione che non indica alcuna cartella di catalogo ha letto. Recuperare spazio da essa interessa questo progetto e nient’altro.

Condivise da ogni progetto Aggrega su questa macchina. Lo store dei moduli compilati, lo store delle descrizioni dei plugin, lo store dei bundle della documentazione e lo store dei plugin cli. Un guest di un provider viene compilato una volta e riutilizzato da ogni progetto, ed è questo che rende veloce la seconda build di qualsiasi cosa, quindi rimuovere una voce significa che la build successiva di qualsiasi progetto sulla macchina lo ricompila. Il bundle della documentazione — le pagine pubblicate da cui leggono aggrega explain, le spiegazioni di un editor e le risorse di documentazione di un assistente, e gli esempi eseguibili che aggrega scaffold --example scrive — viene conservato una sola volta per registry e versione, perché il suo contenuto non dipende da nient’altro: il primo di essi che lo recupera lo recupera per ogni progetto, e ogni progetto lo riceve comunque solo dopo che il proprio controllo della firma ammette la copia. Nulla va perso in modo permanente — un modulo rimosso viene ricostruito su richiesta, e un bundle rimosso viene recuperato di nuovo dalla spiegazione o dall’esempio successivi, o da un server dell’assistente al suo prossimo avvio — ma il costo ricade su chi esegue la build successiva, che potresti non essere tu.

Lo store dei plugin cli conserva i byte di ogni plugin cli aggiunto con aggrega plugin add cli in una cartella che non è un workspace, così il suo comando funziona da qualsiasi cartella; un plugin cli aggiunto all’interno di un workspace conserva invece i propri byte nella cache degli artefatti di quel workspace. A differenza di un modulo compilato o di un bundle, un plugin cli i cui byte vengono rimossi non viene recuperato di nuovo da solo: finché aggrega plugin add cli <name> non lo aggiunge di nuovo, il suo comando manca e ogni comando avverte che non è stato possibile aggiungerlo, indicando il comando aggrega plugin add cli che lo aggiunge di nuovo alla versione fissata dalla tua configurazione.

Gli store a livello di macchina sono conservati dove ogni piattaforma conserva le cache di un utente: su Windows in aggrega\cache all’interno della directory indicata dalla variabile d’ambiente LOCALAPPDATA, in ~/Library/Caches/aggrega su macOS, e in una directory aggrega all’interno di quella indicata da XDG_CACHE_HOME — ~/.cache/aggrega quando XDG_CACHE_HOME non è impostata — su Linux e sugli altri sistemi Unix. aggrega config init stampa la directory sulla macchina su cui viene eseguito. Dove nessuna di queste variabili è impostata, i plugin compilati vengono conservati solo per l’esecuzione e nessun bundle della documentazione viene conservato: una spiegazione dice allora perché manca la sua guida passo passo, le risorse di documentazione di un assistente rispondono «non trovato», e aggrega scaffold --example rifiuta, dicendo che non si risolve alcuna directory di cache; anche aggrega plugin add cli eseguito in una cartella che non è un workspace rifiuta, dicendo che non si risolve alcuna posizione di cache a livello di macchina.

aggrega cache status lo indica per ogni classe anziché lasciarlo dedurre dal nome: ogni classe è riportata come relativa al workspace o alla macchina, e la stessa portata è riportata per ogni elemento che prune, evict e clear rimuovono. evict agisce solo sullo store condiviso dei moduli compilati; prune non rimuove mai un bundle della documentazione né uno snapshot del catalogo letto da un’importazione, poiché nessun lockfile fa riferimento né all’uno né all’altro, e riporta ciascuna di queste classi come non idonea al prune; prune conserva i byte di ogni plugin cli fissato dall’elenco plugins.cli della tua configurazione — nello store dei plugin cli come nella cache degli artefatti del workspace, insieme alla relativa voce di descrizione del plugin — e rimuove quelli che nessun pin indica; clear agisce su tutto, ed è per questo che chiede conferma prima di iniziare.

Una radice del workspace che non può essere usata. Quando la radice del workspace data al comando è un file o un percorso che non esiste, status, evict e clear agiscono solo sugli store dell’intera macchina, terminano come farebbero altrimenti e lo segnalano sullo standard error, con le stesse parole con cui ogni altro comando rifiuta quella radice:

note: —workspace-root names the workspace root "<root>", which is not a directory: <root>; only the machine-wide caches are acted on (nota: —workspace-root indica una radice del workspace che non è una directory; si agisce solo sulle cache dell’intera macchina)

Un percorso che non esiste riporta which cannot be used: e il motivo al posto di which is not a directory:. prune invece si ferma, perché ha bisogno dei lockfile del workspace.

Questo vale ovunque venga invocata l’operazione, non solo in un terminale. Le stesse operazioni sono raggiungibili da una sessione dell’editor e dalla chiamata a uno strumento di un assistente, e le loro risposte riportano la stessa portata per lo stesso motivo. Dove un assistente può invocarle per tuo conto, vedi aggrega mcp.

La directory della cache degli artifact è l’unico luogo da cui tutto ciò che è nella cache viene letto, in cui viene scritto e da cui viene rimosso — sia il valore predefinito .aggrega/cache sia una directory indicata da artifact_cache_dir che risale oltre la radice del workspace (../shared-cache). Qualsiasi elemento al suo interno che sia un link simbolico che porta fuori da quella directory — una delle directory proprie della cache, come .aggrega/cache/inputs, o un file al loro interno — non viene usato per leggere, scrivere né rimuovere, anche dove il link porta a un’altra directory dello stesso workspace. Ciò che una scrittura può raggiungere sotto la directory della cache è esattamente ciò che una rimozione può raggiungere.

  • Un pull, una build e ogni altra operazione che scrive nella cache si arrestano con E0320, nominando il link e dove porta, e non scrivono nulla.
  • status, prune e clear non elencano nulla attraverso un link di questo tipo. Dove una delle directory proprie della cache è il link, status si arresta con E0321, e un prune o un clear si arresta con E0320 prima di elencare o rimuovere qualsiasi cosa — quindi nulla di ciò a cui punta il link viene rimosso, e il link resta dov’è. Dove il link è un file al loro interno, tutti e tre si arrestano con E0321.
  • Una build, un pull e ogni altra operazione che legge la cache si arrestano con E0321 anziché leggere byte conservati altrove, anche dove quei byte corrisponderebbero al digest registrato nel lockfile.
  • Un link che resta all’interno della directory della cache viene seguito. Dove una delle directory proprie della cache è un link a un’altra directory all’interno della directory della cache, quella directory appartiene alla cache: status elenca ciò che vi si trova, prune vi rimuove elementi, e clear la svuota, mantiene il link e riporta i byte che vi ha rimosso.

La directory della cache stessa. Un artifact_cache_dir scritto all’interno della radice del workspace — incluso il valore predefinito — può essere a sua volta un link a un’altra directory del workspace, e la cache viene allora conservata dove porta il link. Uno che porta fuori dal workspace viene rifiutato: qualunque operazione lo incontri si arresta con E0321 o E0320, nominando il link, prima che qualcosa venga letto o scritto attraverso di esso. Una directory scritta risalendo oltre la radice del workspace viene rispettata dove porta, anche quando è essa stessa un link.

Rimuovi il link ed esegui di nuovo il pull per riempire la cache sul posto. Per conservare la cache altrove, imposta artifact_cache_dir su quella directory, scritta in modo relativo alla radice del workspace, anziché creare un link verso di essa: una directory indicata lì viene letta e scritta dove porta. Gli store a livello di macchina non sono vincolati ad alcun workspace; uno che conservi altrove tramite un link viene elencato, sottoposto a prune e svuotato dove porta il link, e clear mantiene il link. Il confine del workspace enuncia la regola per intero.

Vedi anche

  • aggrega-pull — risolve le dipendenze di una Release nel lockfile e nella cache.
  • aggrega-config — dove si scrivono artifact_cache_dir e le altre impostazioni della cache.