vm-lab

VM 实验室

如果任务需要一台干净的 macOS VM 来测试 GUI 自动化、TCC 提示、截图、点击、输入、性能，或对类似 Peekaboo 的工具进行“双向验证”，请使用此环境。

核心思路：在客户机内运行待测工具，同时通过 Parallels 截图和主机端观察从客户机外部进行验证。不要关闭不属于你的应用。

安全规则

• 只有任务专属克隆可以丢弃。保留源快照／黄金快照、恢复 VM 和其他任务的 VM；绝不要重置、还原或删除它们的快照。
• 绝不要访问继承的客户机凭据，也不要绕过登录／启动安全机制来引导克隆。
• 绝不要打印机密信息。如果需要使用 op，请遵循 1Password 技能，并且只在 tmux 中运行。
• 优先使用你自己创建的新应用窗口：TextEdit、本地 HTML 测试页面或小型测试应用。
• 主机上的写入仅限于任务专属临时诊断文件，以及明确获准的克隆恢复操作。绝不要为了实验室变通方案更改全局 Bash／Codex 设置。
• 对 VM 内的 Git 仓库，使用 HTTPS 远程地址并遵循常规分支管理规范。

引导前检查

开始客户机自动化之前，确认任务专属 VM 的确切 UUID 和快照来源；以下名称仅为示例，并不代表获准操作现有 VM。

• Apple-VZ 克隆无法启动：检查活动原始磁盘的内容，而不只是克隆是否成功或逻辑大小。仅有稀疏链接子磁盘并不能证明链已损坏；clone --unlink 会创建另一个克隆，而不是原地修复。
• 打包过程在首次输出之前卡住：检查任务专属 shell 进程和 heredoc 重定向，然后再考虑更改产品代码或构建保护逻辑。使用系统 Bash 重试时，也必须仅对本次调用固定通过 PATH 解析的子 shell。

只读检查、证据限制和范围严格限定的恢复边界，请参阅 引导诊断。

VM 发现

列出 VM：

prlctl list --all

获取 VM 状态／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 终端。
• 首次捕获失败后，请检查“系统设置 > 隐私与安全性 > 屏幕与系统音频录制”。
• 通过 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 创建客户机脚本，打开／聚焦 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 "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 按键注入使用自有的键码表，并且可能受键盘布局影响。

已知陷阱

• 从 prlctl exec 调用 macOS 剪贴板 API 可能会失败；在无头访客环境中，pbcopy、AppleScript 剪贴板和 Peekaboo 粘贴都可能失败。
• 在 macOS 上，open -na Ghostty.app --args -e ... 可能只会将已有的 Ghostty 窗口置于前台；不要假定它会运行命令。
• prlctl exec 可能会通过访客系统 Shell 重新拼接 argv；对于复杂负载，请传入一个完整转义的 Shell 命令字符串，或使用简短的 Python 写入程序创建文件。
• Parallels 的 send-key-event --key 使用 Parallels 键值，而非 macOS 虚拟键码。
• 对于常规输入，请发送 prlctl send-key-event <vm> --key <key>，不要使用 --event；显式的 press/release 可能导致重复输入或按键卡住。Return 是个例外：请先按下，再释放。
• 优先使用一次 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，请将其记录为产品 Bug；不要将其与 VM 测试框架的问题混淆。

双向验证

对于每项 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

报告

交接时仅包含：

• VM 名称和 OS 构建版本。
• 已测试的仓库提交。
• 权限状态。
• 成功/失败的命令。
• 独立验证器结果。
• 发现的产品 Bug。