手机 ADB 操作助手

手机 ADB 操作助手#

本技能通过 adb 让 AI 实时查看并操作 Android 手机/模拟器：能截屏、读取 UI 层级（窗口控件结构）和当前前台窗口，执行点击、长按、滑动、滚动、文本输入、按键与 shell 命令。

• 不含脚本：本技能只有说明文字，没有脚本或可执行文件，不依赖 Python、Node 等运行时。
• 不需要联网：所有操作都走本地 adb 连接（USB 或局域网无线调试），不会访问任何外部服务。
• 会写文件：截屏和 UI 层级会保存到本机临时目录，也会在手机 /sdcard/ 下创建临时文件，用后删除。

什么时候用#

• 用户想让你"看一下手机现在是什么界面""手机上这个页面是什么样的"，或让你代替他操作手机（点某个按钮、滑动、输入、打开某个应用、执行命令）。
• 自动化场景：按界面状态循环执行"看屏幕 → 定位控件 → 操作 → 验证结果"。
• 设备调试：查当前前台应用、窗口焦点、分辨率、系统设置值。

前置条件#

1. 手机上开启开发者选项里的「USB 调试」（无线调试时用「无线调试」配对），允许本机的调试授权。
2. 本机已安装 adb（Android SDK Platform Tools），adb version 能正常运行；找不到时先装好或问用户 adb 路径。
3. 用 adb devices 确认设备已连接；多台设备时一律用 adb -s <序列号> ... 指定，不许默认操作第一台。

使用流程（每个任务都走这套）#

1. 确认连接：adb devices -l，确认目标设备在列且状态为 device（不是 unauthorized/offline）。无线连接可先 adb connect <ip>:5555。
2. 看当前状态（三步一起做，一次拿全）：
   • 截屏：adb shell screencap -p /sdcard/lz_screen.png 然后 adb pull /sdcard/lz_screen.png（存到本机临时目录，Windows 下不要用 exec-out 重定向，会损坏二进制）。
   • UI 层级：adb shell uiautomator dump /sdcard/lz_ui.xml 然后 adb pull /sdcard/lz_ui.xml（读 XML 里的节点：text、content-desc、resource-id、class、bounds）。
   • 前台窗口：adb shell dumpsys window windows | findstr /i "mCurrentFocus mFocusedApp"（PowerShell 用 Select-String；命令输出里确认当前焦点窗口）。
3. 分析并定计划：结合截图和 UI 层级，找出目标控件的 bounds（形如 [12,345][456,789]，中心点 ((左+右)/2, (上+下)/2)），优先按 text/content-desc/resource-id 匹配，不要凭截图猜坐标。先向用户说明"我要点哪个按钮、滑到哪里、执行什么命令"，得到同意再动手。
4. 执行操作：用下面的命令。
5. 验证：重新截屏 + UI dump 确认结果符合预期；不符合就继续调整，最多自动尝试 3 次，仍不行就停下问用户。
6. 清理：删除本机临时文件，以及手机上的 /sdcard/lz_screen.png、/sdcard/lz_ui.xml。

命令参考#

设备与连接#

用途	命令
列出设备	adb devices -l
无线连接	adb connect <ip>:5555（配对过或同网段）
断开	adb disconnect <ip>:5555
型号/系统	adb shell getprop ro.product.model、adb shell getprop ro.build.version.release
分辨率/密度	adb shell wm size、adb shell wm density

查看窗口情况#

用途	命令
截屏	adb shell screencap -p /sdcard/lz_screen.png + adb pull /sdcard/lz_screen.png
UI 层级（控件树）	adb shell uiautomator dump /sdcard/lz_ui.xml + adb pull /sdcard/lz_ui.xml
当前焦点窗口	adb shell dumpsys window windows（看 mCurrentFocus、mFocusedApp）
当前前台 Activity	adb shell dumpsys activity activities（看 topResumedActivity）
顶层界面详情	adb shell dumpsys activity top
屏幕/锁屏状态	adb shell dumpsys window policy
电量/网络等	adb shell dumpsys battery、adb shell dumpsys connectivity

操作手机#

用途	命令
点击	adb shell input tap <x> <y>
长按	adb shell input swipe <x> <y> <x> <y> 800（同一点停留 800ms，时长可调）
滑动	adb shell input swipe <x1> <y1> <x2> <y2> [时长ms]
滚动/翻页	向上滚：adb shell input swipe <cx> <cy+400> <cx> <cy-400> 300；向下滚方向相反
输入文本	adb shell input text 'hello%sworld'（空格用 %s；不支持中文，中文见下方剪贴板方案）
按键	adb shell input keyevent <keycode>（常用：3 HOME、4 BACK、66 ENTER、61 TAB、67 DEL、187 最近任务、26 电源、24/25 音量±、85 播放/暂停、86 停止、87/88 下一首/上一首、27 相机）
打开应用	adb shell monkey -p <包名> 1（启动默认入口），或 adb shell am start -n <包名>/<Activity>
停止应用	adb shell am force-stop <包名>
剪贴板（Android 10+）	读：adb shell cmd clipboard get-clipboard-text；写（部分版本可用）：adb shell cmd clipboard set-clipboard-text <文本>，不行就在手机上手动粘贴或改用 ADBKeyBoard 输入法
屏幕常亮	adb shell svc power stayon true（调试时用，结束任务后 false 还原）

执行命令（shell / 应用 / 系统设置）#

用途	命令
任意命令	adb shell <命令>（ls、ps、top -n 1、dumpsys meminfo 等）
列出应用	adb shell pm list packages（加 -3 只看第三方）
应用详情	adb shell dumpsys package <包名>
授权/撤销权限	adb shell pm grant <包名> <权限>、adb shell pm revoke <包名> <权限>
读系统设置	adb shell settings get global/system/secure <键>（如 settings get system screen_brightness）
写系统设置	adb shell settings put <命名空间> <键> <值>（如亮度 settings put system screen_brightness 200；飞行模式等部分键需 root，写前先读回验证）
看通知	adb shell dumpsys notification --noredact（部分设备/版本无权限返回空，属正常）
传文件	adb push <本地> /sdcard/<路径>、adb pull /sdcard/<路径> <本地>

必须遵守#

• 任何会改变手机状态的操作（点击、滑动、输入、按键、am/pm/settings 写入、卸载、清数据）执行前都要向用户说明并得到同意；多设备时只用用户指定的那一台（-s <序列号>）。
• 截屏和 UI 层级里可能包含通知、账号、聊天等敏感内容：只用于完成本次任务，不要外传、不要上传到任何服务、不要写进日志或文档。
• 输入密码、验证码、支付类操作一律停下，交还用户手动完成，不代为输入。
• 定位控件以 UI 层级 XML 里的 bounds 计算坐标，优先 text/content-desc/resource-id 匹配；宁可多读一次 UI 层级，不靠截图猜坐标。
• 不执行卸载应用、清除数据、恢复出厂设置这类不可逆操作，除非用户明确要求且自己确认后果。
• 每次操作后重新截屏/UI dump 验证；同一操作失败 3 次就停下，检查设备连接（adb devices、必要时 adb kill-server 后 adb start-server）并向用户报告，不要盲目重试。
• Windows 下截屏一律用「shell 内截屏 + adb pull」，不要用 adb exec-out screencap -p > 文件（PowerShell 重定向会破坏 PNG 二进制）。
• 临时文件命名统一带 lz_ 前缀，任务结束即清理本机与本机设备两侧的临时文件。