---
tags:
  - 工作手机
  - 手册
  - 主文档
doc-type: 主文档
layer: 9、手册
parent: [[9、手册/README|9、手册]]
related:
  - "[[SDK操作手册]]"
  - "[[微信消息E2E验证指南]]"
  - "[[开发文档/README|开发文档总入口]]"
  - "[[开发进度总表]]"
---

![文档说明](images/doc-headers/工作手机_五图总览与使用手册_2e1534.png)

# 工作手机 · 完整整合手册（补全包并入版）

> **版本**：v2.4 · **更新**：2026-05-24  
> **一句话**：2026-05-18 补全包 Frida 闭环 **已全部收编进 `sdk/`**；五图看全局，正文只补图中没有的命令、路径与验收数字。  
> **进度真源**：[开发进度总表.md](../10、项目管理/开发进度总表.md)（**99.5%**）  
> **图形风格**：[架构图风格标准.md](../2、架构/05-规范/架构图风格标准.md)

---

## 导读 · 为什么值得现在就读

这不是冷冰冰的 ZIP 归档说明。

我们把 **2026-05-18 中断的补全包** 里那套「服务器 → WebSocket → 手机 Agent → Frida → 微信 Hook」最小闭环，**已经焊进主线 `sdk/`**。110 个 action、132 条 RPC、7877 好友真机导出、无线 Frida 批量验证——不是 PPT，是跑通过的数字。

**你要做的只有三件事**：Type-C 或 WiFi 连上真机 → 一键脚本或 curl 探活 → 对微信下第一条 `send_message`。  
剩下的，交给 Frida 主控通道。

---

## 〇、内容目录

