# snow-ai

**Repository Path**: qimingjin/snow-ai

## Basic Information

- **Project Name**: snow-ai
- **Description**: 多模态 AI 创作与对话平台:对话、文生图、文生视频，一站式 AI 创作工作台
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-06-27
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="snow-ai-web/src/assets/logo.svg" width="96" alt="snow-ai logo" />
</p>

# snow-ai — AI Conversation & Creation Platform

> 一个支持多用户的 AI 对话与多媒体创作平台，集成流式对话、文生图、文生视频于一体。  
> A multi-user AI platform with streaming chat, text-to-image, and text-to-video in one place.

[![Java](https://img.shields.io/badge/Java-17-orange)](https://adoptium.net/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5-brightgreen)](https://spring.io/projects/spring-boot)
[![React](https://img.shields.io/badge/React-19-blue)](https://react.dev/)
[![Ant Design X](https://img.shields.io/badge/Ant%20Design%20X-2.8-1677ff)](https://x.ant.design/)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

---

## ✨ Features / 核心功能

| Feature | Description |
|---------|-------------|
| 💬 **Streaming Chat** | Multi-turn AI conversation with real-time SSE streaming and Markdown rendering<br>多轮 AI 对话，SSE 流式输出，支持代码块/表格等 Markdown 即时渲染 |
| 🎨 **Text-to-Image** | Generate images in 1:1 / 16:9 / 9:16 ratios with style presets<br>文生图，支持 1:1 / 16:9 / 9:16 三种比例、多种风格预设（赛博朋克/水彩/电影感/二次元） |
| 🎬 **Text-to-Video** | Async video generation (5s/10s) with live progress thought-chain via SSE, plus video-specific style presets<br>文生视频，异步生成，SSE 实时思维链进度（理解提示词 → 分镜 → 渲染 → 完成），并提供视频专属风格预设 |
| 🪄 **Prompt Optimization** | One-click AI rewrite of a rough idea into a structured video prompt: Subject + Action + Scene + Camera + Lighting + Style<br>视频创作一键「优化提示词」：AI 按 [主体]+[动作]+[场景]+[镜头运动]+[光线]+[风格] 六要素把粗略想法扩写为专业提示词 |
| 👥 **Multi-user** | Per-user data isolation: conversations and creations are strictly separated<br>多用户隔离，会话/作品数据各自独立，越权访问统一按"不存在"处理 |
| 📂 **Session History** | Separate session sidebars for Chat and Create, with persistent history<br>对话与创作各有独立多会话侧边栏，历史记录持久化可随时恢复 |
| 🎨 **Theming** | Light / Dark mode × Brand Pink / Ant Design Blue = 4 theme combinations<br>浅/深主题 × 品红/蓝主色 = 4 种主题组合，持久化偏好 |

---

## 🖼️ Screenshots / 截图

<table>
  <tr>
    <td align="center" width="50%">
      <img src="snow-ai-web/src/assets/login.png" width="100%" alt="登录页 Login" />
      <br/><sub>登录 / 注册 Login & Register</sub>
    </td>
    <td align="center" width="50%">
      <img src="snow-ai-web/src/assets/chat.png" width="100%" alt="对话页 Chat" />
      <br/><sub>流式对话 Streaming Chat</sub>
    </td>
  </tr>
  <tr>
    <td align="center" width="50%">
      <img src="snow-ai-web/src/assets/chat2.png" width="100%" alt="对话页 Chat 2" />
      <br/><sub>流式对话 Streaming Chat</sub>
    </td>
    <td align="center" width="50%">
      <img src="snow-ai-web/src/assets/chat4.png" width="100%" alt="对话页 Chat 4" />
      <br/><sub>流式对话 Streaming Chat</sub>
    </td>
  </tr>
</table>

---

## 🛠️ Tech Stack / 技术栈

### Backend / 后端
| Technology | Version | Role |
|-----------|---------|------|
| Spring Boot | 3.5 | Web framework / Web 框架 |
| Spring AI | 1.1 | OpenAI-compatible LLM integration / 大模型接入 |
| Sa-Token | 1.41 | Authentication & session / 鉴权与会话 |
| MyBatis-Plus | 3.5 | ORM with logical delete / ORM + 逻辑删除 |
| MySQL | 8.0 | Primary database / 主数据库 |
| Redis | 7 | Session store / 会话存储 |

### Frontend / 前端
| Technology | Version | Role |
|-----------|---------|------|
| React | 19 | UI framework / UI 框架 |
| Ant Design | 6 | Component library / 组件库 |
| Ant Design X | 2.8 | AI-native components (Bubble, Sender, XMarkdown) / AI 对话组件 |
| Zustand | 5 | State management / 状态管理 |
| TypeScript | 5.9 | Type safety / 类型安全 |
| Vite | 6 | Build tool / 构建工具 |

---

## 📋 Prerequisites / 前提条件

**For Docker Quick Start (recommended):**
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) 24+
- An Agnes AI API key ([agnes-ai.com](https://agnes-ai.com))

> **Note 兼容性说明:** Chat and video prompt optimization use Spring AI's OpenAI-compatible chat adapter and can be pointed to compatible chat providers via `AGNES_BASE_URL` / `AGNES_API_KEY`. Image and video generation currently call Agnes REST endpoints and require Agnes-compatible image/video APIs, model names, and response formats.<br>对话与视频提示词优化基于 Spring AI 的 OpenAI-compatible Chat Adapter，可通过 `AGNES_BASE_URL` / `AGNES_API_KEY` 指向兼容的对话模型服务；文生图与文生视频当前主要适配 Agnes REST 接口，需要兼容 Agnes 的图像/视频端点、模型名和响应结构。

**For Manual Setup:**
- Java 17 ([Eclipse Temurin](https://adoptium.net/) recommended)
- Node.js 18+
- MySQL 8.0
- Redis 7

---

## 🚀 Quick Start (Docker) / 快速启动

```bash
# 1. Clone the repository / 克隆仓库
git clone https://gitee.com/qimingjin/snow-ai.git
cd snow-ai

# 2. Configure environment / 配置环境变量
cp .env.example .env
# Open .env and fill in AGNES_API_KEY (required)
# 打开 .env，填入 AGNES_API_KEY（必填）

# 3. Start all services / 一键启动
docker compose up -d

# 4. Open in browser / 浏览器访问
open http://localhost
```

All services start automatically: MySQL → Redis → Backend → Frontend.  
所有服务自动按依赖顺序启动：MySQL → Redis → 后端 → 前端。

> **First startup note:** Spring Boot uses Flyway to create and version database tables on first run. Do not edit published migration files; add a new `V2__*.sql` / `V3__*.sql` file for future schema changes.  
> **首次启动说明：** Spring Boot 通过 Flyway 自动建表并记录数据库版本；已发布迁移脚本不要修改，后续表结构变化请新增 `V2__*.sql` / `V3__*.sql`。

---

## 🔧 Manual Setup / 手动部署

### 1. Database / 数据库

Create a MySQL database named `snow-ai`:
```sql
CREATE DATABASE `snow-ai` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
Tables are created and versioned by Flyway on first backend startup.  
表结构在后端首次启动时由 Flyway 自动创建并记录迁移版本。

### 2. Backend / 后端

```bash
cd snow-ai-server

# Set required environment variables / 设置环境变量
export AGNES_API_KEY=your_api_key_here
export DB_PASSWORD=your_mysql_password
# Optional overrides (see Configuration Reference below):
# export DB_URL=jdbc:mysql://localhost:3306/snow-ai?...
# export REDIS_HOST=localhost

# Java 17 is required (switch if needed)
# 需要 Java 17（如本机默认非 17，先切换）：
# export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home

./mvnw spring-boot:run
# Backend starts at http://localhost:8080
```

### 3. Frontend / 前端

```bash
cd snow-ai-web
npm install
npm run dev
# Frontend starts at http://localhost:5173
# Vite automatically proxies /api/* to http://localhost:8080
```

Open http://localhost:5173, register an account, and start chatting.  
访问 http://localhost:5173，注册账号即可开始使用。

---

## ⚙️ Configuration Reference / 环境变量说明

| Variable | Default | Description |
|----------|---------|-------------|
| `DB_URL` | `jdbc:mysql://localhost:3306/snow-ai?...` | MySQL connection URL / 数据库连接 |
| `DB_USER` | `root` | MySQL username / 数据库用户名 |
| `DB_PASSWORD` | _(empty)_ | MySQL password / 数据库密码 |
| `REDIS_HOST` | `localhost` | Redis host / Redis 主机 |
| `REDIS_PORT` | `6379` | Redis port / Redis 端口 |
| `REDIS_PASSWORD` | _(empty)_ | Redis password / Redis 密码 |
| `AGNES_BASE_URL` | `https://apihub.agnes-ai.com` | AI provider base URL / 大模型服务地址 |
| `AGNES_API_KEY` | **Required / 必填** | API key for the AI provider / 大模型 API 密钥 |
| `AGNES_MODEL` | `agnes-2.0-flash` | Chat model name / 对话模型 |
| `AGNES_IMAGE_MODEL` | `agnes-image-2.0-flash` | Image generation model / 图像模型 |
| `AGNES_VIDEO_MODEL` | `agnes-video-v2.0` | Video generation model / 视频模型 |
| `AGNES_VIDEO_POLL_INTERVAL` | `10` | Video status poll interval in seconds / 视频状态轮询间隔（秒） |

---

## 📡 API Overview / 接口概览

All API endpoints require authentication via `satoken` header (obtained from login).  
所有受保护接口需在请求头携带 `satoken: <token_value>`（登录后获取）。

OpenAPI JSON is available at `/v3/api-docs`, and Swagger UI is available at `/swagger-ui.html`.  
OpenAPI JSON 地址为 `/v3/api-docs`，Swagger UI 地址为 `/swagger-ui.html`。

SSE streaming endpoints do not wrap responses in `Result<T>`; see [`docs/api/sse.md`](docs/api/sse.md) for event/data formats.  
SSE 流式接口不使用 `Result<T>` 包裹响应，事件与 data 格式详见 [`docs/api/sse.md`](docs/api/sse.md)。

### Authentication / 认证
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/auth/register` | Register a new user / 注册 |
| `POST` | `/api/auth/login` | Login, returns token / 登录，返回 token |
| `GET`  | `/api/auth/me` | Get current user / 获取当前用户 |

### Conversation / 对话会话
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/chat/stream` | **[SSE]** Streaming chat / 流式对话 |
| `POST` | `/api/conversations` | Create conversation / 新建会话 |
| `GET`  | `/api/conversations` | List conversations / 会话列表 |
| `DELETE` | `/api/conversations/{id}` | Delete conversation / 删除会话 |
| `GET`  | `/api/conversations/{id}/messages` | Get message history / 历史消息 |

### Creation / 创作
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/image` | Generate image (sync ~20-30s) / 文生图（同步） |
| `POST` | `/api/video` | Create video task (async) / 创建视频任务（异步） |
| `GET`  | `/api/video/{id}/stream` | **[SSE]** Video progress / 视频生成进度 |
| `POST` | `/api/video/prompt/optimize` | Optimize a video prompt (six-element rewrite) / 优化视频提示词（六要素扩写） |
| `POST` | `/api/creation-sessions` | Create creation session / 新建创作会话 |
| `GET`  | `/api/creation-sessions?type=image\|video` | List creation sessions / 创作会话列表 |
| `DELETE` | `/api/creation-sessions/{id}` | Delete creation session / 删除创作会话 |
| `GET`  | `/api/creation-sessions/{id}/items` | Session history / 会话历史 |
| `GET`  | `/api/creations?type=image\|video` | List creations library / 作品库列表 |

---

## 📁 Project Structure / 项目结构

```
snow-ai/
├── snow-ai-server/          # Spring Boot backend / 后端
│   ├── src/main/java/com/snowai/server/
│   │   ├── controller/      # REST controllers (Auth/Chat/Conversation/Create)
│   │   ├── service/         # Business logic
│   │   ├── manager/         # Third-party & cross-cutting (ChatStreamManager, VideoGenManager)
│   │   ├── dal/             # Database layer (Entity + Mapper)
│   │   ├── dto/             # Request objects
│   │   ├── vo/              # Response view objects
│   │   └── common/          # Shared utilities (ErrorCode, BizException, Result)
│   └── src/main/resources/
│       ├── application.yml  # Configuration
│       └── db/migration/    # Flyway database migrations (V1__init_schema.sql, ...)
│
├── snow-ai-web/             # React frontend / 前端
│   ├── src/
│   │   ├── pages/           # Chat.tsx, Create.tsx, Login.tsx, Register.tsx
│   │   ├── components/      # AppLayout, MessageBubbles, CreationStream, VideoCard...
│   │   ├── stores/          # Zustand stores (Auth/Chat/Create/Theme)
│   │   ├── api/             # API client (chat, image, video, conversation...)
│   │   └── theme/           # Ant Design theme tokens (light/dark)
│   └── nginx.conf           # Production Nginx config (used in Docker)
│
├── docker-compose.yml       # One-command startup / 一键启动
├── .env.example             # Environment variables template / 环境变量模板
└── README.md
```

---

## 🏗️ Architecture / 架构说明

```
Browser
  │  HTTP + SSE
  ▼
Nginx (port 80)  ──── /api/* ────►  Spring Boot (port 8080)
  │  static files                       │
  └── React SPA                         ├── Sa-Token  (auth)
                                        ├── MyBatis-Plus → MySQL
                                        ├── Redis (sessions)
                                        └── Spring AI → Agnes AI
                                              (chat / image / video)
```

**Key design decisions 关键设计决策:**
- **SSE over WebSocket**: Spring MVC `SseEmitter` handles streaming; simpler than WebSocket for unidirectional push
- **5-layer architecture**: Controller → Service → Manager → DAL (Alibaba convention); Manager encapsulates all third-party calls
- **Logical delete**: All entities use `deleted` flag; MyBatis-Plus auto-filters on BaseMapper queries

---

## 🤝 Contributing / 贡献指南

Contributions are welcome! / 欢迎提交 PR 和 Issue！

```bash
# Start dev environment / 启动开发环境
# Backend
cd snow-ai-server && ./mvnw test        # Run tests / 运行测试
cd snow-ai-server && ./mvnw spring-boot:run

# Frontend
cd snow-ai-web && npm test              # Run tests / 运行测试
cd snow-ai-web && npm run dev
```

Please ensure all tests pass before submitting a PR.  
提交 PR 前请确保全部测试通过（后端 `./mvnw test` + 前端 `npm test`）。

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).

---

<p align="center">Built with ❤️ using Spring Boot, React, and Ant Design X</p>