WindowTimePlug

WindowTimePlug 是一个面向 Windows 桌面的倒计时插件。当前项目以 Win10 兼容性为第一优先，运行时使用 .NET Framework 4.8 + GDI+ + layered window 自绘链路，让组件能够稳定挂在已经验证过的桌面层上，并尽量在 Win + D 后保持正确显示。

先看哪里

如果你是第一次接手这个项目，建议先按这个顺序阅读：

1. AGENTS.md
2. docs/ENGINEERING_HANDOFF.zh-CN.md
3. scripts/package_release.ps1
4. WindowTimePlug.App/Services/WidgetController.cs
5. WindowTimePlug.App/Widgets/DesktopWidgetWindow.cs

当前产品方向

• 这是“桌面插件”，不是普通倒计时窗口。
• 视觉方向是“轻透玻璃分组”，但不追求依赖系统模糊 API 的高风险效果。
• Win10 可读性、稳定性、耐看性优先于截图效果。
• 当前已经明确放弃背景截图式伪透明。
• 当前保留现有桌面宿主方案，即使它会显示在桌面图标/文件之上。

关键文档

• AGENTS.md
  • 给后续 AI / 工程接手者的短操作规则
• docs/ENGINEERING_HANDOFF.zh-CN.md
  • 需求动机、设计推理、系统结构、构建链路、踩坑记录、修改边界

工程结构

• WindowTimePlug.App
  • 桌面应用、托盘、设置窗口、桌面组件自绘
• WindowTimePlug.Core
  • 倒计时计算、配置模型
• WindowTimePlug.Core.Tests
  • 配置与规则测试
• scripts/package_release.ps1
  • 唯一推荐的打包入口
• installer/WindowTimePlug.iss
  • Inno Setup 安装器脚本

开发命令

本地调试：

dotnet build .\WindowTimePlug.App\WindowTimePlug.App.csproj -c Debug
dotnet test .\WindowTimePlug.Core.Tests\WindowTimePlug.Core.Tests.csproj

推荐发布流程：

powershell -ExecutionPolicy Bypass -File .\scripts\package_release.ps1

脚本执行完成后会直接打印：

• WindowTimePlug.exe 的文件路径
• WindowTimePlug.exe 所在目录
• portable zip 的文件路径
• portable zip 所在目录

为什么必须用脚本打包

这个项目的发布不是单纯 dotnet build 就够了，因为过去反复踩过以下问题：

• WindowTimePlug.exe 正在运行导致输出文件被锁
• 便携包压缩时，刚生成的输出目录文件仍然被占用
• 开发者忘记先跑测试

当前脚本已经处理这些问题，固定流程如下：

1. 检测并结束 WindowTimePlug.exe
2. 等待进程退出
3. 执行 dotnet test
4. 执行 dotnet build -c Release
5. 生成 dist/WindowTimePlug-Portable.zip
6. 如果本机有 ISCC.exe，继续构建安装器

如果本机没有 Inno Setup，脚本仍然会成功完成，并保留 portable zip 作为发布产物。

运行时配置

配置文件写入：

• %AppData%\WindowTimePlug\config.json

主要字段包括：

• title
• subtitle
• targetLocalTime
• showHours
• showMinutes
• showSeconds
• theme
• position
• locked
• runAtStartup
• desktopMode

当前特别重要的约束

• 不要重新引入背景截图式透明
• 不要用整窗 alpha 来控制玻璃透明度
• 不要轻易重写桌面宿主挂载策略
• 默认位置现在是“右上角锚定”
• 用户拖拽后会切换为手动位置，不应再被默认逻辑覆盖

产物位置

• Release 主程序：
  • WindowTimePlug.App\bin\Release\net48\WindowTimePlug.exe
• 便携包：
  • dist\WindowTimePlug-Portable.zip

维护要求

后续如果改了以下任一内容，请同步更新 AGENTS.md 与 docs/ENGINEERING_HANDOFF.zh-CN.md：

• 桌面宿主策略
• 透明渲染链路
• 默认位置逻辑
• 打包脚本
• 图标系统
• 兼容性策略