aggrega cache
Przegląda i utrzymuje pamięci podręczne na dysku
Składnia
aggrega cacheOpis
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.Podpolecenia
| Polecenie | Opis |
|---|---|
aggrega cache clear | Czyści wszystkie pamięci podręczne, w tym skompilowane moduły |
aggrega cache evict | Przycina pamięć podręczną skompilowanych modułów do limitu rozmiaru, zaczynając od najstarszych |
aggrega cache prune | Usuwa wpisy pamięci podręcznej artefaktów, do których nie odwołuje się żaden plik blokady |
aggrega cache status | Wyświetla zawartość pamięci podręcznej i łączne podsumowanie |
Opis 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.Flagi aggrega cache clear
| Flaga | Domyślnie | Opis |
|---|---|---|
--yes | false | pomija monit o potwierdzenie (do użycia nieinteraktywnego/w CI) |
Opis 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.Flagi aggrega cache evict
| Flaga | Domyślnie | Opis |
|---|---|---|
--max-size | — | limit rozmiaru pamięci podręcznej skompilowanych modułów (np. 5GiB, 512MiB lub liczba bajtów); wymagana |
Opis 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.Opis 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.Czym jest pamięć podręczna, a czym nie jest
Pamięć podręczna artefaktów w artifact_cache_dir (domyślnie .aggrega/cache) przechowuje to, co umieściło w niej pobieranie: encje katalogu i artefakty źródłowe, każdy zapisany pod swoim rodzajem oraz współrzędną i wersją, w której został pobrany, i poświadczony skrótem zapisanym w pliku blokady. Nie jest to katalog z encjami, a skanowanie katalogów ją pomija — dlatego zawartość pamięci podręcznej jest odczytywana jako zależność, poprzez przypięcie, które ją poświadcza, a nigdy jako encja utworzona przez autora.
Konsekwencja, którą najłatwiej napotkać. Jeśli pamięć podręczna zawiera encję, której nie przypina żaden plik blokady, encja ta jest niewidoczna dla kompilacji, a kompilacja, która jej potrzebuje, zatrzymuje się z komunikatem, że jej nie znaleziono. Zatrzymanie podaje nazwę encji, więc brakujące przypięcie można zidentyfikować na podstawie komunikatu.
Gdy chodzi o encję SchemaLibrary, do której sięga $ref:, każde polecenie zgłaszające odwołanie jako nierozwiązane dodaje po zgłoszeniu wiersz remediation: wymieniający każdą bibliotekę przechowywaną w pamięci podręcznej, której nie przypina żaden wpis pliku blokady i której nie dostarcza żaden katalog encji, oraz działanie skuteczne dla tego polecenia:
aggrega buildiaggrega validate --release <release>odczytują plik blokady encji Release, więc wiersz podajeaggrega pull --release <release>, aby rozwiązać bibliotekę i zapisać jej wpis.aggrega validatebez argumentu orazaggrega validate <entity-path>z--releaselub bez niego odczytują biblioteki wyłącznie z katalogów encji i nie odczytują żadnego pliku blokady, więc żaden zapisany wpis nie zmienia ich werdyktu. Wiersz to stwierdza i podajeaggrega pull --release <release>, a po nimaggrega validate --release <release>, które sprawdza encję Release względem tego, co przypina jej plik blokady.aggrega pullorazaggrega build --auto-pullw trybie offline nie mogą ani pobrać biblioteki, ani zapisać dla niej wpisu, więc wiersz każe uruchomićaggrega pull --release <release>tam, gdzie da się dotrzeć do rejestru. Przy połączeniu pull, który nie znajduje biblioteki w żadnym katalogu encji ani w żadnym odczytywanym przez siebie rejestrze, nie ma żadnego wpisu do zapisania.
Każdy z tych wierszy proponuje też drugie wyjście: utworzyć bibliotekę w katalogu encji.
Co uruchomić. aggrega pull --release <release> rozwiązuje encję i zapisuje jej skrót, po czym ta sama kompilacja ją odnajduje. Jeśli encja jest własna, a nie jest zależnością, należy zamiast tego utworzyć ją w katalogu wymienionym w workspace.catalog_dirs — skanowanie go odczytuje. aggrega cache prune usuwa wpisy, do których nie odwołuje się żaden plik blokady, co stanowi porządkującą połowę tej samej zasady.
Układ pamięci podręcznej, kontrakt artifact_cache_dir oraz powód, dla którego artefakt rozwiązywania celowo nie jest odczytywany jako treść autorska, opisano w architecture/13-catalog-and-registry.md.
Które pamięci podręczne należą do tego projektu, a które do maszyny
Nie każda pamięć podręczna, na której działają te polecenia, jest ograniczona do projektu, w którym się pracuje, a ta różnica decyduje o tym, jak daleko sięga odzyskiwanie miejsca.
Tylko dla tego projektu. Pamięć podręczna artefaktów w artifact_cache_dir — encje, artefakty źródłowe i przypięte wejścia zewnętrzne, które ten projekt rozwiązał, oraz migawki opublikowanego katalogu odczytane przez import, który nie wskazuje żadnego folderu katalogu. Odzyskiwanie z niej miejsca dotyczy tego projektu i niczego więcej.
Wspólne dla wszystkich projektów Aggrega na tej maszynie. Magazyn skompilowanych modułów, magazyn opisów pluginów, magazyn pakietów dokumentacji i magazyn pluginów cli. Gość dostawcy jest kompilowany raz i ponownie używany przez każdy projekt, dzięki czemu druga kompilacja czegokolwiek jest szybka, więc usunięcie wpisu oznacza, że następna kompilacja dowolnego projektu na tej maszynie skompiluje go ponownie. Pakiet dokumentacji — opublikowane strony, z których odczytywane są aggrega explain, objaśnienia edytora i zasoby dokumentacji asystenta, oraz uruchamialne przykłady, które zapisuje aggrega scaffold --example — jest przechowywany raz na rejestr i wersję, ponieważ jego zawartość nie zależy od niczego innego: którekolwiek z nich pobierze go pierwsze, pobiera go dla każdego projektu, a każdy projekt otrzymuje go dopiero wtedy, gdy jego własna weryfikacja podpisu dopuści tę kopię. Nic nie ginie bezpowrotnie — usunięty moduł jest odbudowywany na żądanie, a usunięty pakiet jest pobierany ponownie przy następnym objaśnieniu lub przykładzie albo przez serwer asystenta przy jego następnym uruchomieniu — ale koszt ponosi ten, kto kompiluje jako następny, a to nie musi być ta sama osoba.
Magazyn pluginów cli przechowuje bajty każdego pluginu cli dodanego za pomocą aggrega plugin add cli w folderze, który nie jest obszarem roboczym, dzięki czemu jego polecenie działa z dowolnego folderu; plugin cli dodany wewnątrz obszaru roboczego przechowuje natomiast swoje bajty w pamięci podręcznej artefaktów tego obszaru roboczego. W odróżnieniu od skompilowanego modułu czy pakietu plugin cli, którego bajty zostały usunięte, nie jest samoczynnie pobierany ponownie: dopóki aggrega plugin add cli <name> nie doda go ponownie, jego polecenia brakuje, a każde polecenie ostrzega, że nie można go było dodać, i podaje polecenie aggrega plugin add cli, które dodaje go ponownie w wersji przypiętej w konfiguracji.
Magazyny ogólnomaszynowe są przechowywane tam, gdzie każda platforma przechowuje pamięci podręczne użytkownika: w systemie Windows w aggrega\cache wewnątrz katalogu wskazanego przez zmienną środowiskową LOCALAPPDATA, w ~/Library/Caches/aggrega w systemie macOS, a w katalogu aggrega wewnątrz katalogu wskazanego przez XDG_CACHE_HOME — ~/.cache/aggrega, gdy XDG_CACHE_HOME nie jest ustawiona — w systemie Linux i innych systemach Unix. aggrega config init wypisuje ten katalog na maszynie, na której zostało uruchomione. Gdy żadna z tych zmiennych nie jest ustawiona, skompilowane pluginy są przechowywane tylko na czas uruchomienia, a żaden pakiet dokumentacji nie jest przechowywany: objaśnienie podaje wtedy, dlaczego brakuje jego omówienia, zasoby dokumentacji asystenta odpowiadają „nie znaleziono”, a aggrega scaffold --example odmawia, informując, że nie można ustalić żadnego katalogu pamięci podręcznej; aggrega plugin add cli uruchomione w folderze, który nie jest obszarem roboczym, również odmawia, informując, że nie można ustalić żadnej ogólnomaszynowej lokalizacji pamięci podręcznej.
aggrega cache status podaje to dla każdej klasy, zamiast pozostawiać wnioskowanie z nazwy: każda klasa jest raportowana jako obejmująca obszar roboczy lub maszynę, a ten sam zasięg jest raportowany dla każdego elementu usuwanego przez prune, evict i clear. evict działa tylko na wspólnym magazynie skompilowanych modułów; prune nigdy nie usuwa pakietu dokumentacji ani migawki katalogu odczytanej przez import, ponieważ żaden plik blokady nie odwołuje się do żadnego z nich, i raportuje każdą taką klasę jako niekwalifikującą się do przycinania; prune zachowuje bajty każdego pluginu cli przypiętego na liście plugins.cli w konfiguracji — zarówno w magazynie pluginów cli, jak i w pamięci podręcznej artefaktów obszaru roboczego, wraz z jego wpisem w magazynie opisów pluginów — i usuwa te, których nie wskazuje żadne przypięcie; clear działa na wszystkim, dlatego przed rozpoczęciem prosi o potwierdzenie.
Katalog główny obszaru roboczego, którego nie można użyć. Gdy katalog główny obszaru roboczego podany poleceniu jest plikiem lub ścieżką, która nie istnieje, status, evict i clear działają wyłącznie na magazynach ogólnomaszynowych, kończą działanie tak, jak zrobiłyby to w przeciwnym razie, i informują o tym na standardowym wyjściu błędów tymi samymi słowami, którymi każde inne polecenie odrzuca ten katalog główny:
note: —workspace-root names the workspace root
"<root>", which is not a directory:<root>; only the machine-wide caches are acted on (uwaga: —workspace-root wskazuje katalog główny obszaru roboczego, który nie jest katalogiem; działania dotyczą tylko pamięci podręcznych całej maszyny)
Dla ścieżki, która nie istnieje, wypisywane jest which cannot be used: i przyczyna w miejsce which is not a directory:. prune zamiast tego się zatrzymuje, ponieważ potrzebuje plików blokady obszaru roboczego.
Dotyczy to każdego miejsca wywołania operacji, nie tylko terminala. Te same operacje są dostępne z sesji edytora i z wywołania narzędzia przez asystenta, a ich odpowiedzi niosą ten sam zasięg z tego samego powodu. Informacje o tym, kiedy asystent może je wywołać w imieniu użytkownika, zawiera aggrega mcp.
Dowiązanie w pamięci podręcznej artefaktów
Katalog pamięci podręcznej artefaktów jest jedynym miejscem, z którego wszystko w pamięci podręcznej jest odczytywane, do którego jest zapisywane i z którego jest usuwane — dotyczy to zarówno domyślnego .aggrega/cache, jak i katalogu wskazanego przez artifact_cache_dir, który wychodzi poza katalog główny obszaru roboczego (../shared-cache). Przez nic, co jest w nim dowiązaniem symbolicznym prowadzącym poza ten katalog — jednym z własnych katalogów pamięci podręcznej, takim jak .aggrega/cache/inputs, lub plikiem w jednym z nich — nie odbywa się ani odczyt, ani zapis, ani usuwanie, nawet jeśli dowiązanie prowadzi do innego katalogu tego samego obszaru roboczego. To, do czego może sięgnąć zapis poniżej katalogu pamięci podręcznej, jest dokładnie tym, do czego może sięgnąć usuwanie.
- Pobieranie, budowanie i każda inna operacja zapisująca pamięć podręczną zatrzymują się z błędem
E0320, podając dowiązanie i miejsce, do którego prowadzi, i niczego nie zapisują. status,pruneiclearniczego nie wyświetlają przez takie dowiązanie. Jeśli dowiązaniem jest jeden z własnych katalogów pamięci podręcznej,statuszatrzymuje się z błędemE0321, aprunelubclearzatrzymuje się z błędemE0320, zanim cokolwiek wyświetli lub usunie — dzięki temu nic, na co wskazuje dowiązanie, nie zostaje usunięte, a samo dowiązanie pozostaje na miejscu. Jeśli dowiązaniem jest plik w jednym z tych katalogów, wszystkie trzy zatrzymują się z błędemE0321.- Budowanie, pobieranie i każda inna operacja odczytująca pamięć podręczną zatrzymują się z błędem
E0321zamiast odczytywać bajty przechowywane gdzie indziej, nawet jeśli te bajty zgadzałyby się ze skrótem zapisanym w pliku blokady. - Dowiązanie, które pozostaje wewnątrz katalogu pamięci podręcznej, jest śledzone. Jeśli jeden z własnych katalogów pamięci podręcznej jest dowiązaniem do innego katalogu wewnątrz katalogu pamięci podręcznej, ten katalog należy do pamięci podręcznej:
statuswyświetla jego zawartość,pruneusuwa z niego, acleargo opróżnia, zachowuje dowiązanie i podaje liczbę usuniętych tam bajtów.
Sam katalog pamięci podręcznej. Wartość artifact_cache_dir zapisana wewnątrz katalogu głównego obszaru roboczego — łącznie z domyślną — może sama być dowiązaniem do innego katalogu obszaru roboczego i wtedy pamięć podręczna jest przechowywana tam, dokąd prowadzi dowiązanie. Dowiązanie prowadzące poza obszar roboczy jest odrzucane: każda operacja, która na nie natrafi, zatrzymuje się z błędem E0321 lub E0320, podając dowiązanie, zanim cokolwiek zostanie przez nie odczytane lub zapisane. Katalog zapisany jako wychodzący poza katalog główny obszaru roboczego jest respektowany tam, dokąd prowadzi, nawet jeśli sam jest dowiązaniem.
Należy usunąć dowiązanie i ponownie wykonać pobieranie, aby wypełnić pamięć podręczną na miejscu. Aby przechowywać pamięć podręczną gdzie indziej, należy ustawić artifact_cache_dir na ten katalog, zapisany względem katalogu głównego obszaru roboczego, zamiast tworzyć do niego dowiązanie: wskazany tam katalog jest odczytywany i zapisywany tam, dokąd prowadzi. Magazyny ogólnosystemowe nie są ograniczone do żadnego obszaru roboczego; magazyn przechowywany gdzie indziej przez dowiązanie jest wyświetlany, przycinany i czyszczony tam, dokąd prowadzi dowiązanie, a clear zachowuje dowiązanie. Granica obszaru roboczego przedstawia tę zasadę w całości.
Zobacz także
aggrega-pull— rozwiązuje zależności encji Release do pliku blokady i pamięci podręcznej.aggrega-config— miejsce, w którym zapisuje sięartifact_cache_diri pozostałe ustawienia pamięci podręcznej.