KITAQ ENTWICKLUNGSSYSTEM
BENUTZERHANDBUCH 2026.09

KITAQ SERIES • REFERENZAUSGABE

SARAKURA

Diagnose, Vergleich und erneute Tests

Von der ersten Codezeile zur Ausführung, Beobachtung und erneuten Prüfung.
Quellenstand: 14. September 2026 · Englische Referenzausgabe: 14. September 2026

Fertige Windows-Version

Im Hauptverzeichnis des Repositorys liegt sarakura.exe. Laden Sie das Repository als ZIP herunter und bewahren Sie die Lizenzhinweise zusammen mit der ausführbaren Datei auf. Für diese Windows-x64-Version müssen weder Rust noch Python oder .NET installiert sein. Die folgenden Build-Schritte dienen dem Neubau aus den Quellen. Der eigenständige Projektcode steht unter der MIT-Lizenz von DAISUKE OBA; die Bedingungen der Abhängigkeiten finden Sie in BINARY_NOTICES.md und licenses/.

1. Die Aufgabe von SARAKURA

SARAKURA führt Build-Informationen des Compilers und Diagnoseereignisse des Emulators zusammen. Die Ergebnisse sollen bei der Fehlersuche, bei Korrekturen und bei erneuten Tests helfen. SARAKURA führt selbst keine ROM aus und verändert Ihren C-Code nicht automatisch.

2. Das Werkzeug kompilieren

powershell
Push-Location .\sarakura
.\scripts\build.ps1
.\sarakura.exe --help
Pop-Location

Die kurzen Aufrufe mit sarakura setzen voraus, dass das Programm im PATH erreichbar ist. Geben Sie andernfalls den Pfad zur ausführbaren Datei an. Verwenden Sie gb analyze für GB und fc analyze für FC.

3. Die erste Analyse

Zwei Eingaben sind erforderlich: --metadata bezeichnet die JSON-Datei mit Build-Daten, --events die JSONL-Datei mit Laufzeitdiagnosen. JSONL enthält pro Zeile ein JSON-Objekt.

powershell
sarakura gb analyze --metadata .\out\build.json --events .\out\gb_events.jsonl --out .\out\report --fail-on error

Öffnen Sie die erzeugte report.html im Browser. Prüfen Sie Zielplattform, beobachtete Frames sowie Fehler- und Warnungszahlen, bevor Sie einzelne Diagnosen lesen. --frames beschreibt die Analysebedingungen. Es veranlasst SARAKURA nicht, eine ROM entsprechend lange auszuführen.

4. Zuerst die Eingaben prüfen

powershell
sarakura inspect-metadata --metadata .\out\build.json
sarakura inspect-events --events .\out\gb_events.jsonl
sarakura emitter-check gb --metadata .\out\build.json --events .\out\gb_events.jsonl --strict

Klären Sie zunächst, ob Dateien lesbar sind, die Plattformen zueinander passen und die Ereignistypen unterstützt werden. Erst danach lässt sich das Spielverhalten sinnvoll untersuchen. Ein gewöhnlicher Emulatorbericht wird nicht dadurch zu einer gültigen Ereignisdatei, dass Sie ihn als solche übergeben.

5. Diagnosen einordnen

Fehler verdienen Vorrang. Warnungen können je nach Situation auf ein Problem hinweisen, während Informationsmeldungen zusätzlichen Kontext liefern. Der Schweregrad hilft bei der Priorisierung, kennt aber nicht die vollständige Absicht des Spiels. Ein wiederholter Programmzähler kann sowohl zu einer normalen Warteschleife auf dem Titelbildschirm als auch zu einem hängenden Programm gehören.

Vergleichen Sie ROM-Hash, Eingabefolge, Szene, Bild, Ton und Quellposition. Halten Sie die Bedingungen vor und nach einer Korrektur gleich. Weniger Diagnosen könnten sonst lediglich bedeuten, dass eine andere Szene ausgeführt wurde.

6. Ausgabedateien

