核心理念：LLM 不直接生成 MIDI —— LLM 负责理解与规划，专业音乐理论引擎负责执行。
- 🎼 AI 作曲：5-Agent Pipeline，LLM 设计 MusicPlan → 音乐理论引擎生成音符 → 演奏优化 → 评价反馈
- 💬 三种工作模式：常规（聊天 + 演奏乐谱）、创造（AI 生成完整曲子）、协同（AI 创作 + 可编辑草稿）
- 🎹 交互式钢琴键盘：三层音频引擎（d-piano 真实采样 → SoundFont2 → 振荡器兜底），支持键盘快捷键和延音踏板
- ✍️ 协同草稿：文本格式音符编辑（
@0ms: C4(800ms)），可录制弹奏、播放回放、导出 MIDI - 📚 Music Wiki 知识库：15 篇音乐理论文档，Qdrant 向量存储，语义 RAG 检索
- 🎤 语音交互：Web Speech API 语音输入 + TTS 语音播报
- 🎵 MIDI 管理：上传、分析、演奏、导出 MIDI 文件
- 📊 五线谱渲染：实时 Canvas 五线谱，演奏音符高亮
- 🖼️ 自定义背景：图片/视频钢琴背景
| 模式 | 图标 | 功能说明 |
|---|---|---|
| 常规 | 💬 | 闲聊 + 从历史记录和「我的乐谱」中查找已有曲子演奏，不创作新曲 |
| 创造 | ⭐ | AI 根据描述生成有 intro/theme/climax/ending 结构的完整钢琴曲 |
| 协同 | ✏️ | 创造 + 可编辑草稿。AI 生成的音符自动追加到草稿，支持手动修改、回放、导出 |
┌─────────────────────────────────────────────────────────┐
│ 浏览器 (Vue 3) │
│ ┌────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ 钢琴 │ │ 五线谱 │ │ 语音 │ │ 聊天/草稿 │ │
│ │ 键盘 │ │ 渲染 │ │ 输入 │ │ 面板 │ │
│ └────────┘ └──────────┘ └──────────┘ └───────────┘ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ piano-engine.js │ │
│ │ d-piano (Salamander 采样) → SoundFont2 → 振荡器 │ │
│ └──────────────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────┘
│ SSE + WebSocket
┌────────────────────┴────────────────────────────────────┐
│ 服务端 Agent Pipeline (Node.js) │
│ │
│ KnowledgeAgent → ComposerAgent → GeneratorAgent │
│ (LLM Wiki RAG) (LLM 规划) (乐理引擎) │
│ ↑ │
│ ┌───────────────────┐ │
│ │ LLM Wiki (15篇) │ │
│ │ 作曲·和声·演奏·风格 │ │
│ └───────────────────┘ │
│ ↓ │
│ PerformanceAgent │
│ (人性化 velocity/timing) │
│ ↓ │
│ CriticAgent │
│ (LLM 评价) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Qdrant │ │ LLM API │ │ Music │ │ SQLite │ │
│ │ 向量库 │ │ (OpenAI │ │ Theory │ │ 数据存储 │ │
│ │ │ │ 兼容) │ │ Engine │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────────────────────────────────────┘
npm install -g piano-agent-ai
piano-agent-ai浏览器打开 http://localhost:3001 即可使用。
首次运行会自动构建前端并安装依赖，请耐心等待。
- Node.js >= 18
- Docker（可选，Qdrant 向量数据库）
- LLM API Key（DeepSeek / OpenAI 兼容，创造和协同模式需要）
Windows 一键启动
双击 start.bat，自动完成依赖安装、前端构建、服务启动。
Linux / macOS 一键启动
chmod +x start.sh
./start.sh手动启动
# 1. 安装依赖
npm install
cd client && npm install && cd ..
# 2. 构建前端
cd client && npm run build && cd ..
# 3. 启动服务
node server/index.js开发模式（热更新）
# 终端 1：API 服务
node server/index.js
# 终端 2：Vite 开发服务器
cd client && npm run dev浏览器打开 http://localhost:5173。
docker run -d -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrantQdrant 用于存储钢琴曲的乐理特征向量（风格、和弦进行、音符嵌入），RAG 检索时用来找相似素材。未启动 Qdrant 时自动降级为关键词匹配。
在设置面板（齿轮图标）中配置，或编辑 server/.env：
LLM_API_URL=https://api.deepseek.com/v1 # API 地址
LLM_API_KEY=sk-your-key-here # API Key
LLM_MODEL=deepseek-chat # 模型名称兼容所有 OpenAI 接口的 API（DeepSeek、OpenAI、通义千问、Ollama、vLLM 等）。配置保存在 SQLite 数据库中。
QDRANT_URL=http://localhost:6333PORT=3001| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/prompt |
SSE 流式 — 聊天 + 音乐生成 |
POST |
/api/collab/chat |
SSE 流式 — 协同创作 |
POST |
/api/mode |
切换模式 (normal / creative) |
GET |
/api/songs |
获取内置歌曲列表 |
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/sheets |
列出所有乐谱 |
POST |
/api/sheets |
上传乐谱 |
DELETE |
/api/sheets/:id |
删除乐谱 |
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/chat-history |
获取聊天历史 |
POST |
/api/chat-history |
保存聊天消息 |
DELETE |
/api/chat-history |
清空聊天历史 |
GET |
/api/drafts |
获取草稿列表 |
POST |
/api/drafts |
保存草稿 |
DELETE |
/api/drafts/:id |
删除草稿 |
GET |
/api/history-sheets |
获取演奏历史 |
POST |
/api/history-sheets |
保存演奏记录 |
DELETE |
/api/history-sheets/:id |
删除演奏记录 |
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/upload/bg |
上传背景 |
GET |
/api/upload/bg-list |
列出背景 |
DELETE |
/api/upload/bg/:id |
删除背景 |
PUT |
/api/upload/bg/mute |
视频静音 |
| 事件 | 说明 |
|---|---|
thinking |
开始处理 |
chat_chunk |
流式聊天文本 |
chat_done |
聊天完成 |
composing |
开始作曲 |
play |
旋律就绪 {melody, description, style, source} |
error |
错误信息 |
done |
流结束 |
PianoAgent/
├── start.bat # Windows 一键启动脚本
├── start.sh # Linux/Mac 一键启动脚本
├── package.json
│
├── client/ # Vue 3 + Vite 前端
│ ├── index.html
│ ├── vite.config.js
│ ├── public/
│ │ └── agentLogo.png
│ └── src/
│ ├── App.vue # 主应用
│ ├── main.js
│ ├── components/
│ │ ├── PianoKeyboard.vue # 钢琴键盘
│ │ ├── SheetMusic.vue # 五线谱渲染
│ │ ├── ModelSettings.vue # 设置面板
│ │ └── MySheets.vue # MIDI 乐谱管理
│ └── utils/
│ ├── piano-engine.js # 三层音频引擎
│ ├── midi-parser.js # MIDI 文件解析
│ └── midi-export.js # 草稿导出 MIDI
│
├── server/ # Node.js + Express 后端
│ ├── index.js # REST + SSE + WebSocket
│ ├── ai-engine.js # AI 引擎入口
│ ├── db.js # SQLite 数据库
│ ├── music-theory.js # 音乐理论引擎
│ ├── song-library.js # 歌曲库
│ ├── qdrant-client.js # Qdrant 向量库
│ ├── .env # 环境变量配置
│ ├── agents/
│ │ ├── knowledge/index.js # KnowledgeAgent
│ │ ├── composer/index.js # ComposerAgent
│ │ ├── generator/index.js # GeneratorAgent
│ │ ├── performance/index.js # PerformanceAgent
│ │ └── critic/index.js # CriticAgent
│ ├── models/
│ │ ├── MusicPlan.js # 创作方案模型
│ │ └── CriticReport.js # 评价报告模型
│ ├── workflow/
│ │ └── music-generation-flow.js # Pipeline 调度
│ ├── wiki/ # Music Wiki 知识库
│ │ ├── documents/ # 15 篇音乐理论文档
│ │ ├── loader/ # MD 读取
│ │ ├── splitter/ # 段落切分
│ │ ├── embedding/ # Embedding 嵌入
│ │ ├── importer/ # 入库
│ │ └── reranker/ # 重排序
│ ├── knowledge/ # 知识检索
│ └── uploads/ # 用户上传文件
用户输入："创作一首忧伤的雨天钢琴曲"
│
▼
┌─────────────────────────────────────────────┐
│ 1. KnowledgeAgent — LLM Wiki RAG 知识检索 │
│ 15 篇 Wiki 文档（作曲·和声·演奏·风格） │
│ → 文档切分 → Embedding → Qdrant 向量检索 │
│ → 重排序 → 注入相关理论片段 │
├─────────────────────────────────────────────┤
│ 2. ComposerAgent — LLM 作曲规划 │
│ 结合 Wiki 检索到的理论知识进行规划 │
│ → MusicPlan JSON {key, tempo, sections[]} │
├─────────────────────────────────────────────┤
│ 3. GeneratorAgent — 乐理引擎生成 │
│ music-theory.js 逐段生成 + 拼接 │
│ → MIDI 音符序列 │
├─────────────────────────────────────────────┤
│ 4. PerformanceAgent — 演奏优化 │
│ velocity 动态、timing 人性化偏移 │
├─────────────────────────────────────────────┤
│ 5. CriticAgent — LLM 评价 │
│ 评分 0-100 + 问题 + 建议 │
│ score<70 → 反馈重新规划 │
└─────────────────────────────────────────────┘
三个八度，电脑键盘直接弹：
| 八度 | 白键 | 黑键 |
|---|---|---|
| 第 1 八度 (C3-B3) | Z X C V B N M | 1 2 3 4 5 |
| 第 2 八度 (C4-B4) | A S D F G H J | W E T Y U |
| 第 3 八度 (C5-B5) | Q R I O P K L | 6 7 8 9 0 |
空格键 = 延音踏板
| 层 | 技术 |
|---|---|
| 前端 | Vue 3, Vite, Canvas API, Web Audio API, Web Speech API |
| 后端 | Node.js, Express, WebSocket (ws), SQL.js |
| AI | OpenAI 兼容 API, Agent Pipeline, RAG |
| 向量库 | Qdrant |
| 音频 | Tone.js, d-piano (Salamander Grand Piano), SoundFont2 |
| 存储 | SQLite (config.db) |
项目内置了一个结构化的音乐理论知识库，用于 RAG（检索增强生成）检索，为 AI 作曲提供专业理论支持。
作曲理论 (wiki/documents/composition/)
intro-design.md- 前奏设计技巧climax-building.md- 高潮构建方法ending-techniques.md- 结尾处理技术
和声理论 (wiki/documents/theory/)
harmony-fundamentals.md- 和声基础chord-progressions.md- 和弦进行模式modal-harmony.md- 调式和声melody-development.md- 旋律发展技巧
演奏技巧 (wiki/documents/performance/)
dynamics-control.md- 力度控制pedal-technique.md- 踏板技术
风格研究 (wiki/documents/style/)
chopin-nocturne.md- 肖邦夜曲风格debussy-impressionism.md- 德彪西印象派sad-piano.md- 悲伤钢琴风格cinematic-piano.md- 电影配乐钢琴ambient-piano.md- 氛围钢琴japanese-film-music.md- 日本电影音乐
用户输入 → KnowledgeAgent → Wiki 检索 → 相关理论片段
↓
ComposerAgent 结合理论知识 → 生成 MusicPlan
- 文档切分：Wiki 文档被切分为语义段落
- 向量嵌入：使用 Embedding API 将段落转换为向量
- Qdrant 存储：向量存储在 Qdrant 向量数据库中
- 语义检索：根据用户输入进行相似度搜索
- 重排序：对检索结果进行相关性排序
- 注入上下文：将相关理论知识注入到 ComposerAgent 的提示词中
- Qdrant 不可用时，自动降级为
seed-data.js中的关键词匹配 - Embedding API 不可用时，使用本地 ngram-hash 嵌入算法
| 场景 | 降级方案 |
|---|---|
| Agent Pipeline 失败 | 本地音乐理论引擎接管 |
| d-piano 不可用 | SoundFont2 → Web Audio 振荡器 |
| Qdrant 不可用 | 关键词知识检索 (seed-data.js) |
| Embedding API 不可用 | ngram-hash 本地嵌入 |
| LLM 未配置 | 仅常规模式可用 |
- Agent Pipeline (5 Agents)
- Music Wiki 知识库 + Qdrant RAG
- 三种工作模式 (常规 / 创造 / 协同)
- 协同草稿编辑 + 录制 + 回放
- 语音交互 (语音输入 + TTS)
- MIDI 导入 / 导出 / 分析
- 五线谱实时渲染
- 对话历史持久化 (SQLite)
- 自定义背景 (图片/视频)
- MusicXML 乐谱导出
- 多音轨作曲
- 外部音乐数据自动导入
欢迎 Issue、PR、Star！项目完全开源，MIT 协议。