Peekaboo：macOS屏幕捕捉与视觉问答工具

Peekaboo 是一个专为 macOS 设计的工具，旨在为 AI 助手提供快速、非侵入式的屏幕捕捉和视觉问答（VQA）功能。它通过苹果的 ScreenCaptureKit 技术实现高效屏幕捕捉，支持捕捉整个屏幕、特定应用或窗口，并可结合本地或云端 AI 模型分析图像内容。Peekaboo 提供命令行界面（CLI）和 MCP 服务器两种使用方式，适合开发者和需要自动化视觉处理的场景。它的设计注重隐私保护，支持本地 AI 模型运行，且捕捉过程不干扰用户操作。工具通过 npm 包或 Homebrew 安装，易于集成到开发流程中。

功能列表

• 快速捕捉 macOS 屏幕，支持整个屏幕、特定应用或窗口。
• 支持视觉问答（VQA），可对捕捉的图像进行 AI 分析。
• 提供模糊匹配功能，精准定位目标窗口。
• 支持多种输出格式，包括 PNG、JPG 和 Base64。
• 自动移除窗口阴影和边框，提升图像清晰度。
• 集成本地 AI 模型（如 Ollama）或云端模型（如 GPT-4 Vision、Claude）。
• 非侵入式捕捉，不干扰当前窗口焦点。
• 提供 TypeScript 支持和 JSON API，方便开发者集成。
• 支持窗口和应用管理，获取运行中的应用和窗口信息。

使用帮助

安装流程

Peekaboo 提供多种安装方式，适合不同用户需求。以下是详细步骤：

方式一：通过 Homebrew 安装（推荐）

Homebrew 是 macOS 的包管理工具，安装 Peekaboo 简单快捷。

1. 打开终端，添加 Peekaboo 的 Homebrew 仓库：

   brew tap steipete/tap
   

2. 安装 Peekaboo：

   brew install peekaboo
   

3. 验证安装，运行以下命令查看版本：

   peekaboo --version
   

方式二：通过 npm 安装（包含 MCP 服务器）

适合需要 MCP 服务器功能的开发者。

1. 确保已安装 Node.js（建议版本 16 或更高）。
2. 在终端运行：

   npm install -g @steipete/peekaboo-mcp
   

3. 验证安装：

   peekaboo --version
   

方式三：从源码构建

适合需要自定义功能的开发者。

1. 克隆 GitHub 仓库：

   git clone https://github.com/steipete/peekaboo.git
   cd peekaboo
   

2. 安装依赖：

   npm install
   

3. 构建 CLI 和 MCP 服务器：

   npm run build:all
   

4. （可选）安装 CLI 到系统路径：

   ./scripts/build-cli-standalone.sh --install
   

方式四：直接下载二进制文件

1. 下载最新版本的二进制文件：

   curl -L https://github.com/steipete/peekaboo/releases/latest/download/peekaboo-macos-universal.tar.gz | tar xz
   

2. 移动到系统路径：

   sudo mv peekaboo-macos-universal/peekaboo /usr/local/bin/
   

配置 AI 模型

Peekaboo 支持本地和云端 AI 模型，用于视觉问答功能。以下以本地 Ollama 模型为例：

1. 安装 Ollama：

   brew install ollama
   ollama serve
   

2. 下载视觉模型（如 llava 或 qwen2-vl）：

   ollama pull llava:latest
   ollama pull qwen2-vl:7b
   

3. 配置 Peekaboo：

   peekaboo config edit
   

   在配置文件中设置 AI 提供者为 <ollama/llava:latest> 或其他模型。

主要功能操作

屏幕捕捉

Peekaboo 支持多种捕捉模式：

• 整个屏幕：捕捉全屏内容。

  peekaboo capture screen --output screen.png
  

• 特定应用：通过应用名称（支持模糊匹配）捕捉。

  peekaboo capture app "Visual Studio Code" --output code.png
  

• 特定窗口：通过窗口标题或索引捕捉。

  peekaboo capture window --title "Document" --output doc.png
  

• 输出格式：支持 PNG、JPG 或 Base64。

  peekaboo capture screen --format base64
  

视觉问答（VQA）

用户可对捕捉的图像提问，AI 模型会分析图像并回答。

1. 捕捉图像并提问：

   peekaboo capture screen --question "What is the main text on the screen?" --output result.json
   

2. 输出结果为 JSON 格式，包含图像和 AI 回答。

窗口管理

列出运行中的应用和窗口：

peekaboo list apps
peekaboo list windows --app "Safari"

注意事项

• 确保 macOS 授予 Peekaboo 屏幕录制权限（系统设置 > 隐私与安全性 > 屏幕录制）。
• 本地 AI 模型需要足够硬件资源，推荐使用 16GB 以上内存。
• 网络连接稳定以确保云端模型正常运行。
• 详细文档可在 GitHub 查看：

  open https://github.com/steipete/peekaboo
  

应用场景

1. 开发者调试
   开发者可使用 Peekaboo 捕捉应用窗口，分析 UI 元素或错误信息。例如，捕捉代码编辑器窗口并询问“代码中是否有语法错误”，快速定位问题。
2. 自动化工作流
   AI 助手可通过 Peekaboo 监控屏幕内容，自动执行任务。例如，捕捉浏览器窗口并提取网页文本，用于数据分析。
3. 教育与培训
   教师可捕捉教学软件界面，结合 VQA 功能生成教学材料。例如，提问“图表中的数据点是什么”，快速整理课程内容。
4. 远程技术支持
   技术支持人员可捕捉用户屏幕，分析界面问题并提供指导，无需用户手动发送截图。

QA

1. Peekaboo 支持哪些 AI 模型？
   支持本地模型（如 Ollama 的 llava 和 qwen2-vl）以及云端模型（如 GPT-4 Vision、Claude）。
2. 是否需要持续联网？
   使用本地模型无需联网，使用云端模型需要稳定网络。
3. 如何确保捕捉不干扰操作？
   Peekaboo 使用 ScreenCaptureKit，捕捉时不更改窗口焦点，保证非侵入式操作。
4. 如何处理权限问题？
   首次运行需在系统设置中授予屏幕录制权限，否则无法捕捉屏幕。