device-interaction

デバイス操作

次の場合に起動します：デバイス上でアプリが動作するか確認・テスト・検証するようユーザーから依頼された場合、デバイスでの検証が必要な UI に影響する機能を実装した後、ユーザーが「動作しますか」「これをテストして」「デバイスで確認して」と言った場合、UI が想定どおりに動作しないとユーザーから報告された場合、タッチや操作の問題をデバッグする必要がある場合。 次の場合は起動しません：ユーザーがユニットテストのみを依頼した場合、デバイスでのテストを伴わないビルドのみの依頼、デバイスでのテストを伴わないコードレビュー、シミュレーターの設定に関する質問、UI に影響しない変更（コメント、リファクタリング、UI 以外のロジックなど）。

---

メインエージェント向け

これはサブエージェントのスキルです。 デバイスでの検証が必要な場合は、Agent ツールから呼び出してください。

Agent tool:
- subagent_type: "general-purpose"
- description: "Verify login feature works"
- prompt: "Using the device-interaction skill, verify that the login feature works correctly on session <device-interaction-session>. Launch the app, capture screenshot and UI hierarchy, check that the login button is visible and tappable, and report if the implementation is working correctly."

UI に影響する機能を実装した後は、このスキルを呼び出して、デバイス上で実装が動作することを検証してください。

セッションのライフサイクル

DeviceInteractionStartSession (do this early, runs in the background)
  → DeviceInteractionInstallAndRun (after each code change; includes building)
    → DeviceEventSynthesize (interact + observe, repeatable)
  → DeviceInteractionEndSession (when done — keeping sessions open is resource-heavy)

DeviceInteractionStartSession ツール

デバイスの検出

新しいデバイス操作セッションを開始するときは、デバイス識別子を渡してデバイスを選択するか、省略して現在の接続先を使用します。一致しない値を渡すと、利用可能なターゲットの一覧が表示されます。

DeviceInteractionInstallAndRun ツール

オプションのパラメーター

• commandLineArguments — アプリの起動時に渡される引数です。スキームに既存の引数を引き継ぐには、トークンとして $(inherited) を使用します（例：["$(inherited)", "--reset-state"] を指定すると、末尾に引数が追加されます）。
• environmentVariables — アプリの起動時に環境に設定されるキーと値のペアです。スキームの既存の環境変数を引き継ぐには、キーとして "$(inherited)" を使用します（例：{"$(inherited)": "", "DEBUG_MODE": "1"}）。

スキームの引数と環境を変更しない場合は、どちらのパラメーターも省略してください。

スキームを直接編集するより、これらのパラメーターを優先してください。 これらはその実行時にのみ適用され、ユーザーの設定には影響しません。

---

サブエージェント向け

コードが原因である可能性のある UI の問題（テキストの重なりや判読不能、画像やテキストの予期しない切り抜き、色の誤りなど）は、必ず報告してください。

DeviceEventSynthesize ツール

このツールを使うと、操作を実行してデバイスの状態を確認できます。

階層ファイルの読み取り

階層ファイルには、各要素の計算済み中心位置が含まれています。

UIView {{100, 200}, {50, 30}}, center: {125.0, 215.0}
  UIButton "Login" {{110, 205}, {30, 20}}, center: {125.0, 215.0}

• {100, 200} - 原点位置
• {50, 30} - 幅と高さ
• center: {125.0, 215.0} - 計算済み中心点（タップに最適）

タッチイベントでは、必ず中心座標を優先してください。

操作コマンドの構文

interactionCommand パラメーターでは、次のコマンド構文を使用できます。

コマンド	説明
t <x> <y> [duration]	指定した座標をタップします。保持時間は省略可能です
d <x> <y>	ダブルタップします
t <x1> <y1> f <x2> <y2> [duration]	(x1,y1) から (x2,y2) までスワイプします
b h/p/u/d [duration]	ハードウェアボタン：h=ホーム、p=電源、u=音量アップ、d=音量ダウン
sender keyboard kbd <text>	テキストを入力します。コマンドチェーンの最後に指定する必要があります — kbd 以降の内容はすべてそのまま扱われます（複数のスペースも保持されます）。特殊文字には \u{XXXX} の Unicode エスケープを使用します：\u{000A}（リターン／改行）、\u{0009}（タブ）
w duration	何も操作せず、指定した時間待機します
orientation faceDown/faceUp/landscapeLeft/landscapeRight/portrait/portraitUpsideDown	デバイスの向きを設定します

