QA 自动回复机器人 — 部署指南

一、功能简介

基于企业微信「智能机器人」接口的自动回复服务：用户在客户群中 @机器人 提问，后端匹配 help-qa.json 中的关键词，回复一句话摘要 + 帮助中心精准链接，引导用户进入帮助网站查看完整图文答案。

不在群里刷大段文字，只做"引路人"
帮助中心已有完整内容（搜索、图文、分类），机器人只负责精准导航
不受「群发消息」每日 1 条的限制（通过 response_url 被动回复）
支持外部客户群和内部群
需要用户 @机器人才会触发（不会监听所有消息）

回复示例

用户在群里发：@机器人安全键

机器人回复：

关于「安全键是什么？哪些键盘有？」：
安全键又称两键下单：需先按住安全键再按下单键，降低误触。

查看详情：https://www.accord1key.cn/help/web/classic-keyboard/features/safe-key

二、环境准备

2.1 Python 依赖

pip install flask pycryptodome requests

或在项目根目录：

# 取消 requirements.txt 中 QA 机器人部分的注释后
pip install -r requirements.txt

2.2 文件结构

help-center/
├── tools/
│   ├── qa_bot_server.py      ← 机器人主程序
│   └── qa_bot_config.json    ← 配置文件（Token / AESKey / 端口）
└── static/data/
    └── help-qa.json          ← QA 数据源（118 条）

三、企业微信后台配置

3.1 创建智能机器人

登录企业微信管理后台
进入 应用管理 → 创建应用（或使用现有自建应用）
在应用设置中找到 智能机器人 功能，点击 创建一个智能机器人
记录 BotID（后续配置需要）

3.2 设置回调 URL

在智能机器人设置页面，点击 「接收消息」→ 设置 API 接收
填写：
- URL: https://your-domain.com/callback（必须 HTTPS）
- Token: 自定义，与 qa_bot_config.json 中的 token 一致
- EncodingAESKey: 点击「随机获取」或自定义 43 位字符串，与配置文件一致
点击「保存」，企微会发送 GET 验证请求（此时服务器必须已运行）

3.3 将机器人添加到客户群

进入目标客户群的群管理
添加「智能机器人」到群
群内用户 @机器人即可触发自动回复

四、配置文件说明

编辑 help-center/tools/qa_bot_config.json：

{
  "token": "填写企微后台的 Token",
  "encoding_aes_key": "填写企微后台的 EncodingAESKey（43位）",
  "corpid": "填写企业 CorpID",
  "port": 5001,
  "host": "0.0.0.0",
  "debug": false,
  "help_center_base": "https://www.accord1key.cn/help/web",
  "fallback_reply": "您好！请访问灵犀汇金帮助中心查找解答：\nhttps://www.accord1key.cn/help/web/\n\n支持搜索，经典键盘 / QMT / 多屏等常见问题均可在此找到。",
  "match_threshold": 0.3
}

字段	说明
`token`	企微智能机器人回调 Token
`encoding_aes_key`	43 位 Base64 编码的 AES 密钥
`corpid`	企业 ID，用于消息解密校验
`port`	HTTP 服务端口，默认 5001
`host`	监听地址，`0.0.0.0` 监听所有网卡
`debug`	Flask 调试模式（生产环境设 false）
`help_center_base`	帮助中心基础 URL，用于拼接精准链接
`cors_origins`	允许跨域请求的来源列表（帮助中心前端域名）
`fallback_reply`	QA 未匹配时的兜底回复（引导到帮助中心首页）
`match_threshold`	匹配置信度阈值（0~1），低于此值视为未匹配

五、启动服务

cd help-center/tools
python qa_bot_server.py

启动成功后会看到：

灵犀汇金 QA 服务
企微回调: http://0.0.0.0:5001/callback
帮助中心API: http://0.0.0.0:5001/api/ask
QA 条数: 111

五b、对接帮助中心浮窗

帮助中心的 QA 浮窗（HelpAssistantWidget）已预留 helpQaApiUrl 配置。只需设置环境变量即可让浮窗使用后端 API 匹配：

# 构建帮助中心时指定后端 API 地址
HELP_QA_API_URL=https://your-domain.com/api/ask npm run build

