# 工作手机SDK v3.0 - 真机部署指南

> 如何将SDK连接到真实的Android手机
> 
> 适用手机：小米/红米、华为、OPPO、vivo、三星等所有Android手机

---

## 目录

1. [准备工作](#1-准备工作)
2. [USB连接方式](#2-usb连接方式)
3. [WiFi无线连接](#3-wifi无线连接)
4. [多台手机管理](#4-多台手机管理)
5. [常见问题解决](#5-常见问题解决)
6. [经验库使用](#6-经验库使用)

---

## 1. 准备工作

### 1.1 手机端设置

#### 第一步：开启开发者选项

| 品牌 | 操作路径 |
|------|----------|
| 小米/红米 | 设置 → 我的设备 → 全部参数 → 连续点击「MIUI版本」7次 |
| 华为 | 设置 → 关于手机 → 连续点击「版本号」7次 |
| OPPO | 设置 → 关于手机 → 连续点击「版本号」7次 |
| vivo | 设置 → 关于手机 → 版本信息 → 连续点击「软件版本号」7次 |
| 三星 | 设置 → 关于手机 → 软件信息 → 连续点击「编译编号」7次 |

#### 第二步：开启USB调试

进入「开发者选项」，打开以下开关：

- ✅ **USB调试**
- ✅ **USB安装**（如果有）
- ✅ **USB调试（安全设置）**（小米需要）
- ✅ **允许模拟位置**（可选）

#### 第三步：关闭USB调试授权超时（推荐）

- 小米：开发者选项 → 关闭「撤销USB调试授权」
- 其他：保持USB调试常开

### 1.2 电脑端准备

确保已安装ADB工具：

```bash
# macOS
brew install android-platform-tools

# 或使用SDK自带
export PATH=$PATH:/usr/local/share/android-commandlinetools/platform-tools

# 验证安装
adb version
```

---

## 2. USB连接方式

### 2.1 连接步骤

```
┌─────────────┐         USB线          ┌─────────────┐
│   电脑      │◄────────────────────────│   手机      │
│  (SDK服务)  │                        │ (开启USB调试)│
└─────────────┘                        └─────────────┘
```

**步骤：**

1. 用USB数据线连接手机到电脑
2. 手机上选择「传输文件(MTP)」模式
3. 弹出「允许USB调试吗？」对话框，勾选「始终允许」后点击「确定」

### 2.2 验证连接

```bash
# 查看设备
adb devices -l

# 预期输出
List of devices attached
XXXXXXXX       device usb:336592896X product:sagit model:MI_6 device:sagit transport_id:1
```

### 2.3 测试控制

```bash
# 截图测试
adb exec-out screencap -p > test.png

# 点击测试
adb shell input tap 540 1200

# 查看屏幕
scrcpy  # 如果安装了scrcpy
```

### 2.4 通过SDK API控制

```bash
# 先扫描设备
curl -X POST http://localhost:8899/api/v3/adb/scan

# 获取设备列表
curl http://localhost:8899/api/v3/adb/devices

# 截图
curl -X POST http://localhost:8899/api/v3/adb/devices/XXXXXXXX/screenshot
```

---

## 3. WiFi无线连接

### 3.1 首次设置（需要USB）

```bash
# 1. 先用USB连接手机
adb devices

# 2. 开启TCP/IP模式
adb tcpip 5555

# 3. 获取手机IP地址
adb shell ip addr show wlan0 | grep "inet "
# 或在手机上查看：设置 → WLAN → 点击已连接网络 → 查看IP

# 4. 断开USB，通过WiFi连接
adb connect 192.168.1.XXX:5555

# 5. 验证
adb devices
# 应显示: 192.168.1.XXX:5555    device
```

### 3.2 架构图

```
┌─────────────┐                        ┌─────────────┐
│   电脑      │       WiFi网络         │   手机      │
│  (SDK服务)  │◄──────────────────────►│ 192.168.1.X │
│             │      TCP 5555端口      │             │
└─────────────┘                        └─────────────┘
```

### 3.3 永久开启（需ROOT，可选）

如果手机已ROOT，可以设置开机自动开启ADB网络模式：

```bash
# 在手机上执行
su
setprop service.adb.tcp.port 5555
stop adbd
start adbd
```

### 3.4 通过SDK连接

```bash
# 连接WiFi设备
adb connect 192.168.1.100:5555

# 扫描设备
curl -X POST http://localhost:8899/api/v3/adb/scan

# 获取设备列表（设备ID为IP:端口）
curl http://localhost:8899/api/v3/adb/devices

# 控制设备
curl -X POST http://localhost:8899/api/v3/adb/devices/192.168.1.100:5555/screenshot
```

---

## 4. 多台手机管理

### 4.1 连接多台手机

```bash
# USB连接的手机
adb devices
# List of devices attached
# ABC123       device   # 手机1
# XYZ789       device   # 手机2

# WiFi连接的手机
adb connect 192.168.1.101:5555
adb connect 192.168.1.102:5555

# 所有设备
adb devices
# List of devices attached
# ABC123                device   # USB手机1
# XYZ789                device   # USB手机2
# 192.168.1.101:5555    device   # WiFi手机3
# 192.168.1.102:5555    device   # WiFi手机4
```

### 4.2 通过SDK管理

```bash
# 获取所有设备
curl http://localhost:8899/api/v3/adb/devices

# 响应示例
{
  "code": 200,
  "data": [
    {
      "serial": "ABC123",
      "model": "MI_6",
      "status": "online"
    },
    {
      "serial": "192.168.1.101:5555",
      "model": "Redmi_Note_12",
      "status": "online"
    }
  ]
}
```

### 4.3 指定设备操作

```bash
# 操作手机1
curl -X POST http://localhost:8899/api/v3/adb/devices/ABC123/screenshot

# 操作手机2
curl -X POST http://localhost:8899/api/v3/adb/devices/192.168.1.101:5555/screenshot
```

### 4.4 批量操作（PHP示例）

```php
$sdk = new WorkPhoneClient('http://localhost:8899', 'api-key');

// 获取所有在线设备
$devices = $sdk->getOnlineDevices();

// 向所有设备发送消息
foreach ($devices as $device) {
    $sdk->sendMessage(
        $device['serial'],
        'wechat',
        '客户群',
        '今日促销活动开始啦！'
    );
}
```

---

## 5. 常见问题解决

### Q1: 设备显示 unauthorized

**原因：** 手机上没有授权USB调试

**解决：**
1. 拔掉USB线重新连接
2. 手机上会弹出授权框，点击「允许」
3. 如果没弹出，进入开发者选项 → 撤销USB调试授权 → 重新连接

### Q2: 设备显示 offline

**原因：** ADB连接异常

**解决：**
```bash
adb kill-server
adb start-server
adb devices
```

### Q3: WiFi连接断开

**原因：** 手机休眠或网络变化

**解决：**
```bash
# 重新连接
adb connect 192.168.1.XXX:5555
```

**预防：**
- 手机设置 → 电池 → 后台活动管理 → 允许后台运行
- 保持手机在同一WiFi网络

### Q4: 小米手机无法安装APK

**原因：** 小米的安全限制

**解决：**
1. 开发者选项 → 开启「USB安装」
2. 开发者选项 → 开启「USB调试（安全设置）」
3. 需要插入SIM卡并登录小米账号

### Q5: 华为手机HDB限制

**原因：** 华为的HiSuite会接管ADB

**解决：**
1. 设置 → 关于手机 → 点击「版本号」7次
2. 开发者选项 → 选择USB配置 → 「仅充电」改为「MTP」
3. 或关闭HiSuite的自动连接

### Q6: 操作延迟高

**原因：** WiFi网络不稳定或USB线质量差

**解决：**
- 使用质量好的USB数据线
- 确保WiFi网络稳定
- 尽量使用5GHz频段

---

## 6. 经验库使用

### 6.1 什么是经验库

经验库会自动记录每次操作：
- 记录点击坐标、输入内容、操作结果
- 学习APP界面元素的位置
- 下次操作时可以直接使用学习到的坐标

### 6.2 查看经验统计

```bash
curl http://localhost:8899/api/v3/experience/statistics

# 响应
{
  "total_operations": 1523,
  "success_rate": 0.95,
  "apps_used": ["com.tencent.mm", "com.larus.nova"],
  "shortcuts_count": 5,
  "elements_learned": 42
}
```

### 6.3 使用快捷操作

SDK内置了常用操作的快捷方式：

```bash
# 查看所有快捷操作
curl http://localhost:8899/api/v3/experience/shortcuts

# 执行微信发消息快捷操作
curl -X POST http://localhost:8899/api/v3/experience/shortcuts/wechat_send_message/execute/ABC123 \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "contact": "张三",
      "message": "你好，这是自动发送的消息"
    }
  }'
```

### 6.4 创建自定义快捷操作

```bash
curl -X POST http://localhost:8899/api/v3/experience/shortcuts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_custom_action",
    "description": "我的自定义操作",
    "steps": [
      {"action": "start_app", "params": {"package": "com.tencent.mm"}, "delay_ms": 2000},
      {"action": "click", "params": {"x": 540, "y": 1200}, "delay_ms": 500},
      {"action": "input_text", "params": {"text": "$message"}, "delay_ms": 300}
    ]
  }'
```

### 6.5 智能坐标建议

当你需要点击某个文字时，经验库会根据历史记录提供坐标建议：

```bash
curl "http://localhost:8899/api/v3/experience/suggest/coordinates?app=com.tencent.mm&text=发送"

# 响应
{
  "x": 980,
  "y": 2100,
  "confidence": 0.9,
  "last_success": "2026-01-27T10:30:00"
}
```

---

## 附录：快速参考卡片

### USB连接

```bash
# 1. 连接手机
# 2. 手机选择MTP模式并授权调试
adb devices              # 查看设备
scrcpy                   # 查看屏幕（可选）
```

### WiFi连接

```bash
adb tcpip 5555                        # 开启WiFi模式
adb connect 192.168.1.XXX:5555        # 连接
adb devices                           # 验证
```

### SDK控制

```bash
# 扫描设备
curl -X POST http://localhost:8899/api/v3/adb/scan

# 设备列表
curl http://localhost:8899/api/v3/adb/devices

# 截图
curl -X POST http://localhost:8899/api/v3/adb/devices/{ID}/screenshot

# 点击
curl -X POST http://localhost:8899/api/v3/adb/devices/{ID}/click \
  -H "Content-Type: application/json" -d '{"x":540,"y":1200}'
```

---

*文档版本：1.0 | 最后更新：2026-01-27*
