Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

aggrega cache

Inspecter et entretenir les caches sur disque

Synopsis

aggrega cache

Description

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.

Sous-commandes

CommandeDescription
aggrega cache clearEfface tous les caches, y compris les modules compilés
aggrega cache evictRéduit le cache des modules compilés à une taille maximale, en commençant par les plus anciens
aggrega cache pruneSupprime les entrées du cache d’artefacts qu’aucun lockfile ne référence
aggrega cache statusListe le contenu du cache et un résumé total

Description de 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.

Options de aggrega cache clear

OptionPar défautDescription
--yesfalseignore l’invite de confirmation (pour un usage non interactif/CI)

Description de 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.

Options de aggrega cache evict

OptionPar défautDescription
--max-size—taille maximale du cache des modules compilés (par ex. 5GiB, 512MiB ou un nombre d’octets) ; obligatoire

Description de 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.

Description de 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.

Ce qu’est le cache, et ce qu’il n’est pas

Le cache d’artefacts sous artifact_cache_dir (.aggrega/cache par défaut) contient ce qu’une récupération y a placé : des entités de catalogue et des artefacts sources, chacun stocké sous son type ainsi que la coordonnée et la version auxquelles il a été récupéré, et garanti par un digest que le lockfile enregistre. Ce n’est pas un répertoire de catalogue, et une analyse du catalogue le contourne — le contenu présent dans le cache est donc lu comme une dépendance, par le pin qui le garantit, et jamais comme une entité que vous avez écrite.

La conséquence que vous rencontrerez le plus probablement. Si le cache contient une entité qu’aucun lockfile n’épingle, cette entité est invisible pour un build, et un build qui en a besoin s’arrête en indiquant qu’elle est introuvable. L’arrêt nomme l’entité, de sorte que le pin manquant est identifiable à partir du message.

Lorsque l’entité est une SchemaLibrary qu’atteint un $ref:, chaque commande qui signale la référence comme non résolue fait suivre son signalement d’une ligne remediation: nommant chaque bibliothèque présente dans le cache qu’aucune entrée de lockfile n’épingle et qu’aucun répertoire de catalogue ne fournit, ainsi que l’action qui fonctionne pour cette commande :

  • aggrega build et aggrega validate --release <release> lisent le lockfile de la Release ; la ligne nomme donc aggrega pull --release <release> pour résoudre la bibliothèque et enregistrer son entrée.
  • aggrega validate sans argument, et aggrega validate <entity-path> avec ou sans --release, lisent les bibliothèques uniquement depuis les répertoires de catalogue et ne lisent aucun lockfile, si bien qu’aucune entrée enregistrée ne change leur verdict. La ligne le dit, et nomme aggrega pull --release <release> suivi de aggrega validate --release <release>, qui vérifie la Release par rapport à ce que son lockfile épingle.
  • aggrega pull, et aggrega build --auto-pull, en mode hors ligne, ne peuvent ni récupérer la bibliothèque ni enregistrer d’entrée pour elle ; la ligne indique donc d’exécuter aggrega pull --release <release> là où un registre est joignable. En ligne, un pull qui ne trouve la bibliothèque dans aucun répertoire de catalogue ni dans aucun registre qu’il lit n’a aucune entrée à enregistrer.

Chacune de ces lignes propose aussi l’autre solution : écrire la bibliothèque dans un répertoire de catalogue.

Ce qu’il faut exécuter. aggrega pull --release <release> résout l’entité et enregistre son digest, après quoi le même build la trouve. Lorsque l’entité est la vôtre plutôt qu’une dépendance, écrivez-la plutôt sous un répertoire listé dans workspace.catalog_dirs — une analyse lit celui-ci. aggrega cache prune élimine les entrées qu’aucun lockfile ne référence, ce qui est la moitié « rangement » de la même règle.

Pour la structure du cache, le contrat de artifact_cache_dir et la raison pour laquelle un artefact de résolution n’est délibérément pas lisible comme contenu écrit, voir architecture/13-catalog-and-registry.md.

Quels caches appartiennent à ce projet, et lesquels à la machine

Tous les caches sur lesquels agissent ces commandes ne sont pas limités au projet dans lequel vous vous trouvez, et la différence détermine jusqu’où s’étend une récupération d’espace.

