KITAQ SISTEMA DE DESARROLLO
MANUAL DE USO 2026.09

SERIE KITAQ • EDICIÓN DE REFERENCIA

SARAKURA

Diagnóstico, comparación y repetición de pruebas

Desde tu primera línea hasta la ejecución, la observación y la repetición de pruebas.
Código fuente recopilado: 14 de septiembre de 2026 · Edición inglesa: 14 de septiembre de 2026

Ejecutable de consola para Windows

El repositorio incluye sarakura.exe en su raíz. Descarga el ZIP del repositorio y conserva los avisos de licencia junto al ejecutable. Esta herramienta de consola para Windows x64 no necesita Rust, Python ni .NET para ejecutarse. Los pasos siguientes sirven para volver a compilarla desde el código fuente. El código propio del proyecto se distribuye bajo la licencia MIT de DAISUKE OBA; las condiciones de las dependencias se conservan en BINARY_NOTICES.md y licenses/.

1. Para qué sirve SARAKURA

SARAKURA combina información de compilación con eventos de diagnóstico del emulador y los presenta de forma que ayuden a investigar reparaciones y repetir pruebas. No ejecuta ROM como un emulador ni modifica silenciosamente tu código C.

2. Compilar la herramienta

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

Los comandos abreviados sarakura suponen que el ejecutable está en PATH. Si no es así, utiliza su ruta. Elige gb analyze para GB o fc analyze para FC.

3. Tu primer análisis

Se necesitan dos entradas: --metadata es un JSON generado durante la compilación y --events es un JSONL de eventos de diagnóstico registrados durante la ejecución. JSONL contiene un objeto JSON por línea.

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

Abre el archivo de salida report.html en un navegador. Antes de leer los diagnósticos individuales, comprueba la plataforma, los fotogramas observados y los recuentos de errores y advertencias. --frames describe las condiciones del análisis; no ordena a SARAKURA ejecutar la ROM durante ese número de fotogramas.

4. Revisar primero las entradas

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

Descarta primero archivos ilegibles, plataformas que no coinciden y tipos de evento no admitidos. Pasar un informe ordinario del emulador como archivo de eventos no lo convierte en una entrada de diagnóstico válida.

5. Interpretar los diagnósticos

Un error merece atención prioritaria; una advertencia puede señalar un problema según las circunstancias; y un elemento informativo aporta contexto. La gravedad ayuda a ordenar la investigación, pero no interpreta por completo la intención del juego. Observar que se repite el contador de programa no siempre permite distinguir un bucle de espera normal de la pantalla de título de un bloqueo.

Compara el hash de la ROM, la secuencia de entrada, la escena, la imagen, el sonido y la ubicación en el código fuente. Mantén las mismas condiciones antes y después de una corrección: una reducción de los diagnósticos podría deberse simplemente a que se ejecutó otra escena.

6. Archivos de salida

Las explicaciones incorporadas, las sugerencias de diagnóstico y las instrucciones de reparación se generan en inglés; el HTML declara lang="en". Las cadenas del usuario y los identificadores de eventos no se traducen automáticamente. La ocultación predeterminada sustituye determinadas etiquetas y rutas del proyecto, pero no anonimiza todas las direcciones ni todas las observaciones. Revisa los informes antes de publicar un análisis de datos privados.

ArchivoFinalidad
ai_diagnostics.jsonDiagnósticos normalizados para procesamiento automático
diagnostic_summary.jsonRecuentos y resumen
report.htmlInforme para su lectura en el navegador
repair_prompt.mdContexto inicial para investigar una reparación
repair_plan.json / .mdOrden y objetivos de las reparaciones
automation_plan.json / .mdPlan de trabajo según las capacidades de las herramientas
retest_plan.jsonPlan para repetir las comprobaciones
repro_bundle.zipPaquete de información para reproducir el problema

