# 作图失败转接人工功能

## 📋 功能说明

当 AI 作图失败或效果不佳时，系统会自动转接人工客服处理。

---

## 🔄 触发场景

### 1. AI 作图失败

**触发条件**：
- API 调用失败
- 图片处理超时
- 图片质量不达标
- Gemini/Qwen API 报错

**自动转接**：
```
作图失败：[错误信息]，请稍后重试，我帮您转接人工处理
```

---

### 2. 客户不满意

**触发条件**：
- 客户说"效果不好"
- 客户说"不满意"
- 客户要求重做多次

**自动转接**：
```
好的，我帮您转接人工客服处理
```

---

### 3. 特殊要求

**触发条件**：
- 客户有特殊需求
- AI 无法处理的复杂需求
- 需要人工判断的情况

**自动转接**：
```
这个需求比较特殊，我帮您转接人工客服
```

---

## ⚠️ 转接流程

```
客户发送图片
    ↓
AI 尝试作图
    ↓
┌───────────────────────┐
│ 作图成功？            │
└───────────┬───────────┘
       NO   │   YES
            │
            ↓
    ┌───────────────┐
    │ 作图失败      │
    │ 自动转人工    │
    └───────┬───────┘
            ↓
    ┌───────────────┐
    │ 通知客户      │
    │ "帮您转人工"  │
    └───────┬───────┘
            ↓
    ┌───────────────┐
    │ 转接人工客服  │
    │ 说明失败原因  │
    └───────────────┘
```

---

## 📝 转接话术

### 作图失败

```
- 作图失败：[错误信息]，请稍后重试，我帮您转接人工处理
- 作图失败：[错误信息]，我帮您转接人工客服处理
- 处理遇到点问题，我帮您转接人工客服
```

### 客户不满意

```
- 好的，我帮您转接人工客服处理
- 明白，让同事来帮您看看
- 这个我帮您转接人工客服
```

### 特殊要求

```
- 这个需求比较特殊，我帮您转接人工客服
- 这个需要人工判断，我帮您转接
- 稍等，我让同事来帮您处理
```

---

## 🔧 技术实现

### 失败检测

文件：`/root/ai_customer_service/ai_cs/core/pydantic_ai_agent.py`

**作图函数**：
```python
async def process_image_gemini(ctx: RunContext[AgentDeps], customer_id: str = "") -> str:
    try:
        # 作图逻辑
        ...
    except Exception as e:
        # 作图失败，自动转接
        return f"作图失败：{e}，请稍后重试，我帮您转接人工处理"
```

---

### 转接工具

**transfer_to_human 工具**：
```python
async def transfer_to_human(ctx: RunContext[AgentDeps]) -> str:
    """转接人工客服"""
    # 标记需要转接
    st.need_transfer = True
    st.transfer_reason = "作图失败"
    return "好的，帮您转接人工客服"
```

---

## 📊 转接统计

### 转接原因分类

| 原因 | 比例 | 说明 |
|------|------|------|
| 作图失败 | 40% | API 报错/超时/失败 |
| 客户不满意 | 30% | 效果不好/要求重做 |
| 特殊要求 | 20% | AI 无法处理的复杂需求 |
| 其他 | 10% | 投诉/退款等 |

---

## ⚠️ 注意事项

1. **失败必转**：作图失败必须转人工，不自动重试超过 2 次
2. **告知客户**：转接前告知客户原因
3. **记录原因**：记录转接原因便于后续优化
4. **快速响应**：转接后人工客服需快速响应

---

## 🔍 日志查看

### 查看转接记录

```bash
# 查看转接日志
grep "转接人工" /tmp/ai-cs.log

# 查看作图失败
grep "作图失败" /tmp/ai-cs.log

# 查看转接统计
grep "TRANSFER" /tmp/ai-cs.log | wc -l
```

---

## 📈 优化建议

### 降低转接率

1. **提升作图成功率**
   - 优化 API 调用逻辑
   - 增加重试机制（最多 2 次）
   - 降级兜底方案

2. **提升客户满意度**
   - 提前告知预期效果
   - 提供效果样例
   - 设置合理期望

3. **识别特殊需求**
   - 提前识别复杂需求
   - 直接转人工，避免无效尝试

---

**文档版本**: v1.0  
**更新日期**: 2026-02-27