first commit

2026-02-22 12:12:02 +08:00
commit b236048a24
1467 changed files with 160403 additions and 0 deletions
@@ -0,0 +1,747 @@
+# RuoYi Chat 模块
+
+## 模块简介
+
+`ruoyi-chat` 是 PoJie 项目的智能聊天系统模块，提供完整的聊天会话管理、消息处理、知识库集成和实时通信功能。该模块通过集成 `ruoyi-ai` 和 `ruoyi-knowledge` 模块，实现了基于知识库的智能问答系统（RAG），支持多种通信方式（REST API、SSE 流式、WebSocket）。
+
+## 功能特性
+
+### 1. 聊天会话管理 ✅
+
+- ✅ 创建和管理聊天会话
+- ✅ 支持多用户并发聊天
+- ✅ 会话历史记录和导出
+- ✅ 会话状态管理
+- ✅ 会话标题自动生成和手动编辑
+
+### 2. 消息处理 ✅
+
+- ✅ 实时消息发送和接收
+- ✅ 消息类型支持（文本、图片等）
+- ✅ 消息历史查询（支持分页和条件筛选）
+- ✅ 消息状态跟踪
+- ✅ Token 使用量和成本统计
+
+### 3. 知识库集成（RAG）✅
+
+- ✅ 基于知识库的智能问答
+- ✅ 上下文理解和构建
+- ✅ 向量相似度搜索
+- ✅ 智能回复生成
+- ✅ 知识库会话管理
+- ✅ 知识库内容搜索
+- **内部对接模块**：
+  - AI 模块：`AiChatService`（统一聊天接口）
+  - 知识库模块：`KnowledgeVectorService`（向量检索）
+
+### 4. 实时通信 ✅
+
+- ✅ **REST API**：标准 HTTP 接口
+- ✅ **SSE 流式**：服务器推送事件，支持流式对话（`ChatOpenApiController`）
+- ✅ **WebSocket**：STOMP 协议，实时双向通信（`ChatStompController`）
+
+### 5. 使用统计 ✅
+
+- ✅ Token 使用量统计
+- ✅ 聊天成本计算
+- ✅ 用户活跃度分析
+- ✅ 模型使用情况
+- ✅ 使用记录导出
+
+### 6. 配置管理 ✅
+
+- ✅ 聊天配置管理（键值对配置）
+- ✅ 模型配置管理（模型信息、价格、API 配置）
+- ✅ 配置分类管理
+- ✅ 配置导入导出
+
+## 目录结构
+
+```
+ruoyi-chat/
+├─ src/main/java/org/dromara/chat/
+│  ├─ controller/         # REST 控制器层
+│  │  ├─ AIKnowledgeChatController.java    # 知识库聊天控制器
+│  │  ├─ ChatSessionController.java        # 会话管理控制器
+│  │  ├─ ChatMessageController.java        # 消息管理控制器
+│  │  ├─ ChatOpenApiController.java        # 开放 API 控制器（SSE 流式）
+│  │  ├─ ChatStompController.java          # WebSocket 控制器（STOMP）
+│  │  ├─ ChatConfigController.java         # 配置管理控制器
+│  │  ├─ ChatModelController.java          # 模型管理控制器
+│  │  └─ ChatUsageTokenController.java     # Token 使用记录控制器
+│  ├─ service/            # 核心业务服务层
+│  │  ├─ AiKnowledgeChatService.java       # 知识库聊天服务
+│  │  ├─ ChatSessionService.java           # 会话管理服务
+│  │  ├─ ChatMessageService.java           # 消息管理服务
+│  │  ├─ ChatConfigService.java            # 配置管理服务
+│  │  ├─ ChatModelService.java             # 模型管理服务
+│  │  ├─ ChatUsageTokenService.java        # Token 使用记录服务
+│  │  └─ impl/                             # 服务实现类
+│  ├─ domain/             # 领域模型
+│  │  ├─ bo/              # 业务对象（Business Object）
+│  │  ├─ vo/              # 视图对象（View Object）
+│  │  ├─ request/         # 请求对象
+│  │  └─ *.java           # 实体类（Entity）
+│  ├─ mapper/             # MyBatis Mapper 接口
+│  ├─ config/             # 配置类（WebSocket 配置等）
+│  └─ client/             # Java SDK（统一网关封装）
+│     └─ ChatSdk.java
+└─ docs/                  # API 使用说明文档
+```
+
+## 模块结构
+
+```
+org.dromara.chat
+├── controller/              # 控制器层
+│   ├── AIKnowledgeChatController.java      # 知识库聊天
+│   ├── ChatSessionController.java          # 会话管理
+│   ├── ChatMessageController.java          # 消息管理
+│   ├── ChatOpenApiController.java          # 开放 API（SSE）
+│   ├── ChatStompController.java            # WebSocket（STOMP）
+│   ├── ChatConfigController.java           # 配置管理
+│   ├── ChatModelController.java            # 模型管理
+│   └── ChatUsageTokenController.java       # Token 统计
+├── service/                 # 服务层
+│   ├── AiKnowledgeChatService.java
+│   ├── ChatSessionService.java
+│   ├── ChatMessageService.java
+│   ├── ChatConfigService.java
+│   ├── ChatModelService.java
+│   ├── ChatUsageTokenService.java
+│   └── impl/                # 服务实现
+├── domain/                  # 领域模型
+│   ├── bo/                  # 业务对象
+│   ├── vo/                  # 视图对象
+│   ├── request/             # 请求对象
+│   ├── ChatSession.java     # 会话实体
+│   ├── ChatMessage.java     # 消息实体
+│   ├── ChatConfig.java      # 配置实体
+│   ├── ChatModel.java       # 模型实体
+│   └── ChatUsageToken.java  # Token 使用实体
+├── mapper/                  # MyBatis Mapper
+├── config/                  # 配置类
+│   └── StompWebSocketConfig.java
+└── client/                  # Java SDK
+    └── ChatSdk.java
+```
+
+## 架构设计
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Chat Controller Layer                    │
+├─────────────────────────────────────────────────────────────┤
+│  AIKnowledgeChatController │ ChatSessionController          │
+│  ChatMessageController     │ ChatConfigController           │
+│  ChatModelController       │ ChatUsageTokenController       │
+│  ChatOpenApiController     │ ChatStompController            │
+│  (SSE 流式)                │ (WebSocket)                    │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────────────┐
+│                    Service Layer                            │
+├─────────────────────────────────────────────────────────────┤
+│  AiKnowledgeChatService    │ ChatSessionService             │
+│  ChatMessageService        │ ChatConfigService              │
+│  ChatModelService          │ ChatUsageTokenService          │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────────────┐
+│                 Integration Layer                           │
+├─────────────────────────────────────────────────────────────┤
+│              RuoYi AI Module                               │
+│              └─ AiChatService                              │
+│              └─ AiChatHistoryService                       │
+│              └─ AiProviderManager                          │
+│                                                             │
+│              RuoYi Knowledge Module                        │
+│              └─ KnowledgeVectorService                     │
+│              └─ KnowledgeInfoService                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 数据库表结构
+
+### 1. 聊天会话表 (chat_session)
+
+存储用户聊天会话信息。
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| id | BIGINT | 主键ID |
+| user_id | BIGINT | 用户ID |
+| session_title | VARCHAR(255) | 会话标题 |
+| session_content | TEXT | 会话内容 |
+| create_by | BIGINT | 创建者 |
+| create_time | DATETIME | 创建时间 |
+| update_by | BIGINT | 更新者 |
+| update_time | DATETIME | 更新时间 |
+| remark | VARCHAR(500) | 备注 |
+
+**索引**：`PRIMARY KEY (id)`
+
+### 2. 聊天消息表 (chat_message)
+
+存储聊天消息记录。
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| id | BIGINT | 主键ID |
+| session_id | BIGINT | 会话ID |
+| user_id | BIGINT | 用户ID |
+| content | LONGTEXT | 消息内容 |
+| role | VARCHAR(255) | 对话角色（user/assistant/system） |
+| deduct_cost | DOUBLE(20,2) | 扣除金额（默认 0.00） |
+| total_tokens | INT(20) | 累计 Tokens（默认 0） |
+| model_name | VARCHAR(255) | 模型名称 |
+| create_by | BIGINT | 创建者 |
+| create_time | DATETIME | 创建时间 |
+| update_by | BIGINT | 更新者 |
+| update_time | DATETIME | 更新时间 |
+| remark | VARCHAR(500) | 备注 |
+
+**索引**：`PRIMARY KEY (id)`
+
+### 3. 聊天配置表 (chat_config)
+
+存储聊天系统配置（键值对形式）。
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| id | BIGINT | 主键ID |
+| category | VARCHAR(255) | 配置类型 |
+| config_name | VARCHAR(255) | 配置名称 |
+| config_value | TEXT | 配置值 |
+| config_dict | VARCHAR(255) | 说明 |
+| create_by | BIGINT | 创建者 |
+| create_time | DATETIME | 创建时间 |
+| update_by | BIGINT | 更新者 |
+| update_time | DATETIME | 更新时间 |
+| remark | VARCHAR(500) | 备注 |
+| version | INT | 版本 |
+| del_flag | CHAR(1) | 删除标志（0存在 1删除） |
+| update_ip | VARCHAR(128) | 更新IP |
+
+**索引**：
+- `PRIMARY KEY (id)`
+- `UNIQUE KEY unique_category_key (category, config_name)`
+
+### 4. 聊天模型表 (chat_model)
+
+存储聊天模型配置信息。
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| id | BIGINT | 主键ID |
+| category | VARCHAR(20) | 模型分类 |
+| model_name | VARCHAR(50) | 模型名称 |
+| model_describe | VARCHAR(255) | 模型描述 |
+| model_price | DOUBLE | 模型价格 |
+| model_type | CHAR(1) | 计费类型 |
+| model_show | CHAR(1) | 是否显示 |
+| system_prompt | VARCHAR(255) | 系统提示词 |
+| api_host | VARCHAR(255) | 请求地址 |
+| api_key | VARCHAR(255) | 密钥 |
+| api_url | VARCHAR(50) | 请求后缀 |
+| create_by | BIGINT | 创建者 |
+| create_time | DATETIME | 创建时间 |
+| update_by | BIGINT | 更新者 |
+| update_time | DATETIME | 更新时间 |
+| remark | VARCHAR(500) | 备注 |
+
+**索引**：`PRIMARY KEY (id)`
+
+### 5. Token 使用记录表 (chat_usage_token)
+
+存储用户 Token 使用统计。
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| id | BIGINT | 主键ID |
+| user_id | BIGINT | 用户ID |
+| token | INT(10) | 待结算 token |
+| model_name | VARCHAR(64) | 模型名称 |
+| total_token | VARCHAR(255) | 累计使用 token |
+
+**索引**：`PRIMARY KEY (id)`
+
+**数据库脚本位置**：`script/sql/ry_chat.sql`
+
+## API 接口
+
+### 知识库聊天接口 (`/chat/knowledge`)
+
+#### 知识库问答
+- **接口**：`POST /chat/knowledge/chat`
+- **说明**：基于知识库进行智能问答
+- **权限**：`chat:knowledge:chat`
+- **参数**：
+  - `sessionId` (Long, 必填) - 会话ID
+  - `userId` (Long, 必填) - 用户ID
+  - `question` (String, 必填) - 问题
+  - `knowledgeId` (Long, 必填) - 知识库ID
+  - `modelName` (String, 必填) - 模型名称
+
+#### 创建知识库会话
+- **接口**：`POST /chat/knowledge/session`
+- **说明**：创建知识库聊天会话
+- **权限**：`chat:knowledge:session`
+- **参数**：
+  - `userId` (Long, 必填) - 用户ID
+  - `knowledgeId` (Long, 必填) - 知识库ID
+  - `sessionTitle` (String, 可选) - 会话标题
+
+#### 搜索知识内容
+- **接口**：`GET /chat/knowledge/search`
+- **说明**：搜索知识库内容
+- **权限**：`chat:knowledge:search`
+- **参数**：
+  - `knowledgeId` (Long, 必填) - 知识库ID
+  - `query` (String, 必填) - 查询内容
+  - `limit` (Integer, 可选, 默认5) - 返回数量
+
+#### 构建知识上下文
+- **接口**：`GET /chat/knowledge/context`
+- **说明**：构建知识库上下文
+- **权限**：`chat:knowledge:context`
+- **参数**：
+  - `knowledgeId` (Long, 必填) - 知识库ID
+  - `question` (String, 必填) - 问题
+
+#### 获取聊天历史
+- **接口**：`GET /chat/knowledge/history/{sessionId}`
+- **说明**：获取知识库聊天历史
+- **权限**：`chat:knowledge:history`
+- **参数**：
+  - `sessionId` (Long, 路径参数) - 会话ID
+  - `limit` (Integer, 可选, 默认20) - 返回数量
+
+### 会话管理接口 (`/chat/session`)
+
+- `GET /chat/session/list` - 查询会话列表（分页）
+- `GET /chat/session/{id}` - 获取会话详情
+- `POST /chat/session` - 创建新会话
+- `PUT /chat/session` - 更新会话
+- `DELETE /chat/session/{ids}` - 删除会话（批量）
+- `POST /chat/session/export` - 导出会话数据
+
+**权限前缀**：`chat:session:*`
+
+### 消息管理接口 (`/chat/message`)
+
+- `GET /chat/message/list` - 查询消息列表（分页）
+- `GET /chat/message/{id}` - 获取消息详情
+- `POST /chat/message` - 新增消息
+- `PUT /chat/message` - 更新消息
+- `DELETE /chat/message/{ids}` - 删除消息（批量）
+- `POST /chat/message/export` - 导出消息数据
+
+**权限前缀**：`chat:message:*`
+
+### 开放 API 接口 (`/chat`)
+
+#### SSE 流式聊天
+- **接口**：`POST /chat/send`
+- **说明**：SSE 流式聊天接口，支持 OpenAI 兼容格式
+- **认证**：需要登录（`@SaCheckLogin`）
+- **响应类型**：`text/event-stream`
+- **请求体**：JSON 格式
+  ```json
+  {
+    "model": "gpt-3.5-turbo",
+    "messages": [
+      {"role": "user", "content": "你好"}
+    ],
+    "sessionId": "1",
+    "temperature": 0.7,
+    "max_tokens": 2000
+  }
+  ```
+
+### WebSocket 接口
+
+#### STOMP 消息映射
+- **映射路径**：`/chat/send`
+- **说明**：STOMP 协议消息发送
+- **订阅主题**：`/topic/session/{sessionId}`
+- **配置类**：`StompWebSocketConfig`
+
+### 配置管理接口 (`/chat/config`)
+
+- `GET /chat/config/list` - 查询配置列表（分页）
+- `GET /chat/config/{id}` - 获取配置详情
+- `POST /chat/config` - 新增配置
+- `PUT /chat/config` - 更新配置
+- `DELETE /chat/config/{ids}` - 删除配置（批量）
+- `POST /chat/config/export` - 导出配置数据
+
+**权限前缀**：`chat:config:*`
+
+### 模型管理接口 (`/chat/model`)
+
+- `GET /chat/model/list` - 查询模型列表（分页）
+- `GET /chat/model/{id}` - 获取模型详情
+- `POST /chat/model` - 新增模型
+- `PUT /chat/model` - 更新模型
+- `DELETE /chat/model/{ids}` - 删除模型（批量）
+- `POST /chat/model/export` - 导出模型数据
+
+**权限前缀**：`chat:model:*`
+
+### Token 使用记录接口 (`/chat/token`)
+
+- `GET /chat/token/list` - 查询 Token 使用记录列表（分页）
+- `GET /chat/token/{id}` - 获取 Token 使用记录详情
+- `POST /chat/token` - 新增 Token 使用记录
+- `PUT /chat/token` - 更新 Token 使用记录
+- `DELETE /chat/token/{ids}` - 删除 Token 使用记录（批量）
+- `POST /chat/token/export` - 导出 Token 使用记录数据
+
+**权限前缀**：`chat:token:*`
+
+## 统一网关与协同
+
+### 后端统一网关
+
+Chat 模块可通过 `ruoyi-ai` 模块的统一网关进行对话：
+
+- `POST /api/ai/chat` - 同步聊天
+- `POST /api/ai/chat/async` - 异步聊天
+- `POST /api/ai/chat/stream` - 流式聊天（SSE）
+- `WS /ws/ai/chat` - WebSocket 实时通道
+
+### Chat 模块与 AI/Knowledge 的协同
+
+1. **知识库增强聊天**：
+   - 在 `AiKnowledgeChatServiceImpl` 中构建 `AiChatRequest`
+   - 调用 `AiChatService.chat`，开启知识库增强（`enableKnowledge=true`）
+   - 通过 `KnowledgeVectorService.vectorSimilaritySearch` 进行相关性检索
+   - 构建上下文并注入到消息中
+
+2. **聊天历史管理**：
+   - 使用 `AiChatHistoryService` 保存和管理聊天记录
+   - 支持 Redis 缓存和历史查询
+
+3. **模型管理**：
+   - 通过 `AiProviderManager` 获取可用模型列表
+   - 支持模型切换和负载均衡
+
+## 使用示例
+
+### 1. 创建知识库会话
+
+```bash
+curl -X POST "http://localhost:8080/chat/knowledge/session" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{
+    "userId": 1,
+    "knowledgeId": 1,
+    "sessionTitle": "技术咨询会话"
+  }'
+```
+
+### 2. 知识库问答
+
+```bash
+curl -X POST "http://localhost:8080/chat/knowledge/chat" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -H "Authorization: Bearer <token>" \
+  -d "sessionId=1&userId=1&question=什么是Spring Boot？&knowledgeId=1&modelName=gpt-3.5-turbo"
+```
+
+### 3. SSE 流式聊天
+
+```bash
+curl -X POST "http://localhost:8080/chat/send" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -H "Accept: text/event-stream" \
+  -d '{
+    "model": "gpt-3.5-turbo",
+    "messages": [
+      {"role": "user", "content": "你好，请介绍一下你自己"}
+    ],
+    "sessionId": "1",
+    "temperature": 0.7
+  }'
+```
+
+### 4. 通过统一网关进行对话
+
+```bash
+curl -X POST "http://localhost:8080/api/ai/chat" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{
+    "userId": "1",
+    "sessionId": "1",
+    "model": "gpt-4o-mini",
+    "enableKnowledge": true,
+    "knowledgeId": "1",
+    "knowledgeLimit": 5,
+    "knowledgeThreshold": 0.7,
+    "messages": [
+      {"role": "user", "content": "什么是Spring Boot？"}
+    ]
+  }'
+```
+
+### 5. 获取聊天历史
+
+```bash
+curl -X GET "http://localhost:8080/chat/knowledge/history/1?limit=10" \
+  -H "Authorization: Bearer <token>"
+```
+
+### 6. 查询会话列表
+
+```bash
+curl -X GET "http://localhost:8080/chat/session/list?pageNum=1&pageSize=10" \
+  -H "Authorization: Bearer <token>"
+```
+
+## Java SDK
+
+### ChatSdk（统一网关封装）
+
+封装类：`org.dromara.chat.client.ChatSdk`
+
+```java
+// 初始化 SDK
+ChatSdk sdk = new ChatSdk("http://localhost:8080")
+    .withToken("Bearer xxx");
+
+// 同步聊天
+String result = sdk.chat("{\"model\":\"gpt-4o\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}");
+
+// 流式聊天（SSE）
+sdk.chatStream("{\"model\":\"gpt-4o\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}", 
+    chunk -> System.out.println(chunk),
+    response -> System.out.println("Complete: " + response),
+    error -> System.err.println("Error: " + error));
+```
+
+## 配置说明
+
+### 应用配置
+
+Chat 模块依赖 `ruoyi-ai` 模块的配置，主要配置在 `application.yml` 中：
+
+```yaml
+ruoyi:
+  ai:
+    # 是否启用 AI 模块
+    enabled: true
+    
+    # 知识库配置
+    knowledge:
+      enabled: true
+      default-search-count: 5
+      similarity-threshold: 0.7
+      max-context-length: 4000
+      
+    # 流式响应配置
+    stream:
+      enabled: true
+      buffer-size: 1024
+      timeout: 60
+```
+
+### WebSocket 配置
+
+WebSocket 配置在 `StompWebSocketConfig` 中：
+
+- **端点路径**：`/ws`
+- **消息映射**：`/chat/send`
+- **订阅主题**：`/topic/session/{sessionId}`
+
+### 数据库配置
+
+确保已执行 `script/sql/ry_chat.sql` 初始化脚本。
+
+## 依赖模块
+
+### 核心依赖
+
+- **ruoyi-ai**: AI 服务集成
+  - `AiChatService` - 统一聊天服务
+  - `AiChatHistoryService` - 聊天历史服务
+  - `AiProviderManager` - Provider 管理器
+- **ruoyi-knowledge**: 知识库服务
+  - `KnowledgeVectorService` - 向量检索服务
+  - `KnowledgeInfoService` - 知识库信息服务
+- **ruoyi-common-core**: 核心工具类
+- **ruoyi-common-mybatis**: 数据库操作
+- **ruoyi-common-web**: Web 框架支持
+- **ruoyi-common-security**: 安全认证（Sa-Token）
+- **ruoyi-common-log**: 日志记录
+- **ruoyi-common-excel**: Excel 导出
+
+## 开发指南
+
+### 添加新的聊天类型
+
+1. 创建新的 Controller 类，继承 `BaseController`
+2. 实现对应的 Service 接口
+3. 添加相关的 BO 和 VO 类
+4. 配置路由映射和权限注解
+
+### 扩展消息类型
+
+1. 在 `ChatMessage` 实体中添加新字段
+2. 更新数据库表结构（修改 `ry_chat.sql`）
+3. 修改消息处理逻辑
+4. 添加相应的验证规则
+
+### 集成新的 AI 模型
+
+1. 在 `ruoyi-ai` 模块中添加新的 Provider
+2. 在 `chat_model` 表中添加模型配置
+3. 测试模型兼容性
+4. 更新文档
+
+### WebSocket 扩展
+
+1. 在 `StompWebSocketConfig` 中添加新的消息映射
+2. 创建对应的 Controller 处理消息
+3. 配置订阅主题
+4. 更新客户端连接代码
+
+## 认证与权限
+
+### 认证方式
+
+- **登录认证**：基于 Sa-Token，所有写操作需要登录态（`@SaCheckLogin`）
+- **权限控制**：管理接口需要相应权限（`@SaCheckPermission`）
+- **令牌格式**：`Authorization: Bearer <token>`
+
+### 权限列表
+
+- `chat:knowledge:*` - 知识库聊天权限
+- `chat:session:*` - 会话管理权限
+- `chat:message:*` - 消息管理权限
+- `chat:config:*` - 配置管理权限
+- `chat:model:*` - 模型管理权限
+- `chat:token:*` - Token 统计权限
+
+### 统一网关权限
+
+统一网关（`/api/ai/*`）需要相应的 AI 模块权限，如 `ai:chat:sync`、`ai:chat:stream` 等。
+
+## 监控和日志
+
+### 关键指标
+
+- 会话创建数量
+- 消息发送成功率
+- 平均响应时间
+- Token 使用量
+- 错误率统计
+- 知识库检索命中率
+
+### 日志配置
+
+```yaml
+logging:
+  level:
+    org.dromara.chat: DEBUG
+    org.dromara.ai: INFO
+    org.dromara.knowledge: INFO
+```
+
+### 日志记录
+
+- 所有接口调用记录（通过 `@Log` 注解）
+- 异常错误日志
+- 性能监控日志
+- Token 使用日志
+
+## 故障排除
+
+### 常见问题
+
+1. **AI 服务不可用**
+   - 检查 `ruoyi-ai` 模块状态
+   - 验证 API 密钥配置
+   - 查看网络连接
+   - 检查 Provider 配置
+
+2. **知识库搜索失败**
+   - 确认知识库 ID 有效
+   - 检查知识库内容是否已索引
+   - 验证搜索权限
+   - 查看向量服务状态
+
+3. **会话创建失败**
+   - 检查用户权限
+   - 验证数据库连接
+   - 查看参数格式
+   - 检查会话表结构
+
+4. **SSE 流式响应中断**
+   - 检查网络连接稳定性
+   - 查看超时配置
+   - 验证模型响应时间
+   - 检查服务器资源
+
+5. **WebSocket 连接失败**
+   - 检查 WebSocket 配置
+   - 验证 STOMP 端点路径
+   - 查看防火墙设置
+   - 检查客户端连接代码
+
+### 性能优化
+
+1. **数据库优化**
+   - 添加适当索引（session_id, user_id, create_time 等）
+   - 定期清理历史数据
+   - 使用连接池
+   - 考虑分表策略（按时间或用户）
+
+2. **缓存策略**
+   - 缓存热门会话
+   - 缓存知识库搜索结果
+   - 使用 Redis 缓存会话信息
+   - 缓存模型配置信息
+
+3. **异步处理**
+   - 异步保存消息
+   - 后台统计计算
+   - 队列处理长任务
+   - 异步日志记录
+
+4. **流式响应优化**
+   - 调整缓冲区大小
+   - 优化模型响应时间
+   - 使用连接池管理 SSE 连接
+   - 实现背压控制
+
+## 版本历史
+
+- **v1.0.0**: 初始版本，基础聊天功能
+- **v1.1.0**: 添加知识库集成（RAG）
+- **v1.2.0**: 支持多模型切换
+- **v1.3.0**: 增加使用统计功能
+- **v1.4.0**: 对接统一 AI 网关与 RAG 能力，完善文档与 SDK
+- **v1.5.0**: 添加 SSE 流式支持和 WebSocket 实时通信
+
+## 贡献指南
+
+1. Fork 项目
+2. 创建功能分支（`git checkout -b feature/AmazingFeature`）
+3. 提交代码变更（`git commit -m 'Add some AmazingFeature'`）
+4. 推送到分支（`git push origin feature/AmazingFeature`）
+5. 创建 Pull Request
+6. 等待代码审查
+
+## 许可证
+
+本项目采用 MIT 许可证，详见 LICENSE 文件。
+
+## 相关文档
+
+- [RuoYi AI 模块文档](../ruoyi-ai/README.md)
+- [RuoYi Knowledge 模块文档](../ruoyi-knowledge/README.md)
+- [API 使用文档](./docs/API.md)