例：

• "t 100 200" - (100, 200) をタップします
• "d 200 300" - (200, 300) をダブルタップします
• "t 200 600 f 200 200 0.3" - 上にスワイプします（下にあるコンテンツまでスクロールします）
• "t 200 200 f 200 600 0.3" - 下にスワイプします（上にあるコンテンツまでスクロールします）
• "b h" - ホームボタンを押します
• "b h b h" - ホームボタンを2回押して、アプリスイッチャーを表示します
• "b h w 0 b h" - デバイスをスリープ解除してロックを解除します（パスコード未設定のデバイスのみ）
• "sender keyboard kbd hello world" - スペースを含むテキストを入力します
• "sender keyboard kbd hello world" - 複数のスペースを保持してテキストを入力します
• "sender keyboard kbd submit\u{000A}" - テキストを入力してから、リターン／送信キーを押します
• "w 0.3" - 0.3 秒待機します
• "orientation landscapeLeft" - デバイスを横向きに回転させます

標準的なサブエージェントのワークフロー

操作を行う前に、必ず階層構造（およびスクリーンショット）をキャプチャして確認してください。操作後は再度キャプチャし、結果を検証してください。トグルやスイッチなどの複雑なコンポーネントでは、Switch や Slider などのネストされた要素を確認してください。近くにある要素が実際のコントロールに対応している場合があります。完了したら、調査結果をメインエージェントに報告してください。

• 操作せずにキャプチャするには、空のinteractionCommandを指定してDeviceEventSynthesizeを使用します。
• スクリーンショットだけを見て位置を推測しないでください。必ず階層構造の中心座標を使用してください。
• 確信が持てない場合やサムネイルの解像度が不十分な場合は、フルサイズのスクリーンショットを分析してください。

タイミングと再試行

• アプリの起動：セッション開始後、アプリの読み込みに数秒かかる場合があります。操作する前に階層構造をキャプチャし、意味のあるUI要素があることを確認してください。階層構造がほぼ空の場合や起動画面が表示されている場合は、先に進む前にもう一度キャプチャしてください。
• 操作後：タップやスワイプをしても期待した変化が起きない場合は、階層構造を再キャプチャして操作を一度だけ再試行してください（アニメーション中に要素の位置が変わった可能性があります）。一度再試行しても失敗する場合は、無期限に再試行せず、失敗を報告してください。
• 読み込み中の状態：階層構造にスピナーや読み込みインジケーターが表示されている場合は、少し待ってから再度キャプチャしてください。読み込み中の要素は操作しないでください。

成功と失敗の判断

検証時は、次のカテゴリを区別してください。

• 機能上のバグ（必ず報告）：要素をタップしても反応しない、誤った画面に移動する、クラッシュする、データが表示されない、期待されるUI要素がない。
• 表示・レイアウト上のバグ（必ず報告）：テキストの重なり、ラベルの途切れ、画面外に表示される要素、誤った色、配置の崩れ。
• 一時的な状態（バグとして報告しない）：読み込みスピナー、短いアニメーション、キーボードの表示・非表示。切り替えが完了してから再度キャプチャしてください。
• 予期しない終了（必ず報告）：クラッシュ、アプリケーションの終了。プロセスIDを追跡し、プロセスの標準出力をキャプチャして特定してください。
• 想定される動作（バグとして報告しない）：プレースホルダーテキストが表示された空の状態、フォームが未入力のときに無効になるボタン、権限ダイアログ。

エラー処理

• アプリケーションが表示されていない場合は、デバイスの動作が遅い可能性があるため、一度だけ再試行してください。
• タップ対象が不明確な場合は、階層データを読み直して正しい中心座標を確認してください。
• トラブルシューティングのためにランタイムログを確認できます。タイミングのバグが疑われる場合は、該当コードに一時的にprint文を追加すると問題の診断に役立つ可能性があることをメインエージェントに提案してください。
• 問題の詳細と提案を添えて、メインエージェントに報告してください。