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

9.8 KiB
Raw Blame History

songforge — Agent 手册(全文)

省 token:默认先读 AGENTS_MIN.md。 只有 dig 失败、改铁律、或 MIN 不够时再读本文。 禁止为「了解实现」整文件粘贴 rules/ironlaw.py / tools/qc_worker.py;用 doctor / media / qc / check 的输出代替。

人类操作见 docs/使用手册.md。算法默认见 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。

## 生歌报告
- 结论: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。

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 时先问用户

入口(在仓根):

.\.venv\Scripts\python.exe songforge.py <命令>

若仍嵌套在 ComfyUI:

cd <ComfyUI>\user\default\workflows
python songforge\songforge.py <命令>

禁止: 手写 tags / 手写前奏 / 改 workflow JSON 调参 / 换 YuE2·Music3·aio / 放宽 QC 阈值 / 把 token 写进文档或提交进 git。


3. 强制流水线

doctor → target → 写歌词 → check → gen → qc --baseline
.\.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;核对 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);不要用改图来改采样
命令行 > 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
.\.venv\Scripts\python.exe songforge.py selftest
.\.venv\Scripts\python.exe songforge.py prune --days 7 --dry-run

冒烟歌词:input/lyrics/pop_灯还亮着.txt。


8. 验收清单

[ ] 已读 AGENTS.md;不确定处已向用户提问
[ ] local.toml 有 comfy_root + server
[ ] doctor 全绿
[ ] check OK
[ ] gen 产出 flac,时长 150–200
[ ] qc --baseline → [PASS]
[ ] 未改阈值、未换模型、未提交 secrets

9. 文档索引

文件 给谁
AGENTS.md(本文) Agent:流程、铁律、何时发问
README.md 人类:clone / 安装 / 远程
docs/使用手册.md 人类:命令与配置详解
config/local.toml.example 本机连接模板
config/default.toml 算法单一事实来源

远程:https://git.nnrc.ren/swl/songforge · https://github.com/lsuen/songforge