dsh-desktop-automation
macOS 桌面自动化 dsh 插件：让 dsh 的 agent 能直接控制桌面——鼠标/键盘/滚动/应用/窗口/截图，并整合视觉闭环（截图 → 识图 → 定位 → 点击 → 验证）。
> 主模型多模态/纯文本均可使用：截图走系统 screencapture（屏幕录制已授权）；识图/定位复用 dsh 视觉凭据（OPENCODE_GO_API_KEY），与 dsh-autovision 共用同一套凭据，无需单独配 key。
它解决什么问题（主要功能）
浏览器自动化（playwright 等）只能操作网页；非浏览器的桌面软件——剪辑工具、设计软件、办公套件、系统设置、原生 App——一直够不着。这个插件把「agent 操作 macOS 桌面」补上：agent 像人一样看屏幕、移鼠标、敲键盘。
核心场景：
- 操作非浏览器应用：剪映/PS/Axure/WPS/企业内部原生客户端——「点这里、填这个、导出那个」直接吩咐
- 自动化办公：批量重命名、表单填写、重复性 GUI 操作、跨应用搬运数据
- GUI 测试/验收：对桌面软件跑「截图→操作→再截图验证」的闭环，替代人工点检
- 远程指挥：人在别处，让 dsh 在 Mac 上替你完成桌面操作
- 视觉定位点击：不依赖 accessibility 树的软件也能点——截图交给视觉模型拿坐标，直接点
一句话：给 agent 一双看屏幕的眼睛（desktop_see/desktop_locate）和一双手（desktop_click/type/key/drag/scroll）。
能力
注册 14 个 agent 工具（模型可直接调用）：
| 工具 | 说明 |
|---|---|
desktop_perm | 权限/服务状态自检 |
desktop_apps | 列出运行中应用 |
desktop_win | 列出窗口（含坐标/尺寸） |
desktop_app | 激活应用（需先启动） |
desktop_mouse | 移动鼠标 |
desktop_click | 点击（左/右/次数） |
desktop_drag | 拖拽 |
desktop_scroll | 滚动 |
desktop_key | 按键/组合键 |
desktop_type | 输入文本（中文 OK，Unicode 注入） |
desktop_shot | 全屏/区域截图 |
desktop_see | 识图：描述图片/OCR/UI 元素（复用 dsh 视觉凭据） |
desktop_locate | 视觉定位：输出可交互元素 type/text/box/center 坐标 |
desktop_stop | 停止服务 |
HTTP 路由：/desktop/status /desktop/start /desktop/stop /desktop/check /desktop/authorize（设置卡片用）。
视觉闭环（desktop_see + desktop_locate）
完整 GUI 自动化：「截图 → 看图理解 → 定位坐标 → 点击 → 再截图验证」：
desktop_shot → 截图
desktop_see → 识图（文字/UI/内容描述）
desktop_locate → 拿到元素 center 坐标（type/text/box/center，已换算回原图像素）
desktop_click → 按坐标点击
desktop_see → 再截图识别，验证操作结果desktop_see封装 see-image 识图（默认 kimi-k2.6 / minimax-m3，走 dsh 凭据）desktop_locate封装 see-image--ui模式（minimax-m3 grounding 输出坐标）- 插件启动时检测 dsh-autovision：已接线则复用，未接线给出提示（不重复安装）
架构
dsh (agent) → 插件 index.js (desktop_* 工具) → 本地 socket → 常驻 CGEvent 服务
↑ GUI 会话按需拉起（非开机自启）- 真正的 CGEvent 由 Swift 服务
desktop-control-server发出。 - 服务是 GUI 会话进程才有辅助功能权限（macOS TCC 判「责任进程」），由插件在需要时
launchctl bootstrap gui/$UID按需拉起，不设登录自启（~/Library/LaunchAgents/无此项）。 - 配套技能文档：
~/.agents/skills/desktop-automation/SKILL.md（含 see-image --ui 视觉定位工作流）。
安装（接线到 dsh）
# 方式一：npm 包（发布后可用）
dsh plugin --profile web add dsh-desktop-automation
# 方式二：GitHub 源
dsh plugin --profile web add github:Junkrat9527/dsh-desktop-automation
# 方式三：本地 link（开发）
dsh plugin --profile web add link:/path/to/dsh-desktop-automation或手动：web profile package.json 的 dependencies 加 "dsh-desktop-automation": "link:/path/to/repo"，bundles 追加 "dsh-desktop-automation"，重启 dsh（或用 dsh-double / twin_evolve 蓝绿）。
授权要求（一次性）
- 服务二进制
desktop-control-server需辅助功能授权（系统设置 → 隐私与安全性 → 辅助功能，添加并打开开关）。 - 屏幕录制默认已授权（
screencapture系统命令）。 - ⚠️ 授权后不要重新编译 server（ad-hoc 签名 CDHash 变化会失效）。
排障
curl http://127.0.0.1:3080/desktop/status→{"status":"up","perm":true,"screen":true}表示正常。perm:false：辅助功能未授权 →/desktop/authorize引导。status:"down"：服务未跑 → 调用任意 desktop_* 工具会自动拉起。
常见问题
- desktop_app 找不到应用？
desktop_app只激活已运行的应用；未运行先用open -a "AppName"启动。 - desktop_see/desktop_locate 报识图失败？确认 dsh 已配置视觉凭据（
OPENCODE_GO_API_KEY，dsh 设置 → LLM 供应商），且网络可达。 - desktop_locate 输出无坐标？当前定位模型 minimax-m3 / kimi-k2.6 对复杂截图可能输出不稳定，换更干净的截图（裁剪目标区域）重试。
License
MIT