名称： peekaboo
描述： 通过 Peekaboo CLI 捕获并自动化 macOS 用户界面。
主页： https://peekaboo.boo
元数据： {"clawdbot":{"emoji":"👀","os":["darwin"],"requires":{"bins":["peekaboo"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/peekaboo","bins":["peekaboo"],"label":"安装 Peekaboo (brew)"}]}}

Peekaboo

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

功能特性 (所有 CLI 能力，不包括代理/MCP)

核心功能
- bridge: 检查 Peekaboo Bridge 主机连接状态
- capture: 实时捕获或视频摄取 + 帧提取
- clean: 清理快照缓存和临时文件
- config: 初始化/显示/编辑/验证配置、提供者、模型和凭证
- image: 捕获屏幕截图（屏幕/窗口/菜单栏区域）
- learn: 打印完整的代理指南和工具目录
- 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: 列出/切换/移动窗口（桌面空间）
- 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 (来自 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 (拖拽/滑动), --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

注意事项
- 需要屏幕录制和辅助功能权限。
- 点击前使用 peekaboo see --annotate 来识别目标。