MusAgent · 音乐工坊 —— AI 音乐创作智能体

AI+ 应用项目提案（Specs）

参赛赛道：AIGC 技术赛道 · 音乐大模型子赛道 参赛方向：方向一 · 研发 AI 智能体工具 参赛身份：个人 版本：v1.2（Wave 2 提交中） · 2026-07-25

详细文档导航：评测细则 docs/evaluation.md ｜ 工具集 docs/toolset.md ｜ 总体规划 PLAN.md ｜ 技能设计 skills/ ｜ 阶段记录 docs/progress/

---

评审导航：提交要求对照表（Wave 2）

比赛要求（方向一 · Wave 2）	本仓库位置	状态
Skills：完整、有效、可运行	skills/ 五个 SKILL.md + 16 个可运行脚本 + 7 份参考文档，输入输出契约全管线对齐；2026-07-23 本机复测 15 项全过（语法 25/25、CLI 14/14、押韵 0.8696、重复度 0.0、提示词编译、整曲段计划 179.9s/8 段、响度补救 -9.8→-14.1 LUFS、封面/发布包双向校验，逐项记录见 wave2-selfcheck.md §2）	✅
核心业务逻辑功能闭环	单曲端到端真实闭环：brief → lyrics → style_prompt → 8 段生成 → 拼接 184.1s 整曲 → QA → 归因 → v2 提示词 → R2 收敛 pass（CLAP 0.2441→0.5703，+0.33 过 0.29 线，seed 链不变单变量归因），每环产出物在库可核对（assets/track-ooden/）。v2 提示词杠杆已固化回编译器（重编译与手工 v2 逐字一致）；T6 旋律接力引擎杠杆双指标失败，如实留痕（三轮对照分析）。断点治理五轮迭代全留痕：R1 人评"断点割裂"→ 静默裁剪（94.8s 缺口 56.1dB→1.8dB）→ 节拍相位对齐（人评"大大进步"）→ R3 groove-lock 织体锚（2026-07-24 收敛：人评"很流畅"，七接缝能量全 ≤±1.6dB，CLAP 0.4586 过线） → R4 分级锚针对"循序渐进"在验（t5-round3/）	✅ 已收敛
按 Specs 评测标准经测试	T3 基线 20 条实测定稿：CLAP 均值 0.0991 / σ=0.1909 → M3 通过线 0.2900（baseline-report.md）；T2 编译组 5 条均值 0.3242 ≥ 0.2900 → M3 初步达成（t2-results.json）；阈值校准落地 run_qa.py CLAP_THRESHOLD = 0.29（留痕 baseline_clap.md）。M1-mini 两轮对照（2026-07-24，20 条 × 10s，冻结 seed）：v1 30% → v2c1 45%（编译器修复 +15pp：genre 词表/mood 抽取按证据扩充）→ v2 选优 55%（n=2 候选 +10pp），增益分解干净、短板归因到风格包（m1-mini-analysis.md、m1-mini-v2-analysis.md）	✅ 初步达成
产品原型（Prototype）跑通	① CLI 原型：五技能脚本链即 CLI 管线，全部可运行；② 最小界面 web/showcase/（React+Vite）：2026-07-23 npm run build 复验通过，展示页已接 T5 真实数据	✅
工作流文档 / 关键模块说明	3.1 系统架构 / 3.2 业务流程图 + PLAN.md + 各 SKILL.md 契约与 references	✅
演示链接	原型演示：web/showcase/运行说明.md（本地构建即可预览，已接真实数据）；工具链实测记录：wave2-selfcheck.md	✅
M1 端到端成功率 ≥70%（20 条全量）	证据链：T5 单曲整曲闭环 + M1-mini 两轮片段对照（30%→55%，趋势与归因明确）；V2 全量三件套已就绪（任务书草案 判定口径/分批/算力预置、20 份冻结歌词三检全过、m1_fullrun.py 编排脚本全链干跑 20/20），待短板修复（pop 包实证固化微实验在验）→ M1-mini-v3 复测过 60% 门即排期	❌ 待补，路径与输入全就绪

一、项目概述

1.1 项目定位

MusAgent（音乐工坊）是一款面向音乐创作全流程的 AI 智能体工具：输入一句话（情绪/场景/主题），输出一首通过客观质量检测、带封面与发布物料的原创单曲。

