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:09 UTC）

• 远程同步基线：cdf33bb
• 当前已不是“进程仍在运行”的阶段，而是：
  • observable PID=431703 已退出
  • legacy PID=424691 已退出
• observable 当前只留下：
  • /tmp/chroma_index_observable_smoke/chromaprint.pkl
  • /tmp/chroma_index_observable_smoke/chromaprint_progress.json
• 最后进度停在：
  • status=building
  • refs_done=4420/8000
• 当前仍未出现 reference_* 或 evaluate.py。
• 因此下一轮工作重心必须切到：排查 build-index 异常退出，而不是继续把它当作纯线性慢任务。
• 已完成一个低风险修复：关键 print() 已加 flush=True，并已用极小样本 RC=1 失败复现验证日志/traceback 可实时落盘，不再出现 0 bytes 日志黑箱。
• 已完成一个高价值容错修复：坏 MP3 / 缺失音频会在 chromaprint/reference 阶段被跳过，并已用 1 good + 1 bad 最小复现验证 RC=0、reference_* 成功产出。
• 下一次值得提交的事件：
  1. 找到明确失败证据/退出原因
  2. 成功小样本复现并补日志
  3. 修复后重新跑到 reference_* 或 evaluate.py

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