AI Music Generation Skill

通过音述 MCP 为当前已认证用户提交异步 AI 音乐生成任务，并查询任务进度和作品结果。

用户可以用自然语言描述音乐需求。仅当用户明确要求生成、创作、制作或重新生成音乐时，Agent 才调用 generate_music。当用户只询问灵感、风格、歌词润色、提示词或模型选择时，只提供建议，不创建任务。

MCP Tools

Authentication and Access Control

• MCP 请求必须在 Authorization 请求头中携带当前用户有效的音述 API Key：Bearer <api_key>；认证失败时服务返回 HTTP 401 Unauthorized。
• 当鉴权失败（HTTP 401 Unauthorized）或 MCP 未配置 API Key 时，提示用户访问 音述开发者设置页 获取或配置 API Key，配置好后重新发起请求。
• 服务通过 API Key 所属用户识别当前用户。
• query_music_task 只能查询当前认证用户创建的任务。任务不存在或不属于当前用户时，工具返回“任务不存在”。
• 音乐生成可能受账户积分和生成频率限制。MCP 当前不提供积分余额或明细查询能力。

Recommended Agent Workflow

1. 确认生成意图：仅在用户明确要求生成音乐时调用 generate_music。不要为了未指定的可选参数阻塞或主动追问。
2. 处理关键冲突：当需求同时包含互相冲突的要求，例如“纯音乐”和“男声演唱”或“按歌词演唱”，先向用户澄清后再提交。
3. 提交任务：从用户描述中提取参数，调用 generate_music。
4. 保存任务 ID：从结果的 task_ids 中保存每个任务 ID；以 work_number 作为本次预计作品数量，不能假定固定数量。
5. 查询进度：提交后可立即对每个任务 ID 调用一次 query_music_task。若状态为 pending 或 running，告知用户任务仍在生成并保留 task ID 供后续查询。以合理间隔进行有限次数查询；不要无限轮询。
6. 处理状态：
   - pending、running：任务仍在生成，可稍后再次查询。
   - succeeded：读取 works 中的作品信息并返回给用户。若 works 为空，说明任务已完成但作品信息暂未同步。
   - failed：读取作品中的 error_reason（如果提供）并向用户说明生成失败；仅当用户明确要求时，才创建新的生成任务。
   - unknown：无法识别的状态，可稍后再次查询或告知用户暂无法确认状态。
7. 返回结果：展示标题、封面、可播放音频、时长和歌词（如有）。优先使用 stream_audio_url 作为播放链接，缺失时使用 audio_url。纯音乐或未返回歌词的作品可提示“当前歌曲暂无歌词”。

任务提交和查询均是独立调用；可以同时存在多个生成任务。当前 MCP 未提供取消任务的工具。

Tool: generate_music

提交异步音乐生成任务。唯一必填参数是非空的 prompt。

参数组合规则

• is_instrumental: true 时，不设置 vocal_gender；除非用户明确要求保留歌词文本，否则通常也不启用 is_custom 或传入 lyric。
• 用户提供歌词但没有明确要求按歌词演唱时，先将歌词视为创作素材；只有明确要求“使用这段歌词生成”或“按歌词演唱”时，设置 is_custom: true 和 lyric。
• phonetic_lyric 仅在用户提供拼音标注或明确要求发音控制时传入，不要自行生成。
• negative_tags 使用简洁、明确的排除项，不要复制完整 prompt。
• 当用户指定男声或女声时，仍在 prompt 中保留该偏好；vocal_gender 只是结构化偏好，不应成为唯一表达。

Prompt 编写建议

当用户描述较简略时，在不改变核心意图的前提下，将 prompt 组织为：

[曲风/年代感] + [情绪与能量] + [使用场景或叙事主题] + [主导乐器与编曲特征] + [节奏/速度偏好] + [演唱与制作特征]

示例：

• 用户：“做一首下雨天适合听的 Lo-fi”
• prompt：“温暖克制的 Lo-fi hip hop，雨天深夜独处氛围，柔和电钢琴、黑胶噪点与轻量鼓组，中慢速，舒缓、略带怀旧感。”

不要凭空补充用户明确未要求的故事、语言、人声性别或对特定在世艺术家的模仿。

用户意图到参数的映射

• 用户说“女声流行歌曲”：在 prompt 保留风格描述，并设置 vocal_gender: 2。
• 用户说“男声摇滚”：在 prompt 保留风格描述，并设置 vocal_gender: 1。
• 用户说“电影感背景音乐，无人声”：设置 is_instrumental: true，并在 prompt 保留电影感和场景描述。
• 用户提供完整歌词并希望按歌词演唱：设置 is_custom: true 和 lyric；可按需要补充 phonetic_lyric。
• 用户要求避开某种元素：将该限制放入 negative_tags，也可在 prompt 中保留自然语言约束。

成功返回

提交成功时，工具返回结构化数据：

{
  "status": "submitted",
  "task_ids": [12345],
  "work_number": 2,
  "next_step": "使用 query_music_task 并传入一个 task_id 查询进度和结果。"
}

• status：提交成功时为 submitted。
• task_ids：后续查询所需的任务 ID 列表。
• work_number：本次生成关联的作品数量，以该字段的实际返回为准。
• next_step：下一步操作提示。

提交失败与积分不足

提交失败时，工具仅返回通用错误：“音乐生成任务提交失败，请检查输入、积分和生成频率后重试”。MCP 不返回可供 Agent 可靠区分的细分原因。

当用户明确表示积分不足，或业务侧已明确告知积分不足时，Agent 应提示用户：

> 当前音述账号积分不足，无法创建音乐生成任务。请使用你自己的音述账号访问 积分充值页面 充值积分后，再重新发起生成请求。

不要自动重试或自动创建新版本；仅在用户明确要求重新生成、再次尝试或改变音乐方向时，才重新调用 generate_music。

Tool: query_music_task

查询一个任务的最新状态。查询可能触发供应商状态刷新并保存最新结果。

成功返回

{
  "task_id": 12345,
  "status": "succeeded",
  "works": [
    {
      "work_id": 67890,
      "title": "示例作品",
      "audio_url": "https://...",
      "stream_audio_url": "https://...",
      "cover_url": "https://...",
      "duration": 180,
      "lyric": "..."
    }
  ]
}

查询错误

• task_id 不是正整数：返回“task_id 必须是正整数”。
• 任务不存在或不属于当前用户：返回“任务不存在”。
• 仓储或生成服务查询失败：返回“任务查询失败，请稍后重试”。

Scope

本 Skill 仅定义音乐任务的提交与查询流程。以下能力不由当前 MCP 工具提供：

• 取消生成中的任务；
• 查询账户授权状态、积分余额、扣费明细或退款结果；
• 获取用户全部历史任务；
• 播放器、下载页、账号系统、积分系统或数据存储实现。