# 电商客服 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 会返回友好提示