peekaboo

Peekaboo

使用 Peekaboo 进行原生 macOS 捕获、UI 检查和自动化。只要 Peekaboo 提供相应操作，就优先使用其原生应用、窗口、辅助功能和输入命令，而不是 AppleScript 或 osascript。

二进制文件

• 如果存在，优先使用 ~/bin/peekaboo；这是 Peter 签名的本地发布版本。
• 否则，使用 PATH 中的 peekaboo。
• 在依赖语法或已安装状态之前，先检查选定的二进制文件。

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

运行时主机和权限

• 需要 GUI Bridge 主机时，在不抢占焦点的情况下启动 Peekaboo.app： open -gj -a Peekaboo。
• 该应用拥有自己的 TCC 授权，并提供 ~/Library/Application Support/Peekaboo/bridge.sock。可复用守护进程拥有独立权限，并提供 daemon.sock；daemon start 并不会启动应用。
• 常规运行时选择会优先使用健康的可复用守护进程，其次是 GUI 主机，然后才启动守护进程。但隐式屏幕捕获观察、AX 树检查、浏览器和快照状态命令会优先选择并可能自动启动当前 CLI 构建专属的、按构建范围划分的守护进程，然后才选择 GUI 主机。使用 bridge status --verbose --json 检查候选项，但请记住，操作要求可能改变其顺序。当需要使用由应用持有的 TCC 权限时，传入 --bridge-socket "$HOME/Library/Application Support/Peekaboo/bridge.sock" 并验证 hostKind: gui，不要想当然地认为已选中该应用。
• 检查 permissions status --all-sources --json。将屏幕录制、辅助功能和事件合成权限授予报告为已选来源的进程，而不只是调用命令的终端。
• 在 SSH、LaunchAgent、Codex 和其他后台会话中，优先使用 Bridge 捕获。--no-remote --capture-engine cg 是本地调试用覆盖选项，在当前活跃的 Aqua 会话之外可能只返回壁纸像素。
• 切勿使用未签名或临时签名的构建访问已保存的 TCC 或 Keychain 状态。

后台优先的安全性

• 默认情况下，不要影响用户的前台应用、键盘焦点和物理光标。提供精确的 --app、--pid、--window-id 或新鲜的快照目标，并使用 Peekaboo 的后台传递方式。
• 切勿仅为猜测性地让命令运行而添加 --foreground。只有在用户授权前台交互，或目标明确拒绝后台传递时，才添加该参数。
• 共享光标和无目标的全局输入必须显式使用前台模式。这包括 move、drag、无目标或平滑滚动，以及无目标键盘输入；click --long-press 只能在前台使用。前台模式可能会打断用户。
• 后台输入和粘贴需要可解析的应用或 PID、最多只有一个符合条件窗口的完整清单，以及事件合成权限。原始 press 还需要精确的窗口选择器或精确窗口的新鲜快照；仅指定应用或 PID 的组合键操作需要显式使用前台模式。
• 除非用户提出要求，或目标是受控测试环境，否则不要点击、输入、粘贴、退出或以其他方式修改 UI。每次修改后都要重新观察；切勿盲目重放结果不确定的输入。

v4 命令名称

• 清单：app list、window list 和 screen list；没有顶层的 list 命令。
• 屏幕截图和 UI 检查：像素检查使用 see --no-elements，仅检查 AX 文本则使用 see --tree --no-screenshot；不要使用已移除的 image 或 inspect-ui CLI 命令。
• 键盘组合键：使用 press；不要使用已移除的 hotkey 命令。
• 命名的辅助功能操作：使用 action；不要使用 perform-action。
• 坐标点击：使用 click --at x,y；不要使用 --coords。

常用命令

"$PB" permissions status --all-sources --json
open -gj -a Peekaboo
"$PB" bridge status --verbose --json

"$PB" screen list --json
"$PB" app list --include-hidden --include-background --json
"$PB" window list --app Safari --json

# Screenshot only; observation does not activate the target app.
"$PB" see --no-elements --mode screen --path /tmp/screen.png --json

# Interactive map plus a directly accessible image artifact.
"$PB" see --app Safari --annotate --path /tmp/safari-see.png --json

# AX-only inspection, with no pixel capture or screenshot artifact.
"$PB" see --app Safari --tree --no-screenshot --json

# Use IDs and the snapshot returned by a fresh `see`.
"$PB" click --on "$ELEMENT_ID" --snapshot "$SNAPSHOT_ID" --json
# Generic `action AXPress` requires explicit foreground consent; use the
# dedicated exact-target `click` route above for background button activation.

# Process-targeted background keyboard delivery.
"$PB" type "text" --app TextEdit --json
"$PB" press Return --app TextEdit --window-id 1234 --json
"$PB" paste "text" --app TextEdit --json

"$PB" tools --json
"$PB" tools describe click --json

安全点击坐标

截图像素不等于点击坐标。click --at 使用逻辑点。使用目标标志时，坐标相对于解析出的窗口；不使用目标标志时，坐标是屏幕全局坐标。添加 --global 可让目标坐标使用全局逻辑空间。转换 Retina 像素时，使用 screen list --json 查看显示器边界和缩放因子。

后台坐标点击需要基于新鲜的精确窗口观察显式指定快照。首先解析规范窗口 ID，然后观察该精确窗口，并使用其窗口 ID 和返回的快照 ID：

"$PB" window list --app Safari --json
"$PB" see --app Safari --window-id 12345 --path /tmp/safari.png --json
"$PB" click --window-id 12345 --at 20,40 --snapshot "$SNAPSHOT_ID" --json

Peekaboo 会在派发前重新验证捕获的 PID、进程代次、窗口 ID 和边界。如果无法建立精确回执，后台输入必须失败，而不能猜测。只有在有意进行可见的共享指针交互时才使用 --foreground。后台右键单击和双击可以派发到精确路由，但无法验证效果；重试前先执行一次新的 see。

处理界面元素时，优先使用新鲜 see 返回的 ID，并显式传入快照。查询和隐式使用最新快照更方便，但确定性较低。操作改变界面后，应捕获新快照，而不是重用过时的 ID。

工作流

1. 解析 PB，确认其版本；需要由应用持有 TCC 权限时，在后台启动已签名的 GUI 主机。
2. 验证选定的 Bridge 主机，并比较各来源的权限。
3. 使用 app list 或 window list 解析目标；需要精确清理或变更时，优先使用 PID／窗口 ID，而不是宽泛的名称或标题。
4. 在不抢夺焦点的情况下观察：使用 see --no-elements 获取截图，使用普通 see 获取元素 ID，或使用 see --tree --no-screenshot 仅检查 AX。调用方需要图像文件时，传入 --path。
5. 使用精确目标和新鲜快照在后台交互。优先使用 action 或元素点击，而不是坐标输入。
6. 使用新的 see 或专用只读命令验证每次变更。
7. 只有在获准使用共享光标／全局输入，或确认存在应用限制时，才明确切换到 --foreground；绝不要悄悄提升模式。
8. 使用 capture live 进行感知变化的捕获，使用 capture video 对视频帧采样，使用 tools describe <name> 查看 MCP 架构，并使用 <command> --help 查看当前 CLI 语法。
9. 使用 sips -g pixelWidth -g pixelHeight <path> 验证图像文件，或在本地查看。

权威来源：~/Projects/peekaboo/docs/commands/ 和选定二进制文件的 --help 输出。