AGENT Memory / 开发续跑记忆

更新：2026-06-02 目的：让新 session 在 1~3 分钟内接上当前开发节奏。

1. 用户长期偏好

• 默认使用中文输出。
• 尽量自主推进，不要频繁停下来询问。
• 每完成一个阶段性 checklist：
  1. 更新 docs/CHANGELOG.md
  2. git commit
  3. git push origin main
• Python 固定使用：/usr/local/miniconda3/bin/python
• 文档优先级：图 > 表 > 文字 > 细节附录。
• 文档要浓缩分类，避免同层级文档过多。
• 外部/内部文档链接优先使用相对路径跳转，不要只用反引号包裹地址。
• 严禁误提交大体积数据、训练产物、/tmp 结果、__pycache__。

2. 当前项目主线

这是一个正在工业化的音乐 ACR / 检索项目，主线是：

• 开放数据集接入
• 音频切片策略优化
• 训练 / 建索引 / 评测闭环
• 准确率与混淆鲁棒性提升
• 文档与交接体系完善

3. 当前已完成重点

• 已实现多种切片策略：
  • random
  • silence_aware
  • high_energy
  • onset_aware
  • beat_aware
  • repeated_section_aware
  • hybrid
• 已实现公平评测控制：
  • evaluate.py --max-queries --seed
  • smoke-local --max-test-queries
  • scripts/ab_smoke_segmentation.py --max-test-queries
• 已补强数据规范、pgvector 指南、FMA/开放数据工作流文档。

4. 当前经验结论

• 小样本真实 FMA smoke 下，多策略都可能接近满分，不能据此定默认策略。
• cap48 规模下结果对 seed 敏感。
• cap64 当前单 seed 下 hybrid 更强。
• bucket toy smoke 已完成完整汇总，并出现不同 bucket 的不同 winner。
• 默认策略决策应基于 multi-seed + bucket/style-aware aggregate，而不是单次跑分。

5. 当前续跑优先级

1. 将 toy prefix bucket 升级为语义 bucket。
   • 通用模板：acr-engine/configs/buckets/fma_semantic_bucket_template.json
   • 业务模板：acr-engine/configs/buckets/business_type_bucket_template.json
   • 业务说明：docs/business-music-bucket-and-type-guide.md
   • Manifest 规范：docs/business-manifest-and-type-role-spec.md
   • 导出 cookbook：docs/business-export-cookbook.md
   • 规范化脚本：acr-engine/scripts/normalize_business_export.py
   • 角色拆分脚本：acr-engine/scripts/split_business_manifest_ready.py
   • 项目 manifest 适配：acr-engine/scripts/build_business_project_manifests.py
2. 补 cap64 multi-seed aggregate。
3. 更新：
   • docs/open-dataset-workflow.md
   • docs/session-handoff.md
   • docs/CHANGELOG.md
4. 提交并推送。
5. 下一轮再推进：
   • 工业级 hard negative / confusion bucket
   • hybrid 波动收敛
   • 更接近商用的数据集组合评测

5.5 最新真实 FMA smoke 运行态（2026-06-02）

• 真实 FMA 数据已本地就绪：acr-engine/data/raw/fma_small_audio/
• 已验证：
  • num_audio_files=8000
  • eligible_query_files=7994
  • ready_for_smoke=true
• 当前有一条真实 FMA 端到端 smoke 正在运行：
  • 进程：src/data/external_adapters.py smoke-local fma ...
  • 输出：/tmp/fma_real_smoke_stopcheck
  • 训练子进程：train.py --data /tmp/fma_real_smoke_stopcheck/fma/manifests ...
• 最新 checkpoint（2026-06-02 12:09 UTC）：
  • train.py 仍在运行
  • ELAPSED=12:00
  • catalog_references=8000
  • train_queries=6401
  • test_queries=1593
  • fma_models_smoke/ 仍为空，这在当前实现中是正常现象，因为 best_model.pt 只会在 Epoch 1 结束后首次保存
• 环境确认无 GPU：
  • nvidia-smi 不可用
  • torch.cuda.is_available() = false
• 因此当前最真实的卡点不是 bug，而是 CPU-only 真实 FMA smoke 耗时长。

6. 高风险注意事项

• git status 中通常会有大量：
  • acr-engine/data/raw/...
  • acr-engine/data/external_smoke/...
  • 模型 checkpoint
  • __pycache__
• 提交时必须显式 git add 目标文档文件，不能使用宽泛全量暂存。

7. 关键文档入口

• docs/README.md
• docs/open-dataset-workflow.md
• docs/dataset-spec.md
• docs/training-data-and-pgvector-guide.md
• docs/session-handoff.md
• docs/CHANGELOG.md

7.5 新 session 最短可跑命令

cd /workspace/acr-engine
/usr/local/miniconda3/bin/python scripts/business_export_offline_smoke.py \
  --output-root /tmp/business_export_offline_smoke

预期：

• 业务导出离线链跑通
• 生成项目 manifests
• train.py --dry-run 通过