KITAQ 開發系統
使用手冊 2026.09

KITAQ SERIES • 參考版

KUROSAKI

NES 與 FDS 執行分析

從第一行程式，到執行、觀察與複測。
原始碼快照：2026 年 9 月 14 日 · 繁體中文版：2026 年 9 月 14 日

已建置的 Windows CLI

儲存庫根目錄提供 kurosaki.exe。下載 ZIP 後，請將執行檔與授權聲明一同保存。Windows x64 CLI 執行時無須 Rust、Python 或 .NET；以下步驟用於從原始碼重新建置。獨立專案程式碼由 DAISUKE OBA 以 MIT 授權提供，相依條件見 BINARY_NOTICES.md 與 licenses/。

1. KUROSAKI 的用途

KUROSAKI 是能讀取 KITAQFC 資訊的 NES／FC／FDS 觀察型模擬器。CLI 可檢查 ROM、執行程式、錄音、診斷、保存快照、重播輸入、反組譯，以及反編譯候選函式。各 mapper 實作範圍不同，請先查看 ROM 與支援資訊。

2. 建置與啟動

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

以下簡寫 kurosaki 假設執行檔目錄已加入 PATH；否則請換成 & "執行檔完整路徑"。

powershell
kurosaki inspect-rom .\out\hello.nes --json .\out\rom.json
kurosaki run .\out\hello.nes --frames 120 --png .\out\hello.png --json .\out\run.json

使用第 4 卷的 hello ROM 驗證文字顯示。inspect-rom 檢查標頭，run 推進 CPU／PPU 執行。標頭檢查成功不代表程式能正常執行。

3. 檢查 mapper 與電路板

名稱表 RAM 映射

PPU 讀取、寫入與繪製會使用 AxROM 的下／上單畫面選擇、FME7 的垂直／水平／下／上選擇，以及全部 16 種僅使用 CIRAM 的 MMC5 配置。不支援 MMC5 ExRAM 與填色繪製。已測試行為請參閱 KITAQFC 各電路板的範例。

模式值與已執行範例

mapper-list 列出已註冊類型，mapper-info 說明特定類型，audit-board 檢查電路板限制。mapper 編號將 ROM 標頭與實體接線假設連結起來；只有名稱無法確定容量、CHR-RAM 或固定 bank 的行為。

powershell
kurosaki mapper-list
kurosaki mapper-info 4
kurosaki audit-board .\out\surom.nes --expected-board surom512 --json .\out\board.json

--allow-unimplemented 允許遇到未實作部分後繼續觀察。使用此選項的執行結果，不能證明相關功能已受支援。

4. 控制器輸入

run --pad1、--pad2 使用 NES 原始位元遮罩：A=1、B=2、SELECT=4、START=8、UP=16、DOWN=32、LEFT=64、RIGHT=128。同時按鍵時將對應值相加。

powershell
kurosaki run .\out\game.nes --frames 120 --pad1 1 --png .\out\held_a.png --json .\out\held_a.json

上例持續按 A 120 個影格。標題、開始、確認等有順序的動作應使用重播。CLI replay-record 範例記錄沒有互動輸入的基準執行，不等同錄下人在 GUI 中的操作。

5. 快照與重播

powershell
kurosaki snapshot-save .\out\game.nes --frames 120 --out .\out\title.kss.json
kurosaki snapshot-load .\out\title.kss.json
kurosaki replay-record .\out\game.nes --frames 120 --out .\out\baseline.replay.json
kurosaki replay-run .\out\game.nes .\out\baseline.replay.json --json .\out\replay.json

可恢復的狀態使用第 2 版快照。請保持狀態與 ROM SHA-256 相符。snapshot-resume 從儲存點繼續；snapshot-rebase 依提供的相容性契約，明確將狀態移轉到另一個相容 ROM。更動程式碼或 RAM 配置後，不應無條件沿用舊狀態；通常應從啟動重新執行相同操作。

快照 JSON 儲存和讀取音訊時序小數時保留完整的 f64 精度。請勿四捨五入或改寫這些數值。若儲存的時序值發生變化，即使 ROM 和輸入相同，也不能據此比較恢復後的狀態是否完全一致。

6. 追蹤、診斷與效能剖析

powershell
kurosaki trace .\out\game.nes --frames 2 --cpu --ppu --apu --mapper --nmi --dma --out .\out\trace.jsonl
kurosaki diagnose .\out\game.nes --frames 120 --out .\out\diagnostics.json --md .\out\diagnostics.md
kurosaki profile .\out\game.nes --frames 120 --out .\out\profile.json

