feat: 完整功能部署 v1.0
新增功能: - 天网协作系统 (HTTP API 端口 6060) - 三种工作流 (查找图片/处理图片/转人工派单) - 图片任务数据库 (支持客户后续增加需求) - 图绘派单系统集成 (API: 8005) - 文字检测与加价 (60-80 元高价值订单) - 风险评估与接单判断 - 作图失败自动转人工 新增文档: - 项目功能汇总.md - 三种工作流功能说明.md - 文字加价功能说明.md - 风险评估功能说明.md - 图片任务数据库功能说明.md - 图绘派单系统集成说明.md - 作图失败转接人工说明.md - DEPLOYMENT.md - TIANWANG_INTEGRATION.md 核心修改: - core/pydantic_ai_agent.py - core/workflow.py - core/websocket_client.py - image/image_analyzer.py - services/service_tuhui_dispatch.py - db/image_tasks_db.py 版本：v1.0 日期：2026-02-28
This commit is contained in:
402
TIANWANG_INTEGRATION.md
Normal file
402
TIANWANG_INTEGRATION.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# 天网 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`
|
||||
|
||||
Reference in New Issue
Block a user