# DeskTool
**Repository Path**: ccubee/desk-tool
## Basic Information
- **Project Name**: DeskTool
- **Description**: 简易桌面工具 windows 上使用的
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-09
- **Last Updated**: 2026-11-13
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# DeskIcon · 桌面图标分类工具
把 Windows 快捷方式收进"分类分组",固定在面板里,双击即启动、拖拽即归类。
**只做引用与索引:不移动、不修改、不删除你的任何文件。**
当前版本 **v1.2.7**(2026-11-13):修自动更新——发行版接口只回附件名、不回下载地址时,不再误判"没有 exe 附件";替换脚本改用绝对路径并留 `apply_update.log`。此前 v1.2.6 去掉了时钟区天气的悬停提示条(悬停详情浮层照旧)。

## 功能(V1.0)
| 能力 | 说明 |
|---|---|
| 分组管理 | 新建 / 重命名 / 换色(8 色)/ 上移下移 / 删除;锁定后禁止拖入拖出 |
| 添加图标 | 拖入 `.lnk` `.exe` `.url` `.bat` `.cmd`、文件夹或任意文件;也可点 + 选择文件 |
| 图标提取 | Shell 256px 高清图标(IImageList JUMBO),按需缩放 32/48/64/96,PNG 磁盘缓存 |
| 启动 | 双击或右键打开;支持"以管理员身份打开"、打开所在位置 |
| 归类 | 图标可在分组之间拖拽移动;拖到窗口空白处归入第一个分组 |
| 搜索 | 按名称 / 目标路径实时过滤 |
| 固定 | 分组锁定、面板置顶、窗口几何持久化(重启还原) |
| 托盘与热键 | 关闭窗口收进托盘,`Ctrl+Alt+Space` 全局唤出 |
| 导入 | 一键把桌面上的 `.lnk` 导入"桌面快捷方式"分组(去重,不动文件) |
| **桌面小组件** | 时间/日期 + 分组图标直接贴在桌面上(压在桌面之上、被普通窗口盖住),双击图标即启动、拖动可换位置 |
| **待办提醒** | 时钟左栏「本周」待办摘要(周一~周日),点开是清单:默认看今天、可翻看本周前几天,勾选完成 / 删除 / 选日期添加,跨天自动重排 |
| **喝水提示** | 可设间隔(默认 60 分钟)与每日目标杯数(默认 8 杯),到点在屏幕底部弹卡片「已经 X 没喝水了」;点「我喝了」记一杯并显示今天第几杯 / 还差几杯,达标那天庆祝一次 |
| **下班提醒** | 工作日到点必弹「快下班啦 / 快要下班了哦,收拾收拾,好好休息~」;明天要是降温 ≥5℃、有雨雪、周五或节前,同一张卡里再加一句 |
| 自启 | 托盘菜单一键开关(仅写 `HKCU\...\Run` 一项) |
| **背景图** | 主面板 `⋯` →「外观设置…」换一张图做底:虚化 0–40px、暗色蒙版 0–90%,取景位置**直接在预览图上按住拖动**(四向箭头光标),铺满裁切统一留 10% 余量,上下左右都挪得动;只换“底”,卡片和文字仍是原来的深色面,换什么图都不影响可读性 |
| **动效强度** | 四档(安静 / 标准 / 轻快 / 关闭),和背景图在同一个对话框:图标格悬停抬升、浮层淡入上移、选中脉冲都跟着档位走 |
| 失效检测 | 目标被删除/移走时图标置灰并提示 |
| 数据安全 | 启动前自动备份 db(保留 7 份),WAL 模式 |
## 界面预览
| | |
|---|---|
| **主面板**:分组卡片 + 图标网格,双击启动、拖拽归类,底部显示「已固定几个分组 / 几个图标」
 | **桌面小组件**:贴在桌面上,按 Win+D 也不消失;左侧大号时钟 + 日期农历 + 待办摘要,右侧是当前分类的图标,滑动换分类
 |
