pomodoro

番茄钟技能

概述

用于专注工作时段的 25 分钟计时器，会将每个时段保存到 SQLite。支持历史记录跟踪、效率分析和长期模式识别。

这是一项系统技能——它提供操作个人数据系统的接口。随着命令运行、时段不断累积，上下文也会逐步建立并不断丰富。系统会通过由观察、定位、决策和行动组成的 OODA 循环学习模式，并提供越来越有价值的洞察。

心智模型：OODA 循环

使用这项技能时，需要持续运行一个循环：

1. 观察 → 检查当前状态（./pomodoro status）并查看历史记录（./pomodoro history）
2. 定位 → 分析数据中的模式（./pomodoro stats --period week）
3. 决策 → 确定最佳行动（例如：“上午时段的完成率为 95%——安排在这时进行深度工作”）
4. 行动 → 开始时段（./pomodoro start）、提供建议并庆祝里程碑

每个循环都会基于累积的数据展开，让洞察随着时间推移更有价值。

依赖项

• 二进制文件位置：~/.claude/skills/pomodoro/pomodoro
• 数据库：首次运行时自动创建于 ~/.claude/skills/pomodoro/pomodoro.db
• 无需外部依赖项

快速决策树

User task → What kind of request?
   ├─ Start focused work → Check status first, then start session
   ├─ Check current timer → Use status command
   ├─ Review productivity → Use stats command (day/week/month/year)
   ├─ View past sessions → Use history command
   └─ Stop early → Use stop command

核心命令

查看所有可用选项：运行 ./pomodoro --help 或 ./pomodoro <command> --help

开始一个时段

开始一个番茄钟时段：

# Traditional 25-minute Pomodoro
./pomodoro start --task "Refactor authentication module"

# Custom durations and cycles
./pomodoro start --task "Quick review" --work 5 --break 3 --cycles 2
./pomodoro start --task "Deep focus" --work 50 --break 10 --cycles 1

# Flash cards (rapid cycles)
./pomodoro start --task "Flash cards" --work 2 --break 1 --cycles 5

选项：

• --work <minutes> - 工作时长（默认值：25）
• --break <minutes> - 休息时长（默认值：5）
• --cycles <count> - 工作与休息的轮数（默认值：1）

行为：

• 同一时间只能运行一个时段
• 计时器在前台运行，每分钟显示一次进度
• 工作时段结束后自动开始休息
• 如果还有剩余轮次，休息结束后自动开始下一个工作时段
• 每个工作时段都会单独保存到数据库

JSON 输出示例：

./pomodoro start --task "Write docs" --json
# Returns: {"status": "started", "task": "Write docs", "duration": 25, "started_at": "2025-10-22T14:30:00Z"}

检查状态

查看计时器是否正在运行：

./pomodoro status
./pomodoro status --json  # For programmatic use

输出示例：

Active session: "Write documentation"
Started: 2:30 PM
Time remaining: 18 minutes

查看历史记录

查看之前的时段：

./pomodoro history --days 7    # Last 7 days
./pomodoro history --days 30   # Last 30 days
./pomodoro history --json      # For programmatic use

输出包括：

• 任务名称
• 开始和完成时间
• 时长
• 完成状态（已完成或提前停止）

分析效率

从累积的数据中获取洞察：

./pomodoro stats --period day     # Today's stats
./pomodoro stats --period week    # This week
./pomodoro stats --period month   # This month
./pomodoro stats --period year    # This year
./pomodoro stats --json           # For programmatic use

统计数据包括：

• 时段总数和已完成时段数
• 完成率（完成的时段百分比）
• 专注总时长
• 一天中效率最高的时段
• 任务分布（完成次数最多的任务）

JSON 输出示例：

{
  "period": "week",
  "total_sessions": 23,
  "completed": 19,
  "completion_rate": 0.826,
  "focus_hours": 7.9,
  "productive_hours": [9, 10, 11],
  "top_tasks": ["Refactoring", "Documentation", "Code review"]
}

提前停止

在当前时段完成前结束它：

./pomodoro stop

在发生干扰或任务提前完成时使用。该时段会在数据库中标记为未完成。

基本工作流

开始专注工作

帮助用户开始番茄钟时段：

