Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

aggrega cache

Inspecionar e manter os caches em disco

Sinopse

aggrega cache

Descrição

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

ComandoDescrição
aggrega cache clearApaga todos os caches, incluindo os módulos compilados
aggrega cache evictReduz o cache de módulos compilados até um limite de tamanho, começando pelos mais antigos
aggrega cache pruneRemove entradas do cache de artefatos que nenhum lockfile referencia
aggrega cache statusLista o conteúdo do cache e um resumo total

Descrição 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

FlagPadrãoDescrição
--yesfalseignora a solicitação de confirmação (para uso não interativo/CI)

Descrição 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

FlagPadrãoDescrição
--max-size—limite de tamanho para o cache de módulos compilados (por exemplo, 5GiB, 512MiB ou uma contagem de bytes); obrigatório

Descrição 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.

Descrição 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.

O que o cache é, e o que ele não é

O cache de artefatos em artifact_cache_dir (.aggrega/cache por padrão) contém o que uma busca colocou ali: entidades de catálogo e artefatos de origem, cada um armazenado sob seu tipo e a coordenada e a versão com que foi buscado, e garantido por um digest que o lockfile registra. Ele não é um diretório de catálogo, e uma varredura do catálogo o ignora — então o conteúdo presente no cache é lido como dependência, por meio do pin que o garante, e nunca como uma entidade escrita por você.

A consequência que você tem mais chance de encontrar. Se o cache contém uma entidade que nenhum lockfile fixa com um pin, essa entidade fica invisível para um build, e um build que precisa dela é interrompido dizendo que ela não foi encontrada. A interrupção nomeia a entidade, então o pin ausente pode ser identificado pela mensagem.

Quando a entidade é uma SchemaLibrary alcançada por um $ref:, todo comando que informa a referência como não resolvida faz o relato ser seguido de uma linha remediation: que nomeia cada biblioteca que o cache contém e que nenhuma entrada de lockfile fixa nem nenhum diretório de catálogo fornece, e a ação que funciona para aquele comando:

  • aggrega build e aggrega validate --release <release> leem o lockfile da Release, então a linha nomeia aggrega pull --release <release> para resolver a biblioteca e registrar sua entrada.
  • aggrega validate sem argumento, e aggrega validate <entity-path> com ou sem --release, leem bibliotecas apenas dos diretórios de catálogo e não leem nenhum lockfile, então nenhuma entrada registrada muda seu veredito. A linha diz isso e nomeia aggrega pull --release <release> seguido de aggrega validate --release <release>, que verifica a Release em relação ao que seu lockfile fixa.
  • aggrega pull, e aggrega build --auto-pull, no modo offline não conseguem nem buscar a biblioteca nem registrar uma entrada para ela, então a linha diz para executar aggrega pull --release <release> onde for possível alcançar um registry. Com conexão, um pull que não encontra a biblioteca em nenhum diretório de catálogo e em nenhum registry que lê não tem entrada para registrar.

Cada uma dessas linhas também oferece o outro caminho: escrever a biblioteca em um diretório de catálogo.

O que executar. aggrega pull --release <release> resolve a entidade e registra seu digest, depois do que o mesmo build a encontra. Quando a entidade é sua e não uma dependência, escreva-a em um diretório listado em workspace.catalog_dirs — uma varredura lê esse diretório. aggrega cache prune elimina as entradas que nenhum lockfile referencia, que é a metade de limpeza da mesma regra.

Para o layout do cache, o contrato de artifact_cache_dir e o motivo pelo qual um artefato de resolução deliberadamente não pode ser lido como conteúdo escrito, consulte architecture/13-catalog-and-registry.md.

Quais caches pertencem a este projeto e quais à máquina

Nem todo cache em que esses comandos atuam é restrito ao projeto em que você está, e a diferença decide até onde vai uma recuperação de espaço.

