规定数据类型
This commit is contained in:
314
QUICKSTART.md
Normal file
314
QUICKSTART.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# 快速开始指南
|
||||
|
||||
## 🚀 5分钟上手
|
||||
|
||||
### 前置检查
|
||||
|
||||
确保你的系统已安装:
|
||||
- ✅ Node.js >= 20.x (`node -v`)
|
||||
- ✅ npm >= 10.x (`npm -v`)
|
||||
- ✅ Git (`git --version`)
|
||||
|
||||
### 步骤 1: 克隆项目
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd sillytavern-repalice
|
||||
```
|
||||
|
||||
### 步骤 2: 安装依赖
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
这会安装所有工作区 (shared, server, client) 的依赖。
|
||||
|
||||
### 步骤 3: 配置环境变量
|
||||
|
||||
```bash
|
||||
# 复制示例配置
|
||||
cp .env.example .env
|
||||
|
||||
# 编辑 .env 文件，填入你的 API 密钥
|
||||
# Windows: notepad .env
|
||||
# macOS/Linux: nano .env
|
||||
```
|
||||
|
||||
最小配置示例:
|
||||
```env
|
||||
OPENAI_API_KEY=sk-your-openai-key
|
||||
LLM_PROVIDER=openai
|
||||
LLM_MODEL=gpt-4
|
||||
```
|
||||
|
||||
### 步骤 4: 启动开发服务器
|
||||
|
||||
```bash
|
||||
# 同时启动前后端（推荐）
|
||||
npm run dev
|
||||
```
|
||||
|
||||
或者分别启动:
|
||||
```bash
|
||||
# 终端 1: 启动后端
|
||||
npm run dev:server
|
||||
|
||||
# 终端 2: 启动前端
|
||||
npm run dev:client
|
||||
```
|
||||
|
||||
### 步骤 5: 访问应用
|
||||
|
||||
打开浏览器访问:
|
||||
- **前端**: http://localhost:5173
|
||||
- **后端 API**: http://localhost:3000/api
|
||||
|
||||
## 🐳 Docker 部署
|
||||
|
||||
### 快速启动
|
||||
|
||||
```bash
|
||||
# 构建并启动所有服务
|
||||
docker-compose up -d
|
||||
|
||||
# 查看运行状态
|
||||
docker-compose ps
|
||||
|
||||
# 查看日志
|
||||
docker-compose logs -f
|
||||
|
||||
# 停止服务
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### 仅构建镜像
|
||||
|
||||
```bash
|
||||
docker-compose build
|
||||
```
|
||||
|
||||
### 数据持久化
|
||||
|
||||
Docker 会自动将数据挂载到 `./data` 目录:
|
||||
```
|
||||
sillytavern-repalice/
|
||||
└── data/ # 此目录会包含所有持久化数据
|
||||
├── characters/
|
||||
├── chats/
|
||||
├── worldinfo/
|
||||
└── presets/
|
||||
```
|
||||
|
||||
## 📂 项目结构速览
|
||||
|
||||
```
|
||||
sillytavern-repalice/
|
||||
├── shared/ # 🔗 前后端共享类型和 schemas
|
||||
│ ├── types/ # TypeScript 类型定义
|
||||
│ └── schemas/ # Zod 验证 schemas
|
||||
│
|
||||
├── server/ # 🖥️ 后端 NestJS
|
||||
│ └── src/
|
||||
│ ├── modules/ # 业务模块
|
||||
│ ├── services/ # 业务逻辑
|
||||
│ └── persistence/ # 数据持久化
|
||||
│
|
||||
├── client/ # 🎨 前端 Vue3
|
||||
│ └── src/
|
||||
│ ├── components/ # UI 组件
|
||||
│ ├── stores/ # 状态管理
|
||||
│ └── router/ # 路由配置
|
||||
│
|
||||
└── data/ # 💾 运行时生成的数据
|
||||
```
|
||||
|
||||
## 🔧 常用命令
|
||||
|
||||
### 开发
|
||||
|
||||
```bash
|
||||
npm run dev # 启动开发环境
|
||||
npm run dev:server # 仅启动后端
|
||||
npm run dev:client # 仅启动前端
|
||||
```
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
npm run build # 构建所有项目
|
||||
npm run build:server # 构建后端
|
||||
npm run build:client # 构建前端
|
||||
```
|
||||
|
||||
### 测试
|
||||
|
||||
```bash
|
||||
npm test # 运行所有测试
|
||||
npm run lint # 代码检查
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
npm run docker:up # 启动容器
|
||||
npm run docker:down # 停止容器
|
||||
npm run docker:build # 构建镜像
|
||||
npm run docker:logs # 查看日志
|
||||
```
|
||||
|
||||
## 🎯 第一个任务：创建角色卡
|
||||
|
||||
> ⚠️ 注意: 当前项目处于架构搭建阶段，UI 组件为占位符。以下流程展示预期的使用方式。
|
||||
|
||||
### 通过 API 创建角色
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/characters \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "艾莉丝",
|
||||
"description": "一位勇敢的冒险者",
|
||||
"personality": "开朗、勇敢、幽默",
|
||||
"scenario": "在一个魔法世界中冒险",
|
||||
"first_mes": "你好！我是艾莉丝，很高兴认识你！",
|
||||
"mes_example": ""
|
||||
}'
|
||||
```
|
||||
|
||||
### 导入 SillyTavern 角色卡
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/import/character \
|
||||
-F "file=@/path/to/character.png"
|
||||
```
|
||||
|
||||
## 🐛 故障排查
|
||||
|
||||
### 问题: 端口被占用
|
||||
|
||||
**错误**: `Error: listen EADDRINUSE: address already in use :::3000`
|
||||
|
||||
**解决**:
|
||||
```bash
|
||||
# Windows
|
||||
netstat -ano | findstr :3000
|
||||
taskkill /PID <PID> /F
|
||||
|
||||
# macOS/Linux
|
||||
lsof -ti:3000 | xargs kill -9
|
||||
```
|
||||
|
||||
或修改 `.env` 中的 `PORT` 变量。
|
||||
|
||||
### 问题: 依赖安装失败
|
||||
|
||||
**解决**:
|
||||
```bash
|
||||
# 清除缓存
|
||||
npm cache clean --force
|
||||
|
||||
# 删除 node_modules
|
||||
rm -rf node_modules server/node_modules client/node_modules shared/node_modules
|
||||
|
||||
# 重新安装
|
||||
npm install
|
||||
```
|
||||
|
||||
### 问题: TypeScript 编译错误
|
||||
|
||||
**解决**:
|
||||
```bash
|
||||
# 清除构建缓存
|
||||
cd server && rm -rf dist
|
||||
cd client && rm -rf dist
|
||||
|
||||
# 重新构建
|
||||
npm run build
|
||||
```
|
||||
|
||||
### 问题: Docker 容器无法启动
|
||||
|
||||
**解决**:
|
||||
```bash
|
||||
# 查看详细日志
|
||||
docker-compose logs backend
|
||||
docker-compose logs frontend
|
||||
|
||||
# 重建容器
|
||||
docker-compose down
|
||||
docker-compose build --no-cache
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## 📚 学习资源
|
||||
|
||||
### 项目文档
|
||||
- [ARCHITECTURE.md](./ARCHITECTURE.md) - 详细架构设计
|
||||
- [README.md](./README.md) - 项目概览
|
||||
|
||||
### 技术栈文档
|
||||
- [NestJS 官方文档](https://docs.nestjs.com/)
|
||||
- [Vue 3 官方文档](https://vuejs.org/)
|
||||
- [Vercel AI SDK](https://sdk.vercel.ai/docs)
|
||||
- [Zod 文档](https://zod.dev/)
|
||||
- [Pinia 文档](https://pinia.vuejs.org/)
|
||||
|
||||
### SillyTavern 参考
|
||||
- [SillyTavern 官方文档](https://st-docs.role.fun/)
|
||||
- [角色卡规范 V2](https://github.com/malfoyslastname/character-card-spec-v2)
|
||||
|
||||
## 🤝 贡献指南
|
||||
|
||||
### 添加新功能
|
||||
|
||||
1. **定义类型** (shared/types/)
|
||||
```typescript
|
||||
// shared/types/my-feature.types.ts
|
||||
export interface MyFeature {
|
||||
id: string;
|
||||
name: string;
|
||||
}
|
||||
```
|
||||
|
||||
2. **创建后端模块** (server/src/modules/my-feature/)
|
||||
```typescript
|
||||
// server/src/modules/my-feature/my-feature.module.ts
|
||||
@Module({
|
||||
controllers: [MyFeatureController],
|
||||
providers: [MyFeatureService],
|
||||
})
|
||||
export class MyFeatureModule {}
|
||||
```
|
||||
|
||||
3. **创建前端组件** (client/src/components/MyFeature/)
|
||||
```vue
|
||||
<!-- client/src/components/MyFeature/MyFeature.vue -->
|
||||
<template>
|
||||
<div>My Feature</div>
|
||||
</template>
|
||||
```
|
||||
|
||||
4. **注册模块**
|
||||
- 在 `server/src/app.module.ts` 中添加后端模块
|
||||
- 在 `client/src/router/index.ts` 中添加路由
|
||||
|
||||
### 提交 PR
|
||||
|
||||
1. Fork 本仓库
|
||||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||||
5. 开启 Pull Request
|
||||
|
||||
## 📞 获取帮助
|
||||
|
||||
- 📖 查阅 [ARCHITECTURE.md](./ARCHITECTURE.md)
|
||||
- 🐛 提交 [GitHub Issue](../../issues)
|
||||
- 💬 参与讨论 (如果有社区)
|
||||
|
||||
---
|
||||
|
||||
**祝你使用愉快！** 🎉
|
||||
|
||||
如有问题或建议，欢迎反馈。
|
||||
Reference in New Issue
Block a user