Focus Break Reminder

Implement a lightweight per-user/session state machine that triggers rest reminders without spamming.

Configure

Create or load references/config.example.json as the default schema.

Required settings: - enabled - timezone - work_minutes - cooldown_minutes - idle_reset_minutes - daily_max_reminders - quiet_hours - snooze_until - templates

Prefer defaults that are practical and non-intrusive: - work interval: 50 minutes - cooldown: 30 minutes - idle reset: 15 minutes - daily cap: 4

Track state

Maintain minimal state per user (or per DM/chat for first version): - session_start_at - last_active_at - last_remind_at - remind_count_today - today_key

Persist to a small JSON file so reminders survive restarts.

Update activity

On each inbound user message: 1. If date changed in configured timezone, reset remind_count_today and today_key. 2. If idle time since last_active_at >= idle_reset_minutes, reset session_start_at to now. 3. Set last_active_at to now.

Evaluate reminder eligibility

Only remind when all conditions pass: 1. enabled is true. 2. Not in quiet hours. 3. Not snoozed (now < snooze_until means skip). 4. Daily cap not exceeded. 5. Active duration (now - session_start_at) >= work_minutes. 6. Cooldown passed (now - last_remind_at) >= cooldown_minutes.

If all pass, send one reminder and set: - last_remind_at = now - remind_count_today += 1

Reminder delivery

Use one short template per reminder. Keep copy practical and non-medical.

Example template: - “你已经连续工作一段时间了。现在起身 2 分钟、喝口水，再看 20 秒远处 👀”

Commands

Support these chat commands: - /break on → enable reminders - /break off → disable reminders - /break status → show current config + next eligible reminder window - /break set <minutes> → update work_minutes - /break snooze <minutes> → set snooze_until = now + minutes

Validate numeric ranges (e.g., 15–180 for work interval).

Heartbeat integration

Use heartbeat polling to run eligibility checks when there is recent activity. Avoid noisy polling loops.

Recommended behavior: - If no user activity for a long period, skip checks. - If reminder was just sent, honor cooldown and return quickly.

Safety and UX boundaries

• Do not provide medical diagnosis or treatment advice.
• Keep reminders optional and easy to disable.
• Store only minimum timestamps and settings needed for reminder logic.
• Use clear language when data is missing: “待补充”.

Testing checklist

Use references/test-cases.md.

At minimum verify: - triggers at/after work interval - cooldown suppresses duplicates - idle reset restarts session timer - quiet hours suppress reminders - snooze suppresses reminders until expiry - daily cap blocks additional reminders