AI 客服系统
基于 PydanticAI 的智能客服，对接千牛 WebSocket，自动接待、收图、转接设计师。
架构概览
客户消息 (千牛)
↓
WebSocket Client → QianniuAdapter (协议转换)
↓
Orchestrator (防抖/去重/冷却/路由)
↓
CustomerServiceBrain (PydanticAI Agent)
├── lookup_chat_history_tool → 查询历史记录
├── transfer_to_human_tool → 转接设计师
└── check_order_status_tool → 订单查询
↓
QianniuAdapter → WebSocket → 回复客户
核心功能
| 功能 | 说明 |
|---|---|
| 智能接待 | 自动引导发图、问需求、转接设计师 |
| 历史记忆 | AI 可调用工具查询完整聊天历史，避免重复提问 |
| 自动转接 | 收到图片+需求后自动派单给在线设计师 |
| 转接冷却 | 转接后 120 秒内不再调用 AI，直接安抚 |
| 情绪识别 | 客户愤怒/投诉时自动转人工 |
| 消息防抖 | 合并短时间内的多条消息，避免重复回复 |
| 订单静默 | 订单通知/SKU 信息自动入库，不触发 AI |
| 时段感知 | 根据时间区分"没上班"/"下班了"/"暂时不在" |
| 图片分析 | 后台调用 Gemini 分析图片复杂度 |
| 日报统计 | 每日自动生成客服数据报告 |
| 多进程 | 支持多 Worker 并行处理 |
快速开始
# 安装依赖
pip install -r requirements.txt
# 配置环境变量
cp .env.example .env
# 编辑 .env 填入 API Key、数据库等配置
# 启动（WebSocket 客服模式）
python run.py
# 完整版（HTTP API + WebSocket）
python run.py --tianwang
# 多进程模式
python run.py --multi -w 4
# 仅 HTTP API
python run.py --api-only
健康检查
curl http://localhost:6060/api/health
项目结构
├── run.py # 统一入口
├── api/
│ └── http_server.py # HTTP API 服务
├── core/
│ ├── orchestrator.py # 总编排（防抖/去重/冷却/路由）
│ ├── pydantic_ai_agent_v2.py # AI 大脑（PydanticAI Agent）
│ ├── agent_tools.py # AI 工具（转接/查历史/查订单）
│ ├── schema.py # 数据模型（StandardMessage/Response）
│ ├── repository.py # 异步数据仓库
│ ├── skill_manager.py # 技能加载器
│ ├── engine.py # 业务逻辑兜底
│ ├── adapters/
│ │ └── qianniu_adapter.py # 千牛协议适配
│ ├── events/
│ │ └── event_bus.py # 异步事件总线
│ └── websocket_*.py # WebSocket 连接/发送/日志
├── db/
│ ├── chat_log_db.py # 聊天记录（SQLite/MySQL）
│ ├── customer_db.py # 客户档案
│ ├── image_tasks_db.py # 图片任务
│ └── task_db/ # 任务模型
├── services/
│ ├── dispatch_service.py # 设计师派单
│ ├── service_gemini.py # Gemini 图片分析
│ ├── service_image_analyzer.py # 图片复杂度分析
│ └── ... # 其他服务
├── skills/ # AI 技能定义（SKILL.md）
│ ├── customer-service/ # 客服核心技能
│ ├── owner-style/ # 店主风格
│ ├── pre-sales-skill/ # 售前
│ ├── after-sales-skill/ # 售后
│ ├── pricing-skill/ # 报价（排除出 prompt）
│ ├── risk-skill/ # 风控
│ └── style-skill/ # 语气风格
├── config/ # 配置文件
├── utils/ # 工具（日报/健康检查/API计费等）
└── scripts/ # 运维脚本
环境变量
| 变量 | 说明 |
|---|---|
OPENAI_API_KEY |
火山引擎 Ark API Key |
OPENAI_BASE_URL |
API 地址 |
OPENAI_MODEL |
对话模型 |
DB_TYPE |
数据库类型（sqlite / mysql） |
MYSQL_HOST/PORT/USER/PASSWORD/DATABASE |
MySQL 连接信息 |
WECHAT_WEBHOOK |
企业微信通知 Webhook |
MESSAGE_DEBOUNCE_SECONDS |
消息防抖时间（秒） |
DISPATCH_BASE_URL |
派单服务地址 |
完整配置见 .env.example。
消息处理流程
- WebSocket 接收 → 千牛原始消息
- 适配器转换 →
StandardMessage（统一格式） - Orchestrator 过滤 → 订单/SKU 静默入库、心跳过滤、商家回复入库
- 防抖合并 → 2 秒窗口内多条消息合并为一条
- 冷却检查 → 转接后 120 秒内直接安抚，不调 AI
- AI 思考 → PydanticAI Agent 调用工具、生成回复
- 转接截获 → 工具返回转接指令时直接发送，不经 AI 二次加工
- 乱码清理 → 过滤
<think>、内部标记等泄露内容 - 发送回复 → 通过 WebSocket 回复客户，同时入库