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 explain

Explicar a condição de interrupção que um código nomeia

Sinopse

aggrega explain <code>

Descrição

Explain the halting condition a code names.
A halting diagnostic opens with the category the failure is attributable to and the condition's short code — the letter E and four digits, as in [CATALOG_ERROR E0209]. That short code is the one to pass here; it is fixed once a condition is published, so a code quoted out of an old report still names the same condition.
aggrega explain E0209
The descriptive code is accepted too — the hyphenated one naming the condition in words, which a structured diagnostic carries as a field of its own. A condition's two codes name the same condition and reach different readers, so either is a code you may be holding, and the condition above is registered under recipe-values-mapping-requires-source:
aggrega explain recipe-values-mapping-requires-source
Every condition is declared inside this binary, so the identifiers and the sentence are reported without a network or a cache. The published reference supplies the walk-through of the authoring fix for every condition, and nothing else is resolved against it. It is read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version — kept in the cache every project on this machine shares, acquired on first use when that cache holds no copy this workspace's signature check admits. Where it cannot be acquired, the condition is still reported and the reason the walk-through is missing is stated.
A number that named a condition and no longer does is reported as retired, with what it named, so a code quoted from an old report is never answered with a different condition.

O que ele faz

Um build que é interrompido imprime um cabeçalho entre colchetes que nomeia a categoria à qual a falha é atribuível e o código curto da condição — a letra E e quatro dígitos:

