screenshot

截图

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

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

工具优先级

• 如有可用的工具专用截图功能，请优先使用（例如：用于 Figma 文件的 Figma MCP/skill，或用于浏览器和 Electron 应用的 Playwright/agent-browser 工具）。
• 仅在用户明确要求、需要截取整个系统桌面，或工具专用截图功能无法满足需求时使用此 skill。
• 其他情况下，对于没有更好集成截图工具的桌面应用，请将此 skill 作为默认选项。

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

在 macOS 上截取窗口/应用前，先运行一次预检辅助程序。它会检查屏幕录制权限，说明需要该权限的原因，并在同一处请求授权。

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

bash <path-to-skill>/scripts/ensure_macos_permissions.sh

为避免多次沙盒授权提示，尽可能在一条命令中结合预检和截图：

bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex"

对于 Codex 检查任务，请将输出保存在临时目录中：

bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
python3 <path-to-skill>/scripts/take_screenshot.py --app "<App>" --mode temp

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

macOS 和 Linux（Python 辅助程序）

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

python3 <path-to-skill>/scripts/take_screenshot.py

常见用法：

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

python3 <path-to-skill>/scripts/take_screenshot.py

• 临时位置（Codex 视觉检查）：

python3 <path-to-skill>/scripts/take_screenshot.py --mode temp

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

python3 <path-to-skill>/scripts/take_screenshot.py --path output/screen.png

• 按应用名称截取应用/窗口（仅限 macOS；支持子字符串匹配；截取所有匹配的窗口）：

python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex"

• 截取应用内标题特定的窗口（仅限 macOS）：

python3 <path-to-skill>/scripts/take_screenshot.py --app "Codex" --window-name "Settings"

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

python3 <path-to-skill>/scripts/take_screenshot.py --list-windows --app "Codex"

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

python3 <path-to-skill>/scripts/take_screenshot.py --mode temp --region 100,200,800,600

• 聚焦/活动窗口（仅截取最前方的窗口；使用 --app 截取所有窗口）：

python3 <path-to-skill>/scripts/take_screenshot.py --mode temp --active-window

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

python3 <path-to-skill>/scripts/take_screenshot.py --window-id 12345

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

工作流示例

• “看看 并告诉我你看到了什么”：截图保存到临时目录，然后按打印出的顺序查看每个路径。

bash <path-to-skill>/scripts/ensure_macos_permissions.sh && \
python3 <path-to-skill>/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 <path-to-skill>/scripts/take_screenshot.ps1

常见用法：

• 默认位置：

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1

• 临时位置（Codex 视觉检查）：

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp

• 指定路径：

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Path "C:\Temp\screen.png"

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

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp -Region 100,200,800,600

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

powershell -ExecutionPolicy Bypass -File <path-to-skill>/scripts/take_screenshot.ps1 -Mode temp -ActiveWindow

• 指定窗口句柄（仅限已提供句柄时）：

powershell -ExecutionPolicy Bypass -File <path-to-skill>/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 <path-to-skill>/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 检查工具是否可用。
• 如果在沙盒环境中保存到操作系统默认位置时遇到权限错误，请使用提升的权限重新运行命令。
• 始终在回复中报告保存的文件路径。