workphone-sdk/开发文档/5、接口/07-对外接口统一清单/01-接口总清单与机器可读API.md

01 · 接口总清单与机器可读 API

工作手机 SDK 全部对外接口按「模块 + 消费方」归类。 实时真源永远是 /api/v3/integration/manifest；本文只保留接入口径、核心接口和历史快照说明，端点数量以实时返回为准。 真源：sdk/app/services/integration_manifest.py + sdk/app/routers/integration.py

一、机器可读集成中心 API（推荐对接方式）

存客宝 / 超管 / AI 数字员工无需读静态文档，直接调用以下接口即可实时发现并调用全部能力：

方法	路径	说明
GET	/api/v3/integration/manifest	全量接口清单（模块 + 消费方 + 端点明细）
GET	/api/v3/integration/modules	模块目录（精简：模块/标签/消费方/端点数）
GET	/api/v3/integration/consumers	消费方列表
GET	/api/v3/integration/consumers/{consumer}	某消费方可用接口子集（cunkebao/superadmin/ai_employee/common）
GET	/api/v3/integration/capability/{device_id}	某设备实时能力矩阵（ready/degraded/offline），?consumer=、?probe=true
GET	/api/v3/integration/health	关键集成点健康聚合（WS/连接方案/存客宝/AI网关）
GET	/api/v3/integration/realtime/status	第三方对接实时状态：在线设备、能力摘要、最近 WS/Hook/Agent 事件
GET	/api/v3/integration/realtime/events	Hook/Agent/WS 事件流，可按 event_type/device_id/platform/limit 过滤

能力矩阵（运行时可调性）

静态清单回答「有哪些接口」，能力矩阵回答「这台设备此刻哪些能直接调用」：

# 存客宝视角看某设备能力（读最近探测缓存）
curl "http://<sdk-host>:8899/api/v3/integration/capability/<device_id>?consumer=cunkebao"
# 轻量刷新 Frida 状态（仅 ping/version/profile，不做全量探针）
curl "http://<sdk-host>:8899/api/v3/integration/capability/<device_id>?probe=true"

status 含义：ready 可直接调用 ｜ degraded 在线但 Frida 未 attach（微信类走 u2 降级）｜ offline 设备不在线。 模块运行时分类：server（SDK 在即可用）/ device（需 WS 在线）/ hook（需 Frida attach 发挥完整能力）。

示例：

# 存客宝只取自己能用的接口
curl http://<sdk-host>:8899/api/v3/integration/consumers/cunkebao

# 超管查看连接方案/存客宝/网关是否就绪
curl http://<sdk-host>:8899/api/v3/integration/health

二、SDK 控手机最小可用接口表（对接方优先验）

这张表回答“第三方系统最少调哪些接口，就能确认手机可控、微信可读写、事件可追踪”。

能力	方法	SDK 路径	用途	对接建议
服务健康	GET	/health	SDK 是否启动、在线设备数	上线门禁第一步
设备列表	GET	/api/v3/devices	单机/ADB/WS 设备发现	控制台和调试可直用
Fleet 汇总	GET	/api/v3/fleet/summary	全部手机数量、在线数、项目分组	存客宝/超管首页
Fleet 设备	GET	/api/v3/fleet/devices?online_only=1	筛选在线手机、能力、MD5	多设备选择器
Fleet 执行	POST	/api/v3/fleet/execute	对一台或多台手机执行动作	多设备写类须 dry_run/confirm
连接状态	GET	/api/v3/connection/status	WS/ADB/Hook 连接口径	设备详情状态卡
能力矩阵	GET	/api/v3/integration/capability/{device_id}	判断 ready/degraded/offline	业务下发前必查
实时状态	GET	/api/v3/integration/realtime/status?consumer=cunkebao	在线设备 + 最近事件	第三方对接看板
实时事件	GET	/api/v3/integration/realtime/events	Hook/Agent 事件流	线索、消息、故障追踪
发消息	POST	/api/v3/message/send	微信单聊/文件助手发消息	白名单或 filehelper 先验
联系人	GET	/api/v3/contacts	联系人分页读取	存客宝客户同步
群列表	GET	/api/v3/group/list	群列表读取	群运营入口
标签列表	GET	/api/v3/tag/list	标签读取	客户分组入口
当前资料	GET	/api/v3/profile/get	当前微信资料/wxid/nickname	设备绑定展示
Hook 执行	POST	/api/v3/hook/execute	统一 Frida/Hook 动作	高级调试和兜底

三、标准控机调用链

