# Easy Study 项目文档总览报告 > 生成时间：2026-07-03 > 目标：把当前项目文档按 **M1 -> M2 -> M3 -> M4** 的里程碑顺序重新整理，帮助快速理解项目进程、当前能力与后续接续点。 ## 1. 项目总览 ### 1.1 项目目标一句话 Easy Study 的当前主线目标，是为 6 岁儿童构建一套以 **自然拼读 + 牛津树绘本阅读** 为核心的英语学习闭环系统，让孩子能独立阅读、点词学拼读，且让家长可查看学习记录与进度。 ### 1.2 当前总体进度 - **M1：已完成** - 单本书完美闭环 - **M2：已完成** - 扩到 5-10 本 + OCR 管线统一 - **M3：已完成** - 拼读学习模块接入主应用 - **M4：未启动 / 未完成** - 家长评估与聚合能力尚未开始正式执行 ### 1.3 当前代码 / 产品能力概览 当前项目已经从早期的纯前端小游戏，演进为一套前后端分离的学习系统：后端使用 FastAPI 提供绘本、单词、拼读与阅读记录接口；前端已经具备书架、绘本阅读器、点词看拼读、音频播放、阅读记录上报、家长端阅读记录展示，以及 Learn / Quiz 的最小拼读学习闭环；数据层以 `docs/data/` 下的 JSON 为主，OCR 与结构化产物已经支撑 stage-03 的 10 本可读绘本。需要特别注意的是，**当前实现以 JSON 文件为准，并未引入数据库**，这与更早的设计愿景文档存在差异。 ### 1.4 读文档前需要知道的三个事实 1. **最重要的时间顺序是：M1 -> M2 -> M3 -> M4，不是 stage1 -> stage5。** `stage1/2/3/5` 是执行流程分层，M1/M2/M3/M4 才是产品里程碑。 2. **`2026-05-23-phonics-trainer-design.md` 是愿景源头，不是当前实现真相。** 它对产品目标、课程/进度模型很重要，但其中的 SQLite、PWA、Docker 等属于早期设计设想，和当前代码并不完全一致。 3. **当前未看到独立的 Stage 4 测试文档。** M1 的闭环主要通过 `stage3-review.md` 的实跑验证，以及 `stage5-e2e-review.md` 的端到端验收完成，因此如果你追项目进度，重点看 Stage 3 和 Stage 5 即可。 ## 2. 推荐阅读顺序 如果你想用最短路径快速总览整个项目，建议按下面顺序阅读： 1. **项目背景** 先看 `项目介绍.md`，理解这个仓库从“早期静态小游戏”演进到“前后端分离学习系统”的全貌。 2. **仓库入口说明** 再看 `README.md` 与 `CLAUDE.md`，了解当前技术栈、目录结构、数据位置、前后端运行方式。 3. **最早的产品设计源头** 看 `docs/specs/2026-05-23-phonics-trainer-design.md`，把握项目最初为什么要做、想做成什么样。 读取时要带着一个前提：**它更像“产品愿景与理想架构”，不是当前实现状态。** 4. **当前这轮执行的总方案** 看 `docs/specs/2026-07-02-multi-agent-execution-plan.md`，理解本轮是如何把目标拆成 M1-M4，并通过 Stage 1-5 的执行工作流推进的。 5. **先看全过程总账** 快速浏览 `docs/specs/agent-run/runlog.md`，这是最好的时间线索引，能一眼看出 M1、M2、M3 是如何完成的。 6. **回看 M1：单本书闭环是怎么跑通的** 推荐顺序： `stage1-plan.md` -> `stage2-feature-list.md` -> `stage2-review.md` -> `stage3-review.md` -> `stage5-e2e-review.md` -> `milestone-M1-done.md` 7. **再看 M2：如何从 1 本扩到 10 本** 推荐顺序： `m2-acceptance.md` -> `dev-ocr-m2-report.md` -> `dev-phonics-m2-report.md` -> `m2-review.md` -> `milestone-M2-done.md` 8. **接着看 M3：如何把拼读学习接进主应用** 推荐顺序： `m3-acceptance.md` -> `dev-fe-m3-report.md` -> `dev-phonics-m3-report.md` -> `m3-review.md` -> `milestone-M3-done.md` 9. **最后看专项问题修复** `docs/specs/2026-07-03-ocr-cross-page-continuation-fix.md` 这篇适合在你理解了 M2 的 OCR/结构化能力之后再看，它解释了为什么某些书会“缺页”，以及如何修复。 10. **准备推进 M4 时再回头看设计与里程碑结论** 重点回看： `2026-07-02-multi-agent-execution-plan.md`、`stage1-plan.md`、`design-api.md`、`design-frontend.md`、`milestone-M3-done.md` ## 3. 按阶段归档文档清单 ## M1：单本书完美闭环 - **阶段目标**：让 1 本目标绘本（`stage-03/AtTheSeaside`）完整跑通“选书 -> 阅读 -> 点词拼读 -> 读完上报 -> 家长端可见”闭环。 - **当前状态**：**已完成** - **阶段文档概况**：主文档 19 篇，覆盖规划、验收标准、详细设计、开发实现、端到端验收与里程碑结论。 | 文档名 | 标题 / 主题 | 归类 | 核心内容摘要 | 建议阅读时机 | |---|---|---|---|---| | `docs/specs/agent-run/stage1-plan.md` | M1-M4 项目整体方案 | 方案 | 明确项目现状、四个里程碑、模块边界、关键风险与 4 周推进路径，是本轮所有执行文档的总入口。 | **开始前必看** | | `docs/specs/agent-run/stage1-acceptance.md` | Stage 1 方案规划验收标准 | 验收标准 | 定义一份“合格总方案”必须覆盖哪些事实、里程碑、风险与约束。 | 看完 `stage1-plan.md` 后看 | | `docs/specs/agent-run/stage1-review.md` | Stage 1 方案评审结论 | 评审结论 | 逐条确认 `stage1-plan.md` 已满足验收条件，也指出 JSON 存储与旧设计文档中的数据库设想存在差异。 | 想确认 Stage 1 是否通过时看 | | `docs/specs/agent-run/stage2-feature-list.md` | M1 优先功能清单 | 规划 | 把 M1 的关键需求拆成 F1-F8，例如书架、去硬编码、点词拼读、阅读记录、家长端展示等。 | 从总方案进入详细设计前看 | | `docs/specs/agent-run/stage2-acceptance.md` | Stage 2 详细设计验收标准 | 验收标准 | 规定 4 份设计文档必须包含的数据结构、接口契约、依赖边界与一致性检查。 | 看设计文档前先看 | | `docs/specs/agent-run/design-api.md` | 后端 API 详细设计 | 详细设计 | 重点补上 M1 缺失的阅读记录接口，并要求 `audio_url` 由后端显式返回，避免前端猜路径。 | 关注后端、记录能力时看 | | `docs/specs/agent-run/design-frontend.md` | 前端书架 / 阅读器详细设计 | 详细设计 | 说明如何把首页改为书架、如何用路由参数去掉 `BookReader` 的硬编码，以及如何上报阅读记录。 | 关注前端主链路时看 | | `docs/specs/agent-run/design-ocr.md` | OCR 管线统一设计 | 详细设计 | 虽以 M2 为主，但在 M1 中用于界定 OCR 与 structured 数据的来源、约束和后续统一方向。 | 想理解数据从哪里来时看 | | `docs/specs/agent-run/design-phonics.md` | 拼读数据补齐设计 | 详细设计 | 分析目标书缺拼读词的真实情况，区分 OCR 噪音与真实缺词，并给出补齐策略。 | 关注点词拼读为什么能跑通时看 | | `docs/specs/agent-run/stage2-review.md` | Stage 2 设计评审结论 | 评审结论 | 统一确认四份设计在 API、前端、OCR、拼读之间的契约一致，没有引入数据库等偏差。 | 想快速确认设计是否成熟时看 | | `docs/specs/agent-run/stage3-acceptance.md` | Stage 3 开发验收标准 | 验收标准 | 定义开发阶段必须达到的后端、前端、拼读、OCR 和端到端闭环标准。 | 看开发报告前看 | | `docs/specs/agent-run/dev-api-report.md` | 阅读记录接口 + `audio_url` 实现报告 | 开发报告 | 记录新增 `records.py`、`RECORDS_DIR`、`book_audio_url()` 等改动，并实测写入/读回闭环。 | 关注后端改了什么时看 | | `docs/specs/agent-run/dev-fe-report.md` | 书架 / 去硬编码 / 上报 / Dashboard 实现报告 | 开发报告 | 记录首页重写为真实书架、`BookReader` 动态选书、读完上报、家长记录展示等改动。 | 关注前端主链路落地时看 | | `docs/specs/agent-run/dev-ocr-report.md` | M1 中 OCR 最小范围说明 | 开发报告 | 明确 M1 不重构 OCR，而是保证现有数据可用，把统一入口留到 M2 去做。 | 想知道 M1 为何没动 OCR 时看 | | `docs/specs/agent-run/dev-phonics-report.md` | 目标书拼读缺口补齐报告 | 开发报告 | 通过 `phonics-missing.json` 与 `patch_phonics.py` 补齐真实缺词，并把 structured 数据重新关联。 | 关注拼读数据怎么补时看 | | `docs/specs/agent-run/stage3-review.md` | Stage 3 开发评审结论 | 评审结论 | 实际启动后端、验证 API、构建前端，确认 M1 的开发实现已经达到闭环标准。 | **M1 核心必看** | | `docs/specs/agent-run/stage5-acceptance.md` | M1 端到端北极星验收标准 | 验收标准 | 把“孩子能独立读完一本书并让家长看到记录”拆成 NS1-NS7 和强制实跑项。 | 看端到端验收前看 | | `docs/specs/agent-run/stage5-e2e-review.md` | M1 端到端验收报告 | 评审 / 验收结论 | 实跑后端 API、验证静态资源、验证 build，确认 M1 北极星指标全部满足。 | **M1 最重要的验证文档** | | `docs/specs/agent-run/milestone-M1-done.md` | M1 里程碑完成结论 | 里程碑结论 | 用业务语言总结 M1 已达成什么、证据来自哪些验收文档，以及下一步应进入 M2。 | 想快速知道 M1 结果时看 | ### M1 小结 M1 是整个项目从“有代码雏形”变成“能真实跑通一条儿童学习链路”的关键阶段。 如果你只想看最短 M1 路径，优先看这 6 篇： 1. `stage1-plan.md` 2. `stage2-feature-list.md` 3. `stage2-review.md` 4. `stage3-review.md` 5. `stage5-e2e-review.md` 6. `milestone-M1-done.md` ## M2：扩到 5-10 本 + OCR 管线统一 - **阶段目标**：把 M1 的单本闭环扩成多本可读，统一 OCR / structure / index 管线，并为每本书打质量分。 - **当前状态**：**已完成** - **阶段文档概况**：主文档 5 篇，另有 1 篇 OCR 专项修复文档与本阶段高度相关。 > 说明：M2 没有重新新建一套 design 文档，而是直接承接 M1 阶段已经产出的 `design-ocr.md`、`design-phonics.md` 和 `stage1-plan.md` 中的 M2 目标。 | 文档名 | 标题 / 主题 | 归类 | 核心内容摘要 | 建议阅读时机 | |---|---|---|---|---| | `docs/specs/agent-run/m2-acceptance.md` | M2 验收标准：扩书 + OCR 统一 | 验收标准 | 明确要求存在单一 `pipeline.py`、10 本 readable 书、质量评分、拼读覆盖率与构建验证。 | **开始看 M2 时先看** | | `docs/specs/agent-run/dev-ocr-m2-report.md` | OCR 管线统一与批量上架报告 | 开发报告 | 记录新增 `backend/tools/pipeline.py`、`ocr_utils.py`、旧脚本弃用标注，以及 9 本新书重跑 structure 的结果。 | 关注 M2 主体实现时看 | | `docs/specs/agent-run/dev-phonics-m2-report.md` | M2 拼读覆盖回关联报告 | 开发报告 | 为 10 本上架书执行 `patch_phonics.py`，补充若干角色名和缩略形式，提升多书点词可用性。 | 想看多书拼读质量时看 | | `docs/specs/agent-run/m2-review.md` | M2 验收报告 | 评审 / 验收结论 | 用实跑结果确认 readable 书架有 10 本、详情 API 可用、M1 未被破坏，并列出每本书的质量分。 | **M2 最重要的验收文档** | | `docs/specs/agent-run/milestone-M2-done.md` | M2 里程碑完成结论 | 里程碑结论 | 用简短方式确认 M2 达成：OCR 管线统一、多书上架、拼读覆盖与首页过滤策略就位。 | 想快速知道 M2 结果时看 | | `docs/specs/2026-07-03-ocr-cross-page-continuation-fix.md` | OCR 跨页续句缺页问题与修复 | 专项修复 / 问题分析 | 解释为什么 `Sniff` 等绘本会在 structured 数据中出现缺页，根因是跨页续句被错误过滤，并给出修复与重跑方法。 | **只在排查 OCR 缺页 / 翻页跳页时看** | ### M2 小结 M2 的价值不在“新增多少页面”，而在于把 M1 的单本能力变成 **可以批量复制的流程**： 有统一管线、有质量度量、有多本 readable 书架，也保住了 M1 的 `AtTheSeaside` 闭环。 ## M3：拼读学习模块 - **阶段目标**：把 `251228-words` 的成熟拼读能力接到主应用，形成“阅读中的词 -> Learn 学拼读 -> Quiz 做检测 -> 结果本地保存”的最小学习闭环。 - **当前状态**：**已完成** - **阶段文档概况**：主文档 5 篇；其设计基础主要沿用 M1 的 `design-frontend.md` 与 `design-phonics.md`。 | 文档名 | 标题 / 主题 | 归类 | 核心内容摘要 | 建议阅读时机 | |---|---|---|---|---| | `docs/specs/agent-run/m3-acceptance.md` | M3 拼读学习模块验收标准 | 验收标准 | 定义 Learn 必须可学、Quiz 必须可测、BookReader 必须能导词、本地状态必须可保存。 | **开始看 M3 时先看** | | `docs/specs/agent-run/dev-fe-m3-report.md` | Learn / Quiz / BookReader 打通报告 | 开发报告 | 把 Learn、Quiz 从占位页变成真实页面，并新增阅读器到学习页和挑战页的入口。 | 关注前端拼读闭环时看 | | `docs/specs/agent-run/dev-phonics-m3-report.md` | 复用 `251228-words` 拼读能力报告 | 开发报告 | 说明复用了哪些成熟能力，例如 `letterPhonemes` 卡片、顺播思路、localStorage 熟练度与错题回流。 | 关注“为什么不是整页搬旧项目”时看 | | `docs/specs/agent-run/m3-review.md` | M3 验收报告 | 评审 / 验收结论 | 逐条确认 Learn 可学、Quiz 可测、BookReader 可导词、状态可持久化，且不破坏 M1/M2。 | **M3 最重要的验收文档** | | `docs/specs/agent-run/milestone-M3-done.md` | M3 里程碑完成结论 | 里程碑结论 | 用简短总结确认 M3 已形成最小可用的拼读学习闭环，并指出下一步应进入 M4 聚合评估。 | 想快速知道 M3 结果时看 | ### M3 小结 M3 的关键不是“做了新的学习页”，而是把阅读器里的生词与学习页、检测页真正串了起来。 从这一阶段开始，项目不只是“可读绘本”，而是“读 + 学 + 测”的最小闭环。 ## M4：家长评估与进度聚合 - **阶段目标**：把阅读记录与拼读结果聚合到家长端，形成可读的进度、薄弱点与评估视图。 - **当前状态**：**未启动 / 未完成** - **阶段产出文档**：**暂无阶段产出文档** ### 当前判断 虽然 M1 已有阅读记录写入与 Dashboard 列表展示，M3 也已经有本地拼读学习与检测结果，但这些能力还没有被系统化整理成正式的 **M4 规划、开发、验收与里程碑结论**。也就是说，**M4 还没有进入正式执行状态**。 ### 建议从哪些已有文档接续 | 参考文档 | 标题 / 主题 | 归类 | 为什么它是 M4 的起点 | 建议阅读时机 | |---|---|---|---|---| | `docs/specs/2026-07-02-multi-agent-execution-plan.md` | 多 Agent 执行方案（含 M4） | 总方案 | 已在 §7.1 明确把 M4 定义为“家长评估”，是当前最直接的 M4 上位规划。 | **M4 启动前必看** | | `docs/specs/agent-run/stage1-plan.md` | M1-M4 总体路线与 DoD | 方案 | 其中 M4 DoD 已定义为聚合阅读/拼读记录并让家长可见，是 M4 的最短目标说明。 | 立项时看 | | `docs/specs/agent-run/design-api.md` | 阅读记录与聚合接口设计雏形 | 详细设计 | 已预留 `GET /api/records/summary` 的聚合思路，是 M4 后端设计的直接起点。 | 开始设计 API 前看 | | `docs/specs/agent-run/design-frontend.md` | 家长端 Dashboard 设计雏形 | 详细设计 | 已说明 Dashboard 当前最小展示方式，可继续扩成进度、薄弱点、统计面板。 | 开始设计前端前看 | | `docs/specs/agent-run/milestone-M3-done.md` | M3 完成结论 | 里程碑结论 | 它明确指出下一步就是把拼读练习结果聚合到家长端评估面板。 | 从 M3 续接到 M4 时看 | | `docs/specs/agent-run/m3-review.md` | M3 验收报告 | 评审结论 | 能帮助你确认 M3 已有哪些可复用数据：待学词、掌握状态、挑战结果、本地持久化。 | 做 M4 数据盘点时看 | ## 4. 按用途归类索引 ## 项目背景 / 总方案 - `项目介绍.md`：最完整的项目总览，适合先建立全局认知。 - `README.md`：仓库级入口说明，偏简略。 - `CLAUDE.md`：技术栈、目录结构、开发约束的简明摘要。 - `docs/specs/2026-05-23-phonics-trainer-design.md`：最早的产品愿景与理想架构文档。 - `docs/specs/2026-07-02-multi-agent-execution-plan.md`：当前这轮文档执行和里程碑推进的总方案。 ## 规划 / 验收标准 - `docs/specs/agent-run/stage1-acceptance.md` - `docs/specs/agent-run/stage2-acceptance.md` - `docs/specs/agent-run/stage3-acceptance.md` - `docs/specs/agent-run/stage5-acceptance.md` - `docs/specs/agent-run/m2-acceptance.md` - `docs/specs/agent-run/m3-acceptance.md` 这些文档适合在“看方案是否完整、看开发是否达标、看某个里程碑是否真正完成”时横向查阅。 ## 详细设计 - `docs/specs/agent-run/design-api.md` - `docs/specs/agent-run/design-frontend.md` - `docs/specs/agent-run/design-ocr.md` - `docs/specs/agent-run/design-phonics.md` 这 4 篇构成了当前主线实现的核心设计层，是理解“为什么代码这样改”的最佳入口。 ## 开发实现报告 - `docs/specs/agent-run/dev-api-report.md` - `docs/specs/agent-run/dev-fe-report.md` - `docs/specs/agent-run/dev-ocr-report.md` - `docs/specs/agent-run/dev-phonics-report.md` - `docs/specs/agent-run/dev-ocr-m2-report.md` - `docs/specs/agent-run/dev-phonics-m2-report.md` - `docs/specs/agent-run/dev-fe-m3-report.md` - `docs/specs/agent-run/dev-phonics-m3-report.md` 这些文档最适合在“想知道具体改了什么、为什么这样实现、有哪些遗留项”时横向查阅。 ## 评审 / 验收结论 - `docs/specs/agent-run/stage1-review.md` - `docs/specs/agent-run/stage2-review.md` - `docs/specs/agent-run/stage3-review.md` - `docs/specs/agent-run/stage5-e2e-review.md` - `docs/specs/agent-run/m2-review.md` - `docs/specs/agent-run/m3-review.md` 如果你不想读完整设计和开发报告，直接看这些文档可以最快知道： 某阶段是否通过、证据是什么、还有没有阻塞项。 ## 里程碑结论 - `docs/specs/agent-run/milestone-M1-done.md` - `docs/specs/agent-run/milestone-M2-done.md` - `docs/specs/agent-run/milestone-M3-done.md` 这三篇是“高层摘要版结论”，适合领导视角、汇报视角或快速复盘视角。 ## 专项问题分析 - `docs/specs/2026-07-03-ocr-cross-page-continuation-fix.md` 这篇不属于里程碑主干，但它非常重要，因为它把“为什么某些绘本正文页会缺失”讲清楚了，也揭示了 OCR 质量问题会如何直接影响阅读体验。 ## 执行过程总账（补充） - `docs/specs/agent-run/runlog.md` 这不是设计文档，也不是验收文档，而是整个 M1-M3 过程的时间线总账。 如果你只能保留一份“过程索引”，这份最有价值。 ## 5. 一页式结论 ### 到目前为止，项目完成了什么 项目已经完成了三段关键跃迁： 1. **M1**：从“硬编码单本书 MVP”变成“真实可用的单本书阅读闭环”。 2. **M2**：从“只有 1 本可跑”变成“10 本可读 + OCR 管线统一 + 有质量评分”。 3. **M3**：从“只能读和点词”变成“读 + 学 + 测 + 本地保存”的最小拼读学习闭环。 ### 哪些能力已经可用 - 书架选书 - 动态加载绘本阅读器 - 点词查看拼读拆分 - 绘本 / 单词音频播放 - 阅读完成上报 - 家长端阅读记录查看 - Learn 学拼读 - Quiz 做最小检测 - 本地保存待学词、掌握状态与挑战结果 - stage-03 的 10 本 readable 绘本 ### 最值得优先看的文档 如果只看最关键的 8 篇，建议优先看： 1. `项目介绍.md` 2. `docs/specs/2026-07-02-multi-agent-execution-plan.md` 3. `docs/specs/agent-run/runlog.md` 4. `docs/specs/agent-run/stage1-plan.md` 5. `docs/specs/agent-run/stage3-review.md` 6. `docs/specs/agent-run/stage5-e2e-review.md` 7. `docs/specs/agent-run/m2-review.md` 8. `docs/specs/agent-run/m3-review.md` ### M4 下一步应该从哪些文档接着做 M4 当前没有正式阶段产出，建议直接按下面顺序接续： 1. `docs/specs/2026-07-02-multi-agent-execution-plan.md` 先确认 M4 的上位目标和阶段位置。 2. `docs/specs/agent-run/stage1-plan.md` 回看 M4 的 DoD：家长能看到阅读与拼读进度评估。 3. `docs/specs/agent-run/design-api.md` 从 `GET /api/records/summary` 的雏形扩成正式聚合接口。 4. `docs/specs/agent-run/design-frontend.md` 把当前简单的 Dashboard 列表扩成评估面板、统计与薄弱点视图。 5. `docs/specs/agent-run/m3-review.md` 与 `milestone-M3-done.md` 盘点 M3 已经积累了哪些本地学习结果，决定哪些要同步到家长端。 ### 最终判断 截至当前，**项目主线并不是停在“做了一堆设计文档”阶段，而是已经完成了 M1、M2、M3 三个实际可运行里程碑**。 真正尚未启动的，是 **M4：把阅读记录与拼读结果做成面向家长的聚合评估能力**。因此，后续阅读与推进，都应该围绕这条未完成主线展开。