Communitygithub.com

JoshRodd/86Box-tool

86Box 가상 머신 시작, 설정, 디버깅, 모니터링을 위한 도구 모음

86Box-tool란 무엇인가요?

이 스킬은 에이전트가 86Box 가상 머신의 전체 수명주기를 제어할 수 있도록 합니다. VM 디렉토리 검증, 이진 파일 선택, 중단 없는 세션을 위한 안정적인 프로세스 이름 추적 등 안전한 실행을 위한 엄격한 규칙을 시행합니다. 여러 VM이 동시에 실행될 수 있으므로 PID 검증을 엄격히 수행하여 충돌을 방지합니다. 주요 기능으로는 `86boxctl.sh`를 통한 수명주기 관리, GDB 스텁을 통한 게스트 디스플레이/메모리 검사 (`rsp.py`), 폴링 기반 변경 감지 (`screenmon.py`), 라이브 양방향 게스트 콘솔 (`guest_console.py`) 등이 있습니다. 특수한 IBM PS/2 Model 80 Type 2 BIOS 작업을 지원하며 커스텀 ROM 이미지를 연결합니다. 내결함성과 가시성을 핵심으로 설계된 이 스킬은 성공을 판단하기 위해 검증 가능한 증거(예: 게스트 화면 캡처, 구성 덤프, PID 일치)를 요구합니다. macOS, Linux, Windows에서 86Box-tool 저장소의 도구를 활용합니다.

지원 대상~Claude Code~Codex CLI✓Cursor
npx skills add JoshRodd/86Box-tool
원본 보기→모든 스킬 둘러보기

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

문서

86Box VM 작업

이 스킬은 86Box 가상 머신을 시작, 구성, 대기, 재시작, 디버깅 또는 검사해야 하는 모든 작업에 사용합니다.

절대적 안전 규칙

  1. 실행 전에 정확한 VM 디렉토리를 확인합니다.
  2. --vmpath <VM 디렉토리> --vmname <표시 이름>으로 실행합니다.
  3. 해당 실행의 PID와 안정적인 제어 프로세스 이름을 추적합니다.
  4. 시그널을 보내기 전에 실행 파일과 정확한 --vmpath로 PID를 확인합니다.
  5. killall, 광범위한 pkill, 광범위한 pgrep 또는 확인되지 않은 PID를 사용하지 마십시오.
  6. 다른 사람이 독립적인 86Box 프로세스를 실행 중이라고 가정합니다.
  7. NVRAM 또는 구성 변경이 중요한 경우 깨끗한 UI 종료를 선호합니다.
  8. 단일 VM 실험을 위해 공유 ROM을 덮어쓰지 마십시오. 완전한 ROM 세트를 복제하고 --rompath로 선택하십시오.

사전 점검

  1. 플랫폼 VM 루트 아래에서 이름을 확인합니다. macOS의 경우:

    ~/Library/Application Support/86Box/Virtual Machines/<이름>

    직접 VM 경로도 유효합니다.

  2. <VM>/86box.cfg를 읽습니다. 다음을 기록합니다:

    • machine;
    • cpu_use_dynarec;
    • 선택적 gdbstub_port;
    • 설정된 미디어 및 어댑터 장치.

  3. 이진 파일을 선택합니다:

    • 일반 상호작용: /Applications/86Box.app/Contents/MacOS/86Box;
    • 게스트 디버깅: 로컬 -DGDBSTUB=ON 빌드.

  4. 명령을 감사합니다 (86Box-tool 프로젝트 루트에서 실행하거나 설치):

    cd ~/src/86Box-tool && uv run ./86boxctl.sh <VM> command

  5. 여러 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/ 아래에 전체 트리를 복제한 다음 이미지를 활성 even/odd 래인 파일로 분할하고 검증한 후 --rompath를 통해 생성된 루트로 실행합니다. 검색이 모호할 때는 --rom-source를 사용하십시오. 실행 없이 빌드하려면 prepare-roms를 사용하십시오.

긴 제어 매개 GUI 세션의 경우 제어 프로세스 관리자를 통해 실행 파일을 시작하십시오:

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

사용자 대기

사용자가 제어 중단까지 기다리라고 하면 정확히 그렇게 합니다. 사용자가 종료 트리거 작업을 요청하지 않는 한 VM이 종료되어도 진행하지 않습니다. 제어 작업 대기자는 관리되는 GUI 프로세스를 백그라운드 작업으로 처리하지 않으므로 긴 유한 비동기 대기 센티널을 만들고, 무기한 제어 시간 제한으로 해당 작업을 기다린 후 사용자의 중단 후 취소합니다.

VM 프로세스는 안정적인 프로세스 이름과 PID로 별도로 추적하십시오.

관찰

호스트 수명주기

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

게스트 화면, 콘솔 및 메모리

