st-react/docs/development-progress.md

云酒馆项目开发进度

最后更新：2026-03-02

项目概述

云酒馆是一个现代化的 AI 角色对话平台，采用前后端分离架构，完全兼容 SillyTavern V2/V3 格式。

• 前端：React 18 + TypeScript + Tailwind CSS + Vite
• 后端：Go 1.24 + Gin + PostgreSQL + GORM
• 设计风格：Glassmorphism + 深色主题 (OLED 优化)

---

开发进度总览

模块	状态	完成度	负责人	备注
用户系统	✅ 已完成	100%	-	注册、登录、资料管理
角色卡管理	✅ 已完成	100%	-	完全兼容 ST V2，前后端已打通
预设管理	✅ 已完成	100%	-	前后端已打通，支持导入导出
对话系统	✅ 已完成	95%	-	预设切换、消息重新生成已完成
AI 集成	✅ 已完成	100%	-	AI 配置管理、API 调用已完成
世界书系统	✅ 已完成	100%	-	前后端已打通，触发引擎已集成到对话系统
正则脚本	✅ 已完成	95%	-	完全兼容 ST，已集成到对话流程

图例：

• ✅ 已完成
• 🚧 进行中
• 📋 待开发
• ⏸️ 暂停
• ❌ 已取消

---

一、用户系统 ✅

1.1 后端 API（已完成 - 2024-02-26）

数据模型：

• ✅ AppUser - 用户模型
• ✅ AppUserSession - 会话模型

API 端点：

• ✅ POST /app/auth/register - 用户注册
• ✅ POST /app/auth/login - 用户登录
• ✅ POST /app/auth/refresh - 刷新Token
• ✅ POST /app/auth/logout - 用户登出
• ✅ GET /app/auth/userinfo - 获取用户信息
• ✅ PUT /app/user/profile - 更新用户资料
• ✅ POST /app/user/change-password - 修改密码

核心功能：

• ✅ JWT 认证（7天有效期）
• ✅ bcrypt 密码加密
• ✅ 会话管理（IP、设备信息）
• ✅ 用户状态检查
• ✅ 最后登录记录

文件清单：

server/
├── api/v1/app/auth.go              # API 控制器
├── model/app/
│   ├── app_user.go                 # 用户模型
│   ├── app_user_session.go         # 会话模型
│   ├── request/auth.go             # 请求结构
│   └── response/auth.go            # 响应结构
├── service/app/auth.go             # 业务逻辑
├── router/app/auth.go              # 路由配置
├── middleware/app_jwt.go           # JWT 中间件
└── utils/app_jwt.go                # JWT 工具

1.2 前端页面（已完成 - 2024-02-26）

页面清单：

• ✅ /login - 登录页
• ✅ /register - 注册页
• ✅ /forgot-password - 忘记密码
• ✅ /profile - 用户中心

功能特性：

• ✅ 表单验证
• ✅ 密码可见性切换
• ✅ 第三方登录入口（GitHub/Google）
• ✅ 用户统计数据展示
• ✅ 账号设置、隐私设置、通知设置

文件清单：

web-app/src/pages/
├── LoginPage.tsx
├── RegisterPage.tsx
├── ForgotPasswordPage.tsx
└── ProfilePage.tsx

1.3 前后端对接（已完成 - 2024-02-26）

API 服务层：

• ✅ web-app/src/api/client.ts - Axios 客户端配置
• ✅ web-app/src/api/auth.ts - 用户认证 API 封装

核心功能：

• ✅ Token 自动注入请求头
• ✅ Token 过期自动刷新
• ✅ 统一错误处理
• ✅ 登录状态持久化（localStorage）
• ✅ 登录后跳转用户中心
• ✅ 未登录自动跳转登录页
• ✅ 用户信息实时加载
• ✅ 登出功能

环境配置：

• ✅ .env.development - 开发环境配置（http://localhost:8888）
• ✅ .env.production - 生产环境配置

依赖安装：

• ✅ axios - HTTP 客户端

---

二、角色卡管理 ✅

2.1 后端 API（已完成 - 2024-02-26）

数据模型：

• ✅ AICharacter - 角色卡模型（完全兼容 SillyTavern V2 格式）
• ✅ 使用 JSONB 存储复杂数据（tags, alternateGreetings, characterBook, extensions）
• ✅ 支持公开/私有角色卡
• ✅ 统计信息（使用次数、收藏次数）

API 端点：

