2026-06-02 cap64 high_energy 首个结果 checkpoint

完成项：

• 已拿到 cap64 中 high_energy 的首个评测结果。
• 主流程已从 high_energy 切换到 hybrid 分支，说明 cap64 仍在继续。

验证证据：

• high_energy/fma_reports_smoke/eval.json：
  • num_queries=32
  • top1=0.625
  • topk=1.0
• progress.json 已同步记录同一结果。
• 当前进程显示：
  • external_adapters.py smoke-local ... /tmp/ab_smoke_seg_cap64_top2/hybrid
  • manifest_tools.py audio-dir-to-splits ... --query-strategy hybrid

说明：

• 截至本 checkpoint，hybrid 结果尚未生成，总 report.json 也尚未生成。

2026-06-02 cap64 索引完成并进入评测 checkpoint

完成项：

• 已确认 cap64 的 high_energy reference index 构建完成。
• 已确认流程从 build-index 推进到 evaluate.py。

验证证据：

• reference_progress.json：
  • status=complete
  • refs_done=64
  • windows_done=657
  • embedding_shape=[657, 192]
  • elapsed_sec=108.986
• 进程树显示：
  • evaluate.py --data /tmp/ab_smoke_seg_cap64_top2/high_energy/fma/manifests ... --seed 42 --max-queries 32
• 截至本 checkpoint：
  • report.json 仍未生成

2026-06-02 cap64 训练完成证据 checkpoint

完成项：

• 追加记录 cap64 的更强 fresh evidence。
• 已从运行会话直接确认 high_energy 的 Epoch 1/1 训练完整跑完。
• 当前主流程仍停留在 run_demo.py build-index，尚未进入 evaluate.py。

验证证据：

• 运行会话输出显示：Epoch 1 从 0/32 推进到 32/32 完成。
• 进程树仍显示：run_demo.py build-index --data /tmp/ab_smoke_seg_cap64_top2/high_energy/fma/manifests ...

2026-06-02 cap64 进入 build-index checkpoint

完成项：

• 追加记录 cap64 benchmark 的阶段推进。
• 已确认 high_energy 分支不再停留在训练，而是进入 run_demo.py build-index。

验证证据：

• 进程树显示：
  • scripts/ab_smoke_segmentation.py --work-root /tmp/ab_smoke_seg_cap64_top2
  • external_adapters.py smoke-local ... /tmp/ab_smoke_seg_cap64_top2/high_energy
  • run_demo.py build-index --data /tmp/ab_smoke_seg_cap64_top2/high_energy/fma/manifests ...
• 截至本 checkpoint：
  • cap64 report.json 仍未生成

2026-06-02 cap64 benchmark 启动 checkpoint

完成项：

• 已启动新的真实 FMA cap64 对照 benchmark。
• 本轮配置：subset_size=64, max_test_queries=32, seed=42。
• 当前已确认流程进入 high_energy 训练阶段。

验证证据：

• 主进程：scripts/ab_smoke_segmentation.py --work-root /tmp/ab_smoke_seg_cap64_top2
• 子流程：external_adapters.py smoke-local ... /tmp/ab_smoke_seg_cap64_top2/high_energy
• 当前训练：train.py --data /tmp/ab_smoke_seg_cap64_top2/high_energy/fma/manifests ... --segment-strategy high_energy

说明：

• 截至本 checkpoint，cap64 结果尚未生成。
• 本次提交的目的是为下一 session 固化新一轮 benchmark 已正式启动的证据。

2026-06-02 cap48 seed999 完结与三 seed 聚合 checkpoint

完成项：

• cap48 top2 seed=999 最终完成。
• 已拿到 high_energy 与 hybrid 的最终评测结果。
• 已完成 cap48 三个 seed 的 aggregate 汇总，并更新默认策略表述。

最终结果（seed=999）：

• high_energy：num_queries=24, top1=0.9167, topk=1.0
• hybrid：num_queries=24, top1=0.8750, topk=1.0
• winner：high_energy

cap48 三 seed aggregate：

• high_energy：
  • mean_top1=0.9167
  • min_top1=0.9167
  • max_top1=0.9167
  • stdev_top1=0.0
• hybrid：
  • mean_top1=0.8750
  • min_top1=0.7917
  • max_top1=0.9583
  • stdev_top1=0.0680

结论：

• 在当前 cap48 真实 FMA smoke 条件下，high_energy 已展现出比 hybrid 更高且更稳定的 top1。
• 默认优先策略表述从“等待更多 seed”推进为：
  • cap48 条件下优先 high_energy
  • hybrid 继续作为优化与对照对象

2026-06-02 seed999 中间结果 checkpoint（hybrid 已落盘）

完成项：

• 记录 cap48 top2 seed=999 中 hybrid 的已完成评测结果。
• 确认 hybrid 结果已经写入 progress.json，而总 report.json 仍待 high_energy 完成后生成。

验证证据：

• hybrid/fma_reports_smoke/eval.json：
  • num_queries=24
  • top1=0.875
  • topk=1.0
• /tmp/ab_smoke_seg_cap48_top2_seed999/progress.json 已记录同一结果。
• 当前进程已切换到：
  • high_energy 的 run_demo.py build-index

说明：

• 截至本 checkpoint，三 seed aggregate 仍不能最终更新，因为 high_energy 的 seed=999 还未完成。

2026-06-02 运行中 benchmark 新证据 checkpoint

完成项：

• 追加记录 cap48 top2 seed=999 的新鲜运行证据。
• 已确认流程并未卡死在 hybrid build-index，而是继续推进到 evaluate.py。
• 已记录 reference index 完成指标：48 refs / 491 windows / 192-d embedding。

验证证据：

• reference_progress.json 显示：
  • status=complete
  • refs_done=48
  • windows_done=491
  • embedding_shape=[491, 192]
  • elapsed_sec=80.26
• 进程树显示：
  • evaluate.py ... --seed 999 --max-queries 24 正在运行

说明：

• 截至本 checkpoint，/tmp/ab_smoke_seg_cap48_top2_seed999/report.json 仍未生成。
• 因此本次仍不更新 3-seed aggregate 结论。

2026-06-02 交付检查点：handoff / changelist / agent memory

完成项：

• 新增根目录 AGENT.md，固化当前开发偏好、提交习惯、续跑优先级与避坑约束。
• 新增 docs/changelist-2026-06-02.md，用于本次交付文件级变更说明。
• 新增 docs/delivery-handoff-2026-06-02.md，用于新 session 快速接管。
• 补充 docs/session-handoff.md：明确当前卡点、运行中的 benchmark、下一步命令与禁止误提交项。

当前卡点：

• cap48 top2 seed=999 benchmark 仍在运行中，尚未产出最终 report.json。
• 仓库存在大量未跟踪数据与模型产物，当前阶段只适合提交文档。

交付说明：

• 本次提交以“可续跑交接”为目标，不等待长时 CPU benchmark 完成。
• 下一 session 进入后应优先检查：
  • /tmp/ab_smoke_seg_cap48_top2_seed999/report.json
  • 相关 eval.json
  • 进程是否仍在运行

Changelog

2026-06-02

Stage: 汇总 cap48 两次 seed 的聚合指标

完成项：

• 汇总：
  • /tmp/ab_smoke_seg_cap48_top2/report.json
  • /tmp/ab_smoke_seg_cap48_top2_seed123/report.json
• 计算 cap48 当前 2 次 seed 的聚合指标
• 更新：
  • open-dataset-workflow.md
  • session-handoff.md
  • CHANGELOG.md

cap48 聚合结果（2 次 seed）：

• high_energy:
  • mean_top1 = 0.9167
  • min_top1 = 0.9167
  • max_top1 = 0.9167
  • stdev_top1 = 0.0
• hybrid:
  • mean_top1 = 0.8750
  • min_top1 = 0.7917
  • max_top1 = 0.9583
  • stdev_top1 = 0.0833

结论：

• 仅看 cap48 当前两次 seed，high_energy 的均值与稳定性更占优
• hybrid 的表现波动更大，但峰值更高
• 当前最稳妥的策略判断应升级为：
  • 单轮结果不可信
  • 默认策略应参考多 seed 聚合
  • 下一步继续扩展 seed 数或 style-aware bucket 比单纯再加单轮更有价值

Stage: 收尾 cap48 seed123 并确认 cap48 对 seed 敏感

完成项：

• 读取 /tmp/ab_smoke_seg_cap48_top2_seed123/report.json
• 读取：
  • /tmp/ab_smoke_seg_cap48_top2_seed123/hybrid/fma_reports_smoke/eval.json
  • /tmp/ab_smoke_seg_cap48_top2_seed123/high_energy/fma_reports_smoke/eval.json
• 更新：
  • open-dataset-workflow.md
  • session-handoff.md
  • CHANGELOG.md

最终结果（subset=48, max_test_queries=24, seed=123）：

• hybrid: num_queries=24, top1=0.9583, topk=1.0
• high_energy: num_queries=24, top1=0.9167, topk=1.0

结论：

• cap48 在不同 seed 下已经出现明显不同排序：
  • 默认 seed：high_energy > hybrid
  • seed=123：hybrid > high_energy
• 这意味着 cap48 当前最可靠的结论不是“谁绝对赢”，而是：
  • 该对比对 seed/抽样敏感
  • 当前默认策略判断必须依赖多 seed 聚合结果
  • hybrid 仍可保留为保守默认，high_energy 仍是强竞争方案

Stage: 启动 cap48 第二个 seed 复核反转结果

完成项：

• 启动第二个 seed 的 cap48 top2 benchmark：
  • work_root = /tmp/ab_smoke_seg_cap48_top2_seed123
  • subset_size = 48
  • max_test_queries = 24
  • seed = 123
  • 策略：hybrid vs high_energy
• 更新 session-handoff.md

当前 fresh evidence：

• 第二个 seed 已启动
• hybrid 已完成首条评测：
  • num_queries = 24
  • top1 = 0.9583
  • topk = 1.0
• high_energy 已进入：
  • run_demo.py build-index --resume --checkpoint-every-refs 100

结论：

• 已经从“单轮 cap48 反转”升级为“开始做多 seed 复核”
• 即使当前 session 结束，新 session 也可直接从 handoff 中的 cap48_top2_seed123 入口继续

Stage: 收尾 cap48 top2 真实 FMA 对照并发现 high_energy 反超

完成项：

• 读取 /tmp/ab_smoke_seg_cap48_top2/report.json
• 读取：
  • /tmp/ab_smoke_seg_cap48_top2/hybrid/fma_reports_smoke/eval.json
  • /tmp/ab_smoke_seg_cap48_top2/high_energy/fma_reports_smoke/eval.json
• 更新：
  • open-dataset-workflow.md
  • session-handoff.md
  • CHANGELOG.md

最终结果（subset=48, max_test_queries=24）：

• high_energy: num_queries=24, top1=0.9167, topk=1.0
• hybrid: num_queries=24, top1=0.7917, topk=1.0

结论：

• cap48 与 cap24 / cap32 给出了不同方向的结果
• 这意味着“默认策略已经完全固定为 hybrid”的说法需要降级为暂时性结论
• 当前更稳妥的表述应是：
  • hybrid 仍可保留为保守默认
  • high_energy 已成为必须严肃对待的强竞争方案
  • 下一步需要更大样本 / 多 seed / style-aware benchmark 再定最终默认

Stage: 启动 cap48 top2 真实 FMA 对照并记录运行阶段

完成项：

• 启动更大的真实 FMA top2 benchmark：
  • work_root = /tmp/ab_smoke_seg_cap48_top2
  • subset_size = 48
  • max_test_queries = 24
  • 策略：hybrid vs high_energy
• 更新 session-handoff.md

当前 fresh evidence：

• scripts/ab_smoke_segmentation.py ... --work-root /tmp/ab_smoke_seg_cap48_top2 已启动
• hybrid 已完成首条评测：
  • num_queries = 24
  • top1 = 0.7917
  • topk = 1.0
• high_energy 已进入：
  • evaluate.py --data /tmp/ab_smoke_seg_cap48_top2/high_energy/fma/manifests ... --max-queries 24
• report.json 尚未落盘

结论：

• 现在已经开始验证 cap24 / cap32 的结论在更大 subset=48 上是否继续成立
• 即使当前 session 结束，新 session 也可直接从 handoff 中的 cap48 入口继续盯结果

Stage: 收尾 cap32 top2 真实 FMA 对照并稳定默认策略结论

完成项：

• 读取 /tmp/ab_smoke_seg_cap32_top2/report.json
• 读取：
  • /tmp/ab_smoke_seg_cap32_top2/hybrid/fma_reports_smoke/eval.json
  • /tmp/ab_smoke_seg_cap32_top2/high_energy/fma_reports_smoke/eval.json
• 更新：
  • open-dataset-workflow.md
  • session-handoff.md
  • CHANGELOG.md

最终结果（subset=32, max_test_queries=20）：

• hybrid: num_queries=20, top1=0.95, topk=1.0
• high_energy: num_queries=20, top1=0.5, topk=1.0

结论：

• cap32 继续强化 cap24 的结论：hybrid 明显优于 high_energy
• 当前默认训练 / query 策略可以稳定固定为 hybrid
• high_energy 更适合作为专项对照策略，而非默认策略

Stage: 启动 cap32 top2 真实 FMA 对照并记录运行阶段

完成项：

• 启动更大的真实 FMA top2 benchmark：
  • work_root = /tmp/ab_smoke_seg_cap32_top2
  • subset_size = 32
  • max_test_queries = 20
  • 策略：hybrid vs high_energy
• 更新 session-handoff.md

当前 fresh evidence：

• scripts/ab_smoke_segmentation.py ... --work-root /tmp/ab_smoke_seg_cap32_top2 已启动
• hybrid 已完成首条评测：
  • num_queries = 20
  • top1 = 0.95
  • topk = 1.0
• high_energy 已进入训练阶段
• report.json 尚未落盘

结论：

• 现在已经开始验证 cap24 结论在更大 subset=32 上是否继续成立
• 当前至少可以确认：hybrid 在更大子集上仍保持较强表现
• 即使当前 session 结束，新 session 也可直接从 handoff 中的 cap32 入口继续盯结果

Stage: 收尾 cap24 top2 真实 FMA 对照并确认默认策略

完成项：

• 读取 /tmp/ab_smoke_seg_cap24_top2/report.json
• 读取 /tmp/ab_smoke_seg_cap24_top2/high_energy/fma_reports_smoke/eval.json
• 更新：
  • open-dataset-workflow.md
  • session-handoff.md
  • CHANGELOG.md

最终结果（subset=24, max_test_queries=16）：

• hybrid: num_queries=16, top1=1.0, topk=1.0
• high_energy: num_queries=16, top1=0.8125, topk=1.0

结论：

• cap24 比 cap16 更有区分度，hybrid 不再只是与 high_energy 打平
• 当前默认训练 / query 策略应明确固定为 hybrid
• high_energy 更适合作为补充对照或偏高能区数据的次选策略

Stage: 启动更大 cap24 top2 真实 FMA 对照并记录首条结果

完成项：

• 启动：
  • /tmp/ab_smoke_seg_cap24_top2
  • 策略仅保留 hybrid 与 high_energy
  • subset_size = 24
  • max_test_queries = 16
• 更新 session-handoff.md

当前 fresh evidence：

• hybrid 已完成：
  • num_queries = 16
  • top1 = 1.0
  • topk = 1.0
• high_energy 已进入训练阶段，整轮对照尚未完成

结论：

• 在比 cap16 更大的真实 FMA 子集上，hybrid 目前仍保持满分
• 下一步只需等待 high_energy 完成，就能判断两者在更大子集上是否继续打平或拉开

Stage: 收尾 cap16 真实 FMA capped segmentation benchmark

完成项：

• 读取 /tmp/ab_smoke_seg_cap16/report.json
• 确认 repeated_section_aware 最终评测结果
• 更新：
  • open-dataset-workflow.md
  • session-handoff.md
  • CHANGELOG.md

最终结果（subset=16, max_test_queries=12）：

• hybrid: num_queries=12, top1=1.0, topk=1.0
• high_energy: num_queries=12, top1=1.0, topk=1.0
• beat_aware: num_queries=12, top1=0.9167, topk=1.0
• repeated_section_aware: num_queries=12, top1=0.8333, topk=1.0

结论：

• 在固定 query 预算下，hybrid 仍是当前默认首选
• high_energy 是最强次选，并且与 hybrid 在这轮 cap16 上打平
• beat_aware 与 repeated_section_aware 单独使用时不如混合策略稳定

Stage: 交付当前切片 benchmark 续跑 handoff

完成项：

• 更新 session-handoff.md
• 记录最新关键提交：
  • 6232787
  • f04a314
  • d7a0894
  • b6cdf66
• 记录中规模真实 FMA capped benchmark 的续跑入口
• 写入当前已拿到的 partial result：
  • hybrid: num_queries=12, top1=1.0, topk=1.0
  • beat_aware: num_queries=12, top1=0.9167, topk=1.0
  • high_energy: num_queries=12, top1=1.0, topk=1.0

验证结果：

• 当前进程确认：
  • scripts/ab_smoke_segmentation.py ... --work-root /tmp/ab_smoke_seg_cap16
  • repeated_section_aware 策略仍在进行中
• 已落盘评测文件确认：
  • /tmp/ab_smoke_seg_cap16/hybrid/fma_reports_smoke/eval.json
  • /tmp/ab_smoke_seg_cap16/beat_aware/fma_reports_smoke/eval.json
  • /tmp/ab_smoke_seg_cap16/high_energy/fma_reports_smoke/eval.json

结论：

• 当前 session 即使立即中断，也已经具备可恢复的续跑交接材料
• 新 session 可以直接从 /tmp/ab_smoke_seg_cap16 和 docs/session-handoff.md 接手，而不需要重新梳理上下文

Stage: 为切片策略评测补齐公平 query cap，并澄清 librosa 分段现状

完成项：

• 修改 acr-engine/evaluate.py
  • 新增 --max-queries
  • 新增 --seed
  • 允许评测前对 query 集进行可复现随机抽样
• 修改 acr-engine/src/data/external_adapters.py
  • smoke-local 新增 --max-test-queries
  • 自动透传到 evaluate.py --max-queries
  • smoke 配置摘要同步记录 cap 信息
• 修改 acr-engine/scripts/ab_smoke_segmentation.py
  • 新增 --max-test-queries
  • 可在策略 A/B smoke 中统一限制 query 预算
• 更新文档：
  • open-dataset-workflow.md
  • dataset-spec.md
  • training-data-and-pgvector-guide.md
• 文档中额外澄清：
  • 当前切片不是只有 random
  • 已经接入 librosa.effects.split / onset_detect / beat_track / chroma_cqt
  • 但尚未把更重的 librosa.segment.* 结构分段作为默认主流程

验证结果：

• 语法检查：
  • /usr/local/miniconda3/bin/python -m py_compile evaluate.py src/data/external_adapters.py scripts/ab_smoke_segmentation.py
• 单点评测验证：
  • evaluate.py --max-queries 5 --seed 123
  • 输出 num_queries = 5
  • top1 = 1.0
  • topk = 1.0
• 端到端 smoke 验证：
  • scripts/ab_smoke_segmentation.py --strategies hybrid --max-test-queries 5
  • 最终报告：
  • max_test_queries = 5
  • num_queries = 5
  • top1 = 1.0
  • topk = 1.0

结论：

• 现在策略 A/B 不再只能比较“谁生成的 query 更多”
• 已经可以在统一 query 成本预算下比较不同切片策略
• 当前项目也已明确进入“random + librosa 音乐感知候选”的混合切片阶段，而不是纯随机切片阶段

Stage: 为内部素材 query 自动补 duration / offset 规则

完成项：

• 扩展 acr-engine/scripts/internal_asset_type_mapper.py
  • 新增 --duration-field
  • 新增 --offset-field
  • 新增 --default-query-duration
  • 新增 --default-query-offset
• 规则更新：
  • query 优先使用 CSV 提供的 duration/offset
  • 无 CSV duration 时，优先使用音频探测时长
  • 无 CSV offset 时，使用默认 offset
• pgvector payload 同步使用生成后的 duration/offset

验证结果：

• 用 3 行样例 CSV 验证：
  • song_a 短视频 query 使用 CSV 值：
  • duration = 5.0
  • offset = 12.5
  • song_c demo query 使用自动回填：
  • duration = 6.5
  • offset = 0.0
• pgvector_payload.json 中的 segments 也已同步带上正确 offset_sec/duration_sec

结论：

• 现在内部素材 query 已经不再只能输出“空 offset”
• 对短视频片段、demo、后续回流片段的训练和入库更接近真实可用状态

Stage: 为内部素材映射脚本增加 pgvector-ready JSON 导出

完成项：

• 扩展 acr-engine/scripts/internal_asset_type_mapper.py
  • 新增 --emit-pgvector-json
  • 新增 --pgvector-split
• 可直接导出：
  • pgvector_payload.json
• 导出结构与现有 pgvector 导出工具兼容，包含：
  • songs
  • references
  • segments
• 同时额外保留：
  • audio_role
  • asset_type_code
  • audio_exists
  • validation_status

验证结果：

• 运行：
  • internal_asset_type_mapper.py ... --emit-pgvector-json --pgvector-split train
