agent-desktop-windows

agent-desktop-windows

observe-act ループ、ref システム、JSON エンベロープ、セッション、トレースはすべてのプラットフォームで共通です。このファイルでは、Windows 固有の違いのみを説明します。

Windows 10 1809 以降／Windows Server 2019 以降（x64 または ARM64）が必要です。サインイン中のユーザーの対話型デスクトップセッションで実行してください。セッション 0（サービスと SYSTEM タスク）、Server Core、セキュアデスクトップ（UAC プロンプト、サインイン画面）、ロックされたデスクトップ、別のユーザーのセッションはサポートされていません。そこでの観察、操作、キャプチャは失敗するか、何も返しません。

機能一覧

グループ	コマンド	Windows でのステータス
観察	snapshot、find、get、is、screenshot	動作します。サーフェスは window、focused、Chromium のモーダルは sheet、開いているアプリケーションメニューは menu です
サーフェス	list-surfaces	動作します。プロセスごとに window、focused、sheet を一覧表示し、メニューが開いている場合は item_count を含む menu も表示します
シェルサーフェス	open-system-surface	start-menu、taskbar、system-tray、system-tray-overflow、action-center で動作し、snapshot --surface <kind> が読み取るウィンドウを返します。quick-settings は action-center を指定して PLATFORM_NOT_SUPPORTED を返します
ref 操作	click、right-click、type、set-value、clear、select、toggle、check、uncheck、expand、collapse、scroll、scroll-to	ヘッドレスモードと --headed モードでセマンティック操作が動作します。right-click と type には --headed が必要で、ヘッドレスモードでは POLICY_DENIED を返します
マルチクリックとフォーカス	double-click、triple-click、focus	グローバルな --headed のみで動作します
キーボードとマウス	press、hover、drag、mouse-click、mouse-move、mouse-wheel	動作します。カーソルを動かす入力には --headed が必要です。First Contact では press --app を説明します
入力の押下状態	key-down、key-up、mouse-down、mouse-up	すべてのプラットフォームでフェイルクローズし、ACTION_NOT_SUPPORTED になります。ヘッドレスモードの mouse-down または mouse-up は、先に POLICY_DENIED を返します
アプリとウィンドウ	launch、close-app、list-windows、list-apps、focus-window、resize-window、move-window、minimize、maximize、restore	動作します。First Contact では launch が受け取る名前を説明します
ディスプレイ	list-displays	動作します
クリップボード	clipboard-get、clipboard-set、clipboard-clear	動作します。テキストと画像の内容に対応します
待機	wait	ms、--element、--window、--text、--menu、--menu-closed、--event、--notification に対応します
通知	list-notifications、dismiss-notification、dismiss-all-notifications、notification-action	アクションセンター経由で動作します。アクションセンターが閉じている場合は --headed を指定してください
カーソルオーバーレイ	cursor-overlay	動作します。enable は、レンダラーがパイプ経由で応答した後にのみ data.rendered: true を返します。references/shell-and-overlay.md を参照してください
システム	status、permissions、version、batch、skills、session、trace	動作します

最初に確認すること

