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 / chromaprint 运行态（2026-06-02）

当前最新快照（15:43 UTC）

• 远程同步基线：81704ac（更新前）
• 当前最重要的新证据：hard-case 短板已经被明确量化。
• real-path clean 闭环：num_queries=35, top1=0.8571, topk=1.0
• synthetic hard-case smoke：num_queries=16, top1=0.6875, topk=1.0
  • humming_like: n=4, top1=0.25, topk=1.0
  • confused: n=1, top1=0.0, topk=1.0
• 关键解释：real-path FMA external smoke manifest 目前只有 clean query；humming_like / confused 需要通过 data/synthetic_v2 这类 hard-case 集补验证。
• 这说明：当前工程链已经足够稳定，下一步的最大收益不在 clean smoke，而在 hard-case top1 提升。
• 下一次值得提交的事件：
  1. hard-case 优化后指标改善
  2. 真实开放数据上的 hard-case 生成/标注方案落地
  3. 更大规模 query/reference 的复测结果

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 通过