argent-android-emulator-setup

1. 前提条件

• PATH に Android SDK Platform Tools が必要です。adb が含まれています。
• PATH に Android Emulator が必要です。AVD の起動に使用します。すでに起動中のエミュレーターまたは物理デバイスだけを使用する場合は、adb だけで十分です。
• Android Studio または avdmanager create avd で作成した AVD が必要です。

adb version と emulator -list-avds で確認してください。

2. セットアップ

1. 準備済みのデバイスを見つける：list-devices を呼び出します。platform: "android" のエントリーに絞り込みます。準備済みのデバイス（state: "device"）が先に表示されます。ユーザーが指定していない限り、最初の serial（例：emulator-5554）を選択します。
2. 必要に応じて起動する：Android デバイスが準備できていない場合は、同じ呼び出しの avds リストから取得した avdName: <name> を指定して boot-device を呼び出します。ツールがホットブートとコールドブートを自動で選択します。AVD の default_boot スナップショットを調べ、使用可能であれば厳しい制限時間内に復元し、そうでなければ完全なコールドブートに切り替えます。ホットブートは通常約 30 秒、コールドブートは 2～10 分かかります。いずれかの段階で失敗すると、ツールは起動したエミュレータープロセスを終了するため、次の呼び出しはクリーンな状態から始まります。
3. Metro（React Native の場合）：デバイスの起動後、adb -s <serial> reverse tcp:8081 tcp:8081 を実行し、デバイスからホスト上の Metro に接続できるようにします。デバイスを再起動した場合は、再度実行してください。

3. デバイスの使用

Android のシリアルを udid として、統合されたインタラクションツール（gesture-tap、gesture-swipe、describe、screenshot、launch-app、keyboard など）に渡します。ID の形式に基づいて自動的に振り分けられます。プラットフォームに依存しないインタラクションツールと、スキルの末尾にある Android 固有の注意事項については、argent-device-interact を参照してください。

4. 注意事項

• Android TV／leanback AVD も同じフロー（boot-device と avdName）で起動しますが、タッチ操作ではなくフォーカス操作を使用します。これらのデバイスでは gesture-tap／gesture-swipe を使用しないでください。list-devices は leanback デバイスに runtimeKind: "tv" のタグを付けます（シリアルではなくシステムの機能リストから判定します。TV AVD のシリアルはスマートフォンのものと同じように見えます）。runtimeKind: "tv" の場合は、フォーカス操作用ツール（describe／tv-remote／keyboard）と argent-tv-interact スキルを使用してください。このスキルでは、Apple TV を含む Android TV の操作と、TV のセットアップ全体を説明しています。
• シリアルは adb のデバイス ID です。iOS の UDID と Android のシリアルは互換性がありませんが、使用するプラットフォームをツールに伝える必要はありません。自動的に振り分けられます。
• Android の describe が返すツリーは iOS より浅く（アクセシビリティサービスに相当するものがないため）、タップ対象の特定には十分対応しています。
• Android の reinstall-app は常に -g を付けてインストールするため、初回起動時のランタイム権限は事前に許可されます。
• エミュレーターを停止するには、シェルで adb -s <serial> emu kill を実行します（正常にシャットダウンします）。qemu に対して pkill -9／kill -9 を実行してはいけません。強制終了するとユーザーデータイメージが不整合になり、その後のコールドブートで復旧に何分もかかることがあります（書き込みが止まらず、boot_completed が切り替わりません）。イメージがこの状態になった場合は、-wipe-data を指定して一度起動し、リセットしてください。