ACR Docs Overview

当前 docs 只保留与 song-centric + 4 表融合 schema 直接相关的文档。

---

1. 先看什么

新同学接手顺序：

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

推荐把前 4 份当作默认接手主路径：

start-here -> delivery-onepager -> session-handoff -> song-ingest-query-delivery

---

2. 当前默认设计口径

逻辑语义：

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

物理落表：

media_entity -> audio_object -> feature_fact -> set_membership

核心目标：

• 最终稳定返回 song_id
• 同一个 song 下允许多个音频文件
• window 是切片/evidence/召回最小单元
• feature_fact 同时承载 exact lane 与 semantic lane
• Phase-1 直接复用开源 encoder，不先训练/微调

---

3. 一键验证主链

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_ready_count = 5
• semantic_fallback_count = 0
• import_counts.feature_fact = 34

---

4. 当前保留文档分别解决什么

• start-here.md：新同学 10 分钟接手入口
• delivery-onepager.md：对外/跨团队交付时先发这一页
• session-handoff.md：下次启动从哪里继续
• song-ingest-query-delivery.md：歌曲从目录入库到查询/评测/交付的完整操作手册
• research-delivery-roadmap.md：当前研究交付、roadmap、checklist
• selected20_songid_eval.md：20 首专题评测摘要
• postgresql-data-model.md：表设计、字段语义、feature 与 audio_object 的绑定关系、Phase-1 模型落库口径
• postgres_db_schema_samples.md：DDL、manifest/SQL 样例、典型查询链路、真实存储示例
• CHANGELOG.md：变更历史

---

5. 文档维护命令

/usr/local/miniconda3/bin/python /workspace/scripts/check_markdown_links.py --root /workspace/docs