desktop-gui-automation-cua

Readme

# desktop-gui-automation-cua

给 AI agent 用的 **macOS 桌面 GUI computer-use** 技能包：用 [cua-driver](https://github.com/trycua/cua) 驱动任意本机应用（点击 / 输入 / 滚动 / 拖拽 / 截图），自动做 **AX → 像素 → 桌面** 三档降级。对微信 4.x、iPhone 镜像、Blender/canvas 这类 **AX 树为空或极稀疏**的软件尤其有用。

开箱即用的目标：**`git clone` → `install.sh` → 在系统设置授权 → 配一个多模态 key → 就能让它驱动你的桌面**。

> **双形态发布**：本仓库同时提供 **skill 形态**（SKILL.md + scripts，装进各 agent 技能目录）与
> **DSH 插件形态**（`plugin/`，通过 `/cua` 命令挂进 DeepSeek Harness）。二者**共享同一份
> `scripts/` 单一事实源** —— skill 用符号链接、插件用子进程调用，**都不复制脚本**，因此
> 改一次仓库两端立即一致，不会随迭代漂移。见文末「双形态与更新」。

## 特性

- **泛用**：一套脚本驱动任意 app（`computer_use.py`），不绑定具体软件
- **三档自动降级**：AX-token（后台不抢焦点）→ 窗口像素（聊天区/canvas）→ 桌面纯视觉（iPhone 镜像）
- **识图定位**：内置 `vision.py` 走任意 OpenAI 兼容多模态端点，做视觉定位与结果验证
- **App 案例配方**：`send_wechat.py`（微信发消息）、`iphonemirror.py`（iPhone 镜像操控）
- **可移植**：全部脚本只用 Python 标准库；识图端点完全可配置

## 文档

| 文档 | 内容 |
|---|---|
| [docs/overview.md](docs/overview.md) | 原理与设计（AX→像素→桌面三档降级、Skyshot/取证、识图、安全） |
| [docs/app-guides.md](docs/app-guides.md) | App 实操教程（原生 app / 微信 / QQ / iPhone 镜像）+ 排障 |
| [docs/reference.md](docs/reference.md) | 脚本 / API / 依赖 参考 |


## 安装（macOS）

**给 AI agent 的一条指令（给你的 Claude / Codex / DSH agent 说这句，它就能自动装）：**

> 请安装 desktop-gui-automation-cua：`git clone https://github.com/afa-cloud/desktop-gui-automation-cua.git && cd desktop-gui-automation-cua && ./install.sh`。装完告诉我需要我提供多模态 API key、以及在「系统设置 → 隐私与安全性 → 辅助功能 / 屏幕录制」授予 CuaDriver 和本 agent 的权限。

装完只剩两件只能你本人做（脚本无法代办）：**① 在系统设置授予 macOS 权限；② 提供识图 API key**。其余全自动。

**手动安装：**

```bash
git clone https://github.com/afa-cloud/desktop-gui-automation-cua.git
cd desktop-gui-automation-cua
./install.sh            # 也可加 --no-cua / --no-plugin / --force
```

`install.sh` 会：
1. 检测/安装 **cua-driver**（若无）
2. 用**符号链接**把 skill 装进你的 agent 技能目录（自动识别 `~/.dsh/skills`、`~/.claude/skills`、`~/.agents/skills` 等）—— 指向本仓库 `scripts/` 与 `SKILL.md`，**不复制**
3. 检测到 DSH web profile 时，**自动安装 DSH 插件**（symlink `plugin/src/index.js` + 追加 `cordis.patch.yml` insert，幂等）
4. 生成识图配置模板 `~/.config/vision-config.json`
5. 引导授予 macOS 权限

### 装完还剩 2 步（必须手动，无法脚本代做）

**① 授权（macOS TCC，唯一硬门槛）** —— 让驱动能看屏幕、能操控界面：

```bash
cua-driver permissions grant
```

然后打开 **系统设置 → 隐私与安全性 → 辅助功能 / 屏幕录制**，勾选 `CuaDriver` 和你的 agent/终端 App，之后**完全退出并重开该 App** 使授权生效。（验证：`cua-driver permissions status --json` 应输出 `accessibility:true` `screen_recording:true`。）

**② 配一个多模态识图 key**（用于视觉定位/验证）：

```bash
cp ~/.config/vision-config.json ~/.config/vision-config.json.bak
# 编辑 ~/.config/vision-config.json 填你自己的 OpenAI 兼容多模态服务
```

`~/.config/vision-config.json` 内容：
```json
{
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-your-key",
  "model": "gpt-4o"
}
```

> 也可以用环境变量，`base_url` 和 `api_key` **至少提供一个**，建议都给：
> `export VISION_BASE_URL=https://api.openai.com/v1 VISION_API_KEY=sk-... VISION_MODEL=gpt-4o`
>
> 任意 OpenAI 兼容 `/chat/completions` 多模态 endpoint 都行（OpenAI / DeepSeek / SiliconFlow / 本地 vLLM 等）。

### 快速自检

```bash
# 1) 权限
cua-driver permissions status --json
# 2) 识图(配好 key 后应能描述图)
python3 ~/.dsh/skills/desktop-gui-automation-cua/scripts/vision.py 某张图.png "描述一下"
# 3) probe 一个 app
python3 ~/.dsh/skills/desktop-gui-automation-cua/scripts/computer_use.py probe 访达
```

## 使用

见 `scripts/SKILL.md`（完整手册）。常用：

```bash
D=~/.dsh/skills/desktop-gui-automation-cua/scripts
# 泛用驱动任意 app
python3 $D/computer_use.py probe <app>                 # 判定 A/B/C 档
python3 $D/computer_use.py snapshot <app> --out t.png  # AX + 截图
python3 $D/computer_use.py inspect <app> "描述界面"     # 识图
python3 $D/computer_use.py click <app> --token s000..  # AX 点击(后台不抢焦点)
python3 $D/computer_use.py click <app> --x 120 --y 750 # 像素点击(window-local px)
python3 $D/computer_use.py type <app> "你好"            # 文本输入
python3 $D/computer_use.py key <app> Return             # 按键

# App 案例配方
python3 $D/send_wechat.py "某人" "消息"                 # 微信发消息
python3 $D/iphonemirror.py tap "Dock栏的照片"           # iPhone 镜像操控
```

### 工作流（对任意 app）

```
1. 定位   computer_use.py windows <app>        # 找窗口
2. 判定   computer_use.py probe <app>          # AX→像素→桌面 三档
3. 快照   snapshot / inspect                   # 取证
4. 交互   A档 AX / B档像素 / C档桌面(前台)
5. 验证   重新 snapshot / scroll到底 / vision 确认
```

## 平台限制

- **macOS 完全支持**（脚本针对 macOS AX / CGEvent / sips 机制）
- **Windows / Linux**：cua-driver 本身跨平台，但本仓库的 app 配方（`send_wechat.py`/`iphonemirror.py`）含 macOS 特定逻辑，需适配；直接驱动核心（`computer_use.py` 的 A/B 档）在 cua-driver 支持的前提下可试

## 目录结构

```
├── README.md                  # 本文件(快速上手)
├── docs/                      # 用户向文档
│   ├── overview.md            # 原理与设计
│   ├── app-guides.md          # App 实操教程
│   └── reference.md           # 脚本/API 参考
├── SKILL.md                   # 完整技能手册(= 安装后 agent 的手册)
├── install.sh                 # 一键安装(skill → 符号链接)
├── update.sh                  # 一键更新(git pull + 重建链接 + 版本自检)
├── plugin/                    # DSH 插件壳(/cua 命令, 子进程调用仓库 scripts)
│   ├── package.json
│   ├── cordis.patch.yml
│   ├── src/index.js
│   └── README.md
├── config/
│   └── .vision-config.example.json  # 识图配置模板
├── scripts/
│   ├── cua_lib.py             # 通用底层(调 cua-driver / 三档决策 / __version__ 单一事实源)
│   ├── computer_use.py        # 泛用驱动入口(任意 app)
│   ├── vision.py              # 多模态识图(可配置端点)
│   ├── send_wechat.py         # 微信发消息配方
│   └── iphonemirror.py        # iPhone 镜像操控配方
└── LICENSE
```

## 双形态与更新

本仓库用「**单一事实源 + 不复制**」消灭双形态漂移：

| 形态 | 装的方式 | 脚本来源 | 会不会漂移 |
|------|---------|---------|-----------|
| **skill** | `install.sh` → **符号链接**到仓库 `scripts/` | 仓库（链接） | 不会（物理同一份） |
| **DSH 插件** | `plugin/` 的 `/cua` 命令 → **子进程**调用仓库 `scripts/` | 仓库（子进程） | 不会（物理同一份） |

两个形态都以仓库 `scripts/` 为准，改一次立刻两端一致。升级只需在仓库里：

```bash
git pull
./update.sh        # 重建链接 + 版本自检(检测已装副本 vs 仓库是否漂移)
```

每个脚本都带 `--version`（来自 `cua_lib.__version__`），可随时比对已装副本与仓库版本。

## 安全与隐私

- 保持 cua-driver 的 **standard 权限档**，不要轻易用 `--dangerously-bypass-approvals`
- 识图只在内存处理截图，不落盘（`computer_use.py`/脚本默认不写图文件）
- 对不可寻址目标 cua-driver 会结构化拒绝，不会静默假成功
- 让 agent 操作真实 app 前请确认：你授权它操作的范围是可控的

## 相关

- [cua-driver / trycua](https://github.com/trycua/cua) — 底层驱动
- 原理与"AX 不可达应用"研究：见 `SKILL.md` 参考

## License

[MIT](LICENSE)