存客宝 / 触客宝 / 超管 / AI 数字员工 / 其他私域项目
  → BFF / SDK REST / OpenAI / MCP
  → 工作手机 SDK :8899
  → WebSocket Agent
  → Frida Hook / u2 / ADB
  → 工作手机真机 APP（微信优先）

对接规则：

1. 存客宝/触客宝优先走 /v1/workphone/*，由 BFF 统一鉴权、租户、日志和错误翻译。
2. 其他内部系统可直连 /api/v3/integration/*、/api/v3/fleet/*、/api/v3/gateway/*，但必须配置服务端 API Key。
3. AI 数字员工优先走 OpenAI 兼容 /api/v3/gateway/v1/chat/completions 或 MCP /api/v3/gateway/mcp/*。
4. 写类动作必须返回真实设备执行结果；设备离线、Hook 未注入、风控限制不允许包装成成功。

四、模块规模总览（历史快照）

指标	值
模块数	33
对外端点	358
存客宝可用	253 端点 / 18 模块
超级管理端可用	129 端点 / 17 模块
AI 数字员工可用	240 端点 / 18 模块

注：上表是 2026-05-30 快照，用于规模参考；最新数量请调用 /api/v3/integration/manifest。

五、消费方说明

消费方 id	标签	主要场景
cunkebao	存客宝	直连业务（微信消息/好友/群/标签/朋友圈/支付）+ 线索/Hook 事件上报
superadmin	超级管理端	连接方案切换、配置开关、防风控、模块管理、全局管控
ai_employee	AI 数字员工	OpenAI/MCP/Agent 网关，自然语言控机
common	通用	设备/健康/发现/经验等基础能力

六、铁律

1. 只暴露工作手机侧出口；严禁改存客宝/AI数字员工/超管代码，需配合的见 03-协作通知与待配合事项.md。
2. 业务下发统一经 WebSocket 主控（WORKPHONE_WS_FIRST=1）；微信动作 Frida Hook 优先、u2 兜底。
3. 响应口径：业务失败用 success=false 表达，HTTP 仍 200；设备不在线返回 503，不假成功。
4. 接口网站：/static/hub.html 的“接口文档（实时）”直接读取 /api/v3/integration/manifest，新增/删除路由后无需手工改前端清单。

---

七、全量接口清单（按模块）

下表为 2026-05-30 动态快照；最新以 GET /api/v3/integration/manifest 为准。

存客宝对接 cunkebao_link · 8 端点 · 消费方: cunkebao, superadmin

方法	路径	说明
POST	/api/v3/cunke-bao/batch-contacts	批量上报联系人到存客宝
GET	/api/v3/cunke-bao/config	查询当前存客宝配置（API Key 脱敏显示）
POST	/api/v3/cunke-bao/config	设置存客宝对接配置
POST	/api/v3/cunke-bao/hook/batch-events	批量接收 Frida Hook 事件
POST	/api/v3/cunke-bao/hook/friend-add	接收 Frida Hook 上报的新好友添加事件
POST	/api/v3/cunke-bao/hook/group-change	接收 Frida Hook 上报的群变动事件
POST	/api/v3/cunke-bao/report-lead	手动上报线索到存客宝
GET	/api/v3/cunke-bao/stats	查询存客宝服务统计信息

连接方案可切换驱动 connection_switch · 6 端点 · 消费方: superadmin, cunkebao

方法	路径	说明
GET	/api/v3/connection/provider/active	解析当前生效连接方案（设备 > 项目 > 全局）
POST	/api/v3/connection/provider/execute	经当前/指定方案统一执行
POST	/api/v3/connection/provider/register	注册/更新方案（自定义无需改代码）
POST	/api/v3/connection/provider/switch	一键切换连接方案
DELETE	/api/v3/connection/provider/{provider_id}	删除自定义方案
GET	/api/v3/connection/provider/{provider_id}/health	方案健康/连通性检查

AI 网关 · OpenAI 兼容 gateway_openai · 3 端点 · 消费方: ai_employee

方法	路径	说明
POST	/api/v3/gateway/v1/chat/completions	OpenAI 兼容 Chat API，像调 GPT 一样控机
GET	/api/v3/gateway/v1/models	列出可用模型
POST	/api/v3/v1/chat/completions	OpenAI 兼容端点（代理本地 Ollama）

AI 网关 · MCP 协议 gateway_mcp · 2 端点 · 消费方: ai_employee

方法	路径	说明
POST	/api/v3/gateway/mcp/call	MCP 调用指定工具
GET	/api/v3/gateway/mcp/tools	MCP 列出所有可用工具

AI 网关 · REST 聚合/编队 gateway · 7 端点 · 消费方: ai_employee, superadmin

方法	路径	说明
POST	/api/v3/gateway/fleet/broadcast	向多台设备广播命令
POST	/api/v3/gateway/fleet/group	创建设备分组
GET	/api/v3/gateway/fleet/groups	列出设备分组
GET	/api/v3/gateway/fleet/status	多设备总览
GET	/api/v3/gateway/info	网关信息（三种对接方式入口）
GET	/api/v3/gateway/journey	所有设备 AI 旅程
GET	/api/v3/gateway/journey/{device_id}	单设备 AI 旅程

AI Agent 控机 ai_agent · 6 端点 · 消费方: ai_employee, cunkebao

方法	路径	说明
GET	/api/v3/agent/download	下载设备端 Agent 打包文件
POST	/api/v3/agent/execute	执行自然语言任务（WS Agent / ADB 自动选择）
GET	/api/v3/agent/status/{device_id}	获取 Agent 状态
POST	/api/v3/agent/stop/{device_id}	停止 Agent 任务
POST	/api/v3/ai/chat	AI 对话控制手机（核心端点）
GET	/api/v3/ai/status	AI 引擎状态

AI Brain 技能注册与调度 ai_brain · 8 端点 · 消费方: ai_employee, superadmin

方法	路径	说明
POST	/api/v3/ai/brain/batch-execute	多设备批量脚本执行
GET	/api/v3/ai/brain/dashboard	AI Brain 仪表盘
POST	/api/v3/ai/brain/execute-script	向指定设备发送技能脚本
GET	/api/v3/ai/brain/skill-registry	全部技能/模块/操作清单
GET/POST	/api/v3/scripts	脚本管理
GET	/api/v3/scripts/{script_id}	脚本详情
POST	/api/v3/scripts/{script_id}/deploy	部署脚本

微信消息 wechat_message · 8 端点 · 消费方: cunkebao, ai_employee

方法	路径	说明
POST	/api/v3/message/send	发送消息（统一接口）
POST	/api/v3/message/batch-send	批量发送（间隔防风控）
POST	/api/v3/mass-send	群发消息
POST	/api/v3/message/forward	转发消息
POST	/api/v3/message/list	获取消息列表
POST	/api/v3/message/recall	撤回最近一条
POST	/api/v3/message/send-card	发送名片
POST	/api/v3/message/voice	发送语音消息

微信好友 wechat_friend · 6 端点 · 消费方: cunkebao, ai_employee

方法	路径	说明
POST	/api/v3/friend/add	添加好友
POST	/api/v3/friend/batch-add	批量添加好友
POST	/api/v3/friend/accept	通过好友请求
POST	/api/v3/friend/delete	删除好友
GET	/api/v3/friend/info	好友详细资料
POST	/api/v3/friend/set-remark	设置备注

微信通讯录 wechat_contacts · 2 端点 · 消费方: cunkebao, ai_employee

方法	路径	说明
GET	/api/v3/contacts	联系人列表（display_name/wechat_id/tags 完整）
GET	/api/v3/contacts/search	搜索联系人

微信群 wechat_group · 10 端点 · 消费方: cunkebao, ai_employee

方法	路径	说明
POST	/api/v3/group/create	创建群聊
POST	/api/v3/group/invite	邀请入群
GET	/api/v3/group/list	群聊列表
GET	/api/v3/group/members	群成员列表
POST	/api/v3/group/quit	退出群聊
POST	/api/v3/group/remove	移出群聊
POST	/api/v3/group/send-message	发送群消息
POST	/api/v3/group/set-name	设置群名
POST	/api/v3/group/set-notice	设置群公告
POST	/api/v3/group/set-welcome	设置群欢迎语

微信标签 wechat_tag · 6 端点 · 消费方: cunkebao, ai_employee

方法	路径	说明
POST	/api/v3/tag/create	创建标签
POST	/api/v3/tag/add	给好友添加标签
POST	/api/v3/tag/remove	移除好友标签
POST	/api/v3/tag/delete	删除标签
GET	/api/v3/tag/list	标签列表
POST	/api/v3/tag/users	按标签取好友

微信朋友圈 wechat_moments · 8 端点 · 消费方: cunkebao, ai_employee

方法	路径	说明
POST	/api/v3/moments/post	发布朋友圈/瞬间
POST	/api/v3/moments/list	朋友圈列表
POST	/api/v3/moments/like	点赞
POST	/api/v3/moments/comment	评论
POST	/api/v3/moments/delete	删除
POST	/api/v3/moments/set-cover	设置封面
POST	/api/v3/moments/set-privacy	设置可见天数
POST	/api/v3/moments/share-link	分享链接

微信支付/转账 wechat_payment · 7 端点 · 消费方: cunkebao, ai_employee

方法	路径	说明
POST	/api/v3/payment/transfer	转账
POST	/api/v3/payment/receive	收款
POST	/api/v3/payment/red-packet	发红包
POST	/api/v3/payment/receive-red-packet	领取红包
GET	/api/v3/payment/code	显示付款码
GET	/api/v3/payment/transactions	查看账单
GET	/api/v3/payment/wallet	查看钱包

微信账号/登录/解封 wechat_account · 16 端点 · 消费方: cunkebao, superadmin

方法	路径	说明
GET	/api/v3/account/status	检查账号状态
GET	/api/v3/account/restrictions	检查功能限制
POST	/api/v3/account/unblock	微信解封
POST	/api/v3/account/unblock-self	自助解封
POST	/api/v3/account/unblock-sms	短信验证解封
POST	/api/v3/account/unblock-appeal	申诉解封
POST	/api/v3/account/unblock-customer-service	联系客服解封（全自动 + AI 对话）
POST	/api/v3/account/appeal-restriction	申诉功能限制
POST	/api/v3/account/change-password	修改密码
GET	/api/v3/account/safety-center	安全中心
POST	/api/v3/account/wechat/check-login-state	u2 检测是否已登录
POST	/api/v3/account/wechat/ensure-login	未登录则自动登录
POST	/api/v3/account/wechat/login-by-password	账号密码登录（u2）
POST	/api/v3/auto-register/check-state	检查登录/注册状态
POST	/api/v3/auto-register/full	全自动微信注册
POST	/api/v3/auto-register/get-sim-phone	取 SIM 手机号

微信扩展操作 wechat_extra · 40 端点 · 消费方: cunkebao, ai_employee

资料/扫码/收藏/表情/文件/位置/通话/小程序/公众号/搜一搜/设置/视频号/微信运动。完整列表见 GET /api/v3/integration/consumers/cunkebao。代表端点：

方法	路径	说明
GET	/api/v3/profile/get	获取账号资料
POST	/api/v3/profile/set-nickname	修改昵称
POST	/api/v3/scan/add-friend	扫码加好友
GET	/api/v3/scan/my-qr	我的二维码
POST	/api/v3/file/send	发送文件
POST	/api/v3/location/send	发送位置
POST	/api/v3/call/voice	语音通话
POST	/api/v3/miniprogram/open	打开小程序
GET	/api/v3/search/wechat	搜一搜
GET	/api/v3/video-channel/list	视频号列表

微信全量操作 wechat_full · 81 端点 · 消费方: cunkebao, ai_employee

/api/v3/wechat/* 全量补全（含 /wechat/execute 统一执行入口支持 128 canonical action）。完整列表见 GET /api/v3/integration/manifest。

Hook 探测/执行/动作 hook · 6 端点 · 消费方: cunkebao, ai_employee, superadmin

方法	路径	说明
GET	/api/v3/hook/probe/{device_id}	探测 Frida Hook 能力
GET	/api/v3/hook/actions	全部操作清单（107 操作/24 模块）
GET	/api/v3/hook/data/{device_id}	一次性取联系人/消息/群/标签/资料
POST	/api/v3/hook/execute	Hawk Hook 统一执行（单接口控全机）
GET/POST	/api/v3/hook/events	Hook 事件流

设备管理与控制 devices · 29 端点 · 消费方: common, cunkebao, ai_employee

设备列表/详情/截图/点击/输入/滑动/UI树/执行/心跳/守护事件 + devices/{id}/ai/*（chat/execute/task/standing-order/queue-task/status）+ 健康评分。完整见 manifest。

设备连接 / 诊断 connection · 8 端点 · 消费方: superadmin, common

bootstrap/modes/protocol/status/providers + 联调 simulate。

防风控 anti_ban · 2 · superadmin, cunkebao ｜ 抓包 capture · 4 · superadmin ｜ Frida 无线 frida · 13 · superadmin, common ｜ Hook 模块管理 hook_modules · 8 · superadmin ｜ ADB 兜底 adb · 15 · superadmin, common

多服务器注册中心 registry · 6 ｜ 设备发现 discovery · 6 ｜ 项目管理 projects · 6 ｜ 经验库 experience · 12 ｜ 二维码 qrcode · 3 ｜ 语音 voice · 4 ｜ 控制台聚合 console · 3 ｜ 集成中心 integration · 7

上述模块端点明细均可经 GET /api/v3/integration/manifest 实时获取，不再静态罗列以避免漂移。