1. 项目背景与目标 1.1 背景 随着企业服务量的增长，传统人工客服面临响应慢、人力成本高、无法7×24小时服务的问题。同时，企业微信已成为企业与客户沟通的主要渠道。为了提升客户体验、降低客服成本，需要构建一套AI优先、人机协同的智能客服系统，使每个客服账号既能由AI自动接待，又能在必要时无缝切换至人工服务。 1.2 目标 AI自动接待：客户向指定客服账号发送消息时，由AI大模型结合企业知识库自动生成回复。 人工无缝接管：在特定条件下（如AI无法回答、客户要求转人工），系统自动将会话转给真人客服，且客户无感知（同一客服身份、聊天记录连续）。 统一客服身份：所有消息（AI或人工）均以同一个客服账号的身份发出，客户始终感觉与同一位“客服”对话。 提升效率：减少人工重复劳动，缩短客户等待时间，提高问题解决率。 2. 用户角色 角色 描述 核心需求 客户 通过企业微信与客服沟通的终端用户 快速获得准确答复；需要人工时能自然转接，不重复描述问题。 AI 服务 系统后端自动处理消息的模块 理解客户意图，调用知识库，生成合规回复；识别转人工场景。 人工客服 企业微信中的真人客服 查看AI对话历史，快速介入会话，使用工作台回复客户。 系统管理员 负责系统配置与维护 配置转人工规则、知识库、客服账号；监控会话质量和AI效果。 3. 功能需求 3.1 客服账号管理 支持在企业微信后台创建多个客服账号（通过“微信客服”功能）。 系统能够获取所有客服账号列表及在线状态。 支持将客服账号与人工客服账号绑定（可选，用于后续绩效统计）。 3.2 消息接收与处理 系统需暴露一个公网可访问的回调接口，用于接收企业微信推送的客户消息。 对接收到的消息进行解密和验签（使用企业微信提供的加解密库）。 解析消息内容、客户ID、客服账号ID、消息ID、时间戳等字段。 将消息存入数据库，并触发后续处理流程。 3.3 AI 自动回复 根据会话当前状态（AI处理中）调用AI大模型生成回复。 若开启了企业知识库，需先通过RAG检索相关文档，作为上下文补充给大模型。 支持多种回复格式：文本、图片、图文链接等（根据业务需要）。 生成的回复内容需经过安全合规检查（如敏感词过滤）。 通过企业微信API，以当前客服账号的身份发送消息给客户。 3.4 转人工策略 支持配置多种转人工触发条件（可组合）： 关键词触发：客户消息包含“人工”、“转人工”、“投诉”等预设词。 AI置信度阈值：AI生成的回复置信度低于设定值（如0.6）。 多轮失败：连续N轮对话AI未能解决问题（如客户重复提问）。 会话时长/轮次：超过设定时长或消息轮次后自动转人工。 手动触发：客户在菜单点击“联系人工客服”（需企业微信菜单支持）。 触发转人工后，系统立即停止AI自动回复，将会话状态置为“待人工接入”，并将会话推送到人工客服队列。 3.5 人工客服工作台 会话列表：显示待接入、进行中的会话，包含客户昵称、最新消息时间、转人工原因等。 聊天窗口： 展示当前客户与AI的完整历史聊天记录（客户消息+AI回复）。 支持人工输入文本、选择快捷回复、发送图片/图文。 发送的消息仍以同一客服账号身份发出，客户无感知。 支持查看客户资料（如姓名、企业、标签），可从企业微信或CRM同步。 转接/结束会话：人工客服可将会话转给其他同事，或主动结束会话。 辅助功能：快捷回复库、知识库搜索、订单查询工具（可选）。 3.6 会话状态管理 会话的生命周期由以下状态机管理： text [初始] -> AI处理中 | 触发转人工条件 v 待人工接入 | 客服点击接入 v 人工处理中 | 客服结束会话/客户超时 v 已结束 系统需维护每个会话的当前状态，并根据状态决定消息路由： AI处理中：消息进入AI处理模块。 待人工接入：消息不处理，仅推送到工作台待接入列表，或暂存等待人工。 人工处理中：消息直接推送到工作台，由人工回复。 3.7 上下文传递 转人工时，需将完整的对话历史（包括客户消息、AI回复、AI检索到的知识片段）传递给人工客服工作台。 人工客服接入后，工作台默认展示全部历史，确保人工快速了解前情。 若客户在人工处理期间继续发消息，工作台实时刷新显示新消息。 3.8 数据统计与监控 记录关键指标：AI回复率、转人工率、人工平均响应时间、会话满意度等。 支持管理员查看每个客服账号的接待量、AI处理占比。 支持导出报表。 4. 非功能需求 需求分类 具体要求 性能 - AI回复平均耗时 < 2秒（不含网络延迟） - 人工消息推送延迟 < 1秒 - 系统支持并发会话数 ≥ 1000 可用性 - 系统可用性 ≥ 99.9% - 关键模块（消息接收、发送）支持多副本部署，无单点故障 安全性 - 企业微信消息加密传输，需正确实现加解密规范 - API调用需携带合法Token，防止重放攻击 - 敏感数据（如客户手机号）在数据库加密存储 可扩展性 - AI模型可替换（如支持不同大模型API） - 知识库支持动态更新，无需重启服务 - 人工工作台可对接企业现有CRM系统 合规性 - 符合企业微信开发者协议 - 消息内容需过滤违法违规信息 5. 技术架构 5.1 整体架构图 text +-------------------+ +-------------------+ +-------------------+ | | | | | | | 企业微信客户端 | <------> | 企业微信服务端 | <------> | 自建 AI 客服系统 | | （客户/客服） | | (API & 回调) | | (核心后端) | | | | | | | +-------------------+ +-------------------+ +-------------------+ | v +------------------------+ | AI 服务模块 | | - 大模型 API | | - 知识库 (RAG) | | - 转人工判断逻辑 | +------------------------+ | v +------------------------+ | 人工客服工作台 | | - Web 界面 | | - 消息推送 (WebSocket) | | - 快捷回复库 | +------------------------+ 5.2 核心模块说明 模块 职责 关键技术 消息接收服务 接收企业微信回调请求，验签解密，将消息写入消息队列 HTTP Server (Spring Boot/Node.js)，企业微信加解密库 会话管理器 维护会话状态，根据状态将消息路由给AI或推送到人工工作台 Redis (存储会话状态)，消息队列 (Kafka/RabbitMQ) AI 处理器 调用大模型生成回复，集成知识库检索，判断是否转人工 大模型 API (OpenAI/DeepSeek)，向量数据库 (Milvus)，LangChain 消息发送服务 通过企业微信 API 发送消息给客户 HTTP Client，企业微信 Access Token 管理 人工工作台后端 提供 WebSocket 推送，API 供工作台调用 WebSocket，RESTful API 人工工作台前端 客服使用的界面，实时接收消息，发送回复 React/Vue，WebSocket 客户端 5.3 数据流转示例 客户发消息 → 企业微信回调 → 消息接收服务 → 存入数据库 → 消息放入队列。 会话管理器从队列消费消息，查询 Redis 中会话状态： 若为 AI 处理中，将消息发给 AI 处理器。 若为人工处理中，通过 WebSocket 推送给对应客服的工作台。 AI 处理器生成回复 → 判断是否转人工： 若不转，将回复内容发给消息发送服务，并最终发给客户。 若转，更新会话状态为待人工接入，并将会话信息存入人工队列，同时将本次回复发给客户（AI 完成最后一句话）。 人工客服登录工作台，看到待接入列表，点击接入 → 会话状态变为人工处理中，后续消息直接推送。 6. 接口定义 6.1 企业微信回调接口 URL: POST /wecom/callback 请求参数 (URL Query): msg_signature, timestamp, nonce, echostr (仅验证时) 请求体: 加密的 XML 格式消息 处理逻辑: 验证签名，解密消息体。 如果是普通消息，解析后存入数据库并推送到消息队列。 如果是事件（如客服接入），更新会话状态。 响应: 成功返回 "ok" 明文（需加密？实际上回调需返回明文 "ok" 或加密后的 "ok"？根据文档，接收消息时需返回加密后的 success 字符串。但简化起见，我们返回明文 "ok" 即可，但必须正确处理加解密。实际应使用官方 SDK 统一处理。） 6.2 发送消息接口（调用企业微信 API） 企业微信 API: POST https://qyapi.weixin.qq.com/cgi-bin/kf/send_msg?access_token=ACCESS_TOKEN 请求体示例: json { "touser": "客户ID", "open_kfid": "客服账号ID", "msgtype": "text", "text": { "content": "AI 生成的回复内容" } } 注意事项：需要管理 Access Token 的获取与刷新，支持多客服账号。 6.3 人工工作台 API WebSocket 连接: ws://your-domain/ws/cs/{客服ID}，用于实时接收新消息和状态更新。 REST API: GET /api/sessions?status=pending 获取待接入会话列表 POST /api/sessions/{sessionId}/accept 客服接入会话 POST /api/sessions/{sessionId}/message 人工发送消息 GET /api/sessions/{sessionId}/history 获取完整聊天记录 7. 数据模型 7.1 会话表 (session) 字段 类型 说明 session_id string 唯一会话ID，通常由企业微信客服API生成 customer_id string 客户ID (企业微信的 external_userid) kf_id string 客服账号ID ( open_kfid ) status enum 'AI' / 'PENDING' / 'MANUAL' / 'CLOSED' created_at datetime 会话创建时间 updated_at datetime 最后更新时间 manual_cs_id string 当前处理的人工客服ID（如果状态为MANUAL） metadata json 扩展信息，如转人工原因、客户标签等 7.2 消息表 (message) 字段 类型 说明 msg_id string 企业微信消息ID（唯一） session_id string 所属会话ID sender_type enum 'customer' / 'ai' / 'manual' sender_id string 发送者标识（客户ID、AI标识、客服ID） content text 消息内容 msg_type string 'text' / 'image' / 'link' 等 created_at datetime 消息时间 raw_data json 原始消息数据（用于调试） 7.3 客服账号表 (kf_account) 字段 类型 说明 kf_id string 客服账号ID name string 客服昵称 avatar string 头像URL status enum 'online' / 'offline'（人工客服在线状态） bind_manual_id string 绑定的企业微信员工ID（可选） 7.4 转人工记录表 (transfer_log) 字段 类型 说明 id int 自增ID session_id string 会话ID trigger_reason string 触发原因（关键词/AI置信度/多轮失败等） trigger_time datetime 触发时间 accepted_time datetime 客服接入时间（可选） accepted_cs_id string 接入的客服ID（可选） 8. 人机切换流程（详细） 8.1 触发转人工 当满足任一转人工条件时，系统执行以下操作： 将会话状态从 AI 更新为 PENDING（待接入）。 记录转人工原因到数据库。 如果此时 AI 正在生成回复，等待其完成并发送（保证回复连贯），然后禁止后续 AI 调用。 将会话信息推送到人工客服队列（可通过 WebSocket 通知所有在线客服有新会话待接入）。 8.2 人工客服接入 客服在工作台看到待接入会话，点击“接入”： 后端校验该会话状态仍为 PENDING，将其更新为 MANUAL，并记录接入的客服ID。 通过 WebSocket 通知该客服的工作台，打开聊天窗口并显示历史消息。 如有必要，可向客户发送一条欢迎语（但建议不发送，保持无感），或让客服主动发送第一条消息。 8.3 消息路由 会话状态为 MANUAL 后，所有客户新消息通过回调进入系统，会话管理器根据状态直接推送到对应客服的 WebSocket 连接上，不再经过 AI。 客服在工作台发送的消息，调用发送消息接口以客服账号身份发出。 8.4 会话结束 客服手动结束会话，或客户超过一定时间未回复（可配置），系统将会话状态置为 CLOSED。 结束后的会话不再接收消息（客户新消息将开启新会话）。 9. 验收标准 9.1 功能验收 客户发送消息，AI 能在 3 秒内回复。 当客户输入“人工”时，会话自动转为待人工，并出现在客服工作台。 客服接入后，能看到完整聊天记录，发送消息客户能收到且显示为同一客服身份。 人工回复后，客户继续发消息，消息能正确推送到该客服的工作台。 支持图片消息接收与发送（至少可转发图片）。 转人工条件可在后台配置并实时生效。 9.2 性能验收 并发 500 个会话同时进行 AI 处理，系统 CPU 负载 < 70%。 消息从客户发出到 AI 回复平均耗时 < 2.5 秒（包含企业微信 API 延迟）。 WebSocket 推送延迟 < 500ms。 9.3 安全性验收 所有回调接口正确验签，非法请求被拒绝。 Access Token 不泄露，定期刷新。 数据库敏感信息加密。 10. 附录 10.1 参考文档 企业微信微信客服 API 文档 企业微信回调消息加解密 MCP 协议介绍（可选，供参考） 10.2 术语表 术语 解释 微信客服 企业微信提供的一种客服功能，支持通过 API 收发消息，身份为客服账号。 open_kfid 客服账号的唯一标识。 external_userid 企业微信客户的唯一标识。 RAG 检索增强生成，一种结合检索和大模型生成的技术。