Skip to main content
Glama
README.md
# Chrome CUA MCP

给没有内置 computer use 的 agent / harness 用的 Chrome 操作工具:一个 MCP 服务,加一个本地 2B 视觉模型,加一个桌面悬浮窗。上层模型只收发文字,页面由本机来看、来点。

![上层模型经 MCP 驱动隔离的 Chrome,随后在悬浮窗里下指令并被高危保护拦下](./assets/demo.gif)

上面是 25 秒实录,未加速、未剪辑。一个 MCP 客户端用 `cua_navigate`、一次 `cua_run_steps`(4 步)和 `cua_ask_screen` 操作隔离的 Chrome,全程 0 张截图;随后在悬浮窗里输入“点击右侧橙色的按钮”,本地模型定位到的是“确认支付”,动作被拦下,人确认后才点击。页面是录制脚本自带的本地演示页,没有真实交易;底部字幕是后期加的,其中的耗时、字节数和回答取自当次调用的真实返回。录制脚本:[scripts/record_demo.py](./scripts/record_demo.py)。

## 它怎么工作

- **两种目标**
  - `managed`:独立配置目录的隔离 Chrome,通过 CDP 读 DOM、点元素。快,不碰你的日常浏览器。
  - `desktop`:你已经登录的本机 Chrome,用窗口截图、Windows 自带 OCR 和真实键鼠输入。
- **文字优先**:能用 DOM 或 OCR 文字匹配的目标不调模型;默认不回传截图,返回体默认精简(`detail="brief"`)。
- **本地模型兜底**:没有文字的图标、需要“看一眼”的问题,交给本机的 Qwen3.5-2B 微调模型(llama.cpp,约 2.3 GB 显存),只把坐标或一句话答案返回给上层。模型在第一次用到视觉时才加载。
- **批量执行**:`cua_run_steps` 一次调用最多跑 12 步,减少上层模型的往返轮次。
- **保护**
  - 支付、下单、删除、转账等高危词(指令里出现,或定位到的目标上出现)会停下来等人确认,返回一次性 `confirm_token`。
  - 登录页和人机验证直接交还给人。
  - `desktop` 模式下 Chrome 不在前台就拒绝发送键鼠;把鼠标甩到屏幕左上角可急停。
  - 带 `require_submit` 的提交步骤只认 URL 变化、明确的表单结果或你指定的新文字,输入框回显不算提交成功。
- **悬浮窗**:平时只有一行输入;上层接入、执行进度、风险确认按需出现。也可以不经上层模型,直接在里面下单步指令。

## 现状和边界

这是一个个人项目,只在一台机器上验证过(Windows 11、RTX 4060 Laptop 8 GB、Python 3.11)。下面的数字都是小样本,不是成功率承诺。

| 项目 | 结果 | 说明 |
| --- | --- | --- |
| 托管模式一次观察 | 2–3 ms | 不截图时 |
| 本地模型一次定位或读屏 | 约 0.5–0.7 s | 模型已加载;首次加载另需约 2–3 s(文件已在系统缓存里时) |
| 桌面模式 OCR | 约 0.7 s | 整窗 |
| 自采真实 Chrome 留出集:点击落框 / 缺失目标拒识 | 103/120、80/80 | 与训练数据同批采集,偏乐观 |
| Venus 中文定位题(没见过的页面):点击落框 / 缺失目标拒识 | 105/240、22/80 | 泛化明显变差 |
| 真实网站上纯视觉找链接 | 两轮 6/15、5/15 | 不执行点击,只比对坐标 |
| Python 文档站内搜索并提交(托管模式) | 10/10 | 修复回车提交后复测 |

