# songforge — Agent 极简卡(默认只读这份) > 省 token:**先读本文**。失败 / 改铁律 / 深挖时再打开 [`AGENTS.md`](AGENTS.md)。 > **禁止**把 `ironlaw.py` / `qc_worker.py` 整文件塞进上下文;用 CLI 输出代替。 ## 交付 硬条件:`gen` 的 run_id + flac + `qc --baseline` → **PASS**。 `style_fam` / `filler_ratio` 只是弱参考;**不要**对外说「风格已验证」。 生歌结束后,用下面模板向用户汇报(缺项写 `—`,FAIL 时停在「结论」并说明下一步): ```text ## 生歌报告 - 结论:PASS | FAIL - 歌名 / 风格 / BPM / 设定时长:… - run_id:… - 音频路径:…(flac;可用 media info 补实测时长) - 歌词:路径 + check 密度结果(音节/区间) - QC:verdict;时长;实测 BPM(±18%);voice_nn;开曲衬词(intro_filler,硬门);filler_ratio(全曲弱参考) - 弱参考(勿当闸门):style_fam / style_conf;全曲 filler_ratio - 模型/采样:ckpt+LoRA(0.5/0.5);shift/steps/cfg/temperature(应与铁律一致) - 种子 / 备注:…(重跑或异常时) - 建议:听哪一段;是否重 gen / 只改词;是否 commit(若改过仓) ``` ## 流水线 ```text doctor_all → target → 写歌词 → check → gen → qc --baseline ``` 仓根: ```powershell .\scripts\doctor_all.ps1 .\.venv\Scripts\python.exe 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 注入) | | 衬音 | **禁止开曲衬词**(嗯/呀/ooh…);默认 lean tags;QC 前奏窗衬词硬 FAIL | | tags | `prefer_lean_tags=true`;勿 `--full-tags`(易诱发开曲衬词);禁点名音节 | 本机路径:`config/local.toml`。算法:`config/default.toml`。 ## 微内核目录 | 层 | 路径 | |----|------| | 内核 | `core/`(引擎/路径/workflow)、`rules/`、`cli/` | | 插件 | **`plugins/`**(钩子总线 + `builtin/` + 第三方) | | 数据 | `input/lyrics/`、`data/runs/`、`config/` | 扩展优先写 `plugins/.py` 或 `plugins//plugin.py`,少改内核。说明见 [`plugins/README.md`](plugins/README.md)。 ## 音频栈(librosa 等) - **已用**(经 `qc_python`,勿塞进轻量 `.venv`):librosa、soundfile、torch、torchaudio、demucs、whisper - CLI:`media` / `qc` 走该栈;不要在 Agent 里手写探测脚本 ## 音频窄接口(勿自写脚本) ```powershell .\.venv\Scripts\python.exe songforge.py media info --file path.flac .\.venv\Scripts\python.exe songforge.py media convert --file in.flac --to wav .\.venv\Scripts\python.exe songforge.py media clip --file in.flac --start 12 --dur 8 --out out.wav ``` (走 `qc_python`,与 qc 同栈。) ## 遇事先问 | 情况 | 动作 | |------|------| | 无 local.toml / Comfy 不通 / 缺模型 | **问用户**路径与是否已启动 | | 风格/歌名/歌词来源不清 | **问** | | 想改采样/换模型/放宽 QC | **拒绝**,除非用户书面坚持 | | secrets / push 哪个 remote | **问**;勿提交 `.secrets`、`local.toml` | ## 改代码铁律(防意外) 发现现状不满足需求、**需要改仓库代码**时: 1. **先停手**,说明缺口与拟改范围,**征求用户明确同意**后再动文件。 2. **建议用户选一种安全路径**(可并列问): - git 备份:新分支 / commit / stash / tag,再改; - 或**新写插件/旁路脚本**,少动核心铁律与默认配置。 3. **问是否 commit、是否 push、推哪个 remote**;未获许可不得提交或推送。 4. 用户同意收尾时再 `commit` +(若许可)`push`;勿擅自 `--force`、勿提交 secrets / `local.toml`。 可自行处理(不必问改代码):`check` 密度失败只改歌词;漏 `--baseline` 补上;`prune --days 7` 清 tmp。 ## 样例 `input/lyrics/pop_灯还亮着.txt` + `--style pop --bpm 104 --dur 180`