TSP智能助手 (TSP Assistant)

基于大语言模型的智能客服系统，专为TSP（Telematics Service Platform）设计

🚀 项目特色

🧠 智能Agent架构

• 多工具集成: 知识库搜索、工单管理、数据分析、通知推送等10+工具
• 智能规划: 基于目标驱动的任务规划和执行
• 自主学习: 从用户反馈中持续优化响应质量
• 实时监控: 主动监控系统状态和异常情况
• 模块化重构: Flask蓝图架构，将1953行单文件重构为模块化蓝图，提升可维护性
• 代码优化: 降低运行风险，提升代码质量和可扩展性

💬 智能对话系统

• 实时通信: WebSocket支持，毫秒级响应
• 上下文理解: 多轮对话记忆和上下文关联
• VIN识别: 自动识别车辆VIN码并获取实时数据
• 知识库集成: 基于TF-IDF和余弦相似度的智能检索
• 语义理解: 使用sentence-transformers进行深度语义相似度计算

📊 数据驱动分析

• 真实数据: 基于数据库的真实性能趋势分析
• 多维度统计: 工单、预警、满意度、性能指标
• 可视化展示: Chart.js图表，直观的数据呈现
• 系统监控: 实时CPU、内存、健康状态监控

🔧 企业级管理

• 多环境部署: 开发、测试、生产环境隔离
• 版本控制: 完整的版本管理和变更日志
• 热更新: 支持前端文件热更新，无需重启服务
• 自动备份: 更新前自动备份，支持一键回滚
• 飞书集成: 支持飞书多维表格数据同步和管理
• 数据库架构: MySQL主数据库 + SQLite备份系统，双重保障
• 权限管理: 工单分发和权限管理，支持模块化权限控制

🏗️ 系统架构

整体架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端界面      │    │   后端服务      │    │   数据存储      │
│                 │    │                 │    │                 │
│ • 仪表板        │◄──►│ • Flask API     │◄──►│ • MySQL DB      │
│ • 智能对话      │    │ • WebSocket     │    │   (主数据库)    │
│ • Agent管理     │    │ • 蓝图架构      │    │ • SQLite备份    │
│ • 数据分析      │    │ • Agent核心     │    │ • Redis缓存     │
│ • 飞书同步      │    │ • LLM集成       │    │ • 知识库        │
│ • 备份管理      │    │ • 备份系统      │    │ • 工单系统      │
└─────────────────┘    └─────────────────┘    │ • 车辆数据      │
                                │              └─────────────────┘
                                ▼
                    ┌─────────────────┐
                    │   监控系统      │
                    │                 │
                    │ • Prometheus    │
                    │ • Grafana       │
                    │ • Nginx代理     │
                    └─────────────────┘

模块化架构

src/
├── web/                    # Web层
│   ├── app.py             # Flask主应用（674行）
│   ├── blueprints/         # 模块化蓝图
│   │   ├── alerts.py      # 预警管理
│   │   ├── workorders.py  # 工单管理
│   │   ├── conversations.py # 对话管理
│   │   ├── knowledge.py   # 知识库管理
│   │   ├── monitoring.py  # 监控管理
│   │   └── system.py      # 系统管理
│   └── websocket_server.py # WebSocket服务
├── agent/                  # Agent层
│   ├── agent_core.py      # Agent核心
│   ├── tool_manager.py    # 工具管理
│   └── planner.py         # 任务规划
├── core/                   # 核心层
│   ├── database.py        # 数据库管理
│   ├── models.py          # 数据模型
│   └── backup_manager.py  # 备份管理
├── integrations/          # 集成层
│   ├── feishu_client.py   # 飞书客户端
│   └── workorder_sync.py  # 工单同步
└── knowledge_base/        # 知识库层
    └── knowledge_manager.py # 知识管理

🎯 核心功能

1. 智能对话 💬

• 多轮对话: 支持上下文关联的连续对话
• VIN识别: 自动识别车辆VIN并获取实时数据
• 知识库检索: 智能匹配相关技术文档和解决方案
• 工单创建: 对话中直接创建和关联工单

2. Agent管理 🤖

• 工具管理: 10+内置工具，支持自定义工具注册
• 执行监控: 实时监控Agent任务执行状态和日志
• 性能统计: 工具使用频率和成功率分析
• 智能规划: 基于目标的任务分解和执行
• 状态管理: 完整的Agent状态跟踪（IDLE、PLANNING、EXECUTING等）

3. 工单系统 📋

