PianoAgent：开源 AI 钢琴作曲 Agent，用自然语言谱写钢琴曲

PianoAgent ：开源 AI 钢琴作曲 Agent ，用自然语言谱写钢琴曲

当前大模型音乐生成类项目层出不穷，但多数方案直接让大语言模型（LLM）输出 MIDI 音符，普遍存在音符错乱、乐理不符合规范、节奏混乱等缺陷。PianoAgent 采用差异化的设计思路：不交由大模型直接生成音符，将 LLM 定位为思考规划角色，把实际作曲工作交由专业音乐引擎完成。

PianoAgent 是一款开源 AI 钢琴作曲 Agent 应用。用户仅需通过自然语言描述曲子的氛围、情绪、曲风，整套 Agent 工作流水线将自动完成乐理知识检索、作曲结构规划、音符序列生成、演奏效果优化、作品质量评估，最终渲染输出可直接播放的钢琴音频。

项目实现完整端到端产品能力，包含前端交互界面、后端 Agent 调度模块、RAG 乐理知识库、音频渲染引擎。既支持本地源码一键启动，也封装为 NPM 工具包，单条命令即可完成部署运行。

1.Agent Pipeline 分工架构（核心设计理念） LLM 不直接生成 MIDI 文件。大模型负责理解用户需求、乐曲构思、整体结构规划；专业音乐模块承担音符生成、乐理校验、演奏细节修饰工作，从根源降低 AI 作曲中常见的乐理错误问题。

完整业务流水线：自然语言输入 → 乐理知识 RAG 检索 → 作曲结构规划 → 音符序列生成 → 演奏力度优化 → 作品质量自评 → 音频渲染输出

2.Web 可视化交互界面 基于 Vue3 构建前端页面，支持钢琴曲实时预览、创作草稿持久保存、播放时行高亮，同时支持自定义图片、视频背景，提供完整流畅的使用体验。

3.开箱即用 CLI 命令行工具 项目封装完整命令行入口，提供两种使用模式：

4.RAG 乐理知识库 内置乐理知识库，创作过程检索和弦、调式、曲式等乐理参考资料，辅助 Agent 产出专业性更强的钢琴作品。

5.SSE 流式响应能力 作曲全流程采用流式输出，页面实时展示 Agent 每一步思考与执行过程，无需等待全部任务完成后再返回结果。

6.草稿持久化能力 自动保存创作草稿，支持继续编辑历史项目，回放过往创作记录。

环境要求 Node.js >=18

全局安装工具包

npm install -g piano-agent-ai

新建独立文件夹，创建.env配置文件填入大模型 API 密钥，在该目录执行命令：

piano-agent

也支持 npx 免安装直接运行：

npx piano-agent-ai

cd PianoAgent

npm install

node bin/cli.js

复制.env.example并重命名为.env，填写大模型接口密钥，访问浏览器服务地址即可开展创作。

CLI 脚本区分开发环境与 NPM 运行环境 本地源码环境检测前端未编译时，自动执行构建；NPM 安装运行环境禁止在 node_modules 目录内执行 npm 操作，避免污染宿主项目依赖。
Git + NPM 标准化工程规范 通过.npmignore过滤媒体资源、缓存、开发类文件；利用prepublishOnly钩子在发布 NPM 包前自动构建前端资源；使用npm pack校验打包输出产物，保障发布质量。
配置解耦设计 优先读取用户当前工作目录下的.env配置文件，不修改 node_modules 内部文件，实现用户业务配置与工具包本体完全解耦。

不少 AI 音乐项目直接通过 Prompt 指令让大模型输出 MIDI 序列。大模型擅长语言理解、创意构思与逻辑推理，但不擅长输出高精度乐理数值。直接生成音符会频繁出现和弦错误、节拍错乱、音域越界、旋律断裂等问题。

PianoAgent 对任务进行职责拆分：

LLM 充当 "作曲家" 负责构思，程序引擎充当 "演奏家" 负责落地执行，各司其职。

欢迎 Star、提交 Issue 与 Pull Request 参与项目共建。项目仓库：https://github.com/YoyuDev/PianoAgent