From 9c6ff12fe6913137269952b73949cd35689ca4f7 Mon Sep 17 00:00:00 2001
From: De-Shiou Huang <huangdeshiou@gmail.com>
Date: Sat, 21 Feb 2026 15:00:23 +0800
Subject: [PATCH 1/5] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E6=95=B0=E6=8D=AE?=
 =?UTF-8?q?=E9=9B=86=E6=96=87=E4=BB=B6=E5=91=BD=E5=90=8D=E5=86=B2=E7=AA=81?=
 =?UTF-8?q?=E9=97=AE=E9=A2=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

将 modules/common/datasets.py 重命名为 data_sources.py，避免与 HuggingFace datasets 库产生命名冲突。更新所有相关文档中的引用。

解决问题：
- TinyStories 数据集下载时 import datasets 失败
- Python 错误导入当前文件而非 HuggingFace 库

修改内容：
- 重命名: datasets.py → data_sources.py
- 更新所有文档中的命令和导入示例
- 包括中英文文档的同步更新

Fixes #19

Co-Authored-By: Claude (pa/claude-sonnet-4-5-20250929) <noreply@anthropic.com>
---
 ROADMAP.md                                      | 2 +-
 docs/guide/quick-start.md                       | 2 +-
 en/ROADMAP.md                                   | 2 +-
 en/docs/guide/quick-start.md                    | 2 +-
 en/modules/01-foundation/index.md               | 2 +-
 en/modules/index.md                             | 6 +++---
 modules/01-foundation/README.md                 | 2 +-
 modules/README.md                               | 6 +++---
 modules/common/{datasets.py => data_sources.py} | 2 +-
 modules/index.md                                | 6 +++---
 10 files changed, 16 insertions(+), 16 deletions(-)
 rename modules/common/{datasets.py => data_sources.py} (99%)

diff --git a/ROADMAP.md b/ROADMAP.md
index f94a932..598c66a 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -38,7 +38,7 @@ source venv/bin/activate
 
 # 3. 下载实验数据（可选，部分实验不需要）
 cd modules/common
-python datasets.py --download-all
+python data_sources.py --download-all
 cd ../..
 ```
 
diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md
index 9125db9..c2ac435 100644
--- a/docs/guide/quick-start.md
+++ b/docs/guide/quick-start.md
@@ -27,7 +27,7 @@ source venv/bin/activate
 
 # 3. 下载实验数据（可选，部分实验不需要）
 cd modules/common
-python datasets.py --download-all
+python data_sources.py --download-all
 cd ../..
 ```
 
diff --git a/en/ROADMAP.md b/en/ROADMAP.md
index ce0190a..14e783d 100644
--- a/en/ROADMAP.md
+++ b/en/ROADMAP.md
@@ -39,7 +39,7 @@ source venv/bin/activate
 
 # 3. Download experiment data (optional, some experiments do not need it)
 cd modules/common
-python datasets.py --download-all
+python data_sources.py --download-all
 cd ../..
 ```
 
diff --git a/en/docs/guide/quick-start.md b/en/docs/guide/quick-start.md
index 1938547..3a1875e 100644
--- a/en/docs/guide/quick-start.md
+++ b/en/docs/guide/quick-start.md
@@ -20,7 +20,7 @@ source venv/bin/activate
 
 # 3. Download experiment datasets (optional)
 cd modules/common
-python datasets.py --download-all
+python data_sources.py --download-all
 cd ../..
 ```
 
diff --git a/en/modules/01-foundation/index.md b/en/modules/01-foundation/index.md
index c2654e7..9d24d2f 100644
--- a/en/modules/01-foundation/index.md
+++ b/en/modules/01-foundation/index.md
@@ -125,7 +125,7 @@ For each module:
 
 A: Check the following:
 1. Did you activate the virtual environment? `source venv/bin/activate`
-2. Did you download data? `cd modules/common && python datasets.py --download-all`
+2. Did you download data? `cd modules/common && python data_sources.py --download-all`
 3. Are you in the correct folder? Experiments must run inside `experiments/`
 
 **Q: Experiments are too slow?**
diff --git a/en/modules/index.md b/en/modules/index.md
index 2004c1a..f88f5cb 100644
--- a/en/modules/index.md
+++ b/en/modules/index.md
@@ -68,7 +68,7 @@ source venv/bin/activate
 
 # 2. Download experiment data (~60 MB)
 cd modules/common
-python datasets.py --download-all
+python data_sources.py --download-all
 ```
 
 ### 30-minute quick experience
@@ -170,10 +170,10 @@ Each design choice answers:
 
 Shared tools live in `modules/common/`:
 
-### datasets.py - Dataset manager
+### data_sources.py - Dataset manager
 
 ```python
-from modules.common.datasets import get_experiment_data
+from modules.common.data_sources import get_experiment_data
 
 # TinyShakespeare
 text = get_experiment_data('shakespeare')
diff --git a/modules/01-foundation/README.md b/modules/01-foundation/README.md
index 4e1967a..3e60591 100644
--- a/modules/01-foundation/README.md
+++ b/modules/01-foundation/README.md
@@ -125,7 +125,7 @@ keywords: Transformer基础组件, 归一化, 位置编码, 注意力机制, 前
 
 A: 检查以下几点：
 1. 是否激活了虚拟环境？ `source venv/bin/activate`
