agent-desktop

agent-desktop は何をしますか？

agent-desktop は、AI エージェントが OS のアクセシビリティツリーを通じてデスクトップアプリケーションを観察・操作できるようにする CLI ツールです。これはツールであり、エージェントではありません。すべてのコマンドは JSON 形式（ok、data、error）で出力します。観察、行動、検証のループはあなたが実行します。

シェル構文

例では POSIX シェルを使用しています。PowerShell では、すべての参照を引用符で囲んでください（'@s8f3k2p9:e1' のように）。裸の @token はスプラッティング演算子として解釈されます。export の代わりに $env:NAME = 'value' を使用し、$(...) や jq の代わりに | ConvertFrom-Json を使用してください。Windows スキルには PowerShell 形式が記載されています。

事前準備

タスクの最初のコマンドの前にこれを実行します。これがツールをインストールする唯一の場です。

1. agent-desktop version を実行します。終了コード 0 なら CLI が存在します: ステップ 4 に進みます。

2. 存在しない場合は、npm でインストールします。npm のみがサポートされるパスです:

   npm install -g agent-desktop

   Homebrew、Scoop、ダウンロードしたアーカイブ、または古いバージョンを試さないでください。このスキルは npm が解決するバージョンに基づいて記述されています。npm が PATH にない場合は、node -v と where npm（Windows）または which npm（macOS、Linux）を実行し、結果を報告してください。他のパッケージマネージャーを推測しないでください。

3. 再度 agent-desktop version を実行します。それでも失敗する場合は、停止してユーザーに次の情報を伝えてください: インストール出力の最後の 20 行、agent-desktop --help が実行できるかどうか、そしてあなたがいる OS。自分でスクリーンショットやマウス自動化に頼らないでください。

4. agent-desktop status を実行します。これにより、プラットフォーム、権限、supported_surfaces が報告されます。macOS でアクセシビリティ許可が不足している場合はここに表示されます。自分で許可を付与しようとせず、ユーザーに agent-desktop permissions --guide を実行するよう指示してください。

5. agent-desktop skills get platform を実行します。これにより、バイナリが動作している OS（macOS、Windows、Linux）のスキルが読み込まれ、このファイルと矛盾する場合はそちらが優先されます。

6. フラグと構文については、agent-desktop <command> --help を実行してください。このスキルはフラグリストを繰り返さないため、--help は常にインストールされているバージョンと一致します。

agent-desktop skills get desktop がこのファイルと異なるルールを出力する場合、バイナリが正しいです: このファイルはコピーであり、バイナリが実際にあなたが操作しているものです。

ループ

役割や正確な名前がわかっている場合は find を使用します。それ以外の場合は、まずアプリ全体をマッピングし、次に1つの領域に掘り下げます。

agent-desktop snapshot --skeleton --app "Notes" -i --compact   # 浅いマップ、カットされたブランチの children_count
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # 1つの領域に掘り下げる
agent-desktop click @s8f3k2p9:e12                              # 修飾された参照に対してアクションを実行
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # 検証: 同じ領域を再読み取り

• 小さいアプリはスケルトンの必要はありません。完全な snapshot -i を取得してください。
• -i はインタラクティブなノードのみを保持するため、行の静的テキストラベルは削除されます。繰り返されるボタンがどの行に属するかを判別するには、--root でその行のコンテナに掘り下げ、-i を省略してください。Windows と Linux では、これにより行が読み取られますが、そのボタンはアクション可能にはなりません: 他の行で繰り返されるボタンはウィンドウ内で双子となり、その参照は拒否されます（「参照」を参照）。
• --root での掘り下げは、その参照を同じスナップショットIDに追加します。掘り下げたサブツリーの外側の参照と、掘り下げたルート自体は有効なままですが、すでに内部にあった参照は置き換えられるため、そこでの古い参照は STALE_REF を返します。
• サーフェス（--surface menu、sheet、alert）に対してスケルトンを行わないでください。サーフェスはすでにフォーカスされています。
• メニュー、シート、アラートを開くアクションは、それを data.surfaces にリストします。次にそのオーバーレイをターゲットにします。
• 非同期ステップの後は、wait を使用してください（references/commands-system.md を参照）。固定スリープはレースの原因になります。

参照

