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
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 波动收敛
   • 更接近商用的数据集组合评测

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