computer-use

コンピューター操作

orca computer を使ってデスクトップ UI を操作する場合に、このスキルを使用します。対象がウェブサイトまたはウェブアプリの場合は、そのページを表示しているデスクトップブラウザーアプリ／ウィンドウを操作します。

前提条件

• orca computer ... を優先してください。Linux で orca が使用できない場合は、orca-ide computer ... を使用してください。この Orca ワークツリーでは、ローカルの開発ランタイムをテストする場合に限り、./config/scripts/orca-dev computer ... を使用してください。
• --json を優先してください。スクリーンショットのバイトデータは JSON から省略され、screenshot.path に書き込まれます。
• ユーザーから明示的に依頼されていない限り、プッシュ、フォームの送信、メッセージの送信、商品の購入、データの削除、アカウント設定の変更、シークレットの公開は行わないでください。
• アプリに機密情報が含まれている場合は、ユーザーが依頼した内容のみを読み取ってください。

orca status --json
orca computer capabilities --json

基本ループ

orca computer list-apps --json
orca computer get-app-state --app com.spotify.client --json
orca computer click --app com.spotify.client --element-index 42 --json

各アクションから返される最新の状態を使って、次に操作する要素のインデックスを選んでください。要素インデックスはツリーに表示される数値ラベルです。ノイズの多いセクションが省略されると、番号が飛ぶことがあります。そのため、elementCount や「表示されている要素」から有効なインデックスを推測しないでください。要素インデックスは一時的なものであり、遅延、ナビゲーション、フォーカスの変更、スクロール、ウィンドウの変更、アプリの再描画後には古くなります。

アプリセレクター

list-apps で取得したバンドル ID を優先してください。曖昧でない場合はアプリ名でもかまいません。バンドル ID または名前による照合が曖昧な場合に限り、pid:<number> を使用してください。

orca computer get-app-state --app com.microsoft.edgemac --json
orca computer get-app-state --app Spotify --json
orca computer get-app-state --app pid:12345 --json

複数のウィンドウがあるアプリや、タイトルが曖昧なアプリでは、先に list-windows を実行してください。表示された ID が none でない場合は --window-id <id> を優先してください。それ以外の場合は --window-index <n> を使用してください。ウィンドウを選択したら、対象のウィンドウが変わるまで、get-app-state と以降のアクションに同じセレクターを渡してください。

コマンド

orca computer permissions --json
orca computer capabilities --json
orca computer list-apps --json
orca computer list-windows --app <app> --json
orca computer get-app-state --app <app> --json
orca computer get-app-state --app <app> --restore-window --json
orca computer click --app <app> --element-index <index> --json
orca computer click --app <app> --x 100 --y 100 --json
orca computer perform-secondary-action --app <app> --element-index <index> --action <name> --json
orca computer set-value --app <app> --element-index <index> --value "text" --json
orca computer type-text --app <app> --text "text" --json
orca computer press-key --app <app> --key Return --json
orca computer hotkey --app <app> --key CmdOrCtrl+A --json
orca computer paste-text --app <app> --text "text" --json
orca computer scroll --app <app> (--element-index <index> | --x <x> --y <y>) --direction down --json
orca computer drag --app <app> --from-element-index <index> --to-element-index <index> --json
orca computer drag --app <app> --from-x 100 --from-y 100 --to-x 300 --to-y 300 --json

画像情報が不要な場合に限り、--no-screenshot を使用してください。機密性の高いテキストには --text-stdin または --value-stdin を使用し、ペイロードがシェルの履歴に残らないようにしてください。Linux と Windows では、アクションのペイロードは短時間だけ存在するローカル操作ファイルを経由するため、ユーザーから明示的に依頼されていない限り、シークレットを送信しないでください。

printf '%s' "$TEXT" | orca computer set-value --app <app> --element-index <index> --value-stdin --json

アクションのルール

• セマンティックアクションを優先してください。編集可能なフィールドには set-value、コントロールには click を使用し、perform-secondary-action は一覧にあるアクション名に対してのみ使用してください。
• UI を変更するアクションの後は、返された状態を使用するか、get-app-state を再実行してから次の要素インデックスを選んでください。
• type-text は、フィールドにフォーカスし、アプリにテキスト入力先がフォーカスされていることを確認した後にのみ使用してください。合成キーボード入力は未検証として報告されるため、テキストが入力されたと決めつけず、返された状態を確認してください。
• Return、Escape、Tab、矢印キーなどの単一キーまたはナビゲーションキーには press-key を使用してください。修飾キーの組み合わせとキー 1 つからなるホットキー（CmdOrCtrl+A や CmdOrCtrl+Shift+P など）に限り、hotkey を使用してください。プラットフォームをまたいで使用する組み合わせには、CmdOrCtrl+... を優先してください。
• バックグラウンドのアプリでも動作するアクションがありますが、アプリによって異なります。成功しても UI に変化がない場合は、状態を更新し、よりセマンティックなアクションを選ぶか、ウィンドウを前面に戻してフォーカスしてください。
• 値を公開しているテキストフィールドには set-value を優先してください。プロバイダーが更新後の値を読み取れる場合、値が確認済みの書き込みとして報告されることがあります。
• 座標はウィンドウ内の相対座標です。同じ対象ウィンドウの最新のスクリーンショットまたは状態から取得した座標を使用してください。

スクリーンショット

get-app-state はツリーとスクリーンショットを返します。インデックスや操作にはツリーを、視覚的な確認にはスクリーンショットを使用してください。キャプチャに失敗する場合は、通常、対象が非表示、最小化、画面外、または権限によってブロックされています。

click、scroll、drag に渡す座標は、ウィンドウ内の操作座標です。スクリーンショットに scale が 1 以外の値で報告されている場合は、操作前にスクリーンショット上の視覚的なピクセル座標を変換してください。