核心价值主张：

• 把 AI 音乐从"黑盒抽卡"变成"工程化创作"——生成可控、质量可测、失败可迭代、成果可交付
• 用智能体编排取代玄学提示词：一句话 → 结构化创作简报 → 驱动全管线
• 每条产出自带质检报告，让"好/坏"第一次有了客观依据

1.2 要解决的创作问题

痛点	现状	后果
生成不可控	提示词靠玄学，风格漂移、结构混乱、歌词跑题	平均抽卡几十次才有一首可用，且无法复现
质量不可测	响度不达标、削波爆音、时长不符只能靠人耳盲听	失败无法归因，不知道改词、改风格还是改参数
流程断裂	歌词、音频、封面、元数据、宣发文案散落各工具	从"一段音频"到"可发布作品"仍有大量手工搬运

1.3 目标用户

优先级	用户群体	痛点需求	使用场景
⭐ 首要	短视频/自媒体创作者（无乐理基础）	不会写提示词，要求"说人话就能出歌"、质量稳定	视频原创 BGM、账号主题曲
次要	独立音乐人/唱作人	灵感验证成本高	动机 → 完整 demo，可反复改词改风格
次要	AIGC 爱好者/内容玩家	要快要好玩要全能晒	热点/玩梗歌曲 + 全套物料一键发社交平台

二、应用场景深度挖掘

2.1 场景一：短视频原创 BGM / 主题曲

场景描述：自媒体创作者需要与内容情绪匹配的原创配乐，但无乐理基础、无版权预算。现状是要么用烂大街的罐头音乐（无辨识度、有撞车风险），要么在生成器里盲目抽卡。

AI 赋能方案：输入"雨夜便利店里的孤独感，慢一点的中文流行歌"，MusAgent 自动完成企划（BPM/调性/段落结构）→ 作词 → 提示词编译 → 生成 → 质检（响度 -14 LUFS 流媒体标准、无削波、时长合规、风格一致性打分）→ 不合格自动归因重生成 → 输出音频 + 封面 + 发布文案。

应用效果（目标值，评测方法见第五章）：端到端成功率 ≥70%（20 条测试集）；平均 10 分钟内出成品；相对裸提示词基线风格一致性显著提升。

后续扩展潜力：接入视频理解，直接读视频画面自动生成配乐简报（"看片出歌"）。

2.2 场景二：独立音乐人灵感 Demo

场景描述：音乐人有一段动机或情绪想验证，但编曲制作成本高、周期长，大量灵感死在 demo 阶段。

AI 赋能方案：结构化创作简报把"感觉"翻译成可控参数；歌词工坊支持按段落反复重写且自检押韵率；质检环节保证 demo 达到可发送给合作方的基本技术标准。用户可在简报、歌词、成品三处人工介入，AI 负责重活。

应用效果（目标值）：灵感到可播放 demo 从"几天"缩短到"10 分钟级"；迭代 ≤3 轮自动完成。

后续扩展潜力：导出分轨/stem 与 MIDI 草案，接入 DAW 工作流。

2.3 场景三：热点/节日歌曲快速产出与发布

场景描述：内容玩家追热点出歌，时效以小时计，且需要封面、标题、文案全套物料才能发平台。

AI 赋能方案：一句话进、物料包出——音频 + 封面图 + 元数据 + 三个平台版本宣发文案一次打包；全流程自动计时，热点窗口内可多次试错。

应用效果（目标值）：从输入到全套物料 ≤10 分钟；发布物料零手工。

后续扩展潜力：热点关键词自动捕获 → 定时自动生成"今日歌单"。

三、核心业务逻辑

3.1 系统架构

┌──────────────────────────────────────────────────────────┐
│ 交互层（Wave 3）                                          │
│  对话式 Agent：简报确认 → 歌词修改 → 候选拍板（三个人工决策点）│
├──────────────────────────────────────────────────────────┤
│ 技能层（Wave 2，本仓库 skills/ 五个 SKILL.md）              │
│  music-brief → lyric-craft → style-prompt → track-qa      │
│       ↑____________ 归因回环（≤3 轮）____________│          │
│                                          release-pack     │
├──────────────────────────────────────────────────────────┤
│ 生成与检测层                                               │
│  音乐生成器（双通道：平台算力额度 / Suno；备选开源 YuE、      │
│  DiffRhythm）｜ ffmpeg + pyloudnorm（硬指标）｜ CLAP（风格分）│
├──────────────────────────────────────────────────────────┤
│ 数据层                                                    │
│  brief.json → lyrics.json → style_prompt.json →           │
│  qa_report.json（brief_id 全程贯穿，质检报告驱动回环）        │
└──────────────────────────────────────────────────────────┘

