KITAQ 开发系统
用户手册 2026.09

KITAQ SERIES • 参考版

SARAKURA

诊断、比较与复测

从第一行代码，到运行、观察和复测。
源码快照：2026 年 9 月 14 日 · 简体中文版：2026 年 9 月 14 日

已构建的 Windows CLI

仓库根目录提供 Windows x64 版 sarakura.exe。下载 ZIP 时请连同许可声明一起保留。运行无需 Rust、Python 或 .NET，下面的构建步骤用于重新编译源码。独立项目代码由 DAISUKE OBA 以 MIT 许可提供，依赖条件保留在 BINARY_NOTICES.md 和 licenses/。

1. SARAKURA 负责什么

SARAKURA 汇总编译器构建信息和模拟器诊断事件，将其整理成有助于修复与复测的资料。它不是运行 ROM 的模拟器，也不会悄悄修改你的 C 源码。

2. 构建工具

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

简写命令 sarakura 假定已加入 PATH，否则请使用可执行文件路径。GB 选择 gb analyze，FC 选择 fc analyze。

3. 第一次分析

需要两类输入：--metadata 是构建时 JSON，--events 是运行时诊断 JSONL。JSONL 每行存放一个 JSON 对象。

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

在浏览器打开输出的 report.html。阅读单项诊断前，先确认目标、观察帧数、错误数和警告数。--frames 描述分析条件，并不是要求 SARAKURA 执行这么多帧的 ROM。

4. 先检查输入

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

研究游戏行为之前，应先区分文件无法读取、平台不匹配、事件类型不支持等问题。把普通模拟器报告当作事件文件传入，不会使它成为有效诊断输入。

5. 理解诊断

error 值得优先调查，warning 是否是问题取决于情境，info 提供背景。严重级别有助于分流，却无法完全理解游戏意图。例如仅凭重复 PC，未必能区分正常标题等待循环和死机。

请结合 ROM 哈希、输入序列、场景、画面、声音与源码位置判断。修复前后的条件应一致，否则诊断减少可能仅仅是因为运行了别的场景。

6. 输出文件

内置说明、诊断提示与修复指引使用英语，HTML 声明 lang="en"。用户字符串和事件 ID 不会自动翻译。默认隐藏处理会替换部分项目标签和路径，但不保证匿名化所有地址或观察内容。公开私人输入的分析结果前，应检查报告。

文件用途
ai_diagnostics.json供自动处理的规范化诊断
diagnostic_summary.json数量统计与摘要
report.html便于阅读的报告
repair_prompt.md开始调查修复所需的上下文
repair_plan.json / .md修复顺序和对象
automation_plan.json / .md按工具能力组织的工作计划
retest_plan.json复测计划
repro_bundle.zip复现资料包

生成计划不等于执行计划。修改 C 源码或 ROM 后，需要重新运行编译器、模拟器和 SARAKURA。

7. 规则目录、筛选与覆盖情况

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 列出诊断规则，pack-plan 按领域分组，coverage 检查对应事件是否被观察到。目录中存在规则，不保证当前模拟器会生成该事件。

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 选择事件名或规则 ID，--phase 选择阶段，--diagnostic-pack 选择领域。筛掉一条诊断并不等于解决问题。

8. 比较修改前后

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

结果分为新增、已解决、改善、持续存在和退化。应区分遗留问题与新引入的问题。比较时固定输入、帧数和诊断过滤条件。

9. 格式验证与 CI

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

持续集成用于自动执行可复现的检查。ci-summary 只有带 --enforce 才改变进程退出码，否则应读取 JSON 判定。analyze 的 --fail-on error 在有错误时返回非零退出码；默认 never 不会因为诊断而失败，因此 CI 必须明确选择策略。选择 warn 时，警告也会造成失败。

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

模式验证成功只验证了数据格式。游戏是否符合设计，还需要输入、画面和声音测试。

10. 处理复现资料

normalize-events 规范化事件记录，inspect-repro 检查复现包。分享前请确认资料对应目标 ROM，并包含所需输入步骤。--allow-project-labels 会明确保留项目派生标签与标识符。

11. 最小练习输入

手册附有小型 GB/FC 构建元数据与事件示例。可打开 GB 合成报告或 FC 合成报告。samples/sarakura_demo.ps1 演示分析流程。这些资料是为学习格式而人工构造的，不是从真实 ROM 捕获的证据；实测应使用 KOKURA 或 KUROSAKI 记录的事件。

12. 一次修复与复测循环

  1. 用同一 ROM 和输入复现问题，保留日志和画面。
  2. 用 SARAKURA 整理候选原因，查看相关源码。
  3. 针对原因做集中修改。
  4. 重新构建并执行同样的操作。
  5. 将 baseline-delta 与图像、声音、游戏行为一起比较。

保持每轮规模较小，才能清楚理解每项修改与结果的关系。

命令语法参考

下方帮助取自本源码版本，可查询可选参数、默认值和允许值。请将示例输入文件名换成自己的文件。实际工具响应保留原文。

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 诊断
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 — 收集 FC 诊断
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 — 验证诊断格式
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 — 比较两组诊断结果
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 — 列出诊断规则
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 — 汇总事件
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 — 检查构建信息
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 — 生成复测计划
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 — 检查事件生成端契约
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 — 规范化事件格式
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 失败条件
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 — 列出已观察规则
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 — 按领域查看规则计划
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 — 生成修复计划
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 — 将计划与工具能力对应
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 — 测量相对基准的改善与退化
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 模式
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 — 检查复现资料包
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