1. 检查是否有正在进行的时段：./pomodoro status
2. 如果没有，则使用合适的选项开始：
   • 传统模式：./pomodoro start --task "Deep work on authentication"
   • 自定义模式：./pomodoro start --task "Sprint planning" --work 15 --break 5 --cycles 3
   • 闪卡模式：./pomodoro start --task "Vocabulary review" --work 2 --break 1 --cycles 10
3. 向用户确认：“已为 [task name] 开始 25 分钟番茄钟。计时器正在运行。”

每日回顾

提供每日效率摘要：

1. 获取今天的数据：./pomodoro stats --period day --json
2. 解析并呈现洞察：
   • “今天完成了 6 个番茄钟（专注时长 3.0 小时）”
   • “已完成 5/6 个时段——完成率为 83%”
   • “主要工作内容：重构、文档”
   • “高效时段：上午 9-11 点”

每周分析

提供每周效率回顾：

1. 获取本周数据：./pomodoro stats --period week --json
2. 识别模式：
   • 如果有数据，与前几周进行比较
   • 记录效率最高的时段
   • 确定完成率最高的任务类型
3. 提出建议：
   • “把深度工作安排在效率最高的时段（上午 9-11 点）”
   • “编码时段的完成率为 90%，而会议为 70%——可以考虑细分任务”

长期模式识别

随着时段数据不断累积，提供越来越有价值的洞察：

经过几个时段（1-5 个）：

• “今天完成了 3 个番茄钟”
• “专注时段正在帮助你培养势头”

经过几天（5-20 个时段）：

• “9 个时段中完成了 7 个——完成率为 78%”
• “上午 9-11 点效率最高”

经过一周（20-50 个时段）：

• “本周表现出色：完成了 23 个时段，完成率为 85%”
• “效率最高的时段：上午 9-11 点（完成率 95%），相比之下，下午 2-4 点为 65%”
• “可以考虑把深度工作安排在上午”

经过一个月（50 个以上时段）：

• “编码任务：完成率为 90%”
• “文档任务：完成率为 70%”
• “可以考虑将文档工作的番茄钟缩短至 15 分钟”

经过几个月（100 个以上时段）：

• “过去 3 个月，完成率从 72% 提升至 85%”
• “星期三效率最高（完成率 92%）”
• “把下午时段限制为 15 分钟时，效率会有所提升”
• “编码任务完成的时段比文档任务多 80%”

用于识别模式的命令：

./pomodoro stats --period month --json  # Get monthly data
./pomodoro history --days 90 --json     # Review last 90 days

里程碑庆祝

在达到关键里程碑时肯定进展：

• 10 个时段：“前 10 个番茄钟已完成——习惯正在养成！”
• 50 个时段：“达成 50 个时段的里程碑——累计专注工作超过 20 小时！”
• 100 个时段：“100 个番茄钟！累计深度专注时间超过 40 小时。”
• 高完成率：“本周完成率达到 95%——专注力出色！”

查看里程碑状态：./pomodoro stats --period year --json

常见问题

已有活动时段时再次开始

❌ 不要在未先检查状态的情况下开始新时段 ✅ 应该在开始前运行 ./pomodoro status

原因：一次只能运行一个时段。在已有活动时段时开始会导致错误。

建议遵循的模式：

# Check first
./pomodoro status
# If "No active session", then start
./pomodoro start --task "New task"

任务名称缺乏描述性

❌ 不要使用含糊的名称：“工作”“杂事”“事情” ✅ 应该使用具体的名称：“重构 auth 模块”“编写 API 文档”“审查 PR #123”

原因：描述性名称有助于更好地进行分析。模式识别需要足够具体的信息，才能确定哪些任务类型效果最好。

中断长时间运行的时段

❌ 不要在时段运行期间关闭终端或终止进程 ✅ 应该在必须中断时使用 ./pomodoro stop

原因：中断的时段不会保存到数据库。使用 stop 命令记录未完成的时段。

忽视完成率信号

❌ 不要忽视某些任务类型持续偏低的完成率 ✅ 应该根据任务类型的模式调整时段时长

原因：如果文档任务的完成率为 60%，而编码任务为 90%，那么较短的时段（15 分钟）可能更适合文档工作。

