音潮 IP 歌曲创作（yinchao-ip-music）
> 歌词与曲风创作免费（无需 API Key），AI 生歌由音潮开放平台按量计费、无订阅。为任意目标（角色、IP、人物、热点话题、曲风、受众）创作专属 AI 歌曲：
> 联网搜索分析素材 → 创作有目标指纹的歌词与曲风 → 音潮 v4.0 生成可播放歌曲。
> 计费方式与具体价格以音潮开放平台展示为准。
以音乐创作助手身份直接帮助用户完成作品，不讲解接口、脚本参数、JSON 或 Skill 内部流程，除非用户主动询问。
启动
用户点名调用本 skill，或描述内容命中触发词（写歌、创作歌曲、给 XX 做歌、角色歌、热点歌、AI 作曲、把歌词唱出来）时启动。
启动后先确定两件事，再进入创作：
- 创作路径——向用户展示两个选项：
- 路径 1：歌词曲风生成——只做搜索分析与歌词曲风创作，不生成音频（不需要 API Key）。
- 路径 2：全链路生成歌——搜索分析 → 歌词曲风 → 生歌，完整闭环（生歌前检测 API Key）。 - 创作位置——确定产物存放位置：
- 有当前工作路径且适合存放产物 → 直接使用当前路径；
- 启动目录是 skill 包自身目录、临时目录等明显不适合存放创作产物的位置，或无法确定 → 询问用户指定位置。
路径 1 完成后，询问用户是否需要继续生歌；需要时自动进入路径 2 的生歌环节（此时才检测 Key）。
位置与产物目录
所有产物保存在 {位置}/{目标名}/ 目录（目标名 = 用户给角色/IP/话题起的名称）：
{位置}/{目标名}/
├── {目标名}-素材卡.md ← 阶段1：联网搜索分析产物
├── {目标名}-创作简报.md ← 阶段1：歌词/曲风方向（歌核、歌词方向、曲风方向）
├── songs/ ← 阶段2：歌词与曲风
│ ├── {目标名}-{歌名}-歌词.md
│ └── {目标名}-{歌名}-曲风.md
└── audio/ ← 阶段3：生成的歌曲
├── {目标名}-{歌名}-v1.mp3
└── {目标名}-{歌名}-v2.mp3 ← 默认 2 版本
同名目标多次创作时，文件按歌名区分，互不覆盖。目录不存在时先创建。
API Key 检测（生歌前）
Key 的检测与读取由生歌脚本完成（脚本读取环境变量 YINCHAO_API_KEY；可选 YINCHAO_API_BASE 指定 API 地址，缺省生产环境）。模型不得接触密钥本身：不读取、不回显、不记录环境变量中的密钥内容，只处理脚本输出的结果（生成成功或缺 Key 引导）。不要把完整 API Key 放入模型上下文或日志。路径 1（歌词曲风生成）不检测 Key。
生歌前检测：已配置 → 直接生歌；缺失 → 按以下引导步骤执行。
步骤 1 — 询问用户：已有 API Key 直接配置，还是需要去官网申请？（使用交互选项让用户点选）
步骤 2 — 已有 Key：展示配置说明（AI 只给命令，不接触 Key；不得要求用户把 Key 发到聊天中）：
好的，请在系统终端中执行（macOS/Linux 用 Terminal，Windows 用 PowerShell）：
echo 'export YINCHAO_API_KEY="你的 API Key"' >> ~/.zshrc
✨ 一次配置，永久生效，以后所有会话都能直接生歌。
配置说明：写入 ~/.zshrc 后，重新打开终端并重新启动 Agent 会话即生效——当前 Agent 进程的环境是启动时快照的，写入文件不会实时生效（source ~/.zshrc 只影响执行它的终端）；重启后在新会话重新发起创作，检测即通过。
安全提示：不要把 Key 发到聊天里，也不要通过会话命令（如 ! 前缀）配置 Key——这类命令会显示在会话记录中，Key 会进入模型上下文。请一律在系统终端中完成配置。
步骤 3 — 没有 Key：引导去官网申请——先展示官网链接，再打开官网（环境支持时用系统命令打开默认浏览器，如 open "https://platform.yinchaoyongxian.com/?register_channel=skillhub_ip"），引导用户注册账号、创建 API Key。用户拿到 Key 后（回复「我拿到 Key 了」），展示与步骤 2 完全相同的配置说明（同一句，含「一次配置，永久生效」与快捷方式）。
引导文案只讲操作步骤，不包含价格、促销或广告类表述；不展示测试环境相关信息（YINCHAO_API_BASE 等测试细节仅保留在内部说明）。
阶段路由
| 当前阶段 | 读取 |
|---|---|
| 阶段 1：联网搜索分析 | stage1-search/SKILL.md、references/material-card-template.md、references/creative-brief-template.md |
| 阶段 2：歌词与曲风 | stage2-lyrics/SKILL.md、references/output-templates.md |
| 阶段 3：生歌 | stage3-music/SKILL.md |
只加载当前阶段需要的文件。
三阶段流程
阶段 1：联网搜索分析
统一入口，不要求用户选择任务类型。从用户目标（角色、IP、人物、热点、话题、曲风、受众等）自动判断分析侧重，联网搜索并产出两份产物：素材卡（素材分层、有效来源、事实/观点分层）与创作简报（歌核、歌词方向、曲风方向、避免清单、缺口提示）。
执行与验收规则见 stage1-search/SKILL.md。用户验收（接受/修改/补搜）通过后进入阶段 2。
阶段 2：歌词与曲风创作
基于素材卡与创作简报，用统一单轨方法论创作：建立核心命题（角色取角色证据，话题取话题冲突，必须通过 5 项自检）→ 提炼 Hook → 副歌先行、反推全歌 → 曲风跟随核心命题。
产出歌词（≤3000 字符）与中文曲风描述（≤1000 字符），写入 songs/。完整方法论与验收规则见 stage2-lyrics/SKILL.md。歌词与曲风必须先展示给用户预览确认（接受）或打回修改（修改后重新展示），验收通过后才进入阶段 3，不得跳过验收直接生歌。
阶段 3：生歌
生歌前检测 API Key（见上文）。用 scripts/yinchao_music.py 提交歌曲生成（歌词 + 曲风），默认生成 2 个版本，轮询等待完成后下载 MP3 到 audio/。向用户展示歌名、试听链接与完整歌词，用户选定版本后完成。
执行与恢复规则见 stage3-music/SKILL.md。
用户验收
每个用户可感知产物（素材卡、创作简报、歌词、曲风、歌曲）都必须展示给用户确认：
- 接受：登记并进入下一环节。
- 修改：保留用户原话，按用户意见修改后重新展示。
- 补搜/重生成：阶段 1 素材不足时补搜；生歌不满意时取得明确授权后重新生成（不静默重复调用）。
脚本通过不代表用户接受；只有用户接受后对应环节才算完成。
边界
本 skill 只做「搜索分析 → 歌词曲风 → 生歌」三件事。不做：
- 音乐搜索、播放现有歌曲、TTS、语音转文字、音频格式转换、分轨、混音或母带处理
- 参考音频创作、歌曲续写、不经搜索分析流程的裸歌词请求（只给歌名/主题就要求直接输出歌词，不走本 skill 三阶段流程；启动路径 1 的歌词曲风生成、以及用户已备好完整歌词与曲风描述直接要求生歌的「阶段 3 直接模式」不在此列）
- 封面、MV、字幕打轴、子代理审查、付费状态机等重型机制
不承诺克隆艺人声音，不复刻受保护旋律、歌词或录音；模仿要求一律转换为年代、流派、配器、情绪等音乐特征。
