xianyan/docs/android-cli-help.md

# Android CLI 完整使用指南

> 创建时间: 2026-05-28 | 版本: 1.0 | 适用: Android CLI v1.0.15498356+

---

## 目录

- [1. 概述](#1-概述)
- [2. 安装与配置](#2-安装与配置)
- [3. 全局选项](#3-全局选项)
- [4. 命令详解](#4-命令详解)
  - [4.1 android update](#41-android-update)
  - [4.2 android info](#42-android-info)
  - [4.3 android init](#43-android-init)
  - [4.4 android create](#44-android-create)
  - [4.5 android describe](#45-android-describe)
  - [4.6 android sdk](#46-android-sdk)
  - [4.7 android emulator](#47-android-emulator)
  - [4.8 android docs](#48-android-docs)
  - [4.9 android skills](#49-android-skills)
  - [4.10 android run](#410-android-run)
  - [4.11 android layout](#411-android-layout)
  - [4.12 android screen](#412-android-screen)
  - [4.13 android studio](#413-android-studio)
- [5. 传统命令行工具](#5-传统命令行工具)
  - [5.1 sdkmanager](#51-sdkmanager)
  - [5.2 avdmanager](#52-avdmanager)
  - [5.3 adb](#53-adb)
- [6. 配置文件 .androidrc](#6-配置文件-androidrc)
- [7. 已知问题与限制](#7-已知问题与限制)
- [8. 常用工作流示例](#8-常用工作流示例)
- [9. 环境变量参考](#9-环境变量参考)

---

## 1. 概述

Android CLI 是 Google 推出的新一代命令行界面工具，专为智能体优先（Agent-first）工作流设计。它为 Android 开发提供了标准化的核心能力入口，包括：

- 从模板创建新项目
- 管理 Android SDK 软件包
- 创建和运行模拟器
- 分析项目结构
- 在设备/模拟器上部署和运行 APK
- 从终端搜索和获取 Android 文档
- 管理 AI 编码代理技能
- 截屏和布局检查
- 与 Android Studio 集成

**基本语法：**

```
android <command> [subcommand] [options] [arguments]
```

**当前安装信息：**

| 项目 | 值 |
|------|------|
| CLI 版本 | 1.0.15498356 |
| 安装路径 | `C:\Users\无书\AppData\AndroidCLI\android.exe` |
| SDK 路径 | `E:\sdk\android` |
| cmdline-tools | 20.0 |

---

## 2. 安装与配置

### 2.1 安装

**Windows:**
```powershell
curl.exe -fsSL https://dl.google.com/android/cli/latest/windows_x86_64/install.cmd -o "%TEMP%\i.cmd" && "%TEMP%\i.cmd"
```

**macOS (Apple Silicon):**
```bash
curl -fsSL https://dl.google.com/android/cli/latest/darwin_arm64/install.sh | bash
```

**macOS (Intel):**
```bash
curl -fsSL https://dl.google.com/android/cli/latest/darwin_x86_64/install.sh | bash
```

**Linux:**
```bash
curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh | bash
```

### 2.2 验证安装

```bash
android --version    # 查看版本
android info         # 查看 SDK 配置信息
```

### 2.3 环境变量配置

**Windows (管理员 PowerShell):**
```powershell
# 设置 Machine 级别 PATH
[System.Environment]::SetEnvironmentVariable("PATH",
    [System.Environment]::GetEnvironmentVariable("PATH", "Machine") +
    ";C:\Users\无书\AppData\AndroidCLI;E:\sdk\android\cmdline-tools\latest\bin;E:\sdk\android\platform-tools",
    "Machine")

# 设置 ANDROID_HOME
[System.Environment]::SetEnvironmentVariable("ANDROID_HOME", "E:\sdk\android", "Machine")
[System.Environment]::SetEnvironmentVariable("ANDROID_SDK_ROOT", "E:\sdk\android", "Machine")
```

**macOS / Linux:**
```bash
# 添加到 ~/.bashrc 或 ~/.zshrc
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
```

---

## 3. 全局选项

### `-h, --help`

显示帮助信息，可用于任何命令层级。

```bash
android -h                  # 显示全局帮助
android create -h           # 显示 create 命令帮助
android sdk list -h         # 显示 sdk list 帮助
```

### `--sdk=<path-to-sdk>`

临时指定本次命令使用的 Android SDK 路径，无需更改全局环境变量。

```bash
android --sdk=/path/to/sdk sdk list
```

### `--version`

显示当前 Android CLI 版本号。

```bash
android --version
# 输出: 1.0.15498356
```

---

## 4. 命令详解

### 4.1 android update

更新 Android CLI 到最新版本。建议定期运行。

```bash
android update
# 输出: Already up-to-date 或更新进度
```

### 4.2 android info

显示当前 Android SDK 配置信息，包括 SDK 路径和版本。

```bash
android info
# 输出示例:
# Android SDK: E:\sdk\android
# SDK Version: 36.1.0
```

### 4.3 android init

初始化 Android CLI 代理环境，下载知识库索引。首次使用或为 AI 代理配置时运行。

```bash
android init
# 下载知识库 (~18MB)，索引约 4882 项
# 安装 android-cli 技能供 AI 代理使用
```

### 4.4 android create

从模板创建新的 Android 项目。

**语法：**
```
android create [--dry-run] [--verbose] [--name=<name>] [--minSdk=api] -o=<dest-path> [<template-name>]
```

**参数：**

| 参数 | 必需 | 说明 |
|------|------|------|
| `-o, --output=<path>` | ✅ | 目标项目目录路径 |
| `<template-name>` | ❌ | 模板名称，默认 `empty-activity-agp-9` |
| `--name=<name>` | ❌ | 应用名称，默认使用输出目录名 |
| `--minSdk=<api>` | ❌ | 最低 SDK 版本，默认由模板定义 |
| `--dry-run` | ❌ | 模拟创建，不实际写入文件 |
| `--verbose` | ❌ | 详细输出，显示复制的文件列表 |
| `--list` | ❌ | 列出所有可用模板 |

**示例：**

```bash
# 列出可用模板
android create --list
# 输出: empty-activity (Empty Activity, Compose + AGP 9)

# 试运行查看模板效果
android create --dry-run --verbose empty-activity

# 创建新项目
android create --name=MyApp --output=./MyApp empty-activity

# 指定最低 SDK 版本
android create --name=MyApp --output=./MyApp --minSdk=26 empty-activity
```

### 4.5 android describe

分析 Android 项目，生成描述性元数据。输出 JSON 文件，包含项目结构、构建目标、APK 位置等信息。

**语法：**
```
android describe --project_dir=<path>
```

**参数：**

| 参数 | 必需 | 说明 |
|------|------|------|
| `--project_dir=<path>` | ✅ | 项目目录路径 |

**示例：**

```bash
android describe --project_dir=./MyApp
# 输出项目结构、构建变体、APK 路径等元数据
```

### 4.6 android sdk

管理 Android SDK 软件包的安装、更新、移除和列表。

#### 4.6.1 android sdk list

列出已安装和可用的 SDK 软件包。

**语法：**
```
android sdk list [--all] [--all-versions] [--beta] [--canary] [<pattern>]
```

**选项：**

| 选项 | 说明 |
|------|------|
| `<pattern>` | 按模式过滤包名（支持 `*` 通配符） |
| `--all` | 显示仓库中所有可用包 |
| `--all-versions` | 显示每个包的所有版本 |
| `--beta` | 包含 Beta 版包 |
| `--canary` | 包含 Canary 版包 |

**示例：**

```bash
# 列出已安装的 platforms 包
android sdk list platforms

# 列出所有可用的 build-tools
android sdk list --all build-tools

# 列出所有包（含 Beta 和 Canary）
android sdk list --all --beta --canary
```

#### 4.6.2 android sdk install

安装 SDK 软件包。

**语法：**
```
android sdk install [--beta] [--canary] [--force] <package>[@<version>]...
```

**选项：**

| 选项 | 说明 |
|------|------|
| `<package>[@<version>]` | 包名，可指定版本，默认最新 |
| `--beta` | 包含 Beta 版包 |
| `--canary` | 包含 Canary 版包 |
| `--force` | 强制降级到旧版本 |

**示例：**

```bash
# 安装最新版 platform
android sdk install "platforms;android-35"

# 安装指定版本的 build-tools
android sdk install "build-tools;35.0.0"

# 安装系统镜像
android sdk install "system-images;android-35;google_apis;x86_64"

# 同时安装多个包
android sdk install "platforms;android-35" "build-tools;35.0.0"
```

#### 4.6.3 android sdk update

更新 SDK 软件包到最新版本。

**语法：**
```
android sdk update [--beta] [--canary] [--force] [<pkg-name>]
```

**选项：**

| 选项 | 说明 |
|------|------|
| `<pkg-name>` | 要更新的包名（可选，不指定则更新全部） |
| `--beta` | 包含 Beta 版包 |
| `--canary` | 包含 Canary 版包 |
| `--force` | 强制降级 |

**示例：**

```bash
# 更新所有已安装的包
android sdk update

# 更新指定包
android sdk update "platforms;android-35"
```

#### 4.6.4 android sdk remove

移除已安装的 SDK 软件包。

**语法：**
```
android sdk remove <pkg-name>
```

**示例：**

```bash
android sdk remove "build-tools;30.0.3"
```

### 4.7 android emulator

管理 Android 虚拟设备（AVD）。

> ⚠️ **已知限制**: Windows 上 `android emulator` 命令目前已被停用，需要使用传统 `emulator` 命令或通过 Android Studio 启动。

#### 4.7.1 android emulator list

列出可用的虚拟设备。

```bash
android emulator list
# 输出:
# Pixel_8_Pro
# Pixel_8_Pro_2
```

#### 4.7.2 android emulator create

创建新的虚拟设备。

**语法：**
```
android emulator create [--list-profiles] <profile>
```

**选项：**

| 选项 | 说明 |
|------|------|
| `<profile>` | 设备配置文件名 |
| `--list-profiles` | 列出可用的设备配置文件 |

**可用配置文件：**

| 配置文件 | 设备类型 |
|----------|----------|
| `medium_phone` | 中等手机 |
| `medium_tablet` | 中等平板 |
| `small_phone` | 小手机 |
| `large_tablet` | 大平板 |
| `wear` | Wear OS 手表 |
| `xr_device` | XR 设备 |

**示例：**

```bash
# 查看可用配置文件
android emulator create --list-profiles

# 创建手机模拟器
android emulator create medium_phone

# 创建平板模拟器
android emulator create medium_tablet

# 创建 Wear OS 模拟器
android emulator create wear
```

#### 4.7.3 android emulator start

启动虚拟设备。命令会在模拟器完全启动并就绪后返回。

**语法：**
```
android emulator start [--cold] <device>
```

**选项：**

| 选项 | 说明 |
|------|------|
| `<device>` | 设备名称（使用 `emulator list` 查看） |
| `--cold` | 冷启动，不从快照加载 |

**示例：**

```bash
# 启动模拟器
android emulator start Pixel_8_Pro

# 冷启动
android emulator start --cold Pixel_8_Pro
```

#### 4.7.4 android emulator stop

停止虚拟设备。

**语法：**
```
android emulator stop [<device>]
```

**选项：**

| 选项 | 说明 |
|------|------|
| `<device>` | 模拟器名称或序列号（仅一个运行时可省略） |

**示例：**

```bash
android emulator stop Pixel_8_Pro
```

#### 4.7.5 android emulator remove

删除虚拟设备。

**语法：**
```
android emulator remove <device>
```

**示例：**

```bash
android emulator remove Pixel_8_Pro
```

### 4.8 android docs

搜索和获取 Android 官方文档。

#### 4.8.1 android docs search

搜索 Android 文档。

**语法：**
```
android docs search <query>
```

**示例：**

```bash
android docs search "Jetpack Compose Navigation"
# 输出:
# 1. Migrate from Fragment-based Navigation to Navigation Compose
#    URL: kb://android/develop/ui/compose/migrate/migration-scenarios/navigation
# 2. Navigation in Compose
#    URL: kb://JetBrains/kotlin-multiplatform-dev-docs/topics/compose/compose-navigation
# ...

android docs search "Room database"
android docs search "Activity lifecycle"
```

#### 4.8.2 android docs fetch

获取指定 URL 的文档内容。URL 由 `docs search` 返回。

**语法：**
```
android docs fetch <url>
```

**示例：**

```bash
android docs fetch "kb://android/develop/ui/compose/navigation"
# 输出完整的文档内容
```

### 4.9 android skills

管理 AI 编码代理技能。技能是为 AI 代理（如 Gemini、GitHub Copilot 等）提供的专业知识模块。

#### 4.9.1 android skills list

列出可用的技能。

**语法：**
```
android skills list [--long] [--project=<path>]
```

**选项：**

| 选项 | 说明 |
|------|------|
| `--long` | 使用详细输出格式 |
| `--project=<path>` | 列出指定项目中已安装的技能 |

**示例：**

```bash
# 列出所有可用技能
android skills list

# 详细列表
android skills list --long

# 列出项目中的技能
android skills list --project=./MyApp
```

**可用技能（18个）：**

| 技能名 | 说明 |
|--------|------|
| `android-cli` | Android CLI 使用指南 |
| `compose-m3` | Jetpack Compose Material 3 指南 |
| `edge-to-edge` | 边到边显示适配 |
| `jetpack-compose-m3` | Wear OS Compose Material3 |
| `display-glasses-with-jetpack-compose-glimmer` | Android XR 显示眼镜开发 |
| `migrate-xml-views-to-jetpack-compose` | XML View 迁移到 Compose |
| `styles` | Jetpack Compose Styles API |
| `kotlin-multiplatform` | Kotlin 多平台开发 |
| ... | 更多技能可通过 `skills list` 查看 |

#### 4.9.2 android skills find

按关键词搜索技能。

**语法：**
```
android skills find <keyword>
```

**示例：**

```bash
android skills find compose
android skills find navigation
android skills find wear
```

#### 4.9.3 android skills add (install)

安装技能到项目或代理。

**语法：**
```
android skills install [--all] [--agent=<agents>] [--project=<path>] <skill>
```

**选项：**

| 选项 | 说明 |
|------|------|
| `<skill>` | 要安装的技能名称 |
| `--all` | 安装所有技能 |
| `--agent=<agents>` | 逗号分隔的代理列表（不指定则安装到所有检测到的代理） |
| `--project=<path>` | 安装到指定项目 |

**示例：**

```bash
# 安装单个技能
android skills install compose-m3

# 安装所有技能
android skills install --all

# 安装到指定项目
android skills install --project=./MyApp compose-m3

# 安装到指定代理
android skills install --agent=gemini compose-m3
```

#### 4.9.4 android skills remove

移除技能。

**语法：**
```
android skills remove [--agent=<agents>] [--project=<path>] <skill>
```

**示例：**

```bash
android skills remove compose-m3
android skills remove --project=./MyApp compose-m3
```

### 4.10 android run

在设备或模拟器上部署和运行 Android 应用。

**语法：**
```
android run [--debug] [--activity=<name>] [--device=<serial>] [--type=<type>] [--apks=<paths>]
```

**选项：**

| 选项 | 说明 |
|------|------|
| `--apks=<paths>` | APK 文件路径（逗号分隔） |
| `--activity=<name>` | 启动的 Activity 名称 |
| `--device=<serial>` | 目标设备序列号 |
| `--type=<type>` | 组件类型（ACTIVITY, SERVICE 等） |
| `--debug` | 以调试模式运行 |

**示例：**

```bash
# 运行 APK
android run --apks=./app-debug.apk

# 指定设备和 Activity
android run --device=emulator-5554 --activity=.MainActivity --apks=./app-debug.apk

# 调试模式
android run --debug --apks=./app-debug.apk
```

### 4.11 android layout

获取应用的布局树，用于 UI 调试和自动化。

**语法：**
```
android layout [-d] [-h] [-p] [--device=<serial>] [-o=<path>]
```

**选项：**

| 选项 | 说明 |
|------|------|
| `-d, --diff` | 返回自上次 ui-dump 以来变化的布局元素 |
| `--device=<serial>` | 设备序列号 |
| `-o, --output=<path>` | 输出到文件，省略则打印到标准输出 |
| `-p, --pretty` | 美化 JSON 输出 |

**示例：**

```bash
# 获取布局树
android layout

# 美化输出并保存到文件
android layout -p -o=layout.json

# 对比布局变化
android layout -d

# 指定设备
android layout --device=emulator-5554 -p
```

### 4.12 android screen

设备屏幕操作命令。

#### 4.12.1 android screen capture

截取设备屏幕截图。

**语法：**
```
android screen capture [-a] [-o=<path>]
```

**选项：**

| 选项 | 说明 |
|------|------|
| `-a, --annotate` | 在 UI 元素周围绘制标注边框 |
| `-o, --output=<path>` | 输出到文件或目录 |

**示例：**

```bash
# 截屏
android screen capture

# 截屏并标注 UI 元素
android screen capture -a -o=screenshot.png
```

#### 4.12.2 android screen resolve

从标注截图中解析 UI 元素坐标。将 `#N` 替换为标注框 N 的中心坐标。

**语法：**
```
android screen resolve --screenshot=<path> --string=<template>
```

**选项：**

| 选项 | 必需 | 说明 |
|------|------|------|
| `--screenshot=<path>` | ✅ | 使用 `screen capture -a` 截取的标注截图 |
| `--string=<template>` | ✅ | 包含 `#N` 占位符的字符串模板 |

**示例：**

```bash
# 先截取标注截图
android screen capture -a -o=annotated.png

# 解析坐标 - 将 #1 替换为标注框1的中心坐标
android screen resolve --screenshot=annotated.png --string="adb shell input tap #1"
```

### 4.13 android studio

与 Android Studio 集成的命令组。

#### 4.13.1 android studio check

检查运行中的 Android Studio 实例状态。

```bash
android studio check
# 需要 Android Studio Quail 1 或更高版本
```

#### 4.13.2 android studio version-lookup

查询 Maven 依赖、Android 工具等的最新版本。

**语法：**
```
android studio version-lookup [--pid=<pid>] [--project=<name>] <artifacts...>
```

**支持的标识符：**

| 标识符 | 说明 | 示例 |
|--------|------|------|
| `groupId:artifactId` | Maven 库 | `androidx.window:window` |
| `pluginId` | Gradle 插件 | `com.android.application` |
| `gradle` | Gradle 构建工具 | - |
| `studio` | Android Studio | - |
| `agp` | Android Gradle Plugin | - |
| `ndk` | Android NDK | - |
| `sdk` | Android SDK | - |
| `emulator` | Android 模拟器 | - |
| `adb` | Android Debug Bridge | - |
| `compose` | Compose BOM | - |
| `kotlin` | Kotlin 语言 | - |
| `android` | Android 版本 | - |
| `platform-tools` | SDK Platform-Tools | - |
| `cmdline-tools` | SDK Command-line Tools | - |
| `build-tools` | SDK Build-Tools | - |

**示例：**

```bash
# 查询多个工具版本
android studio version-lookup agp kotlin compose gradle

# 查询 Maven 库版本
android studio version-lookup "androidx.window:window" "androidx.navigation:navigation-compose"

# 查询 Android 和 NDK 版本
android studio version-lookup android ndk
```

#### 4.13.3 其他 studio 子命令

| 命令 | 说明 |
|------|------|
| `android studio find-declaration` | 查找符号声明 |
| `android studio find-usages` | 查找符号使用 |
| `android studio open-file` | 在 Android Studio 中打开文件 |
| `android studio analyze-file` | 在 Android Studio 中分析文件 |
| `android studio render-compose-preview` | 渲染 Compose 预览 |

---

## 5. 传统命令行工具

除了新版 `android` CLI，SDK 还包含传统的命令行工具，位于 `cmdline-tools/latest/bin/` 目录。

### 5.1 sdkmanager

管理 SDK 软件包的传统工具。

**基本用法：**

```bash
sdkmanager --version                                    # 查看版本
sdkmanager --list                                       # 列出所有包
sdkmanager --list_installed                             # 列出已安装的包
sdkmanager "platforms;android-35"                       # 安装包
sdkmanager --install "build-tools;35.0.0"               # 安装包（显式）
sdkmanager --uninstall "build-tools;30.0.3"             # 卸载包
sdkmanager --update                                     # 更新所有已安装的包
sdkmanager --licenses                                   # 接受所有许可
```

**通用参数：**

| 参数 | 说明 |
|------|------|
| `--sdk_root=<path>` | 指定 SDK 根目录 |
| `--channel=<id>` | 渠道: 0(Stable), 1(Beta), 2(Dev), 3(Canary) |
| `--include_obsolete` | 包含过时的包 |
| `--no_https` | 使用 HTTP 而非 HTTPS |
| `--verbose` | 详细输出 |
| `--proxy=<type>` | 代理类型: http 或 socks |
| `--proxy_host=<addr>` | 代理地址 |
| `--proxy_port=<port>` | 代理端口 |

### 5.2 avdmanager

管理 Android 虚拟设备的传统工具。

**基本用法：**

```bash
avdmanager list target              # 列出可用目标
avdmanager list avd                 # 列出已有 AVD
avdmanager list device              # 列出设备定义

# 创建 AVD
avdmanager create avd -n Pixel_8 -k "system-images;android-35;google_apis;x86_64" -d pixel_8

# 删除 AVD
avdmanager delete avd -n Pixel_8

# 移动/重命名 AVD
avdmanager move avd -n OldName -r NewName
```

**全局选项：**

| 选项 | 说明 |
|------|------|
| `-s, --silent` | 静默模式 |
| `-v, --verbose` | 详细模式 |
| `--clear-cache` | 清除缓存 |

### 5.3 adb

Android Debug Bridge，与设备通信的核心工具。

**基本用法：**

```bash
adb devices                          # 列出连接的设备
adb devices -l                       # 详细列出设备
adb shell                            # 进入设备 Shell
adb shell <command>                  # 在设备上执行命令
adb install <apk>                    # 安装 APK
adb install -r <apk>                 # 覆盖安装
adb uninstall <package>              # 卸载应用
adb uninstall -k <package>           # 卸载但保留数据
adb push <local> <remote>            # 推送文件到设备
adb pull <remote> <local>            # 从设备拉取文件
adb reboot                           # 重启设备
adb reboot bootloader                # 重启到 Bootloader
adb reboot recovery                  # 重启到 Recovery
adb logcat                           # 查看日志
adb bugreport                        # 生成 Bug 报告
adb shell screencap -p /sdcard/screen.png  # 截屏
adb shell dumpsys activity top       # 查看当前 Activity
adb shell pm list packages           # 列出所有包
adb shell pm list packages -3        # 列出第三方包
adb shell getprop ro.build.version.sdk  # 获取 SDK 版本
```

---

## 6. 配置文件 .androidrc

创建 `.androidrc` 文件可在每次运行 Android CLI 时自动应用默认标志。

**文件位置：**
- Windows: `%USERPROFILE%\.androidrc`
- macOS / Linux: `~/.androidrc`

**示例内容：**

```
--sdk=E:\sdk\android
--no-metrics
```

每行一个标志，自动应用于所有 `android` 命令调用。

---

## 7. 已知问题与限制

| 问题 | 说明 |
|------|------|
| Windows emulator 命令停用 | `android emulator` 在 Windows 上目前已停用，需使用传统 `emulator` 命令 |
| SDK XML 版本警告 | cmdline-tools 20.0 可能出现 SDK XML 版本不匹配警告，不影响功能 |
| studio 命令需要 Android Studio | `android studio` 系列命令需要 Android Studio Quail 1+ 运行 |
| JDK 警告 | Windows 上可能出现 `UseAllWindowsProcessorGroups` 警告，可忽略 |

---

## 8. 常用工作流示例

### 8.1 从零创建项目并运行

```bash
# 1. 查看可用模板
android create --list

# 2. 创建项目
android create --name=MyApp --output=./MyApp empty-activity

# 3. 安装必要 SDK
android sdk install "platforms;android-35" "build-tools;35.0.0"

# 4. 创建模拟器
android emulator create medium_phone

# 5. 启动模拟器
android emulator start medium_phone

# 6. 构建项目
cd MyApp && ./gradlew assembleDebug

# 7. 运行 APK
android run --apks=./app/build/outputs/apk/debug/app-debug.apk
```

### 8.2 CI/CD 环境配置

```bash
# 1. 更新 CLI
android update

# 2. 安装所有必需 SDK
android sdk install "platforms;android-35" "build-tools;35.0.0" "system-images;android-35;google_apis;x86_64"

# 3. 接受许可
sdkmanager --licenses

# 4. 创建无界面模拟器
avdmanager create avd -n ci_device -k "system-images;android-35;google_apis;x86_64" -d medium_phone

# 5. 启动模拟器（无窗口）
emulator -avd ci_device -no-window -no-audio &

# 6. 运行测试
./gradlew connectedAndroidTest
```

### 8.3 AI 代理工作流

```bash
# 1. 初始化代理环境
android init

# 2. 安装所需技能
android skills install compose-m3
android skills install edge-to-edge

# 3. 搜索文档
android docs search "Compose Navigation"

# 4. 获取文档详情
android docs fetch "kb://android/develop/ui/compose/navigation"

# 5. 查询最新版本
android studio version-lookup agp kotlin compose
```

### 8.4 UI 调试工作流

```bash
# 1. 截取标注截图
android screen capture -a -o=debug.png

# 2. 获取布局树
android layout -p -o=layout.json

# 3. 对比布局变化
android layout -d

# 4. 解析 UI 元素坐标
android screen resolve --screenshot=debug.png --string="tap at #1"
```

---

## 9. 环境变量参考

| 变量 | 说明 | 示例值 |
|------|------|--------|
| `ANDROID_HOME` | Android SDK 根目录 | `E:\sdk\android` |
| `ANDROID_SDK_ROOT` | Android SDK 根目录（旧名） | `E:\sdk\android` |
| `JAVA_HOME` | JDK 安装路径 | `C:\Program Files\Java\jdk-21` |
| `PATH` | 需包含以下路径 | 见下方 |

**PATH 应包含的路径：**

```
C:\Users\无书\AppData\AndroidCLI          # android CLI
E:\sdk\android\cmdline-tools\latest\bin   # sdkmanager, avdmanager
E:\sdk\android\platform-tools             # adb, fastboot
E:\sdk\android\emulator                   # emulator
E:\sdk\android\tools\bin                  # 旧版工具
```

---

## 参考链接

- [Android CLI 官方文档](https://developer.android.google.cn/tools/agents/android-cli?hl=zh-cn)
- [Android CLI 下载页面](https://developer.android.google.cn/tools/agents?hl=zh-cn)
- [Android Skills 文档](https://developer.android.google.cn/tools/agents/android-skills?hl=zh-cn)
- [sdkmanager 文档](https://developer.android.com/studio/command-line/sdkmanager)
- [adb 文档](https://developer.android.com/studio/command-line/adb)
- [Android CLI 实用指南 (掘金)](https://juejin.cn/post/7637700476638068787)