VM Lab
當任務需要一個乾淨的 macOS VM 來測試 GUI 自動化、TCC 提示、螢幕截圖、點擊、輸入、效能,或對 Peekaboo 等工具進行「雙向驗證」時,請使用此技能。
核心概念:在 guest 內部執行受測工具,但從 guest 外部透過 Parallels 螢幕截圖和 host 端觀察來進行驗證。請勿關閉不屬於您的應用程式。
安全規則
- 將 VM 快照視為可拋棄的,而非 host 主機。
- 絕不輸出機密。如果需要
op,請遵循 1Password 技能,並僅在tmux內執行。 - 偏好使用您自己建立的全新應用程式視窗:TextEdit、本機 HTML 測試頁面,或一個小型測試應用程式。
- 避免修改 host 狀態,除非是在
/tmp下的臨時截圖。 - 對於 VM 內的 git 倉庫,請使用 HTTPS 遠端和常規的分支規範。
VM 探索
列出 VM:
prlctl list --all
取得 VM 狀態/IP:
prlctl list --info "macOS Tahoe"
以 Peter 身份執行 guest 指令:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H /bin/zsh -lc '\''source ~/.zprofile 2>/dev/null || true; uname -a'\'''
從 host 端獨立截圖:
prlctl capture "macOS Tahoe" --file /tmp/vm-reference.png
sips -g pixelWidth -g pixelHeight /tmp/vm-reference.png
TCC / GUI 歸因
對於 macOS 螢幕錄製和輔助使用權限,負責的行程很重要。
prlctl exec是無頭的,可能無法產生有用的螢幕錄製歸因。- 當涉及螢幕錄製時,請從 guest 中一個可見的終端機應用程式啟動測試指令。
- 如果已安裝,Ghostty 可作為 GUI 終端機使用。
- 在首次擷取失敗後,請檢查
系統設定 > 隱私權與安全性 > 螢幕錄製與系統音訊錄製。 - 透過
prlctl exec執行的permissions status可能在允許 Ghostty 後仍回報螢幕錄製為 false;請透過從 Ghostty 重新執行擷取來驗證螢幕錄製。
開啟「螢幕錄製」設定面板:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"'
開啟 Ghostty:
prlctl exec "macOS Tahoe" 'sudo -u steipete -H open -a Ghostty'
透過 Ghostty 執行指令
最佳路徑:使用 prlctl exec 建立 guest 腳本,開啟/聚焦 Ghostty,然後僅在可見終端機中輸入一個簡短的啟動器路徑。
Guest 腳本模式:
prlctl exec "macOS Tahoe" 'sudo -u steipete -H /bin/zsh -lc '\''cat > /tmp/run-vm-lab.zsh <<EOF
#!/bin/zsh
source ~/.zprofile 2>/dev/null || true
cd ~/Projects/Peekaboo || exit 1
Apps/CLI/.build/debug/peekaboo image --path /tmp/peekaboo-vm.png --json
rc=$?
echo "EXIT:$rc"
[ -f /tmp/peekaboo-vm.png ] && sips -g pixelWidth -g pixelHeight /tmp/peekaboo-vm.png
echo "Press return to close..."
read _
exit $rc
EOF
chmod +x /tmp/run-vm-lab.zsh
ln -sf /tmp/run-vm-lab.zsh /tmp/r
open -a Ghostty'\'''
然後將啟動器連結到 Ghostty 的家目錄,並使用 scripts/parallels_type.py 輸入 ./r。這可以避免 Parallels 按鍵注入中不可靠的路徑字元。
prlctl exec "macOS Tahoe" \
"sudo -u steipete -H /bin/zsh -lc 'ln -sf /tmp/run-vm-lab.zsh ~/r'"
python3 skills/vm-lab/scripts/parallels_type.py "macOS Tahoe" $'\./r\n'
避免輸入過長的指令。Parallels 按鍵注入使用其自己的按鍵碼表,並且可能對鍵盤佈局敏感。
已知陷阱
- macOS 剪貼簿 API 可能從
prlctl exec中失敗;pbcopy、AppleScript 剪貼簿和 Peekaboo 貼上在無頭 guest 環境中都可能失敗。 open -na Ghostty.app --args -e ...在 macOS 上可能只會聚焦一個已存在的 Ghostty 視窗;不要假設它會執行指令。prlctl exec可能會透過 guest shell 重新組合 argv;對於複雜的負載,請傳遞一個完整的 shell 引用指令字串,或使用一個小型 Python 寫入器建立檔案。- Parallels
send-key-event --key使用 Parallels 按鍵值,而非 macOS 虛擬按鍵碼。 - 對於一般打字,請發送
prlctl send-key-event <vm> --key <key>且不加--event;明確的press/release可能會重複或卡住。返回鍵是個例外:需先 press 再 release。 - 優先使用一個
prlctl send-key-event --json批次指令,而非多個獨立的send-key-event行程;分開的呼叫可能會因焦點/延遲而產生時間偏移。 - 使用
PRL_KEY_ENTER = 36、PRL_KEY_SLASH = 61、PRL_KEY_R = 27、PRL_KEY_T = 28、PRL_KEY_M = 58、PRL_KEY_P = 33。 - 如果按鍵輸入產生亂碼,請發送 Return 清除該行,建立一個更短的啟動器,然後重試。
- 如果 Peekaboo 權限探測因缺少螢幕錄製而掛起,並發出
SWIFT TASK CONTINUATION MISUSE,請將其記錄為產品錯誤;不要將其與 VM 測試框架混淆。
雙向驗證
對於每個 GUI 動作,請透過兩個獨立的訊號進行驗證:
- 受測工具輸出:JSON、截圖檔案、AX 結果或應用程式狀態。
- 外部驗證器:
prlctl capture、host 端影像檢查、guest 內的檔案內容,或行程/視窗狀態。
範例:
- 截圖:比較 Peekaboo 影像的尺寸/內容與
prlctl capture。 - 點擊:使用 Peekaboo 點擊一個測試按鈕,然後驗證 guest 應用程式的狀態和 host 截圖。
- 輸入:使用 Peekaboo 在一個受控制的文字欄位中輸入,然後驗證 AX 值和 host 截圖。
- 效能:使用
/usr/bin/time -p包裝指令;重複冷/熱運行;將輸出保留在/tmp中。
Peekaboo VM 基準
在 guest 內部:
cd ~/Projects/Peekaboo
git pull --recurse-submodules
swift build --package-path Apps/CLI
Apps/CLI/.build/debug/peekaboo --version
Apps/CLI/.build/debug/peekaboo permissions status --json
Host 端參考截圖:
prlctl capture "macOS Tahoe" --file /tmp/vm-prlctl-reference.png
透過 Ghostty 在 guest 端執行 Peekaboo 擷取:
/tmp/r
比較:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H /bin/zsh -lc '\''sips -g pixelWidth -g pixelHeight /tmp/peekaboo-vm.png'\'''
sips -g pixelWidth -g pixelHeight /tmp/vm-prlctl-reference.png
回報
交接時,僅包含:
- VM 名稱和 OS 版本號。
- 測試的程式碼倉庫提交。
- 權限狀態。
- 通過/失敗的指令。
- 獨立驗證器結果。
- 發現的產品錯誤。