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) містить те, що туди помістило завантаження: сутності каталогу й вихідні артефакти, кожен з яких зберігається за своїм видом, а також за координатою та версією, з якими його було завантажено, і засвідчений дайджестом, який записує lock-файл. Це не каталог із сутностями, і сканування каталогів його оминає — тож вміст кешу читається як залежність, через закріплення, що його засвідчує, і ніколи як сутність, яку створили ви.
Наслідок, з яким ви найімовірніше зіткнетеся. Якщо кеш містить сутність, яку не закріплює жоден lock-файл, ця сутність невидима для збірки, і збірка, якій вона потрібна, зупиняється з повідомленням, що її не знайдено. Зупинка називає сутність, тож відсутнє закріплення можна визначити з повідомлення.
Якщо сутність — це 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 вилучає записи, на які не посилається жоден lock-файл, — це прибиральна половина того самого правила.
Про структуру кешу, контракт 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 ніколи не видаляє пакет документації чи знімок каталогу, який прочитав імпорт, оскільки жоден lockfile не посилається ні на те, ні на інше, і повідомляє, що кожен такий клас не підлягає очищенню; 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, називаючи посилання, ще до того, як через нього щось буде прочитано чи записано. Каталог, записаний так, що виходить за межі кореня робочого простору, використовується там, куди він веде, навіть якщо сам є посиланням.
Видаліть посилання й виконайте отримання ще раз, щоб заповнити кеш на місці. Щоб зберігати кеш деінде, задайте в artifact_cache_dir цей каталог, записаний відносно кореня робочого простору, замість створювати на нього посилання: вказаний там каталог читається й записується там, куди він веде. Загальномашинні сховища не прив’язані до жодного робочого простору; сховище, яке ви зберігаєте деінде через посилання, виводиться, очищується (prune) і спорожнюється там, куди веде посилання, а clear зберігає посилання. Межа робочого простору викладає це правило повністю.
Див. також
aggrega-pull— розв’язує залежності сутності Release у lockfile і кеш.aggrega-config— де задаютьсяartifact_cache_dirта інші налаштування кешу.