Case 00519

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

Level	Behavior	Examples
Safe	Execute directly	adb devices, logcat, screencap, getprop, pull, file listing
Moderate	Show command, then execute	install, push, am start, input tap, pm grant
Dangerous	Show command, explain risk, require explicit "yes"	pm clear, uninstall, factory reset, flash, wipe, reboot

Quick Tasks

Device Info

bash <skill_dir>/scripts/device_check.sh

Screenshot

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

Logcat Capture

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

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

Linux (common DEs)

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

# 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"

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

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

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

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

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

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

输出示例：

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 — 用户选择后，打开新终端窗口展示对应条目：

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

"Dump UI hierarchy"

Two-level fallback:

1. uiautomator dump (first try):

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

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

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"

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?"

adb shell dumpsys activity activities | grep mResumedActivity

"App performance check"

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

"Connect via WiFi"

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

Issue	Fix
device not found	Check USB cable, enable USB debugging in Developer Options
device unauthorized	Accept RSA key prompt on device, or adb kill-server && adb start-server
multiple devices	Use -s <serial>
INSTALL_FAILED_*	Check error suffix — common: ALREADY_EXISTS (use -r), INSUFFICIENT_STORAGE, OLDER_SDK
Permission denied	Try adb root or run-as <package>
Command hangs	Ctrl+C, then adb kill-server && adb start-server

Reference

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