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

存客宝的AI手机控制引擎 - 一套SDK，控制所有APP

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

## 安装

```bash
npm install @cunkebao/workphone-sdk
# 或
yarn add @cunkebao/workphone-sdk
# 或
pnpm add @cunkebao/workphone-sdk
```

## 快速开始

```typescript
import WorkPhoneSDK from '@cunkebao/workphone-sdk';

// 初始化SDK
const sdk = new WorkPhoneSDK({
  baseUrl: 'https://workphone.example.com',
  apiKey: 'your-api-key'
});

// 发送微信消息
const result = await sdk.sendMessage({
  deviceId: 'device-001',
  platform: 'wechat',
  toId: '张三',
  content: '你好！'
});

console.log(result);
// { code: 200, data: { success: true, message_id: 'wx_xxx' }, channel_used: 'sdk_control' }
```

## 功能模块

### 一、消息管理

```typescript
// 发送消息（支持微信/抖音/小红书/闲鱼）
await sdk.sendMessage({
  deviceId: 'device-001',
  platform: 'wechat',
  toId: '张三',
  content: '你好！',
  msgType: 'text'  // text/image/video
});

// 获取消息列表
await sdk.getMessages({
  deviceId: 'device-001',
  platform: 'wechat',
  conversationId: '张三',
  limit: 20
});

// 批量发送消息
await sdk.batchSendMessage({
  deviceId: 'device-001',
  platform: 'wechat',
  toIds: ['张三', '李四', '王五'],
  content: '群发消息内容',
  interval: 2.0  // 发送间隔(秒)
});
```

### 二、好友管理

```typescript
// 添加好友
await sdk.addFriend({
  deviceId: 'device-001',
  platform: 'wechat',
  userId: 'wxid_xxx',
  message: '你好，我是xxx'
});

// 通过好友请求
await sdk.acceptFriend({
  deviceId: 'device-001',
  platform: 'wechat',
  userId: 'wxid_xxx'
});

// 设置备注
await sdk.setFriendRemark({
  deviceId: 'device-001',
  platform: 'wechat',
  userId: 'wxid_xxx',
  remark: '客户-张三'
});

// 获取联系人列表
await sdk.getContacts({
  deviceId: 'device-001',
  platform: 'wechat',
  limit: 100
});
```

### 三、群聊管理

```typescript
// 创建群聊
await sdk.createGroup({
  deviceId: 'device-001',
  platform: 'wechat',
  groupName: '新群名称',
  memberIds: ['张三', '李四', '王五']
});

// 邀请入群
await sdk.inviteToGroup({
  deviceId: 'device-001',
  platform: 'wechat',
  groupId: '群名或群ID',
  memberIds: ['新成员1', '新成员2']
});

// 发送群消息（支持@）
await sdk.sendGroupMessage({
  deviceId: 'device-001',
  platform: 'wechat',
  groupId: '群名',
  content: '大家好',
  atAll: true  // @所有人
});

// 设置群欢迎语
await sdk.setGroupWelcome({
  deviceId: 'device-001',
  platform: 'wechat',
  groupId: '群名',
  welcomeText: '欢迎新成员！'
});

// 获取群列表
await sdk.getGroups({
  deviceId: 'device-001',
  platform: 'wechat'
});
```

### 四、标签管理

```typescript
// 给好友添加标签
await sdk.addTag({
  deviceId: 'device-001',
  platform: 'wechat',
  userId: '张三',
  tags: ['VIP客户', '高意向']
});

// 获取标签列表
await sdk.getTags({
  deviceId: 'device-001',
  platform: 'wechat'
});

// 根据标签获取好友
await sdk.getUsersByTag({
  deviceId: 'device-001',
  platform: 'wechat',
  tagName: 'VIP客户'
});
```

### 五、朋友圈管理

```typescript
// 发布朋友圈
await sdk.postMoments({
  deviceId: 'device-001',
  platform: 'wechat',
  content: '今日分享',
  images: ['https://example.com/image1.jpg'],
  location: '上海市'
});

// 点赞朋友圈
await sdk.likeMoments({
  deviceId: 'device-001',
  platform: 'wechat',
  userId: '张三',
  postIndex: 0  // 第一条
});

// 评论朋友圈
await sdk.commentMoments({
  deviceId: 'device-001',
  platform: 'wechat',
  userId: '张三',
  postIndex: 0,
  comment: '写得真好！'
});
```

### 六、设备管理

```typescript
// 获取设备列表
await sdk.getDevices();

// 获取设备详情
await sdk.getDevice('device-001');

// 检查设备是否在线
const isOnline = await sdk.isOnline('device-001');

// 获取在线设备列表
const onlineDevices = await sdk.getOnlineDevices();

// 设备截图
await sdk.screenshot('device-001');
```

### 七、AI Agent（智能模式）

```typescript
// 执行自然语言任务
const result = await sdk.executeTask({
  deviceId: 'device-001',
  task: '打开微信给张三发消息：明天下午2点开会',
  llmProvider: 'deepseek'
});

// 获取Agent状态
await sdk.getAgentStatus('device-001');

// 停止Agent任务
await sdk.stopAgent('device-001');
```

### 八、快捷方法

```typescript
// 发送微信消息
await sdk.wechatSend('device-001', '张三', '你好');

// 发送抖音私信
await sdk.douyinSend('device-001', 'user_xxx', '感谢关注');

// 发送小红书私信
await sdk.xhsSend('device-001', 'user_xxx', '你好');
```

## 错误处理

```typescript
try {
  const result = await sdk.sendMessage({...});
  
  if (result.code === 200 && result.data.success) {
    console.log('发送成功:', result.data.message_id);
  } else {
    console.error('发送失败:', result.data.error);
  }
} catch (error) {
  console.error('请求异常:', error.message);
}
```

## 错误码说明

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

## 通道说明

SDK会自动选择最优通道：

| 通道 | 说明 | 优先级 |
|------|------|--------|
| official_api | 官方API（抖音等） | 1（最高） |
| sdk_control | SDK控制（uiautomator2） | 2 |
| ai_agent | AI Agent（智能兜底） | 3 |

响应中的 `channel_used` 字段会告知实际使用的通道。

## 支持的平台

| 平台 | platform值 | 支持的功能 |
|------|------------|------------|
| 微信 | wechat | 消息/好友/群聊/标签/朋友圈 |
| 抖音 | douyin | 消息/粉丝/评论 |
| 小红书 | xhs | 消息/笔记/评论 |
| 闲鱼 | xianyu | 消息 |
| Soul | soul | 消息 |

## 技术支持

- **负责人**: 卡若
- **微信**: 28533368

## License

MIT