À vous seul. Le cache d’artefacts sous artifact_cache_dir — les entités, les artefacts sources et les entrées externes épinglées que ce projet a résolus, ainsi que les instantanés du catalogue publié qu’a lus une importation n’indiquant aucun dossier de catalogue. Y récupérer de l’espace affecte ce projet et rien d’autre.

Partagés par tous les projets Aggrega de cette machine. Le magasin des modules compilés, le magasin des descriptions de plugins, le magasin des bundles de documentation et le magasin des plugins cli. Un guest de provider est compilé une fois et réutilisé par tous les projets, ce qui rend rapide le deuxième build de n’importe quoi ; supprimer une entrée signifie donc que le prochain build de n’importe quel projet de la machine le recompile. Le bundle de documentation — les pages publiées à partir desquelles aggrega explain, les explications d’un éditeur et les ressources de documentation d’un assistant sont lues, et les exemples exécutables que aggrega scaffold --example écrit — est conservé une seule fois par registre et par version, car son contenu ne dépend de rien d’autre : le premier d’entre eux qui le récupère le récupère pour tous les projets, et chaque projet ne le reçoit toutefois qu’une fois que sa propre vérification de signature admet la copie. Rien n’est perdu définitivement — un module supprimé est reconstruit à la demande, et un bundle supprimé est récupéré à nouveau par l’explication ou l’exemple suivant, ou par un serveur d’assistant à son prochain démarrage —, mais le coût retombe sur celui qui construit ensuite, qui n’est peut-être pas vous.

Le magasin des plugins cli contient les octets de chaque plugin cli ajouté avec aggrega plugin add cli dans un dossier qui n’est pas un workspace, de sorte que sa commande s’exécute depuis n’importe quel dossier ; un plugin cli ajouté à l’intérieur d’un workspace conserve plutôt ses octets dans le cache d’artefacts de ce workspace. Contrairement à un module compilé ou à un bundle, un plugin cli dont les octets sont supprimés n’est pas récupéré à nouveau de lui-même : tant que aggrega plugin add cli <name> ne l’a pas ajouté à nouveau, sa commande est absente et chaque commande avertit qu’il n’a pas pu être ajouté, en nommant la commande aggrega plugin add cli qui l’ajoute à nouveau à la version qu’épingle votre configuration.

Les magasins à l’échelle de la machine sont conservés là où chaque plateforme conserve les caches d’un utilisateur : sous Windows dans aggrega\cache à l’intérieur du répertoire que nomme la variable d’environnement LOCALAPPDATA, sous ~/Library/Caches/aggrega sur macOS, et dans un répertoire aggrega à l’intérieur de celui que nomme XDG_CACHE_HOME — ~/.cache/aggrega lorsque XDG_CACHE_HOME n’est pas définie — sur Linux et les autres systèmes Unix. aggrega config init affiche le répertoire sur la machine où il s’exécute. Lorsqu’aucune de ces variables n’est définie, les plugins compilés ne sont conservés que pour l’exécution, et aucun bundle de documentation n’est conservé : une explication indique alors pourquoi son guide pas à pas manque, les ressources de documentation d’un assistant répondent « introuvable », et aggrega scaffold --example refuse, en indiquant qu’aucun répertoire de cache ne se résout ; aggrega plugin add cli exécuté dans un dossier qui n’est pas un workspace refuse également, en indiquant qu’aucun emplacement de cache à l’échelle de la machine ne se résout.

aggrega cache status l’indique par classe plutôt que de le laisser déduire du nom : chaque classe est signalée comme couvrant le workspace ou la machine, et la même portée est signalée pour chaque élément que prune, evict et clear suppriment. evict n’agit que sur le magasin partagé des modules compilés ; prune ne supprime jamais un bundle de documentation ni un instantané de catalogue qu’une importation a lu, puisqu’aucun lockfile ne référence l’un ou l’autre, et signale chacune de ces classes comme non éligible au prune ; prune conserve les octets de chaque plugin cli qu’épingle la liste plugins.cli de votre configuration — dans le magasin des plugins cli comme dans le cache d’artefacts du workspace, avec son entrée de description de plugin — et supprime ceux qu’aucun épinglage ne nomme ; clear agit sur tout, c’est pourquoi il demande confirmation avant de commencer.

Une racine de workspace inutilisable. Lorsque la racine de workspace donnée à la commande est un fichier ou un chemin qui n’existe pas, status, evict et clear n’agissent que sur les magasins à l’échelle de la machine, se terminent comme ils le feraient autrement et le signalent sur la sortie d’erreur standard, dans les termes mêmes par lesquels toute autre commande refuse cette racine :