追蹤記錄事件順序，診斷指出符合規則的觀察，效能剖析呈現執行集中位置。異常附近的幾個影格，通常比冗長的完整紀錄更容易分析。

以 --kitaqfc-debug 傳入相符的建置除錯 JSON。缺少原始碼行號資訊的觀察，不能解讀為完整的原始碼逐行追蹤。

7. 儲存聲音與畫面

powershell
kurosaki audio-export .\out\sound.nes --frames 180 --wav .\out\sound.wav --json .\out\audio.json
kurosaki run .\out\game.nes --frames 120 --png .\out\frame.png --snapshot .\out\frame.kss.json --json .\out\frame.json

暫存器變化、PCM 產生與聲音實際正確，是三項不同檢查。測試內建或擴充音源時，請記錄 mapper。單張 PNG 無法證明移動或輸入行為，應同時保留前後狀態與輸入。

8. 反組譯與反編譯

powershell
kurosaki disasm .\out\game.nes --bytes 256 --text .\out\reset.txt
kurosaki decompile .\out\game.nes --format markdown --out .\out\decompile.md

disasm 輸出指令序列；decompile 輸出函式邊界候選、CFG、參照與虛擬碼。有可切換 bank 時，CPU 位址不足以確定 ROM 實體位置。必要時透過 --snapshot 提供 mapper 狀態，並以執行追蹤或註解佐證。這不是完整還原原始碼。

Reset、Nmi 和 Irq 依據擷取的 mapper 狀態中讀取的各個向量識別。其他快照目前 PC 是帶有自動名稱 sub_B... 的 current_pc 候選，不代表發生了重設，也不表示函式邊界已經確認。

9. 連接 SARAKURA

powershell
kurosaki run .\out\game.nes --frames 300 --emit-diagnostics .\out\kurosaki_events.jsonl --json .\out\run.json
sarakura fc analyze --metadata .\out\build.json --events .\out\kurosaki_events.jsonl --out .\out\fc_report --fail-on error

KUROSAKI 的 --emit-diagnostics 與 KOKURA 一樣，接收 JSONL 檔案路徑。請區分 CPU 追蹤與診斷事件檔。

10. FDS 與存檔 RAM

fds-inspect 檢查磁碟結構，export-assets 匯出素材。FDS 的啟動、BIOS、磁碟存取條件與 NES 卡匣不同，應另外測試。電池存檔 .sav 和 .kss.json 快照用途不同，須採用實作支援的儲存配置。

powershell
kurosaki battery-export .\out\game.nes .\out\title.kss.json --out .\out\save.sav
kurosaki battery-run .\out\game.nes --sav .\out\save.sav --frames 120 --save-out .\out\next.sav --png .\out\battery.png

battery-export 從相符的 ROM 與快照擷取原始存檔 RAM；battery-run 載入該 RAM 並從開機開始，不恢復中斷時的 CPU／PPU 執行狀態。使用 --save-out 指定輸出。這些操作需要具有存檔 RAM 的受支援 ROM，不適用於所有教學 ROM。

命令語法參考

下方說明取自本原始碼版本，可查詢選用引數、預設值與允許值。請將範例輸入檔名換成自己的檔案。實際工具回應保留原文。

kurosaki
help
KITAQFC-aware clean-room NES observation emulator CLI

Usage: kurosaki.exe <COMMAND>

Commands:
  battery-export   Export raw battery RAM from a matching snapshot (not a snapshot file)
  battery-run      Cold boot with an explicit battery file; no implicit save-file writes
  inspect-rom      
  audit-board      
  run              
  trace            
  audio-export     
  profile          
  diagnose         
  replay-record    
  replay-run       
  snapshot-save    
  snapshot-load    
  snapshot-rebase  Rebind a reviewed v2 snapshot to an explicitly allowlisted compatible ROM
  snapshot-resume  
  diff             
  decompile        Recover bounded function CFGs and readable pseudocode from a mapper context
  disasm           
  mapper-test      
  fds-inspect      
  export-assets    
  report           
  mapper-list      
  mapper-info      
  help             Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
kurosaki battery-export — 從狀態檔匯出原始電池 RAM
powershell
kurosaki battery-export out/game.nes out/state.kss.json --out out/save.sav
help
Export raw battery RAM from a matching snapshot (not a snapshot file)

