Peekaboo - macOS UI 自动化工具

Peekaboo 是一款完整的 macOS UI 自动化 CLI，能够捕获/检查屏幕、定位 UI 元素、驱动输入、管理应用/窗口/菜单。所有命令共享快照缓存，支持 --json/-j 用于脚本化。运行 peekaboo 或 peekaboo --help 查看所有 flag；peekaboo --version 会打印构建元数据。提示：通过 polter peekaboo 运行可确保使用最新构建。

功能概览（所有 CLI 能力，不包括 agent/MCP）

Core（核心）

• bridge：检查 Peekaboo Bridge 主机连通性
• capture：实时捕获或视频导入 + 帧提取
• clean：清理快照缓存和临时文件
• config：初始化/显示/编辑/校验，提供 providers、models、credentials 配置
• image：捕获屏幕/窗口/菜单栏区域的截图
• learn：打印完整的 agent 使用指南 + 工具目录
• list：列出 apps、windows、screens、menubar、permissions 等信息
• permissions：检查屏幕录制 / 辅助功能 权限状态
• run：执行 .peekaboo.json 脚本
• sleep：暂停执行指定时长
• tools：列出可用工具，支持过滤/显示选项

Interaction（交互）

• click：通过 ID、查询或坐标点击元素，支持智能等待
• drag：在元素/坐标/Dock 之间拖拽
• hotkey：发送组合键，例如 cmd,shift,t
• move：移动光标，可选平滑曲线
• paste：写入剪贴板 → 粘贴 → 恢复原内容
• press：发送特殊键序列，可设置重复次数
• scroll：方向滚动（可定位 + 平滑）
• swipe：手势式拖动，在两个目标之间滑动
• type：输入文本 + 控制键（--clear、延时等）

System（系统）

• app：启动/退出/重新启动/隐藏/显示/切换/列出应用
• clipboard：读取/写入剪贴板（文本/图片/文件）
• dialog：点击/输入/文件/关闭/列出系统弹窗
• dock：启动/右键/隐藏/显示/列出 Dock 项目
• menu：点击/列出应用菜单及菜单扩展项
• menubar：列出/点击状态栏项目
• open：增强版 open，支持指定应用 + JSON 负载
• space：列出/切换/移动窗口到不同 Space
• visualizer：展示 Peekaboo 可视化反馈动画
• window：关闭/最小化/最大化/移动/重新设置大小/聚焦/列出窗口

Vision（视觉）

• see：生成带注解的 UI 图谱，返回快照 ID，可选分析功能

全局运行时参数

• --json/-j, --verbose/-v, --log-level
• --no-remote, --bridge-socket

快速上手（Happy 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（see 返回的 ID，默认使用最新快照）
• 元素/坐标：--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（drag/swipe），--steps，--delay（type/scroll/press）
• 人类化移动：--profile human|linear, --wpm（打字速度）
• 滚动：--direction up|down|left|right, --amount , --smooth

示例

基本流程：先 see 再 click 再 type（最可靠）

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

注意事项

• 需要 Screen Recording 与 Accessibility 权限。
• 使用 peekaboo see --annotate 在点击前先确认目标位置。