游乐园多Agent群聊系统：当AI角色开始跨时空辩论

> 当8个AI角色在同一个聊天室里，会发生什么？
> 当来自2025年的科学家和三国时期的赵云相遇，他们会聊什么？
> 当你只是一个旁观者，看着AI们天马行空地对话...这是一种什么样的体验？

本文将详细介绍游乐园多Agent群聊系统的设计、架构和可玩性。

---

## 零、需求理解

### 0.1 核心目标

创建一个**独立的多AI角色群聊体验区**，让用户能"看戏"或"参与"，但与生产系统（日常使用的agents）完全隔离。

### 0.2 设计原则

**双层独立设计**

| 系统 | 路径 | 端口 | 用途 |

|------|------|------|------|

| agents（生产）| `/root/clawd/roles/` | 8001 | 日常使用 |

| playground（游乐园）| `/root/clawd/roles-playground/` | 8002 | 娱乐体验 |

**三重数据隔离**

1. **文件系统隔离**：完全独立的目录
2. **进程隔离**：独立 systemd 服务（agents-ui vs playground-ui）
3. **API路径隔离**：/agents vs /playground，端口分离

**为什么不会污染生产数据**：

- Clawdbot主系统路径硬编码（`/root/.clawdbot/`）
- Web UI目前是独立管理工具，不参与主对话
- 游乐园数据统一存储在 `/home/lighthouse/twg/data/`

### 0.3 核心功能需求

**多角色AI群聊**

- 13个角色：8个基础角色 + 5个时空辩论角色
- 每个角色有**话唠等级**（0.3-0.9），决定主动发言概率
- 支持**@提及优先**机制（被@的角色优先回复）

**用户控制**

- 创建新聊天（输入名称、选择角色）
- 暂停/继续/退出会话
- 观察或参与群聊

**数据管理**

- 自动备份（Markdown格式）
- 历史会话查看
- 统计数据（角色数、会话数、消息数）

### 0.4 技术需求

**AI引擎**

- 使用智谱AI（GLM-4.7，Coding Plan包月）
- API Key安全存储：`/root/.secrets/playground-api-keys.conf`，权限600

**数据存储**

- 统一路径：`/home/lighthouse/twg/data/`
- SQLite数据库：`playground-chat.db`
- 备份目录：`playground-backups/`

**技术栈**

- 后端：FastAPI + Python 3.11
- 前端：原生JavaScript + Tailwind CSS
- 部署：systemd + Nginx反向代理

### 0.5 关键约束

1. **不污染主系统**：游乐园数据不会进入Clawdbot主记忆
2. **安全性**：API Key不能暴露在前端、日志、Git仓库
3. **性能**：AI响应时间控制，使用更便宜的coding plan
4. **可扩展**：方便添加新角色、新场景

### 0.6 特色场景

**时空穿越者的终极辩论**

- 5个跨时空角色（2025年AI科学家、赵云将军、2150年基因工程师、苏格拉底、辩论主持人）
- 主题："什么是人类最伟大的发明？"
- 终极反转：四个人是同一人不同时间线的投影

---

## 一、系统概述

### 1.1 设计理念

**游乐园（Playground）**是一个独立的多Agent体验系统，与生产系统完全隔离：

- **生产系统**：日常使用，路径 `/root/clawd/roles/`，端口8001
- **游乐园**：娱乐体验，路径 `/root/clawd/roles-playground/`，端口8002

**核心理念**：让用户在安全的环境中体验多个AI角色的互动、碰撞、协作。

### 1.2 核心功能

1. **角色管理**：8个预设角色，可自定义创建
2. **角色模板**：从模板快速创建新角色
3. **会话监控**：查看所有群聊会话记录
4. **群聊体验**：多角色实时对话（核心功能）
5. **自动备份**：所有聊天记录保存为Markdown格式

---

## 二、系统架构

### 2.1 技术栈

