Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

aggrega cache

Inspeccionar y mantener las cachés en disco

Sinopsis

aggrega cache

Descripción

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.

Subcomandos

ComandoDescripción
aggrega cache clearBorra todas las cachés, incluidos los módulos compilados
aggrega cache evictRecorta la caché de módulos compilados hasta un límite de tamaño, empezando por los más antiguos
aggrega cache pruneElimina las entradas de la caché de artefactos a las que no hace referencia ningún lockfile
aggrega cache statusLista el contenido de la caché y un resumen total

Descripción de 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.

Flags de aggrega cache clear

FlagPredeterminadoDescripción
--yesfalseomite la solicitud de confirmación (para uso no interactivo/CI)

Descripción de 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.

Flags de aggrega cache evict

FlagPredeterminadoDescripción
--max-size—límite de tamaño para la caché de módulos compilados (p. ej., 5GiB, 512MiB o un número de bytes); obligatorio

Descripción de 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.

Descripción de 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.

Qué es la caché y qué no es

La caché de artefactos en artifact_cache_dir (.aggrega/cache de forma predeterminada) contiene lo que una obtención colocó allí: entidades del catálogo y artefactos de origen, cada uno almacenado bajo su tipo y la coordenada y la versión con que se obtuvo, y avalado por un digest que registra el lockfile. No es un directorio de catálogo, y un escaneo del catálogo lo omite — así que el contenido que hay en la caché se lee como una dependencia, a través del pin que lo avala, y nunca como una entidad que tú escribiste.

La consecuencia con la que es más probable que te encuentres. Si la caché contiene una entidad que ningún lockfile fija con un pin, esa entidad es invisible para una compilación, y una compilación que la necesita se detiene indicando que no se encontró. La detención nombra la entidad, de modo que el pin que falta se puede identificar a partir del mensaje.

Cuando la entidad es una SchemaLibrary a la que llega un $ref:, todo comando que informa de la referencia como no resuelta hace seguir el informe de una línea remediation: que nombra cada biblioteca que contiene la caché y que ninguna entrada de lockfile fija ni ningún directorio de catálogo proporciona, junto con la acción que funciona para ese comando:

  • aggrega build y aggrega validate --release <release> leen el lockfile de la Release, así que la línea nombra aggrega pull --release <release> para resolver la biblioteca y registrar su entrada.
  • aggrega validate sin argumento, y aggrega validate <entity-path> con o sin --release, leen las bibliotecas solo de los directorios de catálogo y no leen ningún lockfile, así que ninguna entrada registrada cambia su veredicto. La línea lo dice, y nombra aggrega pull --release <release> seguido de aggrega validate --release <release>, que comprueba la Release frente a lo que fija su lockfile.
  • aggrega pull, y aggrega build --auto-pull, en modo sin conexión no pueden ni obtener la biblioteca ni registrar una entrada para ella, así que la línea indica ejecutar aggrega pull --release <release> donde se pueda llegar a un registro. Con conexión, un pull que no encuentra la biblioteca en ningún directorio de catálogo ni en ningún registro que lee no tiene ninguna entrada que registrar.

Cada una de esas líneas ofrece también la otra salida: escribir la biblioteca en un directorio de catálogo.

Qué ejecutar. aggrega pull --release <release> resuelve la entidad y registra su digest, tras lo cual la misma compilación la encuentra. Si la entidad es tuya y no una dependencia, escríbela en su lugar en un directorio listado en workspace.catalog_dirs — un escaneo lee ese. aggrega cache prune elimina las entradas a las que no hace referencia ningún lockfile, que es la mitad de limpieza de la misma regla.

Para la estructura de la caché, el contrato de artifact_cache_dir y por qué un artefacto de resolución no se puede leer deliberadamente como contenido escrito, consulta architecture/13-catalog-and-registry.md.

Qué cachés pertenecen a este proyecto y cuáles a la máquina

No todas las cachés sobre las que actúan estos comandos se limitan al proyecto en el que te encuentras, y la diferencia decide hasta dónde llega una recuperación de espacio.

