opencode-gui-bridge

让 opencode（或任何 MCP 客户端）获得电脑使用能力：能看（理解屏幕状态）、能操作（点击/输入/滚动）、能验证（确认操作生效）。

基于 PySide6 + Win32 API + Windows UI Automation + 本地 OCR 实现，零系统级依赖。基础操作全部本地运行，无网络需求（仅视觉 describe 可选配网络 API）。

快速开始

1. 解压项目到任意目录（示例 D:\gui-bridge\），双击 setup.bat，等它显示 Done.

2. 在你的 opencode 工作目录放一个 opencode.json（内容见「接入 opencode」），把两处路径改成第 1 步的实际路径

3. 重启 opencode

4. 用 AI 对话框直接说：

   • 「列出电脑上的窗口」→ 得到 list_targets 结果

   • 「打开记事本，在里面输入你好」→ 会自动执行 打开→绑定→快照→点击→输入→验证

安装

.\setup.bat

脚本一次性完成：创建 venv 虚拟环境（已存在则跳过）→ pip 安装依赖 → 跑冒烟测试。看到 Done. 即安装成功；失败时它会退出并打印原因。

手动装也是一样的效果：

python -m venv venv
venv\Scripts\python -m pip install -e .
venv\Scripts\python tests\smoke_test.py

要求：Windows 10/11 + Python 3.10+（安装时勾选 Add python.exe to PATH）。

接入 opencode

opencode.json 放在你运行 opencode 的工作目录下（不放在项目里）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gui-bridge": {
      "type": "local",
      "command": [
        "D:\\gui-bridge\\venv\\Scripts\\python.exe",
        "D:\\gui-bridge\\server.py"
      ],
      "enabled": true,
      "environment": {
        "SILICONFLOW_API_KEY": "{env:SILICONFLOW_API_KEY}"
      }
    }
  }
}

两步改动：

1. 把两个 D:\\gui-bridge\\... 换成你的实际路径（\ 在 JSON 里要写成 \\）

2. SILICONFLOW_API_KEY 那行：本地 OCR 与点击输入不需要任何 key，只有你打算用视觉 describe 才需要配置（见下一节）。没 key 就删掉这行。

验证接入成功：重启 opencode 后，跟 AI 说一句「列出电脑上的窗口」；若 AI 能返回窗口列表，说明 python.exe 与 server.py 路径配置正确。

视觉通道配置（describe 用，可选）

list_targets 返回的 channels.vision 会标明状态：ready（有 key）或 no-key（没有）。走 OpenAI 兼容 API，任意厂商：

三种设置方式，任选其一：

a) opencode.json 内嵌（跟随配置，最推荐）

"environment": {
  "VISION_BASE_URL": "https://api.siliconflow.cn/v1",
  "VISION_API_KEY": "{env:OPENAI_API_KEY}",
  "VISION_MODEL": "Qwen/Qwen3-VL-32B-Instruct"
}

{env:XXX} 表示读取你本机已有的同名环境变量。

b) 系统级持久化（对所有终端生效）：

setx VISION_API_KEY "sk-xxxx"
setx VISION_BASE_URL "https://api.siliconflow.cn/v1"

设完要重开终端 和重开 opencode 才生效。

c) 只在该次终端会话生效：

$env:VISION_API_KEY = "sk-xxxx"

CDP 通道配置（WebView2 / Tauri / Electron）

Tauri、WebView2、Electron 等 Web 内核应用，UIA 只能看到外层壳，读不到 DOM。开启 CDP 调试端口后，快照会自动走 CDP 通道（元素 id 前缀 d:），读取全文是毫秒级。

按应用类型开启调试端口：

$env:WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS = "--remote-debugging-port=9222 --remote-allow-origins=*"
Start-Process 目标应用

启动后用 list_targets 确认：返回的 channels.cdp 会显示端口号（如 9222）。之后 snapshot 自动走 CDP，act 自动路由 DOM 操作：

• 读页面全文：DOM innerText，<10ms（OCR 要 1~6s）

• 点击：原生 DOM click（绕过物理 hit-test 覆盖层）

• 输入：Input.insertText 真实输入管线（兼容 Quill 等编辑器）

• 元素坐标：CSS×DPR+窗口位置近似（操作不依赖坐标）

没开启也不影响使用：这类应用会自动降级走本地 OCR 通道，照样能读屏和操作。

工具箱：7 个 MCP 工具

规则：snapshot/act 需要在 focus_target 之后调用。

act 动作详解

返回结构 {ok, verify, detail}：

• ok: 动作是否执行

• verify: 执行后自动验证的结果

  • changed / matched：界面确实变了 / 输入内容已确认出现

  • no_change / no_match：没检测到预期变化（可能动作没生效，建议重新 snapshot 看最新状态）

  • cdp_insert / skipped：走了 CDP 输入或指定关闭验证

  • failed：执行失败，detail 会带原因，点击类失败会自动物理重试并附诊断截图路径

• detail: 人类可读的结果说明，可能附 诊断截图: <路径>

架构

┌─ Agent (AI)
│   7 个 MCP 工具: list_targets / focus_target / snapshot /
│   act / wait_change / screenshot / describe
├─ server.py      会话编排: 目标窗口绑定, 通道选择, 验证闭环
├─ snapshot.py    统一元素抽象: {id, type, text, bbox, enabled, focused}
│                 通道融合 + 稳定 id (u:路径链 / o:OCR索引)
├─ executor.py    动作路由: click/input/press/scroll + 内置验证
├─ uia.py         UIA 控件树通道 (L1, 毫秒级, 原生应用)
├─ ocr.py         本地 OCR 通道 (L2, 1~6s, WebView 兜底)
├─ win32io.py     Win32 底层: 窗口/鼠标/键盘/截图/PostMessage/PrintWindow
└─ vision.py      视觉模型通道 (L3, 兜底理解, 需 API key)

运行日志写入 `logs/gui-bridge.log`（JSON lines：每次工具调用的耗时/通道/结果）。

核心设计

1. AI 只按元素 id 操作，不用坐标。快照给 id，act 自动把 id 路由到最优通道。

2. 通道自动降级：CDP → UIA → OCR → 视觉；点击: InvokePattern → PostMessage → 物理。

3. 验证闭环内置：act 返回 verify=changed/no_match/failed + 原因。

4. 遮挡安全捕获：OCR 与验证用 PrintWindow 直取目标窗口真实内容，目标被其他窗口盖住也不串内容。

元素 id 规则

o: 和界面变化后失效的 u:，点击前请先重新 snapshot 拿新 id。

测试

venv\Scripts\python tests\smoke_test.py   # 7 工具 + UIA 全链路（自建测试窗口）
venv\Scripts\python tests\ocr_test.py     # OCR 通道兜底链路
venv\Scripts\python tests\stdio_e2e.py    # 端到端：真实 MCP stdio 会话

已知限制

• WebView2/Tauri 双层壳 DOM 不暴露给 UIA → 自动走 OCR 通道（实测可完整读屏与操作）

• Windows 可能禁止后台进程抢焦点 → focus_target 会提示，必要时手动点一次目标窗口

• OCR 通道每快照 1~6s（画面静止时快照缓存命中可到亚秒级），是 WebView 应用的主要延迟来源

• 当前仅支持 Windows