BraveCowNoFear/desktop-control-for-windows

Desktop Control for Windows（Windowsデスクトップ制御）

概要

このスキルを使用すると、人間のように高速に可視Windows UIを操作できます。スクリーンショットを撮り、ピクセルから推論し、ターゲットウィンドウをアクティブにし、バンドルされたスクリプトを通じてキーボード/マウス操作を実行します。アクティブなワークフローはローカルのPython自動化のみです。

このスキルには2つの役割があります：

• Coordinator（調整役）：UI Workerではない任意の深さのエージェント。可視UI制御が必要かどうかを判断し、委任が利用可能な場合は1つのUIタスクをUI Workerに委任し、委任が本当に利用できない場合にのみツール/ポリシーブロッカーを報告します。
• UI Worker（UI作業者）：すでに委任されたエージェントで、スクリーンショットを撮り、ピクセルを検査し、scripts/ui_control.pyを直接実行します。

必須の委任ゲート：ライブWindows UI制御タスクの場合、まず与えられたプロンプトから自分の役割を判断してください。このUIタスクのUI Worker/画面制御Workerとして明示的に生成されていない場合は、より大きなタスクのサブエージェントであってもCoordinatorです。スクリーンショットを撮ったり、スクリーンショットを表示したり、scripts/ui_control.pyを呼び出したり、ライブ画面イメージを自分で検査したりしないでください。専用のUI Workerを1つだけ委任してください。spawn_agentまたは同等の委任ツールが利用可能な場合、このスキルのアクティブな使用はWorkerを作成するための承認となります。ユーザーにマジックワードやパスフレーズ、追加確認を求めないでください。自分がすでにUI Workerである場合、またはこのスキル自体をデバッグ/編集している場合にのみ、委任をスキップしてください。

再帰的なUI Worker委任は禁止です。通常のタスクエージェントは2〜3階層までネストされていても、自分の可視UIフェーズ用に1つの専用UI Workerを作成できます。リーフのUI Worker自身は、追加のエージェントを生成、委任、メッセージ送信、待機してはいけません。バンドルされたスクリプトを使用してローカルでUI作業を行い、簡潔なテキストレポートを返してください。

グローバルUIロック：すべてのライブUI Workerはscripts/ui_control.pyを通じて1つのロックファイルを共有します。UI WorkerはUIフェーズの開始時にロックを取得し、返された--lock-tokenをすべてのスクリーンショット/ウィンドウ/マウス/キーボード/クリップボードコマンドに渡し、戻る前にロックを解放する必要があります。別のWorkerがすでにロックを保持している場合は、待機するか、ビジーロックの詳細とともにpartialを返します。これにより、並列エージェントがマウス、キーボード、フォアグラウンドウィンドウ、クリップボードを巡って競合するのを防ぎます。

ロケール依存のテキスト入力：WeChatファイル転送アシスタントなどの名前付きUIターゲットを検索する前に、UIロックを保持した状態でアプリの言語/表示ラベルを確認してください。UIが中国語の場合、中国語ラベルをASCII Unicodeエスケープとしてtype ... --decode-unicode-escapes --method pasteまたはclipboard set ... --decode-unicode-escapesに渡してください（例：\u6587\u4ef6\u4f20\u8f93\u52a9\u624b）。ネストされたプロンプト、シェル引数、コマンドファイルを通じて生の中国語テキストを入力しないでください。UIが英語の場合は、英語ラベルまたはfilehelperなどのASCIIセーフなエイリアスを使用してください。言語が判断できない場合は、生の非ASCIIテキストよりもスクリプト経由のUnicodeエスケープ入力を優先し、結果として得られるターゲットを操作前に確認してください。

ソースはClawHubリポジトリbreckengan/control v1.0.0からローカルデスクトップ制御パターンとして移行されました。

移行範囲

