Add align/recheck/compare, plugins, and refresh Agent docs.
selftest / selftest (push) Canceled after 0s
selftest / selftest (push) Canceled after 0s
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>
This commit is contained in:
+65
-52
@@ -1,42 +1,60 @@
|
||||
# songforge — Agent 极简卡(默认只读这份)
|
||||
|
||||
> 省 token:**先读本文**。失败 / 改铁律 / 深挖时再打开 [`AGENTS.md`](AGENTS.md)。
|
||||
> **禁止**把 `ironlaw.py` / `qc_worker.py` 整文件塞进上下文;用 CLI 输出代替。
|
||||
> 省 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` 只是弱参考;**不要**对外说「风格已验证」。
|
||||
`style_fam` / 全曲 `filler_ratio` 弱参考;**开曲衬词**(`intro_filler` / `recheck`)是硬门。
|
||||
**不要**说「风格已验证」。
|
||||
|
||||
生歌结束后,用下面模板向用户汇报(缺项写 `—`,FAIL 时停在「结论」并说明下一步):
|
||||
生歌结束后用此模板汇报(缺项写 `—`):
|
||||
|
||||
```text
|
||||
## 生歌报告
|
||||
- 结论:PASS | FAIL
|
||||
- 歌名 / 风格 / BPM / 设定时长:…
|
||||
- run_id:…
|
||||
- 音频路径:…(flac;可用 media info 补实测时长)
|
||||
- 歌词:路径 + check 密度结果(音节/区间)
|
||||
- QC:verdict;时长;实测 BPM(±18%);voice_nn;开曲衬词(intro_filler,硬门);filler_ratio(全曲弱参考)
|
||||
- 弱参考(勿当闸门):style_fam / style_conf;全曲 filler_ratio
|
||||
- 模型/采样:ckpt+LoRA(0.5/0.5);shift/steps/cfg/temperature(应与铁律一致)
|
||||
- 种子 / 备注:…(重跑或异常时)
|
||||
- 建议:听哪一段;是否重 gen / 只改词;是否 commit(若改过仓)
|
||||
- 音频路径:…(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 → 写歌词 → check → gen → qc --baseline
|
||||
doctor_all → target → [align] → check → gen [--auto-retry N] → recheck → qc --baseline → compare?
|
||||
```
|
||||
|
||||
仓根:
|
||||
|
||||
```powershell
|
||||
.\scripts\doctor_all.ps1
|
||||
.\.venv\Scripts\python.exe songforge.py <命令>
|
||||
.\.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 …`
|
||||
|
||||
## 硬锁定
|
||||
|
||||
| 项 | 值 |
|
||||
@@ -44,57 +62,52 @@ doctor_all → target → 写歌词 → check → gen → qc --baseline
|
||||
| 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 注入) |
|
||||
| 衬音 | **禁止开曲衬词**(嗯/呀/ooh…);默认 lean tags;QC 前奏窗衬词硬 FAIL |
|
||||
| tags | `prefer_lean_tags=true`;勿 `--full-tags`(易诱发开曲衬词);禁点名音节 |
|
||||
| 衬音 | 禁止开曲衬词;默认 lean tags;禁点名 mm/ooh/嗯 |
|
||||
| tags | `prefer_lean_tags=true`;勿随意 `--full-tags` |
|
||||
|
||||
本机路径:`config/local.toml`。算法:`config/default.toml`。
|
||||
## 命令速查(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/`(引擎/路径/workflow)、`rules/`、`cli/` |
|
||||
| 插件 | **`plugins/`**(钩子总线 + `builtin/` + 第三方) |
|
||||
| 数据 | `input/lyrics/`、`data/runs/`、`config/` |
|
||||
| 内核 | `core/` `rules/` `cli/` `lyrics/` |
|
||||
| **插件** | **`plugins/`** ← 扩展写这里 |
|
||||
| 数据 | `input/lyrics/` `data/runs/` `config/` |
|
||||
| 文档 | **本文** → `AGENTS.md` → `docs/使用手册.md` → `plugins/README.md` |
|
||||
|
||||
扩展优先写 `plugins/<name>.py` 或 `plugins/<name>/plugin.py`,少改内核。说明见 [`plugins/README.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)。
|
||||
|
||||
## 音频栈(librosa 等)
|
||||
## 音频栈
|
||||
|
||||
- **已用**(经 `qc_python`,勿塞进轻量 `.venv`):librosa、soundfile、torch、torchaudio、demucs、whisper
|
||||
- CLI:`media` / `qc` 走该栈;不要在 Agent 里手写探测脚本
|
||||
|
||||
## 音频窄接口(勿自写脚本)
|
||||
|
||||
```powershell
|
||||
.\.venv\Scripts\python.exe songforge.py media info --file path.flac
|
||||
.\.venv\Scripts\python.exe songforge.py media convert --file in.flac --to wav
|
||||
.\.venv\Scripts\python.exe songforge.py media clip --file in.flac --start 12 --dur 8 --out out.wav
|
||||
```
|
||||
|
||||
(走 `qc_python`,与 qc 同栈。)
|
||||
经 `qc_python`(勿塞进轻量 `.venv`):**librosa、soundfile、torch、torchaudio、demucs、whisper**。
|
||||
`media` / `qc` / `recheck` 都走这栈。
|
||||
|
||||
## 遇事先问
|
||||
|
||||
| 情况 | 动作 |
|
||||
|------|------|
|
||||
| 无 local.toml / Comfy 不通 / 缺模型 | **问用户**路径与是否已启动 |
|
||||
| 无 local.toml / Comfy 不通 / 缺模型 | **问**路径与是否已启动 |
|
||||
| 风格/歌名/歌词来源不清 | **问** |
|
||||
| 想改采样/换模型/放宽 QC | **拒绝**,除非用户书面坚持 |
|
||||
| secrets / push 哪个 remote | **问**;勿提交 `.secrets`、`local.toml` |
|
||||
| 需改仓库代码 | 先说明范围征求同意;建议 git 备份或新插件;问 commit/push/remote |
|
||||
| secrets / 推哪个 remote | **问**;勿提交 `.secrets`、`local.toml` |
|
||||
|
||||
## 改代码铁律(防意外)
|
||||
|
||||
发现现状不满足需求、**需要改仓库代码**时:
|
||||
|
||||
1. **先停手**,说明缺口与拟改范围,**征求用户明确同意**后再动文件。
|
||||
2. **建议用户选一种安全路径**(可并列问):
|
||||
- git 备份:新分支 / commit / stash / tag,再改;
|
||||
- 或**新写插件/旁路脚本**,少动核心铁律与默认配置。
|
||||
3. **问是否 commit、是否 push、推哪个 remote**;未获许可不得提交或推送。
|
||||
4. 用户同意收尾时再 `commit` +(若许可)`push`;勿擅自 `--force`、勿提交 secrets / `local.toml`。
|
||||
|
||||
可自行处理(不必问改代码):`check` 密度失败只改歌词;漏 `--baseline` 补上;`prune --days 7` 清 tmp。
|
||||
可自行:`check` 密度失败 → `align` 或改词;漏 `--baseline` 补上;`prune --days 7`。
|
||||
|
||||
## 样例
|
||||
|
||||
|
||||
Reference in New Issue
Block a user