☰
首页
/
聚好麦 AI 客服系统 — 平台对接技术文档
目录
聚好麦 AI 客服系统 — 平台对接技术文档
一、平台架构总览
域名与路由
二、核心 API 接口
2.1 Admin 系统 API
2.2 Kefu 系统 API
2.3 WebSocket
2.4 API 速查卡
三、认证体系（三层 Token）
Token 层级
Headers 规范
四、消息收发流程
4.1 接收流程
4.2 发送流程
4.3 消息格式转换（聚好麦 → 内部格式）
Step 1: 解析聚好麦外层JSON
Step 2: 提取内层 content JSON（双重编码）
Step 3: 转为内部 PDDChatMessage 兼容格式
五、登录流程（完整序列）
六、自动回复启动流程
七、踩坑全记录（18个）
🔴 致命级（5个）
坑1：消息发送走 HTTP POST 而非 WebSocket
坑2：CDN 反爬（istio-envoy TLS 指纹）
坑3：shop_id 内外ID不匹配
坑4：客服知识搜索 AND 逻辑漏召回
坑5：WebSocket 协议层与应用层 ping 冲突
🟠 严重级（5个）
坑6：消息回显死循环
坑7：Base64 Padding Bug
坑8：update_cookies 未提取 Token
坑9：AI 回复 latin-1 编码错误
坑10：商品卡片发送空白
🟡 中等级（6个）
坑11：AI 不自动调用知识库
坑12：AI 回复 Markdown 星号
坑13：DeepSeek `top_logprobs`/`logprobs` 冲突
坑14：websockets 版本兼容
坑15：数据库路径空字符串
坑16：知识库UI闪退
🟢 低级（2个）
坑17：JWT token提取时机错误
坑18：登录页选择器超时
八、核心代码架构
8.1 目录结构
8.2 数据库 ER
8.3 Token 数据流
九、配置参考
config.json
websocket_config.json
多模型配置
十、故障排查
消息收不到
消息发不出
知识库搜不到
WebSocket 频繁断开
DeepSeek 400 错误
十一、关键经验总结