移行されたローカル制御機能：絶対/相対マウス移動、PyAutoGUIによるスムーズ時間経過移動、左/右/中/ダブルクリック、マウスダウン/アップ、マウス長押し、ドラッグ、縦/横スクロール、マウス位置、キーストロークまたはクリップボード貼り付けによるテキスト入力、ホットキー、キーダウン/アップ、キー長押し、スクリーンショット、領域スクリーンショット、ピクセルカラー、画像マッチング、画面サイズ、ウィンドウ一覧/アクティブ/アクティブ化/情報/最小化/最大化/復元/閉じる、クリップボード設定/取得、フェイルセーフ、オプションの承認、厳格な境界チェック、JSONLアクションログ、バッチプラン。

意図的にコピーしなかったもの：アップストリームのデモスクリプトとルールベースのai_agent.pyアプリデモ。Codexでは、高レベルの推論はアクティブなエージェントループに残し、planは決定論的なバッチ処理に使用してください。

Coordinatorプロトコル（UI Workerではない任意のエージェント）

すべての実際のUI制御タスクにおいて、Coordinatorは現在のランタイムポリシーがエージェント委任を許可する場合、必ず1つのUI Workerに委任する必要があります。Workerがスクリーンショット、視覚検査、UI実行を実行します。Coordinatorは、スキル実装をデバッグしている場合を除き、スクリーンショットを撮ったり、スクリーンショットを表示したり、scripts/ui_control.pyを実行したり、画面イメージを検査したりしてはいけません。これにより、画面ピクセル、プライベートウィンドウコンテンツ、視覚的推論がメインの会話コンテキストから除外されます。

直接制御のフォールバック：Coordinatorがランタイムポリシーやツールの利用可能性によりUI Workerを生成またはメッセージ送信できない場合は、UIに触れる前に停止し、そのブロッカーを報告する必要があります。儀式的な認証フレーズをユーザーに求めないでください。それは不足しているツールを作成したり、ランタイムポリシーをオーバーライドしたりしません。自分のコンテキスト内でローカルのスクリーンショット/画像検査/UI制御作業を続行してはいけません。

すでに委任されたUI Workerコンテキスト内にいる場合は、このプロトコルをスキップして、以下のUI Workerプロトコルに従ってください。spawn_agent、send_input、wait_agent、close_agent、OpenSpace委任ツール、または同等のネストWorkerメカニズムを呼び出さないでください。

UI作業を委任する前にreferences/subagent-workflow.mdを読んでください。Coordinatorは以下を行う必要があります：

• 内部で目標を明確にし、サブエージェント用の狭いUIタスクを定義する。
• 正確なターゲットアプリ/ウィンドウ、望ましい結果、安全制限、および不可逆アクションが許可されるかどうかを含める。
• Workerプロンプトに明示的に「あなたはUI Workerです。別のエージェントを生成したり委任したりしないでください。」と記述する。
• サブエージェントにUIに触れる前にグローバルUIロックを取得し、すべてのscripts/ui_control.pyコマンドに--lock-tokenを渡し、戻る前にロックを解放するように指示する。
• サブエージェントにローカルのscripts/ui_control.pyのみを使用するように指示し、リモートビジュアルモデル、ブラウザ拡張機能、外部サービスを使用しないようにする。
• サブエージェントに検索/入力テキストを選択する前にUIの言語を検査するように指示する。中国語UIには--decode-unicode-escapesが必要で、英語UIは英語/ASCIIエイリアスを使用してもよい。
• サブエージェントに使用されたコマンド、最終状態、スクリーンショットファイルパス、および未解決の不確実性を含む簡潔なテキストレポートを返すように要求する。
• ユーザーが特に必要としない限り、サブエージェントの最終回答に生のスクリーンショットを要求しない。

UI Workerプロトコル

このセクションは、プロンプトに明示的に「あなたはWindows UIタスクの画面制御Worker、UI Worker、または委任されたWorkerです」と記載されている場合、またはWindows UI制御用に生成されたエージェント内で既に実行している場合にのみ使用してください。より大きなタスクの汎用サブエージェントであることは、あなたをUI Workerにはしません。その場合は、ライブUI制御が必要なときにCoordinatorプロトコルに従ってください。

厳格なルール：

