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. В диалоге с ИИ просто скажите:

   • «Перечисли окна на компьютере» → получите результат 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 и кликов/ввода ключ не нужен, он требуется только если вы планируете использовать визуальный describe (см. следующий раздел). Если ключа нет — удалите эту строку.

Проверка подключения: после перезапуска opencode скажите ИИ «Перечисли окна на компьютере»; если ИИ вернёт список окон, значит пути python.exe и server.py настроены правильно.

Настройка визуального канала (для describe, опционально)

channels.vision в ответе list_targets показывает статус: ready (есть ключ) или 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 и т.п.) 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. ИИ работает только по 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 с двойной оболочкой не expose DOM в UIA → автоматически используется OCR-канал (на практике полное чтение экрана и операции работают)

• Windows может запрещать фоновым процессам захватывать фокус → focus_target выведет предупреждение; при необходимости один раз кликните по целевому окну вручную

• OCR-канал занимает 1~6s на снимок (при статичном экране кэш снимков может дать субсекундный ответ) — это основной источник задержки для WebView-приложений

• В настоящее время поддерживается только Windows