Make the documentation system navigable, sourced, and release-ready

Turn the docs set into a layered documentation portal with navigation, source tracing, and reusable governance templates so the project can scale beyond ad hoc notes.

Constraint: Industrialization requires documentation that supports decisions, traceability, and release discipline
Rejected: Keep docs as isolated topical files without navigation or templates | would slow onboarding and weaken release governance
Confidence: high
Scope-risk: narrow
Directive: Keep future docs in the executive-summary -> diagram -> table -> text -> appendix pattern with explicit Sources sections
Tested: structural checks for core docs and templates; source-section checks; docs file-presence checks; service /config and /health smoke checks from earlier stage remain valid
Not-tested: rendered markdown visuals in a browser; external publishing pipeline

@@ -8,25 +8,36 @@ from pydantic import BaseModel
 from src.engines.chromaprint_matcher import ChromaprintMatcher
 from src.engines.ecapa_embedder import ECAPAEmbedder
 from src.engines.hybrid_engine import HybridEngine
+from src.service.settings import ServiceSettings
 
 
 class RecognizeRequest(BaseModel):
     query_path: str
-    data_dir: str = "data/synthetic_v2"
-    model_path: str = "data/models_v3/best_model.pt"
-    index_prefix: str = "data/index_v3/reference"
+    data_dir: Optional[str] = None
+    model_path: Optional[str] = None
+    index_prefix: Optional[str] = None
     top_n: int = 5
-    device: str = "cpu"
+    device: Optional[str] = None
 
 
 class BuildIndexRequest(BaseModel):
-    data_dir: str
-    model_path: str
+    data_dir: Optional[str] = None
+    model_path: Optional[str] = None
     output_dir: str
-    device: str = "cpu"
+    device: Optional[str] = None
 
 
-app = FastAPI(title="ACR Service", version="0.1.0")
+app = FastAPI(title="ACR Service", version="0.2.0")
+settings = ServiceSettings()
+
+
+def _resolve(req_data_dir=None, req_model_path=None, req_index_prefix=None, req_device=None):
+    return {
+        "data_dir": req_data_dir or settings.data_dir,
+        "model_path": req_model_path or settings.model_path,
+        "index_prefix": req_index_prefix or settings.index_prefix,
+        "device": req_device or settings.device,
+    }
 
 
 def _load_engine(data_dir: str, model_path: str, index_prefix: str, device: str) -> HybridEngine:
@@ -57,14 +68,20 @@ def _load_engine(data_dir: str, model_path: str, index_prefix: str, device: str)
 
 @app.get("/health")
 def health():
-    return {"status": "ok"}
+    return {"status": "ok", "service": "acr", "version": "0.2.0"}
+
+
+@app.get("/config")
+def config():
+    return settings.model_dump()
 
 
 @app.post("/recognize")
 def recognize(req: RecognizeRequest):
+    resolved = _resolve(req.data_dir, req.model_path, req.index_prefix, req.device)
     if not Path(req.query_path).exists():
         raise HTTPException(status_code=400, detail=f"Missing query file: {req.query_path}")
-    engine = _load_engine(req.data_dir, req.model_path, req.index_prefix, req.device)
+    engine = _load_engine(**resolved)
     return engine.recognize(req.query_path, top_n=req.top_n)
 
 
@@ -72,9 +89,10 @@ def recognize(req: RecognizeRequest):
 def build_index(req: BuildIndexRequest):
     from run_demo import build_chroma_index, build_embedding_index
 
-    data_dir = Path(req.data_dir)
+    resolved = _resolve(req.data_dir, req.model_path, None, req.device)
+    data_dir = Path(resolved["data_dir"])
     out_dir = Path(req.output_dir)
     out_dir.mkdir(parents=True, exist_ok=True)
     build_chroma_index(data_dir, out_dir)
-    _, ref_embs, ref_ids = build_embedding_index(data_dir, Path(req.model_path), out_dir / "reference", req.device)
+    _, ref_embs, ref_ids = build_embedding_index(data_dir, Path(resolved["model_path"]), out_dir / "reference", resolved["device"])
     return {"status": "ok", "num_reference_windows": len(ref_ids), "embedding_dim": int(ref_embs.shape[1]) if len(ref_embs.shape) > 1 else 0}

+from pathlib import Path
+from pydantic import BaseModel
+
+
+class ServiceSettings(BaseModel):
+    data_dir: str = "data/synthetic_v2"
+    model_path: str = "data/models_v3/best_model.pt"
+    index_prefix: str = "data/index_v3/reference"
+    device: str = "cpu"
+
+    def ensure_parent_dirs(self):
+        for p in [Path(self.data_dir), Path(self.model_path).parent, Path(self.index_prefix).parent]:
+            p.mkdir(parents=True, exist_ok=True)

@@ -75,3 +75,23 @@
 - API `build_index(...)` 成功返回 reference window 数量
 - API `recognize(...)` 成功返回候选结果
 - `train.py --dry-run` 成功
+
+## 2026-06-02
+
+### Stage: 文档治理闭环（导航 / 引用 / 模板）
+
+完成项：
+- 新增 `docs/README.md` 作为文档总入口
+- 新增 `docs/references-and-sources.md` 作为引用来源总图
+- 新增 `docs/benchmark-report-template.md`
+- 新增 `docs/model-card-template.md`
+- 新增 `docs/release-checklist.md`
+- 核心文档统一补充 `Sources` 小节
+- 核心文档统一补齐 executive summary / mermaid / table / appendix 风格
+
+验证结果：
+- docs 总入口结构检查通过
+- references map 结构检查通过
+- 核心 docs 存在性检查通过
+- benchmark/model/release 模板结构检查通过
+- 所有核心文档均具备 Sources；SOTA 文档已补齐 Mermaid 图

