docs(验收): 存客宝3100本地联调验收表 §七

补充首页四接口与真任务脚本验收项，关联 cunkebao 对接 README。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-24 11:09:13 +08:00
parent a56e97343b
commit f4da6faabf
1 changed files with 101 additions and 85 deletions
--- a/开发文档/5、接口/06-验收与矩阵/2026-05-24_微信真机可见验收_单项确认.md
+++ b/开发文档/5、接口/06-验收与矩阵/2026-05-24_微信真机可见验收_单项确认.md
@@ -14,125 +14,141 @@ related:
  - "[[开发文档/README|开发文档总入口]]"
  - "[[开发进度总表]]"
 ---
-# 微信真机可见验收 · 单项确认（2026-05-24）
+# 微信真机验收 · WebSocket + Frida 主控（2026-05-24）

-> **目的**：在你当前连接的 Redmi Note 13 上，用**可在手机里直接看到**的动作，确认 Hook 真机控制有效；并给出批量验收报告的**确定文件路径**。
+> **验收口径（已锁定）**：全部微信能力经 **WebSocket Agent → Frida Hook** 执行；**禁止**走服务端 ADB UI 自动化（`sdk_control` / `wechat_adb_engine`）。  
+> 存客宝对接：**ThinkPHP BFF `/v1/workphone/*` → SDK `/api/v3/*`**，设备须 WS 在线。

 ---

-## 一、已确定的批量验收文档（先看这些）
-
-| 类型 | 结论 | 文件路径（本机绝对路径） |
-|------|------|--------------------------|
-| **REST 全矩阵 E2E** | **96/96 通过（100%）** | `/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/tmp/matrix_v8056_verify_xgfe65eimrrofyws_1779590389.md` |
-| REST JSON 明细 | 同上 | `/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/tmp/matrix_v8056_verify_xgfe65eimrrofyws_1779590389.json` |
-| **Hook catalog 探针** | **173/173 通过** | `/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/tmp/matrix_hook_catalog_xgfe65eimrrofyws_1779590658.json` |
-| **Hook E2E 脚本** | **8/8 通过** | `sdk/tests/test_hook_e2e.py`（Phantom 无 Agent WS） |
-| **功能矩阵文档（带逐行状态）** | 0 项「待补全」 | `/Users/karuo/Documents/workphone-devdoc/5、接口/03-Hook与微信/微信全功能矩阵_v8.0.56.md` |
-| 项目内同步副本 | 同上 | `/Users/karuo/Documents/开发/2、私域银行/工作手机/开发文档/5、接口/03-Hook与微信/微信全功能矩阵_v8.0.56.md` |
-| E2E 最近一次 JSON | 96/96 | `/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/data/e2e_report.json` |
-
-**复验命令（后端）**：
+## 一、标准启动（无线 ADB + WS Agent + Phantom Frida）

 ```bash
-cd "/Users/karuo/Documents/开发/2、私域银行/工作手机"
-SDK_MATRIX_VERIFY=1 python3 sdk/tests/test_wechat_full_e2e.py --matrix
-SDK_MATRIX_VERIFY=1 python3 sdk/scripts/matrix_hook_catalog_verify.py -d xgfe65eimrrofyws
+adb connect 192.168.110.80:5555
+cd "/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/scripts"
+DEVICE_SERIAL=192.168.110.80:5555 bash frida_workphone_oneclick.sh
+```
+
+环境变量（SDK 已内置默认值，oneclick 自动 export）：
+
+| 变量 | 含义 |
+|------|------|
+| `WECHAT_WS_HOOK_ONLY=1` | 微信仅 WebSocket Agent + Frida |
+| `WECHAT_BACKEND_ONLY=1` | 禁止 u2/ADB UI 降级 |
+| `SDK_MATRIX_VERIFY=1` | 矩阵验收跳过 batch 防封 |
+
+Agent 单独拉起（frida-server 已跑时）：
+
+```bash
+bash sdk/scripts/ensure_ws_agent.sh
 ```

 ---

-## 二、当前真机 / 微信真实情况（2026-05-24 10:38 现场拉取）
+## 二、当前真机

 | 项 | 值 |
 |----|-----|
-| ADB 串号 | `192.168.110.80:5555`（无线，状态 **device**） |
-| SDK device_id | `xgfe65eimrrofyws` |
-| 手机型号 | Redmi Note 13 5G（gold / 2312DRAABC） |
-| 微信版本 | **8.0.56** |
-| 当前登录昵称 | **游条姐-游戏教学辅助看我朋友圈** |
-| 当前 wxid | `wxid_5g37snchpv8e22` |
-| 账号状态 API | `active`（Frida Hook 通道） |
-| 微信进程 pid | 10446 |
-| SDK 健康 | `http://127.0.0.1:8899/health` → **healthy** |
+| ADB（无线） | `192.168.110.80:5555` |
+| **WS device_id** | `192.168.110.80:5555`（与 ADB serial 一致） |
+| 微信 | 8.0.56 |
+| Frida | Phantom remote（见 `sdk/scripts/anti_detect/phantom_frida_config.json`） |
+| 安全会话 | `filehelper` / 文件传输助手 |