- **适合**:上层模型负责拆任务和核对结果,本工具负责在托管 Chrome 里按 DOM 执行;需要看图时本地模型兜底;高危动作由人确认。
- **不适合**:无人值守的长链任务;纯视觉操作陌生网站;拖拽、画图、滑块(动作协议里没有按住拖动)。
- **没有验证过**:除 Codex、Antigravity 以外的 MCP 客户端;上层模型实际节省了多少 token;Windows 10 和其他显卡。
- **微调权重没有随仓库发布**。`m0_setup_local.py` 能下载官方基座的 GGUF,但基座不按本项目的动作协议输出(协议判分 0/24),视觉定位基本不可用;不依赖模型的 DOM 路径不受影响。要用视觉功能,需要按[训练](#模型训练)一节自己训练并导出。

## 环境要求

- Windows 10/11,Google Chrome 装在默认位置(`C:\Program Files\Google\Chrome\Application\chrome.exe`)
- Python 3.11
- 视觉功能需要 NVIDIA 显卡(llama.cpp 的 CUDA 12.4 预编译包),约 2.3 GB 显存

## 安装

```powershell
git clone https://github.com/Assangejulian/chrome-cua-mcp.git
cd chrome-cua-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

# 可选:下载 llama.cpp(b12441,CUDA 12.4)和官方基座 GGUF 到 tools/ 与 models/
.\.venv\Scripts\python.exe .\scripts\m0_setup_local.py
```

模型放在 `models/<目录>/` 下,启动时按下表自动发现,排在前面的优先:

| 悬浮窗里的名字 | 目录 | 模型文件 | 视觉投影文件 |
| --- | --- | --- | --- |
| M3.5 | `models/m35_gguf/` | `m35-qwen35-2b-Q4_K_M.gguf`(或 `Q8_0`) | `m35-mmproj-f16.gguf` |
| M3 | `models/m3_gguf/` | `m3-qwen35-2b-Q4_K_M.gguf` | `m3-mmproj-f16.gguf` |
| 基座 | `models/qwen35_2b_gguf/` | `Qwen3.5-2B-Q4_K_M.gguf` | `mmproj-F16.gguf` |

## 运行

**悬浮窗(同时提供 HTTP MCP,`http://127.0.0.1:18390/mcp`)**

```powershell
.\启动_Chrome_Pilot_M35.bat
```

悬浮窗启动时如果发现已打开的 Chrome,会默认选中“本机 Chrome”,之后的动作是真实键鼠输入到你的浏览器。想在隔离浏览器里操作,先点 ≡ 把第一个下拉切到“后台托管”。

**只起 MCP 服务(默认 `managed`)**

```powershell
.\.venv\Scripts\python.exe .\scripts\chrome_cua_mcp.py --stdio
.\.venv\Scripts\python.exe .\scripts\chrome_cua_mcp.py --http --port 18390
```

可选参数:`--target-mode managed|desktop`、`--profile-dir <目录>`(托管 Chrome 的配置目录,默认是项目下的 `profiles/cua_chrome`,里面有登录状态,已被 git 忽略)。

**接入上层模型**

Stdio(Codex 的 `config.toml`,路径换成你的克隆位置):

```toml
[mcp_servers.chrome-pilot-cua]
command = 'D:\path\to\chrome-cua-mcp\.venv\Scripts\python.exe'
args = ['D:\path\to\chrome-cua-mcp\scripts\chrome_cua_mcp.py', '--stdio']
```

HTTP(悬浮窗或 `--http` 已在运行时):

```json
{ "mcpServers": { "chrome-pilot-cua": { "url": "http://127.0.0.1:18390/mcp" } } }
```

`configs/` 里是同样的三份配置,其中的绝对路径是作者机器上的,使用前要改;悬浮窗“接入”菜单里的“复制 Stdio 配置”复制的也是这份文件。

## 工具

| 工具 | 作用 |
| --- | --- |
| `cua_navigate` | 打开网址、前进后退、切换标签页,或切换 `managed` / `desktop`;返回标题、正文摘要和可点元素 |
| `cua_observe` | 读当前页面:URL、标题、正文、可点元素(坐标为 0–1000 归一化)、是否遇到登录或验证码 |
| `cua_act` | 执行一步:按元素编号、OCR 编号、文字提示,或用自然语言交给本地模型定位 |
| `cua_run_steps` | 一次最多 12 步的小计划:打开、点击并输入、滚动到、等待、提问等;遇到弹窗、高危动作、未观察到提交会停下并说明 |
| `cua_ask_screen` | 让本地模型回答一个关于当前画面的事实问题,只返回文字 |
| `cua_locate` | 只预览本地模型的定位坐标,不发送任何输入 |
| `cua_dismiss_popup` | 尝试关闭弹窗或横幅 |
| `cua_extract` | 提取页面可见文字和链接 |
| `cua_status` | 当前模型、显存、浏览器和任务状态(不会触发模型加载) |
| `cua_task` | 把任务的开始、进度、完成显示到悬浮窗上 |

省上层 token 的用法:能拼出网址就直接 `cua_navigate`;多步操作打包进一次 `cua_run_steps`;需要确认页面细节时用 `cua_ask_screen` 而不是要截图;只有排查问题时才传 `include_screenshot=true` 或 `detail="full"`。`status` 只表示动作是否发出、提交是否被观察到,关键业务结果仍应由上层独立核对。

## 环境变量

| 变量 | 作用 |
| --- | --- |
| `CUA_PREWARM=1` | 第一次工具调用时就在后台加载本地模型。默认关闭:开启后首个视觉任务快约 1.7–2.6 s,但只做 DOM 的会话会白占约 2.3 GB 显存 |
| `CHROME_PILOT_MOTION=0` | 关闭悬浮窗动效 |
| `CHROME_PILOT_GLASS=0` | 关闭悬浮窗的半透明亚克力效果,改用不透明深色背景 |

## 测试

```powershell
.\.venv\Scripts\python.exe -u .\scripts\test_cua_mcp.py
```

全量回归约 2 分钟,会启动一个隔离的 Chrome 和本地模型,覆盖 Stdio / HTTP 两种 MCP、提交判定、桌面 OCR、前台保护、悬浮窗交互与动效。需要本地模型文件;界面相关的测试会短暂在屏幕上显示窗口。

## 模型训练

本地模型是 `Qwen/Qwen3.5-2B` 的 LoRA 微调(语言侧,监督微调),合并后导出为 GGUF(Q4_K_M)和配套的视觉投影文件。当前使用的一版(M3.5)训练集 4,148 条、验证集 645 条,来源是公开网页定位数据、自采的中文 Chrome 截图和困难负样本,在 Colab A100 上训练。输出是单行 JSON 动作(`left_click`、`type`、`scroll`、`not_found` 等,坐标 0–1000 归一化)。

- [01_任务书_Chrome视觉鼠标操作模型.md](./01_任务书_Chrome视觉鼠标操作模型.md):最初的工程任务书(动作空间、坐标与 DPI 链路、数据规范、验收标准)。项目后来从“纯视觉模型”转向“DOM 优先、模型兜底”,任务书保留作为背景。
- [02_从YOLO到VLM后训练实战指南.md](./02_从YOLO到VLM后训练实战指南.md)、[03_LLM与VLM训练全景教学手册.md](./03_LLM与VLM训练全景教学手册.md):写给有目标检测经验的人的 VLM 微调入门。
- [notebooks/](./notebooks):数据准备和 Colab 训练、导出用的 Notebook;由 `scripts/build_colab_notebooks.py`、`scripts/m3_train_colab.py`、`scripts/m35_build_notebook.py` 生成。
- `scripts/m1_*`、`m3_*`、`m35_*`:采集、数据整理、离线对照和端到端评测脚本。训练数据包和评测原始结果不在仓库里。

## 目录

```
scripts/cua_engine.py         引擎:托管 / 桌面两条路径、本地模型生命周期、提交判定、保护规则
scripts/chrome_cua_mcp.py     MCP 服务(Stdio 与 Streamable HTTP)
scripts/chrome_pilot_panel.py 悬浮窗
scripts/live_chrome_pilot.py  悬浮窗入口与 llama-server 启动
scripts/desktop_perceiver.py  桌面模式的 OCR 与画面感知
scripts/action_executor.py    带保护的真实键鼠执行
scripts/test_cua_mcp.py       全量回归
scripts/record_demo.py        录制上面的演示动图
configs/                      MCP 接入配置示例
notebooks/                    训练与数据准备
```

`models/`、`tools/`、`artifacts/`、`profiles/` 是本机生成的目录,不入库。

## 许可证

代码以 Apache-2.0 发布,见 [LICENSE](./LICENSE)。Qwen3.5 基座模型和 llama.cpp 各有自己的许可证,使用前请分别查看。