aggrega explain
Wyjaśnia warunek zatrzymania wskazany przez kod
Składnia
aggrega explain <code>Opis
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.Działanie
Kompilacja, która się zatrzymuje, wypisuje w nawiasach kwadratowych nagłówek wskazujący kategorię, której można przypisać błąd, oraz krótki kod warunku — literę E i cztery cyfry:
[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...aggrega explain E0209 zamienia ten kod na warunek, który wskazuje, oraz na omówienie poprawki po stronie autora:
aggrega explain E0209Odpowiedź zaczyna się od obu identyfikatorów warunku i stałego zdania, od którego zaczynają się jego diagnostyki, a następnie przytacza wpis wyjaśniający, co powoduje warunek i co należy zmienić — ten sam wpis, który opublikowano w fatal-halts.md.
Kod do przekazania
Akceptowany jest każdy z dwóch kodów warunku, ponieważ każdy z nich trafia do użytkownika innym kanałem.
Krótki kod to ten, który pokazuje terminal, i to po niego należy sięgnąć, gdy dostępne jest tylko wypisane wyjście. Numer jest przydzielany raz, a potem pozostaje stały, więc krótki kod wklejony do raportu rok temu nadal wskazuje ten sam warunek co wtedy.
Kod opisowy to kod z łącznikami, który diagnostyka strukturalna zawiera jako osobne pole i według którego program rozgałęzia działanie. Nazywa warunek słowami i nie ma prefiksu, więc pozostaje stały nawet wtedy, gdy kompilator zostanie wokół niego przeorganizowany. Jeśli to on jest dostępny, można przekazać właśnie jego — powyższy warunek jest zarejestrowany pod recipe-values-mapping-requires-source:
aggrega explain recipe-values-mapping-requires-sourceDwa kody warunku wskazują ten sam warunek, więc obie pisownie dają identyczną odpowiedź. Krótki kod jest dopasowywany bez względu na wielkość liter, ponieważ jest to wartość odczytywana z ekranu i wpisywana ponownie.
sentinels.md omawia trzy identyfikatory, które ma warunek, oraz to, kiedy sięgać po każdy z nich.
Skąd pochodzi odpowiedź
Każdy warunek deklarowany przez ten plik binarny jest objaśniany na podstawie pliku binarnego. Jego dwa kody i zdanie, od którego zaczynają się jego diagnostyki, są zadeklarowane w kompilatorze, więc ta część nie wymaga sieci, pamięci podręcznej ani konfiguracji.
Kod, którego ten plik binarny nie deklaruje, jest wyszukiwany w opublikowanej dokumentacji referencyjnej. Wtyczka zgłasza zatrzymanie, wybierając warunek deklarowany przez kompilator, więc żaden warunek nie jest deklarowany nigdzie indziej. Opublikowana dokumentacja referencyjna, sentinels.md, wymienia każdy warunek deklarowany przez produkt i mogła zostać opublikowana dla innej wersji niż uruchomiony plik binarny — dlatego kod zacytowany z raportu sporządzonego nowszym lub starszym wydaniem nadal może tam zostać rozwiązany.
Omówienie również jest opublikowaną dokumentacją, odczytywaną z fatal-halts.md. Obie strony pochodzą z pakietu dokumentacji, przechowywanego raz na maszynę w pamięci podręcznej współdzielonej przez wszystkie projekty Aggrega, po jednej kopii dla każdego rejestru i wersji — zob. aggrega cache. Odczytywany jest pakiet opublikowany dla uruchomionej wersji aggrega; jeśli dla tej wersji żaden nie został opublikowany, jest to najnowszy pakiet opublikowany dla wcześniejszego wydania — ten sam wybór, którego dokonuje aggrega scaffold --example, dzięki czemu oba polecenia nigdy nie odczytują różnej dokumentacji. Kod, którego nie zawiera dokumentacja referencyjna wcześniejszego wydania, może wskazywać warunek zadeklarowany później, dlatego jest odrzucany jako nierozstrzygnięty, a nie jako kod, który niczego nie wskazuje, a odrzucenie informuje, dokumentację referencyjną której wersji odczytano. Obszar roboczy określa, z którego rejestru pochodzi pakiet, czyli ze swojego domyślnego rejestru, oraz to, czy kopię już obecną na maszynie można odczytać: przed udostępnieniem strony podpisy przechowywane obok kopii są ponownie weryfikowane w ramach własnego sprawdzania podpisów obszaru roboczego dla tego rejestru, tego samego, któremu podlega pobranie pakietu. To sprawdzanie działa również offline. Jeśli przypina klucz lub korzeń zaufania, odczytuje tylko je; jeśli nie przypina żadnego z nich, jak wbudowane sprawdzanie oficjalnego huba, weryfikuje względem publicznego korzenia zaufania Sigstore, którego obszar roboczy offline nie może pobrać — dlatego offline weryfikuje względem korzenia zaufania pozostawionego w .sigstore w katalogu domowym przez wcześniejsze pobranie online na tej maszynie i niczego nie pobiera. Gdy na maszynie nie ma kopii lub nie ma takiej, którą dopuszcza sprawdzanie, polecenie raz pozyskuje kopię w ramach tego sprawdzania, a potem odczytuje ją z pamięci podręcznej. Ta sama kopia obsługuje dokumentację, którą asystent odczytuje przez aggrega mcp, oraz wyjaśnienia, które edytor pokazuje przez aggrega serve.
Warto rozpoznawać trzy odpowiedzi, ponieważ każda wymaga czegoś innego.
Warunek, który nie ma jeszcze wpisu. Zgłaszane są kody i zdanie, a uwaga informuje, że strona warunków zatrzymania nie zawiera omówienia tego warunku. Każdy warunek jest jednak wymieniony w sentinels.md.
Dokumentacja niedostępna. W przypadku warunku deklarowanego przez kompilator kody i zdanie są nadal zgłaszane, a uwaga podaje pakiet i wersję, których nie udało się odczytać. W przypadku kodu, którego ten plik binarny nie deklaruje, nie ma już nic, czym można by odpowiedzieć, więc kod zostaje odrzucony — a odrzucenie informuje, że nie udało się odczytać dokumentacji referencyjnej, ponieważ bez niej kodu z innej wersji nie da się odróżnić od literówki, i pozostawia otwarte obie naprawy: poprawienie kodu lub pobranie dokumentacji. Zwykle przyczyną jest obszar roboczy przypięty do trybu offline lub taki, który nigdy nie połączył się ze swoim rejestrem. Jeśli na maszynie jest kopia, której sprawdzanie podpisów obszaru roboczego nie dopuszcza — pobrana przez inny projekt przy luźniejszym ustawieniu lub taka, której obszar roboczy offline nie może sprawdzić, bo ta maszyna nigdy nie pobrała publicznego korzenia zaufania, względem którego weryfikuje jego sprawdzanie — uwaga informuje, że kopię odrzucono, a nie że jej brakuje, oraz dlaczego. Jeśli dla używanej wersji nie opublikowano żadnego pakietu, a najnowszy wcześniejszy ma format, którego ta wersja aggrega już nie odczytuje — na przykład w przypadku wersji kandydującej uruchomionej przed opublikowaniem jej własnej dokumentacji — uwaga podaje obie te informacje w jednym zdaniu:
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.mdWycofany numer. Numer, który wskazywał warunek, a już go nie wskazuje, jest objaśniany jako wycofany, wraz z tym, co wskazywał, a nie jako kod, który nigdy nie istniał — i nigdy nie jest objaśniany innym warunkiem, ponieważ wycofany numer nie jest przydzielany ponownie.
Przykłady
Wyjaśnienie kodu wziętego wprost z nieudanej kompilacji:
aggrega build --release release.yaml || aggrega explain E0209Wyjaśnienie kodu, do którego dopasował się program:
aggrega explain plugin-value-not-representableTa sama odpowiedź od asystenta
Asystent AI połączony przez aggrega mcp uzyskuje to samo rozwinięcie za pomocą narzędzia explain-error. Należy przekazać mu tekst diagnostyki, a nie sam kod — asystent ma to, co wypisała kompilacja — a jeśli ten tekst zaczyna się od krótkiego kodu, odpowiedź zawiera warunek, zdanie, od którego zaczynają się jego diagnostyki, oraz opublikowane omówienie poprawki po stronie autora, złożone tak samo jak powyższa odpowiedź. Zawiera też kod opisowy, dzięki czemu asystent może rozgałęziać działanie według niego, a nie według brzmienia komunikatu, oraz adres, pod którym opublikowano warunek.
Wszystko, co powyższe sekcje mówią o brakującym omówieniu, obowiązuje także tam: zarówno warunek, dla którego strona nie dokumentuje wpisu, jak i obszar roboczy, który nie może odczytać dokumentacji, kończą się objaśnieniem warunku z uwagą wskazującą, który przypadek zaszedł. Wycofany numer również tam jest objaśniany jako wycofany, wraz z tym, co wskazywał, więc asystent, który otrzyma starą diagnostykę, dowiaduje się, że numer nie jest już używany, zamiast zostać odesłanym do strony o czymś innym. Interfejs asystenta pobiera dokumentację raz przy otwarciu sesji, więc rozwinięcie odczytuje to, co już jest w pamięci podręcznej.
Demon odpowiada na to samo pytanie dla edytora, na podstawie kodu, a nie diagnostyki. Wszystkie trzy to jedno rozwinięcie w trzech postaciach, a nie trzy odpowiedzi, które przypadkiem są zgodne.