From 1de26548582a14cc8891351e9b4073dcc3defbb7 Mon Sep 17 00:00:00 2001 From: swl Date: Sat, 10 Oct 2026 02:02:00 +0800 Subject: [PATCH] Document agent ask-first rules across AGENTS and manuals. Co-authored-by: Cursor --- .secrets.example | 16 ++-- AGENTS.md | 171 +++++++++++++++++++++++++++++--------- README.md | 42 ++++------ config/local.toml.example | 11 ++- docs/使用手册.md | 17 +++- 5 files changed, 183 insertions(+), 74 deletions(-) diff --git a/.secrets.example b/.secrets.example index ec548a0..df8fa92 100644 --- a/.secrets.example +++ b/.secrets.example @@ -1,6 +1,12 @@ -# 复制目录 .secrets/ 并放入本地 token 文件(勿提交)。 -# 例如: -# .secrets/github.token # 仅本地 push / gh API -# .secrets/testserver_gitea.token +# 本地密钥目录说明(复制思路即可,不要提交真实 token)。 # -# 文件内容为一行 token,无引号。 +# 创建目录 .secrets/(已在 .gitignore),例如: +# .secrets/github.token +# .secrets/gitea_music.token +# +# 每个文件一行 token,无引号。 +# +# Agent: +# - 永远不要把 token 写进 README / 对话记录 / commit +# - 需要 push 但找不到 token 或远程不明时,先问用户 +# - 推送前确认不要包含 .secrets/、config/local.toml、.venv/ diff --git a/AGENTS.md b/AGENTS.md index 5aeeae3..dd99124 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 \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 --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/` | | 外部 | `/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 diff --git a/README.md b/README.md index 091d32e..0cb9dc4 100644 --- a/README.md +++ b/README.md @@ -4,33 +4,33 @@ **独立项目**:clone 到任意目录,写好 `config/local.toml` 指向本机 ComfyUI,即可生成。 -| 文档 | 给谁 | -|------|------| -| [`AGENTS.md`](AGENTS.md) | Agent / 自动化 | -| [`docs/使用手册.md`](docs/使用手册.md) | 人类操作 | +| 文档 | 给谁 | 何时读 | +|------|------|--------| +| **[`AGENTS.md`](AGENTS.md)** | **Agent / Cursor / 自动化** | **做歌或改仓前必读**(含「遇事先问」) | +| [`docs/使用手册.md`](docs/使用手册.md) | 人类 | 命令与配置详解 | +| [`config/local.toml.example`](config/local.toml.example) | 所有人 | 第一次连本机 ComfyUI | + +> 给 Agent:读完 `AGENTS.md` 再动手。缺 `local.toml`、Comfy 没起、风格/歌名不清、想改模型或阈值时——**先问用户,不要猜**。 ## 换目录也能用(推荐) ```powershell -# 1) clone(GitHub 或 Gitea) cd D:\CodeFiles\ProProjects git clone https://git.nnrc.ren/swl/songforge.git +# 或:git clone https://github.com/lsuen/songforge.git cd songforge -# 2) CLI 环境(Python >= 3.11) .\scripts\setup_venv.ps1 - -# 3) 本机 ComfyUI 连接(只改这一份) copy config\local.toml.example config\local.toml -# 编辑: +# 编辑 local.toml: # [engine] server = "http://127.0.0.1:8188" # [paths] comfy_root / qc_python / music_dir -# 4) 先起 ComfyUI,再体检 +# 先启动本机 ComfyUI,再: .\.venv\Scripts\python.exe songforge.py doctor ``` -只要 ComfyUI 在跑、`local.toml` 里 `comfy_root` 指向正确安装根(含 `models/checkpoints` 与 LoRA),**不必**把本仓放进 ComfyUI 的 `user/default/workflows`。 +不必把本仓放进 ComfyUI 的 `user/default/workflows`。 ## 两个 Python 环境 @@ -44,9 +44,10 @@ copy config\local.toml.example config\local.toml | 文件 | 作用 | |------|------| | `config/default.toml` | 算法 / 相对路径(相对**本仓根**) | -| `config/local.toml` | 本机 Comfy 根、服务地址、QC Python(gitignore) | -| `workflows/template.json` | 包内 workflow 图(JSON,与配置分流) | +| `config/local.toml` | 本机 Comfy 根、服务地址、QC Python(**勿提交**) | +| `workflows/template.json` | workflow 图(JSON) | | `config/baseline/*.json` | QC 基线数据 | +| `.secrets/` | 远程 token(**勿提交**) | 优先级:`命令行 > SONGFORGE_* > local.toml > default.toml > DEFAULTS` @@ -59,7 +60,7 @@ copy config\local.toml.example config\local.toml .\.venv\Scripts\python.exe songforge.py qc --run gen-<时间戳> --baseline ``` -`qc` 必须带 `--baseline`。音频写到 ComfyUI `output/MyMusic/`(可用 `music_dir` 覆盖)。 +`qc` 必须带 `--baseline`。完整 Agent 规则与「何时发问」见 [`AGENTS.md`](AGENTS.md)。 ## 硬约束(摘要) @@ -70,21 +71,10 @@ copy config\local.toml.example config\local.toml | 时长 | 完整歌 150–200 秒 | | 前奏 | 8 小节器乐 hook;CLI 自动注入 | -## 目录 - -``` -songforge/ # clone 下来的仓根 = 包根 - config/default.toml - config/local.toml # 本机(勿提交) - data/runs/YYYY-MM-DD/ # gen 产物 - workflows/template.json - .venv/ -``` - ## 远程 -- GitHub: https://github.com/lsuen/songforge - Gitea: https://git.nnrc.ren/swl/songforge +- GitHub: https://github.com/lsuen/songforge ## License diff --git a/config/local.toml.example b/config/local.toml.example index 9049496..0c65e2e 100644 --- a/config/local.toml.example +++ b/config/local.toml.example @@ -1,15 +1,18 @@ -# 复制为 local.toml(已 gitignore)。clone 到任意目录后只改这里即可连本机 ComfyUI。 +# 复制为 local.toml(已 gitignore,勿提交)。 +# clone 到任意目录后只改这里即可连本机 ComfyUI。 # -# 例:D:\CodeFiles\ProProjects\songforge +# 例: # copy config\local.toml.example config\local.toml -# 填好下方路径 → .\.venv\Scripts\python.exe songforge.py doctor +# 填好下方 → 启动 ComfyUI → .\.venv\Scripts\python.exe songforge.py doctor +# +# Agent:若本文件不存在或路径不对,先问用户 comfy_root / server / qc_python,不要猜。 [engine] # ComfyUI 已启动的地址(本机默认 8188) server = "http://127.0.0.1:8188" [paths] -# ComfyUI 安装根(含 models/ checkpoints、loras、custom_nodes) +# ComfyUI 安装根(含 models/checkpoints、models/loras、custom_nodes) comfy_root = "D:/CodeFiles/Thinking/ComfyUI-MiniMaxH3" # QC 用的 Python(需 librosa/torch/demucs;可与 CLI .venv 分离) diff --git a/docs/使用手册.md b/docs/使用手册.md index e455bb2..a7b7ae1 100644 --- a/docs/使用手册.md +++ b/docs/使用手册.md @@ -1,6 +1,13 @@ # songforge 使用手册 -本手册讲「怎么跑」。参数铁律、踩坑与版本史见上级目录 [`生歌规则.md`](../../生歌规则.md)(唯一规范)。 +本手册讲「怎么跑」。 + +| 文档 | 用途 | +|------|------| +| [`../AGENTS.md`](../AGENTS.md) | **Agent 必读**:流水线、铁律、**遇事先问** | +| [`../README.md`](../README.md) | clone / 安装 / 远程 | +| [`../config/default.toml`](../config/default.toml) | 算法默认(本仓为准) | +| 若仍嵌套 ComfyUI:`生歌规则.md` | 踩坑长文;与 `default.toml` 冲突时以 TOML + AGENTS 为准 | 推荐:clone 到任意目录后在**仓根**执行(先配 `config/local.toml`): @@ -16,7 +23,13 @@ cd D:\CodeFiles\Thinking\ComfyUI-MiniMaxH3\user\default\workflows python songforge\songforge.py <命令> [选项] ``` -`local.toml` 填 `engine.server` + `paths.comfy_root` 即可连本机 ComfyUI。QC 音频栈用 `paths.qc_python`(常为 ComfyUI venv)。 +`local.toml` 填 `engine.server` + `paths.comfy_root` 即可连本机 ComfyUI。QC 用 `paths.qc_python`(常为 ComfyUI venv)。 + +### 给 Agent / 自动化 + +1. 先读 [`AGENTS.md`](../AGENTS.md),再跑命令。 +2. 没有 `local.toml`、Comfy 没起、风格/歌名/歌词来源不清 → **先问用户**,不要猜路径或改铁律。 +3. 交付以 `qc --baseline` PASS 为准;不要把 `style_fam` 说成「风格已验证」。 ---