Android CLI 完全用法解析

Android CLI 完全用法解析

随着 AI 代理（Gemini、Claude、Codex 等）越来越多地参与 Android 开发，Google 推出了一个为"代理优先"工作流设计的命令行工具——Android CLI（即 android 命令）。它把建项目、管设备、装 SDK、查文档、装技能、连 Android Studio 等一整套能力收进终端，既方便开发者脚本化操作，也方便 AI 代理直接调用。本文按命令分组，把 Android CLI 的完全用法讲清楚。

1、概述、安装、配置与注意事项

Android CLI 是面向开发者、脚本与 AI 代理的命令行入口，把官方工具、技能与知识库串成一条命令链路。下载后先升级、再为代理初始化技能即可上手。

# 下载安装后，升级到最新版
android update

# 验证是否已安装（返回路径即成功）
which android

# 为 AI 代理安装 android-cli 技能
android init

# 配置文件：macOS/Linux 为 ~/.androidrc，Windows 为 %USERPROFILE%\.androidrc
# 每行一个参数，每次调用自动附加，例如：
--sdk=/path/to/Android/Sdk

基本约定：

        - 下载地址 developer.android.com/tools/agents；which android 验证安装

        - .androidrc 自动附加参数；全局选项 --sdk 临时指定 SDK，-h 查帮助，-V 查版本

        - Windows 上 emulator 子命令暂不可用，也不支持从 PowerShell 下载

        - 遥测只收集命令调用与预定义参数值，不收集 CLI 响应、用户输入或文件路径

2、项目与知识库：create / describe / docs

create 从模板脚手架新建项目，describe 分析项目结构，docs 两步检索 Android 知识库。

# 用模板创建新项目（默认模板 empty-activity-agp-9）
android create --output=./MyApp

# 列出全部可用模板
android create list

# 分析项目，生成结构与产物位置的 JSON 元数据
android describe --project_dir=/path/to/project

# 第一步：检索知识库，返回 kb:// 链接
android docs search 'How do I improve my app performance?'

# 第二步：用 kb:// 链接取回文档正文
android docs fetch kb://android/topic/performance/overview

要点：

1. create 的 --output 指定输出目录，--name 可改项目名，--dry-run 可预演

2. create list 查看所有模板，默认使用 empty-activity-agp-9

3. describe 产出供代理读取的项目元数据（构建目标、APK 位置等）

4. docs 是"先 search 拿链接、再 fetch 取正文"的两步流程

3、虚拟设备与部署：emulator / run

emulator 子命令管理虚拟设备；run 把已构建好的 APK 部署到设备或模拟器（不包含构建步骤）。

# 创建虚拟设备（默认 medium_phone），--list-profiles 看可选机型
android emulator create
android emulator create --profile=medium_phone

# 列出 / 启动 / 停止虚拟设备
android emulator list
android emulator start medium_phone
android emulator stop emulator-5554

# 部署 APK（多个用逗号分隔）
android run --apks=app/build/outputs/apk/debug/app-debug.apk
android run --apks=base.apk,density-hdpi.apk,lang-en.apk

要点：

1. emulator create 用 --profile 选机型，默认 medium_phone

2. start 传设备名，stop 传设备序列号（如 emulator-5554）

3. run 的 --apks 必填，支持 split APKs 一起部署

4. run 可选 --activity、--device，--type 支持 ACTIVITY / WATCH_FACE / TILE 等

4、SDK 管理：sdk install / list / remove / update

sdk 子命令把 SDK 包管理搬进终端，支持安装指定版本、按通道与正则过滤。

# 安装 SDK 包（可带 @version 指定版本，可多包空格分隔）
android sdk install platforms/android-34 build-tools/34.0.0
android sdk install platforms/android-34@2

# 列出 / 移除 / 更新
android sdk list 'build-tools'
android sdk remove build-tools/36.1.0
android sdk update
android sdk update build-tools/34.0.0

要点：

1. sdk install 可用 @version 锁版本，--beta / --canary 选通道，--force 允许降级

2. sdk list 支持正则过滤，--all 看全部、--all-versions 看所有版本

