347 lines
13 KiB
Markdown
347 lines
13 KiB
Markdown
# 电商客服 AI 自动回复系统
|
||
|
||
## 项目概述
|
||
|
||
基于 PydanticAI 的淘宝修图店客服系统，支持自动回复、智能报价、转接人工、客户画像等功能。
|
||
付款后自动触发图片处理流水线，完成后通过邮件将结果发送给客户。
|
||
|
||
---
|
||
|
||
## 最近更新
|
||
|
||
| 更新项 | 说明 |
|
||
|--------|------|
|
||
| **消息处理非阻塞** | 图片分析、Agent 回复改为后台任务，接收循环不阻塞，可同时处理多客户 |
|
||
| **同客户串行** | 按客户加锁，保证「发图→这个高清」等顺序，避免误判 |
|
||
| **并发限流** | agent_reply 最多 8 个并发，防止 API 打满 |
|
||
| **图片分析缓存** | 同一 URL 5 分钟内复用结果，节省视觉 API 调用 |
|
||
| **报价维度** | 平整度、含文字（小字加价）、含人脸、阴影，越平整越便宜 |
|
||
| **项目结构** | 主文件归类到 `core/`、`db/`、`image/`、`services/`、`mail/`、`utils/` 子目录 |
|
||
| **配置中心** | `config/config.py` 统一路径、常量，支持 `LOG_MAX_BYTES`、`IMAGE_QUEUE_*` 等 |
|
||
| **转接分组** | `config/transfer_groups.json` 店铺→分组映射 |
|
||
| **设计师派单** | SQLite 存储，转人工时按需查询在线，轮询派单 |
|
||
| **健康检查** | 定时检测轻简连接，断线企微告警 |
|
||
| **日志轮转** | 按 10MB 切分，保留 7 份 |
|
||
| **图片队列** | 并发限制 2，高并发时排队 |
|
||
| **邮件重试** | 发送失败自动重试 1 次 |
|
||
| **Web 启动器** | `scripts/launcher_ui.py` 酷炫控制台，http://localhost:5679 |
|
||
| **矢量化/美图 Tool** | `vectorize_to_eps_tool`、`meitu_enhance_tool` |
|
||
| **客服对话增强** | 语义匹配、多轮记忆、个性化、主动预测 |
|
||
| **单元测试** | `tests/test_config.py`、`test_image_queue.py`、`test_health_check.py` 等 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 2. 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env 填入 API Key、邮件等
|
||
|
||
# 3. 启动（需轻简软件已运行在 ws://127.0.0.1:9528）
|
||
python run.py
|
||
```
|
||
|
||
---
|
||
|
||
## 功能列表
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 自动回复 | 收到消息自动回复，防抖合并连续短消息，后台处理不阻塞接收 |
|
||
| 售前分流 | 自动识别售前/售后阶段 |
|
||
| 智能报价 | 图片分析后按复杂度报价（10-30元，5的整数倍），平整度/文字/人脸/阴影影响价格 |
|
||
| 压价应对 | 只让价一次，记录历史让价次数 |
|
||
| 转接人工 | 退款/投诉/情绪激动自动转接 |
|
||
| 订单识别 | 自动识别系统订单消息，付款后触发作图 |
|
||
| 付款检测 | 催单时核查付款状态，未付款不误导客户 |
|
||
| 图片处理 | 透视矫正 + Qwen高清增强五步流水线 |
|
||
| 质检重试 | 视觉AI质检，不合格自动重试（最多2次）|
|
||
| 颜色匹配 | 类PS「匹配颜色」算法，修正AI处理后色差 |
|
||
| 边框裁切 | 自动检测任意颜色背景边并裁切 |
|
||
| 客户画像 | 自动提取邮箱/电话/微信/性格/价格敏感度 |
|
||
| 企微通知 | API异常/质检失败/订单金额异常推送企微 |
|
||
| SKILL.md | 支持技能文档动态加载 |
|
||
| 矢量化 | 图片转 EPS 矢量文件（独立 Tool）|
|
||
| 美图增强 | 画质增强（极速/标准/增强/HDR/人像）|
|
||
| Web 启动器 | 酷炫控制台一键启停客服机器人 |
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
D:\Terminator\
|
||
├── run.py # 项目入口（启动客服机器人）
|
||
├── core/ # 核心逻辑
|
||
│ ├── websocket_client.py # WebSocket 客户端（主程序，含防抖）
|
||
│ ├── pydantic_ai_agent.py# AI Agent 核心（含报价/风险/订单逻辑）
|
||
│ └── workflow.py # 工作流（付款触发 → 作图 → 发邮件）
|
||
├── db/ # 数据层
|
||
│ ├── customer_db.py # 客户画像数据库（SQLite）
|
||
│ ├── chat_log_db.py # 聊天记录数据库
|
||
│ └── designer_roster_db.py # 设计师派单（同一人不同店铺不同分组，轮询）
|
||
├── image/ # 图片处理
|
||
│ ├── image_analyzer.py # 图片分析（复杂度/风险/Gemini提示词）
|
||
│ ├── image_processor.py # 图片处理主模块（下载→透视→增强→质检）
|
||
│ ├── image_tools.py # 独立图片工具（去背景/透视/增强/裁边等）
|
||
│ ├── image_qa.py # 视觉AI质检（对比原图和结果，0-100分）
|
||
│ └── perspective_fix.py # 透视矫正五步流水线（独立可运行）
|
||
├── services/ # 外部服务
|
||
│ ├── service_gemini.py # Gemini API（去背景/增强）
|
||
│ ├── service_qwen.py # Qwen RunningHub API（高清增强）
|
||
│ ├── service_meitu.py # 美图 API（画质增强）
|
||
│ └── service_vectorizer.py # 矢量化服务（转 EPS）
|
||
├── mail/ # 邮件（避免与标准库 email 冲突）
|
||
│ ├── email_sender.py # 邮件发送（SMTP）
|
||
│ └── email_receiver.py # 邮件接收（IMAP 轮询）
|
||
├── utils/
|
||
│ ├── daily_summary.py # 日报推送
|
||
│ ├── service_base.py # 服务基类（矢量化等）
|
||
│ ├── intent_analyzer.py # 语义匹配（意图/情绪）
|
||
│ ├── image_queue.py # 图片处理队列
|
||
│ ├── health_check.py # 健康检查
|
||
│ └── designer_roster.py # 设计师在线（转人工时按需查询）
|
||
├── config/
|
||
│ ├── config.py # 配置中心（路径、常量）
|
||
│ └── transfer_groups.json # 店铺 acc_id → 转接分组 group_id 映射
|
||
├── scripts/ # 可执行脚本
|
||
│ ├── launcher_ui.py # Web 控制台（一键启停客服机器人）
|
||
│ ├── init_designer_roster.py # 设计师派单数据初始化
|
||
│ ├── chat_ui.py # 聊天记录 Web 查看器
|
||
│ └── chat_log_viewer.py # 聊天记录 CLI 查看器
|
||
├── tests/
|
||
│ ├── test_process.py # 图片处理流程测试
|
||
│ ├── test_config.py # 配置中心测试
|
||
│ ├── test_image_queue.py # 图片队列测试
|
||
│ └── test_health_check.py# 健康检查测试
|
||
├── archive/ # 归档（未用/旧版文件）
|
||
├── logs/ # 日志
|
||
├── results/ # 处理结果图片
|
||
└── .env # 环境配置
|
||
```
|
||
|
||
---
|
||
|
||
## 图片处理流水线（perspective_fix.py）
|
||
|
||
客户付款后自动运行，共五步：
|
||
|
||
```
|
||
原图
|
||
│
|
||
▼ Step 1 Gemini 去背景 → 纯白/纯色背景
|
||
│ ┗ 自动检测白色覆盖率，< 20% 则换强化提示词重试
|
||
│
|
||
▼ Step 2 OpenCV 轮廓检测 + 透视矫正
|
||
│ ┗ 三种策略：approxPolyDP → 凸包极值 → minAreaRect
|
||
│ ┗ 自动检测 Gemini 旋转问题并纠正方向
|
||
│
|
||
▼ Step 3 Qwen（RunningHub ComfyUI）高清增强
|
||
│ ┗ 失败时降级到 Gemini 简化提示词兜底
|
||
│
|
||
▼ Step 4 豆包视觉 AI 决策后处理
|
||
│ ┣ 颜色匹配（需要时）：LAB色彩空间 Reinhard 算法
|
||
│ │ ┗ 按颜色差异程度自动调整强度（明显80% / 轻微55%）
|
||
│ ┗ 背景边裁切（需要时）：自适应背景色检测，支持任意颜色边框
|
||
│ ┗ 从四角采样背景色，逐行/列扫描（非硬编码白色）
|
||
│
|
||
▼ 输出最终图片（results/ 目录）
|
||
```
|
||
|
||
### 独立运行
|
||
```bash
|
||
python -m image.perspective_fix <图片路径或URL> [--debug] [--skip-step1] [--skip-step3]
|
||
```
|
||
|
||
---
|
||
|
||
## 环境配置 (.env)
|
||
|
||
```env
|
||
# 火山引擎豆包 API
|
||
OPENAI_API_KEY=你的API Key
|
||
OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
|
||
OPENAI_MODEL=doubao-seed-2-0-lite-260215
|
||
VISION_MODEL=doubao-seed-2-0-mini-260215
|
||
|
||
# 邮件SMTP
|
||
SMTP_HOST=smtp.qq.com
|
||
SMTP_PORT=587
|
||
SMTP_USER=your_email@qq.com
|
||
SMTP_PASSWORD=your_smtp_password
|
||
SENDER_NAME=修图客服
|
||
|
||
# 企业微信群机器人 Webhook
|
||
WECHAT_WEBHOOK=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=你的key
|
||
|
||
# 质检配置
|
||
QA_PASS_SCORE=70 # 质检合格分（0-100）
|
||
PROCESS_MAX_RETRIES=2 # 最大重试次数
|
||
|
||
# 日报
|
||
SUMMARY_EMAIL= # 接收日报的邮箱，留空不发
|
||
SUMMARY_HOUR=23
|
||
SUMMARY_MINUTE=50
|
||
|
||
# 可选：语义匹配（embedding 意图/情绪，不配置则用关键词）
|
||
# EMBEDDING_MODEL=text-embedding-3-small
|
||
|
||
# 可选：美图画质增强（Tool 调用时需）
|
||
# MEITU_API_URL=http://your-meitu-api:port
|
||
|
||
# 可选：矢量化服务（Tool 调用时需）
|
||
# 矢量化服务 base_url 在 service_vectorizer.py 中默认配置
|
||
|
||
# 日志轮转（默认 10MB 切分，保留 7 份）
|
||
# LOG_MAX_BYTES=10
|
||
# LOG_BACKUP_COUNT=7
|
||
|
||
# 图片队列（默认并发 2，队列上限 20）
|
||
# IMAGE_QUEUE_MAX_CONCURRENT=2
|
||
# IMAGE_QUEUE_MAX_SIZE=20
|
||
|
||
# 健康检查（默认 60 秒）
|
||
# HEALTH_CHECK_INTERVAL=60
|
||
```
|
||
|
||
---
|
||
|
||
## 运行方式
|
||
|
||
```bash
|
||
# 启动主程序（客服机器人）
|
||
python run.py
|
||
|
||
# 不启用 AI（仅监听消息）
|
||
python run.py --no-agent
|
||
|
||
# Web 控制台（酷炫界面一键启停，含 Agent 开关）
|
||
python scripts/launcher_ui.py
|
||
# 访问 http://localhost:5679
|
||
|
||
# 单独测试图片处理流水线
|
||
python -m image.perspective_fix results/your_image.jpg --debug
|
||
|
||
# 测试完整流程（含付款触发）
|
||
python tests/test_process.py
|
||
|
||
# 运行单元测试
|
||
python tests/test_config.py
|
||
python tests/test_image_queue.py
|
||
python tests/test_health_check.py
|
||
|
||
# 聊天记录 Web UI
|
||
python scripts/chat_ui.py
|
||
# 访问 http://localhost:5678
|
||
|
||
# 聊天记录 CLI 查看
|
||
python scripts/chat_log_viewer.py # 列出所有客户
|
||
python scripts/chat_log_viewer.py <客户ID> # 查看某客户全部对话
|
||
python scripts/chat_log_viewer.py -s <关键词> # 全局搜索
|
||
python scripts/chat_log_viewer.py -t <客户ID> # 只看今天
|
||
python scripts/chat_log_viewer.py -l # 实时监听最新消息
|
||
```
|
||
|
||
---
|
||
|
||
## 报价逻辑
|
||
|
||
| 复杂度 | 价格区间 | 说明 |
|
||
|--------|----------|------|
|
||
| 简单 | 10-15 元 | 画面平整、无小字、无人脸、无阴影 |
|
||
| 一般 | 15-20 元 | 一般复杂度 |
|
||
| 复杂 | 20-25 元 | 细节偏多、有褶皱/小字/人脸/阴影 |
|
||
| 困难 | 25-30 元 | 非常复杂 |
|
||
|
||
**价格必须为 5 的整数倍**（10/15/20/25/30）
|
||
|
||
**报价维度（越平整越便宜）：**
|
||
- **平整度**：flat 便宜 → mild 中等 → rough 贵
|
||
- **含文字**：大字不加价，小字需精细保留则加价
|
||
- **含人脸**：有人脸加价
|
||
- **阴影**：有明显阴影需处理则加价
|
||
|
||
**风险等级：**
|
||
- `none`：直接报价
|
||
- `low`（含人脸）：报价 + 风险提示，说明人脸相似度约70-90%
|
||
- `high`（严重模糊/需打印/老照片）：必须先说明风险再报价
|
||
- `no`（无法处理）：告知客户换图，不报价
|
||
|
||
---
|
||
|
||
## 触发转接
|
||
|
||
发送以下关键词自动转接人工：
|
||
- `test`（测试）
|
||
- `我要退款` / `退货` / `投诉`
|
||
- 情绪激动
|
||
|
||
**店铺→分组映射**：不同店铺对应不同客服分组，相同客服在不同店铺的分组 ID 不同。在 `config/transfer_groups.json` 中配置：
|
||
|
||
```json
|
||
{
|
||
"default": "20252916034",
|
||
"店铺A_acc_id": "分组ID1",
|
||
"店铺B_acc_id": "分组ID2"
|
||
}
|
||
```
|
||
|
||
- `default`：未配置店铺时的默认分组
|
||
- 其他 key 为店铺 `acc_id`，value 为该店铺的转接分组 ID
|
||
|
||
**设计师派单（可选）**：SQLite 存储，同一设计师不同店铺不同 group_id。`python scripts/init_designer_roster.py example` 初始化。转人工时按需 GET `DESIGNER_ROSTER_API` 同步在线状态，无人在线时发企微「谁在线啊」。
|
||
|
||
---
|
||
|
||
## 客户画像字段
|
||
|
||
从对话自动提取并持久化：
|
||
|
||
| 字段 | 内容 |
|
||
|------|------|
|
||
| 联系方式 | 邮箱、手机、微信 |
|
||
| 消费记录 | 订单数、历史报价、最低接受价 |
|
||
| 性格标签 | 爽快/纠结/砍价/批量 |
|
||
| 图片偏好 | 处理类型、格式偏好、尺寸需求 |
|
||
| 最近图片 | URL、Gemini提示词、比例、透视状态 |
|
||
| 处理参数 | gemini_prompt、aspect_ratio、perspective |
|
||
|
||
数据库：`customer_db/customers.json`
|
||
|
||
---
|
||
|
||
## 已实现
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **config/config.py** | 配置中心，统一路径与常量 |
|
||
| **健康检查** | 定时检测轻简连接，断线时企微告警 |
|
||
| **日志轮转** | 按 10MB 切分，保留 7 份 |
|
||
| **图片队列** | 并发限制 2，队列上限 20，高并发时排队 |
|
||
| **单元测试** | `tests/test_*.py` |
|
||
| **客服对话增强** | 语义匹配、多轮记忆、个性化、主动预测 |
|
||
|
||
### 客服对话增强
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| **语义匹配** | 配置 `EMBEDDING_MODEL` 后用 embedding 识别意图/情绪，否则关键词 |
|
||
| **多轮记忆** | 重启后从数据库加载近期对话，补充上下文 |
|
||
| **个性化** | 按性格（爽快/砍价/纠结）调整语气，按价格敏感度调整报价策略 |
|
||
| **主动预测** | 批量潜力客户主动推打包价，老客爽快直接推成交 |
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. 需要轻简软件运行在 `ws://127.0.0.1:9528`
|
||
2. 转接格式：`话术|[转移会话],分组{group_id},无原因`，分组 ID 由 `config/transfer_groups.json` 按店铺映射
|
||
3. Gemini 使用西风代理接口，需配置对应 API Key
|
||
4. Qwen 高清增强使用 RunningHub ComfyUI 工作流，需配置 `api_key`（service_qwen.py）
|
||
5. 图片处理结果保存在 `results/` 目录（可通过 `RESULT_IMAGE_DIR` 环境变量修改）
|
||
6. 美图、矢量化 Tool 需对应服务可用；缺失依赖（如 aiofiles）时 Tool 会返回友好提示
|