Die eingebauten Erklärungen, Diagnosehinweise und Anweisungen zur Fehlersuche sind auf Englisch. Die HTML-Berichte deklarieren lang="en". Texte aus Benutzereingaben und Ereignis-IDs werden nicht automatisch übersetzt. Standardmäßig werden bestimmte Projektbezeichnungen und Pfade ersetzt; diese Bereinigung anonymisiert jedoch nicht jede Adresse oder Beobachtung. Prüfen Sie Berichte, bevor Sie Analysen privater Eingaben veröffentlichen.

DateiZweck
ai_diagnostics.jsonNormalisierte Diagnosen zur automatisierten Verarbeitung
diagnostic_summary.jsonZählwerte und Zusammenfassung
report.htmlLesbarer Bericht
repair_prompt.mdAusgangsinformationen für die Fehlersuche
repair_plan.json / .mdReihenfolge und Ziele der Korrekturen
automation_plan.json / .mdArbeitsplan auf Grundlage der Werkzeugfunktionen
retest_plan.jsonPlan für erneute Prüfungen
repro_bundle.zipPaket mit Informationen zur Reproduktion

Einen Plan zu erzeugen heißt noch nicht, ihn auszuführen. Nach Änderungen an C-Quellen oder einer ROM müssen Compiler, Emulator und SARAKURA erneut laufen.

7. Kataloge, Filter und Abdeckung

powershell
sarakura catalog gb --json
sarakura catalog fc --json
sarakura pack-plan gb
sarakura coverage gb --events .\out\gb_events.jsonl --out .\out\coverage.json

catalog listet Diagnoseregeln auf. pack-plan ordnet sie Bereichen zu. coverage untersucht, welche zugehörigen Ereignisse beobachtet wurden. Ein Eintrag im Katalog garantiert nicht, dass der aktuelle Emulator das betreffende Ereignis ausgibt.

powershell
sarakura gb analyze --metadata .\out\build.json --events .\out\gb_events.jsonl --out .\out\ppu_report --diagnostic-pack ppu --min-severity warn --fail-on error

--diagnostic-rule wählt einen Ereignisnamen oder eine Katalog-ID aus, --phase eine Phase und --diagnostic-pack einen Bereich. Eine Diagnose auszublenden behebt ihre Ursache nicht.

8. Vorher und nachher vergleichen

powershell
sarakura baseline-delta --baseline .\out\before --current .\out\after --out .\out\delta --markdown .\out\delta --fail-on-new error --fail-on-regression error --enforce

Die Ergebnisse werden als neu, behoben, verbessert, weiterhin vorhanden oder verschlechtert eingeordnet. Unterscheiden Sie bestehende Probleme von neu hinzugekommenen. Lassen Sie bei Vergleichen Eingaben, Frame-Zahlen und Diagnosefilter unverändert.

9. Validierung und kontinuierliche Integration

powershell
sarakura validate .\out\report\ai_diagnostics.json --strict
sarakura ci-summary --diagnostics .\out\report --fail-on error --enforce
sarakura schema export --out .\out\schemas

Kontinuierliche Integration automatisiert wiederholbare Prüfungen. ci-summary beeinflusst den Exitcode des Prozesses nur mit --enforce; ohne diese Option müssen Sie das Urteil in der JSON-Ausgabe auswerten. Bei analyze sorgt --fail-on error für einen von null verschiedenen Exitcode, wenn Fehler auftreten. Die Voreinstellung never lässt den Prozess wegen Diagnosen nicht fehlschlagen. Wählen Sie deshalb für CI ausdrücklich eine passende Regel. Mit warn führen auch Warnungen zum Fehlschlag.

powershell
sarakura ci-summary --diagnostics .\out\report --fail-on error --enforce
if ($LASTEXITCODE -ne 0) { throw "The diagnostic failure condition was met" }

Eine erfolgreiche Schemavalidierung bestätigt das Datenformat. Ob das Spiel wie vorgesehen funktioniert, erfordert zusätzlich Tests von Eingaben, Bild und Ton.

10. Reproduktionsdateien handhaben

normalize-events vereinheitlicht Ereignisdatensätze, inspect-repro untersucht ein Reproduktionspaket. Prüfen Sie vor der Weitergabe, ob die Informationen zur vorgesehenen ROM gehören und die nötigen Eingabeschritte enthalten. Mit --allow-project-labels bleiben aus dem Projekt stammende Bezeichnungen und Kennungen ausdrücklich erhalten.

