# 工作手机SDK v3.0 - 存客宝对接文档

> **版本**: v3.0.0  
> **更新日期**: 2026-02-05  
> **联系人**: 卡若 (微信: 28533368)

---

## 一、概述

### 1.1 简介

工作手机SDK是存客宝的AI手机控制引擎，支持：

- **多平台**: 微信、抖音、小红书、闲鱼、Soul
- **多功能**: 消息收发、好友管理、群聊管理、标签管理、朋友圈管理
- **智能通道**: 自动选择最优执行通道（官方API → SDK控制 → AI Agent）

### 1.2 架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                      存客宝系统                                   │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                 存客宝后端 (ThinkPHP)                      │   │
│   │   $sdk = new WorkPhoneClient('http://sdk.xxx.com', 'key');│   │
│   │   $sdk->sendMessage('device-001', 'wechat', '张三', '你好');│   │
│   └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                │ HTTPS REST API
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    工作手机SDK v3.0 服务器                        │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                 统一服务交互层 (Facade)                     │   │
│   │           自动选择: 官方API → SDK控制 → AI Agent            │   │
│   └─────────────────────────────────────────────────────────┘   │
│                                │                                 │
│              ┌─────────────────┼─────────────────┐              │
│              ▼                 ▼                 ▼              │
│   ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐  │
│   │   官方API通道    │ │   SDK控制通道    │ │   AI Agent通道   │  │
│   │   (抖音等)      │ │  (uiautomator2)  │ │   (DeepSeek)    │  │
│   │   优先级: 1     │ │   优先级: 2      │ │   优先级: 3      │  │
│   └─────────────────┘ └─────────────────┘ └─────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                │ WebSocket
                                ▼
                    ┌─────────────────────┐
                    │     手机设备         │
                    │   Agent APP        │
                    └─────────────────────┘
```

### 1.3 接入方式

| 接入方式 | 适用场景 | 文件位置 |
|---------|---------|---------|
| PHP SDK | 存客宝后端 | `php-sdk/WorkPhoneClient.php` |
| TypeScript SDK | 前端/Node.js | `typescript-sdk/index.ts` |
| REST API | 任意语言 | 直接调用HTTP接口 |

---

## 二、快速开始

### 2.1 安装PHP SDK

```php
// 将 php-sdk/WorkPhoneClient.php 复制到 extend/Cunkebao/WorkPhone/

// 或使用 composer（如果已发布）
composer require cunkebao/workphone-sdk
```

### 2.2 配置

```php
// config/workphone.php
return [
    'server_url' => env('WORKPHONE_URL', 'https://workphone.example.com'),
    'api_key' => env('WORKPHONE_KEY', 'your-api-key'),
    'timeout' => 30,
];
```

### 2.3 基本使用

```php
use Cunkebao\WorkPhone\WorkPhoneClient;

// 初始化
$sdk = new WorkPhoneClient(
    config('workphone.server_url'),
    config('workphone.api_key')
);

// 发送微信消息
$result = $sdk->sendMessage('device-001', 'wechat', '张三', '你好！');

// 检查结果
if ($result['code'] === 200 && $result['data']['success']) {
    echo '发送成功: ' . $result['data']['message_id'];
} else {
    echo '发送失败: ' . ($result['data']['error'] ?? $result['message']);
}
```

---

## 三、接口文档

### 3.1 基础信息

| 项目 | 值 |
|------|-----|
| Base URL | `https://workphone.example.com/api/v3` |
| 认证方式 | Bearer Token |
| Content-Type | application/json |
| 字符编码 | UTF-8 |

### 3.2 认证

所有请求需要在Header中携带API Key：

```http
Authorization: Bearer {api_key}
```

### 3.3 通用响应格式

```json
{
    "code": 200,
    "message": "success",
    "data": {},
    "channel_used": "sdk_control"
}
```

### 3.4 错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 成功 | - |
| 400 | 请求参数错误 | 检查参数 |
| 401 | 未授权 | 检查API Key |
| 404 | 资源不存在 | 检查设备ID |
| 408 | 设备响应超时 | 增加timeout或重试 |
| 500 | 服务器内部错误 | 联系技术支持 |
| 503 | 设备不在线 | 检查设备状态 |

