Session Handoff / 持续开发交接文档

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

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

---

首选启动流程（最短路径）

下次启动如果目标是“先判断当前 host 能不能继续推进 Phase-1”，不要先手工翻很多文档，先直接跑：

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/run_planner_validation_commands_live.py   --dsn 'postgres://d2:d2pass@127.0.0.1:5432/d2'   --output data/pgvector_eval/music20/planner_validation_commands_runner_report.json

当前这条命令的 fresh evidence 已有：

• executed_count = 4
• all_passed = true

它会一次性执行：

1. prereq_audit
2. worker_contract_smoke
3. semantic_vector_negative_matrix
4. asset_level_upsert_validation

跑完之后怎么判断

如果结果仍是当前状态：

• downloads_root_exists = false
• ready_jobs = 0
• exact = failed/unreadable_audio_assets
• semantic = 4/4 failed

那么说明：

当前不该继续怀疑 PostgreSQL contract，而应该优先解决 音频挂载 与 模型 runtime 依赖。

如果未来这条 runner 开始失败，才优先检查：

• planner 报告是否变了
• validation scripts 是否回归
• schema / worker contract 是否被破坏

一页结论

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

为版权保护场景建设一个可演进的音乐 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/phase1-worker-contract.md
8. 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
• Phase-1 registry bootstrap 已有幂等性证据：同 schema 连续执行两次后，model_registry=5 / feature_set_registry=6 / reference_set_registry=2 保持不变
• PostgreSQL acr_test schema 上已真实创建 5 条 feature_extraction_job，后续 MERT / MuQ 接入可直接从 pending jobs 启动
• PostgreSQL acr_test schema 上已真实生成 Phase-1 extraction execution plan，当前顺序是 chromaprint -> mert -> mert-long -> muq -> ecapa
• extraction plan 报告里已包含 command_suggestions / primary_command，下次可直接从 plan 抄 worker 命令模板
• Phase-1 worker 入口已真实落地：run_chromaprint_job.py / run_embedding_job.py / mark_job_status.py
• 下一阶段已经不是“补 planner”，而是把 dry-run worker 替换为真实 extractor，并把 audio_fingerprint / audio_embedding 写入做成幂等执行
• semantic lane 也已完成 live failure contract：run_embedding_job.py 现在会同时暴露 unreadable_audio_assets 与 model_runtime_unavailable，而不是把失败伪装成 completed
• audio_embedding 已补上 window / asset 双路唯一键，后续真实 encoder 只需替换 inference adapter 即可复用同一 upsert 合同
• scripts/run_phase1_embedding_preflight_matrix_live.py 已跑通，4 条 semantic jobs（mert/muq/ecapa）在 acr_test 上都被稳定标记为 preflight_failed；当前共性 blocker 已收敛为 /workspace/downloads 缺失 + 语义模型 runtime 缺失
• scripts/validate_audio_embedding_asset_upsert_live.py 已在隔离 schema acr_asset_upsert_test 上验证 uq_audio_embedding_feature_asset：重复 insert 会被唯一键拒绝，upsert 会复用同一 embedding_id，说明 asset-level 幂等键也已有真实证据
• scripts/run_phase1_worker_contract_smoke_live.py 已提供一条命令的全局 smoke：当前 exact lane = failed/unreadable_audio_assets，semantic lane = 4/4 failed，共性 blocker 已固化为音频挂载缺失 + 语义模型 runtime 缺失
• scripts/run_embedding_vector_table_negative_matrix_live.py 已在 live PostgreSQL 上补齐 semantic vector-table 负例矩阵：vector_table_dim_mismatch、vector_table_not_allowlisted、vector_table_missing_in_schema 三类错误都能被稳定写入 vector_table_report.reason
• scripts/run_phase1_prereq_audit_live.py 已给出当前 host 的先决条件审计：downloads_root_exists=false、ready_jobs=0/5，并把 torch/torchaudio/transformers/speechbrain 的缺失状态按 job 落成 JSON 报告
• phase1_extraction_plan_report.json 现已附带 validation_commands，下次 session 可以直接从 planner 复制 prereq_audit / worker_contract_smoke / semantic_vector_negative_matrix / asset_level_upsert_validation 四类命令
• phase1_validation_commands_execution_report.json 已证明 planner 里的 4 条 validation commands 都可以被直接脚本消费且 returncode=0：prereq_audit、worker_contract_smoke、semantic_vector_negative_matrix、asset_level_upsert_validation
• scripts/run_planner_validation_commands_live.py 已把这 4 条 validation commands 收敛成通用 runner；当前 planner_validation_commands_runner_report.json 显示 executed_count=4 且 all_passed=true
• phase1_hot_reference_v1 在 acr_test 里已经真实补齐 20 个 reference members，因此 worker dry-run 当前看到的 scope 已是 20 recordings / 20 assets / 20 windows
• worker contract 现在已有基础前置状态保护；重复执行同一 chromaprint dry-run job 会被 expected_status=pending 明确拒绝，证据见 phase1_worker_double_claim_guard_report.json
• exact lane 的 run_chromaprint_job.py 已具备非 dry-run 写入路径；当前在 acr_test 的 live 结果是因为 /workspace/downloads/... 缺失而明确 failed，不是继续假装 completed

未验证 / 仍是缺口

• 未实际跑 MERT / MuQ encoder-only 特征抽取
• semantic / cover 等后续 lane 仍主要停留在 dry-run；exact lane 已接上真实 audio_fingerprint 写入路径，但当前容器缺 reference 音频挂载，live 结果仍停在可审计失败
• 还未落更大规模的生产 reference set 真实业务数据（当前仅验证了 acr_test 下的 20-song live members）
• 未定义最终线上分数融合细则
• 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
• 0679481 — Attach runnable command templates to the extraction plan

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

---

一句话交接

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