XuLan ScreenPilot

XuLan ScreenPilot

Windows の実画面を、AI エージェントが操作できる構造化された要素テーブルに変換します。

English | 简体中文

XuLan ScreenPilot は、座標を推測するためのスクリーンショットではなく、番号付きの要素テーブルをエージェントに提供することで、AI エージェントによる GUI 自動化の典型的な 2 つの課題、つまり 要素が見えないこと と クリックを逃すこと を解決します。エージェントは一度スキャンしてテーブルを読み取り、要素 ID（click / type）で画面を操作する閉ループ方式です。

CPU のみで完全にローカルで動作します。クラウドモデル、GPU、API キーは不要です。

v1.0.0 の主な機能

• コンパクトスキャンモードをデフォルトで有効化 — 番号を割り当てる前に、空の非インタラクティブなシェルと重複するラベルを除外します。一般的なスキャンでは、すべてのインタラクティブなコントロールを保持しながら、要素とプロンプトトークンを約 23% 削減します（compact=false で未加工のテーブルに戻せます。フィルタリングされた内容は meta.compact_removed で確認できます）。
• プライバシー優先の要素ブックをデフォルトで有効化 — 機密性の高いウィンドウ（Notepad、チャットアプリ、ログインダイアログ）のスキャンは通常どおり認識されますが、永続的な要素ブックには書き込まれません（meta.privacy_skip）。明示的に book=true を指定すると、この動作を上書きできます。
• ハングを防ぐ UIA 呼び出し — 応答を停止した対象ウィンドウは、処理が 30 秒以上ブロックされる代わりに、約 2 秒で構造化エラーとして通知されます（メッセージポンププローブ）。UIA 呼び出しには設定可能なタイムアウトが適用され、COM の失敗は分類され、meta.errors.uia_stats に集計されます。
• 曖昧さのない expect のセマンティクス — ビジネス上の待機がタイムアウトしても、ok=false にまとめられることはありません。action_executed により、「クリックは送信されたが証拠が現れなかった」場合と「アクション自体が失敗した」場合を区別できるため、リスクの高いボタンをむやみに再試行しません。
• 必要に応じて最新の切り抜きを取得 — crop_screen / crop_xy の force_refresh を指定すると、操作直後に画面を確認する際、60 秒間のスクリーンショットキャッシュを回避できます。

動作の仕組み

3つのエンジンが並列で動作し、優先順位 UIA > OCR > visual で1つの要素テーブルに統合されます。

エンジン	ソース	対象
uia	Windows UIA アクセシビリティツリー	ネイティブアプリ、ブラウザー（Web アクセシビリティツリーを含む）— 高精度かつ高速
ocr	RapidOCR（onnxruntime、CPU）	コントロールツリーのないゲームや独自描画の UI、全画面テキストのフォールバック
visual	OpenCV の連結成分＋形状検出器	アイコン候補、チェックボックス／ラジオボタン／スライダー／閉じるボタン専用チャネル

統合時には、中心点の包含または IoU ≥ 0.3 によって重複を除去し、要素に上から下、左から右の順に番号を付け、次を生成します。

• elements.json — 要素テーブルのキャッシュ（クリック／入力時に ID で照会）
• annotated_scan.png — 注釈付きスクリーンショット（赤＝UIA、青＝OCR、緑＝visual、各ボックスに ID を表示）

テーブルに加えて、次の機能もあります。

• フレーム間の ID 安定性 — 再スキャンしても同じ要素には同じ ID が維持され、新しい要素には新しい ID が割り当てられます（meta.tracker で維持／新規／消失を報告）。
• バックグラウンドキャプチャ — ウィンドウを前面に表示せずに、PrintWindow で覆われたウィンドウの実際のピクセルを取得します。
• 揺らぎのあるクリック — 物理クリックにガウスジッターと移動軌跡を加え、自動化が機械的に見えないようにします。precise=True を指定するとピクセル単位の精度に戻ります。
• ウィンドウの重なりを認識 — 座標クリックごとに、実際にクリックした最上位ウィンドウを報告します（hit_window）。また、遮られた対象へのクリックを拒否できます（top_must）。
• 2段階ビジョン＋テキストチャネル — 任意の要素をネイティブ解像度で切り出して、細かいテキストやアイコンを読み取れます。SigLIP ベクトルブックを使うと、再スキャンせずに名前または画像から UI 要素を検索できます。
• 時間軸の認識 — トースト通知や一時的なフィードバックのバースト監視、入力後の表示確認、ハング時の ESC プローブ、フレーム間での静的要素と動的要素（UI のベースレイヤーと移動する対象）の分離ができます。
• 業務レベルの待機 — expect {find, mode: appear|disappear} を使うと、画面に業務上の証拠が表示された場合にのみクリックを「成功」と判定します。
• セッションのクリーンアップ — セッションごとの台帳でエージェントが起動したウィンドウを追跡します。タスク終了時に cleanup_windows でウィンドウを閉じます（WM_CLOSE のみ、6段階の安全確認、taskkill は使用しません）。セッションがクラッシュした場合は残存レポートが記録され、次のセッションで自動的に表示されます。

インストール

必要環境：Windows 10/11、Python 3.11 以降、CPU のみ。

git clone <repo-url> screenpilot && cd screenpilot
pip install uiautomation rapidocr-onnxruntime onnxruntime opencv-python numpy pillow pyperclip pyautogui mcp
python screenpilot.py scan                       :: full-screen scan, prints the element table

