# 快速开始指南

## 🚀 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)
- 💬 参与讨论 (如果有社区)

---

**祝你使用愉快！** 🎉

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