3.2 核心业务流程

用户输入一句话
  ↓ music-brief：解析为结构化创作简报（风格/情绪/BPM/调性/段落结构/目标时长）
  ↓ lyric-craft：按简报生成歌词，押韵率≥60% 自检，不合格自动重写（≤2 次）
  ↓ style-prompt：编译为生成器 style 提示词与参数（内置五风格 tag 库）
  ↓ 音乐生成器产出候选（每轮 2 个）
  ↓ track-qa：硬检测（时长 120–240s / true peak < -1 dBTP / 响度 -14±1 LUFS）
              + CLAP 风格一致性打分，多候选择优
  ├─ 全部通过 → release-pack：封面 + 元数据 + 宣发文案 → 可发布单曲包
  └─ 未通过 → 自动归因（歌词问题→回 lyric-craft；风格参数问题→回 style-prompt；
              主题矛盾→回 music-brief），迭代 ≤3 轮，全程留日志

3.3 数据流转设计

• 每件作品以 brief_id 唯一标识，贯穿简报、歌词、提示词、质检报告、物料包，全链路可追溯；
• 质检不合格不丢弃：归因记录（category / route_to / fix_suggestion）是下一轮迭代的输入，也是评测失败分析的原始数据；
• 阈值双轨制：目标值（-14 LUFS）与判定容差（[-15,-13]）分离，元数据照抄实测值，防止数据造假。

四、产品需求规格

4.1 功能需求

需求 ID	需求描述	优先级	交付轮次
FR1.1	一句话输入解析为结构化创作简报（JSON：风格/情绪/BPM/调性/结构/时长）	P0	Wave 2
FR1.2	简报支持人工确认与修改	P1	Wave 3
FR2.1	按简报生成带段落结构标注的歌词	P0	Wave 2
FR2.2	押韵率/重复度/主题一致性自检，不合格自动重写 ≤2 次	P0	Wave 2
FR3.1	内置五风格 tag 库（流行/国风/电子/嘻哈/City Pop），编译生成器提示词与参数	P0	Wave 2
FR3.2	tag 库可扩展新风格	P1	Wave 3
FR4.1	音频硬指标自动检测（时长/削波/响度）	P0	Wave 2
FR4.2	CLAP 风格一致性自动打分、多候选择优	P0	Wave 2
FR4.3	不合格自动归因并回环重生成，≤3 轮，全程日志	P0	Wave 2
FR4.4	响度不合格先做 loudnorm 归一化补救再归因	P1	Wave 2
FR5.1	封面图自动生成（由简报驱动）	P0	Wave 3
FR5.2	元数据（标题/艺人/简介/标签）与实测音频参数打包	P0	Wave 3
FR5.3	三平台版本宣发文案	P1	Wave 3
FR6.1	对话式交互：三个人工决策点（简报/歌词/拍板）	P0	Wave 3

4.2 非功能需求

类别	需求描述	目标值
性能	端到端生成时长（输入→单曲包）	≤10 分钟
性能	单轮质检耗时	≤2 分钟
可靠性	自动迭代上限	≤3 轮，超限向用户如实报告
可解释	每条产出自带质检报告（七项数值全记录）	100% 覆盖
合规	发布物料标注 AIGC 来源；歌词片段查重	100% 覆盖

五、评测标准

完整细则、20 条测试集全文与记录表模板见 docs/evaluation.md。核心理念：评测先行——Wave 1 即建立基线，后续每轮改进可量化、可对比。

5.1 测试集

20 条创作指令 = 5 种风格（流行/国风/电子/嘻哈/City Pop）× 4 种情绪场景，确认后冻结、逐轮复用，保证各轮成绩可比。

5.2 功能性评测

