Ein komplexes CLI-Werkzeug aus Skripten starten und den Erfolg im JSON-Bericht prüfen

## Den Erfolg der CLI an strukturierten Daten messen, nicht am Fortschrittstext Wenn ein Skript, eine Verarbeitungskette oder ein Programmierassistent ein komplexes Kommandozeilenwerkzeug steuert, ist die CLI als versionierte Maschinenschnittstelle und nicht als interaktive Befehlseingabe zu behandeln. Planung, Ausführung und Prüfung sind zu trennen, damit jede Stufe strukturierte Daten verarbeitet und Nachweise erzeugt, welche die nächste Stufe prüfen kann. - Menschenlesbare Fortschrittstexte dürfen nicht ausgewertet werden, um über den Erfolg eines Laufs zu entscheiden. - Unterstützte Aufgaben, Ausgabeklassen oder Lizenzanforderungen dürfen nicht aus dem Gedächtnis abgeleitet werden. - Werkzeugversion, aufgelöste Laufzeiteinstellungen, angeforderter Umfang und erzeugte Artefakte sind festzuhalten. - Fehlen erforderliche strukturierte Nachweise oder sind sie widersprüchlich, muss der Lauf sicherheitsgerichtet als fehlgeschlagen gelten. ## Vor der Planung die Aufgaben und Klassen des Werkzeugs abfragen Vor dem Aufbau eines aufwendigen Auftrags ist der leichtgewichtige Informations- oder Registerbefehl des Werkzeugs zu verwenden. Zu bevorzugen ist eine JSON-Ansicht aus demselben Register, das auch die Haupt-CLI prüft, da aus dem Quelltext übernommene Listen und fest eingetragene Namen von der installierten Version abweichen können. Die Funktionsermittlung soll Folgendes bereitstellen: - verfügbare Aufgaben und deren Eingabeart; - die Angabe, ob eine Aufgabe eine Lizenz oder Berechtigung erfordert; - die genaue, von Klassenfiltern akzeptierte Zuordnung zwischen Index und Klassenname; - die installierte Werkzeugversion und aufgabenspezifische Einschränkungen. Zu bevorzugen ist ein Ermittlungsweg, der keine umfangreichen Inferenzabhängigkeiten lädt, keinen Beschleuniger initialisiert, keine Modellgewichte herunterlädt und den lokalen Zustand nicht verändert. Wird nicht das gesamte Register benötigt, ist die Abfrage auf eine Aufgabe oder eine Klassenansicht zu begrenzen. ## Alle Eingaben, Ausgaben und Optionen angeben, damit der Lauf wiederholbar ist Jeder Lauf ist aus eindeutigen Werten aufzubauen: Eingabe, Ausgabe, Aufgabe, Gerätevorgabe, optionale Klassenmenge, Ausgabeform und Berichtspfad. Zulässig sind nur dokumentierte Eingabeformen, etwa eine Volumendatei, ein Verzeichnis geordneter Schichten oder ein Schichtenarchiv. Das gewählte Ausgabeziel ist gegen die ausgewählte Ausgabeart zu prüfen. Vor der Ausführung: 1. Prüfen, ob die angeforderte Aufgabe und die Klassen im aktuellen Funktionsregister vorhanden sind. 2. Prüfen, ob die Eingabeform unterstützt wird und der Ausgabepfad eindeutig ist. 3. Die Lizenzfrage klären, bevor eine zugangsbeschränkte Aufgabe gestartet wird. 4. Gerät und Leistungsmodus bewusst auswählen. 5. Einen eindeutigen Pfad für den maschinenlesbaren Laufbericht reservieren. Ein Ausgabeverzeichnis darf nicht wiederverwendet werden, wenn veraltete Artefakte mit aktuellen Ergebnissen verwechselt werden könnten. Die aufgelösten Befehlsparameter sind zusammen mit den Laufnachweisen aufzubewahren. ## Gerät und Schnellmodus wählen und vor lizenzpflichtigen Aufgaben die Lizenz prüfen Geräteauswahl und Geschwindigkeitsoptionen sind als Teil des Reproduzierbarkeitsvertrags zu behandeln. Festzuhalten ist das tatsächlich aufgelöste Gerät und nicht nur das angeforderte, da fehlende Beschleunigung zu einer CPU-Ausweichlösung mit erheblich anderer Laufzeit führen kann. Bei knappen Ressourcen sind die Kosten durch dokumentierte Einstellungen zu senken: - einen schnellen Modus mit geringerer Auflösung nur verwenden, wenn der Genauigkeitsverlust vertretbar ist; - nur die Klassen anfordern, die für die nachfolgende Verarbeitung benötigt werden; - bei mehreren Geräten einen bestimmten Beschleunigerindex verwenden; - bei Bedarf das unterstützte Plattformmodul ausdrücklich auswählen. Ein schnellerer oder enger begrenzter Modus darf niemals stillschweigend eingesetzt werden, wenn er Ausgabequalität oder Umfang verändert. Ist eine Aufgabe lizenzpflichtig, muss die Ausführung vor der Inferenz anhalten, sofern keine gültige Berechtigung eingerichtet ist. ## Den JSON-Bericht und jede darin genannte Datei prüfen Nach erfolgreichem Abschluss muss die CLI einen strukturierten Bericht schreiben. Dieser Bericht ist das maßgebliche Übergabeartefakt für die Automatisierung und soll Folgendes enthalten: - Versionen von Werkzeug, Laufzeitumgebung, Softwaregerüst und Abhängigkeiten; - Aufgabe, Eingabemodalität und Lizenzanforderung; - aufgelöstes Gerät und Leistungsmerkmale; - normalisierte Eingabe- und Ausgabeorte; - angeforderte Klassenmenge und endgültige Zuordnung zwischen Index und Klassenname; - tatsächliche Laufzeit und die genaue Liste der erzeugten Ausgabedateien. Es ist zu prüfen, ob der Bericht vorhanden ist, als JSON gelesen werden kann, die erwartete Aufgabe bezeichnet und jedes für die nächste Stufe benötigte Artefakt aufführt. Anschließend ist die Existenz jeder aufgeführten Datei zu prüfen. Für Volumen, Intensität, Voxelanzahl, Streuung, Extremwerte, Schwerpunkte oder Begrenzungsrahmen je Klasse sind eigene Statistikausgaben zu verwenden; diese Werte dürfen nicht aus Dateinamen oder Fortschrittstexten abgeleitet werden. ## Fehler nach Exit-Code unterscheiden und in einem neuen Ordner wiederholen Vor dem Lesen optionaler Artefakte ist der Prozessbeendigungszustand auszuwerten. Erfolgreicher Abschluss, Laufzeitfehler und Argument- oder Bedienfehler sind zu unterscheiden, damit Wiederholungen keine ungültigen Befehle erneut ausführen. - Bei Erfolg sind der Bericht und die darin angegebenen Ausgabedateien zu prüfen. - Bei einem Laufzeitfehler ist die diagnostische Standardfehlerausgabe zu sichern und die Ursache etwa als fehlende Berechtigung, nicht verfügbare Ressource, beschädigte Eingabe oder unbehandelter Werkzeugfehler einzuordnen. - Bei einem Argumentfehler sind Aufgabe, Eingabe, Ausgabe oder Optionssatz vor dem nächsten Versuch zu berichtigen. - Der stille Modus dient dazu, gewöhnliche Meldungen zu verringern; der Fehlersuchmodus ist nur zu verwenden, wenn zusätzliche Diagnoseangaben nötig sind. Teilweise erzeugte Dateien, eine Fortschrittsmeldung oder ein leeres Ausgabeverzeichnis dürfen nicht als Erfolg gelten. Ein neuer Versuch muss ein neues oder bereinigtes Ziel verwenden, damit Artefakte des fehlgeschlagenen Versuchs die Prüfung nicht erfüllen können. ## Die öffentliche API nutzen und Folgeschritte über die Dateiliste des Berichts verbinden Wenn eine Ausführung innerhalb desselben Prozesses erforderlich ist, ist die unterstützte übergeordnete Programmierschnittstelle zu verwenden. Dabei gilt derselbe eindeutige Vertrag für Aufgabe, Eingabe, Ausgabe und Prüfung wie beim CLI-Ablauf. Für Planung und Prüfung ist ein leichtgewichtiges Registermodul vorzuziehen, das Aufgaben und Klassen auflisten kann, ohne die vollständige Inferenzlaufzeit zu laden. Die Ablaufsteuerung ist von den Einzelheiten der Umsetzung zu entkoppeln: Funktionen werden über das offizielle Register ermittelt, über die dokumentierte CLI oder API ausgeführt und die Weiterverarbeitung anhand der Ausgabeliste des strukturierten Berichts verkettet. So bleibt die Automatisierung über Versionsänderungen hinweg erhalten, ohne die Standardausgabe brüchig auszuwerten oder Funktionslisten zu vervielfachen.