+# ACR Docs Overview
+
+> 更新：2026-06-02
+
+## 一页结论
+
+这套文档已经按“**重点 → 图 → 表 → 文 → 细节**”重构，建议按下面顺序阅读：
+
+1. **项目定位与职责**
+2. **系统架构**
+3. **数据规范**
+4. **服务接口**
+5. **benchmark 与工业化路线**
+6. **数据来源与许可**
+7. **SOTA 调研**
+
+---
+
+## 1. 文档导航图
+
+```mermaid
+flowchart TD
+    A[Docs Entry] --> B[Project Responsibility]
+    A --> C[Architecture]
+    A --> D[Dataset Spec]
+    A --> E[Service API]
+    A --> F[Industrial Benchmark]
+    A --> G[Industrialization Roadmap]
+    A --> H[Licensing & Sources]
+    A --> I[SOTA Research]
+
+    B --> C
+    C --> D
+    C --> E
+    D --> F
+    F --> G
+    H --> G
+    I --> G
+```
+
+---
+
+## 2. 阅读顺序表
+
+| 读者角色 | 建议先读 |
+|---|---|
+| 产品/负责人 | `industrialization-roadmap.md` |
+| 算法/模型 | `acr-architecture.md`, `dataset-spec.md`, `sota-research-2026.md` |
+| 平台/后端 | `service-api.md`, `industrial-benchmark-spec.md` |
+| 数据/合规 | `dataset-sources-and-licensing.md` |
+| 新成员 | `project-responsibility-map.md`, `README.md` |
+
+---
+
+## 3. 文档清单
+
+- `project-responsibility-map.md`
+- `acr-architecture.md`
+- `dataset-spec.md`
+- `service-api.md`
+- `industrial-benchmark-spec.md`
+- `industrialization-roadmap.md`
+- `dataset-sources-and-licensing.md`
+- `sota-research-2026.md`
+- `CHANGELOG.md`
+
+---
+
+## 4. 文字说明
+
+这套文档不是“平铺型说明书”，而是尽量面向：
+- 决策
+- 分工
+- 分层
+- 工业化演进
+
+因此每份文档都优先呈现：
+- 重点结论
+- 图示关系
+- 表格归纳
+- 文字说明
+- 细节附录
+
+---
+
+## 5. 细节附录
+
+建议后续继续补充：
+- Benchmark report 模板
+- Model card 模板
+- License review checklist
+- Release checklist
+
+## Sources
+- This file is an internal documentation navigation artifact for the current repo state.

-# ACR 项目架构图
+# ACR 系统架构图
 
 > 更新：2026-06-02
 
-## 1. 总体架构
+## 一页结论
+
+- 识别链路已不是单一模型，而是 **指纹 + 向量 + melody-aware rerank** 的混合结构
+- 数据与服务已经进入工业化演进阶段
+- 当前主短板在：`humming_like` 与 `confused` 的 hard-case 精度
+
+---
+
+## 1. 总体架构图
 
 ```mermaid
 flowchart LR
-    Q[Query 音频] --> P[预处理]
-    P --> F1[传统指纹特征]
-    P --> F2[Mel 特征]
+    Q[Query Audio] --> P[Preprocess]
+    P --> F1[Chromaprint Features]
+    P --> F2[128-Mel Features]
+    P --> F3[Melody Signature]
+
+    F1 --> M1[Fingerprint Matcher]
+    F2 --> M2[ECAPA + BandSplit Embedder]
+    F3 --> M3[Melody Similarity]
 
-    F1 --> M1[Chromaprint Matcher]
-    F2 --> M2[ECAPA Embedder]
+    C[Catalog References] --> I1[Fingerprint Index]
+    C --> I2[Embedding Window Index]
+    C --> I3[Reference Melody Cache]
 
-    R[Reference 曲库] --> I1[指纹索引]
-    R --> I2[Embedding 索引]
+    M1 --> H[Hybrid Fusion]
+    M2 --> H
+    M3 --> H
 
-    M1 --> C[候选集合]
-    M2 --> C
-    C --> H[Hybrid 重排序]
-    H --> O[Top-K 识别结果]
+    H --> O[Top-K + Reject]
 ```
 
-## 2. 训练架构
+---
+
+## 2. 在线/离线分层图
 
 ```mermaid
 flowchart TD
-    A[原始/合成音频] --> B[随机裁剪]
-    B --> C[增强: 噪声/变速/移调/混响]
-    C --> D[Mel Spectrogram]
-    D --> E[ECAPA-TDNN]
-    E --> F[Embedding]
-    F --> G[SupCon Loss]
-    F --> H[AAM Softmax]
-    G --> I[联合优化]
-    H --> I
+    A[Offline Pipeline] --> A1[Dataset Prep]
+    A --> A2[Training]
+    A --> A3[Index Build]
+    A --> A4[Benchmark]
+
+    B[Online Service] --> B1[/health]
+    B --> B2[/recognize]
+    B --> B3[/index/build]
 ```
 
-## 3. 推理架构
+---
 
-```mermaid
-sequenceDiagram
-    participant U as User Query
-    participant P as Preprocessor
-    participant C as Chroma Matcher
-    participant E as ECAPA Embedder
-    participant H as Hybrid Engine
-
-    U->>P: 输入音频
-    P->>C: 指纹特征
-    P->>E: Mel 特征
-    C-->>H: Top-N 指纹候选
-    E-->>H: Top-N embedding 候选
-    H-->>U: 融合后的识别结果
-```
+## 3. 关键模块表
+
+| 模块 | 输入 | 输出 | 作用 |
+|---|---|---|---|
+| Preprocess | wav | mel/chroma/f0 | 统一特征入口 |
+| Fingerprint Matcher | query audio | chroma candidates | 快速召回 |
+| ECAPA Embedder | mel | embeddings | 语义向量检索 |
+| Melody Similarity | query/ref melody | melody score | 哼唱场景补强 |
+| Hybrid Fusion | multi-scores | ranked candidates | 综合排序 |
+| Service API | request | JSON result | 对外调用 |
+
+---
+
+## 4. 当前设计重点
+
+### 4.1 为什么是混合结构
+纯指纹对哼唱弱，纯 embedding 对局部强匹配和解释性不足，因此使用混合结构更稳妥。
+
+### 4.2 为什么加入 melody-aware
+目前 hard-case 主要在哼唱/近旋律混淆，因此用 melody signature 做辅助排序。
+
+### 4.3 为什么要 window-level index
+整曲平均 embedding 会损失局部片段信息；window-level 更贴近 ACR 场景。
+
+---
 
-## 4. 当前可运行闭环
+## 5. 细节附录
 
-1. 用 `synthetic.py` 生成合成曲库
-2. 用 `train.py` 训练 ECAPA 原型模型
-3. 用 `run_demo.py build-index` 构建：
-   - 指纹索引
-   - embedding 索引
-4. 用 `run_demo.py recognize` 对片段做识别
+代码映射：
+- `src/engines/chromaprint_matcher.py`
+- `src/engines/ecapa_embedder.py`
+- `src/engines/hybrid_engine.py`
+- `src/service/app.py`
 
