diff --git a/assets/DATABASE.md b/assets/DATABASE.md
new file mode 100644
index 0000000..2cf33e3
--- /dev/null
+++ b/assets/DATABASE.md
@@ -0,0 +1,311 @@
+# 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
+    }
+
+    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. 流程图
+
+### 消息流
+
+```mermaid
+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 调度
+
+```mermaid
+flowchart TD
+    A[用户消息] --> 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]
+    end
+```
+
+## 6. 迁移
+
+```python
+from luxx.core.database import init_db
+init_db()  # 创建所有表
+```