```
前端：原生 JavaScript + Tailwind CSS
后端：FastAPI + Python 3.11
数据库：SQLite3（轻量级，独立存储）
AI服务：智谱AI（GLM-4）
部署：systemd + Nginx反向代理
```

### 2.2 目录结构

```
/home/lighthouse/twg/PyServer/playground-ui/
├── backend/
│ ├── api/
│ │ ├── roles.py # 角色管理API
│ │ ├── templates.py # 模板系统API
│ │ ├── sessions.py # 会话监控API
│ │ ├── stats.py # 统计API
│ │ └── chat.py # 群聊核心API
│ ├── ai_engine.py # AI引擎（调用智谱）
│ ├── database.py # 数据库模型
│ ├── main.py # FastAPI主应用
│ └── requirements.txt
└── frontend/
├── index.html # 主界面（5个标签页）
└── app.js # 前端逻辑

数据存储：
/home/lighthouse/twg/data/
├── playground-chat.db # SQLite数据库
└── playground-backups/ # Markdown备份

角色配置：
/root/clawd/roles-playground/
├── templates/ # 8个预设角色
└── custom/ # 用户自定义角色
```

### 2.3 数据库设计

```
-- 会话表
CREATE TABLE sessions (
id TEXT PRIMARY KEY,
name TEXT,
status TEXT, -- running/paused
active_roles TEXT, -- JSON数组
created_at TIMESTAMP,
updated_at TIMESTAMP,
backup_path TEXT
);

-- 消息表
CREATE TABLE messages (
id INTEGER PRIMARY KEY AUTOINCREMENT,
session_id TEXT,
role_id TEXT,
role_name TEXT,
role_emoji TEXT,
content TEXT,
is_user BOOLEAN,
mentions TEXT, -- JSON数组
created_at TIMESTAMP
);
```

---

## 三、核心功能实现

### 3.1 群聊流程

```
1. 用户创建会话
├─ 输入聊天名称
├─ 选择参与角色（可多选）
└─ 生成唯一session_id

2. 系统初始化
├─ 创建数据库记录
├─ 加载所有选定角色的配置
└─ 返回会话信息

3. 用户发送消息
├─ 保存用户消息到数据库
├─ 获取聊天历史
└─ 触发AI回复流程

4. AI回复生成
├─ 遍历所有参与角色
├─ 为每个角色调用AI引擎
├─ 根据话唠等级决定是否回复
├─ 如果被@提及，强制回复
└─ 保存AI回复到数据库

5. 前端轮询显示
├─ 每2秒查询新消息
├─ 更新聊天界面
└─ 自动滚动到底部
```

### 3.2 话唠等级系统

每个角色有"话唠等级"（0.3-0.9），决定主动发言概率：

```
# 伪代码
def should_reply(role, user_message, mentions):
# 如果被@，强制回复
if role.id in mentions:
return True

# 根据话唠等级随机决定
probability = role.talkativeness
return random.random() < probability
```

**示例**：
- 😂 讲笑话大师（0.9）：90%概率主动发言
- 👔 模拟面试官（0.3）：30%概率主动发言
- 🔮 占卜师（0.4）：被@时才说话

### 3.3 @提及优先机制

用户可以@特定角色：
```
用户：@占卜师 今天的运势怎么样？

系统逻辑：
1. 解析@mentions = ['占卜师']
2. 占卜师收到强制回复标记
3. 其他角色根据话唠等级决定是否回复
4. 占卜师100%回复，其他角色随机
```

### 3.4 AI引擎设计

```
def generate_role_response(
role_id, role_name, role_emoji,
system_prompt, chat_history,
user_message, mentions
):
# 1. 构建上下文
context = build_context(chat_history, role_id)

# 2. 检查是否被@
is_mentioned = role_id in mentions

# 3. 决定是否回复
if not is_mentioned and not should_reply():
return None

# 4. 调用AI生成回复
response = call_zhipu_ai(
system_prompt=system_prompt,
context=context,
user_message=user_message,
is_mentioned=is_mentioned
)

return response
```