识别方法：

./pomodoro stats --period month --json
# Review completion rates by task type
# Suggest duration adjustments based on patterns

最佳实践

时段管理

• 使用描述性任务名称，以便更好地进行分析
• 尽可能完成完整的 25 分钟
• 在时段之间休息
• 根据任务类型调整时长（使用 --work 标志）
• 如果受到干扰，请明确停止（不要让进程被终止）

用户交互

• 庆祝里程碑（10、50、100、250、500 个时段）
• 肯定完成率：“专注力出色——本周完成率达到 90%！”
• 根据历史数据建议最佳时段
• 鼓励保持练习
• 指出进步：“完成率从 75% 提升至 85%”

数据分析

• 每天结束时查看每日统计数据
• 检查每周规律，获取日程安排建议
• 跟踪长期趋势（按月、按年）
• 使用 JSON 输出进行自定义分析
• 交叉对比任务类型与完成率
• 找出效率最高的时段

命令组合

组合多个命令，获取更深入的分析：

# Morning check-in: status + daily stats
./pomodoro status
./pomodoro stats --period day

# Weekly review: history + stats
./pomodoro history --days 7 --json
./pomodoro stats --period week --json

# Long-term analysis: monthly trends
./pomodoro stats --period month --json
./pomodoro history --days 90 --json

技术说明

JSON 输出

所有命令都支持 --json 标志，以便通过程序访问：

./pomodoro status --json
./pomodoro history --json
./pomodoro stats --json

以下情况请使用 JSON 输出：

• 以编程方式解析数据
• 构建自定义分析
• 将数据传入其他工具
• 需要结构化输出

数据库

• 位置：~/.claude/skills/pomodoro/pomodoro.db
• 格式：包含单个 sessions 表的 SQLite 数据库
• 持久性：所有会话都会永久保存
• 增长：数据库会随使用而增长（每个会话约 100 bytes）
• 分析：随着数据积累，可获得更丰富的分析结果
• 维护：无需清理或归档

架构：

CREATE TABLE sessions (
  id INTEGER PRIMARY KEY,
  task TEXT NOT NULL,
  duration INTEGER NOT NULL,
  started_at TEXT NOT NULL,
  completed_at TEXT
);

计时器行为

• 在前台进程中运行（会阻塞终端）
• 工作时段内每分钟显示一次进度
• 休息时段内每分钟显示一次进度
• 自动按工作 → 休息 → 工作的顺序切换
• 每个工作时段都会单独保存到数据库
• 支持通过标志自定义时长

会话流程示例（3 个周期）：

Work 25min → Break 5min → Work 25min → Break 5min → Work 25min → Break 5min → Done

结果：数据库中有 3 条独立记录（每个工作时段一条）

二进制文件位置

• 路径：~/.claude/skills/pomodoro/pomodoro
• 始终使用：从技能目录运行时使用 ./pomodoro
• 完整路径：从任何位置运行时使用 ~/.claude/skills/pomodoro/pomodoro

从技能目录运行：

cd ~/.claude/skills/pomodoro
./pomodoro start --task "Task name"

系统技能模式实践

此技能展示了系统技能模式（CLI + SKILL.md + 数据库）：

1. CLI 二进制文件：提供操作系统的接口，可启动会话、查询历史记录、分析规律
2. SKILL.md：用于 OODA 循环（观察 → 定向 → 决策 → 行动）的操作流程
3. SQLite 数据库：持久化记忆，每个会话都会增添上下文

关键见解：借助这三个组件，技能驱动的是一个系统，而不只是响应请求。每次交互都以前一次为基础。分析结果会越来越丰富，洞察会越来越精准，工具的价值也会不断累积。

价值累积示例：

• 第 1 周：“启动了 5 个会话”
• 第 4 周：“上午时段的完成率为 95%。下午为 70%。建议将深度工作安排在上午。”
• 第 3 个月：“编码任务的完成率为 90%。文档任务为 72%。尝试将文档工作安排为 15 分钟的时段。”

这种模式适用于任何数据积累能够增加价值，且为 Claude 提供操作系统的接口比一次性响应更有用的技能。

另请参阅：README.md，了解更深入的技术细节和实施指南。