# TSP智能助手完整文档 ## 📋 目录 - [项目概述](#项目概述) - [系统架构](#系统架构) - [核心功能](#核心功能) - [技术栈](#技术栈) - [安装部署](#安装部署) - [配置说明](#配置说明) - [使用指南](#使用指南) - [API接口](#api接口) - [数据库设计](#数据库设计) - [开发指南](#开发指南) - [故障排除](#故障排除) - [更新日志](#更新日志) --- ## 🚀 项目概述 TSP智能助手是一个基于大语言模型的智能客服系统，专为TSP（Telematics Service Provider）车辆服务提供商设计。系统集成了智能对话、工单管理、知识库、数据分析、飞书集成等核心功能。 ### 核心特性 - **智能Agent架构**: 多工具集成，智能规划，自主学习 - **实时对话系统**: WebSocket支持，上下文理解，VIN识别 - **数据驱动分析**: 真实数据统计，可视化展示，系统监控 - **企业级管理**: 多环境部署，版本控制，热更新，自动备份 - **飞书集成**: 支持飞书多维表格数据同步和管理 - **AI准确率优化**: 智能判断AI建议质量，优先使用高质量内容入库 --- ## 🏗️ 系统架构 ### 整体架构 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ 前端界面 │ │ 后端服务 │ │ 数据存储 │ │ │ │ │ │ │ │ • 仪表板 │◄──►│ • Flask API │◄──►│ • MySQL DB │ │ • 智能对话 │ │ • WebSocket │ │ • 知识库 │ │ • Agent管理 │ │ • Agent核心 │ │ • 工单系统 │ │ • 数据分析 │ │ • LLM集成 │ │ • 车辆数据 │ │ • 飞书同步 │ │ • 备份系统 │ │ • SQLite备份 │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ### 模块化设计 - **Web层**: Flask蓝图架构，模块化API设计 - **业务层**: Agent核心、对话管理、工单处理 - **数据层**: MySQL主库 + SQLite备份，ORM映射 - **集成层**: 飞书API、LLM服务、监控系统 --- ## 🎯 核心功能 ### 1. 智能对话系统 💬 - **多轮对话**: 支持上下文关联的连续对话 - **VIN识别**: 自动识别车辆VIN并获取实时数据 - **知识库检索**: 基于TF-IDF和余弦相似度的智能检索 - **工单创建**: 对话中直接创建和关联工单 ### 2. Agent管理系统 🤖 - **工具管理**: 10+内置工具，支持自定义工具注册 - **执行监控**: 实时监控Agent任务执行状态 - **性能统计**: 工具使用频率和成功率分析 - **智能规划**: 基于目标的任务分解和执行 ### 3. 工单管理系统 📋 - **AI建议生成**: 基于知识库生成工单处理建议 - **人工审核**: 支持人工输入和AI建议对比 - **语义相似度**: 使用sentence-transformers进行准确度评估 - **智能入库**: AI准确率<90%时优先使用人工描述入库 - **知识库更新**: 高相似度建议自动入库 ### 4. 知识库管理 📚 - **多格式支持**: TXT、PDF、DOC、DOCX、MD文件 - **智能提取**: 自动从文档中提取Q&A对 - **向量化检索**: TF-IDF + 余弦相似度搜索 - **质量验证**: 支持知识条目验证和置信度设置 ### 5. 数据分析系统 📊 - **实时趋势**: 基于真实数据的性能趋势分析 - **多维度统计**: 工单、预警、满意度等关键指标 - **系统健康**: CPU、内存、响应时间监控 - **可视化展示**: 丰富的图表和仪表板 ### 6. 飞书集成系统 📱 - **多维表格同步**: 自动同步飞书多维表格数据 - **字段映射**: 智能映射飞书字段到本地数据库 - **实时更新**: 支持增量同步和全量同步 - **数据预览**: 同步前预览数据，确保准确性 ### 7. 系统设置管理 ⚙️ - **API管理**: 支持多种LLM提供商配置 - **模型参数**: 温度、最大令牌数等参数调节 - **端口配置**: Web服务和WebSocket端口管理 - **日志级别**: 灵活的日志级别控制 --- ## 🛠️ 技术栈 ### 后端技术 - **Python 3.8+**: 核心开发语言 - **Flask**: Web框架和API服务 - **SQLAlchemy**: ORM数据库操作 - **WebSocket**: 实时通信支持 - **psutil**: 系统资源监控 ### 前端技术 - **Bootstrap 5**: UI框架 - **Chart.js**: 数据可视化 - **JavaScript ES6+**: 前端逻辑 - **WebSocket**: 实时通信客户端 ### AI/ML技术 - **大语言模型**: 支持OpenAI、通义千问等 - **sentence-transformers**: 语义相似度计算 - **TF-IDF**: 文本向量化 - **余弦相似度**: 语义相似度计算 - **Agent框架**: 智能任务规划 ### 部署运维 - **Docker**: 容器化部署 - **Nginx**: 反向代理和静态文件服务 - **Systemd**: 服务管理 - **Git**: 版本控制 --- ## 🚀 安装部署 ### 环境要求 - Python 3.8+ - Node.js 16+ (可选，用于前端构建) - Git - MySQL 8.0+ ### 安装步骤 1. **克隆项目** ```bash git clone http://jeason.online:3000/zhaojie/assist.git cd assist ``` 2. **安装依赖** ```bash pip install -r requirements.txt ``` 3. **配置数据库** ```bash # 创建MySQL数据库 mysql -u root -p CREATE DATABASE tsp_assistant CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` 4. **初始化数据库** ```bash python init_database.py ``` 5. **启动服务** ```bash python start_dashboard.py ``` 6. **访问系统** - 打开浏览器访问: `http://localhost:5000` - 默认端口: 5000 (可在系统设置中修改) ### Windows快速启动 ```cmd # 双击运行 快速启动.bat ``` --- ## ⚙️ 配置说明 ### 环境变量 ```bash # 数据库配置 DATABASE_URL=mysql+pymysql://user:password@host:port/database # LLM配置 LLM_PROVIDER=openai LLM_API_KEY=your_api_key LLM_MODEL=gpt-3.5-turbo # 服务配置 SERVER_PORT=5000 WEBSOCKET_PORT=8765 LOG_LEVEL=INFO ``` ### 配置文件结构 ``` config/ ├── llm_config.py # LLM客户端配置 ├── integrations_config.json # 飞书集成配置 ├── ai_accuracy_config.py # AI准确率配置 └── README.md # 配置说明文档 ``` ### 飞书集成配置 ```json { "feishu": { "app_id": "cli_a8b50ec0eed1500d", "app_secret": "ccxkE7ZCFQZcwkkM1rLy0ccZRXYsT2xK", "app_token": "XXnEbiCmEaMblSs6FDJcFCqsnIg", "table_id": "tblnl3vJPpgMTSiP", "status": "active" }, "system": { "sync_limit": 10, "ai_suggestions_enabled": true, "auto_sync_interval": 0 } } ``` ### AI准确率配置 ```python # 默认配置 auto_approve_threshold = 0.95 # 自动审批阈值 use_human_resolution_threshold = 0.90 # 使用人工描述阈值 manual_review_threshold = 0.80 # 人工审核阈值 ``` --- ## 📖 使用指南 ### 基础操作 #### 1. 智能对话 1. 在"智能对话"页面输入问题 2. 系统自动检索知识库并生成回答 3. 支持VIN码识别和车辆数据查询 #### 2. 工单管理 1. 创建工单并获取AI建议 2. 输入人工处理描述 3. 系统自动计算语义相似度 4. 根据相似度决定入库策略 #### 3. 知识库维护 1. 手动添加Q&A对 2. 上传文档自动提取知识 3. 设置置信度和验证状态 #### 4. 飞书数据同步 1. 配置飞书应用凭证 2. 在主仪表板"飞书同步"标签页 3. 测试连接并执行数据同步 ### 高级功能 #### 1. Agent工具管理 - 查看工具使用统计 - 注册自定义工具 - 监控执行历史 #### 2. 数据分析 - 多维度数据统计 - 自定义时间范围 - 导出分析报告 #### 3. 系统配置 - API和模型参数配置 - 端口和日志级别设置 - 环境变量管理 --- ## 🔌 API接口 ### 工单管理API ```http POST /api/workorders/{id}/ai-suggestion POST /api/workorders/{id}/human-resolution POST /api/workorders/{id}/approve-to-knowledge GET /api/workorders POST /api/workorders PUT /api/workorders/{id} DELETE /api/workorders/{id} ``` ### 知识库API ```http GET /api/knowledge POST /api/knowledge PUT /api/knowledge/{id} DELETE /api/knowledge/{id} POST /api/knowledge/search POST /api/knowledge/upload ``` ### 对话API ```http POST /api/chat/session GET /api/chat/session/{id} DELETE /api/chat/session/{id} POST /api/chat/message ``` ### Agent管理API ```http GET /api/agent/status POST /api/agent/tools/execute POST /api/agent/tools/register GET /api/agent/tools/stats ``` --- ## 🗄️ 数据库设计 ### 核心表结构 #### work_orders (工单表) ```sql CREATE TABLE work_orders ( id INT PRIMARY KEY AUTO_INCREMENT, order_id VARCHAR(50) UNIQUE NOT NULL, title VARCHAR(200) NOT NULL, description TEXT NOT NULL, category VARCHAR(100) NOT NULL, priority VARCHAR(20) NOT NULL, status VARCHAR(20) NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, resolution TEXT, satisfaction_score FLOAT, -- 飞书集成字段 feishu_record_id VARCHAR(100), source VARCHAR(50), module VARCHAR(100), created_by VARCHAR(100), wilfulness VARCHAR(100), date_of_close DATETIME, vehicle_type VARCHAR(100), vin_sim VARCHAR(50), app_remote_control_version VARCHAR(100), hmi_sw VARCHAR(100), parent_record VARCHAR(100), has_updated_same_day VARCHAR(50), operating_time VARCHAR(100) ); ``` #### work_order_suggestions (工单建议表) ```sql CREATE TABLE work_order_suggestions ( id INT PRIMARY KEY AUTO_INCREMENT, work_order_id INT NOT NULL, ai_suggestion TEXT, human_resolution TEXT, ai_similarity FLOAT, approved BOOLEAN DEFAULT FALSE, use_human_resolution BOOLEAN DEFAULT FALSE, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, FOREIGN KEY (work_order_id) REFERENCES work_orders(id) ); ``` #### knowledge_entries (知识库表) ```sql CREATE TABLE knowledge_entries ( id INT PRIMARY KEY AUTO_INCREMENT, question TEXT NOT NULL, answer TEXT NOT NULL, category VARCHAR(100), confidence_score FLOAT DEFAULT 0.5, usage_count INT DEFAULT 0, is_active BOOLEAN DEFAULT TRUE, is_verified BOOLEAN DEFAULT FALSE, verified_by VARCHAR(100), verified_at DATETIME, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ); ``` --- ## 👨‍💻 开发指南 ### 项目结构 ``` tsp-assistant/ ├── src/ # 源代码 │ ├── agent/ # Agent核心模块 │ ├── analytics/ # 数据分析模块 │ ├── config/ # 配置模块 │ ├── core/ # 核心模块 │ ├── dialogue/ # 对话模块 │ ├── integrations/ # 集成模块 │ ├── knowledge_base/ # 知识库模块 │ ├── utils/ # 工具模块 │ ├── vehicle/ # 车辆数据模块 │ └── web/ # Web应用模块 ├── config/ # 配置文件 ├── scripts/ # 脚本文件 ├── uploads/ # 上传文件 ├── requirements.txt # 依赖文件 ├── init_database.py # 数据库初始化 └── start_dashboard.py # 启动脚本 ``` ### 代码规范 - **Python**: 遵循PEP 8规范 - **JavaScript**: 使用ES6+语法 - **提交信息**: 使用约定式提交格式 - **文档**: 新功能需要添加相应的文档 ### 开发流程 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 --- ## 🚨 故障排除 ### 常见问题 #### 1. 数据库连接失败 ```bash # 检查数据库服务状态 systemctl status mysql # 检查连接配置 python -c "from src.core.database import db_manager; print(db_manager.test_connection())" ``` #### 2. 飞书集成问题 - 检查飞书应用权限配置 - 验证app_token和table_id是否正确 - 确认网络连接和API访问权限 #### 3. AI建议生成失败 - 检查LLM API配置 - 验证知识库数据完整性 - 查看应用日志 #### 4. 数据库字段缺失 ```bash # 运行数据库迁移 python init_database.py # 手动添加字段 mysql -u root -p tsp_assistant ALTER TABLE work_order_suggestions ADD COLUMN use_human_resolution BOOLEAN DEFAULT FALSE; ``` ### 日志位置 - **应用日志**: `logs/tsp_assistant.log` - **访问日志**: Nginx访问日志 - **错误追踪**: 详细的错误堆栈信息 ### 性能优化 - **数据库索引**: 为常用查询字段添加索引 - **缓存策略**: 使用Redis缓存热点数据 - **异步处理**: 耗时操作使用异步处理 - **连接池**: 配置数据库连接池 --- ## 📝 更新日志 ### v1.4.0 (2025-09-19) - ✅ 飞书集成功能：支持飞书多维表格数据同步 - ✅ 页面功能合并：飞书同步页面合并到主仪表板 - ✅ 数据库架构优化：扩展工单表字段，支持飞书数据 - ✅ 代码重构优化：大文件拆分，降低运行风险 - ✅ 字段映射完善：智能映射飞书字段到本地数据库 - ✅ 数据库初始化改进：集成字段迁移到初始化流程 - ✅ AI准确率优化：AI准确率<90%时优先使用人工描述入库 - ✅ 语义相似度计算：使用sentence-transformers提升准确度 ### v1.3.0 (2025-09-17) - ✅ 数据库架构优化：MySQL主数据库+SQLite备份系统 - ✅ 工单详情API修复：解决数据库会话管理问题 - ✅ 备份管理系统：自动备份MySQL数据到SQLite - ✅ 数据库状态监控：实时监控MySQL和SQLite状态 - ✅ 备份管理API：支持数据备份和恢复操作 ### v1.2.0 (2025-09-16) - ✅ 系统设置扩展：API管理、模型参数配置、端口管理 - ✅ 真实数据分析：修复性能趋势图表显示问题 - ✅ 工单AI建议功能：智能生成处理建议 - ✅ 知识库搜索优化：提升检索准确率 - ✅ Agent管理改进：工具使用统计和自定义工具 --- ## 📄 许可证 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 ## 📞 支持与联系 - **项目地址**: http://jeason.online:3000/zhaojie/assist - **问题反馈**: 请在Issues中提交问题 - **功能建议**: 欢迎提交Feature Request ## 🙏 致谢 感谢所有为项目做出贡献的开发者和用户！ --- **TSP智能助手** - 让车辆服务更智能，让客户体验更美好！ 🚗✨