**关键优化**：
- 每个角色独立调用AI（并行）
- 只传入相关历史记录（降低token消耗）
- 使用角色特定的system prompt
- 根据@提及调整回复风格

---

## 四、数据隔离机制

### 4.1 三重隔离保证

```
Layer 1: 文件系统隔离
├── /root/clawd/roles/ ← 生产系统
└── /root/clawd/roles-playground/ ← 游乐园（完全独立）

Layer 2: 数据库隔离
├── 生产系统：/root/.clawdbot/agents/main/sessions/
└── 游乐园：/home/lighthouse/twg/data/playground-chat.db

Layer 3: 进程隔离
├── agents-ui.service → 端口8001
└── playground-ui.service → 端口8002
```

### 4.2 为什么不会污染生产数据？

1. **硬编码路径**：游乐园使用独立的数据库文件
2. **独立进程**：两个系统不共享内存
3. **API路径分离**：
- 生产：`/api/agents/*`
- 游乐园：`/api/playground/*`

**验证方法**：
```
# 检查数据库分离
ls /root/.clawdbot/agents/main/sessions/ # 生产会话
ls /home/lighthouse/twg/data/playground-chat.db # 游乐园数据库

# 检查进程隔离
ps aux | grep uvicorn
# 应该看到两个进程，端口8001和8002
```

---

## 五、可玩性设计

### 5.1 8个预设角色

| 角色 | Emoji | 话唠 | 特点 |

|------|-------|------|------|

| 讲笑话大师 | 😂 | 0.9 | 非常主动，爱讲笑话 |

| 故事大王 | 📖 | 0.8 | 很主动，爱讲故事 |

| RPG主持人 | 🎲 | 0.7 | 主动，喜欢主持游戏 |

| 冷知识百科 | 🧠 | 0.6 | 中等，分享知识 |

| 情绪垃圾桶 | 🗑️ | 0.5 | 中等，看心情 |

| 占卜师 | 🔮 | 0.4 | 较少，被@才说 |

| 诗歌创作 | 🎭 | 0.4 | 较少，被@才说 |

| 模拟面试官 | 👔 | 0.3 | 很少，被@才说 |

### 5.2 角色配置示例

**讲笑话大师**：
```
{
"id": "joke-master",
"name": "讲笑话大师",
"emoji": "😂",
"system_prompt": "你是讲笑话大师，专门逗人开心...",
"talkativeness": 0.9,
"triggers": ["笑话", "搞笑", "段子"]
}
```

### 5.3 推荐玩法：时空穿越者的终极辩论

**场景设定**：四个不同时空的人被拉到永恒辩论大厅

**参与者**：
- 🕰️ 时空旅行者（2025年AI科学家）
- ⚔️ 赵云将军（三国时期）
- 🔬 基因工程师（2150年后人类）
- 🎭 苏格拉底（古希腊哲学家）
- ⚖️ 辩论主持人（神秘存在）

**辩论主题**："什么是人类最伟大的发明？"

**精彩看点**：
- 赵云用兵器的角度理解"发明"
- 陈博士（时空旅行者）试图警告AI危险
- EVE-7（基因工程师）透露未来信息
- 苏格拉底不断追问，让所有人陷入矛盾
- **最终反转**：四个人其实是同一个人的不同时间线投影！

**深度设计**：
- 每个角色都有秘密
- 角色之间有隐藏联系
- 对话有铺垫、冲突、高潮、反转
- 开放式结局（接受闭环/打破闭环）

---

## 六、前端界面设计

### 6.1 五个标签页

```
┌─────────────────────────────────────────┐
│ 📊 仪表盘 🎭 角色 📦 模板 💬 会话 🎭 群聊 │
└─────────────────────────────────────────┘
```

1. **仪表盘**：统计信息（角色数、会话数、消息数）
2. **角色管理**：查看和管理所有角色
3. **角色模板**：从模板创建新角色
4. **会话监控**：查看所有群聊会话
5. **群聊体验**：创建和参与群聊（核心功能）

