Community影像github.com

steipete/peekaboo

macOS 螢幕截圖、UI 檢查、點擊、鍵入、應用程式/視窗自動化。

peekaboo 是什麼?

Peekaboo 是一個 macOS 專用的工具,整合了螢幕截圖、UI 檢測與 GUI 自動化功能。它依賴一個後台應用程式(Peekaboo.app)來處理 TCC 權限以及與 CLI 的通訊;CLI 本身不會自動啟動此應用程式。使用前需確認「螢幕錄製」與「輔助使用」權限已啟用——截圖需要前者,點擊與鍵入等操作則需要後者。Peekaboo 支援多種自動化工作流程,包括螢幕抓取、應用程式/視窗列舉、元素點擊、文字輸入以及長時間的螢幕錄製。其 CLI 輸出採用 JSON 格式,便於機器解析,並提供 `tools` 與 `learn` 指令供探索與學習使用。該工具主要針對 macOS 開發者與 AI 代理設計,可透過本機建置或預編譯的二進位檔(建議位於 `~/bin/peekaboo`)安裝。

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

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

在你喜歡的 AI 中提問

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

說明文件

peekaboo 是做什麼的?

用於 macOS 螢幕截圖、UI 檢測和 GUI 自動化。

二進位檔

  • 優先使用 ~/bin/peekaboo(若存在);這是 Peter 的本機發行副本。
  • 否則使用 peekaboo。
  • 先檢查:~/bin/peekaboo --version || peekaboo --version。

Mac 應用程式主機

  • 在進行即時截圖/自動化之前,請啟動 Peekaboo.app;CLI 不會自動啟動它。
  • 此應用程式擁有 TCC 授權,並提供 ~/Library/Application Support/Peekaboo/bridge.sock 服務。
  • 已安裝的應用程式:open -a Peekaboo。從儲存庫建置:建置 Apps/Mac/Peekaboo.xcodeproj 的 Peekaboo 方案,然後開啟產生的 Peekaboo.app。
  • peekaboo daemon start 並非啟動應用程式;守護程式有獨立的權限和 daemon.sock。
  • 使用 peekaboo bridge status --verbose --json 驗證是否選擇了 hostKind: gui;若需要確定性的應用程式路由,請使用 --bridge-socket "$HOME/Library/Application Support/Peekaboo/bridge.sock"。

安全性

  • 在進行截圖/自動化之前,請檢查權限:peekaboo permissions status --json。
  • 螢幕截圖需要「螢幕錄製」權限;點擊、鍵入、視窗控制則需要「輔助使用」權限。
  • 在遠端 Mac 上,螢幕截圖可能因缺少「螢幕錄製」而受阻,但點擊/鍵入仍可透過「輔助使用」運作;當目標在其他方面可知時,可繼續使用點擊或 DOM 自動化。
  • 偏好使用 --json 以利機器解析,並在測試本機 TCC 時使用 --no-remote。
  • 除非使用者要求,或目標是受控測試環境,否則請勿進行點擊/鍵入/破壞性自動化。

常用指令

PB="${PEEKABOO_BIN:-$HOME/bin/peekaboo}"
[ -x "$PB" ] || PB="$(command -v peekaboo)"

"$PB" permissions status --json
open -a Peekaboo
"$PB" bridge status --verbose --json
"$PB" list screens --json
"$PB" list apps --json
"$PB" list windows --app Safari --json
"$PB" image --mode screen --screen-index 0 --path /tmp/screen.png --json --no-remote
"$PB" see --app frontmost --path /tmp/frontmost.png --json --annotate
"$PB" tools --json
"$PB" learn
"$PB" click --coords 100,100 --json
"$PB" type "text" --json

工作流程

  1. 如上解析 PB,並在安裝狀態重要時確認版本。
  2. 若需進行即時 UI 操作,請啟動 Peekaboo.app;驗證 GUI 橋接及其權限。
  3. 執行 permissions status --json;若缺少 TCC,請回報確切缺失的授權。
  4. 若要截圖,請使用 image;加上 --path、--json,且通常(僅在刻意測試呼叫端本機 TCC 時)加上 --no-remote。
  5. 若要定位元素,請執行 see --json --annotate,然後依元素 id/快照進行點擊。
  6. 若需長時間或可感知變化的螢幕截圖,請使用 capture live;若需取樣影片影格,請使用 capture video。
  7. 使用 tools --json 進行指令/工具探索,並在需要完整代理指南時使用 learn。
  8. 使用 sips -g pixelWidth -g pixelHeight <path> 驗證輸出檔案,或直接檢視圖片。

文件:~/Projects/Peekaboo/docs/commands/。

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.

相關技能