chenmoranzhi/SillyTavern_replica
2
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

基本完成，舒适性修补

Browse Source
This commit is contained in:
moranzhi
2026-05-10 00:09:29 +08:00
parent 9faccc2c03
commit d6745b45a5
78 changed files with 3133 additions and 8850 deletions
Download Patch File Download Diff File Expand all files Collapse all files

559
README.md
View File

@@ -1,166 +1,131 @@
# LLM Workflow Engine
一个基于 React + TypeScript + FastAPI 的 AI 聊天工作流引擎，支持流式对话、动态表格生成、图片生成等功能。
一个功能强大的 LLM 聊天工作流引擎，兼容 SillyTavern 生态系统。
## 🚀 技术栈
## 📋 目录
### 前端
- **React 18** - 用户界面框架
- **TypeScript** - 类型安全的 JavaScript
- **Vite** - 现代化的前端构建工具
- **Zustand** - 轻量级状态管理
- **React Markdown** - Markdown 渲染
- **Tailwind CSS** - 实用优先的 CSS 框架
- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [核心功能](#核心功能)
- [开发指南](#开发指南)
- [配置说明](#配置说明)
- [常见问题](#常见问题)
---
## 功能特性
### 🎯 核心功能
- **多模型支持** - 兼容 OpenAI、Claude、Gemini 等多种 LLM API
- **角色卡系统** - 完整的角色创建、导入、导出功能（兼容 SillyTavern 格式）
- **聊天管理** - 多聊天切换、历史总结、消息编辑
- **预设系统** - 灵活的提示词组件管理，支持拖拽排序
- **世界书** - 动态世界知识注入系统
- **正则替换** - 强大的文本处理规则系统（完全兼容 SillyTavern）
### ✨ 高级功能
- **酒馆助手（Tavern Helper）**
- JavaScript 沙盒执行引擎
- 提示词模板系统（支持 `{{var}}`、`{{roll}}`、`{{random}}` 等语法）
- 脚本管理（全局/角色/预设三种作用域）
- 代码块渲染功能
- **多主题支持** - 完整的 CSS 变量主题系统
- **流式输出** - 实时显示 AI 生成内容
- **消息 Swipes** - 多版本切换和重roll功能
- **API 配置管理** - 安全的 API Key 存储和加密
### 🔒 安全特性
- API Key 加密存储（Fernet 对称加密）
- JavaScript 沙盒隔离执行
- 危险 API 拦截机制
- 环境变量安全管理
---
## 技术栈
### 后端
- **FastAPI** - 现代化的 Python Web 框架
- **Python 3.11** - 编程语言
- **Uvicorn** - ASGI 服务器
- **WebSockets** - 实时通信
## 📁 项目结构
- **框架**: FastAPI (Python 3.11+)
- **数据库**: 文件系统 + JSON（轻量级，易于备份）
- **WebSocket**: 实时流式通信
- **加密**: Fernet 对称加密（cryptography 库）
- **依赖管理**: pip + requirements.txt
```
llm_workflow_engine/
├── backend/ # 后端服务
│ ├── api/ # API 路由
│ ├── core/ # 核心模型和配置
│ ├── tools/ # 工具函数
│ ├── workflows/ # 工作流定义
│ ├── Dockerfile # 后端 Docker 配置
│ ├── main.py # 后端入口
│ └── requirements.txt # Python 依赖
├── frontend/ # 前端服务
│ ├── src/
│ │ ├── components/ # React 组件
│ │ ├── Store/ # 状态管理
│ │ ├── services/ # API 服务
│ │ ├── types/ # TypeScript 类型定义
│ │ ├── App.tsx # 主应用组件
│ │ └── main.tsx # 入口文件
│ ├── Dockerfile # 前端 Docker 配置
│ ├── nginx.conf # Nginx 配置（生产环境）
│ ├── package.json # Node.js 依赖
│ └── tsconfig.json # TypeScript 配置
├── data/ # 数据存储
├── docker-compose.yml # Docker Compose 配置
└── README.md # 项目文档
```
### 前端
## 🛠️ 安装和运行
- **框架**: React 18 + Vite
- **状态管理**: Zustand（轻量级 Redux 替代）
- **样式**: CSS3 + CSS 变量（支持多主题）
- **Markdown**: react-markdown + remark-gfm
- **HTTP 客户端**: Fetch API
### 使用 Docker Compose（推荐）
### 部署
这是最简单的运行方式，适合开发和生产环境。
- **容器化**: Docker + Docker Compose
- **反向代理**: Nginx
- **开发服务器**: Vite HMR
1. **克隆项目**
```bash
git clone <repository-url>
cd llm_workflow_engine
```
---
2. **配置环境变量**
```bash
# 复制环境变量模板
cp .env.example .env
## 快速开始
# 根据需要编辑 .env 文件
```
### 环境要求
3. **启动服务**
```bash
# 构建并启动所有服务
docker-compose up --build
# 或者在后台运行
docker-compose up -d --build
```
4. **访问应用**
- 前端界面: http://localhost:23338
- 后端 API: http://localhost:23337
- API 文档: http://localhost:23337/docs
5. **停止服务**
```bash
docker-compose down
```
- Python 3.11+
- Node.js 18+
- Docker & Docker Compose（可选）
### 本地开发
如果你想分别运行前后端进行开发：
#### 1. 克隆项目
#### 后端开发
1. **安装 Python 依赖**
```bash
git clone https://github.com/your-repo/llm-workflow-engine.git
cd llm-workflow-engine
```
#### 2. 后端启动
```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 安装依赖
pip install -r backend/requirements.txt
# 启动服务
cd backend
pip install -r requirements.txt
python main.py
```
2. **启动后端服务**
```bash
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
```
后端服务将在 `http://localhost:23338` 启动。
#### 前端开发
#### 3. 前端启动
1. **安装 Node.js 依赖**
```bash
cd frontend
npm install
```
2. **启动前端开发服务器**
```bash
# 安装依赖
npm install
# 启动开发服务器
npm run dev
```
3. **访问应用**
- 前端界面: http://localhost:5173
- 确保后端在 http://localhost:8000 运行
前端将在 `http://localhost:5173` 启动，自动代理 API 请求到后端。
## 🔧 配置说明
### 环境变量
#### 前端环境变量 (frontend/.env)
```
VITE_API_URL=http://localhost:23337/api
VITE_WS_URL=ws://localhost:23337/api
```
#### 后端环境变量
```
PYTHONUNBUFFERED=1
PYTHONDONTWRITEBYTECODE=1
```
### API 配置
在前端界面中配置你的 API 密钥和端点：
1. 打开左侧栏的 "API 配置" 标签
2. 添加你的 API 配置（URL 和密钥）
3. 选择要使用的 API
## 📖 功能特性
- ✅ **流式对话** - 实时显示 AI 回复
- ✅ **多角色支持** - 支持多个聊天角色和会话
- ✅ **消息编辑** - 可以编辑和删除历史消息
- ✅ **HTML 渲染** - 支持 Markdown 和 HTML 渲染
- ✅ **动态表格** - 自动生成和更新数据表格
- ✅ **图片生成** - 集成图片生成工作流
- ✅ **世界书** - 管理角色和世界设定
- ✅ **预设管理** - 保存和加载不同的对话预设
## 🐳 Docker 命令参考
### Docker 部署
```bash
# 构建并启动
docker-compose up --build
# 后台运行
# 一键启动
docker-compose up -d
# 查看日志
@@ -168,59 +133,319 @@ docker-compose logs -f
# 停止服务
docker-compose down
# 重启服务
docker-compose restart
# 进入容器
docker-compose exec backend bash
docker-compose exec frontend sh
# 清理所有容器和卷
docker-compose down -v
```
## 🔍 开发工具
访问 `http://localhost:80` 即可使用。
### 前端
---
## 项目结构
```
llm-workflow-engine/
├── backend/ # 后端服务
│ ├── api/ # API 路由
│ │ └── routes/ # 路由处理
│ ├── core/ # 核心配置
│ ├── models/ # 数据模型
│ ├── services/ # 业务逻辑
│ │ ├── chat_service.py # 聊天服务
│ │ ├── js_sandbox.py # JavaScript 沙盒
│ │ ├── script_manager.py # 脚本管理器
│ │ ├── regex_service.py # 正则服务
│ │ └── ...
│ ├── utils/ # 工具函数
│ ├── main.py # 应用入口
│ └── requirements.txt # Python 依赖
│
├── frontend/ # 前端应用
│ ├── src/
│ │ ├── components/ # React 组件
│ │ │ ├── Mid/ # 中间区域（聊天框）
│ │ │ ├── SideBarLeft/ # 左侧边栏
│ │ │ │ └── tabs/ # 标签页组件
│ │ │ │ └── TavernHelper/ # 酒馆助手
│ │ │ ├── SideBarRight/# 右侧边栏
│ │ │ └── TopBar/ # 顶部栏
│ │ ├── Store/ # Zustand 状态管理
│ │ ├── styles/ # 全局样式
│ │ ├── types/ # TypeScript 类型定义
│ │ ├── utils/ # 工具函数
│ │ ├── App.jsx # 根组件
│ │ └── main.jsx # 应用入口
│ ├── package.json # Node.js 依赖
│ └── vite.config.js # Vite 配置
│
├── data/ # 数据目录（运行时生成）
│ ├── chat/ # 聊天记录
│ ├── preset/ # 预设文件
│ ├── worldbooks/ # 世界书
│ ├── regex/ # 正则规则
│ └── ...
│
├── docker-compose.yml # Docker 编排
├── .env.example # 环境变量示例
├── .gitignore # Git 忽略文件
└── README.md # 项目文档
```
---
## 核心功能
### 1. 酒馆助手（Tavern Helper）
完全兼容 SillyTavern 酒馆助手的提示词模板系统。
#### 支持的语法
| 语法 | 功能 | 示例 |
|------|------|------|
| `{{var}}` 或 `{{getvar::key}}` | 获取变量 | `{{name}}` |
| `{{setvar::key::value}}` | 设置变量 | `{{setvar::age::25}}` |
| `{{delvar::key}}` | 删除变量 | `{{delvar::temp}}` |
| `{{random::a,b,c}}` | 随机选择（逗号） | `{{random::苹果,香蕉,橙子}}` |
| `{{pick::a\|b\|c}}` | 随机选择（竖线） | `{{pick::剑\|斧\|弓}}` |
| `{{roll XdY}}` | 掷骰子 | `{{roll 3d6}}` |
| `{{// 注释}}` | 注释（不输出） | `{{// 这是注释}}` |
#### 使用示例
```python
from backend.services.js_sandbox import JSSandboxExecutor
sandbox = JSSandboxExecutor()
template = """
{{setvar::character::勇者}}
{{setvar::weapon::{{random::剑,斧,弓}}}}
{{character}}手持{{weapon}}，掷出了：{{roll 1d20}}
{{// 这是注释，不会显示}}
""".strip()
result = sandbox.render_template(template)
print(result)
# 输出: 勇者手持剑，掷出了：15
```
#### 脚本管理
支持三种作用域的脚本：
- **GLOBAL** - 全局脚本，对所有聊天可用
- **CHARACTER** - 角色脚本，绑定到当前角色卡
- **PRESET** - 预设脚本，绑定到当前预设
详细文档：[TAVERN_HELPER_IMPLEMENTATION.md](./TAVERN_HELPER_IMPLEMENTATION.md)
### 2. 正则替换系统
强大的文本处理规则，完全兼容 SillyTavern 格式。
#### 应用位置（placement）
- `0` - System Prompt（系统提示词）
- `1` - User Input（用户输入）
- `2` - AI Output（AI 输出）
- `3` - Quick Reply（快捷回复）
- `4` - World Info（世界书信息）
- `5` - Reasoning/Thinking（推理/思考内容）
#### 规则示例
```json
{
"id": "hide-thinking-001",
"scriptName": "隐藏思考标签",
"findRegex": "<thinking>[\\s\\S]*?<\\/thinking>",
"replaceString": "",
"placement": [2],
"substituteRegex": 0,
"markdownOnly": false,
"promptOnly": false,
"disabled": false
}
```
### 3. 预设系统
灵活的提示词组件管理。
#### 特性
- 多组件拖拽排序
- 角色字段支持（system/user/assistant）
- 注入位置控制（injection_position）
- 注入深度控制（injection_depth）
- 触发条件（injection_trigger）
- 完全兼容 SillyTavern 预设格式
### 4. 聊天管理
完整的聊天生命周期管理。
#### 功能
- 多聊天切换
- 消息编辑和保存
- 消息 Swipes（多版本）
- 右键菜单（编辑/复制/重roll/删除）
- 历史总结
- 智能滚动
---
## 开发指南
### API 路由
所有 API 路由定义在 `backend/api/routes/` 目录下：
- `chatWsRoute.py` - WebSocket 聊天（流式输出）
- `chatsRoute.py` - 聊天管理
- `charactersRoute.py` - 角色卡管理
- `presetsRoute.py` - 预设管理
- `worldbooksRoute.py` - 世界书管理
- `regexRoute.py` - 正则规则管理
- `apiConfigRoute.py` - API 配置管理
### 状态管理
前端使用 Zustand 进行状态管理，store 定义在 `frontend/src/Store/`：
```
Store/
├── Mid/ # 中间区域状态
│ ├── ChatBoxSlice.jsx # 聊天框状态
│ └── ChatBoxUISlice.jsx # 聊天框 UI 状态
├── SideBarLeft/ # 左侧边栏状态
├── SideBarRight/ # 右侧边栏状态
└── TopBar/ # 顶部栏状态
```
### 样式系统
使用 CSS 变量实现多主题：
```css
:root {
--color-bg-primary: #ffffff;
--color-text-primary: #1a1a1a;
--color-accent: #667eea;
/* ... */
}
[data-color-theme='dark'] {
--color-bg-primary: #1a1a1a;
--color-text-primary: #ffffff;
/* ... */
}
```
---
## 配置说明
### 环境变量
创建 `.env` 文件（从 `.env.example` 复制）：
```env
# 后端配置
HOST=0.0.0.0
PORT=23338
DEBUG=True
# 前端代理
VITE_API_URL=http://localhost:23338
# API 加密密钥（自动生成，不要手动修改）
FERNET_KEY=your_generated_key_here
```
### API 配置
API Key 通过前端界面配置，自动加密存储到 `data/apiconfig/` 目录。
⚠️ **注意**：`data/apiconfig/*.json` 已添加到 `.gitignore`，不会被提交到版本控制。
---
## 常见问题
### 1. 前端无法连接后端
**问题**: 前端请求返回 404 或网络连接错误
**解决**:
```bash
# 类型检查
npm run type-check
# 检查后端是否运行
curl http://localhost:23338/api/health
# 构建
npm run build
# 预览生产构建
npm run preview
# 检查前端代理配置
cat frontend/vite.config.js
```
### 后端
### 2. API Key 不生效
**问题**: 配置了 API Key 但仍然无法调用 LLM
**解决**:
1. 检查 API 配置文件是否存在：`data/apiconfig/`
2. 检查加密密钥是否正确：`.env` 中的 `FERNET_KEY`
3. 重启后端服务
### 3. Docker 部署后无法访问
**问题**: `docker-compose up` 后无法访问服务
**解决**:
```bash
# 运行测试（如果有的话）
cd backend
pytest
# 查看容器状态
docker-compose ps
# 代码格式化
black .
# 查看日志
docker-compose logs -f backend
docker-compose logs -f frontend
# 重新构建
docker-compose up -d --build
```
## 📝 待办事项
### 4. 正则规则不生效
- [ ] 添加单元测试
- [ ] 完善错误处理
- [ ] 添加用户认证
- [ ] 优化性能
- [ ] 添加更多语言支持
- [ ] 完善文档
**问题**: 配置了正则规则但没有效果
## 🤝 贡献
**解决**:
1. 检查规则是否启用（disabled: false）
2. 检查 placement 是否正确
3. 检查正则表达式语法
4. 重启后端服务
欢迎提交 Issue 和 Pull Request！
---
## 📄 许可证
## 贡献指南
MIT License
1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
## 📞 联系方式
---
如有问题，请提交 Issue 或联系维护者。
## 许可证
本项目遵循与 SillyTavern 相同的分发协议。
---
## 致谢
- [SillyTavern](https://github.com/SillyTavern/SillyTavern) - 优秀的开源项目，提供了设计灵感和兼容标准
- [JS-Slash-Runner](https://github.com/N0VI028/JS-Slash-Runner) - Tavern Helper 扩展，提供了 JavaScript 沙盒实现参考
---
**最后更新**: 2026-05-05
**版本**: 1.0.0