手机操控 Agent (蓝蓝版)

SKILL.md

---
name: phone-agent
description: 手机操控技能。通过 USB ADB 连接安卓手机，捕获屏幕、分析 UI 元素、执行点击/滑动/输入等操作。当用户要求操控手机、执行 App 操作、打开应用、发送消息时使用。
---

# 📱 手机操控技能 (phone-agent)

## 功能概览
- 通过 USB ADB 连接安卓手机
- 捕获手机屏幕（UI Dump，无需 AI 看图）
- 分析界面元素位置（XML 结构解析）
- 执行 UI 操作：点击、滑动、输入文字、按键
- 打开 App、搜索联系人、发送简单消息

## 限制
- ⚠️ 无法直接输入中文（ADB `input text` 绕过输入法，只能输入英文/数字/拼音）
- ⚠️ 需要 USB 调试权限
- ⚠️ 部分国产手机（如小米）需要额外开启"USB 调试安全设置"

---

## 第一部分：手机端配置（新手机一次性操作）

### 1. 开启开发者选项
1. 设置 → 关于手机 → 连续点击"MIUI 版本号"7次
2. 返回设置 → 更多设置 → 开发者选项

### 2. 开启 USB 调试
1. 开发者选项 → 开启"USB 调试"
2. **小米额外设置**：开发者选项 → 开启"USB 调试(安全设置)"
   - 这个需要 SIM 卡关联的小米账号登录后才能开启
   - 或者插 SIM 卡重启后自动解锁

### 3. 连接手机
1. 用 USB 线连接手机和 Mac（电脑）
2. 手机上弹出"允许 USB 调试"→ 点"允许"
3. 建议同时开启"充电模式下允许 ADB"

### 4. 调整手机设置（避免息屏断开）
1. 设置 → 显示 → 息屏时间 → 改为"最长"
2. 或保持手机在充电状态

### 5. 检查连接
```bash
adb devices
```
应显示设备 ID，如 `803203a    device`

---

## 第二部分：Skill 安装检查清单

### 依赖工具（已预装）
- ✅ `adb`（Android SDK Platform Tools）
- ✅ `python3`（内置）
- ✅ 截图工具（系统自带）

### 验证安装
```bash
# 检查 adb
adb version

# 检查 skill 脚本
ls -la ~/.openclaw/skills/phone-agent/agent.py
```

---

## 第三部分：Skill 使用方法

### 基本命令

```bash
# 查看连接状态
python3 ~/.openclaw/skills/phone-agent/agent.py connected

# 截图并保存到临时文件
python3 ~/.openclaw/skills/phone-agent/agent.py screenshot

# 获取屏幕尺寸
python3 ~/.openclaw/skills/phone-agent/agent.py size

# 点击坐标 (x, y)
python3 ~/.openclaw/skills/phone-agent/agent.py tap 500 1000

# 滑动 (x1, y1, x2, y2, duration)
python3 ~/.openclaw/skills/phone-agent/agent.py swipe 600 2400 600 800

# 输入文字（仅英文/数字）
python3 ~/.openclaw/skills/phone-agent/agent.py text "hello"

# 按键
python3 ~/.openclaw/skills/phone-agent/agent.py home      # HOME 键
python3 ~/.openclaw/skills/phone-agent/agent.py back      # 返回键
python3 ~/.openclaw/skills/phone-agent/agent.py power     # 电源键

# 启动 App（包名）
python3 ~/.openclaw/skills/phone-agent/agent.py start com.tencent.mm

# 强制停止 App
python3 ~/.openclaw/skills/phone-agent/agent.py stop com.tencent.mm
```

---

## 第四部分：典型工作流程

### 流程一：打开微信并搜索联系人

