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

12 KiB

Raw Blame History

工作手机SDK v3.0 使用说明书

存客宝的AI手机控制引擎

版本：3.0.0 | 更新日期：2026-01-27

1. 系统概述

1.1 系统架构

┌─────────────────────────────────────────────────────────────┐
│                      存客宝后端                              │
│                    (PHP/Laravel)                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ HTTP API
┌─────────────────────────────────────────────────────────────┐
│                   工作手机SDK v3.0                           │
│                   (Python/FastAPI)                          │
│                                                             │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│   │  ADB控制    │  │  WebSocket  │  │  AI Agent   │        │
│   │  (直连)     │  │  (远程)     │  │  (智能)     │        │
│   └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌─────────┐     ┌─────────┐     ┌─────────┐
        │ 手机1   │     │ 手机2   │     │ 手机N   │
        │ (微信)  │     │ (抖音)  │     │ (小红书)│
        └─────────┘     └─────────┘     └─────────┘

1.2 核心功能

功能	说明	支持平台
发送消息	自动发送文字/图片消息	微信、抖音、小红书
获取消息	读取聊天记录	微信、抖音、小红书
添加好友	自动添加好友/关注	微信、抖音、小红书
通过好友	自动通过好友请求	微信
发朋友圈	自动发布动态	微信、抖音
截图	实时获取屏幕截图	所有APP
UI控制	点击、滑动、输入	所有APP
AI Agent	自然语言控制	所有APP

1.3 服务地址

服务	地址	说明
API服务	http://localhost:8899	主服务地址
API文档	http://localhost:8899/docs	Swagger文档
健康检查	http://localhost:8899/health	服务状态

2. 快速开始

2.1 启动服务

方式一：Docker启动（推荐生产环境）

cd sdk
docker compose up -d

方式二：本地启动（开发调试）

cd sdk/app
pip3 install -r ../requirements.txt
python3 -c "import uvicorn; from main import app; uvicorn.run(app, host='0.0.0.0', port=8899)"

2.2 连接手机

真实手机：

开启手机「开发者选项」→「USB调试」
用USB线连接电脑
手机上点击「允许USB调试」

模拟器（无真机时）：

# 创建模拟器
avdmanager create avd -n RedMi13 -k "system-images;android-34;google_apis;arm64-v8a"

# 启动模拟器
emulator -avd RedMi13 &

2.3 验证连接

# 检查设备
curl http://localhost:8899/api/v3/adb/devices

# 响应示例
{
  "code": 200,
  "data": [{
    "serial": "emulator-5554",
    "model": "sdk_gphone64_arm64",
    "android_version": "14",
    "status": "online"
  }]
}

3. API接口详解

3.1 设备管理

获取设备列表

GET /api/v3/adb/devices

响应：

{
  "code": 200,
  "data": [
    {
      "serial": "emulator-5554",
      "model": "sdk_gphone64_arm64",
      "brand": "google",
      "android_version": "14",
      "display": {"width": 1080, "height": 2400},
      "status": "online"
    }
  ]
}

扫描设备

POST /api/v3/adb/scan

获取设备详情

GET /api/v3/adb/devices/{serial}

3.2 基础控制

截图

POST /api/v3/adb/devices/{serial}/screenshot

响应：

{
  "code": 200,
  "data": {
    "base64": "iVBORw0KGgo...",
    "width": 1080,
    "height": 2400,
    "size": 148845
  }
}

效果展示：

点击坐标

POST /api/v3/adb/devices/{serial}/click
Content-Type: application/json

{
  "x": 540,
  "y": 1200
}

响应：

{
  "code": 200,
  "data": {
    "success": true,
    "x": 540,
    "y": 1200
  }
}

点击文字

POST /api/v3/adb/devices/{serial}/click-text
Content-Type: application/json

{
  "text": "设置",
  "timeout": 10
}

输入文字

POST /api/v3/adb/devices/{serial}/input
Content-Type: application/json

{
  "text": "Hello World",
  "clear": true
}

滑动屏幕

POST /api/v3/adb/devices/{serial}/swipe
Content-Type: application/json

{
  "direction": "up",
  "scale": 0.5
}

方向参数：

up - 向上滑动
down - 向下滑动
left - 向左滑动
right - 向右滑动

效果展示：

滑动前	滑动后

按键操作

POST /api/v3/adb/devices/{serial}/key
Content-Type: application/json

{
  "key": "back"
}

支持的按键：

back - 返回键
home - 主页键
recent - 最近任务
enter - 回车
volume_up - 音量+
volume_down - 音量-

3.3 APP控制

启动APP

POST /api/v3/adb/devices/{serial}/app/start
Content-Type: application/json

{
  "package": "com.android.settings"
}

常用APP包名：

APP	包名
微信	com.tencent.mm
抖音	com.ss.android.ugc.aweme
小红书	com.xingin.xhs
淘宝	com.taobao.taobao
设置	com.android.settings

效果展示：

停止APP

POST /api/v3/adb/devices/{serial}/app/stop
Content-Type: application/json

{
  "package": "com.android.settings"
}

获取当前APP

GET /api/v3/adb/devices/{serial}/app/current

响应：

{
  "code": 200,
  "data": {
    "package": "com.android.settings",
    "raw": "mCurrentFocus=Window{...com.android.settings...}"
  }
}

获取已安装APP

GET /api/v3/adb/devices/{serial}/app/list

3.4 UI分析

获取UI树

GET /api/v3/adb/devices/{serial}/ui-tree

响应：

{
  "code": 200,
  "data": {
    "xml": "<?xml version=\"1.0\"?><hierarchy>..."
  }
}

4. PHP SDK使用

4.1 安装

将 php-sdk/WorkPhoneClient.php 复制到项目中：