-## 5. 后续生产化架构建议
 
-- API Gateway
-- 异步音频入库流水线
-- Faiss/HNSW 向量服务
-- Postgres/MySQL 元数据服务
-- 对象存储保存原始音频
-- 模型服务与索引服务解耦
+## Sources
+- See `docs/references-and-sources.md` for the current source map.

+# Benchmark Report Template
+
+> 用于每次模型版本评测输出
+
+## 一页结论
+- 模型版本：
+- 数据版本：
+- 核心结论：
+- 是否通过上线门禁：
+
+## 1. 评测范围图
+
+```mermaid
+flowchart LR
+    A[Model Version] --> B[Datasets]
+    A --> C[Scenario Buckets]
+    A --> D[Latency / Ops]
+```
+
+## 2. 指标表
+
+| Bucket | top1 | top5 | MRR | FAR | Notes |
+|---|---:|---:|---:|---:|---|
+| clean |  |  |  |  |  |
+| humming_like |  |  |  |  |  |
+| confused |  |  |  |  |  |
+
+## 3. 文字分析
+- 最强项：
+- 最弱项：
+- 与上一版本对比：
+
+## 4. 细节附录
+- 评测命令
+- 数据清单
+- 原始 JSON 报告路径
+
+## Sources
+- `docs/industrial-benchmark-spec.md`

-# Dataset Sources and Licensing Notes
+# Dataset Sources and Licensing
 
 > 更新：2026-06-02
 
-## 注意
-以下仅为工程接入与研究规划说明，不等于法律意见。实际商用前需要逐条复核原始 license、dataset terms 和再训练约束。
+## 一页结论
 
-## 候选数据源
+- 外部数据集接入的第一原则不是“能下载”，而是“**能否合法商用**”
+- 当前建议优先级：
+  1. FMA
+  2. MTG-Jamendo
+  3. CCMusic（审批/核验后）
+  4. ModelScope music datasets（白名单后）
+- ModelScope 与 CCMusic 当前都不能默认直接进入商用训练
 
-### 1. FMA
-- URL: https://github.com/mdeff/fma
-- 特点: 开放、MIR 常用、适合 retrieval baseline
-- 风险: 音频 license 按 artist/track 可能不同，需逐条核验
+---
 
-### 2. MTG-Jamendo
-- URL: https://github.com/MTG/mtg-jamendo-dataset
-- 特点: Creative Commons 来源，适合音乐检索/标签任务
-- 风险: 仍需按具体曲目用途与商业场景做 license 审查
+## 1. 来源分层图
 
-### 3. CCMusic
-- 论文/介绍: https://transactions.ismir.net/articles/10.5334/tismir.194
-- 主页: https://ccmusic-database.github.io/en/database/ccm.html
-- 特点: 中国音乐 MIR 数据资源丰富
-- 风险: 部分数据集可能需要申请或存在使用边界，必须单独核验
+```mermaid
+flowchart TD
+    A[Candidate Datasets] --> B[Open / MIR Baselines]
+    A --> C[Chinese / Regional Sources]
+    A --> D[Discovery Surfaces]
 
-### 4. ModelScope music datasets
-- 入口: https://www.modelscope.cn/datasets
-- 搜索: https://modelscope.cn/search?page=1&search=music&type=dataset
-- 特点: 数据发现方便，可扩充中文生态
-- 风险: license 分散，不能默认可商用；接入前必须建立白名单
+    B --> B1[FMA]
+    B --> B2[MTG-Jamendo]
+    C --> C1[CCMusic]
+    D --> D1[ModelScope music datasets]
+```
 
-## 接入原则
+---
 
-- 只接入 license 明确的数据集
-- 默认拒绝“来源不明 / 不允许商业使用 / 禁止训练衍生模型”的数据
-- 训练前把数据集及许可信息落盘到 registry
+## 2. 数据源表
+
+| 数据源 | 角色 | 风险 | 当前策略 |
+|---|---|---|---|
+| FMA | 首批真实 baseline | track license 需核验 | review_required |
+| MTG-Jamendo | retrieval/tagging corpus | CC 细则需核验 | review_required |
+| CCMusic | 中文 MIR 资源 | 可能需申请/存在限制 | review_required |
+| ModelScope music | 数据发现入口 | license 分散 | deny_until_whitelisted |
+
+---
+
+## 3. 白名单流程图
+
+```mermaid
+flowchart LR
+    A[发现数据集] --> B[收集 license / terms]
+    B --> C[法律/合规审查]
+    C --> D{可商用?}
+    D -- 是 --> E[加入 whitelist]
+    D -- 否 --> F[禁止进入训练]
+```
+
+---
+
+## 4. 文字说明
+
+### 4.1 为什么 ModelScope 只能先当 discovery surface
+因为不同数据集来源和条款差异很大，不能因为“在 ModelScope 上”就默认可商用。
+
+### 4.2 为什么 CCMusic 要单独看
+它对中文音乐任务很有价值，但部分子集可能涉及申请、协议或非标准商业许可边界。
+
+### 4.3 为什么 license registry 要和模型版本绑定
+这样才能在未来追踪：
+- 某个模型到底用了哪些数据
+- 这些数据是否允许对应商用场景
+
+---
+
+## 5. 细节附录
+
+入口链接：
+- FMA: https://github.com/mdeff/fma
+- MTG-Jamendo: https://github.com/MTG/mtg-jamendo-dataset
+- CCMusic: https://ccmusic-database.github.io/en/database/ccm.html
+- ModelScope search: https://modelscope.cn/search?page=1&search=music&type=dataset
+
+
+## Sources
+- See `docs/references-and-sources.md` for the current source map.

@@ -2,41 +2,111 @@
 
 > 更新：2026-06-02
 
