328 lines
9.0 KiB
Markdown
328 lines
9.0 KiB
Markdown
# Luxx 数据库设计文档
|
||
|
||
## 1. 数据库概述
|
||
|
||
- **类型**: SQLite
|
||
- **ORM**: SQLAlchemy 2.0
|
||
- **连接字符串**: `sqlite:///./chat.db`
|
||
|
||
## 2. ER 关系图
|
||
|
||
```mermaid
|
||
erDiagram
|
||
USER {
|
||
int id PK
|
||
string username UK
|
||
string email UK
|
||
string password_hash
|
||
string role
|
||
int permission_level
|
||
string workspace_path
|
||
bool is_active
|
||
datetime created_at
|
||
}
|
||
|
||
LLM_PROVIDER {
|
||
int id PK
|
||
int user_id FK
|
||
string name
|
||
string provider_type
|
||
string base_url
|
||
string api_key
|
||
string default_model
|
||
int max_tokens
|
||
bool is_default
|
||
bool enabled
|
||
datetime created_at
|
||
}
|
||
|
||
PROJECT {
|
||
string id PK
|
||
int user_id FK
|
||
string name
|
||
string description
|
||
datetime created_at
|
||
}
|
||
|
||
CONVERSATION {
|
||
string id PK
|
||
int user_id FK
|
||
int provider_id FK
|
||
string title
|
||
string model
|
||
text system_prompt
|
||
float temperature
|
||
bool thinking_enabled
|
||
datetime created_at
|
||
}
|
||
|
||
MESSAGE {
|
||
string id PK
|
||
string conversation_id FK
|
||
string role
|
||
text content
|
||
int token_count
|
||
string usage
|
||
datetime created_at
|
||
}
|
||
|
||
AGENT {
|
||
string id PK
|
||
string name
|
||
string role
|
||
string avatar
|
||
text system_prompt
|
||
int provider_id FK
|
||
string model
|
||
string tools
|
||
bool is_active
|
||
int priority
|
||
bool auto_response
|
||
bool mention_trigger
|
||
float temperature
|
||
int max_tokens
|
||
}
|
||
|
||
CHAT_ROOM {
|
||
string id PK
|
||
string name
|
||
string description
|
||
int owner_id FK
|
||
bool is_active
|
||
datetime created_at
|
||
datetime updated_at
|
||
}
|
||
|
||
ROOM_PARTICIPANT {
|
||
string id PK
|
||
string room_id FK
|
||
string agent_id FK "optional"
|
||
int user_id FK "optional"
|
||
string role
|
||
bool is_active
|
||
datetime joined_at
|
||
}
|
||
|
||
CHAT_ROOM_MESSAGE {
|
||
string id PK
|
||
string room_id FK
|
||
string participant_id
|
||
string sender_name
|
||
text content
|
||
string mentions
|
||
string parent_id
|
||
int token_count
|
||
datetime created_at
|
||
}
|
||
|
||
USER ||--o{ LLM_PROVIDER : has
|
||
USER ||--o{ PROJECT : owns
|
||
USER ||--o{ CONVERSATION : creates
|
||
USER ||--o{ CHAT_ROOM : owns
|
||
USER ||--o{ AGENT : creates
|
||
LLM_PROVIDER ||--o{ CONVERSATION : powers
|
||
LLM_PROVIDER ||--o{ AGENT : configures
|
||
CONVERSATION ||--o{ MESSAGE : contains
|
||
CHAT_ROOM ||--o{ CHAT_ROOM_MESSAGE : contains
|
||
CHAT_ROOM ||--o{ ROOM_PARTICIPANT : has
|
||
ROOM_PARTICIPANT }o--|| AGENT : agent
|
||
ROOM_PARTICIPANT }o--|| USER : user
|
||
```
|
||
|
||
## 3. 表设计
|
||
|
||
### users 用户表
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | INTEGER | PK | 用户 ID |
|
||
| username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 |
|
||
| email | VARCHAR(120) | UNIQUE | 邮箱 |
|
||
| password_hash | VARCHAR(255) | - | 密码哈希 |
|
||
| role | VARCHAR(20) | DEFAULT 'user' | 角色 |
|
||
| permission_level | INTEGER | DEFAULT 1 | 权限等级 |
|
||
| workspace_path | VARCHAR(500) | - | 工作空间路径 |
|
||
| is_active | BOOLEAN | DEFAULT 1 | 是否激活 |
|
||
| created_at | DATETIME | - | 创建时间 |
|
||
|
||
**权限等级:** 1=READ_ONLY, 2=WRITE, 3=EXECUTE, 4=ADMIN
|
||
|
||
### llm_providers LLM 提供商表
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | INTEGER | PK | 提供商 ID |
|
||
| user_id | INTEGER | FK(users.id) | 所属用户 |
|
||
| name | VARCHAR(100) | NOT NULL | 提供商名称 |
|
||
| provider_type | VARCHAR(50) | NOT NULL | 类型 |
|
||
| base_url | VARCHAR(500) | NOT NULL | API 地址 |
|
||
| api_key | VARCHAR(500) | NOT NULL | API 密钥 |
|
||
| default_model | VARCHAR(100) | NOT NULL | 默认模型 |
|
||
| max_tokens | INTEGER | DEFAULT 8192 | 最大 token |
|
||
| is_default | BOOLEAN | DEFAULT 0 | 是否默认 |
|
||
| enabled | BOOLEAN | DEFAULT 1 | 是否启用 |
|
||
|
||
### projects 项目表
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | VARCHAR(64) | PK | 项目 ID |
|
||
| user_id | INTEGER | FK(users.id) | 所属用户 |
|
||
| name | VARCHAR(255) | NOT NULL | 项目名称 |
|
||
| description | TEXT | - | 描述 |
|
||
| created_at | DATETIME | - | 创建时间 |
|
||
|
||
### conversations 会话表
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | VARCHAR(64) | PK | 会话 ID |
|
||
| user_id | INTEGER | FK(users.id) | 所属用户 |
|
||
| provider_id | INTEGER | FK(llm_providers.id) | LLM 提供商 |
|
||
| title | VARCHAR(255) | NOT NULL | 会话标题 |
|
||
| model | VARCHAR(64) | NOT NULL | 模型名称 |
|
||
| system_prompt | TEXT | NOT NULL | 系统提示词 |
|
||
| temperature | FLOAT | DEFAULT 0.7 | 温度参数 |
|
||
| max_tokens | INTEGER | DEFAULT 2000 | 最大 token |
|
||
| thinking_enabled | BOOLEAN | DEFAULT 0 | 思维链开关 |
|
||
|
||
### messages 消息表
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | VARCHAR(64) | PK | 消息 ID |
|
||
| conversation_id | VARCHAR(64) | FK(conversations.id) | 所属会话 |
|
||
| role | VARCHAR(16) | NOT NULL | user/assistant/system/tool |
|
||
| content | TEXT | NOT NULL | JSON 格式内容 |
|
||
| token_count | INTEGER | DEFAULT 0 | Token 数 |
|
||
| usage | TEXT | - | Token 使用统计 |
|
||
| created_at | DATETIME | - | 创建时间 |
|
||
|
||
**content 格式:** `{"text": "...", "steps": [...]}`
|
||
|
||
### agents Agent 表
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | VARCHAR(64) | PK | Agent ID |
|
||
| name | VARCHAR(50) | NOT NULL | 名称 |
|
||
| role | VARCHAR(50) | NOT NULL | 角色类型 |
|
||
| avatar | VARCHAR(500) | - | 头像 URL |
|
||
| system_prompt | TEXT | NOT NULL | 系统提示词 |
|
||
| provider_id | INTEGER | FK(llm_providers.id) | LLM 提供商 |
|
||
| model | VARCHAR(100) | - | 模型 |
|
||
| tools | TEXT | - | 工具列表(JSON 数组) |
|
||
| is_active | BOOLEAN | DEFAULT 1 | 是否启用 |
|
||
| priority | INTEGER | DEFAULT 5 | 优先级 |
|
||
| auto_response | BOOLEAN | DEFAULT 1 | 自动响应 |
|
||
| mention_trigger | BOOLEAN | DEFAULT 0 | @ 触发 |
|
||
| temperature | FLOAT | DEFAULT 0.7 | 温度 |
|
||
| max_tokens | INTEGER | DEFAULT 2048 | 最大 token |
|
||
|
||
### chat_rooms 聊天室表
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | VARCHAR(64) | PK | 聊天室 ID |
|
||
| name | VARCHAR(100) | NOT NULL | 聊天室名称 |
|
||
| description | TEXT | - | 描述 |
|
||
| owner_id | INTEGER | FK(users.id) | 所有者 |
|
||
| is_active | BOOLEAN | DEFAULT 1 | 是否启用 |
|
||
| created_at | DATETIME | - | 创建时间 |
|
||
|
||
### room_participants 聊天室成员表（统一用户和 Agent）
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | VARCHAR(64) | PK | 关联 ID |
|
||
| room_id | VARCHAR(64) | FK(chat_rooms.id) | 聊天室 ID |
|
||
| agent_id | VARCHAR(64) | FK(agents.id) | Agent ID (可选) |
|
||
| user_id | INTEGER | FK(users.id) | User ID (可选) |
|
||
| role | VARCHAR(32) | DEFAULT 'member' | 角色 (owner/admin/member) |
|
||
| is_active | BOOLEAN | DEFAULT 1 | 是否启用 |
|
||
| joined_at | DATETIME | - | 加入时间 |
|
||
|
||
**注意:** agent_id 和 user_id 至少有一个不为空
|
||
|
||
### chat_room_messages 聊天室消息表
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | VARCHAR(64) | PK | 消息 ID |
|
||
| room_id | VARCHAR(64) | FK(chat_rooms.id) | 聊天室 ID |
|
||
| participant_id | VARCHAR(64) | NOT NULL | 统一参与者 ID (格式: "user:123" 或 "agent:abc") |
|
||
| sender_name | VARCHAR(50) | NOT NULL | 发送者名称 |
|
||
| content | TEXT | NOT NULL | 消息内容 |
|
||
| mentions | TEXT | - | @ 提及列表(JSON) |
|
||
| parent_id | VARCHAR(64) | - | 回复的消息 ID |
|
||
| token_count | INTEGER | DEFAULT 0 | Token 数 |
|
||
| created_at | DATETIME | - | 创建时间 |
|
||
|
||
**participant_id 格式:**
|
||
- 用户: `user:{user_id}` (如 `user:123`)
|
||
- Agent: `agent:{agent_id}` (如 `agent:abc-001`)
|
||
|
||
## 4. 流程图
|
||
|
||
### 消息流（统一参与者）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as User
|
||
participant WS as WebSocket
|
||
participant PS as ParticipantService
|
||
participant RS as ChatRoomService
|
||
participant A as Agent
|
||
participant LLM as LLM
|
||
|
||
U->>WS: 发送消息
|
||
WS->>PS: process_message()
|
||
PS->>RS: save_message()
|
||
RS->>RS: 创建 participant_id
|
||
RS-->>PS: 消息保存成功
|
||
PS->>A: 触发 Agent
|
||
A->>LLM: stream_call
|
||
LLM-->>A: SSE 流
|
||
A-->>PS: process_step
|
||
PS-->>WS: 实时推送
|
||
WS-->>U: 显示
|
||
```
|
||
|
||
### Agent 调度
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[用户/Agent 消息] --> B{有 @ 提及?}
|
||
|
||
B -->|是| C[触发指定 Agent]
|
||
B -->|否| D[触发 auto_response Agent]
|
||
|
||
C --> E[并行调用]
|
||
D --> E
|
||
E --> F[流式响应]
|
||
F --> G[聚合结果]
|
||
G --> H[WebSocket 推送]
|
||
```
|
||
|
||
## 5. 索引
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph indexes[推荐索引]
|
||
I1[users.username UNIQUE]
|
||
I2[users.email UNIQUE]
|
||
I3[conversations.user_id]
|
||
I4[messages.conversation_id]
|
||
I5[chat_rooms.owner_id]
|
||
I6[chat_room_messages.room_id]
|
||
I7[room_participants.room_id]
|
||
end
|
||
```
|
||
|
||
## 6. 迁移
|
||
|
||
```python
|
||
from luxx.core.database import init_db
|
||
init_db() # 创建所有表
|
||
```
|