Community影像github.com

steipete/vm-lab

Parallels macOS VM 實驗室:GUI 自動化、Peekaboo、TCC、Ghostty。

vm-lab 是什麼?

此技能提供一個乾淨的 macOS VM 環境,用於測試 GUI 自動化、TCC 權限提示、螢幕截圖、點擊、鍵盤輸入、性能分析,以及工具(如 Peekaboo)的雙向驗證。核心策略是在 guest 內部執行受測工具,但從 host 端透過 Parallels 截圖和觀察來進行驗證,確保測試結果的獨立性與可靠性。支援透過 `prlctl` 指令管理 VM、執行 guest 指令,並能直接操作 Ghostty 終端機來處理需要螢幕錄製權限的操作。內建安全規則與已知陷阱清單,幫助開發者避免常見問題,例如避免在無頭的 guest 環境中使用剪貼簿 API,以及正確處理 Parallels 按鍵注入的佈局敏感性。此技能適用於 Claude Code、Cursor 等 AI 代理工具,透過詳細的指令與腳本範例,引導使用者建立高效的 macOS GUI 自動化測試工作流程。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/vm-lab

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 版本號。
  • 測試的程式碼倉庫提交。
  • 權限狀態。
  • 通過/失敗的指令。
  • 獨立驗證器結果。
  • 發現的產品錯誤。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

相關技能