-## 1. 目标
+## 一页结论
+
+- 数据规范的核心不是文件格式，而是**分离 catalog 与 query**
+- 外部数据集进入系统前必须先转换成统一 manifest
+- 当前系统的标准输入是：
+  - **16k mono audio**
+  - **128 Mel**
+  - **window-level retrieval**
+- 当前系统的标准输出是：
+  - top-k candidates
+  - confidence
+  - reject/accept
+  - metadata
+
+---
+
+## 1. 数据流图
+
+```mermaid
+flowchart LR
+    A[External / Synthetic Audio] --> B[Manifest Conversion]
+    B --> C[Catalog Manifest]
+    B --> D[Query Manifest]
+    C --> E[Reference Index Build]
+    D --> F[Training / Evaluation Queries]
+    E --> G[Hybrid Retrieval]
+    F --> G
+```
+
+---
+
+## 2. 数据对象表
+
+| 对象 | 作用 | 必要字段 | 说明 |
+|---|---|---|---|
+| Reference | 可检索曲库 | `song_id`, `audio_path`, `duration`, `type=reference` | 用于建索引 |
+| Query Segment | 待识别片段 | `song_id`, `audio_path`, `duration`, `type` | 用于训练/评测 |
+| Catalog Manifest | reference 总表 | JSON list | 用于离线索引 |
+| Query Manifest | query 总表 | JSON list | 用于训练与评测 |
+
+---
+
+## 3. Manifest 结构图
+
+```mermaid
+flowchart TD
+    M[Manifest] --> R[Reference Records]
+    M --> Q[Query Records]
+    R --> R1[song_id]
+    R --> R2[audio_path]
+    R --> R3[duration]
+    R --> R4[type=reference]
+    Q --> Q1[song_id]
+    Q --> Q2[audio_path]
+    Q --> Q3[duration]
+    Q --> Q4[type=clean/augmented/confused/humming_like]
+```
+
+---
+
+## 4. 输入输出总表
+
+| 环节 | 输入 | 输出 |
+|---|---|---|
+| 训练 | query segments | embeddings + logits |
+| 索引 | catalog references | chromaprint index + embedding index |
+| 识别 | query audio | ranked candidates |
+| 评测 | query manifest + catalog | top1/top5/hard-case report |
+
+---
+
+## 5. 文字说明
+
+### 5.1 为什么必须分离 catalog 和 query
+早期原型容易把 train split 直接当搜索库，这会让评测和真实服务语义混乱。工业化系统必须把：
+- “可搜索曲库”
+- “训练/评测 query”
+
+明确分离。
 
-定义本项目数据集规范、输入输出处理流程、catalog/query 划分方式，以及训练/评测所需的 manifest 结构。
+### 5.2 为什么输入层是 128 Mel
+音乐任务需要更丰富的频带表达，128 Mel 更适合 band-split 和音乐 timbre/harmony 建模。
 
-## 2. 数据层对象
+### 5.3 query 类型为什么要显式标注
+`clean / augmented / confused / humming_like` 是评测与训练策略的重要条件，不应只放在隐式文件名里。
 
-### 2.1 Reference / Catalog
-可检索曲库中的标准参考音频。
+---
 
-字段：
+## 6. 细节附录
 
+### Reference 示例
 ```json
 {
   "song_id": "song_0001",
   "audio_path": "songs/song_0001.wav",
   "duration": 20.0,
-  "base_freq": 261.63,
   "type": "reference"
 }
 ```
 
-用途：
-- 建立 chromaprint 索引
-- 建立 embedding window 索引
-- 作为检索目标集合
-
-### 2.2 Query Segment
-待识别片段。
-
-字段：
-
+### Query 示例
 ```json
 {
   "song_id": "song_0001",
-  "audio_path": "segments/song_0001_seg_02_confused.wav",
+  "audio_path": "segments/song_0001_seg_04_confused.wav",
   "duration": 5.0,
   "type": "confused",
   "offset": 8.3,
@@ -44,105 +114,6 @@
 }
 ```
 
-用途：
-- 训练片段对
-- top-k 检索评测
-- 鲁棒性测试
-
-## 3. Manifest 文件
-
-| 文件 | 用途 |
-|---|---|
-| `train.json` | 训练查询片段 + 训练 reference |
-| `val.json` | 验证查询片段 + 验证 reference |
-| `test.json` | 测试查询片段 + 测试 reference |
-| `catalog.json` | 可搜索 reference 总表 |
-
-注意：
-- `catalog.json` 是**检索索引输入**
-- `train/val/test.json` 是**实验 split**
-- 不再把 “模型训练 split” 和 “可搜索曲库” 混为一谈
-
-## 4. 输入特征规范
-
-### 4.1 输入音频
-- 默认采样率：`16 kHz`
-- 通道：`mono`
-- 训练/query 窗长：`5s`
-- 滑窗步长：`2.5s`
-
-### 4.2 声学特征
-当前改为：
-- **128维 Mel 频谱**
-
-不再采用传统说话人任务常见的 40 维 MFCC 作为主输入，因为：
-- 音乐任务更依赖频带结构与谐波信息
-- Mel 频谱对音乐 timbre / harmony / texture 表达更自然
-- 便于 band-split 模块对频带进行分块建模
-
-## 5. 输出规范
-
-### 5.1 训练输出
-模型输出：
-- `embedding: [B, D]`
-- `logits: [B, num_classes]`（辅助分类头）
-
-主要目标：
-- retrieval embedding 学得稳定
-- 同 song 片段彼此接近
-- 不同 song 分离
-
-### 5.2 推理输出
-识别输出：
-
-```json
-{
-  "candidates": [
-    {
-      "song_id": "song_0001",
-      "confidence": 0.93,
-      "chromaprint_score": 0.88,
-      "ecapa_score": 0.96,
-      "accepted": true,
-      "metadata": {}
-    }
-  ],
-  "processing_time_ms": 120.4,
-  "num_candidates": 5
-}
-```
-
-## 6. Query 类型定义
-
-| type | 含义 |
-|---|---|
-| `clean` | 原始干净片段 |
-| `augmented` | 常规增强片段 |
-| `confused` | 强混淆/干扰片段 |
-| `humming_like` | 哼唱风格近似片段 |
-| `reference` | 标准参考整曲 |
-
-## 7. pro-WGAN 平衡策略（工程近似版）
-
-当前仓库先实现的是**pro-WGAN 风格的数据平衡近似策略**，不是完整生成式 GAN 训练：
-
-- 对难样本类型（`confused`, `humming_like`）增加更强增广概率
-- 通过 harder augmentation 近似 minority/hard-case oversampling
-- 保持 manifest 结构兼容，后续可替换成真正的生成式平衡器
-
-后续若接入完整 GAN 平衡器，可把它作为：
-- 离线样本扩增器
-- 困难类别样本生成器
-- catalog/query domain adaptation 工具
-
-## 8. 频带分割模块
-
-输入层新增 `BandSplitBlock`：
-- 将 128 Mel bins 分割为多个子频带
-- 每个子带做独立投影
-- 再拼接进入主干网络
 
