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

aggrega explain

Explicar la condición de detención que nombra un código

Sinopsis

aggrega explain <code>

Descripción

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.

Qué hace

Un build que se detiene imprime un encabezado entre corchetes que nombra la categoría a la que es atribuible el fallo y el código corto de la condición — la letra E y cuatro dígitos:

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

aggrega explain E0209 convierte ese código en la condición que nombra y en la guía paso a paso de la corrección:

Terminal window
aggrega explain E0209

La respuesta empieza con los dos identificadores de la condición y la frase fija con la que comienzan sus diagnósticos, y después reproduce la entrada que explica qué causa la condición y qué cambiar — la misma entrada publicada en fatal-halts.md.

El código que se debe pasar

Se acepta cualquiera de los dos códigos de la condición, porque cada uno te llega en una superficie distinta.

El código corto es el que te muestra un terminal, y es el que debes usar cuando solo tienes la salida impresa. Un número se asigna una vez y luego queda fijo, así que un código corto que pegaste en un informe hace un año sigue nombrando la condición que nombraba entonces.

El código descriptivo es el que lleva guiones, que un diagnóstico estructurado incluye como campo propio y en el que se ramifica un programa. Nombra la condición con palabras y no lleva prefijo, así que permanece fijo incluso cuando el compilador se reorganiza a su alrededor. Si es el que tienes a mano, pásalo en su lugar — la condición anterior está registrada como recipe-values-mapping-requires-source:

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

Los dos códigos de una condición nombran la misma condición, así que ambas grafías obtienen la misma respuesta. El código corto se compara sin distinguir mayúsculas y minúsculas, ya que es un valor que lees en una pantalla y vuelves a escribir.

sentinels.md explica los tres identificadores que lleva una condición y cuándo usar cada uno.

De dónde viene la respuesta

Toda condición que declara este binario se responde desde el binario. Sus dos códigos y la frase con la que empiezan sus diagnósticos están declarados dentro del compilador, así que para eso no hace falta red, caché ni configuración.

Un código que este binario no declara se busca en la referencia publicada. Un plugin informa de una detención eligiendo una condición que declara el compilador, así que ninguna condición se declara en ningún otro lugar. La referencia publicada, sentinels.md, enumera todas las condiciones que declara el producto, y puede haberse publicado para una versión distinta del binario que estás ejecutando — así que un código citado de un informe hecho con una versión más reciente o más antigua todavía puede resolverse allí.

La guía paso a paso también es documentación publicada, leída de fatal-halts.md. Ambas páginas provienen del paquete de documentación, que se guarda una vez por máquina en la caché que comparten todos los proyectos de Aggrega, una copia por cada registro y versión — consulta aggrega cache. El paquete que se lee es el publicado para la versión de aggrega que estás ejecutando; cuando no hay ninguno publicado para esa versión, es el más reciente publicado para una versión anterior — la misma elección que hace aggrega scaffold --example, de modo que ambos nunca leen documentación distinta. Un código que no figura en la referencia de una versión anterior puede nombrar una condición declarada después, así que se rechaza como indeterminado en lugar de como un código que no nombra nada, y el rechazo indica de qué versión se leyó la referencia. Tu workspace decide de qué registro procede el paquete, su registro predeterminado, y si puede leerse una copia que ya está en la máquina: antes de servir una página, las firmas guardadas junto a la copia se verifican de nuevo con la comprobación de firmas de tu workspace para ese registro, la misma comprobación a la que se somete una descarga del paquete. Esa comprobación también se ejecuta sin conexión. Cuando fija una clave o una raíz de confianza, lee solo esas; cuando no fija ninguna de las dos, como hace la comprobación integrada del hub oficial, verifica frente a la raíz de confianza pública de Sigstore, que un workspace sin conexión no puede descargar — así que, sin conexión, verifica frente a la raíz de confianza que una descarga anterior con conexión en esta máquina dejó en .sigstore en tu directorio personal, y no descarga nada. Cuando la máquina no tiene ninguna copia, o ninguna que tu comprobación admita, el comando obtiene una con esa comprobación, una sola vez, y después lee de la caché. La misma copia sirve la documentación que lee un asistente a través de aggrega mcp y las explicaciones que muestra un editor a través de aggrega serve.

Conviene reconocer tres respuestas, porque cada una te pide algo distinto.

Una condición todavía sin entrada. Se informan los códigos y la frase, y una nota indica que la página de condiciones de detención no contiene ninguna guía paso a paso para esa condición. Toda condición sigue figurando en sentinels.md.

No hay documentación disponible. Para una condición que declara el compilador, se siguen informando los códigos y la frase, y una nota nombra el paquete y la versión que no se pudieron leer. Para un código que este binario no declara no queda nada con lo que responder, así que el código se rechaza — y el rechazo indica que no se pudo leer la referencia, porque sin ella un código de otra versión no puede distinguirse de una errata, y deja abiertas ambas soluciones: corregir el código u obtener la documentación. La causa habitual es un workspace fijado sin conexión, o uno que nunca ha llegado a su registro. Cuando la máquina contiene una copia que la comprobación de firmas de tu workspace no admite — una que otro proyecto descargó con una configuración más permisiva, o una que un workspace sin conexión no puede comprobar porque esta máquina nunca ha descargado la raíz de confianza pública frente a la que verifica su comprobación —, la nota indica que la copia se rechazó en lugar de faltar, y por qué. Cuando no hay ningún paquete publicado para tu versión y el más reciente anterior está en un formato que esta versión de aggrega ya no lee — por ejemplo, una versión candidata ejecutada antes de que se publique su propia documentación —, la nota indica ambas cosas en una sola 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

Un número retirado. Un número que nombraba una condición y ya no lo hace se responde como retirado, con lo que nombraba, en lugar de como un código que nunca existió — y nunca se responde con una condición distinta, porque un número retirado no se vuelve a asignar.

Ejemplos

Explicar un código tomado directamente de un build fallido:

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

Explicar un código con el que coincidió un programa:

Terminal window
aggrega explain plugin-value-not-representable

La misma respuesta desde un asistente

Un asistente de IA conectado a través de aggrega mcp llega a esta misma explicación mediante la herramienta explain-error. Pásale el texto del diagnóstico en lugar de un código suelto — un asistente tiene lo que imprimió el build —, y cuando ese texto empieza con un código corto, la respuesta contiene la condición, la frase con la que empiezan sus diagnósticos y la guía paso a paso publicada de la corrección, compuestas igual que la respuesta anterior. También contiene el código descriptivo, para que el asistente pueda ramificarse en él en lugar de en la redacción de un mensaje, y la dirección en la que está publicada la condición.

Todo lo que las secciones anteriores dicen sobre una guía paso a paso que falta se aplica también allí: una condición para la que la página no documenta ninguna entrada, y un workspace que no puede leer la documentación, dejan cada uno la condición respondida con una nota que indica de qué caso se trata. Allí también un número retirado se responde como retirado, con lo que nombraba, de modo que un asistente que recibe un diagnóstico antiguo sabe que el número ya no está en uso en lugar de ser enviado a una página sobre otra cosa. La superficie del asistente obtiene la documentación una vez al abrirse la sesión, así que una explicación lee lo que ya está en caché.

El daemon responde a la misma pregunta para un editor, a partir de un código en lugar de un diagnóstico. Los tres son una sola explicación en tres presentaciones, no tres respuestas que resultan coincidir.