Google 官方 Android CLI：让AI直接读布局结构而不是用adb截图验证

本文所有命令、参数、输出均在 Android CLI v1.0.16625370 上实际运行验证。

一、先说结论：它是什么

android 是 Google 官方推出的 Android 命令行工具 。它不是 adb 的替代品 ，而是 adb 之上的语义化编排层：

你描述意图（"把这版装到车机上并启动"），它替你编排出正确的底层命令组合
底层仍然复用 adb 与 SDK 工具链完成实际传输 ------ 它没有替代 adb，而是让 adb 不再需要你手动拼装
内置 35 个官方技能包 （android skills），并自动同步到 36 个主流 AI Agent 宿主
依赖 Agent Skills 开放标准，不绑定 Google 生态

一句话概括三个跃迁：

维度	传统做法（adb）	Android CLI
交互单位	坐标（`input tap 540 1200`）	语义选择器（`input tap --match "..."`）
部署方式	整包覆盖安装	增量安装（比 adb 快几个数量级）
知识来源	开发者记忆 / 零散博客	官方 Knowledge Base （`docs search`，实测 5319 条索引）
测试方式	手写坐标脚本	自然语言 Journey（代理视觉 + 推理执行）

二、为什么要有这个工具：三个真实痛点

痛点 1：adb 是"零件"，不是"工具"

adb 的命令设计是面向传输协议的，它假设你知道设备内部的机制。于是日常开发里反复出现这种代码：

bash 复制代码

# 传统做法：要装 APK、授予权限、启动、等待、截图，5 条命令还得记住顺序

adb install -r -g app-debug.apk

adb shell am start -n com.example/.MainActivity

adb shell sleep 3

adb exec-out screencap -p > shot.png

而 android run 一条命令覆盖全流程，还多了增量安装：

bash 复制代码

android run --apks=app-debug.apk --activity=com.example.MainActivity --debug

本质区别：adb 把"部署"当成四个离散动作暴露给你；Android CLI 把"部署"当成一个意图，在内部处理顺序、等待与重试。

痛点 2：UI 自动化脚本会因分辨率而碎裂

这是最被低估的价值点。传统 UI 自动化写死了像素坐标：

bash 复制代码

adb shell input tap 540 1200   # 换分辨率、换刘海屏、换横竖屏 → 失效

Android CLI 提供了两条互补路径：

bash 复制代码

# 路径 A：语义选择器 ------ 依据视图树中的文本/属性定位

android input tap --match "text=确定" --wait 3000


# 路径 B：视觉标注 ------ 截图自动检测 UI 元素并编号

android screen capture --annotate --output=shot.png

android screen resolve --screenshot=shot.png --string="点击 #3 完成登录"

路径 B 的设计意图非常明确。官方对 --annotate 的描述是：

"This lets AI agents and scripts reference on-screen UI elements by label number instead of manually calculating pixel coordinates"

即：**把"人看截图找位置"这件事，自动化成"机器检测元素并编号"**。

官方 android-cli 技能文档里给出了一条很有代表性的协作范式 ------ 用 CLI 做视觉定位，再交给 adb 执行：

bash 复制代码

adb shell input $(android screen resolve --screenshot screen.png --string "tap #34")

这条命令把两者的优势组合起来：坐标由 CLI 的视觉检测算出，动作由 adb 精确执行。

痛点 3：知识是二手的，且会过时

android docs 接入的是官方 Knowledge Base，实测首轮执行会下载并建立索引：

bash 复制代码

Index created with 5319 items and committed.

搜"camera"返回的是一手官方文档 URL：

bash 复制代码

1. Migrate Camera1 to CameraX

   URL: kb://android/media/camera/camerax/camera1-to-camerax

2. Camera Enumeration

   URL: kb://android/media/camera/camera2/camera-enumeration

这直接解决了 AI 编码最常见的失效模式：模型凭记忆写出已过时的 API 用法。

三、下载与安装

安装方式：四条路，按权限需求选

Android CLI 不走 SDK Manager 分发 ，而是从 dl.google.com 直接拉独立二进制。官网提供四条路径，前两条是官方推荐的一键脚本：

macOS（Apple 芯片）--- 本地安装，不需 sudo

bash 复制代码

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

macOS（Intel 芯片） ------ 只需把路径里的 darwin_arm64 换成 darwin_x86_64：

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

Windows（CMD，注意不是 PowerShell）

bash 复制代码

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

