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            # 健康检查

任务数据结构

{
  "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"
}

返回格式

{
  "code": 200,
  "message": "任务接收成功",
  "data": {
    "task_id": "TASK_20260226_001",
    "status": "pending"
  }
}

---

2️⃣ 任务调度系统 ✅

任务状态流转

pending → waiting → running → completed
                      ↓
                   failed

功能特性

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

---

3️⃣ 条件监听增强 ✅

触发条件类型

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 # 本文档

---

🚀 使用方法

启动天网协作版

cd /root/ai_customer_service/ai_cs

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

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

API 调用示例

1. 接收任务

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. 查询任务状态

curl http://localhost:5678/api/task/status/TASK_20260226_001

3. 取消任务

curl -X POST http://localhost:5678/api/task/cancel \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "TASK_20260226_001",
    "reason": "客户已退款"
  }'

---

📊 数据库表结构

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：

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：客户说"好的"后发送文件

天网下发任务:

{
  "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：客户付款后发送教程

天网下发任务:

{
  "task_id": "TASK_002",
  "type": "send_tutorial_after_payment",
  "customer": {"id": "customer_456"},
  "trigger": {"type": "customer_payment"},
  "action": {
    "type": "send_message",
    "message": "感谢购买！这是使用教程：..."
  }
}

---

场景 3：定时发送问候

天网下发任务:

{
  "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": "早上好！有什么可以帮您？"
  }
}

---

🔍 监控与日志

查看任务日志

journalctl -u ai-cs -f | grep "任务"

查询数据库

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';

统计信息

curl http://localhost:5678/api/task/stats

---

⚠️ 注意事项

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

---

🐛 故障排查

任务未触发

# 1. 检查任务状态
curl http://localhost:5678/api/task/status/TASK_ID

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

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

HTTP API 无法访问

# 1. 检查端口
netstat -tlnp | grep 5678

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

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

任务执行失败

# 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