Document agent ask-first rules across AGENTS and manuals.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
swl
2026-10-10 02:02:00 +08:00
co-authored by Cursor
parent cd2fb51575
commit 1de2654858
5 changed files with 183 additions and 74 deletions
+134 -37
View File
@@ -1,46 +1,109 @@
# songforge — Agent 生歌手册
# songforge — Agent 手册(必读)
> 远程 / channel Agent 读这份文件即可做歌。上下文不够时**重新打开本文件**。
> 人类规范见 ComfyUI 仓内 `生歌规则.md`(若仍嵌套部署);行为冲突以 `config/default.toml` 为准。
> **任何 Agent / 自动化:做歌或改本仓前先读完本文。** 上下文不够时**重新打开本文件**,不要凭记忆改参数。
>
> 人类操作细节见 [`docs/使用手册.md`](docs/使用手册.md)。算法默认见 [`config/default.toml`](config/default.toml)。
> 若仍嵌套在 ComfyUI 大仓,踩坑长文还可对照 `user/default/workflows/生歌规则.md`;**冲突时以本仓 `default.toml` + 本文为准**。
## 0. 交付物
---
1. 一次 `gen` 的 `run_id`
2. ComfyUI 产出的 flac
## 0. 你是谁、交什么
你是 songforge 流水线操作员。一次合格交付:
1. `gen` 的 `run_id`
2. ComfyUI 产出的 flac(路径在 manifest / catalog)
3. `qc --baseline` → **PASS**
`style_fam` 只是弱参考,不要当 PASS 条件。
`style_fam` / `style_conf` 是弱参考,**不要**当 PASS 条件,也**不要**对外说「风格已验证」。
## 1. 工作目录
---
**推荐(独立仓):** 在 clone 根目录执行:
## 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` |
| 要提交 `.secrets/`、`local.toml`、token | **拒绝**;问用户是否只推代码 |
| 仓库路径 / clone 位置不清 | 当前工作目录是哪?独立仓还是嵌套在 ComfyUI 里? |
| 两个远程(GitHub / Gitea)要推哪个 | 推哪个 remote?是否允许 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\setup_venv.ps1
copy config\local.toml.example config\local.toml
# 编辑 local.toml:engine.server / paths.comfy_root / qc_python / music_dir
# 用户需先启动本机 ComfyUI
.\.venv\Scripts\python.exe songforge.py doctor
```
入口(在**仓根**):
```powershell
cd D:\CodeFiles\ProProjects\songforge # 或任意 clone 路径
.\.venv\Scripts\python.exe songforge.py <命令>
```
**嵌套在 ComfyUI 时**也可:
若仍嵌套在 ComfyUI:
```powershell
cd <ComfyUI>\user\default\workflows
python songforge\songforge.py <命令>
```
禁止:手写 tags / 手写前奏 / 改 workflow JSON 调参 / 换 YuE2·Music3·aio / 放宽 QC 阈值。
**禁止:** 手写 tags / 手写前奏 / 改 workflow JSON 调参 / 换 YuE2·Music3·aio / 放宽 QC 阈值 / 把 token 写进文档或提交进 git。
## 2. 流水线
---
## 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 区间写歌词到 input/lyrics/xxx.txt(勿写 [intro] / tags)
.\.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
.\.venv\Scripts\python.exe songforge.py qc --run <run_id> --baseline
.\.venv\Scripts\python.exe songforge.py catalog --limit 20
```
- `check` 不过 → **只改歌词**
- `doctor` 服务不可达 → 先起 ComfyUI;检查 `config/local.toml` 的 `engine.server` / `paths.comfy_root`
- `qc` 必须带 `--baseline`
- `doctor` 服务不可达 → 请用户启动 ComfyUI;核对 `local.toml`
- `qc` 必须带 `--baseline`;`--run` 可用 run_id 或 `data/runs/...` 路径
- 索引:`catalog` / `catalog --rebuild`
## 3. 硬锁定
---
## 4. 硬锁定(不可谈判)
| 项 | 值 |
|----|-----|
@@ -48,52 +111,86 @@ doctor → target → 写歌词 → check → gen → qc --baseline
| 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 自动注入 |
| 前奏 | 8 小节器乐 hook,第一拍进鼓;CLI `assemble` 自动注入 |
算法 → `config/default.toml`;本机路径 → `config/local.toml`(gitignore)。
- 算法 / 相对路径 → `config/default.toml`(可提交)
- 本机绝对路径 → `config/local.toml`(gitignore,从 `.example` 复制)
- workflow 图 → `workflows/template.json`(JSON);**不要**用改图来改采样
```text
命令行 > SONGFORGE_* > local.toml > default.toml > DEFAULTS
```
CLI = 项目 `.venv`;QC = `local.toml` 的 `qc_python`。
| 环境 | 用途 |
|------|------|
| 本仓 `.venv` | CLI |
| `local.toml` → `qc_python` | QC(librosa/torch/demucs,可指向 ComfyUI venv) |
## 4. 目录(相对仓根)
---
## 5. 目录地图(相对仓根)
| 级别 | 路径 |
|------|------|
| 项目 | `input/lyrics/`、`config/baseline/`、`workflows/template.json` |
| 本机 | `config/local.toml` |
| 数据 | `data/runs/YYYY-MM-DD/`、`data/tmp/`、`index/catalog.jsonl`、`cache/` |
| 项目 | `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/` |
## 5. 写歌词
过程 JSON(`manifest.json` / `qc.json`)只出现在 `data/runs/...`,不要堆在仓根。
1. 先 `target`,音节进放行区间。
2. 不要写 `[intro]` / tags——`assemble` 会注入。
3. 段落用 `[verse]` `[chorus]` 等。
4. 英文低音吟唱用 `--chill-vocal`。
---
## 6. 失败速查
## 6. 写歌词
1. 先 `target`,正文音节落进放行区间(偏稀 → 模型用拖腔填空)。
2. **不要**写 `[intro]` / Instrumental 前奏 / tags。
3. 段落用 `[verse]` `[chorus]` 等英文结构标记。
4. 英文低音吟唱用 `--chill-vocal`(自动 sparse)。
---
## 7. 失败速查
| 现象 | 动作 |
|------|------|
| doctor FAIL 服务 | 启动 ComfyUI;核对 local.toml server |
| doctor FAIL 模型 | comfy_root 下是否有锁定 checkpoint/LoRA |
| check 密度失败 | 改歌词 |
| qc voice_nn=null | 漏了 `--baseline` |
| qc FAIL | 修歌/重 gen,不改阈值 |
| 无 local.toml | **问用户**路径后创建并填写 |
| doctor FAIL 服务 | 请用户启动 ComfyUI;核对 server |
| doctor FAIL 模型 | **问**模型是否在该 comfy_root |
| check 密度失败 | 改歌词到 target 区间 |
| gen 提交失败 | `selftest`;必要时 `--dry-run` |
| qc voice_nn=null | 补 `--baseline` |
| qc FAIL | 修歌/重 gen,**不**改阈值;反复失败则**问用户**听哪一版 |
| CLI 像坏了 | `selftest`;仍异常则**问用户**并贴 log |
```powershell
.\.venv\Scripts\python.exe songforge.py selftest
```
## 7. 验收清单
---
## 8. 验收清单
```text
[ ] local.toml 已填 comfy_root / server
[ ] 已读 AGENTS.md;不确定处已向用户提问
[ ] local.toml 有 comfy_root + server
[ ] doctor 全绿
[ ] check OK
[ ] gen 产出 flac,时长 150–200
[ ] qc --baseline → PASS
[ ] 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