Peekaboo

Peekaboo 是一个完整的 macOS UI 自动化 CLI：捕获/检查屏幕、定位 UI 元素、驱动输入，以及管理应用/窗口/菜单。所有命令共享一个快照缓存并支持--json/-j选项以方便脚本编写。运行peekaboo或peekaboo <命令> --help来查看参数；peekaboo --version会打印构建元数据。 提示：通过polter peekaboo运行以确保使用最新构建版本。

功能（所有 CLI 能力，不包括代理/MCP）

核心

• bridge：检查 Peekaboo Bridge 主机连接性
• capture：实时捕获或视频摄取 + 帧提取
• clean：清理快照缓存和临时文件
• config：初始化/显示/编辑/验证配置，管理提供商、模型和凭证
• image：捕获屏幕截图（屏幕/窗口/菜单栏区域）
• learn：打印完整的代理指南和工具目录
• list：应用程序、窗口、屏幕、菜单栏、权限
• permissions：检查屏幕录制/辅助功能状态
• run：执行.peekaboo.jsonscripts
• sleep：暂停执行一段时间
• tools：列出可用的工具，支持筛选和显示选项

交互

• click：通过ID/查询/坐标定位目标，并带有智能等待功能
• drag：跨元素/坐标/程序坞进行拖放操作
• hotkey：组合键，例如cmd,shift,t
• move光标定位（可选平滑处理）
• 粘贴：设置剪贴板 → 粘贴 → 恢复原状
• 按键：特殊按键序列（支持重复操作）
• 滚动：定向滚动（支持目标定位+平滑滚动）
• 滑动：目标间手势式拖拽操作
• 输入：文本+控制键输入（--清除、延迟设置）

系统

• 应用：启动/退出/重启/隐藏/显示/切换/列举应用程序
• 剪贴板：读写剪贴板（支持文本/图像/文件）
• 对话框：点击/输入/文件选择/关闭/列举系统对话框
• 程序坞：启动/右键点击/隐藏/显示/列举程序坞项目
• 菜单：点击/列举应用程序菜单及菜单栏附加功能
• 菜单栏：列出/点击状态栏项目
• 打开：增强型打开附带应用定位 + JSON 负载
• 空间：列出/切换/移动窗口（空间）
• 可视化工具：运用 Peekaboo 视觉反馈动画
• 窗口：关闭/最小化/最大化/移动/调整大小/聚焦/列出

视觉

• 查看：带注释的 UI 映射、快照 ID、可选分析

全局运行时标志

• --json/-j,--verbose/-v,--log-level <level>
• --no-remote,--bridge-socket <路径>

快速入门（理想路径）

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

菜单、菜单栏、程序坞

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

注意事项

• 需要屏幕录制 + 辅助功能权限。
• 使用方法peekaboo see --annotate在点击前识别目标。