AI 英语学习助手实战:翻译源降级、大模型按需补全与游戏化背记
这是我给女儿做的英语学习应用,Flask + 原生 JS + SQLite,迭代到 v2.0.0。这个系列不铺项目全貌,只挑真正花了时间的取舍来讲:这篇是概览,讲需求约束、整体架构和技术选型;四篇专题分别讲翻译降级、大模型按需补全、游戏化背记、数据层与部署,按需读。
一、项目背景与整体架构
1.1 需求约束
这是给女儿做的工具,所以约束和"面向大众的 SaaS"完全不同:
- 注意力短:翻译要秒回,操作路径不能超过两步
- 要有正反馈:光背单词坚持不下来,得有游戏和徽章
- 断网也不能白屏:已经存下来的单词、例句必须离线可看
- 家长得能自己维护:一个人开发一个人运维,不能引入需要值守的中间件
1.2 整体架构
前端是原生 JS,没有构建步骤;后端是单个 Flask 进程,路由薄、业务逻辑沉在 services/;数据落 SQLite;外部依赖全是 HTTP API。
1.3 技术选型的取舍
选 Flask + 原生 JS,不是因为它"先进",而是因为这个项目的真实成本结构:
| 维度 | 选择 | 理由 |
|---|---|---|
| 前端框架 | 原生 JS | 单机自用,不需要 SSR、前端路由和状态管理;省掉整条构建链,改完刷新就生效 |
| 后端框架 | Flask | 29 个接口、以同步 IO 为主,Flask 足够;各家 SDK 与示例最全 |
| 数据库 | SQLite | 单用户单机,零运维;备份就是拷一个文件 |
| 部署 | Docker Compose | 一条命令起停,不用管 systemd 和虚拟环境 |
代价也要讲清楚:api.js 已经涨到 189 KB 单文件。这是"不建前端工程化"的直接账单,第二篇会具体说它的后果。
二、系列导读:四篇专题各讲什么
| 篇目 | 讲什么 | 什么时候读 |
|---|---|---|
| (一)翻译源降级与缓存 | 按输入分流、金山词霸 buildId 动态抓取、统一返回契约、翻译缓存 | 要对接会变、会挂的第三方 API |
| (二)大模型按需补全与成本控制 | 角色 prompt、本地秒开 + 按需 AI 补全、prompt 放前端的代价、缺密钥降级 | 想把大模型接进产品,又怕慢、怕贵 |
| (三)一套底座撑起 9 款背记游戏 | game-kit.js 共用内核、自适应出题 / 错词回炉 / 连对升星、断网与跨设备进度 | 做学习类、激励类功能 |
| (四)数据层取舍与部署密钥治理 | 表结构、upsert 不碰学习进度、成就判定、统计口径、Docker 与 .env | 准备长期自用或部署上线 |
三、小结
这个项目没有什么惊人技术,但有几条我认为可以复用的做法:
- 第三方 API 一律假设它会变 —— buildId 动态抓取、404 强制刷新重试、音频播放降级
- 区分"必须立刻有"和"可以等" —— 本地秒开加按需 AI 补全,把成本花在用户无感的地方
- "不写什么"也是设计 —— upsert 里刻意缺席的那四个字段,比写一堆判断更可靠
- 抽象等被维护成本逼出来再做 ——
game-kit.js是第 N 款游戏的痛逼出来的,不是一开始就设计好的
项目已开源(MIT):https://github.com/zhaoxuejie/moqian-wendy-translator
素材说明:项目内三张头像(柯南、小丸子、哆啦A梦)为受版权保护的动漫角色,仅用于个人家庭学习场景,不在 MIT 授权范围内。如果你要复用这个项目,记得换成原创或免版权素材。