tw/TIANWANG_INTEGRATION.md

# 天网 AI 客服协作系统 - 完整文档

## 📋 项目概述

**目标**: 实现天网（任务调度中心）与 AI 客服的协作，支持设计师在群里下发任务，AI 客服自动执行。

**协作流程**:
```
设计师（群里） → 天网（任务分析） → AI 客服（执行）
     ↑                              ↓
     └←←←←←←  结果反馈  ←←←←←←←←←←┘
```

---

## 🚀 已实现的功能

### 1️⃣ 任务接收接口 ✅

#### API 端点
```
POST   /api/task/receive      # 接收天网下发的任务
POST   /api/task/cancel       # 取消任务
GET    /api/task/status/:id   # 查询任务状态
GET    /api/task/list         # 任务列表
GET    /api/health            # 健康检查
```

#### 任务数据结构
```json
{
  "task_id": "TASK_20260226_001",
  "type": "send_file_after_reply",
  "customer": {
    "name": "小明",
    "id": "customer_123"
  },
  "trigger": {
    "type": "customer_reply",
    "keyword": "好的"
  },
  "action": {
    "type": "send_file",
    "file_url": "https://xxx.com/file.zip",
    "message": "这是您要的文件"
  },
  "priority": "normal",
  "timeout_hours": 24,
  "created_by": "设计师 lz"
}
```

#### 返回格式
```json
{
  "code": 200,
  "message": "任务接收成功",
  "data": {
    "task_id": "TASK_20260226_001",
    "status": "pending"
  }
}
```

---

### 2️⃣ 任务调度系统 ✅

#### 任务状态流转
```
pending → waiting → running → completed
                      ↓
                   failed
```

#### 功能特性
- ✅ 优先级队列（urgent > high > normal）
- ✅ 超时处理（默认 24 小时）
- ✅ 自动重试（最多 3 次）
- ✅ 状态持久化（SQLite）
- ✅ 天网回调通知

---

### 3️⃣ 条件监听增强 ✅

#### 触发条件类型
```python
TRIGGER_TYPES = {
    "customer_reply": "客户回复指定内容",
    "customer_keyword": "客户说某关键词",
    "customer_payment": "客户付款",
    "customer_order": "客户下单",
    "time_reach": "到达指定时间",
    "custom_event": "自定义事件"
}
```

#### 触发流程
```
收到客户消息 
  ↓
检查是否有匹配的任务
  ↓
触发任务执行
  ↓
自动回复客户
```

---

### 4️⃣ 文件/链接发送功能 🔄

- ✅ 消息发送（已实现）
- 🔄 文件发送（待接入轻简 API）
- 🔄 链接发送（已实现为基础消息）

---

## 📁 项目结构

```
ai_customer_service/ai_cs/
├── db/task_db/
│   ├── task_model.py      # 任务数据模型
│   └── tasks.db           # SQLite 数据库
├── core/
│   ├── task_scheduler.py  # 任务调度器
│   └── websocket_client.py # WebSocket 客户端（已增强）
├── api/
│   └── http_server.py     # HTTP API 服务器
├── scripts/
│   └── multi_process_launcher.py
├── run_with_tianwang.py   # 天网协作版启动器
└── TIANWANG_INTEGRATION.md # 本文档
```

---

## 🚀 使用方法

### 启动天网协作版

```bash
cd /root/ai_customer_service/ai_cs

# 方式 1：使用专用启动器
python3 run_with_tianwang.py

# 方式 2：使用 run.py（未来整合）
python3 run.py --tianwang
```

### API 调用示例

#### 1. 接收任务
```bash
curl -X POST http://localhost:5678/api/task/receive \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "TASK_20260226_001",
    "type": "send_file_after_reply",
    "customer": {
      "name": "小明",
      "id": "customer_123"
    },
    "trigger": {
      "type": "customer_reply",
      "keyword": "好的"
    },
    "action": {
      "type": "send_message",
      "message": "这是您要的文件"
    },
    "priority": "normal",
    "timeout_hours": 24,
    "created_by": "设计师 lz"
  }'
```

#### 2. 查询任务状态
```bash
curl http://localhost:5678/api/task/status/TASK_20260226_001
```

#### 3. 取消任务
```bash
curl -X POST http://localhost:5678/api/task/cancel \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "TASK_20260226_001",
    "reason": "客户已退款"
  }'
```

---

## 📊 数据库表结构

