☰
首页
/
聚好麦 AI 客服系统 — 平台对接完整技术文档 v3.0
目录
聚好麦 AI 客服系统 — 平台对接完整技术文档 v3.0
一、平台架构总览
1.1 域名体系
1.2 路由表
二、核心 API 接口
2.1 Admin API（api.zwxx2022.com）
2.1.1 获取店铺信息
2.1.2 获取商品列表
2.1.3 获取 IM 登录 URL 和 Kefu JWT（⭐最关键）
2.2 Kefu API（api.yixikeji.cn）
2.2.1 获取客服信息与 WebSocket Token
2.2.2 发送消息（⭐最核心）
2.3 WebSocket（仅接收消息）
三、认证体系
3.1 三层 Token 结构与获取路径
3.2 Admin API Headers 完整规范
base_request.py - _merge_headers() 自动构建
动态添加:
authorization: Bearer <self.token> (或 <self.kefu_bearer_token> for yixikeji.cn)
code: <self.code>
3.3 响应格式标准化
base_request.py - _normalize_response()
聚好麦格式: {"code": 0, "msg": "操作成功", "data": {...}}
→ 统一格式: {"success": True, "result": {...}, "error_msg": ""}
3.4 Cookie 提取逻辑（关键）
base_request.py - update_cookies()
四、消息收发流程
4.1 完整数据流
4.2 消息去重（死循环防护）
core/pdd_message_handler.py
4.3 聚好麦 → 内部格式转换
core/pdd_message_handler.py - _process_websocket_message()
跳过非消息事件
4.4 AI 回复 Markdown 清理
ai_handler.py - _clean_reply()
4.5 知识库预搜索（绕过 LLM 工具调用）
ai_handler.py - _search_local_knowledge()
五、登录流程
5.1 完整 16 步序列
5.2 JWT 解码函数
六、自动回复启动流程
七、核心类与方法详解
7.1 BaseRequest（HTTP 请求基类）
7.2 PDDChannel（WebSocket 主类）
7.3 KnowledgeService（知识库服务）
7.4 PDDChatMessage（消息类型）
7.5 Context 与 ChannelType
八、数据库完整 Schema 与数据流
8.1 完整 SQL
8.2 商品同步数据流（product_sync.py）
8.3 商品缓存机制
product_sync.py - _get_cached_product_list()
九、配置体系
9.1 config.json（运行时配置）
9.2 websocket_config.json
9.3 config.py（Pydantic 模型）
LLM API 兼容性修复
volcengine_models.py - ChatCompletionRequest
DeepSeek: top_logprobs 需要 logprobs=True，都设为 None 避免 400 错误
十、踩坑全纪录
🔴 致命级（5个）— 不修复系统完全不可用
坑 1：消息发送走 HTTP POST 而非 WebSocket
坑 2：CDN 反爬拦截（istio-envoy TLS 指纹）
Python requests → 被 CDN 拦截
返回: {"code":401,"msg":"非法操作-u"}
或: {"code":401,"msg":"缺少用户标识","data":"中国湖北武汉 (IP:xxxx)"}
解决方案: Playwright 浏览器 fetch()
坑 3：shop_id 内外 ID 不匹配
外部 ID vs 内部 ID
❌ 错误
✅ 正确
坑 4：知识库搜索 AND 逻辑漏召回
修复1: 去查询前缀
修复2: OR 逻辑
坑 5：WebSocket 协议层与应用层 ping 冲突
❌ 旧配置: 协议层 ping 与应用层 {"cmd":"ping"} 冲突
5分钟后 code 1006 断开
✅ 新配置: 禁用协议层，全靠应用层
应用层: 每 3 秒 '{"seq":"","cmd":"ping"}'
🟠 严重级（5个）— 导致功能异常
坑 6：消息回显死循环
❌ 未过滤 → 自己发的回复被当作新消息 → 无限循环
✅ 过滤 is_kefu="yes"
坑 7：Base64 JWT 解码 Bug
❌ Bug: len % 4 == 0 时添加 4 个 =
✅ 修复
坑 8：`update_cookies` 未提取 Token
❌ 旧: 只存 cookies，token 仍为 None
✅ 新: 同时提取所有 token 和 code
坑 9：商品卡片空白
❌ 旧: 只传 sn，IM 客户端无法渲染
✅ 新: 从本地 DB 查完整信息
坑 10：AI 回复 latin-1 编码错误
❌ requests 默认 latin-1 编码 form 数据
✅ 手动 UTF-8 urlencode
🟡 中等级（6个）— 影响用户体验
坑 11-13：AI 回复问题
坑 14-15：库版本问题
坑 16：知识库UI闪退
❌ current_selection 在 if 块内定义
✅ 移到条件块外
🟢 低级（2个）
坑 17：Token 提取时机
坑 18：登录页选择器超时
十一、故障排查决策树
11.1 消息收不到
11.2 消息发不出
11.3 知识库搜不到
11.4 WebSocket 频繁断开
11.5 DeepSeek 400 错误
十二、关键经验总结