macOS 桌面自动化技能 afa-cloud/desktop-gui-automation-cua

desktop-gui-automation-cua

给 AI agent 用的 macOS 桌面 GUI computer-use 技能包：用 cua-driver 驱动任意本机应用（点击 / 输入 / 滚动 / 拖拽 / 截图），自动做 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 | 原理与设计（AX→像素→桌面三档降级、Skyshot/取证、识图、安全） |
| docs/app-guides.md | App 实操教程（原生 app / 微信 / QQ / iPhone 镜像）+ 排障 |
| 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。其余全自动。

手动安装：

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，唯一硬门槛） —— 让驱动能看屏幕、能操控界面：

cua-driver permissions grant

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

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

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

~/.config/vision-config.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 等）。

快速自检

1) 权限 cua-driver permissions status --json
2) 识图(配好 key 后应能描述图)bash
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 # 判定 A/B/C 档
python3 $D/computer_use.py snapshot --out t.png # AX + 截图
python3 $D/computer_use.py inspect "描述界面" # 识图
python3 $D/computer_use.py click --token s000.. # AX 点击(后台不抢焦点)
python3 $D/computer_use.py click --x 120 --y 750 # 像素点击(window-local px)
python3 $D/computer_use.py type "你好" # 文本输入
python3 $D/computer_use.py key Return # 按键

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

工作流（对任意 app）

1. 定位 computer_use.py windows # 找窗口
2. 判定 computer_use.py probe # 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 — 底层驱动
- 原理与“AX 不可达应用”研究：见 SKILL.md 参考

许可证

MIT