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 的垂直／水平／下半／上半选择，以及 MMC5 的全部十六种仅使用 CIRAM 的布局。不支持 MMC5 ExRAM 和填充绘制。已测试的行为请参阅 KITAQFC 针对各电路板的示例。

模式值与运行示例

名称表 RAM 映射

PPU 读取、写入和渲染支持 AxROM 的低页/高页单屏选择、FME7 的垂直/水平/低页/高页选择，以及全部十六种纯 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. 接口范围

本手册涵盖 CLI 与集成 API。

11. 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