| **天气浮层**:鼠标悬停(或点一下)时钟右边的天气,弹出当前详情(体感、湿度、风向风力)+ 今天 / 明天 / 后天预报
 | **待办清单**:点时钟下方的待办卡片展开,本周日期条默认停在今天、可翻看周一起的前几天;**点文字看完整内容**(详情卡里可标记完成/删除)、勾圆圈勾选、× 删除,顶部选日期添加
 |
| **⋯ 菜单**:小组件开关、显示哪个分组、**置顶(F4)**、待办 / 喝水 / 下班提醒、天气城市、每行图标数、时钟字体、开机自启都在这里
 | **时钟字体**:导入 .ttf / .otf / .ttc(只登记字体,不动你磁盘上的文件)+ 字号 14~72pt,带 00:00:00 实时预览
 |
| **喝水提示设置**:自绘蓝色开关(深色底上系统勾选框几乎看不见)、间隔 / 目标 / 每杯毫升 / 工作时段 / 全屏静默 / 提示音,下方直接写「下一次提醒」
 | **下班提醒设置**:工作日到点必弹「快下班啦」;天气/周末节假日只决定卡片里那句附注,可各自开关
 |
| **外观设置(背景图)**:选图 / 用当前壁纸 / 不使用;虚化、暗色蒙版、动效强度三行;中间预览图**直接按住拖动**就是取景 —— 不再有上下、左右两条位置滑杆
 | **待办详情卡**:条目文字太长会被省略号截断,点一下弹这张卡看全文 + 归属日期 + 完成状态,卡里能直接标记完成 / 取消完成 / 删除
 |

天气浮层(正常态 / 加载失败态,点天气图标即可立即重刷):
 
