Capture the current ACR delivery state so the next engineer can resume immediately

Constraint: Keep the live song-centric mainline and selected20 regression baseline aligned in docs and artifacts
Rejected: Deferring README/handoff consolidation | Would force the next session to reconstruct context again
Confidence: high
Scope-risk: narrow
Directive: Update CHANGELOG, roadmap checklist, and handoff docs together whenever onboarding or delivery facts change
Tested: /usr/local/miniconda3/bin/python /workspace/scripts/check_markdown_links.py --root /workspace/docs; selected20 baseline vs fresh report equality check; git diff --check; architect review APPROVED
Not-tested: No new runtime pipeline execution in this commit; relies on already-generated selected20 artifacts

+# ACR Workspace Handoff / 快速接手入口
+
+> 这份 README 面向新接手的开发人员：先告诉你**项目现在是什么、先看什么、先跑什么**，避免从零重新梳理。
+
+---
+
+## 1. 这个仓库现在在做什么
+
+当前主线是一个 **song-centric 音乐 ACR 系统**，重点有两条：
+
+1. **live PostgreSQL 主链**
+   - 把歌曲目录转换为 `song -> asset -> window -> fingerprint / embedding`
+   - 落到当前 4 表 schema：
+
+```text
+media_entity -> audio_object -> feature_fact -> set_membership
+```
+
+2. **selected20 小样本实战评测链**
+   - 用 20 首歌的专题数据评估当前方案在真实 query 条件下的 `song_id` 命中率
+   - 当前专题重点关注：
+     - `type_7`
+     - `type_16`
+
+一句话理解：
+
+> **数据库宿主链已经打通，当前要在不破坏主链的前提下继续优化 semantic lane，并用 selected20 做回归基线。**
+
+---
+
+## 2. 新同学先看哪些文档
+
+建议按这个顺序读：
+
+1. [docs/start-here.md](./docs/start-here.md)
+2. [docs/delivery-onepager.md](./docs/delivery-onepager.md)
+3. [docs/session-handoff.md](./docs/session-handoff.md)
+4. [docs/song-ingest-query-delivery.md](./docs/song-ingest-query-delivery.md)
+5. [docs/research-delivery-roadmap.md](./docs/research-delivery-roadmap.md)
+6. [docs/selected20_songid_eval.md](./docs/selected20_songid_eval.md)
+7. [docs/postgresql-data-model.md](./docs/postgresql-data-model.md)
+8. [docs/postgres_db_schema_samples.md](./docs/postgres_db_schema_samples.md)
+9. [docs/CHANGELOG.md](./docs/CHANGELOG.md)
+
+如果只想快速进入状态，至少看这 4 份：
+
+- [docs/start-here.md](./docs/start-here.md)
+- [docs/session-handoff.md](./docs/session-handoff.md)
+- [docs/research-delivery-roadmap.md](./docs/research-delivery-roadmap.md)
+- [docs/selected20_songid_eval.md](./docs/selected20_songid_eval.md)
+
+---
+
+## 3. 先跑什么
+
+### 3.1 live PostgreSQL 主链验证
+
+```bash
+cd /workspace
+/usr/local/miniconda3/bin/python acr-engine/scripts/run_songcentric_directory_pipeline_live.py \
+  --dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
+  --schema acr_songcentric_test \
+  --input-root acr-engine/data/songcentric_builder_smoke \
+  --output-dir acr-engine/data/pgvector_eval/music20
+```
+
+或：
+
+```bash
+acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.0.0.1:5432/d2'
+```
+
+### 3.2 selected20 回归评测
+
+```bash
+cd /workspace/acr-engine
+/usr/local/miniconda3/bin/python scripts/evaluate_selected20_songid_retrieval.py \
+  --downloads-dir /root/hikoon_song_files/output/selected_20_songs/downloads \
+  --reference-type 11 \
+  --query-types 1 7 12 16 \
+  --duration 8.0 \
+  --topk 3 \
+  --exact-weight 0.6 \
+  --semantic-weight 0.4 \
+  --output-json /workspace/acr-engine/data/local_eval/selected20_songid_eval_report.json \
+  --output-md /workspace/docs/selected20_songid_eval.md
+```
+
+---
+
+## 4. 当前你需要知道的核心事实
+
+### 主链事实
+
+- 4 表 song-centric schema 已作为当前默认口径
+- exact lane 已接入 `chromaprint_matcher`
+- semantic lane 已接入 `mert-v1-95m`
+- 当前 live 主链已有 fresh evidence
+
+### selected20 事实
+
+- baseline 报告已存在
+- fresh 重跑报告已存在
+- baseline 与 fresh 结果一致，当前专题已可作为回归基线
+
+当前 overall：
+
+| lane | count | top1 | top3 |
+|---|---:|---:|---:|
+| exact | 123 | 0.6016 | 0.8130 |
+| semantic | 123 | 0.4715 | 0.6016 |
+| fused | 123 | 0.6341 | 0.8537 |
+
+当前关键结论：
+
+- `type_1` 不是主要问题
+- `type_12` 表现已经较好
+- `type_7 / type_16` 仍是主要短板
+
+### 当前 blocker
+
+- MuQ 还没接通
+- 当前已知 blocker：
+  - `RuntimeError: operator torchvision::nms does not exist`
+
+---
+
+## 5. 建议下一步怎么做
+
+优先顺序：
+
+1. **守住当前主链与 selected20 基线**
+2. **先整理 hard-case 白名单**
+3. **再解锁 MuQ runtime**
+4. **最后把有效策略回灌到 PostgreSQL 在线主链**
+
+详细 roadmap 和 checklist 见：
+
+- [docs/research-delivery-roadmap.md](./docs/research-delivery-roadmap.md)
+
+---
+
+## 6. 代码和文档主要位置
+
+- 主代码：
+  - [acr-engine/](./acr-engine/)
+- 核心文档：
+  - [docs/](./docs/)
+- 运行脚本：
+  - [acr-engine/scripts/](./acr-engine/scripts/)
+- 会话/交付状态：
+  - [.omx/](./.omx/)
+
+---
+
+## 7. 如果你是新接手开发，最短路径
+
+只做这几步：
+
+1. 读 [docs/start-here.md](./docs/start-here.md)
+2. 读 [docs/session-handoff.md](./docs/session-handoff.md)
+3. 读 [docs/research-delivery-roadmap.md](./docs/research-delivery-roadmap.md)
+4. 跑一次主链验证
+5. 跑一次 selected20 回归
+
+这样基本就能在 10~20 分钟内进入当前上下文。

+# Selected 20 Songs 实战检索评测
+
+- 数据目录：`/root/hikoon_song_files/output/selected_20_songs/downloads`
+- reference：`type_11`
+- queries：`type_1, type_7, type_12, type_16`
+- 当前方案：`chromaprint_matcher + mert-v1-95m`
+- 语义截断时长：`8.0s`
+- reference 文件数：`24`
+- query 文件数：`123`
+
+## 1. 总体结果
+
+| lane | count | top1 | top3 |
+|---|---:|---:|---:|
+| exact | 123 | 0.6016 | 0.8130 |
+| semantic | 123 | 0.4715 | 0.6016 |
+| fused | 123 | 0.6341 | 0.8537 |
+
+## 2. 分 query type 结果
+
+| query_type | lane | count | top1 | top3 |
+|---|---|---:|---:|---:|
+| type_1 | exact | 21 | 1.0000 | 1.0000 |
+| type_1 | semantic | 21 | 1.0000 | 1.0000 |
+| type_1 | fused | 21 | 1.0000 | 1.0000 |
+| type_7 | exact | 41 | 0.4146 | 0.7073 |
+| type_7 | semantic | 41 | 0.1707 | 0.3902 |
+| type_7 | fused | 41 | 0.4390 | 0.7561 |
+| type_12 | exact | 23 | 0.8261 | 0.9130 |
+| type_12 | semantic | 23 | 1.0000 | 1.0000 |
+| type_12 | fused | 23 | 0.9130 | 1.0000 |
+| type_16 | exact | 38 | 0.4474 | 0.7632 |
+| type_16 | semantic | 38 | 0.1842 | 0.3684 |
+| type_16 | fused | 38 | 0.4737 | 0.7895 |
+
+## 3. 失败样例（fused rank != 1）
+
+- `type_7` / true=`572816` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/572816/type_7/三军令（副歌版）.mp3` / top1=`614397`
+- `type_7` / true=`604814` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/604814/type_7/偏差（剪辑版2）-吉鹏泽.wav` / top1=`614397`
+- `type_7` / true=`604814` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/604814/type_7/偏差（剪辑版3）-吉鹏泽.wav` / top1=`614397`
+- `type_7` / true=`643015` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/643015/type_7/置念 抖音推广音频.wav` / top1=`637559`
+- `type_7` / true=`656394` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/656394/type_7/把你宠坏-推广片段.wav` / top1=`614740`
+- `type_7` / true=`657848` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/657848/type_7/小神仙 主歌剪-1.mp3` / top1=`614397`
+- `type_7` / true=`659300` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/659300/type_7/推广片段2.WAV` / top1=`614397`
+- `type_7` / true=`675118` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675118/type_7/敲冰求火片段1.1x.wav` / top1=`614397`
+- `type_7` / true=`675118` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675118/type_7/敲冰求火片段_2.wav` / top1=`614397`
+- `type_7` / true=`675406` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675406/type_7/2.mp3` / top1=`614397`
+
+## 4. 结论
+
+- `exact` 代表当前指纹链路单独表现。
+- `semantic` 代表当前 MERT 单独表现。
+- `fused` 代表当前版权保护场景里更接近实战的合并结果。

