aggrega explain
Die Abbruchbedingung erklären, die ein Code benennt
Übersicht
aggrega explain <code>Beschreibung
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.Funktionsweise
Ein Build, der abbricht, gibt einen Kopf in eckigen Klammern aus, der die Kategorie nennt, der der Fehler zuzuordnen ist, sowie den Kurzcode der Bedingung – den Buchstaben E und vier Ziffern:
[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...aggrega explain E0209 wandelt diesen Code in die Bedingung um, die er benennt, und in die Schritt-für-Schritt-Anleitung zur Korrektur:
aggrega explain E0209Die Antwort beginnt mit beiden Bezeichnern der Bedingung und dem festen Satz, mit dem ihre Diagnosen beginnen, und gibt dann den Eintrag wieder, der erklärt, was die Bedingung verursacht und was zu ändern ist – derselbe Eintrag, der in fatal-halts.md veröffentlicht ist.
Der zu übergebende Code
Jeder der beiden Codes der Bedingung wird akzeptiert, weil jeder Sie auf einer anderen Oberfläche erreicht.
Der Kurzcode ist derjenige, den Ihnen ein Terminal zeigt, und derjenige, zu dem Sie greifen, wenn Sie nur die ausgegebene Ausgabe haben. Eine Nummer wird einmal vergeben und bleibt dann fest, sodass ein Kurzcode, den Sie vor einem Jahr in einen Bericht eingefügt haben, noch immer die Bedingung benennt, die er damals benannte.
Der beschreibende Code ist der mit Bindestrichen, den eine strukturierte Diagnose als eigenes Feld trägt und anhand dessen ein Programm verzweigt. Er benennt die Bedingung in Worten und trägt kein Präfix, sodass er auch dann fest bleibt, wenn der Compiler um ihn herum umorganisiert wird. Wenn Sie diesen vorliegen haben, übergeben Sie stattdessen ihn – die obige Bedingung ist unter recipe-values-mapping-requires-source registriert:
aggrega explain recipe-values-mapping-requires-sourceDie beiden Codes einer Bedingung benennen dieselbe Bedingung, daher liefern beide Schreibweisen dieselbe Antwort. Beim Kurzcode wird Groß- und Kleinschreibung nicht beachtet, da es ein Wert ist, den Sie von einem Bildschirm ablesen und wieder eintippen.
sentinels.md erklärt die drei Bezeichner, die eine Bedingung trägt, und wann zu welchem zu greifen ist.
Woher die Antwort stammt
Jede Bedingung, die dieses Binary deklariert, wird aus dem Binary beantwortet. Ihre beiden Codes und der Satz, mit dem ihre Diagnosen beginnen, sind im Compiler deklariert, sodass dafür weder Netzwerk noch Cache noch Konfiguration nötig ist.
Ein Code, den dieses Binary nicht deklariert, wird in der veröffentlichten Referenz nachgeschlagen. Ein Plugin meldet einen Abbruch, indem es eine Bedingung wählt, die der Compiler deklariert, sodass nirgendwo sonst eine Bedingung deklariert wird. Die veröffentlichte Referenz, sentinels.md, listet jede Bedingung auf, die das Produkt deklariert, und sie kann für eine andere Version veröffentlicht worden sein als das Binary, das Sie ausführen — sodass ein Code, der aus einem mit einer neueren oder älteren Version erstellten Bericht zitiert wird, dort dennoch aufgelöst werden kann.
Auch die Schritt-für-Schritt-Anleitung ist veröffentlichte Dokumentation, gelesen aus fatal-halts.md. Beide Seiten stammen aus dem Dokumentationspaket, das einmal pro Rechner in dem Cache abgelegt wird, den alle Aggrega-Projekte teilen, eine Kopie für jede Registry und Version – siehe aggrega cache. Gelesen wird das Paket, das für die Version von aggrega veröffentlicht wurde, die Sie ausführen; wo für diese Version keines veröffentlicht ist, ist es das neueste, das für eine frühere Version veröffentlicht wurde – dieselbe Wahl, die aggrega scaffold --example trifft, sodass die beiden nie unterschiedliche Dokumentation lesen. Ein Code, den die Referenz einer früheren Version nicht enthält, kann eine seither deklarierte Bedingung benennen; daher wird er als unbestimmt abgelehnt statt als Code, der nichts benennt, und die Ablehnung nennt die Version, deren Referenz gelesen wurde. Ihr Workspace entscheidet, aus welcher Registry das Paket stammt, nämlich aus seiner Standard-Registry, und ob eine bereits auf dem Rechner vorhandene Kopie gelesen werden darf: Bevor eine Seite ausgeliefert wird, werden die neben der Kopie abgelegten Signaturen erneut mit der Signaturprüfung Ihres Workspace für diese Registry verifiziert, derselben Prüfung, der auch ein Abruf des Pakets unterliegt. Diese Prüfung läuft auch offline. Wo sie einen Schlüssel oder eine Trust Root festlegt, liest sie nur diese; wo sie keines von beiden festlegt, wie die eingebaute Prüfung des offiziellen Hubs, verifiziert sie gegen die öffentliche Sigstore-Trust-Root, die ein Offline-Workspace nicht abrufen kann – offline verifiziert sie daher gegen die Trust Root, die ein früherer Online-Abruf auf diesem Rechner unter .sigstore in Ihrem Home-Verzeichnis hinterlassen hat, und ruft nichts ab. Wenn der Rechner keine Kopie hat oder keine, die Ihre Prüfung zulässt, beschafft der Befehl einmalig eine unter dieser Prüfung und liest danach aus dem Cache. Dieselbe Kopie liefert die Dokumentation, die ein Assistent über aggrega mcp liest, und die Erklärungen, die ein Editor über aggrega serve anzeigt.
Drei Antworten sollten Sie erkennen können, weil jede etwas anderes von Ihnen verlangt.
Eine Bedingung noch ohne Eintrag. Die Codes und der Satz werden gemeldet, und ein Hinweis besagt, dass die Seite der Abbruchbedingungen keine Schritt-für-Schritt-Anleitung für diese Bedingung enthält. Jede Bedingung ist weiterhin in sentinels.md aufgeführt.
Keine Dokumentation verfügbar. Für eine Bedingung, die der Compiler deklariert, werden die Codes und der Satz weiterhin gemeldet, und ein Hinweis nennt das Paket und die Version, die nicht gelesen werden konnten. Für einen Code, den dieses Binary nicht deklariert, bleibt nichts, womit geantwortet werden könnte, daher wird der Code abgelehnt – und die Ablehnung besagt, dass die Referenz nicht gelesen werden konnte, weil ohne sie ein Code aus einer anderen Version nicht von einem Tippfehler zu unterscheiden ist, und lässt beide Abhilfen offen: den Code korrigieren oder die Dokumentation beschaffen. Die übliche Ursache ist ein offline festgelegter Workspace oder einer, der seine Registry nie erreicht hat. Wo der Rechner eine Kopie enthält, die die Signaturprüfung Ihres Workspace nicht zulässt – eine, die ein anderes Projekt unter einer lockereren Einstellung abgerufen hat, oder eine, die ein Offline-Workspace nicht prüfen kann, weil dieser Rechner die öffentliche Trust Root, gegen die seine Prüfung verifiziert, nie abgerufen hat –, besagt der Hinweis, dass die Kopie abgelehnt wurde, statt zu fehlen, und warum. Wo für Ihre Version kein Paket veröffentlicht ist und das neueste frühere in einem Format vorliegt, das diese Version von aggrega nicht mehr liest – etwa bei einer Vorabversion, die ausgeführt wird, bevor ihre eigene Dokumentation veröffentlicht ist –, nennt der Hinweis beides in einem Satz:
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.mdEine ausgemusterte Nummer. Eine Nummer, die eine Bedingung benannte und dies nicht mehr tut, wird als ausgemustert beantwortet, mit dem, was sie benannte, statt als Code, der nie existiert hat – und sie wird nie mit einer anderen Bedingung beantwortet, weil eine ausgemusterte Nummer nicht erneut vergeben wird.
Beispiele
Einen Code direkt aus einem fehlgeschlagenen Build erklären:
aggrega build --release release.yaml || aggrega explain E0209Einen Code erklären, auf den ein Programm abgeglichen hat:
aggrega explain plugin-value-not-representableDieselbe Antwort von einem Assistenten
Ein über aggrega mcp verbundener KI-Assistent erreicht dieselbe Erläuterung über das Tool explain-error. Übergeben Sie ihm den Diagnosetext statt eines bloßen Codes – ein Assistent hat vorliegen, was der Build ausgegeben hat –, und wo dieser Text mit einem Kurzcode beginnt, enthält die Antwort die Bedingung, den Satz, mit dem ihre Diagnosen beginnen, und die veröffentlichte Schritt-für-Schritt-Anleitung zur Korrektur, zusammengestellt wie die obige Antwort. Sie enthält auch den beschreibenden Code, sodass der Assistent anhand dessen statt anhand des Wortlauts einer Meldung verzweigen kann, sowie die Adresse, unter der die Bedingung veröffentlicht ist.
Alles, was die obigen Abschnitte über eine fehlende Schritt-für-Schritt-Anleitung sagen, gilt auch dort: Eine Bedingung, für die die Seite keinen Eintrag dokumentiert, und ein Workspace, der die Dokumentation nicht lesen kann, führen jeweils dazu, dass die Bedingung mit einem Hinweis beantwortet wird, der angibt, welcher Fall vorliegt. Auch dort wird eine ausgemusterte Nummer als ausgemustert beantwortet, mit dem, was sie benannte, sodass ein Assistent, dem eine alte Diagnose übergeben wird, erfährt, dass die Nummer nicht mehr verwendet wird, statt auf eine Seite über etwas anderes geschickt zu werden. Die Assistenten-Oberfläche beschafft die Dokumentation einmal beim Öffnen der Sitzung, sodass eine Erläuterung liest, was bereits im Cache liegt.
Der Daemon beantwortet dieselbe Frage für einen Editor, ausgehend von einem Code statt von einer Diagnose. Alle drei sind eine Erläuterung in drei Darstellungen und nicht drei Antworten, die zufällig übereinstimmen.