补全环境配置说明：添加 venv 创建、依赖安装和 Python 版本要求

[joyehuang]

修复 #15：所有文档的环境配置部分缺少虚拟环境创建步骤、
pip install 依赖安装步骤和 Python 版本要求说明。

在 README.md、README_en.md、ROADMAP.md、docs/guide/quick-start.md、 docs/index.md、modules/README.md 六个文件中统一补全：

• python3 -m venv venv 虚拟环境创建步骤
• pip install -r requirements.txt 依赖安装步骤
• Python 3.9+ 版本要求说明
• Windows 激活命令提示
• CPU/GPU 使用说明（README 中）

https://claude.ai/code/session_01GB4mLX8YhKyf3Q5dHdhTtW

📝 变更描述

清晰简洁地描述这个 PR 做了什么。

🎯 变更类型

请勾选适用的选项：

• 🐛 Bug 修复
• ✨ 新功能
• 📖 文档更新
• 🔬 新实验
• 🎨 代码风格/格式化（不影响功能）
• ♻️ 代码重构
• ⚡ 性能优化
• ✅ 测试相关
• 🔧 构建/工具相关
• 🌍 翻译

📚 相关模块

这个 PR 涉及哪些模块？

• 01-normalization
• 02-position-encoding
• 03-attention
• 04-feedforward
• 02-architecture
• 文档/网站
• 通用工具
• 其他: ___________

🔗 相关 Issue

关联的 Issue（如果有）：

• Closes #
• Related to #

✅ 检查清单

在提交 PR 之前，请确认：

代码质量

• 代码遵循项目的代码风格
• 代码有充分的中文注释
• 没有引入新的 linter 错误
• 代码可以独立运行（如果是实验代码）

实验相关（如果适用）

• 实验可以独立运行
• 结果可复现（固定了随机种子）
• 添加了必要的可视化
• 更新了相关文档

文档相关（如果适用）

• 更新了相关 README
• 更新了 teaching.md（如果适用）
• 添加了必要的代码注释
• 检查了拼写和语法

测试

• 我已经测试了这些更改
• 实验可以正常运行
• 没有破坏现有功能

📸 截图/结果

如果适用，请添加截图或实验结果：

🔍 测试说明

如何测试这些更改：
1.
2.
3.

📝 额外说明

任何其他需要说明的信息。

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
minimind-notes	Ready	Preview, Comment	Feb 16, 2026 7:06am

[claude]