Generar un plan no equivale a ejecutarlo. Después de modificar el código C o una ROM, vuelve a ejecutar el compilador, el emulador y SARAKURA.

7. Catálogos, filtros y cobertura

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 enumera las reglas de diagnóstico; pack-plan las agrupa por área; y coverage examina cuáles de sus eventos correspondientes se observaron. Que una regla figure en el catálogo no garantiza que el emulador actual emita ese evento.

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 selecciona un nombre de evento o un identificador del catálogo; --phase, una fase; y --diagnostic-pack, un área. Ocultar un diagnóstico mediante un filtro no resuelve su causa.

8. Comparar el antes y el después

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

Los resultados se clasifican como nuevos, resueltos, mejorados, persistentes o empeorados. Distingue los problemas que siguen presentes de los que se han introducido con el cambio. Mantén fijos la entrada, el número de fotogramas y los filtros de diagnóstico durante la comparación.

9. Validación e integración continua

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

La integración continua automatiza comprobaciones reproducibles. ci-summary solo modifica el código de salida del proceso cuando se indica --enforce; en caso contrario, lee el veredicto de su JSON. En analyze, --fail-on error devuelve un código distinto de cero si se detectan errores. El valor predeterminado never no hace fallar el proceso por los diagnósticos, así que escoge expresamente la política que quieras aplicar en CI. Con warn, las advertencias también provocan un fallo.

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

Validar correctamente el esquema comprueba el formato de los datos. Para verificar que el juego funciona como se pretende también hacen falta pruebas de entrada, imagen y sonido.

10. Gestionar los archivos de reproducción

normalize-events normaliza los registros de eventos. inspect-repro examina un paquete de reproducción. Antes de compartirlo, comprueba que sus datos correspondan a la ROM prevista y que incluya los pasos de entrada necesarios. --allow-project-labels conserva expresamente las etiquetas y los identificadores derivados del proyecto.

11. Entradas mínimas para practicar

El manual incluye pequeños ejemplos de metadatos de compilación y eventos para GB y FC. Abre el informe sintético de GB o el informe sintético de FC. samples/sarakura_demo.ps1 muestra cómo analizarlos. Son entradas sintéticas para aprender el formato, no registros obtenidos de una ROM real. Para probar una ROM real, utiliza eventos registrados por KOKURA o KUROSAKI.

12. Un ciclo de corrección y prueba

  1. Reproduce el problema con la misma ROM y la misma entrada; conserva los registros y las imágenes.
  2. Organiza las posibles causas con SARAKURA y examina el código pertinente.
  3. Realiza un cambio concreto que aborde la causa.
  4. Vuelve a compilar y repite las mismas acciones.
  5. Compara baseline-delta con las imágenes, el audio y el comportamiento del juego.

Mantén este ciclo acotado para poder entender cada cambio y su efecto.

Referencia de sintaxis de comandos

La siguiente ayuda se capturó para esta edición del código fuente. Consúltala para conocer los argumentos opcionales, los valores predeterminados y los valores admitidos. Sustituye los nombres de archivo ilustrativos por tus propios archivos. Las respuestas capturadas de las herramientas conservan su redacción original.

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 — Recopilar diagnósticos de Game Boy
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 — Recopilar diagnósticos de Famicom
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 — Validar el formato de diagnóstico
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 — Comparar dos resultados de diagnóstico
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 — Enumerar reglas de diagnóstico
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 — Resumir eventos
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 — Examinar la información de compilación
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 — Crear un plan de nuevas pruebas
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 — Comprobar el contrato de emisión de eventos
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 — Normalizar el formato de los eventos
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 — Evaluar las condiciones de fallo de CI
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 — Enumerar reglas observadas
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 — Describir planes de reglas por área
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 — Crear un plan de reparación
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 — Relacionar planes con las capacidades de las herramientas
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 — Medir mejoras y regresiones respecto a una referencia
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 — Exportar esquemas JSON
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 — Examinar un paquete de reproducción
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