Só seu. O cache de artefatos em artifact_cache_dir — as entidades, os artefatos de origem e as entradas externas com pin que este projeto resolveu, e os snapshots do catálogo publicado que uma importação que não indica nenhuma pasta de catálogo leu. Recuperar espaço dele afeta este projeto e nada mais.

Compartilhados por todos os projetos Aggrega nesta máquina. O armazenamento de módulos compilados, o armazenamento de descrições de plugins, o armazenamento de pacotes de documentação e o armazenamento de plugins cli. O guest de um provider é compilado uma vez e reutilizado por todos os projetos, o que torna rápido o segundo build de qualquer coisa, então remover uma entrada significa que o próximo build de qualquer projeto na máquina o recompila. O pacote de documentação — as páginas publicadas de onde aggrega explain, as explicações de um editor e os recursos de documentação de um assistente são lidos, e os exemplos executáveis que aggrega scaffold --example grava — é mantido uma única vez por registry e versão, porque seu conteúdo não depende de mais nada: o primeiro deles que o busca o busca para todos os projetos, e ainda assim cada projeto só o recebe quando a própria verificação de assinatura admite a cópia. Nada se perde permanentemente — um módulo removido é reconstruído sob demanda, e um pacote removido é buscado novamente pela próxima explicação ou pelo próximo exemplo, ou por um servidor de assistente na próxima vez que ele iniciar —, mas o custo recai sobre quem fizer o próximo build, que pode não ser você.

O armazenamento de plugins cli guarda os bytes de cada plugin cli adicionado com aggrega plugin add cli em uma pasta que não é um workspace, de modo que seu comando é executado a partir de qualquer pasta; um plugin cli adicionado dentro de um workspace mantém, em vez disso, seus bytes no cache de artefatos desse workspace. Ao contrário de um módulo compilado ou de um pacote, um plugin cli cujos bytes são removidos não é buscado novamente por conta própria: até que aggrega plugin add cli <name> o adicione novamente, seu comando fica ausente e todo comando avisa que ele não pôde ser adicionado, nomeando o comando aggrega plugin add cli que o adiciona novamente na versão que sua configuração fixa.

Os armazenamentos de toda a máquina ficam onde cada plataforma mantém os caches de um usuário: no Windows em aggrega\cache dentro do diretório que a variável de ambiente LOCALAPPDATA nomeia, em ~/Library/Caches/aggrega no macOS, e em um diretório aggrega dentro daquele que XDG_CACHE_HOME nomeia — ~/.cache/aggrega quando XDG_CACHE_HOME não está definida — no Linux e nos demais sistemas Unix. aggrega config init imprime o diretório na máquina em que é executado. Quando nenhuma dessas variáveis está definida, os plugins compilados são mantidos apenas durante a execução, e nenhum pacote de documentação é mantido: uma explicação diz então por que falta seu passo a passo, os recursos de documentação de um assistente respondem “não encontrado”, e aggrega scaffold --example recusa, dizendo que nenhum diretório de cache é resolvido; aggrega plugin add cli executado em uma pasta que não é um workspace também recusa, dizendo que nenhum local de cache de toda a máquina é resolvido.

aggrega cache status informa isso por classe em vez de deixar que seja deduzido pelo nome: cada classe é informada como abrangendo o workspace ou a máquina, e o mesmo alcance é informado para cada elemento que prune, evict e clear removem. evict atua apenas no armazenamento compartilhado de módulos compilados; prune nunca remove um pacote de documentação nem um snapshot de catálogo que uma importação leu, já que nenhum lockfile referencia nenhum dos dois, e informa cada uma dessas classes como não elegível para prune; prune mantém os bytes de cada plugin cli que a lista plugins.cli da sua configuração fixa — tanto no armazenamento de plugins cli quanto no cache de artefatos do workspace, junto com sua entrada de descrição de plugin — e remove aqueles que nenhuma fixação nomeia; clear atua em tudo, e é por isso que pergunta antes de começar.

