# timer_gadget

**Repository Path**: believingheart/timer_gadget

## Basic Information

- **Project Name**: timer_gadget
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 刻刻 Timer

一个面向 Windows 10/11 x64 的常驻托盘倒计时 Gadget。启动程序只会进入托盘后台并显示今日 Dock；按 `Win+K`、双击托盘图标、点击托盘菜单“开始计时”或点击 Gadget 的重新开始按钮，才会显示 Gadget 并开始新一轮计时。

## 使用

1. 运行 `TimerGadget-Setup-x64.msi` 完成按用户安装，无需管理员权限，也无需预装 .NET。
2. 安装后程序会写入当前用户开机启动项；下次登录自动在后台启动。
3. 按 `Win+K`、双击右下角托盘图标或使用托盘菜单“开始计时”；Gadget 会播放一个短促上扬音、先显示 `3→2→1`，再开始完整配置时长的倒计时。
4. Dock 常驻 Gadget 所在显示器的屏幕边缘；程序启动或正常完成一次 Gadget 后，未悬停时显示本轮提醒周期，悬停时展开为今日活动总览。
5. 右键托盘图标并选择“设置”，可配置 `10–3600` 秒、`5–240` 分钟久坐提醒间隔、呼出音效、久坐提醒强度和今日时间轴起点；倒计时必须严格短于提醒间隔，保存后当前倒计时继续使用旧时长，久坐提醒间隔立即应用到当前周期。
6. 设置窗口左下角的“清空今日状态”经二次确认后，会停止当前倒计时并删除今天 00:00 至现在的活动记录。
7. 鼠标指针位于 Gadget 上时滚动滚轮，可在 70%–180% 范围内整体缩放界面；缩放比例和窗口位置会自动保存。
8. 时间轴默认停靠屏幕右侧，悬停后向屏幕内展开；悬停轨道会显示鼠标时刻附近一小时的放大预览，拖动可切换显示器及左右停靠侧。
9. 点击 Gadget 的隐藏按钮或按 `Alt+F4` 会提前结束当前倒计时并恢复呼出前的提醒周期；Dock 和托盘进程继续运行。
10. 只有托盘右键菜单中的“退出”会真正结束程序。

## 系统行为

