android-use

Android 设备控制技能

此技能可让你控制通过 ADB（Android Debug Bridge）连接的 Android 设备。你既是推理引擎，也是执行引擎：直接读取设备的 UI 状态，并决定采取哪些操作。

前提条件

• Android 设备通过 USB 连接，并已启用 USB 调试
• 已安装 ADB，且可通过 PATH 访问
• 设备已获准进行调试（已接受“允许 USB 调试？”提示）

多设备支持

所有脚本都支持 -s <serial> 标志，可指定目标设备。当连接了多台设备时（例如，一台实体手机和一台模拟器），这项功能至关重要。

识别设备

运行 scripts/check-device.sh 查看所有已连接设备：

Multiple devices connected (2):

  [PHYSICAL] 1A051FDF6007PA - Pixel 6
  [EMULATOR] emulator-5554 - sdk_gphone64_arm64

Use -s <serial> to specify which device to use.

选择正确的设备

当用户提到：

• “phone”、“my phone”、“physical device” → 使用 [PHYSICAL] 设备
• “emulator”、“virtual device”、“AVD” → 使用 [EMULATOR] 设备
• 如果不明确，询问用户要操作哪台设备

使用序列号标志

确定目标设备后，在后续所有脚本中传入 -s <serial>：

# Check specific device
scripts/check-device.sh -s 1A051FDF6007PA

# All actions on that device
scripts/get-screen.sh -s 1A051FDF6007PA
scripts/tap.sh -s 1A051FDF6007PA 540 960
scripts/launch-app.sh -s 1A051FDF6007PA chrome

重要： 保持一致——在同一会话的所有命令中使用相同的序列号。

核心工作流

收到任务后，按以下感知—操作循环执行：

1. 检查设备连接——先运行 scripts/check-device.sh
   • 如果有多台设备：根据用户意图确定目标，或询问用户
   • 记下序列号，供后续命令使用
2. 获取当前屏幕状态——运行 scripts/get-screen.sh [-s serial] 导出 UI 层级结构
3. 分析 XML——读取无障碍树，了解屏幕上的内容
4. 决定下一步操作——根据目标和当前状态选择操作
5. 执行操作——根据需要，运行相应脚本并传入 -s serial
6. 稍作等待——留出时间让 UI 更新（通常为 500ms-1s）
7. 重复——返回第 2 步，直到完成目标

读取 UI XML

scripts/get-screen.sh 脚本会输出 Android 的无障碍 XML。需要查看的关键属性：

<node index="0" text="Settings" resource-id="com.android.settings:id/title"
      class="android.widget.TextView" content-desc=""
      bounds="[42,234][1038,345]" clickable="true" />

重要属性：

• text - 元素上显示的文本
• content-desc - 无障碍描述（对图标很有用）
• resource-id - 元素的唯一标识符
• bounds - 屏幕坐标，格式为 [left,top][right,bottom]
• clickable - 元素是否可响应点击
• scrollable - 元素是否可滚动
• focused - 元素是否获得输入焦点

计算点击坐标： 根据 bounds="[left,top][right,bottom]" 计算中心点：

• x = (left + right) / 2
• y = (top + bottom) / 2

示例：bounds="[42,234][1038,345]" → 在 x=540、y=289 处点击

可用脚本

所有脚本均位于 scripts/ 目录中。通过 bash 运行。

所有脚本都支持 -s <serial>，可指定目标设备。

设备管理

脚本	参数	说明
check-device.sh	[-s serial]	列出设备／验证连接
wake.sh	[-s serial]	唤醒设备并关闭锁屏
screenshot.sh	[-s serial]	截取屏幕图像

屏幕读取

脚本	参数	说明
get-screen.sh	[-s serial]	导出 UI 无障碍树

输入操作

脚本	参数	说明
tap.sh	[-s serial] x y	点击指定坐标
type-text.sh	[-s serial] "text"	输入文本字符串
swipe.sh	[-s serial] direction	向上／下／左／右滑动
key.sh	[-s serial] keyname	按下按键（home/back/enter/recent）

应用管理

脚本	参数	说明
launch-app.sh	[-s serial] package_or_name	按包名启动应用，或按名称搜索
install-apk.sh	[-s serial] path/to/file.apk	将 APK 安装到设备

操作指南

何时点击

• 点击目标可交互元素
• 始终根据边界计算中心点
• 优先选择 clickable="true" 的元素

何时输入

• 点击文本输入框后
• 输入框应具有 focused="true" 或 class="android.widget.EditText"
• 如有需要，先清除现有文本（全选并删除）

何时滑动