---

## 四、消息管理接口

### 4.1 发送消息

最重要的接口，支持所有平台。

```http
POST /api/v3/message/send
```

**请求体**:

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "to_id": "张三",
    "content": "你好！",
    "msg_type": "text",
    "media_url": null,
    "at_list": null
}
```

**参数说明**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| device_id | string | ✅ | 设备ID |
| platform | string | ✅ | 平台: wechat/douyin/xhs/xianyu/soul |
| to_id | string | ✅ | 接收者ID（联系人名称/微信号等） |
| content | string | ✅ | 消息内容 |
| msg_type | string | ❌ | 消息类型: text/image/video，默认text |
| media_url | string | ❌ | 媒体URL（图片/视频时需要） |
| at_list | array | ❌ | @列表（群聊时使用） |

**响应**:

```json
{
    "code": 200,
    "data": {
        "success": true,
        "message_id": "wx_1234567890",
        "error": null
    },
    "channel_used": "sdk_control"
}
```

**PHP示例**:

```php
$result = $sdk->sendMessage('device-001', 'wechat', '张三', '你好！');
// 或使用快捷方法
$result = $sdk->wechatSend('device-001', '张三', '你好！');
```

### 4.2 获取消息列表

```http
POST /api/v3/message/list
```

**请求体**:

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "conversation_id": "张三",
    "limit": 20,
    "since_time": null
}
```

**响应**:

```json
{
    "code": 200,
    "data": {
        "messages": [
            {
                "message_id": "msg_001",
                "from_id": "张三",
                "to_id": "my_wxid",
                "content": "你好",
                "msg_type": "text",
                "timestamp": 1704931200,
                "is_self": false
            }
        ]
    }
}
```

### 4.3 批量发送消息

```http
POST /api/v3/message/batch-send
```