```sql
CREATE TABLE tasks (
    task_id TEXT PRIMARY KEY,
    type TEXT NOT NULL,
    customer_name TEXT,
    customer_id TEXT,
    trigger_type TEXT,
    trigger_keyword TEXT,
    trigger_keywords TEXT,  -- JSON array
    action_type TEXT,
    action_file_url TEXT,
    action_message TEXT,
    priority TEXT DEFAULT 'normal',
    timeout_hours INTEGER DEFAULT 24,
    status TEXT DEFAULT 'pending',
    retry_count INTEGER DEFAULT 0,
    max_retry INTEGER DEFAULT 3,
    created_at TEXT,
    created_by TEXT,
    triggered_at TEXT,
    completed_at TEXT,
    error_message TEXT,
    result TEXT  -- JSON
)
```

---

## 🔧 配置说明

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `HTTP_API_HOST` | HTTP 服务器地址 | 0.0.0.0 |
| `HTTP_API_PORT` | HTTP 服务器端口 | 5678 |
| `TASK_DB_PATH` | 任务数据库路径 | db/task_db/tasks.db |

### 天网回调配置

在 `core/task_scheduler.py` 中配置天网回调 URL：

```python
async def _notify_tianwang(self, task_id: str, status: str, error: str = None):
    async with httpx.AsyncClient() as client:
        await client.post(
            'http://tianwang-server/api/task/callback',  # ← 修改这里
            json={
                'task_id': task_id,
                'status': status,
                'error': error,
                'timestamp': datetime.now().isoformat()
            }
        )
```

---

## 📝 使用场景示例

### 场景 1：客户说"好的"后发送文件

**天网下发任务**:
```json
{
  "task_id": "TASK_001",
  "type": "send_file_after_reply",
  "customer": {"id": "customer_123"},
  "trigger": {"type": "customer_reply", "keyword": "好的"},
  "action": {
    "type": "send_file",
    "file_url": "https://xxx.com/file.zip",
    "message": "这是您要的文件"
  }
}
```

**流程**:
1. 客户在群里说"好的"
2. AI 客服检测到匹配任务
3. 自动发送文件给客户
4. 任务标记为 completed

---

### 场景 2：客户付款后发送教程

**天网下发任务**:
```json
{
  "task_id": "TASK_002",
  "type": "send_tutorial_after_payment",
  "customer": {"id": "customer_456"},
  "trigger": {"type": "customer_payment"},
  "action": {
    "type": "send_message",
    "message": "感谢购买！这是使用教程：..."
  }
}
```

---

### 场景 3：定时发送问候

**天网下发任务**:
```json
{
  "task_id": "TASK_003",
  "type": "send_greeting",
  "customer": {"id": "customer_789"},
  "trigger": {"type": "time_reach", "time": "2026-02-27 09:00:00"},
  "action": {
    "type": "send_message",
    "message": "早上好！有什么可以帮您？"
  }
}
```

---

## 🔍 监控与日志

### 查看任务日志
```bash
journalctl -u ai-cs -f | grep "任务"
```

### 查询数据库
```bash
sqlite3 /root/ai_customer_service/ai_cs/db/task_db/tasks.db

# 查看所有任务
SELECT task_id, status, created_at FROM tasks ORDER BY created_at DESC LIMIT 10;

# 查看失败任务
SELECT task_id, error_message FROM tasks WHERE status='failed';
```

### 统计信息
```bash
curl http://localhost:5678/api/task/stats
```

---

## ⚠️ 注意事项

1. **HTTP 端口**: 默认 5678，确保端口未被占用
2. **数据库路径**: 确保有写权限
3. **天网回调**: 需要配置正确的回调 URL
4. **任务超时**: 默认 24 小时，根据业务需求调整
5. **重试次数**: 默认 3 次，避免无限重试

---

## 🐛 故障排查

### 任务未触发
```bash
# 1. 检查任务状态
curl http://localhost:5678/api/task/status/TASK_ID

# 2. 查看日志
journalctl -u ai-cs -f | grep "任务触发"

# 3. 检查触发条件是否匹配
# 确认客户消息包含触发关键词
```

### HTTP API 无法访问
```bash
# 1. 检查端口
netstat -tlnp | grep 5678

# 2. 检查防火墙
firewall-cmd --list-ports

# 3. 重启服务
systemctl restart ai-cs
```

### 任务执行失败
```bash
# 1. 查看错误信息
curl http://localhost:5678/api/task/status/TASK_ID

# 2. 查看日志
journalctl -u ai-cs -f | grep "任务执行失败"

# 3. 手动重试
# 取消任务后重新下发
```

---

## 📞 技术支持

如有问题请联系：
- 文档：`/root/ai_customer_service/ai_cs/TIANWANG_INTEGRATION.md`
- 日志：`journalctl -u ai-cs -f`
- 数据库：`/root/ai_customer_service/ai_cs/db/task_db/tasks.db`