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 后应能描述图)
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（完整手册）。常用：

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/ 为准，改一次立刻两端一致。升级只需在仓库里：

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 参考

License

MIT