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 등 웹 커널 애플리케이션은 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: UI가 실제로 변경됨 / 입력 내용이 확인됨

  • 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:와 UI 변경 후 무효화된 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만 지원