VM Lab
当任务需要一个干净的 macOS 虚拟机来测试 GUI 自动化、TCC 提示、截图捕获、点击、输入、性能或对 Peekaboo 类工具进行“双向验证”时,使用此技能。
核心思想:在客户机内运行被测工具,但从客户机外部通过 Parallels 截图和主机端观察进行验证。不要关闭你不拥有的应用程序。
安全规则
- 将虚拟机快照视为可丢弃的,而非主机。
- 绝不打印秘钥。如果需要
op,请遵循 1Password 技能,并仅在tmux内运行。 - 优先使用自己创建的新应用窗口:TextEdit、本地 HTML 测试页面或小型测试应用。
- 避免修改主机状态,除非是
/tmp下的临时截图。 - 对于虚拟机内的 git 仓库,使用 HTTPS 远程地址和常规分支规范。
虚拟机发现
列出虚拟机:
prlctl list --all
获取虚拟机状态/IP:
prlctl list --info "macOS Tahoe"
以 Peter 身份运行客户机命令:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H /bin/zsh -lc '\''source ~/.zprofile 2>/dev/null || true; uname -a'\'''
捕获独立的主机端截图:
prlctl capture "macOS Tahoe" --file /tmp/vm-reference.png
sips -g pixelWidth -g pixelHeight /tmp/vm-reference.png
TCC / GUI 归属
对于 macOS 屏幕录制和辅助功能,负责的进程至关重要。
prlctl exec是无头操作,可能无法产生有用的屏幕录制归属信息。- 当涉及屏幕录制时,请从客户机内的可见终端应用启动测试命令。
- 如果安装了 Ghostty,它可作为一个 GUI 终端使用。
- 在第一次捕获失败后,检查
系统设置 > 隐私与安全性 > 屏幕与系统音频录制。 - 在允许 Ghostty 后,通过
prlctl exec运行的permissions status仍可能报告屏幕录制为假;请通过从 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 创建客户机脚本,打开/聚焦 Ghostty,然后将一个简短的启动器路径输入到可见终端中。
客户机脚本模式:
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 "按回车关闭..."
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 按键注入使用其自己的键码表,并且可能受键盘布局影响。
已知陷阱
- 从
prlctl exec调用时,macOS 剪贴板 API 可能失败;pbcopy、AppleScript 剪贴板和 Peekaboo 粘贴在无头客户机上下文中都可能失败。 open -na Ghostty.app --args -e ...在 macOS 上可能仅聚焦已存在的 Ghostty 窗口;不要假设它会运行该命令。prlctl exec可能通过客户机 shell 重新连接 argv;对于复杂负载,传递一个完全 shell 引用的命令字符串,或使用一个小型 Python 写入器创建文件。- Parallels
send-key-event --key使用 Parallels 键值,而非 macOS 虚拟键码。 - 对于普通输入,使用
prlctl send-key-event <vm> --key <key>且不带--event;显式的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。 - 如果按键产生乱码,发送回车清除该行,创建一个更短的启动器,然后重试。
- 如果 Peekaboo 权限探测因缺少屏幕录制而挂起并发出
SWIFT TASK CONTINUATION MISUSE,请将其记录为产品缺陷;不要将其与虚拟机工具混淆。
双向验证
对于每个 GUI 操作,通过两个独立的信号进行验证:
- 被测工具输出:JSON、截图文件、AX 结果或应用状态。
- 外部验证器:
prlctl capture、主机端图像检查、客户机内文件内容或进程/窗口状态。
示例:
- 截图:比较 Peekaboo 图像尺寸/内容与
prlctl capture。 - 点击:使用 Peekaboo 点击测试按钮,然后同时验证客户机应用状态和主机截图。
- 输入:使用 Peekaboo 在受控文本字段中键入,然后验证 AX 值和主机截图。
- 性能:使用
/usr/bin/time -p包装命令;重复冷/热运行;将输出保存在/tmp中。
Peekaboo VM 基线
在客户机内:
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
主机端参考捕获:
prlctl capture "macOS Tahoe" --file /tmp/vm-prlctl-reference.png
客户机端通过 Ghostty 的 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
报告
交接时,仅包含:
- 虚拟机名称和操作系统版本。
- 测试的仓库提交。
- 权限状态。
- 通过/失败的命令。
- 独立验证器结果。
- 发现的产品缺陷。