require_once 'WorkPhoneClient.php';
use Cunkebao\WorkPhone\WorkPhoneClient;

4.2 初始化

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

4.3 使用示例

发送消息

// 微信消息
$result = $sdk->sendMessage(
    'emulator-5554',    // 设备ID
    'wechat',           // 平台
    '张三',              // 接收者
    '你好，这是测试消息'   // 内容
);

// 快捷方式
$sdk->wechatSend('emulator-5554', '张三', '你好');
$sdk->douyinSend('emulator-5554', '用户', '感谢关注');
$sdk->xhsSend('emulator-5554', '用户', 'Hi~');

设备管理

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

// 检查设备是否在线
if ($sdk->isOnline('emulator-5554')) {
    echo "设备在线";
}

// 截图
$screenshot = $sdk->screenshot('emulator-5554');
$imageData = base64_decode($screenshot['data']['base64']);
file_put_contents('screen.png', $imageData);

控制操作

// 点击
$sdk->click('emulator-5554', 540, 1200);

// 输入
$sdk->input('emulator-5554', 'Hello World');

// 滑动
$sdk->swipe('emulator-5554', 'up');

// 执行脚本
$sdk->execute('emulator-5554', 'wechat', 'send_message', [
    'to_id' => '张三',
    'content' => '你好'
]);

AI Agent

// 执行自然语言任务
$result = $sdk->executeTask(
    'emulator-5554',
    '打开微信给张三发消息：明天下午3点开会'
);

// 获取任务状态
$status = $sdk->getAgentStatus('emulator-5554');

// 停止任务
$sdk->stopAgent('emulator-5554');

5. 实际操作演示

5.1 完整流程：打开设置APP

步骤1：检查设备

curl http://localhost:8899/api/v3/adb/devices

步骤2：启动APP

curl -X POST http://localhost:8899/api/v3/adb/devices/emulator-5554/app/start \
  -H "Content-Type: application/json" \
  -d '{"package": "com.android.settings"}'

步骤3：截图确认

curl -X POST http://localhost:8899/api/v3/adb/devices/emulator-5554/screenshot \
  | jq -r '.data.base64' | base64 -d > settings.png

效果：

5.2 完整流程：滑动浏览

向上滑动：

curl -X POST http://localhost:8899/api/v3/adb/devices/emulator-5554/swipe \
  -H "Content-Type: application/json" \
  -d '{"direction": "up", "scale": 0.5}'

向下滑动：

curl -X POST http://localhost:8899/api/v3/adb/devices/emulator-5554/swipe \
  -H "Content-Type: application/json" \
  -d '{"direction": "down", "scale": 0.5}'

5.3 完整流程：发送微信消息（伪代码）

$sdk = new WorkPhoneClient('http://localhost:8899', 'key');

// 1. 检查设备
if (!$sdk->isOnline('device-001')) {
    die('设备不在线');
}

// 2. 启动微信
$sdk->execute('device-001', 'wechat', 'launch', []);
sleep(3);

// 3. 搜索联系人
$sdk->execute('device-001', 'wechat', 'search', ['keyword' => '张三']);
sleep(2);

// 4. 发送消息
$result = $sdk->execute('device-001', 'wechat', 'send_message', [
    'to_id' => '张三',
    'content' => '你好，这是自动发送的消息',
    'msg_type' => 'text'
]);

if ($result['data']['success']) {
    echo '发送成功！';
}

6. 常见问题

Q1: 设备连接不上？

检查步骤：

确认USB调试已开启
执行 adb devices 查看设备
如果显示 unauthorized，需要在手机上点击「允许调试」

Q2: 截图返回空？

可能原因：

设备屏幕已关闭
执行 adb -s {serial} shell input keyevent KEYCODE_WAKEUP 唤醒

Q3: 点击不生效？

可能原因：

坐标错误，使用截图确认位置
APP有弹窗遮挡

Q4: 如何获取元素坐标？

方法1：截图 + 图片查看器

截图后用图片查看器查看坐标

方法2：使用UI树

curl http://localhost:8899/api/v3/adb/devices/{serial}/ui-tree

从XML中查找 bounds="[x1,y1][x2,y2]"

Q5: 如何支持多台手机？

每台手机有唯一的 serial（如 emulator-5554、192.168.1.100:5555）， API调用时指定不同的 serial 即可。

附录

A. 错误码说明

错误码	说明
200	成功
400	参数错误
404	设备/资源不存在
408	操作超时
500	服务器错误
503	设备不在线

B. 联系方式

技术负责人：卡若
微信：28533368
邮箱：zhiqun@qq.com

文档版本：1.0 | 最后更新：2026-01-27

12 KiB Raw Blame History Unescape Escape

工作手机SDK v3.0 使用说明书

目录

1. 系统概述

1.1 系统架构

1.2 核心功能

1.3 服务地址

2. 快速开始

2.1 启动服务

2.2 连接手机

2.3 验证连接

3. API接口详解

3.1 设备管理

获取设备列表

扫描设备

获取设备详情

3.2 基础控制

截图

点击坐标

点击文字

输入文字

滑动屏幕

按键操作

3.3 APP控制

启动APP

停止APP

获取当前APP

获取已安装APP

3.4 UI分析

获取UI树

4. PHP SDK使用

4.1 安装

4.2 初始化

4.3 使用示例

发送消息

设备管理

控制操作

AI Agent

5. 实际操作演示

5.1 完整流程：打开设置APP

5.2 完整流程：滑动浏览

5.3 完整流程：发送微信消息（伪代码）

6. 常见问题

Q1: 设备连接不上？

Q2: 截图返回空？

Q3: 点击不生效？

Q4: 如何获取元素坐标？

Q5: 如何支持多台手机？

附录

A. 错误码说明

B. 联系方式

12 KiB

Raw Blame History