# 天网 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`