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. Передайте йому текст діагностичного повідомлення, а не лише код, — асистент має те, що вивела збірка, — і якщо цей текст починається з короткого коду, відповідь містить умову, речення, з якого починаються її діагностичні повідомлення, та опублікований покроковий опис виправлення, складені так само, як у відповіді вище. Вона також містить описовий код, щоб асистент міг розгалужуватися за ним, а не за формулюванням повідомлення, і адресу, за якою опубліковано умову.
Усе, що в розділах вище сказано про відсутній покроковий опис, справджується й там: і умова, для якої сторінка не документує запису, і робочий простір, що не може прочитати документацію, дають відповідь з умовою та приміткою, яка вказує, що саме сталося. Вилучений номер там так само дістає відповідь як вилучений, із зазначенням того, що він позначав, тож асистент, якому передали старе діагностичне повідомлення, дізнається, що номер більше не використовується, а не потрапляє на сторінку про щось інше. Інтерфейс асистента отримує документацію один раз під час відкриття сеансу, тож розгортання читає те, що вже є в кеші.
Демон відповідає на те саме питання для редактора — за кодом, а не за діагностичним повідомленням. Усі три — це одне розгортання у трьох поданнях, а не три відповіді, які випадково збігаються.