前导检查（先执行）

_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
[ -x "$_ROOT/skill/bin/baiyin-skill-update-check" ] && _UPD=$(bash "$_ROOT/skill/bin/baiyin-skill-update-check" "$_ROOT/skill/baiyin-music-generate" 2>/dev/null || true)
[ -n "${_UPD:-}" ] && echo "$_UPD"

如果输出 UPGRADE_AVAILABLE <old> <new> <slug>：

读取 skill/baiyin-skills-upgrade/SKILL.md，执行其中的「内联升级流程」。
如果宿主支持 AskUserQuestion，使用中文四选一：立即更新 / 以后自动更新 / 暂不更新 / 不再提醒。
如果宿主不支持 AskUserQuestion（例如 OpenClaw 当前会话），直接询问用户： 检测到百音技能 <slug> 有新版本（当前 v<old>，最新 v<new>）。请回复：1 立即更新 / 2 以后自动更新 / 3 暂不更新 / 4 不再提醒。

如果输出 JUST_UPGRADED <old> <new> <slug>：

告诉用户：百音技能 <slug> 已更新到 v<new>，继续处理你的请求。

如果输出 UP_TO_DATE、SNOOZED、CHECK_DISABLED 或 CHECK_FAILED：

不打断当前任务，直接继续。

百音 AI 音乐

把自然语言请求稳定映射为百音开放平台的音乐任务请求。不要猜模型、不要猜字段类型、不要猜边界值；只使用本文明确列出的模型、枚举和规则。

前置要求

BAIYIN_API_KEY

运行时配置

BASE_URL 固定使用 https://ai.hikoon.com
只有 BAIYIN_API_KEY 缺失时，才向用户索要 API Key。

公网地址处理

当参考生成或改编需要公网音频 URL，而用户提供的是本地文件路径、聊天附件、网盘私链或其他不可直接访问的地址时，不要只提示“需要公网 URL”。
直接指导用户先使用百音开放平台文件上传接口上传文件，拿到公网地址后再继续当前流程。
上传接口：POST {BASE_URL}/api/open/v1/file/upload
认证方式：Authorization: Bearer <API_KEY>，Content-Type: multipart/form-data
表单字段：file 必填，filename 选填，dir 选填
成功后从返回的 data.url 取公网地址，填入 url 等需要 URL 的字段
不要求用户自行准备 OSS、CDN 或其他外部存储；优先提示百音开放平台上传能力

接口地址

创建任务：POST {BASE_URL}/api/open/v1/music/generate
查询任务：GET {BASE_URL}/api/open/v1/tasks/{taskId}
查询余额：GET {BASE_URL}/api/open/v1/account/quota

强约束

只允许使用下方白名单里的 mv 值。不要自行猜测 chirp-v2、chirp、invalid-model-xyz 之类的值。
如果用户指定了不在白名单中的模型，不要原样透传；直接说明不支持，并给出白名单让用户选。
prompt 必须是非空字符串。空字符串或缺失都会触发 400。
数值字段必须传 number，不要传 string。
task = "cover" 时，必须同时有 cover_clip_id。只有外部 url 不足以进入改编模式。
url 只接受可访问的 http:// 或 https:// 公网链接。不要传本地路径、file://、../ 这类路径。
后端当前对无效 mv 的拦截并不可靠，skill 侧必须自己做白名单校验。

可用模型白名单

只使用这些值：

| mv 值 | 展示版本 | 特点 | 适用场景 | prompt 上限 | tags 上限 | |---|---|---|---|---:|---:| | chirp-fenix | V5.5 | 次世代旗舰音乐模型，超越录音棚级音质 | 默认首选，通用高质量生成 | 5000 | 1000 | | chirp-crow | V5 | 录音棚级音质，强音质表现 | 对音质要求高 | 5000 | 1000 |

规则：

默认模型：chirp-fenix
如果用户明确指定了上表中的模型，则使用用户指定值
如果用户没有指定模型，则始终回落到 chirp-fenix

字段清单

顶层字段