-目的：
-- 强化低频节奏 / 中频和声 / 高频音色的分带建模
-- 更符合音乐频谱结构
-- 为后续更复杂 band-aware retrieval 打基础
+## Sources
+- See `docs/references-and-sources.md` for the current source map.

+# External Manifest Template
+
+适用于 FMA / Jamendo / CCMusic / ModelScope 白名单数据集。
+
+## catalog.csv 最小字段
+
+```csv
+song_id,audio_path,duration,source_dataset
+track_0001,raw/track_0001.wav,12.5,fma
+```
+
+转换命令：
+
+```bash
+python src/data/manifest_tools.py csv-to-catalog catalog.csv manifests/catalog.json
+```
+
+## 输出 catalog.json 结构
+
+```json
+{
+  "song_id": "track_0001",
+  "audio_path": "raw/track_0001.wav",
+  "duration": 12.5,
+  "type": "reference",
+  "source_dataset": "fma"
+}
+```

@@ -2,58 +2,82 @@
 
 > 更新：2026-06-02
 
-## 目标
-为工业级可商用 ACR 设立持续基准，不只看总体 top1/top5，还看场景化与风险化指标。
-
-## Benchmark 维度
-
-### 1. Retrieval Quality
-- top1
-- top5
-- MRR
-- recall@k
-
-### 2. Scenario Buckets
-- clean
-- noisy
-- compressed
-- time-stretched
-- pitch-shifted
-- humming_like
-- confused
-- partial-overlap
-- far-field / device-recorded
-
-### 3. Catalog Scale Buckets
-- 1K songs
-- 10K songs
-- 100K songs
-- 1M+ songs
-
-### 4. Operational Metrics
-- p50 / p95 latency
-- indexing throughput
-- incremental update time
-- memory / disk footprint
-
-### 5. Business Safety Metrics
-- false accept rate
-- rejection quality
-- near-duplicate confusion rate
-- license provenance coverage
-
-## Required Artifacts per Model Release
-- dataset registry snapshot
-- training config snapshot
-- benchmark report JSON
-- benchmark summary markdown
-- model card
-- license review manifest
-
-## Minimum Go/No-Go Gate
+## 一页结论
+
+- 工业级 ACR 不能只看总 top1
+- 必须同时看：
+  1. hard-case
+  2. rejection / false accept
+  3. latency / scale
+  4. license provenance completeness
+
+---
+
+## 1. Benchmark 分层图
+
+```mermaid
+flowchart TD
+    A[Industrial Benchmark] --> B[Accuracy]
+    A --> C[Robustness]
+    A --> D[Operational]
+    A --> E[Compliance]
+
+    B --> B1[top1/top5/MRR]
+    C --> C1[humming/confused/noisy]
+    D --> D1[latency/indexing/throughput]
+    E --> E1[data provenance/license coverage]
+```
+
+---
+
+## 2. 指标表
+
+| 维度 | 指标 | 目标 |
+|---|---|---|
+| Accuracy | top1 / top5 / MRR | 主识别质量 |
+| Robustness | humming/confused/noisy top1 | hard-case 质量 |
+| Operational | p50/p95 latency | 服务能力 |
+| Operational | index throughput | 建库能力 |
+| Safety | false accept rate | 误识别风险 |
+| Compliance | license coverage | 商业可用前提 |
+
+---
+
+## 3. 场景图
+
+```mermaid
+flowchart LR
+    Q[Queries] --> Q1[clean]
+    Q --> Q2[augmented]
+    Q --> Q3[humming_like]
+    Q --> Q4[confused]
+    Q --> Q5[noisy/compressed]
+```
+
+---
+
+## 4. 文字说明
+
+### 4.1 为什么 hard-case 要单独出报表
+因为总体 top1 很容易掩盖哼唱和混淆场景的失败，而这些正是用户最敏感的场景。
+
+### 4.2 为什么要加入 operational metrics
+工业级系统不是离线竞赛模型，需要考虑服务响应与增量索引成本。
+
+### 4.3 为什么要把 compliance 放进 benchmark
+对于商用系统，如果训练/评测数据来源不可追溯，再高精度也不能安全上线。
+
+---
+
+## 5. 细节附录
+
+推荐 release gate：
 - clean top1 >= 0.95
 - noisy top1 >= 0.85
 - confused top1 >= 0.70
 - humming_like top1 >= 0.60
-- top5 >= 0.95 on all production-relevant buckets
-- false accept below agreed threshold
+- top5 >= 0.95 on production-relevant buckets
+
+
+## Sources
+- See `docs/references-and-sources.md` for the current source map.

-# ACR 工业级可商用演进路线
+# 工业化路线图
 
 > 更新：2026-06-02
 
