screenshot

截图

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

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

工具优先级

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

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

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

辅助程序会将 Swift 的模块缓存路径设为 $TMPDIR/letta-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 "Letta Code"

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

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

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

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 "Letta Code"

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

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

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

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

• 像素区域（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

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

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