## 外观设置(背景图 / 虚化 / 蒙版 / 动效)
入口:主面板右上 `⋯` →「外观设置…」。主面板和桌面小组件共用同一张底图。
| 项 | 说明 |
|---|---|
| 选择图片 / 用当前壁纸 / 不使用 | 「用当前壁纸」直接把系统墙纸路径登记进来,不复制文件;「不使用」回到原来的纯色深底 |
| 虚化 | 0–40px,默认 16。0 就是原图直铺 |
| 暗色蒙版 | 0–90%,默认 45。越浓图标和文字越清楚;只盖在“底”上,卡片本身另有底色 |
| 动效强度 | 安静 / 标准 / 轻快 / 关闭 四档,全局生效(图标格悬停抬升、浮层淡入上移、选中脉冲都跟着变) |
### 取景:直接拖图,没有位置滑杆
预览图就是取景框,**按住鼠标拖**就能上下左右挪动背景图:
- 光标平时是四向箭头,按下去变抓手;往右拖 = 图往右走 = 露出左边
- 拖满一整个预览高度,取景就从最上走到最下(按预览尺寸成比例换算,不是按像素 1:1 跟手——按像素的话余量只有几十像素,拖一点点就到头)
- 滚轮在预览上滚可以微调上下
- 哪边顶到头了,那个方向就挪不动了,预览的悬停提示会说明
**为什么以前“上下滑动无效”**:铺满裁切(cover)按最大比例缩放,16:9 的壁纸放进接近 16:9 的窗口时,纵向可移动像素正好是 0,位置调节和拖动都会静默失效。现在统一多留 10% 的裁切余量(`ui/backdrop.py` 的 `OVERSCAN = 1.10`),两个方向都有几十像素可挪;代价是四周各多裁掉约 5%。
设置都落在 `deskicon.db`:`ui.bg_image` / `ui.bg_blur` / `ui.bg_dim` / `ui.bg_pos_y` / `ui.bg_pos_x` / `ui.motion`。点「保存」立即生效,不用重启;升级新版时旧的取景位置会沿用,不会跳。
## 运行(开发态)
```powershell
cd D:\ruoyi\DeskIcon
.\.venv\Scripts\python.exe main.py
```
首次运行会自动创建 `%LOCALAPPDATA%\DeskIcon\deskicon.db` 与默认分组「未分类」。
## 打包
```powershell
.\.venv\Scripts\python.exe build.py
# 产物:dist\DeskIcon.exe(单文件,无需 Python)
```
## 桌面小组件(贴在桌面上)
主面板右上 ⋯ 菜单里:
- **显示桌面小组件(时间/日期/图标)** —— 勾选后,桌面右下角出现一块面板:大号时钟 + 日期 + 快捷方式
- **桌面小组件显示哪个分组** —— 可选「显示全部分类(上下滚动)」或某一个分类
- **一屏一个分类** —— 桌面小组件右侧一次只显示一个分类:分类名 + 图标数,下面一行图标(默认每行 5 个,可设置 3~8 个)
- **时钟 + 农历** —— 大号时间(默认 32pt)+ 公历日期 + 农历(含干支年与生肖,如「农历十月初一 丙午年·马」)
- **上下滑动换分类** —— 鼠标滚轮上下滚,或在面板上按住上下拖,就切到上一个/下一个分类(带滑动动画,底部小圆点显示当前是第几个分类)
- **左右滑动看更多** —— 某个分类图标超过「每行个数」时,按住图标行左右拖(或用触摸板左右划)就能看到后面的;滑动会吸附到整格,松手后右边永远是完整图标,不会出现半个;分类名右侧的小三角提示还能往哪边看
- **设置每行图标数…** —— ⋯ 菜单里可改一行显示几个(3~8),面板宽度跟着变;在桌面上直接右键小组件同样有这一项
- **时钟字体…** —— 只要两件事:**导入字体文件**(.ttf / .otf / .ttc,只登记字体、不动你磁盘上的原文件)+ **字号**(14~72pt,带 00:00:00 实时预览);导入的字体自带字重,不再叠叠加粗;文件没了或认不出会回落到系统默认字体。面板宽度与高度按字号自动重算,字号调大不会溢出;桌面上右键小组件也能直接进这个对话框
- **天气** —— 时钟右边是自绘的天气图标 + 当前温度(晴/多云/阴/雨/雪/雾/雷各一套图形,夜间晴天变月亮);**鼠标悬停**弹出浮层:当前天气详情(体感、湿度、风向风力)+ 今天 / 明天 / 后天预报。**点一下天气图标 = 立即重新拉取**(不走 30 分钟缓存,图省事不用加按钮),浮层底部会先显示「刷新中…」再变成「更新于 14:24」;刷新失败但有旧数据时继续显示旧数据,不会把温度抹成「—」
- **设置天气城市…** —— 默认泰安,可改成任意城市(中文或拼音)
- **待办提醒(本周 周一~周日)** —— 时钟左栏底部一张待办小卡片:「N 项未完成」+ 最靠前的两条(今天/明天的用中文提示,过期未勾的显示为「逾期N天」并标红);**点卡片**展开待办清单浮层:顶部是本周日期条(周一~周日),**默认停在今天**,点前面几天(周一/周二)就能回看那天的待办;下面按「逾期未完成 / 今天 周三 11-11」分组列出,本周内已过去的日子不算逾期,可勾选完成、点 × 删除;**点条目文字弹出详情卡**,显示完整内容(条目太长会被省略号截断)+ 归属日期 + 完成状态,卡里能直接标记完成 / 取消完成 / 删除;浮层顶部输入框 + 日期下拉(本周七天)**像日历一样选日期添加**,回车即保存。卡片右上角 + 直接进入添加输入框;点面板其他地方自动收起浮层。待办只存在本地 `deskicon.db` 的 `todos` 表;跨周自动整块滑到下一周,跨天自动重算「今天/明天」与逾期
- **待办提醒开关** —— ⋯ 菜单里「桌面小组件显示待办提醒」可关掉卡片;「待办提醒…(本周)」不显示小组件也能打开同一张清单
- 双击图标即启动;按住面板空白处可拖动换位置(位置会记住);右键可打开主面板或隐藏
- **F4 置顶切换** —— 按 `F4` 在「贴在桌面层」和「浮在所有窗口最前面」之间切换(键位被别的程序占了会自动退到 `Ctrl+F4`,并写回设置里);主面板 ⋯ 菜单里也有「桌面小组件置顶(F4)」,勾选状态与热键同步。切到置顶后 Win+D 也不再把它压回桌面层,它就一直在最前面
### 换时钟字体 / 改字号(三步)
1. **打开设置**:桌面上**右键小组件** →「设置时钟字体…」;或主面板右上 ⋯ →「设置时钟字体…」。主面板缩到托盘时也能用,对话框会自己弹到前台。
2. **选字体**:点「导入字体文件…」,挑一个 `.ttf / .otf / .ttc`。程序只把这个字体**登记进当前进程**,不复制、不移动、不改名你磁盘上的原文件;想退回系统字体点「用系统默认字体」。
3. **调字号**:拖「字号」(14~72pt),上面的 `00:00:00` 是实时预览,满意了点「确定」。小组件立刻按新字体重建,左栏宽度和一屏高度跟着字号自动重算,字号调大不会把文字或图标挤出去。
字体从哪来:
- **系统自带就够用**:`C:\Windows\Fonts` 里直接拿——楷体 `simkai.ttf`、宋体 `simsun.ttc`、黑体 `simhei.ttf`、等线、Consolas、Segoe UI……把这些文件本身导入即可,不用下载。
- **免费可商用**:思源黑体/宋体(GitHub `adobe-fonts/source-han-sans`、`source-han-serif` 的 Release)、阿里巴巴普惠体(alibabafonts.com)、得意黑 Smiley Sans(GitHub `atelier-anchor/smiley-sans`)、MiSans(小米)、HarmonyOS Sans(华为)、OPPO Sans、站酷系列(站酷字体专区)、Google Fonts 里的 Inter / Orbitron 等数字字体。
- 只下**单个字体文件**,别下 `.exe` 安装包(容易捆广告);商用项目别用来源不明的网盘合集,授权说不清。
几个注意点:
- 导入的字体一般自带字重,程序**不再叠叠加粗**;用回系统默认字体时会自动恢复加粗。
- 字体文件被删/挪走,或者格式 Qt 认不出来,会自动回落到微软雅黑,面板不会崩。
- 字号太大觉得「头重脚轻」,调回 30 左右即可;每行图标数(3~8)也在同一个右键菜单里改。
- 改完不需要重启:保存后小组件当场重建,来源字体和字号记在 `deskicon.db` 的 `clock.font_file` / `clock.pt`。
### 下班提醒(每天一句「快下班啦」)
工作日到点(默认 **17:30**)必定弹一张深色卡片,不抢焦点;周末和节日当天不弹:
```
🔔 快下班啦
快要下班了哦,收拾收拾,好好休息~ [ 知道了 ]
```
明天要真有变化,就在同一张卡里多一句(下面这几项可以单独开关):
```
🔔 快下班啦
快要下班了哦,收拾收拾,好好休息~
明天最低 1℃,比今天低 8℃,记得多穿件衣服哦。 [ 知道了 ]
```
| 附注条件 | 追加的那句 |
|---|---|
| 明天最高温比今天低 ≥ 阈值(默认 5℃) | 明天最低 X℃,比今天低 Y℃,记得多穿件衣服哦。 |
| 明天有雨/雪 | 明天 X~Y℃。出门记得带伞。 |
| 明天是节假日(元旦/春节/清明/劳动节/端午/中秋/国庆) | 明天是中秋节,假期到了,好好休息哦~ |
| 今天周五(明天周六) | 周五啦,明天就是周末,好好休息哦~ |
- **每天必弹**:主文案固定是「快下班啦 / 快要下班了哦,收拾收拾,好好休息~」,不再等天气变化,也不会因为「昨天已经用掉名额」而整天静默。
- **拉不到天气也弹**:天气只用来决定那句附注,网络挂了照样弹主文案,只是没有附注。
- **一天只弹一次**:弹完就把日期记在 `advice.last`,重启也不会重弹;只在工作日说,周六周日和节日当天不打扰。
- **入口**:主面板 `⋯` →「下班提醒…」;桌面小组件右键也有这一项。设置项:开关 / 提醒时间 / 降温阈值(2~20℃)/ 明天雨雪附注 / 周末节假日附注 / 卡片停留(和喝水提示共用,默认 30 秒),还有「先看一眼效果」按钮,改完不用重启。
- 开关和喝水提示是同一个自绘滑块(关掉时下面的时间、阈值、两个勾选项一起置灰);卡片弹在**屏幕右下角、任务栏上方**,带附注时卡片会自动长高一行;两张卡片碰在一起时后弹的会往上叠、不会糊成一团。
- 天气和桌面小组件同源(wttr.in,30 分钟缓存);节日里清明按 4 月 5 日近似,调休补班的工作日暂不识别。
### 喝水提示(独立于桌面小组件)
到点在**屏幕右下角、任务栏上方**弹一张深色卡片(右侧距边 16px、底边贴任务栏 12px),不抢焦点、不进 Alt+Tab,**强制置顶**(前台铺满的浏览器也不会盖住它)。**默认停留 30 秒**,不点按钮就自动淡出(鼠标移入会暂停倒计时,移开继续);停留时长可在设置里改(5–120 秒,喝水提示和下班提醒共用这一个值):
```
💧 已经 1 小时 2 分钟没喝水了
今天第 3 杯 · 还差 5 杯 · 记得喝水哦~
●●●○○○○○ [ 稍后 10 分钟 ] [ 我喝了 ]
```

