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外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | swift（运行 get_window_id.swift 或 -e 内联执行 CoreGraphics 枚举） |
| cli | screencapture（macOS 系统自带，窗口/区域截图） |
| cli | osascript / System Events（AppleScript 控制 app 窗口） |
| cli | sips / 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 上需要程序化截图的场景：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:
Option B · Copy Guide for Agentfb587255b81bdc81…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.