前言¶
做短視頻、播客或產品演示時，配樂往往卡在「找素材」和「版權」兩步：現成 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 爲準：
