Changelog

2026-06-02

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 信号