# 工作手机SDK v3.0 - 系统架构说明

## 一、整体架构图

```
┌──────────────────────────────────────────────────────────────────┐
│                         你的Mac电脑                              │
│                                                                  │
│  ┌─────────────────────┐    ┌─────────────────────────────────┐ │
│  │   SDK服务 (Python)   │    │     Android模拟器/真机           │ │
│  │                     │    │                                 │ │
│  │  FastAPI服务器      │◄───┤     emulator-5554               │ │
│  │  端口: 8899         │ADB │     (RedMi13模拟器)             │ │
│  │                     │命令│                                 │ │
│  │  位置:              │    │     运行的APP:                  │ │
│  │  sdk/app/main.py    │    │     - 豆包                      │ │
│  │                     │    │     - Chrome                    │ │
│  └─────────────────────┘    │     - 设置                      │ │
│           ▲                 │                                 │ │
│           │ HTTP API        │     位置:                       │ │
│           │                 │     ~/.android/avd/RedMi13.avd  │ │
│           ▼                 └─────────────────────────────────┘ │
│  ┌─────────────────────┐           ▲                           │
│  │   存客宝后端 (PHP)   │           │                           │
│  │                     │           │ USB/WiFi                  │
│  │   调用SDK的API      │           │                           │
│  └─────────────────────┘    ┌──────┴──────┐                    │
│                             │  scrcpy窗口  │                    │
│                             │  (屏幕镜像)  │                    │
│                             └─────────────┘                    │
└──────────────────────────────────────────────────────────────────┘
```

## 二、各组件位置

| 组件 | 位置 | 说明 |
|------|------|------|
| **SDK服务端** | `/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/app/` | Python FastAPI服务 |
| **SDK配置** | `/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/.env` | 环境变量配置 |
| **PHP客户端** | `/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/php-sdk/` | 存客宝调用SDK的库 |
| **模拟器AVD** | `~/.android/avd/RedMi13.avd/` | Android虚拟设备文件 |
| **ADB工具** | `/usr/local/share/android-commandlinetools/` | Android调试桥 |

## 三、通信流程详解

### 流程1：存客宝发送微信消息

```
存客宝后端                    SDK服务                      手机/模拟器
    │                           │                              │
    │ 1. HTTP POST              │                              │
    │ /api/v3/message/send      │                              │
    │ {device_id, platform,     │                              │
    │  to_id, content}          │                              │
    │─────────────────────────►│                              │
    │                           │                              │
    │                           │ 2. adb shell命令             │
    │                           │ 启动微信、搜索联系人、        │
    │                           │ 点击、输入、发送              │
    │                           │─────────────────────────────►│
    │                           │                              │
    │                           │ 3. 操作完成                   │
    │                           │◄─────────────────────────────│
    │                           │                              │
    │ 4. 返回结果               │                              │
    │ {success: true,           │                              │
    │  message_id: xxx}         │                              │
    │◄─────────────────────────│                              │
```

### 流程2：截图

```
存客宝后端                    SDK服务                      手机/模拟器
    │                           │                              │
    │ POST /screenshot          │                              │
    │─────────────────────────►│                              │
    │                           │ adb exec-out screencap -p    │
    │                           │─────────────────────────────►│
    │                           │                              │
    │                           │ 返回PNG图片数据               │
    │                           │◄─────────────────────────────│
    │                           │                              │
    │ {base64: "iVBORw0..."}   │                              │
    │◄─────────────────────────│                              │
```

## 四、核心技术原理

### 4.1 ADB (Android Debug Bridge)

ADB是Android官方的调试工具，SDK通过它控制手机：

```bash
# 查看连接的设备
adb devices

# 截图
adb exec-out screencap -p > screen.png

# 点击屏幕坐标
adb shell input tap 540 1200

# 滑动
adb shell input swipe 540 1800 540 600 500

# 输入文字
adb shell input text "Hello"

# 启动APP
adb shell am start -n com.tencent.mm/.ui.LauncherUI

# 按键
adb shell input keyevent KEYCODE_BACK
```

### 4.2 SDK将ADB封装成HTTP API

```python
# sdk/app/services/adb_device.py

class ADBDevice:
    def click(self, x: int, y: int):
        """点击坐标"""
        self._shell(f"input tap {x} {y}")
    
    def screenshot(self):
        """截图"""
        result = subprocess.run(
            ["adb", "-s", self.serial, "exec-out", "screencap", "-p"],
            capture_output=True
        )
        return base64.b64encode(result.stdout)
```

### 4.3 存客宝通过PHP调用

```php
// 存客宝后端代码
$sdk = new WorkPhoneClient('http://localhost:8899', 'api-key');

// 发送消息
$sdk->sendMessage('emulator-5554', 'wechat', '张三', '你好');

// 截图
$screenshot = $sdk->screenshot('emulator-5554');
```

## 五、实际运行的进程

```bash
# 1. SDK服务进程
ps aux | grep python
# Python  63973  ...  uvicorn main:app --host 0.0.0.0 --port 8899

# 2. 模拟器进程
ps aux | grep emulator
# emulator -avd RedMi13 -no-snapshot -gpu host

# 3. ADB服务进程
ps aux | grep adb
# adb -L tcp:5037 fork-server server

# 4. scrcpy屏幕镜像
ps aux | grep scrcpy
# scrcpy -s emulator-5554 --window-title "红米13模拟器"
```

## 六、文件关系图

```
sdk/
├── app/                          # SDK服务端
│   ├── main.py                   # FastAPI入口 (监听8899端口)
│   ├── config.py                 # 配置
│   ├── routers/
│   │   ├── adb.py                # ADB设备控制API
│   │   ├── devices.py            # 设备管理API
│   │   └── unified.py            # 统一消息API
│   └── services/
│       └── adb_device.py         # ADB命令封装
│
├── php-sdk/
│   └── WorkPhoneClient.php       # 存客宝用的PHP客户端
│
└── agent/                        # 手机端Agent (可选)
    └── agent.py                  # 运行在手机上的程序
```

## 七、为什么这样设计

### 优点

1. **无需ROOT** - 使用官方ADB接口，不需要ROOT手机
2. **跨平台** - 支持任何Android APP，不限于微信
3. **成本低** - 不依赖第三方服务商
4. **可扩展** - 可以添加AI Agent实现智能控制

### 与奥创的区别

| 特性 | 自研SDK | 奥创 |
|------|---------|------|
| 控制方式 | ADB命令 | Hook注入 |
| 需要ROOT | 否 | 是 |
| 支持APP | 任意APP | 仅微信 |
| 月费用 | 服务器成本(~500元) | 500元/台 |
| 稳定性 | 高(官方接口) | 中(可能被检测) |