rap-clone-workflow 总控（对标说唱全链路编排）
职责：按顺序调度 5 个子技能 + 守 6 道关卡。所有执行细节在各子技能内，本文件只管编排、契约、关卡。
状态：v1。 各环节单独已验证（下载 / DNA 拆解 / 对拍 / TTS），全链路串联请逐关卡人工验收后再放开自动执行。
编排链
S0 输入清单（本技能负责，缺则追问）
↓
S1 rap-clone-s1-download → 01_download/{source_video.mp4, audio.wav}
↓ G1 视频完整
S2 rap-clone-s2-dna → 02_analysis/{dna_card.json, vocals.wav, clone_sample.wav}
↓ G2 歌词人工校对 + DNA 卡确认
S3 rap-clone-s3-lyrics → 03_lyrics/lyrics_final.json（frozen=true）
↓ G3 用户定稿冻结
S4 rap-clone-s4-tts → 04_tts/{dry_vocal.wav, tts_report.json}
↓ G4 音色"像" / G5 失配<2%
S5 rap-beat-align → 05_align/{mix, 纯人声, click, 验证图, report.json}
↓ G6 click 耳朵终审
S6 交付（本技能负责）：报全部文件绝对路径 + 交付清单
S0 输入清单
- 对标视频链接（抖音/B站/小红书等）；
- 仿写要求：主题/产品/卖点 + 口吻 + 押韵偏好 + 想保留哪些原词梗；
- 伴奏来源：默认用对标视频分离的伴奏（S2 的 no_vocals.wav）；用户自备则给路径；
- 项目代号 slug（英文短横线）。
目录约定
每个项目一个独立目录（<workspace> 换成你的工作区根目录）：
<workspace>/rap_clone/<slug>/
01_download/ source_video.mp4 / audio.wav / source_info.txt
02_analysis/ demucs输出 / clone_sample.wav / dna_card.json / dna_card.md
03_lyrics/ lyrics_draft.md / lyrics_final.json
04_tts/ dry_vocal.wav / tts_report.json
05_align/ mix / 纯人声 / check_click / 验证图 / align_report.json
三份契约文件（阶段间只认文件，不认口头）
| 契约文件 | 产出 | 消费 | 关键字段 |
|---|---|---|---|
02_analysis/dna_card.json |
S2 | S3 / S4 / S5 | tempo_bpm / beat_phase / beat_period / gap_beats / phrase_pattern / n_phrases / first_phrase_beat / lyrics / clone_sample / voice_notes |
03_lyrics/lyrics_final.json |
S3 | S4 / S5 | frozen=true 才可进 S4；phrases[{idx,chars,text}]（字数=phrase_pattern 逐项对应） |
04_tts/tts_report.json |
S4 | S5 | voice_id / speech_rate / measured_bpm / dna_bpm / mismatch_pct / iterations |
契约字段缺失 = 该阶段打回上游，不允许"先跑着后面补"。
验收关卡汇总
| 关卡 | 阶段 | 内容 | 通过标准 |
|---|---|---|---|
| G1 | S1 | 视频 | 完整可播、时长与平台一致 |
| G2 | S2 | DNA 卡 | 歌词人工校对 + 密度读数确认 + 克隆素材试听 |
| G3 | S3 | 歌词 | 字数模式程序核验 + 用户定稿冻结 |
| G4 | S4 | 音色 | 试听"像不像" |
| G5 | S4 | TTS | 试听无读错 + 速度失配 <2%（或明示接受 S5 拉伸） |
| G6 | S5 | 对拍 | click 耳朵终审 + median ≤10ms |
总控铁律
- 顺序不可跳：DNA 卡未确认不写词；歌词未冻结不合成；TTS 失配 >2% 且用户未接受拉伸方案不进 S5。
- 每阶段完成立即向用户报文件绝对路径，等关卡确认再进下一阶段。
- 画面用户手动剪辑——本工作流交付到音频为止。
- 单站故障不跨站修补：某站验收不过，回到该站的技能重做，不允许下游"顺手改"上游产物。
依赖速查
- 子技能：
rap-clone-s1-download/rap-clone-s2-dna/rap-clone-s3-lyrics/rap-clone-s4-tts/rap-beat-align - 对拍代码：本仓库
scripts/（measure_tempo.py 测速 / global_tempo_fix.py 全局校正 / align_phrases.py 对齐终稿 / verify_alignment.py 复测 / diag_silence.py 阈值诊断） - TTS：火山引擎豆包语音 API，调用封装
scripts/tts.py（Key 走环境变量DOUBAO_SPEECH_API_KEY） - 音色复刻：火山引擎控制台人工提交样本（
scripts/tts.py亦含clone_voice()API 尝试，以控制台文档为准） - demucs / faster-whisper / RubberBand 4.0.0（安装见 README）
📦 包内资源索引（SkillHub 发布版，装好后直接可用）
本技能以自包含包发布，编排全链路所需引擎与素材都在本包内：
skills/— 5 个子技能的 SKILL.md（S1 下载 / S2 节奏DNA / S3 仿写 / S4 TTS / S5 对拍）。它们位于本包子目录，不与主 skills 目录并列；编排各阶段时直接读取本包内对应 SKILL.md 文件。presets/wannengjiao.json— 万能胶 120BPM 预设卡：拍相位 0.188 / 首句第 5 拍进 / [2,2,4] 落点密度 / 混音比例全套内置，对拍零调试。- 伴奏与示例音频（平台限制不随包分发，去 GitHub 下载）：
assets/beats/wannengjiao_120bpm.flac（120 BPM，前 64 秒）与examples/banxiyan/完整示例素材包（原始 TTS 人声 / 对拍干声成品 / FX9 后期成品）。下载地址：https://github.com/scrofied/rap-clone-skill —— 下载后放回本包同名目录即可完全复现。伴奏版权归原作，仅供学习对齐演示，发布作品前自行取得授权，见assets/beats/NOTICE.md。 examples/banxiyan/lyrics.txt— 真实案例歌词契约（36 短语 [3,3,7]×12）+examples/banxiyan/README.md复现说明与实测数据。test/lyrics_demo.txt— 歌词契约格式示例（逗号=3字短句、句号=7字长句）。- 环境依赖：
pip install -r requirements.txt；RubberBand CLI（下载地址见 README.md 安装节）；ffmpeg；可选 demucs / faster-whisper。
S5 一键对拍（推荐入口）（伴奏需先从 GitHub 下载放入 assets/beats/，或用 --acc 指定你自己的伴奏文件）：
python scripts/align_phrases.py --preset wannengjiao \
--vocal <人声文件> --lyrics-text <歌词文本> --out-dir 05_align/
产出 5 件：mix.wav/.mp3（成品）/ vocal_aligned_phrases.wav（对齐人声）/ check_click.wav（节拍器验收）/ 验证图 / align_report.json（落点表，报短语号可单点重排）。
