aggrega cache
Die Caches auf der Festplatte inspizieren und pflegen
Übersicht
aggrega cacheBeschreibung
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.Unterbefehle
| Befehl | Beschreibung |
|---|---|
aggrega cache clear | Löscht jeden Cache, einschließlich kompilierter Module |
aggrega cache evict | Kürzt den Cache kompilierter Module auf eine Größenobergrenze, die ältesten zuerst |
aggrega cache prune | Entfernt Einträge des Artefakt-Caches, auf die keine Lockfile verweist |
aggrega cache status | Listet den Cache-Inhalt und eine Gesamtzusammenfassung auf |
Beschreibung von aggrega cache clear
Wipe every cache: the workspace artifact cache (entities, source artifacts,external inputs) and the caches every project on the machine shares (compiledmodules, plugin descriptors, documentation bundles, and the cli plugins addedwhere no workspace was found). This is the total-wipe verb; unlike prune itreclaims the compiled-module cache and the documentation bundles as well.Cleared caches repopulate on the next build, and the documentation bundle onthe next read of the documentation; a cli plugin cleared from the cache isfetched again by adding it again.
Because the wipe is irreversible, clear asks for confirmation before removinganything. Pass --yes to skip the prompt for non-interactive use; without --yeson a non-interactive stdin it refuses rather than blocking on a prompt no onecan answer.Flags von aggrega cache clear
| Flag | Standard | Beschreibung |
|---|---|---|
--yes | false | überspringt die Bestätigungsabfrage (für nicht interaktive Verwendung/CI) |
Beschreibung von aggrega cache evict
Trim the compiled-module cache to a size cap by removing theleast-recently-compiled modules first, until the cache total is at or below--max-size. The compiled-module cache is machine-global: every provider guest iscompiled once and reused across every project on the machine, so over time it candominate on-disk cache use.
Unlike prune (which reclaims artifact-cache entries no lockfile references) andclear (which wipes every cache), evict is size-bounded and touches only thecompiled-module cache. Evicted modules recompile on demand on the next build, soeviction loses no irrecoverable state.
--max-size is required and accepts a binary-unit size in the same vocabulary thestatus summary prints — for example 5GiB, "4.5 GiB", or 512MiB — or a bareinteger byte count. The unit suffix is case-insensitive and an optional spacemay separate the number from the unit.
This verb is the on-demand trim, at a cap you give it once. The cache is alsoheld to a standing cap without being asked: every invocation that loads a pluginapplies the `compiled_module_cache.max_bytes` setting (53687091200 bytes, 50 GiB,by default) before it compiles anything, using this same removal order. Use thisverb to reclaim space now or below the standing cap; change the setting to movethe standing cap itself. When the cache already fits the cap, evict reports ano-op and removes nothing.Flags von aggrega cache evict
| Flag | Standard | Beschreibung |
|---|---|---|
--max-size | — | Größenobergrenze für den Cache kompilierter Module (z. B. 5GiB, 512MiB oder eine Byteanzahl); erforderlich |
Beschreibung von aggrega cache prune
Remove cache entries whose content digest no workspace lockfile references,retaining every referenced entry. The reference set is the union of thedigests pinned across every lockfile (*.lock) in the workspace, together withthe digests the configuration's plugins.cli list pins, so a cli plugin youadded keeps the bytes it runs from.
Prune acts on the caches whose entries carry a content digest — the workspaceartifact cache (entities, source artifacts, external inputs), theplugin-describe cache and the cli-plugin cache, which holds the cli pluginsadded where no workspace was found — and on the compiled-module cache by reference: a compiledplugin module is reclaimed when no lockfile still references the plugin itbelongs to, and the shared runtime module every plugin depends on is reclaimedonce the last plugin referring to it is pruned. A compiled module that cannot betraced back to a plugin is retained rather than removed on a guess; thatremainder is reclaimed by "aggrega cache evict" or "aggrega cache clear".
Prune needs a pulled workspace: it fails when no lockfile is present.Beschreibung von aggrega cache status
List the contents of every cache, one element per line, followed by asummary line of the form "N elements, <human size>". The listing isdeterministic: identical cache state produces byte-identical output.Was der Cache ist und was er nicht ist
Der Artefakt-Cache unter artifact_cache_dir (standardmäßig .aggrega/cache) enthält, was ein Abruf dort abgelegt hat: Katalogentitäten und Quellartefakte, jeweils unter ihrer Art sowie der Koordinate und Version gespeichert, mit der sie abgerufen wurden, und verbürgt durch einen Digest, den die Lockfile aufzeichnet. Er ist kein Katalogverzeichnis, und ein Katalog-Scan überspringt ihn — Inhalte im Cache werden daher als Abhängigkeit gelesen, über den Pin, der für sie bürgt, und niemals als eine Entität, die Sie verfasst haben.
Die Folge, der Sie am ehesten begegnen. Wenn der Cache eine Entität enthält, die keine Lockfile pinnt, ist diese Entität für einen Build unsichtbar, und ein Build, der sie benötigt, hält mit der Meldung an, dass sie nicht gefunden wurde. Der Abbruch nennt die Entität, sodass der fehlende Pin anhand der Meldung identifiziert werden kann.
Ist die Entität eine SchemaLibrary, die ein $ref: erreicht, lässt jeder Befehl, der die Referenz als nicht aufgelöst meldet, auf die Meldung eine remediation:-Zeile folgen, die jede Bibliothek im Cache nennt, die kein Lockfile-Eintrag pinnt und kein Katalogverzeichnis liefert, sowie die Maßnahme, die für diesen Befehl funktioniert:
aggrega buildundaggrega validate --release <release>lesen die Lockfile des Release, daher nennt die Zeileaggrega pull --release <release>, um die Bibliothek aufzulösen und ihren Eintrag festzuhalten.aggrega validateohne Argument undaggrega validate <entity-path>mit oder ohne--releaselesen Bibliotheken nur aus Katalogverzeichnissen und lesen keine Lockfile, daher ändert kein festgehaltener Eintrag ihr Urteil. Die Zeile sagt das und nenntaggrega pull --release <release>, gefolgt vonaggrega validate --release <release>, das das Release gegen das prüft, was seine Lockfile pinnt.aggrega pullundaggrega build --auto-pullkönnen im Offline-Modus die Bibliothek weder abrufen noch einen Eintrag für sie festhalten, daher sagt die Zeile,aggrega pull --release <release>dort auszuführen, wo eine Registry erreichbar ist. Mit Verbindung hat ein Pull, der die Bibliothek in keinem Katalogverzeichnis und keiner Registry findet, die er liest, keinen Eintrag festzuhalten.
Jede dieser Zeilen bietet auch den anderen Weg an: die Bibliothek unter einem Katalogverzeichnis zu verfassen.
Was auszuführen ist. aggrega pull --release <release> löst die Entität auf und zeichnet ihren Digest auf, danach findet derselbe Build sie. Wenn die Entität Ihre eigene ist und keine Abhängigkeit, verfassen Sie sie stattdessen unter einem Verzeichnis, das in workspace.catalog_dirs aufgeführt ist — ein Scan liest dieses. aggrega cache prune räumt die Einträge aus, auf die keine Lockfile verweist; das ist die aufräumende Hälfte derselben Regel.
Zum Layout des Caches, zum Vertrag von artifact_cache_dir und dazu, warum ein Auflösungsartefakt absichtlich nicht als verfasster Inhalt lesbar ist, siehe architecture/13-catalog-and-registry.md.
Welche Caches zu diesem Projekt gehören und welche zur Maschine
Nicht jeder Cache, auf den diese Befehle wirken, ist auf das Projekt beschränkt, in dem Sie sich befinden, und der Unterschied entscheidet, wie weit eine Freigabe von Speicherplatz reicht.
Nur Ihrer. Der Artefakt-Cache unter artifact_cache_dir — die Entitäten, Quellartefakte und gepinnten externen Eingaben, die dieses Projekt aufgelöst hat, und die Snapshots des veröffentlichten Katalogs, die ein Import gelesen hat, der keinen Katalogordner nennt. Speicherplatz daraus freizugeben betrifft dieses Projekt und nichts anderes.
Gemeinsam genutzt von jedem Aggrega-Projekt auf dieser Maschine. Der Speicher für kompilierte Module, der Speicher für Plugin-Beschreibungen, der Speicher für Dokumentations-Bundles und der Speicher für cli-Plugins. Ein Provider-Guest wird einmal kompiliert und von jedem Projekt wiederverwendet, was den zweiten Build von allem schnell macht; das Entfernen eines Eintrags bedeutet daher, dass der nächste Build irgendeines Projekts auf der Maschine ihn neu kompiliert. Das Dokumentations-Bundle — die veröffentlichten Seiten, aus denen aggrega explain, die Erklärungen eines Editors und die Dokumentationsressourcen eines Assistenten gelesen werden, und die ausführbaren Beispiele, die aggrega scaffold --example schreibt — wird einmal pro Registry und Version aufbewahrt, weil sein Inhalt von nichts anderem abhängt: Wer von ihnen es zuerst abruft, ruft es für jedes Projekt ab, und jedes Projekt erhält es dennoch erst, sobald seine eigene Signaturprüfung die Kopie zulässt. Nichts geht dauerhaft verloren — ein entferntes Modul wird bei Bedarf neu gebaut, und ein entferntes Bundle wird bei der nächsten Erklärung oder dem nächsten Beispiel erneut abgerufen oder von einem Assistentenserver bei seinem nächsten Start —, aber die Kosten trägt, wer als Nächstes baut, und das sind möglicherweise nicht Sie.
Der Speicher für cli-Plugins enthält die Bytes jedes cli-Plugins, das mit aggrega plugin add cli in einem Ordner hinzugefügt wurde, der kein Workspace ist, sodass sein Befehl aus jedem Ordner heraus läuft; ein innerhalb eines Workspace hinzugefügtes cli-Plugin legt seine Bytes stattdessen im Artefakt-Cache dieses Workspace ab. Anders als ein kompiliertes Modul oder ein Bundle wird ein cli-Plugin, dessen Bytes entfernt wurden, nicht von selbst erneut abgerufen: Bis aggrega plugin add cli <name> es erneut hinzufügt, fehlt sein Befehl, und jeder Befehl warnt, dass es nicht hinzugefügt werden konnte, und nennt den Befehl aggrega plugin add cli, der es in der von Ihrer Konfiguration festgelegten Version erneut hinzufügt.
Die maschinenweiten Speicher liegen dort, wo jede Plattform die Caches eines Benutzers ablegt: unter Windows in aggrega\cache innerhalb des Verzeichnisses, das die Umgebungsvariable LOCALAPPDATA nennt, unter macOS in ~/Library/Caches/aggrega und unter Linux und den anderen Unix-Systemen in einem Verzeichnis aggrega innerhalb desjenigen, das XDG_CACHE_HOME nennt — ~/.cache/aggrega, wenn XDG_CACHE_HOME nicht gesetzt ist. aggrega config init gibt das Verzeichnis auf der Maschine aus, auf der es läuft. Wenn keine dieser Variablen gesetzt ist, werden kompilierte Plugins nur für den Lauf aufbewahrt, und überhaupt kein Dokumentations-Bundle wird aufbewahrt: Eine Erklärung sagt dann, warum ihre Schritt-für-Schritt-Anleitung fehlt, die Dokumentationsressourcen eines Assistenten antworten mit „nicht gefunden“, und aggrega scaffold --example lehnt ab mit dem Hinweis, dass sich kein Cache-Verzeichnis auflösen lässt; aggrega plugin add cli, in einem Ordner ausgeführt, der kein Workspace ist, lehnt ebenfalls ab mit dem Hinweis, dass sich kein maschinenweiter Cache-Speicherort auflösen lässt.
aggrega cache status gibt dies pro Klasse an, statt es aus dem Namen erschließen zu lassen: Jede Klasse wird als den Workspace oder die Maschine abdeckend gemeldet, und dieselbe Reichweite wird für jedes Element gemeldet, das prune, evict und clear entfernen. evict wirkt nur auf den gemeinsamen Speicher für kompilierte Module; prune entfernt nie ein Dokumentations-Bundle oder einen Katalog-Snapshot, den ein Import gelesen hat, da keine Lockfile auf eines der beiden verweist, und meldet jede solche Klasse als nicht für prune geeignet; prune behält die Bytes jedes cli-Plugins, das die Liste plugins.cli Ihrer Konfiguration festlegt — im Speicher für cli-Plugins ebenso wie im Artefakt-Cache des Workspace, samt seinem Eintrag im Speicher für Plugin-Beschreibungen — und entfernt diejenigen, die keine Festlegung nennt; clear wirkt auf alles, weshalb es vor dem Start nachfragt.
Ein Workspace-Stammverzeichnis, das nicht verwendet werden kann. Wenn das dem Befehl übergebene Workspace-Stammverzeichnis eine Datei oder ein nicht existierender Pfad ist, wirken status, evict und clear nur auf die maschinenweiten Speicher, beenden sich wie sonst auch und melden dies auf der Standardfehlerausgabe, mit denselben Worten, mit denen jeder andere Befehl dieses Stammverzeichnis ablehnt:
note: —workspace-root names the workspace root
"<root>", which is not a directory:<root>; only the machine-wide caches are acted on (Hinweis: —workspace-root nennt ein Workspace-Stammverzeichnis, das kein Verzeichnis ist; es wird nur auf die maschinenweiten Caches eingewirkt)
Bei einem nicht existierenden Pfad steht which cannot be used: und der Grund anstelle von which is not a directory:. prune hält stattdessen an, da es die Lockfiles des Workspace benötigt.
Dies gilt unabhängig davon, von wo der Vorgang aufgerufen wird, nicht nur im Terminal. Dieselben Vorgänge sind aus einer Editor-Sitzung und über den Tool-Aufruf eines Assistenten erreichbar, und ihre Antworten melden aus demselben Grund dieselbe Reichweite. Wo ein Assistent sie in Ihrem Namen aufrufen darf, siehe aggrega mcp.
Ein Link im Artefakt-Cache
Das Verzeichnis des Artefakt-Caches ist der einzige Ort, aus dem alles im Cache gelesen, in den es geschrieben und aus dem es entfernt wird — der Standard .aggrega/cache ebenso wie ein Verzeichnis, das artifact_cache_dir nennt und das aus dem Workspace-Stammverzeichnis herausführt (../shared-cache). Alles darin, was ein symbolischer Link ist, der aus diesem Verzeichnis herausführt — eines der eigenen Verzeichnisse des Caches, etwa .aggrega/cache/inputs, oder eine Datei darin —, wird weder zum Lesen, Schreiben noch Entfernen durchlaufen, selbst wenn der Link zu einem anderen Verzeichnis desselben Workspace führt. Was ein Schreibvorgang unterhalb des Cache-Verzeichnisses erreichen darf, ist genau das, was ein Entfernen erreichen darf.
- Ein Pull, ein Build und jeder andere Vorgang, der in den Cache schreibt, halten mit
E0320an, nennen den Link und wohin er führt, und schreiben nichts. status,pruneundclearlisten nichts über einen solchen Link auf. Wenn eines der eigenen Verzeichnisse des Caches der Link ist, hältstatusmitE0321an, und einpruneoder einclearhält mitE0320an, bevor es etwas auflistet oder entfernt — so wird nichts entfernt, worauf der Link zeigt, und der Link bleibt, wo er ist. Wenn eine Datei darin der Link ist, halten alle drei mitE0321an.- Ein Build, ein Pull und jeder andere Vorgang, der den Cache liest, halten mit
E0321an, statt anderswo aufbewahrte Bytes zu lesen, selbst wenn diese Bytes dem Digest entsprächen, den die Lockfile aufzeichnet. - Einem Link, der innerhalb des Cache-Verzeichnisses bleibt, wird gefolgt. Wenn eines der eigenen Verzeichnisse des Caches ein Link auf ein anderes Verzeichnis innerhalb des Cache-Verzeichnisses ist, gehört dieses Verzeichnis dem Cache:
statuslistet auf, was dort liegt,pruneentfernt von dort, undclearleert es, behält den Link und meldet die Bytes, die es dort entfernt hat.
Das Cache-Verzeichnis selbst. Ein artifact_cache_dir, das innerhalb des Workspace-Stammverzeichnisses geschrieben ist — den Standard eingeschlossen —, darf selbst ein Link auf ein anderes Verzeichnis des Workspace sein, und der Cache wird dann dort aufbewahrt, wohin der Link führt. Einer, der aus dem Workspace herausführt, wird abgelehnt: Welcher Vorgang auch immer darauf trifft, hält mit E0321 oder E0320 an und nennt den Link, bevor irgendetwas darüber gelesen oder geschrieben wird. Ein Verzeichnis, das so geschrieben ist, dass es aus dem Workspace-Stammverzeichnis herausführt, wird dort beachtet, wohin es führt, selbst wenn es selbst ein Link ist.
Entfernen Sie den Link und führen Sie erneut einen Pull aus, um den Cache an Ort und Stelle zu befüllen. Um den Cache woanders aufzubewahren, setzen Sie artifact_cache_dir auf dieses Verzeichnis, relativ zum Workspace-Stammverzeichnis geschrieben, statt darauf zu verlinken: Ein dort genanntes Verzeichnis wird dort gelesen und beschrieben, wohin es führt. Die maschinenweiten Speicher sind an keinen Workspace gebunden; einer, den Sie über einen Link woanders aufbewahren, wird dort aufgelistet, bereinigt und geleert, wohin der Link führt, und clear behält den Link. Die Workspace-Grenze gibt die Regel vollständig an.
Siehe auch
aggrega-pull— die Abhängigkeiten eines Release in die Lockfile und den Cache auflösen.aggrega-config— woartifact_cache_dirund die anderen Cache-Einstellungen geschrieben werden.