截图热键工具（WbShot）
这个 skill 是什么
一套不依赖第三方软件的全局热键截图工具，支持两个平台：
| 平台 | 热键 | 实现 |
|---|---|---|
| Windows 10/11 | Alt+A 框选 / Ctrl+Alt+F 全屏 |
PowerShell + WinForms 自绘遮罩，自带热键监听 |
| macOS | ⌥A 框选 / ⌥F 全屏（由系统快捷键绑定） |
系统自带 screencapture，无自绘界面 |
两边行为一致：截图进剪贴板；只有前台（截图时焦点所在的程序）是 WorkBuddy / 豆包时才自动贴进输入框；
前台是别的程序时图留在剪贴板，右下角弹一条「截图已复制到剪贴板」提示，切回对话框手动 Ctrl+V 即可。
绝不会把别的窗口拉到前台，也绝不会把图贴进错误的应用。
安装后（不传热键参数）会自动弹出「设置截图快捷键」窗口，用户自己按键录入；
要退回「自动把目标程序拉到前台再贴」的旧行为，安装时加 -ActivateTarget。
关键点：不要修改 WorkBuddy 的 app.asar。 客户端有完整性校验，改过会打不开并触发自愈还原（本项目早期踩过这个坑）。截图必须走外部热键。
何时使用
| 用户意图 | 动作 |
|---|---|
| "帮我装个截图工具" / "热键截图" | 按当前平台执行安装 |
| "帮我截个图 / 截个屏幕看看" | 用 shot.ps1 / shot.sh 截一张，读图回答 |
| "热键不灵 / 改成 XX 键" | 重装并换热键参数 |
| "不想要了" | 执行卸载 |
先判断平台
uname -s # Darwin = macOS；Linux 等其它结果都不支持
- Windows →
scripts/win/（全部.ps1） - macOS →
scripts/mac/（全部.sh） - 鸿蒙 / iOS / Android → 明确告诉用户不支持，原因见文末「不支持的平台」，不要尝试安装
Windows 安装
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<skill>/scripts/win/install.ps1" -AreaHotkey "Alt+A" -FullHotkey "Ctrl+Alt+F"
不给 agent 用、纯手动的场合，解压后在本目录执行 powershell -NoProfile -ExecutionPolicy Bypass -File scripts\win\install.ps1 即可；
分享版包里还有个 install.cmd，双击就装（上架版没有，因为技能市场禁止 .cmd）。
可选参数：
| 参数 | 说明 | 默认 |
|---|---|---|
-TargetDir |
安装目录 | %LOCALAPPDATA%\WbShot |
-AreaHotkey |
框选热键，如 Alt+A、Ctrl+Alt+S、F9 |
Alt+A |
-FullHotkey |
全屏热键 | Ctrl+Alt+F |
-PasteTargets |
允许自动粘贴的进程名，逗号分隔通配符 | WorkBuddy*,Doubao* |
-ActivateTarget |
前台不是目标时，把目标程序拉到前台再贴（默认关：图留剪贴板） | 关 |
-NoAutostart |
不写开机自启 | 否（默认写） |
-NoSetupPrompt |
装完不弹快捷键设置窗口 | 否（默认弹） |
快捷键设置窗口：安装成功后会自动弹出（除非命令行传了 -AreaHotkey 或 -NoSetupPrompt），
用户点击输入框后直接按组合键即可录入，保存时自动重启监听并验证；热键被占用会当场提示换键。
以后想改键：双击安装目录或开始菜单里的 设置快捷键，或运行
powershell -NoProfile -STA -ExecutionPolicy Bypass -File "<安装目录>\hotkey-ui.ps1"。
纯命令行改键用 apply-hotkey.ps1 -Root "<安装目录>" -AreaHotkey "Alt+X"（改完立即生效，自启同步更新）。
agent 注意：为用户安装时不要传 -AreaHotkey，让设置窗口弹出来，由用户自己挑键；
无人值守/自动化场景才传 -AreaHotkey 或 -NoSetupPrompt。
安装器会：复制脚本 → 写 settings.json → 生成隐藏启动器 start-listener.vbs → 停掉旧监听 → 写 Startup 自启 → 起监听 → 读日志确认热键注册 → 弹出设置窗口 → 创建「设置快捷键」快捷方式。
退出码：0 成功；2 热键被别的程序占用（换键重装）；3 监听没起来（查 logs/hotkey.log）。
安装后必须把日志里的 register MAIN(...)=True 报给用户，作为"确实生效"的证据。
macOS 安装
bash "<skill>/scripts/mac/install.sh" # 加 --skhd 则顺带写 skhd 配置
装完还需要用户做两件事（脚本会把步骤打印出来）：
- 授权：系统设置 → 隐私与安全性 → 给宿主程序（Terminal / WorkBuddy / 豆包）勾上 屏幕录制；要用自动粘贴再加 辅助功能。不授权会截出黑图或按键发不出去。
- 绑热键：macOS 不给第三方脚本注册全局热键，所以走系统这一层——
Automator 新建「快速操作」→ 拖入「运行 Shell 脚本」→ 粘贴"$HOME/bin/wbshot" -m area -p→ 存成WbShot Capture→ 系统设置 → 键盘 → 快捷键 → 服务 里分配⌥A。
装了 skhd 的话可以全自动：install.sh --skhd 会写 ~/.config/skhd/wbshot.skhd 并挂进 skhdrc。
自动粘贴同样只认前台：目标 App 正在最前才 ⌘V，否则图留在剪贴板；加 -A 可改成
「激活目标 App 再贴」（和 Windows 的 -ActivateTarget 对应）。
macOS 版没有在真机上验证过（开发机是 Windows）。逻辑按 Apple 官方 API 写的，但权限相关的边界行为（尤其是首次授权前后的报错）只能实机确认。遇到问题先看 references/troubleshooting.md 的 macOS 一节。
让 agent 自己截图
用户说"看看我屏幕上是什么""帮我看看这个报错"时，agent 应当自己截，不要让用户手动截图再上传。
Windows
powershell.exe -NoProfile -STA -ExecutionPolicy Bypass -File "<skill>/scripts/win/shot.ps1" -Mode full -SaveTo "D:\tmp\shot.png" -NoPaste
macOS
bash "<skill>/scripts/mac/shot.sh" -m full -q -o /tmp/shot.png # 默认不粘贴
参数对照：
| 用途 | Windows | macOS |
|---|---|---|
| 框选（等用户拖） | -Mode area |
-m area |
| 整屏 | -Mode full |
-m full |
| 当前窗口 | -Mode window |
-m window（点击选择） |
| 存 PNG | -SaveTo <路径> |
-o <路径> |
| 不自动粘贴 | -NoPaste |
macOS 默认就不粘，加 -p 才粘 |
两边都输出一行 RESULT ok mode=... file=... bytes=...；用户取消或没授权时是 RESULT no-image ...。
拿到 PNG 之后怎么"看"
按 agent 自身能力依次尝试，成功一种就停：
- 直接读图：有看图能力的 agent 直接打开返回的 PNG。
- 作为附件引用：把 PNG 路径作为图片附件带上（部分客户端支持
file://或本地路径）。 - 降级：读不了图的 agent 就别硬来——重跑一次并允许自动粘贴，让图进输入框，然后告诉用户"图已贴进输入框，请发送"。不要谎称自己看到了画面。
在其他 AI 客户端里用（豆包 / 通义 / 元宝等）
截图本身与客户端无关，差别只在「自动粘贴」这一环：
- 白名单默认
WorkBuddy*,Doubao*（macOS 侧是应用名，默认WorkBuddy,Doubao,豆包）。 - 想在别的客户端也自动贴：Windows 查进程名（
tasklist | findstr /i 名字）后用-PasteTargets重装；macOS 设环境变量WBSHOT_TARGETS="WorkBuddy,Doubao,通义"。 - 自动粘贴只发生在「前台就是白名单程序」时；不是就留在剪贴板（Windows 会弹提示）。
agent 用shot.ps1/shot.sh -p -A走的是带激活的老路径，方便把图塞进目标输入框。
豆包的两个注意点：
- 任务必须选本地电脑执行；云电脑没有图形界面，热键和截屏全部无效。
- 技能入口在「插件 · 技能 · 伙伴 → 技能 → + 添加 → 上传技能」，直接传 zip（不解压也行），它读的就是这份
SKILL.md。
卸载
Windows
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<skill>/scripts/win/uninstall.ps1"
停进程、删自启、删文件；加 -KeepFiles 只停服务不删文件。
macOS
bash "<skill>/scripts/mac/uninstall.sh" # --keep 只列出将删的东西
Automator 里手动建的快速操作不会自动删，需要用户自己移除。
文件说明
| 文件 | 作用 |
|---|---|
scripts/win/capture.ps1 |
截图核心：DPI aware、遮罩框选、写剪贴板、可选存 PNG、可选自动粘贴 |
scripts/win/hotkey.ps1 |
常驻热键监听（内联 C# 调 RegisterHotKey），支持任意 修饰键+键 |
scripts/win/install.ps1 |
安装/升级，含热键占用检测；装完弹快捷键设置窗口 |
scripts/win/apply-hotkey.ps1 |
改热键：重写启动器 → 重启监听 → 验证，改完立即生效 |
scripts/win/hotkey-ui.ps1 |
「设置截图快捷键」窗口：点击输入框直接按组合键录入 |
scripts/win/shot.ps1 |
一次性截图，供 agent 调用 |
scripts/win/uninstall.ps1 |
卸载 |
scripts/mac/shot.sh |
macOS 截图核心：调用系统 screencapture，处理权限与剪贴板 |
scripts/mac/install.sh |
macOS 安装：装到 ~/Library/Application Support/WbShot，建 ~/bin/wbshot 包装器 |
scripts/mac/uninstall.sh |
macOS 卸载 |
install.sh |
平台分派入口（macOS 直接跑，Windows 打印指引） |
references/troubleshooting.md |
热键不灵、截图偏移、开机不启动、mac 权限等排查 |
已知限制
- Windows：多显示器遮罩覆盖整个虚拟屏，可跨屏框选；200% 缩放已做 DPI 感知，截图是物理像素；每按一次热键起一个 PowerShell 进程（约 100ms），常驻的只有监听进程。
- macOS：框选界面是系统自带的，外观与 Windows 版不同；
window模式需要点击选窗口；热键依赖系统「服务」绑定，不能由脚本直接注册；首次授权必须用户手动点。 .ps1必须是纯 ASCII（PowerShell 5.1 按 GBK 解析 UTF-8 无 BOM 会炸）；.sh没这个限制。- 每次改脚本后都要重新同步到用户技能目录，否则跑的还是旧代码。
不支持的平台
- 鸿蒙（含鸿蒙 PC）：纯应用模型（ArkTS/ArkUI），第三方应用没有全局热键与任意脚本执行能力，做不了。要这功能只能系统级实现。
- iOS / Android：沙箱限制，同理不支持。
