zhaojie
11eef49271
- 新增 .agents/summary/ 完整文档（架构、组件、接口、数据模型、流程、依赖） - 新增 AGENTS.md（AI 助手导航） - 更新 README.md - 修复 dashboard.html 租户模态框多余 </div> 导致保存按钮失效 - 更新 .gitignore 排除虚拟环境文件
131 lines
4.5 KiB
Markdown
131 lines
4.5 KiB
Markdown
# TSP 智能助手
|
||
|
||
AI 驱动的多租户客服与工单管理系统，支持飞书机器人、WebSocket 实时对话、知识库语义搜索。
|
||
|
||
## 功能概览
|
||
|
||
- **智能对话** — WebSocket 实时聊天 + 飞书机器人（长连接模式），按租户隔离知识库
|
||
- **工单管理** — 创建、编辑、删除、飞书多维表格双向同步，AI 生成处理建议
|
||
- **知识库** — TF-IDF + 可选 Embedding 语义搜索，支持文件导入、人工验证
|
||
- **多租户** — 数据按 tenant_id 隔离，每个租户独立的系统提示词和飞书群绑定
|
||
- **数据分析** — 工单趋势、预警统计、满意度分析，支持按租户筛选
|
||
- **预警系统** — 自定义规则、多级别预警、批量管理
|
||
- **Agent 模式** — ReAct 风格 LLM Agent，支持工具调度（知识搜索、车辆查询、飞书消息等）
|
||
- **系统管理** — 模块权限控制、流量/成本/安全配置、Token 监控
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
cp .env.example .env # 编辑填入 LLM API Key、飞书凭证等
|
||
python init_database.py
|
||
python start_dashboard.py
|
||
```
|
||
|
||
访问 http://localhost:5000，默认账号 `admin` / `admin123`。
|
||
|
||
## 系统架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Clients["客户端"]
|
||
Browser["浏览器 Dashboard"]
|
||
FeishuBot["飞书机器人"]
|
||
WSClient["WebSocket"]
|
||
end
|
||
|
||
subgraph App["应用层"]
|
||
Flask["Flask :5000"]
|
||
WS["WebSocket :8765"]
|
||
FeishuLC["飞书长连接"]
|
||
end
|
||
|
||
subgraph Services["业务层"]
|
||
DM["对话管理"]
|
||
KM["知识库"]
|
||
WOS["工单同步"]
|
||
Agent["ReAct Agent"]
|
||
end
|
||
|
||
subgraph Infra["基础设施"]
|
||
DB["SQLAlchemy"]
|
||
LLM["Qwen API"]
|
||
Cache["Redis"]
|
||
end
|
||
|
||
Clients --> App
|
||
App --> Services
|
||
Services --> Infra
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/
|
||
├── config/ # 配置管理（unified_config）
|
||
├── core/ # 基础设施（数据库、LLM、缓存、认证、ORM 模型）
|
||
├── dialogue/ # 对话管理（realtime_chat、dialogue_manager）
|
||
├── knowledge_base/ # 知识库（搜索、导入、验证）
|
||
├── analytics/ # 监控与分析（预警、Token、AI 成功率）
|
||
├── integrations/ # 外部集成（飞书客户端、工单同步）
|
||
├── agent/ # ReAct Agent（工具调度）
|
||
├── vehicle/ # 车辆数据管理
|
||
├── utils/ # 通用工具
|
||
└── web/ # Web 层
|
||
├── app.py # Flask 应用
|
||
├── blueprints/ # API 蓝图（16 个，每个领域一个文件）
|
||
├── service_manager.py # 懒加载服务注册
|
||
├── static/ # 前端资源 (JS/CSS)
|
||
└── templates/ # Jinja2 模板
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `SECRET_KEY` | Flask session 密钥 | 随机生成 |
|
||
| `DATABASE_URL` | 数据库连接串 | SQLite |
|
||
| `LLM_BASE_URL` | LLM API 地址 | DashScope |
|
||
| `LLM_API_KEY` | LLM API 密钥 | — |
|
||
| `LLM_MODEL` | 模型名称 | qwen-plus-latest |
|
||
| `FEISHU_APP_ID` | 飞书应用 ID | — |
|
||
| `FEISHU_APP_SECRET` | 飞书应用密钥 | — |
|
||
| `FEISHU_APP_TOKEN` | 飞书多维表格 App Token | — |
|
||
| `FEISHU_TABLE_ID` | 飞书多维表格 Table ID | — |
|
||
| `REDIS_HOST` | Redis 地址 | localhost |
|
||
| `REDIS_ENABLED` | 启用 Redis 缓存 | True |
|
||
| `EMBEDDING_ENABLED` | 启用 Embedding 语义搜索 | True |
|
||
| `EMBEDDING_MODEL` | Embedding 模型 | BAAI/bge-small-zh-v1.5 |
|
||
|
||
完整变量列表见 `.env.example`。
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|---|---|
|
||
| Web 框架 | Flask 3.x + Flask-CORS |
|
||
| ORM | SQLAlchemy 2.x (MySQL / SQLite) |
|
||
| 实时通信 | websockets (port 8765) |
|
||
| 缓存 | Redis 5.x + hiredis |
|
||
| LLM | Qwen/DashScope (OpenAI-compatible) |
|
||
| Embedding | sentence-transformers + BAAI/bge-small-zh-v1.5 (可选) |
|
||
| NLP | jieba + scikit-learn (TF-IDF) |
|
||
| 飞书 | lark-oapi 1.3.x |
|
||
| 认证 | JWT + SHA-256 |
|
||
|
||
## 数据库
|
||
|
||
- **开发**: SQLite (`data/tsp_assistant.db`)
|
||
- **生产**: MySQL via PyMySQL
|
||
- **核心表**: Tenant, WorkOrder, ChatSession, Conversation, KnowledgeEntry, Alert, Analytics, VehicleData, User
|
||
|
||
## 部署
|
||
|
||
- Docker + docker-compose (MySQL 8, Redis 7, Nginx, Prometheus, Grafana)
|
||
- Nginx 反向代理 (80/443 → 5000)
|
||
- 默认端口: Flask 5000, WebSocket 8765, Redis 6379, MySQL 3306
|
||
|
||
## 详细文档
|
||
|
||
完整技术文档见 `.agents/summary/` 目录，推荐从 `index.md` 开始阅读。
|