11. Kleine Übungseingaben

Das Handbuch enthält kleine Beispiele für Build-Metadaten und Ereignisse für GB und FC. Öffnen Sie den synthetischen GB-Bericht oder den synthetischen FC-Bericht. samples/sarakura_demo.ps1 zeigt die Analyse dieser Daten. Es handelt sich um künstliche Übungseingaben zum Erlernen des Formats, nicht um Aufzeichnungen einer tatsächlichen ROM. Für reale ROM-Tests verwenden Sie Ereignisse von KOKURA oder KUROSAKI.

12. Ein Korrektur- und Testdurchlauf

  1. Reproduzieren Sie das Problem mit derselben ROM und denselben Eingaben und bewahren Sie Protokolle und Bilder auf.
  2. Ordnen Sie mit SARAKURA mögliche Ursachen ein und untersuchen Sie den betreffenden Quelltext.
  3. Nehmen Sie eine gezielte Änderung an der Ursache vor.
  4. Kompilieren Sie erneut und wiederholen Sie dieselben Aktionen.
  5. Vergleichen Sie baseline-delta mit Bildern, Ton und Spielverhalten.

Halten Sie die Durchläufe überschaubar, damit Änderung und Wirkung nachvollziehbar bleiben.

Referenz der Befehlssyntax

Die folgende Hilfe wurde für diese Quellenausgabe aufgezeichnet. Sie erläutert optionale Argumente, Standardwerte und zulässige Werte. Ersetzen Sie die beispielhaften Eingabedateinamen durch Ihre eigenen Ausgaben. Aufgezeichnete Werkzeugantworten behalten ihren ursprünglichen Wortlaut.

sarakura
help
SARAKURA diagnostic translation CLI

Usage: sarakura.exe <COMMAND>

Commands:
  gb                
  fc                
  validate          
  compare           
  catalog           
  inspect-events    
  inspect-metadata  
  retest-plan       
  emitter-check     
  normalize-events  
  ci-summary        
  coverage          
  pack-plan         
  repair-plan       
  automation-plan   
  baseline-delta    
  schema            
  inspect-repro     
  help              Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
sarakura gb
help
Usage: sarakura.exe gb <COMMAND>

Commands:
  analyze  
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
sarakura gb analyze — Game-Boy-Diagnosen erfassen
powershell
sarakura gb analyze --metadata out/build.json --events out/events.jsonl --out out/report --fail-on error
help
Usage: sarakura.exe gb analyze [OPTIONS] --metadata <METADATA> --events <EVENTS> --out <OUT>

Options:
      --metadata <METADATA>
          
      --events <EVENTS>
          
      --out <OUT>
          
      --frames <FRAMES>
          [default: 300]
      --diagnostic-summary-limit <DIAGNOSTIC_SUMMARY_LIMIT>
          [default: 200]
      --diagnostic-rule <DIAGNOSTIC_RULES>
          Analyze only this event_type or catalog ID. Can be repeated
      --phase <PHASE>
          Analyze only this phase, for example MVP-1. Can be repeated
      --diagnostic-pack <DIAGNOSTIC_PACKS>
          Analyze only this diagnostic pack/domain, for example core, ppu, audio, mapper, fds. Can be repeated
      --min-severity <MIN_SEVERITY>
          Keep only diagnostics at or above this severity [possible values: error, warn, info]
      --fail-on <FAIL_ON>
          Return a non-zero exit code if diagnostics at or above this severity remain [default: never] [possible values: never, error, warn, info]
      --no-report
          Do not emit report.html
      --no-repro-bundle
          Do not emit repro_bundle.zip
      --allow-project-labels
          Preserve project build labels, paths, and source identifiers in output
  -h, --help
          Print help
sarakura fc
help
Usage: sarakura.exe fc <COMMAND>

Commands:
  analyze  
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
sarakura fc analyze — Famicom-Diagnosen erfassen
powershell
sarakura fc analyze --metadata out/build.json --events out/events.jsonl --out out/report --fail-on error
help
Usage: sarakura.exe fc analyze [OPTIONS] --metadata <METADATA> --events <EVENTS> --out <OUT>

