capture-screen

捕获屏幕

在 macOS 上以编程方式截取屏幕：查找窗口、控制视图、捕获图像。

选择观察或前台控制

对于现有视图，枚举并捕获确切窗口，无需激活它。 无需更改视图时，跳过步骤 2。窗口图像只能证明捕获时可见的内容，不能证明键盘焦点、输入是否送达或业务操作是否成功。

打开／调高窗口、滚动、选择、更改缩放或发送按键之前，执行任务的 Agent 应检查用户活动情况以及其他 Agent 是否拥有操作权。使用明确的任务交接或现有的明确桌面空闲授权；若依据后者操作，应协调独占访问权限，然后继续，无需再次询问。输入空闲本身不代表拥有操作权。若桌面占用繁忙／未知或出现意外输入，应停止前台操作；继续独立读取，不要在人类接管后恢复旧焦点。

检查所选工具的激活语义。针对应用的调用或在后台运行的 Shell 任务，并不能证明它会保留焦点。捕获失败不代表可以调高窗口、更改权限，或在遇到主机拒绝／GUI 锁定时改用其他工具。仅在缺少现有授权时请求交接。

快速开始

观察未识别的对话框或整个桌面

用户要求查看整个屏幕，或允许的窗口观察无法识别所报告的遮挡时，使用此流程。首先确认主机允许此捕获及其范围。应用特定的控制操作遭到拒绝，并不能证明无法截屏；也不代表可以使用其他工具读取主机保护的内容。如果拒绝涵盖拟议的捕获，或 GUI 锁定阻止捕获，请停止。

不激活、不滚动、不输入，直接捕获：

capture_dir="$(mktemp -d)"
screencapture -x "$capture_dir/desktop.png"

使用主机许可的图像查看器检查生成的图像。在多显示器桌面上，声称已检查整个桌面之前，应检查每个生成的显示器图像。仅创建文件不能证明已捕获所需的对话框。识别后，后续观察优先使用确切窗口，并将用户报告的交互故障纳入考虑。

按照 macOS 权限所有者的 macos-permissions 条目进行分类和恢复。

捕获已知窗口

# Find Excel window ID
swift scripts/get_window_id.swift Excel

# Capture that window (replace 12345 with actual WID)
screencapture -x -l 12345 output.png

步骤 1：获取窗口 ID（Swift）

主机允许枚举窗口时，使用捆绑的 Swift/CoreGraphics 流程。如果主机提供所需的 ID，优先使用主机原生窗口清单。

快速内联执行

swift -e '
import CoreGraphics
let keyword = "Excel"
let list = CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID) as? [[String: Any]] ?? []
for w in list {
    let owner = w[kCGWindowOwnerName as String] as? String ?? ""
    let name = w[kCGWindowName as String] as? String ?? ""
    let wid = w[kCGWindowNumber as String] as? Int ?? 0
    if owner.localizedCaseInsensitiveContains(keyword) || name.localizedCaseInsensitiveContains(keyword) {
        print("WID=\(wid) | App=\(owner) | Title=\(name)")
    }
}
'

使用捆绑脚本

swift scripts/get_window_id.swift Excel
swift scripts/get_window_id.swift Chrome
swift scripts/get_window_id.swift          # List all windows

输出格式：WID=12345 | App=Microsoft Excel | Title=workbook.xlsx

解析出 WID 数字，以便与 screencapture -l 配合使用。

步骤 2：控制窗口（AppleScript，可选的前台操作）

仅在上述授权的前台操作时段内使用这些命令。使用任何 active window 或 active workbook 示例之前，先确定确切的应用／窗口／文档；切勿根据恰好处于活动状态的窗口推断目标。

Microsoft Excel（完整支持 AppleScript）

# Activate (bring to front)
osascript -e 'tell application "Microsoft Excel" to activate'

# Set zoom level (percentage)
osascript -e 'tell application "Microsoft Excel"
    set zoom of active window to 120
end tell'

# Scroll to specific row
osascript -e 'tell application "Microsoft Excel"
    set scroll row of active window to 45
end tell'

# Scroll to specific column
osascript -e 'tell application "Microsoft Excel"
    set scroll column of active window to 3
end tell'

# Select a cell range
osascript -e 'tell application "Microsoft Excel"
    select range "A1" of active sheet
end tell'

# Select a specific sheet
osascript -e 'tell application "Microsoft Excel"
    activate object sheet "DCF" of active workbook
end tell'

# Open a file
osascript -e 'tell application "Microsoft Excel"
    open POSIX file "/path/to/file.xlsx"
end tell'

任意应用（基本控制）

# Activate any app
osascript -e 'tell application "Google Chrome" to activate'

# Bring specific window to front (by index)
osascript -e 'tell application "System Events"
    tell process "Google Chrome"
        perform action "AXRaise" of window 1
    end tell
