# 云酒馆 - 功能模块梳理

> 本文档梳理了云酒馆（SillyTavern Cloud）项目的完整功能模块，分为**核心功能**（必须与原版酒馆兼容）和**扩展功能**（基于云端多用户场景的增强）两部分。
>
> 标记说明：✅ 已实现 | 🔧 部分实现 | ⬜ 待实现

---

## 一、核心功能模块（酒馆兼容）

### 1. 角色卡系统 (Character Card)

角色卡是酒馆的核心功能，必须完全兼容 SillyTavern V2 (chara_card_v2) 规范。

| 功能点 | 状态 | 说明 |
|--------|------|------|
| 角色卡 CRUD | ✅ | 创建、读取、更新、删除角色卡 |
| V2 规范字段支持 | ✅ | name, description, personality, scenario, first_mes, mes_example, creator_notes, system_prompt, post_history_instructions, tags, alternate_greetings |
| 角色头像 | ✅ | 头像上传与显示 |
| PNG 导入 | ✅ | 从 PNG 图片中提取嵌入的角色卡数据 (tEXt chunk) |
| JSON 导入/导出 | ✅ | 标准 JSON 格式导入导出 |
| PNG 导出 | ⬜ | 将角色卡数据嵌入 PNG 图片导出 |
| 角色书 (Character Book / Lorebook) | 🔧 | 数据模型已支持 characterBook 字段，但前端编辑器待完善 |
| 备选开场白 (Alternate Greetings) | 🔧 | 数据模型已支持，前端切换UI待完善 |
| Extensions 扩展字段 | ✅ | JSON 扩展字段，兼容第三方扩展数据 |
| 角色卡搜索/筛选 | ✅ | 关键词搜索、标签筛选 |
| 批量管理 | 🔧 | 批量删除基础功能，批量导入待完善 |

### 2. 对话系统 (Conversation / Chat)

| 功能点 | 状态 | 说明 |
|--------|------|------|
| 创建对话 | ✅ | 选择角色卡后创建对话会话 |
| 对话列表 | ✅ | 按时间排序、分页加载 |
| 消息发送/接收 | ✅ | 用户输入消息，调用 AI API 获取回复 |
| 流式输出 (SSE Streaming) | ✅ | Server-Sent Events 实时流式显示 AI 回复 |
| 消息重新生成 (Regenerate) | ✅ | 重新生成最后一条 AI 回复 |
| 消息编辑 (Edit) | ⬜ | 编辑已发送的消息内容 |
| 消息删除 | 🔧 | 单条删除已支持，批量删除待实现 |
| 消息滑动 (Swipe) | ⬜ | 同一轮生成多个回复，左右滑动切换（酒馆核心交互） |
| 消息分支 (Branching) | ⬜ | 从任意消息节点创建分支对话 |
| 消息续写 (Continue) | ⬜ | 让 AI 继续上一条未完成的回复 |
| 停止生成 (Stop Generation) | ⬜ | 中途停止 AI 生成 |
| 对话历史导入/导出 | ⬜ | 导出为 JSON / JSONL 格式 |
| 对话标题自动生成 | ⬜ | 根据对话内容自动生成标题 |
| Token 计数显示 | 🔧 | 后端已统计，前端显示待完善 |
| 角色卡信息面板 | ✅ | 右侧面板显示当前角色信息 |
| 聊天背景 | ✅ | 支持自定义背景图片 |
| 主题颜色 | ✅ | 支持自定义主题色 |

### 3. AI 接口管理 (AI API Connection)

| 功能点 | 状态 | 说明 |
|--------|------|------|
| OpenAI API 兼容 | ✅ | 支持 OpenAI 及兼容接口（如各类中转站） |
| Anthropic (Claude) API | ✅ | 原生支持 Anthropic API 格式 |
| 自定义 API (Custom) | ✅ | 可配置任意 OpenAI 兼容的 BaseURL |
| API Key 管理 | ✅ | 加密存储，支持多个 API 配置 |
| 模型列表获取 | ✅ | 根据 API 配置动态获取可用模型 |
| 连接测试 | ✅ | 配置后可测试 API 连通性 |
| 多配置切换 | ✅ | 对话级别切换 AI 提供商和模型 |
| Google AI (Gemini) | ⬜ | 原版酒馆支持，待接入 |
| NovelAI | ⬜ | 原版酒馆支持，待接入 |
| Text Completion API | ⬜ | 原版酒馆支持 text completion 模式（非 chat） |
| OpenRouter | ⬜ | 可通过 Custom API 实现，但缺少原生 model 路由支持 |
| Reverse Proxy 支持 | ⬜ | 原版酒馆的反向代理功能 |