-## 1. 目标定义
-
-把当前原型升级为一个可商用的工业级 ACR 系统，满足：
-
-- 可扩展曲库管理
-- 可重复训练 / 评测 / 部署
-- 多数据源接入（synthetic / FMA / Jamendo / CCMusic / ModelScope）
-- 更强鲁棒性（噪声、失真、哼唱、混淆）
-- 检索服务化
-- 商用合规与授权边界可审计
-
-## 2. 工业级分层
-
-### 2.1 数据层
-- `catalog.json` / query manifests
-- 外部 dataset adapters
-- license / usage tracking
-- 数据版本与快照
-
-### 2.2 训练层
-- baseline encoder
-- foundation-model encoder
-- retrieval-first losses
-- hard negative mining
-- 数据平衡与生成增强
-
-### 2.3 索引层
-- window-level embeddings
-- ANN index (Faiss/HNSW)
-- 指纹索引与向量索引双路
-- 增量入库
-
-### 2.4 服务层
-- FastAPI / gRPC
-- batch ingest
-- recognize API
-- top-k candidate + rejection
-- metadata lookup
-
-### 2.5 质量层
-- regression benchmark
-- hard-case benchmark
-- online shadow evaluation
-- 数据/模型回滚机制
-
-## 3. 数据集策略
-
-### 第一梯队（优先）
-- FMA small / medium
-- MTG-Jamendo
-- CCMusic（需核验申请/授权方式）
-- ModelScope music datasets（按 license 白名单接入）
-
-### 第二梯队
-- humming / QBSH 数据集
-- instrument / structure / singing datasets 作为辅助监督
-
-## 4. 商用必做项
-
-- 每个 dataset 记录：
-  - 来源 URL
-  - license
-  - 是否允许商业使用
-  - 再分发限制
-  - 模型训练用途限制
-- 每个模型版本记录训练数据组成
-- 每次上线保留评测报告与可追溯哈希
-
-## 5. 当前到工业化的缺口
-
-- 缺 dataset adapter 层
-- 缺 ANN 检索
-- 缺 API 服务
-- 缺 license registry
-- 缺 foundation-model baseline
-- 缺真正的 hard-negative mining
-- 缺真实开源数据 benchmark
+## 一页结论
+
+当前项目已完成：
+- 原型可运行
+- retrieval-first 初步改造
+- 服务骨架
+- 外部数据 adapter 雏形
+
+下一阶段必须聚焦三件事：
+1. **真实数据接入**
+2. **hard-case 精度**
+3. **商业化合规与服务稳定性**
+
+---
+
+## 1. 路线图图示
+
+```mermaid
+flowchart LR
+    P0[P0 原型跑通] --> P1[P1 真实数据验证]
+    P1 --> P2[P2 工程化与服务化]
+    P2 --> P3[P3 大规模索引]
+    P3 --> P4[P4 商用上线]
+```
+
+---
+
+## 2. 阶段表
+
+| 阶段 | 目标 | 当前状态 | 核心产物 |
+|---|---|---|---|
+| P0 | 端到端原型 | 已完成 | demo/train/index/eval |
+| P1 | 白名单真实数据接入 | 进行中 | adapters/manifests/benchmark |
+| P2 | API / benchmark / ops | 进行中 | FastAPI + spec |
+| P3 | ANN / 增量索引 | 未完成 | Faiss/HNSW |
+| P4 | 可商用平台 | 未完成 | license gate / SLA / release flow |
+
+---
+
+## 3. 近期优先级
+
+### Priority A
+- FMA / Jamendo 小规模白名单子集接入
+- humming_like / confused 精度提升
+- service 配置化与真实部署 smoke
+
+### Priority B
+- ANN 向量索引
+- 拒识/误接收指标
+- 模型版本化
+
+### Priority C
+- foundation model baseline
+- 在线评估与监控
+- 商业部署流程
+
+---
+
+## 4. 分层职责
+
+| 层 | 重点 |
+|---|---|
+| 数据层 | 只接入可审计白名单数据 |
+| 模型层 | 以 retrieval 指标为主，不迷信分类头 |
+| 检索层 | 强化 hard-case 与 rejection |
+| 服务层 | 稳定 API、可配置、可观测 |
+| 合规层 | 任何上线模型必须可追溯数据来源 |
+
+---
+
+## 5. 细节附录
+
+关联文档：
+- `docs/dataset-sources-and-licensing.md`
+- `docs/industrial-benchmark-spec.md`
+- `docs/service-api.md`
+
+
+## Sources
+- See `docs/references-and-sources.md` for the current source map.

+# Model Card Template
+
+## 一页结论
+- 模型名称：
+- 版本：
+- 适用场景：
+- 不适用场景：
+
+## 1. 模型结构图
+
+```mermaid
+flowchart LR
+    A[Input Audio] --> B[128 Mel + BandSplit]
+    B --> C[Encoder]
+    C --> D[Embedding]
+    D --> E[Hybrid Retrieval]
+```
+
+## 2. 关键信息表
+
+| 项 | 内容 |
+|---|---|
+| 训练数据 |  |
+| 评测数据 |  |
+| 主要指标 |  |
+| 已知风险 |  |
+| 许可证约束 |  |
+
+## 3. 文字说明
+- 训练方式：
+- 模型限制：
+- 风险提示：
+
+## 4. 细节附录
+- checkpoint 路径
+- config 路径
+- benchmark 报告路径
+
+## Sources
+- `docs/dataset-spec.md`
+- `docs/benchmark-report-template.md`

@@ -2,91 +2,128 @@
 
 > 更新：2026-06-02
 
-## 1. 项目定位
-
-本项目是一个**听歌识曲 / 音频内容识别（ACR）原型系统**，目标是先跑通：
-
-- 数据生成
-- 特征提取
-- 模型训练
-- 指纹检索
-- embedding 检索
-- hybrid 混合识别
-
-当前不以生产服务为目标，重点是**算法链路验证**。
-
-## 2. 仓库职责分层
-
-```text
-/workspace
-├── acr-engine/                 # ACR 核心算法与可运行 demo
-│   ├── configs/                # 训练/推理参数配置
-│   ├── src/data/               # 数据集读取、合成数据生成
-│   ├── src/models/             # 声学模型、损失函数
-│   ├── src/engines/            # 指纹/embedding/hybrid 检索引擎
-│   ├── train.py                # 模型训练入口
-│   ├── run_demo.py             # 数据生成、建索引、识别入口
-│   └── requirements.txt        # Python 依赖
-├── docs/                       # 设计、架构、路线图、使用说明
-├── scripts/                    # 环境安装与工具 bootstrap
-├── container/                  # 容器环境定义
-└── .codex/.omx/                # Codex / OMX 协作与运行时元数据
-```
+## 一页结论
+
+- 本项目已经从“算法原型”升级为“**面向工业化的 ACR 平台雏形**”
+- 当前系统分为 **数据层、训练层、检索层、服务层、评测层、合规层**
+- 近期重点不是再堆功能，而是：
+  1. 提升 `humming_like` / `confused` 准确率
+  2. 接入真实白名单数据集
+  3. 完善服务、索引、benchmark 与合规闭环
 
-## 3. 模块职责图
+---
+
+## 1. 分层图
 
 ```mermaid
 flowchart TD
-    A[音频输入] --> B[数据层]
-    B --> B1[合成数据生成 synthetic.py]
-    B --> B2[训练/验证数据集 dataset.py]
-
-    A --> C[特征层]
-    C --> C1[Mel Spectrogram]
-    C --> C2[Chroma / F0]
-    C --> C3[增强 augment.py]
-
-    C --> D[模型层]
-    D --> D1[ECAPA-TDNN]
-    D --> D2[SupCon + AAM Loss]
-
-    A --> E[检索层]
-    E --> E1[ChromaprintMatcher]
-    E --> E2[ECAPAEmbedder]
-    E --> E3[HybridEngine]
-
-    D --> F[训练入口 train.py]
-    E --> G[推理入口 run_demo.py]
+    A[L1 业务目标层] --> B[L2 系统能力层]
+    B --> C[L3 核心模块层]
+    C --> D[L4 工程服务层]
+    C --> E[L5 数据与合规层]
+
+    A1[听歌识曲 / 哼唱识别 / 商业可用]:::goal --> A
+
+    B1[高准确率识别] --> B
+    B2[可扩展曲库] --> B
+    B3[可服务化调用] --> B
+    B4[可审计数据来源] --> B
+
+    C1[训练与表征学习] --> C
+    C2[指纹检索] --> C
+    C3[向量检索] --> C
+    C4[混合重排] --> C
+    C5[评测基准] --> C
+
+    D1[FastAPI] --> D
+    D2[Index Build] --> D
+    D3[Manifest Tools] --> D
+
+    E1[External Adapters] --> E
+    E2[Dataset Registry] --> E
+    E3[License Review] --> E
+
+    classDef goal fill:#e8f5e9,stroke:#2e7d32;
 ```
 