Uma raiz de workspace que não pode ser usada. Quando a raiz de workspace passada ao comando é um arquivo ou um caminho que não existe, status, evict e clear agem apenas sobre os armazenamentos da máquina inteira, terminam como terminariam em outro caso e informam isso na saída de erro padrão, com as mesmas palavras com que qualquer outro comando recusa essa raiz:

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 nomeia uma raiz de workspace que não é um diretório; age-se apenas sobre os caches da máquina inteira)

Um caminho que não existe mostra which cannot be used: e o motivo no lugar de which is not a directory:. Já prune para, pois precisa dos lockfiles do workspace.

Isso se aplica de onde quer que a operação seja invocada, não só em um terminal. As mesmas operações podem ser acessadas a partir de uma sessão do editor e da chamada de ferramenta de um assistente, e suas respostas informam o mesmo alcance pelo mesmo motivo. Para saber quando um assistente pode invocá-las em seu nome, consulte aggrega mcp.

O diretório do cache de artefatos é o único lugar de onde tudo no cache é lido, para onde é gravado e de onde é removido — tanto o .aggrega/cache padrão quanto um diretório que artifact_cache_dir nomeia e que sai da raiz do workspace (../shared-cache). Qualquer coisa dentro dele que seja um link simbólico que leve para fora desse diretório — um dos diretórios do próprio cache, como .aggrega/cache/inputs, ou um arquivo dentro de um deles — não é usado para leitura, gravação nem remoção, mesmo quando o link leva a outro diretório do mesmo workspace. O que uma gravação pode alcançar sob o diretório do cache é exatamente o que uma remoção pode alcançar.

  • Um pull, um build e qualquer outra operação que grava no cache são interrompidos com E0320, nomeando o link e para onde ele leva, e não gravam nada.
  • status, prune e clear não listam nada por meio de um link assim. Quando um dos diretórios do próprio cache é o link, status é interrompido com E0321, e um prune ou um clear é interrompido com E0320 antes de listar ou remover qualquer coisa — assim, nada daquilo para que o link aponta é removido, e o link permanece onde está. Quando o link é um arquivo dentro de um deles, os três são interrompidos com E0321.
  • Um build, um pull e qualquer outra operação que lê o cache são interrompidos com E0321 em vez de ler bytes mantidos em outro lugar, mesmo quando esses bytes corresponderiam ao digest que o lockfile registra.
  • Um link que permanece dentro do diretório do cache é seguido. Quando um dos diretórios do próprio cache é um link para outro diretório dentro do diretório do cache, esse diretório pertence ao cache: status lista o que há ali, prune remove dali, e clear o esvazia, mantém o link e informa os bytes que removeu ali.

O próprio diretório do cache. Um artifact_cache_dir escrito dentro da raiz do workspace — incluindo o padrão — pode ser ele mesmo um link para outro diretório do workspace, e o cache é então mantido para onde o link leva. Um que leve para fora do workspace é recusado: qualquer operação que o encontre é interrompida com E0321 ou E0320, nomeando o link, antes que qualquer coisa seja lida ou gravada por meio dele. Um diretório escrito saindo da raiz do workspace é respeitado para onde leva, mesmo quando é ele próprio um link.

Remova o link e faça pull novamente para preencher o cache no lugar. Para manter o cache em outro lugar, defina artifact_cache_dir como esse diretório, escrito de forma relativa à raiz do workspace, em vez de criar um link para ele: um diretório nomeado ali é lido e gravado para onde leva. Os armazenamentos de toda a máquina não estão vinculados a nenhum workspace; um que você mantenha em outro lugar por meio de um link é listado, limpo e esvaziado para onde o link leva, e clear mantém o link. O limite do workspace apresenta a regra completa.

Veja também

  • aggrega-pull — resolve as dependências de uma Release no lockfile e no cache.
  • aggrega-config — onde artifact_cache_dir e as demais configurações de cache são escritas.