• AI建议生成: 基于知识库和工单描述智能生成处理建议
• 语义相似度评估: 使用sentence-transformers进行深度语义相似度计算
• 智能入库策略: AI准确率<90%时优先使用人工描述，≥95%自动审批
• 人工审核流程: 支持人工输入和AI建议对比，灵活选择最佳方案
• 处理过程记录: 完整的工单处理历史记录，支持追溯和优化
• 知识库自动更新: 高相似度建议自动入库，持续优化知识库质量
• 工单分发管理: 支持模块化分发（TBOX、OTA等），权限管理

4. 知识库管理 📚

• 多格式支持: TXT、PDF、DOC、DOCX、MD文件
• 智能提取: 自动从文档中提取Q&A对
• 向量化检索: TF-IDF + 余弦相似度搜索
• 质量验证: 支持知识条目验证和置信度设置
• 批量管理: 支持批量导入、导出和删除操作
• 使用统计: 跟踪知识条目使用频率，优化检索结果

5. 数据分析 📊

• 实时趋势: 基于真实数据库的性能趋势分析
• 多维度统计: 工单、预警、满意度、AI准确率等关键指标
• 系统健康: CPU、内存、响应时间监控
• 可视化展示: Chart.js图表，直观的数据呈现
• Token监控: LLM Token使用情况统计和优化建议
• AI性能监控: AI建议准确率、响应时间等性能指标

6. 系统设置 ⚙️

• API管理: 支持多种LLM提供商配置（OpenAI、通义千问等）
• 统一配置: 集中管理LLM、飞书、AI准确率等配置
• 模型参数: 温度、最大令牌数等参数调节
• 端口配置: Web服务和WebSocket端口管理
• 日志级别: 灵活的日志级别控制
• 数据库状态: 实时监控MySQL和SQLite数据库状态

7. 飞书集成 📱

• 多维表格同步: 自动同步飞书多维表格数据
• 灵活字段映射: 智能映射飞书字段到本地数据库，支持自定义映射规则
• 实时更新: 支持增量同步和全量同步
• 数据预览: 同步前预览数据，确保准确性
• 统一管理: 飞书功能集成到主仪表板，无需独立页面
• 工单扩展: 支持12+飞书字段扩展，包括来源、模块、责任人等

🛠️ 技术栈

后端技术

• Python 3.11+: 核心开发语言
• Flask 2.3+: Web框架和API服务，采用蓝图架构实现模块化
• SQLAlchemy 2.0+: ORM数据库操作，支持MySQL和SQLite
• WebSocket: 实时通信支持，毫秒级响应
• psutil: 系统资源监控
• Redis: 缓存和会话管理（可选）
• Pandas: 数据处理和分析

前端技术

• Bootstrap 5: UI框架
• Chart.js: 数据可视化
• JavaScript ES6+: 前端逻辑
• WebSocket: 实时通信客户端

AI/ML技术

• 大语言模型: 支持OpenAI、通义千问等多种LLM提供商
• TF-IDF: 文本向量化和特征提取
• 余弦相似度: 传统语义相似度计算（备用方案）
• Sentence-Transformers: 深度语义相似度计算，准确率更高
• Agent框架: 智能任务规划和执行
• Transformers: 预训练模型支持（可选）
• AI准确率优化: 智能判断AI建议质量，优先使用高质量内容入库

部署运维

• Docker: 容器化部署
• Docker Compose: 多服务编排
• Nginx: 反向代理和静态文件服务
• Prometheus: 监控数据收集
• Grafana: 监控仪表板
• MySQL 8.0: 主数据库
• Redis 7: 缓存服务

🚀 快速开始

环境要求

Docker部署（推荐）

• Docker 20.10+
• Docker Compose 2.0+
• 4GB+ 可用内存
• 10GB+ 可用磁盘空间

本地部署

• Python 3.11+
• Node.js 16+ (可选，用于前端构建)
• MySQL 8.0+ 或 SQLite
• Redis 7+ (可选)
• Git

🐳 Docker部署（推荐）

1. 克隆项目

git clone http://jeason.online:3000/zhaojie/assist.git
cd assist

2. 一键启动所有服务

# 使用部署脚本
chmod +x scripts/docker_deploy.sh
./scripts/docker_deploy.sh start

# 或直接使用docker-compose
docker-compose up -d

3. 访问系统

• TSP助手: http://localhost:5000
• Nginx代理: http://localhost
• Prometheus监控: http://localhost:9090
• Grafana仪表板: http://localhost:3000 (admin/admin123456)

4. 服务管理

# 查看服务状态
./scripts/docker_deploy.sh status

# 查看日志
./scripts/docker_deploy.sh logs tsp-assistant

# 停止服务
./scripts/docker_deploy.sh stop

# 重启服务
./scripts/docker_deploy.sh restart

💻 本地部署

1. 克隆项目

git clone http://jeason.online:3000/zhaojie/assist.git
cd assist

2. 安装依赖

pip install -r requirements.txt

