コンテンツにスキップ
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どのロックファイルからも参照されていないアーティファクトキャッシュのエントリを削除します
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)以下のアーティファクトキャッシュには、フェッチによって置かれたものが格納されます。カタログのエンティティとソースアーティファクトであり、それぞれ自身の種別と、フェッチされたときの座標とバージョンの下に保存され、ロックファイルに記録されたダイジェストによって正当性が保証されます。これはカタログディレクトリではなく、カタログのスキャンはこれをスキップします。そのため、キャッシュ内のコンテンツは、それを保証するピンを通じて依存関係として読み込まれ、自分で作成したエンティティとして読み込まれることはありません。

最も遭遇しやすい影響。 どのロックファイルもピン留めしていないエンティティがキャッシュにある場合、そのエンティティはビルドからは見えず、それを必要とするビルドは見つからないとして停止します。停止時にはエンティティ名が示されるため、欠けているピンはメッセージから特定できます。

そのエンティティが $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 には、記録するエントリーがありません。

これらの行はいずれも、もう 1 つの解決策も示します。それは、カタログディレクトリの下にライブラリを作成することです。

実行するコマンド。 aggrega pull --release <release> はエンティティを解決してダイジェストを記録し、その後は同じビルドでエンティティが見つかるようになります。エンティティが依存関係ではなく自分のものである場合は、代わりに workspace.catalog_dirs に列挙されたディレクトリの下で作成してください。スキャンはそこを読み込みます。aggrega cache prune はどのロックファイルも参照していないエントリを削除します。これは同じルールの整理側の半分にあたります。

キャッシュのレイアウト、artifact_cache_dir の契約、および解決アーティファクトが作成済みコンテンツとして意図的に読み込めないようになっている理由については、architecture/13-catalog-and-registry.md を参照してください。

このプロジェクトに属するキャッシュと、マシンに属するキャッシュ

これらのコマンドが操作するキャッシュのすべてが、現在作業しているプロジェクトにスコープされているわけではありません。この違いによって、領域の回収がどこまで及ぶかが決まります。

このプロジェクト専用。 artifact_cache_dir 配下の成果物キャッシュです。このプロジェクトが解決したエンティティ、ソース成果物、ピン留めされた外部入力、そしてカタログフォルダーを指定しないインポートが読み込んだ公開カタログのスナップショットが含まれます。ここから回収しても、影響はこのプロジェクトだけに及び、他には何も影響しません。

このマシン上のすべての Aggrega プロジェクトで共有。 コンパイル済みモジュールストア、プラグイン記述ストア、ドキュメントバンドルストア、cli プラグインストアです。プロバイダーのゲストは一度だけコンパイルされ、すべてのプロジェクトで再利用されます。これにより 2 回目以降のビルドが高速になるため、エントリを削除すると、マシン上の任意のプロジェクトの次のビルドでそれが再コンパイルされます。ドキュメントバンドル(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 は、ドキュメントバンドルもインポートが読み込んだカタログスナップショットも参照するロックファイルがないため、それらを削除することはなく、そうした各クラスを prune 対象外として報告します。prune は、構成の plugins.cli リストが固定するすべての 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 cannot be used: とその理由が、which is not a directory: の代わりに表示されます。prune はワークスペースのロックファイルを必要とするため、代わりに停止します。

これは、ターミナルからだけでなく、操作がどこから呼び出された場合にも当てはまります。 同じ操作はエディタのセッションやアシスタントのツール呼び出しからも実行でき、その応答には同じ理由で同じ範囲が示されます。アシスタントが代わりにこれらを呼び出す場合については、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 やその他のキャッシュ設定を記述する場所です。