macpilot-screenshot-ocr

MacPilot 截图与 OCR

使用 MacPilot 捕获屏幕、指定区域或应用窗口的截图，并使用 Apple 内置的 Vision OCR 从图像或屏幕区域中提取文本。

适用场景

在以下情况下使用此技能：

• 需要捕获当前屏幕内容
• 需要从图像文件中提取文本
• 需要读取屏幕特定区域中的文本
• 需要捕获特定应用窗口
• 需要验证应用的视觉状态
• 需要录制屏幕

截图命令

全屏

macpilot screenshot --json                           # Capture to temp file
macpilot screenshot ~/Desktop/screen.png --json      # Capture to specific path
macpilot screenshot --with-permissions --json        # Use CGWindowListCreateImage directly

指定区域

macpilot screenshot --region 100,200,800,600 --json
# Region format: x,y,width,height (from top-left corner)

指定窗口

macpilot screenshot --window "Safari" --json         # Capture Safari window
macpilot screenshot --window "Finder" --json         # Capture Finder window

所有窗口

macpilot screenshot --all-windows --json             # Each window separately

指定显示器

macpilot screenshot --display 1 --json               # Second display (0-indexed)

格式选项

macpilot screenshot --format png ~/Desktop/shot.png  # PNG (default, lossless)
macpilot screenshot --format jpg ~/Desktop/shot.jpg  # JPEG (smaller files)

OCR 命令

从图像文件中提取文本

macpilot ocr scan /path/to/image.png --json
macpilot ocr scan ~/Desktop/screenshot.png --json

从屏幕区域中提取文本

macpilot ocr scan 100 200 800 600 --json
# Arguments: x y width height (captures region then OCRs it)

多语言 OCR

macpilot ocr scan image.png --language en-US --json       # English
macpilot ocr scan image.png --language ja --json           # Japanese
macpilot ocr scan image.png --language zh-Hans --json      # Simplified Chinese
macpilot ocr scan image.png --language de --json           # German
macpilot ocr scan image.png --language fr --json           # French

OCR 点击（查找并点击屏幕上的文本）

macpilot ocr click "Submit" --json                    # Find text on screen and click it
macpilot ocr click "OK" --app Finder --json           # Click text in specific app
macpilot ocr click "Accept" --timeout 10 --json       # Retry until text appears (10s)

OCR 点击会截取屏幕、运行 OCR、查找匹配文本（不区分大小写），并点击其中心坐标。等待文本出现时，可使用 --timeout 轮询并重试。

屏幕录制（ScreenCaptureKit）

开始录制

macpilot screen record start --output ~/Desktop/recording.mov --json
macpilot screen record start --output rec.mov --region 0,0,1920,1080 --json  # Region
macpilot screen record start --output rec.mov --window Safari --json          # Window
macpilot screen record start --output rec.mov --display 1 --json              # Display
macpilot screen record start --output rec.mov --audio --json                  # With audio
macpilot screen record start --output rec.mov --quality high --fps 60 --json  # Quality

控制录制

macpilot screen record stop --json         # Stop and save
macpilot screen record status --json       # Check if recording
macpilot screen record pause --json        # Pause recording
macpilot screen record resume --json       # Resume recording

画质选项：low（1 Mbps）、medium（5 Mbps，默认）和 high（10 Mbps）。默认 FPS：30。

显示器信息

macpilot display-info --json
# Returns: all displays with resolution, position, scale factor

工作流模式

在一个流程中完成截图和 OCR

# Take screenshot of specific region
macpilot screenshot --region 0,0,1920,1080 ~/tmp/capture.png --json
# Extract text from it
macpilot ocr scan ~/tmp/capture.png --json

快速识别屏幕区域中的文本

# Directly OCR a screen region without saving
macpilot ocr scan 200 100 600 400 --json

查找并点击文本（无需计算坐标）

# Instead of screenshot > OCR > parse > click, just:
macpilot ocr click "Submit" --json
macpilot ocr click "Next" --timeout 5 --json   # Wait up to 5s for text to appear

验证 UI 状态

# Screenshot a window to see its current state
macpilot screenshot --window "Safari" ~/tmp/safari.png --json
# Read the image to verify content
macpilot ocr scan ~/tmp/safari.png --json

录制自动化操作

macpilot screen record start --output ~/Desktop/demo.mov
macpilot app open Safari
macpilot wait seconds 2
macpilot keyboard key cmd+l
macpilot keyboard type "https://example.com"
macpilot keyboard key enter
macpilot wait seconds 3
macpilot screen record stop

提示

• 必须在“系统设置”中授予 MacPilot.app 屏幕录制权限
• 对于包含文本的截图，PNG 格式效果最好（无损）；照片则使用 JPEG
• OCR 在高对比度文本上的效果最好；如果文本较小，请增大截图区域
• 捕获指定区域前，使用 display-info 获取屏幕尺寸
• 坐标系从左上角（0,0）开始，x 轴向右递增，y 轴向下递增
• 在 Retina 显示器上，坐标以逻辑点为单位（而非物理像素）