Files
songforge/AGENTS_MIN.md
T
swlandCursor b1afe68f3c
selftest / selftest (push) Canceled after 0s
Fix opening filler via lean tags and intro QC gate.
Stop naming filler syllables in tags (they conditioned the model); default prefer_lean_tags; hard-fail intro_filler in QC; add plugins/ hook bus as thin microkernel extension point.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-10 12:49:25 +08:00

102 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/<name>.py` 或 `plugins/<name>/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`