android-emulator

在机主的手机或项目模拟器上运行 Android 应用——启动和停止模拟器、选择设备、构建、安装、打开应用并截取屏幕截图。当任务需要运行 Android 应用（设备或模拟器上）、需要其截图，或机主要求启动、停止或检查模拟器时使用。

android-emulator 是什么？

该技能旨在让 AI 助手能够直接在机主的 Android 设备或项目的模拟器上运行、测试和调试 Android 应用。它通过读取项目特定的 `.claude/android-emulator.md` 配置文件（包含 AVD 名称、应用 ID 和脚本路径）来确定环境。核心流程包括：选择设备（优先机主手机，无手机时使用模拟器）、启动/停止模拟器（通过项目或技能自带的脚本管理，支持后台运行和快照保存）、构建安装（支持按 ABI 构建以加快无线调试速度）、打开应用（使用 adb 命令启动指定 Activity），以及获取屏幕截图、模拟点击输入和查看日志等调试功能。该技能特别关注数据安全：在机主手机上从不未经询问就卸载应用或清除数据，且会在任务完成后恢复对手机所做的任何更改（如深色模式）并停止启动过的模拟器。

兼容平台✓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> 是项目脚本接受此选择的方式。

一旦选定设备，始终向 adb 传递 -s <serial>，因为同时可能有其他设备连接。

模拟器

仅在需要时启动模拟器，并在任务完成后停止它，因为它会占用数 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