• 输出摘要：
  • pgvector_songs = 2
  • pgvector_references = 2
  • pgvector_segments = 2
• 抽样检查：
  • reference 行含 duration_sec/sample_rate/audio_role/asset_type_code
  • segment 行含 offset_sec/split/type/segment_type/audio_role

结论：

• 现在内部素材 CSV 已经可以直接桥接到 pgvector 入库准备阶段
• 后续再补 loader 或数据库直写时，不需要重新设计内部素材导出结构

Stage: 为内部素材映射脚本增加音频存在性与时长校验

完成项：

• 扩展 acr-engine/scripts/internal_asset_type_mapper.py
  • 新增 --audio-root
  • 自动探测 audio_exists
  • 自动探测 duration_sec
  • 自动写入 validation_status
• 在 summary 中新增：
  • missing_audio
  • trainable_audio_rows
• 更新 training-data-and-pgvector-guide.md

验证结果：

• 构造了 6 行样例 CSV，其中 4 个真实音频、2 个缺失路径
• 运行：
  • internal_asset_type_mapper.py ... --audio-root /tmp/internal_assets_audio --emit-manifests
• 输出摘要：
  • missing_audio = 2
  • trainable_audio_rows = 4
• 生成的 reference/query 记录已带：
  • audio_exists = true
  • validation_status = ok
  • 正确的 duration

结论：

• 现在内部素材 CSV 到 manifest 的链路已经具备最基础的训练前质量校验
• 后续再补 offset / 更细粒度质量规则时，不需要推翻现有脚本结构

Stage: 让内部素材映射脚本直接输出 train/test manifests

完成项：

• 扩展 acr-engine/scripts/internal_asset_type_mapper.py
  • 新增 --emit-manifests
  • 新增 --eval-ratio
  • 新增 --seed
• 在原有 references/queries/metadata_only/excluded 基础上，新增：
  • manifest_bundle/catalog.json
  • manifest_bundle/train.json
  • manifest_bundle/test.json
  • manifest_bundle/val.json
• 增加小样本保护：
  • 即使 query 很少，也尽量保证 train/test 都有 query
• 更新 training-data-and-pgvector-guide.md

验证结果：

• 使用 6 行样例 CSV 执行：
  • internal_asset_type_mapper.py ... --emit-manifests --eval-ratio 0.5 --seed 42
• 输出摘要：
  • manifest_bundle 已生成
  • manifest_train_rows = 3
  • manifest_test_rows = 3
  • manifest_val_rows = 0
• manifest 检查：
  • catalog：2 references
  • train：1 query + 2 references
  • test：1 query + 2 references

结论：

• 现在内部素材 CSV 已经可以一步变成接近可训练的 manifest bundle
• 后续如果再补充 duration/offset/audio existence 校验，就能更平滑接入正式训练链路

Stage: 将内部素材 type 策略落成可执行映射脚本

完成项：

• 新增 acr-engine/scripts/internal_asset_type_mapper.py
• 支持从内部素材 CSV 自动分流到：
  • references.json
  • queries.json
  • metadata_only.json
  • excluded.json
• 支持 --include-conditionals-as，可选把伴奏类临时导出成 query 或 reference
• 在 training-data-and-pgvector-guide.md 增加脚本入口说明

验证结果：

• 使用 6 行样例 CSV 验证：
  • 11/1 -> references
  • 7/18 -> queries
  • 3 -> metadata_only
  • 12 -> excluded
• 摘要输出：
  • references = 2
  • queries = 2
  • metadata_only = 1
  • excluded = 1

结论：

• 现在内部素材 type 策略已经不只在文档里，而是可以直接作为批量清洗入口使用
• 后续如果要从数据库导出 CSV 再转 manifest，已经有第一版可执行桥接脚本

Stage: 为内部素材 type 枚举补齐训练参与策略文档

完成项：

• 在 training-data-and-pgvector-guide.md 新增内部素材 type 映射章节
• 对用户给出的素材类型补齐：
  • 主 reference 推荐
  • 主 query 推荐
  • 伴奏类的条件式参与策略
  • 文本/图片/授权/压缩包的 metadata-only 策略
• 增加 canonical_song_id / version_id / asset_type_code / audio_role 的落库建议

验证结果：

• 文档中已出现以下关键锚点：
  • 12. 你这批内部素材 type，哪些推荐参与训练
  • 12.3 最推荐的主任务训练组合
  • instrumental_variant
  • short_video_clip
• 当前建议与现有数据规范保持一致：
  • reference / query 分离
  • 伴奏版本默认不无脑并入原曲主标签
  • 非音频资产不进入音频模型训练

结论：

• 现在这批内部资产已经有一套明确的训练白名单 / 条件白名单 / 元数据白名单
• 后续做批量导入或 pgvector 入库时，可以直接按文档映射执行

Stage: 为外部数据集接入增加 overlap query manifest 能力

完成项：

• 修改 acr-engine/src/data/manifest_tools.py
  • 为 audio-dir-to-splits 增加 --query-stride
  • 支持按 stride 为单首歌生成多个 query
  • 新 query 记录增加 query_index
• 修改 acr-engine/src/data/external_adapters.py
  • prepare-local / smoke-local 透传 --query-stride
  • smoke 配置摘要里记录 manifest_query_stride
• 更新 open-dataset-workflow.md 与 dataset-spec.md

验证结果：

• CLI 验证：
  • manifest_tools.py audio-dir-to-splits --help 已出现 --query-stride
• 小数据验证：
  • 执行：
  • prepare-local fma data/synthetic_v2/songs --query-duration 8.0 --query-stride 4.0
  • 返回：
  • train_queries = 57
  • test_queries = 15
  • 解析 manifest 后得到：
  • num_queries = 72
  • sample_query.offset = 0.0
  • query_index = 0
  • max_query_index = 2

结论：

• 现在外部开源数据接入已经不再局限于“每首歌只采一个随机 query”
• 当需要更高覆盖率时，可以直接生成多 query / overlap query manifests，用于更稳定的训练与评测

Stage: 显式拆分 smoke 配置里的 8s query 与 5s training segment 语义

完成项：

• 修改 acr-engine/src/data/external_adapters.py
  • 新增 load_default_training_config()
  • 新增 build_smoke_config_summary()
  • 让 smoke-local 产出的 config.json 显式记录：
  • manifest_query_duration
  • train_segment_duration
  • sample_rate
  • n_fft
  • hop_length
  • query_duration_legacy
• 更新 training-data-and-pgvector-guide.md，说明新旧配置口径

验证结果：

• 通过直接调用 build_smoke_config_summary() 验证输出：
  • manifest_query_duration = 8.0
  • train_segment_duration = 5.0
  • requested_device = auto
  • resolved_device = cpu
• 默认训练配置读取自：
  • configs/default.yaml
  • 其中 data.segment_dur = 5.0

结论：

• 现在 smoke 配置摘要已经能明确区分“manifest 的 query 时长”和“训练 clip 时长”
• 后续即使 report 产物跨实验对比，也更容易避免 5s/8s 语义混淆

Stage: 将连续开发偏好与当前进度固化到 AGENTS.md

完成项：

• 在根级 AGENTS.md 新增 Project Continuity Memory / 持续开发记忆
• 记录用户长期偏好：
  • 自动继续执行
  • 每阶段更新 changelog 并 commit/push
  • 使用 /usr/local/miniconda3/bin/python
  • 文档优先图表/表格/相对路径链接/浓缩结构
• 记录当前项目方向、真实 FMA 数据状态、smoke-local 设备能力、当前宿主机无 CUDA 的事实
• 记录最近完成的工程阶段与建议下一步，方便新 session 直接续做

验证结果：

• AGENTS.md 已可检索到以下关键记忆锚点：
  • Project Continuity Memory
  • smoke-local
  • fma_small_audio
  • torch.cuda.is_available() == False
  • Highest-value next steps
• 新增内容与当前代码/文档状态一致：
  • smoke-local 已支持 --device cpu|cuda|auto
  • build-index 进度日志增强已完成
  • 当前真实 FMA 长跑仍位于 CPU build-index 阶段

结论：

• 现在新 session 启动时，不需要重新摸索用户偏好、数据目录、当前瓶颈与下一步计划
• AGENTS.md 已承担仓库级连续开发记忆入口

Stage: 增强 build-index 进度可见性，降低真实 FMA 长跑误判成本

完成项：

• 修改 acr-engine/src/engines/ecapa_embedder.py
  • 在 build_reference_index 中输出 start/progress/finish 日志
  • 日志包含 refs、windows、elapsed_sec、eta_sec
• 修改 acr-engine/run_demo.py
  • 在 build-index 阶段显式打印 chromaprint 与 embedding 两个阶段的开始提示
• 复核当前宿主机设备条件，确认本机当前无 CUDA，只能走 CPU

验证结果：

• 宿主机设备：
  • torch.cuda.is_available() = False
  • device_count = 0
• 小数据验证：
  • 使用 /tmp/acr_smoke_device_test/fma/manifests 运行 PYTHONUNBUFFERED=1 /usr/local/miniconda3/bin/python run_demo.py build-index ... --device cpu
  • 看到新的阶段日志：
  • [build-index] starting chromaprint index ...
  • [build-index] starting embedding index ...
  • [build-reference-index] start: refs=24 ...
  • [build-reference-index] progress: refs=1/24 ...
  • [build-reference-index] progress: refs=24/24 ...
  • 结束时成功输出：
  • Built reference index: 120 windows, embeddings shape (120, 192)
• 真实 FMA 状态复检：
  • 真实长跑仍停留在 run_demo.py build-index ... --device cpu
  • 但当前可以明确判断它是在 CPU 上长时间构建 embedding index，而不是“无输出的假卡死”

结论：

• 现在真实 FMA 长跑的主要瓶颈已被明确定位为 CPU embedding index 构建
• 即使当前宿主机无 GPU，也已经具备了更可观测的长跑诊断能力，方便后续迁移到 CUDA 机器或继续做索引阶段优化

Stage: 让 smoke-local 支持显式设备选择并验证 auto 设备解析

完成项：

• 修改 acr-engine/src/data/external_adapters.py，为 smoke-local 增加 --device
• 增加 auto -> cpu/cuda 的内部解析，避免把字符串 auto 直接传给 embedding / eval 侧
• 将训练、建索引、评测三个子命令统一改为透传解析后的设备
• 在 smoke 配置摘要中记录 requested_device 与 resolved_device
• 同步更新 open-dataset-workflow.md 与 training-data-and-pgvector-guide.md

验证结果：

• CLI 验证：
  • /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local --help 已出现 --device DEVICE
• 最小链路验证：
  • 使用 data/synthetic_v2/songs 运行 smoke-local ... --device auto
  • 训练阶段输出 Device: cpu，说明 auto 已被正确解析
  • 随后手动验证后半段命令可正常运行：
  • run_demo.py build-index --device cpu
  • evaluate.py --device cpu
  • evaluate.py 返回：
  • top1=1.0
  • topk=1.0
• 真实 FMA 状态复检：
  • 真实 FMA smoke 主进程仍存活
  • 当前子进程停留在 run_demo.py build-index ... --device cpu

结论：

• 现在 smoke-local 已具备 GPU/CPU/auto 设备入口，可直接用于后续真实数据 GPU smoke
• 同时也暴露出新的后续任务：真实 FMA smoke 的后半段索引/产物生成仍需继续观察与优化

Stage: 补齐训练数据、重叠窗口、GPU 与 FMA 数据处理文档

完成项：

• 重写并压缩 dataset-spec.md，补齐训练切片、检索重叠滑窗、manifest 生成差异
• 扩展 training-data-and-pgvector-guide.md，补齐 FMA / MTG / 自有数据接入、目录规范、脚本职责、GPU 加速说明
• 明确记录当前真实代码事实：训练端 5s 随机裁剪、检索端 5s/2.5s 重叠滑窗、外部 manifest 默认 8s query
• 记录当前 smoke 现状：smoke-local 仍固定 CPU，真实 FMA smoke 正在运行
• 记录当前实验产物一致性风险：旧的 fma_reports_smoke/config.json 与最新 manifests 时间戳不一致，需后续统一配置治理

验证结果：

• 源码复核：
  • src/data/dataset.py：训练端随机 5s crop
  • src/utils/audio.py / src/engines/ecapa_embedder.py：5s window + 2.5s stride
  • src/data/manifest_tools.py：每首歌 1 个随机 query，默认 8.0s
  • src/data/external_adapters.py：smoke-local 当前硬编码 --device cpu
  • train.py：支持 --device auto，CUDA 路径支持 mixed precision
• 真实运行状态：
  • FMA smoke 进程仍在运行
  • 最新可见进度约 82% epoch 1
• 文档链接验证：主文档仍使用相对路径链接到仓库文件与同组文档

结论：

• 当前项目关于训练数据格式、3 分钟 mp3 切片、是否重叠窗口、GPU 是否可显著加速、FMA 与开放数据如何复用流程，已形成可交接文档
• 后续可继续沿两条线推进：
  1. 让 smoke-local 支持 GPU
  2. 增加 overlap query manifest 生成能力

Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：

• 复检归档下载状态，确认 fma_small.zip 已达完整字节数
• 验证本地 FMA 音频目录已可用于真实 smoke
• 直接启动真实 FMA smoke-local，进入训练/索引/评测主链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=7679594875
  • archive_progress_percent=100.0
  • num_audio_files=3025（inspect 阶段）
• 本地解压目录复检：
  • find data/raw/fma_small_audio ... | wc -l 返回 5827
  • check-local-ready / inspect-local 返回：
  • ready_for_smoke=true
  • num_audio_files=8000
  • eligible_query_files=7994
  • recommended_train_queries=6395
  • recommended_test_queries=1599
• 真实 smoke 已启动：
  • /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/raw/fma_small_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2
• 当前训练侧实时证据：
  • Device: cpu
  • Classes: 6381
  • Train songs: 6381
  • Epoch 1 已启动
  • 当前 epoch 总 batch 数：3191

结论：

• 真实 FMA 数据下载门槛已正式打开
• 项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段

Stage: 真实 FMA 下载超过八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 09:28
• 守护日志已增长到至少 19 轮：
  • cycle=18, 83.937%
  • cycle=19, 85.7155%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6724517888
  • archive_progress_percent=87.5634
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=87.5649

结论：

• detached guard 已在九分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 08:25
• 守护日志已增长到至少 17 轮：
  • cycle=16, 81.1776%
  • cycle=17, 82.7758%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6432636928
  • archive_progress_percent=83.7627
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=83.764

结论：

• detached guard 已在八分钟级别继续稳定驻留
• 真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过八成

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 复检后处理门槛是否仍未打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 07:15
• 守护日志已增长到至少 15 轮：
  • cycle=14, 78.2606%
  • cycle=15, 79.6962%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6173982720
  • archive_progress_percent=80.3946
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=80.3946

结论：

• detached guard 已在七分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过四分之三

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 06:12
• 守护日志已增长到至少 13 轮：
  • cycle=12, 75.3734%
  • cycle=13, 76.9423%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5953486848
  • archive_progress_percent=77.5234
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=77.5247

结论：

• detached guard 已在六分钟级别继续稳定驻留
• 真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近四分之三

完成项：

• 再次复检 detached guard 的更长时段存活情况
• 采集新的多轮日志增长证据
• 再次确认后处理门槛是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 05:19
• 守护日志已增长到至少 11 轮：
  • cycle=10, 72.2831%
  • cycle=11, 73.8305%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5748047872
  • archive_progress_percent=74.8483
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=74.8485

结论：

• detached guard 已在五分钟级别继续稳定驻留
• 真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛

Stage: 真实 FMA 下载超过七成

完成项：

• 再次复检 detached guard 长时运行状态
• 采集新一轮日志增长证据
• 复检后处理门槛是否已经打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 04:16
• 守护日志已增长到至少 9 轮：
  • cycle=8, 68.0898%
  • cycle=9, 70.2949%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5479727104
  • archive_progress_percent=71.3544
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=71.3559

结论：

• detached guard 在更长时间窗口内继续稳定工作
• 真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛

Stage: 真实 FMA 下载进度过三分之二

完成项：

• 再次复检 detached guard 的持续运行情况
• 采集新的多轮日志增长证据
• 复检后处理门槛是否已打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 03:19
• 守护日志已增长到至少 7 轮：
  • cycle=6, 63.9577%
  • cycle=7, 65.6775%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5160501248
  • archive_progress_percent=67.1976
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=67.1995

结论：

• detached guard 在更长时段内继续稳定工作
• 真实 FMA 下载已超过三分之二，但后处理门槛仍未打开

Stage: 真实 FMA 守护长时稳定性再验证

完成项：

• 再次复检 detached guard 进程与运行时长
• 检查守护日志是否继续稳定跨轮输出
• 再次复检后处理门槛状态

验证结果：

• 守护进程继续存活：
  • pid=52277
  • PPID=1
  • 运行时长 02:15
• 守护日志已继续增长到至少 5 轮：
  • cycle=4, 60.0672%
  • cycle=5, 62.0764%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4836065280
  • archive_progress_percent=62.9729
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=62.9733

结论：

• detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
• 当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数

Stage: 真实 FMA 守护稳定性续验

完成项：

• 复检新守护进程 pid 与运行时长
• 复检守护日志是否已跨更多轮持续输出
• 再次执行后处理就绪检查，确认是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 01:29
• 守护日志已连续输出至少 3 轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%
  • cycle=3, 58.5098%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4612112384
  • archive_progress_percent=60.0567
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=60.0582

结论：

• 新的守护启动方式已表现出明显更好的长期稳定性
• 当前唯一阻塞继续保持为：FMA 归档尚未完整下载

Stage: 真实 FMA 后台守护方式稳定化

完成项：

• 对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
• 判断二次掉线更可能来自后台脱离方式而非轮询逻辑
• 新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
• 验证新守护方式可跨多轮轮询持续存活

验证结果：

• 前台验证：
  • /usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3 连续输出 3 轮 polling，并正常结束为 status=waiting
• 下载进度继续增长到：
  • 4261445632 -> 4265574400
  • 55.4905% -> 55.5443%
• 新守护脚本启动后：
  • pid=52277
  • PPID=1
  • 进程状态仍存活
• 守护日志已连续输出至少两轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%

结论：

• 之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
• 现在真实 FMA 自动承接链路已有更稳的守护启动入口

Stage: 真实 FMA 长时等待器二次掉线复验

完成项：

• 复检长期等待器与日志输出状态
• 确认下载继续前进，但长期等待器再次退出
• 重新拉起等待器，恢复“下载完成后自动后处理”能力

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4102045696
  • archive_progress_percent=53.4149
• 进程侧未发现 wait_for_fma_and_prepare.py
• 日志文件只保留首轮输出：
  • cycle=1
  • archive_progress_percent=52.5032
• 重新启动后，进程再次恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30

结论：

• 下载本身没有停，问题集中在长期等待器稳定性仍不足
• 下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路

Stage: 真实 FMA 等待器寿命缺陷修复

完成项：

• 诊断 wait_for_fma_and_prepare.py 掉线原因
• 确认原实现默认 max-cycles=3，约 90 秒后自然退出
• 修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
• 重新启动长期等待器并验证日志开始产生轮询输出

验证结果：

• 复检下载进度时已达到：
  • archive_size=3886596096
  • archive_progress_percent=50.6094
• 修复后执行：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2 返回两轮 polling，并确认字节继续增长到：
  • 3977117696 -> 3977314304
  • 51.7881% -> 51.7907%
• 长期等待器已重新启动：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30
• 日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON

结论：

• 之前等待器掉线不是下载异常，而是脚本寿命设计过短
• 现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力

Stage: 真实 FMA 守护链路掉线恢复

完成项：

• 再次复检 FMA 下载进度
• 复检后台等待器是否仍存活
• 发现等待器已退出后，重新拉起自动等待与后处理守护链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3650322432
  • archive_progress_percent=47.5327
• 复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
• 等待器日志文件存在但为空：
  • acr-engine/.omx_wait_for_fma.log
• 重新启动后，进程确认恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 新守护进程 pid：51526

结论：

• 真实 FMA 下载仍在持续推进
• 自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态

Stage: 真实 FMA 自动等待与后处理守护启动

完成项：

• 再次复检 FMA 归档进度
• 检查是否已有后台“等待完成后自动后处理”任务
• 启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3518038016
  • archive_progress_percent=45.8102
• 启动后台等待器后，进程确认存在：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 当前后台等待器 pid：51242
• 等待器日志文件已创建：
  • acr-engine/.omx_wait_for_fma.log

结论：

• 除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
• 后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段

Stage: 真实 FMA 下载活跃性复验

完成项：

• 再次采集 FMA 归档字节进度
• 执行 watchdog 续验并附带进程级活跃性确认

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3403972608
  • archive_progress_percent=44.3249
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3406938112
  • archive_progress_percent=44.3635
  • live_curl=true
  • restarted=null
• 进程侧确认：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行

结论：

• 下载链路仍在持续前进且后台拉取进程健康
• 真实 FMA 下游工作仍等待归档完整这一单一前置条件

Stage: 真实 FMA 后处理门槛复验

完成项：

