Android ADB

支持通过自然语言或直接输入命令执行 ADB 操作，具备多设备支持、安全防护机制及沙箱化 ADB 安装能力。

工作流程

1. 列出设备：直接运行 adb devices -l。若命令失败（提示 command not found），进入 ADB 解析流程查找或安装 adb，然后重试。
2. 选择设备：若连接多个设备，先列出所有设备，并请用户选择目标设备。后续所有命令均需前置 -s 参数。
3. 将请求翻译为 ADB 命令：根据用户意图映射到对应 ADB 命令。完整命令参考见 references/adb-commands.md。
4. 安全检查：若命令具有破坏性（参见“危险操作”章节），需先向用户展示命令并获得明确确认后方可执行。
5. 执行与反馈：运行命令，解析输出结果，并以清晰易读的方式呈现给用户。

ADB 解析

当系统中未找到 adb 时，通过 scripts/adb_env.sh 进行解析，查找顺序为：系统 PATH → 常见 SDK 路径（~/Library/Android/sdk/、~/Android/Sdk/）→ sandbox 本地路径（/tools/platform-tools/adb）。

若上述路径均未找到，向用户询问：“ADB 未安装，是否需要我帮你安装到 skill 本地目录？（不影响系统配置）”

若用户同意，则执行 bash /scripts/install_adb.sh（无需 sudo 权限，不修改 PATH；卸载方式为 rm -rf /tools/）。

多设备处理

当 adb devices -l 返回多个设备时：

1. 显示带编号的设备列表，包含序列号（serial）、机型（model）和 Android 版本
2. 请用户从中选择一个设备（或选择 “all” 进行广播操作）
3. 记录所选设备的 serial，并在当前会话中所有命令前自动添加 -s
4. 在 skill 目录下运行 bash scripts/device_check.sh 获取设备快速概览

安全等级

快捷任务

设备信息

bash /scripts/device_check.sh

截图

bash /scripts/screenshot.sh [output_dir] [serial]

Logcat 日志捕获

bash /scripts/logcat_capture.sh all [output_file] [serial]
bash /scripts/logcat_capture.sh crash [output_file] [serial]
bash /scripts/logcat_capture.sh app  [output_file] [serial]
bash /scripts/logcat_capture.sh tag  [output_file] [serial]

长输出规则

当用户请求任何长时间运行或高冗余度的日志输出（如 logcat 流式输出、dropbox dump、dumpsys、大型 trace 输出等）时，除非用户明确指定了输出文件路径，否则一律新开一个系统终端窗口来显示输出。此举可为用户提供可滚动、可中断、专属的查看界面，且不会阻塞当前对话流。

仅当用户明确说出“保存到文件” / “输出到 xxx.txt” 或提供了具体文件路径时，才将内容写入文件。

macOS

osascript -e 'tell app "Terminal" to do script ""'

Linux（常见桌面环境）

# GNOME
gnome-terminal -- bash -c '; exec bash'
# KDE
konsole -e bash -c '; exec bash'
# 回退方案
x-terminal-emulator -e bash -c '; exec bash'

将 替换为实际命令，例如：

• adb logcat —— 全量日志
• adb logcat | grep -i "redirect" --line-buffered —— 按关键词过滤
• adb logcat -s MyTag:D —— 按 Tag 过滤
• adb logcat --pid=$(adb shell pidof com.example.app) —— 按应用进程过滤

zsh 兼容性说明

zsh 将 * 视为通配符。当命令中含 *（例如 Tag:*）时，必须在 osascript 字符串中对其转义：

# 错误 —— zsh 会提前展开 *
osascript -e 'tell app "Terminal" to do script "adb logcat -s MyTag:*"'
# 正确 —— 对 * 进行转义
osascript -e 'tell app "Terminal" to do script "adb logcat -s MyTag:\*"'

终端窗口启动后，需向用户明确报告：“已打开新终端窗口，正在运行以下命令：[命令]”。

常见场景

“安装这个 APK”

adb install -r 

若安装失败，请检查：设备存储空间（adb shell df -h）、已有应用版本、是否启用测试包标志（-t）。

“查看崩溃日志”

采用两级回退策略：

1. logcat crash buffer（首选）：

adb logcat -b crash -d | grep 

2. dropbox（当 crash buffer 为空时启用）：

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

步骤 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 ...

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

步骤 3 —— 用户选择后，在新终端窗口中展示对应条目：

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

“导出 UI 层级结构”

采用两级回退策略：

1. uiautomator dump（首选）：

adb shell uiautomator dump /sdcard/ui_dump.xml
adb pull /sdcard/ui_dump.xml 
adb shell rm /sdcard/ui_dump.xml

2. dumpsys activity top（回退方案 —— 部分设备如华为可能返回 could not get idle state）：

adb shell dumpsys activity top -a > 

该方式输出基于文本的 View Hierarchy（非 XML 格式），但包含等效的结构化信息。

“屏幕录制”

adb shell screenrecord /sdcard/recording.mp4              # 默认最长 180 秒
adb shell screenrecord --time-limit 30 /sdcard/recording.mp4  # 限制为 30 秒
# 按 Ctrl+C 停止录制，然后拉取：
adb pull /sdcard/recording.mp4 
adb shell rm /sdcard/recording.mp4

“当前前台运行的是哪个应用？”

adb shell dumpsys activity activities | grep mResumedActivity

“应用性能检查”

adb shell dumpsys meminfo 
adb shell dumpsys gfxinfo 
adb shell dumpsys cpuinfo | grep 

“通过 WiFi 连接设备”

adb tcpip 5555
# 查看设备 IP（通常来自 wlan 接口）：
adb shell ip route | grep wlan
adb connect :5555

危险操作

执行以下任一操作前，均须强制确认：

• pm clear —— 永久清除应用数据
• uninstall —— 卸载应用
• rm -rf —— 删除文件或目录
• reboot / reboot recovery / reboot bootloader
• factory reset / wipe_data
• fastboot flash —— 覆盖写入分区
• pm disable-user —— 禁用系统应用
• settings put —— 修改 system/secure/global 设置项
• setprop —— 修改系统属性
• su / adb root —— 提权至 root 权限
• sideload —— 刷入 OTA 包
• 对系统应用使用含 --user 0 的命令

需向用户准确展示待执行命令及一行风险说明，并等待其明确确认。

故障排查

参考文档

完整的 ADB 命令速查表（按功能分类整理），详见 references/adb-commands.md。