🍅 Tomato Timer / 番茄钟 - Anki Add-on
Pomodoro timer + card review stats, right inside Anki.
番茄钟 + 卡片复习统计,就在 Anki 里。

公众号:棉花糖的神奇口袋
Stay focused during Anki reviews. A pomodoro countdown on the right dock, card review stats on the left dock, and daily tracking to keep you motivated.
在 Anki 复习时保持专注。右侧 dock 显示番茄倒计时,左侧 dock 显示卡片复习统计,每日追踪让你保持动力。
✨ Features / 功能
| 🇬🇧 English | 🇨🇳 中文 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| 25+5 default rhythm, customizable work / break / long break durations | 25+5 默认节奏,可自定义工作 / 休息 / 长休息时长 |
| Timer presets: classic 25/5, deep 50/10, sprint 90/20 | 计时预设:经典 25/5、深度 50/10、冲刺 90/20 |
| Long break every N pomodoros (default: every 4, 15 min) | 每 N 个番茄进入长休息(默认每 4 个,15 分钟) |
| Optional auto-start on review & auto-continue to next phase | 可选"进入复习时自动开始"和"完成后自动进入下一阶段" |
| Optional auto-pause when leaving the reviewer | 可选离开复习时自动暂停计时器 |
| Skip the current phase without polluting pomodoro stats | 可跳过当前阶段,且不会污染番茄统计 |
| Quiet hours can suppress completion sound overnight or during custom time windows | 安静时段可在夜间或自定义时间段关闭完成提示音 |
| Left dock: review count, mastery status, per-session accuracy | 左侧统计:复习次数、已掌握判定、本次会话正确率 |
| Timer dock shows today's pomodoro goal progress at a glance | 计时器主面板直接显示今日番茄目标进度 |
| Optional session card goal can finish a focus session early | 可设置本轮卡片目标,答够后自动完成专注 |
| Daily stats panel: goal progress, streak, 7/30-day totals, 30-day heatmap, CSV export | 每日统计面板:目标进度、连续达标、近 7/30 天累计、30 天热力图、CSV 导出 |
| JSON backup and non-destructive restore for pomodoro records | 番茄记录支持 JSON 备份和非破坏性恢复 |
| Manual correction for today's pomodoro count | 支持补记、扣减或清零今日番茄数 |
| Scrollable settings and stats dialogs for small screens/high DPI | 设置和统计对话框支持滚动,适配小屏和高缩放 |
| Dark card-based UI with mode chips, gradient progress bars, 64px timer | 深色卡片化 UI,模式 chip、渐变进度条、64px 大字计时器 |
| Completion sound (optional) | 完成时可选提示音 |
| Tools menu to show/hide docks and open settings | 工具菜单可显示/隐藏计时器和卡片统计,并打开设置 |
📸 Screenshots / 截图
📋 Requirements / 系统要求
- Anki 25.02 or later / 或更高版本
- Windows / macOS / Linux
📦 Installation / 安装
- Download
tomato_timer-2.13.0.ankiaddon from the Releases page / 从 发布页 下载
- In Anki: Tools → Add-ons → Install from file… → select the downloaded file / 在 Anki 中:工具 → 插件 → 从文件安装… → 选择下载的文件
- Restart Anki / 重启 Anki
- You'll see 🍅 番茄钟 in the Tools menu / 工具菜单中出现 🍅 番茄钟
🚀 Usage / 使用方法
| Step | 🇬🇧 | 🇨🇳 |
| ---- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 1 | Tools → 番茄钟 → Show Timer - opens the right dock | 工具 → 番茄钟 → 显示计时器 - 打开右侧 dock |
| 2 | Tools → 番茄钟 → Show Card Stats - opens the left dock | 工具 → 番茄钟 → 显示卡片统计 - 打开左侧 dock |
| 3 | Click ▶ Start Focus to begin a 25-minute session | 点击 ▶ 开始专注 开始 25 分钟番茄 |
| 4 | Use Skip when you need to jump from focus to break or break to focus | 需要时可用 跳过阶段 在专注和休息之间快速切换 |
| 5 | Tools → 番茄钟 → Settings - customize durations, goals, and behavior | 工具 → 番茄钟 → 设置 - 自定义时长、目标和行为 |
| 6 | Tools → 番茄钟 → Daily Stats - view heatmap/progress, correct today's count, backup/restore JSON, and export CSV | 工具 → 番茄钟 → 每日统计 - 查看热力图/进度、修正今日数量、备份/恢复 JSON 并导出 CSV |
⚙️ Configuration / 配置项
| Setting / 设置 | Default / 默认值 | Description / 说明 |
| ---------------------------------------- | ---------------- | ------------------------------------------------------------ |
| Timer preset / 计时预设 | Classic / 经典 | One-click rhythm presets, switches to custom after manual edits / 一键节奏预设,手动修改后自动变为自定义 |
| Work minutes / 工作时间 | 25 | Focus session duration / 专注时长 |
| Break minutes / 休息时间 | 5 | Short break duration / 短休息时长 |
| Long break minutes / 长休息时间 | 15 | Long break duration / 长休息时长 |
| Long break interval / 长休息间隔 | 4 | Pomodoros before a long break / 几个番茄后长休息 |
| Daily goal / 今日目标 | 4 | Target pomodoros per day / 每日番茄目标 |
| Card goal / 本轮卡片目标 | Off | Finish the active focus session after N reviewed cards / 专注计时期间答够 N 张卡后自动完成本轮番茄 |
| Auto-start / 自动开始 | Off | Start timer when a card appears / 显示题目时自动开始 |
| Auto-continue / 自动继续 | Off | Start next phase after completion / 完成后自动进入下一阶段 |
| Pause on reviewer end / 离开复习自动暂停 | Off | Pause a running timer when leaving review / 离开复习时暂停正在运行的计时器 |
| Completion sound / 提示音 | On | Beep when timer finishes / 计时完成时蜂鸣 |
| Quiet hours / 安静时段 | Off, 22:00-07:00 | Suppress completion sound during the time window / 指定时段内不播放完成提示音 |
| Card review stats / 卡片统计 | On | Show review count & accuracy / 显示复习次数和正确率 |
| Mastery threshold / 掌握阈值 | 3 | Reviews needed for "mastered" / 判定"已掌握"所需次数 |
🔧 Development / 开发
# Windows: one-command build + test / 一键打包+测试
.\scripts\package.ps1
# Cross-platform / 跨平台
python -m py_compile __init__.py common.py config.py storage.py styles.py
python scripts/package.py
python scripts/smoke_test.py
Handoff-first docs for future developers and AI agents:
面向换电脑、换 AI、换开发者的接手文档:
AGENTS.md - shortest rules for the next AI agent / 下一位 AI 的最短规则
HANDOFF.md - current state, build commands, release status / 当前状态、构建命令、发布状态
DEVELOPMENT.md - full developer guide / 完整开发者文档
📁 Project Structure / 项目结构
tomato_timer/
├── __init__.py # Entry point & UI classes / 入口 + UI 类
├── common.py # Shared utilities / 共享工具
├── config.py # Config load/save / 配置加载保存
├── storage.py # SQLite database / 数据库操作
├── styles.py # Theme & QSS stylesheets / 主题样式
├── manifest.json # Add-on metadata / 插件元数据
├── scripts/
│ ├── package.py # Build .ankiaddon / 打包脚本
│ ├── package.ps1 # Windows one-click build / Windows 一键打包
│ └── smoke_test.py # Automated checks / 冒烟测试
└── README.md
📝 Changelog / 更新日志
v2.13.0
- 🆕 Absorbed Pomodium-style session card goals / 吸收 Pomodium 的本轮卡片目标思路
- 🎯 Focus sessions can finish early after the configured reviewed-card count / 达到设置的答卡数后自动完成本轮专注
- 🧪 Smoke tests now guard card-goal config, UI, and answer-hook integration / 冒烟测试覆盖卡片目标配置、UI 和答题钩子
v2.12.0
- 🆕 Timer dock now shows today's progress as
count / daily goal / 计时器主面板显示“今日数量 / 今日目标”
- ✅ Progress chip turns complete when today's goal is reached / 今日目标达成后进度 chip 会切换为完成状态
- 🧪 Smoke tests now guard the daily-goal progress chip / 冒烟测试覆盖今日目标进度 chip
v2.11.0
- 🐛 Session accuracy now resets when leaving review / 离开复习后会重置本次正确率
- 🔄 Left dock rate display resets to 0% for the next session / 左侧正确率显示会为下一次复习回到 0%
- 🧪 Smoke tests now guard session-stat reset behavior / 冒烟测试覆盖会话统计重置
v2.10.0
- 🆕 Optional auto-pause when leaving Anki review / 新增离开复习时自动暂停计时器选项
- 🛡️ Prevents focus/break timers from continuing unnoticed after review ends / 防止退出复习后计时器在后台误跑
- 🧪 Smoke tests now guard reviewer-end pause behavior / 冒烟测试覆盖离开复习自动暂停入口
v2.9.0
- 🆕 Settings and stats dialogs are now scrollable / 设置和统计对话框支持滚动
- 🖥️ Better usability on small screens and high-DPI scaling / 小屏和高缩放环境下更容易完整操作
- 🧪 Smoke tests now guard scrollable dialog layout / 冒烟测试覆盖滚动对话框布局
v2.8.0
- 🆕 Timer dock now has a skip-phase button / 计时器 dock 新增跳过当前阶段按钮
- 🛡️ Skipping a focus session does not increment today's pomodoro count / 跳过专注不会增加今日番茄数
- 🧪 Smoke tests now guard the skip-phase UI / 冒烟测试覆盖跳过阶段入口
v2.7.0
- 🆕 Timer presets in settings: classic, deep work, and sprint / 设置新增经典、深度和冲刺计时预设
- 🔄 Manual duration edits automatically switch the preset to custom / 手动调整时长后自动切换为自定义
- 🧪 Smoke tests now guard preset config and settings UI / 冒烟测试覆盖预设配置和设置入口
v2.6.0
- 🆕 Quiet hours: suppress completion sound during a configurable time window / 新增安静时段,指定时间内不播放完成提示音
- 🌓 Cross-midnight windows work by default, e.g. 22:00-07:00 / 默认支持跨午夜时段,例如 22:00-07:00
- 🧪 Smoke tests now guard quiet-hours config and settings UI / 冒烟测试覆盖安静时段配置和设置入口
v2.5.0
- 🆕 30-day heatmap in the stats dialog / 每日统计面板新增 30 天热力图
- 🔄 Heatmap refreshes after manual correction and JSON restore / 手动修正和 JSON 恢复后热力图即时刷新
- 🧪 Smoke tests now guard heatmap UI hooks / 冒烟测试覆盖热力图入口
v2.4.0
- 🆕 Full JSON backup for all stored pomodoro records / 支持完整 JSON 备份番茄记录
- 🆕 Non-destructive JSON restore: same-day conflicts keep the larger count / 支持非破坏性恢复,同一天保留较大计数
- 🧪 Smoke tests now guard backup/restore APIs and dialog buttons / 冒烟测试覆盖备份恢复 API 和按钮入口
v2.3.0
- 🆕 Daily stats now supports today's +1 / -1 / reset actions / 每日统计支持今日补记、扣减和清零
- 🔄 Manual corrections immediately refresh the stats panel and timer dock / 手动修正后即时刷新统计面板和计时器 dock
- 🧪 Smoke tests now guard the manual correction API and buttons / 冒烟测试覆盖修正 API 和按钮入口
v2.2.0
- 🆕 Long break: configure
long_break_minutes and long_break_interval / 新增长休息配置
- 🆕 Auto-continue: automatically start the next phase after completion / 完成后自动进入下一阶段
- 🆕 Timer chip shows whether the next break is short or long / 计时器 chip 提示下次休息类型
- 🔧 Settings changes refresh the timer display immediately without interrupting / 保存设置即时刷新,不打断运行
v2.1.1
- 🐛 Fix settings & stats dialogs not opening on Anki 25 / PyQt6 / 修复 PyQt6 下对话框无法打开
v2.1.0
- 🆕 Daily stats panel with CSV export / 每日统计面板 + CSV 导出
- 🆕
auto_start now works: timer starts when a review card appears / auto_start 正式生效
- 🆕
daily_goal setting / 新增每日目标配置
- 🔧 Refactored into modules:
common, config, storage, styles / 拆分为多模块
- 🔧 Build scripts with smoke tests / 新增打包和冒烟测试脚本
📄 License / 许可证
GNU GPL v3
🔗 Links / 链接
Made with ❤️ for Anki learners everywhere. / 为全世界的 Anki 学习者而建。