客服小精灵 / CS Elf

WhatsApp AI 智能客服 Agent —— 自动接待、意向分析、客户评分、转人工，一个文件搞定。

它解决什么问题

外贸/跨境电商在 WhatsApp 上每天收到大量客户咨询，人工客服根本回不过来。客服小精灵自动：

7×24 接待 — 客户发消息进来，AI 秒回（知识库优先，查不到再调 OpenAI）
无感采集意向 — 对话中自动提取 8 类信息：国家/产品/数量/预算/时间/身份/诉求/紧急度
智能评分 — 0-100 分三档（高/中/低意向），自动打标签
自动转人工 — 6 种触发条件（报价/付款/物流/投诉/大额/要求人工），避免错失大客户
Web 管理面板 — 仪表盘/客户列表/产品库/知识库/设置，一个浏览器全搞定

快速启动

pip install fastapi uvicorn httpx openai python-multipart

# 编辑 references/bot_config.json 填入 API Key
python scripts/wa_kefu_server.py --port 8765

打开 http://localhost:8765 即可使用管理面板。

功能一览

| 模块 | 说明 | |------|------| | Webhook 接收 | Meta Cloud API + Twilio 双通道 | | AI 自动回复 | 知识库优先匹配 → 查不到调 OpenAI → 全不通走多语言智能兜底 | | 多语言 | 自动检测 15+ 语种（英/西/葡/法/阿/中/日/韩/俄/泰/越/印尼/德/意/土）| | 意向采集 | 30 个国家/城市关键词 + 多语言家具产品词 + 数量/预算/紧急度正则 | | 客户评分 | 0-100 分自动分层 + 自动标签（询价/高预算/紧急/批发/代理等）| | 转人工 | 6 种条件自动触发 + 手动转接 API | | 管理面板 | 仪表盘/客户/产品/对话/知识库/设置 | | 数据存储 | SQLite，自带家具行业种子数据（10 产品 + 5 客户 + 对话）|

管理面板页面

| 页面 | 功能 | |------|------| | 仪表盘 | 客户总数/高意向/今日消息/待转人工/产品分类统计 | | 客户列表 | 搜索/筛选/分页，查看意向评分和标签 | | 客户详情 | 8 类意向信息 + 完整聊天记录 + 手动发消息 + 标成交 | | 产品库 | 家具产品（沙发/餐桌/床/衣柜/办公桌等）| | 知识库 | FAQ 新增/编辑/删除，多语言多类型 | | 设置 | WhatsApp 通道/AI 模型/Temperature |

API 端点

| 端点 | 说明 | |------|------| | GET / | Web 管理面板 | | GET /api/health | 健康检查 | | GET /api/stats | 统计数据 | | GET /api/customers | 客户列表（分页/搜索/筛选）| | GET /api/customers/{wa_id} | 客户详情 + 对话 | | PATCH /api/customers/{wa_id}/deal | 更新成交状态 | | POST /api/customers/{wa_id}/message | 人工发送消息 | | GET /api/products | 产品列表 | | GET/POST/PUT/DELETE /api/knowledge | 知识库 CRUD | | POST /api/settings | 保存配置 | | GET/POST /api/v1/webhook/whatsapp/meta | Meta Webhook | | POST /api/v1/webhook/whatsapp/twilio | Twilio Webhook |

配置文件

编辑 references/bot_config.json：

{
  "whatsapp_channel": "meta",
  "meta_token": "你的 Meta Token",
  "meta_phone_number_id": "你的 Phone Number ID",
  "meta_verify_token": "cs-elf-verify",
  "openai_api_key": "sk-xxx",
  "openai_model": "gpt-4o-mini",
  "ai_temperature": 0.3
}

转人工触发条件

| 条件 | 触发关键词 | |------|-----------| | 索要正式报价 | proforma invoice, quotation sheet, PI | | 付款/发货咨询 | payment, shipping, delivery, freight, pago, envio | | 客户投诉 | complaint, refund, return, quality bad, 投诉 | | 要求转人工 | talk to human, manager, 转人工 | | 大额采购 | bulk order, container, 大货 | | AI 无法回答 | 知识库无匹配 + OpenAI 不可用时 |

技术栈

Python 3.10+ / FastAPI / Uvicorn
SQLite（零配置，开箱即用）
OpenAI API（可选，不通时走知识库+智能兜底）
单文件部署（wa_kefu_server.py 含全部逻辑+管理面板 HTML）

适用场景

外贸家具出口（已预置家具产品和 FAQ）
跨境电商客服（修改知识库即可适配其他品类）
WhatsApp 销售线索自动筛选和评分

References

| File | Description | |------|-------------| | references/bot_config.json | Configuration template (API keys, WhatsApp channel, model) | | references/knowledge_base.json | FAQ knowledge base (13 entries, multilingual keywords) | | references/requirements.txt | Python dependencies | | references/intent-extraction-technique.md | Multilingual intent extraction architecture & scoring algorithm | | references/deployment-pitfalls.md | Common deployment issues (BOM, WSL, port conflicts, OpenAI 403) |

Common Pitfalls

依赖未装：首次运行前 pip install fastapi uvicorn httpx openai python-multipart
Token 安全：bot_config.json 含敏感信息，勿提交 Git
公网访问：开发用 ngrok，生产需 HTTPS
OpenAI 被墙：国内使用需配置 openai_base_url 中转地址，或依赖知识库兜底
端口冲突：默认 8765，--port 可改
PowerShell 写 JSON 带 BOM：用 Python pathlib.Path.write_bytes() 写配置文件，不要用 Set-Content -Encoding UTF8（会加 BOM 导致 json.JSONDecodeError）
后台 terminal 走 WSL bash：启动 Windows Python 服务器须用 cmd.exe /c "python ..." 包裹，否则路径被 WSL 篡改
家具关键词必须含复数："bookshelf" 匹配不到 "bookshelves"，每个产品关键词需同时包含单复数形式
产品提取须在数量提取之前：FURNITURE_KW 字典匹配先于 fallback 正则 (?:need)\s+(.+?)，否则整句被吃掉
正则替换的双反斜杠陷阱：用 Python 脚本 patch .py 文件中的正则时，\\s 在嵌套字符串中会变成 \\\\s（字面量），编译不报错但永远不匹配。用 write_file 写独立脚本而非 python -c