workphone-sdk/sdk/android-app

工作手机Agent APP

安装在手机上，实现远程控制和项目绑定

---

功能特性

• ✅ 远程服务器连接 - WebSocket长连接
• ✅ 项目绑定 - 每台手机绑定指定项目
• ✅ 后台运行 - 前台服务保持运行
• ✅ 开机自启 - 系统启动后自动连接
• ✅ 断线重连 - 网络恢复后自动重连
• ✅ 远程命令执行 - 接收服务器指令并执行

---

安装方式

方式1: 直接安装APK

1. 从Release页面下载 WorkPhoneAgent.apk
2. 传输到手机并安装
3. 允许"安装未知来源应用"权限

方式2: 源码编译

# 进入项目目录
cd sdk/android-app

# 使用Gradle编译
./gradlew assembleDebug

# APK位置
# app/build/outputs/apk/debug/app-debug.apk

---

使用指南

1. 首次配置

1. 打开APP
2. 填写服务器地址: ws://sdk.quwanzhi.com:8899/ws/device
3. 填写项目ID: 从管理后台获取
4. 设备ID默认自动生成为奥创兼容格式：md5(android_id)（可自定义覆盖）
5. 点击"连接服务器"

2. 状态说明

状态	说明
未连接	服务未启动
正在连接...	正在建立WebSocket连接
已连接	成功连接服务器
已断开	连接已断开
连接错误	网络或服务器异常

3. 后台运行

• 连接成功后，服务会在后台持续运行
• 通知栏会显示"工作手机Agent - 已连接"
• 即使关闭APP，服务依然运行
• 开机后自动启动并连接

---

服务器端配置

WebSocket端点

服务器需要提供WebSocket端点接收设备连接:

ws://your-server:8899/ws/device/{device_id}

消息格式

设备注册消息:

{
  "type": "register",
  "device_id": "device_001",
  "project_id": "project_xxx",
  "platform": "android",
  "model": "Redmi Note 13",
  "sdk_version": 34,
  "app_version": "1.0.0"
}

心跳消息（默认30秒，可远程配置）:

{
  "type": "heartbeat",
  "device_id": "device_001",
  "timestamp": 1706000000000
}

心跳配置（服务器下发）:

{
  "type": "config",
  "heartbeat_interval_seconds": 10
}

执行命令（服务器发送）:

{
  "type": "execute",
  "command_id": "cmd_001",
  "action": "open_app",
  "params": {
    "package": "com.tencent.mm"
  }
}

命令结果（设备返回）:

{
  "type": "result",
  "command_id": "cmd_001",
  "device_id": "device_001",
  "success": true,
  "message": "已打开 com.tencent.mm",
  "timestamp": 1706000001000
}

---

支持的命令

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

---

权限说明

权限	用途
INTERNET	网络连接
FOREGROUND_SERVICE	后台服务
POST_NOTIFICATIONS	显示通知
RECEIVE_BOOT_COMPLETED	开机自启
SYSTEM_ALERT_WINDOW	悬浮窗（预留）

---

项目结构

android-app/
├── app/
│   ├── src/main/
│   │   ├── java/com/workphone/agent/
│   │   │   ├── MainActivity.kt      # 主界面
│   │   │   ├── AgentService.kt      # 后台服务
│   │   │   └── BootReceiver.kt      # 开机启动
│   │   ├── res/
│   │   │   ├── layout/              # 布局文件
│   │   │   └── values/              # 资源文件
│   │   └── AndroidManifest.xml
│   └── build.gradle
├── build.gradle
├── settings.gradle
└── README.md

---

编译要求

• Android Studio 2023.1+
• JDK 17
• Gradle 8.2
• Android SDK 34

---

联系方式

• 微信: 28533368
• 邮箱: zhiqun@qq.com