-## 4. 角色职责
-
-| 模块 | 职责 | 当前状态 |
-|---|---|---|
-| `src/data/synthetic.py` | 生成可控的合成歌曲与片段 | 已实现 |
-| `src/data/dataset.py` | 训练/验证数据装载 | 已实现 |
-| `src/utils/audio.py` | Mel、滑窗、F0、Chroma | 已实现 |
-| `src/utils/augment.py` | 噪声、变速、移调、混响增强 | 已实现 |
-| `src/models/ecapa_tdnn.py` | embedding 编码器 | 已实现 |
-| `src/models/losses.py` | 对比学习 + 分类训练目标 | 已实现 |
-| `src/engines/chromaprint_matcher.py` | 传统哈希指纹检索 | 已实现 |
-| `src/engines/ecapa_embedder.py` | embedding 提取与向量检索 | 已实现 |
-| `src/engines/hybrid_engine.py` | 融合匹配结果 | 已实现 |
-| `train.py` | 训练入口 | 已实现 |
-| `run_demo.py` | demo 入口 | 本次补齐 |
-
-## 5. 当前边界
-
-当前项目**负责**：
-
-- 原型级算法验证
-- 小规模曲库识别
-- 本地训练与本地识别 demo
-
-当前项目**暂不负责**：
-
-- 在线 API 服务
-- 海量曲库 ANN 线上部署
-- 权限、账号、计费
-- 真正版权音频数据治理
-- 生产监控告警
+---
+
+## 2. 职责总表
+
+| 层级 | 模块 | 负责内容 | 当前状态 |
+|---|---|---|---|
+| 数据层 | `src/data/*` | synthetic 数据、external adapters、manifest | 已有基础 |
+| 训练层 | `train.py` / `src/models/*` | 128 Mel、band-split、embedding 学习 | 可运行 |
+| 检索层 | `src/engines/*` | chromaprint、embedding、melody-aware hybrid | 可运行 |
+| 服务层 | `src/service/*` | health / recognize / index build | 骨架已通 |
+| 评测层 | `evaluate.py` | top1/top5/hard-case benchmark | 已建立 |
+| 合规层 | registry/docs | dataset source / licensing / whitelist | 雏形已建 |
+
+---
+
+## 3. 分工图
+
+```mermaid
+flowchart LR
+    D[数据团队] --> D1[数据接入]
+    D --> D2[manifest 标准化]
+    D --> D3[license 审查]
+
+    M[模型团队] --> M1[特征与模型]
+    M --> M2[鲁棒训练]
+    M --> M3[hard-case 优化]
+
+    R[检索团队] --> R1[指纹索引]
+    R --> R2[向量索引]
+    R --> R3[融合与拒识]
+
+    S[平台团队] --> S1[API 服务]
+    S --> S2[部署]
+    S --> S3[监控]
+
+    Q[质量团队] --> Q1[benchmark]
+    Q --> Q2[回归验证]
+    Q --> Q3[上线门禁]
+```
+
+---
+
+## 4. 文字说明
+
+### 4.1 数据层
+负责把不同来源的数据集（synthetic、FMA、Jamendo、CCMusic、ModelScope 白名单集）转成统一的 `catalog/query manifest`。
+
+### 4.2 训练层
+负责音乐任务特征建模，目前已经从低维说话人风格输入升级到：
+- 128 Mel
+- band-split
+- retrieval-first 训练方向
+
+### 4.3 检索层
+负责三路信息融合：
+- 指纹匹配
+- embedding 匹配
+- melody-aware 重排
+
+### 4.4 服务层
+负责把离线原型包装成可调用系统，目前已有 FastAPI 骨架。
+
+### 4.5 评测层
+负责质量门禁，不能只看总体 top1，要看 hard-case、拒识、误接收。
+
+### 4.6 合规层
+负责商用前提，任何外部数据集都必须进入 registry 和白名单流程。
+
+---
+
+## 5. 细节附录
+
+关键文档：
+- `docs/dataset-spec.md`
+- `docs/industrial-benchmark-spec.md`
+- `docs/dataset-sources-and-licensing.md`
+- `docs/industrialization-roadmap.md`
+
+
+## Sources
+- See `docs/references-and-sources.md` for the current source map.

