离线优先的儿童英语学习伙伴，让阅读、跟读、闯关和复习成为一次魔法冒险。
Magic English Buddy 是一个支持安装到主屏幕的英语学习 PWA。课程、词典和学习记录保存在本机，支持多个孩子共用设备，通过独立学习档案保留各自的进度。
当前版本 2.0.0，以下按当前代码与内置资源整理（2026-09-15）：
| 能力 | 当前支持 |
|---|---|
| 分级课程 | L1–L7 共 90 篇，全部接入学习地图，按通关进度解锁 |
| 阅读与跟读 | 连续朗读、逐词高亮、三档语速、中文翻译、查词收藏、分段示范与录音回放 |
| 离线词典 | 1,100 条源记录，归一化去重后 1,074 个词条，覆盖全部 4,253 次课文可点击词出现 |
| 课程练习 | 听音辨图、单词拼装、句子排序、填空选择；中断后可恢复已保存的答题状态 |
| 离线音频 | 1,721 个预生成 MP3，共 25,329,964 字节（约 25.3 MB），覆盖课文、听题、课文单词和词典发音 |
| 成长记录 | Buddy 进化、魔力奖励、卡牌、成就、连续学习记录、生词复习与学习证书 |
| 学习档案 | 本机创建、切换和改名；每个档案的地图、练习、词卡和奖励独立 |
| 备份与分享 | 全档案 JSON 备份与恢复、当前档案二维码摘要、文字报告、证书 PNG 与打印 |
- 首次打开应用，完成引导并为学习者和 Buddy 起名；已有备份也可从引导页进入恢复。
- 在学习地图进入已解锁的课程，阅读、听朗读、查词或练习跟读，再完成课程练习。
- 在 成长记录 查看学习数据、领取成就奖励，通过 卡牌 → 复习收藏的单词 温习生词。
- 共用设备时，在 设置 → 学习档案 为其他孩子创建档案或切换当前学习者。
- 准备离线使用前，联网打开生产版本并完成应用缓存，再到 设置 → 离线音频（可选） 下载所需音频包。
| 等级 | 区域 | 课程数 |
|---|---|---|
| L1 | 萌芽之森 🌱 | 20 |
| L2 | 回声山谷 🏔️ | 11 |
| L3 | 闪耀之海 🌊 | 15 |
| L4 | 云端之城 ☁️ | 13 |
| L5 | 永恒星空 ⭐ | 13 |
| L6 | 时光回廊 ⚙️ | 10 |
| L7 | 创世之核 💎 | 8 |
- 地图展示课程的锁定、可学习和已完成状态，所有内置课程均可沿路径到达。
- 课程练习达到 60 分即通过，并解锁后续关卡；已通过课程可再次练习。
- 下载高等级音频不会解锁课程。升级应用时保留已有地图进度和奖励记录。
- 连续朗读：播放课文并逐词高亮，支持暂停、继续以及
0.8× / 1.0× / 1.2×语速切换。 - 中文辅助：阅读页可切换翻译显示，设置页可保存默认偏好。
- 魔法查词：点击或长按单词打开词典，查看释义与例句，再点击发音按钮听读音；支持常见词形还原与词卡收藏。
- 分段跟读：手动选择段落、听示范、录制自己的声音，再回放本次录音。需浏览器支持并允许麦克风访问；录音仅在当前会话中保留，切换段落后需重新录音。
朗读优先使用 Kokoro 预生成音频，播放器读取实际词时间点来驱动高亮；无法使用预生成音频时尝试系统语音。系统语音的可用性取决于浏览器与设备，可靠的离线朗读应提前下载音频包。详见 逐词高亮与音频对齐。
| 题型 | 操作 |
|---|---|
| 听音辨图 | 查看英文提示，可点击听题，选择对应图片 |
| 单词拼装 | 排列字母组成单词 |
| 句子排序 | 排列词语还原句子 |
| 魔法填空 | 选择适合上下文的词语 |
- 提交答案后显示反馈，可使用提示并查看本轮成绩。
- 提交答案、进入下一题或使用提示后保存状态；刷新或重新打开课程时恢复已保存的答题、反馈或结果页。
- 课程题目更新后，会丢弃不再适用的旧答题草稿。
- 首次通过课程获得课程配置奖励及答题奖励：每题正确
+3，每次提示-5，答题奖励最低为0；重做保存练习记录，不重复领取首通奖励。
- Buddy 依次经历魔法蛋、小雏龙、幼龙和魔法龙四个阶段；魔力达到 100、500、1,500 后，可在成长记录中手动触发下一阶段进化。
- 查词收藏和首通奖励可获得词卡；成长记录中可查看卡牌和领取已解锁的成就奖励。
- 完成阅读、提交课程答题（含重做与未通过）或保存到期词卡复习，会计入本地学习日；同一天只计一次，连续日期累计，中断后重新计算。
- 通过至少一节课程后，可生成当前档案的学习里程碑证书，预览并下载 PNG，或调用系统打印。
- 二维码与可复制的文字报告用于导出当前档案的学习摘要。
入口：成长记录 → 卡牌 → 复习收藏的单词。
- 每轮最多 10 个词，优先复习到期词，通过选择中文释义作答。
- 到期词答对后提升熟练度，并安排 1、3 或 7 天后复习；答错后回到学习中，次日再复习。
- 每题结果立即保存。没有到期词时可提前练习，提前练习不重复累计熟练度或改变复习日期。
独立档案：在设置中创建、切换或重命名学习者与 Buddy。新档案从第一课和 0 魔力开始；地图、阅读与答题历史、未完成练习、词卡和成就按档案保存。切换时停止旧档案的播放和录音，离线音频及朗读／显示设置在同一应用存储空间内共用。
学习备份：设置中可导出 JSON，包含全部档案、各自学习记录、当前档案选择和设置；当前格式为 v2，兼容 v1 备份。文件保存在用户选择的位置，不会上传，可用于手动迁移设备或浏览器。
恢复前会展示备份摘要并要求确认。恢复会替换本机全部学习记录，需要保留当前记录时请先导出备份。已下载音频会保留；音频文件和临时跟读录音不随备份迁移。详见 多档案、备份与证书验证。
- 应用与课程：生产构建使用 Service Worker 缓存应用资源。首次联网加载并完成缓存后，阅读、查词、练习和本机记录可离线使用。
- 音频按需下载：设置中可选择 L1–L7、词典发音包或全部下载。安装、更新应用及联网播放均不会自动保存课程音频。
- 断点续传：下载可暂停，关闭页面或网络中断后保留已完成文件，下次只补齐缺失内容；文件通过大小与 SHA-256 校验后保存。
- 空间管理：多个音频包共用的片段只保存一份。删除音频包会保留其他已选包需要的片段，删除全部音频也不影响学习记录；设置中的“清除所有数据”会同时删除学习记录和音频。
- iPhone / iPad：建议先通过 Safari 分享菜单添加到主屏幕，再从主屏幕打开、学习和下载。Safari 与主屏幕版分别保存记录和音频，已有记录可通过学习备份手动迁移。
- 出门前检查：浏览器可能因空间不足清理缓存，离线前请检查下载状态；学习记录建议定期导出备份。
音频包大小、生成方式和设备验证记录见 离线音频说明。
- 本机档案用于区分学习进度，不提供账号密码或云端身份。自动跨设备同步、扫码导入和班级汇总尚未实现。
- 当前跟读支持示范与录音分别播放，尚无双声轨对比和真实发音评分；段落排序和关键词口述尚未作为课程题型实现。
- 词典覆盖率与音频技术校验不代表完成教学审核，全量释义、例句和音频仍需人工教学审核。
- 已有 Chrome、WebKit 与 iPhone 模拟器验证记录；实体 iPhone 的麦克风、耳机和锁屏音频回归仍待补充。
准备 Node.js 22.12+ 和 pnpm，也支持 Node.js 20.19+ 的 20.x 版本；版本要求与当前 React Vite 插件一致。
pnpm install
pnpm dev开发地址：http://localhost:3000/magic-english-buddy/。
pnpm build
pnpm preview --host 127.0.0.1 --port 4174预览地址：http://127.0.0.1:4174/magic-english-buddy/。开发模式未启用 Service Worker，请使用生产构建预览验证 PWA 与离线行为。
部署产物为 dist/，默认基础路径为 /magic-english-buddy/。更改部署路径时，需要同步调整 vite.config.ts 中的 base、PWA start_url / scope 与 src/router.tsx 的 basename。
pnpm type-check # TypeScript 检查
pnpm lint # ESLint
pnpm test:run # 单元与组件测试，一次运行
pnpm audit:content # 课程、词形与词典覆盖检查
# 首次运行端到端测试前准备浏览器；Chrome 项目使用系统 Google Chrome
pnpm exec playwright install webkit
pnpm test:e2e # 自动构建，再执行 Chrome / WebKit 当前回归套件端到端测试需安装 Google Chrome，且 4174 端口空闲；请先停止手动启动的预览服务。当前测试范围由 playwright.config.ts 指定，覆盖学习流程、移动端界面、离线音频、答题恢复、备份、多档案与证书。
pnpm audio:prepare # 导出全部课程、听题与词典的音频输入
pnpm audio:generate # 生成或补齐 MP3，需 uv、Python 3.13、ffmpeg
pnpm audio:verify # 校验解码、哈希、时长、逐词时间点和覆盖，需 ffmpeg/ffprobe生成器使用 Kokoro；模型和生成环境只在开发机运行，应用分发预生成音频。修改课文或词典后应重新检查内容覆盖并更新音频。词典数据来源与补充脚本见 课程词典来源。
| 类别 | 技术 |
|---|---|
| 框架与路由 | React 19、TypeScript、Vite 6、React Router 7 |
| 状态与存储 | Zustand、Dexie / IndexedDB |
| 动画与交互 | Framer Motion、Lottie、dnd-kit |
| 音频 | Kokoro 预生成 MP3、Web Audio、系统语音与 MediaRecorder |
| PWA 与样式 | vite-plugin-pwa / Workbox、CSS Modules、CSS Variables |
| 导出与测试 | html2canvas、qrcode、Vitest、Testing Library、Playwright |
src/
├── main.tsx # 当前应用入口
├── router.tsx # 页面路由与课程访问保护
├── components/ # 阅读器、练习、Buddy、成长记录和设置组件
├── pages/ # 引导、地图、阅读、练习、成长、复习、证书与设置
├── services/ # 播放、下载、学习结算、档案、备份与复习服务
├── stores/ # Zustand 状态与设备设置
├── db/ # Dexie 数据结构与迁移
├── data/ # L1–L7 故事、地图、词典和音频清单
├── styles/ # 全局样式与设计变量
└── __tests__/ # 单元与组件测试
public/audio/ # 可选下载的预生成 MP3
scripts/ # 内容审查、词典补充与音频生成／校验
e2e/ # Playwright 回归测试
docs/ # 功能说明、验证记录与设计文档
历史规划中的勾选状态不代表当前已上线能力；使用时请以当前代码和相应验证记录为准。
项目许可见 LICENSE。第三方词典数据的许可见 ECDICT 许可，音频模型与生成信息见 音频来源说明。
Made with ❤️ for educational equity