Peekaboo 🫣 - 实现屏幕识别与自动点击的 macOS 自动化工具

Peekaboo 为 macOS 带来了高保真的屏幕捕获、AI 分析以及完整的 GUI 自动化功能。3.0 版本增加了原生 Agent 流程以及跨 CLI 和 MCP 服务器的多屏幕自动化能力。

主要功能

• 像素级精准捕获（窗口、屏幕、菜单栏），支持可选的 Retina 2x 缩放。
• 支持自然语言的 Agent，可串联 Peekaboo 工具（查看、点击、输入、滚动、热键、菜单、窗口、应用、Dock、空间）。
• 以操作为先的 UI 自动化，适用于日常的点击/滚动任务；当已知目标时，默认使用后台进程输入。
• 直接利用辅助功能（Accessibility）工具进行数值设定和命名操作（set-value, perform-action）。
• 菜单和菜单栏发现功能（输出结构化 JSON），无需点击即可探测。
• 通过 Tachikoma 支持多提供商 AI，包括托管式、本地端以及兼容 OpenAI/Anthropic 的接口。
• 为 Codex、Claude Code、Cursor 提供 MCP 服务器，同时也提供原生 CLI；两者工具集完全一致。
• 可配置、可测试的工作流，支持可复现的会话及严格类型检查。
• 需要 macOS“屏幕录制”和“辅助功能”权限（详情请见 docs/permissions.md）。

安装

• macOS 应用 + CLI (Homebrew):

  brew install steipete/tap/peekaboo
  

• MCP 服务器 (需 Node 22+，无需全局安装):

  npx -y @steipete/peekaboo
  

快速上手

# 以 Retina 分辨率截取全屏并保存至桌面
peekaboo image --mode screen --retina --path ~/Desktop/screen.png

# 通过标签点击按钮（一次性完成捕获、解析并点击）
peekaboo see --app Safari --json | jq -r '.data.snapshot_id' | read SNAPSHOT
peekaboo click --on "Reload this page" --snapshot "$SNAPSHOT"

# 当辅助功能数值可设置时，直接设定文本字段值
peekaboo set-value --on T1 --value "hello" --snapshot "$SNAPSHOT"

# 在元素上调用特定的辅助功能操作
peekaboo perform-action --on B1 --action AXPress --snapshot "$SNAPSHOT"

# 运行自然语言自动化任务
peekaboo agent "Open Notes and create a TODO list with three items"

# 作为 MCP 服务器运行 (Codex, Claude Code, Cursor)
npx -y @steipete/peekaboo

# 最小化 MCP 客户端配置片段:
# {
#   "mcpServers": {
#     "peekaboo": {
#       "command": "npx",
#       "args": ["-y", "@steipete/peekaboo"],
#       "env": {
#         "PEEKABOO_AI_PROVIDERS": "openai/gpt-5.5,anthropic/claude-opus-4-7"
#       }
#     }
#   }
# }

Shell 自动补全

Peekaboo 可以直接利用 Commander 元数据生成 Shell 原生补全，这些元数据同时也驱动了 CLI 的帮助文档：

# 当前 Shell (推荐)
eval "$(peekaboo completions $SHELL)"

# 指定 Shell
eval "$(peekaboo completions zsh)"
eval "$(peekaboo completions bash)"
peekaboo completions fish | source

关于持久化配置和故障排除，请参考 docs/commands/completions.md。

后台输入 vs 前台输入

当 Peekaboo 可以通过 --app、--pid、--window-id 或快照元数据解析出目标进程时，click、type、press、hotkey 和 paste 命令默认采用后台投递模式。后台投递会在不将目标应用置于前台的情况下发送进程特定输入，因此脚本可以在不抢占焦点的情况下与 Safari、Notes、Terminal 等应用交互。

当应用仅在获得焦点且处于激活状态的窗口中接受输入时，或者你需要模拟真实的前台鼠标事件，又或者你有意控制当前焦点时，请使用 --foreground。焦点相关标志（如 --space-switch 和 --bring-to-current-space）同样暗示使用前台投递。后台输入需要发送事件的进程拥有“事件合成（Event Synthesizing）”权限；如果 permissions status 显示未获得权限，请运行 peekaboo permissions request-event-synthesizing。