Options:
      --metadata <METADATA>
          
      --events <EVENTS>
          
      --out <OUT>
          
      --frames <FRAMES>
          [default: 300]
      --diagnostic-summary-limit <DIAGNOSTIC_SUMMARY_LIMIT>
          [default: 200]
      --diagnostic-rule <DIAGNOSTIC_RULES>
          Analyze only this event_type or catalog ID. Can be repeated
      --phase <PHASE>
          Analyze only this phase, for example MVP-1. Can be repeated
      --diagnostic-pack <DIAGNOSTIC_PACKS>
          Analyze only this diagnostic pack/domain, for example core, ppu, audio, mapper, fds. Can be repeated
      --min-severity <MIN_SEVERITY>
          Keep only diagnostics at or above this severity [possible values: error, warn, info]
      --fail-on <FAIL_ON>
          Return a non-zero exit code if diagnostics at or above this severity remain [default: never] [possible values: never, error, warn, info]
      --no-report
          Do not emit report.html
      --no-repro-bundle
          Do not emit repro_bundle.zip
      --allow-project-labels
          Preserve project build labels, paths, and source identifiers in output
  -h, --help
          Print help
sarakura validate — Das Diagnoseformat prüfen
powershell
sarakura validate out/report/ai_diagnostics.json --strict
help
Usage: sarakura.exe validate [OPTIONS] <PATH>

Arguments:
  <PATH>  

Options:
      --strict  
  -h, --help    Print help
sarakura compare — Zwei Diagnoseergebnisse vergleichen
powershell
sarakura compare --before out/before --after out/after --out out/comparison
help
Usage: sarakura.exe compare --before <BEFORE> --after <AFTER> --out <OUT>

Options:
      --before <BEFORE>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --after <AFTER>    Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>        
  -h, --help             Print help
sarakura catalog — Diagnoseregeln auflisten
powershell
sarakura catalog gb --json
help
Usage: sarakura.exe catalog [OPTIONS] <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --json  Emit JSON instead of a Markdown table
  -h, --help  Print help
sarakura inspect-events — Ereignisse zusammenfassen
powershell
sarakura inspect-events --events out/events.jsonl
help
Usage: sarakura.exe inspect-events [OPTIONS] --events <EVENTS>

Options:
      --events <EVENTS>  
      --out <OUT>        Optional path to write the JSON inspection summary
      --json             Emit JSON to stdout instead of a compact text summary
  -h, --help             Print help
sarakura inspect-metadata — Build-Informationen untersuchen
powershell
sarakura inspect-metadata --metadata out/build.json
help
Usage: sarakura.exe inspect-metadata [OPTIONS] --metadata <METADATA>

Options:
      --metadata <METADATA>  
      --out <OUT>            Optional path to write the JSON inspection summary
      --json                 Emit JSON to stdout instead of a compact text summary
  -h, --help                 Print help
sarakura retest-plan — Einen Plan für erneute Tests erstellen
powershell
sarakura retest-plan --diagnostics out/report --out out/retest.json
help
Usage: sarakura.exe retest-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>                  Optional path to write retest_plan.json. If omitted, JSON is printed to stdout
  -h, --help                       Print help
sarakura emitter-check — Einhaltung der Vorgaben für die Ereignisausgabe prüfen
powershell
sarakura emitter-check gb --metadata out/build.json --events out/events.jsonl --strict
help
Usage: sarakura.exe emitter-check [OPTIONS] --events <EVENTS> <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --metadata <METADATA>      
      --events <EVENTS>          
      --strict                   Fail when compatibility warnings are found
      --check-snapshot-refs      Check that snapshot_ref paths exist
      --check-trace-window-refs  Check that trace_window_ref paths exist
      --base-dir <BASE_DIR>      Base directory for snapshot_ref and trace_window_ref existence checks
      --out <OUT>                Optional path to write the compatibility summary JSON
  -h, --help                     Print help
sarakura normalize-events — Das Ereignisformat vereinheitlichen
powershell
sarakura normalize-events --events out/events.jsonl --out out/normalized.jsonl
help
Usage: sarakura.exe normalize-events [OPTIONS] --events <EVENTS> --out <OUT>

Options:
      --events <EVENTS>  
      --out <OUT>        
      --json-array       Also write a pretty JSON array next to the JSONL output for fixture review
  -h, --help             Print help