**请求体**:

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "to_ids": ["张三", "李四", "王五"],
    "content": "群发消息内容",
    "msg_type": "text",
    "interval": 2.0
}
```

**PHP示例**:

```php
$result = $sdk->batchSendMessage(
    'device-001',
    'wechat',
    ['张三', '李四', '王五'],
    '群发消息内容',
    'text',
    2.0  // 发送间隔(秒)
);
```

---

## 五、好友管理接口

### 5.1 添加好友

```http
POST /api/v3/friend/add
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "user_id": "wxid_xxx",
    "message": "你好，我是xxx",
    "source": "微信搜索"
}
```

### 5.2 通过好友请求

```http
POST /api/v3/friend/accept
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "user_id": "wxid_xxx"
}
```

### 5.3 设置好友备注

```http
POST /api/v3/friend/set-remark
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "user_id": "张三",
    "remark": "客户-张三-高意向"
}
```

### 5.4 删除好友

```http
POST /api/v3/friend/delete
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "user_id": "张三"
}
```

### 5.5 获取联系人列表

```http
GET /api/v3/contacts?device_id=device-001&platform=wechat&limit=100
```

---

## 六、群聊管理接口

### 6.1 创建群聊

```http
POST /api/v3/group/create
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "group_name": "VIP客户群",
    "member_ids": ["张三", "李四", "王五"]
}
```

**PHP示例**:

```php
$result = $sdk->createGroup('device-001', 'wechat', 'VIP客户群', ['张三', '李四', '王五']);
// 或使用快捷方法
$result = $sdk->wechatCreateGroup('device-001', 'VIP客户群', ['张三', '李四', '王五']);
```

### 6.2 邀请入群

```http
POST /api/v3/group/invite
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "group_id": "VIP客户群",
    "member_ids": ["新成员1", "新成员2"]
}
```

### 6.3 发送群消息

```http
POST /api/v3/group/send-message
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "group_id": "VIP客户群",
    "content": "大家好，明天有活动",
    "msg_type": "text",
    "at_all": true,
    "at_list": null
}
```

**PHP示例**:

```php
// 发送群消息并@所有人
$result = $sdk->sendGroupMessage(
    'device-001', 'wechat', 'VIP客户群',
    '明天有活动', 'text', true
);
// 或使用快捷方法
$result = $sdk->wechatGroupSend('device-001', 'VIP客户群', '明天有活动', true);
```

### 6.4 设置群公告

```http
POST /api/v3/group/set-notice
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "group_id": "VIP客户群",
    "notice": "群规：\n1. 禁止广告\n2. 文明交流"
}
```

### 6.5 设置群欢迎语

```http
POST /api/v3/group/set-welcome
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "group_id": "VIP客户群",
    "welcome_text": "欢迎新成员加入！请先阅读群公告~",
    "welcome_image": null
}
```

### 6.6 获取群列表

```http
GET /api/v3/group/list?device_id=device-001&platform=wechat&limit=100
```

### 6.7 获取群成员

```http
GET /api/v3/group/members?device_id=device-001&platform=wechat&group_id=VIP客户群
```

---

## 七、标签管理接口

### 7.1 给好友添加标签

```http
POST /api/v3/tag/add
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "user_id": "张三",
    "tags": ["VIP客户", "高意向", "电商"]
}
```

**PHP示例**:

```php
$result = $sdk->addTag('device-001', 'wechat', '张三', ['VIP客户', '高意向']);
// 或使用快捷方法
$result = $sdk->wechatAddTag('device-001', '张三', ['VIP客户', '高意向']);
```

### 7.2 移除好友标签

```http
POST /api/v3/tag/remove
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "user_id": "张三",
    "tags": ["低意向"]
}
```

### 7.3 创建标签

```http
POST /api/v3/tag/create
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "tag_name": "新标签"
}
```

### 7.4 获取标签列表

```http
GET /api/v3/tag/list?device_id=device-001&platform=wechat
```

### 7.5 根据标签获取好友

```http
POST /api/v3/tag/users
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "tag_name": "VIP客户",
    "limit": 100
}
```

---

## 八、朋友圈管理接口

### 8.1 发布朋友圈

```http
POST /api/v3/moments/post
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "content": "今日分享：好产品推荐",
    "images": ["https://example.com/image1.jpg"],
    "video_url": null,
    "location": "上海市浦东新区",
    "visible_list": null,
    "invisible_list": null
}
```

**PHP示例**:

```php
$result = $sdk->postMoments(
    'device-001', 'wechat',
    '今日分享：好产品推荐',
    ['https://example.com/image1.jpg'],
    null,  // video_url
    '上海市'  // location
);
// 或使用快捷方法
$result = $sdk->wechatPostMoments('device-001', '今日分享', ['image1.jpg']);
```

### 8.2 点赞朋友圈

```http
POST /api/v3/moments/like
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "user_id": "张三",
    "post_index": 0
}
```

### 8.3 评论朋友圈

```http
POST /api/v3/moments/comment
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "user_id": "张三",
    "post_index": 0,
    "comment": "写得真好！",
    "reply_to": null
}
```

### 8.4 获取朋友圈

```http
POST /api/v3/moments/list
```

```json
{
    "device_id": "device-001",
    "platform": "wechat",
    "user_id": "张三",
    "limit": 10
}
```

---

## 九、设备管理接口

### 9.1 获取设备列表

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

**响应**:

```json
{
    "code": 200,
    "data": [
        {
            "device_id": "device-001",
            "name": "工作手机1",
            "model": "Redmi K60",
            "status": "online",
            "android_version": "14",
            "agent_version": "1.0.0",
            "capabilities": ["frida", "u2"],
            "apps": ["wechat", "douyin"],
            "last_heartbeat": "2026-02-05T10:00:00Z"
        }
    ]
}
```

### 9.2 获取设备详情

```http
GET /api/v3/devices/{device_id}
```

### 9.3 检查设备是否在线

```php
$isOnline = $sdk->isOnline('device-001');
```

### 9.4 获取在线设备列表

```php
$onlineDevices = $sdk->getOnlineDevices();
```

### 9.5 设备截图

```http
POST /api/v3/devices/{device_id}/screenshot
```

---

## 十、AI Agent接口

### 10.1 执行自然语言任务

当需要执行复杂任务时，可以用自然语言描述：

```http
POST /api/v3/agent/execute
```

```json
{
    "device_id": "device-001",
    "task": "打开微信，找到张三，发送消息：明天下午2点开会",
    "llm_provider": "deepseek",
    "max_steps": 30
}
```

**PHP示例**:

```php
$result = $sdk->executeTask(
    'device-001',
    '打开微信给张三发消息：明天开会'
);
```

**响应**:

```json
{
    "code": 200,
    "data": {
        "success": true,
        "steps": [
            "启动微信",
            "点击搜索",
            "输入张三",
            "点击联系人",
            "输入消息",
            "点击发送"
        ],
        "duration_ms": 12500
    }
}
```

---

## 十一、通道选择策略

SDK会自动选择最优通道：

```
1. 有官方API支持 → 优先用API（最稳定）
2. 设备在线 → 用SDK控制（成本低）
3. SDK失败 → 用AI Agent（最灵活）
4. 全部失败 → 返回错误
```

响应中会返回实际使用的通道：

```json
{
    "code": 200,
    "data": {...},
    "channel_used": "official_api"  // official_api / sdk_control / ai_agent
}
```

---

## 十二、与存客宝现有代码对接

### 12.1 替换原有WebSocket调用

```php
// ========== 原代码 (调用奥创) ==========
$signInData = [
    "cmdType" => "CmdSendMsg",
    "wechatAccountId" => $wechatId,
    "toWxid" => $toWxid,
    "content" => $content,
];
$this->client->send(json_encode($signInData));