或本地开发时：

HELP_QA_API_URL=http://localhost:5001/api/ask npm start

接口协议（已与前端 pickIdFromApi 兼容）：

POST /api/ask
Content-Type: application/json

请求: {"query": "用户问题", "candidates": [{"id": "downloads", "label": "驱动与软件下载"}, ...]}
响应: {"id": "downloads"}  或  {"id": null}

前端收到 id 后自行从 help-qa.json 取 answer_md，在浮窗内渲染完整图文答案（支持图片、视频、表格、链接）。

架构示意

企微群 @机器人 ──────┐
                     │
帮助中心浮窗提问 ────┼──► qa_bot_server.py（同一个服务）
                     │     ├─ POST /callback  → 企微回调
                     │     ├─ POST /api/ask   → 帮助中心浮窗
                     │     └─ QAMatcher（共用匹配引擎）
未来更多入口 ────────┘

六、本地开发 — ngrok 调试

企微回调要求公网 HTTPS URL。本地开发时可用 ngrok 暴露：

6.1 安装 ngrok

从 ngrok.com 下载并配置 authtoken：

ngrok config add-authtoken YOUR_TOKEN

6.2 启动隧道

ngrok http 5001

ngrok 会输出一个公网 URL，例如 https://xxxx.ngrok-free.app。

将 https://xxxx.ngrok-free.app/callback 填入企微后台「接收消息 URL」。

⚠️ 免费版 ngrok 每次重启会更换 URL，需同步更新企微后台配置。

6.3 调试接口

接口	用途
`GET /health`	健康检查，查看 QA 加载数量
`GET /test_match?q=下载`	测试关键词匹配效果
`POST /reload_qa`	热重载 help-qa.json（无需重启）

示例：

curl http://localhost:5001/test_match?q=下载
# {"matched": "downloads", "score": 1.0, "title": "驱动与软件下载",
#  "reply": "关于「驱动与软件下载」：\n请打开站内统一下载页...\n\n查看详情：https://..."}

curl http://localhost:5001/test_match?q=键盘没反应
# {"matched": "ck_0020", "score": 0.48, "reply": "关于「...」：\n...\n\n查看详情：https://..."}

七、生产环境部署

7.1 云服务器方式

# 使用 gunicorn 替代 Flask 内置服务器
pip install gunicorn
gunicorn -w 2 -b 0.0.0.0:5001 "qa_bot_server:create_app(load_config(), QAMatcher())"

Nginx 反代配置：

server {
    listen 443 ssl;
    server_name bot.your-domain.com;
    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /callback {
        proxy_pass http://127.0.0.1:5001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

7.2 systemd 服务（Linux）

[Unit]
Description=LXHJ QA Bot
After=network.target

[Service]
WorkingDirectory=/opt/lxqmt/help-center/tools
ExecStart=/usr/bin/python3 qa_bot_server.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

八、常见问题

Q: URL 验证失败？

确认 token、encoding_aes_key、corpid 与企微后台完全一致
确认服务已启动，公网 URL 可访问

Q: 收不到消息？

用户必须 @机器人 发消息才会触发回调
检查机器人是否已添加到目标群
检查日志中是否有解密失败报错

Q: 匹配不准确？

调整 match_threshold（降低阈值可匹配更多，但可能不太精确）
在 help-qa.json 中为对应条目添加更多 aliases
使用 /test_match?q=xxx 接口调试匹配效果

Q: 如何更新 QA 数据？

修改 help-qa.json 后，调用 POST /reload_qa 即可热重载，无需重启服务

一、功能简介​

回复示例​

二、环境准备​

2.1 Python 依赖​

2.2 文件结构​

三、企业微信后台配置​

3.1 创建智能机器人​

3.2 设置回调 URL​

3.3 将机器人添加到客户群​

四、配置文件说明​

五、启动服务​

五b、对接帮助中心浮窗​

架构示意​

六、本地开发 — ngrok 调试​

6.1 安装 ngrok​

6.2 启动隧道​

6.3 调试接口​

七、生产环境部署​

7.1 云服务器方式​

7.2 systemd 服务（Linux）​

八、常见问题​