全部技能 / 文档与知识 / capture-screen
文档与知识 · 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.

风险提醒：蓝色 · 知晓即可AI 侦查报告
作者 daymadeGitHub daymade/claude-code-skills ↗Stars 1385许可 MIT（仓库根 LICENSE，Copyright (c) 2025 daymade；GitHub API spdx MIT）commit d5c4678cb5
agent 宿主通常会约束 skill 执行权限；风险提醒为 AI 侦查观点，不构成质量或安全保证。第三方 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外部依赖

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

4风险提醒 风险提醒：蓝色 · 知晓即可

风险提醒：蓝色 · 知晓即可
  • 截屏内容敏感：像素级副本可能含密码/私人文档 — screencapture 捕获的是真实屏幕像素；产物文件落本地且可能进入模型上下文。涉及敏感窗口时需宿主权限纪律与文件清理。
  • AppleScript/System Events 是本地 UI 控制面 — osascript 可激活/操作任意 app，System Events 键盘模拟 fallback 可向 app 发送按键；这是宿主 shell 授权内的本地能力，恶意输入（app 名来自不可信源）需宿主命令注入防护。
  • TCC 授权是硬前置且授权对象常是 helper 进程 — 无 Screen Recording 授权则枚举失败；授权显示名可能是 swift/Terminal 而非目标 app，用户可能误授权/找不到条目（脚本已提供 hint 缓解）。
  • WID 会失效、UI 时序敏感 — app 重启/窗口重建后 CGWindowID 失效需重取；osascript 可能挂死（须 timeout）；UI 动画未完成时截图会错位（须 sleep）。属可靠性注意项。
风险提醒：蓝色，知晓即可。纯本地 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 权限的受限环境。
    安装 agent 直装可复制
    ① 本站镜像 更新 2026-09-09
    方式 A · 人下载镜像包下载 capture-screen.tar.gz
    sha256: fb587255b81bdc81…
    方式 B · JSON 格式安装指南，复制给 agent
    安装指南
    agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
    ② 上游 GitHub · 原始来源
    能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗
    本页镜像锁定 commit d5c4678cb5；上游为实时仓库。
    来源信息 GitHub 原始
    作者 / 仓库daymade / daymade/claude-code-skills
    原始 GitHubdaymade/claude-code-skills ↗
    Stars1385
    最近推送2026-09-09
    本 skill commitd5c4678cb5
    许可MIT（仓库根 LICENSE，Copyright (c) 2025 daymade；GitHub API spdx MIT）
    本站信息
    收录日期2026-09-06
    分类文档与知识
    侦查报告2026-09-06 · 2 遍
    本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。