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