• 滚动列表或页面时
• 在屏幕间导航时（例如，左右滑动切换标签页）
• 方向：up（向下滚动）、down（向上滚动）、left、right

何时使用按键

• home - 返回主屏幕
• back - 返回 / 关闭对话框
• enter - 提交表单 / 确认
• recent - 打开最近使用的应用

何时截屏

• XML 未能提供足够信息，需要进行视觉调试时
• 验证视觉状态（颜色、图像等）时
• 任务需要视觉确认时

何时唤醒设备

• 开始任何任务前（设备可能已进入睡眠状态）
• get-screen.sh 返回空白或内容很少的 XML 时
• 操作似乎无效时（屏幕可能已关闭）
• 注意：这不会绕过 PIN、图案或密码，用户必须手动解锁

常见模式

打开应用

# By package name (fastest)
scripts/launch-app.sh com.android.chrome

# By app name (searches installed apps)
scripts/launch-app.sh "Chrome"

点击按钮

1. 获取屏幕内容：scripts/get-screen.sh
2. 查找文本 / content-desc 匹配的元素
3. 根据边界计算中心点
4. 点击：scripts/tap.sh 540 289

在输入框中输入文本

1. 点击文本输入框以聚焦
2. 等待键盘出现
3. 输入：scripts/type-text.sh "your text here"
4. 如有需要，按回车：scripts/key.sh enter

滚动查找内容

1. 获取屏幕内容，检查目标是否可见
2. 如果未找到，滑动：scripts/swipe.sh up
3. 再次获取屏幕内容，重复以上步骤，直到找到目标或到达末尾

处理对话框 / 弹窗

• 查找文本类似“OK”“Allow”“Accept”“Cancel”的元素
• 点击相应按钮
• 或按返回键关闭：scripts/key.sh back

错误处理

未连接设备

• 检查 USB 连接
• 确认已启用 USB 调试
• 手动运行 adb devices 进行故障排查

未找到元素

• UI 可能已发生变化，请重新获取屏幕内容
• 尝试滚动查找元素
• 元素可能位于不同的屏幕 / 状态中

操作无效

• 延长操作间隔（UI 可能较慢）
• 确认坐标是否正确
• 检查是否出现弹窗 / 对话框

应用无响应

• 按 home 键，然后重新打开应用
• 或强制关闭应用并重启

示例会话

单台设备

用户请求：“打开 Chrome 并搜索天气”

1. scripts/check-device.sh
   → Device connected: Pixel 6
   → Serial: 1A051FDF6007PA
   → Type: Physical

2. scripts/launch-app.sh com.android.chrome
   → Chrome launched

3. scripts/get-screen.sh
   → [Read XML, find search/URL bar]
   → Found: bounds="[0,141][1080,228]" resource-id="com.android.chrome:id/url_bar"
   → Center: x=540, y=184

4. scripts/tap.sh 540 184
   → Tapped URL bar

5. scripts/get-screen.sh
   → [Verify keyboard appeared and field is focused]

6. scripts/type-text.sh "weather"
   → Typed "weather"

7. scripts/key.sh enter
   → Pressed enter to search

8. scripts/get-screen.sh
   → [Verify search results loaded]
   → Task complete!

多台设备

用户请求：“在我的手机上打开 Settings”（模拟器也在运行）

1. scripts/check-device.sh
   → Multiple devices connected (2):
   →   [PHYSICAL] 1A051FDF6007PA - Pixel 6
   →   [EMULATOR] emulator-5554 - sdk_gphone64_arm64

   User said "my phone" → target the PHYSICAL device
   Serial to use: 1A051FDF6007PA

2. scripts/check-device.sh -s 1A051FDF6007PA
   → Device connected: Pixel 6
   → Serial: 1A051FDF6007PA
   → Type: Physical
   → Status: Ready

3. scripts/launch-app.sh -s 1A051FDF6007PA settings
   → Resolved 'settings' to package: com.android.settings
   → Launched: com.android.settings

4. scripts/get-screen.sh -s 1A051FDF6007PA
   → [Read XML, verify Settings app is open]
   → Task complete!

提示

• 耐心等待 - Android UI 可能较慢，请在操作间留出等待时间
• 仔细阅读 - XML 会准确告知屏幕上显示的内容
• 检查操作结果 - 每次操作后都获取屏幕内容，以验证状态
• 使用截图 - XML 未能提供足够上下文时使用
• 从简单任务开始 - 将复杂任务拆分为小步骤
• 多台设备 - 始终先检查是否有多台设备；目标不明确时询问用户
• 保持序列号一致 - 选定设备后，在所有命令中都使用 -s <serial>