评测项	评测方法	通过标准
M1 端到端成功率（核心）	20 条测试集无人工干预跑通	≥70%
M2 音频硬指标合规率	ffmpeg + pyloudnorm 自动测量	响度 -14±1 LUFS、true peak < -1 dBTP、时长 120–240s
M3 风格一致性	laion-clap 对音频与目标风格描述打分	≥ 基线均值 + 1 个标准差
M4 歌词质量	脚本测押韵率 + LLM 评审主题一致性	押韵率 ≥60%，评审 ≥4/5

5.3 体验与效率评测

评测项	评测方法	通过标准
M5 人评 MOS（终审）	≥10 名听众双盲对比基线，5 分制	≥3.8 且高于基线 ≥0.5
M6 效率	管线日志自动计时	端到端 ≤10 分钟，迭代 ≤3 轮

5.4 基线对比

同一测试集用"裸提示词"（原句直接喂生成器、不挑选）跑一遍作为基线。本项目必须证明"编排 + 质检 + 迭代"相对"裸抽卡"有显著、可量化的提升——这是核心假设，也是评审核心证据。

测量工具链状态（2026-07-20 全部实测通过）：M2 检测链路（ffmpeg/ffprobe + pyloudnorm）实测通过，全自动产出质检报告（样例）；M3 CLAP 打分实测通过——真实生成音频 vs 目标风格 0.4598 / 无关风格 0.0865（冒烟测试）；开源生成→质检→打分闭环实测通过（L1 报告）。即：评测方法不是纸面设计，而是已落地的可执行管线。

六、技术实现

6.1 技术栈

层级	技术选型	说明
编排/LLM	Kimi	企划、作词、评审、归因、文案
音乐生成	双通道：赛事平台算力额度 / Suno；备选开源 YuE、DiffRhythm、MusicGen	单点故障可切换
音频检测	ffmpeg / ffprobe、pyloudnorm、laion-clap、librosa	硬指标 + 风格分全自动（均已安装并实测，2026-07-20）
封面视觉	图像生成插件	简报驱动封面描述
展示交付	自研作品展示网页（Wave 3）	播放 + 创作过程可视化

6.2 五技能（Skills）设计

本仓库 skills/ 目录已包含五个技能的完整设计稿（输入输出 JSON 契约全管线对齐，阈值一致），Wave 2 将其实现为可运行技能：

技能	职责	关键自检
music-brief	一句话 → 结构化创作简报	字段完整性、目标值写死
lyric-craft	歌词生成	押韵率 ≥60%、重写 ≤2 次
style-prompt	提示词工程	五风格 tag 库、排除项
track-qa	质检 + 归因回环	三硬指标 + CLAP、迭代 ≤3 轮
release-pack	发布打包	实测值入元数据、AIGC 标注

6.3 创新点

• 工程化创作闭环：业内多为单点工具或裸生成器，本项目把企划-生成-质检-迭代-打包编成闭环；
• 质检报告即产品：每条产出自带客观报告，失败可归因、可自动修复——把"抽卡运气"变成"工程参数"；
• 评测先行的开发方式：先建基线与量化指标，再迭代能力，每轮进步可证明；
• 阈值双轨与实测元数据：从机制上防止质量数据造假，适配 AI 评测与交叉评审的可审计要求。

七、商业模式

• 参赛阶段：免费开源方案与技能设计，积累评测数据与案例；
• 工具订阅：面向自媒体/音乐人按月订阅（生成额度 + 质检报告 + 物料包）；
• 单曲物料包：按首计费的一次性打包（音频 + 封面 + 文案）；
• 承制服务：为品牌/活动定制主题曲，工具降本、人工兜底。

八、社会价值

• 降低创作门槛：让无乐理基础的表达者也能拥有原创音乐，扩大音乐创作人口；
• 正版化：原创生成替代盗用罐头音乐，减少短视频配乐版权纠纷；
• AIGC 合规：物料强制标注 AI 生成来源、歌词查重，推动行业透明规范。

九、项目进展

Wave 1（2026-07-19 ~ 07-21，已完成）

