yy-WeChatPublicNumber/技术文档.md

微信公众号AI助手服务技术文档

1. 概述

本服务是一个基于Flask的微信公众号后端服务，实现了与Dify AI平台的集成。主要功能包括：

• 验证微信服务器请求的合法性
• 接收用户消息并调用Dify AI服务获取智能回复
• 通过微信客服消息接口异步返回AI回复
• 维护用户会话状态，支持多轮对话

2. 功能描述

功能模块	描述	实现方式
微信服务器验证	验证微信服务器请求的合法性	SHA1签名验证
消息接收与路由	接收并处理用户消息	XML解析与路由
AI服务调用	调用Dify AI服务获取智能回复	HTTP POST请求
会话管理	维护用户对话上下文	内存映射(conv_map)
客服消息发送	异步发送AI回复给用户	微信客服消息接口
被动回复	即时返回"正在查询"提示	XML格式响应

3. 环境要求

• Python 3.7+
• Flask 2.0+
• Requests库
• 微信公众号（服务号或订阅号）
• Dify AI服务（本地或云端）

4. 配置说明

在代码全局配置区设置以下参数：

# 微信相关配置
TOKEN = "your_wechat_token"  # 与微信公众号后台配置一致
APPID = "your_appid"         # 微信公众号APPID
APPSECRET = "your_appsecret" # 微信公众号APPSECRET

# Dify AI服务配置
DIFY_API_BASE = "http://your-dify-server/api"  # Dify API地址
DIFY_API_KEY = "your_dify_api_key"             # Dify API密钥（可选）

5. 核心模块说明

5.1 微信服务器验证 (/wx GET请求)

• 验证流程：
  1. 获取请求参数：signature, timestamp, nonce, echostr
  2. 对token、timestamp、nonce进行字典序排序
  3. 拼接字符串并进行SHA1加密
  4. 比较加密结果与signature是否一致
• 成功：返回echostr
• 失败：返回403错误

5.2 消息处理 (/wx POST请求)

• 支持的消息类型：文本消息(MsgType=text)
• 处理流程：
  1. 解析XML消息体
  2. 提取用户OpenID、公众号ID和消息内容
  3. 启动后台线程调用AI服务
  4. 立即返回"正在查询"的被动回复

5.3 Dify AI服务调用 (async_reply函数)

sequenceDiagram
    participant W as 微信用户
    participant S as 本服务
    participant D as Dify AI服务
    W->>S: 发送文本消息
    S->>S: 启动后台线程
    S->>W: 返回"正在查询"提示
    S->>D: 发送用户消息和会话ID
    D->>S: 返回AI回复和会话ID
    S->>S: 更新会话映射(conv_map)
    S->>W: 通过客服消息发送AI回复

5.4 客服消息发送 (send_wechat_customer_message函数)

• 使用微信客服消息接口发送文本消息
• 前提条件：
  • 公众号已完成认证
  • 用户在48小时内与公众号有过交互
• 消息格式：

  {
    "touser": "OPENID",
    "msgtype": "text",
    "text": {"content": "消息内容"}
  }
  

5.5 会话管理

• 使用全局字典conv_map存储会话状态
• 数据结构：{user_openid: conversation_id}
• 会话保持：每次调用Dify时带上conversation_id
• 新会话：当用户首次交互时自动创建新会话

6. 部署与运行

6.1 安装依赖

pip install flask requests

6.2 运行服务

python wechat_kefu.py

6.3 微信公众号配置

1. 服务器地址(URL): http://your-domain/wx
2. Token: 与代码中TOKEN一致
3. 消息加解密方式: 明文模式

7. 注意事项

7.1 安全性

1. 验证所有来自微信服务器的请求
2. 保护APP_SECRET和API_KEY不被泄露
3. 生产环境禁用DEBUG模式
4. 使用HTTPS加密传输

7.2 性能优化

1. 实现access_token缓存（有效期7200秒）
2. 限制用户请求频率
3. 使用连接池管理HTTP连接
4. 监控conv_map内存使用情况

7.3 异常处理

1. Dify服务不可用：返回用户友好提示
2. 客服消息发送失败：记录日志并重试
3. 会话丢失：自动创建新会话
4. 非文本消息：忽略并返回success

7.4 扩展性

1. 支持其他消息类型（如图片、语音）
2. 添加用户身份验证
3. 集成多个AI服务提供商
4. 实现消息队列处理异步任务

8. 常见问题排查

问题现象	可能原因	解决方案
微信验证失败	TOKEN配置不一致	检查公众号后台配置
无法接收消息	服务器网络问题	检查服务器防火墙设置
客服消息发送失败	access_token过期	实现token缓存机制
AI回复乱码	编码问题	检查Unicode解码逻辑
会话不连续	conv_map未持久化	使用数据库存储会话

9. 版本信息

• 初始版本：1.0
• 最后更新：2025-06-05
• 依赖版本：
  • Flask 2.1.2
  • Requests 2.28.1

注意：本服务需要微信公众号具备客服消息接口权限，开发前请确认公众号类型和权限设置。