メインコンテンツへ移動
AIチュートリアル

Jev GUI Delegateチュートリアル：CodexにWindowsとChromeのGUI操作を委任する

このチュートリアルでは、WindowsへのJev GUI Delegateのインストール、オフラインテストの実行、Codexとの接続方法を解説し、タスク契約、決定論的マッチング、Jevによる意味的な選択、結果の検証、障害復旧の仕組みについて説明します。

約16分で読了
Jev GUI Delegateチュートリアル：CodexにWindowsとChromeのGUI操作を委任する

プロジェクト概要

Jev GUI Delegate は、Codex 向けの Windows および Chrome GUI 委譲プロトタイプです。メインモデルはタスクの目標と受け入れ条件を提示し、ローカルコントローラーは画面の観察、コントロールの照合、アクションの実行を担当し、各ステップで実際の結果を確認します。コントローラーは、決定的なルールでは処理できない意味的な選択に直面した場合にのみ TypeSafe Jev を呼び出します。

解決しようとしている中心的な課題は、メインモデルがウェブページやデスクトップアプリを段階的に操作すると、画面を繰り返し読み取り、コントロールを選択し、ツールの戻り値を処理する必要があり、コストの高い操作ループが生じることです。Jev GUI Delegate は、明確に検証可能な一連の操作をローカルコントローラーに連続して実行させながら、状態確認、異常復旧、ユーザーによる操作引き継ぎの能力を維持します。

このプロジェクトは、個人が設計し、AI の支援で実装し、継続的に検証しているプロトタイプです。タスク契約、ツールのオーケストレーション、復旧メカニズム、権限チェック、テスト、フィードバックによる反復改善がプロジェクトの貢献に含まれます。Jev モデル、TypeSafe SDK、Codex、ブラウザープラグインは上流製品です。

ワークフロー

  1. Codex のメインモデルが目標と受け入れ条件を送信します。

  2. タスクを検証可能なローカルタスク契約に整理します。

  3. コントローラーが現在の画面を観察し、決定的なコントロール照合を試みます。

  4. 直接判断できない場合、コントローラーが Jev を呼び出して意味的な選択を行います。

  5. Chrome の操作はホストが提供する公式ブラウザーセッションを通じて実行し、Windows の操作は UI Automation を通じて実行します。

  6. コントローラーが実際の結果を検証し、進捗を保存したうえで、続行、復旧、一時停止、またはメインモデルへの追加情報要求を判断します。

このワークフローは個人のブラウザー設定をコピーせず、Cookie も取得しません。Chrome 経路は Codex ホストが提供する互換性のある公式ブラウザーセッション API に依存しており、リポジトリ自体がそのセッションを作成したり代替したりすることはできません。

主な機能

2 つの GUI 実行経路

  • Chrome：ホストが提供する公式ブラウザーセッションを再利用します。

  • Windows：Windows UI Automation を使用して、アクセス可能なデスクトップコントロールを操作します。

明示的なタスク契約

タスク契約には、目標、許可されたアクション、操作範囲、必要な入力、実行手順、成功条件を明確に記述します。これにより、コントローラーは実行前に権限と範囲を確認し、実行後に成功条件に基づいてタスクが本当に完了したかを判断できます。

必要に応じた Jev の呼び出し

ローカルルールで決定できるコントロールはコードで直接照合し、テキストの意味や候補項目の意味を理解する必要がある場合にのみ Jev を呼び出します。プロジェクトは実際の状況に応じてモデル呼び出し回数 0 を記録し、それを誤って成功した Jev 推論として計上することはありません。

連続実行と復旧

コントローラーは実行進捗を保存し、入力不足、部分的な選択ミス、一時停止、キャンセル、ユーザーによる操作引き継ぎなどに対応できます。送信アクションが成功したか確認できない場合は、重複送信のリスクを下げるため、自動的に再実行しません。

結果と安全性のチェック

システムは操作前に本人確認、認可、範囲を照合し、操作後に実際の値またはページ状態を確認します。モデル使用量と失敗原因は別々に記録され、コストの問題と実行の問題を区別しやすくなっています。

実行環境と前提条件

プロジェクトは以下の環境を対象としています。

  • Windows x64

  • Python 3.12

  • Node.js

  • ネイティブ GUI 操作用の対話型デスクトップ

  • Chrome 経路を使用する場合は、Codex ホストが提供する互換性のある公式ブラウザーセッション API

プロジェクトは C:\jev\jev-bridge にインストールすることを推奨します。一部の旧来のコマンドと Codex skill の例では、この場所をデフォルトで使用しています。別のディレクトリを選択する場合は、関連する例と設定も同時に変更する必要があります。