• 再次复检 FMA 下载进度
• 直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3322314752
  • archive_progress_percent=43.2616
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • archive_size=3323641856
  • progress_percent=43.2789

结论：

• 真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
• 当前阻塞已被脚本化验证，不是人工主观判断

Stage: 真实 FMA 下载续进展验证

完成项：

• 再次执行 FMA 归档 inspect
• 执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3222601728
  • archive_progress_percent=41.9632
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3222896640
  • archive_progress_percent=41.967
  • live_curl=true
  • restarted=null
• 对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节

结论：

• 当前下载未卡死，仍在稳定推进
• 真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛

Stage: 真实 FMA 下载状态续验

完成项：

• 复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 复检后台下载进程与本地归档体积
• 确认当前仍未达到可解压/可真实 smoke 的完成门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_bytes_expected=7679594875
  • archive_size=3117514752
  • archive_progress_percent=40.5948
  • num_audio_files=0
• 后台下载进程仍存活：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 当前本地归档文件：
  • data/raw/fma_small.zip = 3.0G

结论：

• 当前主卡点仍是 FMA 归档未完整下载
• 真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续

Stage: 训练数据与 pgvector 专项说明补强

完成项：

• 重写并补强 docs/training-data-and-pgvector-guide.md
• 单独详细说明：
  • 当前训练输入应由音频资产 + song_id 标签 + manifest 组成
  • reference 与 query 的角色区分
  • BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
  • 面向 PostgreSQL + pgvector 的字段保留与入库分层
• 将该专项文档挂接到 docs/README.md 的“数据与评测”主入口

验证结果：

• 已校验文档内新增相对链接全部可达
• 文档已覆盖：
  • 输入格式
  • 切片时长建议
  • label 设计
  • song_id/version_id 规范
  • pgvector 数据模型与入库流程
• 当前引用的仓库内实现锚点：
  • acr-engine/scripts/export_manifest_to_pgvector_json.py
  • acr-engine/sql/pgvector_schema.sql

结论：

• 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
• 新 session 与后续数据工程实现可直接按该文档落地

Stage: 文档浓缩与相对链接跳转

完成项：

• 重构 docs/README.md 为 4 组主文档入口
• 将多处相对路径从反引号文本改为 Markdown 可点击链接
• 收拢“数据接入”阅读入口，降低文档数量感知
• 修正文档内对脚本、manifest、关联文档的跳转方式

验证结果：

• 入口文档现在按：
  • 项目与架构
  • 数据与评测
  • 服务与工程
  • 研究与路线 进行分组
• dataset-spec.md / dataset-sources-and-licensing.md / industrialization-roadmap.md / service-api.md / industrial-benchmark-spec.md 已使用相对链接替代部分反引号路径

结论：

• 文档入口已明显浓缩
• 读者不再需要先面对大量平铺文件名
• 相对路径现在更适合直接跳转

Stage: 开放数据单页工作流

完成项：

• 新增 docs/open-dataset-workflow.md
• 把开放数据接入流程浓缩为：
  • inspect-local / inspect-batch
  • prepare-local
  • validate-local
• 将该工作流挂到 docs/README.md 的“数据与评测”组下

验证结果：

• /usr/local/miniconda3/bin/python src/data/external_adapters.py inspect-local fma data/synthetic_v2/songs --eval-ratio 0.2 --query-duration 5.0 成功
• /usr/local/miniconda3/bin/python src/data/external_adapters.py prepare-local fma data/synthetic_v2/songs --output-root data/external_ingested/synthetic_as_open --eval-ratio 0.2 --query-duration 5.0 成功
• /usr/local/miniconda3/bin/python src/data/external_adapters.py validate-local fma data/external_ingested/synthetic_as_open/fma/manifests 成功
• 当前结果：
  • num_audio_files=24
  • catalog=24
  • train_queries=16
  • test_queries=8
  • ok=true

结论：

• 现在开放数据接入路径已经浓缩成单页可执行工作流
• 后续接真实 FMA / MTG-Jamendo 本地目录时，上手成本更低

Stage: 开放数据 manifests 直连训练

完成项：

• 修复 src/data/manifest_tools.py 生成的开放数据 manifests 路径自洽性
• 让开放数据音频复制到输出根下的 audio/
• 修复 src/data/dataset.py 对 .../manifests 目录布局的路径解析
• 打通 prepare-local -> validate-local -> train.py --dry-run

验证结果：

• /usr/local/miniconda3/bin/python src/data/external_adapters.py prepare-local fma data/synthetic_v2/songs --output-root data/external_ingested/synthetic_as_open_fixed --eval-ratio 0.2 --query-duration 5.0 成功
• /usr/local/miniconda3/bin/python src/data/external_adapters.py validate-local fma data/external_ingested/synthetic_as_open_fixed/fma/manifests 成功
• /usr/local/miniconda3/bin/python train.py --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --output data/models_open_smoke_fixed --device cpu --epochs 1 --batch-size 2 --dry-run 成功
• 当前结果：
  • catalog=24
  • train_queries=16
  • test_queries=8
  • Dry run passed!

结论：

• 开放数据路径现在不仅能生成 manifests，还能真正进入训练
• 后续接入真实 FMA / MTG-Jamendo 时，可以直接走同一链路

Stage: 开放数据完整 smoke 闭环（train/index/eval）

完成项：

• 修复 run_demo.py 对开放数据自包含布局的索引入口假设
• 修复 src/engines/ecapa_embedder.py / src/engines/chromaprint_matcher.py 对 reference 路径的硬编码筛选
• 修复 evaluate.py 对开放数据 query 与 manifests 根路径的解析
• 打通开放数据 prepare-local -> validate-local -> train -> build-index -> evaluate

验证结果：

• /usr/local/miniconda3/bin/python train.py --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --output data/models_open_smoke_fixed --device cpu --epochs 1 --batch-size 2 成功
• /usr/local/miniconda3/bin/python run_demo.py build-index --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --model data/models_open_smoke_fixed/best_model.pt --output data/index_open_smoke_fixed --device cpu 成功
• /usr/local/miniconda3/bin/python evaluate.py --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --model data/models_open_smoke_fixed/best_model.pt --index-prefix data/index_open_smoke_fixed/reference --split test --device cpu --fast-eval --output-json reports/open-smoke-fixed/fma/eval.json 成功
• 当前结果：
  • num_queries=8
  • top1=1.0
  • topk=1.0

结论：

• 开放数据接入链路现在已经完整闭环
• 真实 FMA / MTG-Jamendo 本地目录接入时，可直接复用同一流程

Stage: 开放数据 smoke 发布制品

完成项：

• 为 reports/open-smoke-fixed/fma/ 补充 config.json
• 用 scripts/generate_artifacts.py 生成开放数据 smoke 的：
  • benchmark report
  • model card
  • release checklist
  • artifact manifest

验证结果：

• /usr/local/miniconda3/bin/python scripts/generate_artifacts.py --eval-json reports/open-smoke-fixed/fma/eval.json --config-json reports/open-smoke-fixed/fma/config.json --output-dir reports/open-smoke-fixed/fma --model-version open-smoke-fixed --data-version synthetic_as_open_fixed_fma 成功
• 产物存在：
  • reports/open-smoke-fixed/fma/benchmark-report.md
  • reports/open-smoke-fixed/fma/model-card.md
  • reports/open-smoke-fixed/fma/release-checklist.md
  • reports/open-smoke-fixed/fma/artifact-manifest.json

结论：

• 现在开放数据链路已经不只是“能跑”，还具备基础发布/汇报产物
• 下一步替换成真实 FMA / MTG-Jamendo 本地目录后，可直接复用同一 release 流程

Stage: 一键 open-dataset smoke

完成项：

• 扩展 src/data/external_adapters.py
• 新增 smoke-local
• 一条命令自动执行：
  • inspect-local
  • prepare-local
  • validate-local
  • train
  • build-index
  • evaluate
  • generate_artifacts

验证结果：

• /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/synthetic_v2/songs --output-root data/external_smoke --eval-ratio 0.2 --query-duration 5.0 --train-epochs 1 --batch-size 2 成功
• 当前结果：
  • num_audio_files=24
  • catalog=24
  • train_queries=16
  • test_queries=8
  • top1=1.0
  • topk=1.0
  • 产物目录：data/external_smoke/fma_reports_smoke

结论：

• 现在只要替换 input_dir，就能对真实 FMA / MTG-Jamendo 本地目录跑完整 smoke
• 这显著降低了真实开放数据集接入和验证成本

Stage: 真实开放数据落点目录模板

完成项：

• 新增 acr-engine/data/raw/README.md
• 新建本地开放数据落点目录：
  • acr-engine/data/raw/fma_small_audio/
  • acr-engine/data/raw/mtg_jamendo_audio/
• 将这些目录入口链接接入开放数据工作流与 docs 总入口

验证结果：

• 本地目录已创建：
  • data/raw/
  • data/raw/fma_small_audio/
  • data/raw/mtg_jamendo_audio/
• data/raw/README.md 已包含可直接执行的下一条 smoke 命令模板

结论：

• 现在真实开放数据只需要放进明确目录即可
• 后续替换真实 FMA / MTG-Jamendo 本地音频时无需再猜目录结构

Stage: 新 session 首次启动清单

完成项：

• 新增 acr-engine/FIRST_RUN_CHECKLIST.md
• 把最常用启动检查命令与读文档顺序固化到 repo
• 将 checklist 接入 docs/README.md 与 docs/session-handoff.md

验证结果：

• FIRST_RUN_CHECKLIST.md 已创建
• docs 入口已挂接 checklist

结论：

• 新 session 现在可以更快进入有效开发状态
• 启动成本和漏看关键文档/命令的风险进一步下降

Stage: 状态快照脚本

完成项：

• 新增 acr-engine/scripts/status_snapshot.py
• 统一输出：
  • latest commit
  • 核心 docs 路径
  • 真实数据 drop zones
  • 已验证 smoke 目录
  • 下一步推荐命令
• 将脚本接入 handoff 文档与 first-run checklist

验证结果：

• /usr/local/miniconda3/bin/python scripts/status_snapshot.py 成功
• 输出已正确指向：
  • /workspace/docs/README.md
  • /workspace/docs/session-handoff.md
  • /workspace/docs/open-dataset-workflow.md

结论：

• 新 session 现在不只靠静态文档，也可以直接读取当前仓库状态快照
• 持续开发交接更稳

Stage: 状态快照落盘

完成项：

• 扩展 acr-engine/scripts/status_snapshot.py
• 新增 --output
• 可直接写入 .omx/latest_status_snapshot.json

验证结果：

• /usr/local/miniconda3/bin/python scripts/status_snapshot.py --output .omx/latest_status_snapshot.json 成功
• 已验证：
  • 文件存在
  • JSON 可解析
  • 包含 latest_commit
  • 包含 next_commands

结论：

• 新 session 现在可以直接读取最近一次状态快照文件
• 交接信息更适合自动化和长期持续开发

Stage: FMA 完成前等待并自动切换

完成项：

• 新增 acr-engine/scripts/wait_for_fma_and_prepare.py
• 支持：
  • 周期性检查 FMA archive 是否已完整
  • 完整后自动调用 fma_postdownload_ready.py
  • 未完成时返回结构化 waiting 快照
• 将脚本接入 docs/open-dataset-workflow.md 与 docs/session-handoff.md

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile scripts/wait_for_fma_and_prepare.py 成功
• /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 2 --max-cycles 2 成功
• 当前结果：
  • 第 1 次快照 archive_size=2110291968
  • 第 2 次快照 archive_size=2115256320
  • status=waiting
  • 最新进度 27.5439%

结论：

• 现在仓库已经具备“等待完成 -> 自动切入解压/就绪检查”的衔接能力
• 后续 session 可以用单命令挂起等待，而不是反复手工轮询

Stage: FMA 下载完成后自动就绪

完成项：

• 新增 acr-engine/scripts/fma_postdownload_ready.py
• 在 FMA 整包完成后，可自动执行：
  • extract
  • check-local-ready
  • inspect-local
• 将该脚本挂接到 docs/open-dataset-workflow.md 与 docs/session-handoff.md

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile scripts/fma_postdownload_ready.py 成功
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 成功返回结构化结果
• 当前结果：
  • status=blocked
  • reason=archive_not_complete
  • archive_size=1631584256
  • progress_percent=21.2457

结论：

• 真实 FMA 下载一旦完成，仓库已经具备单命令进入“解压 + 本地就绪检查”的能力
• 后续 session 不需要再手工串接这些步骤

Stage: pgvector bulk load plan 模板

完成项：

• 新增 acr-engine/scripts/pgvector_bulk_load_template.py
• 为 pgvector 导出结果补充 PostgreSQL bulk-load plan 模板
• 在 docs/training-data-and-pgvector-guide.md 中补充对应说明

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile scripts/pgvector_bulk_load_template.py 成功
• /usr/local/miniconda3/bin/python scripts/pgvector_bulk_load_template.py --input reports/pgvector_manifest_export_test.json --output reports/pgvector_bulk_load_plan_test.json 成功
• 当前结果：
  • songs=24
  • references=24
  • segments=20

结论：

• pgvector 方向现在已经具备：
  • schema 模板
  • manifest 导出模板
  • bulk-load plan 模板
• 后续接真实 PostgreSQL 时，只差 live loader，而不是从零设计数据入口

Stage: pgvector 落库模板

完成项：

• 新增 acr-engine/sql/pgvector_schema.sql
• 新增 acr-engine/scripts/export_manifest_to_pgvector_json.py
• 在 docs/training-data-and-pgvector-guide.md 中补充可执行模板说明

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile scripts/export_manifest_to_pgvector_json.py 成功
• /usr/local/miniconda3/bin/python scripts/export_manifest_to_pgvector_json.py --data data/synthetic_v2 --split test --source-dataset synthetic_v2 --output reports/pgvector_manifest_export_test.json 成功
• 当前导出结果：
  • songs=24
  • references=24
  • segments=20

结论：

• pgvector 方向现在不仅有概念文档，还有可直接复用的 schema 和 manifest 导出桥接脚本
• 后续接 PostgreSQL 时返工成本会显著降低

Stage: FMA 下载自动守护

完成项：

• 新增 acr-engine/scripts/watch_fma_download.py
• 支持周期性：
  • inspect 当前下载进度
  • 检查 curl 进程是否存活
  • 如果停滞或进程消失则自动重新触发 bg-download

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile scripts/watch_fma_download.py 成功
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 2 --interval 2 成功
• 当前 watcher 观测到：
  • 第 1 次 archive_size=513179648
  • 第 2 次 archive_size=516587520
  • 两次 live_curl=true
  • 两次 restarted=null（说明下载健康推进，无需重启）
• 最新 inspect：
  • archive_size=522387456
  • archive_progress_percent=6.8023

结论：

• 现在真实 FMA 下载不只可手动恢复，也具备基础自动守护能力
• 长时间下载的持续性进一步增强

Stage: 训练数据与 pgvector 专项文档

完成项：

• 新增 docs/training-data-and-pgvector-guide.md
• 单独详细说明：
  • 当前训练数据/输入数据应该是什么格式
  • reference / query 的角色区分
  • BGM / 手机录音 / 直播录屏如何转成训练数据
  • song_id / type / offset / segment_type 等标签建议
  • 未来接 pgvector 时的推荐表结构与字段设计
• 将该文档挂接到 docs/README.md 与 docs/session-handoff.md

验证结果：

• 文档内容已对齐当前代码行为：
  • acr-engine/src/data/dataset.py
  • acr-engine/src/data/manifest_tools.py
• 已补充从“原始音频 -> 标准化资产 -> manifest -> pgvector”的完整分层说明

结论：

• 现在项目对“训练数据应该长什么样”与“以后怎么接 pgvector”已经有独立、可交接、可执行的文档说明

Stage: FMA 后台续传恢复

完成项：

• 为 acr-engine/scripts/prepare_fma_archive.py 新增 bg-download
• 使用 nohup curl + 日志文件的方式增强大文件后台续传稳定性
• 在发现下载停滞后，切换到新的后台恢复路径并重新托管 ModelScope 下载

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py bg-download 成功
• 当前返回：
  • returncode=0
  • pid=47175
  • log_path=/tmp/fma_modelscope_download.log
• 重新 inspect 后结果：
  • archive_size 从 61550592 增长到 71835648
  • archive_progress_percent=0.9354
• 日志验证：
  • Resuming transfer from byte position 61550592
  • 当前吞吐已达到 MB/s 级别

结论：

• FMA 真实数据下载不再依赖脆弱的一次性前台命令
• 当前已恢复到可持续的后台续传状态，后续 session 更容易接力

Stage: FMA 下载进度可视化

完成项：

• 增强 acr-engine/scripts/prepare_fma_archive.py 的 inspect 输出
• 新增：
  • archive_bytes_expected
  • archive_progress_ratio
  • archive_progress_percent

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile scripts/prepare_fma_archive.py 成功
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 成功
• 当前结果：
  • archive_size=61550592
  • archive_progress_percent=0.8015

结论：

• 新 session 现在不需要手工换算大包下载进度
• 长时间 FMA 下载的交接成本进一步降低

Stage: FMA 源切换到 ModelScope

完成项：

• 将 acr-engine/scripts/prepare_fma_archive.py 的默认 FMA 整包源切换到用户提供的 ModelScope 地址
• 同步更新：
  • acr-engine/data/raw/README.md
  • docs/open-dataset-workflow.md
  • docs/session-handoff.md
• 通过 repo 内脚本重新启动托管下载流程

验证结果：

• curl -I -L --max-time 60 https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 成功
• 当前响应关键信息：
  • 200
  • content-length=7679594875
  • accept-ranges: bytes
• curl -L --range 0-1023 ... 成功获取 1024 bytes
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 成功
• 当前结果：
  • archive_url=https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
  • archive_size=53620736
  • 托管下载进程存在：prepare_fma_archive.py download

结论：

• 真实 FMA 下载现在已切换到用户指定的 ModelScope 通道
• 下载控制面也已统一回 repo 内脚本，后续 session 更容易续传与接力

Stage: 服务 HTTP smoke

完成项：

• 新增 acr-engine/scripts/service_smoke.py
• 用 uvicorn 真正拉起 FastAPI 服务，而不是只做函数级调用
• 更新 acr-engine/README.md 与 docs/service-api.md 的服务运行说明

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile scripts/service_smoke.py 成功
• /usr/local/miniconda3/bin/python scripts/service_smoke.py 成功
• 当前 smoke 已验证：
  • /health
  • /ready
  • /config
  • /cache
• 当前结果：
  • health.ready=true
  • ready.ready=true
  • engine_cache_size=0（未执行 recognize 前）

结论：

• 服务现在已经具备最小 HTTP 级 smoke 验证
• 后续继续做鉴权、异步任务、监控时，有了更真实的回归入口

Stage: 服务就绪探针与缓存可见性

完成项：

• 增强 acr-engine/src/service/app.py
• 新增：
  • /ready
  • /cache
• 为服务默认模型/索引/manifest 增加 readiness 快照
• 为 HybridEngine 增加进程内缓存，避免同配置重复重载
• 更新 docs/service-api.md

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile src/service/app.py 成功
• 直接调用 health() / ready() / cache_status() 成功
• 直接调用 _load_engine() 两次成功
• 当前结果：
  • 默认 service ready=true
  • 首次加载 cache_hit=false
  • 第二次加载 cache_hit=true
  • same_object=true

结论：

• 服务层现在不再只是“能调接口”的骨架
• 已具备最基本的就绪探针与缓存可见性，更接近工业级内网服务原型

Stage: FMA 整包下载/解压脚手架

完成项：

• 新增 acr-engine/scripts/prepare_fma_archive.py
• 支持：
  • inspect
  • download（支持 resume）
  • extract
• 将 FMA 官方整包路径接入：
  • acr-engine/data/raw/README.md
  • docs/open-dataset-workflow.md

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile scripts/prepare_fma_archive.py 成功
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 成功
• 当前结果：
  • archive_exists=true
  • archive_size=9404416
  • extract_exists=true
  • num_audio_files=0

结论：

• 真实 FMA 整包路径现在不仅在下载，而且已经有标准化的 inspect/download/extract 工具链
• 即使下载耗时较长，后续 session 也能直接续传与接力

Stage: FMA 官方整包下载路径确认

完成项：

• 进一步验证 FMA Small 的稳定 archive 下载路径
• 确认 fma_small.zip 可通过官方归档地址直接访问
• 将该路径补充到开放数据工作流与交接文档

验证结果：

• curl -I -L --max-time 60 https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 成功
• 当前响应头关键信息：
  • 200 OK
  • Content-Type: application/zip
  • Content-Length: 7679594875
  • Accept-Ranges: bytes
• curl -L --range 0-1023 ... 成功获取前 1024 bytes

结论：

• FMA 真实数据已经不再缺下载地址
• 当前剩余问题从“找不到稳定 URL”转为“是否开始实际拉取 7.68 GB 归档并落盘”

Stage: FMA 下载器模块调用修复

完成项：

• 修复 acr-engine/scripts/fetch_fma_subset.py 的 yt-dlp 检测方式
• 从 shell 可执行查找改为优先支持：
  • yt-dlp 可执行文件
  • /usr/local/miniconda3/bin/python -m yt_dlp 模块调用
