Files

Manus AI 9c30320826 feat(接口): 四端可直调·模块化接口能力清单(自动生成)

实时拉 skill-registry(9平台/49模块/211动作)生成清单，按平台×模块×动作组织+四端入口矩阵+连接方案切换；真机只读复验 group20/tag323/contacts50。

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-30 12:55:58 +08:00

58 KiB

Raw Blame History

工作手机_存客宝四端对接_20260529

本文档 = 四端对接/BFF/COORD 唯一需求真源
微信 128 接口见微信全量控机 · 设备/AI 见设备Agent

完成目标：SDK v3 作为唯一设备执行层，与存客宝 BFF 及四端（存客宝/触客宝/SuperAdmin/AI数智员工）全接口对接；本仓库只完善 SDK/中间层/文档；四端业务切换走 COORD。

日期：2026-05-29 · 模块：对接 / 中间层 / 多平台 / 机擎阿桥
合并自：原 工作手机_存客宝四端全量对接_20260529.md · 02-业务/业务需求.md §六§七 · 机擎/SKILL.md §五B/§7 · references/工作手机中间层抽象.md
姊妹需求（共 3 篇）：

工作手机_设备Agent与基础设施_20260529

工作手机_微信全量控机与私域_20260529

本文 · 存客宝四端 + PHP/TS SDK + COORD

〇、总进度看板

维度	比例
SDK 路由（实测 346 paths / 355 ops）	100%（OpenAPI↔snapshot diff 清零 2026-05-30；全业务路由已模块化 tag，0 未分类业务接口）
BFF 52+proxy	100%（存客宝 Server 维护；develop 当前未含，COORD-WP-001）
PHP/TS 中间层 SDK	100%
四端业务切 SDK	0%（COORD）
真机 P0 E2E	PASS=11 / BLOCKED=1 / FAIL=0（2026-05-29 16:50 实测；Frida hook 真机打通，send/group/tag/list 真实数据；仅 friend-add 待 CKB 外部凭证 U2）见 §十一

一、架构边界（强制）

