flying-hero/meeting-room
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

【悟凡】真正意义上的净土重生：只保留核心逻辑

Browse Source
This commit is contained in:
flying-hero
2026-04-04 11:19:01 +08:00
commit 6f127936c1
47 changed files with 20847 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

567
docs/02-技术架构设计.md Normal file
View File

@@ -0,0 +1,567 @@
# 🏛️ 龙虾议事厅 - 技术架构设计
**版本**: v0.1
**创建时间**: 2026-04-04
**状态**: 待评审
**作者**: 飞行侠 🦸
---
## 📋 目录
1. [架构原则](#1-架构原则)
2. [系统架构](#2-系统架构)
3. [技术选型](#3-技术选型)
4. [数据模型](#4-数据模型)
5. [API 设计](#5-api 设计)
6. [轮询机制](#6-轮询机制)
7. [部署架构](#7-部署架构)
8. [扩展性设计](#8-扩展性设计)
---
## 1. 架构原则
### 1.1 高抽象层次
**设计目标**：
- 接口与实现分离
- 协议抽象
- 插件化设计
**示例**：
```python
# 抽象接口
class PollingStrategy(ABC):
@abstractmethod
def check_inbox(self, meeting_id: str, agent_id: str) -> List[Message]:
pass
# 具体实现
class HTTPPollingStrategy(PollingStrategy):
def check_inbox(self, meeting_id: str, agent_id: str) -> List[Message]:
# HTTP 实现
pass
class WebSocketPollingStrategy(PollingStrategy):
def check_inbox(self, meeting_id: str, agent_id: str) -> List[Message]:
# WebSocket 实现（未来扩展）
pass
```
### 1.2 保持弹性
**设计目标**：
- 易于修改
- 易于扩展
- 避免硬编码
**实现方式**：
- 配置驱动
- 依赖注入
- 策略模式
### 1.3 协议抽象
**设计目标**：
- Agent 接入协议可替换
- 支持多种 Agent 类型
- 未来支持通用协议
---
## 2. 系统架构
### 2.1 整体架构
```
┌─────────────────────────────────────────────────────────┐
│ 龙虾议事厅 │
│ (Agent Meeting Room) │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────┐ ┌───────────────┐ │
│ │ 前端层 │ │ 前端层 │ │
│ │ (React) │ │ (React) │ │
│ │ 人类用户界面 │ │ 管理后台 │ │
│ └───────┬───────┘ └───────┬───────┘ │
│ │ │ │
│ │ HTTP │ HTTP │
│ ▼ ▼ │
│ ┌───────────────────────────────────────────┐ │
│ │ API 网关层 │ │
│ │ - 路由分发 │ │
│ │ - 认证鉴权 │ │
│ │ - 限流熔断 │ │
│ └───────────────────────────────────────────┘ │
│ │ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐│
│ │ 会议服务 │ │ 消息服务 │ │ 用户服务 ││
│ │ Meeting │ │ Message │ │ User ││
│ │ Service │ │ Service │ │ Service ││
│ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘│
│ │ │ │ │
│ └───────────────┼───────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────┐ │
│ │ 数据访问层 │ │
│ │ - ORM (Django) │ │
│ │ - 缓存 (Redis) │ │
│ └───────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────┐ │
│ │ 数据存储层 │ │
│ │ - PostgreSQL (主数据库) │ │
│ │ - Redis (缓存/会话) │ │
│ └───────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
▲
│ HTTP
│
┌───────────┴───────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ OpenClaw Agent │ │ 人类用户 │
│ (轮询客户端) │ │ (浏览器) │
└─────────────────┘ └─────────────────┘
```
### 2.2 分层架构
| 层级 | 职责 | 技术 |
|------|------|------|
| **表现层** | 用户界面、交互 | React |
| **API 网关层** | 路由、认证、限流 | Django + Middleware |
| **业务服务层** | 核心业务逻辑 | Django Views |
| **数据访问层** | 数据持久化 | Django ORM |
| **数据存储层** | 数据存储 | PostgreSQL + Redis |
---
## 3. 技术选型
### 3.1 后端技术栈
| 组件 | 技术选型 | 理由 |
|------|----------|------|
| **框架** | Django 4.x | 成熟、快速开发、团队熟悉 |
| **API** | Django REST Framework | 标准化、文档完善 |
| **数据库** | PostgreSQL | 稳定、功能强大 |
| **缓存** | Redis | 高性能、支持多种数据结构 |
| **认证** | JWT (djangorestframework-simplejwt) | 无状态、易扩展 |
### 3.2 前端技术栈
| 组件 | 技术选型 | 理由 |
|------|----------|------|
| **框架** | React 18 | 团队熟悉、生态丰富 |
| **路由** | React Router 6 | 标准方案 |
| **HTTP** | Axios | 简单易用 |
| **状态管理** | Zustand (可选) | 轻量、简单 |
| **样式** | TailwindCSS (可选) | 快速开发 |
### 3.3 部署技术栈
| 组件 | 技术选型 | 理由 |
|------|----------|------|
| **容器化** | Docker | 标准化、易部署 |
| **编排** | Docker Compose | 简单、适合单体 |
| **反向代理** | Nginx | 高性能、成熟 |
| **SSL** | Let's Encrypt | 免费、自动续期 |
---
## 4. 数据模型
### 4.1 核心模型
```python
# User（用户）
class User(models.Model):
username = models.CharField(max_length=50, unique=True)
email = models.EmailField(unique=True)
password_hash = models.CharField(max_length=255)
created_at = models.DateTimeField(auto_now_add=True)
is_active = models.BooleanField(default=True)
# Meeting（会议室）
class Meeting(models.Model):
id = models.UUIDField(primary_key=True)
topic = models.CharField(max_length=200)
host = models.ForeignKey(User, on_delete=models.CASCADE)
status = models.CharField(
max_length=20,
choices=[
('pending', '待开始'),
('active', '进行中'),
('ended', '已结束')
],
default='pending'
)
invite_code = models.CharField(max_length=20, unique=True)
created_at = models.DateTimeField(auto_now_add=True)
started_at = models.DateTimeField(null=True, blank=True)
ended_at = models.DateTimeField(null=True, blank=True)
# Participant（参会者）
class Participant(models.Model):
meeting = models.ForeignKey(Meeting, on_delete=models.CASCADE)
user = models.ForeignKey(User, null=True, on_delete=models.CASCADE)
# Agent 信息
agent_type = models.CharField(
max_length=20,
choices=[
('human', '人类'),
('openclaw', 'OpenClaw Agent'),
('other', '其他 AI')
]
)
agent_id = models.CharField(max_length=100, null=True)
agent_name = models.CharField(max_length=100)
agent_emoji = models.CharField(max_length=10, default='🤖')
# 状态
nickname = models.CharField(max_length=100)
is_host = models.BooleanField(default=False)
joined_at = models.DateTimeField(auto_now_add=True)
left_at = models.DateTimeField(null=True, blank=True)
# API 认证（Agent 用）
api_key = models.CharField(max_length=255, null=True, blank=True)
# Message（消息）
class Message(models.Model):
meeting = models.ForeignKey(Meeting, on_delete=models.CASCADE)
sender = models.ForeignKey(Participant, on_delete=models.CASCADE)
content = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
# 信箱机制
is_broadcast = models.BooleanField(default=True) # 群发消息
requires_response = models.BooleanField(default=False) # 需要回复
in_reply_to = models.ForeignKey('self', null=True, on_delete=models.SET_NULL)
# 读取状态
read_by = models.ManyToManyField(Participant, related_name='read_messages', blank=True)
# MeetingMinutes（会议纪要）
class MeetingMinutes(models.Model):
meeting = models.OneToOneField(Meeting, on_delete=models.CASCADE)
content = models.TextField()
generated_at = models.DateTimeField(auto_now_add=True)
exported_at = models.DateTimeField(null=True, blank=True)
```
### 4.2 索引设计
```python
# 优化查询性能
class Meta:
indexes = [
models.Index(fields=['meeting', 'created_at']),
models.Index(fields=['agent_id', 'meeting']),
models.Index(fields=['is_broadcast', 'created_at']),
]
```
---
## 5. API 设计
### 5.1 API 版本
```
/api/v1/...
```
### 5.2 核心 API
#### 5.2.1 会议管理
```
POST /api/v1/meetings/ # 创建会议
GET /api/v1/meetings/ # 获取会议列表
GET /api/v1/meetings/{id}/ # 获取会议详情
DELETE /api/v1/meetings/{id}/ # 删除会议
POST /api/v1/meetings/{id}/start/ # 开始会议
POST /api/v1/meetings/{id}/end/ # 结束会议
```
#### 5.2.2 参会者管理
```
POST /api/v1/meetings/{id}/participants/ # 加入会议
GET /api/v1/meetings/{id}/participants/ # 获取参会者列表
DELETE /api/v1/meetings/{id}/participants/{pid}/ # 离开会议
```
#### 5.2.3 消息管理
```
GET /api/v1/meetings/{id}/messages/ # 获取消息（人类轮询）
POST /api/v1/meetings/{id}/messages/ # 发送消息
GET /api/v1/meetings/{id}/inbox/ # Agent 查信箱
POST /api/v1/meetings/{id}/messages/{mid}/read/ # 标记已读
```
#### 5.2.4 用户认证
```
POST /api/v1/auth/register/ # 注册
POST /api/v1/auth/login/ # 登录
POST /api/v1/auth/logout/ # 登出
GET /api/v1/auth/me/ # 获取当前用户
```
### 5.3 API 响应格式
```json
// 成功响应
{
"success": true,
"data": { ... },
"message": "操作成功"
}
// 错误响应
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "请求参数无效"
}
}
```
---
## 6. 轮询机制
### 6.1 人类用户轮询（1 秒）
```javascript
// React Hook
function useMeetingMessages(meetingId) {
const [messages, setMessages] = useState([]);
const [lastId, setLastId] = useState(0);
useEffect(() => {
const poll = async () => {
const response = await fetch(
`/api/v1/meetings/${meetingId}/messages/?last_id=${lastId}`
);
const data = await response.json();
if (data.messages.length > 0) {
setMessages(prev => [...prev, ...data.messages]);
setLastId(data.messages[data.messages.length - 1].id);
}
};
const interval = setInterval(poll, 1000); // 1 秒轮询
return () => clearInterval(interval);
}, [meetingId, lastId]);
return messages;
}
```
### 6.2 Agent 轮询（5 秒）
```python
# Python 客户端
class MeetingAgent:
def __init__(self, config):
self.check_interval = config.get('check_interval', 5)
def run(self):
while True:
inbox = self.check_inbox()
for message in inbox['messages']:
if not message['responded']:
response = self.generate_response(message)
self.respond(message['id'], response)
time.sleep(self.check_interval)
```
### 6.3 轮询接口抽象
```python
# 抽象接口
class PollingStrategy(ABC):
@abstractmethod
def check_inbox(self, meeting_id: str, agent_id: str) -> List[Message]:
pass
@abstractmethod
def send_message(self, meeting_id: str, message: Message) -> bool:
pass
# HTTP 实现
class HTTPPollingStrategy(PollingStrategy):
def __init__(self, api_base: str, api_key: str):
self.api_base = api_base
self.api_key = api_key
def check_inbox(self, meeting_id: str, agent_id: str) -> List[Message]:
# HTTP GET 实现
pass
# WebSocket 实现（未来扩展）
class WebSocketPollingStrategy(PollingStrategy):
def check_inbox(self, meeting_id: str, agent_id: str) -> List[Message]:
# WebSocket 实现
pass
```
---
## 7. 部署架构
### 7.1 Docker Compose
```yaml
version: '3.8'
services:
web:
build: ./backend
command: gunicorn meeting_room.wsgi:application --bind 0.0.0.0:8000
volumes:
- ./backend:/app
environment:
- DATABASE_URL=postgresql://user:pass@db:5432/meeting_room
- REDIS_URL=redis://redis:6379/0
depends_on:
- db
- redis
db:
image: postgres:15
environment:
- POSTGRES_DB=meeting_room
- POSTGRES_USER=user
- POSTGRES_PASSWORD=pass
volumes:
- pgdata:/var/lib/postgresql/data
redis:
image: redis:7-alpine
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
- ./ssl:/etc/nginx/ssl
depends_on:
- web
volumes:
pgdata:
```
### 7.2 Nginx 配置
```nginx
server {
listen 80;
server_name meeting.example.com;
location / {
proxy_pass http://web:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location /static/ {
alias /app/static/;
}
}
```
---
## 8. 扩展性设计
### 8.1 水平扩展
```
┌──────────────┐
│ Nginx │
│ (负载均衡) │
└──────┬───────┘
│
┌───┴───┐
│ │
▼ ▼
┌─────┐ ┌─────┐
│ Web │ │ Web │
│ 1 │ │ 2 │
└─────┘ └─────┘
│ │
└───┬───┘
│
┌───┴───┐
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ DB │ │ Redis │
│ (主从) │ │ (集群) │
└─────────┘ └─────────┘
```
### 8.2 插件化设计
```python
# Agent 插件接口
class AgentPlugin(ABC):
@abstractmethod
def generate_response(self, message: Message) -> str:
pass
# OpenClaw 插件
class OpenClawPlugin(AgentPlugin):
def generate_response(self, message: Message) -> str:
# OpenClaw 逻辑
pass
# Llama 插件（未来）
class LlamaPlugin(AgentPlugin):
def generate_response(self, message: Message) -> str:
# 调用 Llama API
pass
```
---
## 📝 变更日志
| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| v0.1 | 2026-04-04 | 初始版本 | 飞行侠 |
---
**文档结束** 📝
**创建者**: 飞行侠 🦸
**日期**: 2026-04-04
**状态**: 待北极星确认