Android ADB#

Execute ADB commands via natural language or direct command input, with multi-device support, safety guardrails, and sandboxed ADB installation.

Workflow#

1. List devices: Directly run adb devices -l. If the command fails (command not found), go to ADB Resolution to find or install adb, then retry.
2. Select device: If multiple devices connected, list them and ask user to choose. Prepend -s <serial> to all subsequent commands.
3. Translate request to ADB command(s): Map the user's intent to appropriate ADB commands. See references/adb-commands.md for the full command reference.
4. Safety check: If the command is destructive (see Dangerous Operations), show the command and ask for confirmation before executing.
5. Execute and report: Run the command, parse output, and present results clearly.

ADB Resolution#

When adb is not found, resolve using scripts/adb_env.sh which checks in order: system PATH → common SDK paths ( ~/Library/Android/sdk/, ~/Android/Sdk/) → sandbox local ( <skill_dir>/tools/platform-tools/adb).

If none found, ask the user: "ADB 未安装，是否需要我帮你安装到 skill 本地目录？（不影响系统配置）"

If agreed, run bash <skill_dir>/scripts/install_adb.sh (no sudo, no PATH modification, uninstall via rm -rf <skill_dir>/tools/).

Multi-Device Handling#

When adb devices -l returns multiple devices:

1. Display a numbered list with serial, model, and Android version
2. Ask the user to pick one (or "all" for broadcast)
3. Store the chosen serial and use -s <serial> for all commands in the session
4. Run bash scripts/device_check.sh in the skill directory for a quick overview

Safety Levels#

LevelBehaviorExamplesSafeExecute directlyadb devices, logcat, screencap, getprop, pull, file listingModerateShow command, then executeinstall, push, am start, input tap, pm grantDangerousShow command, explain risk, require explicit "yes"pm clear, uninstall, factory reset, flash, wipe, reboot

Quick Tasks#

Device Info#

bash

bash <skill_dir>/scripts/device_check.sh

Screenshot#

bash

bash <skill_dir>/scripts/screenshot.sh [output_dir] [serial]

Logcat Capture#

bash

bash <skill_dir>/scripts/logcat_capture.sh all [output_file] [serial]
bash <skill_dir>/scripts/logcat_capture.sh crash [output_file] [serial]
bash <skill_dir>/scripts/logcat_capture.sh app <package> [output_file] [serial]
bash <skill_dir>/scripts/logcat_capture.sh tag <TAG> [output_file] [serial]

Long Output Rule#

When the user requests any long-running or verbose log output (logcat streaming, dropbox dump, dumpsys, large trace output, etc.), unless the user explicitly specifies an output file, always open a new system terminal window to display the output. This gives the user a scrollable, stoppable, dedicated view without blocking the conversation.

Only write to file when the user explicitly says "保存到文件" / "输出到 xxx.txt" / provides a file path.

macOS#

bash

osascript -e 'tell app "Terminal" to do script "<adb_logcat_command>"'

Linux (common DEs)#

bash

# GNOME
gnome-terminal -- bash -c '<adb_logcat_command>; exec bash'
# KDE
konsole -e bash -c '<adb_logcat_command>; exec bash'
# Fallback
x-terminal-emulator -e bash -c '<adb_logcat_command>; exec bash'

Replace <adb_logcat_command> with the actual command, e.g.:

• adb logcat — all logs
• adb logcat | grep -i "redirect" --line-buffered — filter by keyword
• adb logcat -s MyTag:D — filter by tag
• adb logcat --pid=$(adb shell pidof com.example.app) — filter by app

zsh compatibility#

zsh treats * as a glob wildcard. When the command contains * (e.g. Tag:*), escape it in the osascript string:

bash

# Wrong — zsh expands *
osascript -e 'tell app "Terminal" to do script "adb logcat -s MyTag:*"'
# Correct — escape the *
osascript -e 'tell app "Terminal" to do script "adb logcat -s MyTag:\\*"'