3. 初始化数据库

# 初始化数据库表结构和初始数据
python init_database.py

# 或创建管理员用户
python create_admin_user.py

4. 启动服务

python start_dashboard.py

5. 访问系统

• 打开浏览器访问: http://localhost:5000
• WebSocket服务: ws://localhost:8765
• 默认端口: 5000 (可在系统设置中修改)

Windows快速启动

# 双击运行
快速启动.bat

📖 使用指南

基础操作

1. 智能对话

   • 在"智能对话"页面输入问题
   • 系统自动检索知识库并生成回答
   • 支持VIN码识别和车辆数据查询
   • 支持多轮对话，保持上下文关联

2. 工单管理

   • 创建工单并获取AI建议（基于知识库和工单描述）
   • 人工输入解决方案
   • 系统使用sentence-transformers自动评估语义相似度
   • AI准确率≥95%自动审批，<90%优先使用人工描述
   • 审批后自动入库，持续优化知识库质量

3. 知识库维护

   • 手动添加Q&A对
   • 上传文档自动提取知识（支持多种格式）
   • 设置置信度和验证状态
   • 批量导入导出和删除操作

4. 系统监控

   • 查看实时性能趋势（基于真实数据库）
   • 监控系统健康状态（CPU、内存、响应时间）
   • 管理预警和通知
   • 监控Token使用和AI性能指标

高级功能

1. Agent工具管理

   • 查看工具使用统计
   • 注册自定义工具
   • 监控执行历史

2. 数据分析

   • 多维度数据统计
   • 自定义时间范围
   • 导出分析报告

3. 系统配置

   • API和模型参数配置
   • 端口和日志级别设置
   • 环境变量管理

🔄 部署与更新

多环境部署

# 开发环境
python scripts/update_manager.py auto-update --source . --environment development

# 测试环境
python scripts/update_manager.py auto-update --source . --environment staging

# 生产环境
python scripts/update_manager.py auto-update --source . --environment production

版本管理

# 更新版本号
python version.py increment --type minor

# 添加变更日志
python version.py changelog --message "新功能描述"

# 创建发布标签
python version.py tag --message "Release v1.3.0"

热更新

# 热更新（无需重启）
python scripts/update_manager.py hot-update --source ./new_version --environment production

# 自动更新（智能选择）
python scripts/update_manager.py auto-update --source ./new_version --environment production

📊 系统监控

健康检查

• API状态: /api/health
• 服务监控: 自动健康检查和故障恢复
• 性能指标: 响应时间、吞吐量、错误率

日志管理

• 应用日志: logs/tsp_assistant.log
• 访问日志: Nginx访问日志
• 错误追踪: 详细的错误堆栈信息

🔧 配置说明

Docker环境变量

# 数据库配置
DATABASE_URL=mysql+pymysql://tsp_user:tsp_password@mysql:3306/tsp_assistant?charset=utf8mb4
REDIS_URL=redis://redis:6379/0

# LLM配置（通过config/llm_config.py统一管理）
LLM_PROVIDER=openai  # 或 qwen, 其他支持的提供商
LLM_API_KEY=your_api_key
LLM_MODEL=gpt-3.5-turbo  # 或通义千问模型名称

# 服务配置
SERVER_PORT=5000
WEBSOCKET_PORT=8765
LOG_LEVEL=INFO
TZ=Asia/Shanghai

# AI准确率配置（可选）
AI_AUTO_APPROVE_THRESHOLD=0.95
AI_USE_HUMAN_THRESHOLD=0.90

统一配置管理

系统采用统一配置管理器，配置优先级：

1. config/unified_config.json - 统一配置文件（推荐）
2. config/llm_config.py - LLM配置
3. 环境变量 - Docker部署时使用
4. 系统设置界面 - 运行时动态配置

Docker服务配置

主要服务

• tsp-assistant: 主应用服务 (端口: 5000, 8765)
• mysql: MySQL数据库 (端口: 3306)
• redis: Redis缓存 (端口: 6379)
• nginx: 反向代理 (端口: 80, 443)

监控服务

• prometheus: 监控数据收集 (端口: 9090)
• grafana: 监控仪表板 (端口: 3000)

数据卷

• mysql_data: MySQL数据持久化
• redis_data: Redis数据持久化
• prometheus_data: Prometheus数据持久化
• grafana_data: Grafana配置和数据持久化

配置文件

• config/llm_config.py: LLM客户端配置（统一配置管理器）
• config/unified_config.json: 统一配置文件（LLM、飞书、AI准确率等）
• config/integrations_config.json: 飞书集成配置
• config/ai_accuracy_config.py: AI准确率阈值配置
• config/field_mapping_config.json: 飞书字段映射配置
• nginx.conf: Nginx反向代理配置
• monitoring/prometheus.yml: Prometheus监控配置
• init.sql: 数据库初始化脚本
• init_database.py: 数据库初始化Python脚本（推荐使用）
• docker-compose.yml: Docker服务编排配置
• Dockerfile: 应用镜像构建配置

