AI Skills
peekaboo

peekaboo

熱門

使用 Peekaboo CLI 捕捉並自動化 macOS 使用者介面。

38萬星標
8.1萬分支
更新於 2026/7/22
獲取技能源代碼

相關技能

seo-sxo1.2萬ui-to-vue24萬frontend-skill8.4萬
SKILL.md
readonlyread-only
name
peekaboo
description

使用 Peekaboo CLI 捕捉並自動化 macOS 使用者介面。

Peekaboo

Peekaboo 是一個完整的 macOS UI 自動化 CLI：可捕捉/檢查螢幕、鎖定 UI 元件、驅動輸入，以及管理應用程式/視窗/選單。所有指令共享快照快取，並支援 --json/-j 以利腳本化。執行 peekaboo 或 peekaboo <cmd> --help 查看旗標；peekaboo --version 會顯示建置中繼資料。提示：透過 polter peekaboo 執行以確保使用最新建置。

OpenClaw Bridge

OpenClaw macOS 應用程式在 ~/Library/Application Support/OpenClaw/bridge.sock 託管 Peekaboo Bridge。從 OpenClaw 執行 Peekaboo 前，請選取該 socket，讓 CLI 使用應用程式的螢幕錄製與輔助使用權限，而非啟動獨立的 daemon：

export PEEKABOO_BRIDGE_SOCKET="${PEEKABOO_BRIDGE_SOCKET:-$HOME/Library/Application Support/OpenClaw/bridge.sock}"

使用 peekaboo bridge status --json 確認路由；hostKind 必須為 gui，且 socket 路徑結尾必須是 OpenClaw/bridge.sock。

功能（所有 CLI 能力，不含 agent/MCP）

核心

  • bridge：檢查 Peekaboo Bridge 主機連線狀態
  • capture：即時捕捉或影片匯入 + 影格萃取
  • clean：清除快照快取與暫存檔
  • config：初始化/顯示/編輯/驗證、提供者、模型、憑證
  • image：擷取螢幕截圖（螢幕/視窗/選單列區域）
  • learn：列印完整 agent 指南 + 工具目錄
  • list：列出應用程式、視窗、螢幕、選單列、權限
  • permissions：檢查螢幕錄製/輔助使用狀態
  • run：執行 .peekaboo.json 腳本
  • sleep：暫停執行一段時間
  • tools：列出可用工具，支援篩選與顯示選項

互動

  • click：依 ID/查詢/座標點擊，具智慧等待
  • drag：跨元件/座標/Dock 拖放
  • hotkey：修飾鍵組合，例如 cmd,shift,t
  • move：游標定位，可選平滑移動
  • paste：設定剪貼簿 -> 貼上 -> 還原
  • press：特殊按鍵序列，可重複
  • scroll：方向性捲動（鎖定目標 + 平滑）
  • swipe：手勢式拖曳，在目標之間
  • type：文字 + 控制鍵（--clear、延遲）

系統

  • app：啟動/結束/重新啟動/隱藏/顯示/切換/列出應用程式
  • clipboard：讀寫剪貼簿（文字/圖片/檔案）
  • dialog：點擊/輸入/檔案/關閉/列出系統對話框
  • dock：啟動/右鍵點擊/隱藏/顯示/列出 Dock 項目
  • menu：點擊/列出應用程式選單 + 選單額外項目
  • menubar：列出/點擊狀態列項目
  • open：強化版 open，支援應用程式鎖定與 JSON 負載
  • space：列出/切換/移動視窗（Spaces）
  • visualizer：展示 Peekaboo 視覺回饋動畫
  • window：關閉/最小化/最大化/移動/調整大小/聚焦/列出

視覺

  • see：附註解的 UI 地圖、快照 ID、可選分析

全域執行時期旗標

  • --json/-j、--verbose/-v、--log-level <level>
  • --no-remote、--bridge-socket <path>

快速入門（快樂路徑）

peekaboo permissions
peekaboo list apps --json
peekaboo see --annotate --path /tmp/peekaboo-see.png
peekaboo click --on B1
peekaboo type "Hello" --return

常見鎖定參數（大部分互動指令）

  • 應用程式/視窗：--app、--pid、--window-title、--window-id、--window-index
  • 快照鎖定：--snapshot（ID 來自 see；預設為最新）
  • 元件/座標：--on/--id（元件 ID）、--coords x,y
  • 焦點控制：--no-auto-focus、--space-switch、--bring-to-current-space、--focus-timeout-seconds、--focus-retry-count

常見捕捉參數

  • 輸出：--path、--format png|jpg、--retina
  • 鎖定：--mode screen|window|frontmost、--screen-index、--window-title、--window-id
  • 分析：--analyze "prompt"、--annotate
  • 捕捉引擎：--capture-engine auto|classic|cg|modern|sckit

常見動作/打字參數

  • 時間：--duration（拖曳/滑動）、--steps、--delay（打字/捲動/按鍵）
  • 擬人化移動：--profile human|linear、--wpm（打字）
  • 捲動：--direction up|down|left|right、--amount <ticks>、--smooth

範例

查看 -> 點擊 -> 打字（最可靠的流程）

peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png
peekaboo click --on B3 --app Safari
peekaboo type "user@example.com" --app Safari
peekaboo press tab --count 1 --app Safari
peekaboo type "supersecret" --app Safari --return

依視窗 ID 鎖定

peekaboo list windows --app "Visual Studio Code" --json
peekaboo click --window-id 12345 --coords 120,160
peekaboo type "Hello from Peekaboo" --window-id 12345

擷取螢幕截圖 + 分析

peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png
peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"
peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"

即時捕捉（動作感知）

peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \
  --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture

應用程式 + 視窗管理

peekaboo app launch "Safari" --open https://example.com
peekaboo window focus --app Safari --window-title "Example"
peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800
peekaboo app quit --app Safari

選單、選單列、Dock

peekaboo menu click --app Safari --item "New Window"
peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"
peekaboo menu click-extra --title "WiFi"
peekaboo dock launch Safari
peekaboo menubar list --json

滑鼠 + 手勢輸入

peekaboo move 500,300 --smooth
peekaboo drag --from B1 --to T2
peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800
peekaboo scroll --direction down --amount 6 --smooth

鍵盤輸入

peekaboo hotkey --keys "cmd,shift,t"
peekaboo press escape
peekaboo type "Line 1\nLine 2" --delay 10

備註

  • 需要螢幕錄製 + 輔助使用權限。
  • 在 OpenClaw 子程序中，請如上設定 PEEKABOO_BRIDGE_SOCKET。除非呼叫程序本身擁有螢幕錄製授權，否則不要傳遞 --no-remote。
  • 診斷子程序捕捉失敗：先執行 peekaboo bridge status --json，再執行 peekaboo permissions status --json，然後執行一般的 Bridge 路由捕捉，例如 peekaboo image --mode screen --json。
  • 在 macOS 15+ 上，「繞過私密視窗選取器」提示與基礎的螢幕錄製授權是分開的；即使 Bridge 權限正確，仍可能出現此提示。
  • 點擊前請使用 peekaboo see --annotate 識別目標。