前言¶
做短视频、播客或产品演示时，配乐往往卡在「找素材」和「版权」两步：现成 BGM 容易撞风格，自己写曲又缺工具链。把音乐生成接到对话式 Agent 里，理想状态是：用自然语言描述场景，由 Skill 按固定接口提交任务、轮询进度并返回可播放链接。
下面介绍 SkillHub 上的 天工音乐AI写歌（@user_e493aefd/xing-he-tiangong-music）。它把星河时光提供的音乐服务封装成通用 SKILL.md，Agent 只走 HTTP REST 调用 https://ai.growingth.com/api，不依赖 MCP 或网页抓取。安装后可在 Cursor 等支持 Skills 的客户端里，用对话完成写歌、配乐、翻唱与伴奏分离等流程。
这是什么¶
天工音乐AI写歌 是社区来源（community）的 design-media 类 Skill，发布者为 user_e493aefd，SkillHub 商店页标注版本 v1.1.2。
一句话定位：面向 Agent 的 AI 音乐创作助手，对接 Suno 系写歌与编曲能力，支持视频配乐、BGM、轻音乐、跑步舞蹈伴奏、翻唱、伴奏分离等；官方简介还说明可获得 商用版权证书，并可在天工音乐小程序、App 与网页 https://xhyue.com 多端使用且数据共享。
商店侧标签含 requires_api_key=true：业务接口需在 Skill 目录 config.json 中配置 MIAOYIN_API_TOKEN（微信扫码或备用登录页获取），不能匿名调用。
核心功能¶
以下能力均来自官方 Skill 文档（SKILL.md / api.md），按接口划分：
- 歌曲生成（
generateCustom）：根据歌词prompt、风格tags、可选标题与make_instrumental（纯音乐）提交任务，默认模型chirp-v5。 - 状态查询（
getMusic）：用taskId或歌曲id查排队、生成中、完成或失败；提交后 Agent 应按文档 每 10 秒 自动轮询，间隔不得短于 10 秒。 - 续写（
generateContinue）：从指定秒数continue_at延长已有曲目。 - 翻唱 / 改编（
generateCover）：在保留主旋律前提下改风格、歌词或音色参数。 - 合并续写（
concat）：将续写片段与父曲合并为完整版。 - 生成视频（
generateVideo）：为已完成歌曲生成视频版。 - WAV 导出（
makeWav）：转为无损 WAV（文档说明可能受版权策略限制）。 - 伴奏分轨（
generateStem）：two/twelve/dry等模式；文档明确 不支持提取人声，仅伴奏相关轨。
交互层规则（对使用 Skill 的 Agent 约束，也影响你作为用户的体验）：
- 有创作意图时，先 确认歌词与风格，再登录或提交；未登录时不默认弹出二维码，需用户发送「登录」后再走微信扫码或 备用登录。
- 生成完成后需改写对外展示的音频/封面域名（如
cdn1.suno.ai→file.growingth.com/song/sv4），并尽量同时给出可点击音频链接与 HTML 试听页。
安装与启用¶
1. 安装 SkillHub CLI（若尚未安装）¶
先检查是否已有 CLI：
command -v skillhub && skillhub --version
未安装时可按 SkillHub 官方说明执行（完整安装示例）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
2. 安装本 Skill¶
安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被客户端加载。
Cursor 常用路径为 ~/.cursor/skills/：
skillhub install xing-he-tiangong-music --namespace user_e493aefd --dir ~/.cursor/skills/
也可在对话中让 Agent 按 SkillHub 安装说明 安装坐标：
请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_e493aefd/xing-he-tiangong-music`。
其他客户端路径（来自同一安装文档，按需选用）：
- Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下.agents/skills/ - Windsurf：
~/.codeium/windsurf/skills/或.windsurf/skills/
安装完成后重启客户端或按产品要求重新加载 Skills。
3. 登录与配置¶
Skill 目录下 config.json 初始形态为：
{
"MIAOYIN_API_TOKEN": ""
}
登录成功后，将 API Key 写入 MIAOYIN_API_TOKEN。环境变量同名字段仅作兼容（config 为空时才读环境变量）。余额可在 https://xhyue.com/skill/connect 查看。
包内还提供 install.sh，默认目标为 OpenClaw 的 ~/.openclaw/workspace/skills/miaoyin-ai-music；若你使用 Cursor 等客户端，仍建议优先用上面的 skillhub install --dir 方式，避免装到未被识别的目录。
典型用法¶
对话驱动（推荐）¶
在已安装并加载 Skill 的 Agent 中，可直接用自然语言，文档给出的示例包括：
- 「帮我生成一首关于夏天的流行歌曲，要有钢琴和吉他」
- 「查一下刚才的歌好了吗」
- 「显示我最近的音乐列表」
- 「获取这首歌的歌词」
Agent 应按 SKILL.md 先做需求理解（整理风格与歌词并请你确认），再检查 config.json 是否已有密钥；未登录则引导试听与发送「登录」，登录成功后用已记住的方案提交生成。
底层 API 形态（便于核对行为）¶
所有业务请求 Base URL 固定为 https://ai.growingth.com/api，方法以 POST 为主，Header 使用 api-token（登录相关接口除外），体为 JSON，且多数接口形如：
{
"name": "操作名称",
"data": { }
}
提交生成示例（generateCustom）：
curl -X POST 'https://ai.growingth.com/api/song/proxy?name=generateCustom' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'api-token: YOUR_MIAOYIN_API_TOKEN' \
-d '{
"data": {
"prompt": "关于夏天的流行歌曲",
"tags": "Piano, Guitar",
"model": "chirp-v5",
"make_instrumental": false
}
}'
成功时返回 data[0].taskId，随后用 getMusic 查询（文档要求轮询间隔 ≥10 秒）：
curl -X POST 'https://ai.growingth.com/api/song/proxy?name=getMusic' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'api-token: YOUR_MIAOYIN_API_TOKEN' \
-d '{
"data": {
"ids": "c13975cda17449da2261"
}
}'
扫码登录会话（无需 api-token）：
curl -X POST 'https://ai.growingth.com/api/music/skill/connect/session' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{ "type": "skill" }'
返回 sid 与 qrcode 后，Agent 按文档每 5 秒轮询 GET https://ai.growingth.com/api/music/skill/connect/status?sid={sid}，成功则将 token 写入 config.json。
更完整的参数表、续写/翻唱/分轨等接口见 Skill 包内 api.md。
适用场景与注意¶
适合谁
- 需要在 Agent 工作流里快速出 BGM、轻音乐、短视频配乐，并希望与 xhyue.com 账号体系打通的团队或个人。
- 已接受 按量/额度计费（余额不足时文档指向 https://xhyue.com/skill/pay 与微信小程序「天工音乐AI写歌」）。
- 愿意让 Agent 严格按 Skill 文档轮询与展示进度，而不是手动反复问「好了吗」。
限制与注意
- 必须 API Key：
requires_api_key=true，未登录不能调业务接口。 - 查询频率：
getMusic自动轮询不得短于 10 秒，过于频繁可能被禁用。 - 分轨能力：
generateStem不能做人声分离；若需求是「只留人声」，文档要求 Agent 直接说明不支持。 - 版权与导出：命中版权保护时，高品质 WAV 等导出可能失败，需换原创内容重试。
- 版本与商店数据：以 SkillHub 页为准当前为 v1.1.2；截至抓取时商店显示评分 100000、下载约 1806 次（数据会随时间变化）。
- Agent 环境：若使用内嵌浏览器播放结果页，沙盒 CSP 需放行
https://file.growingth.com，否则音频可能被拦截（见 Skill 文档第 15 条）。
结尾¶
天工音乐AI写歌 把写歌、配乐、翻唱与伴奏处理收敛到一套 HTTP API 与详尽的 Agent 操作规程里，适合挂在 Cursor 等客户端的 Skills 目录，用对话完成从方案确认到成曲交付。安装与详情以 SkillHub 为准：