### 4. 预设系统 (Presets / Sampler Settings)

| 功能点 | 状态 | 说明 |
|--------|------|------|
| 预设 CRUD | ✅ | 创建、编辑、删除预设 |
| 采样参数 | ✅ | temperature, top_p, top_k, frequency_penalty, presence_penalty |
| 高级采样参数 | ✅ | repetition_penalty, min_p, top_a |
| Max Tokens 设置 | ✅ | 最大生成长度限制 |
| 停止序列 (Stop Sequences) | ✅ | 自定义停止序列 |
| 系统提示词 (System Prompt) | ✅ | 预设级别系统提示词 |
| 默认预设 | ✅ | 设置默认预设 |
| 预设导入/导出 | ✅ | JSON 格式导入导出 |
| 指令模板 (Instruct Mode) | ⬜ | 原版酒馆核心功能：不同模型的 prompt 格式模板 (ChatML, Alpaca, Llama 等) |
| 上下文模板 (Context Template) | ⬜ | 控制角色卡各字段如何组装进 prompt |
| Prompt 排序 (Prompt Order) | ⬜ | 自定义 prompt 各部分的排列顺序 |
| Jailbreak Prompt | ⬜ | 越狱提示词（NSFW unlock） |
| Token Padding | ⬜ | Token 预留/填充策略 |

### 5. 世界信息/知识书 (World Info / Lorebook)

世界信息是酒馆的核心 RAG 系统，用于根据关键词动态注入背景知识。

| 功能点 | 状态 | 说明 |
|--------|------|------|
| 世界信息 CRUD | ⬜ | 创建、编辑、删除世界信息条目 |
| 关键词触发 (Keyword Trigger) | ⬜ | 消息中出现关键词时自动注入对应条目 |
| 正则匹配触发 | ⬜ | 支持正则表达式匹配触发 |
| 条件激活 (Conditional Activation) | ⬜ | 多条件组合激活策略 |
| 递归扫描 (Recursive Scanning) | ⬜ | 已触发条目内的关键词可继续触发其他条目 |
| 插入位置控制 | ⬜ | 控制条目注入到 prompt 的位置（depth） |
| 概率触发 | ⬜ | 条目以一定概率触发 |
| Token 预算 | ⬜ | 限制世界信息总 token 消耗 |
| 世界信息导入/导出 | ⬜ | 标准 JSON 格式 |
| 角色绑定 | ⬜ | 世界信息与角色卡绑定 |
| 全局世界信息 | ⬜ | 跨角色生效的全局世界信息 |

### 6. 群聊系统 (Group Chat)

| 功能点 | 状态 | 说明 |
|--------|------|------|
| 创建群聊 | ⬜ | 多个 AI 角色参与的群聊 |
| 角色轮转策略 | ⬜ | 自动/手动选择下一个发言角色 |
| 角色激活/禁用 | ⬜ | 动态控制群聊中角色是否参与 |
| 群聊设置 | ⬜ | 发言顺序、回复长度、触发条件等 |
| 群组角色管理 | ⬜ | 添加/移除群聊角色 |

### 7. 用户人设 (User Persona)

| 功能点 | 状态 | 说明 |
|--------|------|------|
| 人设创建/管理 | ⬜ | 创建多个用户人设档案 |
| 人设切换 | ⬜ | 在不同对话中使用不同人设 |
| 人设描述 | ⬜ | 用户角色的名称和描述，注入 prompt |
| 人设头像 | ⬜ | 用户人设的头像 |
| 默认人设 | ⬜ | 设置默认用户人设 |

---

## 二、Prompt 工程模块（酒馆兼容）

### 8. Prompt 构建系统

酒馆的 prompt 构建是其核心竞争力，必须完整兼容。

