CommunityBildgithub.com

steipete/vm-lab

Parallels macOS VM-Lab: GUI-Automatisierung, Peekaboo, TCC, Ghostty.

Was ist vm-lab?

Dieses Skill ermöglicht den Aufbau und die Nutzung einer sauberen macOS-VM in Parallels zum Testen von GUI-Automatisierung, TCC-Berechtigungsaufforderungen, Screenshot-Erfassung, Mausklicks, Tastatureingaben und Performance-Analysen. Der Kernansatz besteht darin, das zu testende Tool innerhalb der VM auszuführen, die Ergebnisse jedoch von außerhalb der VM zu verifizieren – z.B. durch Parallels-Screenshots und hostseitige Beobachtungen. So wird eine „Zwei-Wege-Validierung“ erreicht: Das Tool liefert JSON-Ausgaben, Screenshot-Dateien oder AX-Ergebnisse, während parallele `prlctl capture`-Befehle und hostseitige Bildprüfungen als unabhängiger, externer Verifizierer dienen. Das Skill unterstützt die VM-Vorbereitung, das Ausführen von Befehlen über Ghostty im Gast, die Behandlung von TCC-Berechtigungen (insbesondere Bildschirmaufnahme) und dokumentiert bekannte Fallstricke bei der Verwendung von `prlctl exec` und Parallels-Tastatur-Injektion. Entwickler erhalten damit eine reproduzierbare Testumgebung für Tools wie Peekaboo, ohne den Host zu gefährden.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/vm-lab

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

VM-Labor

Verwenden Sie dies, wenn eine saubere macOS-VM benötigt wird, um GUI-Automatisierung, TCC-Aufforderungen, Screenshot-Erfassung, Klicken, Tippen, Leistung oder „Zwei-Wege-Validierung“ von Peekaboo-ähnlichen Werkzeugen zu testen.

Kernidee: Führen Sie das zu testende Werkzeug innerhalb des Gasts aus, aber verifizieren Sie es von außerhalb des Gasts mit Parallels-Screenshots und hostseitigen Beobachtungen. Schließen Sie keine Apps, die Ihnen nicht gehören.

Sicherheitsregeln

  • Behandeln Sie den VM-Snapshot als wegwerfbar, nicht den Host.
  • Geben Sie niemals Geheimnisse aus. Wenn op benötigt wird, folgen Sie dem 1Password-Skill und führen Sie es nur innerhalb von tmux aus.
  • Bevorzugen Sie frische App-Fenster, die Sie selbst erstellen: TextEdit, eine lokale HTML-Testseite oder eine kleine Test-App.
  • Vermeiden Sie es, den Host-Status zu ändern, außer bei temporären Screenshots unter /tmp.
  • Verwenden Sie für Git-Repos innerhalb der VM HTTPS-Remotes und normale Branch-Disziplin.

VM-Erkennung

VMs auflisten:

prlctl list --all

VM-Status/IP abrufen:

prlctl list --info "macOS Tahoe"

Gast-Befehle als Peter ausführen:

prlctl exec "macOS Tahoe" \
  'sudo -u steipete -H /bin/zsh -lc '\''source ~/.zprofile 2>/dev/null || true; uname -a'\'''

Unabhängigen hostseitigen Screenshot erstellen:

prlctl capture "macOS Tahoe" --file /tmp/vm-reference.png
sips -g pixelWidth -g pixelHeight /tmp/vm-reference.png

TCC-/GUI-Zuordnung

Für macOS-Bildschirmaufnahme und Bedienungshilfen ist der verantwortliche Prozess entscheidend.

  • prlctl exec ist kopflos und kann fehlschlagen, eine nützliche Bildschirmaufnahme-Zuordnung zu liefern.
  • Starten Sie den Testbefehl aus einer sichtbaren Terminal-App im Gast, wenn die Bildschirmaufnahme betroffen ist.
  • Ghostty funktioniert als GUI-Terminal, falls installiert.
  • Nach einem ersten fehlgeschlagenen Erfassungsversuch überprüfen Sie Systemeinstellungen > Datenschutz & Sicherheit > Bildschirm- & Systemaudioaufnahme.
  • permissions status, ausgeführt über prlctl exec, kann nach dem Erlauben von Ghostty immer noch „false“ für die Bildschirmaufnahme melden; validieren Sie die Bildschirmaufnahme, indem Sie die Erfassung über Ghostty wiederholen.

Den Bereich „Bildschirmaufnahme“ öffnen:

prlctl exec "macOS Tahoe" \
  'sudo -u steipete -H open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"'

Ghostty öffnen:

prlctl exec "macOS Tahoe" 'sudo -u steipete -H open -a Ghostty'

Befehle über Ghostty ausführen