• ✅ POST /app/character - 创建角色卡
• ✅ GET /app/character - 获取角色卡列表（分页、搜索、标签筛选）
• ✅ GET /app/character/:id - 获取角色卡详情
• ✅ PUT /app/character/:id - 更新角色卡
• ✅ DELETE /app/character/:id - 删除角色卡
• ✅ POST /app/character/upload - 上传角色卡文件（PNG/JSON）
• ✅ GET /app/character/:id/export - 导出角色卡为 JSON

核心功能：

• ✅ 完全兼容 SillyTavern V2 格式
• ✅ PNG 元数据提取（使用 utils/character_card.go）
• ✅ JSON 格式导入导出
• ✅ 角色卡搜索和标签筛选
• ✅ 用户权限控制（只能编辑自己的角色卡）
• ✅ 支持 Base64 编码的 PNG tEXt chunk

文件清单：

server/
├── api/v1/app/character.go          # API 控制器
├── model/app/ai_character.go        # 角色卡模型
├── model/app/request/character.go   # 请求结构
├── model/app/response/character.go  # 响应结构
├── service/app/character.go         # 业务逻辑
├── router/app/character.go          # 路由配置
└── utils/character_card.go          # SillyTavern V2 格式工具

2.2 前端页面（已完成 - 2024-02-26）

页面：

• ✅ /characters - 角色卡管理页

功能特性：

• ✅ 上传 PNG 角色卡（后端自动解析）
• ✅ 上传 JSON 角色卡
• ✅ 角色卡编辑（名称、描述、性格、场景、系统提示词等）
• ✅ 角色卡导出为 JSON
• ✅ 角色卡删除
• ✅ 搜索功能
• ✅ 分页加载

文件清单：

web-app/src/
├── api/character.ts                 # 角色卡 API 封装
└── pages/CharacterManagePage.tsx    # 角色卡管理页面

2.3 前后端对接（已完成 - 2024-02-26）

API 服务层：

• ✅ web-app/src/api/character.ts - 角色卡 API 封装

核心功能：

• ✅ 角色卡列表加载（分页、搜索）
• ✅ 文件上传（PNG/JSON）
• ✅ 角色卡编辑和保存
• ✅ 角色卡删除
• ✅ 角色卡导出
• ✅ 错误处理和用户提示
• ✅ 登录状态检查

---

三、预设管理 ✅

3.1 后端 API（已完成 - 2026-02-27）

数据模型：

• ✅ AIPreset - 预设模型（完全兼容 SillyTavern 格式）
• ✅ 支持所有采样参数（temperature/topP/topK/frequencyPenalty/presencePenalty/maxTokens/repetitionPenalty/minP/topA）
• ✅ 支持系统提示词和停止序列
• ✅ 使用 JSONB 存储扩展字段（extensions）
• ✅ 支持公开/私有预设和默认预设

API 端点：

• ✅ POST /app/preset - 创建预设
• ✅ GET /app/preset - 获取预设列表（分页、搜索、公开筛选）
• ✅ GET /app/preset/:id - 获取预设详情
• ✅ PUT /app/preset/:id - 更新预设
• ✅ DELETE /app/preset/:id - 删除预设
• ✅ POST /app/preset/:id/default - 设置默认预设
• ✅ POST /app/preset/import - 导入预设（JSON 文件）
• ✅ GET /app/preset/:id/export - 导出预设为 JSON

核心功能：

• ✅ 完全兼容 SillyTavern 预设格式
• ✅ JSON 格式导入导出
• ✅ 预设搜索和筛选
• ✅ 用户权限控制（只能编辑自己的预设）
• ✅ 默认预设管理
• ✅ 使用统计

文件清单：

server/
├── api/v1/app/preset.go             # API 控制器
├── model/app/preset.go              # 预设模型
├── model/app/request/preset.go      # 请求结构
├── model/app/response/preset.go     # 响应结构
├── service/app/preset.go            # 业务逻辑
└── router/app/preset.go             # 路由配置

3.2 前端页面（已完成 - 2026-02-27）

页面：

• ✅ /presets - 预设管理页

功能特性：

• ✅ 导入 JSON 预设
• ✅ 预设参数编辑（Temperature、Top P、Top K、Frequency Penalty、Presence Penalty 等）
• ✅ 预设复制
• ✅ 预设导出
• ✅ 预设删除
• ✅ 搜索功能
• ✅ 设置默认预设

文件清单：

web-app/src/
├── api/preset.ts                    # 预设 API 封装
└── pages/PresetManagePage.tsx       # 预设管理页面

3.3 前后端对接（已完成 - 2026-02-27）

