chenmoranzhi/sillytavern-repalice

Fork 0

Files

moranzhi 35eff3faf6 规定数据类型

2026-04-24 01:45:41 +08:00

6.1 KiB

Raw Blame History

快速开始指南

🚀 5分钟上手

前置检查

确保你的系统已安装:

✅ Node.js >= 20.x (node -v)
✅ npm >= 10.x (npm -v)
✅ Git (git --version)

步骤 1: 克隆项目

git clone <repository-url>
cd sillytavern-repalice

步骤 2: 安装依赖

npm install

这会安装所有工作区 (shared, server, client) 的依赖。

步骤 3: 配置环境变量

# 复制示例配置
cp .env.example .env

# 编辑 .env 文件，填入你的 API 密钥
# Windows: notepad .env
# macOS/Linux: nano .env

最小配置示例:

OPENAI_API_KEY=sk-your-openai-key
LLM_PROVIDER=openai
LLM_MODEL=gpt-4

步骤 4: 启动开发服务器

# 同时启动前后端（推荐）
npm run dev

或者分别启动:

# 终端 1: 启动后端
npm run dev:server

# 终端 2: 启动前端
npm run dev:client

步骤 5: 访问应用

打开浏览器访问:

前端: http://localhost:5173
后端 API: http://localhost:3000/api

🐳 Docker 部署

快速启动

# 构建并启动所有服务
docker-compose up -d

# 查看运行状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

仅构建镜像

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/             # 💾 运行时生成的数据

🔧 常用命令

开发

npm run dev          # 启动开发环境
npm run dev:server   # 仅启动后端
npm run dev:client   # 仅启动前端

构建

npm run build        # 构建所有项目
npm run build:server # 构建后端
npm run build:client # 构建前端

测试

npm test             # 运行所有测试
npm run lint         # 代码检查

Docker

npm run docker:up    # 启动容器
npm run docker:down  # 停止容器
npm run docker:build # 构建镜像
npm run docker:logs  # 查看日志

🎯 第一个任务：创建角色卡

⚠️ 注意: 当前项目处于架构搭建阶段，UI 组件为占位符。以下流程展示预期的使用方式。

通过 API 创建角色

curl -X POST http://localhost:3000/api/characters \
  -H "Content-Type: application/json" \
  -d '{
    "name": "艾莉丝",
    "description": "一位勇敢的冒险者",
    "personality": "开朗、勇敢、幽默",
    "scenario": "在一个魔法世界中冒险",
    "first_mes": "你好！我是艾莉丝，很高兴认识你！",
    "mes_example": ""
  }'

导入 SillyTavern 角色卡

curl -X POST http://localhost:3000/api/import/character \
  -F "file=@/path/to/character.png"

🐛 故障排查

问题: 端口被占用

错误: Error: listen EADDRINUSE: address already in use :::3000

解决:

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:3000 | xargs kill -9

或修改 .env 中的 PORT 变量。

问题: 依赖安装失败

解决:

# 清除缓存
npm cache clean --force

# 删除 node_modules
rm -rf node_modules server/node_modules client/node_modules shared/node_modules

# 重新安装
npm install

问题: TypeScript 编译错误

解决:

# 清除构建缓存
cd server && rm -rf dist
cd client && rm -rf dist

# 重新构建
npm run build

问题: Docker 容器无法启动

解决:

# 查看详细日志
docker-compose logs backend
docker-compose logs frontend

# 重建容器
docker-compose down
docker-compose build --no-cache
docker-compose up -d

📚 学习资源

项目文档

ARCHITECTURE.md - 详细架构设计
README.md - 项目概览

技术栈文档

SillyTavern 参考

🤝 贡献指南

添加新功能

定义类型 (shared/types/)

// shared/types/my-feature.types.ts
export interface MyFeature {
  id: string;
  name: string;
}

创建后端模块 (server/src/modules/my-feature/)

// server/src/modules/my-feature/my-feature.module.ts
@Module({
  controllers: [MyFeatureController],
  providers: [MyFeatureService],
})
export class MyFeatureModule {}

创建前端组件 (client/src/components/MyFeature/)

<!-- client/src/components/MyFeature/MyFeature.vue -->
<template>
  <div>My Feature</div>
</template>

注册模块
- 在 server/src/app.module.ts 中添加后端模块
- 在 client/src/router/index.ts 中添加路由

提交 PR

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📞 获取帮助

📖 查阅 ARCHITECTURE.md
🐛 提交 GitHub Issue
💬 参与讨论 (如果有社区)

祝你使用愉快！ 🎉

如有问题或建议，欢迎反馈。

6.1 KiB Raw Blame History Unescape Escape