🍅 TomatoTimer · 番茄钟

不只是一个计时器，而是你的专注产出记录仪。

中文 · English

---

✨ 这个番茄钟不一样

市面上的番茄钟解决的是**"计时"**问题，但用户真正的痛点是：

痛点	现有方案	TomatoTimer 的解法
做完番茄就过去了，不记得产出	只计数，不记录	专注日记（v1.5）：每次完成自动记录做了什么
不知道一天/一周时间花在哪	无数据沉淀	时间报告（v1.5）：按日/周/月自动生成
没办法回顾自己的专注模式	无分析能力	AI 洞察（v2.0）：分析你的高效时段与规律

一句话定位：不只是一个计时器，而是你的专注产出记录仪。

---

📸 预览

v0.1 首版界面 — 轻柔番茄红配色，环形进度环，响应式布局

截图占位：正式截图将在 v1.0 完成后补充，见 docs/screenshots/

（截图待补充）

---

🚀 快速开始

无需构建，无需依赖，双击即用：

git clone https://github.com/<your-username>/TomatoTimer.git
cd TomatoTimer

然后：

• Windows：双击 index.html，或在项目目录执行 start index.html
• macOS：open index.html
• Linux：xdg-open index.html

如需本地 HTTP 服务器（v1.0+ 的 PWA 需要）：

# 任选其一
npx serve .
python -m http.server 8000

---

🗺️ 路线图（Roadmap）

版本	状态	核心能力	说明
v0.1	✅ 已发布	单文件基础版：25 分钟倒计时、开始/暂停/重置、环形进度环、专注/休息切换、完成音效	验证可行性
v1.0	🚧 开发中	工程化重构、自定义时长、暗色模式、系统通知、键盘快捷键、PWA、响应式	产品级：能给别人用
v1.5	📋 规划中	专注日记：每次完成记录产出、历史列表、周视图、CSV 导出	差异化核心
v2.0	📋 规划中	AI 报告：兼容 OpenAI 格式 API，自动生成每日/每周专注总结	智能分析
v2.5	📋 规划中	Vercel 部署上线、SEO、图标完善	上线可用

完整规划详见 番茄钟项目.md。

---

🧱 技术栈

层	选型	原因
前端	原生 HTML + CSS + JavaScript	零依赖、部署简单、性能好
存储	localStorage	纯前端、无需后端、用户数据在自己手里
AI（v2.0）	OpenAI 兼容 API	用户可自配 Key（Claude / DeepSeek / 通义千问等）
部署（v2.5）	Vercel	免费、git push 自动部署、自带 HTTPS
PWA（v1.0）	manifest.json + Service Worker	可安装到桌面、离线可用

核心承诺：零 npm 依赖、零构建工具、单文件也能跑。

---

📁 项目结构

v0.1（当前）— 单文件

TomatoTimer/
├── index.html              # 所有代码在此
├── 番茄钟项目.md            # 完整路线图与 v1.0~v2.5 详细规划
├── README.md
├── LICENSE
├── CHANGELOG.md
├── .gitignore
├── .env.example            # AI Key 占位（供 v2.0 使用）
└── _workflow/              # 开发过程文档（透明化记录）

v1.0（规划）— 工程化

TomatoTimer/
├── index.html
├── manifest.json           # PWA 配置
├── sw.js                   # Service Worker
├── css/
│   └── style.css
├── js/
│   ├── app.js              # 主入口 + 键盘快捷键 + 通知
│   ├── timer.js            # 计时器核心
│   └── settings.js         # 设置面板
└── assets/
    └── icons/
        ├── icon-192.png
        └── icon-512.png

---

🎨 设计原则

• 轻柔放松：番茄红主色调 + 暖色背景，避免视觉疲劳
• 零依赖：不引入任何 CDN、构建工具、npm 包
• 本地优先：数据存 localStorage，用户完全掌控
• 可访问：遵循 WCAG，支持键盘导航、prefers-reduced-motion、系统字体缩放
• 响应式：手机、平板、桌面三档适配（375 / 768 / 1024+）

---

🔐 敏感信息处理

本仓库遵循严格的敏感信息隔离：

• ✅ .env.example — 只含占位符和注释，可提交
• ❌ .env / .env.local — 存放真实 Key，已在 .gitignore 屏蔽，不提交
• 用户填入 API Key 后，Key 仅存于本地浏览器 localStorage，永不上传

首次使用（v2.0+）：

cp .env.example .env      # 或手动创建
# 编辑 .env，把 sk-xxx 替换成你的真实 Key

---

🤝 贡献

这是一个个人练习项目，但欢迎 Issue 与 PR：

• 报 Bug / 提功能：Issues
• PR 前请先开 Issue 讨论
• 提交遵循 Conventional Commits：feat: fix: docs: refactor: 等

---

📄 License

MIT © 2026

---

English

TomatoTimer — Not just a Pomodoro timer, but a focus productivity recorder.

• 🍅 25-minute focus + 5/15-minute break with ring progress
• 📔 (v1.5) Auto-log what you accomplished after each session
• 🤖 (v2.0) AI-generated daily/weekly focus reports (OpenAI-compatible API)
• 📱 (v1.0) PWA installable, offline-capable
• 🎨 Soft tomato-red palette, keyboard shortcuts, dark mode
• 💾 100% local, zero dependencies, single HTML works standalone

See 番茄钟项目.md for the full roadmap.