// ========== 新代码 (调用自有SDK) ==========
$sdk = new WorkPhoneClient(config('workphone.server_url'), config('workphone.api_key'));
$result = $sdk->sendMessage($deviceId, 'wechat', $toWxid, $content);
```

### 12.2 封装为Service

```php
// app/service/WorkPhoneService.php

namespace app\service;

use Cunkebao\WorkPhone\WorkPhoneClient;

class WorkPhoneService
{
    private WorkPhoneClient $sdk;
    
    public function __construct()
    {
        $this->sdk = new WorkPhoneClient(
            config('workphone.server_url'),
            config('workphone.api_key')
        );
    }
    
    /**
     * 发送微信消息
     */
    public function sendWechatMessage(string $deviceId, string $toId, string $content): array
    {
        return $this->sdk->wechatSend($deviceId, $toId, $content);
    }
    
    /**
     * 创建微信群
     */
    public function createWechatGroup(string $deviceId, string $groupName, array $members): array
    {
        return $this->sdk->wechatCreateGroup($deviceId, $groupName, $members);
    }
    
    /**
     * 给好友打标签
     */
    public function tagFriend(string $deviceId, string $userId, array $tags): array
    {
        return $this->sdk->wechatAddTag($deviceId, $userId, $tags);
    }
    
    /**
     * 发朋友圈
     */
    public function postMoments(string $deviceId, string $content, ?array $images = null): array
    {
        return $this->sdk->wechatPostMoments($deviceId, $content, $images);
    }
}
```

---

## 十三、成本对比

| 设备数量 | 自研SDK | 奥创 | 节省 |
|----------|---------|------|------|
| 10台 | 500元/月 | 5,000元/月 | **90%** |
| 50台 | 500元/月 | 25,000元/月 | **98%** |
| 100台 | 800元/月 | 50,000元/月 | **98%+** |

---

## 十四、常见问题

### Q1: 设备不在线怎么办？

A: 检查设备Agent APP是否正常运行，WebSocket连接是否正常。

### Q2: 消息发送失败怎么排查？

A: 
1. 检查设备是否在线
2. 检查联系人名称是否正确
3. 查看SDK日志
4. 尝试使用AI Agent模式

### Q3: 如何处理微信版本更新？

A: SDK会自动尝试AI Agent模式作为兜底，可以适应UI变化。

### Q4: 批量操作会被封号吗？

A: 建议：
- 设置合理的发送间隔（2-5秒）
- 避免短时间内大量操作
- 模拟真人操作节奏

---

## 十五、技术支持

- **负责人**: 卡若
- **微信**: 28533368
- **文档地址**: /docs/存客宝对接文档.md
- **API文档**: http://localhost:8899/docs