• 出力される参照は修飾されています: @<snapshot_id>:e<N>、例: @s8f3k2p9:e1。そのまま後続のコマンドに渡してください。
• 参照は1回のスナップショットに対して有効です。UI が変更された後は、影響を受けた領域を再掘り下げるか、新しいスナップショットを取得してください。
• アドレス可能な要素のみが参照を取得します。静的テキストや非インタラクティブなコンテナは取得しません。
• コマンドはアクションを実行する前に要素を再識別します。macOS では、参照は要素自身のアドレスを保持するため、同一の双子はそれぞれ自身の参照を維持します。Windows と Linux では、参照は、そのスナップショットがキャプチャしたウィンドウ内で、その役割、ネイティブID、名前、説明が一致し、スケルトンや深さカットの下でもカウントされ、かつ正確に1つのライブ要素が一致する場合にのみ解決されます。そこでの同一の双子には参照パスがありません: --headed mouse-click --xy X,Y のみが1つを選択でき、それはフォアグラウンドになり、Linux Wayland セッションはそれを拒否します。
• STALE_REF: 要素が存在しないか、一致しなくなりました。details.kind は macOS では saved_ref_absent または retained_object_stale です。新しいスナップショットを取得し、新しい参照を使用してください。
• AMBIGUOUS_TARGET: 同一の要素が現れた（saved_ref_ambiguous）、またはキャプチャ時に参照が一意であることが証明されていませんでした（identity_not_unique）。参照を再試行したり、同一の双子を再スナップショットしても同じ拒否になります。ウィンドウ内で一意なコントロールに対してアクションを実行してください。identity_not_unique は、時間内にウィンドウ全体を読み取れなかったスナップショットの後にも発生します: より大きな --timeout-ms で再取得してください。
• TIMEOUT と details.kind: resolution_identity_unknown: ライブ読み取りが応答しなかったため、同一性が証明されていません。何も送信されていません。再試行してください。
• SNAPSHOT_NOT_FOUND: スナップショットIDが期限切れです。再度スナップショットを取得してください。

配送とリトライ

アクションの結果は data.disposition を、エラーは error.disposition を持ち、それぞれに delivery と retry が含まれます。snapshot などの観測コマンドは成功時にはこれらを持ちません。そのエラーと、すべての INVALID_ARGS 拒否は、not_delivered と retry: safe を持ちます。

• disposition.retry が safe の場合のみ、アクションを再試行または代替してください。not_delivered のみが安全です。
• それ以外の配送値は、アクションが到達した可能性があることを意味します。繰り返すと、クリック、タイプ、送信が2回実行されたり、toggle が元に戻されたりする可能性があります。
• 安全でない結果の場合は、ライブ状態を読み取り（get、is、または新しいスナップショット）、それに基づいて判断してください。details.post_state は存在する場合に役立ちます。
• error.code と error.disposition に基づいて分岐してください。メッセージと提案テキストは変更される可能性があります。
• details.retryable: false は、待機しても結果が変わらないことを意味します。別のアプローチを試してください。

ヘッドレスとヘッド付き

参照アクションはデフォルトでヘッドレスです。これらはセマンティックアクセシビリティ呼び出しを使用し、フォーカスを取得せず、カーソルを移動せず、キーを合成せず、クリップボードも使用しません。セマンティックパスが存在しない場合、アクションは失敗します。ユーザーが明示的に物理入力を許可した場合（ダブルクリック、ホバー、ドラッグ、フォーカスなど）にのみ、グローバルな --headed フラグを使用してください。ヘッドレスの失敗から回復するためにヘッド付きモードに切り替えないでください。生の座標（--xy）は決してフォーカスを意味しません。どのアクションが --headed を必要とするかは OS によって異なります: プラットフォームスキルを読んでください。

参考文献

必要なときだけロードしてください: agent-desktop skills get desktop <reference>

参考文献	開くタイミング
commands-observation	snapshot、find、get、is、screenshot、list-surfaces のセマンティクス、部分木、または --root ルールが必要な場合
commands-interaction	click、type、set-value、select、toggle、scroll、press、mouse コマンドのどれを選択するか、またはアクションエラーをデバッグする場合
commands-system	アプリの起動・終了、ウィンドウ管理、クリップボード使用、wait、batch、セッション、マルチエージェントカーソル、トレース、またはスキルのロードを行う場合
workflows	定型的なパターン（フォーム、メニュー、ダイアログ、新しいウィンドウの待機、スクロール検索、ドラッグ）とアンチパターンリストが必要な場合