🎨 添加文档和测试用例

docs/重构文档.md

@@ -0,0 +1,458 @@
+这是一个需要长期演进、但方向已经比较清晰的重构计划。为了让“云酒馆”既能承载多用户公共场景，又能高度兼容 SillyTavern（以下简称 **ST**）生态，本方案结合当前代码与 `st/` 源码，对整体架构和落地路径进行整理与校准。
+
+---
+
+## 1. 总体架构与设计原则
+
+### 1.1 技术栈与目录结构
+
+- **前端**：React 18 + TypeScript + Tailwind CSS + Zustand  
+  - 代码目录：`web-app/`
+- **后端**：Go + Gin + GORM + pgvector  
+  - 代码目录：`server/`
+- **数据库**：PostgreSQL 15+（大量使用 JSONB，部分向量字段使用 pgvector）
+- **文件存储**：S3 兼容（MinIO / OSS 等），用于 PNG 角色卡 / 头像等
+- **ST 源码**：`st/` 目录，用作兼容参考与数据样例
+
+### 1.2 云版 vs 本地版的根本差异
+
+- **ST 当前形态**：
+  - 本地应用，配置与数据以文件形式存在 `default/content/**` 与 `data/**`
+  - 单机 / 小规模用户，无严格多租户和权限隔离
+- **云酒馆目标形态**：
+  - **数据库优先**：所有业务数据（用户、角色、预设、世界书、对话、正则脚本等）统一落到 PostgreSQL
+  - **多租户隔离**：所有核心表带 `user_id`，中间件强制 `WHERE user_id = ?`
+  - **前后端分层清晰**：  
+    - 后端 → 唯一“真相来源”（SSOT）：负责 Prompt pipeline、世界书触发、正则处理、变量替换、AI 调用  
+    - 前端 → 纯 UI 壳：负责编辑与展示，不再私自保存“内存版世界书/预设”
+
+---
+
+## 2. 当前系统现状（结合现有代码）
+
+### 2.1 后端（`server/`）
+
+从 `server/model/app/README.md` 以及各模型文件来看，当前状态大致为：
+
+- **用户与会话**（已完成）
+  - 模型：`AppUser`、`AppUserSession`
+  - JWT 登录 / 刷新 / 注销 / 用户资料修改等已具备
+- **角色卡管理（AICharacter）**（已完成）
+  - 模型：`AICharacter`（使用 JSONB 存 ST V2 数据，如 `CardData` / `Tags` 等）
+  - 支持 PNG / JSON 角色卡导入、角色列表、详情、编辑、删除、导出
+- **预设管理（AIPreset）**（模型已就绪，API 待补齐）
+  - 模型：`AIPreset`，已拆分采样参数字段 + `Extensions JSONB`
+- **世界书（AIWorldInfo）与正则脚本（RegexScript）**（模型已存在，逻辑未完全落地）
+  - 模型：`AIWorldInfo`（世界书实体）  
+  - 模型：`RegexScript`（完全对齐 ST 正则脚本字段）
+- **对话与消息**（基础模型已存在）
+  - 模型：`AIChat`、`AIMessage`、`AIMessageSwipe`，用于会话与多候选
+- **AI 配置与向量记忆**（已具备）
+  - 模型：`AIProvider`、`AIModel`、`AIMemoryVector` 等
+
+> 小结：后端数据模型已经为「ST 兼容 + 云平台」打好了基础，但 Prompt pipeline、世界书触发引擎、正则处理引擎等运行时逻辑仍需集中落地。
+
+### 2.2 前端（`web-app/`）
+
+- **状态管理（Zustand）**：`src/store/index.ts`
+  - 单一 Store，明确区分 `Model` / `Actions` / `Selectors`
+  - 内置变量系统 `variables: { user, char, ... }` 与 `substituteVariables()` 工具
+- **用户系统**：登录 / 注册 / 用户资料页已接入后端
+- **角色卡管理**：角色列表 / 上传 PNG/JSON / 编辑 / 导出已接入 `/app/character`
+- **预设管理**：有 UI 骨架，但部分仍依赖前端假数据，需要接入真实 `/app/preset`
+- **聊天界面**：`ChatPage` + `ChatArea` + `MessageContent`
+  - 布局与基本会话切换已完成
+  - 近期已接入：
+    - `regexEngine.ts`：前端正则脚本执行引擎
+    - `textRenderer.ts`：文本渲染管线（解析 `<maintext>` / `<Status_block>` / choices 等）
+    - `ChatArea.tsx` 中从后端加载 `RegexScript` 列表，将用户 / 角色变量与脚本一并传入 `MessageContent`
+
+> 小结：前端已具备 MVU 风格的状态管理与 ST 风格文本渲染能力，下一步是把预设 / 世界书 / 正则选择与后端 pipeline 串联起来。
+
+---
+
+## 3. 目标架构（SillyTavern 兼容实现）
+
+### 3.1 核心领域模型（后端视角）
+
+基于当前 `server/model/app`，目标是让以下模型整体表达 ST 的角色卡 / 世界书 / 正则 / 预设 / 对话体系：
+
+- **AICharacter**
+  - 存 ST 角色卡 V2/V3 标准化版本（结构化字段）+ 原始 JSON 存档（用于无损导出）
+  - 预留：
+    - `raw_card_json JSONB`（若尚未添加，可在后续迁移中补上）
+    - `bound_worldinfo_ids`：角色绑定世界书 ID 列表（可选）
+    - `bound_regex_ids`：角色绑定正则脚本 ID 列表（可选）
+- **AIWorldInfo（Worldbook & WorldbookEntry）**
+  - 支持：
+    - 角色内世界书（挂在某个角色下）
+    - 用户级 / 全局世界书（多个角色共享）
+  - 字段需覆盖 ST 世界书的完整配置：
+    - `keys / secondary_keys / comment / content / constant / disabled / use_regex / case_sensitive / match_whole_words / selective / selective_logic / position / depth / order / probability / sticky / cooldown / delay / group / 额外 JSON`
+- **RegexScript**
+  - 已与 ST 字段对齐：
+    - `findRegex / replaceWith / trimStrings(JSONB)`
+    - `placement`（输入 / 输出 / 世界书 / 显示等阶段）
+    - `disabled / markdownOnly / runOnEdit / promptOnly`
+    - `substituteRegex / minDepth / maxDepth`
+    - `scope (global | character | preset)` + `ownerCharId / ownerPresetId`
+    - `order`（执行顺序）
+- **AIPreset + 绑定关系**
+  - `AIPreset` 存采样参数 + systemPrompt + 其他配置
+  - 预留 `PresetPrompt` / `PresetRegexBinding` 等概念，用于：
+    - 描述 prompt 列表（不同位置、深度）
+    - 绑定正则脚本到特定预设
+- **AIChat / AIMessage**
+  - 对话（Conversation）与消息（Message）  
+  - 与 `AICharacter`、`AIPreset`、AI 配置等建立关联
+  - `AIChat.Settings JSONB` 存储会话级设置：
+    - 当前 presetId
+    - 活动世界书 ID 列表
+    - 活动正则脚本 ID 列表
+
+### 3.2 运行时 Prompt Pipeline（目标形态）
+
+所有客户端（目前只有 React Web，未来可能有更多）统一通过 Go 后端完成以下完整流程：
+
+1. **加载上下文**：
+   - 根据 conversationId 加载：`AIChat`、`AICharacter`、`AIPreset`、AIConfig、绑定的 `AIWorldInfo` 与 `RegexScript`
+2. **输入正则处理（placement = input）**：
+   - 对用户输入文本先跑一遍 RegexScript（global + character + preset）
+3. **写入 user message** 到数据库
+4. **世界书扫描（World Info Engine）**：
+   - 在最近 N 条消息 + 角色描述 / 场景 等组成的扫描文本上，套用 ST 的 world-info 算法：
+     - 主 / 副关键词匹配，支持 `use_regex`、`caseSensitive`、`matchWholeWords`
+     - `selectiveLogic` 控制主 / 副键组合逻辑
+     - `depth`、`sticky`、`cooldown`、`delay`、`probability` 等控制触发频次与时间窗
+5. **Prompt 构建**：
+   - system 部分：角色 system + scenario + 作者注 + preset.systemPrompt + world info
+   - history 部分：最近若干 user/assistant 消息
+   - 预设附加 prompt：按 depth / position / order 注入其他内容
+6. **模型调用**：
+   - 根据 `AIProvider` / `AIModel` / `/app/ai-config` 配置，调用相应厂商 API（OpenAI 兼容 / Anthropic 等）
+   - 支持 SSE 流式输出，将 token 流推送给前端
+7. **输出正则处理（placement = output）**：
+   - 对完整 AI 输出再次执行 RegexScript（global + character + preset）
+8. **写入 assistant message** 到数据库
+9. **返回前端**：
+   - 返回最终完整消息内容；若使用 SSE，还需流式推送增量 token
+
+---
+
+## 4. 关键子系统的详细设计
+
+### 4.1 用户与多租户隔离
+
+- 所有“用户私有”数据表必须带 `user_id`：
+  - 角色：`ai_characters.user_id`
+  - 预设：`ai_presets.user_id`
+  - 世界书：`ai_world_info.user_id`
+  - 正则脚本：`regex_scripts.user_id`
+  - 对话 / 消息：`ai_chats.user_id`、`ai_messages.user_id`
+- **共有资源**：
+  - 官方 Demo 角色 / 预设，可以 `user_id = 0` 或 `NULL`
+- **中间件**：
+  - 在 Gin 中实现统一鉴权中间件，从 JWT 中解析 `user_id`  
+  - 在 Service 层封装“自动附带 `user_id` 条件”的查询方法，避免重复书写 `WHERE user_id = ?`
+
+### 4.2 预设系统（AIPreset）与 ST 兼容
+
+- **ST 现状**：
+  - 预设分散在 `st/default/content/presets/**` 的 JSON 文件中，按 API 类型区分（`context` / `instruct` / `openai` / `textgen` 等）
+  - 前端 `public/scripts/preset-manager.js` 在内存管理这些预设
+- **云酒馆设计**：
+  - 使用 `AIPreset` 表存储统一预设：
+    - 常见采样参数拆为字段（`Temperature/TopP/TopK/...`）
+    - 复杂或厂商特定配置放入 `Extensions jsonb`
+  - 导入工具：
+    - 后台脚本扫描 ST `presets` 目录 → 解析 JSON → 映射为 `AIPreset`
+  - 前端：
+    - 新建 `src/api/preset.ts` 封装 `/app/preset` 系列接口
+    - `PresetManagePage` 完全改为“后端驱动”（删除假数据 `useState`）
+
+### 4.3 变量与宏系统（Variables & Macros）
+
+> 这一块需要区分“现状”与“目标”。
+
+- **ST 当前做法（前端）**：
+  - `public/scripts/variables.js`：维护局部 / 全局变量（基于 `chat_metadata` 与 `extension_settings`）
+  - `public/scripts/macros.js` + `scripts/macros/**`：处理 `{{user}} / {{char}} / {{random}} / {{pick:...}}` 等宏
+  - 宏替换发生在前端构造 prompt 的阶段
+- **云酒馆现状（前端）**：
+  - `web-app/src/store/index.ts`：
+    - `variables: Record<string, string>` 存 `user` / `char` 等
+    - `substituteVariables(text, customVars?)` 支持时间宏、随机数、`pick` 等
+  - `web-app/src/lib/textRenderer.ts` 中也实现了一套独立的变量替换逻辑
+- **目标设计（后端统一化）**：
+  - 中短期可以继续在前端做变量替换（已实现），减少一次性改动量
+  - 中长期建议：
+    - 后端增加 `user_variables` 表，存 `(user_id, key, value)`
+    - 在 Prompt pipeline 最后一步由后端统一执行递归变量 / 宏替换（直到不再出现 `{{...}}`）
+  - 文档中要清楚标注：**“后端统一替换变量”是重构目标，而非当前 ST 现状，也不是当前实现状态。**
+
+### 4.4 世界书引擎（World Info Engine）
+
+- **ST 实现（真实代码）**：`st/public/scripts/world-info.js`
+  - 非常复杂，包含：
+    - 多种扫描策略（按 persona / description / scenario / creatorNotes 等）
+    - 关键字与正则混用（`use_regex`）
+    - 主键 / 副键组合逻辑（`selectiveLogic`）
+    - `depth` / `sticky` / `cooldown` / `delay` / `probability` / `position` / `group` 等参数
+- **云酒馆建议做法**：
+  1. 从以下来源收集“激活世界书列表”：
+     - 用户全局启用：例如用户偏好中的 `activeWorldInfoIds`
+     - 角色绑定：`AICharacter` 上的世界书绑定字段
+     - 会话级设置：`AIChat.Settings.activeWorldInfoIds`
+  2. 遍历所有激活世界书的 entries：
+     - 跳过 `disabled`
+     - 若 `constant = true`，无视关键词匹配直接候选（仍受 sticky / cooldown / delay / probability 影响）
+     - 根据 `use_regex` / `caseSensitive` / `matchWholeWords` 对 `keys` / `secondary_keys` 做匹配
+     - 按 `selectiveLogic` 结合主副键匹配结果
+     - 应用 `depth` / `sticky` / `cooldown` / `delay` / `probability` 等控制触发频次
+  3. 将激活的 entries 按 `order` / `position` 规则，注入到 Prompt 中对应位置
+- **现实建议**：
+  - 为保证兼容性，尽量参考 / 复刻 ST `world-info.js` 的排序和筛选逻辑，而不是“重写一套简化版”。
+
+### 4.5 正则脚本引擎（Regex Scripts）
+
+- **后端模型**：`RegexScript`（已实现，字段与 ST 对齐）
+- **前端执行（显示层）**：
+  - `web-app/src/lib/regexEngine.ts`：
+    - `applyRegexScripts(text, placement, scripts, depth?)`
+    - `processAIOutput` / `processUserInput` 等便捷函数
+    - 支持 `/pattern/flags`、捕获组 `$1/$2/...`、`{{match}}`、`trimStrings`
+  - `ChatArea.tsx`：加载 `/api/regex` 列表，过滤掉 `disabled`，传给 `MessageContent`
+- **后端执行（Prompt 层）**：
+  - 输入阶段：用户文本入库 / 调用模型前，对应 ST 的“input placement”
+  - 输出阶段：模型输出保存 / 返回前，对应 ST 的“output placement”
+  - 世界书阶段：若需要在构造 world info 前后也跑一次 Regex，可以利用 `placement` 细分
+
+---
+
+## 5. 前端重构与集成方案（`web-app/`）
+
+### 5.1 MVU 状态管理（Zustand）
+
+- **现状**：
+  - `src/store/index.ts` 已以 MVU 思路实现：
+    - `AppState` = Model
+    - `AppActions` = Update
+    - React 组件 = View
+  - 使用 `persist` 与 `devtools` 扩展，变量系统内置在 `variables` 字段中
+- **建议**：
+  - 将以下信息也纳入 Store，而不是零散地用本地 `useState`：
+    - 当前会话使用的 `presetId`
+    - 当前会话启用的世界书 ID 列表
+    - 当前会话启用的正则脚本 ID 列表
+  - 通过一个统一的 `ConversationSettings` 结构，与后端 `AIChat.Settings` 对应
+
+### 5.2 角色卡管理页面（CharacterManagePage）
+
+目标：前端字段与 ST V2/V3 完全对齐，为后端世界书 / 正则拆分做好数据基础。
+
+- **字段映射建议**：
+  - `firstMes` ↔ `first_mes`
+  - `mesExample` ↔ `mes_example`
+  - `systemPrompt` ↔ `system_prompt`
+  - `postHistoryInstructions` ↔ `post_history_instructions`
+  - `characterBook` ↔ `character_book`
+  - `extensions` ↔ `extensions`
+- **世界书编辑 UI**：
+  - 在现有 `keys / content / enabled / position` 基础上，逐步引入高级字段（折叠到“高级设置”）：
+    - `secondary_keys`、`constant`、`use_regex`、`case_sensitive`、`match_whole_words`
+    - `selective`、`selective_logic`
+    - `depth`、`order`、`probability`、`sticky`、`cooldown`、`delay`、`group`
+  - 保存时将上述字段完整写入 `characterBook.entries` 中，后端再拆分到 `AIWorldInfo` 相关表
+- **导入/导出**：
+  - 前端不对 ST JSON 结构做“智能改写”，只做表单 ↔ JSON 的字段映射
+  - ST 兼容性由后端 `utils/character_card.go` + `AICharacter` 来保证
+
+### 5.3 预设管理页面（PresetManagePage）
+
+目标：彻底从“前端内存预设”升级为“后端驱动的 ST 预设系统”。
+
+- 实施步骤：
+  1. 后端按规划实现 `/app/preset` 的 CRUD + 导入/导出
+  2. 前端新建 `src/api/preset.ts`，统一管理预设相关请求
+  3. 将 `PresetManagePage` 中的本地假数据与 `useState` 初始值删除，全部改为从 API 加载
+  4. 预设 JSON 字段对齐 ST：
+     - 采样参数：`temperature/top_p/top_k/frequency_penalty/presence_penalty/...`
+     - Prompt 配置：`system_prompt/stop_sequences/...`
+
+### 5.4 聊天与设置面板（ChatPage / SettingsPanel / CharacterPanel）
+
+- **SettingsPanel 增强**：
+  - 增加：
+    - 当前会话使用的 preset（下拉列表来自 `/app/preset`）
+    - 启用的世界书列表（来自 `/app/worldinfo`，初期可只展示角色内世界书）
+    - 启用的正则脚本列表（来自 `/app/regex`）
+  - 保存时调用 `/app/chat/:id/settings`（或 `PUT /app/conversation/:id`）更新 `AIChat.Settings`
+- **ChatArea & MessageContent 集成**：
+  - `ChatArea.tsx`：
+    - 已从 `useAppStore` 取出 `user` 与 `variables`
+    - 已加载 `RegexScript` 列表，并传给 `MessageContent`
+  - `MessageContent.tsx`：
+    - 利用 `regexEngine` + `textRenderer` 完成：
+      - 正则处理（AI 输出修饰）
+      - `<maintext>` / `<Status_block>` / choices 解析
+      - 变量替换 / HTML 转义 / 代码块提取 / XSS 防护
+
+---
+
+## 6. 分阶段落地路线图
+
+### 阶段 1：打通 CRUD 与数据流（短期）
+
+- **后端**：
+  - 巩固 `/app/character`（保证 ST V2/V3 导入/导出稳定）
+  - 实现 `/app/preset` 全套 CRUD + 导入/导出
+  - 补齐世界书 `/app/worldinfo` 与正则 `/app/regex` 接口（基于现有模型）
+- **前端**：
+  - `PresetManagePage` 完全接入 `/app/preset`
+  - 角色编辑页面补全世界书 entry 字段，保持与 ST 的字段对齐
+
+### 阶段 2：实现 Prompt Pipeline 与对话 API（中期）
+
+- **后端**：
+  - 在 service 层实现统一的 `chatPipeline`，串接世界书、正则、变量、预设、AI 调用逻辑
+  - 统一对话入口，例如：`POST /app/chat/:id/messages` 或 `POST /app/conversation/:id/message`
+  - 支持 SSE 流式输出，将 token 流推送给前端
+- **前端**：
+  - Chat 页面改造为消费 SSE 流（追加消息 / 局部更新）
+  - SettingsPanel / CharacterPanel 配置的 preset / 世界书 / 正则 与后端 `AIChat.Settings` 打通
+
+### 阶段 3：插件系统与高级特性（长期）
+
+- **后端**：
+  - 引入插件表与 Hook 定义（`onUserInput` / `onWorldInfoScan` / `beforePromptBuild` / `onAssistantDone`）
+  - 使用 goja / WASM 等方式实现安全的插件执行沙箱
+  - 增强审计、统计与限流机制
+- **前端**：
+  - 插件管理页：安装 / 启用 / 配置 / 查看日志
+  - 调试视图：展示某次回复中有哪些 world info / 正则 / 插件生效
+
+---
+
+## 7. 重要澄清与修正（相对早期文档）
+
+- **关于 Zod**：
+  - 当前 `st/` 源码并未使用 Zod，而是通过 `TavernCardValidator` 等自写校验器验证角色卡结构  
+  - 在 `web-app` 中引入 Zod 进行前端 schema 校验是一个“改进方向”，不是 ST 现状
+- **关于 MVU**：
+  - ST 当前前端仍是 jQuery + 全局脚本，不是典型 MVU 架构  
+  - MVU 已在云酒馆前端的 Zustand Store 中落地，应把 MVU 归于“云酒馆前端架构”，而非 ST 现状
+- **关于变量 / 宏所在层级**：
+  - ST 将变量与宏主要放在前端处理  
+  - 云酒馆的目标是：短期兼容这种做法，中长期逐步迁移到后端统一替换
+- **关于 PNG 块类型**：
+  - ST 将角色卡 JSON 植入 PNG 文本 chunk（如 `tEXt` / 自定义块），不必限定为 `iTXt`  
+  - Go 侧应兼容多种文本块，保证最大兼容性
+
+
+## 8. 核心模块开发方案
+
+### 8.1 用户管理与数据隔离
+
+**ST 现状**: 物理文件夹隔离（`public/users/admin/...`）。
+**重构方案**:
+
+* **数据库设计**: 所有表（`characters`, `chats`, `presets`, `lorebooks`）必须包含 `user_id` 字段。
+* **权限控制**: 后端中间件统一拦截请求，从 JWT 中提取 `user_id`，并在所有 SQL 查询中强制加入 `WHERE user_id = ?` 约束。
+* **隔离策略**:
+* **共有资源**: 官方提供的默认预设、系统角色卡（`user_id` 为 0 或 NULL）。
+* **私有资源**: 用户上传或创建的内容。
+
+
+
+### 8.2 预设系统 (Presets) 兼容方案
+
+**ST 现状**: 大量的 JSON 文件，分为 API、Instruct、Context 等类别。
+**重构方案**:
+
+* **存储**: 在 PostgreSQL 中创建 `presets` 表，核心配置字段设为 `jsonb` 类型。
+* **导入逻辑**: 编写一个 Go 工具类，读取 ST 的 `presets` 文件夹，将 JSON 解析后存入数据库。
+* **注意事项**: ST 的预设经常更新字段，Go 的结构体定义要使用 `map[string]interface{}` 或冗余字段来保证在 ST 更新协议时，你的后端不会因为缺失字段而崩溃。
+
+### 8.3 变量管理与宏引擎 (Variables & Macros)
+
+这是兼容性的灵魂。
+**实现原理**:
+
+1. **基础宏**: `{{user}}`, `{{char}}`, `{{description}}` 等。
+2. **动态变量**: 用户通过 `/setvar` 定义的变量。
+   **重构方案**:
+
+* **后端处理**: 不要在前端替换变量，而是在后端构建 Prompt 的最后一刻进行正则替换。
+* **变量表**: `user_variables` 表，存储 `(user_id, key, value)`。
+* **递归解析**: ST 支持嵌套宏，你的 Go 后端需要实现一个递归替换函数，直到字符串中不再包含 `{{...}}`。
+
+### 8.4 前端渲染与通信兼容 (Iframe/Sandbox)
+
+**ST 现状**: jQuery 操作 DOM，扩展直接注入 HTML。
+**重构方案**:
+
+* **渲染分离**: 使用 React 开发 UI。消息列表应支持 Markdown 解析（推荐使用 `react-markdown` 并配合插件）。
+* **通信协议**:
+* 前端 React 通过 **WebSocket** 或 **SSE** 与 Go 后端保持长连接，模拟 ST 的流式输出。
+* 定义一套标准的 JSON API 响应格式，模仿 ST 的 `/api/...` 接口，以便未来的脚本迁移。
+
+
+
+### 8.5 扩展系统 (Extensions) 的安全性重构
+
+**ST 现状**: 动态加载 JS 脚本，安全性极低。
+**重构方案 (公共平台推荐)**:
+
+* **后端扩展**: 模仿 ST 的插件钩子，但在 Go 后端实现。例如，在发送 Prompt 前，调用一个“拦截器”逻辑。
+* **前端扩展**: 如果要兼容 ST 的 JS 插件，**必须将其运行在沙箱（Sandbox）中**。
+* 使用 `<iframe>` 隔离扩展 UI。
+* 通过 `postMessage` 机制进行通信。
+* **注意事项**: 绝不允许第三方扩展直接访问浏览器的 `localStorage` 或获取用户的 `user_token`。
+
+
+
+---
+
+## 9. Zod 与 MVU 的重构实现
+
+### 9.1 Zod 变量的作用与迁移
+
+在 ST 源码中，Zod 用于 **Runtime Schema Validation**。
+
+* **作用**: 当用户上传一个外部角色卡（JSON 或 PNG 嵌入数据）时，系统无法确定数据是否完整。Zod 会在前端校验数据格式，如果缺失关键字段，会提供默认值或报错。
+* **重构建议**:
+* **前端**: 继续在 React 中使用 `zod`。在处理角色卡导入逻辑时，定义与 ST 完全一致的 `CharacterSchema`。
+* **后端**: Go 端使用 `go-playground/validator` 或直接解析 `jsonb`。确保你的 Go 结构体（Struct）打上 `json:",omitempty"` 标签，以处理 ST 角色卡中不稳定的可选字段。
+
+
+
+### 9.2 MVU (Model-View-Update) 的应用
+
+* **作用**: ST 引入 MVU 是为了解决 jQuery 状态难以管理的问题。
+* **重构建议**:
+* 在 React 中，MVU 就是 **Zustand/Redux + React Components**。
+* **Model**: Zustand 中的 `store`。
+* **Update**: Store 中的 `actions`。
+* **View**: React 组件。
+* 你不需要在代码里写 `mvu` 变量名，只需遵循这种单向数据流即可实现比 ST 稳定得多的状态管理。
+
+
+
+---
+
+## 10. 开发注意事项 (踩坑预警)
+
+1. **角色卡解析**: ST 的 PNG 角色卡数据存放在 PNG 的 `iTXt` 块中。Go 语言需要使用 `image/png` 包并手动读取这些 Metadata 块。不要只支持 JSON，因为大部分玩家的资源都是 PNG。
+2. **Lorebook (世界书) 逻辑**:
+* 这是最难兼容的部分。它涉及：关键字扫描、递归深度、插入位置、插入顺序。
+* **建议**: 直接复刻 ST 的 `world-info.js` 中的排序算法。如果这部分算法不一致，AI 的表现会与原版 ST 大相径庭。
+
+
+3. **计算 Token**: ST 使用 `Tiktoken` 或特定模型的 Tokenizer。为了节省服务器资源，建议在前端进行初次计算，后端在调用 API 前再次校准。
+4. **跨域与 API 代理**: 公共平台需要处理大量大模型 API 的转发。Go 后端要实现一个高性能的 **Proxy Layer**，处理超时、重试以及不同厂商（OpenAI, Anthropic, Google）的协议转换。
+
+
+
+
+
+