adb

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use ADB commands to interact with an Android device or emulator to complete a user-defined mission. Operates in a screenshot-act-verify loop until the mission is accomplished.

Usage:

```
/adb <mission>
```
— Describe what you want done on the device (e.g., "open Settings and enable Dark Mode")

Prerequisites:

```
adb
```
must be in PATH
A device or emulator must be connected

Instructions:

Verify ADB connectivity:
- Run
```
adb devices
```
  and confirm at least one device is listed (not "unauthorized")
- If no device is found, inform the user and STOP
- If multiple devices are found, use
```
AskUserQuestion
```
  to ask which device to target, then pass
```
-s <serial>
```
  to all subsequent
```
adb
```
  commands
Understand the mission:
- Parse
```
$ARGUMENTS
```
  as the mission description
- If
```
$ARGUMENTS
```
  is empty, use
```
AskUserQuestion
```
  to ask what the user wants to accomplish on the device
- Break the mission into a mental checklist of expected steps (do not output this — it's for your own planning)

Enter the screenshot-act-verify loop:

Repeat the following cycle until the mission is complete or you determine it cannot be completed:

a) Take a screenshot:

bash

mkdir -p .tmp && adb exec-out screencap -p > .tmp/screen.png

Read the screenshot with the
```
Read
```
tool to understand the current screen state

b) Analyze the screen:

Identify what app/screen is currently displayed
Determine what UI elements are visible (buttons, text fields, toggles, lists, etc.)
Assess progress toward the mission goal
If the screen is unclear or you need more detail about the UI element tree, run a UI dump:
bash
```
adb shell uiautomator dump /sdcard/ui.xml && adb pull /sdcard/ui.xml .tmp/ui.xml
```
Then read
```
.tmp/ui.xml
```
to get element bounds, text, and resource IDs for precise tap coordinates.

c) Decide and execute the next action:

Use one or more of these ADB commands:

Action	Command
Tap at coordinates	`adb shell input tap <x> <y>`
Swipe	`adb shell input swipe <x1> <y1> <x2> <y2> [duration_ms]`
Type text	`adb shell input text "<text>"`
Press Back	`adb shell input keyevent 4`
Press Home	`adb shell input keyevent 3`
Press Enter	`adb shell input keyevent 66`
Press Recent Apps	`adb shell input keyevent 187`
Launch an app	`adb shell am start -n <package>/<activity>`
Open a URL	`adb shell am start -a android.intent.action.VIEW -d "<url>"`
Long press	`adb shell input swipe <x> <y> <x> <y> 1000`

Coordinate tips:

When tapping a UI element, aim for its center based on the screenshot or the
```
bounds
```
attribute from the UI dump (e.g., bounds
```
[0,200][1080,350]
```
→ tap at
```
540,275
```
)
For scrolling down, swipe from the lower third to the upper third of the screen (e.g.,
```
adb shell input swipe 540 1500 540 500 300
```
)
For text input, tap the field first, wait briefly, then type

d) Wait and verify:

After each action, wait briefly for the UI to settle (
```
sleep 1
```
)
Take another screenshot to verify the action had the expected effect
If the action did not work as expected (e.g., wrong element tapped, dialog appeared, screen didn't change), adjust and retry
Do not retry the same failing action more than 2 times — if it keeps failing, try an alternative approach (different coordinates, different navigation path, use the UI dump for precise bounds)

Handle common situations:
- Keyboard covering the screen: After typing, press Back (
```
keyevent 4
```
  ) to dismiss the keyboard before taking a verification screenshot
- Dialogs/popups: If an unexpected dialog appears, read it and dismiss it appropriately (tap "OK", "Allow", "Deny", etc. based on what makes sense for the mission)
- Loading screens: If the screen shows a loading state, wait 2-3 seconds and take another screenshot
- App not installed: If the target app isn't found, inform the user and STOP
- Permission prompts: Grant permissions that are necessary for the mission (tap "Allow"), deny those that aren't relevant
- Screen locked: If the device shows a lock screen, try swiping up (
```
adb shell input swipe 540 1800 540 800
```
  ) to unlock. If a PIN/password is needed, ask the user
Check logcat when things go wrong:
- If an app crashes or behaves unexpectedly, check recent logs:
  bash
```
adb logcat -d -t 50
```
- Use the logs to understand what happened and inform the user if the issue is not recoverable
Mission complete:
- Once the mission objective is achieved, take a final screenshot as confirmation
- Present the final screenshot to the user with a brief summary:
```
## Mission Complete

<description of what was accomplished>

Final state: <what's currently on screen>
Actions taken: <count> steps
```
Cleanup:
- Remove temporary files:
  bash
```
rm -f .tmp/screen.png .tmp/ui.xml
```

使用ADB命令与Android设备或模拟器交互，完成用户定义的任务。按照截图-执行-验证循环运行，直到任务完成。

使用方法：

```
/adb <mission>
```
— 描述你想要在设备上完成的操作（例如："打开设置并启用深色模式"）

前置条件：

```
adb
```
必须已添加到系统PATH中
已连接一台设备或模拟器

使用说明：

验证ADB连接状态：
- 运行
```
adb devices
```
  并确认至少列出一台设备（状态不为"unauthorized"）
- 如果未找到设备，告知用户并停止运行
- 如果找到多台设备，使用
```
AskUserQuestion
```
  询问用户要操作哪台设备，之后所有
```
adb
```
  命令都需加上
```
-s <serial>
```
  参数
理解任务需求：
- 将
```
$ARGUMENTS
```
  解析为任务描述
- 如果
```
$ARGUMENTS
```
  为空，使用
```
AskUserQuestion
```
  询问用户想要在设备上完成什么操作
- 将任务拆解为预期步骤的心理检查清单（无需输出，仅用于你自己规划流程）

进入截图-执行-验证循环：

重复以下流程直到任务完成，或你判定任务无法完成：

a) 截图：