-2. 是否下载了数据？ `cd modules/common && python datasets.py --download-all`
+2. 是否下载了数据？ `cd modules/common && python data_sources.py --download-all`
 3. 是否在正确的目录？实验需要在 `experiments/` 目录下运行
 
 **Q: 实验太慢怎么办？**
diff --git a/modules/README.md b/modules/README.md
index 3b85d16..152dc42 100644
--- a/modules/README.md
+++ b/modules/README.md
@@ -68,7 +68,7 @@ source venv/bin/activate
 
 # 2. 下载实验数据（约 60 MB）
 cd modules/common
-python datasets.py --download-all
+python data_sources.py --download-all
 ```
 
 ### 30 分钟快速体验
@@ -170,10 +170,10 @@ python exp_xxx.py --help
 
 模块提供了以下通用工具（位于 `modules/common/`）：
 
-### datasets.py - 数据集管理
+### data_sources.py - 数据集管理
 
 ```python
-from modules.common.datasets import get_experiment_data
+from modules.common.data_sources import get_experiment_data
 
 # 获取 TinyShakespeare
 text = get_experiment_data('shakespeare')
diff --git a/modules/common/datasets.py b/modules/common/data_sources.py
similarity index 99%
rename from modules/common/datasets.py
rename to modules/common/data_sources.py
index 3eeae1a..999fffe 100644
--- a/modules/common/datasets.py
+++ b/modules/common/data_sources.py
@@ -7,7 +7,7 @@
 - 合成数据（用于可视化实验）
 
 使用示例：
-    from modules.common.datasets import get_experiment_data
+    from modules.common.data_sources import get_experiment_data
 
     # 获取 TinyShakespeare
     text = get_experiment_data('shakespeare')
diff --git a/modules/index.md b/modules/index.md
index 11a7a42..4d4a32a 100644
--- a/modules/index.md
+++ b/modules/index.md
@@ -68,7 +68,7 @@ source venv/bin/activate
 
 # 2. 下载实验数据（约 60 MB）
 cd modules/common
-python datasets.py --download-all
+python data_sources.py --download-all
 ```
 
 ### 30 分钟快速体验
@@ -170,10 +170,10 @@ python exp_xxx.py --help
 
 模块提供了以下通用工具（位于 `modules/common/`）：
 
-### datasets.py - 数据集管理
+### data_sources.py - 数据集管理
 
 ```python
-from modules.common.datasets import get_experiment_data
+from modules.common.data_sources import get_experiment_data
 
 # 获取 TinyShakespeare
 text = get_experiment_data('shakespeare')

From 7446ff674f1ae41b069372ae719e7d6a115782d0 Mon Sep 17 00:00:00 2001
From: De-Shiou Huang <huangdeshiou@gmail.com>
Date: Sat, 21 Feb 2026 15:22:57 +0800
Subject: [PATCH 2/5] =?UTF-8?q?=E6=A0=B9=E6=8D=AE=E4=BB=A3=E7=A0=81?=
 =?UTF-8?q?=E8=AF=84=E5=AE=A1=E6=94=B9=E8=BF=9B=E8=BF=81=E7=A7=BB=E6=96=B9?=
 =?UTF-8?q?=E6=A1=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

改进内容：
1. 添加废弃提示文件 datasets.py，给出清晰错误信息
2. 创建 modules/common/README.md 详细说明工具和迁移方法
3. 在主要文档中添加迁移说明（中英文）

解决评审关注点：
- 现有/未来代码兼容性：废弃文件会抛出友好错误提示
- 文档完整性：README 提供完整的工具说明和迁移指南
- 向后不兼容可见性：在用户文档中明确说明变更

Co-Authored-By: Claude (pa/claude-sonnet-4-5-20250929) <noreply@anthropic.com>
---
 en/modules/index.md        |  29 ++++++++++-
 modules/README.md          |  29 ++++++++++-
 modules/common/README.md   | 100 +++++++++++++++++++++++++++++++++++++
 modules/common/datasets.py |  28 +++++++++++
 modules/index.md           |  29 ++++++++++-
 5 files changed, 212 insertions(+), 3 deletions(-)
 create mode 100644 modules/common/README.md
 create mode 100644 modules/common/datasets.py

diff --git a/en/modules/index.md b/en/modules/index.md
index f88f5cb..a674c6d 100644
--- a/en/modules/index.md
+++ b/en/modules/index.md
@@ -204,7 +204,34 @@ from modules.common.visualization import (
 )
 ```
 
-See docstrings in each file for details.
+See docstrings in each file or [`modules/common/README.md`](../modules/common/README.md) for details.
+
+#### ⚠️ Migration Notice
+
+**2025-02**: `datasets.py` has been renamed to `data_sources.py`
+
+If your code uses the old import:
+```python
+# Old code (will error)
+from modules.common.datasets import get_experiment_data
+```
+
+Please update to:
+```python
+# New code
+from modules.common.data_sources import get_experiment_data
+```
+
+Command-line usage also needs updating:
+```bash
+# Old command
+python datasets.py --download-all
+
+# New command
+python data_sources.py --download-all
+```
+
+**Reason for change**: Avoid naming conflict with HuggingFace `datasets` library. See [PR #20](https://github.com/joyehuang/minimind-notes/pull/20)
 
 ---
 
diff --git a/modules/README.md b/modules/README.md
index 152dc42..e889591 100644
--- a/modules/README.md
+++ b/modules/README.md
@@ -204,7 +204,34 @@ from modules.common.visualization import (
 )
 ```
 
