Files

Developer 63a0559721 refactor: 重构项目路由与模块结构，统一发现页命名与路径

1. 全局替换tool_center/inspiration为discover模块，统一路由路径
2. 调整AppRoutes路由常量，将discover作为主Tab页，inspiration作为子页面
3. 更新页面注册表与路由配置，修正跳转目标
4. 调整启动页可选配置项，修正路由ID对应关系
5. 新增翻译服务、内容发现、热搜相关工具类与数据模型
6. 修复缓存清理后未刷新统计的问题，调整x86_64架构注释
7. 更新AGENTS.md文档约束规则
8. 新增一批调试用截图资源文件

2026-05-28 06:42:20 +08:00

25 KiB

Raw Blame History

Android CLI 完整使用指南

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

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:

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):

curl -fsSL https://dl.google.com/android/cli/latest/darwin_arm64/install.sh | bash

macOS (Intel):

curl -fsSL https://dl.google.com/android/cli/latest/darwin_x86_64/install.sh | bash

Linux:

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

2.2 验证安装

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

2.3 环境变量配置

Windows (管理员 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:

# 添加到 ~/.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`

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

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

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

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

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

`--version`

显示当前 Android CLI 版本号。

android --version
# 输出: 1.0.15498356

4. 命令详解

4.1 android update

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

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

4.2 android info

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

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

4.3 android init

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

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`	❌	列出所有可用模板

示例：

# 列出可用模板
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>`	✅	项目目录路径

示例：

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 版包

示例：

# 列出已安装的 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`	强制降级到旧版本

示例：

# 安装最新版 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`	强制降级

示例：

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

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

4.6.4 android sdk remove

移除已安装的 SDK 软件包。

语法：

android sdk remove <pkg-name>

示例：

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

列出可用的虚拟设备。

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 设备

示例：

# 查看可用配置文件
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`	冷启动，不从快照加载

示例：

# 启动模拟器
android emulator start Pixel_8_Pro

# 冷启动
android emulator start --cold Pixel_8_Pro

4.7.4 android emulator stop

停止虚拟设备。

语法：

android emulator stop [<device>]

选项：

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

示例：

android emulator stop Pixel_8_Pro

4.7.5 android emulator remove

删除虚拟设备。

语法：

android emulator remove <device>

示例：

android emulator remove Pixel_8_Pro

4.8 android docs

搜索和获取 Android 官方文档。

4.8.1 android docs search

搜索 Android 文档。

语法：

android docs search <query>

示例：

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>

示例：

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>`	列出指定项目中已安装的技能

示例：

# 列出所有可用技能
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>

示例：

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>`	安装到指定项目

示例：

# 安装单个技能
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>

示例：

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`	以调试模式运行

示例：

# 运行 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 输出

示例：

# 获取布局树
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>`	输出到文件或目录

示例：

# 截屏
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` 占位符的字符串模板

示例：

# 先截取标注截图
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 实例状态。

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	-

示例：

# 查询多个工具版本
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 软件包的传统工具。

基本用法：

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 虚拟设备的传统工具。

基本用法：

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，与设备通信的核心工具。

基本用法：

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 从零创建项目并运行

# 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 环境配置

# 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 代理工作流

# 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 调试工作流

# 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                  # 旧版工具

25 KiB Raw Blame History Unescape Escape

Android CLI 完整使用指南

目录

1. 概述

2. 安装与配置

2.1 安装

2.2 验证安装

2.3 环境变量配置

3. 全局选项

-h, --help

--sdk=<path-to-sdk>

--version

4. 命令详解

4.1 android update

4.2 android info

4.3 android init

4.4 android create

4.5 android describe

4.6 android sdk

4.6.1 android sdk list

4.6.2 android sdk install

4.6.3 android sdk update

4.6.4 android sdk remove

4.7 android emulator

4.7.1 android emulator list

4.7.2 android emulator create

4.7.3 android emulator start

4.7.4 android emulator stop

4.7.5 android emulator remove

4.8 android docs

4.8.1 android docs search

4.8.2 android docs fetch

4.9 android skills

4.9.1 android skills list

4.9.2 android skills find

4.9.3 android skills add (install)

4.9.4 android skills remove

4.10 android run

4.11 android layout

4.12 android screen

4.12.1 android screen capture

4.12.2 android screen resolve

4.13 android studio

4.13.1 android studio check

4.13.2 android studio version-lookup

4.13.3 其他 studio 子命令

5. 传统命令行工具

5.1 sdkmanager

5.2 avdmanager

5.3 adb

6. 配置文件 .androidrc

7. 已知问题与限制

8. 常用工作流示例

8.1 从零创建项目并运行

8.2 CI/CD 环境配置

8.3 AI 代理工作流

8.4 UI 调试工作流

9. 环境变量参考

参考链接

25 KiB

Raw Blame History

`-h, --help`

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

`--version`