# 设备端 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

```bash
cd sdk/android-app
./gradlew assembleDebug
```

APK 输出：

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

### 3.2 USB 安装（Root 静默）

```bash
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

```bash
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 端口反向（本机联调）：

```bash
adb reverse tcp:8899 tcp:8899
```

---

## 5. 服务端交互协议

### 5.1 连接地址

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

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

```json
{
  "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 心跳消息（设备 -> 服务端）

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

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

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

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

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

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

```json
{
  "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`

请求体：

```json
{
  "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` 持续更新

