sillytavern-repalice/README.md

# 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 部署后访问
# 后端: http://localhost:3000
# 前端: http://localhost:23337
```

### Docker 部署

#### 中国大陆用户特别说明

由于网络原因，在中国大陆构建 Docker 镜像可能会遇到依赖下载缓慢或卡死的问题。项目已针对此情况进行了优化：

1. **自动使用国内镜像源**：通过 `.npmrc` 文件配置 `https://registry.npmmirror.com` 作为 npm 镜像源
2. **简化构建流程**：移除 BuildKit cache mount，使用更稳定的方式
3. **提供一键构建脚本**：
   ```bash
   # Windows 用户（PowerShell）
   .\build-docker.ps1
   
   # Windows 用户（CMD）
   build-docker.bat
   
   # Linux/Mac 用户
   chmod +x build-docker.sh
   ./build-docker.sh
   ```

4. **详细的故障排除指南**：如果构建仍然失败，请参考 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)

#### 标准部署流程

```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/) - 前端框架