end tell'

时序与超时

AppleScript 命令后务必添加 sleep 1，以便 UI 完成渲染。

重要提示：如果目标应用未运行或无响应，osascript 会无限期挂起。务必使用 timeout 包装：

timeout 5 osascript -e 'tell application "Microsoft Excel" to activate'

步骤 3：捕获（screencapture）

# Capture specific window by ID
screencapture -l <WID> output.png

# Silent capture (no camera shutter sound)
screencapture -x -l <WID> output.png

# Capture as JPEG
screencapture -l <WID> -t jpg output.jpg

# Capture with delay (seconds)
screencapture -l <WID> -T 2 output.png

# Capture a screen region (interactive)
screencapture -R x,y,width,height output.png

Retina 显示器

在 Retina Mac 上，screencapture 默认以 2 倍分辨率输出（例如，2032x1238 的窗口会生成 4064x2476 的 PNG）。这是正常现象。要获得 1 倍分辨率，请在捕获后调整大小：

sips --resampleWidth 2032 output.png --out output_1x.png

验证捕获结果

# Check file was created and has content
ls -la output.png
file output.png    # Should show "PNG image data, ..."

多次截取工作流

前台操作示例：截取 Excel 工作簿的多个部分。首先建立上述授权并确保拥有独占操作权。如果用户接管，应停止剩余操作，而不是重放操作序列或恢复之前的焦点。

# 1. Open file and activate Excel
osascript -e 'tell application "Microsoft Excel"
    open POSIX file "/path/to/model.xlsx"
    activate
end tell'
sleep 2

# 2. Set up view
osascript -e 'tell application "Microsoft Excel"
    set zoom of active window to 130
    activate object sheet "Summary" of active workbook
end tell'
sleep 1

# 3. Get window ID
#    IMPORTANT: Always re-fetch before capturing. CGWindowID is invalidated
#    when an app restarts or a window is closed and reopened.
WID=$(swift -e '
import CoreGraphics
let list = CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID) as? [[String: Any]] ?? []
for w in list {
    let owner = w[kCGWindowOwnerName as String] as? String ?? ""
    let wid = w[kCGWindowNumber as String] as? Int ?? 0
    if owner == "Microsoft Excel" { print(wid); break }
}
')
echo "Window ID: $WID"

# 4. Capture Section A (top of sheet)
osascript -e 'tell application "Microsoft Excel"
    set scroll row of active window to 1
end tell'
sleep 1
screencapture -x -l $WID section_a.png

# 5. Capture Section B (further down)
osascript -e 'tell application "Microsoft Excel"
    set scroll row of active window to 45
end tell'
sleep 1
screencapture -x -l $WID section_b.png

# 6. Switch sheet and capture
osascript -e 'tell application "Microsoft Excel"
    activate object sheet "DCF" of active workbook
    set scroll row of active window to 1
end tell'
sleep 1
screencapture -x -l $WID dcf_overview.png

失败的方法（切勿使用）

这些方法已在 macOS 上经过测试，确认会失败：

方法	错误	失败原因
System Events → id of window	Error -1728	System Events 无法访问 screencapture 所需格式的窗口 ID
Python import Quartz（PyObjC）	ModuleNotFoundError	系统 Python 未安装 PyObjC；不要尝试安装，请改用 Swift
osascript 窗口 ID	格式错误	返回的是 AppleScript 窗口索引，而不是 screencapture -l 所需的 CGWindowID

权限故障排查

如果 get_window_id.swift 无法枚举窗口，或缺少所需字段， 请先读取实际结果，再判断失败是否由屏幕录制权限导致。请求 辅助工具提供诊断指引，但不要枚举窗口：

swift scripts/get_window_id.swift --permission-hint screen
swift scripts/get_window_id.swift --permission-hint microphone

使用辅助工具诊断流程解读该输出。 提示会打印指引和执行上下文；它不会检查授权状态，也不会确定应向哪个进程授予权限。请将常规 TCC 归因、 权限变更和请求恢复交由 macos-permissions 处理。

支持的应用程序

应用程序	窗口 ID	AppleScript 控制	备注
Microsoft Excel	Swift	完整（缩放、滚动、选择、激活工作表）	支持最佳
Google Chrome	Swift	基础（激活、窗口管理）	无法通过 AppleScript 滚动或缩放
其他 macOS 应用	Swift 或经许可的宿主清单	视应用而定	捕获需要宿主权限以及可捕获的表面

AppleScript 控制能力因应用而异。Excel 拥有最丰富的 AppleScript 词典。对于 AppleScript 支持有限的应用，只有通过入口检查后，才可将通过 System Events 模拟按键作为前台替代方案；它不是后台操作失败后的自动恢复方式。