プロジェクトのインストール

ステップ 1：リポジトリをクローンして仮想環境を作成する

git clone https://github.com/YUTA-fywoo/jev-gui-delegate.git C:\jev\jev-bridge
cd C:\jev\jev-bridge
py -3.12 -m venv .venv

ステップ 2：固定済みの依存関係をインストールする

.\.venv\Scripts\python.exe -m pip install --require-hashes -r requirements.lock

--require-hashes はロックファイル内のハッシュに基づいて依存関係をインストールし、インストール内容がプロジェクトの記録と一致することを確認するのに役立ちます。サードパーティー依存関係のディレクトリはリポジトリで公開されていないため、原作者の配布元からインストールしてください。

ステップ 3：ランタイムを準備する

.\.venv\Scripts\python.exe scripts/setup-runtime.py

ステップ 4：オフラインテストを実行する

.\.venv\Scripts\python.exe -m unittest discover -s gui_delegate/tests -p "test_*.py"

これらのテストは、コントローラー、復旧フロー、境界条件を対象としています。オフライン回帰テストでは合成データと制御された代替実装を使用しており、実環境での GUI 操作と同等ではなく、リアルタイムの Jev リクエストを装うこともありません。より完全な結果については、リポジトリの リリース検証ドキュメントを参照してください。

Jev キーの設定

キーは、ローカル環境変数 TYPESAFE_API_KEY または Windows 資格情報マネージャーから提供できます。プロジェクトでは、set-key.cmd が開くローカル入力ウィンドウを使用して設定することを推奨しています。

set-key.cmd

キーを Git リポジトリ、タスク契約、チャット内容に書き込まないでください。インストール先のマシンで生成される chrome-runtime.json は無視されるため、リポジトリに原作者のマシン上の環境パスが含まれることはありません。

Codex への登録

プロジェクトを Codex に接続する場合は、プロジェクトディレクトリで以下のインストールスクリプトを実行します。

install.cmd
gui-install.cmd

インストーラーはユーザー単位の MCP、skill、ルーティング設定を変更し、バックアップを保持して競合を確認します。マシン上に同名のディレクトリがすでに存在する場合は、先に用途を確認してください。インストーラーが、そのマシンで使用中のプロジェクトを直接上書きすることはありません。

インストール可能な個人用 Codex skill は gui_delegate/skill/SKILL.md にあります。プロジェクトをデフォルトディレクトリ以外にインストールした場合は、パスに関係する例も確認してください。

基本的な使用方法と検証

ローカルの準備状態を確認する

インストール後、次を実行できます。

health.cmd

health.cmd はコンポーネントの準備状態だけを確認し、リアルタイムの Jev 検証が実行済みであることや、現在のマシンが実際の GUI シナリオの受け入れ検証に合格していることを示すものではありません。

リアルタイム検証を実行する

プロジェクトが提供する verify.cmd などのリアルタイム検証フローは、Jev サービスを呼び出します。

verify.cmd

実行前にキーが正しく設定されていることを確認し、オフライン回帰テストの結果とリアルタイムサービスの結果を区別してください。README では、過去の開発環境における「ローカルで検証済み」という状態を、すべてのインストール環境がそのまま継承できる結論とはみなしていません。

委譲に適したタスクを設計する

このプロトタイプは、境界が明確で、手順を限定でき、結果を検証できる GUI 操作に適しています。コントローラーにタスクを渡す際は、少なくとも以下を明確にしてください。

  • 目標：最終的にどのような状態にする必要があるか。

  • 範囲：どのページ、ウィンドウ、オブジェクト内で操作を許可するか。

  • 許可されたアクション：コントローラーが実行できるインタラクションの種類。

  • 入力：タスクの実行に必要で、使用を許可されたデータ。

  • 手順：連続して実行できる操作段階。

  • 成功条件：完了後に確認できる実際の値またはページ状態。

たとえば、指定されたページ範囲内で対象のコントロールを探し、承認済みの入力を入力し、ページ状態によって結果を確認するようコントローラーに要求できます。具体的な契約フィールドと結果モデルは gui_delegate/schema.py の実装を基準とし、README で定義されていない形式を独自に仮定しないでください。

ソースコードの読み進め方

