Peekaboo 🫣

Peekaboo 是一款面向 macOS 的 AI 驱动 GUI 自动化工具，由 openclaw 组织开发维护。它通过 ScreenCaptureKit 实现像素级屏幕捕获（全屏、窗口、菜单栏，支持 Retina 2x，延迟 20–100 ms），将截图送入多供应商 AI 视觉模型（GPT-5.1、Claude 4.x、Grok 4-fast、Gemini 2.5、本地 Ollama）进行元素检测与语义标注，输出结构化 JSON 快照（snapshot_id + UI 元素列表），再基于 macOS Accessibility API 执行 click、type、scroll、swipe、drag、hotkey 等全套 GUI 操作。

核心能力

• 自然语言 Agent：peekaboo agent 命令支持自然语言任务，自动链式调用 see → decide → do 循环，完成多步骤 GUI 自动化
• 脚本化执行：peekaboo run 执行 .peekaboo.json 自动化脚本，可集成 CI/CD
• MCP Server 模式：通过 @steipete/peekaboo npm 包以 MCP 协议暴露完整工具集，与 Claude Desktop、Cursor 等 AI 编码工具无缝集成
• 菜单结构化发现：无需点击即可列出应用菜单和系统菜单栏的结构化 JSON
• 多屏支持：v3 新增跨屏幕自动化能力
• 快照缓存：元素检测结果按快照缓存，避免重复 AI 调用
• 可视化反馈层：PeekabooVisualizer 独立模块，通过 NSDistributedNotificationCenter 提供非阻塞动画反馈
• Shell 补全：peekaboo completions 生成 zsh/bash/fish 补全脚本

架构设计 采用服务定位器 + 依赖注入模式，分为以下模块：

• PeekabooAutomation：自动化核心，直接调用 macOS Accessibility 与 ScreenCaptureKit API，负责配置、截图、应用/菜单/窗口服务、快照管理、类型化模型
• Tachikoma：AI 模型管理（依赖注入模式），抽象 OpenAI/Anthropic/Grok/Ollama 供应商
• PeekabooAgentRuntime：MCP 工具注册、ToolRegistry、Agent 服务编排
• PeekabooVisualizer：独立可视化反馈层（VisualizationClient、事件存储）
• PeekabooCore：Umbrella 模块，导出导入 + PeekabooServices 便捷容器

所有 UI 操作绑定 MainActor 以满足 macOS Accessibility API 主线程要求，采用分层错误处理（服务层 → 编排层 → Agent 层 → 客户端层）。

子项目（git submodules）：AXorcist（Accessibility 封装）、Commander（CLI 框架）、Swiftdansi（ANSI 终端输出）、Tachikoma（AI 模型抽象）、TauTUI（TUI 组件）

安装与使用

• Homebrew：brew install steipete/tap/peekaboo
• MCP Server：npx -y @steipete/peekaboo（需 Node 22+）
• 前置条件：macOS 15+（Sequoia）、Screen Recording + Accessibility 权限、至少一个 AI 供应商凭证或本地 Ollama
• 配置优先级：CLI 参数 > 环境变量 > 凭证文件 > 配置文件 > 默认值

能力边界：仅支持 macOS（Windows 有非官方重写 PeekabooWin）；视觉理解依赖外部 AI 模型，本身不含推理模型；需 Screen Recording + Accessibility 两项系统权限。采用 MIT 许可证。