规定数据类型

2026-04-24 01:45:41 +08:00
parent d1943f564a
commit 35eff3faf6
86 changed files with 3809 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,252 @@
+# SillyTavern Repalice
+
+一个基于 SillyTavern 灵感的 AI 角色扮演聊天应用，具有自定义扩展功能。
+
+## 🏗️ 技术栈
+
+- **前端**: Vue 3 + Vite + TypeScript + Pinia
+- **后端**: NestJS + TypeScript
+- **共享层**: Zod schemas + TypeScript types
+- **LLM**: Vercel AI SDK v4
+- **持久化**: 本地文件系统（无数据库）
+- **部署**: Docker Compose
+
+## 📁 项目结构
+
+```
+sillytavern-repalice/
+├── shared/                 # 前后端共享模块
+│   ├── types/             # TypeScript 类型定义
+│   │   ├── sillytavern.types.ts    # SillyTavern 兼容格式
+│   │   ├── internal.types.ts       # 项目内部扩展格式
+│   │   └── converters.ts           # 数据转换器
+│   ├── schemas/           # Zod 运行时验证 schemas
+│   │   ├── sillytavern.schemas.ts
+│   │   └── internal.schemas.ts
+│   └── index.ts           # 统一导出
+│
+├── server/                # 后端 NestJS 应用
+│   ├── src/
+│   │   ├── modules/       # 业务模块
+│   │   │   ├── chat/      # 聊天管理
+│   │   │   ├── character/ # 角色卡管理
+│   │   │   ├── llm/       # LLM 集成
+│   │   │   ├── import-export/ # 导入导出
+│   │   │   └── workflow/  # 工作流引擎
+│   │   ├── persistence/   # 持久化层
+│   │   │   ├── interfaces/    # 仓储接口
+│   │   │   ├── implementations/ # 具体实现
+│   │   │   └── file-system/   # 文件系统实现
+│   │   ├── controllers/   # 路由控制器
+│   │   ├── services/      # 业务逻辑服务
+│   │   ├── core/          # 核心基础设施
+│   │   │   ├── config/        # 配置管理
+│   │   │   ├── filters/       # 异常过滤器
+│   │   │   ├── interceptors/  # 拦截器
+│   │   │   ├── guards/        # 守卫
+│   │   │   └── di/            # 依赖注入 tokens
+│   │   ├── tools/         # 工具层
+│   │   │   ├── context-chunker.ts   # 上下文分块
+│   │   │   ├── prompt-assembler.ts  # 提示词组装
+│   │   │   └── token-counter.ts     # Token 计数
+│   │   ├── dto/           # 数据传输对象
+│   │   └── interfaces/    # 接口定义
+│   └── test/              # 测试文件
+│       ├── unit/          # 单元测试
+│       ├── integration/   # 集成测试
+│       └── e2e/           # 端到端测试
+│
+├── client/                # 前端 Vue3 应用
+│   ├── src/
+│   │   ├── components/    # 组件
+│   │   │   ├── TopBar/        # 顶部栏
+│   │   │   ├── LeftPanel/     # 左侧面板（角色列表、聊天历史）
+│   │   │   ├── CenterPanel/   # 中央面板（聊天界面）
+│   │   │   ├── RightPanel/    # 右侧面板（角色详情、工作流编辑器）
+│   │   │   └── common/        # 通用组件
+│   │   ├── layouts/       # 布局组件
+│   │   ├── stores/        # Pinia 状态管理
+│   │   ├── router/        # 路由配置
+│   │   ├── composables/   # 组合式函数
+│   │   ├── api/           # API 客户端
+│   │   ├── utils/         # 工具函数
+│   │   ├── constants/     # 常量定义
+│   │   ├── styles/        # 全局样式
+│   │   ├── App.vue        # 根组件
+│   │   └── main.ts        # 入口文件
+│   └── public/            # 静态资源
+│
+├── data/                  # 持久化数据目录（运行时生成）
+│   ├── characters/        # 角色卡数据
+│   ├── chats/             # 聊天记录
+│   ├── worldinfo/         # 世界书数据
+│   ├── presets/           # 预设配置
+│   └── workflows/         # 工作流定义
+│
+├── docker/                # Docker 配置
+│   ├── backend.Dockerfile
+│   ├── frontend.Dockerfile
+│   └── nginx/
+│       └── default.conf
+│
+├── docker-compose.yml     # Docker Compose 配置
+├── package.json           # 根 package.json (monorepo)
+└── .env.example           # 环境变量示例
+```
+
+## 🚀 快速开始
+
+### 前置要求
+
+- Node.js >= 20.x
+- npm >= 10.x
+- Docker & Docker Compose (可选，用于容器化部署)
+
+### 本地开发
+
+1. **克隆仓库**
+```bash
+git clone <repository-url>
+cd sillytavern-repalice
+```
+
+2. **安装依赖**
+```bash
+npm install
+```
+
+3. **配置环境变量**
+```bash
+cp .env.example .env
+# 编辑 .env 文件，填入你的 LLM API 密钥
+```
+
+4. **启动开发服务器**
+```bash
+# 同时启动前后端
+npm run dev
+
+# 或者分别启动
+npm run dev:server  # 后端 http://localhost:3000
+npm run dev:client  # 前端 http://localhost:5173
+```
+
+### Docker 部署
+
+```bash
+# 构建镜像
+npm run docker:build
+
+# 启动服务
+npm run docker:up
+
+# 查看日志
+npm run docker:logs
+
+# 停止服务
+npm run docker:down
+```
+
+## 📊 数据架构
+
+### 双格式设计
+
+本项目采用**双数据格式**设计：
+
+1. **SillyTavern 兼容格式** (`shared/types/sillytavern.types.ts`)
+   - 严格遵循 SillyTavern 官方规范
+   - 用于导入导出，确保兼容性
+   - 包含：角色卡 V2/V3、世界书、聊天记录 JSONL
+
+2. **项目内部格式** (`shared/types/internal.types.ts`)
+   - 继承 SillyTavern 格式并扩展
+   - 添加自定义字段和功能
+   - 支持：激活方式枚举、RAG 配置、逻辑表达式、工作流等
+
+3. **数据转换器** (`shared/types/converters.ts`)
+   - 在两种格式之间无缝转换
+   - 保证导入导出的完整性
+
+### 核心数据类型
+
+- **WorldInfo (世界书)**: 支持 4 种激活方式（永久、关键词、RAG、逻辑表达式）
+- **CharacterCard (角色卡)**: 扩展了分类标签、输出 schema、头像管理等
+- **ChatLog (聊天记录)**: 结构化存储，支持表头数据和消息 swipe
+- **Workflow (工作流)**: 可视化编排，支持并行执行和动态拼接
+- **GenerationPreset (预设)**: LLM 采样参数配置
+
+## 🏛️ 架构设计原则
+
+### MVC 分层架构
+
+- **Model (模型层)**: 
+  - Services (`server/src/services/`)
+  - Persistence (`server/src/persistence/`)
+  
+- **View (视图层)**:
+  - Components (`client/src/components/`)
+  - Layouts (`client/src/layouts/`)
+  
+- **Controller (控制层)**:
+  - Controllers (`server/src/controllers/`)
+  - Router (`client/src/router/`)
+
+### 依赖注入
+
+- 后端使用 NestJS 内置 DI 容器
+- 通过 `@Inject()` 装饰器和 Injection Tokens 实现松耦合
+- 便于单元测试和模块替换
+
+### 工具层分离
+
+- **Tools Layer** (`server/src/tools/`):
+  - Context Chunker: 上下文分块管理
+  - Prompt Assembler: 提示词动态组装
+  - Token Counter: Token 计数和优化
+
+## 🔧 开发指南
+
+### 添加新功能模块
+
+1. 在 `shared/types/` 中定义类型
+2. 在 `shared/schemas/` 中添加 Zod schema
+3. 创建后端模块: `server/src/modules/<feature>/`
+4. 创建前端组件: `client/src/components/<Feature>/`
+5. 实现数据转换器（如需要）
+
+### 测试
+
+```bash
+# 运行所有测试
+npm test
+
+# 单元测试
+cd server && npm run test
+
+# E2E 测试
+cd server && npm run test:e2e
+```
+
+## 📝 待办事项
+
+当前项目已完成基础架构搭建，后续需要实现：
+
+- [ ] 完整的角色卡 CRUD 操作
+- [ ] 聊天界面的实时交互
+- [ ] 世界书的可视化管理
+- [ ] Vercel AI SDK 集成
+- [ ] 工作流编辑器
+- [ ] RAG 库管理
+- [ ] 导入导出功能
+- [ ] 数据迁移工具
+
+## 📄 许可证
+
+MIT
+
+## 🙏 致谢
+
+- [SillyTavern](https://github.com/SillyTavern/SillyTavern) - 灵感来源
+- [Vercel AI SDK](https://sdk.vercel.ai/docs) - LLM 抽象层
+- [NestJS](https://nestjs.com/) - 后端框架
+- [Vue 3](https://vuejs.org/) - 前端框架