loser/st
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

🎨 优化扩展模块，完成ai接入和对话功能

Browse Source
This commit is contained in:
loser
2026-02-12 23:12:28 +08:00
parent 4e611d3a5e
commit 572f3aa15b
779 changed files with 194400 additions and 3136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

343
云酒馆开发文档.md
View File

@@ -6,9 +6,10 @@
### 技术栈概览
- **前端应用 (web-app)**: Node.js + Express + 原生 JavaScript
- **用户前端 (web-app-vue)**: Vue 3 + TypeScript + Vite + Element Plus + Pinia（重构中）
- **管理后台 (web)**: Vue 3 + Vite + Element Plus + Pinia
- **后端服务 (server)**: Go + Gin + Gorm + PostgreSQL/PostgreSQL
- **后端服务 (server)**: Go + Gin + Gorm + PostgreSQL
- **原版酒馆 (web-app)**: Node.js + Express + 原生 JavaScript（SillyTavern，仅作参考）
---
@@ -16,7 +17,8 @@
```
st/
├── web-app/ # 用户前端应用（SillyTavern基础）
├── web-app-vue/ # 用户前端应用（Vue 3 重构版，主要开发）
├── web-app/ # 原版 SillyTavern（仅作参考）
├── web/ # 管理后台前端
├── server/ # Go后端服务
├── deploy/ # 部署配置
@@ -28,16 +30,218 @@ st/
---
## 二、Web-App 用户前端应用
## 二、Web-App-Vue 用户前端应用（Vue 3 重构版）
> **这是云酒馆的主要用户前端，正在积极开发中。**
### 2.1 项目信息
- **名称**: SillyTavern (基础版本)
- **名称**: web-app-vue (云酒馆前台)
- **技术栈**: Vue 3 + TypeScript + Vite + Element Plus
- **Node要求**: >= 18
- **开发端口**: 3000
- **API代理**: → http://localhost:8888 (Go 后端)
### 2.2 技术栈
#### 核心框架
- **Vue 3.5.25**: 渐进式 JavaScript 框架
- **TypeScript 5.9.3**: 类型安全
- **Vite 7.3.1**: 下一代前端构建工具
- **Element Plus 2.13.2**: UI 组件库
- **Pinia 3.0.4**: 状态管理
- **Vue Router 4.6.4**: 路由管理
- **Axios 1.13.5**: HTTP 客户端
- **VueUse 14.2.1**: Vue 组合式工具集
#### 开发工具
- **unplugin-auto-import**: 自动导入 Vue、Vue Router 等 API
- **unplugin-vue-components**: 自动导入组件
- **Sass**: CSS 预处理器
### 2.3 目录结构
```
web-app-vue/
├── index.html # 入口 HTML
├── package.json # 依赖配置
├── vite.config.ts # Vite 配置
├── tsconfig.json # TypeScript 配置
├── 启动指南.md # 快速启动文档
├── public/ # 静态资源
└── src/ # 源代码
├── main.ts # 应用入口
├── App.vue # 根组件
├── api/ # API 接口
│ ├── auth.ts # 认证 API
│ ├── character.ts # 角色 API
│ ├── extension.ts # 扩展 API
│ ├── regexScript.ts # 正则脚本 API
│ └── worldInfo.ts # 世界书 API
├── assets/ # 资源文件
│ └── styles/ # 样式文件
│ └── index.scss
├── components/ # 全局组件
│ ├── character/ # 角色相关组件
│ ├── chat/ # 对话相关组件
│ ├── common/ # 通用组件
│ ├── settings/ # 设置相关组件
│ └── ExtensionDrawer.vue
├── composables/ # 组合式函数
├── layouts/ # 布局组件
│ ├── AuthLayout.vue # 认证页面布局
│ └── DefaultLayout.vue # 默认布局
├── router/ # 路由配置
│ └── index.ts
├── stores/ # Pinia 状态管理
│ ├── auth.ts # 认证状态
│ ├── character.ts # 角色状态
│ ├── extension.ts # 扩展状态
│ ├── regexScript.ts # 正则脚本状态
│ └── worldInfo.ts # 世界书状态
├── types/ # TypeScript 类型定义
│ ├── api.d.ts # API 类型
│ ├── character.d.ts # 角色类型
│ ├── extension.d.ts # 扩展类型
│ ├── regexScript.d.ts # 正则脚本类型
│ ├── user.d.ts # 用户类型
│ └── worldInfo.d.ts # 世界书类型
├── utils/ # 工具函数
│ ├── request.ts # Axios 请求封装
│ └── extensionRuntime.ts # 扩展运行时
└── views/ # 页面视图
├── auth/ # 认证页面
│ ├── Login.vue # 登录
│ └── Register.vue # 注册
├── character/ # 角色管理
│ ├── Detail.vue # 角色详情
│ ├── Edit.vue # 角色编辑/创建
│ └── MyCharacters.vue # 我的角色
├── chat/ # 对话页面
├── extension/ # 扩展管理
│ ├── ExtensionList.vue # 扩展列表
│ ├── ExtensionListNew.vue # 扩展列表（新版）
│ └── ExtensionSettings.vue # 扩展设置
├── home/ # 首页
│ ├── Index.vue # 角色广场
│ └── CharacterList.vue
├── regex/ # 正则脚本
│ ├── RegexScriptList.vue # 脚本列表
│ └── RegexScriptEdit.vue # 脚本编辑
├── settings/ # 设置页面
├── user/ # 用户页面
└── worldbook/ # 世界书管理
├── WorldBookList.vue # 世界书列表
├── WorldBookEdit.vue # 世界书编辑
└── WorldInfoEntryForm.vue # 条目表单
```
### 2.4 核心功能模块
#### 1. 认证模块
- **用户登录/注册**: Token-based 认证
- **路由守卫**: 自动拦截未登录用户
- **Token 管理**: 自动存储和刷新
- **状态管理**: Pinia store 管理用户状态
#### 2. 角色管理
- **角色广场** (`views/home/`): 浏览公开角色卡
- **角色详情** (`views/character/Detail.vue`): 查看角色详细信息
- **角色创建/编辑** (`views/character/Edit.vue`): 角色卡 CRUD
- **我的角色** (`views/character/MyCharacters.vue`): 管理个人角色卡
#### 3. 对话功能（开发中）
- **对话界面** (`views/chat/`): AI 对话交互
- **消息历史**: 对话记录存储
- **实时通信**: WebSocket 支持
#### 4. 世界书系统
- **世界书管理** (`views/worldbook/`): 世界设定 CRUD
- **条目编辑**: 关键词、内容、触发规则
#### 5. 扩展系统
- **扩展列表** (`views/extension/`): 扩展安装与管理
- **扩展配置**: 每个扩展的独立设置
- **扩展运行时** (`utils/extensionRuntime.ts`): 扩展加载执行
#### 6. 正则脚本
- **脚本管理** (`views/regex/`): 正则替换规则
- **输入/输出处理**: 消息过滤与转换
### 2.5 路由结构
| 路径 | 名称 | 说明 | 需认证 |
|-----|------|-----|-------|
| `/auth/login` | Login | 登录页 | ❌ |
| `/auth/register` | Register | 注册页 | ❌ |
| `/` | Home | 角色广场 | ❌ |
| `/character/:id` | CharacterDetail | 角色详情 | ❌ |
| `/my-characters` | MyCharacters | 我的角色 | ✅ |
| `/character/create` | CreateCharacter | 创建角色 | ✅ |
| `/character/:id/edit` | EditCharacter | 编辑角色 | ✅ |
| `/worldbook` | WorldBookList | 世界书列表 | ✅ |
| `/worldbook/create` | CreateWorldBook | 创建世界书 | ✅ |
| `/worldbook/edit/:id` | EditWorldBook | 编辑世界书 | ✅ |
| `/extension` | ExtensionList | 扩展列表 | ✅ |
| `/extension/settings/:id` | ExtensionSettings | 扩展设置 | ✅ |
| `/regex` | RegexScriptList | 正则脚本列表 | ✅ |
| `/regex/create` | CreateRegexScript | 创建脚本 | ✅ |
| `/regex/edit/:id` | EditRegexScript | 编辑脚本 | ✅ |
### 2.6 启动脚本
```bash
# 安装依赖
npm install
# 启动开发服务器
npm run dev
# 构建生产版本
npm run build
# 预览生产构建
npm run preview
```
### 2.7 开发进度
#### ✅ 已完成
- 用户认证（登录/注册）
- 路由守卫
- 角色管理基础功能
- 世界书管理
- 扩展管理
- 正则脚本管理
- 基础 UI 框架
#### 🚧 开发中
- AI 对话界面
- WebSocket 实时通信
- 消息历史记录
- 用户设置页面
#### 📋 待开发
- 群组对话
- 图片生成集成
- TTS/STT 语音功能
- 主题定制
---
## 三、Web-App 原版 SillyTavern（仅作参考）
> **注意：此模块是原版 SillyTavern，仅作为功能参考，不再主动开发。新功能请在 web-app-vue 中实现。**
### 3.1 项目信息
- **名称**: SillyTavern (原版酒馆)
- **版本**: 1.15.0
- **许可**: AGPL-3.0
- **Node要求**: >= 18
- **状态**: 仅作功能参考
### 2.2 技术栈
### 3.2 技术栈
#### 核心框架
- **Express.js 4.21.0**: 后端服务框架
@@ -70,7 +274,7 @@ st/
}
```
### 2.3 目录结构
### 3.3 目录结构
```
web-app/
@@ -111,7 +315,7 @@ web-app/
└── tests/ # 测试文件
```
### 2.4 核心功能模块
### 3.4 核心功能模块（参考）
#### 1. AI 集成模块
- **路径**: `src/endpoints/`
@@ -148,7 +352,7 @@ web-app/
- **备份恢复**: 数据备份与恢复
- **扩展插件**: 插件系统
### 2.5 启动脚本
### 3.5 启动脚本
```json
{
@@ -159,7 +363,7 @@ web-app/
}
```
### 2.6 关键特性
### 3.6 关键特性
1. **多AI模型支持**: 统一接口适配多个AI服务提供商
2. **向量记忆**: 使用向量数据库实现长期记忆功能
@@ -171,15 +375,15 @@ web-app/
---
## 三、Web 管理后台前端
## 四、Web 管理后台前端
### 3.1 项目信息
### 4.1 项目信息
- **名称**: gin-vue-admin
- **版本**: 2.8.9
- **框架**: Vue 3
### 3.2 技术栈
### 4.2 技术栈
#### 核心框架
- **Vue 3.5.7**: 渐进式JavaScript框架
@@ -196,7 +400,7 @@ web-app/
- **highlight.js**: 代码高亮
- **marked**: Markdown解析
### 3.3 目录结构
### 4.3 目录结构
```
web/
@@ -265,7 +469,7 @@ web/
└── package.json # 依赖配置
```
### 3.4 核心功能模块
### 4.4 核心功能模块
#### 1. 系统管理
- **用户管理**: 用户CRUD、角色分配
@@ -291,7 +495,7 @@ web/
- **文件管理**: 文件上传下载
- **断点续传**: 大文件上传
### 3.5 启动脚本
### 4.5 启动脚本
```json
{
@@ -303,15 +507,15 @@ web/
---
## 四、Server Go后端服务
## 五、Server Go后端服务
### 4.1 项目信息
### 5.1 项目信息
- **框架**: Gin-Vue-Admin v2.8.9
- **Go版本**: 1.24.0+
- **模块路径**: git.echol.cn/loser/st/server
### 4.2 技术栈
### 5.2 技术栈
#### 核心框架
- **Gin 1.10.0**: Web框架
@@ -342,7 +546,7 @@ web/
- **定时任务**: robfig/cron
- **Excel**: xuri/excelize
### 4.3 目录结构
### 5.3 目录结构
```
server/
@@ -433,7 +637,7 @@ server/
└── ...
```
### 4.4 核心功能模块
### 5.4 核心功能模块
#### 1. 用户与权限系统
- **用户管理** (`sys_user.go`)
@@ -503,7 +707,7 @@ server/
- 自动初始化数据库
- 初始数据导入
### 4.5 数据库设计
### 5.5 数据库设计
#### 核心表结构
@@ -564,7 +768,7 @@ sys_operation_records
- resp: 响应体
```
### 4.6 API 接口规范
### 5.6 API 接口规范
#### 统一响应格式
@@ -592,7 +796,7 @@ type PageResult struct {
}
```
### 4.7 配置文件 (config.yaml)
### 5.7 配置文件 (config.yaml)
```yaml
# 系统配置
@@ -642,25 +846,28 @@ zap:
---
## 五、项目重构方案
## 六、项目重构方案
本项目计划进行架构重构，将 web-app 从 Node.js 后端+前端一体化架构重构为 Go 后端 + 纯前端架构。
本项目正在进行架构重构，使用 Vue 3 重新开发用户前端（web-app-vue），替代原版 SillyTavern 的 Node.js + 原生 JavaScript 架构。
### 5.1 重构目标
### 6.1 重构目标
- **后端统一**: 使用 Go + PostgreSQL 提供所有后端服务
- **前端分离**: web-app 改造为纯前端应用，仅包含页面和前端逻辑
- **前端现代化**: 使用 Vue 3 + TypeScript 重新开发用户前端（web-app-vue）
- **数据迁移**: 将文件系统存储迁移到 PostgreSQL + 对象存储
- **性能提升**: 利用 Go 的高并发能力和 PostgreSQL 的向量扩展（pgvector）
### 5.2 技术架构
### 6.2 技术架构
```
重构后架构
├── web-app/ # 用户前端（纯前端）
│ ├── 静态 HTML/CSS/JS
│ ├── 调用 Go 后端 API
│ └── Nginx 静态服务器部署
├── web-app-vue/ # 用户前端（Vue 3，主要开发）
│ ├── Vue 3 + TypeScript
│ ├── Vite 构建工具
│ ├── Element Plus UI
│ └── 调用 Go 后端 API
│
├── web-app/ # 原版 SillyTavern（仅作参考）
│
├── web/ # 管理后台前端
│ ├── Vue 3 + Vite
@@ -674,14 +881,14 @@ zap:
└── 对象存储服务
```
### 5.3 详细重构方案
### 6.3 详细重构方案
**完整的重构实施方案请查看**: [`docs/重构实施方案.md`](./docs/重构实施方案.md)
该文档包含：
- 详细的数据库设计（PostgreSQL 表结构）
- Go 后端 API 开发指南
- 前端改造步骤（web-app 去 Node.js 化）
- Vue 前端开发指南（web-app-vue）
- 数据迁移脚本与策略
- 测试方案与性能优化
- Docker 部署配置
@@ -689,16 +896,16 @@ zap:
---
## 六、开发环境搭建
## 七、开发环境搭建
### 6.1 环境要求
### 7.1 环境要求
- **Node.js**: >= 18.0.0
- **Go**: >= 1.24.0
- **PostgreSQL**: >= 12
- **Redis**: >= 6.0 (可选)
### 6.2 快速启动
### 7.2 快速启动
#### 1. 启动后端服务
@@ -716,7 +923,15 @@ npm install
npm run dev
```
#### 3. 启动用户前端
#### 3. 启动用户前端 (Vue 版)
```bash
cd web-app-vue
npm install
npm run dev
```
#### 4. 启动原版酒馆 (仅作参考)
```bash
cd web-app
@@ -724,7 +939,7 @@ npm install
npm start
```
### 6.3 开发工具推荐
### 7.3 开发工具推荐
- **IDE**: GoLand / VSCode
- **API测试**: Postman / Apifox
@@ -733,9 +948,9 @@ npm start
---
## 七、部署架构
## 八、部署架构
### 7.1 Docker部署
### 8.1 Docker部署
```yaml
# docker-compose.yml
@@ -767,25 +982,25 @@ services:
ports:
- "80:80"
web-app:
build: ./web-app
web-app-vue:
build: ./web-app-vue
ports:
- "8000:8000"
- "3000:3000"
```
### 7.2 Kubernetes部署
### 8.2 Kubernetes部署
参考 `deploy/kubernetes/` 目录下的配置文件。
---
## 八、API文档
## 九、API文档
### 8.1 Swagger文档
### 9.1 Swagger文档
后端启动后访问: `http://localhost:8888/swagger/index.html`
### 8.2 主要接口列表
### 9.2 主要接口列表
#### 用户认证
- `POST /base/login` - 用户登录
@@ -806,9 +1021,9 @@ services:
---
## 九、开发规范
## 十、开发规范
### 9.1 代码规范
### 10.1 代码规范
#### Go代码规范
- 遵循 Go 官方代码风格
@@ -820,7 +1035,7 @@ services:
- 使用 ESLint 进行代码检查
- 组件命名使用 PascalCase
### 9.2 Git提交规范
### 10.2 Git提交规范
```
feat: 新功能
@@ -832,7 +1047,7 @@ test: 测试相关
chore: 构建/工具相关
```
### 9.3 分支管理
### 10.3 分支管理
- `main`: 主分支，生产环境
- `develop`: 开发分支
@@ -841,7 +1056,7 @@ chore: 构建/工具相关
---
## 十、常见问题 (FAQ)
## 十一、常见问题 (FAQ)
### Q1: 如何切换数据库类型?
修改 `server/config.yaml` 中的 `system.db-type`,支持 PostgreSQL、sqlite、sqlserver。
@@ -851,15 +1066,15 @@ chore: 构建/工具相关
### Q3: 前端如何配置后端地址?
- **web**: 修改 `web/.env.development` 中的 `VITE_BASE_API`
- **web-app**: 修改相应的API配置文件
- **web-app-vue**: 修改 `web-app-vue/vite.config.ts` 中的代理配置
---
## 十一、联系方式
## 十二、联系方式
- **项目仓库**: git.echol.cn/loser/st
- **技术栈**: Go + Gin + Vue 3 + Node.js
- **框架**: Gin-Vue-Admin + SillyTavern
- **技术栈**: Go + Gin + Vue 3 + TypeScript
- **框架**: Gin-Vue-Admin + SillyTavern (参考)
---
@@ -867,12 +1082,20 @@ chore: 构建/工具相关
### A. 依赖版本清单
#### Web-App
#### Web-App-Vue (主要开发)
- Vue: 3.5.25
- Vite: 7.3.1
- TypeScript: 5.9.3
- Element Plus: 2.13.2
- Pinia: 3.0.4
- Vue Router: 4.6.4
#### Web-App (原版酒馆，仅参考)
- Node.js: >= 18
- Express: 4.21.0
- Webpack: 5.98.0
#### Web
#### Web (管理后台)
- Vue: 3.5.7
- Vite: 6.2.3
- Element Plus: 2.10.2