| 章 | 主题 | 跳转 |
|:--:|------|------|
| 1 | 补全包并入地图 · 九模块真源路径 | [§一](#一补全包并入地图九模块一条链打穿微信) |
| 2 | 整体原理 · 五层架构 · 五通道 | [§二](#二整体原理与五层架构) |
| 3 | 对接与集成 · 存客宝 / SDK / 设备 | [§三](#三对接与集成全景) |
| 4 | 功能能力矩阵 · 110 action 验收数字 | [§四](#四功能能力矩阵) |
| 5 | 真机测试环境 · 本机实测 | [§五](#五真机测试环境与本机实测) |
| 6 | 统一使用 · 一键闭环 | [§六](#六统一使用方式与一键闭环) |
| 7 | RPC 兼容 · 补全包核心设计 | [§七](#七rpc-四层兼容补全包最值钱的设计) |
| 8 | 无线 Frida 部署 · WiFi 免 Type-C | [§八](#八无线-frida-部署wifi-场景) |
| 9 | 交付物与文档索引 | [§九](#九交付物与文档索引) |
| 10 | 版本记录 | [§十](#十版本记录) |

**五图快览**：图1 架构 → 图2 对接 → 图3 能力 → 图4 真机 → 图5 用法（详见 §二～§六）

---

## 一、补全包并入地图：九模块一条链打穿微信

补全包与 `工作手机SDK补全包_微信Frida/` 曾用独立目录 `/home/ubuntu/work_phone_sdk_completion/` 和原型 API `/api/v3/wechat-frida/*`。**主线已吸收，路径以 `sdk/` 为准**——下表只保留一份，不再在两个目录里各写一遍。

```text
存客宝 / 脚本 / 控制台
  ↓  POST /api/v3/hook/execute   （统一入口，取代补全包 wechat-frida/execute）
FastAPI  sdk/app/main.py
  ↓  WebSocket  /ws/device/{device_id}
设备 Agent  sdk/agent/agent.py  或  v4.0 Kotlin APK
  ↓  FridaManager.attach + load_script
frida-server  →  rpc.exports  →  微信进程
  ↓  result + channel_used
JSON 回执 / 控制台 / 验收报告
```

### 1.1 九模块对照（补全包 F01～F09 → 主线代码）

| 编号 | 模块 | 职责 | **主线代码路径** | 状态 |
|:----:|------|------|------------------|:----:|
| F01 | Frida 连接管理 | attach 微信、加载 Hook、释放会话 | `sdk/agent/hook/frida_manager.py` | ✅ |
| F02 | RPC 兼容调用 | camelCase / snake_case / lowercase / invoke | 同上 `FridaManager.call()` | ✅ |
| F03 | 微信动作目录 | action、rpc、危险动作标记 | `sdk/app/skills/wechat/` + Hook JS 导出 | ✅ |
| F04 | Hook 执行器 | 业务 action → RPC | `sdk/agent/hook/hook_executor.py` | ✅ |
| F05 | 手机 Agent | WS 接入、执行 Frida 指令 | `sdk/agent/agent.py` · `sdk/agent/wireless_agent.py` | ✅ |
| F06 | 服务端 API | 设备注册、动作下发、回传 | `sdk/app/routers/unified.py` · `frida_wireless.py` | ✅ |
| F07 | Hook 桥接 | ping、连接状态、完整 Hook 入口 | `sdk/agent/hook/wechat_hook_v*.js` · 桥接模板 `wechat_hook_bridge.js` | ✅ |
| F08 | 自动验证 | 批量验证 + JSON/Markdown 报告 | `开发文档/8、部署/05-测试验收/scripts/wireless_frida_wechat_batch_verify.py` | ✅ |
| F09 | 真机截图证明 | 逐项截图归档 | `开发文档/8、部署/05-测试验收/wireless_frida_20260518/` | ✅ |

> **2026-05-24 已收编**：根目录补全包目录已移除；代码与文档真源为 `sdk/` + 本手册；历史 ZIP 见 `资料/archive/`。

### 1.2 补全包落地时间线（精华，不重复长表）

| 日期 | 里程碑 |
|------|--------|
| 2026-05-18 | 补全包重建 FastAPI + WS Agent + FridaManager + 验证脚本；RPC 方法名四层兼容 |
| 2026-05-18～19 | 无线 Frida 真机批量验证、110 矩阵 V5 纠偏 |
| 2026-05-23 | 红米真机 `xgfe65eimrrofyws` 实测，进度推至 **99.5%** |
| 2026-05-24 | 补全包文档 **全部并入本手册**；根目录补全包目录 **移除**，代码收编 `sdk/` |

---

## 二、整体原理与五层架构

> **图1 即本章全文**：五层分工、Frida 主控、设备主动连云端、五通道优先级——**均以图为准**。

<figure id="fig1">
  <img src="images/workphone_fig01_architecture.png" alt="图1 工作手机SDK五层架构与Frida主控原理" width="100%">
  <figcaption><strong>图1 · 整体原理与五层架构</strong> — 业务层 → 接入层 → 服务端 → 数据层 → 设备层；微信生产环境强制 P1 Frida Hook（<code>WECHAT_BACKEND_ONLY</code>）。</figcaption>
</figure>

**架构详图（补全包未单独画、但开发必看）**：

<figure>
  <img src="images/workphone_fig08_sdk_architecture.png" alt="工作手机SDK整体架构图" width="100%">
  <figcaption><strong>附 · SDK 整体架构</strong> — 存客宝生态 ↔ 云端 FastAPI ↔ 多设备 Agent。</figcaption>
</figure>

<figure>
  <img src="images/workphone_fig09_frida_hook_mode.png" alt="Hook Frida控制模式" width="100%">
  <figcaption><strong>附 · P1 Frida Hook 模式</strong> — 五通道中优先级最高，微信控制的「主炮」。</figcaption>
</figure>

**图中未标、但开发必记**：

- 统一入参：`device_id` + `platform` + `action` + `params` → `POST /api/v3/hook/execute`
- 可观测：`GET /api/v3/hook/probe/{id}`、`GET /api/v3/connection/status`、回执 `_channel_used`
- 更细模块拆分：[系统架构.md](../2、架构/01-总览/系统架构.md)

---

## 三、对接与集成全景

<figure id="fig2">
  <img src="images/workphone_fig02_integration.png" alt="图2 存客宝与SDK与设备对接集成" width="100%">
  <figcaption><strong>图2 · 对接与集成全景</strong> — 存客宝 / 卡若AI / 脚本 → SDK :8899 → Agent + Frida + 微信。</figcaption>
</figure>

> 调用链见**图2**；下列为图中未列全的 **API 与示例**（只写一份，与补全包契约合并）。

### 3.1 核心 API（微信 · 统一入口）

| 方法 | 路径 | 用途 |
|------|------|------|
| GET | `/health` | SDK 存活 |
| GET | `/api/v3/connection/status` | WS / ADB / 心跳 |
| GET | `/api/v3/hook/probe/{device_id}` | Frida / 微信版本 / Root |
| GET | `/api/v3/hook/actions` | 110 action 目录 |
| POST | `/api/v3/hook/execute` | **统一执行（推荐）** |
| POST | `/api/v3/message/send` | 发消息快捷路径 |
| WS | `/ws/device/{device_id}` | Agent 长连接 |

> 补全包原型 `/api/v3/wechat-frida/*` 已收敛为上表；勿在新集成里再开第二套路径。

### 3.1.1 接口网站与机器可读入口（2026-05-30）

![接口网站实时接口文档页](images/hub_api_docs_20260530.png)

| 入口 | 用途 |
|------|------|
| `/static/hub.html` | 人类可读接口网站：设备管理 → 接口文档（实时） |
| `/llms.txt` | AI/LLM 可读摘要入口 |
| `/openapi.json` | OpenAPI 真源 |
| `/api/v3/integration/manifest` | 全量机器清单（33 模块 / 358 端点） |
| `/api/v3/integration/consumers/cunkebao` | 存客宝可用子集（18 模块 / 253 端点） |
| `/api/v3/integration/capability/{device_id}?consumer=cunkebao` | 某设备实时能力矩阵 |

更细说明见：[工作手机·接口网站与任意项目对接手册.md](02-操作指南/工作手机·接口网站与任意项目对接手册.md)。

### 3.2 设备侧命令

```bash
adb reverse tcp:8899 tcp:8899
cd sdk/app && python3 -m uvicorn main:app --host 0.0.0.0 --port 8899
# Agent（设备端）
cd sdk/agent && python3 agent.py --server ws://127.0.0.1:8899/ws/device/<device_id>
```

### 3.3 PHP 示例（存客宝）

```php
$client = new WorkPhoneClient('http://127.0.0.1:8899', $apiKey);
$result = $client->hookExecute('<device_id>', 'wechat', 'send_message', [
    'to_id' => '卡若', 'content' => '1', 'msg_type' => 'text',
], true);
```

---

## 四、功能能力矩阵

<figure id="fig3">
  <img src="images/workphone_fig03_capabilities.png" alt="图3 微信110操作与多平台功能矩阵" width="100%">
  <figcaption><strong>图3 · 功能能力矩阵</strong> — 微信 110 action / 132 RPC / 24 模块；抖音·小红书；防封 6 件套；AI Brain；v4.0 统一 APK。</figcaption>
</figure>

| 指标 | 值 |
|------|-----|
| RPC 导出（去重） | **132**（V5 矩阵纠偏 V4 误判 32 条） |
| 对外 action | **110** |
| 真机好友全量导出 | **7877**（`get_contacts` + `limit=10000`） |
| 自动注册 Phase 9 | **85%** |

操作清单：`GET /api/v3/hook/actions` · 矩阵详情：[110项功能逐项确认/](../5、接口/06-验收与矩阵/110项功能逐项确认/)

---

## 五、真机测试环境与本机实测

> 口语「心态测试」= **真机测试**（ASR）。

<figure id="fig4">
  <img src="images/workphone_fig04_test_environment.png" alt="图4 红米真机测试环境与实测结果" width="100%">
  <figcaption><strong>图4 · 真机测试环境与本机实测</strong> — 实测日 2026-05-23，序列号 <code>xgfe65eimrrofyws</code>；进度 99.5%。</figcaption>
</figure>

**无线 Frida 批量验证现场**（补全包 F08/F09 产出）：

<figure>
  <img src="images/workphone_fig06_wireless_wechat_home.png" alt="无线Frida验证-微信首页" width="48%">
  <img src="images/workphone_fig07_wireless_verify.png" alt="无线Frida验证-返回首页" width="48%">
  <figcaption><strong>附 · 无线 Frida 真机截图</strong> — 原图存 <code>8、部署/05-测试验收/wireless_frida_20260518/</code>。</figcaption>
</figure>

**仅补图中未写清的一条**：微信若无法启动，先 `adb shell pm enable com.tencent.mm`，再 `am start -n com.tencent.mm/.ui.LauncherUI`。

矩阵纠偏：[微信SDK真实控制接口矩阵V5_*.md](../5、接口/06-验收与矩阵/110项功能逐项确认/2026-05-18/)

---

## 六、统一使用方式与一键闭环

<figure id="fig5">
  <img src="images/workphone_fig05_usage_flow.png" alt="图5 一键接入与日常使用流程" width="100%">
  <figcaption><strong>图5 · 统一使用方式与一键闭环</strong> — Type-C → 健康检查 → 控制台 → Hook 探测 → 发信。</figcaption>
</figure>

### 6.1 发消息

```bash
curl -s -X POST "http://127.0.0.1:8899/api/v3/hook/execute" \
  -H "Content-Type: application/json" \
  -d '{"device_id":"<id>","platform":"wechat","action":"send_message",
       "params":{"to_id":"卡若","content":"你好","msg_type":"text"},"hook_only":true}'
```

成功：`"success": true` 且 `"channel_used": "frida/hook"`（或 `_channel_used`）。

### 6.2 全量好友

```bash
curl -s -X POST "http://127.0.0.1:8899/api/v3/hook/execute" \
  -H "Content-Type: application/json" \
  -d '{"device_id":"<id>","platform":"wechat","action":"get_contacts","params":{"limit":10000}}'
```

### 6.3 故障速查

| 症状 | 修复 |
|------|------|
| 8899 无响应 | `cd sdk/app && python3 -m uvicorn main:app --host 0.0.0.0 --port 8899` |
| WS=0 | `adb reverse` + 重启 Agent |
| probe failed | 单实例 frida-server；先启微信 |
| send 503 | 先 probe 通过；勿关 `WECHAT_BACKEND_ONLY` |

**控制台**：http://127.0.0.1:8899/static/index.html

### 6.4 家里 NAS 生产环境（2026-05-24）

| 场景 | 入口 | 说明 |
|------|------|------|
| **公网（推荐）** | **https://workphone.quwanzhi.com/hub** | kr Nginx 443 → frp → 家里 NAS :8899 |
| 家里 WiFi | http://192.168.110.29:8899/hub | 同网直连，最稳 |
| API 文档 | https://workphone.quwanzhi.com/docs | OpenAPI |
| API Key | Header `X-API-Key: workphone-secret-key` | |

**部署脚本**（Mac 与 NAS 同网）：`bash sdk/scripts/deploy_home_station.sh`

**外网注意**：本机开 Clash 时域名可能 fake-ip（198.18.x）→ 规则加 `DOMAIN-SUFFIX,quwanzhi.com,DIRECT`；HTTP:80 部分网络 Empty reply，请用 **HTTPS**。

**真机 Agent 连生产 NAS**（WiFi ADB 已通时，Mac 上执行）：

```bash
cd sdk/agent
python3 agent.py -d xgfe65eimrrofyws \
  -s wss://workphone.quwanzhi.com/ws/device --heartbeat 10
```

验收：`GET /health` → `devices_online: 1`。

---

## 七、RPC 映射与 Frida 兼容

### 7.1 Frida RPC 映射（ACTION_TO_RPC）

业务 API 用 **snake_case**（`send_message`），Frida 脚本用 **camelCase**（`sendMessage`）。对照表在 `hook_executor.ACTION_TO_RPC`，**119 条已与 `wechat_hook_v2.js` rpc.exports 对齐**。

完整五层调用链、curl/PHP 示例、验收数字 → **[微信Frida_API契约.md](../5、接口/03-Hook与微信/微信Frida_API契约.md)**。

### 7.2 RPC 方法名四层兼容（FridaManager.call_rpc）

补全包反复踩坑的是 Frida Python 绑定方法名：`getMessages` vs `get_messages` vs `getmessages`。

**主线已固化在 `FridaManager.call_rpc()`**，调用顺序：

1. **snake_case**（Python 绑定常用）
2. 原始 **camelCase**（Hook 导出原名）

### 7.3 Phantom 反检测 Frida（2026-05-24）

stock `frida-server -D` attach 微信可能超时。标准做法：

- 随机二进制名 + 随机端口 → `phantom_frida_config.json`
- `unified.py` 自动读配置，走 **remote** attach
- 一键：`sdk/scripts/frida_workphone_oneclick.sh`

详见契约文档 §六。

---

## 八、无线 Frida 部署（WiFi 场景）

Type-C 是开发首选；**量产与远程运维走 WiFi**。补全包 `mobile_agent/wireless_agent.py` 能力已并入 `sdk/agent/wireless_agent.py` + `sdk/app/routers/frida_wireless.py`。

### 8.1 服务端

```bash
cd sdk/app
pip install -r requirements.txt   # 或项目根依赖
python3 -m uvicorn main:app --host 0.0.0.0 --port 8899
```

### 8.2 手机端（Termux 或 v4.0 APK 内置 Agent）

```bash
cd sdk/agent
python3 wireless_agent.py \
  --server-ws ws://<服务器IP>:8899/ws/device/<device_id> \
  --hook hook/wechat_hook_v7.js
```

### 8.3 验证

```bash
# 设备列表 / 连接状态
curl http://127.0.0.1:8899/api/v3/connection/status
curl http://127.0.0.1:8899/api/v3/hook/probe/<device_id>

# 批量验收（补全包 F08 主线版）
python3 开发文档/8、部署/05-测试验收/scripts/wireless_frida_wechat_batch_verify.py
```

危险动作（发消息、加好友、建群）默认跳过；需完整验收取 `--include-dangerous` 并确认测试号。

### 8.4 2026-06-07 无 USB 一键无线主控

当前红米测试机已验证 WiFi ADB 开发态：

```bash
bash sdk/scripts/wireless_master_oneclick.sh xgfe65eimrrofyws 127.0.0.1:8899 5555
```

验收结果：

| 项 | 结果 |
|---|---|
| ADB | 仅 WiFi serial `192.168.110.80:5555` 在线 |
| Agent | `PPID=1` 驻留，WS 注册成功 |
| Frida | phantom `fs_*` 重启后 attach，`supports_hook=true` |
| 微信 P0 | 发消息、收消息、发朋友圈 PASS=3 |
| 留痕 | `8、部署/05-测试验收/20260607_Wireless_Wechat_P0_E2E/README.md` |

图形参考：无线验收截图仍使用本章上方图6、图7（`images/workphone_fig06_wireless_wechat_home.png`、`images/workphone_fig07_wireless_verify.png`）；管理端新版截图待 W13 完成后补入。

---

## 九、交付物与文档索引

| 类别 | 路径 |
|------|------|
| 一键打开手册 | `开发文档/9、手册/open_handbook.sh`（HTML 优先） |
| **本手册（唯一主入口）** | `开发文档/9、手册/工作手机·五图总览与使用手册.md` |
| 主线代码 | `sdk/app` · `sdk/agent` · `sdk/php-sdk` |
| 历史归档 ZIP | `资料/archive/微信Frida_SDK_20260518_补全包.zip` |
| 五图 + 附图原文件 | `images/workphone_fig01~09.png`（01～05 五图；06～07 无线真机；08～09 架构附） |
| 架构详文 | [系统架构.md](../2、架构/01-总览/系统架构.md) |
| 命令速查 | [SDK操作手册.md](02-操作指南/SDK操作手册.md) |
| E2E 验收 | [微信消息E2E验证指南.md](03-验证/微信消息E2E验证指南.md) |
| **接口网站与任意项目接入** | [工作手机·接口网站与任意项目对接手册.md](02-操作指南/工作手机·接口网站与任意项目对接手册.md) |
| 存客宝对接 | [工作手机·一键接入与存客宝对接操作手册.md](02-操作指南/工作手机·一键接入与存客宝对接操作手册.md) |
| **接口全量目录** | [5、接口/07-对外接口统一清单/01-接口总清单与机器可读API.md](../5、接口/07-对外接口统一清单/01-接口总清单与机器可读API.md)（358 端点 / 33 模块） |
| **存客宝 BFF 映射** | [5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md](../5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md) |
| 接口 OpenAPI | [5、接口/04-OpenAPI/openapi_v3.0.json](../5、接口/04-OpenAPI/openapi_v3.0.json) |
| ReDoc 静态参考 | [5、接口/05-交互图/接口ReDoc静态参考.html](../5、接口/05-交互图/接口ReDoc静态参考.html) |
| 进度 | [开发进度总表.md](../10、项目管理/开发进度总表.md) |

| **Frida RPC 完整参考** | [5、接口/03-Hook与微信/微信Frida_API契约.md](../5、接口/03-Hook与微信/微信Frida_API契约.md) |

以下文档 **已并入本章**，保留文件仅为旧链接锚点：

- [微信Frida_API契约.md](../5、接口/03-Hook与微信/微信Frida_API契约.md) → §七 + 契约全文
- [微信Frida无线部署与验证说明.md](../8、部署/02-设备Hook/微信Frida无线部署与验证说明.md) → 见 §八

---

## 十、版本记录

| 日期 | 版本 | 说明 |
|------|------|------|
| 2026-05-24 | **v2.4** | **Frida RPC 映射 + Phantom 部署** 契约文档扩写；§7 分拆映射/兼容/反检测 |
| 2026-05-24 | **v2.3** | **接口全量目录 328 条** + 存客宝 BFF 映射 + 对接架构图；OpenAPI 315 paths 重导出 |
| 2026-05-24 | **v2.1** | 附图本地化 fig06～09；机擎/开发文档总入口对齐 |
| 2026-05-24 | **v2.0** | **补全包 + 微信Frida 补全包全文并入**；九模块路径对齐 `sdk/`；RPC 兼容 §七；无线部署 §八；架构/真机附图；去重原型 API |
| 2026-05-24 | v1.2 | 五图为主、正文只补 API/命令/数字 |
| 2026-05-24 | v1.0 | 首版五图 + 手册 |

---

*五图 + 九模块 + 一条 API，看懂就能控微信。架构变更时先改 `images/` 原图，再改各章「图中未标」补充条。*
## 🔗 关联导航

| 方向 | 文档 |
|------|------|
| ↑ 上级索引 | [[9、手册/README|9、手册]] |
| ↔ 相关 | [[SDK操作手册]] · [[微信消息E2E验证指南]] · [[开发文档/README|开发文档总入口]] · [[开发进度总表]] |