用途：该技能用于从命令行或脚本驱动 macOS 的 CleanShot X。CleanShot X 只暴露 cleanshot:// URL Scheme 作为自动化接口，没有公开 CLI、AppleScript 字典或 HTTP API；Shortcuts.app 的动作内部也调用同一 Scheme。每个命令的完整参数与版本限制见 references/url-scheme.md，自动化前应先阅读。
主要能力：19 个命令分为七组——截图（capture-area、capture-previous-area、capture-fullscreen、capture-window、self-timer、scrolling-capture、pin）、录屏（record-screen）、OCR（capture-text）、标注（open-annotate、open-from-clipboard）、All-In-One（all-in-one）、桌面图标（toggle/hide/show-desktop-icons）、历史与叠加层与设置（add-quick-access-overlay、open-history、restore-recently-closed、open-settings）。通用参数包括 action=copy|save|annotate|upload|pin（需 4.7+）、x/y/width/height/display 指定区域（多数命令需 4.7+，坐标为点而非 Retina 像素，原点在屏幕左下）、filepath（绝对路径、需 URL 编码，截图命令接受 PNG/JPEG，add-quick-access-overlay 还接受 MP4）。
使用方式：基本原语是 open "cleanshot://…"。示例：open "cleanshot://capture-area?action=annotate"；open "cleanshot://capture-previous-area?action=copy"；open "cleanshot://capture-text?filepath=/Users/me/Desktop/screenshot.png&linebreaks=true"；open "cleanshot://pin?filepath=/Users/me/Desktop/diagram.png"；open "cleanshot://open-settings?tab=recording"。也可用 osascript -e 'open location "cleanshot://capture-fullscreen?action=upload"'。URL 中的空格与用户路径需百分号编码，传给 open 时始终加引号。
限制与注意事项：需要该用户有已登录的 Aqua 图形会话，SSH 下仅当该用户同时本地登录才生效，不能在 launchd Background agent 或登录前运行；CleanShot X 必须已安装并能启动（可用 mdfind "kMDItemCFBundleIdentifier == 'pl.maketheweb.cleanshotx'" 验证）。URL 异步触发、无返回值、无完成信号，open 交接触发即返回 0，需通过配置的保存文件夹（defaults 键为 exportPath，而非 CaptureFolder）或剪贴板确认结果。capture-window 始终是交互式悬停选择，无法按窗口名、PID 或窗口 ID 指定；无人值守截取已知窗口应改用 capture-area 并显式传入 x/y/width/height，且需处理坐标系翻转（cs_y = display_height - top_y - height）。不要用 PyObjC 或 import Quartz，默认 macOS 的 python3 没有该模块；坐标用点，勿将 Retina 像素除以 2，缩放模式下会出错。scrolling-capture 在 4.7+ 需 start=true，完全无人值守加 autoscroll=true；record-screen 不会自行停止，需用户在菜单栏或快捷键停止。首次运行可能弹出 TCC 权限提示（屏幕录制、启用音频时的麦克风），智能体无法自动接受。action 只能单值，不能链式组合。