API 服务层：

• ✅ web-app/src/api/preset.ts - 预设 API 封装

核心功能：

• ✅ 预设列表加载（分页、搜索）
• ✅ 文件上传（JSON）
• ✅ 预设编辑和保存
• ✅ 预设删除
• ✅ 预设导出
• ✅ 默认预设设置
• ✅ 错误处理和用户提示
• ✅ 登录状态检查

---

四、对话系统 ✅

4.1 后端 API（已完成 - 2026-02-27）

数据模型：

• ✅ Conversation - 对话会话模型
• ✅ Message - 消息模型
• ✅ 支持用户、角色、预设关联
• ✅ 支持 AI 提供商和模型配置
• ✅ 使用 JSONB 存储对话设置和消息元数据
• ✅ 统计信息（消息数量、Token 使用量）

API 端点：

• ✅ POST /app/conversation - 创建对话
• ✅ GET /app/conversation - 获取对话列表（分页）
• ✅ GET /app/conversation/:id - 获取对话详情
• ✅ PUT /app/conversation/:id/settings - 更新对话设置
• ✅ DELETE /app/conversation/:id - 删除对话
• ✅ GET /app/conversation/:id/messages - 获取消息历史（分页）
• ✅ POST /app/conversation/:id/message - 发送消息
• ✅ POST /app/conversation/:id/message?stream=true - 流式发送消息（SSE）

核心功能：

• ✅ 对话会话管理
• ✅ 消息发送接收
• ✅ 对话历史存储
• ✅ SSE 流式响应支持
• ✅ Token 统计
• ✅ 用户权限控制

文件清单：

server/
├── api/v1/app/conversation.go       # API 控制器
├── model/app/conversation.go        # 对话和消息模型
├── model/app/request/conversation.go # 请求结构
├── model/app/response/conversation.go # 响应结构
├── service/app/conversation.go      # 业务逻辑
└── router/app/conversation.go       # 路由配置

4.2 前端页面（已完成 - 2026-02-27）

页面：

• ✅ /chat - 聊天界面

功能特性：

• ✅ 对话列表侧边栏
• ✅ 角色选择弹窗
• ✅ 消息输入框
• ✅ 对话菜单（导出、删除）
• ✅ 实时消息发送
• ✅ 消息流式显示
• ✅ 对话历史加载
• ✅ 背景图和主题色设置

待完善：

• ✅ 预设切换功能（流式模式已修复应用预设参数）
• ✅ 消息重新生成（支持流式，自动删除旧回复）
• 📋 消息编辑
• 📋 世界书开关
• 📋 正则脚本开关

文件清单：

web-app/src/
├── api/conversation.ts              # 对话 API 封装
├── pages/ChatPage.tsx               # 聊天页面
├── components/Sidebar.tsx           # 侧边栏
├── components/ChatArea.tsx          # 聊天区域
├── components/CharacterPanel.tsx    # 角色面板
└── components/SettingsPanel.tsx     # 设置面板

4.3 前后端对接（已完成 - 2026-02-27）

API 服务层：

• ✅ web-app/src/api/conversation.ts - 对话 API 封装

核心功能：

• ✅ 对话列表加载（分页）
• ✅ 创建新对话
• ✅ 发送消息
• ✅ 消息历史加载
• ✅ 对话设置更新
• ✅ 对话删除
• ✅ 错误处理和用户提示
• ✅ 登录状态检查

---

五、AI 集成 🚧

5.1 后端 API（部分完成 - 2026-02-27）

数据模型：

• ✅ AIConfig - AI 配置模型
• ✅ 支持多种 AI 提供商（OpenAI/Anthropic/Custom）
• ✅ API Key 加密存储
• ✅ 模型配置和参数管理

API 端点：

• ✅ POST /app/ai-config - 创建 AI 配置
• ✅ GET /app/ai-config - 获取配置列表
• ✅ GET /app/ai-config/:id - 获取配置详情
• ✅ PUT /app/ai-config/:id - 更新配置
• ✅ DELETE /app/ai-config/:id - 删除配置
• ✅ POST /app/ai-config/:id/test - 测试连接

待实现功能：

• ✅ 实际 AI API 调用集成（OpenAI/Anthropic）
• 📋 本地模型支持（Ollama/LM Studio）
• 📋 Token 计数优化
• 📋 错误重试机制
• 📋 提示词模板系统

文件清单：