-详细文档见各文件的 docstring。
+详细文档见各文件的 docstring 或 [`modules/common/README.md`](./common/README.md)。
+
+#### ⚠️ 迁移说明
+
+**2025-02**: `datasets.py` 已重命名为 `data_sources.py`
+
+如果你的代码使用了旧的导入方式：
+```python
+# 旧代码（会报错）
+from modules.common.datasets import get_experiment_data
+```
+
+请更新为：
+```python
+# 新代码
+from modules.common.data_sources import get_experiment_data
+```
+
+命令行使用也需要更新：
+```bash
+# 旧命令
+python datasets.py --download-all
+
+# 新命令
+python data_sources.py --download-all
+```
+
+**变更原因**: 避免与 HuggingFace `datasets` 库命名冲突，详见 [PR #20](https://github.com/joyehuang/minimind-notes/pull/20)
 
 ---
 
diff --git a/modules/common/README.md b/modules/common/README.md
new file mode 100644
index 0000000..d042d5c
--- /dev/null
+++ b/modules/common/README.md
@@ -0,0 +1,100 @@
+# 通用工具 (Common Utilities)
+
+本目录包含所有实验模块共享的工具代码。
+
+## 📦 可用工具
+
+### data_sources.py - 数据集管理
+
+提供统一的实验数据接口，支持：
+- TinyShakespeare（经典字符级数据，1MB）
+- TinyStories（现代英文，支持取子集）
+- 合成数据（用于可视化实验）
+
+**使用示例**:
+```python
+from modules.common.data_sources import get_experiment_data
+
+# 获取 TinyShakespeare
+text = get_experiment_data('shakespeare')
+
+# 获取 TinyStories 子集（10MB）
+texts = get_experiment_data('tinystories', size_mb=10)
+
+# 生成合成数据
+text = get_experiment_data('synthetic', size_mb=1)
+```
+
+**命令行使用**:
+```bash
+cd modules/common
+
+# 下载所有数据集
+python data_sources.py --download-all
+
+# 测试单个数据集
+python data_sources.py --dataset shakespeare
+```
+
+### experiment_base.py - 实验基类
+
+提供统一的实验框架，包括：
+- 自动设备检测（CPU/MPS/CUDA）
+- 结果保存（图表 + 指标）
+- 进度显示
+- 可复现性（固定随机种子）
+
+**使用示例**:
+```python
+from modules.common.experiment_base import Experiment
+
+class MyExperiment(Experiment):
+    def __init__(self):
+        super().__init__(
+            name="my_experiment",
+            output_dir="experiments/results"
+        )
+
+    def run(self):
+        # 你的实验代码
+        metrics = {'accuracy': 0.95}
+        self.print_metrics(metrics)
+        self.save_metrics(metrics)
+
+exp = MyExperiment()
+exp.run()
+```
+
+### visualization.py - 可视化工具
+
+提供常用的可视化函数（如果存在）。
+
+## ⚠️ 重要变更说明
+
+### datasets.py 已重命名为 data_sources.py (2025-02)
+
+**原因**: 避免与 HuggingFace `datasets` 库的命名冲突，该冲突会导致 TinyStories 数据集下载失败。
+
+**迁移方法**:
+
+| 旧代码 | 新代码 |
+|--------|--------|
+| `from modules.common.datasets import ...` | `from modules.common.data_sources import ...` |
+| `python datasets.py --download-all` | `python data_sources.py --download-all` |
+
+**注意**:
+- 为了帮助排查问题，我们保留了 `datasets.py` 文件，但它会抛出清晰的错误提示
+- 所有官方文档和实验代码已更新为新文件名
+- 如果你的代码使用了旧的导入方式，运行时会看到友好的错误提示
+
+**相关链接**:
+- Issue: https://github.com/joyehuang/minimind-notes/issues/19
+- PR: https://github.com/joyehuang/minimind-notes/pull/20
+
+## 📝 贡献指南
+
+在添加新工具时，请：
+1. 在本 README 中添加工具说明
+2. 在文件头部添加清晰的文档字符串
+3. 提供使用示例
+4. 确保工具是通用的，可以被多个模块复用
diff --git a/modules/common/datasets.py b/modules/common/datasets.py
new file mode 100644
index 0000000..3f19cb7
--- /dev/null
+++ b/modules/common/datasets.py
@@ -0,0 +1,28 @@
+"""
+⚠️ 此文件已废弃
+
+datasets.py 已重命名为 data_sources.py 以避免与 HuggingFace datasets 库的命名冲突。
+
+迁移方法：
+    旧代码:
+        from modules.common.datasets import get_experiment_data
+
+    新代码:
+        from modules.common.data_sources import get_experiment_data
+
+详见: https://github.com/joyehuang/minimind-notes/pull/20
+"""
+
+# 抛出清晰的错误信息
+raise ImportError(
+    "\n\n"
+    "=" * 70 + "\n"
+    "⚠️  datasets.py 已废弃\n"
+    "=" * 70 + "\n\n"
+    "此文件已重命名为 data_sources.py 以避免与 HuggingFace datasets 库冲突。\n\n"
+    "请更新你的导入语句：\n\n"
+    "  旧: from modules.common.datasets import get_experiment_data\n"
+    "  新: from modules.common.data_sources import get_experiment_data\n\n"
+    "详见: https://github.com/joyehuang/minimind-notes/pull/20\n"
+    "=" * 70 + "\n"
+)
diff --git a/modules/index.md b/modules/index.md
index 4d4a32a..75e38ba 100644
--- a/modules/index.md
+++ b/modules/index.md
@@ -204,7 +204,34 @@ from modules.common.visualization import (
 )
 ```
 
-详细文档见各文件的 docstring。
+详细文档见各文件的 docstring 或 [`modules/common/README.md`](./common/README.md)。
+
+#### ⚠️ 迁移说明
+
+**2025-02**: `datasets.py` 已重命名为 `data_sources.py`
+
+如果你的代码使用了旧的导入方式：
+```python
+# 旧代码（会报错）
+from modules.common.datasets import get_experiment_data
+```
+
+请更新为：
+```python
+# 新代码
+from modules.common.data_sources import get_experiment_data
+```
+
+命令行使用也需要更新：
+```bash
+# 旧命令
+python datasets.py --download-all
+
+# 新命令
+python data_sources.py --download-all
+```
+
+**变更原因**: 避免与 HuggingFace `datasets` 库命名冲突，详见 [PR #20](https://github.com/joyehuang/minimind-notes/pull/20)
 
 ---
 

From 8a3c45fa9ce16cb8e864cf97bafdd48c84c99ac0 Mon Sep 17 00:00:00 2001
From: De-Shiou Huang <huangdeshiou@gmail.com>
Date: Sat, 21 Feb 2026 15:32:01 +0800
Subject: [PATCH 3/5] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20Python=20=E7=89=88?=
 =?UTF-8?q?=E6=9C=AC=E8=A6=81=E6=B1=82=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

改进内容：
1. 在 modules/common/README.md 添加系统要求章节
   - 明确要求 Python 3.10+
   - 说明类型注解语法的兼容性限制
   - 列出必需的依赖库

2. 更新 data_sources.py 文档字符串
   - 添加重命名原因的详细说明
   - 添加 Python 版本要求
   - 添加依赖说明

3. 更新 datasets.py 废弃提示
   - 说明命名冲突的技术原因
   - 添加 Python 版本要求

4. 在主模块文档中添加系统要求
   - modules/README.md（中文）
   - modules/index.md（中文）
   - en/modules/index.md（英文）

解决审核建议：
- Python 兼容性问题通过文档明确说明解决
- 用户可以清楚了解最低版本要求

Co-Authored-By: Claude (pa/claude-sonnet-4-5-20250929) <noreply@anthropic.com>
---
 en/modules/index.md            | 17 +++++++++++++++++
 modules/README.md              | 17 +++++++++++++++++
 modules/common/README.md       | 18 ++++++++++++++++++
 modules/common/data_sources.py |  9 +++++++++
 modules/common/datasets.py     | 10 +++++++++-
 modules/index.md               | 17 +++++++++++++++++
 6 files changed, 87 insertions(+), 1 deletion(-)

diff --git a/en/modules/index.md b/en/modules/index.md
index a674c6d..37acd2e 100644
--- a/en/modules/index.md
+++ b/en/modules/index.md
@@ -58,6 +58,23 @@ _(Planned)_
 
 ---
 
+## 📋 System Requirements
+
+### Python Version
+- **Recommended**: Python 3.10+
+- **Minimum**: Python 3.10
+
+Some utility code uses Python 3.10+ union type syntax (e.g., `str | list`). Earlier versions will not work.
+
+### Dependencies
+```bash
+pip install torch requests datasets matplotlib numpy
+```
+
+See: [Environment Setup Guide](../docs/guide/environment-setup.md)
+
+---
+
 ## ⚡ Quick Start
 
 ### Environment setup
diff --git a/modules/README.md b/modules/README.md
index e889591..263811b 100644
--- a/modules/README.md
+++ b/modules/README.md
@@ -58,6 +58,23 @@ _（后续扩展）_
 
 ---
 
+## 📋 系统要求
+
+### Python 版本
+- **推荐**: Python 3.10+
+- **最低**: Python 3.10
+
+部分工具代码使用了 Python 3.10+ 的类型注解语法（如 `str | list`），低于此版本将无法运行。
+
+### 依赖安装
+```bash
+pip install torch requests datasets matplotlib numpy
+```
+
+详见：[环境配置指南](../docs/guide/environment-setup.md)
+
+---
+
 ## ⚡ 快速开始
 
 ### 准备环境
diff --git a/modules/common/README.md b/modules/common/README.md
index d042d5c..2f1a4b8 100644
--- a/modules/common/README.md
+++ b/modules/common/README.md
@@ -2,6 +2,24 @@
 
 本目录包含所有实验模块共享的工具代码。
 
+## 📋 系统要求
+
+### Python 版本
+- **推荐**: Python 3.10+
+- **最低**: Python 3.10
+
+**注意**: 代码使用了 Python 3.10+ 的类型注解语法（如 `str | list`），低于 3.10 的版本将无法运行。
+
+### 依赖库
+- `torch` - PyTorch 深度学习框架
+- `requests` - HTTP 请求（用于数据下载）
+- `datasets` - HuggingFace datasets 库（用于 TinyStories 下载）
+
+安装方法：
+```bash
+pip install torch requests datasets
+```
+
 ## 📦 可用工具
 
 ### data_sources.py - 数据集管理
diff --git a/modules/common/data_sources.py b/modules/common/data_sources.py
index 999fffe..573479d 100644
--- a/modules/common/data_sources.py
+++ b/modules/common/data_sources.py
@@ -6,6 +6,15 @@
 - TinyStories（现代英文，支持取子集）
 - 合成数据（用于可视化实验）
 
+注意：
+    - 此文件原名为 datasets.py，已重命名为 data_sources.py
+    - 重命名原因：避免与 HuggingFace datasets 库产生命名冲突
+    - 详见：https://github.com/joyehuang/minimind-notes/pull/20
+
+系统要求：
+    - Python 3.10+（使用了类型联合语法 str | list）
+    - 依赖：requests（TinyShakespeare）、datasets（TinyStories）
+
 使用示例：
     from modules.common.data_sources import get_experiment_data
 
diff --git a/modules/common/datasets.py b/modules/common/datasets.py
index 3f19cb7..12c48d1 100644
--- a/modules/common/datasets.py
+++ b/modules/common/datasets.py
@@ -1,7 +1,12 @@
 """
 ⚠️ 此文件已废弃
 
-datasets.py 已重命名为 data_sources.py 以避免与 HuggingFace datasets 库的命名冲突。
+datasets.py 已重命名为 data_sources.py
+
+重命名原因：
+    避免与 HuggingFace datasets 库的命名冲突。
+    当本地文件与第三方库同名时，Python 会优先导入本地文件，
+    导致 'from datasets import load_dataset' 失败。
 
 迁移方法：
     旧代码:
@@ -10,6 +15,9 @@
     新代码:
         from modules.common.data_sources import get_experiment_data
 
+Python 版本要求：
+    新文件需要 Python 3.10+（使用了类型联合语法 str | list）
+
 详见: https://github.com/joyehuang/minimind-notes/pull/20
 """
 
diff --git a/modules/index.md b/modules/index.md
index 75e38ba..76e1879 100644
--- a/modules/index.md
+++ b/modules/index.md
@@ -58,6 +58,23 @@ _（后续扩展）_
 
 ---
 
+## 📋 系统要求
+
+### Python 版本
+- **推荐**: Python 3.10+
+- **最低**: Python 3.10
+
+部分工具代码使用了 Python 3.10+ 的类型注解语法（如 `str | list`），低于此版本将无法运行。
+
+### 依赖安装
+```bash
+pip install torch requests datasets matplotlib numpy
+```
+
+详见：[环境配置指南](../docs/guide/environment-setup.md)
+
+---
+
 ## ⚡ 快速开始
 
 ### 准备环境

From f34cbc656e3cfb0833913409cf8d09a38c780a20 Mon Sep 17 00:00:00 2001
From: De-Shiou Huang <huangdeshiou@gmail.com>
Date: Sat, 21 Feb 2026 15:40:23 +0800
Subject: [PATCH 4/5] =?UTF-8?q?=E6=A0=B9=E6=8D=AE=E4=BB=A3=E7=A0=81?=
 =?UTF-8?q?=E5=AE=A1=E6=9F=A5=E5=BD=BB=E5=BA=95=E4=BF=AE=E5=A4=8D=E5=91=BD?=
 =?UTF-8?q?=E5=90=8D=E5=86=B2=E7=AA=81=E5=92=8C=E7=9B=B8=E5=85=B3=E9=97=AE?=
 =?UTF-8?q?=E9=A2=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

关键修复（解决最严重的问题）：
1. 删除 datasets.py stub 文件
   - 只要 datasets.py 存在就会干扰 Python 模块解析
   - Python 会优先找到本地 datasets.py 而非 PyPI 的 datasets 包
   - 即使文件只抛出错误也无济于事
   - 已完全删除该文件，通过 git 历史仍可追溯

代码质量改进：
2. 增强 data_sources.py 文档注释
   - 详细解释为什么不叫 datasets.py（Python 模块搜索优先级）
   - 防止未来维护者误将文件重命名回去

3. 移除模块级副作用
   - 将 DATA_DIR.mkdir() 从模块级移到实际需要时
   - 在 _get_shakespeare 和 _get_tinystories 保存缓存前创建目录
   - 避免模块导入时产生副作用

4. 修正浮点数文件名问题
   - 将 tinystories_{size_mb}mb.json 改为 tinystories_{int(size_mb)}mb.json
   - 避免浮点数文件名在不同平台的路径问题

文档改进：
5. 简化重复的迁移说明
   - modules/README.md 保留完整迁移指南
   - modules/index.md 和 en/modules/index.md 简化为引用
   - 避免多处维护相同内容导致内容漂移

解决的审查问题：
- ✅ Python 模块冲突彻底解决
- ✅ 代码注释清晰易懂
- ✅ 消除模块级副作用
- ✅ 文件名跨平台兼容
- ✅ 文档维护性提升

Co-Authored-By: Claude (pa/claude-sonnet-4-5-20250929) <noreply@anthropic.com>
---
 en/modules/index.md            | 25 ++---------------------
 modules/common/data_sources.py | 21 +++++++++++++-------
 modules/common/datasets.py     | 36 ----------------------------------
 modules/index.md               | 25 ++---------------------
 4 files changed, 18 insertions(+), 89 deletions(-)
 delete mode 100644 modules/common/datasets.py

diff --git a/en/modules/index.md b/en/modules/index.md
index 37acd2e..f418c93 100644
--- a/en/modules/index.md
+++ b/en/modules/index.md
@@ -225,30 +225,9 @@ See docstrings in each file or [`modules/common/README.md`](../modules/common/RE
 
 #### ⚠️ Migration Notice
 
-**2025-02**: `datasets.py` has been renamed to `data_sources.py`
+**2025-02**: `datasets.py` has been renamed to `data_sources.py` to avoid naming conflict with HuggingFace datasets library.
 
-If your code uses the old import:
-```python
-# Old code (will error)
-from modules.common.datasets import get_experiment_data
-```
-
-Please update to:
-```python
-# New code
-from modules.common.data_sources import get_experiment_data
-```
-
-Command-line usage also needs updating:
-```bash
-# Old command
-python datasets.py --download-all
-
-# New command
-python data_sources.py --download-all
-```
-
-**Reason for change**: Avoid naming conflict with HuggingFace `datasets` library. See [PR #20](https://github.com/joyehuang/minimind-notes/pull/20)
+For detailed migration guide, see [modules/common/README.md](../modules/common/README.md) or [PR #20](https://github.com/joyehuang/minimind-notes/pull/20).
 
 ---
 
diff --git a/modules/common/data_sources.py b/modules/common/data_sources.py
index 573479d..b068b2a 100644
--- a/modules/common/data_sources.py
+++ b/modules/common/data_sources.py
@@ -6,10 +6,15 @@
 - TinyStories（现代英文，支持取子集）
 - 合成数据（用于可视化实验）
 
-注意：
-    - 此文件原名为 datasets.py，已重命名为 data_sources.py
-    - 重命名原因：避免与 HuggingFace datasets 库产生命名冲突
-    - 详见：https://github.com/joyehuang/minimind-notes/pull/20
+⚠️ 文件命名说明：
+    此文件名为 data_sources.py 而非 datasets.py，原因是：
+
+    Python 模块搜索时，当前目录优先级高于 site-packages。
+    如果命名为 datasets.py，则 `from datasets import load_dataset`
+    会优先导入本地文件而非 HuggingFace datasets 库，导致 ImportError。
+
+    重命名为 data_sources.py 避免了此冲突。
+    详见：https://github.com/joyehuang/minimind-notes/pull/20
 
 系统要求：
     - Python 3.10+（使用了类型联合语法 str | list）
@@ -31,9 +36,8 @@
 from typing import List, Optional
 import json
 
-# 数据缓存目录
+# 数据缓存目录（按需创建，不在模块导入时创建）
 DATA_DIR = Path(__file__).parent / 'data'
-DATA_DIR.mkdir(exist_ok=True)
 
 
 def get_experiment_data(
@@ -88,6 +92,7 @@ def _get_shakespeare(cache: bool = True) -> str:
 
         # 保存缓存
         if cache:
+            DATA_DIR.mkdir(exist_ok=True)  # 确保目录存在
             cache_file.write_text(text, encoding='utf-8')
             print(f"✅ 已缓存到: {cache_file}")
 
@@ -108,7 +113,8 @@ def _get_tinystories(size_mb: float, cache: bool = True) -> List[str]:
         pip install datasets
     """
 
-    cache_file = DATA_DIR / f'tinystories_{size_mb}mb.json'
+    # 使用整数文件名避免浮点数路径问题
+    cache_file = DATA_DIR / f'tinystories_{int(size_mb)}mb.json'
 
     # 检查缓存
     if cache and cache_file.exists():
@@ -140,6 +146,7 @@ def _get_tinystories(size_mb: float, cache: bool = True) -> List[str]:
 
         # 保存缓存
         if cache:
+            DATA_DIR.mkdir(exist_ok=True)  # 确保目录存在
             with open(cache_file, 'w', encoding='utf-8') as f:
                 json.dump(texts, f, ensure_ascii=False)
             print(f"✅ 已缓存到: {cache_file}")
diff --git a/modules/common/datasets.py b/modules/common/datasets.py
deleted file mode 100644
index 12c48d1..0000000
--- a/modules/common/datasets.py
+++ /dev/null
@@ -1,36 +0,0 @@
-"""
-⚠️ 此文件已废弃
-
-datasets.py 已重命名为 data_sources.py
-
-重命名原因：
-    避免与 HuggingFace datasets 库的命名冲突。
-    当本地文件与第三方库同名时，Python 会优先导入本地文件，
-    导致 'from datasets import load_dataset' 失败。
-
-迁移方法：
-    旧代码:
-        from modules.common.datasets import get_experiment_data
-
-    新代码:
-        from modules.common.data_sources import get_experiment_data
-
-Python 版本要求：
-    新文件需要 Python 3.10+（使用了类型联合语法 str | list）
-
-详见: https://github.com/joyehuang/minimind-notes/pull/20
-"""
-
-# 抛出清晰的错误信息
-raise ImportError(
-    "\n\n"
-    "=" * 70 + "\n"
-    "⚠️  datasets.py 已废弃\n"
-    "=" * 70 + "\n\n"
-    "此文件已重命名为 data_sources.py 以避免与 HuggingFace datasets 库冲突。\n\n"
-    "请更新你的导入语句：\n\n"
-    "  旧: from modules.common.datasets import get_experiment_data\n"
-    "  新: from modules.common.data_sources import get_experiment_data\n\n"
-    "详见: https://github.com/joyehuang/minimind-notes/pull/20\n"
-    "=" * 70 + "\n"
-)
diff --git a/modules/index.md b/modules/index.md
index 76e1879..282ce57 100644
--- a/modules/index.md
+++ b/modules/index.md
@@ -225,30 +225,9 @@ from modules.common.visualization import (
 
 #### ⚠️ 迁移说明
 
-**2025-02**: `datasets.py` 已重命名为 `data_sources.py`
+**2025-02**: `datasets.py` 已重命名为 `data_sources.py`，避免与 HuggingFace datasets 库命名冲突。
 
-如果你的代码使用了旧的导入方式：
-```python
-# 旧代码（会报错）
-from modules.common.datasets import get_experiment_data
-```
-
-请更新为：
-```python
-# 新代码
-from modules.common.data_sources import get_experiment_data
-```
-
-命令行使用也需要更新：
-```bash
-# 旧命令
-python datasets.py --download-all
-
-# 新命令
-python data_sources.py --download-all
-```
-
-**变更原因**: 避免与 HuggingFace `datasets` 库命名冲突，详见 [PR #20](https://github.com/joyehuang/minimind-notes/pull/20)
+详细的迁移指南请参考 [modules/README.md](./README.md) 或 [modules/common/README.md](./common/README.md)。
 
 ---
 

From 030bfe423e64198dfb59ab605f2f002bdfcc2ba2 Mon Sep 17 00:00:00 2001
From: De-Shiou Huang <huangdeshiou@gmail.com>
Date: Sat, 21 Feb 2026 15:53:12 +0800
Subject: [PATCH 5/5] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E4=B8=8E=E5=AE=9E=E7=8E=B0=E4=B8=8D=E7=AC=A6=E7=AD=89=E5=AE=A1?=
 =?UTF-8?q?=E6=A0=B8=E9=97=AE=E9=A2=98=EF=BC=88=E6=9C=80=E7=BB=88=E7=89=88?=
 =?UTF-8?q?=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

关键问题修复：
1. 修正 README 描述与实际不符的问题
   - 之前：说"保留了 datasets.py 文件"但实际已删除
   - 现在：明确说明"datasets.py 文件已完全删除"
   - 添加：解释 Python 模块搜索优先级导致的冲突
   - 添加：说明如何通过 git 历史追溯旧文件

2. 修复 int() 截断导致的缓存混用问题
   - 问题：size_mb=10.5 会生成 tinystories_10mb.json，与 size_mb=10 冲突
   - 方案：将所有 size_mb 参数类型从 float 改为 int
   - 影响：get_experiment_data、_get_tinystories、_generate_synthetic
   - 好处：类型系统强制整数，避免静默截断

3. 修正日期错误
   - 所有文档中的 "2025-02" 改为 "2026-02"
   - 影响文件：modules/README.md, modules/index.md, en/modules/index.md

文档改进：
4. 简化 PR URL 引用
   - modules/README.md 中将硬编码的 GitHub PR 链接改为内部文档引用
   - 引用目标：./common/README.md#重要变更说明

5. 改进 visualization.py 描述
   - 明确说明"此文件目前尚未创建，计划在后续模块中添加"
   - 避免"如果存在"等模糊表述

6. 简化系统要求描述
   - 合并重复的"推荐"和"最低"版本要求
   - 统一为"要求: Python 3.10+"

解决的审核问题：
- ✅ README 描述与实现一致性
- ✅ 类型安全（避免浮点数截断）
- ✅ 日期准确性
- ✅ 文档自包含性（减少外部链接依赖）
- ✅ 描述清晰度

Co-Authored-By: Claude (pa/claude-sonnet-4-5-20250929) <noreply@anthropic.com>
---
 en/modules/index.md            |  2 +-
 modules/README.md              |  4 ++--
 modules/common/README.md       | 24 ++++++++++++++----------
 modules/common/data_sources.py | 20 +++++++++++++-------
 modules/index.md               |  2 +-
 5 files changed, 31 insertions(+), 21 deletions(-)

diff --git a/en/modules/index.md b/en/modules/index.md
index f418c93..9a2d64f 100644
--- a/en/modules/index.md
+++ b/en/modules/index.md
@@ -225,7 +225,7 @@ See docstrings in each file or [`modules/common/README.md`](../modules/common/RE
 
 #### ⚠️ Migration Notice
 
-**2025-02**: `datasets.py` has been renamed to `data_sources.py` to avoid naming conflict with HuggingFace datasets library.
+**2026-02**: `datasets.py` has been renamed to `data_sources.py` to avoid naming conflict with HuggingFace datasets library.
 
 For detailed migration guide, see [modules/common/README.md](../modules/common/README.md) or [PR #20](https://github.com/joyehuang/minimind-notes/pull/20).
 
diff --git a/modules/README.md b/modules/README.md
index 263811b..4271b89 100644
--- a/modules/README.md
+++ b/modules/README.md
@@ -225,7 +225,7 @@ from modules.common.visualization import (
 
 #### ⚠️ 迁移说明
 
-**2025-02**: `datasets.py` 已重命名为 `data_sources.py`
+**2026-02**: `datasets.py` 已重命名为 `data_sources.py`
 
 如果你的代码使用了旧的导入方式：
 ```python
@@ -248,7 +248,7 @@ python datasets.py --download-all
 python data_sources.py --download-all
 ```
 
-**变更原因**: 避免与 HuggingFace `datasets` 库命名冲突，详见 [PR #20](https://github.com/joyehuang/minimind-notes/pull/20)
+**变更原因**: 避免与 HuggingFace `datasets` 库命名冲突，详见 [通用工具文档](./common/README.md#重要变更说明)
 
 ---
 
diff --git a/modules/common/README.md b/modules/common/README.md
index 2f1a4b8..ae3ce70 100644
--- a/modules/common/README.md
+++ b/modules/common/README.md
@@ -5,10 +5,9 @@
 ## 📋 系统要求
 
 ### Python 版本
-- **推荐**: Python 3.10+
-- **最低**: Python 3.10
+- **要求**: Python 3.10+
 
-**注意**: 代码使用了 Python 3.10+ 的类型注解语法（如 `str | list`），低于 3.10 的版本将无法运行。
+**注意**: 代码使用了 Python 3.10+ 的类型联合语法（`str | list`），低于此版本将无法运行。
 
 ### 依赖库
 - `torch` - PyTorch 深度学习框架
@@ -85,14 +84,18 @@ exp.run()
 
 ### visualization.py - 可视化工具
 
-提供常用的可视化函数（如果存在）。
+提供常用的可视化函数。
+
+**注意**: 此文件目前尚未创建，计划在后续模块中添加。
 
 ## ⚠️ 重要变更说明
 
-### datasets.py 已重命名为 data_sources.py (2025-02)
+### datasets.py 已重命名为 data_sources.py (2026-02)
 
 **原因**: 避免与 HuggingFace `datasets` 库的命名冲突，该冲突会导致 TinyStories 数据集下载失败。
 
+**背景**: Python 模块搜索时优先查找当前目录，如果存在本地 `datasets.py`，会导致 `from datasets import load_dataset` 错误导入本地文件而非 HuggingFace 库。
+
 **迁移方法**:
 
 | 旧代码 | 新代码 |
@@ -101,13 +104,14 @@ exp.run()
 | `python datasets.py --download-all` | `python data_sources.py --download-all` |
 
 **注意**:
-- 为了帮助排查问题，我们保留了 `datasets.py` 文件，但它会抛出清晰的错误提示
+- `datasets.py` 文件已完全删除（不再存在于仓库中）
+- 使用旧导入方式会收到标准的 `ModuleNotFoundError`
 - 所有官方文档和实验代码已更新为新文件名
-- 如果你的代码使用了旧的导入方式，运行时会看到友好的错误提示
+- Git 历史中仍可通过 `git log -- modules/common/datasets.py` 追溯旧文件
 
-**相关链接**:
-- Issue: https://github.com/joyehuang/minimind-notes/issues/19
-- PR: https://github.com/joyehuang/minimind-notes/pull/20
+**相关信息**:
+- 问题追踪: GitHub Issue #19
+- 详细讨论: GitHub Pull Request #20
 
 ## 📝 贡献指南
 
diff --git a/modules/common/data_sources.py b/modules/common/data_sources.py
index b068b2a..7d41840 100644
--- a/modules/common/data_sources.py
+++ b/modules/common/data_sources.py
@@ -42,7 +42,7 @@
 
 def get_experiment_data(
     dataset: str = 'shakespeare',
-    size_mb: Optional[float] = None,
+    size_mb: Optional[int] = None,
     cache: bool = True
 ) -> str | List[str]:
     """
@@ -51,9 +51,9 @@ def get_experiment_data(
     Args:
         dataset: 数据集名称
             - 'shakespeare': TinyShakespeare (1MB)
-            - 'tinystories': TinyStories (可指定大小)
+            - 'tinystories': TinyStories (可指定大小，单位: MB，必须为整数)
             - 'synthetic': 合成随机数据
-        size_mb: 数据大小限制（仅对 tinystories 有效）
+        size_mb: 数据大小限制（仅对 tinystories 和 synthetic 有效，单位: MB）
         cache: 是否使用缓存
 
     Returns:
@@ -105,16 +105,19 @@ def _get_shakespeare(cache: bool = True) -> str:
         raise
 
 
-def _get_tinystories(size_mb: float, cache: bool = True) -> List[str]:
+def _get_tinystories(size_mb: int, cache: bool = True) -> List[str]:
     """
     获取 TinyStories 子集
 
+    Args:
+        size_mb: 数据大小（MB），必须为整数
+        cache: 是否使用缓存
+
     注意：需要安装 datasets 库
         pip install datasets
     """
 
-    # 使用整数文件名避免浮点数路径问题
-    cache_file = DATA_DIR / f'tinystories_{int(size_mb)}mb.json'
+    cache_file = DATA_DIR / f'tinystories_{size_mb}mb.json'
 
     # 检查缓存
     if cache and cache_file.exists():
@@ -162,10 +165,13 @@ def _get_tinystories(size_mb: float, cache: bool = True) -> List[str]:
         raise
 
 
-def _generate_synthetic(size_mb: float) -> str:
+def _generate_synthetic(size_mb: int) -> str:
     """
     生成合成数据（用于快速测试）
 
+    Args:
+        size_mb: 数据大小（MB），必须为整数
+
     生成简单的重复模式，用于验证模型是否能学习
     """
 
diff --git a/modules/index.md b/modules/index.md
index 282ce57..99c5b7a 100644
--- a/modules/index.md
+++ b/modules/index.md
@@ -225,7 +225,7 @@ from modules.common.visualization import (
 
 #### ⚠️ 迁移说明
 
-**2025-02**: `datasets.py` 已重命名为 `data_sources.py`，避免与 HuggingFace datasets 库命名冲突。
+**2026-02**: `datasets.py` 已重命名为 `data_sources.py`，避免与 HuggingFace datasets 库命名冲突。
 
 详细的迁移指南请参考 [modules/README.md](./README.md) 或 [modules/common/README.md](./common/README.md)。