文档

⏱ 60 分钟专注循环

采用固定 60 分钟学习周期。60 分钟结束后进入 5 分钟请辨倒计时，浮层展示一条随机请辨金句，帮助你在休息前回顾学习内容。请辨结束后进入 5 分钟休息，休息结束后自动打开 B 站收藏夹视频。

每 3 轮休息后自动打开护眼视频（BV14Y4y1N7PW），缓解长时间用眼疲劳。

👁 20-20-20 护眼提醒

遵循眼科推荐的 20-20-20 法则：每学习 20 分钟，弹出轻量浮窗提醒看 6 米外 20 秒。浮窗 15 秒后自动消失，不打断学习流。可拖动到任意位置，下次启动记住位置。

📊 学习时长追踪与打卡

每次 60 分钟倒计时完成自动累计 1 小时学习时长。每日学习满 4 小时完成打卡。

• 连续打卡：每日达标自动累计，中断后从零开始
• 里程碑金句：连续 1/3/7/14/30/60/90/365 天触发专属激励文案
• 数据持久化：学习时长、休息时长、打卡记录全部存储在本地 JSON 文件
• 请辨金句：休息前展示思辨金句，每日不重复循环

📈 趋势分析

5 个标签页提供多维度学习数据分析：

🤖 AI 学习分析

基于任意 OpenAI 兼容 API，根据你的学习数据自动生成深度分析报告。支持 日报/周报/月报/季报/年报 五级报告。

未配置 API Key 时自动降级为本地数据摘要报告，确保功能可用。

💡 使用技巧

🎯 学习计时

固定 60 分钟学习周期。包含 5 分钟请辨倒计时和 5 分钟休息，循环自动进行。

💬 请辨模式

休息前展示思辨金句，帮助你在休息前回顾学习内容。金句库每日不重复循环。

👁 20-20-20 护眼

每 20 分钟弹出护眼提醒浮窗，看 6 米外 20 秒，15 秒自动消失。可关闭。

📊 学习统计

开启后记录学习时长和休息时长，用于趋势分析和连续打卡。

📝 复盘提醒

每小时学习结束后弹出复盘评分弹窗，记录学科和标签。

🔊 声音提醒

休息提醒时播放提示音。休息音为轻柔两音符，倒计时结束为三音符上行琶音。

⚡ 开机自启

通过注册表实现开机自动启动。开启后程序随系统启动并在后台运行。

🤫 静默启动

启动后只显示浮球，不弹出主窗口。点击浮球弹出信息面板，显示倒计时与学习状态。

🗂 关闭最小化

关闭主窗口时最小化到系统托盘，而非退出程序。

环境要求

• Python 3.14+ — 核心依赖，必须使用 3.14 或更高版本
• PyQt5 — GUI 框架（项目 vendor/ 目录已内嵌兼容版本）
• Windows 10/11 — 使用 Win32 API（ctypes），仅支持 Windows

快速启动

git clone https://github.com/kuangketongxue/library-remind.git
cd library-remind
C:\Python314\python.exe rest_reminder.py --silent

注意：必须使用完整路径 C:\Python314\python.exe，PATH 中的 python 可能指向其他版本，导致 ImportError。

项目结构

状态机

程序基于四态循环状态机：idle → running → paused → resting → idle。所有状态转换逻辑集中在主循环的 _tick() 方法中。新增状态时需同步更新 _BTN_CONFIG、对应的 _handle_* 方法、以及主循环路由分支。

构建 EXE

pyinstaller RestReminder.spec

spec 文件已配置好 hiddenimports 和 icon。构建产物在 dist/ 目录，约 48MB。

代码规范

• 改完代码后先 py_compile 检查语法，再启动验证
• 所有数据文件使用 JSONStore 统一读写，不直接 open/write
• PyQt 数值 API 只接受 int，float 必须显式 int() 转换
• from PyQt5 import sip（不能用 import sip，3.14 不兼容）
• except 块必须有 log，不允许 bare pass

项目配置

项目已配置 CLAUDE.md 和 AGENTS.md，Claude Code 打开项目目录后会自动加载开发规则、踩坑记录和关键配置位置。无需额外配置。

开发工作流