• 別のエージェントを生成したり、委任したり、OpenSpaceを使用してネストされたWorkerを作成したりしないでください。
• Coordinatorプロトコルを再実行しないでください。
• このスキルのscripts/ui_control.pyと、出力を検査するために必要な通常のローカルシェルコマンドのみを使用してください。
• スクリーンショットは$env:TEMP\codex-ui-subagent\などの一時フォルダに保存してください。
• スクリーンショットは自分のコンテキスト内で検査し、テキストとスクリーンショットパスのみを返してください。
• UIタスクをローカルで完了できない場合は、ブロッカーとともにpartialまたはfailedを報告してください。別のエージェントを生成してエスカレーションしないでください。

Workerループ：

1. lock acquire --owner "<task label>"でグローバルUIロックを取得し、返されたトークンをWorkerコンテキスト内で秘密に保持します。
2. 解放するまで、すべての非ドライランのscripts/ui_control.pyコマンドに--lock-token <token>を渡します。
3. ロックを保持したままstatus --windowsを実行し、新しいスクリーンショットを撮ります。
4. スクリーンショットをローカルで検査し、最も小さな安全なアクションを選択します。
5. 信頼性が高い場合は、マウス座標よりもホットキーとクリップボード貼り付けを優先します。
6. 長いまたはリスクの高いプランの前に--dry-runを使用します。
7. scripts/ui_control.pyで実行します。
8. 別のスクリーンショットまたは画像以外のステータスコマンドで検証します。
9. クリーンアップでlock release --token <token>を使用してロックを解放します。
10. 結果、要約されたアクション、最終的に観測された状態、スクリーンショットパス、および未解決の不確実性を返します。

決定ルール

• 通常のAPI、CLIコマンド、ブラウザ自動化、またはアプリ固有のツールが存在し信頼性が高い場合は、それらを優先してください。
• ライブWindows UI制御には、スクリーンショット、画像検査、またはscripts/ui_control.py呼び出しの前に、必須の委任ゲートを適用してください。
• 高速なローカルWindows制御にはscripts/ui_control.pyを使用します：ホットキー、テキスト貼り付け/タイピング、マウスクリック、ドラッグ、スクロール、スクリーンショット、クリップボード、ウィンドウアクティブ化、ピクセルチェック、画像マッチング、アクションプラン。
• 同じインタラクションループからターゲット座標/状態がすでにわかっている場合を除き、アクションの前にスクリーンショットを撮ってください。
• より高速で安全な場合は、マウスナビゲーションの前にホットキーとクリップボード貼り付けを使用してください。
• planを使用して既知のアクションをバッチ処理し高速化しますが、視覚的な決定ループは段階的に維持します：スクリーンショット、検査、アクション、検証。
• WeChatなどのローカライズされたアプリでは、検索前に可視UIが中国語か英語かを判断してください。ネストされたWorkerコンテキストでは、中国語のラベル/メッセージに--decode-unicode-escapesを使用し、生の中国語テキストがプロンプト、CLI、PowerShell、ログリダイレクト層で維持されることに依存しないでください。

ローカル制御

このセクションはUI Workerとスキルデバッグのみを対象としています。CoordinatorはライブUIタスクでこれらのコマンドを実行してはいけません。最初に1つのUI Workerに委任するか、委任が利用できない場合は委任ブロッカーを報告する必要があります。

スキルディレクトリから実行：

python scripts\ui_control.py lock acquire --owner "wechat-file-transfer"
python scripts\ui_control.py --lock-token <token> status --windows
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\screen.png"
python scripts\ui_control.py --lock-token <token> hotkey ctrl l
python scripts\ui_control.py --lock-token <token> type '\u6587\u4ef6\u4f20\u8f93\u52a9\u624b' --decode-unicode-escapes --method paste
python scripts\ui_control.py --lock-token <token> click --x 500 --y 300
python scripts\ui_control.py --lock-token <token> right-click --x 500 --y 300
python scripts\ui_control.py --lock-token <token> drag 100 100 700 450 --duration 0.5
python scripts\ui_control.py --lock-token <token> scroll -6 --x 900 --y 500
python scripts\ui_control.py --lock-token <token> hold-mouse --x 500 --y 300 --seconds 1.2
python scripts\ui_control.py lock release --token <token>

