147 lines
4.9 KiB
Markdown
Executable File
147 lines
4.9 KiB
Markdown
Executable File
# 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 并行处理 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 安装依赖
|
||
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
|
||
```
|
||
|
||
### 健康检查
|
||
|
||
```bash
|
||
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`。
|
||
|
||
---
|
||
|
||
## 消息处理流程
|
||
|
||
1. **WebSocket 接收** → 千牛原始消息
|
||
2. **适配器转换** → `StandardMessage`（统一格式）
|
||
3. **Orchestrator 过滤** → 订单/SKU 静默入库、心跳过滤、商家回复入库
|
||
4. **防抖合并** → 2 秒窗口内多条消息合并为一条
|
||
5. **冷却检查** → 转接后 120 秒内直接安抚，不调 AI
|
||
6. **AI 思考** → PydanticAI Agent 调用工具、生成回复
|
||
7. **转接截获** → 工具返回转接指令时直接发送，不经 AI 二次加工
|
||
8. **乱码清理** → 过滤 `<think>`、内部标记等泄露内容
|
||
9. **发送回复** → 通过 WebSocket 回复客户，同时入库
|