```bash
# 1. 启动微信
adb shell monkey -p com.tencent.mm -c android.intent.category.LAUNCHER 1

# 2. 等待启动后，dump UI 结构
adb exec-out uiautomator dump /sdcard/dump.xml && adb pull /sdcard/dump.xml /tmp/dump.xml

# 3. 分析 XML，找到搜索按钮坐标
python3 << 'EOF'
import xml.etree.ElementTree as ET
tree = ET.parse('/tmp/dump.xml')
root = tree.getroot()
for node in root.iter():
    text = node.attrib.get('text', '')
    bounds = node.attrib.get('bounds', '')
    if '搜索' in text or 'search' in text.lower():
        print(f"TEXT: {text}, BOUNDS: {bounds}")
EOF

# 4. 点击搜索按钮（如坐标 [912,140][1056,284]）
python3 ~/.openclaw/skills/phone-agent/agent.py tap 984 212

# 5. 输入搜索文字
python3 ~/.openclaw/skills/phone-agent/agent.py text "蓝汐"

# 6. 在搜索结果 XML 中找到联系人坐标，点击进入
```

### 流程二：发送消息

```bash
# 1. 在聊天界面，找到输入框和发送按钮的坐标
# 2. 点击输入框
python3 ~/.openclaw/skills/phone-agent/agent.py tap 540 2534

# 3. 输入文字
python3 ~/.openclaw/skills/phone-agent/agent.py text "hello"

# 4. 点击发送按钮（如坐标 [1020,1476][1170,1608]）
python3 ~/.openclaw/skills/phone-agent/agent.py tap 1095 1542
```

---

## 第五部分：UI Dump 分析指南

### 获取 UI 结构
```bash
adb exec-out uiautomator dump /sdcard/dump.xml && adb pull /sdcard/dump.xml /tmp/dump.xml
```

### 分析脚本
```python
import xml.etree.ElementTree as ET

tree = ET.parse('/tmp/dump.xml')
root = tree.getroot()

# 查找所有可点击元素
for node in root.iter():
    text = node.attrib.get('text', '')
    bounds = node.attrib.get('bounds', '')
    clickable = node.attrib.get('clickable', '')
    resource_id = node.attrib.get('resource-id', '')
    
    if clickable == 'true' and text:
        print(f"TEXT: {text!r}, BOUNDS: {bounds}, ID: {resource_id}")

# 查找特定关键词
for node in root.iter():
    text = node.attrib.get('text', '')
    bounds = node.attrib.get('bounds', '')
    if '微信' in text or '搜索' in text:
        print(f"FOUND: {text!r}, BOUNDS: {bounds}")
```

### 从 bounds 计算点击坐标
```python
# bounds = "[228,1766][1008,1835]"
# 中心点: x = (228+1008)/2 = 618, y = (1766+1835)/2 = 1800
```

---

## 第六部分：常见问题

### Q: USB 频繁断开
**A:** 
1. 手机息屏后会断开 → 开启"保持唤醒"或"充电模式下调试"
2. USB 线质量差 → 换一根好线
3. 重启 ADB: `adb kill-server && adb start-server`

### Q: 点击位置不准
**A:** 
1. 确认屏幕分辨率：`adb shell wm size`
2. UI Dump 的 bounds 是物理坐标，直接计算中心点点击
3. 多次点击有偏移可以调整 ±10-20 像素

### Q: 无法输入中文
**A:** 
- ADB `input text` 只能输入 ASCII 字符
- 解决方案：
  1. 在手机上预先打开输入法，让 AI 控制粘贴
  2. 使用 ClipboardManager（需要 App 配合）
  3. 通过 App Inventor 开发专用剪贴板 App

### Q: 小米手机点击无效
**A:** 
- 必须开启"USB 调试(安全设置)"
- 设置 → 更多设置 → 开发者选项 → USB 调试安全设置

### Q: 如何获取 App 包名？
**A:**
```bash
# 方法1: 列出已安装包
adb shell pm list packages | grep 关键词

# 方法2: 在 Play 商店查看 URL 中的 id
# 方法3: 用 UI Dump 分析桌面图标
```

---

## 附录：常用 App 包名

| App | 包名 |
|-----|------|
| 微信 | `com.tencent.mm` |
| QQ | `com.tencent.mobileqq` |
| 美团 | `com.sankuai.meituan` |
| 淘宝 | `com.taobao.taobao` |
| 支付宝 | `com.eg.android.AlipayGphone` |
| 抖音 | `com.ss.android.ugc.aweme` |
| 小红书 | `com.xingin.xhs` |
| Blued | `com.soft.blued` |