screenshot

name	screenshot
description	当用户明确要求桌面或系统截图时使用（整个屏幕、特定应用或窗口、或某个像素区域），或者当特定工具的捕获能力不可用、需要操作系统级捕获时使用。

截图捕获

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

1. 如果用户指定了路径，保存到那里。
2. 如果用户要截图但没给路径，保存到操作系统默认截图位置。
3. 如果 Codex 需要截图供自己检查，保存到临时目录。

工具优先级

• 在可用时，优先使用特定工具的截图能力（例如：针对 Figma 文件用 Figma MCP/技能，针对浏览器和 Electron 应用用 Playwright/agent-browser 工具）。
• 当被明确要求、需要整个系统桌面捕获、或特定工具的捕获无法满足需求时，使用本技能。
• 否则，对于没有更好集成捕获工具的桌面应用，把本技能当作默认选择。

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/技能捕获设计稿，然后用本技能捕获正在运行的应用（通常到临时目录），在任何处理之前先对比原始截图。

多显示器行为

• 在 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 检查工具是否可用。
• 如果在沙箱中保存到操作系统默认位置因权限错误失败，用提升的权限重新运行命令。
• 始终在响应中报告已保存的文件路径。