server/
├── api/v1/app/ai_config.go          # API 控制器
├── model/app/ai_config.go           # AI 配置模型
├── model/app/request/ai_config.go   # 请求结构
├── model/app/response/ai_config.go  # 响应结构
└── service/app/ai_config.go         # 业务逻辑

5.2 前端页面（已完成 - 2026-02-27）

功能特性：

• ✅ AI 配置管理界面
• ✅ API Key 配置
• ✅ 模型选择
• ✅ 连接测试

文件清单：

web-app/src/
└── api/aiConfig.ts                  # AI 配置 API 封装

---

六、世界书系统 ✅

6.1 后端 API（已完成 - 2026-02-27）

数据模型：

• ✅ Worldbook - 世界书模型
• ✅ WorldbookEntry - 世界书条目模型（完全兼容 SillyTavern 格式）
• ✅ 支持公开/私有世界书
• ✅ 使用 JSONB 存储关键词数组和扩展字段

已实现字段：

• ✅ keys/secondary_keys - 主关键词和次要关键词
• ✅ content - 条目内容
• ✅ constant/enabled - 常驻和启用标志
• ✅ use_regex/case_sensitive/match_whole_words - 匹配选项
• ✅ selective/selective_logic - 选择性触发逻辑
• ✅ position/depth/order - 注入位置和深度
• ✅ probability/scan_depth - 触发概率和扫描深度
• ✅ group_id - 分组管理

API 端点：

• ✅ POST /app/worldbook - 创建世界书
• ✅ GET /app/worldbook - 获取世界书列表（分页、搜索）
• ✅ GET /app/worldbook/:id - 获取世界书详情
• ✅ PUT /app/worldbook/:id - 更新世界书
• ✅ DELETE /app/worldbook/:id - 删除世界书（级联删除条目）
• ✅ POST /app/worldbook/import - 导入世界书（JSON）
• ✅ GET /app/worldbook/:id/export - 导出世界书为 JSON
• ✅ POST /app/worldbook/:id/entry - 创建条目
• ✅ GET /app/worldbook/:id/entries - 获取条目列表
• ✅ PUT /app/worldbook/:id/entry/:entryId - 更新条目
• ✅ DELETE /app/worldbook/:id/entry/:entryId - 删除条目

核心功能：

• ✅ 完全兼容 SillyTavern 世界书格式
• ✅ JSON 格式导入导出
• ✅ 世界书搜索和筛选
• ✅ 用户权限控制（只能编辑自己的世界书）
• ✅ 条目计数自动更新
• ✅ 关键词触发引擎（WorldbookEngine）
• ✅ 与对话系统完全集成（非流式 + 流式）

文件清单：

server/
├── api/v1/app/worldbook.go          # API 控制器
├── model/app/worldbook.go           # 世界书和条目模型
├── model/app/request/worldbook.go   # 请求结构
├── model/app/response/worldbook.go  # 响应结构
├── service/app/worldbook.go         # 业务逻辑
├── service/app/worldbook_engine.go  # 关键词触发引擎
└── router/app/worldbook.go          # 路由配置

6.2 前端页面（已完成 - 2026-02-27）

页面：

• ✅ /worldbooks - 世界书管理页

功能特性：

• ✅ 导入 JSON 世界书
• ✅ 创建世界书
• ✅ 世界书列表展示
• ✅ 世界书搜索
• ✅ 世界书导出
• ✅ 世界书删除
• ✅ 条目创建和编辑
• ✅ 条目列表展示
• ✅ 条目删除
• ✅ 关键词管理（主关键词、次要关键词）
• ✅ 条目选项配置（常驻、启用、正则、大小写等）
• ✅ 高级选项（触发概率、扫描深度）

文件清单：

web-app/src/
├── api/worldbook.ts                 # 世界书 API 封装
└── pages/WorldbookManagePage.tsx    # 世界书管理页面

6.3 前后端对接（已完成 - 2026-02-27）

API 服务层：

• ✅ web-app/src/api/worldbook.ts - 世界书 API 封装

核心功能：

• ✅ 世界书列表加载（分页、搜索）
• ✅ 文件上传（JSON）
• ✅ 世界书创建、编辑、删除
• ✅ 世界书导出
• ✅ 条目创建、编辑、删除
• ✅ 条目列表加载
• ✅ 错误处理和用户提示
• ✅ 登录状态检查

6.4 对话系统集成（已完成 - 2026-02-27）

触发引擎（service/app/worldbook_engine.go）：

