siyu-bank/workphone-sdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
workphone-sdk/开发文档/9、手册/工作手机·五图总览与使用手册.md
Manus AI a073d95f1c
Some checks failed
SDK CI / python-compile (push) Has been cancelled
Details
chore: GitHub源码文档交接快照 2026-07-19 
保留源码与部署文档，排除超大二进制和本地运行配置。
2026-07-19 16:16:14 +08:00

19 KiB
Raw Permalink Blame History

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

文档说明

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

版本：v2.4 · 更新：2026-05-24
一句话：2026-05-18 补全包 Frida 闭环 已全部收编进 sdk/；五图看全局，正文只补图中没有的命令、路径与验收数字。
进度真源：开发进度总表.md（99.5%）
图形风格：架构图风格标准.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 兼容 · 补全包核心设计 §七
8 无线 Frida 部署 · WiFi 免 Type-C §八
9 交付物与文档索引 §九
10 版本记录 §十

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

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

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

存客宝 / 脚本 / 控制台
  ↓  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 主控、设备主动连云端、五通道优先级——均以图为准。

图1 工作手机SDK五层架构与Frida主控原理
图1 · 整体原理与五层架构 — 业务层 → 接入层 → 服务端 → 数据层 → 设备层；微信生产环境强制 P1 Frida Hook（WECHAT_BACKEND_ONLY）。

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

工作手机SDK整体架构图
附 · SDK 整体架构 — 存客宝生态 ↔ 云端 FastAPI ↔ 多设备 Agent。
Hook Frida控制模式
附 · P1 Frida Hook 模式 — 五通道中优先级最高，微信控制的「主炮」。

图中未标、但开发必记：

  • 统一入参：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 存客宝与SDK与设备对接集成
图2 · 对接与集成全景 — 存客宝 / 卡若AI / 脚本 → SDK :8899 → Agent + Frida + 微信。

调用链见图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）

接口网站实时接口文档页

入口 用途
/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。

3.2 设备侧命令

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 示例（存客宝）

$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);

四、功能能力矩阵

图3 微信110操作与多平台功能矩阵
图3 · 功能能力矩阵 — 微信 110 action / 132 RPC / 24 模块；抖音·小红书；防封 6 件套；AI Brain；v4.0 统一 APK。
指标 值
RPC 导出（去重） 132（V5 矩阵纠偏 V4 误判 32 条）
对外 action 110
真机好友全量导出 7877（get_contacts + limit=10000）
自动注册 Phase 9 85%

操作清单：GET /api/v3/hook/actions · 矩阵详情：110项功能逐项确认/

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

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

图4 红米真机测试环境与实测结果
图4 · 真机测试环境与本机实测 — 实测日 2026-05-23，序列号 xgfe65eimrrofyws；进度 99.5%。

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

无线Frida验证-微信首页 无线Frida验证-返回首页
附 · 无线 Frida 真机截图 — 原图存 8、部署/05-测试验收/wireless_frida_20260518/。

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

矩阵纠偏：微信SDK真实控制接口矩阵V5_*.md

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

图5 一键接入与日常使用流程
图5 · 统一使用方式与一键闭环 — Type-C → 健康检查 → 控制台 → Hook 探测 → 发信。

6.1 发消息

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 全量好友

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 上执行）：

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。

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 服务端

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）

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

8.3 验证

# 设备列表 / 连接状态
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 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
命令速查 SDK操作手册.md
E2E 验收 微信消息E2E验证指南.md
接口网站与任意项目接入 工作手机·接口网站与任意项目对接手册.md
存客宝对接 工作手机·一键接入与存客宝对接操作手册.md
接口全量目录 5、接口/07-对外接口统一清单/01-接口总清单与机器可读API.md（358 端点 / 33 模块）
存客宝 BFF 映射 5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md
接口 OpenAPI 5、接口/04-OpenAPI/openapi_v3.0.json
ReDoc 静态参考 5、接口/05-交互图/接口ReDoc静态参考.html
进度 开发进度总表.md

| Frida RPC 完整参考 | 5、接口/03-Hook与微信/微信Frida_API契约.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
↔ 相关 SDK操作手册 · 微信消息E2E验证指南 · [[开发文档/README