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