From 11eef4927136caf0203c258a2a4c5cb4ffe938d2 Mon Sep 17 00:00:00 2001 From: zhaojie <1710884619@qq.com> Date: Wed, 8 Apr 2026 23:26:17 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=BD=93=E7=B3=BB=20+=20=E4=BF=AE=E5=A4=8D?= =?UTF-8?q?=E7=A7=9F=E6=88=B7=E5=88=9B=E5=BB=BA=E6=A8=A1=E6=80=81=E6=A1=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 .agents/summary/ 完整文档（架构、组件、接口、数据模型、流程、依赖） - 新增 AGENTS.md（AI 助手导航） - 更新 README.md - 修复 dashboard.html 租户模态框多余 导致保存按钮失效 - 更新 .gitignore 排除虚拟环境文件 --- .agents/summary/architecture.md | 109 +++++++++++++++++++++++++ .agents/summary/codebase_info.md | 51 ++++++++++++ .agents/summary/components.md | 79 ++++++++++++++++++ .agents/summary/data_models.md | 136 +++++++++++++++++++++++++++++++ .agents/summary/dependencies.md | 90 ++++++++++++++++++++ .agents/summary/index.md | 56 +++++++++++++ .agents/summary/interfaces.md | 104 +++++++++++++++++++++++ .agents/summary/review_notes.md | 41 ++++++++++ .agents/summary/workflows.md | 127 +++++++++++++++++++++++++++++ .gitignore | 8 ++ AGENTS.md | 96 ++++++++++++++++++++++ README.md | 95 ++++++++++++++++++--- src/web/templates/dashboard.html | 1 - 13 files changed, 979 insertions(+), 14 deletions(-) create mode 100644 .agents/summary/architecture.md create mode 100644 .agents/summary/codebase_info.md create mode 100644 .agents/summary/components.md create mode 100644 .agents/summary/data_models.md create mode 100644 .agents/summary/dependencies.md create mode 100644 .agents/summary/index.md create mode 100644 .agents/summary/interfaces.md create mode 100644 .agents/summary/review_notes.md create mode 100644 .agents/summary/workflows.md create mode 100644 AGENTS.md diff --git a/.agents/summary/architecture.md b/.agents/summary/architecture.md new file mode 100644 index 0000000..54bc2c4 --- /dev/null +++ b/.agents/summary/architecture.md @@ -0,0 +1,109 @@ +# Architecture / 系统架构 + +## 整体架构 + +```mermaid +graph TB + subgraph Clients["客户端"] + Browser["浏览器 Dashboard"] + FeishuBot["飞书机器人"] + WSClient["WebSocket 客户端"] + end + + subgraph EntryPoints["入口层"] + Flask["Flask App :5000"] + WS["WebSocket Server :8765"] + FeishuLC["飞书长连接服务"] + end + + subgraph WebLayer["Web 层"] + Blueprints["16 个 Flask Blueprints"] + Decorators["装饰器: handle_errors, require_json, resolve_tenant_id, rate_limit"] + SM["ServiceManager (懒加载)"] + end + + subgraph BusinessLayer["业务层"] + DM["DialogueManager"] + RCM["RealtimeChatManager"] + KM["KnowledgeManager"] + WOS["WorkOrderSyncService"] + Agent["ReactAgent"] + AM["AnalyticsManager"] + AS["AlertSystem"] + end + + subgraph CoreLayer["基础设施层"] + DB["DatabaseManager (SQLAlchemy)"] + LLM["LLMClient (Qwen API)"] + Cache["CacheManager (Redis)"] + Auth["AuthManager (JWT)"] + Embed["EmbeddingClient (可选)"] + end + + subgraph External["外部服务"] + QwenAPI["Qwen/DashScope API"] + FeishuAPI["飞书 API"] + RedisServer["Redis"] + Database["MySQL / SQLite"] + end + + Browser --> Flask + WSClient --> WS + FeishuBot --> FeishuLC + + Flask --> Blueprints + Blueprints --> Decorators + Blueprints --> SM + SM --> BusinessLayer + + WS --> RCM + FeishuLC --> DM + + DM --> LLM + DM --> KM + RCM --> DM + Agent --> LLM + KM --> Embed + WOS --> FeishuAPI + + DB --> Database + LLM --> QwenAPI + Cache --> RedisServer +``` + +## 架构模式 + +### Singleton Managers +核心服务均为单例模式：`DatabaseManager`, `ServiceManager`, `UnifiedConfig`。通过 `get_config()` / `db_manager` 全局访问。 + +### Blueprint-per-Domain +每个功能域一个 Flask Blueprint，共 16 个： +`workorders`, `alerts`, `knowledge`, `conversations`, `chat`, `agent`, `tenants`, `auth`, `analytics`, `monitoring`, `system`, `feishu_sync`, `feishu_bot`, `vehicle`, `core`, `test` + +### Service Manager with Lazy Loading +`ServiceManager` 提供线程安全的懒初始化。Blueprint 通过它获取业务服务实例，避免循环导入和启动时的重量级初始化。 + +### Decorator-Driven API +通用横切关注点通过装饰器实现： +- `@handle_errors` — 统一异常处理 +- `@require_json` — JSON 请求验证 +- `@resolve_tenant_id` — 从请求中提取 tenant_id +- `@rate_limit` — 频率限制 +- `@cache_response` — 响应缓存 + +### Multi-Tenant by Convention +所有核心表包含 `tenant_id` 字段，查询时按 tenant_id 过滤实现数据隔离。 + +## 线程模型 + +```mermaid +graph LR + Main["主线程: Flask App"] + T1["守护线程: WebSocket Server"] + T2["守护线程: 飞书长连接"] + + Main --> T1 + Main --> T2 +``` + +`start_dashboard.py` 在主线程运行 Flask，WebSocket 和飞书长连接分别在守护线程中运行。 diff --git a/.agents/summary/codebase_info.md b/.agents/summary/codebase_info.md new file mode 100644 index 0000000..9ec8d74 --- /dev/null +++ b/.agents/summary/codebase_info.md @@ -0,0 +1,51 @@ +# Codebase Info + +## 基本信息 + +- **项目名称**: TSP 智能助手 (TSP Assistant) +- **语言**: Python 3.11+ +- **框架**: Flask 3.x + SQLAlchemy 2.x + WebSocket +- **代码风格**: 变量名英文，注释/UI/日志中文 +- **数据库**: SQLAlchemy ORM（开发用 SQLite，生产用 MySQL via PyMySQL） +- **入口文件**: `start_dashboard.py` + +## 技术栈 + +| 层级 | 技术 | +|---|---| +| Web | Flask 3.x + Flask-CORS | +| ORM | SQLAlchemy 2.x | +| 实时通信 | `websockets` (port 8765) | +| 缓存 | Redis 5.x + hiredis | +| LLM | OpenAI-compatible API (Qwen/通义千问 via DashScope) | +| Embedding | `sentence-transformers` + `BAAI/bge-small-zh-v1.5` (可选) | +| NLP | jieba (分词) + scikit-learn (TF-IDF) | +| 飞书 SDK | `lark-oapi` 1.3.x (长连接模式) | +| 认证 | JWT (`pyjwt`) + SHA-256 | +| 监控 | psutil | + +## 目录结构概览 + +``` +src/ +├── config/ # UnifiedConfig 单例，从 .env 加载 +├── core/ # 数据库、LLM、缓存、认证、ORM 模型 +├── dialogue/ # 对话管理、实时聊天 +├── knowledge_base/ # 知识库 CRUD、搜索、导入 +├── analytics/ # 监控、预警、Token 统计 +├── integrations/ # 飞书客户端、工单同步 +├── agent/ # ReAct Agent（工具调度） +├── vehicle/ # 车辆数据管理 +├── utils/ # 通用工具 +└── web/ # Flask 应用层 + ├── app.py # 应用工厂 + 中间件 + ├── service_manager.py # 懒加载服务注册 + ├── decorators.py # 通用装饰器 + ├── blueprints/ # 按领域划分的 API 蓝图 (16 个) + ├── static/ # 前端资源 + └── templates/ # Jinja2 模板 +``` + +## 启动流程 + +`start_dashboard.py` → 设置日志 → 检查数据库 → 启动 WebSocket 线程 → 启动飞书长连接线程 → 启动 Flask 应用 diff --git a/.agents/summary/components.md b/.agents/summary/components.md new file mode 100644 index 0000000..4d1ba73 --- /dev/null +++ b/.agents/summary/components.md @@ -0,0 +1,79 @@ +# Components / 核心组件 + +## 业务组件 + +### DialogueManager (`src/dialogue/dialogue_manager.py`) +对话管理核心。处理用户消息，调用 LLM 生成回复，根据意图自动创建工单。连接知识库检索和 LLM 调用。 + +### RealtimeChatManager (`src/dialogue/realtime_chat.py`) +实时聊天管理器。管理 WebSocket 会话，维护 `ChatMessage` 数据结构，协调 DialogueManager 处理消息流。 + +### KnowledgeManager (`src/knowledge_base/knowledge_manager.py`) +知识库管理。支持 CRUD、TF-IDF 关键词搜索、可选 Embedding 语义搜索、文件导入、人工验证。已验证条目在检索时获得更高置信度。 + +### WorkOrderSyncService (`src/integrations/workorder_sync.py`) +工单同步服务。实现本地工单与飞书多维表格的双向同步。定义 `WorkOrderStatus` 和 `WorkOrderPriority` 枚举。 + +### ReactAgent (`src/agent/react_agent.py`) +ReAct 风格 LLM Agent。注册工具（知识搜索、车辆查询、分析、飞书消息），通过思考-行动-观察循环完成复杂任务。 + +### AnalyticsManager (`src/analytics/analytics_manager.py`) +数据分析管理器。工单趋势、预警统计、满意度分析，支持按租户筛选。 + +### AlertSystem (`src/analytics/alert_system.py`) +预警系统。自定义 `AlertRule`，支持多级别（`AlertLevel`）和多类型（`AlertType`）预警，批量管理。 + +## 基础设施组件 + +### DatabaseManager (`src/core/database.py`) +数据库管理单例。封装 SQLAlchemy session 管理，提供 `get_session()` 上下文管理器。支持 SQLite（开发）和 MySQL（生产）。 + +### LLMClient (`src/core/llm_client.py`) +LLM 调用客户端。封装 OpenAI-compatible API 调用（默认 Qwen/DashScope），支持流式和非流式响应。 + +### UnifiedConfig (`src/config/unified_config.py`) +配置单例。从 `.env` 加载环境变量，映射到 typed dataclasses： +`DatabaseConfig`, `LLMConfig`, `ServerConfig`, `FeishuConfig`, `AIAccuracyConfig`, `EmbeddingConfig`, `RedisConfig` + +### AuthManager (`src/core/auth_manager.py`) +认证管理。JWT token 生成/验证，SHA-256 密码哈希。 + +### ServiceManager (`src/web/service_manager.py`) +服务注册中心。线程安全的懒加载，Blueprint 通过它获取业务服务实例。 + +## 集成组件 + +### FeishuService (`src/integrations/feishu_service.py`) +飞书 API 客户端。获取 tenant_access_token，发送消息，操作多维表格。 + +### FeishuLongConnService (`src/integrations/feishu_longconn_service.py`) +飞书事件订阅长连接服务。接收飞书机器人消息事件，转发给 DialogueManager 处理。 + +## Web 层组件 + +### Flask Blueprints (`src/web/blueprints/`) + +```mermaid +graph TD + subgraph API["API Blueprints"] + WO["workorders — 工单 CRUD + AI 建议"] + AL["alerts — 预警管理"] + KN["knowledge — 知识库管理"] + CV["conversations — 对话历史"] + CH["chat — HTTP 聊天 + 会话管理"] + AG["agent — Agent 模式交互"] + TN["tenants — 租户管理"] + AU["auth — 登录/注册/JWT"] + AN["analytics — 数据分析导出"] + MO["monitoring — Token/AI 监控"] + SY["system — 系统配置/备份/优化"] + FS["feishu_sync — 飞书同步配置"] + FB["feishu_bot — 飞书 Webhook 事件"] + VH["vehicle — 车辆数据"] + CO["core — 监控规则/批量操作"] + TE["test — API 连接测试"] + end +``` + +### WebSocketServer (`src/web/websocket_server.py`) +独立 WebSocket 服务器（port 8765）。处理客户端连接，转发消息给 RealtimeChatManager。 diff --git a/.agents/summary/data_models.md b/.agents/summary/data_models.md new file mode 100644 index 0000000..3ce5842 --- /dev/null +++ b/.agents/summary/data_models.md @@ -0,0 +1,136 @@ +# Data Models / 数据模型 + +## ORM 模型 (`src/core/models.py`) + +所有模型继承 SQLAlchemy `Base`，核心表均包含 `tenant_id` 字段用于多租户隔离。 + +```mermaid +erDiagram + Tenant ||--o{ WorkOrder : "tenant_id" + Tenant ||--o{ ChatSession : "tenant_id" + Tenant ||--o{ KnowledgeEntry : "tenant_id" + Tenant ||--o{ Alert : "tenant_id" + Tenant ||--o{ Analytics : "tenant_id" + + WorkOrder ||--o{ Conversation : "work_order_id" + WorkOrder ||--o{ WorkOrderProcessHistory : "work_order_id" + WorkOrder ||--o{ WorkOrderSuggestion : "work_order_id" + + ChatSession ||--o{ Conversation : "session_id" + + Tenant { + int id PK + string tenant_id UK + string name + text description + bool is_active + text config "JSON: feishu, system_prompt" + } + + WorkOrder { + int id PK + string tenant_id FK + string order_id UK + string title + text description + string category + string priority + string status + string feishu_record_id "飞书记录ID" + string assignee + text ai_suggestion + string assigned_module + string module_owner + string vin_sim "车架号" + } + + ChatSession { + int id PK + string tenant_id FK + string session_id UK + string source "websocket/api/feishu_bot" + } + + Conversation { + int id PK + string tenant_id FK + int work_order_id FK + string session_id FK + string role "user/assistant/system" + text content + } + + KnowledgeEntry { + int id PK + string tenant_id FK + string question + text answer + string category + bool is_verified + float confidence_score + } + + Alert { + int id PK + string tenant_id FK + string level + string type + text message + bool is_resolved + } + + VehicleData { + int id PK + string vehicle_id + string vin + text data "JSON" + } + + Analytics { + int id PK + string tenant_id FK + string metric_type + float value + text details "JSON" + } + + User { + int id PK + string username UK + string password_hash + string role "admin/user" + } + + WorkOrderProcessHistory { + int id PK + int work_order_id FK + string action + text details + } + + WorkOrderSuggestion { + int id PK + int work_order_id FK + text suggestion + float confidence + } +``` + +## 配置 Dataclasses (`src/config/unified_config.py`) + +| Dataclass | 关键字段 | +|-----------|---------| +| `DatabaseConfig` | `url` | +| `LLMConfig` | `api_key`, `base_url`, `model`, `temperature`, `max_tokens`, `timeout` | +| `ServerConfig` | `host`, `port`, `websocket_port`, `debug`, `log_level` | +| `FeishuConfig` | `app_id`, `app_secret`, `app_token`, `table_id` | +| `AIAccuracyConfig` | `auto_approve_threshold`, `manual_review_threshold` | +| `EmbeddingConfig` | `enabled`, `model`, `dimension`, `similarity_threshold` | +| `RedisConfig` | `host`, `port`, `db`, `password`, `pool_size`, `default_ttl`, `enabled` | + +## 业务枚举 + +- `WorkOrderStatus`: 工单状态流转 +- `WorkOrderPriority`: 工单优先级 +- `AlertLevel`: 预警级别 +- `AlertType`: 预警类型 diff --git a/.agents/summary/dependencies.md b/.agents/summary/dependencies.md new file mode 100644 index 0000000..a89acaa --- /dev/null +++ b/.agents/summary/dependencies.md @@ -0,0 +1,90 @@ +# Dependencies / 外部依赖 + +## 核心依赖 + +| 包 | 版本 | 用途 | +|---|---|---| +| flask | 3.0.3 | Web 框架 | +| flask-cors | 5.0.0 | 跨域支持 | +| sqlalchemy | 2.0.32 | ORM | +| pymysql | 1.1.1 | MySQL 驱动 | +| websockets | 15.0.1 | WebSocket 服务器 | +| redis | 5.0.1 | 缓存客户端 | +| hiredis | 2.3.2 | Redis 高性能解析器 | + +## LLM / NLP + +| 包 | 版本 | 用途 | +|---|---|---| +| jieba | 0.42.1 | 中文分词 | +| scikit-learn | 1.4.2 | TF-IDF 向量化 | +| numpy | 1.26.4 | 数值计算 | + +## 飞书集成 + +| 包 | 版本 | 用途 | +|---|---|---| +| lark-oapi | 1.3.5 | 飞书 SDK（事件订阅 2.0，长连接模式） | + +## 数据处理 + +| 包 | 版本 | 用途 | +|---|---|---| +| pandas | 2.2.2 | 数据分析 | +| openpyxl | 3.1.5 | Excel 读写 | +| ujson | 5.10.0 | 高性能 JSON | + +## 安全 / 认证 + +| 包 | 版本 | 用途 | +|---|---|---| +| pyjwt | 2.9.0 | JWT token | +| bcrypt | 4.2.1 | 密码哈希 | +| cryptography | 43.0.1 | 加密支持 | + +## 数据验证 + +| 包 | 版本 | 用途 | +|---|---|---| +| pydantic | 2.9.2 | 数据验证 | +| marshmallow | 3.23.3 | 序列化/反序列化 | + +## 监控 / 工具 + +| 包 | 版本 | 用途 | +|---|---|---| +| psutil | 5.9.8 | 系统监控 | +| python-dotenv | 1.0.1 | 环境变量加载 | +| structlog | 24.4.0 | 结构化日志 | +| aiohttp | 3.10.10 | 异步 HTTP | +| httpx | 0.27.2 | HTTP 客户端 | + +## 可选依赖 + +| 包 | 用途 | 条件 | +|---|---|---| +| sentence-transformers | 本地 Embedding 模型 | `EMBEDDING_ENABLED=True` | +| torch | PyTorch（sentence-transformers 依赖） | `EMBEDDING_ENABLED=True` | + +## 开发依赖 + +| 包 | 版本 | 用途 | +|---|---|---| +| pytest | 8.3.3 | 测试框架 | +| pytest-asyncio | 0.24.0 | 异步测试 | +| pytest-cov | 6.0.0 | 覆盖率 | +| black | 24.8.0 | 代码格式化 | +| flake8 | 7.1.1 | Linting | +| mypy | 1.11.1 | 类型检查 | +| isort | 5.13.2 | Import 排序 | + +## 外部服务依赖 + +```mermaid +graph LR + App["TSP Assistant"] --> Qwen["Qwen/DashScope API"] + App --> FeishuAPI["飞书 Open API"] + App --> Redis["Redis Server"] + App --> DB["MySQL / SQLite"] + App --> HF["HuggingFace (可选, 首次下载模型)"] +``` diff --git a/.agents/summary/index.md b/.agents/summary/index.md new file mode 100644 index 0000000..f7f23e8 --- /dev/null +++ b/.agents/summary/index.md @@ -0,0 +1,56 @@ +# TSP 智能助手 — 文档索引 + +> **面向 AI 助手的使用指南**: 本文件是文档体系的入口。根据问题类型查阅对应文件即可获取详细信息。大多数问题只需本文件 + 1~2 个子文件即可回答。 + +## 文档目录 + +| 文件 | 内容摘要 | 适用问题 | +|------|---------|---------| +| [codebase_info.md](codebase_info.md) | 项目基本信息、技术栈、目录结构、启动流程 | "这个项目是什么？" "用了什么技术？" "怎么启动？" | +| [architecture.md](architecture.md) | 系统架构图、架构模式（单例/Blueprint/装饰器/多租户）、线程模型 | "系统怎么组织的？" "请求怎么流转？" "多租户怎么实现？" | +| [components.md](components.md) | 所有核心组件的职责说明（业务层、基础设施层、Web 层） | "DialogueManager 做什么？" "有哪些 Blueprint？" | +| [interfaces.md](interfaces.md) | REST API 列表、WebSocket 接口、外部集成时序图、装饰器接口 | "工单 API 有哪些？" "飞书怎么集成的？" | +| [data_models.md](data_models.md) | ORM 模型 ER 图、字段说明、配置 Dataclass、业务枚举 | "WorkOrder 有哪些字段？" "数据库表结构？" | +| [workflows.md](workflows.md) | 6 个关键流程的时序图（启动、对话、工单同步、知识搜索、飞书消息、Agent） | "消息怎么处理的？" "工单怎么同步到飞书？" | +| [dependencies.md](dependencies.md) | 所有 Python 依赖分类说明、外部服务依赖图 | "用了哪些库？" "有哪些外部依赖？" | +| [review_notes.md](review_notes.md) | 文档一致性/完整性检查结果、待补充区域、改进建议 | "文档有什么遗漏？" "哪些地方需要补充？" | + +## 快速导航 + +### 按任务类型 + +- **修 Bug / 改功能** → `components.md` 找到对应组件 → `architecture.md` 理解依赖关系 +- **加新 API** → `interfaces.md` 了解现有 API 模式 → `architecture.md` 中的装饰器模式 +- **改数据库** → `data_models.md` 查看表结构和关系 +- **理解流程** → `workflows.md` 查看时序图 +- **加新依赖** → `dependencies.md` 了解现有依赖 +- **部署/配置** → `codebase_info.md` 查看启动方式 + +### 按代码位置 + +- `src/core/` → `components.md` 基础设施组件 + `data_models.md` +- `src/web/blueprints/` → `interfaces.md` API 列表 + `components.md` Blueprint 说明 +- `src/dialogue/` → `components.md` 对话组件 + `workflows.md` 对话流程 +- `src/integrations/` → `interfaces.md` 外部集成 + `workflows.md` 飞书流程 +- `src/config/` → `data_models.md` 配置 Dataclass +- `start_dashboard.py` → `workflows.md` 启动流程 + +## 文件间关系 + +```mermaid +graph TD + INDEX["index.md (本文件)"] --> CI["codebase_info.md"] + INDEX --> ARCH["architecture.md"] + INDEX --> COMP["components.md"] + INDEX --> INTF["interfaces.md"] + INDEX --> DM["data_models.md"] + INDEX --> WF["workflows.md"] + INDEX --> DEP["dependencies.md"] + INDEX --> RN["review_notes.md"] + + ARCH --> COMP + COMP --> INTF + COMP --> DM + INTF --> WF + DM --> WF +``` diff --git a/.agents/summary/interfaces.md b/.agents/summary/interfaces.md new file mode 100644 index 0000000..9026ec1 --- /dev/null +++ b/.agents/summary/interfaces.md @@ -0,0 +1,104 @@ +# Interfaces / 接口与集成 + +## REST API 概览 + +所有 API 以 `/api/` 为前缀，返回 JSON。认证通过 Flask session 或 JWT。 + +### 工单 (workorders) +| Method | Path | 说明 | +|--------|------|------| +| GET | `/api/workorders` | 工单列表（分页） | +| POST | `/api/workorders` | 创建工单 | +| GET | `/api/workorders/` | 工单详情 | +| PUT | `/api/workorders/` | 更新工单 | +| DELETE | `/api/workorders/` | 删除工单 | +| POST | `/api/workorders/ai-suggestion` | 生成 AI 建议 | +| POST | `/api/workorders/import` | 批量导入 | + +### 知识库 (knowledge) +| Method | Path | 说明 | +|--------|------|------| +| GET | `/api/knowledge` | 知识条目列表 | +| POST | `/api/knowledge` | 添加条目 | +| GET | `/api/knowledge/search` | 搜索知识库 | +| GET | `/api/knowledge/stats` | 统计信息 | +| POST | `/api/knowledge/upload` | 文件导入 | +| PUT | `/api/knowledge//verify` | 验证条目 | + +### 对话 (chat / conversations) +| Method | Path | 说明 | +|--------|------|------| +| POST | `/api/chat/sessions` | 创建会话 | +| GET | `/api/chat/sessions` | 活跃会话列表 | +| POST | `/api/chat/message` | 发送消息 | +| POST | `/api/chat/message/stream` | 流式消息 (SSE) | +| GET | `/api/conversations` | 对话历史 | + +### 租户 (tenants) +| Method | Path | 说明 | +|--------|------|------| +| GET | `/api/tenants` | 租户列表 | +| POST | `/api/tenants` | 创建租户 | +| PUT | `/api/tenants/` | 更新租户 | +| DELETE | `/api/tenants/` | 删除租户 | +| GET | `/api/tenants/feishu-groups` | 飞书群列表 | + +### 认证 (auth) +| Method | Path | 说明 | +|--------|------|------| +| POST | `/api/auth/login` | 登录 | +| POST | `/api/auth/logout` | 登出 | +| GET | `/api/auth/status` | 认证状态 | +| POST | `/api/auth/register` | 注册 | + +### Agent +| Method | Path | 说明 | +|--------|------|------| +| POST | `/api/agent/chat` | Agent 对话 | +| GET | `/api/agent/status` | Agent 状态 | +| POST | `/api/agent/tools/execute` | 执行工具 | + +### 飞书同步 (feishu-sync) +| Method | Path | 说明 | +|--------|------|------| +| GET | `/api/feishu-sync/status` | 同步状态 | +| POST | `/api/feishu-sync/from-feishu` | 从飞书拉取 | +| POST | `/api/feishu-sync//to-feishu` | 推送到飞书 | +| GET/POST | `/api/feishu-sync/config` | 同步配置 | + +## WebSocket 接口 + +- **端口**: 8765 +- **协议**: JSON 消息 +- **功能**: 实时聊天，客户端连接后通过 JSON 消息与 RealtimeChatManager 交互 + +## 外部集成 + +```mermaid +sequenceDiagram + participant User as 用户 + participant Feishu as 飞书 + participant LongConn as 飞书长连接服务 + participant DM as DialogueManager + participant LLM as Qwen API + participant KB as KnowledgeManager + + User->>Feishu: 发送消息 + Feishu->>LongConn: 事件推送 + LongConn->>DM: 处理消息 + DM->>KB: 知识库检索 + KB-->>DM: 相关知识 + DM->>LLM: 生成回复 + LLM-->>DM: AI 回复 + DM->>Feishu: 回复消息 +``` + +## 装饰器接口 + +| 装饰器 | 位置 | 功能 | +|--------|------|------| +| `@handle_errors` | `decorators.py` | 统一异常捕获，返回标准错误响应 | +| `@require_json(fields)` | `decorators.py` | 验证请求体为 JSON 且包含必填字段 | +| `@with_service(name)` | `decorators.py` | 从 ServiceManager 注入服务实例 | +| `@rate_limit(max, period)` | `decorators.py` | 基于 IP 的频率限制 | +| `@cache_response(timeout)` | `decorators.py` | 响应缓存 | diff --git a/.agents/summary/review_notes.md b/.agents/summary/review_notes.md new file mode 100644 index 0000000..5dbc1c9 --- /dev/null +++ b/.agents/summary/review_notes.md @@ -0,0 +1,41 @@ +# Review Notes / 审查记录 + +## 一致性检查 ✅ + +- 所有文档中的组件名称、文件路径与代码库一致 +- 数据模型字段与 `src/core/models.py` 中的 ORM 定义匹配 +- API 路径与 Blueprint 注册的路由一致 +- 配置项与 `.env.example` 中的变量对应 + +## 完整性检查 + +### 已充分覆盖的区域 ✅ +- 系统架构和线程模型 +- 核心业务组件（对话、工单、知识库、Agent） +- 数据模型和 ER 关系 +- REST API 接口概览 +- 外部集成（飞书、LLM） +- 启动流程和关键工作流 + +### 需要补充的区域 ⚠️ + +| 区域 | 说明 | 建议 | +|------|------|------| +| `src/core/cache_manager.py` | 缓存策略细节未深入分析 | 补充 Redis 缓存键命名规范和 TTL 策略 | +| `src/core/vector_store.py` | 向量存储实现细节 | 补充 Embedding 索引结构说明 | +| `src/core/embedding_client.py` | Embedding 客户端接口 | 补充模型加载和推理流程 | +| `src/web/static/js/` | 前端模块化结构 | 补充前端模块职责说明 | +| `src/repositories/` | 数据访问层（steering 中提到但未深入） | 补充 Repository 模式和自动 tenant_id 过滤机制 | +| 错误处理 | `error_handlers.py` 的统一响应格式 | 补充 API 错误码规范 | +| 部署配置 | Docker / Nginx 配置细节 | 补充 `nginx.conf` 和 docker-compose 说明 | + +### 语言支持限制 +- 代码注释和 UI 文本为中文，文档已采用中英混合风格覆盖 +- 无其他语言支持限制 + +## 建议 + +1. 为 `src/repositories/` 层补充文档，说明自动 tenant_id 过滤的实现 +2. 补充前端 JS 模块的职责划分文档 +3. 考虑为 API 添加 OpenAPI/Swagger 规范 +4. 补充部署相关的 Docker 和 Nginx 配置说明 diff --git a/.agents/summary/workflows.md b/.agents/summary/workflows.md new file mode 100644 index 0000000..22d8b33 --- /dev/null +++ b/.agents/summary/workflows.md @@ -0,0 +1,127 @@ +# Workflows / 关键流程 + +## 1. 应用启动流程 + +```mermaid +sequenceDiagram + participant Main as start_dashboard.py + participant Log as setup_logging + participant DB as DatabaseManager + participant WS as WebSocket Thread + participant FS as 飞书长连接 Thread + participant Flask as Flask App + + Main->>Log: 初始化日志（按启动时间分目录） + Main->>DB: check_database_connection() + alt 连接失败 + Main->>Main: sys.exit(1) + end + Main->>WS: 启动守护线程 (port 8765) + Main->>FS: 启动守护线程 (飞书长连接) + Main->>Main: sleep(2) 等待初始化 + Main->>Flask: app.run(port=5000, threaded=True) +``` + +## 2. 用户对话流程 (WebSocket) + +```mermaid +sequenceDiagram + participant Client as 浏览器 + participant WS as WebSocketServer + participant RCM as RealtimeChatManager + participant DM as DialogueManager + participant KB as KnowledgeManager + participant LLM as LLMClient + + Client->>WS: WebSocket 连接 + Client->>WS: JSON 消息 + WS->>RCM: 转发消息 + RCM->>DM: process_message() + DM->>KB: search() 知识库检索 + KB-->>DM: 匹配结果 + DM->>LLM: 调用 Qwen API（含知识上下文） + LLM-->>DM: AI 回复 + DM-->>RCM: 回复内容 + RCM-->>WS: 发送回复 + WS-->>Client: JSON 回复 +``` + +## 3. 工单创建与飞书同步 + +```mermaid +sequenceDiagram + participant User as 用户/AI + participant API as workorders Blueprint + participant DB as Database + participant Sync as WorkOrderSyncService + participant Feishu as 飞书多维表格 + + User->>API: POST /api/workorders + API->>DB: 创建工单记录 + DB-->>API: 工单 ID + + opt 飞书同步已配置 + API->>Sync: sync_to_feishu(workorder_id) + Sync->>Feishu: 创建/更新记录 + Feishu-->>Sync: feishu_record_id + Sync->>DB: 更新 feishu_record_id + end + + API-->>User: 工单创建成功 +``` + +## 4. 知识库搜索流程 + +```mermaid +flowchart TD + Q["用户查询"] --> TF["TF-IDF 关键词匹配"] + Q --> EMB{"Embedding 启用?"} + + EMB -->|是| VEC["向量语义搜索"] + EMB -->|否| SKIP["跳过"] + + TF --> MERGE["合并结果"] + VEC --> MERGE + SKIP --> MERGE + + MERGE --> RANK["按相似度排序"] + RANK --> VERIFIED{"已验证条目优先"} + VERIFIED --> RESULT["返回 Top-K 结果"] +``` + +## 5. 飞书机器人消息处理 + +```mermaid +sequenceDiagram + participant User as 飞书用户 + participant Feishu as 飞书服务器 + participant LC as FeishuLongConnService + participant DM as DialogueManager + participant LLM as LLMClient + participant FS as FeishuService + + User->>Feishu: @机器人 发送消息 + Feishu->>LC: 长连接事件推送 + LC->>LC: 消息去重 + LC->>LC: resolve_tenant_by_chat_id() + LC->>DM: 处理消息（带 tenant_id） + DM->>LLM: 生成回复 + LLM-->>DM: AI 回复 + DM->>FS: 发送飞书消息 + FS->>Feishu: API 回复 +``` + +## 6. Agent 工具调度 + +```mermaid +flowchart TD + INPUT["用户输入"] --> THINK["Thought: 分析意图"] + THINK --> ACT["Action: 选择工具"] + ACT --> EXEC["执行工具"] + EXEC --> OBS["Observation: 获取结果"] + OBS --> DONE{"任务完成?"} + DONE -->|否| THINK + DONE -->|是| ANSWER["Final Answer: 返回结果"] +``` + +ReactAgent 注册的工具包括：知识库搜索、车辆查询、数据分析、飞书消息发送等。 diff --git a/.gitignore b/.gitignore index 5a3d184..5201250 100644 --- a/.gitignore +++ b/.gitignore @@ -42,3 +42,11 @@ test_*.py # 缓存 .cache/ + +# Virtual environment +bin/ +lib/ +lib64 +include/ +pyvenv.cfg +To diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e6af922 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,96 @@ +# AGENTS.md — TSP 智能助手 + +> AI 助手代码导航指南。详细文档见 `.agents/summary/index.md`。 + +## 项目概述 + +TSP 智能助手是一个 AI 驱动的多租户客服与工单管理系统。Python 3.11+ / Flask 3.x / SQLAlchemy 2.x。入口文件 `start_dashboard.py`。 + +## 目录导航 + +``` +src/ +├── config/unified_config.py # UnifiedConfig 单例，所有配置从 .env 加载 +├── core/ +│ ├── models.py # 所有 SQLAlchemy ORM 模型（11 个表） +│ ├── database.py # DatabaseManager 单例，session 管理 +│ ├── llm_client.py # LLMClient — OpenAI-compatible API (Qwen) +│ ├── auth_manager.py # JWT + SHA-256 认证 +│ ├── cache_manager.py # Redis 缓存 +│ └── vector_store.py # Embedding 向量存储 +├── dialogue/ +│ ├── dialogue_manager.py # 核心对话处理，调用 LLM + 知识库 +│ └── realtime_chat.py # WebSocket 实时聊天管理 +├── knowledge_base/ +│ └── knowledge_manager.py # 知识库 CRUD + TF-IDF/Embedding 搜索 +├── integrations/ +│ ├── feishu_service.py # 飞书 API 客户端 +│ ├── feishu_longconn_service.py # 飞书长连接事件订阅 +│ └── workorder_sync.py # 工单 ↔ 飞书多维表格双向同步 +├── agent/react_agent.py # ReAct Agent（工具调度循环） +├── analytics/ +│ ├── analytics_manager.py # 数据分析 +│ └── alert_system.py # 预警规则引擎 +└── web/ + ├── app.py # Flask 应用工厂 + 路由 + ├── service_manager.py # 懒加载服务注册中心 + ├── decorators.py # @handle_errors, @require_json, @resolve_tenant_id, @rate_limit + ├── websocket_server.py # 独立 WebSocket 服务器 (port 8765) + └── blueprints/ # 16 个 Flask Blueprint（每个领域一个文件） +``` + +## 关键模式 + +### 多租户 +所有核心表含 `tenant_id` 字段。`@resolve_tenant_id` 装饰器从请求中提取。查询时必须过滤 `tenant_id`。 + +### 服务获取 +Blueprint 通过 `ServiceManager` 懒加载获取服务实例，不要直接实例化业务类。 + +### API 装饰器栈 +典型 API 端点模式： +```python +@bp.route('/api/xxx', methods=['POST']) +@handle_errors() +@require_json(['field1', 'field2']) +def create_xxx(): + ... +``` + +### 配置 +所有配置通过 `get_config()` 获取，从 `.env` 加载。不要硬编码配置值。参考 `.env.example` 了解所有可用变量。 + +## 入口与启动 + +- `start_dashboard.py` — 主入口，启动 Flask + WebSocket + 飞书长连接（3 个线程） +- `start_feishu_bot.py` — 独立飞书机器人入口 +- `init_database.py` — 数据库初始化 + +## 数据库 + +- 开发: SQLite (`data/tsp_assistant.db`) +- 生产: MySQL via PyMySQL +- ORM: SQLAlchemy 2.x，模型定义在 `src/core/models.py` +- 核心表: `Tenant`, `WorkOrder`, `ChatSession`, `Conversation`, `KnowledgeEntry`, `Alert`, `Analytics`, `VehicleData`, `User` + +## 外部集成 + +- **LLM**: Qwen/DashScope (OpenAI-compatible API)，通过 `LLMClient` 调用 +- **飞书**: `lark-oapi` SDK，长连接模式接收消息，API 模式发送消息和操作多维表格 +- **Redis**: 可选缓存层，`REDIS_ENABLED` 控制 + +## 详细文档 + +完整文档体系在 `.agents/summary/` 目录： +- `index.md` — 文档索引（推荐作为 AI 上下文入口） +- `architecture.md` — 架构图和设计模式 +- `components.md` — 组件职责 +- `interfaces.md` — API 列表 +- `data_models.md` — 数据模型 ER 图 +- `workflows.md` — 关键流程时序图 +- `dependencies.md` — 依赖说明 + +## Custom Instructions + diff --git a/README.md b/README.md index 186e3ec..c325c05 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ AI 驱动的多租户客服与工单管理系统，支持飞书机器人、WebSo - **多租户** — 数据按 tenant_id 隔离，每个租户独立的系统提示词和飞书群绑定 - **数据分析** — 工单趋势、预警统计、满意度分析，支持按租户筛选 - **预警系统** — 自定义规则、多级别预警、批量管理 +- **Agent 模式** — ReAct 风格 LLM Agent，支持工具调度（知识搜索、车辆查询、飞书消息等） - **系统管理** — 模块权限控制、流量/成本/安全配置、Token 监控 ## 快速开始 @@ -23,25 +24,58 @@ 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 + config_service） -├── core/ # 基础设施（数据库、LLM、缓存、认证） -├── dialogue/ # 对话管理（realtime_chat、message_pipeline） +├── config/ # 配置管理（unified_config） +├── core/ # 基础设施（数据库、LLM、缓存、认证、ORM 模型） +├── dialogue/ # 对话管理（realtime_chat、dialogue_manager） ├── knowledge_base/ # 知识库（搜索、导入、验证） -├── repositories/ # 数据访问层（自动 tenant_id 过滤） ├── analytics/ # 监控与分析（预警、Token、AI 成功率） ├── integrations/ # 外部集成（飞书客户端、工单同步） ├── agent/ # ReAct Agent（工具调度） +├── vehicle/ # 车辆数据管理 +├── utils/ # 通用工具 └── web/ # Web 层 ├── app.py # Flask 应用 - ├── blueprints/ # API 蓝图（每个领域一个文件） - ├── service_manager.py - ├── static/js/ # 前端模块 - │ ├── dashboard.js # 核心 - │ └── modules/ # 功能模块 + ├── blueprints/ # API 蓝图（16 个，每个领域一个文件） + ├── service_manager.py # 懒加载服务注册 + ├── static/ # 前端资源 (JS/CSS) └── templates/ # Jinja2 模板 ``` @@ -50,12 +84,47 @@ src/ | 变量 | 说明 | 默认值 | |------|------|--------| | `SECRET_KEY` | Flask session 密钥 | 随机生成 | +| `DATABASE_URL` | 数据库连接串 | SQLite | | `LLM_BASE_URL` | LLM API 地址 | DashScope | -| `LLM_API_KEY` | LLM API 密钥 | - | +| `LLM_API_KEY` | LLM API 密钥 | — | | `LLM_MODEL` | 模型名称 | qwen-plus-latest | -| `FEISHU_APP_ID` | 飞书应用 ID | - | -| `FEISHU_APP_SECRET` | 飞书应用密钥 | - | +| `FEISHU_APP_ID` | 飞书应用 ID | — | +| `FEISHU_APP_SECRET` | 飞书应用密钥 | — | +| `FEISHU_APP_TOKEN` | 飞书多维表格 App Token | — | +| `FEISHU_TABLE_ID` | 飞书多维表格 Table ID | — | | `REDIS_HOST` | Redis 地址 | localhost | -| `ADMIN_PASSWORD` | 默认管理员密码 | admin123 | +| `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` 开始阅读。 diff --git a/src/web/templates/dashboard.html b/src/web/templates/dashboard.html index 8768a32..d5933a8 100644 --- a/src/web/templates/dashboard.html +++ b/src/web/templates/dashboard.html @@ -2314,7 +2314,6 @@
机器人回复时使用的角色设定，不同租户可以有不同的品牌定位
-