| 字段 | 类型 | 是否必填 | 允许值 / 边界 | 说明 | |---|---|---|---|---| | prompt | string | 是 | 非空；长度受 mv 限制 | 歌词或歌曲描述 | | mv | string | 否，但 skill 应始终传 | 见模型白名单 | 音乐模型 | | title | string | 否 | 未见明确后端长度校验 | 歌曲标题；缺失时自动生成短标题 | | tags | string | 否 | 长度受 mv 限制 | 逗号分隔的风格标签 | | negative_tags | string | 否 | 未见明确后端长度校验 | 负向风格约束 | | make_instrumental | boolean | 否 | true / false | 是否纯音乐 | | isCustom | boolean | 是 | true / false | 完整歌词时通常为 true，只有创作描述时通常为 false | | url | string | 否 | 必须是可访问的 http/https 链接 | 参考音频链接，仅参考生成或外部音频辅助时使用 | | task | string | 否 | "" 或 "cover" | 任务模式；改编才用 "cover" | | cover_clip_id | string | 条件必填 | task = "cover" 时必填 | 改编目标的 musicId / clip_id | | cusromPrompt | boolean | 否，但建议固定传 | true | 接口历史字段，拼写就是 cusromPrompt，不要改成 customPrompt | | options.parentMessageId | number | 否，但建议固定传 | 0 | 固定传 0 即可 |

`control_option`

| 字段 | 类型 | 是否必填 | 允许值 / 边界 | 说明 | |---|---|---|---|---| | control_option.gender | string | 否 | m / f / random | 歌手性别 | | control_option.weirdness_constraint | number | 否 | 0 到 1 | 随机度；越高越放飞 | | control_option.style_weight | number | 否 | 0 到 1 | 风格影响权重 | | control_option.audio_weight | number | 否 | 0 到 1 | 参考音频影响权重 |

字段组装规则

`prompt`

用户给了完整歌词：直接作为 prompt，并设 isCustom = true
用户只给了主题、情绪、风格、用途：整理成歌曲描述作为 prompt，并设 isCustom = false
不允许传空字符串

`title`

用户给了歌名：直接用
用户没给：自动生成简短标题
不要为了标题单独追问

`mv`

用户明确指定白名单模型：用用户值
用户没指定：用 chirp-fenix
用户指定了白名单外模型：不要透传，直接告诉他当前只支持白名单模型

`tags`

把风格、情绪、乐器、年代、人声特征整理成逗号分隔字符串
示例：流行,温暖,女声,钢琴
不要把自然语言整段塞进 tags

`make_instrumental`

用户明确说“纯音乐”“BGM”“背景音乐”“不要人声”时：true
其他情况：false

`control_option.gender`

男声：m
女声：f
未指定：random
如果是纯音乐，性别不是关键约束；未指定时仍可保留 random

`negative_tags`

只有用户明确提出“不要电音”“不要摇滚”“不要说唱”时才填
没说就传空字符串或不传

`url`

只有用户明确提供外部参考音频并要求“参考这个音频来做”时才传
普通文本生歌不要强行要求 url
只接受公网 http/https 链接

`task` 与 `cover_clip_id`

普通生成：task = ""，不传 cover_clip_id
参考音频生成：task = ""，可传 url
改编模式：必须同时满足
- task = "cover"
- cover_clip_id 有值
如果用户只是给了一个外部音频链接，但没有百音历史结果 musicId，这更像“参考音频生成”，不是严格的“改编”

模式判定

普通生成

适用：

“写一首歌”
“做一首流行歌”
“根据这个主题写首歌”

请求特征：

不传 url
task = ""

参考音频生成

适用：

“参考这个音频做一版”
“按这个音频的感觉生成”
“基于这个 demo 做一首歌”

请求特征：

传 url
task = ""
不要强行补 cover_clip_id

改编模式

适用：

“改编刚才那首”
“把第一首改成男声版”
“把上一首换成摇滚风”

请求特征：

task = "cover"
cover_clip_id 必填
如有必要可额外传 url，但不能只靠 url

默认值

除非用户明确指定，否则使用：

{
  "mv": "chirp-fenix",
  "make_instrumental": false,
  "negative_tags": "",
  "cusromPrompt": true,
  "options": { "parentMessageId": 0 },
  "control_option": {
    "gender": "random",
    "weirdness_constraint": 0.5,
    "style_weight": 0.5,
    "audio_weight": 0.5
  }
}

最小安全请求体

普通生成 / 参考音频生成

{
  "prompt": "<非空字符串>",
  "mv": "chirp-fenix",
  "title": "<标题>",
  "tags": "<逗号分隔标签>",
  "negative_tags": "",
  "make_instrumental": false,
  "isCustom": false,
  "cusromPrompt": true,
  "options": { "parentMessageId": 0 },
  "control_option": {
    "gender": "random",
    "weirdness_constraint": 0.5,
    "style_weight": 0.5,
    "audio_weight": 0.5
  }
}

