Files
songforge/AGENTS_MIN.md
T
swlandCursor 6d79ab93a2
selftest / selftest (push) Canceled after 0s
Add align/recheck/compare, plugins, and refresh Agent docs.
Wire deliver_report/listen_pack/retry hooks; gen --auto-retry and intro light check; make AGENTS_MIN the up-to-date agent entry with full command map.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-10 13:03:44 +08:00

115 lines
4.5 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 输出代替。
## 进仓 30 秒
```powershell
cd <songforge仓根>
.\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 <run_id>
.\.venv\Scripts\python.exe songforge.py qc --run <run_id> --baseline
.\.venv\Scripts\python.exe songforge.py compare --runs <run_a>,<run_b>
```
仓根入口:`.\.venv\Scripts\python.exe songforge.py <命令>`
嵌套 ComfyUI 时:`cd <ComfyUI>\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`