# 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 回复客户，同时入库