背单词最容易失败的地方，不是记不住，而是「记住了又忘」
先说三个我自己踩过的坑：
- 孤立的单词表：一个个背、反复刷，记住的其实是「英文 ↔ 中文」的对应关系，不是这个词怎么用。
- 词要放在句子里才有生命，可自己造不出那么多句子，词典里的例句又跟自己的生活毫不相干。
- 有道词典里其实攒了几百上千个生词，收藏完那一刻很爽，之后就再没打开过——收藏夹变成了坟场。
这个工具就是为了解决第三点顺带解决前两点：把你在有道词典里收藏的生词拿出来，交给大模型编成一段连贯的英文短文，你读故事的时候顺便把词认了。
它到底怎么工作：一句话流程
- 读词库：程序直接读你本机有道词典的单词本数据库（
newlocal，SQLite 文件，只读打开，绝不修改你的收藏），自动拿到词条、音标、释义、分组、是否已掌握。 - 编段落：按复习算法挑一组生词（默认 6 个）交给大模型，提示词要求它先想好一个小主题，再让这些生词自然长在故事线上，写成一段 100~150 词的短文。
- 读 + 认：在网页里读这段英文，生词自动高亮、悬停看释义、点一下听发音。读完对每个词点「认识 / 模糊 / 不认识」，系统据此决定它下次什么时候再出现。
提示：早期版本我让模型「尽量保留真实例句原句」，结果段落变成例句拼接、没有故事线，可读性很差。现在真实例句只当用词参考，写作仍然可读性优先；例句本身放到段落下方单独展示。
三个段落来源，随心情切换
| 模式 | 英文从哪来 | 要不要 API Key | 适合 |
|---|---|---|---|
| 大模型原创（默认） | 大模型自由创作，先讲故事再让生词融入 | 要 | 日常复习，可读性最好 |
| 真实语料参考 | 段落仍由大模型写（不照抄素材），同时把该词的真实原版例句列在下方，带出处 | 要 | 想同时看地道用例和出处 |
| 真实例句原文 | 直接列真实例句，完全不改写，不调大模型 | 不要 | 只想看原汁原味的句子 |
真实语料的出处来自 FORBES / NEWYORKER / WSJ / CNN / BBC、VOA 原声、名校公开课，界面上会标出每条例句的来源，也能单独朗读。
四条语音通道，随便挑
单词和段落都能读出声，而且不止一种方案：
| 通道 | 是什么 | 特点 |
|---|---|---|
| 有道真人发音 | dictvoice 接口 |
单词发音首选，英音缺失时自动退美音 |
| edge-tts | 微软神经网络语音 | 免费，47 个英文音色（美/英/澳），段落朗读默认走它 |
| Piper | 本地 ONNX 模型（onnxruntime） | 完全离线、不联网、不花钱，隐私最好 |
| 豆包语音 | 火山引擎「语音生成 / 语音合成」 | 音色最自然，两条独立接口都给接上了 |
共同点：同一段落只会生成一次。文本 hash 落盘缓存，第二次点播放是零请求的秒播（页面上会直接标出「已缓存」），不用为同一段文字重复花钱。
复习节奏：Leitner 盒子
每个词有一个「盒子」编号，你的判定决定它下次什么时候出现：
| 你的判定 | 结果 |
|---|---|
| 认识 | 盒子上移一级，下次间隔 1 / 3 / 7 / 16 / 35 天 |
| 模糊 | 维持当前盒子，过一会儿再来 |
| 不认识 | 回到 0 号盒，下次优先出现 |
「智能」模式优先挑到期该复习的词，其次挑复习次数少、掌握程度低的词。你在有道词典里手动标成「已掌握」的词，工具会自动跳过（也可以在页面上勾选「包含已掌握的词」把它们拉回来）。
数据在哪？全在你自己电脑上
- 词库、复习进度、段落缓存、音频缓存，都在本机
data/目录里，不经过任何第三方服务器。 - 只有当前这一组的几个生词和它们的释义会发送给你自己配置的大模型接口。
- 有道词典的数据库是只读打开的，工具不会动你的收藏。
实现上的几个小坚持
- 只要 Python 标准库，不需要 pip 安装任何东西（
edge-tts可选，装了音质更好），Python 3.9+，实测 3.12。 - 双击
run.bat就能用，一个脚本电脑手机通用（默认监听局域网，启动时直接打印手机可访问的地址）。 - 后端只有 6 个文件：
server.py本地服务、youdao.py读词库、paragraph.py选词与提示词、tts.py朗读、store.py读写、youdao_online.py在线音标与例句。没有框架、没有数据库迁移，出问题自己也能看懂。 - 段落缓存按「词 + 配置 + 提示词版本」生成 key，同样的条件只花一次钱。
怎么上手
- 装 Python 3.9 以上（Windows 上就是一路下一步）。
- 把工具放到任意目录，双击
run.bat，浏览器自动打开http://127.0.0.1:8765/。 - 右上角「⚙ 设置」里填大模型配置（
api_base/api_key/model），任何 OpenAI 兼容接口都行：DeepSeek、OpenAI、通义千问，甚至本地 Ollama。 - 点「生成新段落」，开始读。
- 想手机上看：首次用管理员运行一次
tools/allow-firewall.bat放行端口，同一个 Wi-Fi 下用手机打开启动时打印的那个局域网地址即可。
不想先花钱买 Key？设置
YOUDAO_REVIEW_MOCK=1可以用离线演示模式先把界面点一遍（内容是固定句式，只为了看流程）。
适合谁
- 有道词典里躺着一堆收藏、但从来没复习过的人
- 厌倦了「单词表 + 反复刷」、想换成语境记忆的人
- 想给孩子/自己找地道例句，又不想被各种背单词 App 的会员体系绑住的人
- 在意隐私，希望词库和复习记录留在自己电脑上的人
