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 树的软件也能点——截图交给视觉模型拿坐标，直接点

能力

注册 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    → 再截图识别，验证操作结果

架构

dsh (agent) → 插件 index.js (desktop_* 工具) → 本地 socket → 常驻 CGEvent 服务
                                                              ↑ GUI 会话按需拉起（非开机自启）

• 真正的 CGEvent 由 Swift 服务 desktop-control-server 发出。
• 服务是 GUI 会话进程才有辅助功能权限（macOS TCC 判「责任进程」），由插件在需要时 launchctl bootstrap gui/$UID 按需拉起，不设登录自启。
• 配套技能文档：~/.agents/skills/desktop-automation/SKILL.md。

安装

# 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

授权要求（一次性）

• 服务二进制 desktop-control-server 需辅助功能授权（系统设置 → 隐私与安全性 → 辅助功能）。
• 屏幕录制默认已授权（screencapture 系统命令）。
• ⚠️ 授权后不要重新编译 server（ad-hoc 签名 CDHash 变化会失效）。

License

MIT