PR Review: 补全环境配置说明 (#18)

总体来说，这个 PR 解决了一个真实存在的问题（issue #15），变更内容清晰、一致，整体质量良好。以下是详细反馈：

---

✅ 优点

1. 一致性好：六个文件的修改保持了统一的格式和内容，没有出现遗漏或不一致的情况。
2. 信息完整：新增了 venv 创建、pip 安装、Python 版本要求、Windows 激活命令，覆盖了主流使用场景。
3. CPU/GPU 提示有价值：README.md 和 README_en.md 中新增的提示说明清楚了学习阶段无需 GPU，降低了新用户的门槛。
4. 步骤编号更新正确：所有受影响的步骤编号都已更新，没有出现跳号或重号。

---

🔍 问题与建议

1. docs/index.md 的 code-group 标签名称不一致

- ```bash [1. 克隆仓库]
+ ```bash [1. 环境准备]

将 git clone、venv 创建和 pip 安装合并到一个名为「1. 环境准备」的 tab 中，但 tab 标签描述与内容有些宽泛。更重要的是：同一文件中如果其他 tab 标签（如「2. 运行第一个实验」）仍按原有命名，整体 code-group 的步骤感会更连贯。这个问题影响不大，但可以考虑在后续优化。

2. docs/index.md 中 venv 激活命令缺少 Windows 提示

README.md、README_en.md、ROADMAP.md、docs/guide/quick-start.md、modules/README.md 中都添加了 Windows 激活命令的注释，但 docs/index.md 的修改中缺少：

source venv/bin/activate
# Windows: venv\Scripts\activate  ← 这一行在 docs/index.md 中缺失

这是六个文件之间的唯一不一致之处，建议补全。

3. requirements.txt 是否为 pip 可用格式？

PR 中引用了 pip install -r requirements.txt，但仓库根目录的 requirements.txt 文件未在此 PR 中被查阅或验证。建议确认该文件是否为标准 pip 格式（而非 conda 环境文件或其他格式），以确保命令对新用户有效。

4. PR 描述模板未填写完整

PR 描述的检查清单（变更类型、相关模块等复选框）均未勾选，Closes # 也未关联 issue（应为 Closes #15）。虽然不影响代码质量，但完整的 PR 描述有助于维护项目历史。

---

📋 总结

维度	评估
问题解决程度	✅ 有效修复了 issue #15
跨文件一致性	⚠️ docs/index.md 缺少 Windows 注释
内容准确性	✅ 步骤正确，信息有用
PR 规范性	⚠️ 描述模板未完整填写

建议：补上 docs/index.md 中缺失的 Windows 激活命令注释，并在 PR 描述中关联 Closes #15，之后即可合并。

[claude]

PR Review: 补全环境配置说明

总体来说，这是一个有价值的文档改进，解决了 issue #15 中提出的环境配置说明不清晰的问题。以下是具体反馈：

---

✅ 优点

1. 统一性好：六个文件的修改保持了一致的风格和内容，不同文档之间不会给用户造成混乱。
2. 步骤完整：添加了 python3 -m venv venv、pip install -r requirements.txt 和 Python 版本要求，解决了原来假设用户已有虚拟环境的问题。
3. 跨平台考虑：添加了 Windows 激活命令的提示，对 Windows 用户友好。
4. CPU/GPU 说明：在 README 中添加的提示说明学习阶段只需 CPU，降低了新用户的心理门槛。

---

⚠️ 潜在问题

1. requirements.txt 是否存在？（关键问题）

文档中新增的 pip install -r requirements.txt 步骤前提是仓库根目录下存在 requirements.txt。请确认：

• 该文件是否已存在于仓库中？
• 如果不存在，这个步骤会直接报错，对新用户体验反而更差。

建议：在合并前验证 requirements.txt 的存在性和内容是否覆盖所有实验所需依赖。

2. python3 命令的跨平台一致性

使用 python3 在 Windows 上可能不可用（部分 Windows 环境下只有 python）。考虑到已经提到了 Windows 用户，可以补充说明：

# Windows 用户可能需要使用 python 而非 python3
python -m venv venv

或者在提示中注明 Windows 用户应将 python3 替换为 python。

3. docs/index.md 的代码块标题语义变化

-```bash [1. 克隆仓库]
+```bash [1. 环境准备]

将标签从"克隆仓库"改为"环境准备"语义上更准确，但这个代码块现在同时包含了 clone、venv 创建和依赖安装三个操作，相比其他文件（分步骤编号）的处理方式更为紧凑。如果用户只需要激活已有环境，这种合并方式可能略显不便，但对于首次用户来说是合理的取舍。

4. PR 模板的检查清单未填写

PR 描述中的检查清单全部未勾选（包括"我已经测试了这些更改"）。虽然这是纯文档修改，风险较低，但建议至少确认：

• 已验证 requirements.txt 存在且可用
• 已在 Linux/macOS 上实际执行过这些命令

5. PR 描述中的模板占位符未清理

PR 描述中仍有大量模板占位符（如"清晰简洁地描述这个 PR 做了什么"、"如何测试这些更改：1. 2. 3."）和未填写的部分。建议清理 PR 描述，只保留实际相关内容。

---

💡 小建议

• modules/README.md 中新增的参考链接 > 详细环境配置说明请参考 [README.md](../README.md#-快速开始) 是个好做法，减少重复内容的维护负担。
• 考虑添加 Python 版本验证步骤：python3 --version 或说明如何安装指定版本，对于版本不满足要求的用户更友好。

---

结论

这个 PR 方向正确，解决了真实的用户痛点。核心问题是需要确认 requirements.txt 文件的存在性，这是合并前必须验证的。其他问题均属于可选优化。

如果 requirements.txt 已存在且内容正确，建议在确认后即可合并。

[claude]

PR Review: 补全环境配置说明

This PR addresses a real usability gap — the previous docs assumed users already had a venv set up, which would confuse anyone running the repo for the first time. The intent is correct and the changes are consistent across files.

What Works Well

• The fix is applied consistently across all 6 affected files (README.md, README_en.md, ROADMAP.md, docs/guide/quick-start.md, docs/index.md, modules/README.md).
• The CPU/GPU clarification tip added to README.md and README_en.md is genuinely useful for learners who may not know a GPU is only needed for full training.
• The cross-reference added in modules/README.md pointing back to README.md avoids duplication and is a good pattern.

Issues to Address

1. requirements.txt has a duplicate entry

jsonlines==4.0.0 appears on both line 9 and line 23. This is a pre-existing issue but is now more visible since this PR directs users to run pip install -r requirements.txt. Worth fixing in a follow-up (or here).

2. requirements.txt dependencies are heavyweight for the learning experiments

The file includes torch==2.6.0, torchvision, transformers, trl, wandb, swanlab, and other large packages. The PR tip says "experiments only require CPU, no GPU needed" — but pip install -r requirements.txt will still download ~2 GB of packages. Consider either:

• Splitting into requirements-experiments.txt (lightweight) and requirements-full.txt (training), or
• Adding a note in the docs that installation may take a while due to PyTorch.

Without this context, a new learner might wait a long time and think something is wrong.

3. Windows activation comment is a comment, not a code block

In several files the Windows command appears as an inline comment:

source venv/bin/activate      # Linux / macOS
# Windows: venv\Scripts\activate

This means Windows users can't copy-paste it directly from most rendered Markdown (GitHub renders # lines as comments, not commands). The docs/index.md section already uses a tabbed code group — consider using the same pattern in README/ROADMAP to give Windows users their own dedicated tab or a proper callout block.

4. PR checklist was not filled out

The standard PR template checkboxes are all unchecked, including the "文档/网站" module box which clearly applies here. Minor, but completing the checklist helps reviewers confirm the author has self-reviewed.

5. Python version recommendation could be more precise

Python 3.9+，推荐 3.10/3.11 — given that torch==2.6.0 supports Python 3.9–3.12, this is accurate. However, the English README says "Python 3.9+" without the recommendation note. Consider keeping the two READMEs in sync on this point.

Summary

The core fix is correct and needed. Before merging, I'd suggest:

1. Adding a brief note about installation size/time alongside the pip install step.
2. Improving the Windows activation command presentation (not buried in a comment).
3. Fixing the duplicate jsonlines entry in requirements.txt (even as a separate small PR).

Overall this is a solid documentation improvement — the issues above are refinements, not blockers.