86Box 虛擬機器操作

每當任務需要啟動、設定、等待、重啟、除錯或檢查 86Box 虛擬機器時，請使用此技能。

不可協商的安全規則

在啟動前，先解析出確切的 VM 目錄。
使用 --vmpath <VM 目錄> --vmname <顯示名稱> 啟動。
追蹤該啟動回傳的 PID 以及穩定的 Harness 行程名稱。
在發送任何訊號前，使用可執行檔路徑和確切的 --vmpath 來驗證 PID 身分。
絕不要使用 killall、廣泛的 pkill、廣泛的 pgrep 或未經驗證的 PID。
假設其他人正在執行獨立的 86Box 行程。
當 NVRAM 或設定變更很重要時，優先使用乾淨的 UI 關機。
絕不要為了單一 VM 實驗而覆寫共用的 ROM；應複製一組完整的 ROM 集，並使用 --rompath 選取它。

前置檢查

在平台 VM 根目錄下解析一個名稱。在 macOS 上：
```
~/Library/Application Support/86Box/Virtual Machines/<名稱>
```
直接指定 VM 路徑也是有效的。
讀取 <VM>/86box.cfg。記錄：
- machine；
- cpu_use_dynarec；
- 可選的 gdbstub_port；
- 已設定的媒體和介面卡設備。
選擇二進位檔：
- 一般操作：/Applications/86Box.app/Contents/MacOS/86Box；
- 客戶機除錯：使用本機的 -DGDBSTUB=ON 建置版本。
稽核指令（從 86Box-tool 專案根目錄執行，或先安裝它）：
```
cd ~/src/86Box-tool && uv run ./86boxctl.sh <VM> command
```
如果要除錯多個 VM，每個設定都需要有獨立的 gdbstub_port，且 cpu_use_dynarec = 0。

啟動

獨立控制器：

./86boxctl.sh <VM> start
./86boxctl.sh <VM> start --gdb-stub

已修補的 IBM PS/2 Model 80 Type 2 BIOS：

./86boxctl.sh <VM> command \
  --model-80-type-2-rom /path/to/sequential-128k.bin
./86boxctl.sh <VM> start \
  --model-80-type-2-rom /path/to/sequential-128k.bin

VM 必須使用 machine = ibmps2_m80。控制器會探索平台標準的 ROM 根目錄，在 <VM>/romsets/ 下複製完整的樹結構，將映像檔分割成作用中的偶數/奇數通道檔案，驗證它們，然後透過 --rompath 使用產生的根目錄啟動。當探索不明確時，請使用 --rom-source。若要建置但不啟動，請使用 prepare-roms。

對於長時間經由 Harness 中介的 GUI 會話，請透過 Harness 行程管理員啟動可執行檔，設定如下：

name        = 唯一的名稱，例如 86box-automatic-configuration
application = 選定的 86Box 二進位檔
args        = [--vmpath, <絕對 VM 目錄>, --vmname, <顯示名稱>]
pty         = false
persist     = true （當操作橫跨多輪時）

記錄回傳的 PID。後續的 describe、logs、restart 和 stop 操作只能使用該穩定的行程名稱。重啟會產生一個新的 PID；請記錄它。

不要將 86box.cfg 作為單一的定位參數傳遞。這樣做只會選取一個設定檔，但不會設定 86Box 的 VM 使用者檔案路徑，因此相對路徑的媒體、NVRAM 和本機 ROM 可能會解析到錯誤的目錄。

建立就緒狀態

僅建立行程不代表客戶機已就緒。

一般建置：需要確切的行程在啟動後存活下來，然後檢查可見的 VM 或具體的 VM 產物。
GDB 建置：需要此 VM 設定的 RSP 埠正在監聽。
絕不要將其他 86Box 行程或埠當作此 VM 的證據。

使用：

./86boxctl.sh <VM> status
./86boxctl.sh <VM> logs --lines 100

等待使用者