1. taskkill /F /IM python.exe
2. C:\Python314\python.exe -c "import py_compile; py_compile.compile('rest_reminder.py')"
3. C:\Python314\python.exe rest_reminder.py --silent
4. tasklist | findstr python.exe
5. type crash.log

注意事项

程序启动后只看到浮球，主界面不显示？

正常行为。默认静默启动只显示右下角浮球，点击浮球弹出信息面板。如需启动即显示主窗口，在设置中关闭「静默启动」。

B 站收藏夹没打开？

检查设置中的 B 站收藏夹 ID（fid）和用户 ID（mid）是否正确。默认使用项目内置的收藏夹，如需更换请在设置中修改。

AI 报告生成失败？

检查设置中是否配置了 SenseNova API Key。未配置时自动使用本地数据摘要报告，不会报错。可在「关于」页面的环境诊断中检查依赖状态。

复盘评分的数据存在哪里？

所有复盘数据存储在程序同目录的 .review_log.json 中。每轮学习结束后自动追加记录，包含时间、学科、标签和评分。

如何卸载？

直接删除程序文件夹即可。如开启了开机自启，请先运行 uninstall.bat 清除注册表项，再删除文件夹。

数据会丢失吗？

所有数据存储在本地 JSON 文件，重启电脑不丢失。重装系统前建议备份程序目录下的 .daily_log.json、.review_log.json、.streak.json 等文件。

支持 macOS / Linux 吗？

目前仅支持 Windows 10/11（基于 PyQt5 和 Windows API）。macOS 和 Linux 版本正在规划中。

需要联网才能用吗？

核心功能（休息提醒、护眼、学习追踪、趋势分析）完全离线运行。只有 AI 学习分析需要联网调用 SenseNova API，其余功能全部本地可用。

连续打卡中断了怎么办？

连续打卡基于每日学习时长判断（满 4 小时算一天）。如果某天未达标，连续天数归零，最佳记录保留。第二天达标后重新开始累计。

如何成为赞助商？

我们欢迎 API 服务、工具产品或其他形式的合作。请发送邮件至 kuangketongxue@gmail.com，注明合作意向和联系方式，我们会在 3 个工作日内回复。

有哪些合作方案？

支持多种合作形式：GitHub README 广告位、应用内预置接入、官网赞助商展示、优先技术支持等。具体方案可根据赞助商的资源和需求定制。

完成洽谈后多久可以上线？

根据合作内容不同，通常 1-2 周内完成接入和上线。简单的 API 接入可更快完成，复杂的定制化合作可能需要更长时间。

赞助商可以获得什么？

赞助商可获得 GitHub README 广告位、应用内预置接入、官网赞助商展示、优先技术支持等权益。具体权益根据赞助等级和合作形式确定。

浮球不显示 / 点击无反应

按以下步骤排查：

1. 检查程序是否在运行：查看系统托盘是否有图标。
2. 右键点击托盘图标 → 选择「⚡ 显示浮球」。
3. 若托盘图标也不存在，检查是否被安全软件拦截。
4. 重启程序，确保无 crash.log 生成。

AI 报告生成失败 / 卡死

按以下步骤排查：

1. 进入「设置 → AI 服务」检查 API Key 是否配置正确。
2. 检查网络连接，确保能访问 API 端点。
3. 未配置 Key 时自动降级为本地数据摘要，不会报错。若仍异常，查看 crash.log。
4. 在「关于」页面的环境诊断中检查依赖状态。

倒计时不准 / 计时漂移

程序使用 time.perf_counter() 作为计时源，长时间运行误差极小。若发现明显不准，请确认没有通过任务管理器强制暂停 python.exe 进程。

B 站收藏夹没打开

按以下步骤排查：

1. 检查设置中的 B 站收藏夹 ID（fid）和用户 ID（mid）是否正确。
2. 确认默认浏览器可正常启动。
3. 尝试手动打开收藏夹链接：https://space.bilibili.com/529362421/favlist?fid=3648313921
4. 如收藏夹为私有，请确保账号已登录。

数据丢失 / 重装后恢复

所有数据存储在程序同目录的 .daily_log.json、.review_log.json、.streak.json。重装前请备份这些文件。