ACR Workspace Handoff / 快速接手入口

这份 README 面向新接手的开发人员：先告诉你项目现在是什么、先看什么、先跑什么，避免从零重新梳理。

---

1. 这个仓库现在在做什么

当前主线是一个 song-centric 音乐 ACR 系统，重点有两条：

1. live PostgreSQL 主链
   • 把歌曲目录转换为 song -> asset -> window -> fingerprint / embedding
   • 落到当前 4 表 schema：

media_entity -> audio_object -> feature_fact -> set_membership

1. selected20 小样本实战评测链
   • 用 20 首歌的专题数据评估当前方案在真实 query 条件下的 song_id 命中率
   • 当前专题重点关注：
     • type_7
     • type_16

一句话理解：

数据库宿主链已经打通，当前要在不破坏主链的前提下继续优化 semantic lane，并用 selected20 做回归基线。

---

2. 新同学先看哪些文档

建议按这个顺序读：

1. docs/start-here.md
2. docs/delivery-onepager.md
3. docs/session-handoff.md
4. docs/song-ingest-query-delivery.md
5. docs/research-delivery-roadmap.md
6. docs/selected20_songid_eval.md
7. docs/postgresql-data-model.md
8. docs/postgres_db_schema_samples.md
9. docs/CHANGELOG.md

如果只想快速进入状态，至少看这 4 份：

• docs/start-here.md
• docs/session-handoff.md
• docs/research-delivery-roadmap.md
• docs/selected20_songid_eval.md

---

3. 先跑什么

3.1 live PostgreSQL 主链验证

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

或：

acr-engine/scripts/start_songcentric_shortest_path.sh 'postgres://d2:d2pass@127.0.0.1:5432/d2'

3.2 selected20 回归评测

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

---

6. 代码和文档主要位置

• 主代码：
  • acr-engine/
• 核心文档：
  • docs/
• 运行脚本：
  • acr-engine/scripts/
• 会话/交付状态：
  • .omx/

---

7. 如果你是新接手开发，最短路径

只做这几步：

1. 读 docs/start-here.md
2. 读 docs/session-handoff.md
3. 读 docs/research-delivery-roadmap.md
4. 跑一次主链验证
5. 跑一次 selected20 回归

这样基本就能在 10~20 分钟内进入当前上下文。