aggrega explain
Объяснение условия остановки, которое обозначает код
Синтаксис
aggrega explain <code>Описание
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.Что делает команда
Остановившаяся сборка выводит заголовок в квадратных скобках, где названы категория, к которой относится сбой, и короткий код условия — буква E и четыре цифры:
[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...aggrega explain E0209 превращает этот код в условие, которое он обозначает, и пошаговое описание исправления в исходных файлах:
aggrega explain E0209Ответ начинается с обоих идентификаторов условия и фиксированной фразы, с которой начинаются его диагностические сообщения, а затем воспроизводит статью, объясняющую, что вызывает условие и что нужно изменить, — ту же статью, что опубликована в fatal-halts.md.
Какой код передавать
Принимается любой из двух кодов условия, потому что каждый из них попадает к вам в разном месте.
Короткий код показывает терминал, и именно его следует использовать, когда у вас есть только напечатанный вывод. Номер выдаётся один раз и затем не меняется, поэтому короткий код, вставленный вами в отчёт год назад, по-прежнему обозначает то же условие, что и тогда.
Описательный код — это код через дефис, который структурированное диагностическое сообщение содержит в отдельном поле и по которому ветвится программа. Он называет условие словами и не имеет префикса, поэтому остаётся неизменным, даже когда компилятор вокруг него реорганизуется. Если у вас именно он, передайте его — условие выше зарегистрировано как recipe-values-mapping-requires-source:
aggrega explain recipe-values-mapping-requires-sourceОба кода условия обозначают одно и то же условие, поэтому на оба написания приходит одинаковый ответ. Короткий код сопоставляется без учёта регистра, так как это значение, которое вы считываете с экрана и вводите заново.
В sentinels.md описаны три идентификатора условия и случаи, когда следует использовать каждый из них.
Откуда берётся ответ
На каждое условие, объявленное этим исполняемым файлом, ответ даёт сам исполняемый файл. Его два кода и фраза, с которой начинаются его диагностические сообщения, объявлены внутри компилятора, поэтому для этой части не нужны ни сеть, ни кэш, ни настройка.
Код, который этот исполняемый файл не объявляет, ищется в опубликованном справочнике. Плагин сообщает об остановке, выбирая условие, объявленное компилятором, поэтому никакие условия не объявляются где-либо ещё. Опубликованный справочник, sentinels.md, перечисляет все условия, объявленные продуктом, и он мог быть опубликован для другой версии, чем запущенный вами исполняемый файл, — поэтому код, процитированный из отчёта, созданного более новым или более старым выпуском, всё равно может там разрешиться.
Пошаговое описание — тоже опубликованная документация, которая читается из fatal-halts.md. Обе страницы берутся из пакета документации, который хранится на машине в единственном экземпляре в кэше, общем для всех проектов Aggrega, по одной копии для каждого реестра и версии, — см. aggrega cache. Читается пакет, опубликованный для запущенной вами версии aggrega; если для этой версии ничего не опубликовано, читается самый новый пакет, опубликованный для более раннего выпуска, — тот же выбор, что делает aggrega scaffold --example, поэтому эти две команды никогда не читают разную документацию. Код, которого нет в справочнике более раннего выпуска, может обозначать условие, объявленное позднее, поэтому он отклоняется как неопределённый, а не как код, который ничего не обозначает, и в отказе сказано, справочник какой версии был прочитан. Ваше рабочее пространство определяет, из какого реестра берётся пакет, а именно из своего реестра по умолчанию, и можно ли читать копию, уже имеющуюся на машине: перед выдачей страницы подписи, хранящиеся рядом с копией, заново проверяются собственной проверкой подписей вашего рабочего пространства для этого реестра — той же, которой подчиняется загрузка пакета. Эта проверка выполняется и в автономном режиме. Если она закрепляет ключ или корень доверия, она читает только их; если не закрепляет ни того, ни другого, как встроенная проверка официального хаба, она проверяет по публичному корню доверия Sigstore, который автономное рабочее пространство загрузить не может, — поэтому в автономном режиме она проверяет по корню доверия, оставленному предыдущей онлайн-загрузкой на этой машине в .sigstore в вашем домашнем каталоге, и ничего не загружает. Если на машине нет копии или нет копии, допускаемой вашей проверкой, команда один раз получает её с этой проверкой и затем читает из кэша. Та же копия обслуживает документацию, которую ассистент читает через aggrega mcp, и пояснения, которые редактор показывает через aggrega serve.
Три ответа стоит уметь распознавать, потому что каждый требует от вас своего.
Условие, для которого ещё нет статьи. Выводятся коды и фраза, а примечание сообщает, что на странице условий остановки нет пошагового описания для этого условия. Все условия по-прежнему перечислены в sentinels.md.
Документация недоступна. Для условия, объявленного компилятором, коды и фраза всё равно выводятся, а примечание называет пакет и версию, которые не удалось прочитать. Для кода, который этот исполняемый файл не объявляет, ответить нечем, поэтому код отклоняется — и в отказе сказано, что справочник не удалось прочитать, потому что без него код из другой версии невозможно отличить от опечатки, и оба способа исправления остаются открытыми: исправить код или получить документацию. Обычная причина — рабочее пространство, закреплённое в автономном режиме, или такое, которое ни разу не обращалось к своему реестру. Если на машине есть копия, которую проверка подписей вашего рабочего пространства не допускает, — загруженная другим проектом с менее строгой настройкой или такая, которую автономное рабочее пространство не может проверить, потому что эта машина ни разу не загружала публичный корень доверия, по которому выполняется проверка, — примечание сообщает, что копия была отклонена, а не отсутствует, и почему. Если для вашей версии пакет не опубликован, а самый новый более ранний имеет формат, который эта версия aggrega больше не читает, — например, релиз-кандидат, запущенный до публикации собственной документации, — примечание сообщает об обоих фактах в одном предложении:
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Выведенный из употребления номер. На номер, который обозначал условие, но больше не обозначает, приходит ответ, что он выведен из употребления, с указанием того, что он обозначал, а не как на код, которого никогда не существовало, — и в ответ никогда не выдаётся другое условие, потому что выведенный номер повторно не выдаётся.
Примеры
Объяснение кода прямо из неудавшейся сборки:
aggrega build --release release.yaml || aggrega explain E0209Объяснение кода, по которому сопоставлялась программа:
aggrega explain plugin-value-not-representableТот же ответ от ассистента
ИИ-ассистент, подключённый через aggrega mcp, получает то же развёрнутое объяснение через инструмент explain-error. Передайте ему текст диагностического сообщения, а не голый код, — у ассистента есть то, что напечатала сборка, — и если этот текст начинается с короткого кода, ответ содержит условие, фразу, с которой начинаются его диагностические сообщения, и опубликованное пошаговое описание исправления, составленные так же, как в ответе выше. Он также содержит описательный код, чтобы ассистент мог ветвиться по нему, а не по формулировке сообщения, и адрес, по которому опубликовано условие.
Всё, что в разделах выше сказано об отсутствующем пошаговом описании, верно и там: условие, для которого на странице нет статьи, и рабочее пространство, не способное прочитать документацию, — в обоих случаях на условие даётся ответ с примечанием о том, какой это случай. Выведенный из употребления номер там тоже получает ответ как выведенный, с указанием того, что он обозначал, поэтому ассистент, получивший старое диагностическое сообщение, узнаёт, что номер больше не используется, а не отправляется на страницу о чём-то другом. Интерфейс ассистента получает документацию один раз при открытии сеанса, поэтому развёрнутое объяснение читает то, что уже находится в кэше.
Демон отвечает на тот же вопрос для редактора — по коду, а не по диагностическому сообщению. Все три — одно и то же развёрнутое объяснение в трёх представлениях, а не три ответа, которые случайно совпадают.