完成世界书、骰子、apiconfig页面处理

2026-04-30 01:35:10 +08:00
parent a3e3711b2b
commit ba9b925c32
4602 changed files with 785225 additions and 23 deletions
--- a/backend/models/README.md
+++ b/backend/models/README.md
@@ -0,0 +1,231 @@
+# Backend Models 数据模型说明
+
+## 目录结构
+
+```
+models/
+├── __init__.py          # 包初始化,导出所有模型
+├── sillytavern.py       # SillyTavern 兼容模型 (仅用于导入/导出)
+├── internal.py          # 内部业务模型 (项目核心使用)
+└── README.md            # 本文件
+```
+
+## 模型分类
+
+### 1. SillyTavern 兼容模型 (`sillytavern.py`)
+
+**用途**: 仅用于与 SillyTavern 格式的数据进行导入/导出兼容
+
+**特点**:
+- 严格遵循 SillyTavern 官方规范
+- 不参与内部业务逻辑
+- 所有字段名、结构与 SillyTavern 保持一致
+- 前缀 `ST` 表示 SillyTavern
+
+**主要模型**:
+- `STWorldInfo` - SillyTavern 世界书
+- `STCharacterCard` - SillyTavern 角色卡
+- `STChatHeader` / `STChatMessage` - SillyTavern 聊天记录
+- `STGenerationPreset` - SillyTavern 采样预设
+- `STPromptPreset` - SillyTavern 提示词预设
+
+**使用场景**:
+```python
+# 从 SillyTavern 导入时
+st_data = json.load(file)
+st_character = STCharacterCard(**st_data)
+
+# 转换为内部模型
+internal_character = converter.st_to_internal(st_character)
+
+# 导出到 SillyTavern 时
+st_data = converter.internal_to_st(internal_character)
+json.dump(st_data.dict(), file)
+```
+
+### 2. 内部业务模型 (`internal.py`)
+
+**用途**: 项目内部真正使用的数据结构,所有业务逻辑都基于这些模型
+
+**特点**:
+- 继承并扩展了 SillyTavern 的功能
+- 添加了项目特色功能 (如 LOGIC 激活、RAG 配置、outputSchema 等)
+- 所有 API 响应、数据存储、工作流交换都使用这些模型
+- 无前缀,直接使用语义化名称
+
+**主要模型**:
+
+#### 世界书相关
+- `ActivationType` - 激活方式枚举 (PERMANENT/KEYWORD/RAG/LOGIC)
+- `LogicExpression` - 逻辑表达式
+- `RAGConfig` - RAG 检索配置
+- `WorldInfoEntry` - 世界书条目
+- `WorldInfo` - 世界书
+
+#### 角色卡相关
+- `OutputSchemaField` - 结构化输出 schema
+- `CharacterCard` - 角色卡
+
+#### 聊天记录相关
+- `ChatHeader` - 聊天头
+- `ChatMessage` - 聊天消息
+- `ChatLog` - 完整聊天记录
+
+#### 预设相关
+- `GenerationPreset` - 采样参数预设
+- `PromptRole` - Prompt 角色枚举
+- `PromptEntry` - Prompt 条目
+- `PromptPresetView` - Prompt 预设视图
+
+#### RAG 配置
+- `RAGSearchConfig` - RAG 搜索配置
+- `CharacterRAGConfig` - 角色卡 RAG 配置
+- `ChatRAGConfig` - 聊天 RAG 配置
+
+**使用场景**:
+```python
+# 业务逻辑中直接使用
+from models import CharacterCard, WorldInfo
+
+character = CharacterCard(
+    id="uuid-123",
+    name="Alice",
+    description="...",
+    ...
+)
+
+# API 响应
+@app.get("/characters/{id}")
+async def get_character(id: str):
+    character = service.get_character(id)
+    return character  # 返回 internal 模型
+```
+
+## 数据转换流程
+
+```
+SillyTavern 文件
+    ↓ (导入)
+STCharacterCard (sillytavern.py)
+    ↓ (转换器)
+CharacterCard (internal.py)
+    ↓ (业务处理)
+CharacterCard (internal.py)
+    ↓ (转换器)
+STCharacterCard (sillytavern.py)
+    ↓ (导出)
+SillyTavern 文件
+```
+
+## 开发规范
+
+### ✅ 正确做法
+
+1. **业务逻辑使用 internal 模型**
+   ```python
+   from models import CharacterCard
+   
+   def create_character(data: dict) -> CharacterCard:
+       return CharacterCard(**data)
+   ```
+
+2. **导入时使用转换器**
+   ```python
+   from models import STCharacterCard, CharacterCard
+   from models.converters import CharacterConverter
+   
+   def import_character(file_path: str) -> CharacterCard:
+       st_data = load_json(file_path)
+       st_char = STCharacterCard(**st_data)
+       return CharacterConverter.st_to_internal(st_char)
+   ```
+
+3. **API 响应使用 internal 模型**
+   ```python
+   @app.get("/characters")
+   async def list_characters() -> List[CharacterCard]:
+       return service.list_characters()
+   ```
+
+### ❌ 错误做法
+
+1. **不要在业务逻辑中直接使用 ST 模型**
+   ```python
+   # 错误!
+   from models import STCharacterCard
+   
+   def process_character(char: STCharacterCard):
+       ...
+   ```
+
+2. **不要混合使用两种模型**
+   ```python
+   # 错误!
+   character = CharacterCard(...)
+   character.name = st_character.data.name  # 不要混用
+   ```
+
+3. **不要在 API 中暴露 ST 模型**
+   ```python
+   # 错误!
+   @app.get("/characters")
+   async def list_characters() -> List[STCharacterCard]:
+       ...
+   ```
+
+## 添加新模型
+
+当需要添加新的数据类型时:
+
+1. **判断用途**:
+   - 如果是为了 SillyTavern 兼容 → 添加到 `sillytavern.py`
+   - 如果是项目内部使用 → 添加到 `internal.py`
+
+2. **遵循命名规范**:
+   - SillyTavern 模型: 前缀 `ST`
+   - 内部模型: 无前缀,使用清晰的语义化名称
+
+3. **添加详细注释**:
+   ```python
+   class MyModel(BaseModel):
+       """
+       模型用途说明
+       
+       详细描述该模型的作用、使用场景等
+       """
+       field1: str = Field(..., description="字段说明")
+   ```
+
+4. **在 `__init__.py` 中导出**:
+   ```python
+   from .internal import MyModel
+   
+   __all__ = [
+       ...,
+       'MyModel',
+   ]
+   ```
+
+## 转换器 (待实现)
+
+`models/converters.py` 将提供双向转换功能:
+
+```python
+class CharacterConverter:
+    @staticmethod
+    def st_to_internal(st_char: STCharacterCard) -> CharacterCard:
+        """SillyTavern → Internal"""
+        ...
+    
+    @staticmethod
+    def internal_to_st(int_char: CharacterCard) -> STCharacterCard:
+        """Internal → SillyTavern"""
+        ...
+```
+
+## 总结
+
+- **sillytavern.py** = 外部兼容层 (Import/Export Only)
+- **internal.py** = 内部业务层 (Core Business Logic)
+- **永远在业务逻辑中使用 internal 模型**
+- **通过转换器进行格式转换**