学习路径

可以把这套文档当作一门紧凑的技术课程。它并不是线性手册，而是按照不同读者目标组织出来的多条入口路径。

先选择你的路线

路线	适合谁	主要收获
高层速览	需要快速判断质量的评审者	理解项目为何存在，以及架构是否自洽
架构研读	资深开发者与面试官	追踪运行时边界、深模块与离线策略
贡献者入门	准备修改代码或文档的工程师	了解行为归属、规范位置与验证流程
研究背景	关心训练模式与先例的读者	看到 Mind Gym 如何把产品选择连接到更广泛的思想来源

推荐课程结构

第一阶段：建立方向感

建议按以下顺序阅读：

1. 项目论纲
2. 系统总览
3. 本页

目标：先理解产品、约束与系统形状，再进入文件级细节。

第二阶段：理解运行时

建议按以下顺序阅读：

1. 状态架构
2. PWA 与离线策略
3. 模块总览

目标：弄清楚谁负责持久化、谁负责会话状态、哪些复杂度被有意集中到了深模块中。

第三阶段：为贡献做准备

建议按以下顺序阅读：

1. 开始使用
2. README.md
3. openspec/specs/
4. openspec/rfc/

目标：不仅理解代码，也理解仓库的决策历史与验证流程。

第四阶段：补足语境与细节

建议按以下顺序阅读：

1. 参考与相关工作
2. 按兴趣选择对应源码文件

目标：把实现选择放回更大的背景中理解，同时避免对产品能力做超出证据的夸大。

按时间预算阅读

你只有...	建议阅读
10 分钟	论纲 → 系统总览 → 模块总览
30 分钟	论纲 → 状态架构 → 离线策略 → 开始使用
60 分钟	论纲 → 全部架构页 → 模块总览 → OpenSpec 规范
半天	完整浏览站点，然后直接研读 app.js、深模块与 sw.js

阅读时应该观察什么

产品读者应追问

• 每种模式是否都在强化同一个产品故事，还是像后加功能？
• 本地优先进度究竟是产品价值，还是只是技术省事？
• 哪些体验明显是为重复使用设计，而不是一次性新鲜感？

架构读者应追问

• 状态归属是否清晰，还是在层之间渗漏？
• 那些被称为“深模块”的文件，接口是否真的足够小、内部行为是否真的足够丰富？
• 离线策略是否真正支撑了“短时、可靠训练”的产品主张？

贡献者应追问

• 我要改的行为到底归哪个文件负责？
• 哪个 spec 或 RFC 约束了这次修改？
• 什么样的最小验证闭环足以证明我没有破坏文档站或应用本身？

实践练习

练习 1

打开 src/game-manager.js，用一句话写出它的公开接口。如果一句话都写不清，说明接口可能还不够小。

练习 2

对比 src/storage.js 与 src/settings-manager.js，分辨底层持久化在何处结束、上层策略在何处开始。

练习 3

阅读 sw.js，标记哪些资源被预缓存、哪些属于运行时缓存，以及哪些仍然依赖首次联网访问。

贡献者的阅读纪律

当你准备修改行为时，建议遵循下面的循环：

1. 先读对应的文档页。
2. 再读匹配的源码文件。
3. 然后交叉核对 OpenSpec。
4. 做最小但完整的修改。
5. 运行对应的验证命令。
6. 若架构叙事发生变化，同步更新文档。

完成学习路径的标准

当你无需猜测就能回答以下问题时，就算完成了这条学习路径：

• 为什么 Mind Gym 要采用三层状态模型？
• 哪些模块属于深模块，为什么？
• 哪些能力能离线保留，哪些不能？
• 当贡献者要改玩法、状态或文档时，应从哪里开始？