action_x = screenshot_pixel_x / screenshot.scale
action_y = screenshot_pixel_y / screenshot.scale

ツリーに要素インデックスや要素のフレームがある場合は、そちらを優先してください。スクリーンショットから取得した生の座標は、最新のスクリーンショットのスケールとウィンドウサイズを確認してから使用してください。

Linux と Windows では、スクリーンショットに対象ウィンドウの範囲内にある表示中のデスクトップ領域が含まれる場合があります。視覚的なピクセル情報が重要な場合は、別のウィンドウに対象領域を覆われないよう --restore-window を使用してください。フォーカスを取得できない場合は、他のウィンドウに隠れている可能性があるピクセル情報よりもツリーを優先してください。

アプリに関する注意事項

ブラウザー：Edge、Chrome、Safari などのブラウザーウィンドウでは、アドレス／検索フィールドを直接設定してから Return キーを押してください。通常の文字入力がアドレスバーに送られると決めつけないでください。ブラウザーがすでに最前面にない場合は --restore-window を使用してください。タブが多数ある場合、アクティブなタブと「非アクティブなブラウザータブは省略されています」というマーカーだけが表示されることがあります。これは意図的なノイズ削減として扱い、ユーザーからタブの管理を依頼されていない限り、現在のページ／アドレスバーを操作してください。

Gmail の作成画面など、ブラウザー上のフォームでは、各フィールドを操作した後にフォーカスされている UI 要素を確認してください。ページのテキストフィールドは、DOM フォーカスを移動せずにアクセシビリティ操作を公開することがあります。クリックや set-value を実行してもフォーカス先が変わらない場合は、フォーカスがあることを確認済みのフィールドから Tab／Shift+Tab を使用するか、最新のスクリーンショットから取得したウィンドウ内座標を使用してください。下書きの本文には、フォーカス先を確認したフィールドに paste-text を使用することを優先し、続行する前に返された状態を確認してください。

orca computer get-app-state --app com.microsoft.edgemac --restore-window --json
orca computer set-value --app com.microsoft.edgemac --element-index <addressBarIndex> --value "test123" --json
orca computer press-key --app com.microsoft.edgemac --key Return --json

Spotify：再生をクリックした後は更新してください。UI の変更は非同期で発生することがよくあります。

Slack：アクセシビリティツリーの情報が浅くても、スクリーンショットには有用な情報が含まれている場合があります。依頼された場合、表示中の Slack UI を読むことは問題ありません。ただし、メッセージの送信やワークフローの実行には、引き続き明示的な許可が必要です。

エラー

• app_not_found：list-appsを実行し、バンドル ID を指定して再試行してください。Gmail などのウェブアプリが対象の場合は、そのアプリが表示されているデスクトップブラウザーのアプリ／ウィンドウを選択してください。orca computer ... --app Gmailを変更せずに再試行しないでください。orca computerのアプリセレクターが参照するのはデスクトップアプリであり、ウェブサイト名ではありません。
• app_blocked：停止してください。対象はコンピューター操作が意図的にブロックされています。
• window_not_found / window_stale：list-windowsを実行して現在のセレクターを選び、その後get-app-stateを再実行してください。
• window_not_focused：--restore-windowを付けて一度だけ再試行してください。復元がすでに要求されたというメッセージが表示された場合は、復元の再試行を中止し、アプリを手動で前面に表示するか、権限を確認してください。編集可能なフィールドではset-valueを優先し、キーボード入力が機能したと決めつける前に状態を確認してください。
• element_not_found：インデックスが古くなっています。get-app-stateを再実行してください。
• unsupported_capability：プロバイダーまたはデスクトップ環境ではその操作を実行できません。セマンティックな代替手段を使用するか、メッセージに記載された依存関係が不足している場合はインストールしてください。
• action_not_supported：要素に表示されているアクションを確認し、そのいずれかの名前を使って再試行するか、適切であればクリックまたは値の設定を使用してください。
• value_not_settable：要素は値の直接書き込みを受け付けません。要素にフォーカスを当て、返された状態を確認できる場合に限り、キーボード入力を使用してください。
• element_not_clickable：要素に操作可能なフレームがありません。フレームを持つ親／子要素を使用するか、最新のスクリーンショットからウィンドウ内の座標を選択してください。
• invalid_argument：コマンドのフラグを修正してください。同じコマンドを変更せずに再試行しないでください。
• action_timeout：再試行する前に現在の状態を確認し、その後、より簡単なセマンティックアクションを使用するか、観察に時間がかかる場合は--no-screenshotを指定してください。
• screenshot_failed：ツリーの状態で十分な場合は--no-screenshotを使用してください。メッセージに画面収録またはスクリーンショットの権限が記載されている場合は、orca computer permissions --id screenshots --jsonを実行してください。
• accessibility_error：orca computer capabilities --jsonを実行してください。メッセージにアクセシビリティ権限が記載されている場合は、orca computer permissions --id accessibility --jsonを実行してください。
• ツリーが空、またはスクリーンショットがない場合：アプリに表示可能なウィンドウがない、最小化されている、または権限が必要な可能性があります。
• 権限エラー：orca computer permissions --jsonを実行してください。メッセージに特定の権限が記載されている場合は、orca computer permissions --id accessibility --jsonまたはorca computer permissions --id screenshots --jsonを実行します。セットアップ UI を使用してから、再試行してください。

次のアクション

すでに確認済みでない場合は Orca の状態を確認し、その後orca computer capabilities --jsonを実行してください。Gmail などのウェブサイトまたはウェブアプリが対象の場合は、そのページが表示されているデスクトップブラウザーのアプリ／ウィンドウを特定し、その対象アプリの状態をorca computer get-app-state --app <app> --jsonで取得してください。