bash

mkdir -p .tmp && adb exec-out screencap -p > .tmp/screen.png

使用
```
Read
```
工具读取截图内容，识别当前屏幕状态

b) 分析屏幕内容：

识别当前显示的应用/界面
确定可见的UI元素（按钮、文本框、开关、列表等）
评估距离任务目标的进度
如果屏幕内容不清晰，或者你需要更多UI元素树的详细信息，运行UI导出命令：
bash
```
adb shell uiautomator dump /sdcard/ui.xml && adb pull /sdcard/ui.xml .tmp/ui.xml
```
然后读取
```
.tmp/ui.xml
```
获取元素边界、文本和资源ID，以确定精确的点击坐标。

c) 决策并执行下一步操作：

使用以下一个或多个ADB命令：

操作	命令
点击指定坐标	`adb shell input tap <x> <y>`
滑动	`adb shell input swipe <x1> <y1> <x2> <y2> [duration_ms]`
输入文本	`adb shell input text "<text>"`
按返回键	`adb shell input keyevent 4`
按主页键	`adb shell input keyevent 3`
按回车键	`adb shell input keyevent 66`
按最近应用键	`adb shell input keyevent 187`
启动应用	`adb shell am start -n <package>/<activity>`
打开URL	`adb shell am start -a android.intent.action.VIEW -d "<url>"`
长按	`adb shell input swipe <x> <y> <x> <y> 1000`

坐标使用提示：

点击UI元素时，根据截图或UI导出的
```
bounds
```
属性定位元素中心（例如边界
```
[0,200][1080,350]
```
→ 点击坐标
```
540,275
```
）
向下滚动时，从屏幕下三分之一处向上三分之一处滑动（例如：
```
adb shell input swipe 540 1500 540 500 300
```
）
输入文本时，先点击输入框，稍作等待后再输入

d) 等待并验证：

每次执行操作后，稍作等待让UI加载稳定（
```
sleep 1
```
）
再次截图验证操作达到了预期效果
如果操作未按预期运行（例如点错了元素、弹出了对话框、屏幕无变化），调整后重试
同一失败操作重试不要超过2次 — 如果持续失败，尝试替代方案（不同坐标、不同导航路径、使用UI导出获取精确边界）

处理常见场景：
- 键盘遮挡屏幕： 输入完成后，按返回键（
```
keyevent 4
```
  ）收起键盘，再拍摄验证截图
- 对话框/弹窗： 如果出现意外弹窗，读取内容后根据任务需求合理关闭（点击"OK"、"Allow"、"Deny"等符合任务目标的选项）
- 加载界面： 如果屏幕显示加载状态，等待2-3秒后再次截图
- 应用未安装： 如果未找到目标应用，告知用户并停止运行
- 权限申请弹窗： 授予任务所需的必要权限（点击"Allow"），拒绝无关权限
- 屏幕锁定： 如果设备显示锁屏界面，尝试上滑解锁（
```
adb shell input swipe 540 1800 540 800
```
  ）。如果需要PIN/密码，询问用户
出现问题时检查logcat：
- 如果应用崩溃或行为异常，查看最近的日志：
  bash
```
adb logcat -d -t 50
```
- 使用日志了解问题原因，如果问题无法恢复，告知用户
任务完成：
- 达成任务目标后，拍摄最终截图作为确认
- 向用户展示最终截图并附上简要说明：
```
## 任务完成

<已完成的操作描述>

最终状态：<当前屏幕显示内容>
执行操作：<数量>步
```
清理：
- 删除临时文件：
bash
```
rm -f .tmp/screen.png .tmp/ui.xml
```

Edge Cases

边界情况

If
```
adb
```
is not found in PATH, display setup instructions and STOP
If the device becomes disconnected mid-mission, attempt
```
adb devices
```
to check — if disconnected, inform the user and STOP
If the mission requires installing an app, ask the user for the APK path or package name before proceeding
If you get stuck in a loop (same screen after 3 attempts), take a UI dump, reassess, and try a completely different approach. If still stuck, inform the user and ask for guidance
If the screen resolution is unknown, read it from the first screenshot dimensions or run
```
adb shell wm size
```

如果系统PATH中找不到
```
adb
```
，显示安装配置说明并停止运行
任务执行过程中设备断开连接，尝试运行
```
adb devices
```
检查状态 — 如果已断开，告知用户并停止运行
如果任务需要安装应用，继续操作前询问用户APK路径或包名
如果陷入循环（3次尝试后仍停留在同一界面），导出UI内容重新评估，尝试完全不同的方案。如果仍然卡住，告知用户并请求指导
如果屏幕分辨率未知，从第一张截图的尺寸读取，或运行
```
adb shell wm size
```
获取