# AI-Voice-Drawing

**Repository Path**: cship/ai-voice-drawing

## Basic Information

- **Project Name**: AI-Voice-Drawing
- **Description**: ------AI 语音绘图工具------
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 声创画坊 SoundArt Studio

demo视频链接：
b站：https://www.bilibili.com/video/BV1NYJK6CEpb/?share_source=copy_web&vd_source=e94402e6a7823937063ce255b089743c

设计文档：
https://gitee.com/cship/ai-voice-drawing/blob/master/ai-command-design.md



> AI 语音操控绘画工具 — 你的声音，就是画笔

[![Spring Boot 3.2](https://img.shields.io/badge/Spring_Boot-3.2-green)](https://spring.io/projects/spring-boot)
[![Vue 3](https://img.shields.io/badge/Vue-3.x-brightgreen)](https://vuejs.org/)
[![Java 17](https://img.shields.io/badge/Java-17-orange)](https://openjdk.org/)

## 项目简介

声创画坊（SoundArt Studio）是一个 AI 驱动的语音绘画工具。用户通过语音描述画面需求，AI 自动理解意图、调用图像生成模型、将图片渲染到画布。支持连续对话修改、上下文记忆、语音导出等功能。

**核心理念**：说出心中画面，AI 为你实时绘制。

## 核心功能

| 功能 | 描述 |
|------|------|
| AI 图像生成 | 语音描述 → LLM 提取 prompt → 硅基流动/通义万象生成图片 → 画布渲染 |
| AI 全自动托管绘画 | 唤醒"小画"后全程语音操控：自动理解意图、生成图像、反馈进度 |
| 创意几何模式 | 语音拼图形：14+ 形状，本地正则快通道 <1ms |
| 语音对话 | 唤醒词"小画小画" → 四态状态机（SLEEPING→LISTENING→THINKING→SPEAKING） |
| 上下文记忆 | 连续创作：追加元素 / 冲突替换 / 主题变更自动处理 |
| 两步反馈 | "好的，正在为您创作~" → 进度动画 → "创作好啦~" → 图片渲染 |
| 语音导出 | 说"导出图片"自动触发浏览器 PNG 下载（2x Retina） |
| 画廊管理 | 作品浏览、筛选、下载、删除 |

## 技术架构

```
前端层     Vue 3 + TypeScript + Fabric.js + AudioWorklet
通信层     /ws/drawing (绘图) + /ws/voice-chat (语音) 双 WebSocket
后端层     Spring Boot 3.2 + CommandRouter (意图路由) + ChatService (对话引擎)
AI 引擎层  讯飞 STT + DeepSeek V4 + 百度 TTS + 硅基流动 / 通义万象
```

## AI 引擎矩阵

| 能力 | 主引擎 | 备用引擎 | 延迟 |
|------|--------|----------|------|
| 语音识别 | 讯飞流式 WebSocket（直连，零 SDK） | 百度 REST ASR | 实时 |
| 对话理解 | DeepSeek V4 | 通义千问 qwen-plus | ~500ms |
| 语音合成 | 百度 TTS REST | Web Speech API（前端） | ~200ms |
| 图像生成 | 硅基流动 Z-Image-Turbo | 通义万象 wanx-v1 | 3-8s |

## 快速开始

### 环境要求

- Java 17+
- Node.js 18+
- Maven 3.9+
- MySQL 8.0+

### 后端启动

```bash
cd backend
# 配置 application-dev.yml 中的数据库和 AI API Key
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

### 前端启动

```bash
cd frontend
npm install
npm run dev
```

### 配置项

| 配置 | 说明 |
|------|------|
| `drawing.deepseek.api-key` | DeepSeek API Key（对话理解） |
| `drawing.tongyi.api-key` | 通义千问 API Key（LLM Fallback） |
| `drawing.siliconflow.api-key` | 硅基流动 API Key（图像生成） |
| `drawing.xunfei.app-id` / `api-key` / `api-secret` | 讯飞语音识别 |
| `drawing.baidu.api-key` / `secret-key` | 百度语音识别 + TTS |

## 项目结构

```
ai-voice-drawing/
├── backend/
│   └── src/main/java/com/drawing/demo/
│       ├── command/        # 指令路由与解析
│       ├── config/         # WebSocket 配置
│       ├── controller/     # REST 接口
│       ├── executor/       # 命令执行引擎
│       ├── imagegen/       # 图像生成服务
│       ├── model/          # 数据模型
│       ├── service/        # 业务服务（ChatService）
│       ├── speech/         # 语音识别/合成
│       └── websocket/      # WebSocket 处理器
├── frontend/
│   └── src/
│       ├── components/     # Vue 组件
│       ├── composables/    # 组合式函数
│       ├── views/          # 页面
│       └── stores/         # 状态管理
├── project-brief.md        # 项目技术说明
├── ai-command-design.md    # AI 指令能力设计文档
└── README.md
```

## 设计文档

- [项目技术说明](project-brief.md) — 技术栈、架构、实现思路、开发难点
- [AI 指令能力设计](ai-command-design.md) — 意图识别体系、指令覆盖、未完成功能与原因

## 参与贡献

### 贡献者

| 贡献者 | 主要负责 | 详细工作 |
|--------|----------|----------|
| **vanguard-one** | 后端 + AI 引擎 + 前端核心功能 | **后端**：Spring Boot 架构设计、双 WebSocket 端点（/ws/drawing + /ws/voice-chat）、CommandRouter 三路意图路由（flowchart/creative/image）、ChatService 对话引擎与绘画意图识别、上下文记忆机制（mergeImagePrompt 追加/冲突替换/主题变更）、VoiceSession 四态状态机、讯飞流式 STT 直连（HMAC-SHA256 自鉴权）、百度 REST ASR 备用通道、硅基流动 Z-Image-Turbo 与通义万象图像生成集成、百度 TTS 语音合成、全局 Fallback 降级策略。共同参与前后端 Bug 修复与项目整体优化。<br>**前端**：用户页面多层次 UI 优化、语音交互全链路（唤醒→聆听→思考→回复）、AI 全自动托管绘画功能、语音导出功能、两步反馈机制（TTS + 进度动画）、DrawingOverlay 生成进度覆盖层。 |
| **Torn** | 前端 + 数据库 + 管理员系统 | **前端**：Vue 3 + TypeScript 架构搭建、Fabric.js 双画布引擎（创意几何 + AI 图像）、AudioWorklet PCM 音频采集、工作台/画廊/画布三页面开发、页面路由与状态管理、ModeSwitch 模式切换、ExportPanel 导出面板、HistoryModal 历史记录。共同参与前后端 Bug 修复与项目整体优化。<br>**后端**：MySQL 数据库设计与优化、用户登录/注册/鉴权系统（JWT + WebSocketAuthInterceptor）、管理员端统计概览与趋势数据接口、操作历史记录与 OSS 图片存储。 |

# 贡献流程

> 基于远端仓库 174 次提交、29 个 Pull Request 的实际协作记录整理

---

## 一、协作概览

| 指标 | 数据 |
|------|------|
| 总提交数 | 174 commits |
| PR 总数 | 29 个（!1 → !29） |
| 开发周期 | 2026-06-12 → 2026-06-14（3天） |
| 贡献者 | 2 人 |

### 提交者统计

| 贡献者 | 提交数 | 占比 | 主要领域 |
|--------|--------|------|----------|
| **Torn** | 96 | 55% | 前端架构、UI 设计系统、画布引擎、工作台/画廊/画布页面、数据库、用户系统、管理员端、操作历史、几何图形库、导出面板 |
| **vanguard-one** | 78 | 45% | 后端架构、AI 引擎集成（DeepSeek/千问/讯飞/百度/硅基流动/通义万象）、WebSocket 端点、语音助手"小画"全链路、ChatService 对话引擎、上下文记忆、图像生成管线、单元测试 |

---

## 二、PR 生命周期（标准流程）

```
┌──────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────┐
│ 1. 建分支 │───▶│ 2. 功能开发  │───▶│ 3. 发起 PR   │───▶│ 4. 审查合并  │───▶│ 5. 验证  │
└──────────┘    └──────────────┘    └──────────────┘    └──────────────┘    └──────────┘
```

### 步骤 1：创建功能分支

从 `master` 拉取最新代码后，按功能创建分支：

```bash
git checkout master
git pull origin master
git checkout -b feat/<功能名>
```

**分支命名规范**：`feat/<英文功能名>`，全小写连字符分隔

```
feat/backend-scaffold      # 后端脚手架
feat/frontend-init         # 前端初始化
feat/voice-assistant       # 语音助手
feat/creative-mode         # 创意几何模式
feat/image-gen             # 图像生成
feat/admin-statistics      # 管理后台统计
```

### 步骤 2：功能开发

在分支上进行增量开发，遵循提交规范：

```bash
# 每完成一个可独立运行的小功能点就提交
git add <files>
git commit -m "feat(scope): 简短描述"
```

**提交信息格式**：`<type>(<scope>): <subject>`

| type | 用途 | 示例 |
|------|------|------|
| `feat` | 新增功能 | `feat(voice): 语音唤醒词检测` |
| `fix` | Bug 修复 | `fix(voice): 修复跨页面对话丢失` |
| `style` | 样式调整 | `style(voice): 助手面板上调20px` |
| `refactor` | 代码重构 | `refactor(executor): 工厂方法重构` |
| `docs` | 文档 | `docs: 添加 AI 小助手开发指南` |
| `chore` | 工程配置 | `chore(deps): 更新依赖版本` |
| `test` | 测试 | `test(backend): 核心模块单元测试` |

**scope（作用域）示例**：`voice`, `draw`, `image`, `admin`, `frontend`, `backend`, `assistant`, `history`, `welcome`, `gallery`

### 步骤 3：发起 Pull Request

开发完成后，推送分支并发起 PR：

```bash
git push origin feat/<功能名>
# 在 Gitee 上创建 Pull Request
```

**PR 标题格式**：`!N feat(scope): 一句话说明本 PR 新增/修改了什么`

**PR 编号**：按合并顺序递增，从 `!1` 到 `!29`

**PR 描述需包含**：

```markdown
## 功能描述
说明该功能的作用与使用方式

## 实现思路
简要说明技术选型或核心实现逻辑

## 测试方式
如何验证该功能正常运行
```

**实际 PR 示例**：

| PR | 标题 | 包含提交 |
|----|------|----------|
| !29 | feat: 语音助手优化 + 操作历史删除 + 跨页面绘图 | 8 commits（fix + feat 混合） |
| !28 | feat(draw): 扩展几何图形库 + 智能定位系统 | 2 commits |
| !27 | feat: AI语音助手界面优化 + 创意模式图形OSS存储 | 2 commits |
| !26 | fix(admin,statistics): 修复统计概览 + 趋势数据接口 | 1 commit |
| !25 | feat(voice): 上下文记忆 + 进度动画 + 语音导出 + 工作台优化 | 8 commits |
| !24 | feat(voice): "小画"操控绘画 — 唤醒+意图+记忆+画布直达 | 14 commits |
| !23 | feat(voice): "小画"AI 语音助手全双工对话系统 | 11 commits |

**实际观察**：每个 PR 包含 1-14 个不等的分步提交（feature commits + fix commits），说明开发过程中采用了"小步提交、增量完善"的策略。

### 步骤 4：审查与合并

- PR 经审查后通过 merge commit 合并到 `master`
- 合并后主分支代码需保持**可运行状态**
- 评委在任意时间查看应能复现演示效果

```
*   3fccec7 !29 feat: 语音助手优化 + 操作历史删除 + 跨页面绘图     ← merge commit
|\
| * a292ba7 fix(voice): 修复跨页面跳转后小画对话内容丢失             ← 分支提交
| * 35d6dc0 feat(voice): 打开小画界面时播报欢迎语                    ← 分支提交
| * 45c2389 fix(voice): 修复工作台跳转画布不自动打开小画              ← 分支提交
|/  
*   bd1b054 !28 feat(draw): 扩展几何图形库 + 智能定位系统             ← 上一PR
```

### 步骤 5：验证

合并后在本地验证功能：

```bash
git checkout master
git pull origin master

# 后端验证
cd backend && mvn spring-boot:run -Dspring-boot.run.profiles=dev

# 前端验证
cd frontend && npm run dev
```

---

## 三、协作分工模式

```
           Torn                              vanguard-one
   ┌─────────────────┐                 ┌─────────────────┐
   │ 前端架构搭建     │                 │ 后端架构搭建     │
   │ Vue 3 + Vite    │                 │ Spring Boot 3.2 │
   │ Fabric.js 画布   │                │ WebSocket 端点   │
   │ UI 设计系统      │                 │ AI 引擎集成     │
   │ 页面与路由       │                 │ 语音识别/合成   │
   │ 数据库设计       │                 │ 图像生成管线    │
   │ 用户/管理员系统  │                 │ 对话引擎        │
   │ 操作历史/画廊    │                 │ 指令路由        │
   └────────┬────────┘                 └────────┬────────┘
            │                                   │
            └──────────┬────────────────────────┘
                       │
               ┌───────┴───────┐
               │  共同 Bug 修复  │
               │  项目整体优化   │
               └───────────────┘
```

**实际 PR 分工**：

| PR 范围 | 主要负责人 | 内容 |
|---------|-----------|------|
| !1 !3 !7 | vanguard-one | 测试、依赖、配置 |
| !2 !5 !6 !9 !11 !15 !17 !20 !22 !26 !27 !28 !29 | Torn | 前端 UI、样式、画布、导出、操作历史、几何图形、管理后台 |
| !4 !8 !10 !12 !13 !14 !16 !18 !19 !21 !23 !24 !25 | vanguard-one | AI 引擎集成、语音助手、上下文记忆、图像生成 |

---

## 四、提交规范要点

### 4.1 单一职责

每个 commit 只做一件事：一个功能点、一个修复、一个重构。

```bash
# ✅ 好的提交
feat(voice): 打开语音助手自动唤醒，无需喊小画小画
fix(voice): 修复欢迎语重复播报
style(voice): AI语音助手整体上调20px

# ❌ 不好的提交
update code
fix bugs
各种修改
```

### 4.2 小步提交

大功能拆分为多个独立 PR，每个 PR 再拆分为多个小步提交。例如"小画"语音助手功能（!23）拆了 11 个 commits：

```
dc4a50a feat(voice): 语音面板改为左下角浮动窗口
12de318 feat(voice): 合并 VoiceChatPanel + AssistantWidget 到右下角
196791a fix(voice): AI 图标跨页面同步 — VoiceChatPanel 提升至 App.vue
ea69dfa fix(image): 画布默认进入图像模式，忽略 localStorage 缓存
c7ac3da fix(voice): 唤醒词同音字容错 — 新增消化/笑话/校花等变体
a6ade7f fix(voice): 关闭按钮增加确认提示 + 沉睡机制
efa5424 fix(voice): 修复消息不显示 — 增加 isOpen 状态守卫
28da79b fix(voice): 合并双图标为单月亮图标 — 常驻不消失
d7ef0c6 fix(voice): 移除画廊页面重复的 AssistantWidget 图标
2dfed54 fix(image): 画布加载时同步初始图像模式到后端
```

### 4.3 可运行性

每个 PR 合并后 `master` 必须可运行，不积压破坏性改动。

---

## 五、开发节奏（按时间线）

```
Day 1 (6/12) ─── 项目初始化 + 基础架构
  ├── 后端脚手架 (Spring Boot + WebSocket + Maven)
  ├── 前端脚手架 (Vue 3 + Vite + Fabric.js)
  ├── 创意几何模式 P0 (语音 → 图形指令)
  ├── 图像生成模式 (通义万象 / 硅基流动)
  ├── !1 ~ !9 共 9 个 PR
  └── 53 commits

Day 2 (6/13) ─── AI 语音助手 + 品牌升级
  ├── "小画"全双工语音对话系统 (!23)
  ├── 品牌更名为声创画坊 SoundArt Studio (!22)
  ├── 用户系统 + 管理后台设计
  ├── AI 小助手全域同步 + 百度 TTS (!19)
  ├── 工作台视觉优化 (!20)
  ├── !10 ~ !24 共 15 个 PR
  └── 59 commits

Day 3 (6/14) ─── 功能完善 + Bug 修复
  ├── AI 绘画上下文记忆 + 进度动画 (!25)
  ├── 管理后台统计修复 (!26)
  ├── 几何图形库扩展 + 智能定位 (!28)
  ├── 语音助手优化 + 操作历史删除 (!29)
  ├── !25 ~ !29 共 5 个 PR
  └── 62 commits
```