Start Here / 新同学接手入口

目标：让新同学在 10 分钟内 知道现在的主链、先跑什么、先看什么。

---

1. 先执行这条命令

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'

当前 fresh evidence：

• song_count = 2
• asset_count = 2
• window_count = 5
• matcher_fingerprint_count = 5
• fallback_fingerprint_count = 0
• semantic_runtime_available = true
• semantic_runtime_missing = []
• semantic_runtime_ready_count = 5
• semantic_fallback_count = 0
• import_counts = media_entity:9 / audio_object:22 / feature_fact:29 / set_membership:9

---

2. 只读这 4 份文档

1. README.md
2. session-handoff.md
3. postgresql-data-model.md
4. postgres_db_schema_samples.md

---

3. 用一句话理解当前项目

我们当前做的是一个 面向版权保护的 song-centric 音乐 ACR 系统： 目标是在约 100w 音频、约 30w 歌曲里，把录音、BGM、片段、翻唱相关查询尽快定位到应归属的 song_id。

---

4. 当前最重要的设计结论

4.1 不再默认走旧的多层 v2 体系

当前默认只认 4 张核心物理表：

media_entity -> audio_object -> feature_fact -> set_membership

4.2 逻辑语义这样理解

song -> asset -> window -> fingerprint / embedding

4.3 切片 / 模型 / feature 到底落哪里

对象	表	关键字段
song	media_entity	entity_type='song'
原始音频文件	audio_object	object_type='asset'
切片窗口	audio_object	object_type='window', parent_object_id=<asset_id>
指纹特征	feature_fact	feature_type='fingerprint', fingerprint_value
embedding 特征	feature_fact	feature_type='embedding', embedding_uri/vector_table_name
模型信息	feature_fact	model_name, model_version, feature_set_name
reference/eval/hot 集	set_membership	set_type, set_name

---

5. 当前主链流程图

flowchart TD
    A[media_entity\nentity_type=song] --> B[audio_object\nobject_type=asset]
    B --> C[audio_object\nobject_type=window]
    C --> D1[feature_fact\nfingerprint]
    C --> D2[feature_fact\nembedding]
    B --> E[set_membership\nreference_set / eval_set / hot_set]
    C --> E

---

6. 当前哪些已经稳定

• live PostgreSQL schema 已真实建表通过
• 真实目录 -> manifest -> import 已打通
• 真实目录 -> fingerprint enrichment -> import 已打通
• semantic lane 已做成 runtime-ready
• 当前 host 已能进入 runtime-ready placeholder 分支，下一步只差接真实 MERT / MuQ
• 当前 exact lane 已优先复用仓库内 ChromaprintMatcher

---

7. 当前最该继续什么

第一优先级

把 semantic lane 从 semantic_runtime_ready_placeholder 升级成真实 encoder adapter，且不破坏现有宿主链。

当前 host 事实

• torch 已可导入
• torchaudio 已可导入
• transformers 已可导入
• 当前 semantic_runtime_available = true
• 当前最新主链产出仍是 semantic_runtime_ready_placeholder，不是真实 MERT / MuQ

---

8. 当前不要再绕回去的点

• 不要回退到旧的 v2 schema 作为默认口径
• 不要重新引入 recording/work/version 作为 Phase-1 必须返回对象
• 不要先讨论训练/微调
• 不要把“模型底座可替换”误解成“数据库要重新拆很多层”

---

一句话结论

当前最重要的是守住 4 表 song-centric 主链，并在这个主链上把 semantic encoder 真正接起来。