# 工作手机SDK v3.0 使用说明书

> 存客宝的AI手机控制引擎
> 
> 版本：3.0.0 | 更新日期：2026-01-27

---

## 目录

1. [系统概述](#1-系统概述)
2. [快速开始](#2-快速开始)
3. [API接口详解](#3-api接口详解)
4. [PHP SDK使用](#4-php-sdk使用)
5. [实际操作演示](#5-实际操作演示)
6. [常见问题](#6-常见问题)

---

## 1. 系统概述

### 1.1 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                      存客宝后端                              │
│                    (PHP/Laravel)                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ HTTP API
┌─────────────────────────────────────────────────────────────┐
│                   工作手机SDK v3.0                           │
│                   (Python/FastAPI)                          │
│                                                             │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│   │  ADB控制    │  │  WebSocket  │  │  AI Agent   │        │
│   │  (直连)     │  │  (远程)     │  │  (智能)     │        │
│   └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌─────────┐     ┌─────────┐     ┌─────────┐
        │ 手机1   │     │ 手机2   │     │ 手机N   │
        │ (微信)  │     │ (抖音)  │     │ (小红书)│
        └─────────┘     └─────────┘     └─────────┘
```

### 1.2 核心功能

| 功能 | 说明 | 支持平台 |
|------|------|----------|
| 发送消息 | 自动发送文字/图片消息 | 微信、抖音、小红书 |
| 获取消息 | 读取聊天记录 | 微信、抖音、小红书 |
| 添加好友 | 自动添加好友/关注 | 微信、抖音、小红书 |
| 通过好友 | 自动通过好友请求 | 微信 |
| 发朋友圈 | 自动发布动态 | 微信、抖音 |
| 截图 | 实时获取屏幕截图 | 所有APP |
| UI控制 | 点击、滑动、输入 | 所有APP |
| AI Agent | 自然语言控制 | 所有APP |

### 1.3 服务地址

| 服务 | 地址 | 说明 |
|------|------|------|
| API服务 | http://localhost:8899 | 主服务地址 |
| API文档 | http://localhost:8899/docs | Swagger文档 |
| 健康检查 | http://localhost:8899/health | 服务状态 |

---

## 2. 快速开始

### 2.1 启动服务

**方式一：Docker启动（推荐生产环境）**

```bash
cd sdk
docker compose up -d
```

**方式二：本地启动（开发调试）**

```bash
cd sdk/app
pip3 install -r ../requirements.txt
python3 -c "import uvicorn; from main import app; uvicorn.run(app, host='0.0.0.0', port=8899)"
```

### 2.2 连接手机

**真实手机：**

1. 开启手机「开发者选项」→「USB调试」
2. 用USB线连接电脑
3. 手机上点击「允许USB调试」

**模拟器（无真机时）：**

```bash
# 创建模拟器
avdmanager create avd -n RedMi13 -k "system-images;android-34;google_apis;arm64-v8a"

# 启动模拟器
emulator -avd RedMi13 &
```

### 2.3 验证连接

```bash
# 检查设备
curl http://localhost:8899/api/v3/adb/devices

# 响应示例
{
  "code": 200,
  "data": [{
    "serial": "emulator-5554",
    "model": "sdk_gphone64_arm64",
    "android_version": "14",
    "status": "online"
  }]
}
```

---

## 3. API接口详解

### 3.1 设备管理

#### 获取设备列表

```http
GET /api/v3/adb/devices
```

**响应：**
```json
{
  "code": 200,
  "data": [
    {
      "serial": "emulator-5554",
      "model": "sdk_gphone64_arm64",
      "brand": "google",
      "android_version": "14",
      "display": {"width": 1080, "height": 2400},
      "status": "online"
    }
  ]
}
```

#### 扫描设备

```http
POST /api/v3/adb/scan
```

#### 获取设备详情

```http
GET /api/v3/adb/devices/{serial}
```

---

### 3.2 基础控制

#### 截图

```http
POST /api/v3/adb/devices/{serial}/screenshot
```

**响应：**
```json
{
  "code": 200,
  "data": {
    "base64": "iVBORw0KGgo...",
    "width": 1080,
    "height": 2400,
    "size": 148845
  }
}
```

**效果展示：**

![桌面截图](images/01_home.png)

---

#### 点击坐标

```http
POST /api/v3/adb/devices/{serial}/click
Content-Type: application/json

{
  "x": 540,
  "y": 1200
}
```

**响应：**
```json
{
  "code": 200,
  "data": {
    "success": true,
    "x": 540,
    "y": 1200
  }
}
```

---

#### 点击文字

```http
POST /api/v3/adb/devices/{serial}/click-text
Content-Type: application/json

{
  "text": "设置",
  "timeout": 10
}
```

---

#### 输入文字

```http
POST /api/v3/adb/devices/{serial}/input
Content-Type: application/json

{
  "text": "Hello World",
  "clear": true
}
```

---

#### 滑动屏幕

```http
POST /api/v3/adb/devices/{serial}/swipe
Content-Type: application/json

{
  "direction": "up",
  "scale": 0.5
}
```

**方向参数：**
- `up` - 向上滑动
- `down` - 向下滑动
- `left` - 向左滑动
- `right` - 向右滑动

**效果展示：**

| 滑动前 | 滑动后 |
|:------:|:------:|
| ![滑动前](images/01_home.png) | ![滑动后](images/02_swipe_up.png) |

---

#### 按键操作

```http
POST /api/v3/adb/devices/{serial}/key
Content-Type: application/json

{
  "key": "back"
}
```

**支持的按键：**
- `back` - 返回键
- `home` - 主页键
- `recent` - 最近任务
- `enter` - 回车
- `volume_up` - 音量+
- `volume_down` - 音量-

---

### 3.3 APP控制

#### 启动APP

```http
POST /api/v3/adb/devices/{serial}/app/start
Content-Type: application/json

{
  "package": "com.android.settings"
}
```

**常用APP包名：**
| APP | 包名 |
|-----|------|
| 微信 | com.tencent.mm |
| 抖音 | com.ss.android.ugc.aweme |
| 小红书 | com.xingin.xhs |
| 淘宝 | com.taobao.taobao |
| 设置 | com.android.settings |

**效果展示：**

![打开设置](images/03_settings.png)

---

#### 停止APP

```http
POST /api/v3/adb/devices/{serial}/app/stop
Content-Type: application/json

{
  "package": "com.android.settings"
}
```

---

#### 获取当前APP

```http
GET /api/v3/adb/devices/{serial}/app/current
```

**响应：**
```json
{
  "code": 200,
  "data": {
    "package": "com.android.settings",
    "raw": "mCurrentFocus=Window{...com.android.settings...}"
  }
}
```

---

#### 获取已安装APP

```http
GET /api/v3/adb/devices/{serial}/app/list
```

---

### 3.4 UI分析

#### 获取UI树

```http
GET /api/v3/adb/devices/{serial}/ui-tree
```

**响应：**
```json
{
  "code": 200,
  "data": {
    "xml": "<?xml version=\"1.0\"?><hierarchy>..."
  }
}
```

---

## 4. PHP SDK使用

### 4.1 安装

将 `php-sdk/WorkPhoneClient.php` 复制到项目中：

```php
require_once 'WorkPhoneClient.php';
use Cunkebao\WorkPhone\WorkPhoneClient;
```

### 4.2 初始化

```php
$sdk = new WorkPhoneClient(
    'http://localhost:8899',           // SDK服务器地址
    'workphone-secret-key-2026'        // API密钥
);
```

### 4.3 使用示例

#### 发送消息

```php
// 微信消息
$result = $sdk->sendMessage(
    'emulator-5554',    // 设备ID
    'wechat',           // 平台
    '张三',              // 接收者
    '你好，这是测试消息'   // 内容
);

// 快捷方式
$sdk->wechatSend('emulator-5554', '张三', '你好');
$sdk->douyinSend('emulator-5554', '用户', '感谢关注');
$sdk->xhsSend('emulator-5554', '用户', 'Hi~');
```

#### 设备管理

```php
// 获取所有设备
$devices = $sdk->getDevices();

// 检查设备是否在线
if ($sdk->isOnline('emulator-5554')) {
    echo "设备在线";
}

// 截图
$screenshot = $sdk->screenshot('emulator-5554');
$imageData = base64_decode($screenshot['data']['base64']);
file_put_contents('screen.png', $imageData);
```

#### 控制操作

```php
// 点击
$sdk->click('emulator-5554', 540, 1200);

// 输入
$sdk->input('emulator-5554', 'Hello World');

// 滑动
$sdk->swipe('emulator-5554', 'up');

// 执行脚本
$sdk->execute('emulator-5554', 'wechat', 'send_message', [
    'to_id' => '张三',
    'content' => '你好'
]);
```

#### AI Agent

```php
// 执行自然语言任务
$result = $sdk->executeTask(
    'emulator-5554',
    '打开微信给张三发消息：明天下午3点开会'
);

// 获取任务状态
$status = $sdk->getAgentStatus('emulator-5554');

// 停止任务
$sdk->stopAgent('emulator-5554');
```

---

## 5. 实际操作演示

### 5.1 完整流程：打开设置APP

**步骤1：检查设备**
```bash
curl http://localhost:8899/api/v3/adb/devices
```

**步骤2：启动APP**
```bash
curl -X POST http://localhost:8899/api/v3/adb/devices/emulator-5554/app/start \
  -H "Content-Type: application/json" \
  -d '{"package": "com.android.settings"}'
```

**步骤3：截图确认**
```bash
curl -X POST http://localhost:8899/api/v3/adb/devices/emulator-5554/screenshot \
  | jq -r '.data.base64' | base64 -d > settings.png
```

**效果：**

![设置界面](images/03_settings.png)

---

### 5.2 完整流程：滑动浏览

**向上滑动：**
```bash
curl -X POST http://localhost:8899/api/v3/adb/devices/emulator-5554/swipe \
  -H "Content-Type: application/json" \
  -d '{"direction": "up", "scale": 0.5}'
```

**向下滑动：**
```bash
curl -X POST http://localhost:8899/api/v3/adb/devices/emulator-5554/swipe \
  -H "Content-Type: application/json" \
  -d '{"direction": "down", "scale": 0.5}'
```

---

### 5.3 完整流程：发送微信消息（伪代码）

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

// 1. 检查设备
if (!$sdk->isOnline('device-001')) {
    die('设备不在线');
}

// 2. 启动微信
$sdk->execute('device-001', 'wechat', 'launch', []);
sleep(3);

// 3. 搜索联系人
$sdk->execute('device-001', 'wechat', 'search', ['keyword' => '张三']);
sleep(2);

// 4. 发送消息
$result = $sdk->execute('device-001', 'wechat', 'send_message', [
    'to_id' => '张三',
    'content' => '你好，这是自动发送的消息',
    'msg_type' => 'text'
]);

if ($result['data']['success']) {
    echo '发送成功！';
}
```

---

## 6. 常见问题

### Q1: 设备连接不上？

**检查步骤：**
1. 确认USB调试已开启
2. 执行 `adb devices` 查看设备
3. 如果显示 `unauthorized`，需要在手机上点击「允许调试」

### Q2: 截图返回空？

**可能原因：**
- 设备屏幕已关闭
- 执行 `adb -s {serial} shell input keyevent KEYCODE_WAKEUP` 唤醒

### Q3: 点击不生效？

**可能原因：**
- 坐标错误，使用截图确认位置
- APP有弹窗遮挡

### Q4: 如何获取元素坐标？

**方法1：截图 + 图片查看器**
- 截图后用图片查看器查看坐标

**方法2：使用UI树**
```bash
curl http://localhost:8899/api/v3/adb/devices/{serial}/ui-tree
```
从XML中查找 `bounds="[x1,y1][x2,y2]"`

### Q5: 如何支持多台手机？

每台手机有唯一的 `serial`（如 `emulator-5554`、`192.168.1.100:5555`），
API调用时指定不同的 serial 即可。

---

## 附录

### A. 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 参数错误 |
| 404 | 设备/资源不存在 |
| 408 | 操作超时 |
| 500 | 服务器错误 |
| 503 | 设备不在线 |

### B. 联系方式

- **技术负责人**：卡若
- **微信**：28533368
- **邮箱**：zhiqun@qq.com

---

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