Solo tuya. La caché de artefactos en artifact_cache_dir — las entidades, los artefactos de origen y las entradas externas con pin que este proyecto ha resuelto, y las instantáneas del catálogo publicado que ha leído una importación que no indica ninguna carpeta de catálogo. Recuperar espacio de ella afecta a este proyecto y a nada más.

Compartidas por todos los proyectos de Aggrega en esta máquina. El almacén de módulos compilados, el almacén de descripciones de plugins, el almacén de paquetes de documentación y el almacén de plugins cli. El guest de un provider se compila una vez y lo reutilizan todos los proyectos, que es lo que hace rápida la segunda compilación de cualquier cosa, así que eliminar una entrada significa que la siguiente compilación de cualquier proyecto de la máquina lo vuelve a compilar. El paquete de documentación — las páginas publicadas de las que leen aggrega explain, las explicaciones de un editor y los recursos de documentación de un asistente, y los ejemplos ejecutables que escribe aggrega scaffold --example — se conserva una sola vez por registro y versión, porque su contenido no depende de nada más: el primero de ellos que lo obtiene lo obtiene para todos los proyectos, y aun así cada proyecto solo lo recibe una vez que su propia comprobación de firma admite la copia. Nada se pierde de forma permanente — un módulo eliminado se reconstruye bajo demanda, y un paquete eliminado se vuelve a obtener con la siguiente explicación o el siguiente ejemplo, o por un servidor de asistente la próxima vez que se inicie —, pero el coste recae en quien compile a continuación, que puede no ser tú.

El almacén de plugins cli guarda los bytes de cada plugin cli añadido con aggrega plugin add cli en una carpeta que no es un workspace, de modo que su comando se ejecuta desde cualquier carpeta; un plugin cli añadido dentro de un workspace guarda en cambio sus bytes en la caché de artefactos de ese workspace. A diferencia de un módulo compilado o de un paquete, un plugin cli cuyos bytes se eliminan no se vuelve a obtener por sí solo: hasta que aggrega plugin add cli <name> lo añada de nuevo, su comando falta y cada comando advierte que no se pudo añadir, indicando el comando aggrega plugin add cli que lo añade de nuevo en la versión que fija tu configuración.

Los almacenes de toda la máquina se guardan donde cada plataforma guarda las cachés de un usuario: en Windows en aggrega\cache dentro del directorio que nombra la variable de entorno LOCALAPPDATA, en ~/Library/Caches/aggrega en macOS, y en un directorio aggrega dentro del que nombra XDG_CACHE_HOME — ~/.cache/aggrega cuando XDG_CACHE_HOME no está definida — en Linux y los demás sistemas Unix. aggrega config init imprime el directorio en la máquina en la que se ejecuta. Cuando ninguna de esas variables está definida, los plugins compilados se conservan solo durante la ejecución y no se conserva ningún paquete de documentación: una explicación indica entonces por qué falta su guía paso a paso, los recursos de documentación de un asistente responden «no encontrado», y aggrega scaffold --example se niega, indicando que no se resuelve ningún directorio de caché; aggrega plugin add cli ejecutado en una carpeta que no es un workspace también se niega, indicando que no se resuelve ninguna ubicación de caché de toda la máquina.

aggrega cache status lo indica por clase en lugar de dejar que se deduzca del nombre: cada clase se notifica como de alcance del workspace o de la máquina, y el mismo alcance se notifica para cada elemento que eliminan prune, evict y clear. evict actúa solo sobre el almacén compartido de módulos compilados; prune nunca elimina un paquete de documentación ni una instantánea del catálogo que haya leído una importación, ya que ningún lockfile hace referencia a ninguno de los dos, y notifica cada una de esas clases como no apta para prune; prune conserva los bytes de cada plugin cli que fija la lista plugins.cli de tu configuración — tanto en el almacén de plugins cli como en la caché de artefactos del workspace, junto con su entrada de descripción de plugin — y elimina los que ninguna fijación nombra; clear actúa sobre todo, por lo que pregunta antes de empezar.

