# songforge — Agent 极简卡(默认只读这份) > 省 token:**进仓先读本文**。失败 / 改铁律 / 深挖再打开 [`AGENTS.md`](AGENTS.md)。 > **禁止**整文件粘贴 `ironlaw.py` / `qc_worker.py`;用 CLI 输出代替。 ## 进仓 30 秒 ```powershell cd .\scripts\doctor_all.ps1 .\.venv\Scripts\python.exe songforge.py --help ``` 本机路径:`config/local.toml`(缺则从 `.example` 复制)。算法:`config/default.toml`。 ## 交付 硬条件:`gen` 的 run_id + flac + `qc --baseline` → **PASS**。 `style_fam` / 全曲 `filler_ratio` 弱参考;**开曲衬词**(`intro_filler` / `recheck`)是硬门。 **不要**说「风格已验证」。 生歌结束后用此模板汇报(缺项写 `—`): ```text ## 生歌报告 - 结论:PASS | FAIL - 歌名 / 风格 / BPM / 设定时长:… - run_id:… - 音频路径:…(flac;可用 media info) - 歌词:路径 + check / align 密度 - QC:verdict;BPM;voice_nn;开曲衬词;filler_ratio(弱) - 产物:report.md;listen/(PASS 后);intro_check.json - 建议:听 listen/;FAIL 换 seed(--auto-retry)或改词 ``` 插件会在 run 目录自动写 `report.md`(`deliver_report`)。 ## 流水线(照这个跑) ```text doctor_all → target → [align] → check → gen [--auto-retry N] → recheck → qc --baseline → compare? ``` ```powershell .\.venv\Scripts\python.exe songforge.py target --style pop --bpm 104 --dur 180 # 密度不够时一键对齐(复用已有行,不造新词): .\.venv\Scripts\python.exe songforge.py align --style pop --lyrics-file input\lyrics\xxx.txt --bpm 104 --dur 180 .\.venv\Scripts\python.exe songforge.py check --style pop --title 歌名 --lyrics-file input\lyrics\xxx.txt --bpm 104 --dur 180 .\.venv\Scripts\python.exe songforge.py gen --style pop --title 歌名 --lyrics-file input\lyrics\xxx.txt --bpm 104 --dur 180 --auto-retry 2 .\.venv\Scripts\python.exe songforge.py recheck --run .\.venv\Scripts\python.exe songforge.py qc --run --baseline .\.venv\Scripts\python.exe songforge.py compare --runs , ``` 仓根入口:`.\.venv\Scripts\python.exe songforge.py <命令>` 嵌套 ComfyUI 时:`cd \user\default\workflows` 后 `python songforge\songforge.py …` ## 硬锁定 | 项 | 值 | |----|-----| | ckpt+LoRA | `ace_step_1.5_turbo_swl_fused` + `swl_voice_best_ep257`(0.5/0.5) | | 采样 | shift=5.5 / steps=28 / cfg=2.0 / temperature=0.68 | | 时长 | 150–200s;8 小节器乐前奏(CLI 注入) | | 衬音 | 禁止开曲衬词;默认 lean tags;禁点名 mm/ooh/嗯 | | tags | `prefer_lean_tags=true`;勿随意 `--full-tags` | ## 命令速查(Agent 常用) | 命令 | 用途 | |------|------| | `doctor` / `doctor_all.ps1` | 体检 | | `target` | 查字数窗口 | | `align` | 歌词音节对齐放行窗 | | `check` | 本地校验 | | `gen` | 生成;`--auto-retry N` 开曲 FAIL 换 seed;`--skip-recheck` 跳过轻检 | | `recheck` | 开曲轻检(前奏窗 ASR) | | `qc --baseline` | 全量验收(必带 baseline) | | `compare --runs a,b` | 多 run 对比 | | `media info\|convert\|clip` | 音频窄接口 | | `catalog` / `prune` | 索引 / 清 tmp | ## 目录(微内核) | 层 | 路径 | |----|------| | 内核 | `core/` `rules/` `cli/` `lyrics/` | | **插件** | **`plugins/`** ← 扩展写这里 | | 数据 | `input/lyrics/` `data/runs/` `config/` | | 文档 | **本文** → `AGENTS.md` → `docs/使用手册.md` → `plugins/README.md` | 内置/包式插件:`intro_guard`、`deliver_report`、`listen_pack`、`retry_on_intro_fail`。 钩子:`after_assemble` / `after_gen` / `after_qc`。详见 [`plugins/README.md`](plugins/README.md)。 ## 音频栈 经 `qc_python`(勿塞进轻量 `.venv`):**librosa、soundfile、torch、torchaudio、demucs、whisper**。 `media` / `qc` / `recheck` 都走这栈。 ## 遇事先问 | 情况 | 动作 | |------|------| | 无 local.toml / Comfy 不通 / 缺模型 | **问**路径与是否已启动 | | 风格/歌名/歌词来源不清 | **问** | | 想改采样/换模型/放宽 QC | **拒绝**,除非用户书面坚持 | | 需改仓库代码 | 先说明范围征求同意;建议 git 备份或新插件;问 commit/push/remote | | secrets / 推哪个 remote | **问**;勿提交 `.secrets`、`local.toml` | 可自行:`check` 密度失败 → `align` 或改词;漏 `--baseline` 补上;`prune --days 7`。 ## 样例 `input/lyrics/pop_灯还亮着.txt` + `--style pop --bpm 104 --dur 180`