⚠️ Windows 已知限制 （官网明确列出）：android emulator 命令在 Windows 上已停用 ；且不支持从 Windows PowerShell 下载 Android CLI，上面的命令要在 CMD 里执行。

全局安装 （装给这台机器的所有用户，需 sudo/管理员权限）把脚本名换成 install_root.sh / install_admin.cmd。

包管理器安装 ------ 从 1.0.15433482 起也支持 apt-get、winget、homebrew，适合纳入 CI 镜像构建。

验证安装

bash 复制代码

$ which android          # 或 command -v android

/User/xxx/Android/Sdk/android


$ android --version

1.0.16625370

环境自检：

bash 复制代码

android info

实测输出（路径因机器而异）：

bash 复制代码

sdk: /User/xxx/Library/Android/sdk

version: 1.0.16625370

launcher_version: 0.7.15378687

首次初始化：为 AI 装上技能

bash 复制代码

android init

这一步除了配置目录，还会安装 android-cli 技能 ------ 这是让 AI Agent "认识"这个工具的开关，详见第八章。

更新

bash 复制代码

android update

官网建议**定期运行 android update**。1.0.16406183 起启动速度大约翻倍（原生下载器库改为按需加载，不再每次解压缩到临时目录），值得保持更新。

数据收集：会收什么、不收什么

CLI 默认上报基础使用数据。官网明确划了边界：

会收集：

命令与子命令的调用（如 android run、android create）
选项名称（如 --sdk、--version）------ 只收名字，不收值
固定的预定义系统选项值，如模拟器模板名（medium_phone）、代理名（GEMINI、CLAUDE、CODEX）
匿名化后的堆栈轨迹与异常消息

不会收集：

命令的响应内容
用户输入的具体值

------ 例如 android create --name=com.company.internal.app，只记录"调用了 create 且带 --name"，不存 com.company.internal.app 这个值

停用方式：加 --no-metrics 标志。

四、`android docs`：把官方文档变成可调用的接口

这是整个 CLI 里对 AI 编码价值最高的一条命令，值得单独展开。

它解决的是什么问题

AI 写 Android 代码最常见的失效模式是凭记忆用过时 API ：写出早已废弃的 Camera.CameraInfo、漏掉 Android 15 的权限变更、用错已更名的方法。根因是模型的知识来自训练语料快照，而 Android 每年都在变。

android docs 把官方 Knowledge Base 变成命令行接口，让模型在写代码前先拿到一手文档。

能力边界：只有两条命令

bash 复制代码

android docs search "<查询词>"      # 搜索，返回标题 + kb:// URL + 摘要

android docs fetch "kb://..."       # 拉取指定文档全文

没有第三种用法。它刻意做得很窄 ------ 只做检索和取全文，不做其他事。

search：返回什么

首次执行会自动下载并建立本地索引，实测输出：

bash 复制代码

Index created with 5319 items and committed.

搜索"camera"：

bash 复制代码

1. Migrate Camera1 to CameraX

   URL: kb://android/media/camera/camerax/camera1-to-camerax

   Learn how to migrate legacy Android camera implementations...


2. Camera Enumeration

   URL: kb://android/media/camera/camera2/camera-enumeration

   This document explains how to list camera lenses and their capabilities...

搜索短语效果更好。实测搜 "predictive back gesture" 精准命中：

bash 复制代码

1. Add support for the predictive back gesture

   URL: kb://android/guide/navigation/custom-back/predictive-back-gesture

2. Predictive back gesture navigation with Compose

   URL: kb://android/develop/ui/compose/system/predictive-back

3. Predictive back design

   URL: kb://android/design/ui/mobile/guides/patterns/predictive-back

用法要点：

多个关键词用英文引号包起来，作为短语检索
返回是有序列表 ，kb:// URL 可直接喂给 fetch
结果里的摘要已足够判断相关性，可先看摘要再决定是否 fetch，省 token

fetch：拿到的是可读的 Markdown 全文

实测抓取 Camera2 主页：

bash 复制代码

android docs fetch kb://android/media/camera/camera2/index

返回结构：

bash 复制代码

Title: Camera2

URL: kb://android/media/camera/camera2/index

----------------------------------------

**Note:** This page refers to the Camera2 package. Unless your app requires

specific, low-level features from Camera2, we recommend using CameraX...


