Community图像github.com

steipete/vm-lab

Parallels macOS 虚拟机实验室:GUI 自动化、Peekaboo、TCC、Ghostty。

vm-lab 是什么?

VM Lab 是一个为 AI 代理(如 Claude Code)设计的 Parallels macOS 虚拟机技能。它通过主机端截图和观察,从外部验证在虚拟机内运行的 GUI 工具(如 Peekaboo)的行为,实现“双向验证”。该技能支持 macOS 屏幕录制和辅助功能权限(TCC)的管理,并提供通过 Ghostty GUI 终端在虚拟机内运行命令的最佳实践。它涵盖了虚拟机发现、安全规则、常见陷阱以及性能测试方法,帮助开发者高效、安全地自动化 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 虚拟机来测试 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

报告

交接时,仅包含:

  • 虚拟机名称和操作系统版本。
  • 测试的仓库提交。
  • 权限状态。
  • 通过/失败的命令。
  • 独立验证器结果。
  • 发现的产品缺陷。

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.

相关技能