aggrega cache
Kiểm tra và bảo trì các cache trên đĩa
Cú pháp
aggrega cacheMô tả
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.Lệnh con
| Lệnh | Mô tả |
|---|---|
aggrega cache clear | Xóa toàn bộ bộ nhớ đệm, bao gồm cả các module đã biên dịch |
aggrega cache evict | Cắt giảm bộ nhớ đệm module đã biên dịch xuống dưới một giới hạn kích thước, bắt đầu từ mục cũ nhất |
aggrega cache prune | Xóa các mục trong bộ nhớ đệm artifact mà không lockfile nào tham chiếu |
aggrega cache status | Liệt kê nội dung bộ nhớ đệm và bản tóm tắt tổng |
Mô tả 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.Các cờ của aggrega cache clear
| Cờ | Mặc định | Mô tả |
|---|---|---|
--yes | false | bỏ qua lời nhắc xác nhận (dùng cho môi trường không tương tác/CI) |
Mô tả 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.Các cờ của aggrega cache evict
| Cờ | Mặc định | Mô tả |
|---|---|---|
--max-size | — | giới hạn kích thước cho bộ nhớ đệm module đã biên dịch (ví dụ 5GiB, 512MiB, hoặc một số byte); bắt buộc |
Mô tả 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.Mô tả 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.Bộ nhớ đệm là gì, và không phải là gì
Bộ nhớ đệm artifact nằm dưới artifact_cache_dir (mặc định là .aggrega/cache) chứa những gì một lần fetch đã đặt vào đó: các thực thể catalog và các artifact nguồn, mỗi thứ được lưu dưới loại của nó cùng tọa độ và phiên bản mà nó đã được fetch, và được bảo chứng bằng một digest mà lockfile ghi lại. Nó không phải là một thư mục catalog, và một lần quét catalog sẽ bỏ qua nó — vì vậy nội dung nằm trong bộ nhớ đệm được đọc như một phụ thuộc, thông qua pin bảo chứng cho nó, và không bao giờ được đọc như một thực thể do bạn tạo ra.
Hệ quả bạn dễ gặp nhất. Nếu bộ nhớ đệm chứa một thực thể mà không lockfile nào pin, thực thể đó sẽ vô hình đối với một lần build, và một lần build cần đến nó sẽ dừng lại với thông báo rằng không tìm thấy nó. Thông báo dừng nêu tên thực thể, nên có thể xác định pin bị thiếu từ thông báo đó.
Khi thực thể là một SchemaLibrary mà một $ref: với tới, mọi lệnh báo cáo tham chiếu là chưa phân giải được sẽ nối tiếp báo cáo bằng một dòng remediation: nêu tên từng thư viện mà cache đang giữ nhưng không mục lockfile nào ghim và không thư mục catalog nào cung cấp, cùng với hành động có tác dụng đối với lệnh đó:
aggrega buildvàaggrega validate --release <release>đọc lockfile của Release, nên dòng này nêuaggrega pull --release <release>để phân giải thư viện và ghi lại mục của nó.aggrega validatekhông có đối số, vàaggrega validate <entity-path>có hoặc không có--release, chỉ đọc thư viện từ các thư mục catalog và không đọc lockfile nào, nên không mục đã ghi nào làm thay đổi phán quyết của chúng. Dòng này nói rõ điều đó, và nêuaggrega pull --release <release>rồi đếnaggrega validate --release <release>, lệnh kiểm tra Release dựa trên những gì lockfile của nó ghim.aggrega pull, vàaggrega build --auto-pull, ở chế độ ngoại tuyến không thể tải thư viện về cũng không thể ghi một mục cho nó, nên dòng này bảo chạyaggrega pull --release <release>ở nơi có thể với tới một registry. Khi có kết nối, một lần pull không tìm thấy thư viện trong thư mục catalog nào và trong registry nào mà nó đọc thì không có mục nào để ghi.
Mỗi dòng đó cũng đưa ra cách còn lại: soạn thư viện bên dưới một thư mục catalog.
Cần chạy gì. aggrega pull --release <release> phân giải thực thể và ghi lại digest của nó, sau đó cùng lần build ấy sẽ tìm thấy nó. Nếu thực thể là của bạn chứ không phải một phụ thuộc, hãy tạo nó dưới một thư mục được liệt kê trong workspace.catalog_dirs — một lần quét sẽ đọc thư mục đó. aggrega cache prune dọn sạch các mục mà không lockfile nào tham chiếu, đây là nửa dọn dẹp của cùng quy tắc đó.
Về bố cục bộ nhớ đệm, hợp đồng artifact_cache_dir, và lý do một artifact phân giải được cố ý làm cho không thể đọc như nội dung do người dùng tạo, xem architecture/13-catalog-and-registry.md.
Bộ nhớ đệm nào thuộc về dự án này, và bộ nhớ đệm nào thuộc về máy
Không phải mọi bộ nhớ đệm mà các lệnh này tác động đều có phạm vi là dự án bạn đang làm việc, và sự khác biệt đó quyết định việc thu hồi dung lượng ảnh hưởng đến đâu.
Chỉ của riêng bạn. Bộ nhớ đệm artifact dưới artifact_cache_dir — các thực thể, artifact nguồn và đầu vào bên ngoài đã được ghim mà dự án này đã phân giải, cùng các bản chụp nhanh của danh mục đã phát hành mà một lần nhập không chỉ định thư mục danh mục nào đã đọc. Thu hồi dung lượng từ đó chỉ ảnh hưởng đến dự án này và không gì khác.
Dùng chung cho mọi dự án Aggrega trên máy này. Kho module đã biên dịch, kho plugin-describe, kho gói tài liệu và kho plugin cli. Một provider guest được biên dịch một lần và được mọi dự án dùng lại, đó là điều làm cho lần build thứ hai của bất kỳ thứ gì trở nên nhanh, vì vậy xóa một mục có nghĩa là lần build tiếp theo của bất kỳ dự án nào trên máy sẽ biên dịch lại nó. Gói tài liệu — các trang đã xuất bản mà aggrega explain, phần giải thích của trình soạn thảo và tài nguyên tài liệu của trợ lý đọc từ đó, cùng các ví dụ chạy được mà aggrega scaffold --example ghi ra — được lưu một lần cho mỗi registry và phiên bản, vì nội dung của nó không phụ thuộc vào gì khác: bất kỳ bên nào trong số đó tải nó trước thì sẽ tải cho mọi dự án, và mỗi dự án vẫn chỉ được cung cấp nó khi bước kiểm tra chữ ký của chính dự án đó chấp nhận bản sao. Không có gì bị mất vĩnh viễn — một module bị xóa sẽ được build lại khi cần, và một gói bị xóa sẽ được tải lại bởi lần giải thích hoặc ví dụ tiếp theo, hoặc bởi máy chủ trợ lý khi nó khởi động lần tới — nhưng chi phí rơi vào người build tiếp theo, mà người đó có thể không phải là bạn.
Kho plugin cli giữ các byte của mỗi plugin cli được thêm bằng aggrega plugin add cli trong một thư mục không phải là workspace, nhờ đó lệnh của nó chạy được từ bất kỳ thư mục nào; một plugin cli được thêm bên trong một workspace thì thay vào đó giữ các byte của nó trong bộ nhớ đệm artifact của workspace đó. Khác với một module đã biên dịch hay một gói, một plugin cli bị xóa các byte sẽ không tự được tải lại: cho đến khi aggrega plugin add cli <name> thêm lại nó, lệnh của nó bị thiếu và mọi lệnh đều cảnh báo rằng không thể thêm nó, đồng thời nêu lệnh aggrega plugin add cli để thêm lại nó ở phiên bản mà cấu hình của bạn ghim.
Các kho dùng chung toàn máy được lưu ở nơi mỗi nền tảng lưu bộ nhớ đệm của người dùng: trên Windows là dưới aggrega\cache bên trong thư mục mà biến môi trường LOCALAPPDATA chỉ định, trên macOS là dưới ~/Library/Caches/aggrega, và trên Linux cùng các hệ thống Unix khác là dưới một thư mục aggrega bên trong thư mục mà XDG_CACHE_HOME chỉ định — ~/.cache/aggrega khi XDG_CACHE_HOME không được đặt. aggrega config init in ra thư mục đó trên máy mà nó chạy. Khi không biến nào trong số đó được đặt, các plugin đã biên dịch chỉ được lưu trong lần chạy, và không gói tài liệu nào được lưu cả: khi đó phần giải thích sẽ cho biết vì sao thiếu phần hướng dẫn chi tiết, tài nguyên tài liệu của trợ lý trả về not-found, và aggrega scaffold --example từ chối, cho biết không xác định được thư mục bộ nhớ đệm nào; aggrega plugin add cli chạy trong một thư mục không phải là workspace cũng từ chối, cho biết không xác định được vị trí bộ nhớ đệm toàn máy nào.
aggrega cache status nêu rõ điều này cho từng loại thay vì để người dùng tự suy ra từ tên: mỗi loại được báo cáo là bao phủ workspace hay toàn máy, và cùng phạm vi đó được báo cáo cho từng phần tử mà prune, evict và clear xóa. evict chỉ tác động lên kho module đã biên dịch dùng chung; prune không bao giờ xóa gói tài liệu hay bản chụp nhanh danh mục mà một lần nhập đã đọc, vì không lockfile nào tham chiếu đến chúng, và báo cáo từng loại như vậy là không đủ điều kiện để prune; prune giữ lại các byte của mọi plugin cli mà danh sách plugins.cli trong cấu hình của bạn ghim — trong kho plugin cli cũng như trong bộ nhớ đệm artifact của workspace, cùng với mục plugin-describe của nó — và xóa những plugin không được ghim nào nêu tên; clear tác động lên mọi thứ, đó là lý do nó hỏi trước khi bắt đầu.
Gốc workspace không dùng được. Khi gốc workspace được truyền cho lệnh là một tệp hoặc một đường dẫn không tồn tại, status, evict và clear chỉ tác động lên các kho dùng chung toàn máy, thoát như bình thường, và thông báo điều đó trên standard error, bằng chính câu chữ mà mọi lệnh khác dùng để từ chối gốc đó:
note: —workspace-root names the workspace root
"<root>", which is not a directory:<root>; only the machine-wide caches are acted on (lưu ý: —workspace-root chỉ định một gốc workspace không phải là thư mục; chỉ các cache toàn máy được tác động)
Một đường dẫn không tồn tại sẽ hiển thị which cannot be used: và lý do thay cho which is not a directory:. prune thì dừng lại, vì nó cần các lockfile của workspace.
Điều này áp dụng bất kể thao tác được gọi từ đâu, không chỉ tại terminal. Các thao tác này cũng có thể được gọi từ một phiên trình soạn thảo và từ lệnh gọi công cụ của trợ lý, và câu trả lời của chúng mang cùng phạm vi vì cùng lý do. Về việc trợ lý có thể gọi chúng thay cho bạn, xem aggrega mcp.
Liên kết trong bộ nhớ đệm artifact
Thư mục bộ nhớ đệm artifact là nơi duy nhất mà mọi thứ trong bộ nhớ đệm được đọc từ đó, ghi vào đó và xóa khỏi đó — dù là .aggrega/cache mặc định hay một thư mục mà artifact_cache_dir chỉ định nằm ngoài thư mục gốc của workspace (../shared-cache). Bất cứ thứ gì trong đó là một liên kết tượng trưng dẫn ra ngoài thư mục đó — một trong các thư mục riêng của bộ nhớ đệm, chẳng hạn .aggrega/cache/inputs, hoặc một tệp bên trong một thư mục như vậy — đều không được đọc, ghi hay xóa thông qua nó, kể cả khi liên kết dẫn đến một thư mục khác của cùng workspace. Những gì một thao tác ghi có thể chạm tới bên dưới thư mục bộ nhớ đệm chính xác là những gì một thao tác xóa có thể chạm tới.
- Một lệnh pull, một lệnh build và mọi thao tác khác ghi vào bộ nhớ đệm sẽ dừng với
E0320, nêu tên liên kết và nơi nó dẫn tới, và không ghi gì cả. status,prunevàclearkhông liệt kê gì thông qua một liên kết như vậy. Khi một trong các thư mục riêng của bộ nhớ đệm là liên kết,statusdừng vớiE0321, cònprunehoặccleardừng vớiE0320trước khi liệt kê hay xóa bất cứ thứ gì — nên không có gì mà liên kết trỏ tới bị xóa, và liên kết vẫn giữ nguyên chỗ cũ. Khi một tệp bên trong một thư mục như vậy là liên kết, cả ba đều dừng vớiE0321.- Một lệnh build, một lệnh pull và mọi thao tác khác đọc bộ nhớ đệm sẽ dừng với
E0321thay vì đọc các byte được lưu ở nơi khác, kể cả khi các byte đó khớp với digest mà lockfile ghi lại. - Một liên kết nằm gọn bên trong thư mục bộ nhớ đệm sẽ được đi theo. Khi một trong các thư mục riêng của bộ nhớ đệm là liên kết tới một thư mục khác bên trong thư mục bộ nhớ đệm, thư mục đó thuộc về bộ nhớ đệm:
statusliệt kê những gì nằm ở đó,prunexóa từ đó, cònclearlàm trống nó, giữ lại liên kết và báo cáo số byte đã xóa ở đó.
Chính thư mục bộ nhớ đệm. Một artifact_cache_dir được viết bên trong thư mục gốc của workspace — kể cả giá trị mặc định — bản thân nó có thể là liên kết tới một thư mục khác của workspace, và khi đó bộ nhớ đệm được lưu tại nơi liên kết dẫn tới. Một liên kết dẫn ra ngoài workspace sẽ bị từ chối: bất kỳ thao tác nào gặp nó đều dừng với E0321 hoặc E0320, nêu tên liên kết, trước khi đọc hay ghi bất cứ thứ gì thông qua nó. Một thư mục được viết nằm ngoài thư mục gốc của workspace được tôn trọng tại nơi nó dẫn tới, kể cả khi bản thân nó là một liên kết.
Hãy xóa liên kết và pull lại để điền bộ nhớ đệm tại chỗ. Để lưu bộ nhớ đệm ở nơi khác, hãy đặt artifact_cache_dir thành thư mục đó, viết tương đối so với thư mục gốc của workspace, thay vì tạo liên kết tới nó: một thư mục được chỉ định ở đó sẽ được đọc và ghi tại nơi nó dẫn tới. Các kho dùng chung trên toàn máy không bị giới hạn trong workspace nào; một kho bạn lưu ở nơi khác thông qua liên kết sẽ được liệt kê, prune và clear tại nơi liên kết dẫn tới, và clear giữ lại liên kết. Ranh giới workspace trình bày đầy đủ quy tắc này.
Xem thêm
aggrega-pull— phân giải các phụ thuộc của một Release vào lockfile và bộ nhớ đệm.aggrega-config— nơi ghiartifact_cache_dirvà các thiết lập bộ nhớ đệm khác.