workphone-sdk/sdk/docs/设备端Hook版本安装与服务端对接手册.md

设备端 Hook 版本安装与服务端对接手册

1. 目标

• 在已 Root 的 Android 设备上安装 工作 APP 与 Hook 能力
• 设备通过 WebSocket 直连服务端，支持命令下发和结果回传
• 提供稳定心跳、断线重连、在线状态检测

---

2.0 无 Root 方案（与 Frida Hook 的区别）

能力	Root + frida-server	无 Root（当前 APP 实现）
进程内 Hook（wechat_hook_v2.js / RPC）	✅	❌ 无法注入 com.tencent.mm
send_message	Frida 或无障碍	✅ 无障碍自动点「搜索→选会话→发送」
get_wechat_version	Hook / PM	✅ PackageManager
get_contacts / get_messages / get_profile	读 DB	❌ 返回 501 说明（需 Root Hook）

使用要求（无 Root）

1. 安装并启动工作手机 APP，连接 WebSocket（同 Root 流程）。
2. 系统设置中为本应用开启 无障碍服务（否则 send_message 会返回 accessibility_disabled）。
3. 微信建议 简体中文 界面，以便匹配「搜索」「发送」等文案。
4. 服务端 POST /api/v3/hook/execute 仍可调用；channel_used 多为 no_root_a11y / no_root_pkg，不是 JS Hook。

若必须全量 Hawk Hook（读库、RPC），仍需 Root 注入或自带 Gadget 的定制包（不在本文「免 Root」范围）。

---

2. 设备端 ID 规则（奥创兼容）

当前设备端默认 device_id 策略：

• 首选：md5(android_id)（奥创兼容）
• 备用：device_${MODEL}_${SDK_INT}

已保留并上报辅助字段（用于排障）：

• device_profile.aochuang_device_id
• device_profile.android_id
• device_profile.serial

---

3. 安装步骤（Root 设备推荐）

3.1 编译 APK

cd sdk/android-app
./gradlew assembleDebug

APK 输出：

• sdk/android-app/app/build/outputs/apk/debug/app-debug.apk

3.2 USB 安装（Root 静默）

adb push sdk/android-app/app/build/outputs/apk/debug/app-debug.apk /data/local/tmp/work.apk
adb shell "su -c 'pm install -r -g /data/local/tmp/work.apk'"

3.3 启动 APP

adb shell "monkey -p com.workphone.agent -c android.intent.category.LAUNCHER 1"

---

4. 设备端配置

APP 设置页填写：

• server_url: ws://<server-ip>:8899/ws/device
• project_id: 项目编号
• device_id: 默认自动生成（奥创兼容），可手工覆盖
• auto_connect: 建议开启

ADB 端口反向（本机联调）：

adb reverse tcp:8899 tcp:8899

---

5. 服务端交互协议

5.1 连接地址

• ws://<server-ip>:8899/ws/device/{device_id}

5.2 注册消息（设备 -> 服务端）

{
  "type": "register",
  "device_id": "b63812da8452b7586ca01f3675ab31e5",
  "project_id": "default",
  "platform": "android",
  "model": "21121119SC",
  "sdk_version": 33,
  "app_version": "2.0.0",
  "heartbeat_interval_seconds": 30,
  "device_profile": {
    "aochuang_device_id": "b63812da8452b7586ca01f3675ab31e5",
    "android_id": "b5f7a11643a1adc5",
    "serial": "e4c02d0c0509"
  }
}

5.3 心跳消息（设备 -> 服务端）

{
  "type": "heartbeat",
  "device_id": "b63812da8452b7586ca01f3675ab31e5",
  "timestamp": 1700000000000
}

5.4 心跳配置（服务端 -> 设备）

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

5.5 执行命令（服务端 -> 设备）

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

5.6 执行结果（设备 -> 服务端）

{
  "type": "result",
  "command_id": "cmd_xxx",
  "device_id": "b63812da8452b7586ca01f3675ab31e5",
  "success": true,
  "message": "已打开 com.tencent.mm",
  "timestamp": 1700000001000
}

---

6. API 使用说明（服务端）

6.1 设备与状态

• GET /health：服务健康与在线设备
• GET /api/v3/devices：设备列表
• GET /api/v3/devices/{device_id}：设备详情
• GET /api/v3/devices/{device_id}/heartbeat：心跳状态

6.2 心跳配置

• POST /api/v3/devices/{device_id}/heartbeat/config

请求体：

{
  "heartbeat_interval_seconds": 10
}

取值范围：5-120 秒

6.3 设备执行

• POST /api/v3/devices/{device_id}/execute
• POST /api/v3/devices/{device_id}/click
• POST /api/v3/devices/{device_id}/input
• POST /api/v3/devices/{device_id}/swipe

---

7. 心跳与重连机制

• 设备端按 heartbeat_interval_seconds 周期上报心跳
• 设备端若连续 3 个周期未收到 pong，主动断线重连
• 服务端后台巡检任务会清理超时设备（max(WS_TIMEOUT, 3*heartbeat_interval)）
• 设备断线后采用指数退避重连（最多 10 次）

---

8. 验收清单

• APP 成功安装并启动前台服务
• 设置页配置 server_url/project_id/device_id 完整
• /health 能看到设备在线
• 下发 open_app/click/input/screenshot 返回成功
• 心跳接口显示 stale=false，heartbeat_age_seconds 持续更新