如果是参考音频生成，再额外补：

{
  "url": "https://example.com/demo.mp3"
}

改编模式

{
  "prompt": "<非空字符串>",
  "mv": "chirp-fenix",
  "title": "<标题>",
  "tags": "<逗号分隔标签>",
  "negative_tags": "",
  "make_instrumental": false,
  "isCustom": true,
  "task": "cover",
  "cover_clip_id": "<历史 Baiyin musicId>",
  "cusromPrompt": true,
  "options": { "parentMessageId": 0 },
  "control_option": {
    "gender": "random",
    "weirdness_constraint": 0.5,
    "style_weight": 0.5,
    "audio_weight": 0.5
  }
}

明确的校验规则

prompt
- 必填
- 非空
- 长度上限取决于 mv
mv
- 必须是白名单值
- 不接受猜测值
control_option.weirdness_constraint
- 类型：number
- 范围：0 <= x <= 1
control_option.style_weight
- 类型：number
- 范围：0 <= x <= 1
control_option.audio_weight
- 类型：number
- 范围：0 <= x <= 1
control_option.gender
- 只能是 m / f / random
task
- 只能是 "" 或 "cover"
cover_clip_id
- 仅当 task = "cover" 时必填

对话处理规则

一句话里给了歌名、性别、歌词、风格、模型时，一次性提取，不要拆成多轮确认
用户说“随便生成一首”“做一首歌”，直接用默认值创建任务，不要过度追问
用户说“查下刚才那个任务”“给我下载链接”，优先复用最近一次明确的 taskId
用户说“把上一首改成男声摇滚版”，优先复用最近一次明确的 musicId
如果需要改编，但没有可复用的 musicId，不要硬上 task = "cover"；先追问要改编哪一首

最少追问原则

只有这些情况才追问：

连可用的 prompt 都组不出来
用户指定了白名单外模型，需要他改选白名单模型
用户要求参考音频生成，但没给可用的公网音频链接
用户要求改编，但上下文里没有可复用的 musicId
用户要求查进度或下载结果，但上下文里没有明确 taskId

不要为了这些事情打断用户：

用户没指定模型
用户没给标题
用户没指定性别
用户只给了宽泛风格描述

错误处理

400
- 参数不合法
- 典型场景：空 prompt、数值越界、数值类型错误、task="cover" 但缺 cover_clip_id
401
- API_KEY 无效或不可用
402
- 余额不足
404 查询任务
- taskId 不存在
404 查询余额
- 当前环境未部署余额接口
后端报 Not found
- 当前参考源不支持改编，或引用资源不存在

示例

示例 1：普通生成

用户：帮我生成一首明亮一点的流行歌，主题是春天和重新出发
结果：
- mv = "chirp-fenix"
- make_instrumental = false
- isCustom = false

示例 2：完整参数一次给齐

用户：帮我生成一首歌，歌名叫《夜航》，女声，歌词是“城市灯火都睡去”，风格是流行电子，模型用 chirp-v4-5
结果：
- title = "夜航"
- control_option.gender = "f"
- prompt = "城市灯火都睡去"
- tags = "流行,电子,女声"
- mv = "chirp-v4-5"
- isCustom = true

示例 3：纯音乐

用户：生成一首赛博电子风的纯音乐，做短视频 BGM
结果：
- make_instrumental = true
- tags 应包含 赛博,电子,BGM

示例 4：参考音频生成

用户：参考这个音频做一版电子流行：https://example.com/demo.mp3
结果：
- url = "https://example.com/demo.mp3"
- task = ""

示例 5：改编已有结果

用户：把第二首改编成男声摇滚版
结果：
- task = "cover"
- cover_clip_id = "<第二首对应的 musicId>"
- control_option.gender = "m"
- tags 包含 摇滚

回复约束

