Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

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 (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.

Флаги aggrega cache clear

ФлагПо умолчаниюОписание
--yesfalseпропустить запрос подтверждения (для неинтерактивного использования и CI)

Описание 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.

Флаги 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 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.

Описание 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.

Что такое кэш и чем он не является

Кэш артефактов в 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 и другие настройки кэша.