android-use

Android デバイス制御スキル

このスキルを使うと、ADB（Android Debug Bridge）経由で接続された Android デバイスを制御できます。UI の状態をデバイスから直接読み取り、実行するアクションを判断する、推論と実行の両方を担います。

前提条件

• USB デバッグが有効になっている Android デバイスが USB 経由で接続されていること
• ADB がインストールされ、PATH からアクセスできること
• デバイスでデバッグが許可されていること（「USB デバッグを許可しますか？」というプロンプトで許可していること）

マルチデバイスのサポート

すべてのスクリプトは、特定のデバイスを対象にするための -s <serial> フラグに対応しています。複数のデバイス（例：実機とエミュレーター）が接続されている場合に不可欠です。

デバイスの確認

、scripts/check-device.sh を実行すると、接続されているすべてのデバイスを確認できます。

Multiple devices connected (2):

  [PHYSICAL] 1A051FDF6007PA - Pixel 6
  [EMULATOR] emulator-5554 - sdk_gphone64_arm64

Use -s <serial> to specify which device to use.

適切なデバイスの選択

ユーザーが次のように指定した場合：

• 「phone」、「my phone」、「physical device」 → [PHYSICAL] デバイスを使用します
• 「emulator」、「virtual device」、「AVD」 → [EMULATOR] デバイスを使用します
• はっきりしない場合は、対象にするデバイスをユーザーに確認します

Serial フラグの使用

対象のデバイスを特定したら、以降のすべてのスクリプトに -s <serial> を指定します。

# Check specific device
scripts/check-device.sh -s 1A051FDF6007PA

# All actions on that device
scripts/get-screen.sh -s 1A051FDF6007PA
scripts/tap.sh -s 1A051FDF6007PA 540 960
scripts/launch-app.sh -s 1A051FDF6007PA chrome

重要： 一貫性を保つため、セッション中はすべてのコマンドで同じ serial を使用してください。

基本的なワークフロー

タスクを受け取ったら、次の知覚とアクションのループに従います。

1. デバイスの接続を確認する — まず scripts/check-device.sh を実行します
   • 複数のデバイスがある場合：ユーザーの意図に基づいて対象を特定するか、ユーザーに確認します
   • 以降のコマンドで使用する serial 番号を控えます
2. 現在の画面状態を取得する — scripts/get-screen.sh [-s serial] を実行して UI 階層を取得します
3. XML を分析する — アクセシビリティツリーを読み、画面に表示されている内容を把握します
4. 次のアクションを決める — 目標と現在の状態に基づいてアクションを選びます
5. アクションを実行する — 必要に応じて -s serial を付け、適切なスクリプトを実行します
6. 少し待つ — UI が更新されるのを待ちます（通常は 500ms～1s）
7. 繰り返す — 目標を達成するまで手順 2 に戻ります

UI XML の読み取り

get-screen.sh スクリプトは、Android のアクセシビリティ XML を出力します。次の主要な属性を確認してください。

<node index="0" text="Settings" resource-id="com.android.settings:id/title"
      class="android.widget.TextView" content-desc=""
      bounds="[42,234][1038,345]" clickable="true" />

重要な属性：

• text — 要素に表示されるテキスト
• content-desc — アクセシビリティの説明（アイコンに便利）
• resource-id — 要素の一意な識別子
• bounds — [left,top][right,bottom] 形式の画面座標
• clickable — 要素がタップに反応するかどうか
• scrollable — 要素をスクロールできるかどうか
• focused — 要素が入力フォーカスを持っているかどうか

タップ座標の計算： bounds="[left,top][right,bottom]" から、中心の座標を計算します。

• x = (left + right) / 2
• y = (top + bottom) / 2

例：bounds="[42,234][1038,345]" → x=540、y=289 をタップ

利用可能なスクリプト

すべてのスクリプトは scripts/ ディレクトリにあります。bash 経由で実行してください。

すべてのスクリプトは、特定のデバイスを対象にするための -s <serial> に対応しています。

デバイス管理

スクリプト	引数	説明
check-device.sh	[-s serial]	デバイスの一覧表示／接続の確認
wake.sh	[-s serial]	デバイスを起動してロック画面を解除
screenshot.sh	[-s serial]	画面イメージをキャプチャ

画面の読み取り

スクリプト	引数	説明
get-screen.sh	[-s serial]	UI アクセシビリティツリーを取得

入力アクション

スクリプト	引数	説明
tap.sh	[-s serial] x y	指定した座標をタップ
type-text.sh	[-s serial] "text"	テキスト文字列を入力
swipe.sh	[-s serial] direction	上／下／左／右にスワイプ
key.sh	[-s serial] keyname	キーを押す（home/back/enter/recent）

アプリ管理

スクリプト	引数	説明
launch-app.sh	[-s serial] package_or_name	パッケージ名でアプリを起動するか、名前で検索
install-apk.sh	[-s serial] path/to/file.apk	デバイスに APK をインストール

アクションのガイドライン

タップするタイミング

• クリック可能な要素を対象にします
• 必ず bounds から中心座標を計算します
• clickable="true" の要素を優先します

入力するとき

• テキスト入力フィールドをタップした後
• フィールドに focused="true" または class="android.widget.EditText" が設定されていること
• 必要に応じて、既存のテキストを先に消去します（すべて選択して削除）

