anki-vocab：一个命令行工具，让背单词变成一件很酷的事
背单词这件事，我折腾了很久。
用了很多 App，要么卡片太简陋（只有单词+中文释义），要么复习流程太机械。我想做的是：把每个单词都变成一张"有温度"的卡片——有英文释义、有使用场景、有记忆技巧、有发音，还有地道的例句。
于是一口气做了这个 CLI 工具：anki-vocab。它把 Claude（LLM）、OpenAI TTS、Anki 串成了一条流水线，按下一个命令，所有事情自动完成。
更妙的是，我发现光"存卡片"还不够。记过的单词得用起来。于是我又加了一个阅读理解练习模式，从你的单词库里抽取词汇，让 Claude 生成一篇考研英语风格的阅读文章，你在浏览器里阅读、做题，鼠标悬停就能看词义。
功能一览
| 功能 | 说明 |
|---|---|
| 🤖AI 制卡 | 调用 Claude 生成结构化单词卡片（英文释义、用法、记忆技巧、Collins 释义、中文翻译） |
| 🔊AI 发音 | OpenAI TTS 生成地道美音，即时播放并嵌入卡片 |
| 🃏一键入库 | 自动存入 Anki，支持创建/更新/去重 |
| 📡AnkiConnect | 通过 HTTP API 与 Anki 交互，无需手动导入 |
| 💾离线缓存 | Anki 没开？自动写入 SQLite，下次自动同步 |
| 📖阅读练习 | 生成考研英语风格阅读理解（400-500 词，5 道题），鼠标悬停查词义 |
| 🎯错题追踪 | 答错的单词自动记录，下次优先练习弱词 |
| 🔌可插拔 TTS | TTS 层完全解耦，换 ElevenLabs 只需一行代码 |
安装
git clone https://github.com/zhchoice123/anki-vocab.git cd anki-vocab python -m venv venv && source venv/bin/activate pip install -r requirements.txt # 配置 API Key cp .env.example .env # 编辑 .env，填入 ANTHROPIC_API_KEY 和 OPENAI_API_KEY前置条件：
- Python 3.11+
- Anki 桌面版 + AnkiConnect 插件
- 一个名为
英语单词模板(vocab配色)的 Note Type（10 个字段）
用法一：查词制卡
最简单的方式：
./word tenacious终端会显示一张漂亮的 Rich 渲染卡片：
╭──────────────────────────────────────────────────────────────╮ │ │ │ tenacious adj.顽强的；坚韧不拔的 │ │ │ │ ★★★★☆ │ │ │ │ 1. SIMPLE MEANING │ │ Someone who keeps trying and never gives up. │ │ │ │ 2. KEY IDEA │ │ It shows very strong will and determination. │ │ │ │ ... │ │ │ │ 🔊 ✓ Saved to Anki │ ╰──────────────────────────────────────────────────────────────╯同时你会听到 TTS 朗读 "tenacious"。卡片已自动存入 Anki。
如果这个词已经在牌组里了，它会直接播放已有音频并展示卡片，不会重复调用 API。
支持短语：
./word "give up"支持参数覆盖：
./word --deck "My Deck" serenity # 指定牌组 ./word --speed 0.8 verbose # 慢速发音，更清晰 ./word -v tenacious # 开启 debug 日志用法二：阅读理解练习
这是我个人最喜欢的功能。
./word practice它会做以下几件事：
- 从你的单词库中智能选词（优先选你答错过的弱词，不足再补新词）
- 调用 Claude 生成一篇阅读文章——题材随机（经济、科技、历史、政治、文化…），400-500 词，4-6 段，考研英语难度
- 生成 5 道选择题，覆盖考研五大题型：主旨大意、细节理解、推理判断、词义猜测、作者态度
- 启动本地 Web 服务（
http://127.0.0.1:8766），自动打开浏览器
页面效果：
- 🌙深色主题，护眼
- ✨目标单词蓝色高亮，鼠标悬停弹出英文简单释义
- ✅做完提交后即时判分，标出对错并显示解析
- 📝错题自动写入 SQLite，下次优先复习
./word practice -n 8 # 只用 8 个词生成文章 ./word practice --port 8767 # 换端口 ./word practice --no-browser # 不自动打开浏览器错题追踪原理
每次你答错一道题，系统会读取这道题的target_word（它考察的是哪个单词），然后在 SQLiteword_errors表中记录一次错误。
下次运行./word practice时，WordSelector会：
- 先按
error_count DESC, last_error DESC取出弱词 - 再用最新添加的单词补足到 10 个
也就是说，你的弱词会被反复"照顾"，直到你真正掌握。
离线也能用
Anki 没开？完全没问题。
当你执行./word tenacious时，如果 AnkiConnect 连不上，工具会静默把完整卡片 + 音频 Base64 写入~/.anki-vocab/pending.db。
下次运行任意命令时，后台线程会自动把这些 pending 的卡片推送到 Anki，并提示：
[sync] synced 3 pending word(s) to Anki技术架构
这个项目代码量不大（约 2000 行 Python），但结构比较清晰：
anki-vocab/ ├── add_word.py # CLI 入口，子命令路由 ├── config.py # 环境变量配置 ├── models.py # 数据模型（WordCard、ReadingMaterial…） ├── anki/ │ ├── repository.py # AnkiConnect HTTP 客户端 │ ├── cache.py # LRU 缓存装饰器 │ ├── formatter.py # WordCard ↔ Anki 字段映射 │ └── local_store.py # SQLite 离线缓存 + 错题追踪 ├── llm/ │ ├── base.py # LLM 抽象基类 │ └── claude.py # Claude 提供商（查词 + 阅读生成） ├── tts/ # TTS 完全解耦 │ ├── base.py # TTS 抽象基类 │ ├── openai_tts.py # OpenAI TTS 实现 │ ├── player.py # 跨平台音频播放 │ └── utils.py # PCM → WAV 工具 ├── services/ │ └── word_service.py # 业务编排层 ├── practice/ # 阅读理解练习模式 │ ├── selector.py # 智能选词（错题优先） │ ├── generator.py # 阅读生成器 │ ├── server.py # Flask Web 服务 │ ├── templates/ │ │ └── practice.html # 阅读 UI │ └── static/ │ └── style.css # 深色主题 + Tooltip ├── display/ │ └── renderer.py # Rich 终端渲染 └── tests/ └── test_core.py # 单元测试（40+ 测试用例）设计亮点
- Repository + Decorator 模式：
CachingAnkiRepository给 Anki 操作加了 LRU 缓存，find读缓存，save/update写穿缓存