sarakura ci-summary — CI-Fehlerbedingungen auswerten
powershell
sarakura ci-summary --diagnostics out/report --fail-on error --enforce
help
Usage: sarakura.exe ci-summary [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --fail-on <FAIL_ON>          CI policy. `error` fails only on errors, `warn` fails on errors or warnings [default: error] [possible values: never, error, warn, info]
      --out <OUT>                  Optional path to write sarakura_ci_summary.json
      --enforce                    Return a non-zero exit code when the CI policy fails
  -h, --help                       Print help
sarakura coverage — Beobachtete Regeln auflisten
powershell
sarakura coverage gb --events out/events.jsonl --out out/coverage.json
help
Usage: sarakura.exe coverage [OPTIONS] --events <EVENTS> <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --events <EVENTS>  
      --out <OUT>        Optional path to write catalog coverage JSON. If a directory is given, diagnostic_coverage.json is created inside it
      --json             Emit JSON to stdout instead of a compact text summary
  -h, --help             Print help
sarakura pack-plan — Regelpläne nach Bereichen beschreiben
powershell
sarakura pack-plan gb
help
Usage: sarakura.exe pack-plan [OPTIONS] <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --out <OUT>  Optional path to write pack plan JSON. If a directory is given, diagnostic_pack_plan.json is created inside it
      --json       Emit JSON to stdout instead of a Markdown summary
  -h, --help       Print help
sarakura repair-plan — Einen Reparaturplan erstellen
powershell
sarakura repair-plan --diagnostics out/report --out out/repair.json --markdown out/repair.md
help
Usage: sarakura.exe repair-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>                  Optional path to write repair_plan.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>        Optional path to write repair_plan.md. If a directory is given, repair_plan.md is created inside it
  -h, --help                       Print help
sarakura automation-plan — Pläne den Fähigkeiten der Werkzeuge zuordnen
powershell
sarakura automation-plan --diagnostics out/report --tool kokura --out out/automation.json
help
Usage: sarakura.exe automation-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>    Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --tool <TOOL>                  Tool name for generated commands. Use auto, kokura, or kurosaki [default: auto]
      --out <OUT>                    Optional path to write automation_plan.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>          Optional path to write automation_plan.md. If a directory is given, automation_plan.md is created inside it
      --capabilities <CAPABILITIES>  Optional SARAKURA tool capability JSON. Unsupported options are omitted from generated commands
  -h, --help                         Print help
sarakura baseline-delta — Verbesserungen und Regressionen gegenüber einem Referenzstand messen
powershell
sarakura baseline-delta --baseline out/before --current out/after --out out/delta --markdown out/delta
help
Usage: sarakura.exe baseline-delta [OPTIONS] --baseline <BASELINE> --current <CURRENT>

Options:
      --baseline <BASELINE>
          Baseline directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --current <CURRENT>
          Current directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>
          Optional path to write baseline_delta.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>
          Optional path to write baseline_delta.md. If a directory is given, baseline_delta.md is created inside it
      --fail-on-new <FAIL_ON_NEW>
          Fail when new diagnostics at or above this severity are introduced [default: error] [possible values: never, error, warn, info]
      --fail-on-regression <FAIL_ON_REGRESSION>
          Fail when existing diagnostics regress at or above this severity [default: error] [possible values: never, error, warn, info]
      --enforce
          Return a non-zero exit code when the baseline policy fails
  -h, --help
          Print help
sarakura schema
help
Usage: sarakura.exe schema <COMMAND>

Commands:
  export  
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
sarakura schema export — JSON-Schemata exportieren
powershell
sarakura schema export --out out/schemas
help
Usage: sarakura.exe schema export [OPTIONS] --out <OUT>

Options:
      --out <OUT>            
      --manifest <MANIFEST>  
  -h, --help                 Print help
sarakura inspect-repro — Ein Reproduktionspaket untersuchen
powershell
sarakura inspect-repro out/report/repro_bundle.zip --json
help
Usage: sarakura.exe inspect-repro [OPTIONS] <BUNDLE>

Arguments:
  <BUNDLE>  

Options:
      --out <OUT>  
      --json       
  -h, --help       Print help