From 9c3032082680e433bd67d2abc05fbec6613396e8 Mon Sep 17 00:00:00 2001 From: Manus AI Date: Sat, 30 May 2026 12:55:58 +0800 Subject: [PATCH] =?UTF-8?q?feat(=E6=8E=A5=E5=8F=A3):=20=E5=9B=9B=E7=AB=AF?= =?UTF-8?q?=E5=8F=AF=E7=9B=B4=E8=B0=83=C2=B7=E6=A8=A1=E5=9D=97=E5=8C=96?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E8=83=BD=E5=8A=9B=E6=B8=85=E5=8D=95(?= =?UTF-8?q?=E8=87=AA=E5=8A=A8=E7=94=9F=E6=88=90)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 实时拉 skill-registry(9平台/49模块/211动作)生成清单，按平台×模块×动作组织+四端入口矩阵+连接方案切换；真机只读复验 group20/tag323/contacts50。 Co-authored-by: Cursor --- sdk/scripts/gen_integration_manifest.py | 171 ++++ .../修改/工作手机_存客宝四端对接_20260529.md | 903 ++++++++++++++++++ .../01-规范与统一层/四端可直调接口能力清单.md | 183 ++++ 开发文档/5、接口/README.md | 2 +- 4 files changed, 1258 insertions(+), 1 deletion(-) create mode 100644 sdk/scripts/gen_integration_manifest.py create mode 100644 开发文档/1、需求/修改/工作手机_存客宝四端对接_20260529.md create mode 100644 开发文档/5、接口/01-规范与统一层/四端可直调接口能力清单.md diff --git a/sdk/scripts/gen_integration_manifest.py b/sdk/scripts/gen_integration_manifest.py new file mode 100644 index 0000000000..b0bd3ea590 --- /dev/null +++ b/sdk/scripts/gen_integration_manifest.py @@ -0,0 +1,171 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +四端可直调·模块化接口能力清单 生成器 + +从运行中的 SDK 实时拉取 skill-registry（211 动作 / 49 模块 / 9 平台）， +生成模块化、可直读的接口能力清单 Markdown，供存客宝 / 触客宝 / AI数智员工 / +SuperAdmin 直接对接判断「哪些能力可直调、走什么通道、经哪个 BFF/SDK 路径」。 + +- 不改任何兄弟仓库代码；只输出工作手机侧文档。 +- 真源：GET /api/v3/ai/brain/skill-registry（live）。 +- 用法：python3 sdk/scripts/gen_integration_manifest.py [--base http://127.0.0.1:8899] + +输出：开发文档/5、接口/01-规范与统一层/四端可直调接口能力清单.md +""" +from __future__ import annotations + +import argparse +import datetime +import json +import os +import sys +import urllib.request + +ROOT = os.path.normpath(os.path.join(os.path.dirname(__file__), "..", "..")) +OUT = os.path.join(ROOT, "开发文档", "5、接口", "01-规范与统一层", "四端可直调接口能力清单.md") + +# 平台 → 默认执行通道 + 四端推荐入口（不改对方代码，全部 HTTP） +PLATFORM_CHANNEL = { + "wechat": ("Frida Hook（主） / u2（兜底）", "/api/v3/message/* friend/* group/* tag/* moments/* + hook/execute"), + "douyin": ("execute-script（AI Brain）", "/api/v3/ai/brain/execute-script (script=douyin)"), + "xhs": ("execute-script（AI Brain）", "/api/v3/ai/brain/execute-script (script=xhs)"), + "xianyu": ("execute-script（AI Brain）", "/api/v3/ai/brain/execute-script (script=xianyu)"), + "soul": ("execute-script（AI Brain）", "/api/v3/ai/brain/execute-script (script=soul)"), + "system": ("Agent 系统能力", "/api/v3/devices/{id}/* "), + "hook": ("Hook 统一执行", "/api/v3/hook/execute"), + "ai_brain":("AI 中台编排", "/api/v3/ai/brain/* · /api/v3/devices/{id}/ai/*"), + "anti_ban":("防封守护", "/api/v3/anti-ban/*"), +} + +# 四端可直调矩阵（来自需求 §3.8 真源；纯文档约定，不改对方代码） +FOUR_END = [ + ("存客宝 H5 (:3100)", "经存客宝 BFF /v1/workphone/* 或联调直连 :8899", "发消息/群发/加好友/朋友圈/标签/线索/状态/中台 Skill"), + ("触客宝 (:3101)", "必经存客宝 BFF（同域 JWT）", "message/send · messages/list · moments/post · agent/execute"), + ("AI数智员工 (:3104)", "经存客宝 OpenPlatform / proxy（不直连 :8899）", "设备状态/截图/终端绑定 + proxy→execute-script 多平台控机"), + ("SuperAdmin (:3103)", "只读聚合 + 连接方案切换主控台", "GET /devices · status · connection/provider/switch"), +] + + +def fetch_registry(base: str) -> dict: + url = base.rstrip("/") + "/api/v3/ai/brain/skill-registry" + try: + with urllib.request.urlopen(url, timeout=10) as r: + return json.loads(r.read().decode()) + except Exception as e: # 离线回退到缓存 + cache = os.path.join(ROOT, "sdk", "tmp", "manifest_20260530", "skill_registry.json") + if os.path.exists(cache): + sys.stderr.write(f"[warn] live 拉取失败({e})，用缓存 {cache}\n") + return json.load(open(cache, encoding="utf-8")) + raise + + +def render(reg: dict, base: str) -> str: + data = reg["data"] + summary = data.get("summary", {}) + skills = data.get("skills", {}) + now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M") + + L = [] + L.append("---") + L.append("tags: [工作手机, 接口, 四端对接, 能力清单, 自动生成]") + L.append("doc-type: 索引") + L.append("layer: 5、接口/01-规范与统一层") + L.append('parent: "[[5、接口/README|5、接口]]"') + L.append("obsidian-color: \"#0277BD\"") + L.append("---\n") + L.append("# 四端可直调 · 模块化接口能力清单") + L.append("") + L.append(f"> **自动生成**（勿手改）：`python3 sdk/scripts/gen_integration_manifest.py` ") + L.append(f"> **真源**：`GET {base}/api/v3/ai/brain/skill-registry`（live） · **生成时间**：{now} ") + L.append("> **铁律**：四端**只调 HTTP**；工作手机**不改**存客宝/触客宝/AI数智员工/SuperAdmin 代码；缺口走 COORD 或 `sdk/proxy` 透传。") + L.append("") + L.append("## 〇、总览") + L.append("") + L.append("| 维度 | 数量 |") + L.append("|:---|:---:|") + L.append(f"| 平台（skill） | {summary.get('total_skills', len(skills))} |") + L.append(f"| 功能模块 | {summary.get('total_modules', '—')} |") + L.append(f"| 动作（action）总计 | {summary.get('total_actions', '—')} |") + L.append(f"| 平台业务动作 | {summary.get('platform_actions', '—')} |") + L.append("") + L.append("**通道图例**：`Frida Hook`=设备本机 Frida RPC（微信主通道）· `execute-script`=AI Brain 多平台脚本 · `u2`=UI 自动化兜底 · `companion`=设备端无障碍/广播模块（资料/红包等需 APK 模块或测试号）。") + L.append("") + + # 四端入口矩阵 + L.append("## 一、四端入口矩阵（不改对方代码）") + L.append("") + L.append("| 端 | 调用方式 | 典型可直调能力 |") + L.append("|:---|:---|:---|") + for end, how, caps in FOUR_END: + L.append(f"| **{end}** | {how} | {caps} |") + L.append("") + L.append("> 连接方案切换（超管主控台）：`POST /api/v3/connection/provider/switch`（jiqing/aochuang/legacy/custom_*）· 列表 `GET /api/v3/connection/providers`。") + L.append("") + + # 平台 → 模块 → 动作 + L.append("## 二、平台 × 模块 × 动作（实时）") + L.append("") + for plat, sk in skills.items(): + ch, entry = PLATFORM_CHANNEL.get(plat, ("—", "—")) + name = sk.get("name", plat) if isinstance(sk, dict) else plat + pkg = sk.get("package", "") if isinstance(sk, dict) else "" + mods = sk.get("modules", {}) if isinstance(sk, dict) else {} + total = sum(len(v) if isinstance(v, (list, dict)) else 0 for v in mods.values()) if isinstance(mods, dict) else 0 + L.append(f"### {name} `{plat}`") + L.append("") + L.append(f"- **包名**：`{pkg or '—'}` · **动作数**：{total} · **默认通道**：{ch}") + L.append(f"- **统一入口**：`{entry}`") + L.append("") + if isinstance(mods, dict) and mods: + L.append("| 模块 | 动作数 | 动作（action） |") + L.append("|:---|:---:|:---|") + for mk, acts in mods.items(): + names = acts if isinstance(acts, list) else (acts.get("actions", []) if isinstance(acts, dict) else []) + disp = " · ".join(f"`{a}`" for a in names) if names else "—" + L.append(f"| {mk} | {len(names)} | {disp} |") + L.append("") + + # 统一调用范式 + L.append("## 三、统一调用范式（可直接联调）") + L.append("") + L.append("```http") + L.append("# 微信（Frida 主通道）") + L.append("POST /api/v3/hook/execute") + L.append('{"device_id":"","platform":"wechat","action":"send_message",') + L.append(' "params":{"to_id":"文件传输助手","content":"hi"},"hook_only":1}') + L.append("") + L.append("# 多平台精确控机（抖音/小红书/闲鱼/Soul）") + L.append("POST /api/v3/ai/brain/execute-script") + L.append('{"device_id":"","script":"douyin","action":"send_message","params":{...}}') + L.append("") + L.append("# 未注册 BFF 的能力 → 经存客宝 BFF 透传（不新造接口）") + L.append("POST /v1/workphone/sdk/proxy") + L.append('{"method":"POST","path":"/api/v3/ai/brain/execute-script","body":{...}}') + L.append("```") + L.append("") + L.append("## 四、关联文档") + L.append("") + L.append("- 四端开放接口与对接铁律：`5、接口/02-业务对接/四端开放接口汇总与对接铁律.md`") + L.append("- 存客宝 BFF↔SDK 映射：`5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md`") + L.append("- 全量接口目录：`5、接口/01-规范与统一层/工作手机API全量接口目录.md`") + L.append("- 需求真源：`1、需求/修改/工作手机_存客宝四端对接_20260529.md` §3.8 / §十") + L.append("- 静态对齐校验：`python3 sdk/scripts/wechat_interface_audit.py`（0 缺失）") + L.append("") + return "\n".join(L) + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--base", default="http://127.0.0.1:8899") + args = ap.parse_args() + reg = fetch_registry(args.base) + md = render(reg, args.base) + os.makedirs(os.path.dirname(OUT), exist_ok=True) + with open(OUT, "w", encoding="utf-8") as f: + f.write(md) + print(f"[ok] 写入 {OUT}（{len(md)} 字）") + + +if __name__ == "__main__": + main() diff --git a/开发文档/1、需求/修改/工作手机_存客宝四端对接_20260529.md b/开发文档/1、需求/修改/工作手机_存客宝四端对接_20260529.md new file mode 100644 index 0000000000..e1008e0722 --- /dev/null +++ b/开发文档/1、需求/修改/工作手机_存客宝四端对接_20260529.md @@ -0,0 +1,903 @@ +# 工作手机_存客宝四端对接_20260529 + +> **本文档 = 四端对接/BFF/COORD 唯一需求真源** +> 微信 128 接口见 [微信全量控机](./工作手机_微信全量控机与私域_20260529.md) · 设备/AI 见 [设备Agent](./工作手机_设备Agent与基础设施_20260529.md) + +完成目标：SDK v3 作为**唯一设备执行层**，与存客宝 BFF 及四端（存客宝/触客宝/SuperAdmin/AI数智员工）**全接口对接**；本仓库只完善 SDK/中间层/文档；四端业务切换走 **COORD**。 + +> **日期**：2026-05-29 · **模块**：对接 / 中间层 / 多平台 / 机擎阿桥 +> **合并自**：原 `工作手机_存客宝四端全量对接_20260529.md` · `02-业务/业务需求.md` §六§七 · `机擎/SKILL.md` §五B/§7 · `references/工作手机中间层抽象.md` +> **姊妹需求（共 3 篇）**： +> - [工作手机_设备Agent与基础设施_20260529](./工作手机_设备Agent与基础设施_20260529.md) +> - [工作手机_微信全量控机与私域_20260529](./工作手机_微信全量控机与私域_20260529.md) +> - **本文** · 存客宝四端 + 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）见 §十一 | + +--- + +## 一、架构边界（强制） + +```text +┌─────────────┐ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ +│ 存客宝 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](./工作手机_设备Agent与基础设施_20260529.md) **§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 存客宝调用示例（可直接联调） + +```http +# ① 发微信（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） + +**触客宝收消息双通道（文档约定）**： + +```text +通道 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 仓）**： + +```http +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](https://github.com/FourTwooo/Hook_WeChat_FaaS) | 微信 | 版本锁定；hook 点维护 | +| wechat_chatter | [yincongcyincong/wechat_chatter](https://github.com/yincongcyincong/wechat_chatter) | 微信 | NetScene/Protobuf 发消息 | +| frida-mcp | [1193776794/frida-mcp](https://github.com/1193776794/frida-mcp) | 通用 | AI+Frida 辅助定位 hook | +| wechat-kf | [yunfei01cs/wechat-kf](https://github.com/yunfei01cs/wechat-kf) | 企微客服 | **回调 URL + 加密**；触客宝收消息可参考 | +| SpecFusion | [wxkingstar/SpecFusion](https://github.com/wxkingstar/SpecFusion) | 多平台 | 抖音/小红书/企微 API 文档检索 | +| WeCom ISV Callback | [openwecom.com](https://openwecom.com/skills/isv/wecom-isv-callback.html) | 企微 | 双 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](./工作手机_设备Agent与基础设施_20260529.md) · 本节写 **四端各自扫什么、调什么**。 + +#### 两种绑定 × 四端分工 + +| 绑定类型 | 存客宝 H5 | 触客宝 | AI数智员工 | SuperAdmin | 工作手机 SDK | +|:---|:---|:---|:---|:---|:---| +| **技术绑定**（连 SDK） | 可生成/展示 **项目 QR**（调用 SDK `/qrcode/*` 或内嵌） | 一般不参与 | 一般不参与 | 可配置租户 `server` URL | ✅ Agent 执行 | +| **业务绑定**（设备入库） | **扫码添加设备** · 工作台设备列表 | 读已绑设备 | **register-imei** · VIP 登录 | 项目-设备唯一绑定 | 提供 online `device_id` | + +#### 四端推荐流程（店员视角） + +```text +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） + +```http +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 连接方案可切换驱动层](./工作手机_设备Agent与基础设施_20260529.md) · 代码 `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，不改四端业务）**： + +```http +# 超管/运营切换全局连接方案 +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（见 [微信全量控机与私域](./工作手机_微信全量控机与私域_20260529.md) §八） | + +--- + +## 七、验收标准 + +### 7.1 SDK 软件层 + +```bash +# 工作手机侧 +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 +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%** | [四端开放接口汇总](../../5、接口/02-业务对接/四端开放接口汇总与对接铁律.md) | +| **一键安装文档** | **100%** | [Type-C指南](../../8、部署/02-设备Hook/Type-C真机一键安装与四端对接指南.md) | +| 真机 E2E P0 | 85% | 29/29 安全组 · send Frida ✅ | +| 四端业务切 SDK | 0% | COORD · **不改四端代码** | +| 线索 friend-add E2E | 0% | Hook 事件待验 | +| 解封 A→E | 0% | 见微信需求 MD | + +--- + +## 十、四端开放接口真源（汇总 · 勿另维护专文） + +> **铁律**：存客宝/触客宝/AI/SuperAdmin **只调 HTTP**；工作手机**不改**兄弟仓库。 + +### 10.1 存客宝私域最小闭环（接口已就绪） + +```text +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 验收复跑（解除阻塞后一键） + +```bash +# 只读探测（任何时候可跑，标 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](./工作手机_设备Agent与基础设施_20260529.md)，代码 `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](../5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md) +- [工作手机API全量接口目录.md](../5、接口/01-规范与统一层/工作手机API全量接口目录.md) +- [业务需求.md](../02-业务/业务需求.md) +- [真机开发铁律.md](../2、架构/01-总览/真机开发铁律.md) +- 存客宝：`cunkebao_v3/开发文档/5、接口/02-存客宝与工作手机对接/README.md` diff --git a/开发文档/5、接口/01-规范与统一层/四端可直调接口能力清单.md b/开发文档/5、接口/01-规范与统一层/四端可直调接口能力清单.md new file mode 100644 index 0000000000..9a545eb899 --- /dev/null +++ b/开发文档/5、接口/01-规范与统一层/四端可直调接口能力清单.md @@ -0,0 +1,183 @@ +--- +tags: [工作手机, 接口, 四端对接, 能力清单, 自动生成] +doc-type: 索引 +layer: 5、接口/01-规范与统一层 +parent: "[[5、接口/README|5、接口]]" +obsidian-color: "#0277BD" +--- + +# 四端可直调 · 模块化接口能力清单 + +> **自动生成**（勿手改）：`python3 sdk/scripts/gen_integration_manifest.py` +> **真源**：`GET http://127.0.0.1:8899/api/v3/ai/brain/skill-registry`（live） · **生成时间**：2026-05-30 12:54 +> **铁律**：四端**只调 HTTP**；工作手机**不改**存客宝/触客宝/AI数智员工/SuperAdmin 代码；缺口走 COORD 或 `sdk/proxy` 透传。 + +## 〇、总览 + +| 维度 | 数量 | +|:---|:---:| +| 平台（skill） | 9 | +| 功能模块 | 49 | +| 动作（action）总计 | 211 | +| 平台业务动作 | 150 | + +**通道图例**：`Frida Hook`=设备本机 Frida RPC（微信主通道）· `execute-script`=AI Brain 多平台脚本 · `u2`=UI 自动化兜底 · `companion`=设备端无障碍/广播模块（资料/红包等需 APK 模块或测试号）。 + +## 一、四端入口矩阵（不改对方代码） + +| 端 | 调用方式 | 典型可直调能力 | +|:---|:---|:---| +| **存客宝 H5 (:3100)** | 经存客宝 BFF /v1/workphone/* 或联调直连 :8899 | 发消息/群发/加好友/朋友圈/标签/线索/状态/中台 Skill | +| **触客宝 (:3101)** | 必经存客宝 BFF（同域 JWT） | message/send · messages/list · moments/post · agent/execute | +| **AI数智员工 (:3104)** | 经存客宝 OpenPlatform / proxy（不直连 :8899） | 设备状态/截图/终端绑定 + proxy→execute-script 多平台控机 | +| **SuperAdmin (:3103)** | 只读聚合 + 连接方案切换主控台 | GET /devices · status · connection/provider/switch | + +> 连接方案切换（超管主控台）：`POST /api/v3/connection/provider/switch`（jiqing/aochuang/legacy/custom_*）· 列表 `GET /api/v3/connection/providers`。 + +## 二、平台 × 模块 × 动作（实时） + +### 微信 `wechat` + +- **包名**：`com.tencent.mm` · **动作数**：98 · **默认通道**：Frida Hook（主） / u2（兜底） +- **统一入口**：`/api/v3/message/* friend/* group/* tag/* moments/* + hook/execute` + +| 模块 | 动作数 | 动作（action） | +|:---|:---:|:---| +| 消息 | 8 | `send_message` · `get_messages` · `forward_message` · `recall_message` · `send_card` · `batch_send_message` · `send_voice_message` · `mass_send` | +| 好友 | 8 | `add_friend` · `accept_friend` · `set_remark` · `delete_friend` · `get_contacts` · `search_contact` · `get_friend_info` · `batch_add_friend` | +| 群聊 | 10 | `create_group` · `invite_to_group` · `remove_from_group` · `set_group_notice` · `set_group_name` · `send_group_message` · `set_group_welcome` · `get_groups` · `get_group_members` · `quit_group` | +| 标签 | 6 | `add_tag` · `remove_tag` · `create_tag` · `delete_tag` · `get_tags` · `get_users_by_tag` | +| 朋友圈 | 8 | `post_moments` · `like_moments` · `comment_moments` · `get_moments` · `delete_moments` · `set_moments_cover` · `set_moments_privacy` · `forward_moments_link` | +| 个人资料 | 6 | `get_profile` · `set_nickname` · `set_signature` · `set_avatar` · `set_gender` · `set_region` | +| 账号安全 | 11 | `check_account_status` · `unblock_account` · `safety_center` · `change_password` · `unblock_self` · `unblock_appeal` · `check_restrictions` · `appeal_restriction` · `unblock_with_sms` · `unblock_via_customer_service` · `check_login_state` | +| 支付 | 7 | `send_red_packet` · `transfer` · `show_payment_code` · `receive_payment` · `view_wallet` · `view_transactions` · `receive_red_packet` | +| 会话管理 | 3 | `set_chat_top` · `set_mute_chat` · `clear_chat_history` | +| 收藏 | 2 | `add_to_favorites` · `get_favorites` | +| 小程序 | 1 | `open_mini_program` | +| 公众号 | 1 | `follow_official_account` | +| 视频号 | 6 | `open_video_channel` · `get_video_list` · `like_video` · `comment_video` · `follow_video_creator` · `share_video` | +| 扫一扫 | 4 | `scan_qr_code` · `scan_add_friend` · `show_my_qr` · `extract_qr_from_image` | +| 通话 | 2 | `voice_call` · `video_call` | +| 搜索发现 | 2 | `wechat_search` · `top_stories` | +| 微信运动 | 2 | `get_steps` · `like_steps` | +| 位置表情文件 | 6 | `send_location` · `share_real_time_location` · `send_emoji` · `get_sticker_list` · `send_file_from_chat` · `download_file` | +| 设置 | 5 | `toggle_do_not_disturb` · `clear_cache` · `check_for_update` · `logout` · `switch_account` | + +### 抖音 `douyin` + +- **包名**：`com.ss.android.ugc.aweme` · **动作数**：18 · **默认通道**：execute-script（AI Brain） +- **统一入口**：`/api/v3/ai/brain/execute-script (script=douyin)` + +| 模块 | 动作数 | 动作（action） | +|:---|:---:|:---| +| 消息 | 3 | `send_message` · `get_messages` · `batch_send_message` | +| 粉丝互动 | 9 | `get_fans` · `follow_user` · `unfollow_user` · `search_user` · `get_comments` · `reply_comment` · `like_video` · `collect_video` · `share_video` | +| 联系人 | 6 | `get_contacts` · `add_friend` · `accept_friend` · `set_remark` · `delete_friend` · `batch_add_friend` | + +### 小红书 `xhs` + +- **包名**：`com.xingin.xhs` · **动作数**：20 · **默认通道**：execute-script（AI Brain） +- **统一入口**：`/api/v3/ai/brain/execute-script (script=xhs)` + +| 模块 | 动作数 | 动作（action） | +|:---|:---:|:---| +| 消息 | 3 | `send_message` · `get_messages` · `batch_send_message` | +| 笔记互动 | 11 | `get_fans` · `follow_user` · `unfollow_user` · `search_user` · `get_comments` · `reply_comment` · `like_note` · `collect_note` · `share_note` · `search_note` · `post_note` | +| 联系人 | 6 | `get_contacts` · `add_friend` · `accept_friend` · `set_remark` · `delete_friend` · `batch_add_friend` | + +### 闲鱼 `xianyu` + +- **包名**：`com.taobao.idlefish` · **动作数**：11 · **默认通道**：execute-script（AI Brain） +- **统一入口**：`/api/v3/ai/brain/execute-script (script=xianyu)` + +| 模块 | 动作数 | 动作（action） | +|:---|:---:|:---| +| 消息 | 3 | `send_message` · `get_messages` · `batch_send_message` | +| 联系人 | 8 | `get_contacts` · `add_friend` · `accept_friend` · `set_remark` · `delete_friend` · `batch_add_friend` · `follow_user` · `unfollow_user` | + +### Soul `soul` + +- **包名**：`cn.soulapp.android` · **动作数**：3 · **默认通道**：execute-script（AI Brain） +- **统一入口**：`/api/v3/ai/brain/execute-script (script=soul)` + +| 模块 | 动作数 | 动作（action） | +|:---|:---:|:---| +| 消息 | 2 | `send_message` · `get_messages` | +| 动态 | 1 | `post_moments` | + +### 系统控制 `system` + +- **包名**：`—` · **动作数**：16 · **默认通道**：Agent 系统能力 +- **统一入口**：`/api/v3/devices/{id}/* ` + +| 模块 | 动作数 | 动作（action） | +|:---|:---:|:---| +| 设备操作 | 9 | `screenshot` · `click` · `click_text` · `input` · `swipe` · `press_key` · `ui_tree` · `device_info` · `status` | +| 应用管理 | 4 | `app_start` · `app_stop` · `current_app` · `installed_apps` | +| 网络 | 1 | `reconnect_network` | +| 守护 | 2 | `dismiss_popups` · `connection_guard` | + +### Hook 引擎 `hook` + +- **包名**：`—` · **动作数**：22 · **默认通道**：Hook 统一执行 +- **统一入口**：`/api/v3/hook/execute` + +| 模块 | 动作数 | 动作（action） | +|:---|:---:|:---| +| Frida 消息 | 3 | `hook_send_message` · `hook_get_messages` · `hook_recall_message` | +| Frida 联系人 | 3 | `hook_get_contacts` · `hook_get_contact_info` · `hook_search_contact` | +| Frida 群聊 | 4 | `hook_get_groups` · `hook_get_group_members` · `hook_create_group` · `hook_invite_to_group` | +| Frida 朋友圈 | 3 | `hook_get_moments` · `hook_post_moment` · `hook_like_moment` | +| Frida 标签 | 3 | `hook_get_labels` · `hook_add_label` · `hook_remove_label` | +| Frida 支付 | 2 | `hook_get_transfers` · `hook_get_red_packets` | +| Frida 设备 | 2 | `hook_get_device_info` · `hook_get_wechat_version` | +| Frida 数据库 | 2 | `hook_query_db` · `hook_get_db_tables` | + +### AI Brain `ai_brain` + +- **包名**：`—` · **动作数**：8 · **默认通道**：AI 中台编排 +- **统一入口**：`/api/v3/ai/brain/* · /api/v3/devices/{id}/ai/*` + +| 模块 | 动作数 | 动作（action） | +|:---|:---:|:---| +| 决策引擎 | 3 | `think` · `heartbeat_cycle` · `autonomous_loop` | +| 任务管理 | 3 | `add_task` · `add_standing_order` · `flush_offline_buffer` | +| API调用 | 2 | `call_ai` · `get_status` | + +### 防封引擎 `anti_ban` + +- **包名**：`—` · **动作数**：15 · **默认通道**：防封守护 +- **统一入口**：`/api/v3/anti-ban/*` + +| 模块 | 动作数 | 动作（action） | +|:---|:---:|:---| +| 拟人化 | 5 | `human_delay` · `human_type` · `human_click` · `human_swipe` · `human_browse` | +| 设备守卫 | 3 | `device_guard_check` · `root_hide_check` · `frida_detect_check` | +| 风控哨兵 | 3 | `risk_check` · `rate_limit` · `content_filter` | +| 养号调度 | 2 | `nurture_plan` · `nurture_execute` | +| 传感器 | 2 | `sensor_simulate` · `touch_harden` | + +## 三、统一调用范式（可直接联调） + +```http +# 微信（Frida 主通道） +POST /api/v3/hook/execute +{"device_id":"","platform":"wechat","action":"send_message", + "params":{"to_id":"文件传输助手","content":"hi"},"hook_only":1} + +# 多平台精确控机（抖音/小红书/闲鱼/Soul） +POST /api/v3/ai/brain/execute-script +{"device_id":"","script":"douyin","action":"send_message","params":{...}} + +# 未注册 BFF 的能力 → 经存客宝 BFF 透传（不新造接口） +POST /v1/workphone/sdk/proxy +{"method":"POST","path":"/api/v3/ai/brain/execute-script","body":{...}} +``` + +## 四、关联文档 + +- 四端开放接口与对接铁律：`5、接口/02-业务对接/四端开放接口汇总与对接铁律.md` +- 存客宝 BFF↔SDK 映射：`5、接口/02-业务对接/存客宝BFF与工作手机SDK映射表.md` +- 全量接口目录：`5、接口/01-规范与统一层/工作手机API全量接口目录.md` +- 需求真源：`1、需求/修改/工作手机_存客宝四端对接_20260529.md` §3.8 / §十 +- 静态对齐校验：`python3 sdk/scripts/wechat_interface_audit.py`（0 缺失） diff --git a/开发文档/5、接口/README.md b/开发文档/5、接口/README.md index 9fc24281bc..54b3b7e9ef 100644 --- a/开发文档/5、接口/README.md +++ b/开发文档/5、接口/README.md @@ -45,7 +45,7 @@ cssclasses: | 大类 | 入口 | |------|------| -| **01 规范与统一层** | [**工作手机API全量接口目录.md**](01-规范与统一层/工作手机API全量接口目录.md)（328 条） · [接口规范.md](01-规范与统一层/接口规范.md) · [通用服务交互层.md](01-规范与统一层/通用服务交互层.md) | +| **01 规范与统一层** | [**四端可直调接口能力清单.md**](01-规范与统一层/四端可直调接口能力清单.md)（9平台/49模块/211动作·自动生成） · [**工作手机API全量接口目录.md**](01-规范与统一层/工作手机API全量接口目录.md)（328 条） · [接口规范.md](01-规范与统一层/接口规范.md) · [通用服务交互层.md](01-规范与统一层/通用服务交互层.md) | | **02 业务对接** | [存客宝BFF映射表](02-业务对接/存客宝BFF与工作手机SDK映射表.md) · [存客宝对接规范.md](02-业务对接/存客宝对接规范.md) · [外部对接网关接口说明.md](02-业务对接/外部对接网关接口说明.md) | | **03 Hook与微信** | [Hook模块管理接口.md](03-Hook与微信/Hook模块管理接口.md) · [微信全功能矩阵](03-Hook与微信/微信全功能矩阵_v8.0.56.md) | | **04 OpenAPI** | [openapi_v3.0.json](04-OpenAPI/openapi_v3.0.json) |