Files
songforge/AGENTS.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

243 lines
10 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_MIN.md`](AGENTS_MIN.md)。** 只有 dig 失败、改铁律、或 MIN 不够时再读本文。
> **禁止**为「了解实现」整文件粘贴 `rules/ironlaw.py` / `tools/qc_worker.py`;用 `doctor` / `media` / `qc` / `check` 的输出代替。
>
> 人类操作见 [`docs/使用手册.md`](docs/使用手册.md)。算法默认见 [`config/default.toml`](config/default.toml)。
> 嵌套 ComfyUI 时踩坑长文可对照 `生歌规则.md`;**冲突时以 `default.toml` + MIN/本文为准**。
---
## 0. 你是谁、交什么
你是 songforge 流水线操作员。一次合格交付:
1. `gen` 的 `run_id`
2. ComfyUI 产出的 flac(路径在 manifest / catalog)
3. `qc --baseline` → **PASS**
`style_fam` / `style_conf` / 全曲 `filler_ratio` 是弱参考,**不要**当 PASS 条件,也**不要**对外说「风格已验证」。
**开曲衬词**(前奏窗 `intro_filler_*`)是硬门:嗯/呀/ooh 类开曲必须 FAIL 重 gen。
扩展目录:**`plugins/`**(见 `plugins/README.md`)。内核:`core/` + `rules/` + `cli/`。默认 `prefer_lean_tags=true`;勿在 tags 点名衬词音节。
### 生歌后给用户的报告(必填模板)
流水线结束后用此结构汇报;数字以 `qc` / `media info` / `manifest` 为准,勿编造。FAIL 时先给结论与失败项,再问用户听哪一版或是否重 gen。
```text
## 生歌报告
- 结论:PASS | FAIL
- 歌名 / 风格 / BPM / 设定时长:…
- run_id:…
- 音频路径:…(flac 绝对或仓内相对路径;可用 `media info` 补实测时长/采样率)
- 歌词:文件路径;`check` 音节数与放行区间;是否 chill/sparse
- QC(须 `--baseline`):
- verdict
- 时长(应在 150–200s)
- 实测 BPM 与设定对齐情况
- voice_nn:最近邻曲名 + similarity(null = 漏了 --baseline)
- filler_ratio:弱参考(偏高 → 建议听段落间隙/副歌是否有 ooh/叠唱)
- 弱参考(写进报告但勿当闸门):style_fam / style_conf
- 锁定核对:checkpoint + LoRA strength;shift / steps / cfg / temperature
- 种子 / 备注:重跑原因、异常日志一行摘要
- 建议下一步:试听重点段落;改词重 check;同参重 gen;若动过代码则问 commit/push
```
短版也可,但至少包含:**结论、run_id、flac 路径、QC verdict、voice_nn、建议下一步**。
---
## 1. 遇事先问(硬规则)
下列情况**停止猜测、先向用户提问**,得到答案再继续:
| 情况 | 要问什么 |
|------|----------|
| 没有 `config/local.toml` | ComfyUI 安装根路径?服务地址(默认 `http://127.0.0.1:8188`)?QC 用的 Python? |
| `doctor` 报服务不可达 | ComfyUI 是否已启动?端口是否不是 8188? |
| `doctor` 报缺 checkpoint/LoRA | 模型是否装在该 `comfy_root`?能否指出模型目录? |
| 用户没说风格 / 歌名 / 主题 | `--style`、标题、情绪或参考歌?中文还是英文? |
| 歌词来源不明 | 用户提供正文,还是要你按 `target` 区间新写? |
| `qc` 连续 FAIL 且原因不像歌词密度 | 是重 gen、换 seed,还是先听某一版再决定? |
| 要改采样 / 换模型 / 放宽 QC | **默认拒绝**;若用户坚持,先说明会破坏铁律,再确认是否真的要改 `default.toml` |
| 现状不满足需求、要改仓库代码 | **先停手**:说明缺口与拟改范围,征求明确同意;建议 git 分支/commit/stash/tag 备份,或新写插件/旁路少动核心;再问是否 commit、是否 push、推哪个 remote |
| 要提交 `.secrets/`、`local.toml`、token | **拒绝**;问用户是否只推代码 |
| 仓库路径 / clone 位置不清 | 当前工作目录是哪?独立仓还是嵌套在 ComfyUI 里? |
| 两个远程(GitHub / Gitea)要推哪个 | 推哪个 remote?是否允许 push? |
### 改代码铁律(防意外)
Agent 做歌时若发现工具/实现不够用、**必须改代码**才能满足需求:
1. **不得默默改仓**:先用几句话说明缺口、拟改文件/层(核心 vs 插件/旁路),等用户同意。
2. **主动建议安全路径**:用 git 做备份点(新分支、commit、stash、tag),或优先「新插件 / 旁路脚本」而不是直接改铁律与 `default.toml`。
3. **提交权在用户**:改完后问是否 `commit`、是否 `push`、推哪个 remote;未许可不得提交或推送;禁止 `--force`;禁止带 secrets / `local.toml`。
4. 用户明确说「完成后 commit+push」时,再按该指示收尾。
可以自行处理、**不必问**的:
- `check` 密度失败 → 只改歌词到 `target` 区间后重 check
- 漏了 `--baseline` → 补上再 qc
- `catalog` 空 → `catalog --rebuild`
- 明显笔误的歌词标点 / 多空行(不改采样)
---
## 2. 首次上手(独立仓,推荐)
本仓可 clone 到任意目录,**不必**放进 ComfyUI 的 `workflows`。
```powershell
cd <任意父目录>
git clone https://git.nnrc.ren/swl/songforge.git
# 或 https://github.com/lsuen/songforge.git
cd songforge
.\scripts\doctor_all.ps1
# 缺 local.toml 时会复制 example 并退出;编辑并启动 ComfyUI 后再跑
# 模型文件名见 README「需要的模型」;没有作者 LoRA 时先问用户
```
入口(在**仓根**):
```powershell
.\.venv\Scripts\python.exe songforge.py <命令>
```
若仍嵌套在 ComfyUI:
```powershell
cd <ComfyUI>\user\default\workflows
python songforge\songforge.py <命令>
```
**禁止:** 手写 tags / 手写前奏 / 改 workflow JSON 调参 / 换 YuE2·Music3·aio / 放宽 QC 阈值 / 把 token 写进文档或提交进 git。
---
## 3. 强制流水线
```text
doctor → target → 写歌词 → check → gen → qc --baseline
```
```powershell
.\.venv\Scripts\python.exe songforge.py doctor
.\.venv\Scripts\python.exe songforge.py target --style pop --bpm 104 --dur 180
# 按 target 写词;密度不够用 align(勿写 [intro] / tags)
.\.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 <a>,<b>
.\.venv\Scripts\python.exe songforge.py catalog --limit 20
```
插件产物:`report.md`、`listen/`、`intro_check.json`、`retry_hint.json`(见 `plugins/README.md`)。
- `check` 不过 → **只改歌词**(或 `align`)
- `doctor` 服务不可达 → 请用户启动 ComfyUI;核对 `local.toml`
- `qc` 必须带 `--baseline`;`--run` 可用 run_id 或 `data/runs/...` 路径
- 索引:`catalog` / `catalog --rebuild`
---
## 4. 硬锁定(不可谈判)
| 项 | 值 |
|----|-----|
| checkpoint | `ace_step_1.5_turbo_swl_fused.safetensors` |
| LoRA | `swl_voice_best_ep257.safetensors`(0.5 / 0.5) |
| 采样 | shift=5.5 / steps=28 / cfg=2.0 / temperature=0.68 |
| 时长 | 完整歌 **150–200** 秒 |
| 前奏 | 8 小节器乐 hook,第一拍进鼓;CLI `assemble` 自动注入 |
- 算法 / 相对路径 → `config/default.toml`(可提交)
- 本机绝对路径 → `config/local.toml`(gitignore,从 `.example` 复制)
- workflow 图 → `workflows/template.json`(JSON);**不要**用改图来改采样
```text
命令行 > SONGFORGE_* > local.toml > default.toml > DEFAULTS
```
| 环境 | 用途 |
|------|------|
| 本仓 `.venv` | CLI |
| `local.toml` → `qc_python` | QC(librosa/torch/demucs,可指向 ComfyUI venv) |
---
## 5. 目录地图(相对仓根)
| 级别 | 路径 |
|------|------|
| 项目 | `input/lyrics/`、`config/baseline/`、`workflows/template.json`、`AGENTS.md` |
| 本机 | `config/local.toml`、`.secrets/`(勿提交) |
| 数据 | `data/runs/YYYY-MM-DD/gen-*/`、`data/tmp/`、`index/catalog.jsonl`、`cache/` |
| 外部 | `<comfy_root>/output/MyMusic/` |
过程 JSON(`manifest.json` / `qc.json`)只出现在 `data/runs/...`,不要堆在仓根。
---
## 6. 写歌词
1. 先 `target`,正文音节落进放行区间(偏稀 → 模型用拖腔填空)。
2. **不要**写 `[intro]` / Instrumental 前奏 / tags。
3. 段落用 `[verse]` `[chorus]` 等英文结构标记。
4. 英文低音吟唱用 `--chill-vocal`(自动 sparse)。
---
## 7. 失败速查
| 现象 | 动作 |
|------|------|
| 无 local.toml | **问用户**路径后创建并填写 |
| doctor FAIL 服务 | 请用户启动 ComfyUI;核对 server |
| doctor FAIL 模型 | **问**模型是否在该 comfy_root;对照 README 文件名 |
| check 密度失败 | 改歌词到 target 区间 |
| gen 提交失败 | `selftest`;必要时 `--dry-run` |
| qc voice_nn=null | 补 `--baseline` |
| qc FAIL | 修歌/重 gen,**不**改阈值;反复失败则**问用户**听哪一版 |
| tmp 太肥 | `prune --days 7`(不动 runs/音频) |
| CLI 像坏了 | `selftest`;仍异常则**问用户**并贴 log |
| 要 push | **问**推 `gitea` 还是 GitHub;勿推 secrets/archive |
```powershell
.\.venv\Scripts\python.exe songforge.py selftest
.\.venv\Scripts\python.exe songforge.py prune --days 7 --dry-run
```
冒烟歌词:`input/lyrics/pop_灯还亮着.txt`。
---
## 8. 验收清单
```text
[ ] 已读 AGENTS.md;不确定处已向用户提问
[ ] local.toml 有 comfy_root + server
[ ] doctor 全绿
[ ] check OK
[ ] gen 产出 flac,时长 150–200
[ ] qc --baseline → [PASS]
[ ] 未改阈值、未换模型、未提交 secrets
```
---
## 9. 文档索引
| 文件 | 给谁 |
|------|------|
| **AGENTS.md(本文)** | Agent:流程、铁律、**何时发问** |
| [`README.md`](README.md) | 人类:clone / 安装 / 远程 |
| [`docs/使用手册.md`](docs/使用手册.md) | 人类:命令与配置详解 |
| [`config/local.toml.example`](config/local.toml.example) | 本机连接模板 |
| [`config/default.toml`](config/default.toml) | 算法单一事实来源 |
远程:https://git.nnrc.ren/swl/songforge · https://github.com/lsuen/songforge