すべてのコマンドはJSONを出力します。続行する前に、ok、error、出力パス、アクティブウィンドウ、座標を確認してください。

ロック動作：--lock-tokenなしのコマンドは、その単一コマンド用の一時的なロックを取得します。マルチステップの可視UIタスクを行うWorkerは、lock acquireを使用し、フェーズ全体にわたって--lock-tokenを渡す必要があります。そうすることで、他のWorkerがスクリーンショット/アクション/検証ループの間にアクションを挿入できなくなります。グローバルオプション（--lock-tokenなど）はサブコマンドの前に配置する必要があります。例：ui_control.py --lock-token <token> type ...（後ではない）。通常のコマンドで--lock-timeout <seconds>を使用して、別のWorkerを待機する時間を制御します。lock statusを使用して、ロックを取得せずに現在の保持者を確認します。期限切れのロックは古くなったと見なされ、自動的に削除されます。

Windowsでは、scripts/ui_control.pyは起動時にDPI認識を有効にします。スクリーンショット、マウス座標、ピクセル読み取り、ウィンドウ矩形はすべて同じ物理ピクセル座標系として扱ってください。statusがアクティブなデスクトップ/ウィンドウサイズと一致しない画面サイズを報告した場合は、クリックする前に停止して不一致を報告してください。

完全なCLI構文については、references/control-api.mdを読んでください。

ワークフロー

1. グローバルUIロックを取得：

python scripts\ui_control.py lock acquire --owner "short task label"

返されたトークンを、解放するまでのすべてのコマンドで--lock-token <token>として使用します。

2. 状態を検査：

python scripts\ui_control.py --lock-token <token> status --windows
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\codex-ui.png"
python scripts\ui_control.py --lock-token <token> screenshot --out "$env:TEMP\codex-active.png" --active
python scripts\ui_control.py --lock-token <token> snapshot --out "$env:TEMP\codex-state.png" --windows --active

3. ターゲットを前面に持ってくる：

python scripts\ui_control.py --lock-token <token> window activate "Notepad"

4. 最速の信頼できるプリミティブを使用：

• テキストフィールド：type --method paste、中国語エスケープテキストには--decode-unicode-escapesを使用し、その後press enterまたはhotkey。
• メニューとショートカット：hotkey、press、key-hold。
• ボタンとキャンバス：click、double-click、right-click、drag、scroll、hold-mouse。
• 既知のアプリ/ウィンドウターゲット：フルスクリーンキャプチャ/検索の前に、snapshot --active、screenshot --active、screenshot --window "<title>"、find-image --active、またはfind-image --window "<title>"を使用します。Workerが同じステップでウィンドウメタデータとスクリーンショットを必要とする場合はsnapshot --windowsを使用します。ウィンドウターゲットは、Windowsが非表示の境界オフセットを報告する場合、可視のプライマリ画面にクランプされます。
• 繰り返しの決定論的シーケンス：JSONアクションファイルを作成し、plan --fileで実行します。
• 未知の可視ターゲット：UI Workerはスクリーンショットを撮って検査し、座標または画像マッチングを使用する必要があります。

5. 別のスクリーンショットまたはステータス呼び出しで検証します。

PowerShellでは、生成されたJSONに対してplan --jsonよりもplan --fileを優先してください。ネイティブコマンド引数として渡される複雑なJSONは、PowerShellがPythonで受け取る前に再引用される可能性があります。

プランアクションはアクション固有のフィールドのみを設定できます。dry-run、require-approval、no-failsafe、strict-bounds、pause-after、log-file、lock-token、lock-timeout、lock-ttl、lock-owner、plan-file、plan-json、func、stdinなどのグローバル/制御フィールドを個々のプランアクション内に配置しないでください。コントローラーはそれらを拒否し、サブアクションがWorkerのロックと安全設定をバイパスできないようにします。プランテキスト入力には、text値またはfileを使用してください。プランで指定された選択肢とブール値は、直接のCLI引数と同様に検証されます。