• 重新执行真实 FMA bounded 下载验证

验证结果：

• which yt-dlp 仍为空
• /usr/local/miniconda3/bin/python -m yt_dlp --version 成功，版本 2026.03.17
• /usr/local/miniconda3/bin/python scripts/fetch_fma_subset.py --report reports/fma_fetch_subset_report.json 成功执行
• 当前结果：
  • ytdlp_cmd=["/usr/local/miniconda3/bin/python", "-m", "yt_dlp"]
  • 8/8 请求均失败
  • 失败原因已从“工具缺失”收敛为 freemusicarchive.org/music/track/<id> 返回 HTTP 404

结论：

• 下载脚本的模块调用问题已经修复
• 当前真实阻塞不再是本地环境，而是 FMA 历史页面 URL 路径已不可用
• 下一步应转向官方整包或稳定镜像，而不是继续重试旧页面 URL

Stage: FMA 真实下载脚手架

完成项：

• 新增 acr-engine/scripts/fetch_fma_subset.py
• 先验证了旧版 FMA 文件直链抓取路径
• 再切换为页面级抓取脚手架，并显式输出阻塞原因
• 将当前真实 FMA 下载状态记录进：
  • docs/open-dataset-workflow.md
  • docs/session-handoff.md

验证结果：

• /usr/local/miniconda3/bin/python scripts/fetch_fma_subset.py --report reports/fma_fetch_subset_report.json 已执行两轮验证
• 第一轮结果：8 个 track id 全部 HTTP 403
• 第二轮结果：yt-dlp not found，脚本返回结构化 blocked JSON

结论：

• 真实 FMA 下载自动化入口已具备
• 但当前环境下仍缺稳定可用下载通道，尚不能宣称真实 FMA 已成功落地
• 该阻塞已经被显式固化到交接文档中，避免新 session 重复踩坑

Stage: 原始开放数据 LFS 治理

完成项：

• 新增根目录 /.gitattributes
• 为 acr-engine/data/raw/ 下的大文件与音频配置 Git LFS 跟踪策略
• 重写 acr-engine/data/raw/README.md，补充：
  • 数据落点职责表
  • check-local-ready -> smoke-local 最短路径
  • 原始数据下载 / LFS 治理策略
• 补充 docs/dataset-sources-and-licensing.md 的下载 / LFS 治理说明

验证结果：

• git lfs version 成功
• git check-attr filter -- acr-engine/data/raw/fma_small_audio/example.wav 返回 filter: lfs
• git check-attr filter -- acr-engine/data/raw/archive.zip 返回 filter: lfs
• 文档已明确区分：
  • 工程可用性
  • benchmark 适用性
  • 商用可部署性

结论：

• 仓库现在具备承接真实开放音频和压缩包的 LFS 基础设施
• 后续下载真实数据时，不会直接把大文件塞进普通 git 历史

Stage: 真实数据就绪度守门

完成项：

• 为 acr-engine/src/data/external_adapters.py 新增 check-local-ready
• 为 smoke-local 增加前置就绪度守门，避免对空目录直接进入训练链路
• 增强 acr-engine/scripts/status_snapshot.py，输出：
  • dataset_readiness
  • capability_map 文档入口
  • check-local-ready 下一步命令
• 补充 docs/open-dataset-workflow.md 与 docs/session-handoff.md 的真实数据检查说明

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile src/data/external_adapters.py scripts/status_snapshot.py 成功
• /usr/local/miniconda3/bin/python src/data/external_adapters.py check-local-ready fma data/raw/fma_small_audio --eval-ratio 0.2 --query-duration 8.0 成功
• /usr/local/miniconda3/bin/python src/data/external_adapters.py check-local-ready mtg_jamendo data/raw/mtg_jamendo_audio --eval-ratio 0.2 --query-duration 8.0 成功
• /usr/local/miniconda3/bin/python scripts/status_snapshot.py --output .omx/latest_status_snapshot.json 成功
• 当前结果：
  • fma.ready_for_smoke=false
  • mtg_jamendo.ready_for_smoke=false
  • 原因均为音频文件数与可切 query 文件数不足

结论：

• 真实开放数据现在有了明确的“进入 smoke 前门槛”
• 新 session 和自动化脚本可以立刻识别空目录，而不是误以为真实数据已经准备完成

Stage: 当前能力地图

完成项：

• 新增 docs/current-capability-map.md
• 明确区分：
  • 已完整闭环
  • 已打通但仍是 smoke 级
  • 仍待真实数据/更大规模验证
• 将能力地图接入 docs 总入口与交接文档

验证结果：

• docs/current-capability-map.md 已创建
• docs/README.md 已挂接
• docs/session-handoff.md 已挂接

结论：

• 新 session 现在更容易快速判断“什么是真的完成了，什么还只是 smoke 级能力”
• 能显著减少误判项目状态的风险

Stage: confused 定向优化 v6（sample-level weighting）

完成项：

• 将 hard-case loss 从 batch 级平均权重改为 sample-level weighting
• SongPairDataset 改为对 confused / humming_like 区分采样强度
• confused 样本权重提高到更高优先级
• 重训 models_v6、重建 index_v6、重跑 smoke-v6 评测
• 生成 reports/smoke-v6/synthetic_v2/ 发布制品
• 补充 docs/dataset-spec.md 中的 hard-case 输入规范说明
• 补充 docs/sota-research-2026.md 中的 v4/v5/v6 对比结论

验证结果：

• train.py --dry-run 成功
• py_compile 成功
• run_demo.py build-index 成功
• evaluate.py --fast-eval --output-json reports/smoke-v6/synthetic_v2/eval.json 成功
• 当前结果：
  • overall top1=0.65, top5=0.95
  • humming_like top1=0.25
  • confused top1=0.25

结论：

• 相比 smoke-v5，overall top1 从 0.60 提升到 0.65
• confused top1 从 0.00 提升到 0.25，说明 sample-level 权重有效
• humming_like top1 从 0.50 回落到 0.25，说明两类 hard case 需要分治，而不能只靠单轴加权

Stage: v7 平衡采样试验（未保留）

完成项：

• 尝试降低 confused 偏置并提高 humming_like 采样强度
• 重跑 smoke-v7 全链路验证
• 基于失败样本回查 residual hard case 的 segment 分布

验证结果：

• smoke-v7 结果退化为：
  • overall top1=0.55, top5=0.80
  • humming_like top1=0.00
  • confused top1=0.00
• 因结果明显回退，已回滚该试验，不作为主线版本保留

结论：

• 单纯重调全局采样比率不稳定
• 当前最优保留点仍是 smoke-v6
• residual confused failure 主要落在 intro 片段，下一轮应改做 segment_type-aware hard negatives

Stage: 检索融合权重参数化 + fast-eval 调优

完成项：

• evaluate.py 新增融合参数：
  • --chroma-weight
  • --ecapa-weight
  • --melody-weight
• 在稳定的 models_v6 + index_v6 资产上做 fresh fast-eval 对比
• 验证 retrieval-time fusion 调优是否比继续改训练权重更有效

验证结果：

• 默认 fast-eval：
  • overall top1=0.65
  • humming_like top1=0.25
  • confused top1=0.25
• 调整为 chroma=0.2 / ecapa=0.55 / melody=0.25 后：
  • overall top1=0.70
  • humming_like top1=0.50
  • confused top1=0.25

结论：

• 在当前阶段，检索融合调优 比继续调训练侧权重更稳定、更划算
• ecapa 权重略升、chroma 略降能恢复 humming_like，同时保持 confused
• 下一阶段应继续把外部开源数据集真正接成 train/eval manifests，而不是只停在 bootstrap

Stage: 开源数据集 ingestion（train/eval manifests）

完成项：

• 扩展 src/data/manifest_tools.py
• 新增 audio-dir-to-splits CLI
• 支持从本地开放音频目录自动生成：
  • catalog.json
  • train.json
  • test.json
  • val.json
• 新增小数据集保护，确保个人使用场景下也能同时有 train/test queries

验证结果：

• python -m py_compile src/data/manifest_tools.py 成功
• 使用本地 demo 音频目录成功生成真实 manifests
• 修正后小样本结果：
  • catalog=2
  • train_queries=1
  • test_queries=1

结论：

• 项目现在不再只停留在 external bootstrap
• 已经具备把开源音乐数据目录直接切成训练/评估输入的能力
• 下一阶段可以继续对接真实 FMA / MTG-Jamendo 下载目录

Stage: adapter-level 本地开源目录接入

完成项：

• 扩展 src/data/external_adapters.py
• 新增 prepare-local 命令
• 支持通过 adapter 入口直接把本地开源音频目录转成：
  • catalog.json
  • train.json
  • test.json
  • val.json

验证结果：

• python -m py_compile src/data/external_adapters.py src/data/manifest_tools.py 成功
• python src/data/external_adapters.py prepare-local fma tmp/open_music_demo --output-root data/external_ingested/demo_via_adapter --eval-ratio 0.5 --query-duration 5.0 成功
• 输出结果：
  • catalog=2
  • train_queries=1
  • test_queries=1

结论：

• 现在接入真实 FMA / MTG-Jamendo 目录时，不需要再手动拼 manifests
• adapter 已经能作为统一入口管理开放数据集的训练/评估切分

Stage: 开源目录规模扫描（inspect-local）

完成项：

• 扩展 src/data/manifest_tools.py
• 新增 inspect-audio-dir
• 扩展 src/data/external_adapters.py
• 新增 inspect-local
• 在真正生成 manifests 之前，可以先报告：
  • 音频文件数量
  • 可切 query 的文件数
  • 推荐 train/test query 数
  • 基础时长统计

验证结果：

• python -m py_compile src/data/manifest_tools.py src/data/external_adapters.py 成功
• python src/data/manifest_tools.py inspect-audio-dir tmp/open_music_demo --query-duration 5.0 --eval-ratio 0.5 成功
• python src/data/external_adapters.py inspect-local fma tmp/open_music_demo --eval-ratio 0.5 --query-duration 5.0 成功
• 返回结果：
  • num_audio_files=2
  • eligible_query_files=2
  • recommended_train_queries=1
  • recommended_test_queries=1

结论：

• 现在真实 FMA / MTG-Jamendo 目录在导入前就能先做规模预估
• 这对个人使用下的快速数据准备非常有帮助

Stage: 多目录批量 inventory（inspect-batch）

完成项：

• 扩展 src/data/external_adapters.py
• 新增 inspect-batch
• 支持一次性检查多个开放数据目录，例如：
  • fma=<dir>
  • mtg_jamendo=<dir>

验证结果：

• python -m py_compile src/data/external_adapters.py src/data/manifest_tools.py 成功
• python src/data/external_adapters.py inspect-batch fma=tmp/open_music_demo_fma mtg_jamendo=tmp/open_music_demo_jamendo --eval-ratio 0.5 --query-duration 5.0 成功
• 返回：
  • count=2
  • 每个数据源均给出 num_audio_files / eligible_query_files / recommended_train_queries / recommended_test_queries

结论：

• 现在可以批量对比多个候选开放数据目录的可用规模
• 这让后续接入真实 FMA / MTG-Jamendo / 其他音乐集更高效

2026-06-02

Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：

• 复检归档下载状态，确认 fma_small.zip 已达完整字节数
• 验证本地 FMA 音频目录已可用于真实 smoke
• 直接启动真实 FMA smoke-local，进入训练/索引/评测主链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=7679594875
  • archive_progress_percent=100.0
  • num_audio_files=3025（inspect 阶段）
• 本地解压目录复检：
  • find data/raw/fma_small_audio ... | wc -l 返回 5827
  • check-local-ready / inspect-local 返回：
  • ready_for_smoke=true
  • num_audio_files=8000
  • eligible_query_files=7994
  • recommended_train_queries=6395
  • recommended_test_queries=1599
• 真实 smoke 已启动：
  • /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/raw/fma_small_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2
• 当前训练侧实时证据：
  • Device: cpu
  • Classes: 6381
  • Train songs: 6381
  • Epoch 1 已启动
  • 当前 epoch 总 batch 数：3191

结论：

• 真实 FMA 数据下载门槛已正式打开
• 项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段

Stage: 真实 FMA 下载超过八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 09:28
• 守护日志已增长到至少 19 轮：
  • cycle=18, 83.937%
  • cycle=19, 85.7155%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6724517888
  • archive_progress_percent=87.5634
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=87.5649

结论：

• detached guard 已在九分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 08:25
• 守护日志已增长到至少 17 轮：
  • cycle=16, 81.1776%
  • cycle=17, 82.7758%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6432636928
  • archive_progress_percent=83.7627
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=83.764

结论：

• detached guard 已在八分钟级别继续稳定驻留
• 真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过八成

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 复检后处理门槛是否仍未打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 07:15
• 守护日志已增长到至少 15 轮：
  • cycle=14, 78.2606%
  • cycle=15, 79.6962%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6173982720
  • archive_progress_percent=80.3946
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=80.3946

结论：

• detached guard 已在七分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过四分之三

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 06:12
• 守护日志已增长到至少 13 轮：
  • cycle=12, 75.3734%
  • cycle=13, 76.9423%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5953486848
  • archive_progress_percent=77.5234
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=77.5247

结论：

• detached guard 已在六分钟级别继续稳定驻留
• 真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近四分之三

完成项：

• 再次复检 detached guard 的更长时段存活情况
• 采集新的多轮日志增长证据
• 再次确认后处理门槛是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 05:19
• 守护日志已增长到至少 11 轮：
  • cycle=10, 72.2831%
  • cycle=11, 73.8305%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5748047872
  • archive_progress_percent=74.8483
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=74.8485

结论：

• detached guard 已在五分钟级别继续稳定驻留
• 真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛

Stage: 真实 FMA 下载超过七成

完成项：

• 再次复检 detached guard 长时运行状态
• 采集新一轮日志增长证据
• 复检后处理门槛是否已经打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 04:16
• 守护日志已增长到至少 9 轮：
  • cycle=8, 68.0898%
  • cycle=9, 70.2949%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5479727104
  • archive_progress_percent=71.3544
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=71.3559

结论：

• detached guard 在更长时间窗口内继续稳定工作
• 真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛

Stage: 真实 FMA 下载进度过三分之二

完成项：

• 再次复检 detached guard 的持续运行情况
• 采集新的多轮日志增长证据
• 复检后处理门槛是否已打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 03:19
• 守护日志已增长到至少 7 轮：
  • cycle=6, 63.9577%
  • cycle=7, 65.6775%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5160501248
  • archive_progress_percent=67.1976
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=67.1995

结论：

• detached guard 在更长时段内继续稳定工作
• 真实 FMA 下载已超过三分之二，但后处理门槛仍未打开

Stage: 真实 FMA 守护长时稳定性再验证

完成项：

• 再次复检 detached guard 进程与运行时长
• 检查守护日志是否继续稳定跨轮输出
• 再次复检后处理门槛状态

验证结果：

• 守护进程继续存活：
  • pid=52277
  • PPID=1
  • 运行时长 02:15
• 守护日志已继续增长到至少 5 轮：
  • cycle=4, 60.0672%
  • cycle=5, 62.0764%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4836065280
  • archive_progress_percent=62.9729
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=62.9733

结论：

• detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
• 当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数

Stage: 真实 FMA 守护稳定性续验

完成项：

• 复检新守护进程 pid 与运行时长
• 复检守护日志是否已跨更多轮持续输出
• 再次执行后处理就绪检查，确认是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 01:29
• 守护日志已连续输出至少 3 轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%
  • cycle=3, 58.5098%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4612112384
  • archive_progress_percent=60.0567
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=60.0582

结论：

• 新的守护启动方式已表现出明显更好的长期稳定性
• 当前唯一阻塞继续保持为：FMA 归档尚未完整下载

Stage: 真实 FMA 后台守护方式稳定化

完成项：

• 对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
• 判断二次掉线更可能来自后台脱离方式而非轮询逻辑
• 新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
• 验证新守护方式可跨多轮轮询持续存活

验证结果：

• 前台验证：
  • /usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3 连续输出 3 轮 polling，并正常结束为 status=waiting
• 下载进度继续增长到：
  • 4261445632 -> 4265574400
  • 55.4905% -> 55.5443%
• 新守护脚本启动后：
  • pid=52277
  • PPID=1
  • 进程状态仍存活
• 守护日志已连续输出至少两轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%

结论：

• 之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
• 现在真实 FMA 自动承接链路已有更稳的守护启动入口

Stage: 真实 FMA 长时等待器二次掉线复验

完成项：

• 复检长期等待器与日志输出状态
• 确认下载继续前进，但长期等待器再次退出
• 重新拉起等待器，恢复“下载完成后自动后处理”能力

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4102045696
  • archive_progress_percent=53.4149
• 进程侧未发现 wait_for_fma_and_prepare.py
• 日志文件只保留首轮输出：
  • cycle=1
  • archive_progress_percent=52.5032
• 重新启动后，进程再次恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30

结论：

• 下载本身没有停，问题集中在长期等待器稳定性仍不足
• 下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路

Stage: 真实 FMA 等待器寿命缺陷修复

完成项：

• 诊断 wait_for_fma_and_prepare.py 掉线原因
• 确认原实现默认 max-cycles=3，约 90 秒后自然退出
• 修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
• 重新启动长期等待器并验证日志开始产生轮询输出

验证结果：

• 复检下载进度时已达到：
  • archive_size=3886596096
  • archive_progress_percent=50.6094
• 修复后执行：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2 返回两轮 polling，并确认字节继续增长到：
  • 3977117696 -> 3977314304
  • 51.7881% -> 51.7907%
• 长期等待器已重新启动：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30
• 日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON

结论：

• 之前等待器掉线不是下载异常，而是脚本寿命设计过短
• 现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力

Stage: 真实 FMA 守护链路掉线恢复

完成项：

• 再次复检 FMA 下载进度
• 复检后台等待器是否仍存活
• 发现等待器已退出后，重新拉起自动等待与后处理守护链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3650322432
  • archive_progress_percent=47.5327
• 复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
• 等待器日志文件存在但为空：
  • acr-engine/.omx_wait_for_fma.log
• 重新启动后，进程确认恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 新守护进程 pid：51526

结论：

• 真实 FMA 下载仍在持续推进
• 自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态

Stage: 真实 FMA 自动等待与后处理守护启动

完成项：

• 再次复检 FMA 归档进度
• 检查是否已有后台“等待完成后自动后处理”任务
• 启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3518038016
  • archive_progress_percent=45.8102
• 启动后台等待器后，进程确认存在：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 当前后台等待器 pid：51242
• 等待器日志文件已创建：
  • acr-engine/.omx_wait_for_fma.log

结论：

• 除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
• 后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段

Stage: 真实 FMA 下载活跃性复验

完成项：

• 再次采集 FMA 归档字节进度
• 执行 watchdog 续验并附带进程级活跃性确认

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3403972608
  • archive_progress_percent=44.3249
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3406938112
  • archive_progress_percent=44.3635
  • live_curl=true
  • restarted=null
• 进程侧确认：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行

结论：

• 下载链路仍在持续前进且后台拉取进程健康
• 真实 FMA 下游工作仍等待归档完整这一单一前置条件

Stage: 真实 FMA 后处理门槛复验

完成项：

• 再次复检 FMA 下载进度
• 直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3322314752
  • archive_progress_percent=43.2616
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • archive_size=3323641856
  • progress_percent=43.2789

结论：

• 真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
• 当前阻塞已被脚本化验证，不是人工主观判断

Stage: 真实 FMA 下载续进展验证

完成项：

• 再次执行 FMA 归档 inspect
• 执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3222601728
  • archive_progress_percent=41.9632
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3222896640
  • archive_progress_percent=41.967
  • live_curl=true
  • restarted=null
• 对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节

结论：

• 当前下载未卡死，仍在稳定推进
• 真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛

Stage: 真实 FMA 下载状态续验

完成项：

• 复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 复检后台下载进程与本地归档体积
• 确认当前仍未达到可解压/可真实 smoke 的完成门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_bytes_expected=7679594875
  • archive_size=3117514752
  • archive_progress_percent=40.5948
  • num_audio_files=0
• 后台下载进程仍存活：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 当前本地归档文件：
  • data/raw/fma_small.zip = 3.0G

结论：

• 当前主卡点仍是 FMA 归档未完整下载
• 真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续

Stage: 训练数据与 pgvector 专项说明补强

完成项：

• 重写并补强 docs/training-data-and-pgvector-guide.md
• 单独详细说明：
  • 当前训练输入应由音频资产 + song_id 标签 + manifest 组成
  • reference 与 query 的角色区分
  • BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
  • 面向 PostgreSQL + pgvector 的字段保留与入库分层
• 将该专项文档挂接到 docs/README.md 的“数据与评测”主入口

验证结果：

• 已校验文档内新增相对链接全部可达
• 文档已覆盖：
  • 输入格式
  • 切片时长建议
  • label 设计
  • song_id/version_id 规范
  • pgvector 数据模型与入库流程
• 当前引用的仓库内实现锚点：
  • acr-engine/scripts/export_manifest_to_pgvector_json.py
  • acr-engine/sql/pgvector_schema.sql

结论：

• 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
• 新 session 与后续数据工程实现可直接按该文档落地