🤝 贡献指南

开发流程

1. Fork项目到个人仓库
2. 创建功能分支: git checkout -b feature/new-feature
3. 提交更改: git commit -m "Add new feature"
4. 推送分支: git push origin feature/new-feature
5. 创建Pull Request

代码规范

• Python代码遵循PEP 8规范
• JavaScript使用ES6+语法
• 提交信息使用约定式提交格式
• 新功能需要添加相应的测试

📝 更新日志

v2.0.0 (2025-09-22) - Docker环境全面升级

• 🐳 Docker环境重构: 升级到Python 3.11，优化镜像构建
• 🐳 多服务编排: MySQL 8.0 + Redis 7 + Nginx + Prometheus + Grafana
• 🐳 监控系统: 集成Prometheus监控和Grafana仪表板
• 🐳 安全增强: 非root用户运行，数据卷隔离
• 🐳 部署脚本: 一键部署脚本，支持启动/停止/重启/清理
• 🔧 知识库搜索修复: 简化搜索算法，提升检索准确率
• 🔧 批量删除优化: 修复外键约束和缓存问题
• 🔧 日志编码修复: 解决中文乱码问题
• 📊 可视化增强: 修复预警、性能、满意度图表显示
• 📚 文档更新: 完整的Docker部署和使用指南
• 🧠 AI准确率优化: 集成sentence-transformers进行语义相似度计算
• 🏗️ 模块化重构: Flask蓝图架构，代码模块化，提升可维护性

v1.4.0 (2025-09-19)

• ✅ 飞书集成功能：支持飞书多维表格数据同步
• ✅ 页面功能合并：飞书同步页面合并到主仪表板
• ✅ 数据库架构优化：扩展工单表字段，支持飞书数据
• ✅ 代码重构优化：大文件拆分，降低运行风险
• ✅ 字段映射完善：智能映射飞书字段到本地数据库
• ✅ 数据库初始化改进：集成字段迁移到初始化流程

v1.3.0 (2025-09-17)

• ✅ 数据库架构优化：MySQL主数据库+SQLite备份系统
• ✅ 工单详情API修复：解决数据库会话管理问题
• ✅ 备份管理系统：自动备份MySQL数据到SQLite
• ✅ 数据库状态监控：实时监控MySQL和SQLite状态
• ✅ 备份管理API：支持数据备份和恢复操作

v1.2.0 (2025-09-16)

• ✅ 系统设置扩展：API管理、模型参数配置、端口管理
• ✅ 真实数据分析：修复性能趋势图表显示问题
• ✅ 工单AI建议功能：智能生成处理建议
• ✅ 知识库搜索优化：提升检索准确率
• ✅ Agent管理改进：工具使用统计和自定义工具

v1.1.0 (2025-09-16)

• ✅ 工单AI建议功能
• ✅ 知识库搜索优化
• ✅ Agent管理改进

v1.0.0 (2024-01-01)

• ✅ 初始版本发布

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

🔧 故障排除

Docker部署问题

常见问题

1. 端口冲突

# 检查端口占用
netstat -tulpn | grep :5000
# 修改docker-compose.yml中的端口映射

2. 内存不足

# 检查Docker资源使用
docker stats
# 增加Docker内存限制或关闭其他服务

3. 数据库连接失败

# 检查MySQL服务状态
docker-compose logs mysql
# 等待数据库完全启动（约30秒）

4. 权限问题

# 给脚本添加执行权限
chmod +x scripts/docker_deploy.sh
# 检查文件权限
ls -la scripts/

日志查看

# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f tsp-assistant
docker-compose logs -f mysql
docker-compose logs -f redis

服务重启

# 重启特定服务
docker-compose restart tsp-assistant

# 重启所有服务
docker-compose down && docker-compose up -d

性能优化

Docker资源限制

# 在docker-compose.yml中添加资源限制
services:
  tsp-assistant:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.0'

数据库优化

-- MySQL性能优化
SET GLOBAL innodb_buffer_pool_size = 1G;
SET GLOBAL max_connections = 200;

📞 支持与联系

• 项目地址: http://jeason.online:3000/zhaojie/assist
• 问题反馈: 请在Issues中提交问题
• 功能建议: 欢迎提交Feature Request
• Docker问题: 请提供docker-compose logs输出

🙏 致谢

感谢所有为项目做出贡献的开发者和用户！

---

TSP智能助手 - 让车辆服务更智能，让客户体验更美好！ 🚗✨