-说明：本机验收** deliberately 使用「文件传输助手」`filehelper`** 作为安全对象，**不会对陌生人发起加好友**，避免误加人。
-
---
-
-## 三、本次「可见」单项确认（请你现在看手机）
-
-### 确认项 F-001：向文件传输助手发送文字消息
-
-| 字段 | 内容 |
-|------|------|
-| **动作** | `POST /api/v3/message/send` → Hook → 微信发文字 |
-| **发给谁** | **文件传输助手**（wxid: `filehelper`，微信里显示「文件传输助手」） |
-| **不是加好友** | 未执行 `add_friend`；仅向已有系统会话发消息 |
-| **消息内容 1** | `[工作手机可见验收] 20260524_103845 真机Hook发送-请看文件传输助手` |
-| **消息内容 2** | `[可见验收 HH:MM:SS] 请在本机微信打开「文件传输助手」查看此条` |
-| **API 返回** | `success: true`，`channel_used: hook` |
-| **message_id** | `msg_1779590319666_281265` / `msg_1779590335482_289198` |
-
-### 你在手机上应看到什么
-
-1. 已执行 **亮屏 + 打开微信主界面**（`adb` 唤起 `com.tencent.mm/.ui.LauncherUI`）。
-2. 进入 **「文件传输助手」** 会话。
-3. 聊天记录里应出现带 **`[工作手机可见验收]`** 或 **`[可见验收`** 前缀的**新发文字**（绿色气泡，右侧为自己发送）。
-
-若聊天里暂时看不到最新一条，但 API 已是 `success: true`：说明 Hook 写入/发送链路已走通，UI 刷新可能有延迟；可下拉刷新或重新进入该会话。
-
-### 截图留证（本机文件，可双击打开）
-
-| 说明 | 路径 |
-|------|------|
-| 验收前/中截屏 | `/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/tmp/visible_verify_20260524_103845.png` |
-| 唤起微信后截屏 | `/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/tmp/visible_verify_wechat_open_20260524.png` |
-| **第 3 轮：亮屏+发消息+截屏** | `/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/tmp/visible_step3_103940.png` |
-
-在 Finder 中打开目录：
+连接自检：

 ```bash
-open "/Users/karuo/Documents/开发/2、私域银行/工作手机/sdk/tmp"
+curl -s http://127.0.0.1:8899/api/v3/connection/status
+# online_ws_count >= 1 且 online_device_ids 含设备 serial
 ```

 ---

-## 四、后端 / 前端成功判定
+## 三、SDK 验收命令（WS + Frida）

-| 层 | 判定 | 依据 |
-|----|------|------|
-| **后端 SDK** | ✅ | `/health` healthy；send 返回 `code:200` + `success:true` + `channel_used:hook` |
-| **Hook/Frida** | ✅ | `get_profile` / `account_status` 均 `frida/hook` 成功 |
-| **批量自动化** | ✅ | `matrix_v8056_verify_*_1779590145.md` → 96/96 |
-| **前端（存客宝）** | ⏳ 待你点页面 | 触客宝/workphone 页需绑 `device_id=xgfe65eimrrofyws` 后发同样接口；本文仅确认 **SDK+真机微信** 链路 |
+```bash
+DEV=192.168.110.80:5555
+# Hook ping
+curl -s -X POST http://127.0.0.1:8899/api/v3/hook/execute \
+  -H "Content-Type: application/json" \
+  -d "{\"device_id\":\"${DEV}\",\"platform\":\"wechat\",\"action\":\"ping\",\"params\":{},\"hook_only\":true}"
+
+# 发消息（channel_used 应为 websocket/frida）
+curl -s -X POST http://127.0.0.1:8899/api/v3/message/send \
+  -H "Content-Type: application/json" \
+  -d "{\"device_id\":\"${DEV}\",\"platform\":\"wechat\",\"to_id\":\"文件传输助手\",\"content\":\"[WS+Frida]\",\"msg_type\":\"text\"}"
+
+# 全矩阵 REST
+SDK_MATRIX_VERIFY=1 SDK_DEVICE_ID=$DEV SDK_E2E_TO_ID=filehelper \
+  python3 sdk/tests/test_wechat_full_e2e.py --matrix
+
+# Hook catalog 探针
+SDK_MATRIX_VERIFY=1 SDK_DEVICE_ID=$DEV \
+  python3 sdk/scripts/matrix_hook_catalog_verify.py -d $DEV
+```

 ---

-## 五、你能达到的效果（本账号实测能力摘要）
+## 四、存客宝 BFF 对接（已补接口）