After launching, report to the user that the terminal window has been opened and what command is running.

Common Scenarios#

"Install this APK"#

bash

adb install -r <path.apk>

If install fails, check: device storage ( adb shell df -h), existing app version, test package flag ( -t).

"Show me crash logs"#

Two-level fallback:

1. logcat crash buffer (first try):

bash

adb logcat -b crash -d | grep <package>

1. dropbox (fallback if crash buffer is empty):

⚠️ 强制规则：严禁主动挑选 dropbox 条目。必须先列出所有条目，等用户选择后再输出内容。绝不允许跳过用户选择步骤。

Step 1 — 列出 dropbox 中所有 crash/anr 条目及其时间戳，供用户选择：

bash

adb shell dumpsys dropbox | grep -E "^[0-9].*(_crash|_anr)"

输出示例：

text

2026-04-09 11:04:34  data_app_anr (compressed text, 23807 bytes)
    Process: com.netease.cloudmusic:play/PID: 2553 ...
2026-04-09 10:23:45  data_app_crash (text, 1234 bytes)
    Process: com.example.app/PID: 1234 ...

Step 2 — 将列表 完整呈现 给用户（包含完整日期时间、类型、进程信息），然后 必须等待用户明确选择 要查看哪一条。 严禁自行判断、自动选择最近一条或任何一条。

Step 3 — 用户选择后，打开新终端窗口展示对应条目：

bash

# 使用用户选择的条目的时间戳
adb shell dumpsys dropbox --print '<tag>' --since <timestamp_ms>

"Dump UI hierarchy"#

Two-level fallback:

1. uiautomator dump (first try):

bash

adb shell uiautomator dump /sdcard/ui_dump.xml
adb pull /sdcard/ui_dump.xml <local_path>
adb shell rm /sdcard/ui_dump.xml

1. dumpsys activity top (fallback — some devices like Huawei may report could not get idle state):

bash

adb shell dumpsys activity top -a > <local_path>

This outputs a text-based View Hierarchy instead of XML, but contains equivalent structural info.

"Screen recording"#

bash

adb shell screenrecord /sdcard/recording.mp4              # default max 180s
adb shell screenrecord --time-limit 30 /sdcard/recording.mp4  # limit to 30s
# Ctrl+C to stop, then pull:
adb pull /sdcard/recording.mp4 <local_path>
adb shell rm /sdcard/recording.mp4

"Which app is in the foreground?"#

bash

adb shell dumpsys activity activities | grep mResumedActivity

"App performance check"#

bash

adb shell dumpsys meminfo <package>
adb shell dumpsys gfxinfo <package>
adb shell dumpsys cpuinfo | grep <package>

"Connect via WiFi"#

bash

adb tcpip 5555
# Note the device IP from:
adb shell ip route | grep wlan
adb connect <ip>:5555

Dangerous Operations#

Always confirm before executing any of:

• pm clear — wipes app data permanently
• uninstall — removes app
• rm -rf — deletes files/directories
• reboot / reboot recovery / reboot bootloader
• factory reset / wipe_data
• fastboot flash — overwrites partitions
• pm disable-user — disables system apps
• settings put — modifies system/secure/global settings
• setprop — changes system properties
• su / adb root — elevates to root privileges
• sideload — flashes OTA packages
• Any command with --user 0 on system packages

Present the exact command and a one-line risk description, then wait for explicit confirmation.

Troubleshooting#

IssueFixdevice not foundCheck USB cable, enable USB debugging in Developer Optionsdevice unauthorizedAccept RSA key prompt on device, or adb kill-server && adb start-server``multiple devicesUse -s <serial>``INSTALL_FAILED_*Check error suffix — common: ALREADY_EXISTS (use -r), INSUFFICIENT_STORAGE, OLDER_SDK``Permission deniedTry adb root or run-as <package>Command hangsCtrl+C, then adb kill-server && adb start-server

Reference#

For the full ADB command cheat sheet organized by category, see references/adb-commands.md.