콘텐츠로 이동
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) 아래의 아티팩트 캐시에는 가져오기(fetch)가 넣어 둔 것이 들어 있습니다. 즉 카탈로그 엔티티와 소스 아티팩트이며, 각각은 자신의 종류와 가져올 때의 좌표 및 버전 아래에 저장되고, lockfile에 기록된 다이제스트로 보증됩니다. 이것은 카탈로그 디렉터리가 아니며 카탈로그 스캔은 이를 건너뜁니다. 따라서 캐시에 있는 내용은 이를 보증하는 고정(pin)을 통해 의존성으로 읽히며, 직접 작성한 엔티티로 읽히는 일은 없습니다.

가장 마주치기 쉬운 결과. 캐시에 어떤 lockfile도 고정하지 않은 엔티티가 있으면 그 엔티티는 빌드에서 보이지 않으며, 그 엔티티가 필요한 빌드는 찾을 수 없다는 메시지와 함께 중단됩니다. 중단 메시지에 엔티티 이름이 나오므로 메시지로부터 누락된 고정을 식별할 수 있습니다.

해당 엔터티가 $ref:가 가리키는 SchemaLibrary인 경우, 그 참조를 해석되지 않은 것으로 보고하는 모든 명령은 보고 뒤에 remediation: 줄을 붙여, 캐시에 있지만 어떤 잠금 파일 항목도 고정하지 않고 어떤 카탈로그 디렉터리도 제공하지 않는 각 라이브러리와, 그 명령에 맞는 조치를 지명합니다:

  • aggrega build와 aggrega validate --release <release>는 Release의 잠금 파일을 읽으므로, 이 줄은 라이브러리를 해석하고 그 항목을 기록하는 aggrega pull --release <release>를 지명합니다.
  • 인수 없는 aggrega validate와, --release 유무에 관계없이 aggrega validate <entity-path>는 카탈로그 디렉터리에서만 라이브러리를 읽고 잠금 파일은 읽지 않으므로, 기록된 항목이 그 판정을 바꾸지 않습니다. 이 줄은 그 사실을 밝히고, aggrega pull --release <release>와 그 뒤에 실행할 aggrega validate --release <release>를 지명합니다. 후자는 Release를 그 잠금 파일이 고정한 내용에 비추어 검사합니다.
  • 오프라인 모드에서는 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 프로젝트가 공유. 컴파일된 모듈 저장소, 플러그인 describe 저장소, 문서 번들 저장소, cli 플러그인 저장소입니다. provider 게스트는 한 번 컴파일되어 모든 프로젝트에서 재사용되며, 이것이 무엇이든 두 번째 빌드를 빠르게 만드는 이유입니다. 따라서 항목을 제거하면 머신에 있는 어느 프로젝트든 다음 빌드에서 그것을 다시 컴파일합니다. 문서 번들, 즉 aggrega explain, 편집기의 설명, 어시스턴트의 문서 리소스가 읽어 오는 게시된 페이지와 aggrega scaffold --example 명령이 기록하는 실행 가능한 예제는 그 내용이 다른 어떤 것에도 의존하지 않으므로 레지스트리와 버전마다 한 번만 보관됩니다. 이들 중 무엇이든 먼저 가져오면 모든 프로젝트를 위해 가져오는 것이며, 각 프로젝트는 자체 서명 검사가 그 사본을 승인한 뒤에만 그것을 제공받습니다. 영구적으로 잃는 것은 없습니다. 제거된 모듈은 필요할 때 다시 빌드되고, 제거된 번들은 다음 설명이나 예제가 요청될 때 또는 어시스턴트 서버가 다음에 시작될 때 다시 가져옵니다. 하지만 그 비용은 다음에 빌드하는 사람이 부담하며, 그 사람이 본인이 아닐 수도 있습니다.

cli 플러그인 저장소는 워크스페이스가 아닌 폴더에서 aggrega plugin add cli로 추가한 각 cli 플러그인의 바이트를 보관하므로, 그 명령은 어느 폴더에서든 실행됩니다. 워크스페이스 안에서 추가한 cli 플러그인은 대신 그 워크스페이스의 아티팩트 캐시에 바이트를 보관합니다. 컴파일된 모듈이나 번들과 달리, 바이트가 제거된 cli 플러그인은 저절로 다시 가져오지 않습니다. aggrega plugin add cli <name>으로 다시 추가할 때까지 그 명령은 존재하지 않으며, 모든 명령이 그것을 추가할 수 없었다고 경고하면서 구성이 고정한 버전으로 그것을 다시 추가하는 aggrega plugin add cli 명령을 알려 줍니다.