當使用者要求等到 Harness 中斷時，就確切地這樣做。除非使用者要求進行觸發於退出的工作，否則不要在 VM 退出時繼續前進。Harness 的工作等待器不會將受管理的 GUI 行程視為背景工作，因此請建立一個長時間有限期的非同步等待信標，使用無限期 Harness 超時等待該工作，並在使用者中斷後取消它。

透過穩定的行程名稱和 PID 分別追蹤 VM 行程。

觀察

主機生命週期

./86boxctl.sh <VM> status
./86boxctl.sh <VM> wait
./86boxctl.sh <VM> logs --lines 100

客戶機螢幕、主控台和記憶體

兩個獨立的路徑：

RSP Stub（需要 GDB-stub 建置；連接時會暫停客戶機）：
```
RSP_PORT=<埠> ./rsp.py probe
RSP_PORT=<埠> ./rsp.py video-mode
RSP_PORT=<埠> ./rsp.py screen
RSP_PORT=<埠> ./rsp.py wait-screen "預期文字" --wait-timeout 600
RSP_PORT=<埠> ./rsp.py dump b8000 fa0
```
在文字模式 0、1、2、3 和 7 中，screen 會選取 40x25 或 80x25，使用 B8000h（彩色）或 B0000h（單色），並跟隨作用中的視訊頁面。在圖形模式 11h 中，它會讀取位於 A0000h 的 packed 640x480 1bpp 幀緩衝區，恢復客戶機執行，並要求 Harness 設定的 @vision 模型解釋產生的 PNG。omp 必須在 PATH 上；使用 --vision-question 自訂提示。快照指令僅暫停進行檢查，並在模型推理前分離。
Memdump 伺服器（無需 GDB Stub，不暫停 CPU）：在 VM 設定中設定 memdump_port。使用即時差異檢視輪詢文字幀緩衝區：
```
./screenmon.py --memdump-port 12348            # 互動式 TTY：ANSI 差異
./screenmon.py --memdump-port 12348 --plain   # 管道輸出：完整幀 + 變更的行
./screenmon.py --memdump-port 12348 --count 30 --interval 0.1
```
screenmon.py 僅渲染兩次輪詢之間有變化的部分；除非使用 --full/--plain 覆寫，否則模式由 isatty() 決定。預設間隔為 0.1 秒。

對於持續的雙向操作：

# 互動式 ANSI 鏡像；Ctrl-] 會分離
RSP_PORT=<埠> ./guest_console.py

# 可處理的螢幕和差異事件
RSP_PORT=<埠> ./guest_console.py \
  --format jsonl --no-input --duration 10

# 透過 BIOS 鍵盤環輸入 DOS 指令
RSP_PORT=<埠> ./guest_console.py \
  --send "DIR" --enter --duration 10

# 早期 POST 需要硬體掃描碼注入
RSP_PORT=<埠> ./guest_console.py \
  --input-mode hardware --key F1 --duration 5

主控台以 70 Hz 取樣，保留完整的字元/屬性緩衝區，並僅輸出合併後的變更區塊。TTY 會收到 ANSI 游標更新；重新導向的輸出預設為 JSONL。啟動後，輸入預設使用經過驗證的 BIOS 鍵盤環。硬體模式會透過模擬的 8042 注入定時的 Set-1 掃描碼，用於 POST。保留 Ctrl-] 用於分離，以便客戶機的 Ctrl-C 仍然可用。

絕不要僅憑注入了一個按鍵就推斷成功。必須觀察結果的螢幕差異或明確的客戶機輸出。

持久性 VM 設定

在乾淨關機後，僅檢查解析出的 VM 目錄：

<VM>/86box.cfg
<VM>/nvr/<machine>.nvr
<VM>/nvr/<machine>_sec.nvr

對於此儲存庫：

uv run --project . refdisk-view-config --vm <名稱> --adf-source rf7080a/disk

