dsh-desktop-automation

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