openai-screenshot

截图捕获

每次都遵循以下保存位置规则：

1. 如果用户指定了路径，就保存到该路径。
2. 如果用户要求截图但未指定路径，就保存到操作系统默认的截图位置。
3. 如果 Agent 需要截图供自身检查，就保存到临时目录。

工具优先级

• 如果有专用工具的截图功能，优先使用（例如：用于 Figma 文件的 Figma MCP/skill，或用于浏览器和 Electron 应用的 Playwright/agent-browser 工具）。
• 仅在用户明确要求、需要捕获整个系统桌面，或专用工具无法捕获所需内容时使用此 skill。
• 其他情况下，对于没有更适合集成的截图工具的桌面应用，默认使用此 skill。

macOS 权限预检（减少重复提示）

在 macOS 上捕获窗口/应用前，先运行一次预检辅助程序。它会检查“屏幕录制”权限、说明为何需要该权限，并在一个步骤中请求权限。

这些辅助程序会将 Swift 的模块缓存路由到 $TMPDIR/codex-swift-module-cache，以避免额外的沙盒模块缓存提示。

bash {baseDir}/scripts/ensure_macos_permissions.sh

为避免多次沙盒批准提示，尽可能在一条命令中组合预检和捕获：

bash {baseDir}/scripts/ensure_macos_permissions.sh && \
python3 {baseDir}/scripts/take_screenshot.py --app "the agent"

对于 Agent 检查时的运行，将输出保存在临时目录中：

bash {baseDir}/scripts/ensure_macos_permissions.sh && \
python3 {baseDir}/scripts/take_screenshot.py --app "<App>" --mode temp

使用随附脚本，避免重新推导特定操作系统的命令。

macOS 和 Linux（Python 辅助程序）

从仓库根目录运行辅助程序：

python3 {baseDir}/scripts/take_screenshot.py

常见用法：

• 默认位置（用户要求“截一张图”）：

python3 {baseDir}/scripts/take_screenshot.py

• 临时位置（Agent 进行视觉检查）：

python3 {baseDir}/scripts/take_screenshot.py --mode temp

• 指定位置（用户提供了路径或文件名）：

python3 {baseDir}/scripts/take_screenshot.py --path output/screen.png

• 按应用名称捕获应用/窗口（仅限 macOS；可以进行子字符串匹配；捕获所有匹配的窗口）：

python3 {baseDir}/scripts/take_screenshot.py --app "the agent"

• 捕获应用内标题匹配的特定窗口（仅限 macOS）：

python3 {baseDir}/scripts/take_screenshot.py --app "the agent" --window-name "Settings"

• 捕获前列出匹配的窗口 ID（仅限 macOS）：

python3 {baseDir}/scripts/take_screenshot.py --list-windows --app "the agent"

• 像素区域（x,y,w,h）：

python3 {baseDir}/scripts/take_screenshot.py --mode temp --region 100,200,800,600

• 当前焦点/活动窗口（仅捕获最前面的窗口；使用 --app 可捕获所有窗口）：

python3 {baseDir}/scripts/take_screenshot.py --mode temp --active-window

• 特定窗口 ID（在 macOS 上使用 --list-windows 查找 ID）：

python3 {baseDir}/scripts/take_screenshot.py --window-id 12345

脚本会为每次捕获输出一个路径。如果匹配到多个窗口或显示器，它会输出多个路径（每行一个），并添加类似 -w<windowId> 或 -d<display> 的后缀。使用图像查看工具依次查看每个路径；仅在需要或用户要求时才处理图像。

工作流示例

• “看看 ，告诉我你看到了什么”：捕获到临时目录，然后按顺序查看输出的每个路径。

bash {baseDir}/scripts/ensure_macos_permissions.sh && \
python3 {baseDir}/scripts/take_screenshot.py --app "<App>" --mode temp

• “Figma 中的设计与实现不一致”：先使用 Figma MCP/skill 捕获设计，再使用此 skill 捕获正在运行的应用（通常保存到临时目录），并在进行任何处理前比较原始截图。

多显示器行为

• 在 macOS 上，连接多台显示器时，全屏捕获会为每台显示器分别保存一个文件。
• 在 Linux 和 Windows 上，全屏捕获使用虚拟桌面（将所有显示器合并为一张图）；需要时使用 --region 隔离单台显示器。

Linux 前置条件和选择逻辑

辅助程序会自动选择第一个可用工具：

1. scrot
2. gnome-screenshot
3. ImageMagick import

如果这些工具都不可用，请让用户安装其中一个，然后重试。

坐标区域捕获需要 scrot 或 ImageMagick import。

--app、--window-name 和 --list-windows 仅限 macOS。在 Linux 上，请使用 --active-window，或在可用时提供 --window-id。

Windows（PowerShell 辅助程序）

运行 PowerShell 辅助程序：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1

常见用法：

• 默认位置：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1

• 临时位置（Agent 进行视觉检查）：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Mode temp

• 指定路径：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Path "C:\Temp\screen.png"

• 像素区域（x,y,w,h）：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Mode temp -Region 100,200,800,600

• 活动窗口（请先让用户将其置于焦点）：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -Mode temp -ActiveWindow

• 特定窗口句柄（仅在已提供时使用）：

powershell -ExecutionPolicy Bypass -File {baseDir}/scripts/take_screenshot.ps1 -WindowHandle 123456

直接使用操作系统命令（备用方案）

无法运行辅助程序时使用这些命令。

macOS

• 全屏截图并保存到指定路径：

screencapture -x output/screen.png

• 像素区域：

screencapture -x -R100,200,800,600 output/region.png

• 指定窗口 ID：

screencapture -x -l12345 output/window.png

• 交互式选择或选择窗口：

screencapture -x -i output/interactive.png

Linux

• 全屏：

scrot output/screen.png

gnome-screenshot -f output/screen.png

import -window root output/screen.png

• 像素区域：

scrot -a 100,200,800,600 output/region.png

import -window root -crop 800x600+100+200 output/region.png

• 活动窗口：

scrot -u output/window.png

gnome-screenshot -w -f output/window.png

错误处理

• 在 macOS 上，先运行 bash {baseDir}/scripts/ensure_macos_permissions.sh，以便集中请求屏幕录制权限。
• 如果在沙盒运行中看到“screen capture checks are blocked in the sandbox”“could not create image from display”或 Swift ModuleCache 权限错误，请使用提升的权限重新运行命令。
• 如果 macOS 应用/窗口截图没有匹配结果，请运行 --list-windows --app "AppName" 并使用 --window-id 重试，同时确保应用在屏幕上可见。
• 如果 Linux 区域/窗口截图失败，请使用 command -v scrot、command -v gnome-screenshot 和 command -v import 检查工具是否可用。
• 如果在沙盒中保存到操作系统默认位置时遇到权限错误，请使用提升的权限重新运行命令。
• 始终在回复中报告保存的文件路径。

适用场景

不适用场景