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 \x3Cserial> 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 (\x3Cskill_dir>/tools/platform-tools/adb).

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

If agreed, run bash \x3Cskill_dir>/scripts/install_adb.sh (no sudo, no PATH modification, uninstall via rm -rf \x3Cskill_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 \x3Cserial> for all commands in the session
4. Run bash scripts/device_check.sh in the skill directory for a quick overview

Safety Levels

Quick Tasks

Device Info

bash \x3Cskill_dir>/scripts/device_check.sh

Screenshot

bash \x3Cskill_dir>/scripts/screenshot.sh [output_dir] [serial]

Logcat Capture

bash \x3Cskill_dir>/scripts/logcat_capture.sh all [output_file] [serial]
bash \x3Cskill_dir>/scripts/logcat_capture.sh crash [output_file] [serial]
bash \x3Cskill_dir>/scripts/logcat_capture.sh app \x3Cpackage> [output_file] [serial]
bash \x3Cskill_dir>/scripts/logcat_capture.sh tag \x3CTAG> [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 "\x3Cadb_logcat_command>"'

Linux (common DEs)

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

Replace \x3Cadb_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 \x3Cpath.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 \x3Cpackage>

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 '\x3Ctag>' --since \x3Ctimestamp_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 \x3Clocal_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 > \x3Clocal_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 \x3Clocal_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 \x3Cpackage>
adb shell dumpsys gfxinfo \x3Cpackage>
adb shell dumpsys cpuinfo | grep \x3Cpackage>

"Connect via WiFi"

adb tcpip 5555
# Note the device IP from:
adb shell ip route | grep wlan
adb connect \x3Cip>: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

Reference

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