opencode-gui-bridge

Verschafft opencode (oder jedem anderen MCP-Client) Computer-Nutzungsfähigkeiten: Sehen (Bildschirmzustand verstehen), Bedienen (Klicken/Eingeben/Scrollen), Verifizieren (bestätigen, dass Aktionen wirksam wurden).

Basiert auf PySide6 + Win32 API + Windows UI Automation + lokaler OCR, ohne systemweite Abhängigkeiten. Alle Basisoperationen laufen lokal, keine Netzwerkanforderungen (nur die visuelle describe-Funktion benötigt optional eine Netzwerk-API).

Schnellstart

1. Projekt in ein beliebiges Verzeichnis entpacken (Beispiel D:\gui-bridge\), setup.bat doppelklicken und warten, bis Done. angezeigt wird.

2. Eine opencode.json in dein opencode-Arbeitsverzeichnis legen (Inhalt siehe „opencode-Anbindung"), die beiden Pfade auf die tatsächlichen Pfade aus Schritt 1 ändern.

3. opencode neu starten.

4. Direkt im KI-Dialogfeld sagen:

   • „Fenster auf dem Computer auflisten" → Ergebnis von list_targets erhalten

   • „Notepad öffnen und 'Hallo' eingeben" → führt automatisch aus: Öffnen → Binden → Snapshot → Klicken → Eingeben → Verifizieren

Installation

.\setup.bat

Das Skript erledigt alles in einem Durchgang: venv-virtuelle Umgebung erstellen (überspringen, falls vorhanden) → pip-Abhängigkeiten installieren → Smoke-Test ausführen. Bei Erfolg erscheint Done.; bei Fehler bricht es ab und gibt den Grund aus.

Manuelle Installation hat denselben Effekt:

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

Voraussetzungen: Windows 10/11 + Python 3.10+ (bei Installation Add python.exe to PATH anhaken).

opencode-Anbindung

opencode.json liegt in deinem opencode-Arbeitsverzeichnis (nicht im Projekt):

{
  "$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}"
      }
    }
  }
}

Zwei Änderungen:

1. Die beiden D:\\gui-bridge\\...-Pfade durch deine tatsächlichen Pfade ersetzen (\ muss in JSON als \\ geschrieben werden).

2. Die Zeile SILICONFLOW_API_KEY: Lokale OCR sowie Klicken/Eingeben benötigen keinen Key, nur wenn du die visuelle describe-Funktion nutzen willst, ist eine Konfiguration nötig (siehe nächster Abschnitt). Ohne Key diese Zeile löschen.

Erfolgreiche Anbindung verifizieren: Nach dem Neustart von opencode dem KI sagen „Fenster auf dem Computer auflisten"; wenn die KI eine Fensterliste zurückgibt, sind python.exe- und server.py-Pfade korrekt konfiguriert.

Konfiguration des visuellen Kanals (für describe, optional)

channels.vision in der list_targets-Rückgabe zeigt den Status: ready (mit Key) oder no-key (ohne). Nutzt eine OpenAI-kompatible API, beliebiger Anbieter:

Drei Einstellungsmöglichkeiten, eine davon wählen:

a) In opencode.json eingebettet (folgt der Konfiguration, am empfehlenswertesten)

"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} bedeutet: die bereits auf deinem Rechner vorhandene gleichnamige Umgebungsvariable lesen.

b) Systemweite Persistierung (wirkt für alle Terminals):

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

Nach dem Setzen müssen Terminal und opencode neu gestartet werden, damit es wirkt.

c) Nur für die aktuelle Terminal-Sitzung wirksam:

$env:VISION_API_KEY = "sk-xxxx"

CDP-Kanal-Konfiguration (WebView2 / Tauri / Electron)

Bei Web-Kern-Anwendungen wie Tauri, WebView2, Electron sieht UIA nur die äußere Hülle und kann das DOM nicht lesen. Nach Aktivierung des CDP-Debug-Ports läuft der Snapshot automatisch über den CDP-Kanal (Element-ID-Präfix d:), das Lesen des vollständigen Texts dauert Millisekunden.

Debug-Port je nach Anwendungstyp aktivieren:

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

Nach dem Start mit list_targets bestätigen: channels.cdp in der Rückgabe zeigt die Portnummer (z. B. 9222). Danach läuft snapshot automatisch über CDP, act routet DOM-Operationen automatisch:

• Volltext der Seite lesen: DOM innerText, <10ms (OCR benötigt 1~6s)

• Klicken: natives DOM click (umgeht physische Hit-Test-Overlays)

• Eingabe: Input.insertText echte Eingabepipeline (kompatibel mit Editoren wie Quill)

• Elementkoordinaten: CSS×DPR+Fensterposition Näherung (Operationen hängen nicht von Koordinaten ab)

Ohne Aktivierung funktioniert es trotzdem: Solche Anwendungen fallen automatisch auf den lokalen OCR-Kanal zurück und können weiterhin Bildschirm lesen und bedienen.

Werkzeugkasten: 7 MCP-Tools

Regel: snapshot/act müssen nach focus_target aufgerufen werden.

act-Aktionen im Detail

Rückgabestruktur {ok, verify, detail}:

• ok: ob die Aktion ausgeführt wurde

• verify: Ergebnis der automatischen Verifikation nach der Ausführung

  • changed / matched: Die UI hat sich tatsächlich geändert / der eingegebene Inhalt wurde bestätigt

  • no_change / no_match: Keine erwartete Änderung erkannt (Aktion möglicherweise nicht wirksam, neues snapshot empfohlen für den aktuellen Zustand)

  • cdp_insert / skipped: CDP-Eingabe verwendet oder Verifikation deaktiviert

  • failed: Ausführung fehlgeschlagen, detail enthält den Grund; bei Klick-Fehlern automatischer physischer Wiederholungsversuch mit Diagnose-Screenshot-Pfad

• detail: Für Menschen lesbare Ergebnisbeschreibung, kann Diagnose-Screenshot: <Pfad> enthalten

Architektur

┌─ 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：每次工具调用的耗时/通道/结果）。

Kerndesign

1. KI operiert nur über Element-IDs, nicht über Koordinaten. Snapshot liefert IDs, act routet die ID automatisch zum optimalen Kanal.

2. Automatische Kanal-Degradierung: CDP → UIA → OCR → Vision; Klicken: InvokePattern → PostMessage → physisch.

3. Integrierte Verifikationsschleife: act gibt verify=changed/no_match/failed + Grund zurück.

4. Sichere Erfassung bei Verdeckung: OCR und Verifikation nutzen PrintWindow, um den echten Inhalt des Ziel-Fensters direkt zu erfassen; selbst wenn das Ziel von anderen Fenstern verdeckt wird, wird kein fremder Inhalt erfasst.

Element-ID-Regeln

Für o: und u:, die nach UI-Änderungen ungültig werden, bitte vor dem Klicken ein neues snapshot für neue IDs ausführen.

Tests

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 会话

Bekannte Einschränkungen

• WebView2/Tauri-Doppelschalen-DOM ist für UIA nicht sichtbar → automatischer Fallback auf OCR-Kanal (praktisch getestet: vollständiges Bildschirmlesen und Bedienen möglich)

• Windows kann Hintergrundprozessen das Ergreifen des Fokus verbieten → focus_target gibt einen Hinweis, bei Bedarf das Ziel-Fenster einmal manuell anklicken

• OCR-Kanal benötigt 1~6s pro Snapshot (bei statischem Bildschirm kann der Snapshot-Cache auf unter eine Sekunde kommen), Hauptlatenzquelle für WebView-Anwendungen

• Aktuell nur Windows unterstützt