Stage: 文档补全 + ACR 最小可运行链路

完成项：

• 补充项目职责图：docs/project-responsibility-map.md
• 补充系统架构图：docs/acr-architecture.md
• 补充阶段路线图：docs/roadmap.md
• 补充运行手册：docs/runbook.md
• 补充引擎说明：acr-engine/README.md
• 新增依赖清单：acr-engine/requirements.txt
• 新增 demo CLI：acr-engine/run_demo.py
• 修复数据集读取路径问题：acr-engine/src/data/dataset.py
• 修复首次训练不落 best checkpoint 的问题：acr-engine/train.py

验证结果：

• 已生成 synthetic dataset
• 已通过 train.py --dry-run
• 已完成 1 epoch CPU 训练并生成 best_model.pt
• 已完成指纹索引与 embedding 索引构建
• 已完成识别命令并输出 JSON 候选结果

2026-06-02

Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：

• 复检归档下载状态，确认 fma_small.zip 已达完整字节数
• 验证本地 FMA 音频目录已可用于真实 smoke
• 直接启动真实 FMA smoke-local，进入训练/索引/评测主链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=7679594875
  • archive_progress_percent=100.0
  • num_audio_files=3025（inspect 阶段）
• 本地解压目录复检：
  • find data/raw/fma_small_audio ... | wc -l 返回 5827
  • check-local-ready / inspect-local 返回：
  • ready_for_smoke=true
  • num_audio_files=8000
  • eligible_query_files=7994
  • recommended_train_queries=6395
  • recommended_test_queries=1599
• 真实 smoke 已启动：
  • /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/raw/fma_small_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2
• 当前训练侧实时证据：
  • Device: cpu
  • Classes: 6381
  • Train songs: 6381
  • Epoch 1 已启动
  • 当前 epoch 总 batch 数：3191

结论：

• 真实 FMA 数据下载门槛已正式打开
• 项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段

Stage: 真实 FMA 下载超过八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 09:28
• 守护日志已增长到至少 19 轮：
  • cycle=18, 83.937%
  • cycle=19, 85.7155%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6724517888
  • archive_progress_percent=87.5634
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=87.5649

结论：

• detached guard 已在九分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 08:25
• 守护日志已增长到至少 17 轮：
  • cycle=16, 81.1776%
  • cycle=17, 82.7758%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6432636928
  • archive_progress_percent=83.7627
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=83.764

结论：

• detached guard 已在八分钟级别继续稳定驻留
• 真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过八成

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 复检后处理门槛是否仍未打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 07:15
• 守护日志已增长到至少 15 轮：
  • cycle=14, 78.2606%
  • cycle=15, 79.6962%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6173982720
  • archive_progress_percent=80.3946
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=80.3946

结论：

• detached guard 已在七分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过四分之三

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 06:12
• 守护日志已增长到至少 13 轮：
  • cycle=12, 75.3734%
  • cycle=13, 76.9423%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5953486848
  • archive_progress_percent=77.5234
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=77.5247

结论：

• detached guard 已在六分钟级别继续稳定驻留
• 真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近四分之三

完成项：

• 再次复检 detached guard 的更长时段存活情况
• 采集新的多轮日志增长证据
• 再次确认后处理门槛是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 05:19
• 守护日志已增长到至少 11 轮：
  • cycle=10, 72.2831%
  • cycle=11, 73.8305%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5748047872
  • archive_progress_percent=74.8483
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=74.8485

结论：

• detached guard 已在五分钟级别继续稳定驻留
• 真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛

Stage: 真实 FMA 下载超过七成

完成项：

• 再次复检 detached guard 长时运行状态
• 采集新一轮日志增长证据
• 复检后处理门槛是否已经打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 04:16
• 守护日志已增长到至少 9 轮：
  • cycle=8, 68.0898%
  • cycle=9, 70.2949%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5479727104
  • archive_progress_percent=71.3544
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=71.3559

结论：

• detached guard 在更长时间窗口内继续稳定工作
• 真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛

Stage: 真实 FMA 下载进度过三分之二

完成项：

• 再次复检 detached guard 的持续运行情况
• 采集新的多轮日志增长证据
• 复检后处理门槛是否已打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 03:19
• 守护日志已增长到至少 7 轮：
  • cycle=6, 63.9577%
  • cycle=7, 65.6775%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5160501248
  • archive_progress_percent=67.1976
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=67.1995

结论：

• detached guard 在更长时段内继续稳定工作
• 真实 FMA 下载已超过三分之二，但后处理门槛仍未打开

Stage: 真实 FMA 守护长时稳定性再验证

完成项：

• 再次复检 detached guard 进程与运行时长
• 检查守护日志是否继续稳定跨轮输出
• 再次复检后处理门槛状态

验证结果：

• 守护进程继续存活：
  • pid=52277
  • PPID=1
  • 运行时长 02:15
• 守护日志已继续增长到至少 5 轮：
  • cycle=4, 60.0672%
  • cycle=5, 62.0764%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4836065280
  • archive_progress_percent=62.9729
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=62.9733

结论：

• detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
• 当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数

Stage: 真实 FMA 守护稳定性续验

完成项：

• 复检新守护进程 pid 与运行时长
• 复检守护日志是否已跨更多轮持续输出
• 再次执行后处理就绪检查，确认是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 01:29
• 守护日志已连续输出至少 3 轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%
  • cycle=3, 58.5098%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4612112384
  • archive_progress_percent=60.0567
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=60.0582

结论：

• 新的守护启动方式已表现出明显更好的长期稳定性
• 当前唯一阻塞继续保持为：FMA 归档尚未完整下载

Stage: 真实 FMA 后台守护方式稳定化

完成项：

• 对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
• 判断二次掉线更可能来自后台脱离方式而非轮询逻辑
• 新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
• 验证新守护方式可跨多轮轮询持续存活

验证结果：

• 前台验证：
  • /usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3 连续输出 3 轮 polling，并正常结束为 status=waiting
• 下载进度继续增长到：
  • 4261445632 -> 4265574400
  • 55.4905% -> 55.5443%
• 新守护脚本启动后：
  • pid=52277
  • PPID=1
  • 进程状态仍存活
• 守护日志已连续输出至少两轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%

结论：

• 之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
• 现在真实 FMA 自动承接链路已有更稳的守护启动入口

Stage: 真实 FMA 长时等待器二次掉线复验

完成项：

• 复检长期等待器与日志输出状态
• 确认下载继续前进，但长期等待器再次退出
• 重新拉起等待器，恢复“下载完成后自动后处理”能力

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4102045696
  • archive_progress_percent=53.4149
• 进程侧未发现 wait_for_fma_and_prepare.py
• 日志文件只保留首轮输出：
  • cycle=1
  • archive_progress_percent=52.5032
• 重新启动后，进程再次恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30

结论：

• 下载本身没有停，问题集中在长期等待器稳定性仍不足
• 下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路

Stage: 真实 FMA 等待器寿命缺陷修复

完成项：

• 诊断 wait_for_fma_and_prepare.py 掉线原因
• 确认原实现默认 max-cycles=3，约 90 秒后自然退出
• 修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
• 重新启动长期等待器并验证日志开始产生轮询输出

验证结果：

• 复检下载进度时已达到：
  • archive_size=3886596096
  • archive_progress_percent=50.6094
• 修复后执行：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2 返回两轮 polling，并确认字节继续增长到：
  • 3977117696 -> 3977314304
  • 51.7881% -> 51.7907%
• 长期等待器已重新启动：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30
• 日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON

结论：

• 之前等待器掉线不是下载异常，而是脚本寿命设计过短
• 现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力

Stage: 真实 FMA 守护链路掉线恢复

完成项：

• 再次复检 FMA 下载进度
• 复检后台等待器是否仍存活
• 发现等待器已退出后，重新拉起自动等待与后处理守护链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3650322432
  • archive_progress_percent=47.5327
• 复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
• 等待器日志文件存在但为空：
  • acr-engine/.omx_wait_for_fma.log
• 重新启动后，进程确认恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 新守护进程 pid：51526

结论：

• 真实 FMA 下载仍在持续推进
• 自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态

Stage: 真实 FMA 自动等待与后处理守护启动

完成项：

• 再次复检 FMA 归档进度
• 检查是否已有后台“等待完成后自动后处理”任务
• 启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3518038016
  • archive_progress_percent=45.8102
• 启动后台等待器后，进程确认存在：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 当前后台等待器 pid：51242
• 等待器日志文件已创建：
  • acr-engine/.omx_wait_for_fma.log

结论：

• 除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
• 后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段

Stage: 真实 FMA 下载活跃性复验

完成项：

• 再次采集 FMA 归档字节进度
• 执行 watchdog 续验并附带进程级活跃性确认

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3403972608
  • archive_progress_percent=44.3249
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3406938112
  • archive_progress_percent=44.3635
  • live_curl=true
  • restarted=null
• 进程侧确认：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行

结论：

• 下载链路仍在持续前进且后台拉取进程健康
• 真实 FMA 下游工作仍等待归档完整这一单一前置条件

Stage: 真实 FMA 后处理门槛复验

完成项：

• 再次复检 FMA 下载进度
• 直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3322314752
  • archive_progress_percent=43.2616
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • archive_size=3323641856
  • progress_percent=43.2789

结论：

• 真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
• 当前阻塞已被脚本化验证，不是人工主观判断

Stage: 真实 FMA 下载续进展验证

完成项：

• 再次执行 FMA 归档 inspect
• 执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3222601728
  • archive_progress_percent=41.9632
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3222896640
  • archive_progress_percent=41.967
  • live_curl=true
  • restarted=null
• 对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节

结论：

• 当前下载未卡死，仍在稳定推进
• 真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛

Stage: 真实 FMA 下载状态续验

完成项：

• 复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 复检后台下载进程与本地归档体积
• 确认当前仍未达到可解压/可真实 smoke 的完成门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_bytes_expected=7679594875
  • archive_size=3117514752
  • archive_progress_percent=40.5948
  • num_audio_files=0
• 后台下载进程仍存活：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 当前本地归档文件：
  • data/raw/fma_small.zip = 3.0G

结论：

• 当前主卡点仍是 FMA 归档未完整下载
• 真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续

Stage: 训练数据与 pgvector 专项说明补强

完成项：

• 重写并补强 docs/training-data-and-pgvector-guide.md
• 单独详细说明：
  • 当前训练输入应由音频资产 + song_id 标签 + manifest 组成
  • reference 与 query 的角色区分
  • BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
  • 面向 PostgreSQL + pgvector 的字段保留与入库分层
• 将该专项文档挂接到 docs/README.md 的“数据与评测”主入口

验证结果：

• 已校验文档内新增相对链接全部可达
• 文档已覆盖：
  • 输入格式
  • 切片时长建议
  • label 设计
  • song_id/version_id 规范
  • pgvector 数据模型与入库流程
• 当前引用的仓库内实现锚点：
  • acr-engine/scripts/export_manifest_to_pgvector_json.py
  • acr-engine/sql/pgvector_schema.sql

结论：

• 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
• 新 session 与后续数据工程实现可直接按该文档落地

Stage: 准确率优化 v2（128 Mel / band-split / retrieval 评测 / dataset 规范 / SOTA 调研）

完成项：

• 补充 dataset / 输入输出规范：docs/dataset-spec.md
• 补充开源数据集接入计划：docs/open-dataset-plan.md
• 补充 2026 SOTA 研究说明：docs/sota-research-2026.md
• 输入特征从低维说话人风格配置改为 128 Mel
• 新增频带分割模块 BandSplitBlock
• 引入 pro-WGAN 风格工程近似平衡策略（针对困难样本的更强增广）
• 合成数据新增 confused / humming_like 样本类型
• 引入 catalog.json 作为可搜索 reference 清单
• 索引从整曲单向量改为 window-level embedding index
• 新增 evaluate.py 做 retrieval 评测
• 训练逻辑改为更 retrieval-oriented 的 song-pair 训练输入

验证结果：

• synthetic_v2 端到端重新跑通
• build-index 成功
• evaluate 成功
• test split 指标：top1=0.65, top5=0.95
• 分类型指标：
  • clean top1=1.00
  • augmented top1=0.75
  • humming_like top1=0.25
  • confused top1=0.25

结论：

• 结构性错误（catalog/index/fusion/评测缺失）已明显改善
• 当前主要剩余短板是 humming_like / confused 的鲁棒识别

2026-06-02

Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：

• 复检归档下载状态，确认 fma_small.zip 已达完整字节数
• 验证本地 FMA 音频目录已可用于真实 smoke
• 直接启动真实 FMA smoke-local，进入训练/索引/评测主链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=7679594875
  • archive_progress_percent=100.0
  • num_audio_files=3025（inspect 阶段）
• 本地解压目录复检：
  • find data/raw/fma_small_audio ... | wc -l 返回 5827
  • check-local-ready / inspect-local 返回：
  • ready_for_smoke=true
  • num_audio_files=8000
  • eligible_query_files=7994
  • recommended_train_queries=6395
  • recommended_test_queries=1599
• 真实 smoke 已启动：
  • /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/raw/fma_small_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2
• 当前训练侧实时证据：
  • Device: cpu
  • Classes: 6381
  • Train songs: 6381
  • Epoch 1 已启动
  • 当前 epoch 总 batch 数：3191

结论：

• 真实 FMA 数据下载门槛已正式打开
• 项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段

Stage: 真实 FMA 下载超过八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 09:28
• 守护日志已增长到至少 19 轮：
  • cycle=18, 83.937%
  • cycle=19, 85.7155%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6724517888
  • archive_progress_percent=87.5634
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=87.5649

结论：

• detached guard 已在九分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 08:25
• 守护日志已增长到至少 17 轮：
  • cycle=16, 81.1776%
  • cycle=17, 82.7758%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6432636928
  • archive_progress_percent=83.7627
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=83.764

结论：

• detached guard 已在八分钟级别继续稳定驻留
• 真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过八成

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 复检后处理门槛是否仍未打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 07:15
• 守护日志已增长到至少 15 轮：
  • cycle=14, 78.2606%
  • cycle=15, 79.6962%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6173982720
  • archive_progress_percent=80.3946
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=80.3946

结论：

• detached guard 已在七分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过四分之三

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 06:12
• 守护日志已增长到至少 13 轮：
  • cycle=12, 75.3734%
  • cycle=13, 76.9423%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5953486848
  • archive_progress_percent=77.5234
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=77.5247

结论：

• detached guard 已在六分钟级别继续稳定驻留
• 真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近四分之三

完成项：

• 再次复检 detached guard 的更长时段存活情况
• 采集新的多轮日志增长证据
• 再次确认后处理门槛是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 05:19
• 守护日志已增长到至少 11 轮：
  • cycle=10, 72.2831%
  • cycle=11, 73.8305%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5748047872
  • archive_progress_percent=74.8483
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=74.8485

结论：

• detached guard 已在五分钟级别继续稳定驻留
• 真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛

Stage: 真实 FMA 下载超过七成

完成项：

• 再次复检 detached guard 长时运行状态
• 采集新一轮日志增长证据
• 复检后处理门槛是否已经打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 04:16
• 守护日志已增长到至少 9 轮：
  • cycle=8, 68.0898%
  • cycle=9, 70.2949%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5479727104
  • archive_progress_percent=71.3544
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=71.3559

结论：

• detached guard 在更长时间窗口内继续稳定工作
• 真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛

Stage: 真实 FMA 下载进度过三分之二

完成项：

• 再次复检 detached guard 的持续运行情况
• 采集新的多轮日志增长证据
• 复检后处理门槛是否已打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 03:19
• 守护日志已增长到至少 7 轮：
  • cycle=6, 63.9577%
  • cycle=7, 65.6775%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5160501248
  • archive_progress_percent=67.1976
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=67.1995

结论：

• detached guard 在更长时段内继续稳定工作
• 真实 FMA 下载已超过三分之二，但后处理门槛仍未打开

Stage: 真实 FMA 守护长时稳定性再验证

完成项：

• 再次复检 detached guard 进程与运行时长
• 检查守护日志是否继续稳定跨轮输出
• 再次复检后处理门槛状态

验证结果：

• 守护进程继续存活：
  • pid=52277
  • PPID=1
  • 运行时长 02:15
• 守护日志已继续增长到至少 5 轮：
  • cycle=4, 60.0672%
  • cycle=5, 62.0764%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4836065280
  • archive_progress_percent=62.9729
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=62.9733

结论：

• detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
• 当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数

Stage: 真实 FMA 守护稳定性续验

完成项：

• 复检新守护进程 pid 与运行时长
• 复检守护日志是否已跨更多轮持续输出
• 再次执行后处理就绪检查，确认是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 01:29
• 守护日志已连续输出至少 3 轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%
  • cycle=3, 58.5098%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4612112384
  • archive_progress_percent=60.0567
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=60.0582

结论：

• 新的守护启动方式已表现出明显更好的长期稳定性
• 当前唯一阻塞继续保持为：FMA 归档尚未完整下载

Stage: 真实 FMA 后台守护方式稳定化

完成项：

• 对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
• 判断二次掉线更可能来自后台脱离方式而非轮询逻辑
• 新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
• 验证新守护方式可跨多轮轮询持续存活

验证结果：

• 前台验证：
  • /usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3 连续输出 3 轮 polling，并正常结束为 status=waiting
• 下载进度继续增长到：
  • 4261445632 -> 4265574400
  • 55.4905% -> 55.5443%
• 新守护脚本启动后：
  • pid=52277
  • PPID=1
  • 进程状态仍存活
• 守护日志已连续输出至少两轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%

结论：

• 之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
• 现在真实 FMA 自动承接链路已有更稳的守护启动入口

Stage: 真实 FMA 长时等待器二次掉线复验

完成项：

• 复检长期等待器与日志输出状态
• 确认下载继续前进，但长期等待器再次退出
• 重新拉起等待器，恢复“下载完成后自动后处理”能力

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4102045696
  • archive_progress_percent=53.4149
• 进程侧未发现 wait_for_fma_and_prepare.py
• 日志文件只保留首轮输出：
  • cycle=1
  • archive_progress_percent=52.5032
• 重新启动后，进程再次恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30

结论：

• 下载本身没有停，问题集中在长期等待器稳定性仍不足
• 下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路

Stage: 真实 FMA 等待器寿命缺陷修复

完成项：

• 诊断 wait_for_fma_and_prepare.py 掉线原因
• 确认原实现默认 max-cycles=3，约 90 秒后自然退出
• 修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
• 重新启动长期等待器并验证日志开始产生轮询输出

验证结果：

• 复检下载进度时已达到：
  • archive_size=3886596096
  • archive_progress_percent=50.6094
• 修复后执行：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2 返回两轮 polling，并确认字节继续增长到：
  • 3977117696 -> 3977314304
  • 51.7881% -> 51.7907%
• 长期等待器已重新启动：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30
• 日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON

结论：

• 之前等待器掉线不是下载异常，而是脚本寿命设计过短
• 现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力

Stage: 真实 FMA 守护链路掉线恢复

完成项：

• 再次复检 FMA 下载进度
• 复检后台等待器是否仍存活
• 发现等待器已退出后，重新拉起自动等待与后处理守护链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3650322432
  • archive_progress_percent=47.5327
• 复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
• 等待器日志文件存在但为空：
  • acr-engine/.omx_wait_for_fma.log
• 重新启动后，进程确认恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 新守护进程 pid：51526

结论：

• 真实 FMA 下载仍在持续推进
• 自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态

Stage: 真实 FMA 自动等待与后处理守护启动

完成项：

• 再次复检 FMA 归档进度
• 检查是否已有后台“等待完成后自动后处理”任务
• 启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3518038016
  • archive_progress_percent=45.8102
• 启动后台等待器后，进程确认存在：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 当前后台等待器 pid：51242
• 等待器日志文件已创建：
  • acr-engine/.omx_wait_for_fma.log

结论：

• 除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
• 后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段

Stage: 真实 FMA 下载活跃性复验

完成项：

• 再次采集 FMA 归档字节进度
• 执行 watchdog 续验并附带进程级活跃性确认

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3403972608
  • archive_progress_percent=44.3249
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3406938112
  • archive_progress_percent=44.3635
  • live_curl=true
  • restarted=null
• 进程侧确认：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行

结论：

• 下载链路仍在持续前进且后台拉取进程健康
• 真实 FMA 下游工作仍等待归档完整这一单一前置条件

Stage: 真实 FMA 后处理门槛复验

完成项：

• 再次复检 FMA 下载进度
• 直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3322314752
  • archive_progress_percent=43.2616
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • archive_size=3323641856
  • progress_percent=43.2789

结论：

• 真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
• 当前阻塞已被脚本化验证，不是人工主观判断

Stage: 真实 FMA 下载续进展验证

完成项：

• 再次执行 FMA 归档 inspect
• 执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3222601728
  • archive_progress_percent=41.9632
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3222896640
  • archive_progress_percent=41.967
  • live_curl=true
  • restarted=null
• 对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节

结论：

• 当前下载未卡死，仍在稳定推进
• 真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛

Stage: 真实 FMA 下载状态续验

完成项：

