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 (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)下的制品缓存保存的是拉取放入其中的内容:目录实体和源制品,每一项都按其种类以及拉取时的坐标和版本存储,并由锁文件记录的摘要担保。它不是目录(catalog)目录,目录扫描会跳过它——因此缓存中的内容是作为依赖、通过担保它的固定版本来读取的,而绝不会被当作你编写的实体。
你最可能遇到的后果。 如果缓存中有一个没有任何锁文件固定的实体,该实体对构建不可见,需要它的构建会停止并报告找不到该实体。停止信息会指出该实体,因此可以从消息中识别出缺失的固定版本。
当该实体是 $ref: 所指向的 SchemaLibrary 时,每个将该引用报告为未解析的命令都会在报告之后附上一行 remediation:,列出缓存中持有、却没有任何锁文件条目固定、也没有任何 catalog 目录提供的每个库,以及对该命令有效的操作:
aggrega build和aggrega validate --release <release>会读取 Release 的锁文件,因此该行给出aggrega pull --release <release>,用于解析该库并记录其条目。- 不带参数的
aggrega validate,以及带或不带--release的aggrega validate <entity-path>,只从 catalog 目录读取库,且不读取锁文件,因此任何已记录的条目都不会改变它们的结论。该行会说明这一点,并给出aggrega pull --release <release>,随后是aggrega validate --release <release>,后者依据锁文件所固定的内容检查 Release。 - 在离线模式下,
aggrega pull和aggrega build --auto-pull既无法获取该库,也无法为其记录条目,因此该行会提示在能够访问注册表的地方运行aggrega pull --release <release>。在联网状态下,如果 pull 在任何 catalog 目录和它读取的任何注册表中都找不到该库,就没有可记录的条目。
上述每一行还都提供另一种解决办法:在 catalog 目录下编写该库。
应运行什么。 aggrega pull --release <release> 会解析该实体并记录其摘要,之后同一构建就能找到它。如果该实体是你自己的而不是依赖,请改为在 workspace.catalog_dirs 列出的目录下编写它——扫描会读取那里。aggrega cache prune 会清除没有任何锁文件引用的条目,这是同一规则中负责整理的另一半。
关于缓存布局、artifact_cache_dir 契约,以及为什么解析制品被有意设计为不能作为编写的内容读取,请参阅 architecture/13-catalog-and-registry.md。
哪些缓存属于本项目,哪些属于本机
这些命令作用的缓存并非都限定在你当前所在的项目内,这一区别决定了一次回收所波及的范围。
仅属于你。 artifact_cache_dir 下的制品缓存——本项目已解析的实体、源制品和已固定的外部输入,以及未指定目录文件夹的导入所读取的已发布目录快照。从中回收只影响本项目,不影响其他任何内容。
由本机上所有 Aggrega 项目共享。 已编译模块存储、插件描述存储、文档包存储和 cli 插件存储。provider guest 只编译一次并由所有项目复用,正是这一点让任何内容的第二次构建变快,因此删除一个条目意味着本机上任何项目的下一次构建都会重新编译它。文档包——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 会打印其运行所在机器上的该目录。若这些变量均未设置,已编译插件只在本次运行期间保留,且完全不保留文档包:此时解释会说明其详细讲解缺失的原因,助手的文档资源返回未找到,而 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 则会停止,因为它需要工作区的 lockfile。
无论从何处调用该操作,这一点都适用,而不仅限于终端。 同样的操作也可从编辑器会话和助手的工具调用中执行,出于同样的原因,它们的回答也带有相同的范围。关于助手可能代你调用它们的情形,请参阅 aggrega mcp。
制品缓存中的链接
制品缓存目录是缓存中一切内容被读取、写入和删除的唯一位置——默认的 .aggrega/cache 和 artifact_cache_dir 所指定的、向上越出工作区根目录的目录(../shared-cache)都是如此。其中任何指向该目录之外的符号链接——无论是缓存自身的某个目录(如 .aggrega/cache/inputs),还是其中的某个文件——都不会经由它进行读取、写入或删除,即使该链接指向同一工作区的另一个目录。写入在缓存目录之下可以到达的范围,与删除可以到达的范围完全相同。
- 拉取、构建以及其他所有写入缓存的操作会以
E0320停止,指出该链接及其指向的位置,并且不写入任何内容。 status、prune和clear不会经由此类链接列出任何内容。若缓存自身的某个目录是该链接,status会以E0321停止,而prune或clear会在列出或删除任何内容之前以E0320停止——因此链接所指向的内容都不会被删除,链接本身也保持原样。若其中某个文件是该链接,三者都会以E0321停止。- 构建、拉取以及其他所有读取缓存的操作会以
E0321停止,而不是读取保存在别处的字节,即使这些字节与锁文件记录的摘要相符。 - **停留在缓存目录内部的链接会被跟随。**若缓存自身的某个目录是指向缓存目录内另一个目录的链接,则该目录属于缓存:
status列出其中的内容,prune从中删除,clear将其清空、保留该链接,并报告在其中删除的字节数。
**缓存目录本身。**写在工作区根目录之内的 artifact_cache_dir(包括默认值)本身可以是指向工作区另一个目录的链接,此时缓存保存在链接指向的位置。指向工作区之外的链接会被拒绝:遇到它的任何操作都会在经由它读取或写入任何内容之前以 E0321 或 E0320 停止,并指出该链接。以向上越出工作区根目录的方式写出的目录,会按其指向的位置使用,即使它本身是一个链接。
删除该链接并重新拉取,即可在原位填充缓存。若要将缓存保存在别处,请将 artifact_cache_dir 设为该目录(相对于工作区根目录书写),而不是链接到它:在那里指定的目录会在其指向的位置被读取和写入。机器范围的存储不受任何工作区的限制;通过链接保存在别处的存储,会在链接指向的位置被列出、修剪和清除,且 clear 会保留该链接。工作区边界完整说明了这一规则。
另请参阅
aggrega-pull— 将某个 Release 的依赖解析到 lockfile 和缓存中。aggrega-config— 说明artifact_cache_dir及其他缓存设置写在何处。