+#!/usr/bin/env /usr/local/miniconda3/bin/python
+from __future__ import annotations
+
+import argparse
+import json
+from collections import defaultdict
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+import librosa
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[1]
+import sys
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.engines.chromaprint_matcher import ChromaprintMatcher, load_audio_mono
+from scripts.enrich_songcentric_manifest_with_local_features import load_mert_runtime
+
+
+def parse_args() -> argparse.Namespace:
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--downloads-dir', required=True)
+    ap.add_argument('--reference-type', type=int, default=11)
+    ap.add_argument('--query-types', nargs='+', type=int, default=[1, 7, 12, 16])
+    ap.add_argument('--duration', type=float, default=8.0)
+    ap.add_argument('--topk', type=int, default=3)
+    ap.add_argument('--exact-weight', type=float, default=0.6)
+    ap.add_argument('--semantic-weight', type=float, default=0.4)
+    ap.add_argument('--output-json', required=True)
+    ap.add_argument('--output-md', required=True)
+    return ap.parse_args()
+
+
+def audio_files(path: Path) -> List[Path]:
+    if not path.exists():
+        return []
+    return sorted([p for p in path.iterdir() if p.is_file()])
+
+
+def collect_dataset(downloads_dir: Path, reference_type: int, query_types: List[int]) -> tuple[list[dict], list[dict]]:
+    references: list[dict] = []
+    queries: list[dict] = []
+    for song_dir in sorted([p for p in downloads_dir.iterdir() if p.is_dir()]):
+        song_id = song_dir.name
+        for ref in audio_files(song_dir / f'type_{reference_type}'):
+            references.append({'song_id': song_id, 'type': reference_type, 'path': str(ref)})
+        for qtype in query_types:
+            for q in audio_files(song_dir / f'type_{qtype}'):
+                queries.append({'song_id': song_id, 'type': qtype, 'path': str(q)})
+    return references, queries
+
+
+def load_semantic_embedding(path: str, duration: float) -> np.ndarray:
+    rt = load_mert_runtime()
+    torch = rt['torch']
+    sr = int(rt['sample_rate'])
+    y, _ = librosa.load(path, sr=sr, mono=True, duration=duration)
+    if y.size == 0:
+        raise ValueError(f'empty audio: {path}')
+    inputs = rt['feature_extractor'](y.astype(np.float32), sampling_rate=sr, return_tensors='pt')
+    with torch.no_grad():
+        outputs = rt['model'](**inputs)
+    emb = outputs.last_hidden_state.mean(dim=1).squeeze(0).cpu().numpy().astype(np.float32)
+    norm = np.linalg.norm(emb)
+    if norm > 0:
+        emb = emb / norm
+    return emb
+
+
+def normalize_score_pairs(score_pairs: List[Tuple[str, float]]) -> Dict[str, float]:
+    if not score_pairs:
+        return {}
+    vals = np.asarray([float(x[1]) for x in score_pairs], dtype=np.float32)
+    ids = [x[0] for x in score_pairs]
+    if vals.size == 1:
+        return {ids[0]: 1.0}
+    vmin = float(vals.min())
+    vmax = float(vals.max())
+    if abs(vmax - vmin) < 1e-12:
+        return {sid: 1.0 for sid in ids}
+    norm = (vals - vmin) / (vmax - vmin)
+    return {sid: float(v) for sid, v in zip(ids, norm)}
+
+
+def topk_from_scores(score_map: Dict[str, float], topk: int) -> List[Dict]:
+    items = sorted(score_map.items(), key=lambda kv: kv[1], reverse=True)[:topk]
+    return [{'rank': idx + 1, 'song_id': sid, 'score': float(score)} for idx, (sid, score) in enumerate(items)]
+
+
+def rank_of(song_id: str, ranked: List[Dict], default_rank: int) -> int:
+    for item in ranked:
+        if item['song_id'] == song_id:
+            return int(item['rank'])
+    return default_rank
+
+
+def build_reference_assets(references: list[dict], duration: float):
+    matcher = ChromaprintMatcher(sr=16000)
+    ref_song_to_embeddings: dict[str, list[np.ndarray]] = defaultdict(list)
+    for ref in references:
+        y, _ = load_audio_mono(ref['path'], sr=matcher.sr)
+        matcher.index_song(ref['song_id'], y)
+        emb = load_semantic_embedding(ref['path'], duration=duration)
+        ref_song_to_embeddings[ref['song_id']].append(emb)
+    ref_song_embeddings: dict[str, np.ndarray] = {}
+    for song_id, embs in ref_song_to_embeddings.items():
+        mat = np.vstack(embs)
+        mean_emb = mat.mean(axis=0)
+        norm = np.linalg.norm(mean_emb)
+        if norm > 0:
+            mean_emb = mean_emb / norm
+        ref_song_embeddings[song_id] = mean_emb.astype(np.float32)
+    return matcher, ref_song_embeddings
+
+
+def evaluate(references: list[dict], queries: list[dict], duration: float, topk: int, exact_weight: float, semantic_weight: float) -> dict:
+    matcher, ref_song_embeddings = build_reference_assets(references, duration=duration)
+    ref_song_ids = sorted(ref_song_embeddings.keys())
+    ref_matrix = np.vstack([ref_song_embeddings[sid] for sid in ref_song_ids]).astype(np.float32)
+
+    results = []
+    by_type: dict[int, list[dict]] = defaultdict(list)
+    lane_rank_lists = {
+        'exact': [],
+        'semantic': [],
+        'fused': [],
+    }
+    for q in queries:
+        qy, _ = load_audio_mono(q['path'], sr=matcher.sr)
+        exact_pairs = matcher.match(qy, top_k=max(topk * 5, 20))
+        exact_norm = normalize_score_pairs(exact_pairs)
+
+        qemb = load_semantic_embedding(q['path'], duration=duration)
+        sims = ref_matrix @ qemb
+        semantic_pairs = [(sid, float(score)) for sid, score in zip(ref_song_ids, sims.tolist())]
+        semantic_norm = normalize_score_pairs(semantic_pairs)
+
+        fused_scores = {}
+        for sid in set(list(exact_norm.keys()) + list(semantic_norm.keys()) + ref_song_ids):
+            fused_scores[sid] = exact_weight * exact_norm.get(sid, 0.0) + semantic_weight * semantic_norm.get(sid, 0.0)
+
+        exact_ranked = topk_from_scores(exact_norm, topk)
+        semantic_ranked = topk_from_scores(semantic_norm, topk)
+        fused_ranked = topk_from_scores(fused_scores, topk)
+
+        default_rank = topk + 1
+        exact_rank = rank_of(q['song_id'], exact_ranked, default_rank)
+        semantic_rank = rank_of(q['song_id'], semantic_ranked, default_rank)
+        fused_rank = rank_of(q['song_id'], fused_ranked, default_rank)
+        lane_rank_lists['exact'].append(exact_rank)
+        lane_rank_lists['semantic'].append(semantic_rank)
+        lane_rank_lists['fused'].append(fused_rank)
+
+        item = {
+            'song_id': q['song_id'],
+            'query_type': q['type'],
+            'query_path': q['path'],
+            'exact_rank': exact_rank,
+            'semantic_rank': semantic_rank,
+            'fused_rank': fused_rank,
+            'exact_topk': exact_ranked,
+            'semantic_topk': semantic_ranked,
+            'fused_topk': fused_ranked,
+        }
+        results.append(item)
+        by_type[q['type']].append(item)
+
+    def metric_block(rank_list: list[int]) -> dict:
+        n = len(rank_list)
+        if n == 0:
+            return {'count': 0, 'top1': 0.0, 'top3': 0.0}
+        return {
+            'count': n,
+            'top1': sum(1 for r in rank_list if r == 1) / n,
+            'top3': sum(1 for r in rank_list if r <= 3) / n,
+        }
+
+    overall = {lane: metric_block(ranks) for lane, ranks in lane_rank_lists.items()}
+    per_type = {}
+    for qtype, items in sorted(by_type.items()):
+        per_type[qtype] = {
+            'exact': metric_block([x['exact_rank'] for x in items]),
+            'semantic': metric_block([x['semantic_rank'] for x in items]),
+            'fused': metric_block([x['fused_rank'] for x in items]),
+        }
+
+    failed_fused = [x for x in results if x['fused_rank'] != 1]
+    failed_fused.sort(key=lambda x: (x['query_type'], x['fused_rank'], x['song_id'], x['query_path']))
+
+    return {
+        'reference_count': len(references),
+        'query_count': len(queries),
+        'reference_song_count': len(ref_song_ids),
+        'query_type_counts': {str(k): len(v) for k, v in sorted(by_type.items())},
+        'weights': {'exact': exact_weight, 'semantic': semantic_weight},
+        'overall': overall,
+        'per_type': per_type,
+        'failed_fused_examples': failed_fused[:20],
+        'results': results,
+    }
+
+
+def render_md(report: dict, downloads_dir: Path, reference_type: int, query_types: List[int], duration: float) -> str:
+    lines = []
+    lines.append('# Selected 20 Songs 实战检索评测')
+    lines.append('')
+    lines.append(f'- 数据目录：`{downloads_dir}`')
+    lines.append(f'- reference：`type_{reference_type}`')
+    lines.append(f'- queries：`{", ".join(f"type_{x}" for x in query_types)}`')
+    lines.append('- 当前方案：`chromaprint_matcher + mert-v1-95m`')
+    lines.append(f'- 语义截断时长：`{duration:.1f}s`')
+    lines.append(f"- reference 文件数：`{report['reference_count']}`")
+    lines.append(f"- query 文件数：`{report['query_count']}`")
+    lines.append('')
+    lines.append('## 1. 总体结果')
+    lines.append('')
+    lines.append('| lane | count | top1 | top3 |')
+    lines.append('|---|---:|---:|---:|')
+    for lane in ['exact', 'semantic', 'fused']:
+        m = report['overall'][lane]
+        lines.append(f"| {lane} | {m['count']} | {m['top1']:.4f} | {m['top3']:.4f} |")
+    lines.append('')
+    lines.append('## 2. 分 query type 结果')
+    lines.append('')
+    lines.append('| query_type | lane | count | top1 | top3 |')
+    lines.append('|---|---|---:|---:|---:|')
+    for qtype, block in report['per_type'].items():
+        for lane in ['exact', 'semantic', 'fused']:
+            m = block[lane]
+            lines.append(f"| type_{qtype} | {lane} | {m['count']} | {m['top1']:.4f} | {m['top3']:.4f} |")
+    lines.append('')
+    lines.append('## 3. 失败样例（fused rank != 1）')
+    lines.append('')
+    if not report['failed_fused_examples']:
+        lines.append('- 无，fused 全部 top1 正确。')
+    else:
+        for item in report['failed_fused_examples'][:10]:
+            lines.append(
+                f"- `type_{item['query_type']}` / true=`{item['song_id']}` / fused_rank=`{item['fused_rank']}` / file=`{item['query_path']}` / top1=`{item['fused_topk'][0]['song_id'] if item['fused_topk'] else 'NA'}`"
+            )
+    lines.append('')
+    lines.append('## 4. 结论')
+    lines.append('')
+    lines.append('- `exact` 代表当前指纹链路单独表现。')
+    lines.append('- `semantic` 代表当前 MERT 单独表现。')
+    lines.append('- `fused` 代表当前版权保护场景里更接近实战的合并结果。')
+    return '\n'.join(lines) + '\n'
+
+
+def main() -> int:
+    args = parse_args()
+    downloads_dir = Path(args.downloads_dir).resolve()
+    refs, queries = collect_dataset(downloads_dir, args.reference_type, args.query_types)
+    report = evaluate(
+        references=refs,
+        queries=queries,
+        duration=args.duration,
+        topk=args.topk,
+        exact_weight=args.exact_weight,
+        semantic_weight=args.semantic_weight,
+    )
+    out_json = Path(args.output_json)
+    out_md = Path(args.output_md)
+    out_json.parent.mkdir(parents=True, exist_ok=True)
+    out_md.parent.mkdir(parents=True, exist_ok=True)
+    report.update({
+        'downloads_dir': str(downloads_dir),
+        'reference_type': args.reference_type,
+        'query_types': args.query_types,
+        'duration_sec': args.duration,
+        'topk': args.topk,
+        'solution': 'chromaprint_matcher + mert-v1-95m',
+    })
+    out_json.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding='utf-8')
+    out_md.write_text(render_md(report, downloads_dir, args.reference_type, args.query_types, args.duration), encoding='utf-8')
+    print(json.dumps({
+        'output_json': str(out_json),
+        'output_md': str(out_md),
+        'overall': report['overall'],
+        'per_type': report['per_type'],
+        'query_count': report['query_count'],
+        'reference_count': report['reference_count'],
+    }, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

 # Changelog
 
 ## 2026-06-04
+- 继续收紧 `docs/README.md` 的默认接手路径表达：除了保留 `delivery-onepager.md` 在阅读顺序中的位置外，又显式增加 `start-here -> delivery-onepager -> session-handoff -> song-ingest-query-delivery` 的主路径说明，避免入口顺序仍被误读。
+- 新增 `docs/delivery-onepager.md`，把当前 PostgreSQL 主链、selected20 基线、最短启动命令、fresh evidence 与下一步动作再压缩成一页交付摘要，方便外部同事或新 session 先快速接手。
+- 更新 `docs/README.md`、`docs/start-here.md` 与 `docs/session-handoff.md`，把 one-pager 接入默认阅读顺序，形成 “one-pager -> handoff -> runbook” 的精炼阅读路径。
+
+## 2026-06-04
+- 新增 `docs/song-ingest-query-delivery.md`，把当前仓库里“歌曲目录 -> manifest -> window/features -> PostgreSQL import -> selected20 查询评测 -> 交付产物”的完整链路、操作命令、产物位置、验证点收敛成一份端到端操作手册。
+- 更新 `docs/README.md`、`docs/start-here.md` 与 `docs/session-handoff.md`，把这份端到端手册接入默认阅读路径，方便新 session 或交付接手时直接定位完整链路说明。
+
+## 2026-06-04
+- 新增仓库根 `README.md`，作为新接手开发人员的快速入口：集中说明“项目当前在做什么、先看哪些核心文档、先跑哪些命令、当前已知事实与 blocker、下一步建议顺序”，并把核心文档链路全部串起来。
+- 根据后续 architect 复核继续修正 `docs/start-here.md` 的入口计数错误：当前实际列出 `8` 份文档，因此把“只读这 7 份文档”更正为“只读这 8 份文档”，避免交付入口文案继续误导。
+- 更新 `docs/research-delivery-roadmap.md` 的 checklist 表述，把“docs 已形成可唤起交付链路”明确扩展到 `root README + docs README + handoff/roadmap/selected20` 整体入口链。
+- 根据 architect 复核修正 `docs/start-here.md` 的入口计数错误：文中实际列出 `7` 份文档，因此把“只读这 6 份文档”更正为“只读这 7 份文档”，避免交付入口文案与真实列表不一致。
+- 在 `docs/research-delivery-roadmap.md` 增加“当前进度快照（2026-06-04）”，把 Phase A~E 当前状态显式化，避免后续 session 只看到 roadmap 而不知道已经推进到哪里。
+- 更新 roadmap checklist：把“docs 已形成可唤起交付链路”和 selected20 的固定入口 / `json+markdown` 输出 / 结果解读文档化标记为已完成，同时保留 hard-case 白名单、MuQ 接入、在线主链回灌为后续待办。
+- 新增 [research-delivery-roadmap.md](./research-delivery-roadmap.md)，把当前研究成果、后续 roadmap、阶段 checklist 和建议任务包集中固化成一份可直接唤起的交付文档。
+- 更新 `docs/README.md`、`docs/start-here.md` 与 `docs/session-handoff.md` 的入口链路，加入 `research-delivery-roadmap.md` 与 `selected20_songid_eval.md`，让后续 session 能从“当前成果 + 后续任务构想”直接接续。
+- 在 `docs/session-handoff.md` 补充 `selected20_songid_eval_report_fresh.json` 与 fresh 重跑一致性的事实，明确 selected20 当前已具备可重复的小样本回归基线属性。
+- 基于现有 `.omx` 记录与产物，补齐 `selected20` 实战评测交付：确认 `acr-engine/data/local_eval/selected20_songid_eval_report.json` 与 `docs/selected20_songid_eval.md` 对应同一轮 20 首歌 song-level 评测，口径为 `type_11` 作为 reference、`type_1/7/12/16` 作为 query、`chromaprint_matcher + mert-v1-95m` 双 lane 融合。
+- 固化 `selected20` 当前实测结论：总计 `123` 条 query，`fused top1=0.6341 / top3=0.8537`，优于单独 `exact top1=0.6016 / top3=0.8130` 与 `semantic top1=0.4715 / top3=0.6016`；说明当前版权保护小样本场景下，融合优于单 lane。
+- 固化 `selected20` 的分类型判断：`type_1` 已满分；`type_12` 由 MERT 单 lane 最强（`top1=1.0`），但融合后更稳；当前主要短板仍集中在 `type_7` 与 `type_16`，其中 `type_7 fused top1=0.4390 / top3=0.7561`、`type_16 fused top1=0.4737 / top3=0.7895`。
+- 补充交付物说明：`docs/selected20_songid_eval_repro.md` 已给出复现命令与输出物位置，当前 20 首歌专题可作为后续接入 MuQ 或迁移 PostgreSQL song-centric 主链前的小样本回归基线。
+
+## 2026-06-04
 - 继续收敛文档到当前 live 主链口径：补齐 `feature_fact.object_id -> audio_object(window)`、`window.parent_object_id -> asset`、`feature_fact.song_id -> media_entity(song)` 的绑定说明，并新增 manifest/SQL 双样例，专门回答 Phase-1 开源模型集合应该如何落地存储以及 feature 与 audio object 如何关联。
 - 修正 `docs/session-handoff.md` 中关于 semantic lane 的旧状态残留，统一到当前真实事实：live 默认已落 `chromaprint_matcher + mert-v1-95m`，MuQ 仍是下一阶段 challenger。
 - 继续补充可复核的 live 样例：把 `feature_id = 34 -> window_id = 22 -> asset_id = 20 -> song_beta` 的真实 PostgreSQL 回溯结果写入 handoff 与 schema sample 文档，方便下次 session 直接人工复核绑定链路。

@@ -9,10 +9,20 @@
 新同学接手顺序：
 
 1. [start-here.md](./start-here.md)
-2. [session-handoff.md](./session-handoff.md)
-3. [postgresql-data-model.md](./postgresql-data-model.md)
-4. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
-5. [CHANGELOG.md](./CHANGELOG.md)
+2. [delivery-onepager.md](./delivery-onepager.md)
+3. [session-handoff.md](./session-handoff.md)
+4. [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
+5. [research-delivery-roadmap.md](./research-delivery-roadmap.md)
+6. [selected20_songid_eval.md](./selected20_songid_eval.md)
+7. [postgresql-data-model.md](./postgresql-data-model.md)
+8. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
+9. [CHANGELOG.md](./CHANGELOG.md)
+
+推荐把前 4 份当作默认接手主路径：
+
+```text
+start-here -> delivery-onepager -> session-handoff -> song-ingest-query-delivery
+```
 
 ---
 
@@ -65,14 +75,18 @@ acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.
 - `semantic_runtime_available = true`
 - `semantic_runtime_ready_count = 5`
 - `semantic_fallback_count = 0`
-- `import_counts.feature_fact = 29
+- `import_counts.feature_fact = 34`
 
 ---
 
 ## 4. 当前保留文档分别解决什么
 
 - [start-here.md](./start-here.md)：新同学 10 分钟接手入口
+- [delivery-onepager.md](./delivery-onepager.md)：对外/跨团队交付时先发这一页
 - [session-handoff.md](./session-handoff.md)：下次启动从哪里继续
+- [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)：歌曲从目录入库到查询/评测/交付的完整操作手册
+- [research-delivery-roadmap.md](./research-delivery-roadmap.md)：当前研究交付、roadmap、checklist
+- [selected20_songid_eval.md](./selected20_songid_eval.md)：20 首专题评测摘要
 - [postgresql-data-model.md](./postgresql-data-model.md)：表设计、字段语义、feature 与 audio_object 的绑定关系、Phase-1 模型落库口径
 - [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)：DDL、manifest/SQL 样例、典型查询链路、真实存储示例
 - [CHANGELOG.md](./CHANGELOG.md)：变更历史

+# ACR 交付一页纸
+
+> 给新接手同事的最短摘要：先看这页，再决定要不要展开到完整 runbook。
+
+---
+
+## 1. 现在已经交付了什么
+
+当前已经有两条可用主线：
+
+1. **PostgreSQL song-centric 主链**
+   - 歌曲目录 -> manifest -> window -> fingerprint/embedding -> PostgreSQL
+2. **selected20 小样本评测主线**
+   - 20 首歌专题 -> exact / semantic / fused song-level 命中率评测
+
+一句话：
+
+> **数据库宿主链已经打通，20 首歌回归基线已经固定；下一步重点不是重做方案，而是在当前基线上继续补 semantic challenger。**
+
+---
+
+## 2. 当前默认模型
+
+逻辑语义：
+
+```text
+song -> asset -> window -> fingerprint / embedding
+```
+
+物理落表：
+
+```text
+media_entity -> audio_object -> feature_fact -> set_membership
+```
+
+---
+
+## 3. 最短启动命令
+
+```bash
+cd /workspace
+/usr/local/miniconda3/bin/python acr-engine/scripts/run_songcentric_directory_pipeline_live.py \
+  --dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
+  --schema acr_songcentric_test \
+  --input-root acr-engine/data/songcentric_builder_smoke \
+  --output-dir acr-engine/data/pgvector_eval/music20
+```
+
+---
+
+## 4. 当前 fresh evidence
+
+主链当前结果：
+- `song_count = 2`
+- `asset_count = 2`
+- `window_count = 5`
+- `matcher_fingerprint_count = 5`
+- `semantic_runtime_ready_count = 5`
+- `import_counts = media_entity:9 / audio_object:22 / feature_fact:34 / set_membership:9`
+
+说明：
+- exact lane 已接 `chromaprint_matcher`
+- semantic lane 已接 `mert-v1-95m`
+- 当前 5 个 window 没走 fallback
+
+---
+
+## 5. selected20 当前结论
+
+- query 总数：`123`
+- exact：`top1=0.6016 / top3=0.8130`
+- semantic：`top1=0.4715 / top3=0.6016`
+- fused：`top1=0.6341 / top3=0.8537`
+
+关键判断：
+- `type_1` 已打满
+- `type_12` 很强
+- 主要短板仍是 `type_7 / type_16`
+
+---
+
+## 6. 你应该先看哪份文档
+
+### 如果你只想快速接手
+1. [start-here.md](./start-here.md)
+2. [delivery-onepager.md](./delivery-onepager.md)
+3. [session-handoff.md](./session-handoff.md)
+
+### 如果你要看完整操作链路
+- [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
+
+### 如果你要看专题评测
+- [selected20_songid_eval.md](./selected20_songid_eval.md)
+- [selected20_songid_eval_repro.md](./selected20_songid_eval_repro.md)
+
+---
+
+## 7. 现在最重要的下一步
+
+1. 保住当前 4 表主链不回退
+2. 接入 MuQ challenger
+3. 每次变更后复跑 selected20
+4. 重点盯 `type_7 / type_16`
+
+---
+
+## 8. 相关文档
+
+- [README.md](./README.md)
+- [start-here.md](./start-here.md)
+- [session-handoff.md](./session-handoff.md)
+- [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
+- [research-delivery-roadmap.md](./research-delivery-roadmap.md)
+- [CHANGELOG.md](./CHANGELOG.md)

+# Research Delivery / 当前研究交付与 Roadmap
+
+> 目标：把当前已经验证过的研究成果、下一阶段待办、以及可执行 checklist 固化成一份可直接唤起的交付文档。
+
+---
+
+## 1. 当前交付了什么
+
+当前已经形成两条可复用主线：
+
+1. **song-centric + 4 表 PostgreSQL 主链**
+   - 完整操作手册：[song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
+2. **selected20（20 首歌）文件级小样本实战评测主线**
+
+一句话总结：
+
+> **数据库宿主链已经打通，20 首专题评测基线也已经建立；下一阶段不是重新争论总方案，而是在当前基线上做 challenger 扩展与 hard-case 改善。**
+
+---
+
+## 2. 当前研究成果摘要
+
+### 2.1 主数据 / 宿主链成果
+
+当前默认物理模型：
+
+```text
+media_entity -> audio_object -> feature_fact -> set_membership
+```
+
+当前默认逻辑语义：
+
+```text
+song -> asset -> window -> fingerprint / embedding
+```
+
+已真实验证：
+
+- live PostgreSQL schema 可建表
+- 真实目录 -> manifest -> import 可跑通
+- `windows[].features[]` 可直接导入 `feature_fact`
+- exact lane 已接 `chromaprint_matcher`
+- semantic lane 已接 `mert-v1-95m`
+- 当前主链在 live PostgreSQL 上已有 fresh evidence
+
+### 2.2 selected20（20 首歌）专题成果
+
+专题数据目录：
+
+- `/root/hikoon_song_files/output/selected_20_songs/downloads`
+
+当前专题方案：
+
+- exact：`chromaprint_matcher`
+- semantic：`mert-v1-95m`
+- fused：`0.6 * exact + 0.4 * semantic`
+
+当前 fresh 结果：
+
+| lane | count | top1 | top3 |
+|---|---:|---:|---:|
+| exact | 123 | 0.6016 | 0.8130 |
+| semantic | 123 | 0.4715 | 0.6016 |
+| fused | 123 | 0.6341 | 0.8537 |
+
+分类型结论：
+
+| query_type | count | 当前判断 |
+|---|---:|---|
+| `type_1` | 21 | 已打满，当前不是主要矛盾 |
+| `type_7` | 41 | 主要短板之一，混淆明显 |
+| `type_12` | 23 | 当前表现很好，semantic 单 lane 已打满 |
+| `type_16` | 38 | 另一主要短板，仍需重点优化 |
+
+一句话判断：
+
+> **当前融合结果优于单独 semantic，也略优于单独 exact；实战瓶颈主要在 `type_7 / type_16`。**
+
+---
+
+## 3. 当前 blocker
+
+### 3.1 语义 challenger blocker
+
+MuQ 当前还没接入成功。
+
+已确认事实：
+
+- 候选：`OpenMuQ/MuQ-large-msd-iter`
+- `muq` 包已安装
+- 当前 host 上 `import muq` 仍被 `RuntimeError: operator torchvision::nms does not exist` 阻塞
+
+所以当前 blocker 不是“还没想到做什么”，而是：
+
+> **MERT baseline 已可用，但 MuQ challenger 受 `torchvision` 兼容问题阻塞。**
+
+### 3.2 效果 blocker
+
+从 selected20 看，当前真正的效果短板不是：
+
+- `type_1`
+- `type_12`
+
+而是：
+
+- `type_7`
+- `type_16`
+
+这意味着下一阶段不能只盯 overall，必须盯 hard-case 的分类型提升。
+
+---
+
+## 4. 后续 Roadmap（建议版）
+
+### 当前进度快照（2026-06-04）
+
+| Phase | 状态 | 当前判断 |
+|---|---|---|
+| Phase A：冻结当前基线 | 进行中 | 主链与 selected20 基线都已形成，fresh 重跑一致性也已确认 |
+| Phase B：接入 MuQ challenger | 未开始 | 仍被 `torchvision::nms` runtime blocker 卡住 |
+| Phase C：selected20 回归闸门 | 进行中 | 已有脚本、JSON、Markdown 摘要，但还未完全制度化成固定门禁 |
+| Phase D：专题策略回灌在线主链 | 未开始 | 还没有把 selected20 的 hard-case 分析映射回 PostgreSQL 查询侧 |
+| Phase E：更大规模评测与工程化 | 未开始 | 当前仍以 selected20 为核心小样本基线 |
+
+### Phase A：冻结当前基线
+
+目标：
+
+- 守住当前 song-centric 4 表主链
+- 守住 selected20 小样本回归基线
+
+完成标准：
+
+- `run_songcentric_directory_pipeline_live.py` 继续稳定可跑
+- `selected20_songid_eval_report.json` 继续作为对照基线
+
+### Phase B：接入 MuQ challenger
+
+目标：
+
+- 在不破坏现有 MERT baseline 的前提下，加一条 MuQ semantic challenger lane
+
+完成标准：
+
+- `import muq` / `from muq import MuQ` 可成功
+- runner/评测脚本能产出 MuQ embedding
+- PostgreSQL 或文件级评测里能看到独立 MuQ 指标
+
+关键评估：
+
+- MuQ 单 lane 是否优于 MERT
+- MuQ + exact 的 fused 是否改善 `type_7 / type_16`
+
+### Phase C：以 selected20 作为回归闸门
+
+目标：
+
+- 把 selected20 固化成每次 encoder / fusion 变更后的回归集
+
+完成标准：
+
+- 每次变更后都能直接复跑 selected20
+- 报告中必须比较：
+  - overall
+  - per-type
+  - 失败样例
+
+### Phase D：把小样本专题映射回在线主链
+
+目标：
+
+- 把 selected20 的有效策略回灌到 PostgreSQL / song-centric 主链
+- 交付/接手时优先参考 [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
+
+完成标准：
+
+- `feature_fact` 中能区分不同 semantic challenger
+- 可以对同一批 query 比较 exact / MERT / MuQ / fused
+
+### Phase E：进入更大规模评测与工程化
+
+目标：
+
+- 从 selected20 扩展到更大的 reference / query 集
+- 明确生产级回归、巡检、落库与索引策略
+
+完成标准：
+
+- 有更大评测集
+- 有固定报表结构
+- 有稳定的主链/专题双回归机制
+
+---
+
+## 5. Checklist（下一阶段执行清单）
+
+### 5.1 基线保护 checklist
+
+- [x] 4 表 song-centric schema 已作为当前默认口径
+- [x] `chromaprint_matcher` 已接入 exact lane
+- [x] `mert-v1-95m` 已接入 semantic baseline
+- [x] selected20 已形成基线报告
+- [x] selected20 fresh 重跑结果与当前基线一致
+- [x] docs 已形成可唤起交付链路（root README / docs README / start-here / handoff / roadmap / selected20）
+- [ ] 把 selected20 失败样例沉淀成 hard-case 白名单
+
+### 5.2 MuQ 接入 checklist
+
+- [ ] 审计 `torch / torchvision / muq` 兼容矩阵
+- [ ] 解决 `torchvision::nms does not exist`
+- [ ] 在本机成功 `from muq import MuQ`
+- [ ] 在评测脚本中增加 MuQ lane
+- [ ] 产出 `MERT vs MuQ vs fused` 对比报告
+
+### 5.3 效果优化 checklist
+
+- [ ] 按 `type_7 / type_16` 汇总失败歌曲对
+- [ ] 统计最常见误判 top1 歌曲
+- [ ] 评估 fusion 权重是否仍应固定在 `0.6 / 0.4`
+- [ ] 尝试基于 hard-case 调整融合策略
+- [ ] 验证优化是否真正改善 `type_7 / type_16`
+
+### 5.4 工程化 checklist
+
+- [x] 让 selected20 评测成为固定入口命令
+- [x] 报告输出统一到 `json + markdown`
+- [x] 在 docs 里固定“怎么读结果 / 怎么继续”
+- [ ] 后续如果切 online path，保留该文件级评测作为快速回归集
+
+---
+
+## 6. 推荐下次启动顺序
+
+1. 先看 [session-handoff.md](./session-handoff.md)
+2. 再看 [selected20_songid_eval.md](./selected20_songid_eval.md)
+3. 再看本文件的 roadmap + checklist
+4. 决定是走：
+   - **MuQ 接入线**
+   - **selected20 hard-case 优化线**
+   - **PostgreSQL 在线回灌线**
+
+### 当前建议的下一步（按收益排序）
+
+1. **先做 hard-case 白名单**
+   - 把 `type_7 / type_16` 的失败样例整理成固定榜单
+2. **再做 MuQ runtime 解锁**
+   - 先解决 `torchvision::nms`，再做 challenger 对比
+3. **最后做主链回灌**
+   - 把 selected20 上确认有效的策略映射回 PostgreSQL 查询路径
+
+---
+
+## 7. 当前建议任务构想
+
+### 任务包 A：MuQ 解锁
+
+目标：
+- 打通 MuQ runtime
+
+产出：
+- 环境兼容记录
+- 可运行 MuQ smoke
+- 可落盘 MuQ embedding
+
+### 任务包 B：selected20 hard-case 分析
+
+目标：
+- 只盯 `type_7 / type_16`
+
+产出：
+- 失败歌曲对榜单
+- 常见误判榜单
+- 是否需要调整 fusion 的结论
+
+### 任务包 C：回归制度化
+
+目标：
+- 让 selected20 成为固定回归门禁
+
+产出：
+- 固定命令
+- 固定报告路径
+- 固定结果解读模板
+
+### 任务包 D：在线主链映射
+
+目标：
+- 把有效的专题结论映射回 PostgreSQL 主链
+
+产出：
+- 主链中的 challenger 标识
+- 可对比的落库数据
+- 在线/离线一致的评估视图
+
+---
+
+## 一句话交付结论
+
+> 当前最值得保护的研究资产不是“某个临时实验数字”，而是 **已经跑通的 4 表 song-centric 主链 + 已经成型的 selected20 小样本回归基线 + 明确的 MuQ / hard-case 后续路线图**。

+# Selected 20 Songs 实战检索评测
+
+> 完整入库/查询主链操作手册见 [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)；本页只负责 `selected20` 文件级实战评测摘要。
+
+- 数据目录：`/root/hikoon_song_files/output/selected_20_songs/downloads`
+- reference：`type_11`
+- queries：`type_1, type_7, type_12, type_16`
+- 当前方案：`chromaprint_matcher + mert-v1-95m`
+- 语义截断时长：`8.0s`
+- reference 文件数：`24`
+- query 文件数：`123`
+
+## 1. 总体结果
+
+| lane | count | top1 | top3 |
+|---|---:|---:|---:|
+| exact | 123 | 0.6016 | 0.8130 |
+| semantic | 123 | 0.4715 | 0.6016 |
+| fused | 123 | 0.6341 | 0.8537 |
+
+## 2. 分 query type 结果
+
+| query_type | lane | count | top1 | top3 |
+|---|---|---:|---:|---:|
+| type_1 | exact | 21 | 1.0000 | 1.0000 |
+| type_1 | semantic | 21 | 1.0000 | 1.0000 |
+| type_1 | fused | 21 | 1.0000 | 1.0000 |
+| type_7 | exact | 41 | 0.4146 | 0.7073 |
+| type_7 | semantic | 41 | 0.1707 | 0.3902 |
+| type_7 | fused | 41 | 0.4390 | 0.7561 |
+| type_12 | exact | 23 | 0.8261 | 0.9130 |
+| type_12 | semantic | 23 | 1.0000 | 1.0000 |
+| type_12 | fused | 23 | 0.9130 | 1.0000 |
+| type_16 | exact | 38 | 0.4474 | 0.7632 |
+| type_16 | semantic | 38 | 0.1842 | 0.3684 |
+| type_16 | fused | 38 | 0.4737 | 0.7895 |
+
+## 3. 失败样例（fused rank != 1）
+
+- `type_7` / true=`572816` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/572816/type_7/三军令（副歌版）.mp3` / top1=`614397`
+- `type_7` / true=`604814` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/604814/type_7/偏差（剪辑版2）-吉鹏泽.wav` / top1=`614397`
+- `type_7` / true=`604814` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/604814/type_7/偏差（剪辑版3）-吉鹏泽.wav` / top1=`614397`
+- `type_7` / true=`643015` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/643015/type_7/置念 抖音推广音频.wav` / top1=`637559`
+- `type_7` / true=`656394` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/656394/type_7/把你宠坏-推广片段.wav` / top1=`614740`
+- `type_7` / true=`657848` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/657848/type_7/小神仙 主歌剪-1.mp3` / top1=`614397`
+- `type_7` / true=`659300` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/659300/type_7/推广片段2.WAV` / top1=`614397`
+- `type_7` / true=`675118` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675118/type_7/敲冰求火片段1.1x.wav` / top1=`614397`
+- `type_7` / true=`675118` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675118/type_7/敲冰求火片段_2.wav` / top1=`614397`
+- `type_7` / true=`675406` / fused_rank=`2` / file=`/root/hikoon_song_files/output/selected_20_songs/downloads/675406/type_7/2.mp3` / top1=`614397`
+
+## 4. 结论
+
+- `exact` 代表当前指纹链路单独表现。
+- `semantic` 代表当前 MERT 单独表现。
+- `fused` 代表当前版权保护场景里更接近实战的合并结果。

+# Selected20 SongID 检索评测复现手册
+
+> 这份文档只覆盖 `selected20` 文件级回归评测；完整数据库主链与“歌曲入库 -> 查询 -> 交付”见 [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)。
+
+## 1. 目标
+
+验证目录：
+
+- `/root/hikoon_song_files/output/selected_20_songs/downloads`
+
+在当前方案下：
+
+- `reference = type_11`
+- `query = type_1 / type_7 / type_12 / type_16`
+- 目录名即 `song_id`
+
+检查实战里是否能够正确识别回对应 `song_id`。
+
+---
+
+## 2. 当前方案口径
+
+本专题默认评测的方案是：
+
+- exact lane：`chromaprint_matcher`
+- semantic lane：`mert-v1-95m`
+- fused：`0.6 * exact + 0.4 * semantic`
+
+说明：
+- `type_11` 视为无损 reference
+- `type_1/7/12/16` 视为 query
+- 最终评测目标是 song-level `song_id` 命中率
+
+---
+
+## 3. 目录结构假设
+
+每首歌结构类似：
+
+```text
+<downloads>/<song_id>/type_1/*
+<downloads>/<song_id>/type_7/*
+<downloads>/<song_id>/type_11/*
+<downloads>/<song_id>/type_12/*
+<downloads>/<song_id>/type_16/*
+```
+
+其中：
+- 目录名 `<song_id>` 就是 ground truth
+- `type_11` 至少 1 个文件
+- query type 可以多文件
+
+---
+
+## 4. 复现命令
+
+```bash
+cd /workspace/acr-engine
+/usr/local/miniconda3/bin/python scripts/evaluate_selected20_songid_retrieval.py \
+  --downloads-dir /root/hikoon_song_files/output/selected_20_songs/downloads \
+  --reference-type 11 \
+  --query-types 1 7 12 16 \
+  --duration 8.0 \
+  --topk 3 \
+  --exact-weight 0.6 \
+  --semantic-weight 0.4 \
+  --output-json /workspace/acr-engine/data/local_eval/selected20_songid_eval_report.json \
+  --output-md /workspace/docs/selected20_songid_eval.md
+```
+
+---
+
+## 5. 输出物
+
+### JSON 报告
+
+- `acr-engine/data/local_eval/selected20_songid_eval_report.json`
+
+包含：
+- overall top1/top3
+- per-type top1/top3
+- 每条 query 的 exact / semantic / fused 排名
+- 失败样例
+
+### Markdown 摘要
+
+- `docs/selected20_songid_eval.md`
+
+适合给研发、产品、算法同学直接阅读。
+
+---
+
+## 6. 评测逻辑
+
+### 6.1 reference 构建
+
+- 遍历每个 `song_id`
+- 读取 `type_11` 文件作为 reference
+- 同时建立：
+  - `chromaprint_matcher` 指纹索引
+  - `mert-v1-95m` song embedding
+
+### 6.2 query 评估
+
+对每个 query 文件：
+
+1. 走 exact：`chromaprint_matcher.match(...)`
+2. 走 semantic：MERT embedding 和 reference song embedding 相似度
+3. 融合：
+
+```text
+fused_score = 0.6 * exact_norm + 0.4 * semantic_norm
+```
+
+4. 输出 topk 候选
+5. 检查 true `song_id` 的 rank
+
+### 6.3 指标
+
+- `top1`：正确 song_id 是否排第 1
+- `top3`：正确 song_id 是否排前 3
+
+---
+
+## 7. 如何看结果
+
+优先看：
+
+1. overall
+2. per query type
+3. failed_fused_examples
+
+建议解释顺序：
+- exact 单独效果
+- semantic 单独效果
+- fused 是否优于单 lane
+- 哪些 type 是当前主要短板
+
+---
+
+## 8. 后续扩展
+
+如果后续接入 MuQ：
+- 可以在该脚本里增加 `muq` lane
+- 输出：`exact / mert / muq / fused`
+- 比较 `type_7 / type_12 / type_16` 是否改善
+
+如果后续切到 PostgreSQL：
+- 可以把当前文件级 query/reference 逻辑迁移为 `song -> asset -> window -> feature_fact`
+- 但这个专题脚本仍然保留，作为**小样本回归评测**基线

@@ -2,6 +2,8 @@
 
 > 目标：让下次启动的新 session 在 **3~10 分钟内** 知道从哪里开始。
 
+快速对外转交时，先发： [delivery-onepager.md](./delivery-onepager.md)
+
 ---
 
 ## 1. 下次启动先做什么
@@ -140,9 +142,11 @@ flowchart TD
 
 1. [README.md](./README.md)
 2. [start-here.md](./start-here.md)
-3. [postgresql-data-model.md](./postgresql-data-model.md)
-4. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
-5. [CHANGELOG.md](./CHANGELOG.md)
+3. [research-delivery-roadmap.md](./research-delivery-roadmap.md)
+4. [selected20_songid_eval.md](./selected20_songid_eval.md)
+5. [postgresql-data-model.md](./postgresql-data-model.md)
+6. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
+7. [CHANGELOG.md](./CHANGELOG.md)
 
 关键代码：
 - `acr-engine/sql/acr_pg_schema_songcentric_v1.sql`
@@ -152,6 +156,9 @@ flowchart TD
 - `acr-engine/scripts/import_songcentric_manifest_live.py`
 - `acr-engine/scripts/start_songcentric_shortest_path.sh`
 
+如果要完整看“歌曲怎么入库、怎么查询/评测、交付时要带哪些产物”，直接读：
+- [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
+
 ---
 
 ## 9. 下一步优先顺序
@@ -161,6 +168,58 @@ flowchart TD
 3. 保留 fallback 分支，不破坏当前 host 的可运行性
 4. 重新跑主链 runner，确认 semantic lane 有 fresh 证据
 
+## 9.1 Selected20（20 首歌）当前评估结论
+
+当前 `.omx` 记录对应的 20 首歌专题产物已经落在：
+
+- `acr-engine/data/local_eval/selected20_songid_eval_report.json`
+- `acr-engine/data/local_eval/selected20_songid_eval_report_fresh.json`
+- `docs/selected20_songid_eval.md`
+- `docs/selected20_songid_eval_repro.md`
+- `docs/research-delivery-roadmap.md`
+
+评测口径：
+- 数据目录：`/root/hikoon_song_files/output/selected_20_songs/downloads`
+- reference：`type_11`
+- query：`type_1 / type_7 / type_12 / type_16`
+- 评测目标：song-level `song_id` 命中率
+- 当前方案：`chromaprint_matcher + mert-v1-95m`
+- 融合口径：`0.6 * exact + 0.4 * semantic`
+
+当前实测汇总：
+
+| lane | count | top1 | top3 |
+|---|---:|---:|---:|
+| exact | 123 | 0.6016 | 0.8130 |
+| semantic | 123 | 0.4715 | 0.6016 |
+| fused | 123 | 0.6341 | 0.8537 |
+
+补充说明：
+
+- 2026-06-04 已做 fresh 重跑
+- `selected20_songid_eval_report_fresh.json` 与当前基线结果一致
+- 说明这份 20 首专题基线已具备可重复性，可直接作为后续 MuQ / fusion 变更的回归对照
+
+按 query type 看：
+
+| query_type | count | 结论 |
+|---|---:|---|
+| `type_1` | 21 | exact / semantic / fused 全部 `top1=1.0`，当前已打满 |
+| `type_7` | 41 | 当前最弱短板之一；`fused top1=0.4390 / top3=0.7561`，比单 semantic 好，但仍不够稳 |
+| `type_12` | 23 | 当前最好的一类之一；semantic 单 lane 已 `top1=1.0`，融合后 `top1=0.9130 / top3=1.0` |
+| `type_16` | 38 | 当前另一主要短板；`fused top1=0.4737 / top3=0.7895`，仅小幅优于 exact |
+
+一句话判断：
+
+> **这 20 首歌专题里，当前融合链路已经明显优于单独 semantic，也略优于单独 exact；但真正限制实战效果的仍是 `type_7 / type_16` 这类混淆/改写 query，而不是 `type_1` 或 `type_12`。**
+
+因此下次如果继续推进这个专题，优先顺序应是：
+1. 先把 `selected20_songid_eval_report.json` 当作小样本回归基线
+2. 接入 MuQ challenger 后直接复跑这份专题
+3. 重点比较 `type_7 / type_16` 是否提升，而不是只看 overall
+4. 如果后续切 PostgreSQL online path，也保留这份文件级评测作为快速回归基线
+5. 继续按 [research-delivery-roadmap.md](./research-delivery-roadmap.md) 的 roadmap + checklist 拆下一阶段任务
+
 ---
 
 ## 一句话 handoff

+# Song Ingest → Query → Delivery 完整操作手册
+
+> 这份文档专门回答：**歌曲是怎么从目录/文件进入当前系统，再怎么被查询/评估，最后交付哪些产物与验证证据。**
+
+---
+
+## 1. 适用范围
+
+当前仓库里有两条你必须区分的链路：
+
+1. **live PostgreSQL song-centric 主链**
+   - 目标：把真实歌曲目录导入当前 4 表 schema，并把 `window + fingerprint + embedding` 落到 PostgreSQL
+   - 入口脚本：
+     - `acr-engine/scripts/run_songcentric_directory_pipeline_live.py`
+     - `acr-engine/scripts/build_songcentric_manifest_from_directory.py`
+     - `acr-engine/scripts/enrich_songcentric_manifest_with_local_features.py`
+     - `acr-engine/scripts/import_songcentric_manifest_live.py`
+
+2. **selected20 文件级实战评测链**
+   - 目标：在 20 首歌专题上评估当前 `exact / semantic / fused` 的 song-level 命中率
+   - 入口脚本：
+     - `acr-engine/scripts/evaluate_selected20_songid_retrieval.py`
+
+这两条链路都重要：
+- **PostgreSQL 主链**负责“怎么入库、怎么绑定、怎么回查 song_id”
+- **selected20 评测链**负责“当前方案实战到底效果如何”
+
+---
+
+## 2. 当前默认数据模型
+
+逻辑语义：
+
+```text
+song -> asset -> window -> fingerprint / embedding
+```
+
+物理落表：
+
+```text
+media_entity -> audio_object -> feature_fact -> set_membership
+```
+
+绑定规则：
+- `media_entity`：song 主体
+- `audio_object(object_type='asset')`：原始音频文件
+- `audio_object(object_type='window')`：切片窗口
+- `feature_fact.object_id -> audio_object.object_id`：feature 绑定 window
+- `audio_object.parent_object_id`：window 回到 asset
+- `feature_fact.song_id -> media_entity.entity_id`：song-level 回查与聚合
+- `set_membership`：reference/eval/hot set 路由
+
+如果要看字段级解释，配套文档：
+- [postgresql-data-model.md](./postgresql-data-model.md)
+- [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
+
+---
+
+## 3. live PostgreSQL song-centric 主链：从歌曲目录到入库
+
+### 3.1 一条命令跑完整主链
+
+```bash
+cd /workspace
+/usr/local/miniconda3/bin/python acr-engine/scripts/run_songcentric_directory_pipeline_live.py \
+  --dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2' \
+  --schema acr_songcentric_test \
+  --input-root acr-engine/data/songcentric_builder_smoke \
+  --output-dir acr-engine/data/pgvector_eval/music20
+```
+
+或：
+
+```bash
+acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.0.0.1:5432/d2'
+```
+
+### 3.2 这个 runner 实际做了什么
+
+`acr-engine/scripts/run_songcentric_directory_pipeline_live.py` 顺序执行 3 步：
+
+1. `build_manifest`
+   - 脚本：`acr-engine/scripts/build_songcentric_manifest_from_directory.py`
+   - 输入：歌曲目录
+   - 输出：`songcentric_pipeline_manifest.jsonl`
+
+2. `enrich_features`
+   - 脚本：`acr-engine/scripts/enrich_songcentric_manifest_with_local_features.py`
+   - 输入：manifest
+   - 输出：`songcentric_pipeline_manifest_with_features.jsonl`
+
+3. `import_manifest`
+   - 脚本：`acr-engine/scripts/import_songcentric_manifest_live.py`
+   - 输入：带 feature 的 manifest
+   - 输出：`songcentric_pipeline_import_report.json`
+
+最终还会生成聚合报告：
+- `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_runner_report.json`
+
+---
+
+## 4. 第一步：build manifest（先把歌曲目录变成结构化 song/asset/window）
+
+脚本：
+- `acr-engine/scripts/build_songcentric_manifest_from_directory.py`
+
+### 4.1 输入目录假设
+
+脚本会递归扫描：
+- `.wav`
+- `.mp3`
+- `.flac`
+- `.ogg`
+- `.m4a`
+
+并把目录结构解析为：
+- 第一级目录：`song_key`
+- 第二级目录：`artist`
+- 文件本身：asset
+
+### 4.2 它做的关键事
+
+1. 推断：`song.biz_key / title / artist_name`
+2. 为每个音频文件生成 1 条 asset
+3. 按 `window_ms=5000`、`stride_ms=2500` 默认切 windows
+4. 给每条记录附上 membership：
+   - `set_type=reference_set`
+   - `set_name=phase1_hot_reference_v1`
+
+### 4.3 输出物
+
+- manifest：
+  - `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest.jsonl`
+- build report：
+  - `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_build_report.json`
+
+### 4.4 当前 fresh evidence
+
+来自 `songcentric_pipeline_runner_report.json`：
+- `song_count = 2`
+- `asset_count = 2`
+- `window_count = 5`
+- `window_ms = 5000`
+- `stride_ms = 2500`
+
+---
+
+## 5. 第二步：enrich features（给每个 window 补 exact / semantic 特征）
+
+脚本：
+- `acr-engine/scripts/enrich_songcentric_manifest_with_local_features.py`
+
+### 5.1 它做的 exact lane
+
+对每个 `wav window`：
+- 优先走仓库内 `ChromaprintMatcher`
+- 生成：
+  - `feature_type='fingerprint'`
+  - `model_name='chromaprint_matcher'`
+  - `model_version='phase1_local'`
+  - `feature_set_name='chromaprint_matcher_5s'`
+
+如果 matcher 提取失败，才回退：
+- `model_name='local_wavehash'`
+
+### 5.2 它做的 semantic lane
+
+语义路径先检查 runtime：
+- `torch`
+- `torchaudio`
+- `transformers`
+
+当前 runtime 可用时：
+- 走 `MERT-v1-95M`
+- 写成：
+  - `feature_type='embedding'`
+  - `model_name='mert-v1-95m'`
+  - `model_version='hf-main'`
+  - `feature_set_name='mert_5s_hop2.5_v1'`
+
+如果 runtime 不可用：
+- 回退到 `local_wavehash_embed`
+
+### 5.3 输出物
+
+- enriched manifest：
+  - `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest_with_features.jsonl`
+- enrich report：
+  - `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_enrich_report.json`
+
+### 5.4 当前 fresh evidence
+
+来自 `songcentric_pipeline_enrich_report.json`：
+- `wav_windows_seen = 5`
+- `features_added = 10`
+- `matcher_fingerprint_count = 5`
+- `fallback_fingerprint_count = 0`
+- `semantic_runtime_available = true`
+- `semantic_runtime_missing = []`
+- `semantic_runtime_ready_count = 5`
+- `semantic_fallback_count = 0`
+
+一句话解释：
+
+> 当前 5 个 window 都已经真实拿到了 `chromaprint_matcher + mert-v1-95m`，没有走 fallback。
+
+---
+
+## 6. 第三步：import manifest（把 song / asset / window / feature 真正落到 PostgreSQL）
+
+脚本：
+- `acr-engine/scripts/import_songcentric_manifest_live.py`
+
+### 6.1 它的写入顺序
+
+对每条 manifest row：
+
+1. `ensure_song()`
+   - 落 `media_entity`
+2. `ensure_asset()`
+   - 落 `audio_object(object_type='asset')`
+3. `ensure_window()`
+   - 落 `audio_object(object_type='window')`
+4. `ensure_feature()`
+   - 落 `feature_fact`
+5. `ensure_membership()`
+   - 落 `set_membership`
+
+### 6.2 它保证的核心绑定
+
+- window 绑定 asset：`parent_object_id`
+- feature 绑定 window：`feature_fact.object_id`
+- feature 归属 song：`feature_fact.song_id`
+- membership 可绑定 `asset` 或 `song`
+
+### 6.3 输出物
+
+- import report：
+  - `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_import_report.json`
+
+### 6.4 当前 fresh evidence
+
+来自 `songcentric_pipeline_import_report.json`：
+- `media_entity = 9`
+- `audio_object = 22`
+- `feature_fact = 34`
+- `set_membership = 9`
+
+当前可直接复核的一条 live 样例：
+- `window_id = 22`
+- `asset_id = 20`
+- `song_id = 9`
+- `title = song beta`
+- `start_ms = 1000`
+- `end_ms = 6000`
+- 对应 feature：
+  - `feature_type = embedding`
+  - `model_name = mert-v1-95m`
+  - `model_version = hf-main`
+  - `feature_set_name = mert_5s_hop2.5_v1`
+
+这条样例证明：
+
+```text
+feature -> window -> asset -> song
+```
+
+这条回溯链现在已经真实落库，不只是文档设计。
+
+---
+
+## 7. 查询阶段：怎么从命中的 feature 回到 song_id
+
+当前 repo 里，查询要分成两层理解：
+
+### 7.1 PostgreSQL 主链里的“回查”
+
+这层重点不是 online ANN 服务，而是：
+- 命中某条 feature 后
+- 如何回查 window / asset / song
+- 如何做 song-level 聚合
+
+这部分 SQL 与样例已经在：
+- [postgresql-data-model.md](./postgresql-data-model.md)
+- [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
+
+重点章节：
+- `在线检索时怎么从 feature 回到 song_id`
+- `exact + semantic 双通道如何融合到 song 排序`
+
+最短可执行回查 SQL（命中某条 feature 后，直接回到 window / asset / song）：
+
+```sql
+select ff.feature_id,
+       ff.feature_type,
+       ff.model_name,
+       win.object_id  as window_id,
+       win.start_ms,
+       win.end_ms,
+       ast.object_id  as asset_id,
+       ast.storage_uri,
+       song.entity_id as song_id,
+       song.biz_key,
+       song.title
+from acr_songcentric_test.feature_fact ff
+join acr_songcentric_test.audio_object win
+  on win.object_id = ff.object_id and win.object_type = 'window'
+join acr_songcentric_test.audio_object ast
+  on ast.object_id = win.parent_object_id and ast.object_type = 'asset'
+join acr_songcentric_test.media_entity song
+  on song.entity_id = ff.song_id and song.entity_type = 'song'
+where ff.feature_id = 34;
+```
+
+如果要直接按 song 做聚合/融合，再回看：
+- [postgresql-data-model.md](./postgresql-data-model.md)
+- [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
+
+### 7.2 当前 selected20 文件级评测里的“查询”
+
+脚本：
+- `acr-engine/scripts/evaluate_selected20_songid_retrieval.py`
+
+它做的是：
+1. 从 `type_11` 建 reference
+2. 用 `chromaprint_matcher` 做 exact 候选
+3. 用 `MERT` embedding 做 semantic 候选
+4. 按 `0.6 * exact + 0.4 * semantic` 做 fused 排序
+5. 检查 true `song_id` 是否在 top1/top3
+
+这条链主要用于：
+- 快速看实战 song-level 正确率
+- 作为后续 MuQ challenger / 融合策略的回归基线
+
+---
+
+## 8. selected20 实战评测：怎么操作、产物在哪、当前效果如何
+
+### 8.1 复现命令
+
+```bash
+cd /workspace/acr-engine
+/usr/local/miniconda3/bin/python scripts/evaluate_selected20_songid_retrieval.py \
+  --downloads-dir /root/hikoon_song_files/output/selected_20_songs/downloads \
+  --reference-type 11 \
+  --query-types 1 7 12 16 \
+  --duration 8.0 \
+  --topk 3 \
+  --exact-weight 0.6 \
+  --semantic-weight 0.4 \
+  --output-json /workspace/acr-engine/data/local_eval/selected20_songid_eval_report.json \
+  --output-md /workspace/docs/selected20_songid_eval.md
+```
+
+### 8.2 输出物
+
+- JSON：`acr-engine/data/local_eval/selected20_songid_eval_report.json`
+- Markdown 摘要：`docs/selected20_songid_eval.md`
+- 复现手册：`docs/selected20_songid_eval_repro.md`
+
+### 8.3 当前实测结果
+
+query 总数：`123`
+
+| lane | top1 | top3 |
+|---|---:|---:|
+| exact | 0.6016 | 0.8130 |
+| semantic | 0.4715 | 0.6016 |
+| fused | 0.6341 | 0.8537 |
+
+分类型：
+- `type_1`：最强，已打满
+- `type_12`：也很强，semantic 单 lane 最优
+- `type_7`：短板之一
+- `type_16`：短板之一
+
+当前最重要的判断：
+
+> **融合链路已经优于单独 exact 和单独 semantic，但 `type_7 / type_16` 仍是主要难点。**
+
+---
+
+## 9. 交付时你应该一起带走哪些文件
+
+### 9.1 主链相关
+
+- `docs/postgresql-data-model.md`
+- `docs/postgres_db_schema_samples.md`
+- `docs/song-ingest-query-delivery.md`
+- `docs/session-handoff.md`
+- `docs/start-here.md`
+- `docs/README.md`
+
+### 9.2 selected20 相关
+
+- `docs/selected20_songid_eval.md`
+- `docs/selected20_songid_eval_repro.md`
+- `acr-engine/data/local_eval/selected20_songid_eval_report.json`
+
+### 9.3 PostgreSQL live 产物相关
+
+- `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest.jsonl`
+- `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_build_report.json`
+- `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_manifest_with_features.jsonl`
+- `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_enrich_report.json`
+- `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_import_report.json`
+- `acr-engine/data/pgvector_eval/music20/songcentric_pipeline_runner_report.json`
+
+---
+
+## 10. 最小交付检查清单
+
+### 10.1 如果你要交付“入库链路”
+
+至少确认：
+- schema 已建好
+- runner 可执行
+- manifest / enriched manifest / import report / runner report 都已生成
+- `feature -> window -> asset -> song` 的 live lineage sample 可回查
+
+### 10.2 如果你要交付“效果评测”
+
+至少确认：
+- selected20 命令可复现
+- JSON 报告存在
+- Markdown 摘要存在
+- overall / per-type 指标已写进交付说明
+
+### 10.3 如果你要交付“下次可接手”
+
+至少确认：
+- `README.md` 有入口
+- `start-here.md` 有最短命令
+- `session-handoff.md` 写清当前状态
+- `CHANGELOG.md` 记录这次交付
+
+---
+
+## 11. 当前最务实的下一步
+
+1. 不要回退 4 表 song-centric 主链
+2. 把 `selected20` 继续作为小样本回归基线
+3. 后续接入 MuQ challenger 后，第一时间复跑 selected20
+4. 重点盯 `type_7 / type_16` 是否改善
+5. PostgreSQL 主链保持 `feature -> window -> asset -> song` 的可回查性不被破坏
+
+---
+
+## 12. 相关文档
+
+- [README.md](./README.md)
+- [start-here.md](./start-here.md)
+- [session-handoff.md](./session-handoff.md)
+- [selected20_songid_eval.md](./selected20_songid_eval.md)
+- [selected20_songid_eval_repro.md](./selected20_songid_eval_repro.md)
+- [postgresql-data-model.md](./postgresql-data-model.md)
+- [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
+- [CHANGELOG.md](./CHANGELOG.md)

@@ -35,12 +35,16 @@ acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.
 
 ---
 
-## 2. 只读这 4 份文档
+## 2. 只读这 8 份文档
 
 1. [README.md](./README.md)
-2. [session-handoff.md](./session-handoff.md)
-3. [postgresql-data-model.md](./postgresql-data-model.md)
-4. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
+2. [delivery-onepager.md](./delivery-onepager.md)
+3. [session-handoff.md](./session-handoff.md)
+4. [song-ingest-query-delivery.md](./song-ingest-query-delivery.md)
+5. [research-delivery-roadmap.md](./research-delivery-roadmap.md)
+6. [selected20_songid_eval.md](./selected20_songid_eval.md)
+7. [postgresql-data-model.md](./postgresql-data-model.md)
+8. [postgres_db_schema_samples.md](./postgres_db_schema_samples.md)
 
 ---
 
@@ -117,6 +121,9 @@ flowchart TD
 ### 第一优先级
 把 semantic lane 从 `mert-v1-95m` baseline 扩展到 `MuQ` challenger，且不破坏现有宿主链。
 
+### 并行专题优先级
+把 `selected20`（20 首歌）作为小样本回归基线固定下来，后续任何 semantic challenger 或 fusion 调整都先复跑这份专题，重点看 `type_7 / type_16` 是否真的改善。
+
 ### 当前 host 事实
 - `torch` 已可导入
 - `torchaudio` 已可导入