- **点「我喝了」不会直接关窗**:卡片原地变成确认态「今天第 4 杯啦,已经喝了 1000 毫升 · 还差 4 杯 · 也要继续加油哦~」,1.8 秒后才淡出
- **达标那天**:凑满当日目标时卡片换成强调色「今天 8 杯全部达标,太棒啦!」,一天只庆祝一次
- **入口**:主面板 `⋯` → **喝水提示…**;桌面小组件右键也能进。设置项:开关 / 间隔(30·45·60·90·120 或自定义 5–480 分钟)/ 每日目标(4·6·8·10·12 杯)/ 每杯毫升 / 工作时段(默认 09:00–21:00)/ 卡片停留(默认 30 秒,5–120 秒)/ 全屏静默 / 提示音,另有「−1 杯(我点错了)」「现在就算我喝了」和「现在提醒一次(只是看效果)」
- **开关是自绘的蓝色滑块**(深色底上系统勾选框几乎看不见),关掉时下面所有参数一起置灰;开关下方会直接写出「下一次提醒:10:47(约 42 分钟后)」,不用猜它到底有没有在工作
- **「现在提醒一次」只弹卡片看效果**:不改变计时、不记杯数、不算顺延次数,用来确认卡片长什么样、位置对不对
- **计时口径**:用「上次喝水时间 + 间隔」的绝对时间戳做差,所以合盖休眠 2 小时、系统校时、程序重启都不会算错;重启时若距上次喝水超过 2 倍间隔会**静默重置**,不会一开机就弹「已经 14 小时没喝水了」
- **默认关闭**(避免升级后毫无预兆地弹),需要你在设置里勾选「开启喝水提醒」
- 全屏应用(看视频/开会)时静默,**退出全屏后补弹一次**;顺延最多 3 次;连点「我喝了」5 秒内只算一杯
技术说明(本机 Win11 26200 实测结论):
1. 经典 `0x052C` 让 Explorer 派生 `WorkerW` 的壁纸层做法**在这台机器上已失效**(`SendMessageTimeout` 返回 0,枚举不到 WorkerW)。
2. 360 桌面助手是把窗口(`360DirectUICls`)挂进 `SHELLDLL_DefView`;**Qt 窗口挂进去后不渲染**(异源父窗口 Qt 不支持),这条路不通。
3. 最终采用等效且稳定的方案:无边框工具窗 + 持续"压在 Progman 正上方"(`SetWindowPos` 插到 Progman 上方那个窗口之后,必要时用 `HWND_BOTTOM`),并加 `WS_EX_NOACTIVATE` 保证点击不把窗口提到前台。
**常驻桌面机制(Win+D 不再闪一下)**:实测 Win+D 并不会真的最小化这个工具窗(`IsIconic` 始终为 0),而是把所有窗口最小化一遍、让桌面层盖上来。所以改成三路即时纠正:
- `SetWinEventHook` 监听"最小化开始/结束"事件(Win+D 会挨个触发):开始事件立刻压底,并在 250ms、600ms 各补压一次(桌面层是在最小化动画结束后才抬升的);最小化结束事件再压一次;
- 50ms 看门狗(最小化事件后的 1.2 秒里自动切到 15ms,约一帧):用 `WindowFromPoint` 在面板中心判断桌面层(`Progman` / `SHELLDLL_DefView` / `SysListView32`)是不是盖在自己上面,是就立即压回;被普通应用窗口正常盖住时不做任何动作。
→ 效果:桌面上常驻可见、被普通应用窗口盖住、**Win+D / 显示桌面时不再先消失再冒出来**(连续采样 40+ 帧、0 帧丢失,实测空档 ≤50ms)、点击不抢焦点、拖动位置会记住;只有退出程序或手动隐藏才不显示。
## 自动更新(托盘)
程序自己盯着 Gitee 上的最新发行版,不用你手动去看有没有新版。
- **什么时候查**:启动 30 秒后查一次(错开启动高峰),之后每 6 小时一次。断网、接口异常都只是静默跳过,不会弹错误框打扰你。
- **有新版本时**:托盘弹气泡「发现新版本 vX」,同时托盘右键菜单里那一项变成「发现新版本 vX(点此更新)」并**一直留着**——气泡错过了也不会漏。
- **点它之后**:进应用内更新对话框,能看到当前版本 → 最新版本、完整更新说明、下载进度条、已下载/总大小。
- **下载完会校验**:自动比对发行版说明里「校验」表格中的 SHA256,不一致就拒绝替换(并提示你去发行版页面重新下载);说明里没写校验值时按未校验处理,会在对话框里标出来。
- **点「立即重启更新」后**:程序退出,交给 `%LOCALAPPDATA%\DeskIcon\update\apply_update.bat` 收尾——等旧进程退出 → `copy /Y` 覆盖 exe → 启动新版;旧进程 60 秒还不退就 `taskkill /IM DeskIcon.exe /T /F` 兜底(onefile 有父+子两个进程,必须连子进程一起结束);万一覆盖失败,也会把旧版重新拉起来,不会把桌面弄成空的。
- **不需要令牌**:查版本走 Gitee 公开接口 `releases/latest`,客户端里没有也不该有 token。
- **哪些情况不会自动替换**:源码运行(`python main.py`)、或者 exe 放在只读目录(如 `Program Files`,需要管理员权限)——这两种只把安装包下载到 `update\` 目录,由你自己手动替换,对话框里会写清路径。
- **想立刻查一次**:托盘菜单「检查更新…」(没发现新版会提示「已经是最新版本 vX」)。
- 更新成功后重启的是新 exe,托盘菜单会自动回到「检查更新…」——因为新进程是全新启动,`reported` 标记不跨进程。
## 数据目录
```
%LOCALAPPDATA%\DeskIcon\
├─ deskicon.db # 分组/图标/设置/待办(todos 表)
├─ icons\*.png # 256px 图标缓存
├─ backups\ # 启动前滚动备份(保留 7 份)
├─ update\ # 自动更新:下载中的新 exe、一次性替换脚本
└─ logs\app.log
```
想换位置(绿色版)可设置环境变量 `DESKICON_HOME=D:\DeskIconData`。
## 测试
```powershell
.\.venv\Scripts\python.exe tests\test_core.py # 数据层 / 图标 / 快捷方式解析
.\.venv\Scripts\python.exe tests\test_ui.py # offscreen 渲染冒烟 + 截图
.\.venv\Scripts\python.exe tests\test_todos.py # 待办:本周窗口/默认今天/翻看前几天/增删改(隔离数据目录)
.\.venv\Scripts\python.exe tests\test_todo_focus.py # 待办浮层:键盘焦点、控件不溢出
.\.venv\Scripts\python.exe tests\test_todo_detail.py # 待办详情卡:点文字看全文、卡内完成/删除/Esc
.\.venv\Scripts\python.exe tests\test_water.py # 喝水提示逻辑:计时/顺延/杯数/跨天/历史(假时钟)
.\.venv\Scripts\python.exe tests\test_water_ui.py # 喝水提示接线:菜单入口、设置对话框落库(offscreen)
.\.venv\Scripts\python.exe tests\test_toast_hold.py # 提醒卡片停留:默认 30 秒、可改、脏数据回默认、两个提醒共用
.\.venv\Scripts\python.exe tests\verify_water_toast.py # 真机:卡片位置/文案/点击反馈/不抢焦点
.\.venv\Scripts\python.exe tests\test_font_dialog.py # 时钟字体:导入 ttf 后族名生效、字号落地
.\.venv\Scripts\python.exe tests\test_menu_clock.py # 小组件右键菜单:时钟字体/每行图标数两项在且能触发
.\.venv\Scripts\python.exe tests\test_win_d.py # 真机:连按 Win+D,小组件始终可见、不被最小化
.\.venv\Scripts\python.exe tests\test_win_d_src.py # 同上(源码态,隔离数据目录)
.\.venv\Scripts\python.exe tests\test_advice.py # 下班提醒逻辑:节日/降温/雨雪/周末与"该不该弹"
.\.venv\Scripts\python.exe tests\test_advice_rest.py # 下班提醒「每天必弹」:没变化也弹、断网也弹、一天只一次
.\.venv\Scripts\python.exe tests\test_advice_ui.py # 下班提醒接线:卡片渲染、设置落库、到点触发与去重
.\.venv\Scripts\python.exe tests\test_update.py # 自动更新:版本比较/校验表解析/下载进度/替换脚本真跑一遍
.\.venv\Scripts\python.exe tests\test_motion.py # 动效:四档强度、悬停抬升不推挤网格、浮层淡入上移
.\.venv\Scripts\python.exe tests\test_widget_motion.py # 小组件选中动效:图标格悬停/按下、分页圆点滑动、日期胶囊脉冲
.\.venv\Scripts\python.exe tests\test_backdrop_cover.py # 背景图取景:16:9 壁纸在各框比例下两方向都留余量
```
## 常见问题
**从资源管理器拖不进来?**
如果资源管理器是以管理员身份运行的,Windows 的 UIPI 会拦截拖拽到普通权限窗口。
改成"点 + 选择文件"或在托盘以管理员身份启动本工具即可。
**图标显示成首字母方块?**
说明该目标不存在或没有可读图标,工具会退化为占位图标,不影响使用。
**会不会动我的桌面?**
不会。面板里的每一项只是"目标路径 + 名称"的记录;删除图标只删数据库记录。
**导入了字体,时钟看着没变?**
先看字号是不是没调(14~72pt,32 左右才有明显效果);再看导入的那个文件是不是 `.ttf/.otf/.ttc`(`.exe` 安装包不能导入)。
还是没变就点「用系统默认字体」再重开一次对话框——对话框里那行 `00:00:00` 预览就是最终效果,预览变了、小组件没变才算异常。
(底层原因:主窗口的全局样式表同时写了 `font-size` 和 `font-family`,只改字号会被吃掉,所以字体族也写进了时钟标签自己的样式表。)
**背景图只能左右挪、上下挪不动?**
那是老版本的问题(铺满裁切时纵向余量为 0),v1.2.4 起不会了:铺满统一多留 10% 裁切余量,
两个方向都有几十像素可挪。升级后如果还是挪不动,先确认跑的是新包(托盘 →「检查更新…」看当前版本),
再看这张图的宽高比是不是和窗口差太多——极端长的图(比如 4:1)在那个方向上仍可能被裁到几乎没有余量。
**桌面小组件被别的桌面美化软件(360 桌面助手、桌面栅栏类工具)挡住?**
这类工具会在 `SHELLDLL_DefView` 里塞全屏覆盖窗。本工具的小组件固定在 `Progman` 正上方,
实测与 360 桌面助手共存时可正常显示;若某个工具把自己置为最顶层全屏覆盖,小组件会被它盖住,
这种情况需要在该工具里关掉它的"桌面层覆盖",或改用本工具的小组件。
**按 Win+D 显示桌面后小组件会消失一下?**
不会了(V1.0.1 起)。它常驻在"桌面之上、应用之下"这一层;Win+D 时系统会把所有窗口最小化一遍,程序监听到最小化开始/结束就立刻把自己压回桌面层(并错开补压两次),同时还有 50ms 兜底检测,实测显示桌面全程 0 帧丢失。
只有这两种情况它才不显示:右键菜单里"隐藏桌面小组件",或退出程序。
**天气不显示 / 显示"—"?**
天气走 `wttr.in` 免费接口(无需 Key),需要联网。取不到时图标显示"—",每 30 分钟自动重试;**点一下这个天气图标可以立即重试**(不用等);
城市可在 ⋯ → **设置天气城市…** 里改。数据为 30 分钟缓存,不会频繁请求。
## 目录结构
```
DeskIcon/
├─ main.py # 入口:单实例 → 托盘 → 主窗 → 全局热键
├─ build.py # 生成 ico + PyInstaller 打包
├─ core/constants.py # 常量、配色、类型
├─ infra/
│ ├─ db.py # SQLite(分组/图标/设置/备份)
│ ├─ icons.py # HICON → PNG 缓存
│ ├─ shellink.py # .lnk/.url 解析、ShellExecute 启动
│ ├─ weather.py # 天气取数 + 中文映射(wttr.in,标准库实现)
│ ├─ todos.py # 待办「本周 周一~周日」窗口与中文日期标签
│ ├─ water.py # 喝水提示:计时/杯数/30 天历史(纯逻辑,无 Qt)
│ ├─ advice.py # 下班提醒:节日表/降温幅度/必弹主文案/该不该弹(纯逻辑,无 Qt)
│ ├─ paths.py # 数据目录
│ └─ win32/ # autostart、hotkey
├─ ui/
│ ├─ main_window.py # 主窗口
│ ├─ desktop_widget.py # 桌面小组件(时钟/日期/天气/图标)
│ ├─ water_reminder.py # 喝水提示调度(1 秒一拍 + 全屏静默判定)
│ ├─ water_toast.py # 底部卡片(提醒 / 已记录 / 达标 三态)
│ ├─ advice_reminder.py # 下班提醒调度(每秒一拍、天气回调绕回主线程)
│ ├─ advice_toast.py # 下班提醒卡片(铃铛图标 + 标题 + 正文 + 知道了)
│ ├─ flow_layout.py # 自动换行布局
│ ├─ theme.py # 深色 QSS
│ ├─ branding.py # 代码生成的图标
│ ├─ dialogs/ # item_edit、clock_font、water_setting、advice_setting
│ └─ widgets/ # group_card、icon_tile
└─ tests/ # 自检脚本
```
## 后续(V1.1 计划)
- 资源管理器右键"添加到分类"
- 分组导入/导出 JSON、批量替换图标、多屏独立布局
- 图标异步加载(当前为同步 + 磁盘缓存,100+ 图标时可优化)
- 桌面小组件接入天气 / 农历(对齐 360 桌面助手那行小字)
设计与排期详见 `..\桌面图标分类工具开发设计文档.md`。