SKILL.md
7.8 KB查看排版效果| 1 | --- |
| 2 | name: adb-device-ops |
| 3 | description: "通过 adb 连接 Android 手机或模拟器，实时查看屏幕与窗口情况（截屏、UI 层级、前台窗口与当前焦点），并按需对手机执行点击、长按、滑动、滚动、文本输入、按键和任意 shell 命令等操作，适合让 AI 代替用户操作手机完成跨应用任务、自动化测试与设备调试。" |
| 4 | --- |
| 5 | |
| 6 | # 手机 ADB 操作助手 |
| 7 | |
| 8 | 本技能通过 adb 让 AI 实时查看并操作 Android 手机/模拟器：能截屏、读取 UI 层级（窗口控件结构）和当前前台窗口，执行点击、长按、滑动、滚动、文本输入、按键与 shell 命令。 |
| 9 | |
| 10 | - 不含脚本：本技能只有说明文字，没有脚本或可执行文件，不依赖 Python、Node 等运行时。 |
| 11 | - 不需要联网：所有操作都走本地 adb 连接（USB 或局域网无线调试），不会访问任何外部服务。 |
| 12 | - 会写文件：截屏和 UI 层级会保存到本机临时目录，也会在手机 `/sdcard/` 下创建临时文件，用后删除。 |
| 13 | |
| 14 | ## 什么时候用 |
| 15 | |
| 16 | - 用户想让你"看一下手机现在是什么界面""手机上这个页面是什么样的"，或让你代替他操作手机（点某个按钮、滑动、输入、打开某个应用、执行命令）。 |
| 17 | - 自动化场景：按界面状态循环执行"看屏幕 → 定位控件 → 操作 → 验证结果"。 |
| 18 | - 设备调试：查当前前台应用、窗口焦点、分辨率、系统设置值。 |
| 19 | |
| 20 | ## 前置条件 |
| 21 | |
| 22 | 1. 手机上开启开发者选项里的「USB 调试」（无线调试时用「无线调试」配对），允许本机的调试授权。 |
| 23 | 2. 本机已安装 adb（Android SDK Platform Tools），`adb version` 能正常运行；找不到时先装好或问用户 adb 路径。 |
| 24 | 3. 用 `adb devices` 确认设备已连接；多台设备时一律用 `adb -s <序列号> ...` 指定，不许默认操作第一台。 |
| 25 | |
| 26 | ## 使用流程（每个任务都走这套） |
| 27 | |
| 28 | 1. **确认连接**：`adb devices -l`，确认目标设备在列且状态为 `device`（不是 `unauthorized`/`offline`）。无线连接可先 `adb connect <ip>:5555`。 |
| 29 | 2. **看当前状态**（三步一起做，一次拿全）： |
| 30 | - 截屏：`adb shell screencap -p /sdcard/lz_screen.png` 然后 `adb pull /sdcard/lz_screen.png`（存到本机临时目录，Windows 下不要用 `exec-out` 重定向，会损坏二进制）。 |
| 31 | - UI 层级：`adb shell uiautomator dump /sdcard/lz_ui.xml` 然后 `adb pull /sdcard/lz_ui.xml`（读 XML 里的节点：`text`、`content-desc`、`resource-id`、`class`、`bounds`）。 |
| 32 | - 前台窗口：`adb shell dumpsys window windows | findstr /i "mCurrentFocus mFocusedApp"`（PowerShell 用 `Select-String`；命令输出里确认当前焦点窗口）。 |
| 33 | 3. **分析并定计划**：结合截图和 UI 层级，找出目标控件的 `bounds`（形如 `[12,345][456,789]`，中心点 `((左+右)/2, (上+下)/2)`），优先按 `text`/`content-desc`/`resource-id` 匹配，不要凭截图猜坐标。先向用户说明"我要点哪个按钮、滑到哪里、执行什么命令"，得到同意再动手。 |
| 34 | 4. **执行操作**：用下面的命令。 |
| 35 | 5. **验证**：重新截屏 + UI dump 确认结果符合预期；不符合就继续调整，最多自动尝试 3 次，仍不行就停下问用户。 |
| 36 | 6. **清理**：删除本机临时文件，以及手机上的 `/sdcard/lz_screen.png`、`/sdcard/lz_ui.xml`。 |
| 37 | |
| 38 | ## 命令参考 |
| 39 | |
| 40 | ### 设备与连接 |
| 41 | |
| 42 | | 用途 | 命令 | |
| 43 | |---|---| |
| 44 | | 列出设备 | `adb devices -l` | |
| 45 | | 无线连接 | `adb connect <ip>:5555`（配对过或同网段） | |
| 46 | | 断开 | `adb disconnect <ip>:5555` | |
| 47 | | 型号/系统 | `adb shell getprop ro.product.model`、`adb shell getprop ro.build.version.release` | |
| 48 | | 分辨率/密度 | `adb shell wm size`、`adb shell wm density` | |
| 49 | |
| 50 | ### 查看窗口情况 |
| 51 | |
| 52 | | 用途 | 命令 | |
| 53 | |---|---| |
| 54 | | 截屏 | `adb shell screencap -p /sdcard/lz_screen.png` + `adb pull /sdcard/lz_screen.png` | |
| 55 | | UI 层级（控件树） | `adb shell uiautomator dump /sdcard/lz_ui.xml` + `adb pull /sdcard/lz_ui.xml` | |
| 56 | | 当前焦点窗口 | `adb shell dumpsys window windows`（看 `mCurrentFocus`、`mFocusedApp`） | |
| 57 | | 当前前台 Activity | `adb shell dumpsys activity activities`（看 `topResumedActivity`） | |
| 58 | | 顶层界面详情 | `adb shell dumpsys activity top` | |
| 59 | | 屏幕/锁屏状态 | `adb shell dumpsys window policy` | |
| 60 | | 电量/网络等 | `adb shell dumpsys battery`、`adb shell dumpsys connectivity` | |
| 61 | |
| 62 | ### 操作手机 |
| 63 | |
| 64 | | 用途 | 命令 | |
| 65 | |---|---| |
| 66 | | 点击 | `adb shell input tap <x> <y>` | |
| 67 | | 长按 | `adb shell input swipe <x> <y> <x> <y> 800`（同一点停留 800ms，时长可调） | |
| 68 | | 滑动 | `adb shell input swipe <x1> <y1> <x2> <y2> [时长ms]` | |
| 69 | | 滚动/翻页 | 向上滚：`adb shell input swipe <cx> <cy+400> <cx> <cy-400> 300`；向下滚方向相反 | |
| 70 | | 输入文本 | `adb shell input text 'hello%sworld'`（空格用 `%s`；不支持中文，中文见下方剪贴板方案） | |
| 71 | | 按键 | `adb shell input keyevent <keycode>`（常用：`3` HOME、`4` BACK、`66` ENTER、`61` TAB、`67` DEL、`187` 最近任务、`26` 电源、`24/25` 音量±、`85` 播放/暂停、`86` 停止、`87/88` 下一首/上一首、`27` 相机） | |
| 72 | | 打开应用 | `adb shell monkey -p <包名> 1`（启动默认入口），或 `adb shell am start -n <包名>/<Activity>` | |
| 73 | | 停止应用 | `adb shell am force-stop <包名>` | |
| 74 | | 剪贴板（Android 10+） | 读：`adb shell cmd clipboard get-clipboard-text`；写（部分版本可用）：`adb shell cmd clipboard set-clipboard-text <文本>`，不行就在手机上手动粘贴或改用 ADBKeyBoard 输入法 | |
| 75 | | 屏幕常亮 | `adb shell svc power stayon true`（调试时用，结束任务后 `false` 还原） | |
| 76 | |
| 77 | ### 执行命令（shell / 应用 / 系统设置） |
| 78 | |
| 79 | | 用途 | 命令 | |
| 80 | |---|---| |
| 81 | | 任意命令 | `adb shell <命令>`（`ls`、`ps`、`top -n 1`、`dumpsys meminfo` 等） | |
| 82 | | 列出应用 | `adb shell pm list packages`（加 `-3` 只看第三方） | |
| 83 | | 应用详情 | `adb shell dumpsys package <包名>` | |
| 84 | | 授权/撤销权限 | `adb shell pm grant <包名> <权限>`、`adb shell pm revoke <包名> <权限>` | |
| 85 | | 读系统设置 | `adb shell settings get global/system/secure <键>`（如 `settings get system screen_brightness`） | |
| 86 | | 写系统设置 | `adb shell settings put <命名空间> <键> <值>`（如亮度 `settings put system screen_brightness 200`；飞行模式等部分键需 root，写前先读回验证） | |
| 87 | | 看通知 | `adb shell dumpsys notification --noredact`（部分设备/版本无权限返回空，属正常） | |
| 88 | | 传文件 | `adb push <本地> /sdcard/<路径>`、`adb pull /sdcard/<路径> <本地>` | |
| 89 | |
| 90 | ## 必须遵守 |
| 91 | |
| 92 | - 任何会改变手机状态的操作（点击、滑动、输入、按键、`am`/`pm`/`settings` 写入、卸载、清数据）**执行前都要向用户说明并得到同意**；多设备时只用用户指定的那一台（`-s <序列号>`）。 |
| 93 | - 截屏和 UI 层级里可能包含通知、账号、聊天等敏感内容：只用于完成本次任务，不要外传、不要上传到任何服务、不要写进日志或文档。 |
| 94 | - 输入密码、验证码、支付类操作一律停下，交还用户手动完成，不代为输入。 |
| 95 | - 定位控件以 UI 层级 XML 里的 `bounds` 计算坐标，优先 `text`/`content-desc`/`resource-id` 匹配；宁可多读一次 UI 层级，不靠截图猜坐标。 |
| 96 | - 不执行卸载应用、清除数据、恢复出厂设置这类不可逆操作，除非用户明确要求且自己确认后果。 |
| 97 | - 每次操作后重新截屏/UI dump 验证；同一操作失败 3 次就停下，检查设备连接（`adb devices`、必要时 `adb kill-server` 后 `adb start-server`）并向用户报告，不要盲目重试。 |
| 98 | - Windows 下截屏一律用「shell 内截屏 + `adb pull`」，不要用 `adb exec-out screencap -p > 文件`（PowerShell 重定向会破坏 PNG 二进制）。 |
| 99 | - 临时文件命名统一带 `lz_` 前缀，任务结束即清理本机与本机设备两侧的临时文件。 |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
