Session Handoff / 持续开发交接文档

更新：2026-06-04 目的：让下次启动的新 session 在 3~10 分钟内 明确：

1. 当前项目已经走到哪里
2. 应该先读哪些文档
3. 应该从哪一步开始推进
4. 哪些是当前稳定结论，哪些还只是待验证假设

---

一页结论

当前项目主线已经从“原型是否能跑通”切到：

为版权保护场景建设一个可演进的音乐 ACR / 检索系统， 目标是让 100w 音频、约 30w 歌曲能够在未来通过 canonical_song / work / recording / recording_asset / audio_window 这条主数据链，以及 model_registry / feature_set_registry 这套模型注册机制，稳定支撑检索、归属、升级与回滚。

当前已经完成的关键交付：

• 文档体系已重构为“角色化阅读路径”
• SOTA 演进路径已明确：Phase-1 先走 encoder-only
• PostgreSQL 主数据与特征注册 DDL 已落地为推荐版 schema
• Phase-1 实施 checklist 和 model/feature/reference set 初始化手册已补齐
• acr_test schema 上已经真实完成 Phase-1 model_registry / feature_set_registry / reference_set_registry bootstrap 验证

当前最重要的下一步不是继续写方案，而是：

1. 按 schema v2 落 PostgreSQL 主数据模型
2. 把 reference set / audio_window / feature_set 初始化做起来
3. 接入 MERT / MuQ 的 encoder-only 抽特征链
4. 跑通 fingerprint lane + semantic lane 的第一版聚合闭环

---

下次启动先读什么

最短阅读顺序（推荐）

1. docs/README.md
2. docs/acr-architecture.md
3. docs/sota-evolution-guide.md
4. docs/postgresql-data-model.md
5. docs/phase1-implementation-checklist.md
6. docs/model-feature-registry-bootstrap.md
7. docs/CHANGELOG.md

如果只想快速恢复上下文，至少读前 5 个。

---

当前稳定结论（可以直接继承）

1. 技术方向

• 当前 ECAPA 路线保留为 baseline，不再作为长期主底座。
• Phase-1 主推 encoder-only foundation 路线。
  • exact lane：Chromaprint
  • semantic lane 主 baseline：MERT-v1-95M
  • semantic lane challenger：MuQ
• Phase-2 才考虑 version / cover lane。
• Phase-3 再进入工业化检索/重排/治理。

2. 数据主链

后续主数据一律围绕：

canonical_song -> work -> recording -> recording_asset -> audio_window

不要再退回到仅有 song_id 的扁平结构。

3. 模型/特征主链

后续 encoder、feature、索引一律围绕：

model_registry -> feature_set_registry -> audio_embedding / audio_fingerprint -> retrieval_index_registry

不要设计成固定列：

• mert_embedding
• muq_embedding
• ecapa_embedding

4. reference 集合

当前结论是：

• 需要显式 reference_set_registry
• is_reference=true 仍然保留，但不再足够表达生产切换
• 未来热 reference 集、A/B、回滚、encoder 升级都要依赖 reference set 版本化

---

本轮新增/修改的关键文件

主文档

• docs/README.md
• docs/acr-architecture.md
• docs/sota-evolution-guide.md
• docs/postgresql-data-model.md
• docs/phase1-implementation-checklist.md
• docs/model-feature-registry-bootstrap.md

SQL / schema

• acr-engine/sql/acr_pg_schema_v2.sql

历史/补充说明（仍有参考价值）

• docs/sota-research-2026.md
• docs/production-encoder-freeze-and-embedding-strategy.md
• docs/training-data-and-pgvector-guide.md

---

当前推荐的启动动作

路线 A：如果下次 session 继续“补文档/补设计”

优先顺序：

1. 补 数据导入手册：100w 音频如何映射到 canonical_song/work/recording/recording_asset
2. 补 检索聚合设计文档：fingerprint lane + semantic lane 的分数融合与 song/work 聚合规则
3. 补 索引与版本治理文档：reference set / feature set / index set 的上线切换规则

路线 B：如果下次 session 开始“进入实现”

直接按下面顺序推进：

1. 建库执行 acr-engine/sql/acr_pg_schema_v2.sql
2. 初始化 canonical_song / work / recording / recording_asset
3. 初始化 reference_set_registry
4. 生成 audio_window
5. 初始化 model_registry / feature_set_registry
6. 接入 MERT / MuQ encoder-only 抽特征
7. 构建 semantic index
8. 跑通 query -> candidate -> canonical_song 闭环

---

下次 session 第一条可直接复制执行的检查命令

cd /workspace
sed -n '1,220p' docs/README.md
sed -n '1,260p' docs/phase1-implementation-checklist.md
sed -n '1,260p' docs/model-feature-registry-bootstrap.md
sed -n '1,260p' docs/postgresql-data-model.md

如果要直接看 schema：

cd /workspace
sed -n '1,320p' acr-engine/sql/acr_pg_schema_v2.sql

---

当前实现与未来实现的边界

当前仓库已经有的东西

• Chromaprint 原型链
• ECAPA embedding baseline
• hybrid engine 原型
• 早期 pgvector prototype schema

当前还没做完的东西

• PostgreSQL v2 schema 的实际落库
• Phase-1 的 reference set 初始化
• MERT / MuQ encoder-only 特征抽取与入库
• semantic lane 的第一版 production-oriented 聚合

所以：

当前项目的“方案层”已经足够启动实现， 下次 session 不应再从头讨论“要不要 song/work/recording”， 而应该直接进入 Schema -> Reference Set -> Feature Set -> Extraction -> Retrieval 的执行链。

---

当前验证状态

已验证

• 新文档结构已补齐并接入 README
• Phase-1 方案、PostgreSQL 设计、实施 checklist、registry bootstrap 均已提交
• architect 审核结论：APPROVED
• 代码已推送远端
• PostgreSQL acr_test live 路径已再次验证：recording / audio_window / audio_embedding 三类 lineage trigger 均有真实负例证据
• 机械校验已补齐：live_pgvector_music20_eval.py 的 py_compile 通过，相关变更 diff --check 通过
• PostgreSQL acr_test schema 上已真实写入 Phase-1 registry bootstrap：chromaprint / mert / muq / ecapa + 5 组 feature set + phase1_hot_reference_v1

未验证 / 仍是缺口

• 未实际跑 MERT / MuQ encoder-only 特征抽取
• 未落 reference set 的真实业务数据
• 未定义最终线上分数融合细则
• type_8 / type_16 还没有进入当前 live JSONL 的 PostgreSQL 实测链
• 当前容器里缺少 /workspace/downloads，因此暂时无法直接从业务样本目录继续补 type_8 / type_16 live query

因此下次 session 应优先从这些未验证缺口里挑一条推进，而不是重复写总方案。

---

最近相关提交

按当前 handoff 相关主线，最近重要提交是：

• a549d1d — Clarify the ACR evolution path and freeze a production-grade data model
• e514a6c — Keep the new ACR architecture guide clean for follow-up edits
• 4b23f54 — Make the Phase-1 ACR plan executable for each delivery role

如果下次需要追踪文档补充点，可以从这三个提交开始看。

---

一句话交接

下次启动不要再从“要不要换模型、要不要重构数据结构”开始讨论。 这些方向已经定了。直接从 PostgreSQL v2 schema 落库 + Phase-1 encoder-only 执行链 开始推进。