Usage: kurosaki.exe battery-export --out <OUT> <ROM> <SNAPSHOT>

Arguments:
  <ROM>       
  <SNAPSHOT>  

Options:
      --out <OUT>  
  -h, --help       Print help
kurosaki battery-run — 以儲存的 RAM 從開機啟動
powershell
kurosaki battery-run out/game.nes --sav out/save.sav --frames 120 --png out/loaded.png --save-out out/next.sav
help
Cold boot with an explicit battery file; no implicit save-file writes

Usage: kurosaki.exe battery-run [OPTIONS] --sav <SAV> <ROM>

Arguments:
  <ROM>  

Options:
      --sav <SAV>            
      --frames <FRAMES>      [default: 600]
      --replay <REPLAY>      
      --json <JSON>          
      --snapshot <SNAPSHOT>  
      --png <PNG>            
      --save-out <SAVE_OUT>  
  -h, --help                 Print help
kurosaki inspect-rom — 檢查 ROM 標頭
powershell
kurosaki inspect-rom out/game.nes --json out/rom.json
help
Usage: kurosaki.exe inspect-rom [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --json <JSON>  
      --md <MD>      
  -h, --help         Print help
kurosaki audit-board — 檢查電路板要求
powershell
kurosaki audit-board out/game.nes --expected-board surom512 --json out/board.json
help
Usage: kurosaki.exe audit-board [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --expected-board <EXPECTED_BOARD>  [default: surom512]
      --metadata <METADATA>              
      --json <JSON>                      
  -h, --help                             Print help
kurosaki run — 執行固定影格數
powershell
kurosaki run out/game.nes --frames 120 --png out/game.png --json out/run.json
help
Usage: kurosaki.exe run [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>                                  [default: 1]
      --max-instructions <MAX_INSTRUCTIONS>              
      --headless                                         
      --state-hash <STATE_HASH>                          
      --json <JSON>                                      
      --md <MD>                                          
      --png <PNG>                                        
      --snapshot <SNAPSHOT>                              
      --observe-json <OBSERVE_JSON>                      
      --trace-jsonl <TRACE_JSONL>                        
      --emit-diagnostics <EMIT_DIAGNOSTICS>              
      --repro-bundle <REPRO_BUNDLE>                      
      --break-on-diagnostic <BREAK_ON_DIAGNOSTIC>        
      --png-on-diagnostic <PNG_ON_DIAGNOSTIC>            
      --snapshot-on-diagnostic <SNAPSHOT_ON_DIAGNOSTIC>  
      --kitaqfc-debug <KITAQFC_DEBUG>                    
      --allow-unimplemented                              
      --pad1 <PAD1>                                      [default: 0]
      --pad2 <PAD2>                                      [default: 0]
  -h, --help                                             Print help
kurosaki trace — 記錄依時間排序的事件追蹤
powershell
kurosaki trace out/game.nes --frames 2 --cpu --ppu --out out/trace.jsonl
help
Usage: kurosaki.exe trace [OPTIONS] --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>                [default: 1]
      --out <OUT>                      
      --cpu                            
      --mem-read                       
      --mem-write                      
      --ppu                            
      --apu                            
      --mapper                         
      --nmi                            
      --dma                            
      --full                           
      --kitaqfc-debug <KITAQFC_DEBUG>  
      --allow-unimplemented            
      --pad1 <PAD1>                    [default: 0]
      --pad2 <PAD2>                    [default: 0]
  -h, --help                           Print help
kurosaki audio-export — 將 PCM 音訊寫入 WAV
powershell
kurosaki audio-export out/game.nes --frames 120 --wav out/audio.wav
help
Usage: kurosaki.exe audio-export [OPTIONS] --wav <WAV> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>      [default: 60]
      --wav <WAV>            
      --json <JSON>          
      --allow-unimplemented  
      --trace-audio          
      --pad1 <PAD1>          [default: 0]
      --pad2 <PAD2>          [default: 0]
  -h, --help                 Print help
kurosaki profile — 找出執行熱點
powershell
kurosaki profile out/game.nes --frames 120 --out out/profile.json
help
Usage: kurosaki.exe profile [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>                [default: 60]
      --out <OUT>                      
      --md <MD>                        
      --kitaqfc-debug <KITAQFC_DEBUG>  
      --allow-unimplemented            
  -h, --help                           Print help
kurosaki diagnose — 產生靜態與執行時診斷
powershell
kurosaki diagnose out/game.nes --frames 120 --out out/diagnostics.json
help
Usage: kurosaki.exe diagnose [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>
          [default: 0]
      --out <OUT>
          
      --md <MD>
          
      --emit-diagnostics <EMIT_DIAGNOSTICS>
          
      --check <CHECK>
          [possible values: ppu, nmi, mapper, apu, abi, input, fds, asset]
      --kitaqfc-debug <KITAQFC_DEBUG>
          
      --allow-unimplemented
          
      --pad1 <PAD1>
          [default: 0]
      --pad2 <PAD2>
          [default: 0]
  -h, --help
          Print help
kurosaki replay-record — 記錄基準重播
powershell
kurosaki replay-record out/game.nes --frames 120 --out out/replay.json
help
Usage: kurosaki.exe replay-record [OPTIONS] --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>      [default: 60]
      --out <OUT>            
      --allow-unimplemented  
  -h, --help                 Print help
kurosaki replay-run — 執行記錄的輸入序列
powershell
kurosaki replay-run out/game.nes out/replay.json --json out/replay-result.json
help
Usage: kurosaki.exe replay-run [OPTIONS] <ROM> <REPLAY>

Arguments:
  <ROM>     
  <REPLAY>  

Options:
      --load-snapshot <LOAD_SNAPSHOT>
          Restore this version-2 snapshot before applying the replay timeline. With this option, --frames and trace bounds are absolute emulator frames
      --frames <FRAMES>
          
      --verify
          
      --json <JSON>
          
      --png <PNG>
          
      --snapshot <SNAPSHOT>
          
      --observe-json <OBSERVE_JSON>
          
      --wav <WAV>
          
      --trace-jsonl <TRACE_JSONL>
          
      --trace-start-frame <TRACE_START_FRAME>
          
      --trace-end-frame-exclusive <TRACE_END_FRAME_EXCLUSIVE>
          
      --cpu
          
      --mem-read
          
      --mem-write
          
      --ppu
          
      --apu
          
      --mapper
          
      --nmi
          
      --dma
          
      --full
          
      --allow-unimplemented
          
  -h, --help
          Print help
kurosaki snapshot-save — 儲存機器狀態
powershell
kurosaki snapshot-save out/game.nes --frames 120 --out out/state.kss.json
help
Usage: kurosaki.exe snapshot-save [OPTIONS] --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>      [default: 1]
      --out <OUT>            
      --allow-unimplemented  
      --pad1 <PAD1>          [default: 0]
      --pad2 <PAD2>          [default: 0]
  -h, --help                 Print help
kurosaki snapshot-load — 檢查狀態檔
powershell
kurosaki snapshot-load out/state.kss.json --json out/state-summary.json
help
Usage: kurosaki.exe snapshot-load [OPTIONS] <SNAPSHOT>

Arguments:
  <SNAPSHOT>  

Options:
      --json <JSON>  
  -h, --help         Print help
kurosaki snapshot-rebase — 依相容性契約將狀態移轉至另一 ROM
powershell
kurosaki snapshot-rebase out/before.nes out/after.nes out/state.kss.json --contract out/compatibility.json --out out/rebased.kss.json
help
Rebind a reviewed v2 snapshot to an explicitly allowlisted compatible ROM

Usage: kurosaki.exe snapshot-rebase [OPTIONS] --contract <CONTRACT> --out <OUT> <SOURCE_ROM> <TARGET_ROM> <SNAPSHOT>

Arguments:
  <SOURCE_ROM>  
  <TARGET_ROM>  
  <SNAPSHOT>    

Options:
      --contract <CONTRACT>               
      --prg-ram-patch <ADDRESS=FILE>      
      --cpu-ram-patch <ADDRESS=HEXBYTES>  
      --out <OUT>                         
      --json <JSON>                       
  -h, --help                              Print help
kurosaki snapshot-resume — 從儲存狀態繼續
powershell
kurosaki snapshot-resume out/game.nes out/state.kss.json --frames 60 --json out/resumed.json
help
Usage: kurosaki.exe snapshot-resume [OPTIONS] <ROM> <SNAPSHOT>

Arguments:
  <ROM>       
  <SNAPSHOT>  

Options:
      --reset-at-start               Reset the CPU after restoring the snapshot while retaining mapper RAM
      --frames <FRAMES>              [default: 1]
      --out <OUT>                    
      --json <JSON>                  
      --png <PNG>                    
      --observe-json <OBSERVE_JSON>  
      --trace-jsonl <TRACE_JSONL>    
      --cpu                          
      --mem-read                     
      --mem-write                    
      --ppu                          
      --apu                          
      --mapper                       
      --nmi                          
      --dma                          
      --full                         
      --allow-unimplemented          
      --pad1 <PAD1>                  [default: 0]
      --pad2 <PAD2>                  [default: 0]
  -h, --help                         Print help
kurosaki diff — 比較儲存的結果
powershell
kurosaki diff --before out/before.kss.json --after out/after.kss.json --json out/diff.json
help
Usage: kurosaki.exe diff [OPTIONS] --before <BEFORE> --after <AFTER>

Options:
      --before <BEFORE>  
      --after <AFTER>    
      --json <JSON>      
      --md <MD>          
  -h, --help             Print help
kurosaki decompile — 推估函式、控制流程圖與虛擬碼
powershell
kurosaki decompile out/game.nes --format markdown --out out/decompile.md
help
Recover bounded function CFGs and readable pseudocode from a mapper context

Usage: kurosaki.exe decompile [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --out <OUT>
          Write the rendered report here; stdout is used when omitted
      --format <FORMAT>
          [default: json] [possible values: json, markdown, text]
      --function <FUNCTIONS>
          Function name or Bnnn:$AAAA physical PRG-bank selector. Repeatable
      --all
          Also start a bounded candidate analysis at $8000 in every physical 8 KiB PRG bank
      --annotations <ANNOTATIONS>
          JSON annotation sidecar. ROM.decompile.json is loaded automatically when present
      --snapshot <SNAPSHOT>
          Restore a version-2 snapshot before capturing the PRG-bank windows
      --trace-jsonl <TRACE_JSONL>
          KUROSAKI trace JSONL to overlay exact physical-bank/PC hit counts
      --max-instructions <MAX_INSTRUCTIONS>
          Per-function static-analysis cap, preventing data from causing unbounded output [default: 2048]
  -h, --help
          Print help
kurosaki disasm — 顯示 CPU 指令
powershell
kurosaki disasm out/game.nes --bytes 256 --text out/disasm.txt
help
Usage: kurosaki.exe disasm [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --bytes <BYTES>              [default: 256]
      --start <START>              CPU address in decimal or with a 0x/$ hexadecimal prefix
      --snapshot <SNAPSHOT>        Restore a version 2 snapshot before reading mapped CPU bytes
      --prg-bank-8k <PRG_BANK_8K>  Read one exact physical 8 KiB PRG-ROM bank, independent of mapper state
      --json <JSON>                
      --text <TEXT>                
  -h, --help                       Print help
kurosaki mapper-test — 觀察 mapper 行為
powershell
kurosaki mapper-test out/game.nes --json out/mapper-test.json
help
Usage: kurosaki.exe mapper-test [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --json <JSON>  
  -h, --help         Print help
kurosaki fds-inspect — 檢查磁碟結構
powershell
kurosaki fds-inspect out/game.fds
help
Usage: kurosaki.exe fds-inspect [OPTIONS] <DISK>

Arguments:
  <DISK>  

Options:
      --json <JSON>  
  -h, --help         Print help
kurosaki export-assets — 從 ROM 匯出素材
powershell
kurosaki export-assets out/game.nes --out out/assets
help
Usage: kurosaki.exe export-assets --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --out <OUT>  
  -h, --help       Print help
kurosaki report — 依儲存的觀察產生報告
powershell
kurosaki report out/run.json --md out/report.md
help
Usage: kurosaki.exe report --md <MD> <INPUT>

Arguments:
  <INPUT>  

Options:
      --md <MD>  
  -h, --help     Print help
kurosaki mapper-list — 列出已註冊 mapper
powershell
kurosaki mapper-list
help
Usage: kurosaki.exe mapper-list [OPTIONS]

Options:
      --all          
      --json <JSON>  
      --md <MD>      
  -h, --help         Print help
kurosaki mapper-info — 查看 mapper 說明
powershell
kurosaki mapper-info 4
help
Usage: kurosaki.exe mapper-info [OPTIONS] <MAPPER>

Arguments:
  <MAPPER>  

Options:
      --json <JSON>  
  -h, --help         Print help