首页 / 全部技能 / 文档与知识 / capture-screen
English (EN)简体中文 (ZH)日本語 (JA)
文档与知识 · daymade/claude-code-skills

capture-screen

Programmatic screenshot capture on macOS. Find window IDs with Swift CGWindowListCopyWindowInfo, control application windows via AppleScript (zoom, scroll, select), and capture with screencapture. Use when automating screenshots, capturing application windows for documentation, or building multi-shot visual workflows.

L4 高权限 · 分级授权与审计V1 已固定执行命令读写文件Dual-pass Audit
Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE，Copyright (c) 2025 daymade；GitHub API spdx MIT）Commit d5c4678cb5
管控等级描述 skill 的能力与建议配套的管控措施，不代表质量或安全认证，也不表示可用或不可用。是否使用由用户和管理者决定。不同 agent 宿主对权限的约束各不相同，请勿假定宿主一定会提供安全兜底。第三方 skill 版权归原作者，使用风险由使用者自行承担。

1实现原理 · 为什么它能做到

三步工作流全部落在 macOS 原生工具上：Swift+CoreGraphics 列窗口拿 WID → AppleScript/osascript 控制视图 → screencapture -l <WID> 精确截图。

daymade-macos/capture-screen/SKILL.md
1. Find Window → Swift CGWindowListCopyWindowInfo → get numeric Window ID 2. Control View → AppleScript (osascript) → zoom, scroll, select 3. Capture → screencapture -l <WID> → PNG/JPEG output
没有自研截图引擎，全链路复用 macOS 系统能力：screencapture 是系统自带截屏 CLI，osascript 是系统 AppleScript 解释器，Swift 脚本只做窗口枚举。

找窗口用 Swift 脚本 get_window_id.swift 调 CoreGraphics CGWindowListCopyWindowInfo(.optionOnScreenOnly)，按 app 名/标题关键词过滤输出 WID=… | App=… | Title=…。