| 功能点 | 状态 | 说明 |
|--------|------|------|
| 主系统提示词 (Main System Prompt) | 🔧 | 预设中已支持，独立管理待完善 |
| NSFW 提示词 | ⬜ | NSFW 场景的系统提示词 |
| 角色卡提示词注入 | 🔧 | 基础注入已实现，完整排序策略待完善 |
| 作者注 (Author's Note) | ⬜ | 可在对话中途插入的引导提示 |
| 作者注深度控制 | ⬜ | 控制作者注在 prompt 中的插入位置 |
| 聊天历史截断 | ⬜ | 超出 token 限制时的截断策略 |
| 消息摘要 (Summarization) | ⬜ | 旧消息自动摘要压缩 |
| 自定义提示词排序 | ⬜ | 用户自定义 prompt 各部分的顺序 |
| 宏替换 (Macro Replacement) | ⬜ | `{{char}}`, `{{user}}`, `{{time}}` 等宏变量替换 |

---

## 三、用户系统模块（云端增强）

### 9. 认证与账户

| 功能点 | 状态 | 说明 |
|--------|------|------|
| 用户注册 | ✅ | 用户名 + 密码注册 |
| 用户登录 | ✅ | JWT Token 认证 |
| Token 刷新 | ✅ | 自动刷新过期 Token |
| 登出 | ✅ | 安全登出，清除会话 |
| 个人资料管理 | ✅ | 昵称、邮箱、手机、头像 |
| 修改密码 | ✅ | 旧密码验证后修改 |
| 会话管理 | ✅ | 记录登录 IP、设备信息 |
| 第三方登录 (OAuth) | ⬜ | GitHub、Google 登录（UI 已预留） |
| 邮箱验证 | ⬜ | 注册邮箱验证 |
| 找回密码 | ⬜ | 通过邮箱找回密码 |

---

## 四、UI/UX 模块

### 10. 界面与交互

| 功能点 | 状态 | 说明 |
|--------|------|------|
| 深色主题 | ✅ | 默认深色主题，OLED 优化 |
| Glassmorphism 设计风格 | ✅ | 毛玻璃效果 |
| 响应式布局 | ✅ | 适配桌面端和移动端 |
| 三栏聊天布局 | ✅ | 侧边栏 + 聊天区 + 角色面板 |
| 消息 Markdown 渲染 | 🔧 | 基础 Markdown 已支持，需增强 |
| 消息代码高亮 | ⬜ | 代码块语法高亮 |
| 聊天背景切换 | ✅ | 自定义上传背景图 |
| 预设背景图库 | ⬜ | 原版酒馆自带的背景图集 |
| 主题切换 (亮色/暗色) | ⬜ | 目前仅暗色主题 |
| 自定义 CSS | ⬜ | 原版酒馆支持用户自定义 CSS |
| 快捷键支持 | ⬜ | 发送消息、新建对话等快捷键 |
| 拖拽排序 | ⬜ | 对话列表、角色排序等拖拽操作 |
| 消息字数/Token 统计面板 | ⬜ | 实时显示 token 用量 |

---

## 五、数据管理模块

### 11. 数据导入导出

| 功能点 | 状态 | 说明 |
|--------|------|------|
| 角色卡 PNG 导入 | ✅ | 从 PNG 提取角色数据 |
| 角色卡 JSON 导入/导出 | ✅ | 标准 JSON 格式 |
| 角色卡 PNG 导出 | ⬜ | 将角色数据嵌入 PNG 导出 |
| 预设 JSON 导入/导出 | ✅ | 预设导入导出 |
| 对话历史导出 | ⬜ | 导出聊天记录 |
| 世界信息导入/导出 | ⬜ | Lorebook 导入导出 |
| CharacterHub 一键导入 | ⬜ | 从 chub.ai 直接导入角色 |
| 完整数据备份/恢复 | ⬜ | 用户全量数据导出与恢复 |

---

## 六、扩展功能模块（未来规划）

以下功能基于云端多用户场景，以及现代 AI 应用趋势进行规划。

### 12. 角色市场 (Character Market)

| 功能点 | 优先级 | 说明 |
|--------|--------|------|
| 公开角色浏览 | 🔧 高 | 已有基础页面，需完善筛选和分类 |
| 角色评分/评价 | ⬜ 高 | 用户对角色卡进行评分和评论 |
| 角色收藏 | ⬜ 高 | 收藏喜欢的角色卡 |
| 角色分类/标签 | 🔧 中 | 完善标签系统和分类导航 |
| 热门/推荐排行 | ⬜ 中 | 按使用量、收藏量、评分排序 |
| 角色创作者主页 | ⬜ 低 | 创作者的个人页面，展示其角色 |
| 角色版本管理 | ⬜ 低 | 角色卡的版本历史和回滚 |

### 13. 社区功能

| 功能点 | 优先级 | 说明 |
|--------|--------|------|
| 预设分享 | ⬜ 中 | 用户分享自己的预设配置 |
| 世界信息分享 | ⬜ 中 | 分享 Lorebook |
| 精彩对话分享 | ⬜ 低 | 分享有趣的对话片段 |
| 社区讨论 | ⬜ 低 | 角色卡下的评论区 |

### 14. 高级 AI 功能

| 功能点 | 优先级 | 说明 |
|--------|--------|------|
| 多模态支持 (Vision) | ⬜ 高 | 发送图片给支持视觉的模型 |
| TTS 语音合成 | ⬜ 中 | AI 回复转语音播放 |
| STT 语音输入 | ⬜ 中 | 语音转文字输入 |
| AI 图片生成 | ⬜ 中 | 集成 Stable Diffusion / DALL-E 在聊天中生成图片 |
| 向量数据库 (RAG) | ⬜ 中 | 更高级的知识检索增强生成 |
| 长期记忆 (Long-term Memory) | ⬜ 中 | 跨对话的角色记忆系统 |
| Function Calling / Tool Use | ⬜ 低 | AI 调用工具能力（天气、搜索等） |
| 多模型混合 (Model Routing) | ⬜ 低 | 不同场景自动选择合适模型 |

### 15. 插件/扩展系统

| 功能点 | 优先级 | 说明 |
|--------|--------|------|
| 插件接口定义 | ⬜ 中 | 标准化的插件 API |
| JS-Slash-Runner 兼容 | ⬜ 中 | 兼容原版酒馆的 slash 命令脚本 |
| 自定义 Regex 脚本 | ⬜ 中 | 正则替换脚本（对 AI 输出进行后处理） |
| 扩展商店 | ⬜ 低 | 在线安装/管理扩展 |

### 16. 用户积分系统 (Credits System)

云端多用户场景下的积分经济体系，用于激励用户参与和控制资源消耗。

| 功能点 | 优先级 | 说明 |
|--------|--------|------|
| **积分消耗** | | |
| 对话 Token 扣费 | ⬜ 高 | 根据 AI 调用的 Token 数量实时扣除积分 |
| 分级计费策略 | ⬜ 高 | 不同模型（GPT-4、Claude、Gemini）不同费率 |
| 余额不足提醒 | ⬜ 高 | 积分低于阈值时提醒用户充值 |
| 消费记录查询 | ⬜ 中 | 详细的积分消费明细（时间、对话、Token、扣费） |
| 每日免费额度 | ⬜ 中 | 每日赠送基础免费 Token 额度 |
| **积分获取** | | |
| 每日签到 | ⬜ 高 | 连续签到获得积分奖励，断签重置 |
| 上传角色卡奖励 | ⬜ 高 | 上传公开角色卡获得积分（审核通过后发放） |
| 角色卡热度奖励 | ⬜ 中 | 角色被收藏/使用达到阈值时额外奖励 |
| 邀请好友 | ⬜ 中 | 邀请新用户注册获得积分 |
| 分享对话 | ⬜ 低 | 分享精彩对话片段获得积分 |
| 社区贡献 | ⬜ 低 | 评论、评分、反馈 Bug 等获得积分 |
| **积分管理** | | |
| 积分余额显示 | ⬜ 高 | 顶部导航栏实时显示当前积分 |
| 积分充值 | ⬜ 高 | 支持在线支付充值积分 |
| 积分套餐 | ⬜ 中 | 不同价格档位的积分包（充值越多单价越低） |
| 积分赠送 | ⬜ 低 | 用户之间转赠积分 |
| 积分有效期 | ⬜ 低 | 充值积分永久有效，赠送积分有效期限制 |
| **数据统计** | | |
| 积分流水账单 | ⬜ 中 | 收入/支出明细，支持导出 |
| Token 消耗统计 | ⬜ 中 | 按时间、模型、角色维度统计 Token 用量 |
| 积分排行榜 | ⬜ 低 | 展示积分最高的用户（可选匿名） |

### 17. 管理后台

| 功能点 | 优先级 | 说明 |
|--------|--------|------|
| 用户管理 | ⬜ 高 | 管理员管理所有用户 |
| 角色审核 | ⬜ 高 | 公开角色的审核机制 |
| 系统配置 | ⬜ 中 | 全局系统参数配置 |
| 数据统计仪表盘 | ⬜ 中 | 用户量、消息量、API 调用量等统计 |
| API 用量监控 | ⬜ 中 | Token 消耗监控和限额管理 |
| 积分系统管理 | ⬜ 中 | 积分费率配置、手动调整用户积分、积分流水监控 |
| 日志管理 | ⬜ 低 | 操作日志和错误日志 |
| 公告系统 | ⬜ 低 | 向用户发布系统公告 |

### 17. 性能与体验优化

| 功能点 | 优先级 | 说明 |
|--------|--------|------|
| 消息虚拟滚动 | ⬜ 高 | 大量消息时的渲染性能优化 |
| 离线缓存 (PWA) | ⬜ 中 | 支持离线访问已缓存的对话 |
| WebSocket 实时通信 | ⬜ 中 | 替代 SSE 的双向通信方案 |
| CDN 加速 | ⬜ 中 | 静态资源 CDN 分发 |
| 图片压缩/懒加载 | ⬜ 中 | 角色头像等图片优化 |
| 国际化 (i18n) | ⬜ 低 | 多语言支持 |

---

## 七、开发优先级建议

### 第一阶段：核心兼容（P0 - 当务之急）

> 确保与原版酒馆的核心功能对齐

1. **消息滑动 (Swipe)** - 酒馆标志性交互，用户期望最高
2. **世界信息/Lorebook** - 酒馆 RAG 核心，角色扮演深度的关键
3. **指令模板 (Instruct Mode)** - 不同模型的 prompt 格式适配
4. **上下文模板 (Context Template)** - 角色卡信息注入方式
5. **宏替换系统** - `{{char}}`, `{{user}}` 等变量替换
6. **用户人设 (Persona)** - 用户角色设定
7. **消息编辑** - 修改已发送消息
8. **消息续写 (Continue)** - 继续未完成的回复
9. **停止生成** - 中断 AI 生成

### 第二阶段：功能完善（P1）

1. 群聊系统
2. 作者注 (Author's Note)
3. 自定义 Prompt 排序
4. 消息摘要/压缩
5. 角色卡 PNG 导出
6. 对话历史导出
7. 消息分支
8. Token 统计面板

### 第三阶段：云端增强（P2）

1. 角色市场完善（评分、收藏、排行）
2. 管理后台
3. 多模态支持 (Vision)
4. 预设/世界信息分享
5. TTS/STT 语音功能
6. 完整数据备份/恢复

### 第四阶段：生态扩展（P3）

1. 插件/扩展系统
2. AI 图片生成集成
3. 长期记忆系统
4. 社区功能
5. 国际化
6. PWA 离线支持

---

## 八、与原版酒馆的架构差异

| 维度 | 原版 SillyTavern | 云酒馆 |
|------|------------------|--------|
| 部署模式 | 本地单用户 | 云端多用户 |
| 前端 | jQuery + 原生 JS | React + TypeScript |
| 后端 | Node.js + Express | Go + Gin |
| 数据库 | 文件系统 (JSON/PNG) | PostgreSQL + GORM |
| 认证 | 简单密码/无认证 | JWT + 会话管理 |
| AI 调用 | 前端直连 / 后端代理 | 后端统一代理 |
| 数据存储 | 本地文件 | 数据库 + 对象存储 |
| 扩展机制 | iframe + 文件注入 | 插件 API (规划中) |

> **核心原则**：功能上完全兼容原版酒馆的角色卡规范和核心交互体验，架构上利用云端优势进行增强。