siyu-bank/workphone-sdk

Fork 0

Files

Manus AI 021d633cc1 feat: publish workphone SDK deployment and API docs

2026-07-14 18:12:18 +08:00

18 KiB

Raw Blame History

工作手机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-sdk/WorkPhoneClient.php 复制到 extend/Cunkebao/WorkPhone/

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

2.2 配置

// 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 基本使用

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：

Authorization: Bearer {api_key}

3.3 通用响应格式

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

3.4 错误码

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

四、消息管理接口

4.1 发送消息

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

POST /api/v3/message/send

请求体:

{
    "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	❌	@列表（群聊时使用）

响应:

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

PHP示例:

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

4.2 获取消息列表

POST /api/v3/message/list

请求体:

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

响应:

{
    "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 批量发送消息

POST /api/v3/message/batch-send

请求体:

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

PHP示例:

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

五、好友管理接口

5.1 添加好友

POST /api/v3/friend/add

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

5.2 通过好友请求

POST /api/v3/friend/accept

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

5.3 设置好友备注

POST /api/v3/friend/set-remark

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

5.4 删除好友

POST /api/v3/friend/delete

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

5.5 获取联系人列表

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

六、群聊管理接口

6.1 创建群聊

POST /api/v3/group/create

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

PHP示例:

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

6.2 邀请入群

POST /api/v3/group/invite

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

6.3 发送群消息

POST /api/v3/group/send-message

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

PHP示例:

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

6.4 设置群公告

POST /api/v3/group/set-notice

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

6.5 设置群欢迎语

POST /api/v3/group/set-welcome

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

6.6 获取群列表

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

6.7 获取群成员

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

七、标签管理接口

7.1 给好友添加标签

POST /api/v3/tag/add

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

PHP示例:

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

7.2 移除好友标签

POST /api/v3/tag/remove

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

7.3 创建标签

POST /api/v3/tag/create

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

7.4 获取标签列表

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

7.5 根据标签获取好友

POST /api/v3/tag/users

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

八、朋友圈管理接口

8.1 发布朋友圈

POST /api/v3/moments/post

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

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 点赞朋友圈

POST /api/v3/moments/like

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

8.3 评论朋友圈

POST /api/v3/moments/comment

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

8.4 获取朋友圈

POST /api/v3/moments/list

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

九、设备管理接口

9.1 获取设备列表

GET /api/v3/devices

响应:

{
    "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 获取设备详情

GET /api/v3/devices/{device_id}

9.3 检查设备是否在线

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

9.4 获取在线设备列表

$onlineDevices = $sdk->getOnlineDevices();

9.5 设备截图

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

十、AI Agent接口

10.1 执行自然语言任务

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

POST /api/v3/agent/execute

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

PHP示例:

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

响应:

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

十一、通道选择策略

SDK会自动选择最优通道：

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

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

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

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

12.1 替换原有WebSocket调用

// ========== 原代码 (调用奥创) ==========
$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

// 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: 消息发送失败怎么排查？

检查设备是否在线
检查联系人名称是否正确
查看SDK日志
尝试使用AI Agent模式

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

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

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

A: 建议：

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

十五、技术支持

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

18 KiB Raw Blame History Unescape Escape

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

一、概述

1.1 简介

1.2 架构图

1.3 接入方式

二、快速开始

2.1 安装PHP SDK

2.2 配置

2.3 基本使用

三、接口文档

3.1 基础信息

3.2 认证

3.3 通用响应格式

3.4 错误码

四、消息管理接口

4.1 发送消息

4.2 获取消息列表

4.3 批量发送消息

五、好友管理接口

5.1 添加好友

5.2 通过好友请求

5.3 设置好友备注

5.4 删除好友

5.5 获取联系人列表

六、群聊管理接口

6.1 创建群聊

6.2 邀请入群

6.3 发送群消息

6.4 设置群公告

6.5 设置群欢迎语

6.6 获取群列表

6.7 获取群成员

七、标签管理接口

7.1 给好友添加标签

7.2 移除好友标签

7.3 创建标签

7.4 获取标签列表

7.5 根据标签获取好友

八、朋友圈管理接口

8.1 发布朋友圈

8.2 点赞朋友圈

8.3 评论朋友圈

8.4 获取朋友圈

九、设备管理接口

9.1 获取设备列表

9.2 获取设备详情

9.3 检查设备是否在线

9.4 获取在线设备列表

9.5 设备截图

十、AI Agent接口

10.1 执行自然语言任务

十一、通道选择策略

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

12.1 替换原有WebSocket调用

12.2 封装为Service

十三、成本对比

十四、常见问题

Q1: 设备不在线怎么办？

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

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

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

十五、技术支持

18 KiB

Raw Blame History