# 青梦

**Repository Path**: auraor/qm

## Basic Information

- **Project Name**: 青梦
- **Description**: 青梦【QM】 是一款集智能对话、AI 绘图与视频生成于一体的创作平台，支持文生图、图生图及多种视频生成方式，提供历史会话管理、作品发布与广场展示，让灵感从交流到创作、分享一站完成。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-09-15
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringAI, ai图片, AI视频

## README

# QM（青梦）· AI 媒体生成平台

QM（青梦）是一个全栈 AI 多媒体内容生成平台，由后端服务 **QM-AI**（Spring Boot 4 + Spring AI）与桌面客户端 **QM-ELECTRON**（Electron + Vue 3）组成。

平台以**统一 Agent** 为入口，覆盖智能对话、文生图 / 图生图、以及文生视频 / 首帧 / 首尾帧 / 参考生视频 / 文件生视频等多模态生成能力，并提供作品发布与浏览、服务端任务自动轮询 + SSE 主动推送、本地优先的聊天记录存储与多端同步等完整链路。

---

## 目录

- [项目架构](#项目架构)
- [核心功能](#核心功能)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [API 接口概览](#api-接口概览)
- [配置说明](#配置说明)
- [许可证](#许可证)

---

## 项目架构

```
QM/
├── QM-AI/                      # Spring Boot 后端服务
│   ├── doc/db/                 # SQL 脚本（建表 + 验证码 / 任务 / 封面等增量脚本）
│   └── src/main/java/xyz/qm/
│       ├── agent/              # 统一 Agent 核心：RouterAgent 意图分发 + Chat/Image/Video 执行器
│       │   └── tool/           # Spring AI @Tool 工具（提交异步生成任务）
│       ├── biz/                # 业务层接口与实现
│       ├── config/             # 配置类（AI 模型、Sa-Token、Redis、线程池等）
│       ├── controller/         # REST API 控制器
│       ├── dto/  vo/           # 请求 / 响应对象
│       ├── entity/  mapper/    # 数据库实体与 MyBatis Plus Mapper
│       ├── enums/              # 枚举（AgentIntent、任务类型 / 状态、会话事件等）
│       ├── service/            # 服务层（任务轮询、SSE 推送、验证码、IP 归属地、视频封面等）
│       └── exception/  aspect/ # 全局异常处理与切面
│
└── QM-ELECTRON/                # Electron 桌面客户端（同一份渲染源码可构建纯 Web 版）
    └── src/
        ├── main/               # 主进程（窗口、IPC、下载、自动更新、日志）
        ├── preload/            # 预加载脚本（contextBridge 暴露受控 API）
        ├── renderer/           # 渲染进程（Vue 3：对话 / 作品 / 登录 / 个人中心）
        └── shared/             # 三方共享的 IPC 频道与类型契约
```

---

## 核心功能

### 统一 Agent 链路

- **单一入口**：`/ai/agent` 统一接收对话、生图、生视频请求（纯 JSON，或含图片 / 视频 / 音频 / 文件素材的 multipart），以 SSE 流式返回。
- **意图分发**：由用户显式选择 `CHAT` / `IMAGE` / `VIDEO` 意图，经 RouterAgent 分发至对应执行器，**不由模型自行覆盖**。
- **工具调用**：基于 Spring AI `@Tool` 将七类生成能力（文生图、图生图、文生视频、首帧、首尾帧、参考生视频、文件生视频）注册为模型工具；工具只负责提交异步任务并立即返回任务 ID。
- **多模态对话**：CHAT 意图携带图片 / 视频时走视觉模型（qwen-vl 系列），携带音频时走全模态模型（qwen-omni 系列）。
- **提示词扩写**：`/ai/agent/prompt/expand` 提供图片 / 视频提示词的 AI 智能扩写。

### 后端服务（QM-AI）

| 模块 | 功能描述 |
|------|---------|
| **AI 对话** | 基于上下文的智能对话，SSE 流式响应；对话记忆存储于 Redis Stack（7 天 TTL 自动清理） |
| **AI 图像生成** | 文生图、图生图，支持 qwen-image 3.0 与 wan2.7-image 双模型族（分辨率档位、思考模式、水印等差异化参数） |
| **AI 视频生成** | 万相 3.0 全能参考模型，支持文生视频、首帧、首尾帧、参考生视频、文件生视频五种模式，可选有声视频 |
| **任务轮询与推送** | 服务端基于 Redisson ZSet 的退避轮询队列自动查询 DashScope 异步任务，完成后经 SSE 主动推送客户端；支持多实例接管与对账兜底，可灰度开关回退客户端轮询 |
| **会话管理与多端同步** | 会话 / 消息增量同步接口 + 独立 SSE 会话事件通道，配合客户端本地优先存储实现多端同步 |
| **用户认证** | 注册、登录（密码 / 邮箱免密）、Token 自动续签、同端互斥多端登录；图片验证码（Hutool）+ 邮箱验证码双验证码 |
| **权限管理** | 基于 Sa-Token 的角色权限控制，登录态 Redis 持久化，支持踢人下线、强制下线、封禁 / 解封 |
| **IP 归属地** | ip2region 离线解析登录 / 注册客户端 IP 归属地并落库 |
| **视频封面** | FFmpeg 命令行自动截取视频首帧封面 |
| **作品管理** | AI 作品发布、撤回、分页浏览、详情查看、按消息溯源 |
| **个人资料** | 资料编辑、头像上传、密码修改与邮箱重置 |
| **文件存储** | 本地 / 静态服务器映射存储模式，图片上传接口 |
| **基础能力** | Redisson 分布式锁、Redis 多类数据结构封装、Spring AOP、异步任务、MCP Server（Streamable-HTTP） |

### 桌面客户端（QM-ELECTRON）

- 跨平台桌面应用（Windows / macOS / Linux），同一份渲染进程源码可构建纯 Web 静态站点
- 对话页三模式（智能对话 / 图片 / 视频）切换，流式输出经 **marked + DOMPurify** 安全渲染 Markdown
- 本地优先聊天记录（Dexie.js / IndexedDB）：会话、消息、草稿三表，流式节流写入、失败重发
- 作品广场：浏览、发布、撤回、生成参数快照查看、图片 / 视频预览
- 媒体下载：主进程原生下载 + 选择保存目录 + 打开目录（IPC）
- 无边框窗口自定义标题栏、设置弹窗、自动更新、统一日志落盘

---

## 技术栈

### 后端

- **Java 21** + **Spring Boot 4.1.1**（WebMVC + WebFlux SSE）
- **Spring AI 2.0.1** — Agent、工具调用与对话记忆（OpenAI 兼容模式对接阿里云百炼 DashScope）
- **DashScope SDK 2.22.30** — qwen-image / wan2.7-image 图像生成、万相 3.0 视频生成原生调用
- **MyBatis Plus 3.5.17** — 数据库访问（逻辑删除、驼峰映射）
- **Sa-Token 1.45.0** — 认证鉴权（Redis Jackson 持久化）
- **Redisson 4.7.0** — 分布式锁、任务轮询 ZSet 队列
- **Hutool 5.8.34 / ip2region 3.3.7 / SpringDoc OpenAPI 3.1.1** — 验证码、IP 归属地、Swagger 文档

### 前端

- **Electron 44** + electron-vite 5 + Vite 7
- **Vue 3.5** + TypeScript 5.9 + Pinia 4 + Vue Router 5
- **Element Plus 2.14** + SCSS
- **Dexie.js 4** — IndexedDB 本地存储
- **marked 18 + DOMPurify 3.4** — Markdown 安全渲染
- **axios / electron-updater / electron-log**

---

## 快速开始

### 环境要求

- **后端**：JDK 21、MySQL 8.0+、Redis Stack 7.0+（对话记忆依赖 RedisJSON 与 Query Engine 模块，普通 Redis 会启动失败）、FFmpeg（视频封面，可选）
- **前端**：Node.js ≥ 24、pnpm

### 后端服务启动

```bash
cd QM-AI

# 1. 执行 SQL 脚本初始化数据库（doc/db/allTables.sql 及增量脚本）
# 2. 在 application-dev.yml 中配置数据库、Redis、百炼 API Key、邮箱 SMTP、文件存储路径
# 3. 启动（注意：命令行须显式指定 JDK 21，否则默认 JDK 会报"不支持发行版本 21"）
JAVA_HOME=<JDK21路径> ./mvnw spring-boot:run
```

> 百炼 API Key 通过环境变量 `DASHSCOPE_API_KEY` 注入；视频封面依赖外部 FFmpeg，可用 `FFMPEG_PATH` 指定可执行文件绝对路径。

启动后可访问 Swagger UI：`http://localhost:8080/swagger-ui.html`

### 桌面客户端启动

```bash
cd QM-ELECTRON

# 安装依赖（postinstall 自动执行 electron-builder install-app-deps）
pnpm install

# 启动开发模式（HMR）
pnpm dev

# 构建纯 Web 版本
pnpm build:web

# 打包桌面安装包（win / mac / linux / all）
pnpm build:mac
```

详见 [QM-ELECTRON/README.md](QM-ELECTRON/README.md)。

---

## API 接口概览

> 除标注外，所有接口均需登录（请求头携带 `satoken`）。

### 统一 Agent（`/ai/agent`）

| 接口 | 方法 | 描述 |
|------|------|------|
| `/ai/agent` | POST (JSON) | 统一 Agent 请求，SSE 流式响应 |
| `/ai/agent` | POST (multipart) | 含素材（图片 / 视频 / 音频 / 文件）的 Agent 请求 |
| `/ai/agent/prompt/expand` | POST | 图片 / 视频提示词 AI 扩写 |
| `/ai/agent/task/{id}/progress` | GET | 单任务进度查询 |
| `/ai/agent/task/list` | GET | 当前用户全部任务分页列表 |
| `/ai/agent/task/events` | GET (SSE) | 任务完成事件主动推送通道 |

### 认证与用户

| 接口 | 方法 | 描述 |
|------|------|------|
| `/auth/register` | POST | 用户注册（图片 + 邮箱双验证码） |
| `/auth/login` | POST | 登录（密码 / 邮箱免密） |
| `/auth/captcha/image` | GET | 获取图片验证码 |
| `/auth/captcha/email` | POST | 发送邮箱验证码 |
| `/auth/logout` · `/auth/me` · `/auth/renew` | POST/GET | 退出登录、当前用户、Token 续签 |
| `/user/profile` | PUT | 个人资料编辑（部分更新语义） |
| `/user/profile/password` | PUT | 修改密码（验证旧密码） |
| `/user/profile/password/reset-code` · `/reset` | POST | 邮箱重置密码验证码 / 重置 |
| `/file/image` | POST | 图片（头像）上传 |

### 会话与作品

| 接口 | 方法 | 描述 |
|------|------|------|
| `/ai/session/list` · `/create` · `/{id}` | GET/POST/DELETE | 会话列表、创建、删除 |
| `/ai/session/{id}/messages` | GET | 会话消息分页 |
| `/ai/session/sync` · `/{id}/messages/sync` | GET | 会话 / 消息增量同步 |
| `/ai/session/events` | GET (SSE) | 会话变更事件推送通道 |
| `/ai/work/publish` · `/list` · `/{id}` | POST/GET | 作品发布、分页浏览、详情 |
| `/ai/work/{id}/withdraw` | POST | 撤回作品 |
| `/ai/work/source/{messageId}` | GET | 按消息 ID 溯源作品 |

### 管理接口（`/admin/auth`）

| 接口 | 方法 | 描述 |
|------|------|------|
| `/admin/auth/online` | GET | 查询在线用户 |
| `/admin/auth/kickout/token/{tokenValue}` · `/kickout/device` | POST | 按 token / 设备踢人下线 |
| `/admin/auth/force-logout/{userId}` | POST | 强制下线 |
| `/admin/auth/ban/{userId}` · `/unban/{userId}` | POST | 封禁 / 解封账号 |
| `/user/list` · `/user/{id}` | GET | 用户列表 / 详情 |
| `/user/{id}` | PUT | 更新用户信息 |

### 直连生成接口（Agent 之外的独立通道）

| 接口 | 方法 | 描述 |
|------|------|------|
| `/ai/image/generate` · `/edit` | POST | 文生图 / 图生图（同步） |
| `/ai/image/async/generate` · `/async/edit` | POST | 文生图 / 图生图（异步任务） |
| `/ai/image/task/{id}/progress` | GET | 图片任务进度 |
| `/ai/video/text-to-video` | POST | 文生视频 |
| `/ai/video/first-frame` · `/first-last-frame` | POST | 首帧 / 首尾帧生视频 |
| `/ai/video/reference` · `/file-to-video` | POST | 参考生视频 / 文件生视频 |
| `/ai/video/task/{id}/progress` | GET | 视频任务进度 |
| ~~`/ai/chat`~~ · ~~`/ai/chat/stream`~~ | POST | 对话（同步 / SSE 流式）**已废弃**，请改用 `/ai/agent` |

---

## 配置说明

主要配置集中在 `QM-AI/src/main/resources/application.yml`（公共）与 `application-{env}.yml`（环境）：

```yaml
server:
  port: 8080

spring:
  # 数据库 / Redis 连接在各环境配置文件中定义
  ai:
    openai:
      # 阿里云百炼 OpenAI 兼容模式
      base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
      chat:
        model: qwen-plus

qm:
  ai:
    chat:
      model: qwen3.8-max           # 记录到对话消息的模型名
      vision-model: qwen-vl-max    # 携带图片 / 视频时的多模态视觉模型
      audio-model: qwen-omni-turbo # 携带音频时的全模态模型
    image:
      model: qwen-image-3.0-pro    # 可选 qwen-image-3.0 / wan2.7-image / wan2.7-image-pro
    video:
      model: wan3.0-video-prime    # 万相 3.0，可选 wan3.0-video（标准版）
    task-poll:
      enabled: true                # 服务端任务轮询 + SSE 主动推送灰度开关
  ip2region:
    v4-xdb-path: classpath:ip2region/ip2region_v4.xdb

file-storage:
  mode: local                      # 本地存储 + Nginx 静态映射（url / path 在环境配置中定义）
  video-cover:
    enabled: true                  # FFmpeg 视频封面截取
    ffmpeg-path: ffmpeg

sa-token:
  token-name: satoken              # 前后端分离：请求头携带 satoken
  timeout: 2592000                 # 30 天有效期，活跃自动续签
```

---

## 许可证

本项目仅供学习交流使用。