workphone-sdk/sdk/php-sdk/README.md

# 工作手机SDK v3.0 - PHP客户端

存客宝后端直接使用此SDK调用工作手机服务。

> **接口全量目录**：[开发文档/5、接口/01-规范与统一层/工作手机API全量接口目录.md](../../开发文档/5、接口/01-规范与统一层/工作手机API全量接口目录.md)（328 路由）  
> **存客宝 BFF 映射**：[存客宝BFF与工作手机SDK映射表.md](../../开发文档/5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md)

## 安装

### 方式1: Composer

```bash
composer require cunkebao/workphone-sdk
```

### 方式2: 手动安装

将 `WorkPhoneClient.php` 复制到 `extend/Cunkebao/WorkPhone/` 目录。

## 快速开始

```php
<?php
use Cunkebao\WorkPhone\WorkPhoneClient;

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

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

// 发送抖音私信
$result = $sdk->sendMessage('device-001', 'douyin', '用户昵称', '感谢关注');

// 执行AI任务
$result = $sdk->executeTask('device-001', '打开微信给张三发消息：下午开会');
```

## 核心接口

### 发送消息（统一接口）

```php
$result = $sdk->sendMessage(
    'device-001',     // 设备ID
    'wechat',         // 平台: wechat/douyin/xhs
    'wxid_xxx',       // 接收者
    '消息内容',        // 内容
    'text'            // 类型: text/image
);

// 响应
[
    'code' => 200,
    'data' => [
        'success' => true,
        'message_id' => 'wx_1234567890'
    ],
    'channel_used' => 'sdk_control'  // 实际使用的通道
]
```

### 快捷方法

```php
// 微信
$sdk->wechatSend('device-001', '张三', '你好');

// 抖音
$sdk->douyinSend('device-001', '用户昵称', '感谢关注');

// 小红书
$sdk->xhsSend('device-001', '用户昵称', 'Hi~');
```

### 设备管理

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

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

// 检查设备是否在线
if ($sdk->isOnline('device-001')) {
    // 设备在线
}

// 截图
$screenshot = $sdk->screenshot('device-001');
```

### AI Agent（自然语言控制）

```php
// 执行复杂任务
$result = $sdk->executeTask(
    'device-001',
    '打开淘宝搜索iPhone16并加入购物车'
);

// 获取Agent状态
$status = $sdk->getAgentStatus('device-001');

// 停止任务
$sdk->stopAgent('device-001');
```

### 底层控制

```php
// 点击坐标
$sdk->click('device-001', 500, 1000);

// 点击文字
$sdk->clickText('device-001', '发送');

// 输入
$sdk->input('device-001', 'Hello World');

// 滑动
$sdk->swipe('device-001', 'up');

// 获取UI树
$uiTree = $sdk->getUiTree('device-001');
```

## 与存客宝集成

### 配置文件

```php
// config/workphone.php
return [
    'server_url' => env('WORKPHONE_URL', 'http://localhost:8899'),
    'api_key' => env('WORKPHONE_KEY', 'workphone-secret-key-2026'),
];
```

### 替换原有代码

```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);
```

## 错误处理

```php
$result = $sdk->sendMessage(...);

if ($result['code'] !== 200) {
    // 处理错误
    $error = $result['message'];
    
    switch ($result['code']) {
        case 503:
            // 设备不在线
            break;
        case 408:
            // 超时
            break;
        case 400:
            // 参数错误
            break;
    }
}
```

## 通道说明

SDK会自动选择最优通道：

| 通道 | 说明 | 优先级 |
|------|------|:---:|
| official_api | 官方API（抖音等） | 1 |
| sdk_control | SDK控制（uiautomator2） | 2 |
| ai_agent | AI Agent（DroidRun） | 3 |

响应中的 `channel_used` 字段表示实际使用的通道。