Bester Weg: Erstellen Sie ein Gast-Skript mit prlctl exec, öffnen/fokussieren Sie Ghostty, und tippen Sie dann nur einen kurzen Launcher-Pfad in das sichtbare Terminal.

Gast-Skript-Muster:

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 "Drücken Sie die Eingabetaste zum Schließen..."
read _
exit $rc
EOF
chmod +x /tmp/run-vm-lab.zsh
ln -sf /tmp/run-vm-lab.zsh /tmp/r
open -a Ghostty'\'''

Verknüpfen Sie dann den Launcher mit Ghosttys Home-Verzeichnis und tippen Sie ./r mit scripts/parallels_type.py. Dies vermeidet unzuverlässige Pfadzeichen in der Parallels-Tasteneingabe.

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'

Vermeiden Sie langes Befehlsgetippe. Die Parallels-Tasteneingabe verwendet eine eigene Tastencodetabelle und kann layoutempfindlich sein.

Bekannte Fallstricke

  • macOS-Zwischenablage-APIs können bei prlctl exec fehlschlagen; pbcopy, AppleScript-Zwischenablage und Peekaboo-Einfügen können alle im kopflosen Gast-Kontext fehlschlagen.
  • open -na Ghostty.app --args -e ... kann nur ein vorhandenes Ghostty-Fenster auf macOS fokussieren; gehen Sie nicht davon aus, dass es den Befehl ausführt.
  • prlctl exec kann argv über eine Gast-Shell wieder zusammenführen; übergeben Sie für komplexe Payloads einen vollständig shell-zitierten Befehlstring oder erstellen Sie die Datei mit einem kleinen Python-Schreiber.
  • Parallels send-key-event --key verwendet Parallels-Tastenwerte, nicht macOS-virtuelle Tastencodes.
  • Für normales Tippen senden Sie prlctl send-key-event <vm> --key <key> ohne --event; explizites press/release kann wiederholen oder hängen bleiben. Die Eingabetaste ist eine Ausnahme: Drücken Sie zuerst press, dann release.
  • Bevorzugen Sie einen prlctl send-key-event --json-Batch gegenüber vielen separaten send-key-event-Prozessen; separate Aufrufe können bei Fokus/Latenz abdriften.
  • Verwenden Sie PRL_KEY_ENTER = 36, PRL_KEY_SLASH = 61, PRL_KEY_R = 27, PRL_KEY_T = 28, PRL_KEY_M = 58, PRL_KEY_P = 33.
  • Wenn Tastatureingaben Müll erzeugen, senden Sie die Eingabetaste, um die Zeile zu löschen, erstellen Sie einen kürzeren Launcher und versuchen Sie es erneut.
  • Wenn Peekaboo-Berechtigungssonden bei fehlender Bildschirmaufnahme hängen bleiben und SWIFT TASK CONTINUATION MISUSE ausgeben, erfassen Sie dies als Produktfehler; verwechseln Sie es nicht mit der VM-Testumgebung.

Zwei-Wege-Validierung

Überprüfen Sie für jede GUI-Aktion über zwei unabhängige Signale:

  • Ausgabe des zu testenden Werkzeugs: JSON, Screenshot-Datei, AX-Ergebnis oder App-Status.
  • Externer Verifizierer: prlctl capture, hostseitige Bildinspektion, Dateiinhalt im Gast oder Prozess-/Fensterstatus.

Beispiele:

  • Screenshot: Vergleichen Sie Peekaboo-Bildabmessungen/-inhalt mit prlctl capture.
  • Klicken: Verwenden Sie Peekaboo, um eine Testschaltfläche zu klicken, und überprüfen Sie dann sowohl den Gast-App-Status als auch den Host-Screenshot.
  • Tippen: Verwenden Sie Peekaboo, um in ein kontrolliertes Textfeld zu tippen, und überprüfen Sie dann den AX-Wert und den Host-Screenshot.
  • Leistung: Wickeln Sie Befehle mit /usr/bin/time -p ein; wiederholen Sie kalte/warme Läufe; behalten Sie Ausgaben in /tmp.

Peekaboo-VM-Baseline

Innerhalb des Gasts:

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

Hostseitige Referenzerfassung:

prlctl capture "macOS Tahoe" --file /tmp/vm-prlctl-reference.png

Gastseitige Peekaboo-Erfassung über Ghostty:

/tmp/r

Vergleichen:

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

Berichterstattung

Fügen Sie bei der Übergabe nur Folgendes ein:

  • VM-Name und OS-Build.
  • Getesteter Repo-Commit.
  • Berechtigungsstatus.
  • Befehle, die bestanden/nicht bestanden haben.
  • Ergebnis des unabhängigen Verifizierers.
  • Entdeckte Produktfehler.

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.

Verwandte Skills