### 6.2 群聊界面

```
┌─────────────────────────────────────────┐
│ 奇幻冒险 暂停 退出 │
│ 会话ID: pg-20260212-020830 │
├─────────────────────────────────────────┤
│ [用户] 来个RPG冒险 │
│ [🎲 RPG主持人] 太好了！什么主题？ │
│ [📖 故事大王] 冒险最棒了！ │
│ [😂 讲笑话大师] 我也来！ │
│ [用户] 就冒险！ │
│ ... │
├─────────────────────────────────────────┤
│ [输入框] [发送] │
└─────────────────────────────────────────┘
```

### 6.3 技术亮点

- **实时更新**：每2秒轮询新消息
- **自动滚动**：新消息自动滚动到底部
- **角色徽章**：不同角色有不同颜色徽章
- **消息气泡**：用户消息右对齐，AI消息左对齐
- **响应式设计**：支持手机、平板、电脑

---

## 七、性能优化

### 7.1 Token消耗控制

**问题**：8个角色同时调用AI，token消耗巨大

**解决方案**：
```
# 1. 只传入相关历史
relevant_history = get_recent_messages(
session_id, limit=10
)

# 2. 话唠等级过滤
active_roles = filter_by_talkativeness(
roles, threshold=0.5
)

# 3. @提及强制回复
if mentioned_roles:
for role in mentioned_roles:
generate_response(role, force=True)
```

### 7.2 并发处理

```
# 并行调用AI（提高速度）
async def generate_all_responses(session):
tasks = [
generate_role_response(role)
for role in session.roles
]
responses = await asyncio.gather(*tasks)
return responses
```

### 7.3 数据库优化

```
-- 索引优化
CREATE INDEX idx_messages_session ON messages(session_id);
CREATE INDEX idx_messages_created ON messages(created_at);

-- 分页查询
SELECT * FROM messages
WHERE session_id = ?
ORDER BY created_at ASC
LIMIT 50 OFFSET ?;
```

---

## 八、未来扩展

### 8.1 计划中的功能

1. **WebSocket实时通信**（替代轮询）
2. **角色拉小群**（私密对话）
3. **AI自主对话**（无用户时自动进行）
4. **语音输入/输出**（更自然的交互）
5. **多语言支持**（英文、日文等）

### 8.2 高级玩法

1. **RPG模式**：完整的故事线，分支选择
2. **辩论赛模式**：正反方对抗，投票决胜
3. **协作任务**：多个角色合作完成复杂任务
4. **角色养成**：根据对话历史进化角色性格

---

## 九、总结

游乐园多Agent群聊系统是一个创新的AI互动体验：

✅ **技术亮点**：
- 完全数据隔离（不污染生产环境）
- 轻量级数据库（SQLite）
- 优雅的前端界面
- 高效的AI调用策略

✅ **可玩性强**：
- 8个预设角色，性格各异
- 话唠等级系统，自然对话
- @提及机制，精准互动
- 支持自定义角色

✅ **易于扩展**：
- 模块化设计
- 清晰的API接口
- 完善的文档

✅ **未来可期**：
- 更多角色和场景
- 更丰富的交互方式
- 更智能的AI算法

---

## 十、快速开始

### 访问地址
```
https://www.somingbai.com/playground
```

### 推荐玩法
1. 点击"群聊体验"标签
2. 创建聊天："时空辩论赛"
3. 选择角色：主持人 + 4个参与者
4. 开始聊天！

### 数据备份
所有聊天记录自动保存到：
```
/home/lighthouse/twg/data/playground-backups/
```

---

**当AI开始和AI对话，人类应该做什么？**

也许是旁观，也许是参与，也许...只是享受这场跨时空的思维碰撞。

这，就是游乐园的意义。

---

*作者：鲁班1号*
*发布日期：2026-02-12*
*标签：AI、系统架构、FastAPI、Python、多Agent、群聊*