3. sdk remove 按包名卸载

4. sdk update 不指定包名则升级全部已装包

5、UI 调试：layout / screen capture / screen resolve

这三件套用于"看懂并操作界面"：导出布局树、带标注截图、把标注翻译成坐标，特别适合让代理精确点击。

# 以 JSON 导出当前界面的 UI 布局树
android layout --output=./hierarchy.json

# 截图，并为每个 UI 元素画上带编号的框
android screen capture --output=ui.png --annotate

# 把编号翻译成真实屏幕坐标，配合 input tap 做点击
android screen resolve --screenshot=ui.png --string="input tap #5"

要点：

1. layout 的 --pretty 缩进、--diff 只看自上次以来的变化

2. screen capture 的 --annotate 给元素编号，供 resolve 使用

3. screen resolve 用 #编号 占位，输出替换为真实坐标

4. 这套组合让代理能"看清界面 → 算出坐标 → 精确操作"

6、技能管理：skills（与 AI 代理）

skills 子命令把官方 Android 技能装到各代理的技能目录，是"代理遵循 Android 最佳实践"的关键，也和 android skills add 的能力直接对应。

# 为指定代理安装某个技能（已安装则更新到最新）
android skills add --agent='gemini' edge-to-edge

# 一次安装全部 Android 技能
android skills add --all

# 查找 / 列出 / 移除技能
android skills find 'performance'
android skills list --long
android skills remove --agent='gemini' --skill=edge-to-edge

要点：

1. skills add 用 --skill 装单个、--all 装全部、--agent 指定代理

2. 不指定代理且无已检测代理时，默认装到 ~/.gemini/antigravity/skills

3. skills list --long 显示描述与已安装代理，find 按关键词检索

4. 自定义过的技能要改名，否则更新时会被覆盖

7、连接 Android Studio：studio 子命令

studio 子命令连接运行中的 Android Studio（需 Quail 2 Canary 1+ 并开启 Gemini、登录），借用 IDE 的语义分析能力，让代理具备跳转、引用、预览与诊断级别的智能。

# 先确认 IDE 在线与已开项目
android studio check

# 用 IDE 检查引擎分析文件的错误、警告、lint
android studio analyze-file --project=MyApplication \
    app/src/main/java/com/example/myapp/MainActivity.kt

# 符号跳转 / 引用查找
android studio find-declaration --short HotelDetailScreen
android studio find-usages --short HotelDetailScreen

# 渲染 Compose @Preview 并导出语义树
android studio render-compose-preview --output-image-file=preview.png \
    app/src/main/java/com/example/myapp/ui/DetailScreen.kt HotelDetailScreenPreview

# 查依赖、AGP、Kotlin、SDK 等最新版本
android studio version-lookup agp kotlin androidx.compose.ui:ui

能力一览：

        - check：查看连接状态与已开项目（含 PID）

        - analyze-file：用 IDE 引擎做错误、警告、lint 检查

        - find-declaration / find-usages：符号声明与引用查找

        - open-file：在编辑器打开文件；render-compose-preview：渲染 Compose 预览

        - version-lookup：查 Maven 坐标、插件 ID 及 gradle/agp/kotlin 等版本

要点：

1. 先 android studio check 确认 IDE 在线、拿到项目 PID

2. 多实例时用 --pid 或 --project 指定目标

3. 让代理获得 IDE 级的跳转、引用、预览与诊断能力

8、总结

Android CLI（android 命令）是 Google 为代理优先工作流推出的命令行入口，覆盖项目脚手架（create）、知识库检索（docs）、虚拟设备（emulator）、APK 部署（run）、SDK 管理（sdk）、UI 调试（layout / screen）、技能管理（skills）与 Android Studio 桥接（studio）八大能力，并用 .androidrc、--sdk 等做配置。

落地建议：下载安装后跑 android init 接入代理，按 create → run → sdk → skills → studio 的主线把日常 Android 开发搬到终端；AI 代理可借 skills add 获得官方最佳实践、借 studio 子命令获得 IDE 级语义能力。Windows 用户需留意 emulator 子命令与 PowerShell 下载的两项限制。