dsh-desktop-automation

Readme

# dsh-desktop-automation

macOS 桌面自动化 dsh 插件：让 dsh 的 agent 能直接控制桌面——鼠标/键盘/滚动/应用/窗口/截图，并整合**视觉闭环**（截图 → 识图 → 定位 → 点击 → 验证）。

> **主模型多模态/纯文本均可使用**：截图走系统 `screencapture`（屏幕录制已授权）；识图/定位复用 dsh 视觉凭据（`OPENCODE_GO_API_KEY`），与 [dsh-autovision](https://github.com/Junkrat9527/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）

```bash
# 方式一：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