• 复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 复检后台下载进程与本地归档体积
• 确认当前仍未达到可解压/可真实 smoke 的完成门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_bytes_expected=7679594875
  • archive_size=3117514752
  • archive_progress_percent=40.5948
  • num_audio_files=0
• 后台下载进程仍存活：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 当前本地归档文件：
  • data/raw/fma_small.zip = 3.0G

结论：

• 当前主卡点仍是 FMA 归档未完整下载
• 真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续

Stage: 训练数据与 pgvector 专项说明补强

完成项：

• 重写并补强 docs/training-data-and-pgvector-guide.md
• 单独详细说明：
  • 当前训练输入应由音频资产 + song_id 标签 + manifest 组成
  • reference 与 query 的角色区分
  • BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
  • 面向 PostgreSQL + pgvector 的字段保留与入库分层
• 将该专项文档挂接到 docs/README.md 的“数据与评测”主入口

验证结果：

• 已校验文档内新增相对链接全部可达
• 文档已覆盖：
  • 输入格式
  • 切片时长建议
  • label 设计
  • song_id/version_id 规范
  • pgvector 数据模型与入库流程
• 当前引用的仓库内实现锚点：
  • acr-engine/scripts/export_manifest_to_pgvector_json.py
  • acr-engine/sql/pgvector_schema.sql

结论：

• 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
• 新 session 与后续数据工程实现可直接按该文档落地

Stage: 工业化服务骨架 + 外部 manifest 转换模板

完成项：

• 新增 FastAPI 服务骨架：acr-engine/src/service/app.py
• 新增 manifest 转换工具：acr-engine/src/data/manifest_tools.py
• 新增工业 benchmark 文档：docs/industrial-benchmark-spec.md
• 扩展外部 dataset adapter CLI：acr-engine/src/data/external_adapters.py
• 新增服务 API 文档：docs/service-api.md
• requirements 增加 FastAPI / uvicorn / pydantic

验证结果：

• external_adapters.py registry 成功
• external_adapters.py describe ccmusic 成功
• external_adapters.py init modelscope_music 成功
• manifest_tools.py csv-to-catalog 成功生成 catalog
• service.app health() 返回 {"status":"ok"}
• API build_index(...) 成功返回 reference window 数量
• API recognize(...) 成功返回候选结果
• train.py --dry-run 成功

2026-06-02

Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：

• 复检归档下载状态，确认 fma_small.zip 已达完整字节数
• 验证本地 FMA 音频目录已可用于真实 smoke
• 直接启动真实 FMA smoke-local，进入训练/索引/评测主链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=7679594875
  • archive_progress_percent=100.0
  • num_audio_files=3025（inspect 阶段）
• 本地解压目录复检：
  • find data/raw/fma_small_audio ... | wc -l 返回 5827
  • check-local-ready / inspect-local 返回：
  • ready_for_smoke=true
  • num_audio_files=8000
  • eligible_query_files=7994
  • recommended_train_queries=6395
  • recommended_test_queries=1599
• 真实 smoke 已启动：
  • /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/raw/fma_small_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2
• 当前训练侧实时证据：
  • Device: cpu
  • Classes: 6381
  • Train songs: 6381
  • Epoch 1 已启动
  • 当前 epoch 总 batch 数：3191

结论：

• 真实 FMA 数据下载门槛已正式打开
• 项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段

Stage: 真实 FMA 下载超过八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 09:28
• 守护日志已增长到至少 19 轮：
  • cycle=18, 83.937%
  • cycle=19, 85.7155%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6724517888
  • archive_progress_percent=87.5634
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=87.5649

结论：

• detached guard 已在九分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 08:25
• 守护日志已增长到至少 17 轮：
  • cycle=16, 81.1776%
  • cycle=17, 82.7758%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6432636928
  • archive_progress_percent=83.7627
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=83.764

结论：

• detached guard 已在八分钟级别继续稳定驻留
• 真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过八成

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 复检后处理门槛是否仍未打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 07:15
• 守护日志已增长到至少 15 轮：
  • cycle=14, 78.2606%
  • cycle=15, 79.6962%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6173982720
  • archive_progress_percent=80.3946
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=80.3946

结论：

• detached guard 已在七分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过四分之三

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 06:12
• 守护日志已增长到至少 13 轮：
  • cycle=12, 75.3734%
  • cycle=13, 76.9423%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5953486848
  • archive_progress_percent=77.5234
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=77.5247

结论：

• detached guard 已在六分钟级别继续稳定驻留
• 真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近四分之三

完成项：

• 再次复检 detached guard 的更长时段存活情况
• 采集新的多轮日志增长证据
• 再次确认后处理门槛是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 05:19
• 守护日志已增长到至少 11 轮：
  • cycle=10, 72.2831%
  • cycle=11, 73.8305%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5748047872
  • archive_progress_percent=74.8483
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=74.8485

结论：

• detached guard 已在五分钟级别继续稳定驻留
• 真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛

Stage: 真实 FMA 下载超过七成

完成项：

• 再次复检 detached guard 长时运行状态
• 采集新一轮日志增长证据
• 复检后处理门槛是否已经打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 04:16
• 守护日志已增长到至少 9 轮：
  • cycle=8, 68.0898%
  • cycle=9, 70.2949%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5479727104
  • archive_progress_percent=71.3544
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=71.3559

结论：

• detached guard 在更长时间窗口内继续稳定工作
• 真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛

Stage: 真实 FMA 下载进度过三分之二

完成项：

• 再次复检 detached guard 的持续运行情况
• 采集新的多轮日志增长证据
• 复检后处理门槛是否已打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 03:19
• 守护日志已增长到至少 7 轮：
  • cycle=6, 63.9577%
  • cycle=7, 65.6775%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5160501248
  • archive_progress_percent=67.1976
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=67.1995

结论：

• detached guard 在更长时段内继续稳定工作
• 真实 FMA 下载已超过三分之二，但后处理门槛仍未打开

Stage: 真实 FMA 守护长时稳定性再验证

完成项：

• 再次复检 detached guard 进程与运行时长
• 检查守护日志是否继续稳定跨轮输出
• 再次复检后处理门槛状态

验证结果：

• 守护进程继续存活：
  • pid=52277
  • PPID=1
  • 运行时长 02:15
• 守护日志已继续增长到至少 5 轮：
  • cycle=4, 60.0672%
  • cycle=5, 62.0764%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4836065280
  • archive_progress_percent=62.9729
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=62.9733

结论：

• detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
• 当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数

Stage: 真实 FMA 守护稳定性续验

完成项：

• 复检新守护进程 pid 与运行时长
• 复检守护日志是否已跨更多轮持续输出
• 再次执行后处理就绪检查，确认是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 01:29
• 守护日志已连续输出至少 3 轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%
  • cycle=3, 58.5098%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4612112384
  • archive_progress_percent=60.0567
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=60.0582

结论：

• 新的守护启动方式已表现出明显更好的长期稳定性
• 当前唯一阻塞继续保持为：FMA 归档尚未完整下载

Stage: 真实 FMA 后台守护方式稳定化

完成项：

• 对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
• 判断二次掉线更可能来自后台脱离方式而非轮询逻辑
• 新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
• 验证新守护方式可跨多轮轮询持续存活

验证结果：

• 前台验证：
  • /usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3 连续输出 3 轮 polling，并正常结束为 status=waiting
• 下载进度继续增长到：
  • 4261445632 -> 4265574400
  • 55.4905% -> 55.5443%
• 新守护脚本启动后：
  • pid=52277
  • PPID=1
  • 进程状态仍存活
• 守护日志已连续输出至少两轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%

结论：

• 之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
• 现在真实 FMA 自动承接链路已有更稳的守护启动入口

Stage: 真实 FMA 长时等待器二次掉线复验

完成项：

• 复检长期等待器与日志输出状态
• 确认下载继续前进，但长期等待器再次退出
• 重新拉起等待器，恢复“下载完成后自动后处理”能力

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4102045696
  • archive_progress_percent=53.4149
• 进程侧未发现 wait_for_fma_and_prepare.py
• 日志文件只保留首轮输出：
  • cycle=1
  • archive_progress_percent=52.5032
• 重新启动后，进程再次恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30

结论：

• 下载本身没有停，问题集中在长期等待器稳定性仍不足
• 下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路

Stage: 真实 FMA 等待器寿命缺陷修复

完成项：

• 诊断 wait_for_fma_and_prepare.py 掉线原因
• 确认原实现默认 max-cycles=3，约 90 秒后自然退出
• 修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
• 重新启动长期等待器并验证日志开始产生轮询输出

验证结果：

• 复检下载进度时已达到：
  • archive_size=3886596096
  • archive_progress_percent=50.6094
• 修复后执行：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2 返回两轮 polling，并确认字节继续增长到：
  • 3977117696 -> 3977314304
  • 51.7881% -> 51.7907%
• 长期等待器已重新启动：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30
• 日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON

结论：

• 之前等待器掉线不是下载异常，而是脚本寿命设计过短
• 现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力

Stage: 真实 FMA 守护链路掉线恢复

完成项：

• 再次复检 FMA 下载进度
• 复检后台等待器是否仍存活
• 发现等待器已退出后，重新拉起自动等待与后处理守护链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3650322432
  • archive_progress_percent=47.5327
• 复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
• 等待器日志文件存在但为空：
  • acr-engine/.omx_wait_for_fma.log
• 重新启动后，进程确认恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 新守护进程 pid：51526

结论：

• 真实 FMA 下载仍在持续推进
• 自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态

Stage: 真实 FMA 自动等待与后处理守护启动

完成项：

• 再次复检 FMA 归档进度
• 检查是否已有后台“等待完成后自动后处理”任务
• 启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3518038016
  • archive_progress_percent=45.8102
• 启动后台等待器后，进程确认存在：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 当前后台等待器 pid：51242
• 等待器日志文件已创建：
  • acr-engine/.omx_wait_for_fma.log

结论：

• 除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
• 后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段

Stage: 真实 FMA 下载活跃性复验

完成项：

• 再次采集 FMA 归档字节进度
• 执行 watchdog 续验并附带进程级活跃性确认

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3403972608
  • archive_progress_percent=44.3249
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3406938112
  • archive_progress_percent=44.3635
  • live_curl=true
  • restarted=null
• 进程侧确认：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行

结论：

• 下载链路仍在持续前进且后台拉取进程健康
• 真实 FMA 下游工作仍等待归档完整这一单一前置条件

Stage: 真实 FMA 后处理门槛复验

完成项：

• 再次复检 FMA 下载进度
• 直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3322314752
  • archive_progress_percent=43.2616
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • archive_size=3323641856
  • progress_percent=43.2789

结论：

• 真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
• 当前阻塞已被脚本化验证，不是人工主观判断

Stage: 真实 FMA 下载续进展验证

完成项：

• 再次执行 FMA 归档 inspect
• 执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3222601728
  • archive_progress_percent=41.9632
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3222896640
  • archive_progress_percent=41.967
  • live_curl=true
  • restarted=null
• 对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节

结论：

• 当前下载未卡死，仍在稳定推进
• 真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛

Stage: 真实 FMA 下载状态续验

完成项：

• 复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 复检后台下载进程与本地归档体积
• 确认当前仍未达到可解压/可真实 smoke 的完成门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_bytes_expected=7679594875
  • archive_size=3117514752
  • archive_progress_percent=40.5948
  • num_audio_files=0
• 后台下载进程仍存活：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 当前本地归档文件：
  • data/raw/fma_small.zip = 3.0G

结论：

• 当前主卡点仍是 FMA 归档未完整下载
• 真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续

Stage: 训练数据与 pgvector 专项说明补强

完成项：

• 重写并补强 docs/training-data-and-pgvector-guide.md
• 单独详细说明：
  • 当前训练输入应由音频资产 + song_id 标签 + manifest 组成
  • reference 与 query 的角色区分
  • BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
  • 面向 PostgreSQL + pgvector 的字段保留与入库分层
• 将该专项文档挂接到 docs/README.md 的“数据与评测”主入口

验证结果：

• 已校验文档内新增相对链接全部可达
• 文档已覆盖：
  • 输入格式
  • 切片时长建议
  • label 设计
  • song_id/version_id 规范
  • pgvector 数据模型与入库流程
• 当前引用的仓库内实现锚点：
  • acr-engine/scripts/export_manifest_to_pgvector_json.py
  • acr-engine/sql/pgvector_schema.sql

结论：

• 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
• 新 session 与后续数据工程实现可直接按该文档落地

Stage: 文档治理闭环（导航 / 引用 / 模板）

完成项：

• 新增 docs/README.md 作为文档总入口
• 新增 docs/references-and-sources.md 作为引用来源总图
• 新增 docs/benchmark-report-template.md
• 新增 docs/model-card-template.md
• 新增 docs/release-checklist.md
• 核心文档统一补充 Sources 小节
• 核心文档统一补齐 executive summary / mermaid / table / appendix 风格

验证结果：

• docs 总入口结构检查通过
• references map 结构检查通过
• 核心 docs 存在性检查通过
• benchmark/model/release 模板结构检查通过
• 所有核心文档均具备 Sources；SOTA 文档已补齐 Mermaid 图

2026-06-02

Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：

• 复检归档下载状态，确认 fma_small.zip 已达完整字节数
• 验证本地 FMA 音频目录已可用于真实 smoke
• 直接启动真实 FMA smoke-local，进入训练/索引/评测主链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=7679594875
  • archive_progress_percent=100.0
  • num_audio_files=3025（inspect 阶段）
• 本地解压目录复检：
  • find data/raw/fma_small_audio ... | wc -l 返回 5827
  • check-local-ready / inspect-local 返回：
  • ready_for_smoke=true
  • num_audio_files=8000
  • eligible_query_files=7994
  • recommended_train_queries=6395
  • recommended_test_queries=1599
• 真实 smoke 已启动：
  • /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/raw/fma_small_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2
• 当前训练侧实时证据：
  • Device: cpu
  • Classes: 6381
  • Train songs: 6381
  • Epoch 1 已启动
  • 当前 epoch 总 batch 数：3191

结论：

• 真实 FMA 数据下载门槛已正式打开
• 项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段

Stage: 真实 FMA 下载超过八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 09:28
• 守护日志已增长到至少 19 轮：
  • cycle=18, 83.937%
  • cycle=19, 85.7155%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6724517888
  • archive_progress_percent=87.5634
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=87.5649

结论：

• detached guard 已在九分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 08:25
• 守护日志已增长到至少 17 轮：
  • cycle=16, 81.1776%
  • cycle=17, 82.7758%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6432636928
  • archive_progress_percent=83.7627
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=83.764

结论：

• detached guard 已在八分钟级别继续稳定驻留
• 真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过八成

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 复检后处理门槛是否仍未打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 07:15
• 守护日志已增长到至少 15 轮：
  • cycle=14, 78.2606%
  • cycle=15, 79.6962%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6173982720
  • archive_progress_percent=80.3946
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=80.3946

结论：

• detached guard 已在七分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过四分之三

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 06:12
• 守护日志已增长到至少 13 轮：
  • cycle=12, 75.3734%
  • cycle=13, 76.9423%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5953486848
  • archive_progress_percent=77.5234
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=77.5247

结论：

• detached guard 已在六分钟级别继续稳定驻留
• 真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近四分之三

完成项：

• 再次复检 detached guard 的更长时段存活情况
• 采集新的多轮日志增长证据
• 再次确认后处理门槛是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 05:19
• 守护日志已增长到至少 11 轮：
  • cycle=10, 72.2831%
  • cycle=11, 73.8305%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5748047872
  • archive_progress_percent=74.8483
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=74.8485

结论：

• detached guard 已在五分钟级别继续稳定驻留
• 真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛

Stage: 真实 FMA 下载超过七成

完成项：

• 再次复检 detached guard 长时运行状态
• 采集新一轮日志增长证据
• 复检后处理门槛是否已经打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 04:16
• 守护日志已增长到至少 9 轮：
  • cycle=8, 68.0898%
  • cycle=9, 70.2949%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5479727104
  • archive_progress_percent=71.3544
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=71.3559

结论：

• detached guard 在更长时间窗口内继续稳定工作
• 真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛

Stage: 真实 FMA 下载进度过三分之二

完成项：

• 再次复检 detached guard 的持续运行情况
• 采集新的多轮日志增长证据
• 复检后处理门槛是否已打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 03:19
• 守护日志已增长到至少 7 轮：
  • cycle=6, 63.9577%
  • cycle=7, 65.6775%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5160501248
  • archive_progress_percent=67.1976
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=67.1995

结论：

• detached guard 在更长时段内继续稳定工作
• 真实 FMA 下载已超过三分之二，但后处理门槛仍未打开

Stage: 真实 FMA 守护长时稳定性再验证

完成项：

• 再次复检 detached guard 进程与运行时长
• 检查守护日志是否继续稳定跨轮输出
• 再次复检后处理门槛状态

验证结果：

• 守护进程继续存活：
  • pid=52277
  • PPID=1
  • 运行时长 02:15
• 守护日志已继续增长到至少 5 轮：
  • cycle=4, 60.0672%
  • cycle=5, 62.0764%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4836065280
  • archive_progress_percent=62.9729
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=62.9733

结论：

• detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
• 当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数

Stage: 真实 FMA 守护稳定性续验

完成项：

• 复检新守护进程 pid 与运行时长
• 复检守护日志是否已跨更多轮持续输出
• 再次执行后处理就绪检查，确认是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 01:29
• 守护日志已连续输出至少 3 轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%
  • cycle=3, 58.5098%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4612112384
  • archive_progress_percent=60.0567
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=60.0582

结论：

• 新的守护启动方式已表现出明显更好的长期稳定性
• 当前唯一阻塞继续保持为：FMA 归档尚未完整下载

Stage: 真实 FMA 后台守护方式稳定化

完成项：

• 对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
• 判断二次掉线更可能来自后台脱离方式而非轮询逻辑
• 新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
• 验证新守护方式可跨多轮轮询持续存活

验证结果：

• 前台验证：
  • /usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3 连续输出 3 轮 polling，并正常结束为 status=waiting
• 下载进度继续增长到：
  • 4261445632 -> 4265574400
  • 55.4905% -> 55.5443%
• 新守护脚本启动后：
  • pid=52277
  • PPID=1
  • 进程状态仍存活
• 守护日志已连续输出至少两轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%

结论：

• 之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
• 现在真实 FMA 自动承接链路已有更稳的守护启动入口

Stage: 真实 FMA 长时等待器二次掉线复验

完成项：

• 复检长期等待器与日志输出状态
• 确认下载继续前进，但长期等待器再次退出
• 重新拉起等待器，恢复“下载完成后自动后处理”能力

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4102045696
  • archive_progress_percent=53.4149
• 进程侧未发现 wait_for_fma_and_prepare.py
• 日志文件只保留首轮输出：
  • cycle=1
  • archive_progress_percent=52.5032
• 重新启动后，进程再次恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30

结论：

• 下载本身没有停，问题集中在长期等待器稳定性仍不足
• 下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路

Stage: 真实 FMA 等待器寿命缺陷修复

完成项：

• 诊断 wait_for_fma_and_prepare.py 掉线原因
• 确认原实现默认 max-cycles=3，约 90 秒后自然退出
• 修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
• 重新启动长期等待器并验证日志开始产生轮询输出

验证结果：

• 复检下载进度时已达到：
  • archive_size=3886596096
  • archive_progress_percent=50.6094
• 修复后执行：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2 返回两轮 polling，并确认字节继续增长到：
  • 3977117696 -> 3977314304
  • 51.7881% -> 51.7907%
• 长期等待器已重新启动：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30
• 日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON

结论：

• 之前等待器掉线不是下载异常，而是脚本寿命设计过短
• 现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力

Stage: 真实 FMA 守护链路掉线恢复

完成项：

• 再次复检 FMA 下载进度
• 复检后台等待器是否仍存活
• 发现等待器已退出后，重新拉起自动等待与后处理守护链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3650322432
  • archive_progress_percent=47.5327
• 复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
• 等待器日志文件存在但为空：
  • acr-engine/.omx_wait_for_fma.log
• 重新启动后，进程确认恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 新守护进程 pid：51526

结论：

• 真实 FMA 下载仍在持续推进
• 自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态

Stage: 真实 FMA 自动等待与后处理守护启动

完成项：

• 再次复检 FMA 归档进度
• 检查是否已有后台“等待完成后自动后处理”任务
• 启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3518038016
  • archive_progress_percent=45.8102
• 启动后台等待器后，进程确认存在：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 当前后台等待器 pid：51242
• 等待器日志文件已创建：
  • acr-engine/.omx_wait_for_fma.log

结论：

• 除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
• 后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段

Stage: 真实 FMA 下载活跃性复验

完成项：

• 再次采集 FMA 归档字节进度
• 执行 watchdog 续验并附带进程级活跃性确认

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3403972608
  • archive_progress_percent=44.3249
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3406938112
  • archive_progress_percent=44.3635
  • live_curl=true
  • restarted=null
• 进程侧确认：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行

结论：

• 下载链路仍在持续前进且后台拉取进程健康
• 真实 FMA 下游工作仍等待归档完整这一单一前置条件

Stage: 真实 FMA 后处理门槛复验

完成项：

• 再次复检 FMA 下载进度
• 直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3322314752
  • archive_progress_percent=43.2616
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • archive_size=3323641856
  • progress_percent=43.2789