-| 能力 | 是否已真机验证 | 说明 |
-|------|----------------|------|
-| 给指定会话发文字 | ✅ 本次可见 | 对象：`filehelper`；可改为任意 wxid/备注名 |
-| 读消息列表 | ✅ | `get_messages` 可读 filehelper 历史 |
-| 读联系人/资料 | ✅ | 昵称、wxid、版本 8.0.56 |
-| 加好友 | ⚠️ Hook 探针过，**未对真人执行** | 需你指定 user_id 才做可见加好友测试 |
-| 建群/退群 | ⚠️ 设备无有效 chatroom | `group_quit` 矩阵项跳过 |
+| BFF | SDK | 前端 `workphone/api.ts` |
+|-----|-----|-------------------------|
+| `GET /v1/workphone/connection/status` | `/api/v3/connection/status` | `fetchWorkPhoneConnection` |
+| `POST /v1/workphone/message/send` | `/api/v3/message/send` | `sendWorkPhoneMessage` |
+| `POST /v1/workphone/hook/execute` | `/api/v3/hook/execute` | `executeWorkPhoneHook` |
+| 原有 7 条 status/device/screenshot/ai/* | 不变 | 不变 |
+
+PHP 封装：`Server/application/common/util/WorkPhoneSDK.php` → `sendMessage` / `hookExecute` / `getConnectionStatus`
+
+**对接要点**：`device_id` 传 WS 注册 ID（本机=`192.168.110.80:5555`）；调用前 BFF 可先查 `connection/status` 确认 `online_ws_count>0`。

 ---

-## 六、下一步建议（你说「继续」默认执行）
+## 五、代码变更摘要

-1. **你确认手机**：文件传输助手是否看到 `[可见验收` 消息 → 回复「看到了」或「没看到」。
-2. **可选可见项**：指定一个**真实好友 wxid/备注**，我再做「发一条可见消息」或「改备注」并更新本文档 §三。
-3. **存客宝前端**：在 workphone 页用同一 `device_id` 点发送，对照本文档 message_id 做前后端一致验收。
+| 模块 | 变更 |
+|------|------|
+| `sdk/app/config.py` | 新增 `WECHAT_WS_HOOK_ONLY` |
+| `sdk/app/routers/unified.py` | WS 优先；禁止服务端 ADB Frida 回退；`message/send` 走 WS execute |
+| `sdk/agent/agent.py` | 自动读 phantom_frida_config → remote Frida |
+| `sdk/scripts/frida_workphone_oneclick.sh` | Agent remote Frida + SDK 环境变量 |
+| `sdk/scripts/ensure_ws_agent.sh` | WS Agent 保活脚本 |
+| 存客宝 route + Controller + WorkPhoneSDK + api.ts | BFF 三条 + 前端封装 |

 ---

-*生成时间：2026-05-24 · 设备 xgfe65eimrrofyws · 引擎 Frida Hook v3.1*
+## 六、批量报告路径
+
+| 类型 | 路径 |
+|------|------|
+| REST 矩阵 | `sdk/tmp/matrix_v8056_verify_*` |
+| Hook catalog | `sdk/tmp/matrix_hook_catalog_*` |
+| E2E JSON | `sdk/data/e2e_report.json` |
+| Agent 日志 | `sdk/logs/agent.log` |
+| SDK 日志 | `sdk/logs/sdk.log` |
+
+---
+
+## 七、存客宝 3100 本地联调验收（2026-05-24）
+
+| 检查项 | 命令/页面 | 预期 |
+|--------|-----------|------|
+| 首页设备 | `GET /v1/dashboard` | `deviceNum=1` |
+| 今日群发 | `GET /v1/dashboard/today-stats` | `groupPushNum>=1` |
+| 场景获客 | `GET /v1/dashboard/plan-stats` | 海报获客 `allNum>=1` |
+| 7日趋势 | `GET /v1/dashboard/sevenDay-stats` | 非全 0 |
+| SDK 状态 | `GET /v1/workphone/status` | `sdk_online=true` |
+| 真任务 | `run_workbench_friend_push_once.php` 等 | 真机收消息 |
+
+文档：`cunkebao_v3/开发文档/工作手机对接/README.md` §本地 Docker 联调
+
+---
+
+*引擎：WebSocket Agent + Frida Hook v3.1 · WECHAT_WS_HOOK_ONLY · 2026-05-24*
+
 ## 🔗 关联导航

 | 方向 | 文档 |
 |------|------|
 | ↑ 上级索引 | [[5、接口/06-验收与矩阵/README|06-验收与矩阵]] |
-| ↔ 相关 | [[接口规范]] · [[微信全功能矩阵_v8.0.56]] · [[工作手机API全量接口目录]] · [[开发文档/README|开发文档总入口]] · [[开发进度总表]] |
+| ↔ 相关 | [[接口规范]] · [[微信全功能矩阵_v8.0.56]] · [[工作手机API全量接口目录]] |