clock 复现与重构方案

更新时间：2025-11-11 作者：Lifu

---

概述

clock 是一个 Windows 防睡眠工具，提供 CLI 与 GUI 两种形态，支持两种防睡眠方式（模拟鼠标/系统 API），集成系统托盘、配置管理、日志记录，并新增“任务栏自动隐藏”控制。本文给出复现与重构的可操作路线。

目录与模块（来自源码/README）

• keep_awake_core.py：核心循环与防睡眠方法选择（定时器）
• keep_awake_gui.py / keep_awake_cli.py：GUI/CLI 入口
• config_manager.py：配置加载/默认值/兼容处理
• log_manager.py：控制台与文件日志（滚动）
• taskbar_manager.py：任务栏自动隐藏开关（注册表+重启 Explorer）
• system_activity_checker.py / power_activity_analyzer.py：系统/电源活动检测
• 启动脚本：start_gui.bat、start_cli.bat
• 依赖：PyQt6（GUI）

环境与依赖

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
# requirements.txt 摘要：PyQt6>=6.4.0（可选：pyautogui）

运行与验证

• GUI：python keep_awake_gui.py
• CLI：python keep_awake_cli.py
• 托盘：关闭窗口应最小化到托盘；双击恢复
• 任务栏自动隐藏：GUI 勾选后即时生效；如需重启 Explorer 会自动处理
• 日志：控制台精简、文件详细（滚动策略）

配置要点

• 默认值健壮：缺失字段按默认；旧版配置向后兼容
• 关键项：防睡眠间隔、方法选择（鼠标/系统 API/两者）、任务栏自动隐藏开关、日志级别与文件大小限制

重构/复现计划（建议里程碑）

• M1 最小可用（1-2 天）
• 复现核心 KeepAwake 与 CLI；两种方法可切换；日志与默认配置
• 单测覆盖核心状态流转（start/stop/is_running）
• M2 GUI 与托盘（1-3 天）
• GUI 主面板与托盘菜单；状态切换、日志查看、配置保存/加载
• 引入 taskbar_manager 提供自动隐藏开关，统一异常提示与日志
• M3 工程化（1-2 天）
• 日志滚动与等级统一；打包脚本（pyinstaller 可选）；错误矩阵与排障

验收清单

• 连续运行 30 分钟稳定，CPU/内存占用可接受
• 两种防睡眠方式均生效；GUI/托盘交互正确
• 任务栏隐藏/恢复成功，设置可持久化
• 单测通过（核心逻辑、配置、关键异常）

一键复现（示例）

cd C:\Users\lifu.liu\clock
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python keep_awake_gui.py

依赖与版本（精确）

# 防睡眠工具依赖列表

# GUI界面依赖
PyQt6>=6.4.0

# 可选：如果需要更好的鼠标控制，可以安装 pyautogui
# pyautogui>=0.9.54

# 开发和测试依赖（可选）
# pytest>=7.0.0
# pytest-qt>=4.2.0
# black>=22.0.0
# flake8>=5.0.0

配置文件（当前示例：keep_awake_config.json）

{
  "interval": 10,
  "method": 0,
  "autostart": false,
  "minimize_to_tray": true,
  "taskbar_autohide": false
}

• 配置文件路径：项目根目录下的 keep_awake_config.json
• 兼容性说明：config_manager 会对不合法的字段进行校正。例如 method 仅接受字符串值：mouse / api / both。当配置为数字（如 0）或其他非法值时，会自动调整为 both。

参数与默认值说明

• interval（执行间隔，秒）
• 默认值：60（代码默认），最小 10，最大 3600；示例文件使用 10
• method（防睡眠方法）
• 可选：mouse（移动鼠标）/ api（Windows API）/ both（两者）
• 默认值：both
• autostart（开机自启）：默认 false
• minimize_to_tray（最小化到托盘）：默认 true
• start_minimized（启动即最小化）：默认 false（未出现在示例文件中时按默认处理）
• taskbar_autohide（任务栏自动隐藏开关）：默认 false