在 86Box UI 中新增一張介面卡並不會自動填入客戶機的 MCA NVRAM。客戶機的 Reference Disk 必須設定 POS 狀態，且 86Box 必須乾淨地儲存它。

ROM 驗證

machine = ... 決定了所需的 ROM 檔案名稱。請檢查：

當 86boxctl status 有記錄時，確切的 --rompath；
產生集中的 .86boxctl-romset.json；
來自 86Box 機器定義的，確切的作用中檔案名稱；
這些作用中檔案的雜湊值或位元組比較。

對於此工作流程，明確的 --rompath 必須包含完整的 86Box ROM 集。雖然 86Box 可以回退到其他搜尋根目錄，但完整性能使執行自給自足，並防止無聲的混合。不要將其指向僅包含一個機器的目錄。

對於原始的連續 128 KiB Model 80 Type 2 映像檔，請使用 --model-80-type-2-rom。控制器會寫入：

machines/ibmps2_m80/15f6637.bin = input[0::2]  # 低/偶數通道
machines/ibmps2_m80/15f6639.bin = input[1::2]  # 高/奇數通道

兩個檔案都是 65,536 位元組；交錯它們必須能還原輸入。start 和 restart 會自動建立或驗證隔離的複本：

./86boxctl.sh <VM> prepare-roms \
  --model-80-type-2-rom /path/to/sequential-128k.bin
./86boxctl.sh <VM> status

預設值是標準的 86Box ROM 根目錄：macOS 的 Application Support，Unix 上的 XDG_DATA_HOME/XDG_DATA_DIRS，以及 Windows 上的 Local/Program/AppData。使用 --rom-source PATH 或 86BOX_ROM_ROOT 覆寫。--refresh-rom-set 僅重建一個被識別出的、已產生的目錄。

備份副檔名（例如 .orig 和 .altered）不會被自動選取。請保留共用的原始檔案。

對於使用真實的、啟用 GDB-stub 的 86Box 行程進行的端到端驗證：

./model80_rom_smoke.py <MODEL80_VM>

需要 machine = ibmps2_m80、cpu_use_dynarec = 0 和一個唯一的 gdbstub_port。Harness 會從標準通道衍生出一個連續影像，將 KB OK 更改為 OKBMR，修復 64 KiB 的校驗和，透過隔離的完整 ROM 複本啟動，觀察客戶機文字 VRAM 中的 OKBMR，並僅停止其記錄的 PID。僅在需要手動檢查時使用 --keep-running。

停止或復原

優先使用乾淨的 UI 關機，然後確認追蹤的行程已退出。如果需要控制：

./86boxctl.sh <VM> stop
./86boxctl.sh <VM> restart

stop 僅向經驗證身分的 PID 發送 SIGTERM，不會靜默地強制終止它。僅在可接受可能的 NVRAM 或設定遺失時才使用 --kill-after-timeout。

發生崩潰時：

擷取 status 和 logs；
確認記錄屬於預期的 VM；
僅重啟該記錄；
記錄新的 PID；
返回先前的等待或觀察步驟。

完成證據

在回報成功之前，提供適合該任務的證據：

確切的 VM 路徑和機器識別碼；
二進位檔和確切的啟動指令；
穩定的行程名稱和目前的 PID；
就緒狀態證據；
乾淨退出或崩潰狀態；
相關的設定/NVRAM 路徑和大小；
客戶機螢幕、暫存器、記憶體或解碼後的設定輸出。

實作細節、GDB-stub 特性、ROM 查詢和故障診斷請參閱 README.md。

JoshRodd/86Box-tool

86Box-tool 是什麼？

在你喜歡的 AI 中提問

說明文件

86Box 虛擬機器操作

不可協商的安全規則

前置檢查

啟動

建立就緒狀態

等待使用者

觀察

主機生命週期

客戶機螢幕、主控台和記憶體

持久性 VM 設定

ROM 驗證

停止或復原

完成證據

相關技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me