opencode-gui-bridge

opencode（または任意のMCPクライアント）にPC操作能力を付与します：見る（画面状態の理解）、操作する（クリック/入力/スクロール）、検証する（操作の効果確認）。

PySide6 + Win32 API + Windows UI Automation + ローカルOCRに基づき、システムレベルの依存関係はゼロ。基本操作はすべてローカルで実行され、ネットワーク不要（ビジュアルdescribeのみオプションでネットワークAPIを利用可能）。

クイックスタート

1. プロジェクトを任意のディレクトリに解凍（例 D:\gui-bridge\）、setup.bat をダブルクリックし、Done. と表示されるまで待つ

2. opencodeの作業ディレクトリに opencode.json を置く（内容は「opencodeへの接続」参照）、2箇所のパスをステップ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}"
      }
    }
  }
}

2つの変更手順：

1. 2箇所の D:\\gui-bridge\\... を実際のパスに置き換える（JSON内では \ は \\ と書く）

2. SILICONFLOW_API_KEY の行：ローカルOCRとクリック入力にはキーは不要。ビジュアルdescribeを使う場合のみ設定が必要（次のセクション参照）。キーがなければこの行を削除。

接続成功の確認：opencode再起動後、AIに「パソコンのウィンドウを一覧表示して」と話しかける。AIがウィンドウ一覧を返せれば、python.exe と server.py のパス設定は正しい。

ビジュアルチャネル設定（describe用、オプション）

list_targets が返す channels.vision は状態を示す：ready（キーあり）または no-key（キーなし）。OpenAI互換APIを使用、任意のベンダー：

3つの設定方法から選択：

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~6秒）

• クリック：ネイティブDOM click（物理ヒットテストのオーバーレイを回避）

• 入力：Input.insertText による実際の入力パイプライン（Quill などのエディタと互換）

• 要素座標：CSS×DPR+ウィンドウ位置の近似（操作は座標に依存しない）

未設定でも使用に影響なし：この種のアプリは自動的にローカルOCRチャネルにフォールバックし、画面読み取りと操作は問題なく可能。

ツールボックス：7つのMCPツール

ルール：snapshot/act は focus_target の後に呼び出す必要がある。

act アクション詳細

戻り値構造 {ok, verify, detail}：

• ok: アクションが実行されたか

• verify: 実行後の自動検証結果

  • changed / matched：画面が実際に変化した / 入力内容が確認された

  • no_change / no_match：期待した変化を検出できなかった（アクションが効いていない可能性。最新状態を確認するため再スナップショット推奨）

  • 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~6秒（画面静止時はスナップショットキャッシュヒットでサブ秒まで短縮可能）。WebViewアプリの主要なレイテンシ要因

• 現在はWindowsのみ対応