[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...

aggrega explain E0209 transforma esse código na condição que ele nomeia e no passo a passo da correção:

Terminal window
aggrega explain E0209

A resposta começa com os dois identificadores da condição e a frase fixa com que seus diagnósticos começam, e depois reproduz a entrada que explica o que causa a condição e o que mudar — a mesma entrada publicada em fatal-halts.md.

O código a passar

Qualquer um dos dois códigos da condição é aceito, porque cada um chega até você em uma superfície diferente.

O código curto é o que um terminal mostra, e é o que você deve usar quando tudo o que tem é a saída impressa. Um número é atribuído uma vez e depois fica fixo, então um código curto que você colou em um relatório há um ano ainda nomeia a condição que nomeava na época.

O código descritivo é o hifenizado que um diagnóstico estruturado traz como um campo próprio, e no qual um programa se ramifica. Ele nomeia a condição em palavras e não tem prefixo, então permanece fixo mesmo quando o compilador é reorganizado ao seu redor. Se é esse que você tem em mãos, passe-o — a condição acima está registrada como recipe-values-mapping-requires-source:

Terminal window
aggrega explain recipe-values-mapping-requires-source

Os dois códigos de uma condição nomeiam a mesma condição, então ambas as grafias recebem a mesma resposta. O código curto é comparado sem diferenciar maiúsculas e minúsculas, já que é um valor que você lê em uma tela e digita de volta.

sentinels.md explica os três identificadores que uma condição traz e quando usar cada um.

De onde vem a resposta

Toda condição que este binário declara é respondida a partir do binário. Seus dois códigos e a frase com que seus diagnósticos começam são declarados dentro do compilador, então isso não exige rede, cache nem configuração.

Um código que este binário não declara é procurado na referência publicada. Um plugin relata uma interrupção escolhendo uma condição que o compilador declara, então nenhuma condição é declarada em nenhum outro lugar. A referência publicada, sentinels.md, lista todas as condições que o produto declara, e ela pode ter sido publicada para uma versão diferente do binário que você está executando — então um código citado de um relatório feito com uma versão mais nova ou mais antiga ainda pode ser resolvido lá.

O passo a passo também é documentação publicada, lido de fatal-halts.md. Ambas as páginas vêm do pacote de documentação, que é mantido uma vez por máquina no cache compartilhado por todos os projetos Aggrega, uma cópia para cada registry e versão — consulte aggrega cache. O pacote lido é o publicado para a versão do aggrega que você está executando; quando nenhum é publicado para essa versão, é o mais recente publicado para uma versão anterior — a mesma escolha que aggrega scaffold --example faz, de modo que os dois nunca leem documentação diferente. Um código que a referência de uma versão anterior não contém pode nomear uma condição declarada depois, então ele é recusado como indeterminado, e não como um código que não nomeia nada, e a recusa diz de qual versão a referência foi lida. Seu workspace decide de qual registry o pacote vem, o seu registry padrão, e se uma cópia já presente na máquina pode ser lida: antes que uma página seja servida, as assinaturas mantidas ao lado da cópia são verificadas novamente pela verificação de assinaturas do seu workspace para esse registry, a mesma verificação à qual um download do pacote está sujeito. Essa verificação também é executada offline. Quando ela fixa uma chave ou uma raiz de confiança, lê apenas essas; quando não fixa nenhuma das duas, como faz a verificação integrada do hub oficial, ela verifica em relação à raiz de confiança pública do Sigstore, que um workspace offline não consegue baixar — então, offline, ela verifica em relação à raiz de confiança que um download online anterior nesta máquina deixou em .sigstore no seu diretório pessoal, e não baixa nada. Quando a máquina não tem nenhuma cópia, ou nenhuma que sua verificação admita, o comando obtém uma sob essa verificação, uma única vez, e depois lê do cache. A mesma cópia serve a documentação que um assistente lê por meio de aggrega mcp e as explicações que um editor mostra por meio de aggrega serve.

Vale a pena reconhecer três respostas, porque cada uma pede algo diferente de você.

Uma condição ainda sem entrada. Os códigos e a frase são informados, e uma nota diz que a página de condições de interrupção não traz nenhum passo a passo para essa condição. Toda condição continua listada em sentinels.md.

Nenhuma documentação disponível. Para uma condição que o compilador declara, os códigos e a frase ainda são informados, e uma nota nomeia o pacote e a versão que não puderam ser lidos. Para um código que este binário não declara, não resta nada com que responder, então o código é recusado — e a recusa diz que a referência não pôde ser lida, porque sem ela um código de outra versão não pode ser distinguido de um erro de digitação, e deixa abertos os dois reparos: corrigir o código ou obter a documentação. A causa habitual é um workspace fixado como offline, ou um que nunca alcançou seu registry. Quando a máquina contém uma cópia que a verificação de assinaturas do seu workspace não admite — uma que outro projeto baixou com uma configuração mais permissiva, ou uma que um workspace offline não consegue verificar porque esta máquina nunca baixou a raiz de confiança pública em relação à qual sua verificação valida —, a nota diz que a cópia foi recusada, e não que está ausente, e por quê. Quando nenhum pacote é publicado para a sua versão e o mais recente anterior está em um formato que esta versão do aggrega não lê mais — uma versão candidata executada antes de sua própria documentação ser publicada, por exemplo —, a nota diz as duas coisas em uma única frase:

hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the walk-through is not shown here; every condition, including the ones a provider declares, is published at aggrega-docs/language-reference/errors/sentinels.md, and the walk-through of each authoring fix at aggrega-docs/language-reference/errors/fatal-halts.md

Um número aposentado. Um número que nomeava uma condição e não nomeia mais é respondido como aposentado, com o que nomeava, em vez de como um código que nunca existiu — e nunca é respondido com uma condição diferente, porque um número aposentado não é atribuído novamente.

Exemplos

Explicar um código tirado diretamente de um build que falhou:

Terminal window
aggrega build --release release.yaml || aggrega explain E0209

Explicar um código com o qual um programa fez correspondência:

Terminal window
aggrega explain plugin-value-not-representable

A mesma resposta a partir de um assistente

Um assistente de IA conectado por meio de aggrega mcp acessa essa mesma explicação por meio da ferramenta explain-error. Passe a ele o texto do diagnóstico em vez de um código isolado — um assistente tem o que o build imprimiu —, e quando esse texto começa com um código curto, a resposta traz a condição, a frase com que seus diagnósticos começam e o passo a passo publicado da correção, compostos da mesma forma que a resposta acima. Ela também traz o código descritivo, para que o assistente possa se ramificar nele em vez de na redação de uma mensagem, e o endereço em que a condição está publicada.

Tudo o que as seções acima dizem sobre um passo a passo ausente vale ali também: uma condição para a qual a página não documenta nenhuma entrada, e um workspace que não consegue ler a documentação, deixam cada um a condição respondida com uma nota que diz qual era o caso. Um número aposentado também é respondido ali como aposentado, com o que nomeava, de modo que um assistente que recebe um diagnóstico antigo descobre que o número não está mais em uso em vez de ser enviado para uma página sobre outra coisa. A superfície do assistente obtém a documentação uma vez quando a sessão é aberta, então uma explicação lê o que já está em cache.

O daemon responde à mesma pergunta para um editor, a partir de um código em vez de um diagnóstico. As três são uma única explicação em três apresentações, e não três respostas que por acaso coincidem.