workphone-sdk/sdk/typescript-sdk

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

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

接口文档：工作手机API全量接口目录.md · BFF映射表

安装

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

快速开始

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' }

功能模块

一、消息管理

// 发送消息（支持微信/抖音/小红书/闲鱼）
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  // 发送间隔(秒)
});

二、好友管理

// 添加好友
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
});

三、群聊管理

// 创建群聊
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'
});

四、标签管理

// 给好友添加标签
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客户'
});

五、朋友圈管理

// 发布朋友圈
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: '写得真好！'
});

六、设备管理

// 获取设备列表
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（智能模式）

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

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

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

八、快捷方法

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

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

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

错误处理

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