• PowerShell では、すべての ref を引用符で囲んでください。 PowerShell は引用符で囲まれていない @token をスプラッティング演算子として読み取り、バイナリが受け取る前に引数を削除するため、set-value @s8f3k2p9:e1 hi は INVALID_ARGS で失敗します。set-value '@s8f3k2p9:e1' hi と記述してください。cmd.exe と bash では引用符は不要です。
• 別のウィンドウの背後にあるウィンドウは操作できますが、最小化されたウィンドウは操作できません。 最小化されたウィンドウのすべての要素は offscreen を返し、ref アクションは失敗します。restore --app <image> を実行し、もう一度スナップショットを取得してください。反射的に focus-window を使わないでください。ユーザーのフォアグラウンドを奪ってしまいます。
• 権限ダイアログはありません。 permissions は automation を not_required として報告します。アクセス制御は昇格境界によってのみ行われます。
• Chromium アプリと Electron アプリでは、状態が落ち着く前にツリーが不完全に読み取られることがあります。 ツリーが空だと判断するのではなく、snapshot に長めの --timeout-ms を指定してください。
• ブロックされるショートカット。 alt+f4、win+l、win+d、alt+tab、win+r、win+x、win+e、ctrl+shift+esc およびこれらに修飾キーを追加した組み合わせは、--force を指定しない限り拒否されます。組み合わせでは、cmd と meta は Windows キーを指すため、meta+c はシェルのショートカットです。コピーするには ctrl+c と記述してください。
• type には --headed が必要です。 SendInput によるキー入力の合成のため、strict-headless での type は POLICY_DENIED を返します。set-value を使うか、--headed を指定してください。フィールドから読み取り可能な Text 選択範囲が取得できない場合は delivered_unverified（verification_scope: "unavailable"）で終了し、取得できる場合は検証できます。新たに get を実行して確認してください。
• press --app は、プロセスごとのターゲット指定を行わず、フォアグラウンドキューに書き込みます。 フォアグラウンドでないアプリに対するヘッドレスの press は、フェイルクローズで失敗します。非対話型の呼び出し元（サービス、スケジュールされたタスク、CI ジョブ）では delivered_unverified になります。
• launch には絶対パス、または System32 か Windows ディレクトリにある拡張子なしの名前（notepad または notepad.exe）を指定します。表示名は指定できません。 実行中のアプリを見つけるには list-apps を使ってください。
• 通知： アクションセンターを閉じた状態で list-notifications を実行するには、--headed が必要です。単一項目を対象にする dismiss-notification と notification-action には、--headed に加えて、INDEX の項目に対する --expected-app または --expected-title が必要です。
• サーフェス： 開いているメニューまたはコンテキストメニューは menu サーフェスです。Windows は menubar サーフェスを公開しません。
• シェルのクロームを表示するコマンドはフォアグラウンドを取得します。 strict headless では、何も表示される前に POLICY_DENIED で拒否されます。
• 状態を変更するアクションは一度だけ実行し、その後、読み取り直して検証してください。 delivered_verified は、読み戻した値が一致したことを意味します。details.kind: "post_action_verification" を伴う ACTION_FAILED は、アクションは反映されたものの読み戻した値が異なることを意味します。details.post_state を読み、再試行しないでください。アプリが再フォーマットする set-value は失敗として読み取られます。references/troubleshooting.md を参照してください。
• 署名されていないバイナリの警告は想定内です。 references/troubleshooting.md を参照してください。

Windows での相違点

• ref アクションは、ヘッドレスモードでも --headed モードでも、意味的な UI Automation 呼び出しです。ただし、right-click、double-click、triple-click、type、focus は、物理操作を行うかフォーカスを取得するため、--headed が必要です。
• カーソルオーバーレイがアクションごとの移動を再生するのは、ヘッドレスの意味的アクションのみです。--headed のアクションでは、実際のカーソルが移動します。

リファレンス

• references/shell-and-overlay.md：open-system-surface、トレイとタスクバーのサーフェス、通知、カーソルオーバーレイ、ホストされた（UWP）ウィンドウの ID、メニュー検出の対応範囲について説明します。
• references/permissions-and-elevation.md：整合性レベル、UIPI、ブロックされるキーの組み合わせ、保護されたプロセス、プロセス間インタラクションリースについて説明します。
• references/chromium-and-electron.md：状態が落ち着くまでの時間、別のウィンドウに隠れた際の問題、WPF の誤ったプロバイダーに関する問題、名前のないウェブコンテンツについて説明します。
• references/troubleshooting.md：症状と原因の対応表、アクション検証の結果、ヘッドレスでのドキュメント保存、インストール時の警告について説明します。

バイナリから任意のファイルを読み取るには、次を実行してください。 agent-desktop skills get agent-desktop-windows references/troubleshooting.md。