• ✅ WorldbookEngine.ScanAndTrigger - 扫描消息历史并触发匹配条目
• ✅ WorldbookEngine.shouldTrigger - 逐条检查触发条件（constant/keys/scanDepth）
• ✅ WorldbookEngine.matchKeys - 关键词匹配（useRegex/caseSensitive/matchWholeWords）
• ✅ WorldbookEngine.BuildPromptWithWorldbook - 将触发条目注入到系统提示词

集成点：

• ✅ conversation.go:callAIService - 非流式消息世界书注入
• ✅ conversation.go:SendMessageStream - 流式消息世界书注入

执行流程：

用户消息 → 扫描最近 N 条消息 → 匹配关键词 → 触发条目排序 → 注入系统提示词 → AI 处理

设置面板（components/SettingsPanel.tsx）：

• ✅ 世界书开关（启用/禁用）
• ✅ 世界书选择器（下拉列表，显示条目数量）
• ✅ 保存到 conversation.worldbookId 和 conversation.worldbookEnabled

6.5 待完善功能

• 📋 概率触发机制（probability 字段已存储，引擎待实现）
• 📋 递归扫描
• 📋 角色绑定世界书（Character Book）
• 📋 全局世界书

---

七、正则脚本系统 ✅

7.1 后端 API（已完成 - 2026-03-02）

数据模型：

• ✅ RegexScript - 正则脚本模型（完全兼容 SillyTavern 格式）
• ✅ 支持全局、角色、预设三种作用域
• ✅ 使用 JSONB 存储扩展字段和修剪字符串数组

已实现字段：

• ✅ name - 脚本名称
• ✅ find_regex - 查找正则表达式
• ✅ replace_with - 替换字符串
• ✅ trim_strings - 修剪字符串数组
• ✅ placement - 执行阶段（0=输入/1=输出/2=世界书/3=显示）
• ✅ disabled - 禁用标志
• ✅ markdown_only - 仅 Markdown 模式
• ✅ run_on_edit - 编辑时运行
• ✅ prompt_only - 仅提示词模式
• ✅ substitute_regex - 宏替换（{{user}}/{{char}}）
• ✅ min_depth/max_depth - 深度控制
• ✅ scope - 作用域（0=全局/1=角色/2=预设）
• ✅ owner_char_id/owner_preset_id - 所有者 ID
• ✅ order - 执行顺序

API 端点：

• ✅ POST /app/regex - 创建正则脚本
• ✅ GET /app/regex - 获取脚本列表（分页、搜索、作用域筛选）
• ✅ GET /app/regex/:id - 获取脚本详情
• ✅ PUT /app/regex/:id - 更新脚本
• ✅ DELETE /app/regex/:id - 删除脚本
• ✅ POST /app/regex/test - 测试脚本执行

核心功能：

• ✅ 完全兼容 SillyTavern 正则脚本格式
• ✅ 多阶段脚本执行（输入/输出/世界书/显示）
• ✅ 正则表达式解析和执行
• ✅ 宏替换系统（{{user}}/{{char}}/{{original}}）
• ✅ 深度控制和条件执行
• ✅ 与对话系统集成
• ✅ 角色卡导入时自动导入正则脚本
• ✅ 角色卡导出时自动导出正则脚本

文件清单：

server/
├── api/v1/app/regex_script.go       # API 控制器
├── model/app/regex_script.go        # 正则脚本模型
├── model/app/request/regex_script.go # 请求结构
├── model/app/response/regex_script.go # 响应结构
├── service/app/regex_script.go      # 业务逻辑和执行引擎
├── router/app/regex_script.go       # 路由配置
└── service/app/character.go         # 角色卡导入导出集成

7.2 前端页面（已完成 - 2026-03-02）

功能特性：

• ✅ 角色卡管理页面集成正则脚本编辑
• ✅ 导入 JSON 正则脚本（兼容 SillyTavern 格式）
• ✅ 正则脚本创建和编辑
• ✅ 正则脚本列表展示
• ✅ 正则脚本删除
• ✅ 执行阶段选择（输入/输出/世界书/显示）
• ✅ 执行顺序配置
• ✅ 启用/禁用开关
• ✅ 作用域管理（全局/角色/预设）

文件清单：

web-app/src/
├── api/regex.ts                     # 正则脚本 API 封装
├── pages/CharacterManagePage.tsx    # 角色卡管理页面（集成正则脚本）
└── components/MessageContent.tsx    # 消息渲染组件（HTML/脚本渲染）

7.3 对话系统集成（已完成 - 2026-03-02）

集成点：