スワイプするとき

• リストやページをスクロールするとき
• 画面間を移動するとき（例：タブを切り替えるには左右にスワイプ）
• 方向：up（下にスクロール）、down（上にスクロール）、left、right

キーを使うとき

• home - ホーム画面に戻る
• back - 戻る／ダイアログを閉じる
• enter - フォームを送信／確定する
• recent - 最近使用したアプリを開く

スクリーンショットを撮るとき

• XML だけでは情報が足りない場合の視覚的なデバッグ
• 視覚的な状態（色、画像など）の確認
• タスクで視覚的な確認が必要な場合

デバイスを起動するとき

• タスクを開始する前（デバイスがスリープ状態になっている可能性があります）
• get-screen.sh が空、または最小限の XML を返す場合
• 操作が機能していないように見える場合（画面がオフになっている可能性があります）
• 注：PIN／パターン／パスワードの入力を回避することはできません。ユーザーが手動でロックを解除する必要があります。

よく使うパターン

アプリを開く

# By package name (fastest)
scripts/launch-app.sh com.android.chrome

# By app name (searches installed apps)
scripts/launch-app.sh "Chrome"

ボタンをタップする

1. 画面を取得します：scripts/get-screen.sh
2. テキストまたは content-desc が一致する要素を探します
3. bounds から中心座標を計算します
4. タップします：scripts/tap.sh 540 289

フィールドにテキストを入力する

1. テキストフィールドをタップしてフォーカスします
2. キーボードが表示されるまで待ちます
3. 入力します：scripts/type-text.sh "your text here"
4. 必要に応じて Enter キーを押します：scripts/key.sh enter

コンテンツを探してスクロールする

1. 画面を取得して、目的の項目が表示されているか確認します
2. 見つからない場合は、スワイプします：scripts/swipe.sh up
3. 画面を再取得し、見つかるか末尾に達するまで繰り返します

ダイアログ／ポップアップに対応する

• 「OK」、「Allow」、「Accept」、「Cancel」などのテキストがある要素を探します
• 適切なボタンをタップします
• または、戻るキーを押して閉じます：scripts/key.sh back

エラー処理

デバイスが接続されていない

• USB 接続を確認します
• USB デバッグが有効になっていることを確認します
• adb devices を手動で実行してトラブルシューティングします

要素が見つからない

• UI が変更されている可能性があります。最新の画面ダンプを取得します
• スクロールして要素を探します
• 要素が別の画面／状態にある可能性があります

操作が機能しなかった

• 操作の間隔を長くします（UI の動作が遅い可能性があります）
• 座標が正しいことを確認します
• ポップアップ／ダイアログが表示されたか確認します

アプリが応答しない

• ホームを押して、アプリを再度開きます
• または、アプリを強制終了して再起動します

実行例

1 台のデバイス

ユーザーのリクエスト：「Chrome を開いて、天気を検索して」

1. scripts/check-device.sh
   → Device connected: Pixel 6
   → Serial: 1A051FDF6007PA
   → Type: Physical

2. scripts/launch-app.sh com.android.chrome
   → Chrome launched

3. scripts/get-screen.sh
   → [Read XML, find search/URL bar]
   → Found: bounds="[0,141][1080,228]" resource-id="com.android.chrome:id/url_bar"
   → Center: x=540, y=184

4. scripts/tap.sh 540 184
   → Tapped URL bar

5. scripts/get-screen.sh
   → [Verify keyboard appeared and field is focused]

6. scripts/type-text.sh "weather"
   → Typed "weather"

7. scripts/key.sh enter
   → Pressed enter to search

8. scripts/get-screen.sh
   → [Verify search results loaded]
   → Task complete!

複数のデバイス

ユーザーのリクエスト：「スマートフォンで設定を開いて」（エミュレーターも起動中）

1. scripts/check-device.sh
   → Multiple devices connected (2):
   →   [PHYSICAL] 1A051FDF6007PA - Pixel 6
   →   [EMULATOR] emulator-5554 - sdk_gphone64_arm64

   User said "my phone" → target the PHYSICAL device
   Serial to use: 1A051FDF6007PA

2. scripts/check-device.sh -s 1A051FDF6007PA
   → Device connected: Pixel 6
   → Serial: 1A051FDF6007PA
   → Type: Physical
   → Status: Ready

3. scripts/launch-app.sh -s 1A051FDF6007PA settings
   → Resolved 'settings' to package: com.android.settings
   → Launched: com.android.settings

4. scripts/get-screen.sh -s 1A051FDF6007PA
   → [Read XML, verify Settings app is open]
   → Task complete!

ヒント

• 焦らずに - Android UI は動作が遅いことがあります。操作の間に待ちます
• よく読む - XML には画面に表示されている内容が正確に記載されています
• 操作を確認する - 各操作の後に画面を取得して、状態を確認します
• スクリーンショットを使う - XML だけでは状況を十分に把握できない場合に使います
• 簡単なところから始める - 複雑なタスクを小さな手順に分けます
• 複数デバイスの場合 - まず複数のデバイスがないか必ず確認し、対象が不明な場合はユーザーに尋ねます
• シリアルを統一する - デバイスを選んだら、すべてのコマンドで -s <serial> を使用します