Python 3.13 でテスト済みです。オプションの要素ブックベクトルチャネルとベンチマークマッチャーには、SCREENPILOT_MODELS_DIR の下にある tokenizers と SigLIP int8 ONNX 重みも必要です。

オプション：セマンティックマッチャーと要素ブックベクトルチャネルでは、SigLIP int8 ONNX モデルを使用します。モデルディレクトリを含むローカルフォルダーを SCREENPILOT_MODELS_DIR に設定してください（README.zh-CN.md §两级视觉与文本通道を参照）。公開ベンチマークのデータセットは SCREENPILOT_DATASETS_DIR に配置してください。

クイックスタート：エージェントのクローズドループ

# MCP tools (stdio server) or the CLI expose the same verbs:
scan_screen(window="记事本")        # 1. scan -> numbered element table
click_element(element_id=7)        # 2. act by id (UIA control-level when possible)
type_text(element_id=3, text="hi") # 3. type into an edit field
click_safe(element_id=12, expect={"find": "设置", "mode": "appear"})   # 4. act only when evidence shows
watch_burst(window="记事本", seconds=3)   # 5. catch transient feedback frames

MCP 設定（例：Claude Desktop／ZCode）：

{"mcpServers": {"screenpilot": {
  "command": "python",
  "args": ["<path>/screenpilot/mcp_server.py"],
  "env": {"PYTHONIOENCODING": "utf-8"}
}}}

ベンチマーク

公開 GUI グラウンディングベンチマーク、固定済みマッチャー、公式スコアリング。GTX 1070 Ti 搭載デスクトップで CPU のみを使用（GPU は未使用）：

ベンチマーク	範囲	acc	oracle*	レイテンシ
ScreenSpot-v2	全 1,272 問	49.61%	88.36%	1 問あたり 1.94 秒
ScreenSpot-Pro	Windows、層化抽出した 200 問（4K の比率が高い）	18.00%	78.5%	1 問あたり 3.87 秒

* oracle = GT の対象に対応する認識可能な候補が要素テーブルにある場合の値です。マッチャーが完全であると仮定した上限値です。これにより、認識エンジンとマッチャーのどちらに起因するかを分けて把握できます。ScreenSpot-Pro では、その差はほぼすべてマッチャー側にあり（ミスの 88% が match_error）、ロードマップが示す改善対象もそこです。acc の数値は、エージェントの代わりに固定済みのヒューリスティックマッチャーを使用した場合のものです。実際の利用では、エージェントがテーブルを直接読み取るため、実際の体験は acc よりも oracle の値に近くなります。都合のよい数値だけを選ばず、両方を報告しています。

再現方法：python bench/public_sspot.py --dataset v2 ／ --dataset pro（データセットは含まれていません。2つの HF ソースについては docstring を参照してください）。

MCP サーバー

stdio 経由で 20 個のツール（scan_screen、scan_image、click_element、click_safe、click_xy、type_text、press_key、scroll_screen、snap_screen、crop_screen、crop_xy、book_find、watch_burst、verify_typing、probe_hang、split_static_dynamic、window_stack、activate_window、register_window、cleanup_windows）を提供します。scan_image は静的ファイルに対して同じエンジンをオフラインで実行します。book_find は永続的な要素ブック（2 段階：テキスト一致＋SigLIP ベクトル検索）を検索するため、再度表示される UI をフルスキャンなしで検出できます。

セッションのクリーンアップ（登録してからクリーンアップ、sp/cleanup.py）：サーバーは起動時にセッション台帳を開きます。register_window はエージェント自身が起動したウィンドウを記録し、状態を変更する 6 つのツールは、操作によって新たに開かれたウィンドウを自動で記録します（参考情報のみ）。タスクの終了時に、cleanup_windows は 6 段階の安全策を適用し、台帳に記録されたウィンドウを穏やかに閉じます。WM_CLOSE のみを使用し、taskkill は一切使用しません。安全策は、ID の再確認（hwnd+pid）、永続的なホワイトリスト（explorer／タスクマネージャー／自身のプロセス）、自身のセッション台帳のみを対象とすること、他セッションのウィンドウは報告のみとすること、未保存の作業は決して閉じない未保存内容の保護、そして終了しなかったウィンドウについてエスカレーションせず報告する再確認です。セッションが終了した場合は残存ウィンドウのレポートが書き込まれ、次のセッションでは最初のツール呼び出し時に自動で通知されます。

ドキュメント

ドキュメント全文（内部の仕組み、既知の制限、テストスイートの構成を含む中国語版）：README.zh-CN.md。

ステータスとロードマップ

スタジオの画面チャネルとして日常的に使用されている、稼働中のシステムです。既知の課題は隠さずに記載しています。ダークテーマのプロ向けアプリでは暗い背景上の小さな文字によって OCR の再現率が低下し、4K のツールバーアイコンはマッチャーに負荷をかけます。また、Pro ベンチマークのスコアは凍結されたマッチャーによって上限が決まっています。詳しくは README.zh-CN.md §已知限制与坑 をご覧ください。

ライセンス

オープンコアです。このリポジトリのコアエンジンは Apache License 2.0 に基づいて公開されています。商用の付加価値インテグレーション（クローズドソース）は、このリポジトリには含まれていません。

謝辞

RapidOCR、uiautomation、OpenCV、onnxruntime を基盤として構築されています。