+# References and Sources Map
+
+> 更新：2026-06-02
+
+## 一页结论
+
+当前项目的引用分成四类：
+1. **开源数据集来源**
+2. **研究/SOTA 来源**
+3. **服务与工程规范来源**
+4. **项目内部文档来源**
+
+---
+
+## 1. 引用分层图
+
+```mermaid
+flowchart TD
+    A[References] --> B[Datasets]
+    A --> C[Research]
+    A --> D[Engineering]
+    A --> E[Internal Docs]
+
+    B --> B1[FMA]
+    B --> B2[MTG-Jamendo]
+    B --> B3[CCMusic]
+    B --> B4[ModelScope]
+
+    C --> C1[Neural AFP]
+    C --> C2[Music Foundation Models]
+    C --> C3[Band-split]
+    C --> C4[Data Balancing]
+```
+
+---
+
+## 2. 外部来源表
+
+| 类别 | 名称 | URL | 当前用途 |
+|---|---|---|---|
+| Dataset | FMA | https://github.com/mdeff/fma | 真实 retrieval baseline 候选 |
+| Dataset | MTG-Jamendo | https://github.com/MTG/mtg-jamendo-dataset | 真实音乐检索候选 |
+| Dataset | CCMusic | https://ccmusic-database.github.io/en/database/ccm.html | 中文 MIR 数据源候选 |
+| Dataset | ModelScope music search | https://modelscope.cn/search?page=1&search=music&type=dataset | 数据发现入口 |
+| Research | MERT | https://arxiv.org/abs/2306.00107 | foundation-model 方向参考 |
+| Research | MuQ | https://arxiv.org/abs/2501.01108 | music representation 方向参考 |
+| Research | Band-split RNN | https://arxiv.org/abs/2209.15174 | 频带建模参考 |
+| Research | BAGAN | https://arxiv.org/abs/1803.09655 | 数据平衡增强参考 |
+
+---
+
+## 3. 内部文档依赖图
+
+```mermaid
+flowchart LR
+    A[references-and-sources.md] --> B[dataset-sources-and-licensing.md]
+    A --> C[sota-research-2026.md]
+    A --> D[industrialization-roadmap.md]
+```
+
+---
+
+## 4. 文字说明
+
+### 4.1 为什么单独做 References Map
+因为后续文档会越来越多，如果不把“哪些结论来自哪里”系统整理出来，很快会失去可追溯性。
+
+### 4.2 目前引用质量说明
+- dataset 来源：优先官方 repo / 官方主页
+- research 来源：优先 arXiv / 论文主页
+- service/工程来源：当前主要以内生工程规范为主
+
+### 4.3 未来要加强的地方
+- 在每篇核心文档底部补“Sources”小节
+- benchmark 报告与 model card 显式引用训练数据与论文版本
+
+---
+
+## 5. 细节附录
+
+建议补充：
+- 每份文档增加 `Sources` 节
+- 每次模型 release 输出引用快照
+
+## Sources
+- FMA: https://github.com/mdeff/fma
+- MTG-Jamendo: https://github.com/MTG/mtg-jamendo-dataset
+- CCMusic: https://ccmusic-database.github.io/en/database/ccm.html
+- ModelScope music search: https://modelscope.cn/search?page=1&search=music&type=dataset

+# Release Checklist
+
+## 一页结论
+发布前必须同时满足：
+- 质量通过
+- 合规通过
+- 服务通过
+- 文档齐全
+
+## 1. 发布门禁图
+
+```mermaid
+flowchart TD
+    A[Release Candidate] --> B[Benchmark Pass]
+    A --> C[License Review Pass]
+    A --> D[Service Smoke Pass]
+    A --> E[Docs Complete]
+```
+
+## 2. Checklist 表
+
+| 项目 | 状态 |
+|---|---|
+| benchmark report 已生成 |  |
+| model card 已生成 |  |
+| license registry 已更新 |  |
+| service smoke test 通过 |  |
+| dataset whitelist 已确认 |  |
+| changelog 已更新 |  |
+
+## 3. 文字说明
+- 任何缺失项都不能视作商用可发布
+
+## 4. 细节附录
+- 发布 commit
+- benchmark 报告路径
+- model card 路径
+- license 审查记录路径
+
+## Sources
+- `docs/dataset-sources-and-licensing.md`
+- `docs/industrial-benchmark-spec.md`

 # ACR Service API
 
-## Endpoints
+> 更新：2026-06-02
 
-### GET /health
-返回服务健康状态。
+## 一页结论
 
-### POST /recognize
-请求体：
+- 当前服务是工业化骨架，不是最终生产网关
+- 已提供最小可调用能力：
+  1. health
+  2. config
+  3. recognize
+  4. index build
+- 下一阶段重点是：鉴权、异步任务、ANN 索引、监控、错误码规范化
 
-```json
-{
-  "query_path": "data/synthetic_v2/segments/song_0021_seg_01_augmented.wav",
-  "data_dir": "data/synthetic_v2",
-  "model_path": "data/models_v3/best_model.pt",
-  "index_prefix": "data/index_v3/reference",
-  "top_n": 5,
-  "device": "cpu"
-}
+---
+
+## 1. 服务结构图
+
+```mermaid
+flowchart LR
+    C[Client] --> H[/health]
+    C --> G[/config]
+    C --> R[/recognize]
+    C --> I[/index/build]
+
+    R --> E[Hybrid Engine]
+    I --> B[Index Builders]
 ```
 
-### POST /index/build
-请求体：
+---
+
+## 2. Endpoint 表
+
+| Endpoint | 方法 | 作用 |
+|---|---|---|
+| `/health` | GET | 健康检查 |
+| `/config` | GET | 查看默认配置 |
+| `/recognize` | POST | 输入 query，输出候选 |
+| `/index/build` | POST | 触发离线索引构建 |
+
+---
+
+## 3. 请求流程图
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant API
+    participant Engine
+
+    Client->>API: POST /recognize
+    API->>Engine: load matcher/index/model
+    Engine-->>API: top-k candidates
+    API-->>Client: JSON result
+```
 
+---
+
+## 4. 文字说明
+
+### 4.1 为什么先暴露文件路径 API
+当前阶段优先验证系统闭环，不急于引入上传存储层与异步 job orchestration。
+
+### 4.2 `/config` 的作用
+帮助服务侧和调用侧快速确认当前默认数据目录、模型路径与索引前缀。
+
+### 4.3 后续生产化差距
+- 缺鉴权
+- 缺对象存储上传
+- 缺异步索引任务
+- 缺可观测性
+- 缺错误码与 SLA 规范
+
+---
+
+## 5. 细节附录
+
+### `/health`
+返回：
+```json
+{"status":"ok","service":"acr","version":"0.2.0"}
+```
+
+### `/config`
+返回：
 ```json
 {
-  "data_dir": "data/synthetic_v2",
-  "model_path": "data/models_v3/best_model.pt",
-  "output_dir": "data/index_v3",
-  "device": "cpu"
+  "data_dir":"data/synthetic_v2",
+  "model_path":"data/models_v3/best_model.pt",
+  "index_prefix":"data/index_v3/reference",
+  "device":"cpu"
 }
 ```
+
+
+## Sources
+- See `docs/references-and-sources.md` for the current source map.

@@ -10,6 +10,17 @@
 2. **Music Foundation Model 作为 backbone / teacher**
 3. **Band-split / band-aware 结构用于音乐频谱建模**
 
+
+## 1. 方向图
+
+```mermaid
+flowchart LR
+    A[2026 ACR / MIR SOTA] --> B[Neural AFP Robustness]
+    A --> C[Music Foundation Models]
+    A --> D[Band-aware Architectures]
+    A --> E[Data Balancing / Hard Negatives]
+```
+
 ## 1. Neural AFP 的更强实践
 
 ### Enhancing Neural Audio Fingerprint Robustness to Audio Degradation for Music Identification (2025)