opencode-gui-bridge

Permite que opencode (o cualquier cliente MCP) obtenga capacidades de uso de computadora: pueda ver (entender el estado de la pantalla), operar (hacer clic / escribir / desplazarse) y verificar (confirmar que la acción surtió efecto).

Implementado con PySide6 + Win32 API + Windows UI Automation + OCR local, con cero dependencias a nivel de sistema. Todas las operaciones básicas se ejecutan localmente sin necesidad de red (solo la opción visual describe puede requerir una API de red).

Inicio rápido

1. Descomprima el proyecto en cualquier directorio (ejemplo D:\gui-bridge\), haga doble clic en setup.bat y espere a que muestre Done.

2. En su directorio de trabajo de opencode, coloque un archivo opencode.json (contenido según «Integración con opencode»), y modifique las dos rutas para que apunten a las rutas reales del paso 1

3. Reinicie opencode

4. Use el cuadro de diálogo de IA directamente:

   • «Lista las ventanas de la computadora» → obtiene el resultado de list_targets

   • «Abre el bloc de notas y escribe hola dentro» → se ejecuta automáticamente: abrir → vincular → instantánea → clic → escribir → verificar

Instalación

.\setup.bat

El script lo hace todo de una vez: crea el entorno virtual venv (si ya existe, lo omite) → instala dependencias con pip → ejecuta una prueba de humo. Si ve Done., la instalación fue exitosa; en caso de fallo, el script sale e imprime el motivo.

Hacerlo manualmente produce el mismo resultado:

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

Requisitos: Windows 10/11 + Python 3.10 o superior (marque Add python.exe to PATH durante la instalación).

Integración con opencode

Coloque opencode.json en el directorio de trabajo donde ejecuta opencode (no dentro del proyecto):

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

Dos cambios:

1. Cambie las dos D:\\gui-bridge\\... por sus rutas reales (en JSON, \ debe escribirse como \\)

2. La línea SILICONFLOW_API_KEY: el OCR local y el clic/escritura no necesitan ninguna clave, solo necesita configurarla si planea usar la descripción visual (consulte la siguiente sección). Si no tiene clave, elimine esa línea.

Para verificar la integración: después de reiniciar opencode, diga a la IA «Lista las ventanas de la computadora»; si la IA devuelve una lista de ventanas, significa que las rutas de python.exe y server.py están configuradas correctamente.

Configuración del canal visual (para describe, opcional)

El campo channels.vision devuelto por list_targets indica el estado: ready (con clave) o no-key (sin clave). Usa una API compatible con OpenAI, de cualquier proveedor:

Hay tres formas de configurarlo, elija una:

a) Incrustado en opencode.json (sigue la configuración, recomendado)

"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} indica que se leerá la variable de entorno del mismo nombre ya existente en su máquina.

b) Persistente a nivel de sistema (afecta a todas las terminales):

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

Después de configurarlo, debe reiniciar la terminal y reiniciar opencode para que surta efecto.

c) Solo para la sesión actual de la terminal:

$env:VISION_API_KEY = "sk-xxxx"

Configuración del canal CDP (WebView2 / Tauri / Electron)

En aplicaciones con núcleo Web como Tauri, WebView2, Electron, etc., UIA solo puede ver la cáscara externa, no el DOM. Al habilitar el puerto de depuración CDP, la instantánea (snapshot) automáticamente usará el canal CDP (los ids de elementos tienen el prefijo d:), y leer el texto completo es cuestión de milisegundos.

Active el puerto de depuración según el tipo de aplicación:

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

Después de iniciar, verifique con list_targets: el campo channels.cdp mostrará el número de puerto (por ejemplo 9222). A partir de entonces, snapshot usará automáticamente CDP y act dirigirá las operaciones del DOM automáticamente:

• Leer el texto completo de la página: DOM innerText, <10ms (el OCR toma de 1 a 6 s)

• Clic: clic DOM nativo (omite las capas de cobertura física hit-test)

• Entrada: canal de entrada real Input.insertText (compatible con editores como Quill)

• Coordenadas de elementos: aproximadas (CSS × DPR + posición de la ventana) (las operaciones no dependen de coordenadas)

Si no se habilita, no afecta el uso: este tipo de aplicaciones degrada automáticamente al canal de OCR local, que igual puede leer y operar la pantalla.

Caja de herramientas: 7 herramientas MCP

Regla: snapshot/act requieren llamar a focus_target antes.

Detalles de las acciones de act

Estructura de retorno {ok, verify, detail}:

• ok: si la acción se ejecutó

• verify: resultado de la verificación automática después de ejecutar

  • changed / matched: la interfaz realmente cambió / el contenido escrito se confirmó

  • no_change / no_match: no se detectó el cambio esperado (posiblemente la acción no surtió efecto, se recomienda tomar una nueva instantánea para ver el estado actual)

  • cdp_insert / skipped: se usó entrada CDP o se desactivó la verificación

  • failed: fallo de ejecución; detail incluirá el motivo; en caso de fallo de clic, se reintenta físicamente automáticamente y adjunta una ruta de captura de diagnóstico

• detail: explicación legible para humanos, puede incluir diagnóstico screenshot: <ruta>

Arquitectura

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

Diseño central

1. La IA opera solo por id de elemento, no por coordenadas. La instantánea da los ids, y act los enruta automáticamente al mejor canal.

2. Degradación automática de canales: CDP → UIA → OCR → visual; clics: InvokePattern → PostMessage → físico.

3. Ciclo de verificación integrado: act retorna verify=changed/no\_match/failed con la razón.

4. Captura segura frente a oclusiones: el OCR y la verificación usan PrintWindow para capturar directamente el contenido real de la ventana objetivo, evitando que si la ventana está cubierta por otras, se mezcle el contenido.

Reglas de id de elemento

Los ids o: y los u: que quedan obsoletos después de cambios de interfaz requieren volver a tomar snapshot antes de hacer clic.

Pruebas

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

Limitaciones conocidas

• El DOM de doble capa de WebView2/Tauri no se expone a UIA → se degrada automáticamente al canal OCR (en pruebas se lee y opera la pantalla por completo)

• Windows puede impedir que procesos en segundo plano tomen el foco → focus_target lo avisará; si es necesario, haga clic manualmente una vez en la ventana objetivo

• El canal OCR toma de 1 a 6 s por instantánea (en reposo, el caché de instantáneas puede dar respuesta en menos de un segundo), siendo la principal fuente de latencia en aplicaciones WebView

• Actualmente solo admite Windows