Luxx/assets/DATABASE.md

Luxx 数据库设计文档

1. 数据库概述

• 类型: SQLite
• ORM: SQLAlchemy 2.0
• 连接字符串: sqlite:///./chat.db

2. ER 关系图

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
    }

    CHAT_ROOM_AGENT {
        string id PK
        string chat_room_id FK
        string agent_id FK
        bool is_active
        datetime joined_at
    }

    CHAT_ROOM_MESSAGE {
        string id PK
        string room_id FK
        string sender_type
        string sender_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{ CHAT_ROOM_AGENT : has
    AGENT ||--o{ CHAT_ROOM_AGENT : joins

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	-	创建时间

chat_room_agents 聊天室成员表

字段	类型	约束	说明
id	VARCHAR(64)	PK	关联 ID
chat_room_id	VARCHAR(64)	FK(chat_rooms.id)	聊天室 ID
agent_id	VARCHAR(64)	FK(agents.id)	Agent ID
is_active	BOOLEAN	DEFAULT 1	是否启用
joined_at	DATETIME	-	加入时间

chat_room_messages 聊天室消息表

字段	类型	约束	说明
id	VARCHAR(64)	PK	消息 ID
room_id	VARCHAR(64)	FK(chat_rooms.id)	聊天室 ID
sender_type	VARCHAR(16)	NOT NULL	user/agent/system
sender_id	VARCHAR(64)	NOT NULL	发送者 ID
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	-	创建时间

4. 流程图

消息流

sequenceDiagram
    participant U as 用户
    participant WS as WebSocket
    participant R as ChatRoomService
    participant A as Agent
    participant LLM as LLM

    U->>WS: 发送消息
    WS->>R: dispatch
    R->>A: 触发 Agent
    A->>LLM: stream_call
    LLM-->>A: SSE 流
    A-->>WS: process_step
    WS-->>U: 实时推送

Agent 调度

flowchart TD
    A[用户消息] --> B{有 @ 提及?}

    B -->|是| C[触发指定 Agent]
    B -->|否| D[触发 auto_response Agent]

    C --> E[并行调用]
    D --> E
    E --> F[流式响应]
    F --> G[聚合结果]
    G --> H[WebSocket 推送]

5. 索引

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]
    end

6. 迁移

from luxx.core.database import init_db
init_db()  # 创建所有表