aggrega cache
Инспекция и обслуживание кэшей на диске
Синтаксис
aggrega cacheОписание
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.Подкоманды
| Команда | Описание |
|---|---|
aggrega cache clear | Очистить все кэши, включая скомпилированные модули |
aggrega cache evict | Сократить кэш скомпилированных модулей до предельного размера, начиная с самых старых |
aggrega cache prune | Удалить записи кэша артефактов, на которые не ссылается ни один lockfile |
aggrega cache status | Вывести содержимое кэша и общую сводку |
Описание 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.Флаги aggrega cache clear
| Флаг | По умолчанию | Описание |
|---|---|---|
--yes | false | пропустить запрос подтверждения (для неинтерактивного использования и CI) |
Описание 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.Флаги aggrega cache evict
| Флаг | По умолчанию | Описание |
|---|---|---|
--max-size | — | предельный размер кэша скомпилированных модулей (например, 5GiB, 512MiB или число байтов); обязательный |
Описание 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.Описание 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.Что такое кэш и чем он не является
Кэш артефактов в artifact_cache_dir (по умолчанию .aggrega/cache) содержит то, что туда поместила загрузка: сущности каталога и исходные артефакты, каждый из которых хранится под своим видом, а также координатой и версией, с которыми он был загружен, и подтверждён дайджестом, записанным в lockfile. Это не каталог сущностей, и сканирование каталогов его пропускает — поэтому содержимое кэша читается как зависимость, через закрепление, которое его подтверждает, и никогда как сущность, созданная вами.
Последствие, с которым вы, скорее всего, столкнётесь. Если в кэше есть сущность, которую не закрепляет ни один lockfile, эта сущность невидима для сборки, и сборка, которой она нужна, останавливается с сообщением, что она не найдена. В сообщении об остановке указана сущность, поэтому по нему можно определить, какого закрепления не хватает.
Если сущность — это SchemaLibrary, до которой доходит $ref:, каждая команда, сообщающая о ссылке как о неразрешённой, дополняет сообщение строкой remediation:, которая называет каждую библиотеку в кеше, которую не закрепляет ни одна запись lock-файла и не предоставляет ни один каталог сущностей, а также действие, которое работает для этой команды:
aggrega buildиaggrega validate --release <release>читают lock-файл сущности Release, поэтому строка называетaggrega pull --release <release>, чтобы разрешить библиотеку и зафиксировать её запись.aggrega validateбез аргументов иaggrega validate <entity-path>с--releaseили без него читают библиотеки только из каталогов сущностей и не читают lock-файл, поэтому ни одна зафиксированная запись не меняет их вердикт. Строка сообщает об этом и называетaggrega pull --release <release>, а затемaggrega validate --release <release>, которая проверяет сущность Release по тому, что закрепляет её lock-файл.aggrega pullиaggrega build --auto-pullв автономном режиме не могут ни загрузить библиотеку, ни записать для неё запись, поэтому строка предлагает выполнитьaggrega pull --release <release>там, где доступен реестр. При наличии подключения pull, который не находит библиотеку ни в одном каталоге сущностей и ни в одном реестре, который он читает, не имеет записи, которую можно было бы зафиксировать.
Каждая из этих строк также предлагает другой выход: создать библиотеку в каталоге сущностей.
Что запустить. aggrega pull --release <release> разрешает сущность и записывает её дайджест, после чего та же сборка её находит. Если сущность ваша, а не зависимость, создайте её вместо этого в каталоге, указанном в workspace.catalog_dirs, — сканирование его читает. aggrega cache prune удаляет записи, на которые не ссылается ни один lockfile; это вторая, наводящая порядок, половина того же правила.
Структура кэша, контракт artifact_cache_dir и причины, по которым артефакт разрешения намеренно не читается как созданное содержимое, описаны в architecture/13-catalog-and-registry.md.
Какие кэши принадлежат этому проекту, а какие — машине
Не каждый кэш, с которым работают эти команды, ограничен проектом, в котором вы находитесь, и от этого различия зависит, насколько далеко распространяется освобождение места.
Только ваш. Кэш артефактов в artifact_cache_dir — сущности, исходные артефакты и закреплённые внешние входные данные, которые разрешил этот проект, а также снимки опубликованного каталога, прочитанные импортом, который не указывает ни одной папки каталога. Освобождение места в нём затрагивает этот проект и ничего больше.
Общие для всех проектов Aggrega на этой машине. Хранилище скомпилированных модулей, хранилище описаний плагинов, хранилище пакетов документации и хранилище cli-плагинов. Гостевой модуль провайдера компилируется один раз и повторно используется всеми проектами — именно поэтому вторая сборка чего угодно выполняется быстро, — поэтому удаление записи означает, что следующая сборка любого проекта на машине перекомпилирует его. Пакет документации — опубликованные страницы, из которых читают aggrega explain, пояснения редактора и ресурсы документации ассистента, а также запускаемые примеры, которые записывает aggrega scaffold --example, — хранится один раз на каждый реестр и версию, поскольку его содержимое ни от чего больше не зависит: кто из них загрузит его первым, тот загружает его для всех проектов, и каждому проекту он всё равно выдаётся только после того, как его собственная проверка подписи допустит копию. Ничего не теряется безвозвратно — удалённый модуль пересобирается по требованию, а удалённый пакет загружается снова при следующем пояснении или примере либо сервером ассистента при его следующем запуске, — но затраты ложатся на того, кто выполняет сборку следующим, и это можете быть не вы.
Хранилище cli-плагинов хранит байты каждого cli-плагина, добавленного с помощью aggrega plugin add cli в папке, которая не является рабочим пространством, поэтому его команда запускается из любой папки; cli-плагин, добавленный внутри рабочего пространства, вместо этого хранит свои байты в кэше артефактов этого рабочего пространства. В отличие от скомпилированного модуля или пакета, cli-плагин, байты которого удалены, не загружается снова сам по себе: пока aggrega plugin add cli <name> не добавит его снова, его команда отсутствует, и каждая команда предупреждает, что его не удалось добавить, называя команду aggrega plugin add cli, которая снова добавляет его в версии, закреплённой вашей конфигурацией.
Общие для машины хранилища размещаются там, где каждая платформа хранит кэши пользователя: в Windows — в aggrega\cache внутри каталога, который указывает переменная окружения LOCALAPPDATA, в macOS — в ~/Library/Caches/aggrega, а в Linux и других системах Unix — в каталоге aggrega внутри каталога, который указывает XDG_CACHE_HOME (~/.cache/aggrega, если XDG_CACHE_HOME не задана). aggrega config init выводит этот каталог на машине, где она запущена. Если ни одна из этих переменных не задана, скомпилированные плагины хранятся только в течение запуска, а пакет документации не хранится вовсе: пояснение тогда сообщает, почему в нём нет пошагового описания, ресурсы документации ассистента отвечают «не найдено», а aggrega scaffold --example отказывается выполняться, сообщая, что каталог кэша не определяется; aggrega plugin add cli, запущенная в папке, которая не является рабочим пространством, также отказывается выполняться, сообщая, что расположение кэша уровня машины не определяется.
aggrega cache status сообщает это для каждого класса, а не оставляет выводить это из имени: о каждом классе сообщается, охватывает ли он рабочую область или машину, и такой же охват сообщается для каждого элемента, который удаляют prune, evict и clear. evict действует только на общее хранилище скомпилированных модулей; prune никогда не удаляет пакет документации или снимок каталога, прочитанный импортом, поскольку ни один lock-файл не ссылается ни на то, ни на другое, и сообщает, что каждый такой класс не подлежит очистке через prune; prune сохраняет байты каждого cli-плагина, закреплённого списком plugins.cli вашей конфигурации, — как в хранилище cli-плагинов, так и в кэше артефактов рабочей области, вместе с его записью в хранилище описаний плагинов, — и удаляет те, которые не названы ни в одном закреплении; clear действует на всё, поэтому перед началом запрашивает подтверждение.
Корень рабочего пространства, который нельзя использовать. Если переданный команде корень рабочего пространства — это файл или несуществующий путь, status, evict и clear действуют только на общемашинные хранилища, завершаются так же, как завершились бы иначе, и сообщают об этом в стандартный поток ошибок теми же словами, которыми любая другая команда отклоняет этот корень:
note: —workspace-root names the workspace root
"<root>", which is not a directory:<root>; only the machine-wide caches are acted on (примечание: —workspace-root указывает корень рабочего пространства, который не является каталогом; действие выполняется только над общемашинными кешами)
Для несуществующего пути вместо which is not a directory: выводится which cannot be used: и причина. prune вместо этого останавливается, поскольку ему нужны lockfile рабочего пространства.
Это относится к любому месту вызова операции, а не только к терминалу. Те же операции доступны из сеанса редактора и из вызова инструмента ассистентом, и их ответы содержат тот же охват по той же причине. О том, когда ассистент может вызывать их от вашего имени, см. aggrega mcp.
Ссылка в кэше артефактов
Каталог кэша артефактов — единственное место, из которого всё содержимое кэша читается, в которое записывается и из которого удаляется, — как каталог по умолчанию .aggrega/cache, так и каталог, заданный в artifact_cache_dir и выходящий за пределы корня рабочего пространства (../shared-cache). Всё, что в нём является символической ссылкой, ведущей за пределы этого каталога, — будь то один из собственных каталогов кэша, например .aggrega/cache/inputs, или файл внутри него, — не используется для чтения, записи или удаления, даже если ссылка ведёт в другой каталог того же рабочего пространства. Запись внутри каталога кэша может затронуть ровно то же, что и удаление.
- Загрузка (pull), сборка и любая другая операция, записывающая в кэш, останавливаются с ошибкой
E0320, указывая ссылку и то, куда она ведёт, и ничего не записывают. status,pruneиclearничего не перечисляют через такую ссылку. Если ссылкой является один из собственных каталогов кэша,statusостанавливается с ошибкойE0321, аpruneилиclearостанавливается с ошибкойE0320прежде, чем что-либо перечислить или удалить, — поэтому ничего из того, на что указывает ссылка, не удаляется, и сама ссылка остаётся на месте. Если ссылкой является файл внутри такого каталога, все три команды останавливаются с ошибкойE0321.- Сборка, загрузка (pull) и любая другая операция, читающая кэш, останавливаются с ошибкой
E0321, а не читают байты, хранящиеся в другом месте, даже если эти байты совпали бы с дайджестом, записанным в lock-файле. - Ссылка, остающаяся внутри каталога кэша, разрешается. Если один из собственных каталогов кэша является ссылкой на другой каталог внутри каталога кэша, этот каталог считается каталогом кэша:
statusперечисляет его содержимое,pruneудаляет из него, аclearочищает его, сохраняет ссылку и сообщает, сколько байтов там удалено.
Сам каталог кэша. Каталог artifact_cache_dir, заданный внутри корня рабочего пространства, — включая каталог по умолчанию, — сам может быть ссылкой на другой каталог рабочего пространства, и тогда кэш хранится там, куда ведёт ссылка. Ссылка, ведущая за пределы рабочего пространства, отвергается: любая операция, встретившая её, останавливается с ошибкой E0321 или E0320, указывая ссылку, прежде чем что-либо будет прочитано или записано через неё. Каталог, заданный с выходом за пределы корня рабочего пространства, используется там, куда он ведёт, даже если сам является ссылкой.
Удалите ссылку и снова выполните загрузку (pull), чтобы заполнить кэш на месте. Чтобы хранить кэш в другом месте, задайте в artifact_cache_dir этот каталог относительно корня рабочего пространства, а не создавайте на него ссылку: указанный там каталог читается и записывается там, куда он ведёт. Общие для машины хранилища не привязаны ни к какому рабочему пространству; хранилище, которое вы держите в другом месте через ссылку, перечисляется, очищается командой prune и командой clear там, куда ведёт ссылка, а clear сохраняет ссылку. Граница рабочего пространства излагает это правило целиком.
См. также
aggrega-pull— разрешение зависимостей сущности Release в lockfile и кэш.aggrega-config— где задаютсяartifact_cache_dirи другие настройки кэша.