android-emulator

在擁有者的手機或專案模擬器上執行 Android 應用程式 — 啟動和停止模擬器、選擇裝置、建置、安裝、開啟應用程式並擷取螢幕截圖。每當任務需要在裝置或模擬器上執行 Android 應用程式、取得其螢幕截圖，或擁有者要求啟動、停止或檢查模擬器時使用。

android-emulator 是什麼？

此技能用於管理 Android 應用程式的開發與測試流程，支援在實體手機或專案模擬器上執行應用程式。它會自動判斷可用裝置：優先使用透過 `adb devices` 偵測到的擁有者手機（序列號不以 `emulator-` 開頭），若無手機則使用專案的模擬器。技能會協助啟動和停止模擬器（headless 或視窗模式），並在啟動時自動關閉其他執行中的模擬器以節省記憶體。建置時支援僅針對特定 ABI 編譯，以加速無線偵錯的安裝流程。安裝後可開啟應用程式、擷取螢幕截圖、模擬觸控與輸入、檢視日誌（包含崩潰日誌），以及切換深色模式與語言設定。所有操作均透過 adb 指令完成，並會將對使用者手機的變更還原，並在任務完成後停止模擬器。此技能適用於 Claude Code、Cursor、Codex 等 AI 代理工具。

相容平台✓Claude Code~Codex CLI~Cursor

npx skills add https://github.com/chencohensolutions/claude-skills/tree/HEAD/plugins/android-emulator/skills/android-emulator

說明文件

Android：手機或模擬器

專案筆記

每個專案在 .claude/android-emulator.md 中命名其模擬器和應用程式：AVD 名稱、應用程式 ID（以及 UI 實驗室的 ID，如果有的話），以及專案自己的執行腳本。請先閱讀此檔案。若無此檔案，請執行 $ANDROID_HOME/emulator/emulator -list-avds 並選擇以專案命名的 AVD；若無任何匹配，請詢問擁有者，然後寫下筆記。

工具：sdk="${ANDROID_HOME:-$HOME/Library/Android/sdk}"，adb="$sdk/platform-tools/adb"。Gradle 需要 JDK：JAVA_HOME，否則使用 Homebrew 的 openjdk@21（/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home），否則使用 Android Studio 內建的 JDK（/Applications/Android Studio.app/Contents/jbr/Contents/Home）。

選擇裝置

優先使用擁有者的手機：adb devices 會列出一個不以 emulator- 開頭的序列號（USB 或無線偵錯）。若無手機，則使用專案的模擬器。擁有者可以要求使用其中一種；DEVICE=phone、DEVICE=emulator 或 DEVICE=<serial> 是專案腳本用來傳遞此選擇的方式。

一旦選定裝置，務必將 -s <serial> 傳遞給 adb，因為在此期間可能有其他裝置連接。

模擬器

僅在需要時啟動模擬器，並在任務完成時停止它，因為它會佔用數 GB 的記憶體。當專案有 scripts/emulator.sh 時使用它；否則使用此技能的 scripts/emulator.sh（位於技能基礎目錄中，載入技能時會顯示），並從筆記中帶入 AVD=<name>：

AVD=<name> <skill dir>/scripts/emulator.sh up       # 無頭模式；等待 Android 啟動完成，然後輸出序列號
AVD=<name> <skill dir>/scripts/emulator.sh status
AVD=<name> <skill dir>/scripts/emulator.sh down     # 儲存快速啟動快照，以便下次啟動只需數秒

up 會先關閉其他執行中的模擬器，因為腳本和 adb 會選擇第一個（KEEP_OTHERS=1 可保留它們）；WINDOW=1 會顯示其視窗，擁有者可能想觀看。當建置可以同時進行時，請在背景執行 up。如果失敗，其日誌位於 ${TMPDIR:-/tmp}/emulator-<avd>.log。

建置、安裝、開啟

優先使用專案的腳本（筆記中會命名它們：一個執行腳本，一個 UI 實驗室腳本）。手動操作步驟：

當專案支援時，僅建置裝置的 ABI（-Pabi=$(adb -s <serial> shell getprop ro.product.cpu.abi)，或使用專案腳本的 ABI=）：原生函式庫會使完整的 APK 在無線偵錯時傳輸緩慢。
adb -s <serial> install -r <apk>。-r 保留應用程式的資料；切勿在未經詢問的情況下解除安裝或對擁有者手機上的應用程式執行 pm clear，因為其中儲存著真實資料。
使用 adb -s <serial> shell am start --user current -S -f 0x10008000 -n <app id>/<activity> 開啟它：-S 停止舊程序以便新建置的應用程式執行，--user current 在具有安全資料夾的手機上是必需的，而標誌（新任務，清除舊任務）可防止 Android 恢復先前的畫面。

檢視它

螢幕截圖：adb -s <serial> exec-out screencap -p > <file>.png，然後檢視檔案。若手機顯示全黑，表示它已鎖定：請擁有者解鎖。
觸控和輸入流程：adb -s <serial> shell input tap <x> <y>、input text <text>、input keyevent KEYCODE_BACK；使用 adb -s <serial> exec-out uiautomator dump /dev/tty 找到座標。
日誌：adb -s <serial> logcat -d --pid=$(adb -s <serial> shell pidof <app id>)，或使用 -s <tag> 指定標籤。崩潰：adb -s <serial> logcat -d -b crash。
深色模式和語言設定：adb -s <serial> shell cmd uimode night yes|no；僅在模擬器上更改語言設定，不要在擁有者的手機上更改。

告知擁有者每個結果來自哪個裝置。完成後，將您在他們手機上更改的任何設定（例如深色模式）恢復原狀，如果您啟動了模擬器，請將其停止。

android-emulator