note: —workspace-root names the workspace root "<root>", which is not a directory: <root>; only the machine-wide caches are acted on (remarque : —workspace-root désigne une racine de workspace qui n’est pas un répertoire ; seuls les caches à l’échelle de la machine sont traités)

Un chemin qui n’existe pas affiche which cannot be used: et la raison à la place de which is not a directory:. prune s’arrête en revanche, puisqu’il a besoin des lockfiles du workspace.

Ceci s’applique quel que soit l’endroit d’où l’opération est invoquée, pas seulement dans un terminal. Les mêmes opérations sont accessibles depuis une session d’éditeur et depuis l’appel d’outil d’un assistant, et leurs réponses indiquent la même portée pour la même raison. Lorsqu’un assistant peut les invoquer en votre nom, voir aggrega mcp.

Le répertoire du cache d’artefacts est le seul endroit depuis lequel tout ce qui se trouve dans le cache est lu, dans lequel il est écrit et duquel il est supprimé — aussi bien le .aggrega/cache par défaut qu’un répertoire nommé par artifact_cache_dir qui remonte au-delà de la racine du workspace (../shared-cache). Tout ce qui s’y trouve et qui est un lien symbolique menant hors de ce répertoire — l’un des répertoires propres du cache, comme .aggrega/cache/inputs, ou un fichier à l’intérieur de l’un d’eux — n’est ni lu, ni écrit, ni supprimé à travers ce lien, même lorsque le lien mène à un autre répertoire du même workspace. Ce qu’une écriture peut atteindre sous le répertoire du cache est exactement ce qu’une suppression peut atteindre.

  • Un pull, un build et toute autre opération qui écrit dans le cache s’arrêtent avec E0320, en nommant le lien et l’endroit où il mène, et n’écrivent rien.
  • status, prune et clear ne listent rien à travers un tel lien. Lorsque l’un des répertoires propres du cache est le lien, status s’arrête avec E0321, et un prune ou un clear s’arrête avec E0320 avant de lister ou de supprimer quoi que ce soit — ainsi rien de ce vers quoi pointe le lien n’est supprimé, et le lien reste en place. Lorsque c’est un fichier à l’intérieur de l’un d’eux qui est le lien, les trois s’arrêtent avec E0321.
  • Un build, un pull et toute autre opération qui lit le cache s’arrêtent avec E0321 plutôt que de lire des octets conservés ailleurs, même lorsque ces octets correspondraient au digest que le lockfile enregistre.
  • Un lien qui reste à l’intérieur du répertoire du cache est suivi. Lorsque l’un des répertoires propres du cache est un lien vers un autre répertoire à l’intérieur du répertoire du cache, ce répertoire appartient au cache : status liste ce qui s’y trouve, prune y supprime, et clear le vide, conserve le lien et signale les octets qu’il y a supprimés.

Le répertoire du cache lui-même. Un artifact_cache_dir écrit à l’intérieur de la racine du workspace — y compris la valeur par défaut — peut lui-même être un lien vers un autre répertoire du workspace, et le cache est alors conservé là où mène le lien. Un lien qui mène hors du workspace est refusé : quelle que soit l’opération qui le rencontre, elle s’arrête avec E0321 ou E0320, en nommant le lien, avant que quoi que ce soit ne soit lu ou écrit à travers lui. Un répertoire écrit en remontant au-delà de la racine du workspace est respecté là où il mène, même lorsqu’il est lui-même un lien.

Supprimez le lien et refaites un pull pour remplir le cache sur place. Pour conserver le cache ailleurs, définissez artifact_cache_dir sur ce répertoire, écrit relativement à la racine du workspace, plutôt que de créer un lien vers lui : un répertoire nommé là est lu et écrit là où il mène. Les magasins à l’échelle de la machine ne sont rattachés à aucun workspace ; un magasin que vous conservez ailleurs au moyen d’un lien est listé, nettoyé et vidé là où mène le lien, et clear conserve le lien. La frontière du workspace énonce la règle dans son ensemble.

Voir aussi

  • aggrega-pull — résout les dépendances d’une Release dans le lockfile et le cache.
  • aggrega-config — où s’écrivent artifact_cache_dir et les autres paramètres du cache.