두 가지 독립적인 경로:

  1. RSP 스텁 (GDB-스텁 빌드 필요, 연결 시 게스트 일시 정지):

    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에서 640x480 1bpp 프레임버퍼를 읽고, 게스트를 재개한 후 생성된 PNG를 해석하기 위해 제어의 구성된 @vision 모델에 요청합니다. omp가 PATH에 있어야 하며, 프롬프트를 사용자 지정하려면 --vision-question을 사용하십시오. 스냅샷 명령은 검사 중에만 일시 정지하고 모델 추론 전에 분리합니다.

  2. Memdump 서버 (GDB 스텁 없음, 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

콘솔은 70Hz로 샘플링하고 완전한 문자/속성 버퍼를 유지하며 병합된 변경된 실행만 내보냅니다. TTY는 ANSI 커서 업데이트를 받고, 리디렉션된 출력은 기본적으로 JSONL입니다. 입력은 부팅 후 검증된 BIOS 키보드 링을 기본값으로 합니다. 하드웨어 모드는 POST를 위해 에뮬레이트된 8042를 통해 페이스 설정된 세트-1 스캔 바이트를 주입합니다. 게스트 Ctrl-C를 사용할 수 있도록 분리를 위해 Ctrl-]을 유지하십시오.

주입된 키만으로 성공을 추론하지 마십시오. 결과 화면 델타 또는 명시적인 게스트 출력을 관찰하십시오.

영구 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이 채워지지 않습니다. 게스트 참조 디스크는 POS 상태를 구성해야 하며 86Box는 이를 깨끗하게 저장해야 합니다.

ROM 검증

machine = ...은 필요한 ROM 파일 이름을 결정합니다. 다음을 확인합니다:

  1. 86boxctl status가 기록한 정확한 --rompath (있는 경우);
  2. 생성된 세트의 .86boxctl-romset.json;
  3. 86Box 머신 정의의 정확한 활성 파일 이름;
  4. 해당 활성 파일의 해시 또는 바이트 비교.

이 워크플로우에서 명시적인 --rompath는 완전한 86Box ROM 세트를 포함해야 합니다. 86Box는 다른 검색 루트로 폴백할 수 있지만, 완전성은 실행을 자체 포함시키고 조용한 혼합을 방지합니다. 하나의 머신만 포함된 디렉토리를 가리키지 마십시오.

원시 순차 128 KiB Model 80 Type 2 이미지의 경우 --model-80-type-2-rom을 사용하십시오. 컨트롤러는 다음을 작성합니다:

machines/ibmps2_m80/15f6637.bin = input[0::2]  # low/even 래인
machines/ibmps2_m80/15f6639.bin = input[1::2]  # high/odd 래인

두 파일 모두 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-스텁 활성화 86Box 프로세스를 사용한 종단 간 증명:

./model80_rom_smoke.py <MODEL80_VM>

machine = ibmps2_m80, cpu_use_dynarec = 0 및 고유한 gdbstub_port가 필요합니다. 제어는 기본 래인에서 순차 이미지를 파생시키고, KB OK를 OKBMR로 변경하고, 64 KiB 체크섬을 수리하고, 고립된 완전한 ROM 복제본을 통해 실행하고, 게스트 텍스트 VRAM에서 OKBMR을 관찰하고, 기록된 PID만 중지합니다. --keep-running은 수동 검사가 필요할 때만 사용하십시오.

중지 또는 복구

깨끗한 UI 종료를 선호한 다음 추적된 프로세스가 종료되었는지 확인합니다. 제어가 필요한 경우:

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

stop은 식별이 검증된 PID에만 SIGTERM을 보내고 조용히 강제 종료하지 않습니다. --kill-after-timeout은 NVRAM 또는 구성 손실 가능성을 수용한 후에만 사용하십시오.

충돌 시:

  1. status 및 logs를 캡처합니다;
  2. 레코드가 의도된 VM에 속하는지 확인합니다;
  3. 해당 레코드만 재시작합니다;
  4. 새 PID를 기록합니다;
  5. 이전 대기 또는 관찰 단계로 돌아갑니다.

완료 증거

성공을 보고하기 전에 작업에 적합한 증거를 제공합니다:

  • 정확한 VM 경로 및 머신 식별자;
  • 이진 파일 및 정확한 실행 명령;
  • 안정적인 프로세스 이름 및 현재 PID;
  • 준비 상태 증거;
  • 깨끗한 종료 또는 충돌 상태;
  • 관련 구성/NVRAM 경로 및 크기;
  • 게스트 화면, 레지스터, 메모리 또는 디코딩된 구성 출력.

자세한 내용은 README.md를 참조하십시오 (구현 세부 정보, GDB-스텁 특성, ROM 검색, 장애 진단).

관련 스킬

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community