# rhythm-windows

**Repository Path**: yz89/rhythm-windows

## Basic Information

- **Project Name**: rhythm-windows
- **Description**: Windows 版「专注-休息」节奏提醒工具
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-28
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Rhythm Windows 使用文档

> Windows 版「专注-休息」节奏提醒工具，功能与 [macOS 版 Rhythm](https://github.com/xiao2dou/rhythm) 完全一致。

## 功能概览

| 功能 | 说明 |
|------|------|
| 专注计时 | 可设置 10~120 分钟专注间隔（5 分钟步进） |
| 休息提醒 | 全屏半透明遮罩 + 倒计时，按 `ESC` 可跳过 |
| 不休息模式 | 到点自动跳过并记录，不弹出遮罩 |
| 锁屏重置 | 检测到 Windows 锁屏后自动重置计时周期 |
| 会话记录 | 保存每次休息的计划时长、实际时长、是否跳过 |
| 系统托盘 | 常驻系统托盘，右键查看状态和操作菜单 |
| 开机启动 | 支持开启/关闭登录时自动启动 |

## 安装

### 环境要求

- Windows 10 / 11
- Python 3.10 或更高版本

### 安装步骤

1. 打开终端（PowerShell 或 CMD），进入项目目录：

```bash
cd D:\claude\rhythm-windows
```

2. 安装依赖：

```bash
pip install -r requirements.txt
```

需要安装的依赖：
- `pystray` — 系统托盘图标
- `Pillow` — 图标生成

## 启动

```bash
python rhythm.py
```

启动后系统托盘（任务栏右下角）会出现一个蓝色圆形 **R** 图标。

> 首次运行可能被 Windows 安全中心拦截，选择「允许」即可。

## 使用说明

### 查看状态

鼠标悬停在托盘图标上，会显示当前状态：

- **专注中** — 显示距离下次休息的倒计时，如 `专注中 - 距休息 25:00`
- **专注中（不休息）** — 不休息模式下的专注状态
- **休息中...** — 休息遮罩已弹出

### 右键菜单

右键点击托盘图标，弹出操作菜单：

```
┌─────────────────────────────────┐
│  专注中 - 距休息 25:00         │  ← 当前状态（灰色，不可点击）
├─────────────────────────────────┤
│  节奏设置                       │
│    ├─ 专注间隔: 30 分钟         │
│    │    ├─ −（减少）            │
│    │    └─ +（增加）            │
│    └─ 休息时长: 1 分钟          │
│         ├─ −（减少）            │
│         └─ +（增加）            │
├─────────────────────────────────┤
│  ✓ 不休息模式                   │  ← 点击切换开/关
│  ✓ 开机启动                     │  ← 点击切换开/关
├─────────────────────────────────┤
│  立即休息                       │  ← 专注中显示
│  重置计时                       │
├─────────────────────────────────┤
│  最近记录                       │
│    ├─ 03-28 09:15  完成 01:00   │
│    ├─ 03-28 08:45  跳过 00:03   │
│    └─ ...                       │
├─────────────────────────────────┤
│  退出                           │
└─────────────────────────────────┘
```

### 节奏设置

#### 专注间隔

- 范围：10 ~ 120 分钟
- 步进：5 分钟
- 默认值：30 分钟
- 修改后立即生效，重新开始计时

#### 休息时长

可选档位（秒）：

| 档位 | 30s | 1min | 1.5min | 2min | 3min | 4min | 5min | 10min |
|------|-----|------|--------|------|------|------|------|-------|
| 秒数 | 30  | 60   | 90     | 120  | 180  | 240  | 300  | 600   |

- 默认值：60 秒（1 分钟）
- 修改后立即生效

### 不休息模式

开启后，专注倒计时到点时：
- **不会**弹出休息遮罩
- 自动记录为一条「不休息」会话
- 立即开始下一轮专注计时

适用场景：开会、深度编码等不适合中断的情况。

### 休息遮罩

专注倒计时结束后，弹出全屏半透明黑色遮罩：

```
┌──────────────────────────────────────────┐
│                                          │
│                                          │
│              休息时间                     │
│                                          │
│               00:58                      │
│                                          │
│          按 ESC 跳过本次休息              │
│                                          │
│             [ 跳过 ]                     │
│                                          │
│                                          │
└──────────────────────────────────────────┘
```

操作方式：
- **等待倒计时结束** — 记为「完成」，实际休息时长 = 倒计时消耗时间
- **按 `ESC` 键** — 记为「跳过」，记录已休息的时间
- **点击「跳过」按钮** — 同按 `ESC`

### 立即休息 / 跳过休息

- **专注中**：菜单显示「立即休息」，点击立即进入休息
- **休息中**：菜单显示「跳过休息」，点击跳过当前休息

### 重置计时

点击后重置当前专注倒计时，从零开始重新计时。

### 锁屏重置

当 Windows 锁屏时（`Win + L` 或自动锁屏）：
- 当前计时周期自动重置
- 解锁后从零开始新的专注周期
- 如果正在休息，休息遮罩会关闭

### 最近记录

菜单底部显示最近 5 条休息记录，格式：

```
MM-DD HH:MM  结果 实际时长
```

结果类型：
- **完成** — 倒计时正常结束
- **跳过** — 按 ESC 或点击跳过
- **不休息** — 不休息模式下自动跳过

## 数据存储

所有数据保存在 `%APPDATA%\Rhythm\` 目录下：

```
%APPDATA%\Rhythm\
├── settings.json     ← 用户设置
└── sessions.json     ← 休息记录（最近 100 条）
```

### settings.json 示例

```json
{
  "focusMinutes": 30,
  "restSeconds": 60,
  "skipRestEnabled": false
}
```

### sessions.json 示例

```json
[
  {
    "id": "a1b2c3d4-...",
    "scheduledRestSeconds": 60,
    "actualRestSeconds": 58,
    "startedAt": "2026-03-28T09:15:00.123456",
    "endedAt": "2026-03-28T09:15:58.123456",
    "skipped": false,
    "skipReason": null,
    "createdAt": "2026-03-28T09:15:58.123456"
  }
]
```

## 开机启动

通过 Windows 注册表实现：

- 注册位置：`HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run`
- 注册名称：`Rhythm`
- 在菜单中点击「开机启动」即可切换开/关

> 注意：开机启动的命令指向当前 `rhythm.py` 的路径。如果移动了项目目录，需要重新开启。

## 常见问题

### 托盘图标不显示？

部分 Windows 11 版本会隐藏新应用的托盘图标。点击任务栏右下角的 `^` 展开隐藏图标，即可看到 Rhythm。

### 休息遮罩没有置顶？

如果其他全屏应用（如游戏）覆盖了遮罩，按 `Alt + Tab` 切换到遮罩窗口即可。

### 如何彻底清除数据？

删除 `%APPDATA%\Rhythm\` 文件夹即可：

```bash
rmdir /s /q "%APPDATA%\Rhythm"
```

### 如何停止应用？

右键托盘图标 → 退出。或在终端中按 `Ctrl + C`。