面向零基础英语学习者的 AI 个性化学习应用。核心闭环：AI 生成词卡 → 间隔重复（FSRS）→ 产出型练习（拼写/听写/测验/混合）→ 情景记忆（语境/故事/记忆法）→ 学习科学持续优化。全程发音（edge-tts 微软神经语音），本地运行。
| 科学原理 | 落地功能 |
|---|---|
| 间隔重复 / 遗忘曲线 | FSRS（py-fsrs）按个人记忆状态排下次复习，desired-retention 思想：近 7 天正确率自动调每日新词量（5/10/15） |
| 提取练习 (Retrieval) | 拼写练习（Qwerty 式逐字反馈）、听写 4 选 1、测验逐题判分 |
| 生成效应 (Generation) | 释义 → 主动拼写英文，比被动识别记忆深 |
| 错误增强 (Errorful Learning) | 答错词加权入库（error_cards），优先重现，连续对 2 次减权 |
| 渐褪提示 (Fading Scaffolding) | 拼写三档：教过（首字母）→ 提示（空格数）→ 独立（自由回忆） |
| 可理解输入 (i+1) | 句子意群切分（3-6 词一块）+ 语法角色语义配色 + 逐块点读跟读，先"读得下来"再"看得懂" |
| 脚手架递减 (Fading) | 中文翻译智能档：复习 <3 次自动显示，≥3 次自动隐藏；也可设置常显/隐藏 |
| 元认知校准 (JOL) | 翻面前"先回想 3 秒"引导 + 过快翻面提醒，破除流畅性错觉 |
| 双重编码 (Dual Coding) | AI 例句/故事强制"具体、有画面感、有情绪"（如 "The red apple rolled off the table into the dog's bowl."） |
| 交错练习 (Interleaving) | 混合练习：拼写/听写/选择随机交错 |
| 自我解释 (Self-explanation) | 每词可写自己的记忆法（谐音/联想），复习时展示 |
| 预测试效应 (Pretesting) | 课程学新词先猜意思再揭晓，猜错时"对比冲击"强化记忆 |
| 难度自适应 (Adaptive) | 近 7 天错误率自动调每日目标（>30% 降 / <15% 升），用户设最低保底 |
| 情绪记忆锚点 | streak、目标环、音效反馈、成绩单分享卡 |
| 睡眠巩固提醒 | 20 点后未学习时提示"睡前复习记忆最牢" |
针对零基础"全英文句子看不懂"的痛点，句子卡全套脚手架：
- 正面中文翻译：句子卡正面直接显示中文（默认智能：复习 <3 次显示，≥3 次自动隐藏），不用翻面才能看懂
- 意群切分：长句切成 3-6 词的小块（AI 生成时切分 + 旧数据前端兜底），每块一个"呼吸单位"
- 语法角色语义配色：🟢 主语 / 🟡 谓宾 / 🟠 状语（AI 生成 role 标记，悬浮显示角色名）
- 逐块点读跟读：点击任意意群块单独朗读该段，跟读节奏；整句朗读/翻面对照保留
- 难度分级标签：词卡=基础句（basic），毕业句子卡=阅读句（reading，带 📖 标签）
- 对话体句优先：毕业句子生成优先 A/B 两人对话（有应答、有人物），正面渲染为气泡对话
- 卡片布局自适应：句子卡更高（420px），内容溢出可滚动不截断，学习区垂直居中
核心学习
- 今日队列：新词 + FSRS 到期卡 + 错词/困难词优先重现
- 课程式学习：AI 20 级递进（音标启蒙 → 高频词 → 简单句 → 场景对话）
- 闪卡学习：翻面对照 + 自动发音 + 意群/中文辅助 + 评分（忘了/模糊/记得/太简单）
- 词毕业：复习 3 次 → 例句自动转句子卡（对话体、阅读句）继续学
产出型练习
- 拼写练习（三档难度、逐字绿/红校验、回车提交、音效）
- 听写练习（播发音 4 选 1）
- 测验（中译英×3 + 选词 + 填空，逐题判分、错题汇总可点进详情）
- 混合练习（三题型随机交错 + 完成页错题列表）
内容与记忆
- 故事模式：AI 用已学词编故事，整句朗读 + 点词弹卡评分
- 语境例句：两句对话体气泡（可"换一个"）
- 自我记忆法（谐音/联想/小故事）
单词本
- 搜索（词/释义/例句中文）+ 相关性排序（完全匹配>前缀>包含>释义>例句）+ A-Z 排序导航 + 右键快速查阅
- 详情页：意群切分/难度标签/复习历史（评分标签）/毕业状态/错词数/困难词标记/例句发音
- 编辑/删除词卡（AI 生成错了可纠正）；句子长句自动换行不截断
学习统计
- 今日目标环（每日目标可设 5/10/15/20）、🔥 streak、错词入口
- 本周正确率 + 8 周趋势柱状
- GitHub 风格热力图（最近一年，hover 显示日期）
- 🏅 成绩单分享卡（canvas 生成，可存图进简历）
数据与设置
- 💾 全量备份 JSON 导出 + 📥 恢复导入（词库/复习/记忆法/错词）
- 🎴 Anki CSV 导出（UTF-8 BOM，无缝沉淀到你现有的 Anki 复习流）
- ⚙️ 设置：发音速度 / 每日新词量 / 中文翻译档位（智能/常显/隐藏）/ 暗色模式
- 新用户 5 分钟闭环：生成词后"马上学一学"不等明天
# 1. 创建虚拟环境并安装依赖
python -m venv .venv
source .venv/Scripts/activate # Windows Git Bash（PowerShell 用 .venv\Scripts\Activate.ps1）
pip install -r requirements.txt
# 2. 配置（复制模板并填入 DeepSeek API key）
cp .env.example .env
# 编辑 .env：DEEPSEEK_API_KEY=sk-xxx
# 3. 初始化数据库
python -m alembic upgrade head
# 4. 启动（8001 是专有端口；8000 常被 WSL 占用）
python -m uvicorn app.main:app --reload --port 8001
# 5. 浏览器打开 http://localhost:8001前端开发：
cd frontend && npm install && npm run dev（Vite dev server，API 代理到 8001） 生产构建：cd frontend && npm run build（输出到app/static/，FastAPI 直接挂载）
首次使用：进「加词」页输入几个单词（如
apple, banana, teacher）→ 点"马上学一学"立即开练；或从「开始零基础课程」走 20 级递进。
python -m pytest # 后端测试
node e2e_test.js # E2E（需 npx playwright + Edge）
node e2e_story.js # 故事流程 E2E启动后访问 http://localhost:8001/docs（FastAPI 自动生成）。
| 领域 | 端点 |
|---|---|
| 队列 | GET /api/today（含 error_cards 优先）、GET /api/stats /stats/history /stats/weekly |
| 学习 | POST /api/reviews（FSRS + 错词加权） |
| 词卡 | GET/POST/PUT/DELETE /api/cards/*、POST /api/cards/{id}/regenerate、/hard |
| 练习 | GET /api/quiz、POST /api/typing/check、GET/POST /api/listening* |
| 课程 | GET /api/lessons*（AI 20 级逐课生成） |
| 故事 | GET/POST/DELETE /api/stories* |
| 记忆法 | GET/PUT /api/memos/{card_id} |
| 发音 | GET /api/tts/audio/{word}（流式 + 缓存 + 预合成） |
| 数据 | GET /api/export/cards、/api/export/anki、POST /api/import/cards |
FastAPI · SQLAlchemy 2.0 · SQLite · Alembic · DeepSeek API（OpenAI 兼容协议，deepseek-v4-flash / v4-pro 双模型路由）· py-fsrs（FSRS 间隔重复）· edge-tts（英音合成）· React 19 + Vite（Web Audio API 音效）· pytest · ruff · Playwright E2E
app/
models/ SQLAlchemy 模型（Card/Review/Story/StoryWord/Lesson/Memo/ErrorCard/HardCard）
routers/ API 路由（today/reviews/quiz/cards/listening/lessons/stories/memos/tts/export）
services/ 业务层（生成器/FSRS/毕业/判分/错词追踪/模型路由/意群生成）
static/ 构建产物（index.html + assets/），由 frontend/ 构建生成
frontend/ React 19 + Vite 源码（views/组件、lib/共享层）
tests/ pytest 测试
data/ SQLite 数据文件（不提交）
- 分支：
main（稳定）←dev（开发）←feature/xxx；提交用 Conventional Commits - 前端静态资源改动后：
index.html里?v=N版本号必须递增（防浏览器缓存） .env永不入库（安全红线）；模型名统一走app/services/model_router.py- 卡片类型（kind）与难度（difficulty）由系统决定，AI 输出不能覆盖