• ✅ 输入阶段（Placement 0）- 用户消息发送前处理
• ✅ 输出阶段（Placement 1）- AI 回复生成后处理
• ✅ 显示阶段（Placement 3）- 前端渲染前处理
• ✅ 开场白消息处理 - 角色首条消息应用正则脚本

实现位置：

• ✅ conversation.go:SendMessage - 非流式消息发送
• ✅ conversation.go:SendMessageStream - 流式消息发送
• ✅ conversation.go:CreateConversation - 创建对话时处理开场白

执行流程：

用户输入 → 输入阶段脚本 → AI 处理 → 输出阶段脚本 → 保存数据库 → 显示阶段脚本 → 前端渲染

7.4 前端渲染优化（已完成 - 2026-03-02）

HTML 渲染支持：

• ✅ 自动提取 markdown 代码块中的 HTML（html...）
• ✅ 移除 markdown 代码块标记（``` 符号）
• ✅ 自动启用脚本渲染（无需手动点击按钮）
• ✅ iframe 沙箱渲染（支持 JavaScript）
• ✅ 直接 HTML 渲染（无脚本内容）
• ✅ 统一容器样式（避免宽高变化）
• ✅ 响应式宽度适配（强制覆盖固定宽度）

选项按钮支持：

• ✅ 自动解析选项格式（A:/A./A、/A：）
• ✅ 渲染为可点击按钮
• ✅ 点击后自动发送选项内容
• ✅ 支持多种选项格式

文件位置：

• ✅ MessageContent.tsx:173-243 - HTML 提取和处理逻辑
• ✅ MessageContent.tsx:246-290 - iframe 渲染逻辑
• ✅ MessageContent.tsx:348-372 - 渲染模式切换

7.5 全局正则脚本管理（已完成 - 2026-03-02）

功能特性：

• ✅ 独立的全局正则脚本管理页面 /regex-scripts
• ✅ 创建、编辑、删除全局正则脚本
• ✅ 导入导出 JSON 格式脚本（兼容 SillyTavern）
• ✅ 只管理 scope=0 的全局脚本
• ✅ 支持批量导出所有脚本

文件位置：

• ✅ web-app/src/pages/RegexScriptManagePage.tsx - 全局正则脚本管理页面
• ✅ web-app/src/App.tsx - 添加路由配置

7.6 变量系统扩展（已完成 - 2026-03-02）

后端新增变量 (server/service/app/regex_script.go):

• ✅ {{time_12h}} - 12小时制时间
• ✅ {{date_short}} - 短日期格式 (MM/DD/YY)
• ✅ {{weekday}} - 星期几
• ✅ {{month}} - 月份名称
• ✅ {{year}} - 年份
• ✅ {{pick:option1|option2|option3}} - 随机选择一个选项
• ✅ {{tab}} - 制表符
• ✅ {{space}} - 空格
• ✅ {{empty}} - 空字符串

前端变量系统 (web-app/src/store/index.ts):

• ✅ 同步支持所有后端变量
• ✅ substituteVariables() 函数可在前端替换变量
• ✅ extractVariables() 函数可提取文本中的变量

7.7 MVU 状态管理架构（已完成 - 2026-03-02）

核心实现 (web-app/src/store/index.ts):

• ✅ 基于 Zustand 实现完整的 MVU 架构
• ✅ Model: 用户、角色、对话、消息、UI、变量状态
• ✅ Update: 完整的状态更新操作
• ✅ View: 状态选择器（Selectors）
• ✅ 持久化存储（localStorage）
• ✅ DevTools 支持

页面集成:

• ✅ ChatPage.tsx - 集成 MVU store 管理对话状态
• ✅ CharacterManagePage.tsx - 导入 MVU store
• ✅ 角色切换时自动更新变量系统

工具函数:

• ✅ substituteVariables() - 替换文本中的变量
• ✅ extractVariables() - 提取文本中的变量

7.8 待完善功能

• 📋 世界书阶段（Placement 2）脚本执行
• 📋 正则脚本测试界面
• 📋 正则脚本模板库
• 🧪 全局正则脚本功能测试
• 🧪 扩展变量系统测试
• 🧪 MVU store 集成测试

---

八、公共页面 ✅

6.1 已完成页面

• ✅ / - 首页（平台介绍、热门角色）
• ✅ /market - 角色广场（浏览、搜索、分类）
• ✅ /character/:id - 角色详情（信息、评价）

文件：

web-app/src/pages/
├── HomePage.tsx
├── CharacterMarket.tsx
└── CharacterDetail.tsx

---

九、技术债务与优化

9.1 待优化项

• ✅ 前后端 API 对接（已完成：用户、角色卡、预设、对话）
• ✅ 实际 AI API 调用集成
• 📋 错误处理统一化
• 📋 加载状态优化
• 📋 响应式布局完善
• 📋 性能优化（虚拟滚动、懒加载）
• 📋 单元测试
• 📋 E2E 测试
• 📋 实际 AI API 调用集成
• 📋 世界书引擎实现
• 📋 正则脚本引擎实现
• 📋 Prompt Pipeline 优化

9.2 已知问题

• ✅ 对话系统预设切换功能（流式模式已支持）
• ✅ 消息重新生成功能（支持流式，自动删除旧回复）
• 📋 消息编辑功能待实现

---

十、部署相关 📋

10.1 待完成

• 📋 Docker 配置
• 📋 CI/CD 流程
• 📋 环境变量管理
• 📋 数据库迁移脚本
• 📋 备份策略
• 📋 监控告警

---

十一、文档完善 📋

11.1 待补充文档

• 🚧 API 接口文档（Swagger 注释已添加，待生成）
• 📋 数据库设计文档
• 📋 部署文档
• 📋 开发规范
• 📋 贡献指南
• ✅ SillyTavern 兼容优化方案（已完成）

---

开发时间线

2024-02-26

• ✅ 完成用户系统后端 API
• ✅ 完成用户系统前端页面
• ✅ 完成用户系统前后端对接
• ✅ 完成角色卡管理后端 API（完全兼容 SillyTavern V2）
• ✅ 完成角色卡管理前端页面
• ✅ 完成角色卡管理前后端对接
• ✅ 完成预设管理前端页面
• ✅ 完成对话系统前端基础界面
• ✅ 完成公共页面（首页、角色广场、角色详情）
• ✅ 项目结构重构（前后端分离）

2026-02-27

• ✅ 完成预设管理后端 API
  • 实现预设 CRUD 操作
  • 实现预设导入导出（JSON）
  • 实现默认预设管理
  • 完全兼容 SillyTavern 预设格式
• ✅ 完成预设管理前后端对接
• ✅ 完成对话系统后端 API
  • 实现对话会话管理
  • 实现消息发送接收
  • 实现 SSE 流式响应
  • 实现对话历史存储
• ✅ 完成对话系统前后端对接
• ✅ 完成 AI 配置管理模块
• ✅ 完成世界书系统
  • 实现世界书 CRUD 操作
  • 实现世界书条目管理
  • 实现导入导出功能
  • 完全兼容 SillyTavern 格式
• ✅ 编写 SillyTavern 完全兼容优化方案
• ✅ 更新开发进度文档

2026-02-27（续）

• ✅ 完成世界书与对话系统集成
  • 实现 WorldbookEngine 关键词触发引擎
  • 集成到非流式（callAIService）和流式（SendMessageStream）消息路径
  • 实现选择性触发逻辑（constant/keys/useRegex/caseSensitive/matchWholeWords）
  • 实现 SettingsPanel 世界书选择器（启用开关 + 世界书下拉）
• ✅ 修复前端消息渲染 Bug
  • 修复通用代码块正则误判导致消息内容消失的问题（恢复仅识别 ```html 标识符）
  • 修复 iframe 宽度坍缩为 300px 问题（助手消息列从 max-w-[70%] 改为 w-[70%]）
  • 保留 HTML 代码块渲染中的 ``` → <pre><code> 转换逻辑

2026-03-02

• ✅ 完成正则脚本系统后端 API
  • 实现正则脚本 CRUD 操作
  • 实现多阶段脚本执行引擎
  • 实现宏替换系统（{{user}}/{{char}}/{{original}}）
  • 完全兼容 SillyTavern 正则脚本格式
• ✅ 完成正则脚本前端管理界面
  • 集成到角色卡管理页面
  • 支持导入导出正则脚本
  • 支持脚本创建、编辑、删除
• ✅ 完成正则脚本与对话系统集成
  • 输入阶段脚本处理（用户消息）
  • 输出阶段脚本处理（AI 回复）
  • 显示阶段脚本处理（前端渲染）
  • 开场白消息脚本处理
• ✅ 完成前端 HTML 渲染优化
  • 自动提取和渲染 markdown 代码块中的 HTML
  • 移除 markdown 代码块标记
  • 自动启用脚本渲染
  • iframe 沙箱渲染支持
  • 响应式宽度适配
• ✅ 完成选项按钮功能
  • 自动解析选项格式
  • 渲染为可点击按钮
  • 点击后自动发送
• ✅ 修复关键 Bug
  • 修复 GetScriptsForPlacement SQL 查询 bug
  • 修复流式消息未应用正则脚本问题
  • 修复 HTML 渲染宽度问题
  • 修复 markdown 符号残留问题

2026-03-02（今天完成）

• ✅ 完成正则脚本前端 HTML 渲染优化
  • 修复 HTML 代码块渲染问题
  • 移除 markdown ``` 符号残留
  • 自动启用脚本渲染
  • 统一 iframe 和直接 HTML 渲染的容器样式
  • 修复宽度适配问题
