screenshot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Screenshot Capture

截图捕获

Follow these save-location rules every time:

If the user specifies a path, save there.
If the user asks for a screenshot without a path, save to the OS default screenshot location.
If Codex needs a screenshot for its own inspection, save to the temp directory.

请始终遵循以下保存位置规则：

如果用户指定路径，保存到该路径。
如果用户要求截图但未指定路径，保存到操作系统默认截图位置。
如果Codex需要截图用于自身检查，保存到临时目录。

Tool priority

工具优先级

Prefer tool-specific screenshot capabilities when available (for example: a Figma MCP/skill for Figma files, or Playwright/agent-browser tools for browsers and Electron apps).
Use this skill when explicitly asked, for whole-system desktop captures, or when a tool-specific capture cannot get what you need.
Otherwise, treat this skill as the default for desktop apps without a better-integrated capture tool.

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

macOS permission preflight (reduce repeated prompts)

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

On macOS, run the preflight helper once before window/app capture. It checks Screen Recording permission, explains why it is needed, and requests it in one place.

The helpers route Swift's module cache to

$TMPDIR/codex-swift-module-cache

to avoid extra sandbox module-cache prompts.

bash

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

To avoid multiple sandbox approval prompts, combine preflight + capture in one command when possible:

bash

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

For Codex inspection runs, keep the output in temp:

bash

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

Use the bundled scripts to avoid re-deriving OS-specific commands.

在macOS上，进行窗口/应用截图前先运行一次预检助手。它会检查屏幕录制权限，解释权限需求，并在统一位置请求权限。

助手会将Swift的模块缓存路由到

$TMPDIR/codex-swift-module-cache

，以避免额外的沙箱模块缓存提示。

bash

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

为避免多次沙箱授权提示，尽可能将预检和截图合并为一个命令：

bash

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

对于Codex检查运行，将输出保存到临时目录：

bash

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

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

macOS and Linux (Python helper)

macOS和Linux（Python助手）

Run the helper from the repo root:

bash

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

Common patterns:

Default location (user asked for "a screenshot"):

bash

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

Temp location (Codex visual check):

bash

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

Explicit location (user provided a path or filename):

bash

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

App/window capture by app name (macOS only; substring match is OK; captures all matching windows):

bash

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

Specific window title within an app (macOS only):

bash

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

List matching window ids before capturing (macOS only):

bash

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

Pixel region (x,y,w,h):

bash

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

Focused/active window (captures only the frontmost window; use
```
--app
```
to capture all windows):

bash

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

Specific window id (use --list-windows on macOS to discover ids):

bash

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

The script prints one path per capture. When multiple windows or displays match, it prints multiple paths (one per line) and adds suffixes like

-w<windowId>

-d<display>

. View each path sequentially with the image viewer tool, and only manipulate images if needed or requested.

从仓库根目录运行助手：

bash

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

常见用法：

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

bash

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

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

bash

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

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

bash

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

按应用名称捕获应用/窗口（仅macOS支持；支持子字符串匹配；捕获所有匹配窗口）：

bash

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

捕获应用内特定标题的窗口（仅macOS支持）：

bash

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

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

bash

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

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

bash

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

聚焦/活动窗口（仅捕获最前端窗口；使用
```
--app
```
捕获所有窗口）：

bash

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

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

bash

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

脚本每次捕获会输出一个路径。当有多个窗口或显示器匹配时，会输出多个路径（每行一个），并添加

-w<windowId>

或

-d<display>

等后缀。使用图片查看工具依次查看每个路径，仅在需要或用户要求时处理图片。

Workflow examples

工作流示例

"Take a look at <App> and tell me what you see": capture to temp, then view each printed path in order.

bash

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

"The design from Figma is not matching what is implemented": use a Figma MCP/skill to capture the design first, then capture the running app with this skill (typically to temp) and compare the raw screenshots before any manipulation.

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

bash

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捕获运行中的应用（通常保存到临时目录），在进行任何处理前对比原始截图。

Multi-display behavior

多显示器行为

On macOS, full-screen captures save one file per display when multiple monitors are connected.
On Linux and Windows, full-screen captures use the virtual desktop (all monitors in one image); use
```
--region
```
to isolate a single display when needed.

在macOS上，当连接多个显示器时，全屏截图会为每个显示器保存一个文件。
在Linux和Windows上，全屏截图使用虚拟桌面（所有显示器合并为一张图片）；必要时使用
```
--region
```
隔离单个显示器。