- 程序运行时通过低级键盘钩子精确接管 `Win+K`，Windows 的“连接/投放”界面不会出现。
- 程序退出后钩子立即移除，`Win+K` 恢复为 Windows 原有功能。
- 倒计时默认 30 秒；每轮先显示三秒准备数字，准备期不消耗配置时长也不记录活动，到期动画结束后 Gadget 自动隐藏。
- 呼出音效默认开启；`Win+K`、托盘双击、托盘“开始计时”和 Gadget 重新开始每次都会从头播放，普通启动、自启动、打开设置和久坐提醒本身不发声。
- 久坐提醒默认 30 分钟、标准强度；程序启动时从当前时刻建立周期，Gadget 正常倒计时完成后从完成时刻重置周期，达到间隔后 Dock 按弱、标准或强档持续红蓝交替并横向呼吸。
- 呼出 Gadget 会暂停旧周期并停止提醒视觉；提前隐藏会恢复旧周期，正常完成则从完成时刻建立一轮完整的新周期。
- 锁屏、系统睡眠和 Gadget 活动期间不累计久坐时间，解除全部暂停原因后从原进度继续；久坐周期不跨进程重启保存，每次启动从当前时刻重新计算。
- 程序启动后立即进入正常跟踪；未悬停时显示提醒周期，Gadget 活动、悬停、无周期或提醒触发时显示今日总览。
- 提醒周期从上到下演进，唯一的 `Notched` 肩台箭头上方为绿色、下方为灰色；右侧 Dock 露出箭头左半边，左侧 Dock 露出箭头右半边，箭头始终朝下。
- 今日时间轴默认从 08:00 开始，到 24:00 结束；灰色表示未活动或未来时段，绿色表示计时活动时段，浅色横线表示当前时间。
- Dock 折叠时为屏幕边缘窄条，鼠标移入后切换今日总览并显示起点、当前时间和 24:00；它不占用 Windows 工作区。
- Dock 显示期间会借助每秒周期刷新恢复到当前用户桌面的置顶层首位，过程不激活窗口、不移动也不改变尺寸；UAC、安全登录和锁屏等独立安全桌面不属于覆盖范围。
- 今日时间轴折叠时保持 6 DIP 细轨；鼠标移入后轨道以半透明方式加宽到 46 DIP，覆盖 Dock 的可见内容区，同时保留下层全天刻度。
- 悬停今日轨道时，Dock 内侧会显示固定 60 分钟的灰绿放大预览；靠近今日起点或 24:00 时整体平移范围，始终保留完整一小时。
- 预览会合并重叠或首尾相接的绿色活动段，并显示该小时内的连续活动次数和总耗时；轨道只保留灰绿活动语义，不绘制指向线或横向网格线。预览窗不抢焦点、不接收鼠标，也不进入任务栏。
- 最近活动 Pie 固定表示当前时刻向前严格 60 分钟；12 点方向是一小时前，时间顺时针演进一整圈到当前时刻，深灰表示空档，深绿表示活动，没有活动时隐藏 Pie。
- 清空今日状态会立即隐藏 Gadget，但今日停靠时间轴保持显示并刷新；跨越午夜的活动只保留午夜前部分。
- 安装或覆盖升级会结束旧的后台进程；正在运行的倒计时不会跨升级保留，重新启动后久坐周期从当前时刻计算，但注册表设置、活动历史、缩放和窗口位置保持不变。
- 同一版本的验收包会执行覆盖升级，不会在“已安装的应用”中增加并列产品项；安装完成后需要重新启动程序。
- 设置保存在 `HKCU\Software\TimerGadget`。
- 开机启动项保存在 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`。
- 日志位于 `%LOCALAPPDATA%\TimerGadget\Logs`，不记录按键内容。

## 构建

需要 Windows x64 与 .NET 9 SDK。WiX 6 依赖会通过 NuGet 自动恢复。

```powershell
powershell -ExecutionPolicy Bypass -File scripts\Build-Installer.ps1
```

构建脚本依次执行 Release 测试、自包含单文件发布和 MSI 构建。输出位于：

- `artifacts\publish\TimerGadget.exe`
- `artifacts\installer\TimerGadget-Setup-x64.msi`

## 验收清单

- 按 `Win+K` 后 Gadget 出现并重置，系统投放界面不出现。
- 普通启动只显示托盘和 Dock，并从当前时刻建立久坐周期；程序运行时再次启动也保持静默，且始终只有一个后台进程。
- 双击托盘图标、菜单“开始计时”和 Gadget 重新开始按钮都能开始新一轮。
- 四个显式计时入口各播放一次短促上扬音；设置关闭音效后全部静音，普通启动和打开设置始终不播放。
- 每轮先依次显示 3、2、1，再从完整配置时长开始倒计时；准备期不新增活动记录。
- 隐藏或关闭全部窗口后进程继续驻留托盘。
- 设置只能从托盘右键菜单进入；倒计时期间保存新时长不重置当前轮，新时长从下一轮生效。
- 久坐提醒间隔可输入 5–240 的任意整数分钟，`−/+` 每次调整 5 分钟；倒计时等于或长于提醒间隔时禁止保存。
- 久坐提醒强度可选择弱、标准、强；程序启动或正常完成后周期从顶部开始，箭头随有效时间向下移动，到期后 Dock 切回今日总览并以对应颜色、速度和横向幅度持续呼吸。
- 锁屏和睡眠等待不触发久坐提醒，解锁或唤醒后按剩余时间继续。
- 呼出 Gadget 后旧周期冻结且提醒视觉停止；提前隐藏恢复原进度，正常完成从新的完成时刻建立完整周期。
- 清空今日状态需要二次确认；确认后停止倒计时、删除当天活动并隐藏 Gadget，今日停靠时间轴仍保持显示。
- Gadget 仅包含倒计时圆环和右侧“重新开始”“隐藏”两个按钮，70%–180% 缩放下无重叠。
- 最近活动 Pie 位于倒计时环内，时间顺时针演进，灰色空档和绿色活动扇区比例正确；没有最近活动时不显示。
- Dock 可左右停靠、悬停展开并跨显示器拖动；右侧只露向下 `Notched` 箭头左半边，左侧只露右半边，箭头上绿下灰且暂停时不移动。
- 未悬停时显示提醒周期；悬停、Gadget 活动、无周期和提醒触发时显示今日总览，切换过程无闪烁且今日预览仍可命中。
- 左右停靠的折叠细轨均贴近屏幕外侧；悬停后半透明轨道加宽到 46 DIP，覆盖完整可见内容区且下层刻度仍清晰可读。
- 悬停今日轨道任意位置会在 Dock 内侧显示一小时放大预览；顶部、中部、底部范围、15 分钟刻度、灰绿活动段、连续活动次数与总耗时正确，预览中没有白色指向线或灰色横向网格线，移出轨道后立即隐藏。
- Gadget 隐藏或倒计时结束后，今日时间轴仍保持显示。
- 使用普通窗口或其他置顶窗口覆盖 Dock 后，Dock 最多一秒内重新显示在上方，当前前台窗口的焦点、Dock 停靠位置和尺寸保持不变。
- 最后五秒变为珊瑚红，到零后窗口自动淡出。
- 开机启动菜单可切换，并在重新登录后生效。
- 安装和覆盖升级会结束旧后台进程，升级后重新启动会从当前时刻建立久坐周期并可正常呼出 Gadget；重复安装同版本不会增加并列产品项，设置与活动历史保持不变。
- 卸载可完成并保留倒计时设置。

## 签名说明

本地生成的 MSI 和 EXE 未使用商业代码签名证书。Windows SmartScreen 可能显示“未知发布者”，生产分发前应使用受信任的 Authenticode 证书签名。