• ✅ 完成全局正则脚本管理功能
  • 创建独立的全局正则脚本管理页面 /regex-scripts
  • 支持创建、编辑、删除、导入、导出全局脚本
  • 完全兼容 SillyTavern 格式
• ✅ 扩展变量系统
  • 后端新增 10+ 个变量类型
  • 支持时间格式化、随机选择、特殊字符等
  • 前端同步支持所有变量
• ✅ 实现 MVU 状态管理架构
  • 基于 Zustand 实现完整的 MVU 模式
  • 集成到 ChatPage 和 CharacterManagePage
  • 支持持久化存储和 DevTools
  • 内置变量替换工具函数
• ✅ 修复关键 Bug
  • 修复开场白消息未应用正则脚本问题
  • 修复 API 导出名称不匹配导致页面空白问题

待测试功能（下次工作）

• 🧪 全局正则脚本功能测试
  • 测试全局脚本在所有对话中的应用
  • 测试导入导出功能
  • 测试脚本执行顺序
• 🧪 扩展变量系统测试
  • 测试所有新增变量类型
  • 测试 {{pick:}} 随机选择功能
  • 测试时间格式化变量
• 🧪 MVU Store 集成测试
  • 测试状态持久化
  • 测试变量系统自动更新
  • 测试跨页面状态同步