• 赛程解读与方向选定（方向一 · 智能体工具）；Specs 提案 v1.0；评测体系：20 条测试集 + M1–M6 指标 + 基线方案（docs/evaluation.md）
• 五技能完整设计稿 + 代码骨架（skills/，超前完成）；本地冒烟 12/12 通过（2026-07-21）
• V3 质检工具链实测通过（2026-07-20）：ffmpeg/ffprobe + pyloudnorm 端到端自动质检（样例报告）
• CLAP 风格打分实测通过（2026-07-20）：生成音频 vs 目标风格 0.4598 / 无关风格 0.0865，判别力显著
• L1 开源生成闭环实测通过（2026-07-20）：MusicGen-small CPU 85 秒产出 10.2s 器乐 → 自动质检（qa-report-l1.json）→ CLAP 打分，全链路零人工

Wave 2（2026-07-20 起，进行中）

• T2 编译组对照实验（2026-07-20，B 机）：5 条 CLAP 均值 0.3242（t2-results.json）
• T3 裸提示词基线定稿（2026-07-22，B 机）：20 条均值 0.0991 / σ=0.1909 → M3 通过线 0.2900；T2 0.3242 ≥ 0.2900 → M3 初步达成（baseline-report.md；正式确认待 V2 全量）
• 阈值校准落地：run_qa.py CLAP_THRESHOLD = 0.29（校准留痕 baseline_clap.md）
• 整曲管线 run_fulltrack.py：段计划 + 等功率交叉淡化 + loudnorm 后处理 + stitch_report；--melody-chain 旋律接力模式（T6，针对段落断点问题的正交验证）
• T5 单曲端到端闭环收敛（2026-07-22 R1 → 07-23 R2，B 机）：8 段生成 → 整曲 184.1s，硬指标全过；R1 CLAP 0.2441 < 0.29 → verdict=fail → 归因 prompt_weak → v2 提示词 → R2 CLAP 0.5703 收敛 pass（+0.3262，seed 链不变单变量归因）（t5-round1/ → t5-round2/）
• T6 旋律接力引擎实验（2026-07-23，失败留痕）：musicgen-melody 接力模式 CLAP 0.0061 + 爆音 8040 clicks，引擎杠杆在当前形态不可行，不再追加轮次；三轮单变量对照分析 t5-t6-compare.md
• v2 提示词杠杆固化回编译器（2026-07-23）：build_style_prompt.py city_pop 包更新，重编译输出与手工 v2 逐字一致，四风格回归通过；顺带修复 M1-mini plan 实测暴露的两个链路 bug（electronic 结构校验、情绪占位词污染）
• Wave 2 提交自检（2026-07-23）：15 项评审点 ✅10 / 🟡1 / ❌3（其中 1 项本次已修）；15 项轻量实测全过（wave2-selfcheck.md）
• M4 歌词查重落地（2026-07-23）：dedup_check.py 8 字滑窗片段比对常见歌词语料，T5 真实歌词实测 0 命中 PASS
• 用户人评 R2（2026-07-23）："明显向接上靠拢，但还是衔接不上"——内容级改善同向验证，瓶颈转向工艺级（94.8s 段首静默缺口）；断点下一杠杆定为拼接前静默裁剪（t5-round2/human_review.md）
• G7 release-pack 端到端打通（2026-07-23）：首个真实 pass 数据驱动全链——封面（图像生成原图 → gen_cover 缩放校验 3000²px）→ 元数据（照抄实测 184.1s / -14.6 LUFS）→ 三平台文案 → validate_pack 校验通过（t5-release/）
• 拼接工艺改进落地（2026-07-23）：run_fulltrack.py 新增 --trim-silence 段首/段尾静默裁剪（默认关闭保单变量，V2 建议开启）+ --restitch-from 免生成重拼（无 torch 依赖）；R2 分段离线验证：verse2 尾 4.89s 静默精准裁剪，94.8s 缺口（56.1 dB 阶跃）消除 → 新接缝 1.8 dB 平滑，其余 6 接缝逐值不变，无裁剪 restitch 与 B 机质检逐项一致（restitch-validation/）
• --beat-align 节拍对齐人评终审通过（2026-07-23）：第二轮人评"节奏不统一"定位为节拍相位（八段 BPM 实测全 104.2 σ=0），接缝 ±0.5 拍微调对齐后第三轮人评"大大进步"；剩余接缝可辨为段落织体差异，转生成侧杠杆
• T5 R3 groove-lock 单变量实验（2026-07-24 收敛 pass）：严格单变量执行（同 v2 提示词/同 seed 链/同 8 段计划，仅段后缀织体锚差异）；CLAP 0.4586 ≥ 0.29 护栏，183.5s / -14.5 LUFS / -1.5 dBTP；七接缝能量阶跃全部 ≤±1.6 dB（R2 最大 7.8 dB 处现为 +0.3）；第四轮人评"很流畅，换音点被盖过"——uniform 模式锁入 V2 默认命令；新发现"无法做到循序渐进"立项 R4（t5-round3/）
• T5 R4 分级织体锚实验（2026-07-24 任务包就绪，排队 m1-mini-v2 后）：--groove-lock arc 保留律动核心锚、配器词按段落分级（intro 极简→chorus 满编→bridge 抽离→outro 渐稀）；三模式 plan 回归过（arc 逐段命中/uniform 与 R3 逐字一致/无锚纯净）；判定=人评"渐进感恢复且接缝仍流畅" + CLAP≥0.29 护栏（t5-r4-teammate-brief.md）
• M1-mini 摸底分析（2026-07-24，B 机回传）：20 条 × 10s 单候选，pass_rate 30%（6/20） 触发"<40% 回炉"分支；归因三条独立杠杆——genre 误判 25% 全灭（均值 0.0687）、mood/场景抽取失效（仅 7/20 注入）、单候选方差大（识别正确组 40%，失败多近 0 分）；零运行错误，B 机 CPU 单条 ≈9.2min（m1-mini-analysis.md，原始数据）
• M1-mini-v2 对照复测（2026-07-24，B 机回传）：三口径 v1 30% → v2c1 45% → 选优 55%——编译器修复 +15pp、候选选优 +10pp，三杠杆全实证有效；未过 60% 门落"先修短板"分支；嘻哈 4/4、国风 3/4、电子 2/4、流行 1/4、City Pop 1/4；原误判 5 条修复通过 3/5；诊断：W1 流行包系统性失效（人声 tag + ballad 核心单一化）、W2 电子子类错配、W3 City Pop 10s 高方差（随整曲验证）；附注 B 机提速 3.3×（V2 全量估算降至 ≈17–20h）（m1-mini-v2-analysis.md，原始数据）
• pop 包实证固化微实验（2026-07-24 任务包就绪，排队 R4 后）：#2/#3/#4 × A 现版/B 去 vocal（city_pop R2 证据）/C 去 vocal+c-pop 核心 × 冻结 seed，plan 9 格实测通过；胜出固化 GENRE_PACKS → M1-mini-v3 复测门 ≥60%（任务书）
• V2 冻结歌词 20 份（2026-07-25，M4 输入就绪）：全部 status=pass——rhyme 0.9615–1.0（≥0.60）、重复度/查重全 0.0；每曲一韵到底、hook 句跨段逐字一致、段序与 brief.structure 断言核对；builder 入库可复现（lyrics-frozen/）
• M1 全量：V2 20 条整曲（压轴）：任务书草案已预置（2026-07-25）——判定口径 M1=M2 硬指标+M4 歌词（≥14/20）、M3 CLAP 双口径、冻结输入清单（歌词已交付）、R3/R4 验证过的三步命令、分批 4×5（新速度 ≈18h / 旧速度 ≈56h，B1 实跑校准）、失败单轮重试政策；编排脚本 m1_fullrun.py 已落地（全链干跑四项 20/20）；三占位待定稿：groove-lock 模式（R4 终审）、pop 包版本（pop-probe）、v3 过门 ≥60%（草案）
• Wave 3：对话式交互 + 封面/物料链 + 作品展示页

十、参赛信息

• 项目名称：MusAgent · 音乐工坊 —— AI 音乐创作智能体
• 参赛赛道：AIGC 技术赛道 · 音乐大模型子赛道
• 参赛方向：方向一 · 研发 AI 智能体工具
• 参赛宣言：让每一句"我想有首歌"，都能在十分钟内变成一首经得起检测的原创单曲。

---

本文档为 AI+ 应用项目提案（Specs），用于赛事评审。项目按 Wave 1→2→3→黑客松持续迭代，各阶段全程记录见 docs/progress/；仓库维护与接力规范见 docs/handoff.md。