在任务真正 succeeded 之前，不要假装歌曲已完成
返回最终结果时，优先读取任务查询结果中的音频资源
如果有多种资源，按音频、视频、图片分组返回
音乐相关的后续查询继续在这个 skill 内完成，不依赖额外 task-center skill
当任务查询结果里存在 result.items 时，必须遍历并返回全部条目，不要只返回第一个音频链接
当用户说“给结果”“把下载链接给我”“把歌曲发我”时，默认行为是返回当前任务下的全部音乐结果，不需要等用户额外要求“把两个版本都给我”
如果当前任务返回了多个音乐条目，要按顺序全部列出；至少使用“版本 1、版本 2、版本 3 ...”或“第 1 首 - 版本 1”这样的明确标签，避免只展示一个链接
如果是批量生成并且一共返回 4 个音乐条目，默认按 4 个条目全部输出；不要自行截断，不要只挑一个“最好”的版本
如果 result.items 里每个条目都带 audioUrl，优先把每个条目的 audioUrl 全量列出来；有 videoUrl、coverUrl 时，再作为补充附在对应条目下

多版本结果返回规则

把 result.items 视为最终结果的完整列表；列表里有几个音乐条目，就返回几个音乐条目
不要自行假设“同一首歌只需要给一个版本”
不要只挑第一个成功的音频链接回复
不要把多个版本合并成一句模糊描述，例如“已生成两个版本，可任选下载”；应该直接把每个版本的下载链接逐条列出来
如果用户没有指定只看某一首或某一个版本，默认返回全量结果
如果用户明确说“只给我第一首”或“只看版本 2”，这时才按用户要求裁剪输出

多版本结果示例

用户：把结果给我
假设 result.items 中有 4 个音乐条目
回复应类似：
- 第 1 首 - 版本 1：<audioUrl>
- 第 1 首 - 版本 2：<audioUrl>
- 第 2 首 - 版本 1：<audioUrl>
- 第 2 首 - 版本 2：<audioUrl>
如果无法可靠判断“第几首”和“第几个版本”的分组关系，至少也要按返回顺序给出：
- 版本 1：<audioUrl>
- 版本 2：<audioUrl>
- 版本 3：<audioUrl>
- 版本 4：<audioUrl>

最终结果输出优先规则

本节优先级高于前文中任何模糊的“简要返回结果”描述
当任务查询结果存在 result.items 时，必须把 result.items 视为完整结果列表
result.items 中有几个音乐条目，就返回几个音乐条目；不要只取第一个
用户说“给我结果”“给我下载链接”“把歌曲发我”时，默认行为是返回当前任务下的全部音乐结果，不需要用户额外说明“把两个版本都给我”
如果是批量生成，且当前任务最终有 4 个音乐条目，就按 4 个条目全部返回
不要只挑一个“最好”的版本，不要擅自截断结果，不要把多个版本合并成一句模糊描述
返回时优先逐条列出每个条目的 audioUrl
如果同一条目还存在 videoUrl、coverUrl，可以作为该条目的补充信息一起返回
如果无法可靠判断“第几首”和“第几个版本”的分组关系，也必须按返回顺序把全部条目列出来，至少标成“版本 1、版本 2、版本 3、版本 4”
只有当用户明确要求“只给我第一首”或“只看版本 2”时，才允许裁剪输出

最终结果输出示例

用户：把结果给我
假设 result.items 一共返回 4 个音乐条目
默认回复示例：
- 第 1 首 - 版本 1：<audioUrl>
- 第 1 首 - 版本 2：<audioUrl>
- 第 2 首 - 版本 1：<audioUrl>
- 第 2 首 - 版本 2：<audioUrl>
如果无法确定分组关系，则至少返回：
- 版本 1：<audioUrl>
- 版本 2：<audioUrl>
- 版本 3：<audioUrl>
- 版本 4：<audioUrl>

baiyin-music-generate

前导检查（先执行）

百音 AI 音乐

前置要求

运行时配置

公网地址处理

接口地址

强约束

可用模型白名单

字段清单

顶层字段

control_option

字段组装规则

prompt

title

mv

tags

make_instrumental

control_option.gender

negative_tags

url

task 与 cover_clip_id

模式判定

普通生成

参考音频生成

改编模式

默认值

最小安全请求体

普通生成 / 参考音频生成

改编模式

明确的校验规则

对话处理规则

最少追问原则

错误处理

示例

示例 1：普通生成

示例 2：完整参数一次给齐

示例 3：纯音乐

示例 4：参考音频生成

示例 5：改编已有结果

回复约束

多版本结果返回规则

多版本结果示例

最终结果输出优先规则

最终结果输出示例

`control_option`

`prompt`

`title`

`mv`

`tags`

`make_instrumental`

`control_option.gender`

`negative_tags`

`url`

`task` 与 `cover_clip_id`