daymade-macos/capture-screen/scripts/get_window_id.swift
CGWindowListCopyWindowInfo( .optionOnScreenOnly, kCGNullWindowID ) as? [[String: Any]] else {
SKILL.md 声明这是 macOS 上唯一可靠方法（System Events 的 id of window 不是 screencapture 需要的 CGWindowID；PyObjC Quartz 又常因未安装而失败——见 'Failed Approaches (DO NOT USE)' 表）。

控制视图层：Excel 有完整 AppleScript 字典支持（激活、缩放 zoom、滚动行/列、选 range、切 sheet、开文件），任意 app 走基础 activate / System Events AXRaise，受限 app 退回键盘模拟。

daymade-macos/capture-screen/SKILL.md
osascript -e 'tell application "Microsoft Excel" set scroll row of active window to 45 end tell'
文档按『支持的应用程序』表区分控制深度：Excel 最全、Chrome 基础、其余通用 activate + screencapture 一定可用；AppleScript 可能挂死 → 一律建议 timeout 包裹。

截图层：screencapture -l <WID> 精确捕获指定窗口（-x 静音、-t jpg、-T 延迟、-R 区域），Retina 2x 输出用 sips 缩回 1x。

daymade-macos/capture-screen/SKILL.md
# Silent capture (no camera shutter sound) screencapture -x -l <WID> output.png
物理工作流示例：多段滚动截长表（每次滚动后 sleep 1 再截，WID 需在 app 重启/窗口重开后重新获取——CGWindowID 会失效）。

权限三连排查模板：Screen Recording 是必须授权；helper binary（swift/python/terminal）与打包 .app 的 TCC 授权身份不同，脚本提供 --permission-hint screen/microphone 打印排查指引。

daymade-macos/capture-screen/SKILL.md
`swift scripts/get_window_id.swift` reads on-screen windows via CoreGraphics, so it needs Screen Recording permission on macOS.
get_window_id.swift 内 printPermissionContextHint() 会枚举 invoker/runtime/script 候选身份并提示『In most cases the entry shown in TCC is the helper process』；这是把一次真实权限排障经验模板化成可复用 triage。

文档化失败路线（DO NOT USE）：System Events id of window（-1728）、Python PyObjC Quartz（ModuleNotFoundError）、osascript window id（格式不对）——防止执行模型重复踩坑。

daymade-macos/capture-screen/SKILL.md
| `System Events` → `id of window` | Error -1728 | System Events cannot access window IDs in the format screencapture needs |
这类『已验证不可行』清单是本 skill 的特色：它把试错成本前置写死，让模型直接走通路径。

2核心能力

01枚举全部/按关键词过滤屏幕上的窗口并输出 CGWindowID（WID=12345 | App=… | Title=…）
02AppleScript 精确控制 Excel 视图：zoom / scroll row/column / select range / 切 sheet / 打开文件
03任意 app activate / 按索引 AXRaise 置顶（System Events）
04按 WID 窗口截图（PNG/JPEG、静音、延时、区域截图）
05Retina 2x→1x 缩放（sips）与截图像素校验（ls/file）
06多段截屏工作流：滚动分页截长表/多 sheet（sleep 同步 + WID 重取纪律）
07权限 triage：--permission-hint screen|microphone 打印 Settings 路径与身份排查清单

3外部依赖

KindDependency / Endpoint
cliswift（运行 get_window_id.swift 或 -e 内联执行 CoreGraphics 枚举）
cliscreencapture（macOS 系统自带，窗口/区域截图）
cliosascript / System Events（AppleScript 控制 app 窗口）
clisips / ls / file / timeout（可选缩放与校验、超时保护）

4管控建议与判定依据

建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
  • scripts/: 执行本地脚本或命令: swift scripts/get_window_id.swift（或 swift -e 内联枚举窗口）
  • 本地工作目录: 文件读写与工件输出: 截图输出文件（output.png/output.jpg 等，由调用者指定路径）
审计说明： 。纯本地 macOS 工具链：运行系统自带 swift/screencapture/osascript/sips，无网络外发、无凭证读取、无第三方依赖；写本地图片文件。注意点：需要 Screen Recording 隐私授权，截屏内容与窗口标题属敏感本地数据（无外发面），System Events 键盘模拟可操作任意 app——全部在宿主本地权限边界内。

5第二遍独立确认

  • [ok] Swift 脚本只做窗口枚举（无隐藏行为） — get_window_id.swift 逻辑 = 参数解析 + CGWindowListCopyWindowInfo(.optionOnScreenOnly) + 过滤打印 + 权限提示文本；无文件写/网络/进程执行调用。
  • [ok] 三步工作流与 description 声明一致 — Find Window/Control View/Capture 三步概览代码块、Step1-3 正文、Quick Start 命令逐字对应；Excel 控制命令含 zoom/scroll/select/sheet。
  • [ok] screencapture -l 兼容 CGWindowID 的说法有失败表佐证 — Failed Approaches 表记录 System Events id of window 报 -1728 等三个失败路径，反向支持『Swift 枚举 + screencapture -l』为主路径。
  • [ok] 无网络/无凭证（安全结论基础） — 全目录 token 扫描零网络/凭证命中；依赖全部是 macOS 系统自带 CLI。
  • [ok] TCC/Screen Recording 依赖表述准确 — SKILL.md Permission Troubleshooting 与脚本 --permission-hint 均明示 Screen Recording 为前置条件，并处理 helper binary 身份问题。
  • [ok] 元数据（commit/license/stars） — 本地 HEAD == pin d5c4678cb5d4fd6acc9c922690df035dbd33d247；GitHub API：MIT、stars 1385（2026-09-09 实采）、pushed_at 2026-09-09T12:33:29Z。

6结论

  • 直接可用且零依赖：全链路 macOS 系统工具，无 pip/npm/编译步骤，复制命令即可跑。
  • 把踩坑结论文档化：Failed Approaches 表与权限 triage 模板让执行模型不走弯路。
  • Excel 场景打磨深：zoom/scroll/select/切 sheet 的完整多段截图示例可直接用于报表/模型文档自动化。
  • 权限问题有系统性解法：helper-binary vs .app 的 TCC 身份差异被识别并模板化。
    • 适合： 适合 macOS 上需要程序化截图的场景：Excel 财务模型/报表分段截图做文档、Chrome 等 app 窗口截图、构建多截图视觉工作流、需要按窗口（而非全屏）精确取图的自动化。对做产品文档、财务模型存档、UI 验证的开发者与分析师最有用。
    不适合： 不适合非 macOS 平台；不适合不需要窗口控制、只想整屏/区域随手截图的人（直接 screencapture 即可，无需此 skill）；不适合需要跨平台截图方案或应用内像素级内容（如密码管理器遮挡内容）的场景；不适合无法授予 Screen Recording 权限的受限环境。
    Install Agent-Ready
    ① Verified Mirror 2026-09-09
    Option A · Direct DownloadDownload capture-screen.tar.gz
    sha256: fb587255b81bdc81…
    Option B · Copy Guide for Agent
    install.json
    agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit d5c4678cb5.