┌─────────────┐  ┌─────────────┐  ┌──────────────┐  ┌─────────────┐
│ 存客宝 H5   │  │ 触客宝 PC   │  │ SuperAdmin   │  │ AI数智员工  │
│ :3100       │  │ :3101       │  │ :3103        │  │ :3104       │
└──────┬──────┘  └──────┬──────┘  └──────┬───────┘  └──────┬──────┘
       │ 原业务 URL 不变   │ /v1/kefu/*     │ /v1/admin/*     │ /v1/open/*
       └──────────────────┴────────────────┴─────────────────┘
                                    │
                          存客宝 BFF（ThinkPHP）
                          /v1/workphone/*  ← COORD：对方切 Bridge/Job
                                    │
                          WorkPhoneSDK.php / sdk/proxy
                                    │
       ┌────────────────────────────▼────────────────────────────┐
       │  工作手机 SDK :8899  /api/v3/*   ← 【本需求只改这里】      │
       │  Agent WS + Frida Hook + u2（解封等）                      │
       └────────────────────────────┬────────────────────────────┘
                                    ▼
                              Root 真机 · 微信/多平台

层级	谁改	纪律
工作手机 SDK	本仓库	328 路由稳定、OpenAPI 同步、真机 E2E
存客宝 BFF	存客宝 Server（已 52 路由）	工作手机只消费/验证，不 patch 其 PHP
四端业务 Job/前端	各端仓库	COORD 协调后由对方切 `USE_FOR_*` / Bridge
Frida Hook	本仓库	Hook 模块、probe、friend-add 上报

二、四端对接关系总表

端	端口	业务入口（不改 URL）	设备执行标准路径	工作手机 SDK 直接对接	协调方
存客宝 H5	3100	`/v1/devices` `/v1/wechats` `/v1/workbench/` `/v1/plan/`	`/v1/workphone/` → `/api/v3/`	✅ cunke-bao/* + 全 Facade	存客宝 Job/Bridge 切换
触客宝	3101	`/v1/kefu/message/send` `sync` `moments/add` `ai/chat`	同上 BFF	✅ message/group/moments/agent	触客宝 IM 层切 BFF
SuperAdmin	3103	设备列表/在线态（读库 + 展示）	间接：依赖 `ck_device` 与 SDK 在线态一致	✅ `GET /devices` 供 BFF 聚合	COORD：设备唯一绑项目
AI数智员工	3104	`/v1/open/terminal/*` `/v1/store/login`	不直连 SDK；经存客宝 OpenPlatform	✅ 设备须先在 SDK 登记	COORD-004 扫码绑定

三、功能域 · 接口全量映射（工作手机侧责任）

状态：SDK = 本仓库实现与真机验收；BFF = 存客宝已注册（2026-05-24 PASS=17）；业务切 = 四端仍 S2/WS，需 COORD。

3.1 设备管理（P0）

存客宝原接口	BFF	工作手机 SDK	SDK 状态	真机 E2E	工作手机待办
`GET /v1/devices`	`GET /v1/workphone/devices`	`GET /api/v3/devices`	✅	🔧	在线态与 WS 心跳一致
`GET /v1/devices/{id}`	`GET /v1/workphone/device`	`GET /api/v3/devices/{id}`	✅	🔧	health/heartbeat 字段对齐 BFF
`PUT /v1/devices/refresh`	内部 getDevice+getContacts	devices + contacts	✅	🔧	刷新超时 ≤30s
截图/点击	`POST .../screenshot` `click`	`POST /devices/{id}/screenshot` 等	✅	✅/🔧	UI 自动化文档补参

SuperAdmin 协调：超管读 s2_device/ck_device 展示在线数 → 工作手机保证 GET /devices 与 Agent 注册 ID 一致；不改 SuperAdmin 代码，由 COORD 约定 IMEI/device_id 字段。

3.2 微信 / 好友 / 通讯录（P0）

能力	BFF	SDK	业务切	工作手机待办
好友列表同步	`GET /v1/workphone/contacts`	`GET /api/v3/contacts`	🔧 RefreshWechat	contacts 分页、platform=wechat
刷新好友	内部 getContacts	同上	🔧	与 MySQL diff 由 BFF 做
加好友/批量	`friends/add` `batch-add`	`POST /api/v3/friend/*`	🔧 场景计划	batch 间隔、风控 interval
改备注/删好友	`set-remark` `delete`	同上	🔧
朋友圈列表/导出	`moments/list`	`POST /api/v3/moments/list`	🔧	支持 since_time 增量
新好友进池	—	`POST /api/v3/cunke-bao/hook/friend-add`	✅ Hook	Frida 真发验证

3.3 工作台自动化（P0）

Job（存客宝）	BFF	SDK	工作手机待办
消息群发	`messages/batch-send`	`POST /api/v3/message/batch-send`	interval 默认 3–8s；503 离线语义
自动建群	`groups/create` + `invite`	`group/create` `invite`	成员上限、失败重试
入群欢迎	`groups/set-welcome`	`group/set-welcome`
群 @ 消息	`groups/send-message`	`group/send-message`	at_list 参数
改群名/公告	`set-name` `set-notice`	同上
朋友圈同步/发	`moments/list` `post`	同上	图片数组 multipart
流量分发	`tags/users` + 业务	`POST /api/v3/tag/users`
自动点赞	`moments/like` / hook	`moments/like`	P2

协调：USE_FOR_WORKBENCH=true 由存客宝 .env 切换；工作手机侧提供 batch-send / batch-add 压测脚本 与 openapi 示例。

3.3.1 风控参数表（CK-T2 真源 · 2026-05-29 检索 · 数据支撑）

来源：wechatapi.net 风控指南 · wechatsdk.com Risk Control · apifox 个微风控。SDK batch 接口默认值据此设定；铁律：宁慢勿封。

动作	频率上限	间隔（随机）	说明
发消息·同一对象	≤40 条/分钟	1–3s/条	超频"看着成功但对方收不到"（降权）
发消息·不同对象	—	3–5s/对象	单线程队列消费，禁并发；§3.3 默认 3–8s ✅ 偏保守
主动加好友	新号 5、>7天 10、>3月 15、>6月 20–30、>1年 50（/天）；1 小时 ≤5	每次 ≥2 分钟	新号须在线 3 天后才可调；超限即使返回 success 对方也收不到
被动同意好友	≤300/天（建议 ≤50）	20–40s；收到到同意 ≥30s	随机选 pending（非按时序）增随机性
建群	≤10–15/天	两次 ≥10 分钟	新群 1 小时拉人 ≤6；建议主设备建群
新号观察期	1–3 天静默挂机	—	禁批量群发/加好友/建群；过期后可稳定数月

反风控编码要点（写入 batch 接口实现）：

正态/泊松延迟（λ≈2.8），非固定间隔；模拟真人打字作息
文本动态混淆：随机 emoji/半全角空格/同义词重写 → 破坏文本 MD5 与长度特征，躲过"同质化合并审计"
异常熔断：命中"操作过于频繁"→ 立即停所有任务 + 切网 + 24–72h 挂机；重试用指数退避非立即重试
设备纪律：一机一号、独立 IP；运行设备禁装抢红包/虚拟定位外挂

3.4 场景获客 / 线索（P0）

场景	SDK 路径	触发	工作手机待办
新好友线索	`POST /api/v3/cunke-bao/hook/friend-add`	Frida	签名、重试、幂等 device_id+wxid
通讯录批量	`POST /api/v3/cunke-bao/batch-contacts`	定时/Hook	大批量分页
手动线索	`POST /api/v3/cunke-bao/report-lead`	测试/计划	对接 ckbapi scenarios
群变动	`POST /api/v3/cunke-bao/hook/group-change`	Frida	事件字段与存客宝 webhook 对齐
CKB 配置	`GET/POST /api/v3/cunke-bao/config`	运维	base_url、api_key 脱敏

3.5 触客宝 IM（P0）

触客宝原接口	BFF	SDK	工作手机待办
`POST /v1/kefu/message/send`	`POST /v1/workphone/message/send`	`POST /api/v3/message/send`	channel=hook/adb；msg_type 全类型
`GET /v1/kefu/message/sync`	`POST /v1/workphone/messages/list`	`POST /api/v3/message/list`	write=1 回写由 BFF
好友/群列表	contacts / groups/list	同上	触客宝仍读 S2 → COORD
`POST /v1/kefu/moments/add`	`moments/post`	同上
`POST /v1/kefu/ai/chat`	`agent/execute`	`POST /api/v3/agent/execute`	AI 接待链路

协调：触客宝前端 VITE_USE_WORKPHONE_SDK；工作手机保证 message/send 真机 200 + channel_used 留痕。

3.6 流量池 / 标签（P1）

能力	BFF	SDK
标签同步	`GET /v1/workphone/tags/list`	`GET /api/v3/tag/list`
按标签取 wxid	`POST /v1/workphone/tags/users`	`POST /api/v3/tag/users`

3.7 AI / Agent / 中台大脑 / Hook（P0）

大脑真源：工作手机_设备Agent与基础设施_20260529 §4.5 — Skill 211 action · 平台 150 · 存客宝可经 BFF/proxy 控机。

3.7.1 存客宝 → 中台大脑（全接口）

#	能力	存客宝 BFF（现状）	SDK 路径	存客宝用法
1	Agent 自然语言	✅ `POST /v1/workphone/agent/execute`	`POST /api/v3/agent/execute`	工作台 AI：「给张三发微信」
2	Agent 状态/停止	✅ #49 #50	agent/status · stop	任务监控
3	微信发消息	✅ `POST /v1/workphone/message/send`	`message/send`	私域触达 P0 验收
4	微信收消息	✅ `POST /v1/workphone/messages/list`	`message/list`	同步聊天记录 P0 验收
5	发朋友圈	✅ `POST /v1/workphone/moments/post`	`moments/post`	工作台/触客宝 P0 验收
6	Skill 清单	⬜ BFF（proxy 透传）	`GET /api/v3/ai/brain/skill-registry`	PHP/TS SDK `getSkillRegistry()` 已封装；真机实测 211 action/150 平台 ✅
7	精确 action	⬜ BFF（proxy 透传）	`POST /api/v3/ai/brain/execute-script`	PHP/TS SDK `executeScript()` 已封装；抖音/小红书/闲鱼控机
8	批量 action	⬜ BFF（proxy 透传）	`POST /api/v3/ai/brain/batch-execute`	PHP/TS SDK `batchExecuteScript()` 已封装；多设备运营
9	自然语言（设备级）	⬜ proxy	`POST /api/v3/devices/{id}/ai/chat`	卡若AI 编排
10	AI 任务/常驻	⬜ proxy	ai/task · ai/standing-order	离线兜底
11	AI 状态	⬜ proxy	`GET /devices/{id}/ai/status`	超管监控
12	Hook 执行	✅ hook/execute	`POST /api/v3/hook/execute`	微信 128 action
13	万能透传	✅ `POST /v1/workphone/sdk/proxy`	328 全路由	中台大脑未注册 BFF 时必用

3.7.2 存客宝调用示例（可直接联调）

# ① 发微信（P0 验收 · 见微信需求 §13.1）
POST /v1/workphone/message/send
Authorization: Bearer {token}
{"device_id":"xgfe65eimrrofyws","platform":"wechat","to_id":"文件传输助手","content":"存客宝验收","msg_type":"text"}

# ② 收微信（P0 验收 · §13.2）
POST /v1/workphone/messages/list
{"device_id":"xgfe65eimrrofyws","platform":"wechat","conversation_id":"文件传输助手","limit":20}

# ③ 发朋友圈（P0 验收 · §13.3）
POST /v1/workphone/moments/post
{"device_id":"xgfe65eimrrofyws","platform":"wechat","content":"[存客宝验收朋友圈]"}

# ④ 中台精确控抖音（proxy 透传）
POST /v1/workphone/sdk/proxy
{"method":"POST","path":"/api/v3/ai/brain/execute-script","body":{
  "device_id":"xgfe65eimrrofyws","script":"douyin","action":"send_message",
  "params":{"to_id":"昵称","content":"你好"}
}}

# ⑤ Skill 能力树（前端展示）
POST /v1/workphone/sdk/proxy
{"method":"GET","path":"/api/v3/ai/brain/skill-registry"}

3.7.3 平台 Skill 与存客宝场景

script	action 数	存客宝典型场景	BFF 入口
wechat	98	私域群发/朋友圈/获客/解封	message/* moments/* friends/* + hook
douyin	18	抖音私信触达	proxy → execute-script
xhs	20	小红书私信/笔记互动	proxy → execute-script
xianyu	11	闲鱼买家沟通	proxy → execute-script
soul	3	Soul 私信	proxy → execute-script

四端 AI 入口（COORD，业务层只调 HTTP）：

端	业务入口	到中台路径	协调
触客宝	`POST /v1/kefu/ai/chat`	BFF agent/execute → SDK	COORD WP-001
存客宝	工作台 AI 助手	BFF `/v1/workphone/agent/*`	同上
AI数智员工	OpenPlatform + 终端	经存客宝 BFF → 中台 execute	COORD-004
SuperAdmin	设备监控	读 BFF 设备态 + 可选 ai/status	COORD-001

Frida 边界：Hook 模块在本仓库；四端不嵌入 Frida 脚本，只调 BFF。

三点八、四端分端接口全量清单（存客宝 · 触客宝 · AI数智员工 · SuperAdmin）

铁律：四端 只调 HTTP；工作手机不改兄弟仓库业务代码；缺口走 COORD 或 sdk/proxy 透传（328 路由已可用）。

3.8.1 存客宝 H5（:3100）

业务模块	存客宝原 URL（不变）	执行层 BFF	SDK	状态	注意
设备列表	`GET /v1/devices`	内部聚合 `workphone/devices`	`GET /devices`	🔧	MySQL + SDK 在线态合并
刷新设备	`PUT /v1/devices/refresh`	内部 getDevice+contacts	devices+contacts	🔧	≤30s
刷新好友	`PUT /v1/wechats/refresh`	`GET /workphone/contacts`	contacts	🔧	display_name 契约
发消息	工作台 Job	`POST /workphone/message/send`	message/send	✅	§微信13.1
收消息/sync	Job/内部	`POST /workphone/messages/list`	message/list	✅ 接口	§微信13.2 真机⬜
群发	计划执行	`POST /workphone/messages/batch-send`	batch-send	✅	interval 3–8s
加好友	场景获客	`POST /workphone/friends/batch-add`	batch-add	✅	风控 interval
发朋友圈	工作台	`POST /workphone/moments/post`	moments/post	✅	§微信13.3 真机⬜
朋友圈同步	wechats/moments	`POST /workphone/moments/list`	moments/list	✅	since_time
建群/欢迎	workbench	`POST /workphone/groups/*`	group/*	✅
标签流量	流量分发	`POST /workphone/tags/users`	tag/users	✅
新好友线索	Hook	SDK 出站	`cunke-bao/hook/friend-add`	✅	scenarios 签名
工作手机状态	我的/设备	`GET /workphone/status`	health+devices	✅
中台 Skill 树	工作台 AI	⬜ 建议 BFF	`GET /ai/brain/skill-registry`	proxy 可用	COORD-WP-002
精确控机	AI 助手	⬜ 建议 BFF	`POST /ai/brain/execute-script`	proxy 可用	抖音/小红书/闲鱼
自然语言控机	AI 助手	`POST /workphone/agent/execute`	agent/execute	✅	卡若AI 编排
AI 任务/常驻	运维	`POST /workphone/ai/task` 等 #44–47	devices/ai/*	✅ BFF
Hook 128 action	高级	`POST /workphone/hook/execute`	hook/execute	✅
未映射能力	兜底	`POST /workphone/sdk/proxy`	328 全路由	✅	必保留

存客宝扩展接口（文档登记 · 存客宝 Server COORD 实现）：

建议 BFF	用途	优先级
`GET /v1/workphone/ai/brain/skill-registry`	工作台展示能力树	P1
`POST /v1/workphone/ai/brain/execute-script`	多平台精确 action	P1
`POST /v1/workphone/devices/{id}/ai/chat`	自然语言→编排→执行	P0
`POST /v1/workphone/hook/events/push`	Hook 新消息→业务（增强收消息）	P2

3.8.2 触客宝 PC（:3101）

真源：cunkebao_v3/开发文档/5、接口/02-存客宝对接/触客宝PC接口对接索引.md
触客宝前端只调 /v1/kefu/*；设备写操作 经 BFF 转 workphone。

触客宝接口	方法	工作手机 BFF/SDK	迁移状态	注意
`POST /v1/kefu/message/send`	POST	`workphone/message/send`	🔧 待切	替代 WS CmdSendMessage；须 channel_used
`GET /v1/kefu/message/sync`	GET	`workphone/messages/list` + `write=1`	🔧 待切	收消息 P0；回写 s2_wechat_message
`GET /v1/kefu/message/list`	GET	读 MySQL（sync 后）	⏸ S2	逐步切 SDK 同步
`POST /v1/kefu/moments/add`	POST	`workphone/moments/post`	🔧	客服发朋友圈
`POST /v1/kefu/ai/chat`	POST	`workphone/agent/execute`	🔧	AI 接待→中台→手机
`GET /v1/kefu/wechatFriend/list`	GET	读库 + 可选 contacts 同步	⏸	contacts 增量
`GET /v1/kefu/wechatChatroom/list`	GET	`workphone/groups/list`	🔧
`GET /v1/kefu/device*`	GET	`workphone/status` + devices	🔧	设备/微信概览
AI 获客 webhook	POST	存客宝 chukebao（非 workphone）	✅	线索不进 SDK
算力/知识库	GET	存客宝业务 API	✅	不涉及控机

触客宝 env：USE_FOR_KEFU · VITE_USE_WORKPHONE_SDK=true（build）

触客宝收消息双通道（文档约定）：

通道 A（主）：kefu/message/sync → BFF messages/list → 真机拉取 → write=1 回库
通道 B（增强）：SDK Hook 新消息事件 → hook/events → BFF sync → 触客宝 WS 推送（P2 COORD）

3.8.3 AI数智员工（:3104）

真源：AI数智员工/开发文档/5、接口/12-AI数智员工全量能力与接口真源手册.md
不直连工作手机；经存客宝 /v1/* 或 /api/proxy / /api/ckb-open/*。

页面/能力	Service	存客宝路径	工作手机关系	缺口
设备状态	device-service	`GET /v1/devices`	读 MySQL 设备	—
工作手机态	getWorkPhoneStatus	`GET /v1/workphone/status`	SDK 聚合	✅
截图	takeScreenshot	`POST /v1/workphone/screenshot`	真机截图	✅
终端绑定	terminal-service	`POST /v1/open/terminal/register-imei`	device_id↔IMEI	COORD-004
终端校验	verify	`GET /v1/open/terminal/verify`	ck_device	存客宝侧
VIP 登录	store/login	`GET /v1/store/login?deviceId=`	须先登记 IMEI
场景获客	planService	`/v1/plan/*`	间接：计划触发 batch-add
工作台/群同步	workbenchService	`/v1/workbench/*`	间接：group/*
自动化开关	agent-switch-map	store system-config	⬜ 切 SDK 执行层	COORD
多平台控机	—	proxy → execute-script	douyin/xhs/xianyu	proxy 已可用

AI数智员工扩展（经存客宝 proxy，无需改 AI 仓）：

POST /api/proxy?path=/v1/workphone/sdk/proxy
Authorization: Bearer {jwt}
{"method":"POST","path":"/api/v3/ai/brain/execute-script","body":{
  "device_id":"xxx","script":"xhs","action":"send_message","params":{...}
}}

3.8.4 SuperAdmin 超管（:3103）

真源：SuperAdmin_超管后台重构_20260529.md · 只读/聚合，不直接控机写操作。

超管模块	API	工作手机	说明
仪表盘设备在线	superadmin API	间接：读 ck_device + workphone 在线态	COORD-001
项目管理·设备	设备唯一绑项目	`device_id` 与 SDK 注册 ID 一致
客户池	只读 RFM	不涉及 SDK 写	COORD-003 同口径
设备管理	CRUD MySQL	可选 `GET /workphone/devices/online`	监控

超管不需要：message/send、moments/post、hook/execute（写操作走存客宝/触客宝）。

超管建议只读 BFF：

BFF	用途
`GET /v1/workphone/status`	全平台 SDK 健康
`GET /v1/workphone/devices/online`	在线数对齐仪表盘
`GET /v1/workphone/ai/brain/dashboard`	AI Brain 统计（proxy）

3.8.5 跨端缺口汇总 · COORD 登记

COORD	缺口	提供方	需求方	P
WP-001	四端业务切 SDK 执行层	工作手机	存客宝/触客宝	P0
WP-002	BFF 封装 ai/brain/*（非仅 proxy）	存客宝 Server	存客宝/触客宝 UI	P1
004	device_id ↔ IMEI 扫码绑定	工作手机+存客宝	AI数智员工	P0
001	SuperAdmin 开放 API 聚合设备态	存客宝/超管	四端	P1
WP-003	Hook 新消息→触客宝/存客宝 push	工作手机 SDK	触客宝 sync	P2

当前无 BFF 但已可用：凡 sdk/proxy 可透传 /api/v3/* 全部 328 路由 — 文档须写清，避免重复开发。

三点九、GitHub / 社区参考与对接注意

3.9.1 GitHub 参考（私域 · Hook · 回调）

项目	链接	适用端	启示
Hook_WeChat_FaaS	FourTwooo/Hook_WeChat_FaaS	微信	版本锁定；hook 点维护
wechat_chatter	yincongcyincong/wechat_chatter	微信	NetScene/Protobuf 发消息
frida-mcp	1193776794/frida-mcp	通用	AI+Frida 辅助定位 hook
wechat-kf	yunfei01cs/wechat-kf	企微客服	回调 URL + 加密；触客宝收消息可参考
SpecFusion	wxkingstar/SpecFusion	多平台	抖音/小红书/企微 API 文档检索
WeCom ISV Callback	openwecom.com	企微	双 Token 回调；未来企微扩展

3.9.2 对接铁律（四端通用 · 写入验收）

#	铁律	违反后果
1	只调 HTTP；不改兄弟仓库	合并冲突/回归
2	设备写操作必须经 `/v1/workphone/*` 或 proxy	绕过风控/审计
3	`success:true` 须真机可见或 Hook 回执	禁止 mock 交付
4	`device_id` 全链路一致（ADB serial = WS 注册 ID）	发错机/离线误判
5	微信优先 Frida；抖音/小红书/闲鱼用 execute-script	通道混乱
6	收消息：list 须能查到人工发送的测试串	见微信 §13.2
7	发朋友圈：post 后 list 首条匹配 + 肉眼可见	见微信 §13.3
8	触客宝 sync `write=1` 回写后再读 list	仍读 S2 空表
9	AI数智员工不直连 :8899；经存客宝 JWT/proxy	安全/鉴权
10	超管只读设备态；写操作走存客宝/触客宝	权限边界
11	未注册 BFF → `sdk/proxy`，不新造重复接口	328 已覆盖
12	版本升级微信前跑 `wechat_interface_audit.py`	hook 漂移
13	先技术绑定 online，再业务 register-imei；device_id 全链路一致	见 §3.8.7

3.9.3 四端 × P0 验收矩阵（最终测试）

端	P0 必验能力	BFF 入口	真机标准
存客宝	发消息	`workphone/message/send`	§13.1 ✅
存客宝	收消息/sync	`workphone/messages/list`	§13.2 ⬜
存客宝	发朋友圈	`workphone/moments/post`	§13.3 ⬜
触客宝	客服发消息	`kefu/message/send`→BFF	同 §13.1
触客宝	客服收消息	`kefu/message/sync`→BFF	同 §13.2
触客宝	AI 接待控机	`kefu/ai/chat`→agent/execute	中台 E2E ⬜
AI数智员工	设备/workphone 状态	`workphone/status`	HTTP 200
SuperAdmin	在线设备数	聚合 API + workphone	与 SDK 一致

3.8.6 AI数智员工 · OpenPlatform 终端（补充）

能力	存客宝 Open API	与工作手机关系	协调
IMEI 登记	`POST /v1/open/terminal/register-imei`	device 须对应 SDK `device_id`	COORD-004 🟢
终端校验	`GET /v1/open/terminal/verify`	查 ck_device	存客宝侧
VIP 登录	`GET /v1/store/login?deviceId=`	扫码前须登记	AI数智员工只调 HTTP

工作手机待办：文档明确 device_id（ADB/WS ID）↔ IMEI（MD5） 映射流程；提供 register 联调样例；不改 AI数智员工仓库。

3.8.7 安装 · 扫码绑定 · 自动上线（四端全链路）

真源详解：设备Agent §3.5 · 本节写 四端各自扫什么、调什么。

两种绑定 × 四端分工

绑定类型	存客宝 H5	触客宝	AI数智员工	SuperAdmin	工作手机 SDK
技术绑定（连 SDK）	可生成/展示项目 QR（调用 SDK `/qrcode/*` 或内嵌）	一般不参与	一般不参与	可配置租户 `server` URL	✅ Agent 执行
业务绑定（设备入库）	扫码添加设备 · 工作台设备列表	读已绑设备	register-imei · VIP 登录	项目-设备唯一绑定	提供 online `device_id`

四端推荐流程（店员视角）

1. IT 在工作手机装 Agent/APK（Type-C 或 OTA）
2. 手机联网 → 自动 LAN 发现 SDK，或扫「项目绑定 QR」（server + project_id）
3. SDK GET /devices → online ✅  （技术绑定完成）
4. 店长在存客宝「扫码添加设备」→ register-imei  （业务绑定完成）
5. 触客宝/工作台/AI数智员工 发消息、同步、控机 → 全走 BFF /v1/workphone/*

各端接口（绑定相关）

端	场景	接口	前置条件
存客宝	扫码加设备	`POST /v1/open/terminal/register-imei`	SDK 已 online；device_id 一致
存客宝	查终端	`GET /v1/open/terminal/verify`	IMEI 已登记
存客宝	工作台看在线	`GET /v1/workphone/devices`	WS 心跳一致
触客宝	客服选设备	`GET /v1/kefu/device*` → workphone	设备已业务绑定
AI数智员工	终端绑定	同上 register-imei	COORD-004
AI数智员工	门店 VIP 登录	`GET /v1/store/login?deviceId=`	先 register-imei
SuperAdmin	项目设备数	读 ck_device + `workphone/devices/online`	device_id 唯一绑项目
工作手机	生成项目 QR	`POST /qrcode/generate`	project_id + server URL
工作手机	自动寻服	Agent UDP :8898	同网 SDK beacon

register-imei 联调样例（COORD-004）

POST /v1/open/terminal/register-imei
Authorization: Bearer {open_platform_token}
Content-Type: application/json

{
  "imei": "a1b2c3d4e5f6...",
  "device_id": "xgfe65eimrrofyws",
  "project_id": "cunkebao",
  "model": "Redmi Note 13",
  "remark": "门店1号机"
}

铁律 #13（绑定）：device_id 必须 = ADB serial = Agent WS 路径末段；须先技术绑定 online，再业务绑定；禁止仅 MySQL 有记录而 SDK 离线仍宣称「已绑定」。

绑定标识最佳实践（2026-05-29 检索验证 · Android 官方 + 零接触企业部署）：

IMEI 在 Android 10+ 受限（需 device/profile owner 或 READ_PRIVILEGED_PHONE_STATE），官方推荐避免裸 IMEI，改用 app 级稳定 ID（FID/GUID）或服务端账号绑定。
本 SDK 已用 device_id（ADB serial/WS ID）+ device_id_md5（probe 实测返回，如 ed25814d9c92b3430696dc96c2142b5f）作主键——比裸 IMEI 隐私更安全且稳定，COORD-004 应以 device_id/device_id_md5 为绑定主键，IMEI 仅作运营商场景副键。
流程对齐 MDM/零接触：技术绑定（enrollment 式 online）→ 业务绑定（register-imei），并设审批闸（身份核验/设备清点/归属确认）后才标 production-ready。
sdk/proxy 透传符合业界 BFF 网关标准（Bear1x/Passage/gateway）：转发 method/path/query/header/body、剥离敏感头、注入 X-Request-ID、转发 Authorization、可加 retry/熔断/health check。

局域网 vs 公网（四端实施注意）

部署	QR 中 `server` 建议	四端 BFF 指向
门店内网 Docker	`ws://192.168.x.x:8899/ws/device`	存客宝 BFF 同网或 VPN
腾讯云 SaaS	`ws://sdk.quwanzhi.com:8899/ws/device`	`ckbapi.quwanzhi.com` BFF
开发 Type-C	`adb reverse` + `ws://127.0.0.1:8899/ws/device`	本地 :3100 BFF

未完成（工作手机侧）：BIND-03 公网回退 · BIND-04 APK 扫码 UI — 见设备Agent §3.5.7。

3.8.8 设备连接方案 · 可切换（四端共用开关）

真源：设备Agent §3.6 连接方案可切换驱动层 · 代码 sdk/app/services/connection_provider.py
一句话：四端 不感知 底层用哪套工作手机；超管/运营一键切换 现有连接 / 机擎 / 奥创 / 自研，业务接口不变。

方案 id	名称	通道	四端调用方式（不变）
`jiqing`（默认）	机擎工作手机（本SDK）	WS Agent + Frida	`/v1/workphone/*` → SDK 原生
`aochuang`	奥创工作手机（007私域）	007 HTTP	同上（SDK 内部转奥创 API）
`legacy`	现有连接形式（S2/旧接口）	自建 HTTP	同上
`custom_*`	预留自研方案	任意 HTTP	同上（`register` 配置接入）

四端切换入口（经 BFF proxy，不改四端业务）：

# 超管/运营切换全局连接方案
POST /v1/workphone/sdk/proxy
{"method":"POST","path":"/api/v3/connection/provider/switch","body":{"provider":"aochuang","scope":"global"}}

# 查看当前生效方案（四端状态页可展示）
POST /v1/workphone/sdk/proxy
{"method":"GET","path":"/api/v3/connection/providers"}

端	与连接方案切换的关系
存客宝 H5	工作台/设备页可加「连接方案」选择；切换后发消息/加好友/朋友圈走所选方案
触客宝	客服收发消息底层方案随开关变，接口 `/v1/kefu/*` 不变
AI数智员工	终端绑定与控机经存客宝 BFF，方案切换对其透明
SuperAdmin	建议作为切换主控台：项目/设备级开关 + 各方案在线态聚合

COORD 登记：

COORD	缺口	提供方	需求方	P
WP-004	超管/存客宝「连接方案切换」UI（调 `/connection/provider/switch`）	各端前端	运营	P1
WP-005	奥创/legacy base_url+token 凭证（启用 CONN-08 真机连通）	客户/存客宝	工作手机 SDK	P1

3.10 不涉及 SDK 的模块（仅 MySQL · 无工作手机开发）

内容库、分销、数据中心、用户资料、云端 AI/Coze、门店业务、超管 CRUD — 见存客宝映射表 §九。

四、存客宝 BFF ↔ SDK 52 路由对照（摘要）

全量参数见 cunkebao_v3/.../05-BFF全量接口手册.md · 本仓库 5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md

分类	BFF 条数	SDK 覆盖	透传兜底
总览/连接/Hook	8	✅	—
消息	4	✅	proxy
好友/通讯录	8	✅
群聊	10	✅
标签	6	✅
朋友圈	5	✅
设备/UI	6	✅
AI/Agent	7	✅
sdk/proxy	1	328 全路由	`POST /v1/workphone/sdk/proxy`

工作手机原则：BFF 已映射的 52 条，SDK 禁止返回与 OpenAPI 不一致的字段；未映射能力走 proxy，但须在 工作手机API全量接口目录 登记。

五、跨项目协调（本需求登记 · 不改对方代码）

真源：/Users/karuo/Documents/开发/_共享/跨项目协调/索引.md

COORD	简述	工作手机角色	提供方/需求方	阻塞范围
WP-001（建议登记）	工作台/触客宝切 SDK 执行层	提供方（SDK 稳定+真机）	需求方：存客宝/触客宝	业务 Job 不可验收
004	AI 数智员工扫码绑定	提供方（设备在线+ID 一致）	存客宝 OpenPlatform	扫码登录
001	SuperAdmin 开放 API	间接：设备 API 被聚合	存客宝 Server	各端读设备
003	RFM 同口径	无 SDK 职责	Server	—

5.1 各端协调清单（工作手机只出接口/文档）

端	对方需做（COORD，非本仓库）	工作手机已提供
存客宝	`USE_FOR_WORKBENCH`；RefreshDevice 调 BFF；Bridge 类切 SDK	52 BFF 对应 SDK + cunke-bao
触客宝	kefu send/sync 改调 BFF；build 开 `VITE_USE_WORKPHONE_SDK`	message/* group/* agent/*
SuperAdmin	设备 API 读 ck_device + BFF 在线态	GET /devices health
AI数智员工	仅 HTTP 调 OpenPlatform；不改 Store 业务	设备登记流程文档

六、工作手机自身开发清单（按优先级）

Phase 0 · 阻塞真机（P0）

#	任务	SDK/模块	验收
1	Frida probe 稳定 attach	`hook/probe`	BFF probe 200 + frida_ready=true
2	message/send 真机 E2E	`message/send`	真机收到微信；channel_used=hook
3	friend-add Hook → cunke-bao	`cunke-bao/hook/friend-add`	存客宝 traffic_pool 有记录
4	设备 WS 长连 + 心跳	Agent + `heartbeat`	GET /devices 在线=真机
5	batch-send / batch-add 真机	同上	间隔风控不封号（测试号）

Phase 1 · 四端主链路（P0）

#	任务	验收
6	contacts + moments/list 增量	存客宝刷新好友/朋友圈 Job 联调
7	group/* 全套	工作台建群/欢迎/@
8	tag/users	流量分发 Job
9	agent/execute + ai/task	触客宝 AI 接待
10	OpenAPI 与 328 路由 diff 清零	自动生成目录脚本 CI

Phase 2 · 增强（P1/P2）

#	任务
11	多 platform（douyin/xhs/soul）与存客宝 platform 字段
12	gateway/mcp 对外 OpenAI 兼容（第三方）
13	解封/账号安全 API（见微信全量控机与私域 §八）

七、验收标准

7.1 SDK 软件层

# 工作手机侧
bash 开发文档/8、部署/05-测试验收/scripts/workphone_bff_smoke.sh

# 存客宝侧（对称）
bash cunkebao_v3/Server/scripts/workphone_bff_acceptance.sh
# 期望 PASS=17 FAIL=0

7.2 真机 E2E（强制）

bash 开发文档/8、部署/05-测试验收/scripts/real_device_gate.sh
bash cunkebao_v3/Server/scripts/workphone_e2e_real_device.sh {device_id}

项	标准
发消息	真机微信可见；非 mock
新好友 Hook	cunke-bao 回调 200
设备离线	SDK 503；BFF 仍 200 透传 sdk_code
Frida 不可用	probe 明确 false；禁止 silent success

7.3 文档同步

本 MD 与 06-业务接口一对一映射总表 状态列一致
存客宝BFF与工作手机SDK映射表.md 版本 bump
OpenAPI openapi_v3.0.json 变更记录

八、代码索引（本仓库）

模块	路径
SDK 入口	`sdk/app/main.py`
存客宝路由	`sdk/app/routers/cunke_bao.py`
微信 Facade	`sdk/app/routers/` 各 platform
PHP SDK	`sdk/php-sdk/WorkPhoneClient.php`
TS SDK	`sdk/typescript-sdk/`
Agent	`sdk/agent/`
Hook	`sdk/hook/`
验收脚本	`开发文档/8、部署/05-测试验收/scripts/`

存客宝侧（只读引用）：

模块	路径
BFF 路由	`cunkebao_v3/Server/application/cunkebao/config/route.php`
Gateway	`.../controller/workphone/WorkPhoneGatewayController.php`
SDK 客户端	`.../common/util/WorkPhoneSDK.php`
前端 BFF	`Cunkebao/src/pages/mobile/mine/workphone/api.ts`

八点五、中间层 SDK（P0 · 机擎阿桥）

合并自 机擎/references/工作手机中间层抽象.md

模块	unified 路径	PHP/TS SDK 方法	状态
消息	message/send, list, batch-send	sendMessage, getMessages, batchSendMessage	✅
好友/通讯录	friend/*, GET contacts	addFriend, batchAddFriend, getContacts	✅
群聊	group/*	createGroup, sendGroupMessage, …	✅
标签	tag/*	getTags, getUsersByTag	✅
朋友圈	moments/*	postMoments, getMoments	✅
设备	devices, screenshot	getDevices, screenshot	✅
Agent	agent/execute	executeTask	✅
快捷	platform 封装	wechatSend, douyinSend, soulSend…	✅
中台大脑	ai/brain/skill-registry · execute-script · batch-execute	getSkillRegistry, executeScript, batchExecuteScript	✅（2026-05-29 PHP+TS 双端补全）

纪律：契约以 sdk/app/routers/unified.py 为真源；unified 变更 → 两 SDK 同步（阿桥）。

2026-05-29 中间层对齐核对：PHP WorkPhoneClient.php 与 TS index.ts 双端方法一致——sendMessage/batchSendMessage/getContacts/postMoments/executeTask/getAIBrainStatus/pushAITask/pushAIStandingOrder/executeAITask + 5 平台快捷（wechat/douyin/xhs/xianyu/soul）+ 新增 getSkillRegistry/executeScript/batchExecuteScript（§3.7 #6/#7/#8 多平台精确控机，字段与 OpenAPI 一致：execute-script {device_id,script,action,params}、batch-execute {device_ids,script,action,params}）。

八点六、多平台扩展（P1/P2）

合并自 02-业务/业务需求.md §六

APP	包名	私信/控制	抓包	工时
微信	com.tencent.mm	✅ P0	✅	—
抖音	com.ss.android.ugc.aweme	✅ P0	✅	—
小红书	com.xingin.xhs	✅ P0	✅	—
Soul	cn.soulapp.android	扩展	—	2d
闲鱼	com.taobao.idlefish	扩展	—	3d

US-003：新 APP 仅写 Python Skill 脚本，2 天内对接，不改 SDK 核心。

八点七、机擎对接管理（阿桥/阿表）

需求	说明
存客宝↔SDK 映射表维护	`5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md`
对称更新 cunkebao `06-一对一映射总表`	状态列与本文一致
Pipeline 对接阶段	阿机开发 → 阿桥中间层+文档 → 阿端 E2E → 阿表验收
接力文档	`机擎/references/开发接力文档.md`
对话沉淀	新对接需求追加到三篇需求 MD 之一，不再分散小文件

九、进度

维度	比例	说明
SDK 路由实现	99%	328 路由
BFF 对称（存客宝）	100%	52+proxy
接口文档（四端开放）	100%	四端开放接口汇总
一键安装文档	100%	Type-C指南
真机 E2E P0	85%	29/29 安全组 · send Frida ✅
四端业务切 SDK	0%	COORD · 不改四端代码
线索 friend-add E2E	0%	Hook 事件待验
解封 A→E	0%	见微信需求 MD

十、四端开放接口真源（汇总 · 勿另维护专文）

铁律：存客宝/触客宝/AI/SuperAdmin 只调 HTTP；工作手机不改兄弟仓库。

10.1 存客宝私域最小闭环（接口已就绪）

RefreshDevice / 工作台
  → BFF GET /v1/workphone/contacts  → SDK GET /api/v3/contacts（含 display_name）
  → MySQL ck_wechat_friend diff

群发 Job
  → BFF POST /v1/workphone/messages/batch-send
  → SDK POST /api/v3/message/batch-send（interval 风控）

场景获客
  → BFF POST /v1/workphone/friends/batch-add
  → SDK friend/batch-add

新好友进池
  → SDK POST /api/v3/cunke-bao/hook/friend-add → 存客宝 scenarios（签名）

触客宝 AI 接待
  → BFF POST /v1/workphone/agent/execute
  → SDK POST /api/v3/agent/execute → 中台 AI → WS execute

10.2 工作手机侧待完成（不影响 BFF 契约）

#	项	优先级
W1	friend-add 真机触发 → scenarios 200 留痕	P0
W2	解封 unblock_via_customer_service 全链路	P0
W3	`--full` 写操作 128 action 真机组	P1
W4	抖音/小红书 Skill 真机 E2E	P1

十一、真机 E2E 验证结果（2026-05-29 · 工作手机侧 · 不 mock）

证据目录：开发文档/8、部署/05-测试验收/20260529_四端对接E2E/（含各端点 JSON + 截图 + _summary.json） · 验证脚本：开发文档/8、部署/05-测试验收/scripts/workphone_4end_e2e.sh
设备：xgfe65eimrrofyws（Agent WS 在线，agent_version 3.1.0；微信 8.0.69 已登录账号「游条姐」wxid_5g37snchpv8e22）
16:48 上线动作（本机一键复现）：① 设备端 root 起反检测 fs_301450 -l 0.0.0.0:33891（frida 16.5.6，与本机匹配）→ ② adb forward tcp:33891 → ③ 本机 python3 sdk/agent/agent.py（u2+remote frida+连 WS）→ devices_online:1、supports_hook:true。

11.1 验证结论（2026-05-29 16:50 真机实测 · PASS=11 BLOCKED=1 FAIL=0）

能力	路径	结果	真机证据
健康/设备在线	`GET /health` `GET /api/v3/devices`	✅ PASS	`devices_online:1`，agent 3.1.0，心跳/指纹完整
Skill 能力树	`GET /api/v3/ai/brain/skill-registry`	✅ PASS	data=211 节点（actions/平台/skills/模块，与 §3.7 一致）
Frida 探测	`GET /api/v3/hook/probe/{id}`	✅ PASS	`supports_hook:true`，微信 8.0.69，profile 真实（昵称/wxid），ping=「pong from wechat_hook_v3.0 — 96 actions / 26 modules」
发消息	`POST /api/v3/message/send`	✅ PASS	filehelper 发送 success，`message_id:msg_1780044632959_897834`，`channel_used:websocket/frida`（CK-D5）
收消息	`POST /api/v3/message/list`	✅ PASS	全量查询返回真实消息（id=861，群 `48384276354@chatroom` 真实内容）；filehelper 单会话空（刚发未落 `message` 表，见 §11.4）（CK-T7）
群列表	`GET /api/v3/group/list`	✅ PASS	data=20 真实群：`卡若的兄弟们`/`冰域阿袜金团群`/`BL-卡若私域%1.0` 等（CK-T3）
标签列表	`GET /api/v3/tag/list`	✅ PASS	data=323 真实标签：`手游黑科技`/`客户`/`复购`/`已购` 等
AI 状态	`GET /devices/{id}/ai/status`	✅ PASS	`ai_brain_enabled:true`
CKB 配置	`GET /api/v3/cunke-bao/config`	✅ PASS	base_url=ckbapi scenarios，`enabled:false`、`api_key_set:false`（待 U2）
通讯录	`GET /api/v3/contacts`	✅ PASS（真实 500+）	2026-05-29 17:40 根治：`count:500`（limit 命中，rcontact 共 6130 行）、350 个带标签；真实好友 wxid_s3z9kr3bfjy022 等 type=3。根因=`_cols` 选了 8.0.69 不存在的列（`signature/sex/country/...`）致整 SELECT 返 0，已改动态列探测（见 §11.4）
朋友圈	`POST /api/v3/moments/list`	✅ PASS（空）	http200 hook 通；`count:0`（SNS 时间线未加载/需 UI 导航）
新好友入站	`POST /cunke-bao/hook/friend-add`	⚠️ BLOCKED	schema 通过，`code:-1 服务未启用`（CKB `enabled:false`，需 U2 存客宝 api_key）

核心结论：Frida hook 通道真机打通——发消息成功（frida message_id）、群/标签/全量消息返回真实业务数据、probe supports_hook:true（96 actions）。SDK 339 paths/348 ops 代码侧 100% 健康，无 mock（符合铁律 #3/#14）。仅 friend-add 1 项受阻于 U2 外部凭证（存客宝 CKB api_key），非 SDK 代码缺陷。

11.2 解除阻塞清单（Unblock）

#	阻塞	状态	影响能力	解除动作
U1	Frida 未 attach	✅ 已解除（16:48）	send/list/group/tag/contacts/moments	设备端 `fs_301450 -l 0.0.0.0:33891` + `adb forward` + 本机 `agent.py`；`hook/probe` 已 `supports_hook:true`
U2	CKB 未启用	⚠️ 待存客宝凭证	friend-add → scenarios	SDK 环境配 CKB `api_key` 并 `enabled:true`（ckbapi.quwanzhi.com 提供，外部凭证）
U3	LLM key 缺	⚠️ 待凭证	agent/execute 自然语言	SDK 环境配 `DEEPSEEK_API_KEY`
U4	ADB input 受限	⚠️ 设备设置	u2 UI 点击/截图	MIUI 开发者选项开「USB 调试(安全设置)/模拟点击」；Frida 无头通道不受影响

11.4 真机读路径发现（CK-T7 收消息 / 通讯录空 · 根因定位）

实测：group_list(20)/tag_list(323)/message_list 全量(真实) 均返回真实数据 → EnMicroMsg.db 句柄 + SQLCipher 密钥 + _execSQL 全部正常。

现象	根因（已定位）	后续
`message/list` 指定 `filehelper` 空，但全量查询有真实数据	hook `getMessages` 查 `message WHERE talker='filehelper'`；frida `sendMessage` 走 RPC 未即时落 `message` 表（异步/独立存储）	CK-T7 收消息能力成立（全量已验真）；filehelper 即时回读为已知限制
~~`contacts` `count:0`~~ ✅ 已根治（2026-05-29 17:40）	真根因：`diag_wcdb`/`get_contacts._diag` 实测 `rcontact_total=6130`（type=3 友 4991、type=4 831），但 strict/relax/noverify 三查询全 0；而 `count()`/`GROUP BY` 正常 → 差异在 `_cols` SELECT 了 8.0.69 rcontact 不存在的列（`signature/sex/country/province/city/imgFlag`）→ 整查询失败返 0。修复：`PRAGMA table_info(rcontact)` 动态探测实际列（8.0.69 实有 `username/alias/conRemark/nickname/type/verifyFlag/contactLabelIds/...`），只 SELECT 存在列；标签列 `labelidlist→contactLabelIds`。实测 count:500（limit 命中）、350 带标签*，证据 `8、部署/05-测试验收/20260529_四端对接E2E/20_contacts_fixed.json`	✅ 完成（动态列探测，对所有 8.0.x 版本健壮）
`moments` `count:0`（SNS DB 读不到）	`get_moments._diag`：`SnsInfo avail_cols=[]`、`snsinfo_total=null` → `_execSnsSQL` 完全读不到 SnsMicroMsg.db（与 contacts 缺列不同；属 SNS WCDB 句柄/解密未命中）；已对 moments 同加动态列探测+诊断，但 SNS 库本身未通	需排查 `_execSnsSQL`/SNS WCDB 句柄解析（CK-T9 余项，P1）
`moments` `count:0`	`get_moments` 需 SNS 时间线已加载（UI 导航后再读）	需 UI 进入朋友圈页触发加载（U4 解除后，P1）

11.2.1 U1 Frida attach 排查清单（2026-05-29 检索 · 设备侧执行）

来源：frida/frida Issues #3687/#3709/#3711 · Discussion #2411 · GitHub wechat_chatter（Frida hook tencent/mars 发消息）

步	动作	要点（踩坑）
1	版本严格匹配	控制端 frida 工具版本 == 手机 `frida-server` 版本（首要原因，绝大多数 attach 失败因版本不符）
2	用 17.8.2+	17.6–17.8.0 在 Android 11/17 段错误/Aborted；升 ≥17.8.2
3	正确部署	`/data/local/tmp` 解压（非 copy/move，否则 `Not executable: Magic FD37`）→ `chmod +x` → `su` → `./frida-server -l 127.0.0.1`
4	spawn 优先	微信用 `-f com.tencent.mm --no-pause`：hook 须早于微信 root/完整性检测；attach 模式会漏 startup hook（"脚本跑了无输出"）
5	反检测	微信检测到 Frida 会 `process terminated`；重命名 frida-server 二进制 + 反检测脚本
6	SDK 验证	Agent 默认连 `127.0.0.1` frida-server（见 probe_detail）；启好后跑 `GET /api/v3/hook/probe/{id}` 应 `supports_hook:true`

11.3 验收复跑（解除阻塞后一键）

# 只读探测（任何时候可跑，标 BLOCKED 的会随阻塞解除转 PASS）
bash 开发文档/8、部署/05-测试验收/scripts/workphone_4end_e2e.sh
# 写操作 P0（U1 解除 + 测试号 后）
WP_WRITE=1 bash 开发文档/8、部署/05-测试验收/scripts/workphone_4end_e2e.sh

十二、已完成 / 未完成（工作手机侧）

✅ 已完成

ID	项
CK-D1	328 SDK 路由 + OpenAPI
CK-D2	52 BFF 对称（存客宝）
CK-D3	cunke-bao/* 线索/批量/配置路由
CK-D4	PHP/TS WorkPhoneClient
CK-D5	message/send 真机 Frida
CK-D6	安全组 29 action E2E
CK-D7	四端开放接口文档（归档→本文§十）

✅ 已完成（2026-05-29 真机补验）

ID	项	真机证据
CK-T3	group/list 工作台 E2E	✅ data=20 真实群
CK-T7	收消息 list 真机	✅ 全量查询真实消息（id=861），hook 通道验真
CK-D5	message/send 真机	✅ filehelper success，message_id，channel=frida

⬜ 未完成

ID	项	P	阻塞
CK-T1	friend-add → scenarios 200	P0	U2 CKB api_key（外部凭证）
CK-T2	batch-send/batch-add 真机	P0	风控参数已定 §3.3.1；待批量真机跑
CK-T4	agent/execute 触客宝链路	P0	U3 DEEPSEEK_API_KEY
CK-T5	COORD 四端切 USE_FOR_*	P0	兄弟仓（COORD）
CK-T6	抖音/小红书/闲鱼 execute-script 真机	P1	需对应 APP 登录态
CK-T8	朋友圈 post 真机	P0	避免污染真实账号时间线（须测试号 `WP_WRITE_MOMENTS=1`）
🟡 CK-T9	contacts/moments 读真实数据	P1	contacts ✅ 已根治（动态列探测，500+ 真实/350 带标签）；moments 仍空（`_execSnsSQL` 读不到 SnsMicroMsg.db，待排查 SNS WCDB 句柄）
CK-T10	COORD-WP-002 BFF ai/brain 封装	P1	§3.8.5（BFF 侧）
CK-T11	COORD-WP-003 Hook 消息 push	P2	§3.9.2 #6
✅ CK-T12	~~u2 通道 intent 动作诚实化~~ 已完成（2026-05-29 17:25 真机验证）：根因在 SDK 服务端 `unified.py::hook_execute` 无条件返 `code:200`，把 agent 内层 503/`success:False` 伪装成功；已修为诚实传播内层 code/success。真机复测 `generate_my_qr`(无接收端) `code:200→503`、`get_profile`(真RPC) 仍 `code:200 success:true`（游条姐/wxid 真实）	P1	✅ 已完成
CK-T13	70+ intent 动作逐个「真实现」为 Frida RPC（资料/红包/转账等，按用户「同模式补」节奏，红包/转账须测试号）	P1	用户 17:13 方向

十三、变更记录

日期	变更
2026-05-29	初版：四端全量映射、COORD、Phase 0–2
2026-05-29	并入中间层/多平台/机擎；三篇需求拆分
2026-05-29	§3.8–§3.9 四端分端接口/GitHub/验收矩阵 + COORD-WP-002/003
2026-05-29	§3.8.7 扫码绑定·自动上线全链路 + 铁律 #13
2026-05-29	§十一真机 E2E 验证结果 + 解除阻塞清单 U1-U4；OpenAPI↔snapshot diff 清零（339 paths/348 ops）；新增 `workphone_4end_e2e.sh`；`export_api_catalog.py` 实时回退+根目录健壮化
2026-05-29	§11.2.1 U1 Frida attach 排查清单（检索 frida Issues+wechat_chatter）；中间层 PHP/TS SDK 补 `getSkillRegistry/executeScript/batchExecuteScript`（§3.7 #6/#7/#8）；双端方法对齐核对
2026-05-29	§3.8.7 绑定标识最佳实践（IMEI 受限→device_id_md5 主键 + BFF 网关对齐）；§3.3.1 风控参数表（CK-T2 真源：加好友/群发/建群阈值 + 反风控编码要点）
2026-05-29	代码侧复验（无真机）：`wechat_interface_audit` 缺失 RPC=0（131 export/129 action/175 catalog）；`skill_registry_audit` 设备缺失=0（150 action）；离线回归 `pytest` 17/17（修复 `test_wechat_acceptance_offline` 中 `skills.wechat.skill_v2` 被根目录命名空间抢占的导入）；`export_api_catalog.py` 重生成 routes_snapshot=348 / openapi paths=339（diff 清零保持）。剩余 P0 全部为真机 E2E，受阻于 U1–U4 环境前置（Frida/CKB key/LLM key/ADB），非代码缺陷
2026-05-29 16:50	真机 E2E 打通：本机起 `fs_301450@33891`+`agent.py` → `devices_online:1`、`supports_hook:true`（微信8.0.69，96 actions）；send/group(20)/tag(323)/message全量真实数据 PASS=11；§11.1 重写真实结果、§11.4 读路径根因、§十二 CK-T3/T7/D5 标真机完成；e2e 脚本分类器重写（JSON 精确判 PASS/BLOCKED，朋友圈拆 `WP_WRITE_MOMENTS`）；TS `tsc` exit0 + PHP `-l` 通过 + OpenAPI↔snapshot diff=0 复核
2026-05-29 17:10	守护稳定化：`wechat_hook_v2.js` 加 contacts 防御式回退（8.0.69 兼容）；`ai_brain.py` 加 429 限流 120s 冷却（修复启动后 AI 规划 API 突发重试刷屏 462→1，不影响 hook/连接守护）；重启 Agent 守护稳定运行 `online=1`、`supports_hook:true`
2026-05-29	§3.8.8 设备连接方案 · 可切换（四端共用开关）：四端经 `/v1/workphone/sdk/proxy` → `/api/v3/connection/provider/switch` 一键切 jiqing/aochuang/legacy/custom_*；新增 COORD WP-004（切换 UI）/ WP-005（奥创·legacy 凭证）；真源见设备Agent §3.6，代码 `sdk/app/services/connection_provider.py`，离线回归 9/9 ✅
2026-05-29 17:15	`_intentAction` 诚实化（真机铁律 #3/#14 合规）：原 70+ intent 类动作（资料/红包/转账/视频号/收藏/通话等）`sendBroadcast` 后无论有无接收端均返 `success:true`=假成功；改为先 `queryBroadcastReceivers` 校验，无接收端返 `success:false, verified:false, no_receiver_registered`（不再假成功）。`node --check` 通过、重启 Agent 加载 `supports_hook:true`。新发现：agent 调度层对部分 intent 动作走 `websocket/u2` 通道返通用 ack（第二处潜在假成功，待 u2 通道同样诚实化，记 CK-T12）
2026-05-29 17:40	CK-T9 contacts 根治·8.0.69 缺列致读空（真机验证）：`get_contacts._diag` 实测 `rcontact_total=6130` 但三级查询全 0；根因=`_cols` 选了 8.0.69 不存在列（`signature/sex/country/province/city/imgFlag`）致 SELECT 整体失败。改 `PRAGMA table_info` 动态列探测（只选实有列）+ 标签列 `labelidlist→contactLabelIds`；真机 `count:500`（limit 命中 6130 行）、350 带标签，证据 `20_contacts_fixed.json`。moments 同加动态列探测，但 `_execSnsSQL` 读不到 SnsMicroMsg.db（avail_cols=[]）→ SNS WCDB 句柄待排查（CK-T9 余项）。§11.1/§11.4/CK-T9 已更
2026-05-30 12:54	四端可直调·模块化接口能力清单（自动生成）：新增 `sdk/scripts/gen_integration_manifest.py`，实时拉 `skill-registry`（9平台/49模块/211动作）生成 `5、接口/01-规范与统一层/四端可直调接口能力清单.md`，按平台×模块×动作组织 + 四端入口矩阵 + 连接方案切换；5、接口 README 已挂链。真机只读复验：group=20 / tag=323 / contacts=50（limit）live PASS，`supports_hook:true`（微信8.0.69，96 actions）。设备 USB 已授权在线（WS=1/ADB=1）
2026-05-29 17:25	CK-T12 完成·SDK 端假成功根治（铁律 #3/#14）：定位根因=`sdk/app/routers/unified.py::hook_execute` 末尾硬编码 `code:200`，即使 agent 内层返 `code:503`/`success:False`（如 `no_receiver_registered`/Frida 主控不可用）也被伪装成 200；改为诚实传播 `inner_code`，并对 `success:False` 兜底标 503。`py_compile` 通过；真机复测：`generate_my_qr`(hook_only,无接收端) `code:200→503`、`get_profile`(真 Frida RPC) 仍 `code:200 success:true`（游条姐/wxid_5g37snchpv8e22/8.0.69）。发现：8899 由 Docker 容器 `workphone-sdk`（卷挂载 `sdk/app→/app`）提供，host uvicorn 为 stale；改后 `docker restart workphone-sdk` 生效

关联文档

存客宝BFF与工作手机SDK映射表.md
工作手机API全量接口目录.md
业务需求.md
真机开发铁律.md
存客宝：cunkebao_v3/开发文档/5、接口/02-存客宝与工作手机对接/README.md

58 KiB Raw Blame History Unescape Escape