workphone-sdk/sdk/docs/APP控制方案.md

工作手机APP控制方案

手机安装Agent APP，实现远程控制与项目绑定

---

一、整体架构

┌─────────────────────────────────────────────────────────────────────────┐
│                           控制中心架构                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐   │
│  │  管理后台     │     │    SDK服务器      │     │   工作手机       │   │
│  │  (Web/PHP)   │────►│  (Python/Docker) │◄────│   (Android)     │   │
│  │              │     │                  │     │                  │   │
│  │  - 项目管理   │     │  - WebSocket Hub │     │  - Agent APP    │   │
│  │  - 设备监控   │     │  - 项目绑定      │     │  - 后台服务      │   │
│  │  - 批量控制   │     │  - 命令分发      │     │  - 开机自启      │   │
│  └──────────────┘     └──────────────────┘     └──────────────────┘   │
│         │                      │                       │               │
│         │      HTTP API        │     WebSocket         │               │
│         └──────────────────────┴───────────────────────┘               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

---

二、部署步骤

2.1 服务器端部署

# 1. 进入SDK目录
cd /path/to/工作手机/sdk

# 2. 启动服务（Docker方式）
docker compose up -d

# 3. 或者直接运行
cd app && python main.py

服务端口:

• HTTP API: 8899
• WebSocket: ws://your-server:8899/ws/device/{device_id}

2.2 手机端安装

方式1: 安装APK

# 编译APK（需要Android Studio）
cd sdk/android-app
./gradlew assembleRelease

# 安装到手机
adb install app/build/outputs/apk/release/app-release.apk

方式2: 直接下载

• 从Release页面下载 WorkPhoneAgent.apk

2.3 APP配置

1. 打开"工作手机Agent"应用
2. 填写配置:
   • 服务器地址: ws://sdk.quwanzhi.com:8899/ws/device
   • 项目ID: 从管理后台获取（如: project_001）
   • 设备ID: 自动生成或自定义
3. 点击"连接服务器"

---

三、API接口说明

3.1 项目管理

获取所有项目:

GET /api/v3/projects

# 响应
{
  "success": true,
  "projects": [
    {
      "project_id": "project_001",
      "total_devices": 10,
      "online_devices": 8
    }
  ]
}

获取项目设备:

GET /api/v3/projects/{project_id}/devices

# 响应
{
  "success": true,
  "project_id": "project_001",
  "devices": [
    {
      "device_id": "device_001",
      "model": "Redmi Note 13",
      "status": "online",
      "connected_at": "2026-01-27T10:00:00"
    }
  ]
}

3.2 批量控制

广播命令（不等待响应）:

POST /api/v3/projects/{project_id}/broadcast
Content-Type: application/json

{
  "action": "open_app",
  "params": {"package": "com.tencent.mm"}
}

# 响应
{
  "success": true,
  "sent": 8,
  "failed": 0
}

执行命令（等待响应）:

POST /api/v3/projects/{project_id}/execute?timeout=30
Content-Type: application/json

{
  "action": "get_device_info",
  "params": {}
}

# 响应
{
  "success": true,
  "total_devices": 8,
  "success_count": 8,
  "results": [...]
}

3.3 单设备控制

POST /api/v3/projects/{project_id}/devices/{device_id}/execute
Content-Type: application/json

{
  "action": "open_app",
  "params": {"package": "com.tencent.mm"}
}

---

四、支持的命令

命令	参数	说明
open_app	package: 包名	打开指定APP
get_installed_apps	无	获取已安装APP列表
get_device_info	无	获取设备信息

扩展命令（需要ROOT或辅助功能权限）:

命令	参数	说明
click	x, y	点击坐标
swipe	x1, y1, x2, y2	滑动
input_text	text	输入文字
screenshot	无	截图

---

五、PHP SDK使用

<?php
require_once 'WorkPhoneClient.php';

$client = new WorkPhoneClient('http://sdk.quwanzhi.com:8899');

// 获取项目设备
$devices = $client->getProjectDevices('project_001');

// 向项目所有设备广播命令
$result = $client->broadcastToProject('project_001', [
    'action' => 'open_app',
    'params' => ['package' => 'com.tencent.mm']
]);

// 在指定设备执行命令
$result = $client->executeOnDevice('project_001', 'device_001', [
    'action' => 'get_device_info'
]);

---

六、运维说明

6.1 设备状态监控

# 查看所有在线设备
curl http://localhost:8899/api/v3/devices

# 查看项目设备
curl http://localhost:8899/api/v3/projects/project_001/devices

6.2 日志查看

# 服务器日志
docker compose logs -f sdk

# 手机端日志（通过ADB）
adb logcat -s AgentService

6.3 故障排查

问题	原因	解决方案
APP无法连接	网络或地址错误	检查服务器地址和端口
频繁断线	心跳超时	检查网络稳定性
命令执行失败	权限不足	授予APP必要权限
开机不自启	被系统优化	关闭电池优化

---

七、安全建议

1. 生产环境使用HTTPS/WSS
2. 添加API认证Token
3. 限制可执行的命令类型
4. 记录操作日志
5. 设置设备白名单

---

八、文件结构

sdk/
├── app/                     # SDK服务器
│   ├── main.py             # 主入口
│   ├── routers/
│   │   └── projects.py     # 项目管理API
│   └── services/
│       └── ws_hub.py       # WebSocket连接管理
│
├── android-app/            # Android Agent APP
│   ├── app/src/main/java/
│   │   └── com/workphone/agent/
│   │       ├── MainActivity.kt      # 主界面
│   │       ├── AgentService.kt      # 后台服务
│   │       └── BootReceiver.kt      # 开机启动
│   └── README.md
│
├── php-sdk/                # PHP客户端SDK
│   └── WorkPhoneClient.php
│
└── docs/
    └── APP控制方案.md      # 本文档