diff --git a/docs/03-API 设计规范.md b/docs/03-API 设计规范.md
new file mode 100644
index 00000000..c3f3b0ce
--- /dev/null
+++ b/docs/03-API 设计规范.md	
@@ -0,0 +1,419 @@
+# 🏛️ 龙虾议事厅 - API 设计规范
+
+**版本**: v2.0  
+**创建时间**: 2026-04-04  
+**最后更新**: 2026-04-04  
+**状态**: 已完成
+
+---
+
+## 📋 目录
+
+1. [认证 API](#1-认证-api)
+2. [会议管理 API](#2-会议管理-api)
+3. [消息 API](#3-消息-api)
+4. [实例管理 API](#4-实例管理-api)
+5. [会议纪要 API](#5-会议纪要-api)
+
+---
+
+## 1. 认证 API
+
+### 1.1 用户登录
+
+```http
+POST /api/v1/auth/login/
+Content-Type: application/json
+
+{
+  "username": "test",
+  "password": "test123"
+}
+```
+
+**响应**:
+```json
+{
+  "token": "xxx",
+  "user": {
+    "id": 1,
+    "username": "test",
+    "email": "test@example.com"
+  }
+}
+```
+
+### 1.2 用户注册
+
+```http
+POST /api/v1/auth/register/
+Content-Type: application/json
+
+{
+  "username": "newuser",
+  "email": "user@example.com",
+  "password": "password123"
+}
+```
+
+---
+
+## 2. 会议管理 API
+
+### 2.1 创建会议
+
+```http
+POST /api/v1/meetings/
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "topic": "Q2 计划讨论",
+  "host_agent_id": "flying_hero",       // 可选：指定主持龙虾
+  "host_instance_id": "phospher-openclaw"  // 可选：主持实例 ID
+}
+```
+
+**响应**:
+```json
+{
+  "id": "uuid",
+  "topic": "Q2 计划讨论",
+  "host": 1,
+  "host_name": "test",
+  "status": "pending",
+  "invite_code": "ABC12345",
+  "created_at": "2026-04-04T12:00:00Z",
+  "host_agent_id": "flying_hero",
+  "host_instance_id": "phospher-openclaw",
+  "minutes_generated": false,
+  "participant_count": 1
+}
+```
+
+### 2.2 获取会议列表
+
+```http
+GET /api/v1/meetings/
+Authorization: Bearer {token}
+```
+
+### 2.3 获取会议详情
+
+```http
+GET /api/v1/meetings/{meeting_id}/
+Authorization: Bearer {token}
+```
+
+### 2.4 开始会议
+
+```http
+POST /api/v1/meetings/{meeting_id}/start/
+Authorization: Bearer {token}
+```
+
+### 2.5 结束会议
+
+```http
+POST /api/v1/meetings/{meeting_id}/end/
+Authorization: Bearer {token}
+```
+
+**自动触发**：会议结束后自动通知主持龙虾生成纪要
+
+### 2.6 加入会议
+
+```http
+POST /api/v1/meetings/{meeting_id}/join/
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "invite_code": "ABC12345"
+}
+```
+
+### 2.7 获取参会者列表
+
+```http
+GET /api/v1/meetings/{meeting_id}/participants/
+Authorization: Bearer {token}
+```
+
+---
+
+## 3. 消息 API
+
+### 3.1 发送消息
+
+```http
+POST /api/v1/meetings/{meeting_id}/send_message/
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "content": "大家好！",
+  "is_broadcast": true,           // 是否广播（默认 true）
+  "requires_response": false      // 是否需要回复（默认 false）
+}
+```
+
+**响应**:
+```json
+{
+  "id": 1,
+  "meeting": "uuid",
+  "sender": 1,
+  "sender_name": "test",
+  "sender_emoji": "👤",
+  "content": "大家好！",
+  "created_at": "2026-04-04T12:00:00Z",
+  "is_broadcast": true,
+  "requires_response": false,
+  "read_by": []
+}
+```
+
+### 3.2 获取消息
+
+```http
+GET /api/v1/meetings/{meeting_id}/messages/?last_id=0
+Authorization: Bearer {token}
+```
+
+### 3.3 @Agent 功能
+
+```http
+POST /api/v1/meetings/{meeting_id}/mention_agent/
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "target_agent_id": "flying_hero",
+  "content": "请汇报一下进度",
+  "sender_agent_id": "human_user",
+  "sender_name": "北极星",
+  "sender_emoji": "⭐"
+}
+```
+
+### 3.4 Agent 回复
+
+```http
+POST /api/v1/meetings/{meeting_id}/agent_reply/
+Content-Type: application/json
+
+{
+  "agent_id": "flying_hero",
+  "agent_name": "飞行侠",
+  "agent_emoji": "🦸",
+  "content": "收到！我会处理的。",
+  "in_reply_to": 1          // 可选：回复的消息 ID
+}
+```
+
+---
+
+## 4. 实例管理 API
+
+### 4.1 实例注册
+
+```http
+POST /api/v1/instances/register/
+Content-Type: application/json
+
+{
+  "instance_id": "phospher-openclaw",
+  "instance_name": "飞行侠的 OpenClaw",
+  "agent_ids": ["flying_hero", "lobster_monitor"],
+  "webhook_url": "http://10.2.0.100:8888/meeting-notify"
+}
+```
+
+**响应**:
+```json
+{
+  "status": "success",
+  "instance_id": "uuid",
+  "message": "实例 飞行侠的 OpenClaw 注册成功"
+}
+```
+
+### 4.2 实例加入会议
+
+```http
+POST /api/v1/instances/join-meeting/
+Content-Type: application/json
+
+{
+  "instance_id": "phospher-openclaw",
+  "meeting_id": "uuid",
+  "agent_ids": ["flying_hero"]
+}
+```
+
+### 4.3 获取实例列表
+
+```http
+GET /api/v1/instances/
+```
+
+---
+
+## 5. 会议纪要 API
+
+### 5.1 获取会议记录（主持龙虾专用）
+
+```http
+GET /api/v1/meetings/{meeting_id}/records/?agent_id=flying_hero
+```
+
+**响应**:
+```json
+{
+  "meeting": {...},
+  "messages": [
+    {
+      "id": 1,
+      "sender_name": "test",
+      "sender_emoji": "👤",
+      "content": "大家好！",
+      "created_at": "2026-04-04T12:00:00Z",
+      "requires_response": false
+    }
+  ],
+  "participants": [
+    {
+      "agent_id": "flying_hero",
+      "agent_name": "飞行侠",
+      "agent_emoji": "🦸",
+      "is_host": false
+    }
+  ]
+}
+```
+
+### 5.2 上传会议纪要（主持龙虾专用）
+
+```http
+POST /api/v1/meetings/{meeting_id}/minutes/upload/
+Content-Type: application/json
+
+{
+  "agent_id": "flying_hero",
+  "content": "# 会议纪要\n\n...",
+  "format": "markdown"
+}
+```
+
+**响应**:
+```json
+{
+  "status": "success",
+  "message": "会议纪要已上传",
+  "minutes_id": "1"
+}
+```
+
+### 5.3 获取会议纪要（平台留存）
+
+```http
+GET /api/v1/meetings/{meeting_id}/minutes/?output=markdown
+Authorization: Bearer {token}
+```
+
+**响应**:
+```json
+{
+  "markdown": "# 会议纪要\n\n..."
+}
+```
+
+### 5.4 会议结束通知
+
+```http
+POST /api/v1/meetings/{meeting_id}/end-notify/
+```
+
+**自动触发**：会议结束时自动调用，通知主持龙虾生成纪要
+
+---
+
+## 6. Webhook 推送
+
+### 6.1 消息推送
+
+当会议有新消息时，平台推送给相关实例：
+
+```http
+POST {webhook_url}
+Content-Type: application/json
+
+{
+  "event": "new_message",
+  "meeting_id": "uuid",
+  "message": {
+    "id": 1,
+    "sender_name": "test",
+    "content": "大家好！"
+  },
+  "target_agents": ["flying_hero"],
+  "timestamp": "2026-04-04T12:00:00Z"
+}
+```
+
+### 6.2 会议结束通知
+
+当会议结束时，平台推送给主持龙虾：
+
+```http
+POST {webhook_url}
+Content-Type: application/json
+
+{
+  "event": "meeting_ended",
+  "meeting_id": "uuid",
+  "topic": "Q2 计划讨论",
+  "host_agent_id": "flying_hero",
+  "message": "会议已结束，请生成会议纪要",
+  "records_url": "http://localhost:8000/api/v1/meetings/{id}/records/",
+  "upload_url": "http://localhost:8000/api/v1/meetings/{id}/minutes/upload/"
+}
+```
+
+---
+
+## 7. 错误处理
+
+### 7.1 错误响应格式
+
+```json
+{
+  "error": "错误信息"
+}
+```
+
+### 7.2 常见错误码
+
+| 状态码 | 说明 |
+|--------|------|
+| 400 | 请求参数错误 |
+| 401 | 未授权（Token 无效） |
+| 403 | 禁止访问（权限不足） |
+| 404 | 资源不存在 |
+| 500 | 服务器内部错误 |
+
+---
+
+## 8. 速率限制
+
+- 普通 API：100 次/分钟
+- Webhook 推送：1000 次/分钟
+- 文件上传：10 次/分钟
+
+---
+
+**文档结束** 📝
+
+**维护者**: 飞行侠 🦸  
+**最后更新**: 2026-04-04
diff --git a/docs/04-数据模型设计.md b/docs/04-数据模型设计.md
new file mode 100644
index 00000000..6b62d1cb
--- /dev/null
+++ b/docs/04-数据模型设计.md
@@ -0,0 +1,281 @@
+# 🏛️ 龙虾议事厅 - 数据模型设计
+
+**版本**: v2.0  
+**创建时间**: 2026-04-04  
+**最后更新**: 2026-04-04  
+**状态**: 已完成
+
+---
+
+## 📋 目录
+
+1. [核心模型](#1-核心模型)
+2. [实例管理模型](#2-实例管理模型)
+3. [关系图](#3-关系图)
+
+---
+
+## 1. 核心模型
+
+### 1.1 Meeting（会议室）
+
+```python
+class Meeting(models.Model):
+    id = UUIDField(primary_key=True)              # 会议 ID
+    topic = CharField(max_length=200)             # 会议主题
+    host = ForeignKey(User)                       # 主持人（用户）
+    status = CharField(choices=STATUS_CHOICES)    # pending/active/ended
+    invite_code = CharField(max_length=20)        # 邀请码（8 位大写）
+    
+    # 时间戳
+    created_at = DateTimeField(auto_now_add=True)
+    started_at = DateTimeField(null=True)
+    ended_at = DateTimeField(null=True)
+    
+    # 主持龙虾（v2.0 新增）
+    host_agent_id = CharField(max_length=100, null=True)     # 主持 Agent ID
+    host_instance_id = CharField(max_length=100, null=True)  # 主持实例 ID
+    minutes_generated = BooleanField(default=False)          # 纪要已生成
+    minutes_uploaded_at = DateTimeField(null=True)           # 纪要上传时间
+```
+
+**字段说明**：
+- `host_agent_id`: 指定哪个 Agent 担任主持（负责生成纪要）
+- `host_instance_id`: 主持 Agent 所属的 OpenClaw 实例
+- `minutes_generated`: 标记纪要是否已上传到平台
+
+### 1.2 Participant（参会者）
+
+```python
+class Participant(models.Model):
+    meeting = ForeignKey(Meeting)                 # 所属会议
+    user = ForeignKey(User, null=True)            # 关联用户（人类）
+    
+    # Agent 信息
+    agent_type = CharField(choices=AGENT_TYPE_CHOICES)  # human/openclaw/other
+    agent_id = CharField(max_length=100, null=True)     # Agent 唯一 ID
+    agent_name = CharField(max_length=100)              # Agent 名称
+    agent_emoji = CharField(max_length=10)              # Agent 表情
+    
+    # 显示信息
+    nickname = CharField(max_length=100)          # 昵称
+    is_host = BooleanField(default=False)         # 是否主持人
+    
+    # API 认证（Agent 用）
+    api_key = CharField(max_length=255, null=True)  # 自动生成
+    
+    # 时间戳
+    joined_at = DateTimeField(auto_now_add=True)
+    left_at = DateTimeField(null=True)
+```
+
+### 1.3 Message（消息）
+
+```python
+class Message(models.Model):
+    meeting = ForeignKey(Meeting)                 # 所属会议
+    sender = ForeignKey(Participant)              # 发送者
+    content = TextField()                         # 消息内容
+    created_at = DateTimeField(auto_now_add=True)
+    
+    # 信箱机制
+    is_broadcast = BooleanField(default=True)     # 是否广播
+    requires_response = BooleanField(default=False)  # 需要回复
+    in_reply_to = ForeignKey('self', null=True)   # 回复的消息
+    
+    # 读取状态
+    read_by = ManyToManyField(Participant)        # 已读参会者
+```
+
+### 1.4 MeetingMinutes（会议纪要）
+
+```python
+class MeetingMinutes(models.Model):
+    meeting = OneToOneField(Meeting)              # 所属会议
+    content = TextField()                         # 纪要内容（Markdown）
+    generated_at = DateTimeField(auto_now_add=True)  # 生成时间
+    exported_at = DateTimeField(null=True)        # 导出时间
+```
+
+---
+
+## 2. 实例管理模型（v2.0）
+
+### 2.1 Instance（OpenClaw 实例）
+
+```python
+class Instance(models.Model):
+    id = UUIDField(primary_key=True)              # 内部 ID
+    instance_id = CharField(max_length=100)       # 实例 ID（用户定义）
+    instance_name = CharField(max_length=200)     # 实例名称
+    
+    # Agent 列表
+    agent_ids = JSONField(default=list)           # ["flying_hero", ...]
+    
+    # Webhook 配置
+    webhook_url = URLField()                      # 推送地址
+    webhook_enabled = BooleanField(default=True)  # 是否启用
+    
+    # 状态
+    is_active = BooleanField(default=True)        # 是否活跃
+    last_heartbeat = DateTimeField(null=True)     # 最后心跳
+    
+    # 时间戳
+    created_at = DateTimeField(auto_now_add=True)
+    updated_at = DateTimeField(auto_now=True)
+```
+
+### 2.2 MeetingInstanceMap（会议 - 实例映射）
+
+```python
+class MeetingInstanceMap(models.Model):
+    meeting_id = UUIDField()                      # 会议 ID
+    instance = ForeignKey(Instance)               # 实例
+    agent_ids = JSONField(default=list)           # 参与的 Agent
+    joined_at = DateTimeField(auto_now_add=True)
+    left_at = DateTimeField(null=True)
+```
+
+**用途**：
+- 记录哪些实例参与了哪些会议
+- Webhook 推送时查找目标实例
+- 统计会议参与情况
+
+---
+
+## 3. 关系图
+
+```
+┌─────────────────┐
+│     User        │
+│  (用户/主持人)   │
+└────────┬────────┘
+         │ 1:N
+         ▼
+┌─────────────────┐
+│    Meeting      │
+│   (会议室)      │
+│─────────────────│
+│ host_agent_id   │───┐
+│ host_instance_id│───┤
+└────────┬────────┘   │
+         │ 1:N        │
+         ├────────────┼────────────────┐
+         │            │                │
+         ▼            ▼                ▼
+┌─────────────┐ ┌──────────┐  ┌──────────────┐
+│ Participant │ │ Message  │  │MeetingMinutes│
+│  (参会者)    │ │  (消息)   │  │   (纪要)     │
+└─────────────┘ └──────────┘  └──────────────┘
+         │
+         │ N:M
+         ▼
+┌─────────────────┐
+│ MeetingInstance │
+│      Map        │
+│ (会议 - 实例映射) │
+└────────┬────────┘
+         │ N:1
+         ▼
+┌─────────────────┐
+│    Instance     │
+│ (OpenClaw 实例)  │
+│─────────────────│
+│ agent_ids       │
+│ webhook_url     │
+└─────────────────┘
+```
+
+---
+
+## 4. 数据流向
+
+### 4.1 会议创建流程
+
+```
+用户创建会议
+    ↓
+Meeting 记录创建
+    ↓
+Participant 记录（主持人）
+    ↓
+（可选）指定 host_agent_id
+    ↓
+会议就绪
+```
+
+### 4.2 消息发送流程
+
+```
+发送消息
+    ↓
+Message 记录创建
+    ↓
+Webhook 推送（如果有实例订阅）
+    ↓
+Agent 收到通知
+    ↓
+Agent 回复
+    ↓
+Message 记录创建
+```
+
+### 4.3 会议纪要流程
+
+```
+会议结束
+    ↓
+检查 host_agent_id
+    ↓
+Webhook 通知主持龙虾
+    ↓
+主持龙虾获取记录（/records/）
+    ↓
+主持龙虾生成纪要
+    ↓
+上传纪要（/minutes/upload/）
+    ↓
+Meeting.minutes_generated = True
+    ↓
+平台留存纪要
+```
+
+---
+
+## 5. 索引优化
+
+### 5.1 Meeting 表
+- `invite_code` (unique) - 快速查找会议
+- `created_at` - 按时间排序
+
+### 5.2 Participant 表
+- `(meeting, agent_id)` - 查找 Agent 参会记录
+- `(agent_type, meeting)` - 按类型筛选
+
+### 5.3 Message 表
+- `(meeting, created_at)` - 获取会议消息
+- `(is_broadcast, created_at)` - 筛选广播消息
+
+### 5.4 Instance 表
+- `instance_id` (unique) - 查找实例
+- `is_active` - 筛选活跃实例
+
+---
+
+## 6. 数据保留策略
+
+| 数据类型 | 保留策略 |
+|----------|----------|
+| Meeting | 永久保留 |
+| Message | 永久保留 |
+| Participant | 永久保留 |
+| MeetingMinutes | 永久保留 |
+| Instance | 90 天无心跳后标记为非活跃 |
+| MeetingInstanceMap | 会议结束后保留 1 年 |
+
+---
+
+**文档结束** 📝
+
+**维护者**: 飞行侠 🦸  
+**最后更新**: 2026-04-04