Linux prerequisites and selection logic

Linux前置条件和选择逻辑

The helper automatically selects the first available tool:

```
scrot
```
```
gnome-screenshot
```
ImageMagick
```
import
```

If none are available, ask the user to install one of them and retry.

Coordinate regions require

scrot

or ImageMagick

import

--app

--window-name

, and

--list-windows

are macOS-only. On Linux, use

--active-window

or provide

--window-id

when available.

助手会自动选择第一个可用工具：

```
scrot
```
```
gnome-screenshot
```
ImageMagick
```
import
```

如果没有可用工具，请要求用户安装其中一个并重试。

坐标区域捕获需要

scrot

或ImageMagick

import

。

--app

、

--window-name

和

--list-windows

是macOS专属功能。在Linux上，使用

--active-window

或在可用时提供

--window-id

。

Windows (PowerShell helper)

Windows（PowerShell助手）

Run the PowerShell helper:

powershell

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

Common patterns:

Default location:

powershell

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

Temp location (Codex visual check):

powershell

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

Explicit path:

powershell

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

Pixel region (x,y,w,h):

powershell

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

Active window (ask the user to focus it first):

powershell

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

Specific window handle (only when provided):

powershell

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

运行PowerShell助手：

powershell

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

常见用法：

默认位置：

powershell

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

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

powershell

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

明确指定路径：

powershell

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

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

powershell

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

活动窗口（请用户先聚焦该窗口）：

powershell

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

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

powershell

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

Direct OS commands (fallbacks)

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

Use these when you cannot run the helpers.

当无法运行助手时使用这些命令。

macOS

Full screen to a specific path:

bash

screencapture -x output/screen.png

Pixel region:

bash

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

Specific window id:

bash

screencapture -x -l12345 output/window.png

Interactive selection or window pick:

bash

screencapture -x -i output/interactive.png

全屏截图到指定路径：

bash

screencapture -x output/screen.png

像素区域截图：

bash

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

特定窗口ID截图：

bash

screencapture -x -l12345 output/window.png

交互式选择或窗口选择：

bash

screencapture -x -i output/interactive.png

Linux

Full screen:

bash

scrot output/screen.png

bash

gnome-screenshot -f output/screen.png

bash

import -window root output/screen.png

Pixel region:

bash

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

bash

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

Active window:

bash

scrot -u output/window.png

bash

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

全屏截图：

bash

scrot output/screen.png

bash

gnome-screenshot -f output/screen.png

bash

import -window root output/screen.png

像素区域截图：

bash

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

bash

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

活动窗口截图：

bash

scrot -u output/window.png

bash

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

Error handling

错误处理

On macOS, run
```
bash <path-to-skill>/scripts/ensure_macos_permissions.sh
```
first to request Screen Recording in one place.
If you see "screen capture checks are blocked in the sandbox", "could not create image from display", or Swift
```
ModuleCache
```
permission errors in a sandboxed run, rerun the command with escalated permissions.
If macOS app/window capture returns no matches, run
```
--list-windows --app "AppName"
```
and retry with
```
--window-id
```
, and make sure the app is visible on screen.
If Linux region/window capture fails, check tool availability with
```
command -v scrot
```
,
```
command -v gnome-screenshot
```
, and
```
command -v import
```
.
If saving to the OS default location fails with permission errors in a sandbox, rerun the command with escalated permissions.
Always report the saved file path in the response.

在macOS上，先运行
```
bash <path-to-skill>/scripts/ensure_macos_permissions.sh
```
，在统一位置请求屏幕录制权限。
如果在沙箱运行中看到“沙箱中阻止了屏幕捕获检查”、“无法从显示器创建图像”或Swift
```
ModuleCache
```
权限错误，请使用提升的权限重新运行命令。
如果macOS应用/窗口截图未返回匹配结果，运行
```
--list-windows --app "AppName"
```
，然后使用
```
--window-id
```
重试，并确保应用在屏幕上可见。
如果Linux区域/窗口截图失败，使用
```
command -v scrot
```
、
```
command -v gnome-screenshot
```
和
```
command -v import
```
检查工具可用性。
如果在沙箱中保存到操作系统默认位置时出现权限错误，请使用提升的权限重新运行命令。
始终在响应中报告保存的文件路径。