実行メカニズムを理解したり、二次開発を行ったりする必要がある場合は、以下の順序で読むことができます。

  1. gui_delegate/schema.py：タスク契約、状態、結果モデルを理解します。

  2. gui_delegate/controller.py：コントローラーが実行ループをどのように構成しているかを確認します。

  3. gui_delegate/drivers.py：ドライバーと構造化された画面観察について理解します。

  4. gui_delegate/security.py：範囲、認可、入力チェックを確認します。

  5. gui_delegate/chrome_gateway.mjs：公式ブラウザーセッションの入口を理解します。

  6. jev_client.py：Jev SDK のラッパー、バージョンチェック、使用量の記録を確認します。

  7. gui_delegate/tests：テストを通じて復旧ロジックと境界動作を理解します。

高度な使用に関する提案

決定的な照合を優先する

コントロールを安定した属性や構造化情報で識別できる場合は、まずローカルコードで照合してください。Jev を呼び出すのは意味的な判断が必要な場合だけにすることで、プロジェクトの設計に沿うだけでなく、モデル使用量も正確に記録できます。

各ステップに観察可能な結果を設定する

「ボタンをクリックする」といったアクションだけでなく、クリック後に表示される値、コントロールの状態、ページの変化も定義してください。プロジェクトでは、ツール呼び出しが成功したことをそのままタスク成功とみなさず、実際の結果を確認することを重視しています。

送信系アクションは慎重に扱う

送信後の結果が不明確な場合、失敗したと仮定して自動的に操作を繰り返さないでください。このプロジェクトでは、結果が不明な場合に送信を自動再実行しないことを明確にしています。このような状態では、一時停止して進捗を保存し、ユーザーまたはメインモデルに確認を委ねるのが適切です。

入力不足と選択ミスを分けて処理する

必要な入力が不足している場合は、入力を補ってから続行してください。部分的な意味的選択を誤った場合にのみ、その選択を修正します。これにより、タスクを最初から再実行することを避け、すでに検証済みの進捗を維持できます。

Jev のバージョンアップ後に再検証する

現在の settings.json では、過去のテストに使用した jev-1.13.0 が固定されています。サーバー側のバージョンが変更された場合は、再確認して設定を更新する必要があります。旧バージョンのテスト結果を新バージョンの品質保証とみなすことはできません。サンプルの戦略も、現在のマシンでキャリブレーションが完了していることを意味しません。

ベンチマークテストを正しく理解する

README には、2026 年 9 月 23 日に実施した 2 ラウンドの合成タスクテストが記録されています。各ラウンドには同じ 4 つのタスクと 24 個のアクションが含まれ、両方のタスクグループで 4/4 を完了しました。

  • 第 1 ラウンドでは、Astra token が 2,266,693 から 236,295 に減少し、89.6% 削減され、エンドツーエンドのタスク速度はベースラインの 3.05 倍でした。

  • 第 2 ラウンドでは、Astra token が 2,256,091 から 192,752 に減少し、91.5% 削減され、エンドツーエンドのタスク速度はベースラインの 3.53 倍でした。

ここでの Astra token にはキャッシュされた入力が含まれ、Jev の追加使用量は別途集計されています。2 ラウンドで繰り返されたのは同じ 4 つのタスクであり、8 種類の独立したシナリオを意味するものではありません。これらの数値は請求額の削減率でもなく、すべてのアプリケーション、任意のタスク、またはあらゆるデプロイ環境で同じ結果が得られることを証明するものでもありません。初期の 3 タスク版では、キャッシュされていない token の結果は改善しませんでした。詳しい範囲についてはテスト説明を確認してください。

既知の制限

  • プロトタイプは、読み取り可能な DOM またはアクセシビリティ情報に依存します。

  • Canvas、画像理解、安全なデスクトップ、一部のフレームワーク横断型コントロールは直接処理できない場合があります。

  • ホストで公開されていない機能については、メインモデルによる追加処理が必要になる場合があります。

  • Chrome 経路は、互換性のあるホスト公式セッションから独立して実行することはできません。

  • 過去のマシンでの検証記録は、新しいインストール環境が受け入れ検証に合格したことを意味しません。

  • 実行ログ、ブラウザー設定、キー、個人タスクの資料、マシンのインストール状態、ロールバックパッケージは公開されていません。

まとめ

Jev GUI Delegate は、検証可能な GUI 操作をメインモデルの段階的なループから分離し、ローカルコントローラーによって決定的な照合、必要に応じた意味的選択、状態検証、障害復旧を実行します。インストール時は、まず固定済みの依存関係、ランタイム設定、オフラインテストを完了してから、キーを設定し、Codex に接続してください。実際の使用では、明確なタスク範囲、観察可能な成功条件、慎重な送信復旧戦略、バージョン変更後の再検証が、信頼できる結果を得るための鍵となります。

上流コンポーネントの詳細については、TypeSafe ドキュメント、MCP Python SDK、pywinautoをご覧ください。