Una raíz de workspace que no se puede usar. Cuando la raíz de workspace que recibe el comando es un archivo o una ruta que no existe, status, evict y clear actúan solo sobre los almacenes de toda la máquina, terminan como lo harían en otro caso y lo indican en la salida de error estándar, con las mismas palabras con las que cualquier otro comando rechaza esa raíz:

note: —workspace-root names the workspace root "<root>", which is not a directory: <root>; only the machine-wide caches are acted on (nota: —workspace-root nombra una raíz de workspace que no es un directorio; solo se actúa sobre las cachés de toda la máquina)

Una ruta que no existe muestra which cannot be used: y el motivo en lugar de which is not a directory:. prune, en cambio, se detiene, ya que necesita los lockfiles del workspace.

Esto se aplica desde dondequiera que se invoque la operación, no solo en un terminal. Las mismas operaciones son accesibles desde una sesión del editor y desde la llamada a una herramienta de un asistente, y sus respuestas indican el mismo alcance por el mismo motivo. Para saber cuándo un asistente puede invocarlas en tu nombre, consulta aggrega mcp.

El directorio de la caché de artefactos es el único lugar desde el que se lee, en el que se escribe y del que se elimina todo lo que hay en la caché — tanto el .aggrega/cache predeterminado como un directorio que nombra artifact_cache_dir y que sale de la raíz del workspace (../shared-cache). Cualquier elemento de su interior que sea un enlace simbólico que conduce fuera de ese directorio — uno de los directorios propios de la caché, como .aggrega/cache/inputs, o un archivo dentro de uno de ellos — no se usa para leer, escribir ni eliminar, aunque el enlace conduzca a otro directorio del mismo workspace. Lo que una escritura puede alcanzar bajo el directorio de la caché es exactamente lo que puede alcanzar una eliminación.

  • Un pull, una compilación y cualquier otra operación que escribe en la caché se detienen con E0320, nombrando el enlace y adónde conduce, y no escriben nada.
  • status, prune y clear no listan nada a través de un enlace así. Cuando uno de los directorios propios de la caché es el enlace, status se detiene con E0321, y un prune o un clear se detiene con E0320 antes de listar o eliminar nada — de modo que no se elimina nada de aquello a lo que apunta el enlace, y el enlace se queda donde está. Cuando el enlace es un archivo dentro de uno de ellos, los tres se detienen con E0321.
  • Una compilación, un pull y cualquier otra operación que lee la caché se detienen con E0321 en lugar de leer bytes guardados en otro lugar, aunque esos bytes coincidieran con el digest que registra el lockfile.
  • Un enlace que permanece dentro del directorio de la caché se sigue. Cuando uno de los directorios propios de la caché es un enlace a otro directorio dentro del directorio de la caché, ese directorio es de la caché: status lista lo que hay allí, prune elimina de allí, y clear lo vacía, conserva el enlace e informa de los bytes que eliminó allí.

El propio directorio de la caché. Un artifact_cache_dir escrito dentro de la raíz del workspace — incluido el predeterminado — puede ser a su vez un enlace a otro directorio del workspace, y la caché se guarda entonces donde conduce el enlace. Uno que conduce fuera del workspace se rechaza: cualquier operación que lo encuentre se detiene con E0321 o E0320, nombrando el enlace, antes de que se lea o escriba nada a través de él. Un directorio escrito saliendo de la raíz del workspace se respeta allí adonde conduce, aunque sea él mismo un enlace.

Elimina el enlace y vuelve a hacer pull para llenar la caché en su sitio. Para guardar la caché en otro lugar, establece artifact_cache_dir en ese directorio, escrito de forma relativa a la raíz del workspace, en lugar de enlazar a él: un directorio nombrado allí se lee y se escribe donde conduce. Los almacenes de toda la máquina no están sujetos a ningún workspace; uno que guardes en otro lugar mediante un enlace se lista, se poda y se vacía donde conduce el enlace, y clear conserva el enlace. El límite del workspace expone la regla completa.

Véase también

  • aggrega-pull — resuelve las dependencias de una Release en el lockfile y la caché.
  • aggrega-config — dónde se escriben artifact_cache_dir y las demás opciones de la caché.