• 🧪 HTML 渲染优化测试
  • 测试 markdown 代码块中的 HTML 渲染
  • 测试 iframe 宽度自适应
  • 测试脚本自动启用功能
• ✅ 实现实际 AI API 调用（OpenAI/Anthropic）
• ✅ 实现世界书系统（完全兼容 SillyTavern，包含触发引擎和对话集成）
• ✅ 实现正则脚本系统（完全兼容 SillyTavern）
• ✅ 实现 Prompt Pipeline（世界书触发注入、正则处理、提示词构建）
• 📋 完善对话系统高级功能（消息编辑）
• 📋 性能优化与测试
• 📋 部署上线

---

下一步计划

短期目标（本周）

1. ✅ 完成角色卡管理后端 API（已完成）
2. ✅ 完成预设管理后端 API（已完成）
3. ✅ 完成对话系统后端 API（已完成）
4. ✅ 实现实际 AI API 调用（OpenAI/Anthropic）
5. ✅ 完善对话系统高级功能（消息重新生成）

中期目标（本月）

1. ✅ 实现世界书系统（完全兼容 SillyTavern）
   • ✅ 数据模型设计
   • ✅ 关键词触发算法（WorldbookEngine）
   • ✅ 选择性触发逻辑
   • ✅ 与对话系统集成
2. ✅ 实现正则脚本系统（完全兼容 SillyTavern）
   • ✅ 数据模型设计
   • ✅ 多阶段脚本执行
   • ✅ 正则表达式引擎
   • ✅ 宏替换系统
3. ✅ 实现 Prompt Pipeline
   • ✅ 世界书扫描与注入
   • ✅ 正则脚本处理
   • ✅ 提示词构建优化
4. 📋 基础功能测试与优化
5. 📋 消息编辑功能

长期目标（下月）

1. 📋 插件系统设计与实现
2. 📋 性能优化（虚拟滚动、懒加载、缓存）
3. 📋 完善文档（API 文档、部署文档）
4. 📋 Docker 部署配置
5. 📋 CI/CD 流程搭建
6. 📋 部署上线
7. 📋 用户反馈收集

---

团队协作

开发规范

• 代码风格：遵循项目现有风格
• 提交规范：使用 Conventional Commits
• 分支管理：feature/* 用于新功能，bugfix/* 用于修复

沟通渠道

• 技术讨论：GitHub Issues
• 进度同步：本文档
• 代码审查：Pull Request

---

备注

• 本文档持续更新，记录项目开发进度
• 每完成一个功能模块，更新对应状态
• 遇到问题及时记录在"已知问题"部分