- [Camera2 basics](https://github.com/android/camera-samples/tree/main/Camera2Basic)

- [Camera2 extensions](https://github.com/android/camera-samples/tree/main/Camera2Extensions)

三个关键点：

正文是 Markdown，不是 HTML ------ 可以直接喂给模型，或存成 .md 进知识库
kb:// 链接会渲染成真实的 developer.android.com 链接 ------ 内容可以溯源到官网核对
保留官方示例代码仓库地址 ------ 上例直接给出了 GitHub 上的 Camera2 sample 路径

落地用法：查 → 取 → 存

推荐的日常工作流：

bash 复制代码

# 1. 搜

android docs search "car parked app quality"


# 2. 看摘要挑最相关的一条，复制它的 kb:// URL


# 3. 取全文存档，作为写代码的依据

android docs fetch kb://android/... > ./car-parked-app.md

对 AI 协作场景，可以把第 3 步的产物直接塞进上下文，替代"让模型自己回忆 API"。

一条实用的元规则

凡是要写 Android API 调用，先 docs search 再写。

这条规则的价值不在于"查文档"本身，而在于它把知识来源从模型记忆切换到官方文档。对于变动频繁的领域，效果尤其明显。

五、能力全景：17 个顶层子命令

按抽象程度从高到低，可归为四层：

L4 文档与代码智能

命令	作用
`android docs search "关键词"`	搜索官方 Knowledge Base（详见第四章）
`android docs fetch kb://...`	拉取指定文档全文
`android studio check`	检查 Android Studio 实例状态
`android studio find-usages`	查符号引用
`android studio find-declaration`	查符号声明
`android studio analyze-file`	分析文件
`android studio open-file`	在 Android Studio 中打开文件
`android studio render-compose-preview`	渲染 Compose `@Preview`
`android studio version-lookup`	查 Maven 构件 / Android 版本最新号

version-lookup 值得单独提一句 ------ 它把"该用哪个版本的依赖"这个高频决策自动化了。

⚠️ studio 有两个硬前提（实测确认）：

必须用 Android Studio Quail 2 或更高版本

打开项目 ------ 官网明确写出的 IDE 版本要求，比"Studio 在运行"严格得多。

--pid

与 --project 通常自动推断：只开了一个实例、或从项目目录内调用时无需手动指定。多实例场景才需要显式传。

L3 界面观察与输入

命令	作用
`android layout --pretty`	输出 UI 布局树（JSON）
`android screen capture --annotate`	截图 + 自动标注 UI 元素编号
`android screen resolve`	把标注框编号替换成坐标
`android input tap / text / swipe / scroll / key`	语义化 UI 操作

layout 的三个关键选项（实测确认，容易踩坑）：

bash 复制代码

android layout --pretty              # 默认只返回"可交互元素"，不是全树

android layout --full                # 要全树（含非交互元素）必须显式加

android layout --no-idle             # 不等 idle 就抓，适用于动画/长任务界面

android layout --flat                # 扁平列表代替树形结构

--full 这个默认值设计很容易让人误判 ------ 直接抓 layout 看到的只是交互元素子集，排查布局问题时要记得加。

screen capture --annotate 的调参能力 （1.0.16406183 起公开，官网称"记录在 --help 中"，实测确实存在）：

bash 复制代码

--features=PARAM                 # 特征检测算法

--edge-thresh-weak / --edge-thresh-strong   # Canny 边缘检测双阈值

--min-area / --min-rect / --min-round        # 形状过滤：面积、长宽比、圆度

--min-nested-area                            # 父特征最小面积

--threshold / --distance                     # 聚类策略

--debug                                     # 输出中间检测步骤

标注不准时不用放弃，可以调参 ------ 这是 1.0.16406183 明确加入的能力。

input tap 支持等待与多匹配处理：

bash 复制代码

android input tap --match "text=确定" --wait 3000

# --match single   多个匹配时报错

# --match first    取第一个

注意 input text 的**参数顺序是 <内容> <选择器>**，与直觉相反：

bash 复制代码

android input text "hello" --match "text=搜索框"

一个值得注意的官方取向 ：Google 官方发布的 android-cli 技能文档，在"输入"这一节**并没有推荐 android input，而是回退到 adb shell input**：

bash 复制代码

### Input

Use `adb shell input` for interacting with Android devices.


To tap on this button, you would execute `adb shell input tap 152 23`.

这印证了一个判断：Android CLI 的定位是"观察与编排"，不是替代 adb 的全部能力 。遇到需要精细控制的动作，官方自己也会选 adb。android input --match 虽然存在且更语义化，但官方技能里并未把它作为首选。

emulator start 是阻塞式的 ------ 命令返回时模拟器已完全就绪，无需再 sleep 等待：

bash 复制代码

android emulator start <AVD名>

android emulator start <AVD名> --cold       # 不加载快照，冷启动

android emulator start <AVD名> --headless   # 无窗口，适合 CI

注意 android emulator 的子命令是大小写不敏感的（1.0.15857036 起），命令名匹配更宽松。

L2 部署与目标控制（日常主战场）

命令	作用
`android run --apks --activity --debug`	构建→安装→启动一步到位
`android install --apks`	仅安装不激活
`android emulator start / stop / list / create`	虚拟设备管理
`android device remote`	远程真机预留与连接

增量安装是 run 与 install 的默认行为 （--use-delta-install 默认 true）：只传输变更的代码与资源，比整包覆盖快。

L1 项目与 SDK 基建

命令	作用
`android create --list`	列出可用项目模板
`android sdk install / list / update / remove`	管理 SDK 组件
`android sdk materialize / resolve`	跨平台组件定位、SHA 解析
`android describe --project_dir`	输出项目结构与构建产物路径 JSON
`android info`	环境自检（SDK、已连设备、配置变量）
`android auth login / logout / status`	Google 服务登录
`android completion [bash	zsh]`
`android update`	更新 CLI 本身

实测 create --list 当前只有一个模板：

bash 复制代码

Template name          Template description    Tags

empty-activity         Empty Activity           compose,activity,agp-9

从 1.0.15498356 起，模板从 SDK 软件包动态下载而非打包在二进制里，所以新建项目总是用最新模板。

completion 是 1.0.16251017 新增的，做法很省心：

bash 复制代码

android completion bash    # 打印脚本

android completion zsh     # 不传 shell 参数则直接安装到用户 profile

全局选项（可与任意命令组合）

bash 复制代码

android --sdk=<path/to/sdk> <command>   # 临时切换 SDK，不改全局环境变量

android -v / -vv / -vvv <command>        # 递进式详细输出

android -V                               # 打印版本

android <command> -h                     # 任意命令的独立帮助

1.0.16406183 起所有主要命令失败时返回非零退出码 （create、run、install、describe、layout、docs、info、skills、update）------ 这对脚本和 CI 是关键改进，之前失败也可能返回 0。

六、Journey：用自然语言测应用，代理当"操作员"

这是 Android CLI 最被低估的一环，也是官网单独开了一个页面讲的能力。

它是什么

Journey（历程）= 用自然语言描述的一段用户流程 。你写"打开应用 → 登录 → 搜索 camera → 打开设置"，选定的 Agent 负责把这些指令翻译成与设备的实际交互，并且能写断言 ------ 代理会根据它在设备上实际看到的内容来评估断言是否成立。

三个关键特性

视觉 + 推理驱动

：不依赖固定选择器，代理靠看懂屏幕来操作
断言由代理评估

：可以描述复杂断言，代理依据设备上的真实内容判断
可在 CI/CD 部署

：因为整套流程都在终端里跑，天然适合流水线

快速开始

不需要写任何代码 ------ 直接让代理帮你创建：

bash 复制代码

为我的应用核心体验创建几个 Journey，覆盖登录、搜索、设置三个流程

然后让智能体在设备上跑这些 Journey。

XML 格式（需要精细控制时）

android-cli 技能文档里有最完整的 150 行 Journey 测试规范，要求包括：

每步严格照做，不得推断意图

------ 原文："If an action says to 'tap the first search result', you MUST find the search results and tap the first one. Do this even if you believe you know the intent behind the action."
失败是预期内的，禁止 AI 急着改 bug

------ 原文："evaluate it as a test. Failure is acceptable, and often expected. Keep debugging and troubleshooting to a minimum"
journey XML 是唯一事实来源

：应用行为与 journey 描述不一致，即判定为失败
固定 Markdown 报告格式（✅/❌ 标记 + Commands + Comment）

这几条约束的设计意图很明确：**防止 Agent 把"测试"偷偷做成"调试"**。Agent 天生倾向于让测试通过，需要用规范把它按回测试的角色。

和 Android Studio Journeys 的区别

官网特别注明：如果你用的是 Android Studio，请看 Android Studio 学习之旅，那是另一套东西。CLI 版的价值在于不依赖 IDE、可进 CI。

七、它与 adb 的架构关系

关键认知 ：Android CLI 不是 adb 的替代品，而是 adb 之上的编排层。三条设计线索：

复用而非重写

：底层仍走 adb 与 SDK 工具链。CLI 解决的是"命令组合"问题，不是"传输协议"问题。
逃生通道始终保留

：所有能力都能回退到裸 adb。CLI 不制造锁定。
技能层独立于 CLI 之上

：35 个技能包可被任意 AI Agent 宿主加载，CLI 本身只是这些技能的一个调用方。

八、35 个官方技能：真正面向 AI Agent 的部分

bash 复制代码

android skills list          # 列出已安装与可用技能

android skills find camera   # 按关键词搜索

android skills add <id>      # 安装指定技能

android skills remove <id>   # 卸载

android skills update        # 批量更新

技能落盘在 ~/.android/cli/skills/<域>/<技能名>/SKILL.md，同步目标包含 codebuddy、claude-code、cursor、windsurf 等 36 个 Agent 宿主。

按功能域看，密度最高的三块：

域	数量	代表技能
性能分析	3	`android-profiler`、`perfetto-sql`、`perfetto-trace-analysis`
Compose UI	3	`adaptive`、`jetpack-compose-performance`、`styles`
Wear OS	3	`jetpack-compose-m3`、`wear-widgets`

其余功能域包括：安全审计（2）、导航（2）、身份认证（2）、车载 parked app（1）、媒体投屏（1）、TV 与 XR（3）、项目与测试基建（4）等。可用 android skills find <关键词> 按需检索。

技能怎么被激活：自动 or 手动

bash 复制代码

# 默认输出带详细信息：技能说明 + 已为哪些代理安装

android skills list


# 只看为某个代理安装的技能

android skills list --agent <agent>

激活方式取决于宿主：

宿主	激活方式
Android Studio	自动按语义匹配；也可在聊天框直接敲 `@skill-name` 手动调用
其他任意 Agent	自动 ------ 提示词里描述任务即可，例如 "Make my app UI edge-to-edge"

⚠️ 一个实践上容易踩的坑：如果你自定义过某个技能，必须改名，否则 skills add 更新时会被官方版本直接覆盖。

技能是怎么让 AI "知道"这个工具的

关键在 SKILL.md 开头的 YAML 元数据 ------ 那是唯一写给模型看的部分。以入口技能 android-cli 为例：

bash 复制代码

---

name: android-cli

description: Provides instructions for installing and using the `android` CLI.

  The `android` command-line tool is a critical tool for Android development

  and helps you create new Android projects, install APKs onto devices and

  emulators and launch and run apps on them, manage and interact with Android

  virtual devices (including screenshots and UI inspection), manage Android SDK

  components, look up official Android documentation, and discover and install

  official Android skills.

license: Complete terms in LICENSE.txt

metadata:

  author: Google LLC

  keywords:

  - android-cli

  - sdk

  - emulator

  - skills

  - docs

  - knowledge base

  - project creation

  - screenshots

---

注意 description 的写法：它不描述"这个技能是什么"，而是逐条枚举这个工具能替你完成哪些事 。模型在会话开始时扫描所有技能的 name 与 description，当你的提问与这段描述语义相似时就自动加载。所以：

你说	命中依据
"把 APK 装到模拟器上跑起来"	`install APKs onto devices and emulators and launch and run apps on them`
"帮我查下 CameraX 怎么用"	`look up official Android documentation`
"截个图看看界面"	`screenshots and UI inspection`

这也解释了一个常见困惑：工具类技能 （android-cli）教 AI 怎么用工具，领域类技能 （camerax、perfetto-sql）提供领域知识，两者配合才完整。

前提：这套自动发现机制要求技能已被同步到对应的 Agent 宿主。若目标宿主未安装该技能，就需要主动点名，例如"用 android CLI 把 APK 装到模拟器"。

九、开发中如何落地使用

场景 A：日常调试闭环

bash 复制代码

# 1. 起一个模拟器（先用 list 查看可用的 AVD 名）

android emulator list

# 输出形如：Pixel_8_API_34 / my_avd_api_33


android emulator start <AVD名>


# 2. 部署并启动

android run --apks=app-debug.apk --activity=com.example.MainActivity --debug


# 3. 观察当前界面

android layout --pretty --output=tree.json


# 4. 操作（语义定位，不写死坐标）

android input tap --match "text=设置" --wait 2000


# 5. 截图取证

android screen capture --output=shot.png

场景 B：让 AI Agent 驱动 UI 自动化

这是 CLI 与 Agent 生态结合最紧密的一环：

bash 复制代码

# 1. 截取带标注的界面

android screen capture --annotate --output=shot.png


# 2. 用编号描述操作意图，交给 resolve 换成坐标

android screen resolve --screenshot=shot.png \

  --string="tap #2 then type #3 with 'hello'"

Agent 只需输出"点 $#2$ (javascript:😉"，坐标由 CLI 计算 ------ 彻底消除了 LLM 输出坐标不准这个老大难问题。

场景 C：让 Journey 进 CI

bash 复制代码

# 1. 本地先让 Agent 生成 Journey，覆盖核心体验

#    "为我的应用创建 Journey，覆盖登录、搜索、设置三个流程"


# 2. 在 CI 里跑（CLI 版不依赖 IDE，这是关键优势）

android emulator start <AVD名> --headless

android run --apks=app-debug.apk --activity=com.example.MainActivity

# → 交给 Agent 执行 Journey 并输出报告

因为整套流程都在终端里，Journeys 可以直接进 CI/CD，这是它与 Android Studio 版 Journeys 最大的差异。

场景 D：查一手文档，避免用过时 API

bash 复制代码

android docs search "CameraX"

android docs fetch kb://android/media/camera/camerax/camera1-to-camerax

建议把这一步固化进 AI 编码流程：先查官方文档，再写代码。

场景 E：把 adb 脚本渐进迁移

不必一次性替换。策略是：

新脚本优先用 android
存量脚本遇到 UI 操作、部署环节时，逐条换成 android 对应命令
保留裸 adb 作为排查底层问题（如端口占用、连接异常）的手段

迁移时注意两条 CLI 的语义变化 ：layout 默认只给可交互元素（要全树得加 --full），input swipe 的距离是屏幕比例不是像素。直接照搬旧脚本的坐标参数会静默出错。

十、上手前必须知道的限制与差异

撰写时实测的几点，供评估时参考。带「官方」标记的是官网明确声明的限制：

官方声明的限制

Windows 上 android emulator 命令已停用
不支持从 Windows PowerShell 下载 Android CLI

，须用 CMD
studio

命令要求 Android Studio Quail 2 或更高版本
自定义技能仅支持放在项目代码库中 （.skills/ 或 .agent/skills/），不支持全局自定义
自定义技能若未改名，skills add 更新时会被官方版本覆盖

实测发现

create

模板目前只有一个 （empty-activity），项目脚手架能力尚不丰富
layout默认只返回可交互元素

，抓全树必须显式加 --full
input swipe

用 --dir 指定方向、--distance 用屏幕比例（0.0--1.0），不是像素
技能列表输出存在重复行 （agp-9-upgrade、android-cli 各出现两次），用脚本处理时需去重
部分命令会产生 Failed to persist metric to spool 警告，属统计写入噪音，不影响功能
CLI 默认上报使用数据（只收选项名不收值），停用加 --no-metrics

版本节奏

1.0.x 的迭代很密（2026 年 4 月 0.7 首版 → 5 月两个版本 → 7 月两个 → 9 月三个），**建议定期 android update**。官方提示更新后能拿到约一倍的启动提速（原生下载器库改为按需加载）。

与官网文档的对照说明

本文以本地实测为准，与官网文档存在两处已知差异，读者注意甄别：

项	官网文档	本地实测（v1.0.16625370）
命令参考页	列出 17 个顶层命令，未列 `input`	`android --help` 实际输出含 `input`（帮助文本为 "Interact with Android apps by performing gestures and key events on UI elements"）
`--no-metrics`	作为全局停用标志说明	在 `run` / `screen` 等命令的 `--help` 中未检出，可能在未文档化的路径或由 `update` 等特定命令处理

除上述两点外，命令清单、技能机制、安装方式等均与官网一致。

附：本文命令速查

bash 复制代码

# 环境

android init                      # 首次初始化（必做，同时装 android-cli 技能）

android info                      # 环境自检（SDK / 已连设备 / 配置变量）

android update                    # 更新 CLI 本身

android completion zsh            # 安装 shell 自动补全

export JAVA_TOOL_OPTIONS=""       # 若被其他工具污染


# 全局选项（可与任意命令组合）

android --sdk=<path> <command>   # 临时切 SDK，不改环境变量

android -vv <command>             # 递进式详细输出


# 项目

android create --list

android create MyApp --application-id=com.example.myapp --min-sdk=33

android describe --project_dir=.  # 输出构建产物路径 JSON


# 设备

android emulator list

android emulator start <AVD名> --headless

android device remote list        # 远程真机（需 Google Cloud project）


# 部署

android run --apks=app.apk --activity=com.example.MainActivity --debug

android install --apks=a.apk,b.apk --install-options=-g,-d


# 观察与操作（注意 text 参数顺序：内容在前，选择器在后）

android layout --pretty --output=tree.json

android layout --full             # 默认只返回可交互元素，要全树必须加

android layout --no-idle          # 不等 idle 直接抓

android screen capture --annotate --output=shot.png

android screen capture --annotate --debug   # 输出中间检测步骤，调参用

android screen resolve --screenshot=shot.png --string="点击 #3"

android input tap --match "text=确定" --wait 3000

android input text "hello" --match "text=搜索框" --submit

android input swipe --match "text=列表" --dir=left --distance=0.6


# 文档与代码（studio 需 Android Studio Quail 2+）

android docs search "camera"

android docs fetch kb://android/media/camera/camerax/camera1-to-camerax

android studio check             # 先确认 Studio 实例可用

android studio version-lookup androidx.camera:camera-core

android studio render-compose-preview <file>


# 技能

android skills list

android skills list --agent <agent>   # 只看某代理已装的技能

android skills find perfetto

android skills add camerax

android skills update

附：官方文档索引

主题	链接
Android CLI 概览	https://developer.android.google.cn/tools/agents/android-cli?hl=zh-cn
下载（各平台安装方式）	https://developer.android.google.cn/tools/agents/android-cli/download?hl=zh-cn
命令参考	https://developer.android.google.cn/tools/agents/android-cli/commands?hl=zh-cn
Journey 支持	https://developer.android.google.cn/tools/agents/android-cli/journeys?hl=zh-cn
版本说明	https://developer.android.google.cn/tools/agents/android-cli/release-notes?hl=zh-cn
Android Skills 概览	https://developer.android.google.cn/tools/agents/android-skills?hl=zh-cn
技能浏览（24 个已上架）	https://developer.android.google.cn/tools/agents/android-skills/browse?hl=zh-cn
技能 GitHub 仓库	https://github.com/android/skills
Agent Skills 开放标准	https://agentskills.io/specification
报告 Bug	https://issuetracker.google.com/issues/new?component=2091212

Google 官方 Android CLI：让AI直接读布局结构而不是用adb截图验证

一、先说结论：它是什么

二、为什么要有这个工具：三个真实痛点

痛点 1：adb 是"零件"，不是"工具"

痛点 2：UI 自动化脚本会因分辨率而碎裂

痛点 3：知识是二手的，且会过时

三、下载与安装

安装方式：四条路，按权限需求选

验证安装

首次初始化：为 AI 装上技能

更新

数据收集：会收什么、不收什么

四、android docs：把官方文档变成可调用的接口

它解决的是什么问题

能力边界：只有两条命令

search：返回什么

fetch：拿到的是可读的 Markdown 全文

落地用法：查 → 取 → 存

一条实用的元规则

五、能力全景：17 个顶层子命令

L4 文档与代码智能

L3 界面观察与输入

L2 部署与目标控制（日常主战场）

L1 项目与 SDK 基建

全局选项（可与任意命令组合）

六、Journey：用自然语言测应用，代理当"操作员"

它是什么

三个关键特性

快速开始

XML 格式（需要精细控制时）

和 Android Studio Journeys 的区别

七、它与 adb 的架构关系

八、35 个官方技能：真正面向 AI Agent 的部分

技能怎么被激活：自动 or 手动

技能是怎么让 AI "知道"这个工具的

九、开发中如何落地使用

场景 A：日常调试闭环

场景 B：让 AI Agent 驱动 UI 自动化

场景 C：让 Journey 进 CI

场景 D：查一手文档，避免用过时 API

场景 E：把 adb 脚本渐进迁移

十、上手前必须知道的限制与差异

官方声明的限制

实测发现

版本节奏

与官网文档的对照说明

附：本文命令速查

附：官方文档索引

四、`android docs`：把官方文档变成可调用的接口