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

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

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

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":"<serial>","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":"<serial>","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()

开发文档/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`

开发文档/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":"<serial>","platform":"wechat","action":"send_message",
+ "params":{"to_id":"文件传输助手","content":"hi"},"hook_only":1}
+
+# 多平台精确控机（抖音/小红书/闲鱼/Soul）
+POST /api/v3/ai/brain/execute-script
+{"device_id":"<serial>","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 缺失）

开发文档/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) |