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:

• - INLINECODE1
• INLINECODE2
• INLINECODE3
• INLINECODE4
• INLINECODE5
• INLINECODE6
• INLINECODE7
• INLINECODE8
• INLINECODE9

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):

• - INLINECODE10
• INLINECODE11
• INLINECODE12
• INLINECODE13
• INLINECODE14

Persist to a small JSON file so reminders survive restarts.

Update activity

On each inbound user message:

1. 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. 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:

• - INLINECODE27
• INLINECODE28

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
• INLINECODE30 → disable reminders
• INLINECODE31 → show current config + next eligible reminder window
• INLINECODE32 → update INLINECODE33
• INLINECODE34 → set INLINECODE35

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