AGENTS.md

Machine-Learning-refactor AGENTS.md

项目定位

D:\pywork\03_Github重构\Machine-Learning-refactor 是 Albertsr/Machine-Learning 的独立本地重构仓库。

当前第一阶段只负责把 Albertsr/Optimization 与马老师本地 “专题12：贝叶斯优化”中确认可公开的作者材料，整合为一个可追溯、 双语、可测试的贝叶斯优化专题。

本项目不是对整个历史 Machine-Learning 仓库的一次性重写。

上游与许可证边界

• 主上游：https://github.com/Albertsr/Machine-Learning
• 待整合上游：https://github.com/Albertsr/Optimization
• 本地作者来源： D:\pywork\02_历史学习资料\05.Machine Learning\专题12：贝叶斯优化
• 马老师确认拥有并重新整理的自有内容，计划采用 MIT 许可。
• Hyperopt 官方示例继续受上游 BSD-3-Clause 约束，必须在 THIRD_PARTY_NOTICES.md 中保留来源、copyright 和许可条件。
• 来源未确认的论文截图、第三方教程、数据和混合改编内容，不得纳入 MIT 覆盖范围，也不得进入维护主线。

可公开与禁止公开

允许进入公开候选：

• 两个既有公开仓库的历史与内容；
• 经来源核对、输出清理和隐私检查的作者 notebook；
• 基于作者原稿做出的英文讲解、兼容补丁、测试和可复现 companion；
• 公共论文、官方文档和公开数据的规范引用。

禁止进入公开候选：

• hyperparameter-optimization/ 第三方教程副本；
• 前司项目、朋友项目、客户或业务材料；
• Caravan 等许可未确认的数据文件；
• 历史 CSV/JSON 结果、模型、缓存和本地绝对路径；
• token、凭据、内部模块、专利或未确认可公开材料。

手写痕迹保护

1. Optimization 历史导入不得使用 --squash。
2. 原样导入、来源标注、文档修订、兼容修复和新示例必须分开提交。
3. 不批量格式化旧代码，不批量改名，不机械翻译所有中文。
4. 修改作者 notebook 时，保留原 cell 顺序、主要函数名、中文注释和推导逻辑。
5. 大幅重构前先建立可复现基线或行为测试。
6. 对新增或改动较大的内容，在文档中区分：
   • Original notebook cell
   • Maintainer note, 2026
   • Compatibility patch, 2026
7. 第三方示例只能作为带来源的 legacy 材料，不能包装为作者原创。

双语规则

• 第一阶段保留中文根 README.md，新增 README.en.md。
• 贝叶斯优化专题使用英文 README.md 与完整中文 README.zh-CN.md。
• 英文必须是可独立阅读的实质性讲解，不是中文的简短摘要。
• 中文入口和作者原有推导顺序必须保留。
• 数学公式、代码和共享图片只维护一份，避免双语副本漂移。
• 新增代码的关键注释和 docstring 优先采用简洁中英双语；代码标识符保持英文。

Notebook 规则

• 原始历史 notebook 默认只做结构审计，不执行。
• 公开快照必须：
  • 记录来源 SHA-256；
  • 清除 outputs 和 execution counts；
  • 删除本地路径、内核环境和无关元数据；
  • 规范 cell IDs；
  • 通过 nbformat.validate；
  • 保存为 UTF-8，不含 U+FFFD 或乱码。
• 现代维护版应在条件具备时通过 pywork_py311 自顶向下执行。
• 未执行或被依赖阻塞时，必须准确记录缺少的包、数据或 API 兼容问题。

目录规则

9. The Foundations of ML/
  Optimization/
    Bayesian Optimization/
      README.md
      README.zh-CN.md
      examples/
      legacy/
        author-notebooks/
        third-party/
        unverified-assets/
      assets/
      references/
      tests/

• legacy/ 保存有明确来源的历史材料，不作为当前推荐 API。
• legacy/third-party/ 保存已确认第三方来源与许可条件的材料。
• legacy/unverified-assets/ 保存仍待核实作者权利或许可的历史证据； 维护版教程不得内嵌这些素材。
• examples/ 保存维护中的可复现教程。
• references/ 保存来源与迁移说明，不放数据副本。
• tests/ 只覆盖新专题和明确现代化的代码，不强迫整个历史仓库通过统一 lint。

Python 与依赖

• 默认解释器： D:\program_files\anaconda\envs\pywork_py311\python.exe
• 不创建工作区本地虚拟环境。
• 项目依赖必须写入专题依赖文件或项目文档。
• 不因验证方便而把本地私有模块复制进公开仓库。

输出、数据与清理

• __pycache__/、*.pyc、.ipynb_checkpoints/、测试缓存和临时文件不进入 Git。
• notebook 执行输出、CSV/JSON 结果、模型和下载数据默认不进入 Git。
• 新技术流程图使用可编辑 SVG，并输出同名 PNG。
• 任何删除必须先确认目标位于本项目内、不是链接或重解析点，且不是来源原稿。

Git 纪律

• 当前工作分支使用 codex/integrate-optimization。
• 不使用 git add . 或 git add -A；按文件和主题精确暂存。
• 未经马老师后续明确确认，不 push、不创建 PR、不修改线上 README、不归档旧仓库。
• 不 rebase、reset hard、force-push 或改写已导入历史。
• 每轮结束前检查本仓库状态，并与 D:\pywork 根仓状态区分报告。