머신 전역 저장소는 각 플랫폼이 사용자 캐시를 보관하는 위치에 보관됩니다. Windows에서는 LOCALAPPDATA 환경 변수가 가리키는 디렉터리 안의 aggrega\cache 아래, macOS에서는 ~/Library/Caches/aggrega 아래, Linux와 기타 Unix 시스템에서는 XDG_CACHE_HOME이 가리키는 디렉터리 안의 aggrega 디렉터리 아래(XDG_CACHE_HOME이 설정되지 않은 경우 ~/.cache/aggrega)입니다. aggrega config init은 실행된 머신에서의 해당 디렉터리를 출력합니다. 이 변수들이 하나도 설정되어 있지 않으면 컴파일된 플러그인은 해당 실행 동안에만 보관되고 문서 번들은 전혀 보관되지 않습니다. 이 경우 설명은 단계별 안내가 없는 이유를 알려 주고, 어시스턴트의 문서 리소스는 not-found로 응답하며, aggrega scaffold --example은 캐시 디렉터리를 확인할 수 없다고 알리며 거부합니다. 또한 워크스페이스가 아닌 폴더에서 실행한 aggrega plugin add cli도 머신 전역 캐시 위치를 확인할 수 없다고 알리며 거부합니다.

aggrega cache status는 이를 이름으로 추론하도록 맡기지 않고 클래스별로 명시합니다. 각 클래스는 워크스페이스를 대상으로 하는지 머신을 대상으로 하는지 보고되며, prune, evict, clear가 제거하는 각 요소에 대해서도 같은 범위가 보고됩니다. evict는 공유된 컴파일 모듈 저장소에만 작동합니다. prune은 어떤 lockfile도 문서 번들이나 가져오기가 읽은 카탈로그 스냅샷을 참조하지 않으므로 이들을 제거하지 않으며, 그러한 각 클래스를 prune 대상이 아닌 것으로 보고합니다. prune은 구성의 plugins.cli 목록이 고정하는 모든 cli 플러그인의 바이트를 cli 플러그인 저장소와 워크스페이스의 아티팩트 캐시 모두에서 해당 플러그인 describe 항목과 함께 유지하고, 어떤 고정에서도 지정하지 않은 것은 제거합니다. 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, build, 그리고 캐시에 쓰는 다른 모든 작업은 링크와 그 링크가 이어지는 위치를 명시하며 E0320으로 중단되고, 아무것도 쓰지 않습니다.
  • **status, prune, clear**는 그러한 링크를 통해 아무것도 나열하지 않습니다. 캐시 자체의 디렉터리 중 하나가 링크인 경우 status는 E0321로 중단되고, prune 또는 clear는 무엇이든 나열하거나 제거하기 전에 E0320으로 중단됩니다. 따라서 링크가 가리키는 것은 아무것도 제거되지 않으며, 링크도 그대로 남습니다. 그 디렉터리 안의 파일이 링크인 경우에는 세 가지 모두 E0321로 중단됩니다.
  • build, pull, 그리고 캐시를 읽는 다른 모든 작업은 다른 곳에 보관된 바이트를 읽는 대신 E0321로 중단됩니다. 그 바이트가 lockfile에 기록된 다이제스트와 일치하더라도 마찬가지입니다.
  • 캐시 디렉터리 안에 머무는 링크는 따라갑니다. 캐시 자체의 디렉터리 중 하나가 캐시 디렉터리 안의 다른 디렉터리로 이어지는 링크인 경우, 그 디렉터리는 캐시의 것입니다. status는 그곳에 있는 것을 나열하고, prune은 그곳에서 제거하며, clear는 그곳을 비우고 링크는 유지한 채 그곳에서 제거한 바이트를 보고합니다.

캐시 디렉터리 자체. 작업 공간 루트 안으로 작성된 artifact_cache_dir는 — 기본값을 포함하여 — 그 자체가 작업 공간의 다른 디렉터리로 이어지는 링크일 수 있으며, 이 경우 캐시는 링크가 이어지는 위치에 보관됩니다. 작업 공간 밖으로 이어지는 링크는 거부됩니다. 그것을 만나는 작업은 무엇이든 링크를 명시하며, 그것을 통해 무엇이든 읽거나 쓰기 전에 E0321 또는 E0320으로 중단됩니다. 작업 공간 루트 밖으로 올라가도록 작성된 디렉터리는 그 자체가 링크인 경우에도 이어지는 위치 그대로 존중됩니다.

링크를 제거하고 다시 pull하면 캐시가 제자리에 채워집니다. 캐시를 다른 곳에 두려면 그 디렉터리로 링크하는 대신 artifact_cache_dir를 작업 공간 루트 기준 상대 경로로 작성한 해당 디렉터리로 설정합니다. 거기에 지정된 디렉터리는 그것이 이어지는 위치에서 읽고 쓰입니다. 머신 전체 저장소는 어떤 작업 공간에도 묶이지 않습니다. 링크를 통해 다른 곳에 둔 저장소는 링크가 이어지는 위치에서 나열, prune, clear되며, clear는 링크를 유지합니다. 작업 공간 경계에서 규칙 전체를 설명합니다.

참고 항목

  • aggrega-pull — Release의 의존성을 lockfile과 캐시로 해석합니다.
  • aggrega-config — artifact_cache_dir와 그 밖의 캐시 설정을 작성하는 위치입니다.