结论：

• 真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
• 当前阻塞已被脚本化验证，不是人工主观判断

Stage: 真实 FMA 下载续进展验证

完成项：

• 再次执行 FMA 归档 inspect
• 执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3222601728
  • archive_progress_percent=41.9632
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3222896640
  • archive_progress_percent=41.967
  • live_curl=true
  • restarted=null
• 对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节

结论：

• 当前下载未卡死，仍在稳定推进
• 真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛

Stage: 真实 FMA 下载状态续验

完成项：

• 复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 复检后台下载进程与本地归档体积
• 确认当前仍未达到可解压/可真实 smoke 的完成门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_bytes_expected=7679594875
  • archive_size=3117514752
  • archive_progress_percent=40.5948
  • num_audio_files=0
• 后台下载进程仍存活：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 当前本地归档文件：
  • data/raw/fma_small.zip = 3.0G

结论：

• 当前主卡点仍是 FMA 归档未完整下载
• 真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续

Stage: 训练数据与 pgvector 专项说明补强

完成项：

• 重写并补强 docs/training-data-and-pgvector-guide.md
• 单独详细说明：
  • 当前训练输入应由音频资产 + song_id 标签 + manifest 组成
  • reference 与 query 的角色区分
  • BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
  • 面向 PostgreSQL + pgvector 的字段保留与入库分层
• 将该专项文档挂接到 docs/README.md 的“数据与评测”主入口

验证结果：

• 已校验文档内新增相对链接全部可达
• 文档已覆盖：
  • 输入格式
  • 切片时长建议
  • label 设计
  • song_id/version_id 规范
  • pgvector 数据模型与入库流程
• 当前引用的仓库内实现锚点：
  • acr-engine/scripts/export_manifest_to_pgvector_json.py
  • acr-engine/sql/pgvector_schema.sql

结论：

• 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
• 新 session 与后续数据工程实现可直接按该文档落地

Stage: 真实评测到发布产物链路打通

完成项：

• evaluate.py 支持 --output-json
• 新增 docs/report-layout.md
• 新增 scripts/generate_artifacts.py
• 打通 eval.json -> benchmark-report.md / model-card.md / release-checklist.md / artifact-manifest.json
• 为快速发布链路新增 --fast-eval（关闭 melody 重排以加快报告生成）

验证结果：

• synthetic_v2 重建、训练、建索引成功
• evaluate.py --fast-eval --output-json ... 成功输出 JSON
• artifact generator 成功输出 4 类发布产物
• reports/smoke-v2/synthetic_v2/ 目录产物存在性检查通过
• 当前 fast-eval 指标：top1=0.60, top5=0.75，hard-case 仍需继续优化

2026-06-02

Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：

• 复检归档下载状态，确认 fma_small.zip 已达完整字节数
• 验证本地 FMA 音频目录已可用于真实 smoke
• 直接启动真实 FMA smoke-local，进入训练/索引/评测主链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=7679594875
  • archive_progress_percent=100.0
  • num_audio_files=3025（inspect 阶段）
• 本地解压目录复检：
  • find data/raw/fma_small_audio ... | wc -l 返回 5827
  • check-local-ready / inspect-local 返回：
  • ready_for_smoke=true
  • num_audio_files=8000
  • eligible_query_files=7994
  • recommended_train_queries=6395
  • recommended_test_queries=1599
• 真实 smoke 已启动：
  • /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/raw/fma_small_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2
• 当前训练侧实时证据：
  • Device: cpu
  • Classes: 6381
  • Train songs: 6381
  • Epoch 1 已启动
  • 当前 epoch 总 batch 数：3191

结论：

• 真实 FMA 数据下载门槛已正式打开
• 项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段

Stage: 真实 FMA 下载超过八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 09:28
• 守护日志已增长到至少 19 轮：
  • cycle=18, 83.937%
  • cycle=19, 85.7155%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6724517888
  • archive_progress_percent=87.5634
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=87.5649

结论：

• detached guard 已在九分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 08:25
• 守护日志已增长到至少 17 轮：
  • cycle=16, 81.1776%
  • cycle=17, 82.7758%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6432636928
  • archive_progress_percent=83.7627
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=83.764

结论：

• detached guard 已在八分钟级别继续稳定驻留
• 真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过八成

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 复检后处理门槛是否仍未打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 07:15
• 守护日志已增长到至少 15 轮：
  • cycle=14, 78.2606%
  • cycle=15, 79.6962%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6173982720
  • archive_progress_percent=80.3946
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=80.3946

结论：

• detached guard 已在七分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过四分之三

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 06:12
• 守护日志已增长到至少 13 轮：
  • cycle=12, 75.3734%
  • cycle=13, 76.9423%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5953486848
  • archive_progress_percent=77.5234
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=77.5247

结论：

• detached guard 已在六分钟级别继续稳定驻留
• 真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近四分之三

完成项：

• 再次复检 detached guard 的更长时段存活情况
• 采集新的多轮日志增长证据
• 再次确认后处理门槛是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 05:19
• 守护日志已增长到至少 11 轮：
  • cycle=10, 72.2831%
  • cycle=11, 73.8305%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5748047872
  • archive_progress_percent=74.8483
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=74.8485

结论：

• detached guard 已在五分钟级别继续稳定驻留
• 真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛

Stage: 真实 FMA 下载超过七成

完成项：

• 再次复检 detached guard 长时运行状态
• 采集新一轮日志增长证据
• 复检后处理门槛是否已经打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 04:16
• 守护日志已增长到至少 9 轮：
  • cycle=8, 68.0898%
  • cycle=9, 70.2949%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5479727104
  • archive_progress_percent=71.3544
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=71.3559

结论：

• detached guard 在更长时间窗口内继续稳定工作
• 真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛

Stage: 真实 FMA 下载进度过三分之二

完成项：

• 再次复检 detached guard 的持续运行情况
• 采集新的多轮日志增长证据
• 复检后处理门槛是否已打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 03:19
• 守护日志已增长到至少 7 轮：
  • cycle=6, 63.9577%
  • cycle=7, 65.6775%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5160501248
  • archive_progress_percent=67.1976
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=67.1995

结论：

• detached guard 在更长时段内继续稳定工作
• 真实 FMA 下载已超过三分之二，但后处理门槛仍未打开

Stage: 真实 FMA 守护长时稳定性再验证

完成项：

• 再次复检 detached guard 进程与运行时长
• 检查守护日志是否继续稳定跨轮输出
• 再次复检后处理门槛状态

验证结果：

• 守护进程继续存活：
  • pid=52277
  • PPID=1
  • 运行时长 02:15
• 守护日志已继续增长到至少 5 轮：
  • cycle=4, 60.0672%
  • cycle=5, 62.0764%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4836065280
  • archive_progress_percent=62.9729
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=62.9733

结论：

• detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
• 当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数

Stage: 真实 FMA 守护稳定性续验

完成项：

• 复检新守护进程 pid 与运行时长
• 复检守护日志是否已跨更多轮持续输出
• 再次执行后处理就绪检查，确认是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 01:29
• 守护日志已连续输出至少 3 轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%
  • cycle=3, 58.5098%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4612112384
  • archive_progress_percent=60.0567
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=60.0582

结论：

• 新的守护启动方式已表现出明显更好的长期稳定性
• 当前唯一阻塞继续保持为：FMA 归档尚未完整下载

Stage: 真实 FMA 后台守护方式稳定化

完成项：

• 对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
• 判断二次掉线更可能来自后台脱离方式而非轮询逻辑
• 新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
• 验证新守护方式可跨多轮轮询持续存活

验证结果：

• 前台验证：
  • /usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3 连续输出 3 轮 polling，并正常结束为 status=waiting
• 下载进度继续增长到：
  • 4261445632 -> 4265574400
  • 55.4905% -> 55.5443%
• 新守护脚本启动后：
  • pid=52277
  • PPID=1
  • 进程状态仍存活
• 守护日志已连续输出至少两轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%

结论：

• 之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
• 现在真实 FMA 自动承接链路已有更稳的守护启动入口

Stage: 真实 FMA 长时等待器二次掉线复验

完成项：

• 复检长期等待器与日志输出状态
• 确认下载继续前进，但长期等待器再次退出
• 重新拉起等待器，恢复“下载完成后自动后处理”能力

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4102045696
  • archive_progress_percent=53.4149
• 进程侧未发现 wait_for_fma_and_prepare.py
• 日志文件只保留首轮输出：
  • cycle=1
  • archive_progress_percent=52.5032
• 重新启动后，进程再次恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30

结论：

• 下载本身没有停，问题集中在长期等待器稳定性仍不足
• 下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路

Stage: 真实 FMA 等待器寿命缺陷修复

完成项：

• 诊断 wait_for_fma_and_prepare.py 掉线原因
• 确认原实现默认 max-cycles=3，约 90 秒后自然退出
• 修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
• 重新启动长期等待器并验证日志开始产生轮询输出

验证结果：

• 复检下载进度时已达到：
  • archive_size=3886596096
  • archive_progress_percent=50.6094
• 修复后执行：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2 返回两轮 polling，并确认字节继续增长到：
  • 3977117696 -> 3977314304
  • 51.7881% -> 51.7907%
• 长期等待器已重新启动：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30
• 日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON

结论：

• 之前等待器掉线不是下载异常，而是脚本寿命设计过短
• 现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力

Stage: 真实 FMA 守护链路掉线恢复

完成项：

• 再次复检 FMA 下载进度
• 复检后台等待器是否仍存活
• 发现等待器已退出后，重新拉起自动等待与后处理守护链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3650322432
  • archive_progress_percent=47.5327
• 复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
• 等待器日志文件存在但为空：
  • acr-engine/.omx_wait_for_fma.log
• 重新启动后，进程确认恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 新守护进程 pid：51526

结论：

• 真实 FMA 下载仍在持续推进
• 自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态

Stage: 真实 FMA 自动等待与后处理守护启动

完成项：

• 再次复检 FMA 归档进度
• 检查是否已有后台“等待完成后自动后处理”任务
• 启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3518038016
  • archive_progress_percent=45.8102
• 启动后台等待器后，进程确认存在：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 当前后台等待器 pid：51242
• 等待器日志文件已创建：
  • acr-engine/.omx_wait_for_fma.log

结论：

• 除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
• 后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段

Stage: 真实 FMA 下载活跃性复验

完成项：

• 再次采集 FMA 归档字节进度
• 执行 watchdog 续验并附带进程级活跃性确认

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3403972608
  • archive_progress_percent=44.3249
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3406938112
  • archive_progress_percent=44.3635
  • live_curl=true
  • restarted=null
• 进程侧确认：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行

结论：

• 下载链路仍在持续前进且后台拉取进程健康
• 真实 FMA 下游工作仍等待归档完整这一单一前置条件

Stage: 真实 FMA 后处理门槛复验

完成项：

• 再次复检 FMA 下载进度
• 直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3322314752
  • archive_progress_percent=43.2616
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • archive_size=3323641856
  • progress_percent=43.2789

结论：

• 真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
• 当前阻塞已被脚本化验证，不是人工主观判断

Stage: 真实 FMA 下载续进展验证

完成项：

• 再次执行 FMA 归档 inspect
• 执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3222601728
  • archive_progress_percent=41.9632
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3222896640
  • archive_progress_percent=41.967
  • live_curl=true
  • restarted=null
• 对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节

结论：

• 当前下载未卡死，仍在稳定推进
• 真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛

Stage: 真实 FMA 下载状态续验

完成项：

• 复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 复检后台下载进程与本地归档体积
• 确认当前仍未达到可解压/可真实 smoke 的完成门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_bytes_expected=7679594875
  • archive_size=3117514752
  • archive_progress_percent=40.5948
  • num_audio_files=0
• 后台下载进程仍存活：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 当前本地归档文件：
  • data/raw/fma_small.zip = 3.0G

结论：

• 当前主卡点仍是 FMA 归档未完整下载
• 真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续

Stage: 训练数据与 pgvector 专项说明补强

完成项：

• 重写并补强 docs/training-data-and-pgvector-guide.md
• 单独详细说明：
  • 当前训练输入应由音频资产 + song_id 标签 + manifest 组成
  • reference 与 query 的角色区分
  • BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
  • 面向 PostgreSQL + pgvector 的字段保留与入库分层
• 将该专项文档挂接到 docs/README.md 的“数据与评测”主入口

验证结果：

• 已校验文档内新增相对链接全部可达
• 文档已覆盖：
  • 输入格式
  • 切片时长建议
  • label 设计
  • song_id/version_id 规范
  • pgvector 数据模型与入库流程
• 当前引用的仓库内实现锚点：
  • acr-engine/scripts/export_manifest_to_pgvector_json.py
  • acr-engine/sql/pgvector_schema.sql

结论：

• 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
• 新 session 与后续数据工程实现可直接按该文档落地

Stage: 外部数据集 bootstrap + hard-case 过采样试验

完成项：

• 新增 src/data/bootstrap_external.py
• 可自动为 fma / ccmusic 生成 bootstrap catalog manifest
• 在 SongPairDataset 中加入困难样本过采样试验（confused / humming_like）
• 重新训练 models_v4、重建 index_v4、重跑 smoke-v4 评测

验证结果：

• data/external_bootstrap/fma/manifests/catalog.bootstrap.json 成功生成
• data/external_bootstrap/ccmusic/manifests/catalog.bootstrap.json 成功生成
• reports/smoke-v4/synthetic_v2/eval.json 成功生成
• 当前试验结果：top1=0.40, top5=0.80
• hard-case 结果未改善：
  • humming_like top1=0.00
  • confused top1=0.00

结论：

• 该轮简单过采样策略无效，且整体精度下降
• 下一轮应改用更细粒度 hard-negative / melody-aware 正则，而不是继续放大样本重复权重

2026-06-02

Stage: 真实 FMA 本地数据门槛打开并进入 smoke 训练

完成项：

• 复检归档下载状态，确认 fma_small.zip 已达完整字节数
• 验证本地 FMA 音频目录已可用于真实 smoke
• 直接启动真实 FMA smoke-local，进入训练/索引/评测主链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=7679594875
  • archive_progress_percent=100.0
  • num_audio_files=3025（inspect 阶段）
• 本地解压目录复检：
  • find data/raw/fma_small_audio ... | wc -l 返回 5827
  • check-local-ready / inspect-local 返回：
  • ready_for_smoke=true
  • num_audio_files=8000
  • eligible_query_files=7994
  • recommended_train_queries=6395
  • recommended_test_queries=1599
• 真实 smoke 已启动：
  • /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/raw/fma_small_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2
• 当前训练侧实时证据：
  • Device: cpu
  • Classes: 6381
  • Train songs: 6381
  • Epoch 1 已启动
  • 当前 epoch 总 batch 数：3191

结论：

• 真实 FMA 数据下载门槛已正式打开
• 项目已从“等待真实数据”切换到“真实数据 smoke 正在执行”的阶段

Stage: 真实 FMA 下载超过八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 09:28
• 守护日志已增长到至少 19 轮：
  • cycle=18, 83.937%
  • cycle=19, 85.7155%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6724517888
  • archive_progress_percent=87.5634
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=87.5649

结论：

• detached guard 已在九分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近八成半

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 08:25
• 守护日志已增长到至少 17 轮：
  • cycle=16, 81.1776%
  • cycle=17, 82.7758%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6432636928
  • archive_progress_percent=83.7627
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=83.764

结论：

• detached guard 已在八分钟级别继续稳定驻留
• 真实 FMA 下载已逼近八成半，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过八成

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 复检后处理门槛是否仍未打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 07:15
• 守护日志已增长到至少 15 轮：
  • cycle=14, 78.2606%
  • cycle=15, 79.6962%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=6173982720
  • archive_progress_percent=80.3946
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=80.3946

结论：

• detached guard 已在七分钟级别继续稳定驻留
• 真实 FMA 下载已超过八成，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载超过四分之三

完成项：

• 再次复检 detached guard 的更长时段稳定性
• 采集新的多轮日志增长证据
• 再次验证后处理门槛仍由未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 06:12
• 守护日志已增长到至少 13 轮：
  • cycle=12, 75.3734%
  • cycle=13, 76.9423%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5953486848
  • archive_progress_percent=77.5234
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=77.5247

结论：

• detached guard 已在六分钟级别继续稳定驻留
• 真实 FMA 下载已超过四分之三，当前唯一阻塞仍是归档尚未完整下载

Stage: 真实 FMA 下载逼近四分之三

完成项：

• 再次复检 detached guard 的更长时段存活情况
• 采集新的多轮日志增长证据
• 再次确认后处理门槛是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 05:19
• 守护日志已增长到至少 11 轮：
  • cycle=10, 72.2831%
  • cycle=11, 73.8305%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5748047872
  • archive_progress_percent=74.8483
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=74.8485

结论：

• detached guard 已在五分钟级别继续稳定驻留
• 真实 FMA 下载已逼近四分之三，但仍未跨过可后处理的完整归档门槛

Stage: 真实 FMA 下载超过七成

完成项：

• 再次复检 detached guard 长时运行状态
• 采集新一轮日志增长证据
• 复检后处理门槛是否已经打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 04:16
• 守护日志已增长到至少 9 轮：
  • cycle=8, 68.0898%
  • cycle=9, 70.2949%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5479727104
  • archive_progress_percent=71.3544
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=71.3559

结论：

• detached guard 在更长时间窗口内继续稳定工作
• 真实 FMA 下载已超过 70%，但仍未达到可后处理的完整归档门槛

Stage: 真实 FMA 下载进度过三分之二

完成项：

• 再次复检 detached guard 的持续运行情况
• 采集新的多轮日志增长证据
• 复检后处理门槛是否已打开

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 03:19
• 守护日志已增长到至少 7 轮：
  • cycle=6, 63.9577%
  • cycle=7, 65.6775%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=5160501248
  • archive_progress_percent=67.1976
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=67.1995

结论：

• detached guard 在更长时段内继续稳定工作
• 真实 FMA 下载已超过三分之二，但后处理门槛仍未打开

Stage: 真实 FMA 守护长时稳定性再验证

完成项：

• 再次复检 detached guard 进程与运行时长
• 检查守护日志是否继续稳定跨轮输出
• 再次复检后处理门槛状态

验证结果：

• 守护进程继续存活：
  • pid=52277
  • PPID=1
  • 运行时长 02:15
• 守护日志已继续增长到至少 5 轮：
  • cycle=4, 60.0672%
  • cycle=5, 62.0764%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4836065280
  • archive_progress_percent=62.9729
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=62.9733

结论：

• detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
• 当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数

Stage: 真实 FMA 守护稳定性续验

完成项：

• 复检新守护进程 pid 与运行时长
• 复检守护日志是否已跨更多轮持续输出
• 再次执行后处理就绪检查，确认是否仍被未完成归档阻塞

验证结果：

• 守护进程持续存活：
  • pid=52277
  • PPID=1
  • 运行时长 01:29
• 守护日志已连续输出至少 3 轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%
  • cycle=3, 58.5098%
• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4612112384
  • archive_progress_percent=60.0567
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • progress_percent=60.0582

结论：

• 新的守护启动方式已表现出明显更好的长期稳定性
• 当前唯一阻塞继续保持为：FMA 归档尚未完整下载

Stage: 真实 FMA 后台守护方式稳定化

完成项：

• 对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
• 判断二次掉线更可能来自后台脱离方式而非轮询逻辑
• 新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
• 验证新守护方式可跨多轮轮询持续存活

验证结果：

• 前台验证：
  • /usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3 连续输出 3 轮 polling，并正常结束为 status=waiting
• 下载进度继续增长到：
  • 4261445632 -> 4265574400
  • 55.4905% -> 55.5443%
• 新守护脚本启动后：
  • pid=52277
  • PPID=1
  • 进程状态仍存活
• 守护日志已连续输出至少两轮：
  • cycle=1, 55.8297%
  • cycle=2, 57.0573%

结论：

• 之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
• 现在真实 FMA 自动承接链路已有更稳的守护启动入口

Stage: 真实 FMA 长时等待器二次掉线复验

完成项：

• 复检长期等待器与日志输出状态
• 确认下载继续前进，但长期等待器再次退出
• 重新拉起等待器，恢复“下载完成后自动后处理”能力

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=4102045696
  • archive_progress_percent=53.4149
• 进程侧未发现 wait_for_fma_and_prepare.py
• 日志文件只保留首轮输出：
  • cycle=1
  • archive_progress_percent=52.5032
• 重新启动后，进程再次恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30

结论：

• 下载本身没有停，问题集中在长期等待器稳定性仍不足
• 下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路

Stage: 真实 FMA 等待器寿命缺陷修复

完成项：

• 诊断 wait_for_fma_and_prepare.py 掉线原因
• 确认原实现默认 max-cycles=3，约 90 秒后自然退出
• 修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
• 重新启动长期等待器并验证日志开始产生轮询输出

验证结果：

• 复检下载进度时已达到：
  • archive_size=3886596096
  • archive_progress_percent=50.6094
• 修复后执行：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2 返回两轮 polling，并确认字节继续增长到：
  • 3977117696 -> 3977314304
  • 51.7881% -> 51.7907%
• 长期等待器已重新启动：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30
• 日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON

结论：

• 之前等待器掉线不是下载异常，而是脚本寿命设计过短
• 现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力

Stage: 真实 FMA 守护链路掉线恢复

完成项：

• 再次复检 FMA 下载进度
• 复检后台等待器是否仍存活
• 发现等待器已退出后，重新拉起自动等待与后处理守护链路

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3650322432
  • archive_progress_percent=47.5327
• 复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
• 等待器日志文件存在但为空：
  • acr-engine/.omx_wait_for_fma.log
• 重新启动后，进程确认恢复：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 新守护进程 pid：51526

结论：

• 真实 FMA 下载仍在持续推进
• 自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态

Stage: 真实 FMA 自动等待与后处理守护启动

完成项：

• 再次复检 FMA 归档进度
• 检查是否已有后台“等待完成后自动后处理”任务
• 启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3518038016
  • archive_progress_percent=45.8102
• 启动后台等待器后，进程确认存在：
  • /usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400
• 当前后台等待器 pid：51242
• 等待器日志文件已创建：
  • acr-engine/.omx_wait_for_fma.log

结论：

• 除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
• 后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段

Stage: 真实 FMA 下载活跃性复验

完成项：

• 再次采集 FMA 归档字节进度
• 执行 watchdog 续验并附带进程级活跃性确认

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3403972608
  • archive_progress_percent=44.3249
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3406938112
  • archive_progress_percent=44.3635
  • live_curl=true
  • restarted=null
• 进程侧确认：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行

结论：

• 下载链路仍在持续前进且后台拉取进程健康
• 真实 FMA 下游工作仍等待归档完整这一单一前置条件

Stage: 真实 FMA 后处理门槛复验

完成项：

• 再次复检 FMA 下载进度
• 直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3322314752
  • archive_progress_percent=43.2616
• /usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：
  • status=blocked
  • reason=archive_not_complete
  • archive_size=3323641856
  • progress_percent=43.2789

结论：

• 真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
• 当前阻塞已被脚本化验证，不是人工主观判断

Stage: 真实 FMA 下载续进展验证

完成项：

• 再次执行 FMA 归档 inspect
• 执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_size=3222601728
  • archive_progress_percent=41.9632
• /usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：
  • archive_size=3222896640
  • archive_progress_percent=41.967
  • live_curl=true
  • restarted=null
• 对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节

结论：

• 当前下载未卡死，仍在稳定推进
• 真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛

Stage: 真实 FMA 下载状态续验

完成项：

• 复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 复检后台下载进程与本地归档体积
• 确认当前仍未达到可解压/可真实 smoke 的完成门槛

验证结果：

• /usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：
  • archive_bytes_expected=7679594875
  • archive_size=3117514752
  • archive_progress_percent=40.5948
  • num_audio_files=0
• 后台下载进程仍存活：
  • curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
• 当前本地归档文件：
  • data/raw/fma_small.zip = 3.0G

结论：

• 当前主卡点仍是 FMA 归档未完整下载
• 真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续

Stage: 训练数据与 pgvector 专项说明补强

完成项：

• 重写并补强 docs/training-data-and-pgvector-guide.md
• 单独详细说明：
  • 当前训练输入应由音频资产 + song_id 标签 + manifest 组成
  • reference 与 query 的角色区分
  • BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
  • 面向 PostgreSQL + pgvector 的字段保留与入库分层
• 将该专项文档挂接到 docs/README.md 的“数据与评测”主入口

验证结果：

• 已校验文档内新增相对链接全部可达
• 文档已覆盖：
  • 输入格式
  • 切片时长建议
  • label 设计
  • song_id/version_id 规范
  • pgvector 数据模型与入库流程
• 当前引用的仓库内实现锚点：
  • acr-engine/scripts/export_manifest_to_pgvector_json.py
  • acr-engine/sql/pgvector_schema.sql

结论：

• 现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
• 新 session 与后续数据工程实现可直接按该文档落地

Stage: MTG-Jamendo / ModelScope bootstrap + type-aware hard-case weighting

完成项：

• 补充 mtg_jamendo 与 modelscope_music 的 bootstrap manifest 生成
• 在训练链路中加入 type-aware hard-case weighting（针对 confused / humming_like）
• 重训 models_v5、重建 index_v5、重跑 smoke-v5 评测

验证结果：

• data/external_bootstrap/mtg_jamendo/manifests/catalog.bootstrap.json 成功生成
• data/external_bootstrap/modelscope_music/manifests/catalog.bootstrap.json 成功生成
• reports/smoke-v5/synthetic_v2/eval.json 成功生成
• 当前结果：top1=0.60, top5=0.90
• hard-case 结果：
  • humming_like top1=0.50（较 v4 有提升）
  • confused top1=0.00（仍未解决）

结论：

• type-aware weighting 比 naive oversampling 更有效
• 下一轮应专门针对 confused 类设计更强的 negative mining / confusion-aware 信号

Stage: internal asset query stride fix + type policy hardening

完成项：

• 修复 acr-engine/scripts/internal_asset_type_mapper.py 中内部素材 query 的自动扩窗逻辑
• 新增 source_audio_duration 透传，使长音频可基于真实总时长按 --query-stride 展开
• 修复 “默认 offset=0 被误判为显式 offset” 的问题，确保只有 CSV 明确给了 offset 才禁用扩窗
• 为 pgvector_payload.json 的 segments 补充 query_index
• 在 docs/training-data-and-pgvector-guide.md 补充内部素材滑窗规则、推荐参数表与自动扩窗示例

验证结果：

• 使用本地 30s songA.wav 验证：
  • --default-query-duration 8 --query-stride 4
  • queries.json 成功导出 7 条 query
  • offset 为 0, 4, 8, 12, 16, 20, 22
  • query_index 为 0..6
• 使用本地 40s songB.wav + CSV 显式 offset=12 验证：
  • 仍只导出 1 条 query
  • 未被自动扩窗覆盖
• manifest_bundle/*.json 与 pgvector_payload.json 均已同步反映扩窗结果

结论：

• 现在内部素材可以稳定支持两种模式：
  • 人工标 offset 的短视频片段：保持单条 query
  • 只有整首音频、没有 query 起点的素材：自动生成多窗口 query
• 这让 7/8/16/18 这类 query 型素材可以更直接进入训练与评测流水线，同时保留对 pgvector 入库的可追踪性

Stage: silence-aware segmentation for training and open-dataset query generation

完成项：

• 在 acr-engine/src/data/dataset.py 为训练切片新增：
  • segment_strategy=random|silence_aware|hybrid
  • silence_top_db
• 接入 librosa.effects.split，用于优先选择非静音区作为训练片段来源
• 在 acr-engine/src/data/manifest_tools.py 为外部数据 query 生成新增：
  • --query-strategy random|sliding|silence_aware|hybrid
  • --silence-top-db
• 在 acr-engine/train.py 暴露训练 CLI 参数：
  • --segment-strategy
  • --silence-top-db
• 在 acr-engine/src/data/external_adapters.py 接通 prepare-local / smoke-local 的策略透传与配置落盘
• 在 docs/training-data-and-pgvector-guide.md 补充“切片策略”章节

验证结果：

• 代码编译验证：
  • /usr/local/miniconda3/bin/python -m py_compile src/data/dataset.py src/data/manifest_tools.py train.py src/data/external_adapters.py
• 人造音频验证：
  • 构造 4s silence + 10s tone + 4s silence
  • manifest_tools.py --query-strategy silence_aware --query-duration 5 --query-stride 2.5
  • 导出 query offset：3.968, 8.968, 9.08
  • 说明 query 已明显偏向非静音主体区
• 训练侧偏移验证：
  • random offset 样本：0.325, 1.13, 2.902, 3.575, 8.313, 8.797, 9.574, 11.598
  • silence_aware offset 样本：4.173, 4.228, 4.736, 5.111, 5.874, 5.974, 8.436, 8.805
  • 说明 silence-aware 显著减少落入头尾静音区的概率
• dry-run 验证：
  • train.py --data data/synthetic_v2 --dry-run --segment-strategy silence_aware
  • forward/backward 成功，Embedding shape: torch.Size([64, 192])
• adapter 验证：
  • external_adapters.py prepare-local ... --query-strategy silence_aware
  • summary 已记录 query_strategy: silence_aware

结论：

• 当前项目不再只有“随机切”
• 已形成：
  • 训练侧：random / silence_aware / hybrid
  • 建库侧：固定滑窗
  • 开源集 query 生成侧：random / sliding / silence_aware / hybrid
• 下一阶段可继续叠加 beat/onset/chorus-aware 切片，而无需推翻现有流程

Stage: build-index checkpoint resume + path compatibility hardening

完成项：

• 在 acr-engine/src/engines/ecapa_embedder.py 完成 embedding index 的 checkpoint / resume 逻辑
  • 支持读取 reference_progress.json
  • 支持复用 reference_embs.partial.npy / reference_ids.partial.npy
  • 若 final index 已存在，--resume 直接命中完成态
• 在 acr-engine/run_demo.py build-index 暴露：
  • --resume
  • --checkpoint-every-refs
• 修复 synthetic / 根目录型数据集的音频路径解析兼容问题：
  • acr-engine/src/engines/ecapa_embedder.py
  • acr-engine/src/engines/chromaprint_matcher.py
• 为 “没有任何 reference 被成功解析” 的场景补充显式报错，避免 np.vstack([]) 这类低可读错误
• 在 docs/open-dataset-workflow.md 补充 build-index --resume 用法

验证结果：

• 代码编译验证：
  • /usr/local/miniconda3/bin/python -m py_compile src/engines/ecapa_embedder.py src/engines/chromaprint_matcher.py run_demo.py
• 兼容性验证：
  • run_demo.py build-index --data data/synthetic_v2 --model data/models_v6/best_model.pt --output /tmp/index_resume_fresh --device cpu
  • synthetic 根目录型 audio_path=songs/... 已可正常建索引
• resume 一致性验证：
  1. 用 data/synthetic_v2/catalog.json 的前 2 首 reference 生成 partial checkpoint
  2. 人工保留 reference_embs.partial.npy / reference_ids.partial.npy + reference_progress.json
  3. 执行：
     • run_demo.py build-index ... --resume --checkpoint-every-refs 1
  4. 与 fresh full rebuild 对比结果：
     • resume_shape == fresh_shape == (120, 192)
     • ids_equal == True
     • embs_allclose == True
     • progress_status == complete
     • progress_refs_done == progress_refs_total == 24
• resume 日志证据：
  • [build-reference-index] resuming from checkpoint: refs_done=2/24 windows_done=10

结论：

• 现在 CPU 长时间 build-index 任务即使中断，也可以从 partial checkpoint 续跑
• 该恢复逻辑已经拿到“恢复结果与 fresh rebuild 完全一致”的新鲜证据
• 下一步可以把这套 resume 能力进一步接到 smoke-local 的自动恢复策略里

Stage: smoke-local auto resume + model-signature safety gate

完成项：

• 在 acr-engine/src/engines/ecapa_embedder.py 为 index checkpoint 增加 model_signature
  • path
  • size_bytes
  • mtime_ns
• 恢复时如果 checkpoint 的 model_signature 与当前 best_model.pt 不一致：
  • 自动拒绝旧 checkpoint
  • 清理旧 partial 文件
  • 从 0 重建 embedding index
• 在 acr-engine/src/data/external_adapters.py 的 smoke-local 中默认启用：
  • run_demo.py build-index --resume
  • --checkpoint-every-refs
• 在 docs/open-dataset-workflow.md 补充模型签名护栏说明

验证结果：

• 编译验证：
  • /usr/local/miniconda3/bin/python -m py_compile src/engines/ecapa_embedder.py src/data/external_adapters.py run_demo.py
• 同模型恢复验证（models_v6 -> models_v6）：
  • 人工构造前 2 首 reference 的 partial checkpoint
  • 日志出现：
  • [build-reference-index] resuming from checkpoint: refs_done=2/24 windows_done=10
  • 与 fresh rebuild 对比：
  • same_final_ids_equal == True
  • same_final_embs_equal == True
  • same_progress_status == complete
• 异模型拒绝恢复验证（models_v6 partial -> models_v5 current）：
  • 日志出现：
  • resume checkpoint ignored due to load failure: model signature mismatch
  • 随后从 0 重建：
  • start: refs=24 ... resume=True refs_done=0
  • 与 models_v5 fresh rebuild 对比：
  • mismatch_final_ids_equal == True
  • mismatch_final_embs_equal == True

结论：

• smoke-local 现在已经具备“可恢复，但不会错误复用旧模型 embedding”的安全自动恢复能力
• 这对真实 FMA 这类 CPU 长时任务尤其重要：重启可续跑，换模型不会串污染 index

Stage: high-energy / onset-aware music segmentation

完成项：

• 在 acr-engine/src/data/dataset.py 新增训练切片候选策略：
  • high_energy
  • onset_aware
• 在 acr-engine/src/data/manifest_tools.py 新增外部 query 生成策略：
  • --query-strategy high_energy
  • --query-strategy onset_aware
• 将 hybrid 升级为可复用：
  • high_energy
  • onset_aware
  • silence_aware 三类音乐感知候选，再补随机 fallback
• 在 train.py 与 external_adapters.py 暴露新策略选项
• 在 docs/training-data-and-pgvector-guide.md 增补策略说明与使用建议

验证结果：

• 编译验证：
  • /usr/local/miniconda3/bin/python -m py_compile src/data/dataset.py src/data/manifest_tools.py train.py src/data/external_adapters.py
• 人造音频验证：
  • 构造 20s 音频：
  • 4-6s 低能 tone
  • 8/10/12s 强起音脉冲
  • 14-19s 高能 tone
• query 生成结果：
  • high_energy offsets：
  • 2.5, 7.5, 10.0, 12.5, 15.0
  • onset_aware offsets：
  • 4.032, 6.048, 8.032, 10.016, 10.048, 12.032
• 训练侧偏移验证：
  • TRAIN_HIGH_ENERGY_OFFSETS：
  • 2.5, 15.0, 15.0, 2.5, 10.0, 12.5
  • TRAIN_ONSET_OFFSETS：
  • 4.064, 4.032, 10.016, 8.032, 8.032, 6.048
  • 说明新策略已明显偏向强能量区或起音邻域，而不是纯随机
• dry-run 验证：
  • train.py --data data/synthetic_v2 --dry-run --segment-strategy high_energy
  • forward/backward 成功，Embedding shape: torch.Size([64, 192])

结论：

• 当前项目的音乐感知切片已经从“避静音”扩展到了“偏主段 / 偏起音”
• 下一步若继续增强，可在此基础上叠加：
  • beat-aware
  • chorus-aware
  • repeated-section-aware

Stage: beat-aware music segmentation

完成项：

• 在 acr-engine/src/data/dataset.py 新增：
  • beat_aware 候选切片策略
• 在 acr-engine/src/data/manifest_tools.py 新增：
  • --query-strategy beat_aware
• 在 train.py 与 external_adapters.py 暴露：
  • beat_aware 选项
• 为 beat_aware 增加容错：
  • 优先使用 librosa.beat.beat_track
  • 若 beat 检测失败，则回退到 onset 间隔估计生成近似节拍点
• 将 hybrid 扩展为优先复用：
  • beat_aware
  • high_energy
  • onset_aware
  • silence_aware

验证结果：

• 编译验证：
  • /usr/local/miniconda3/bin/python -m py_compile src/data/dataset.py src/data/manifest_tools.py train.py src/data/external_adapters.py
• 人造节拍音频验证：
  • 构造 20s 音频
  • 4s-18s 区间每 0.5s 注入一次脉冲（约 120 BPM）
  • 再叠加轻微 tonal bed
• 直接 beat 候选结果：
  • DIRECT_BEAT_CANDIDATES_SEC：
  • 4.032, 5.952, 7.872, 9.792, 11.712, 13.632, 15.0
• query 生成结果：
  • BEAT_QUERY_OFFSETS：
  • 4.032, 7.872, 9.792, 11.712, 13.632, 15.0
  • HYBRID_QUERY_OFFSETS：
  • 3.968, 4.032, 4.064, 4.544, 5.0, 5.536, 6.016, 6.048, 7.872, 9.591, 9.792, 10.0
• 训练侧偏移验证：
  • TRAIN_BEAT_AWARE_OFFSETS：
  • 13.632, 4.032, 4.032, 13.632, 7.872, 5.952
  • TRAIN_HYBRID_OFFSETS：
  • 2.5, 5.536, 4.064, 12.5, 7.872, 4.032
  • 说明 beat-aware 已明显偏向规则拍点，hybrid 也已吸收 beat-aware 候选
• dry-run 验证：
  • train.py --data data/synthetic_v2 --dry-run --segment-strategy beat_aware
  • forward/backward 成功，Embedding shape: torch.Size([64, 192])

结论：

• 当前项目的音乐感知切片已经进一步从“高能/起音”扩展到“规则拍点”
• 下一步可继续叠加：
  • repeated-section-aware
  • chorus-like candidate mining

Stage: repeated-section-aware / chorus-like candidate sampling

完成项：

• 在 acr-engine/src/data/dataset.py 新增：
  • repeated_section_aware
• 在 acr-engine/src/data/manifest_tools.py 新增：
  • --query-strategy repeated_section_aware
• 在 train.py 与 external_adapters.py 暴露：
  • repeated_section_aware
• 实现方式：
  • 对滑窗片段提取 chroma_cqt
  • 取窗口级平均 chroma 向量
  • 计算窗口间相似度
  • 优先选择“与其它窗口最相似”的片段，作为重复主段 / 副歌 hook 的轻量近似
• 将 hybrid 扩展为优先复用：
  • repeated_section_aware
  • beat_aware
  • high_energy
  • onset_aware
  • silence_aware

验证结果：

• 编译验证：
  • /usr/local/miniconda3/bin/python -m py_compile src/data/dataset.py src/data/manifest_tools.py train.py src/data/external_adapters.py
• 人造“重复副歌”音频验证：
  • 构造 24s 音频
  • 8-12s 与 16-20s 放置两段重复 motif
• 直接重复候选结果：
  • DIRECT_REPEAT_CANDIDATES_SEC：
  • 6.0, 8.0, 10.0, 14.0, 16.0, 18.0
• query 生成结果：
  • REPEAT_QUERY_OFFSETS：
  • 6.0, 10.0, 14.0, 16.0, 18.0
  • HYBRID_QUERY_OFFSETS：
  • 2.016, 2.048, 2.08, 6.0, 6.048, 8.0, 8.064, 10.0, 12.789, 14.0, 15.968, 16.0
• 训练侧偏移验证：
  • TRAIN_REPEAT_OFFSETS：
  • 17.5, 0.0, 0.0, 17.5, 7.5, 2.5
  • TRAIN_HYBRID_OFFSETS：
  • 0.0, 8.032, 2.5, 2.048, 2.016, 7.5
  • 说明 repeated-section-aware 已能明显偏向重复主段周边，而 hybrid 也已吸收这类候选
• dry-run 验证：
  • train.py --data data/synthetic_v2 --dry-run --segment-strategy repeated_section_aware
  • forward/backward 成功，Embedding shape: torch.Size([64, 192])

结论：

• 当前项目的音乐感知切片已经从：
  • 避静音
  • 高能区
  • 起音点
  • 拍点 进一步扩展到：
  • 重复主段 / 近似副歌
• 下一步可继续做更强的：
  • chorus-like multi-feature ranking
  • 小规模真实数据策略 A/B 对比

Stage: real FMA mini-subset segmentation A/B smoke benchmark

完成项：

• 新增脚本：
  • acr-engine/scripts/ab_smoke_segmentation.py
• 能力：
  • 从本地真实数据目录抽取固定数量子集
  • 依次运行 smoke-local
  • 自动比较多种切片策略的 smoke 结果
  • 汇总 top1 / topk / num_queries
• 修正排序规则：
  • 不再只按 top1/topk
  • 改为 top1 -> topk -> num_queries
  • 避免在分数持平时把 query 更少的策略误判为 winner

验证结果：

• 真实数据来源：
  • data/raw/fma_small_audio
• smoke 子集：
  • 8 首 FMA 音频
  • query_duration=8
  • train_epochs=1
  • batch_size=2
• 比较策略：
  • random
  • silence_aware
  • high_energy
  • beat_aware
  • repeated_section_aware
  • hybrid
• 报告路径：
  • /tmp/ab_smoke_seg/report.json
• 排序修正后的结果：
  1. hybrid：num_queries=37, top1=1.0, topk=1.0
  2. beat_aware：num_queries=13, top1=1.0, topk=1.0
  3. high_energy：num_queries=12, top1=1.0, topk=1.0
  4. repeated_section_aware：num_queries=12, top1=1.0, topk=1.0
  5. random：num_queries=4, top1=1.0, topk=1.0
  6. silence_aware：num_queries=2, top1=1.0, topk=1.0

结论：

• 在这个极小真实子集 smoke 上，所有策略都能达到 top1/top5 = 1.0
• 但从 query 覆盖率 看：
  • hybrid 当前最优
  • beat_aware / high_energy / repeated_section_aware 是更强的次优候选
• 下一步应扩大真实子集规模，并引入更难的 query 类型，进一步拉开策略差异