电商客服 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 等 |
快速开始
# 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/ 目录）
独立运行
python -m image.perspective_fix <图片路径或URL> [--debug] [--skip-step1] [--skip-step3]
环境配置 (.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
运行方式
# 启动主程序（客服机器人）
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 中配置：
{
"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 识别意图/情绪，否则关键词 |
| 多轮记忆 | 重启后从数据库加载近期对话，补充上下文 |
| 个性化 | 按性格（爽快/砍价/纠结）调整语气，按价格敏感度调整报价策略 |
| 主动预测 | 批量潜力客户主动推打包价，老客爽快直接推成交 |
注意事项
- 需要轻简软件运行在
ws://127.0.0.1:9528 - 转接格式：
话术|[转移会话],分组{group_id},无原因，分组 ID 由config/transfer_groups.json按店铺映射 - Gemini 使用西风代理接口，需配置对应 API Key
- Qwen 高清增强使用 RunningHub ComfyUI 工作流，需配置
api_key（service_qwen.py） - 图片处理结果保存在
results/目录（可通过RESULT_IMAGE_DIR环境变量修改） - 美图、矢量化 Tool 需对应服务可用；缺失依赖（如 aiofiles）时 Tool 会返回友好提示