DesktopFX v1.5.0

DesktopFX v1.5.0

两批改动：鼠标光环大改（波动幅度放大 3 倍、三种新样式、全部改成稀疏描边）

• 暂停快捷键与恢复后层级修复。

鼠标光环 v2

波动幅度：从写死变成可调，上限是原来的 3 倍

原先半径的涨落系数 0.55 是写在代码里的，用户根本调不了。现在做成
滑块「波动幅度」（0~1.65，默认 0.55）—— 上限正好是原值的 3 倍，调到头
就是"音乐最响时光环比安静时涨 165%"。

半径上限 320 像素：极端组合（大小 160 + 幅度拉满）理论半径 424，会被削掉
一小段 —— 有意的，再大的光环既难看又抢戏。

辐条 / 星芒改空心（描边 + 中心让开鼠标指针）

实心辐条是一根根从圆心射出的楔形，十几根在指针周围堆成一坨，尖端正好压在
光标上 —— 想点准一个小按钮得先猜光标在哪。

• 辐条 = "口"字框（两条径向边 + 一道外弧）
• 星芒 = 描边三角（两条斜边 + 外弧），内端离圆心留出 0.34 倍半径

判据：光标附近 12 像素内一个像素都不能有。

新增三种样式

• 三条线：三条同心细弧随音乐散开，像均衡器的三根柱
• 折线圆环：不规则多边形边框（而不是圆），随音乐缩放并缓慢自转
• 赛博风：断续霓虹段 + 旋转扫描弧 + 沿圈分布的数据块

九种样式全部由代码绘制，不引入图片资源。

全部样式改稀疏描边（这是幅度能放大的前提）

包围盒面积 ∝ 半径²。幅度放大 3 倍 ⇒ 面积涨 9 倍 —— 逐像素画法直接爆：
实测「大小 160 + 幅度 1.65 + 音乐正响」时星芒要 90ms/帧（60fps 预算只有
16.7ms）。

改成稀疏描边：用极坐标把每条笔画参数化出来，只写真正有墨的像素。代价从
O(包围盒面积) 降到 O(笔画总长)，只随半径线性增长。

同一极端组合优化后：最慢 10.5ms（彩虹），星芒 9.3ms。

顺带修掉一个真 bug：「粒子光环」一直是空白

粒子位置是屏幕绝对坐标，而包围盒坐标是相对框内的，两者没换算，窗口全被
裁到框外 —— 一个粒子都画不出来。

暂停快捷键失效 + 恢复后层级不对

缺陷一：pause 事件只有控制面板消费

("pause", None) 事件原先只有控制面板在处理。而控制面板是可选的 ——
它没起来、或还没跑到它的 _poll 时，事件就堆在队列里没人管，用户按
Ctrl+Alt+R 毫无反应。

而且状态被两处各切一次（App 与面板），谁后处理谁说了算 —— 表现就是
"按一下没反应、按两下才暂停"，界面上的"[已暂停]"标记还常常是错的。

改法：状态归 App 管，界面只负责显示。

• App 新增统一入口 on_pause_event，事件泵里就地处理
• 转发给面板时换事件名 pause-state，面板只刷界面、不再切状态
• 面板上点状态区也走同一个入口 —— 三条路（面板点击 / 托盘菜单 / 快捷键）
  汇到同一个入口，状态只有一处说了算

缺陷二：恢复时"骑在面板之上"的标志可能残留

_ride_above_panel 残留 True 时，keep_on_top 开头就 return False ——
置顶位自愈永远不执行，特效层再也抢不回顶。

为什么残留：暂停期间渲染循环整个被 continue 跳过，标志的配对清理没机会跑。

改法：恢复路径里强制复位该标志，并立刻补做被跳过的维护（置顶位自愈 +
两层先后纠正）。恢复后的第一帧用户就在看，等下一帧慢慢自愈会看到
"闪一下才浮上来"。

体验：热键被占用时给出提示

系统级热键全局唯一。Ctrl+Alt+R 被别的程序抢占时，原先只在 error.log 里留痕，
用户按了没反应却不知道为什么。现在启动时弹一次提示（只弹一次），并说明
仍可用托盘菜单 / 面板状态区。

验证

• tests/_verify_halo.py 13 项：幅度 3 倍（半径涨落量实测 2.98 倍）、
  空心中心零像素、性能预算、跨文件一致性
• tests/_verify_pause.py（新）9 项：热键投递、App 侧独立处理、面板不重复
  切状态、暂停往返、置顶自愈、骑乘标志复位、leave_panel_ride 不丢置顶位、
  两层先后、不误伤同层像素
• 全量 _run_all_verify.py 42/42 通过
• 真机：赛博风与空心星芒都在真实屏幕上确认过

资源

• DesktopFX.exe：单文件打包（PyInstaller，含 assets 与内置音效）
• 源码已同步至 main，标签 v1.5.0

DesktopFX v1.4.0

DesktopFX v1.4.0

新增鼠标光环：跟随光标的一圈光环，随系统正在播放的音乐律动 —— 鼓点一响就跳一下。

鼠标光环

• 六种样式（全部代码绘制，不引入图片资源）：呼吸圆环 / 双环脉冲 / 彩虹光环 /
  辐条光环 / 星芒光环 / 粒子光环
• 电平取自 Windows 的 IAudioMeterInformation（系统默认渲染设备的实时峰值，
  纯 ctypes 调 COM，零新依赖）—— 读的是系统正在播放的声音，不是程序自己
  播放器的声音，所以放什么歌它就跟什么
• 可调：样式 / 大小 / 灵敏度 / 颜色；拿不到音频设备时不报错也不崩，
  光环退化成"一圈很淡的环"
• 三件事让它"看起来像律动"：① 自适应归一化（不同音量下峰值差一个数量级，
  实测 0.01~0.10，固定阈值会让轻音乐不动、重音乐爆表）② 双时间常数包络
  （上升快、下降慢，光环不会疯狂闪烁）③ 采集在后台线程（设备被拔也能自恢复）
• 取舍：峰值电平是"整体强弱"，拿不到频谱（分不出低频鼓点与高频镲片）——
  分频段需要自己抓 PCM 做 FFT，代价大得多

顺带修掉的两处

• 控制面板的悬浮提示不再飘离面板：提示浮层原本自己设了 -topmost，而面板在
  v1.3.0 改成普通窗口后，两者分属不同 z 序组，"从属窗口永远在拥有者之上"的
  规则失效 —— 提示会飘到离面板很远的地方。现在去掉它自己的 -topmost
• 窗口高度会同时考虑侧栏：新增特效后侧栏比最高的页面还高，之前按内容算
  窗口高会把侧栏多出来的那截切掉，最后一项特效露不出来

性能

鼠标层每帧预算很紧，初版最慢 18.8ms/帧（彩虹样式），已优化到最慢 8.2ms，
其余 0.5~3.8ms：按样式收缩包围盒、角度懒计算、彩虹改 256 级色环查表、
辐条抖动系数查表、粒子只在小方框内算。

验证

• tests/_verify_halo.py（新）10 项：电平算法 4 项 + 样式渲染 3 项 +
  跨文件一致性 2 项 + 注册与 Scene 接线 1 项
• 全量 _run_all_verify.py 41/41 通过
• 真机：7 个内置音效全部起播；电平随音乐起伏（实测 0.000 → 0.818）

资源

• DesktopFX.exe：单文件打包（PyInstaller，含 assets 与内置音效）
• 源码已同步至 main，标签 v1.4.0

DesktopFX v1.3.0

DesktopFX v1.3.0

修掉一批交互与音量的顽疾，并把控制面板改回普通窗口的行为。

点击音效：音量真正对所有音效生效

MCI 的 waveaudio 设备根本不支持 setaudio volume（实测发任何取值都返回
err 261），此前"只有气泡声和旅店铃声有音量"的真凶就在这里 —— 那两个是
mp3，走的是 mpegvideo 设备，0~1000 区间合法；而全部 wav 走 waveaudio，
音量命令直接被拒，滑块动了等于没动。

改用 waveOut 软件混音（ctypes 直接调 waveOut*，零新依赖）：

• wave 读 16-bit PCM → numpy 乘音量系数 → 统一 44.1k 立体声后起播
• 每条流一条句柄，多击仍可叠播；守护线程轮询 WHDR_DONE 回收
• 解码失败 / 无音频设备 / 池满自动退回 MCI 兜底
• mp3/wma 维持原路径（区间实测合法）

同时新增音量滑块，默认 100% 即等于当前系统音量；「语音与文字统一」
挑中的那条语音也纳入同一支滑块。

点击文字 / 表情：控制面板上也能看到了

此前"命中配置面板就整块屏蔽点击"，面板空白处也一并没了。改为三态判定：

• 桌面与其它程序 → 照常触发
• 面板的交互控件（按钮 / 滑块 / 侧栏导航）→ 抑制，
  彻底避免"按下触发的旧音效"与"选择后的试听"叠成两声
• 面板其它区域 → 放行

控制面板：改成普通窗口

• 不再 -topmost、不再每秒抢顶层，点它正常获得焦点、正常被别的窗口盖住
• 双击托盘唤出时仍会临时置顶一次再立刻摘掉置顶位，保证出现在最前面
• 移除播放点击特效期间的面板观感切换 —— 那会让面板"点一下颜色变深、
  播完又变回来"
• 特效层是 topmost，天然显示在普通窗口之上，不再需要任何临时提层

已知遗留

配置面板标题栏（用于拖动窗口的那一条）仍会被判定为交互控件，
点它第一次有特效、第二次没有。三个修法已评估，待定。

验证

• _run_all_verify --fast 15/15 通过
• _verify_zorder 新增 4 条不变量（提层让位 / 恢复 / 标志置位 / 自愈），25→29
• _verify_click 79 项（含音量解码与语义、面板三态判定、试听接线）
• 真机：7 个内置音效全部起播且句柄回收；面板点击特效 0.2~2.0s 稳定可见；
  6 秒内抢顶归零 0 次；点击时面板颜色变化 0

资源

• DesktopFX.exe：单文件打包（PyInstaller，含 assets 与内置音效）
• 源码已同步至 main，标签 v1.3.0

DesktopFX v1.2.0

DesktopFX v1.2.0

桌面特效能力大幅扩展、工程结构重构、并更换了软件图标。

新增 / 增强特效

• 宠物跟随二期：帧动画 + 静止渐隐 + 点击表情，同屏上限提到 10
• 点击表情：支持 GIF 动图、自选图片、单次取图模式
• 点击文字：支持语音包，文字与音频可统一播放
• 点击特效：修掉文字横向被切、惯用色与"彩色"、彩带曲线、字体/预设/倾斜
• 流星雨：燃尽距离改由屏幕几何决定，覆盖整屏（解决高屏只有上半屏有流星）
• 独立「点击音效」：不画像素，点一下响一声；多点击允许重叠播放

稳定性与交互

• 渲染线程加异常保护、三处 JSON 改原子写、配置值钳制、挂载失败回滚
• 声音统一到「点击音效」；预设不再冻结素材来源
• 界面：标题栏增加窗控钮、移除悬浮操作条

工程

• fx_effects.py（5633 行）拆分为 fx_image + fx_click + fx_effects 三层
• 38 个 _verify_*.py 收进 tests/、25 个开发脚本收进 tools/
• 托盘图标换成参考图风格的霓虹光效鼠标箭头（assets/tray_icon.*）

资源

• DesktopFX.exe：单文件打包（PyInstaller，含 assets 与内置音效）
• 源码已同步至 main，标签 v1.2.0

桌面特效 DesktopFX v1.1.0

下载

DesktopFX.exe · 30.1 MB · Windows 10 / 11 64 位 · 免安装单文件

SHA-256: 0983425b24d63ded61a7355f0a15273a62ad86abcb02109aa05969fd140018ab

放到任意可写目录双击即可。配置、自定义预设、界面状态都写在 exe 同目录 ——
换个目录就是一套全新配置，整个目录搬走设置也跟着走，卸载 = 删目录。
不需要 Python、不需要联网。

首次运行 Windows 可能弹 SmartScreen「已保护你的电脑」：因为 exe 没有代码签名
（签名证书要钱），点「更多信息」→「仍要运行」即可。

---

本次新增

真实水波（全新特效）

二维波动方程（高度场 + 速度场双缓冲）驱动的真水面。波会向外传播、相互干涉、撞到屏幕边缘反射；
一次点击的涟漪要好几秒才传遍屏幕、二十多秒才平复。透明覆盖层拿不到桌面像素做折射，所以改成把
波面坡度当法线、按固定光向做迎光提亮 / 背光压暗加浪尖高光，对任何桌面底色都成立。
上屏走双线性显示网格，否则每个格子就是一块硬方块。浓度有 20% 硬上限，五档预设可从"几乎看不见"调到上限。

窗口水波重做：桌面上的窗口就是水面里的活塞

它自己不画一个像素，只往与真实水波共用的那片水面上注入位移 —— 一个桌面本来就只有一片水，
鼠标划过和窗口推过该落在同一张水面上，于是波速 / 余波 / 光照 / 浓度也自然共用。

• 移动：前缘推水、后缘留下空腔（船首浪 + 船尾迹）
• 缩放：拉宽是水被推开，缩窄是水合拢回来
• 最小化 / 恢复：水从四周合拢填掉窗口占的位置 / 重新把水压开
• 平移与改尺寸走同一个式子（四条边各按自身法向速度注入），静止的窗口绝对零注入
• 波只朝窗外扩散：扰动带只铺窗外一侧、包两端归零、并连速度场一起写成一列朝外走的行波。
  三层齐全后窗内漏量 128% → 8.5%，而窗外波高与旧写法实测比 0.94 —— 手感不变，
  少掉的只是原先灌进窗口里的那半截

双图层显示层级

全屏特效与鼠标特效分别画在两个独立的覆盖窗口上，因此可以各自设定显示层级：
最上层（默认）或仅桌面图层（挂到桌面壁纸层，被任何窗口盖住，像壁纸的一部分）。
可以只让雨雪沉到壁纸里，而聚光灯仍浮在窗口之上。

其它

• 特效三类分组 + 同类互斥 / 多开：默认同类只留一个（开"下雪"自动关掉"下雨"），
  也可在「其他设置」里改成允许多开（雨雪同屏、聚光灯 + 水波一起上）
• 控制面板可自定义大小：八向拖拽 + 滑块，最小宽度 520
• 每帧置顶保活：被全屏视频 / 画中画 / Citrix 类远控全屏窗盖住时自动抢回
• 避让任务栏：特效不上屏到任务栏上（否则真实水波那种整片条纹糊上去就是"残影"）

修复（均为根因修复，不是打补丁）

• SetParent 会废掉分层表面：切到「仅桌面图层」后特效消失，且切回最上层也恢复不了 ——
  窗口状态、屏幕矩形、置顶标记全部正常，但就是永不再上屏，必须重建分层表面
• 桌面层上屏的坐标系：子窗口用父客户区坐标，副屏在主屏左侧时桌面层特效整片偏移
• 抢顶插入锚点不得自封顶：拿控制面板当锚点，而面板被对手压住时，每次"抢顶"都白费
  （实测被盖采样 0% → 100%，20fps 与 60fps 结果相同 —— 瓶颈是方向不是频率）
• 切换图层时的闪屏、启动时的闪动（构造期刷新 23 次 → 4 次）
• 鼠标层特效不再允许切到「仅桌面图层」（开关置灰 + 禁用）

性能

• 水波上屏两条优化：dep → 预乘像素 的查表着色（与逐项公式逐字节相同）
  与整片直写。4K 满屏波 33.6 ms → 18.7 ms
• 渲染循环去掉两块可省开销；空层不再空转上屏

验证

发布前 _run_all_verify.py --fast 10/10 全绿（52 秒）；完整套件共 33 个验证脚本。
exe 已做启动冒烟：引导正常、覆盖窗创建成功、无 error.log。

DesktopFX v1.0.0

首个正式版。

下载

文件	说明
DesktopFX.exe	免安装单文件（约 29 MB），双击即用。需要 Windows 10 / 11 64 位

放到任意可写目录即可 —— 配置、自定义预设、界面状态都写在 exe 同目录，换个目录就是一套全新配置，卸载 = 删目录。

首次运行 Windows 可能弹 SmartScreen「已保护你的电脑」：exe 没有代码签名（签名证书要钱），点「更多信息」→「仍要运行」即可。

这个版本有什么

9 组可独立开关、任意叠加的特效图层

• 下雨 — 3 层景深，风偏 / 长度 / 浓度 / 速度 / 落点溅水花
• 下雪 — 3 档近大远小（画家算法），逐粒子亮度脉动、近雪辉光、独立阵风
• 落樱 — 主体到边缘泛白的双色渐变，自旋 + 翻面（侧立时收扁偏白），逐片相位摆动
• 流星雨 — 斜向彗星 + 可选星空；轨迹按间距采样成圆盘链，核内留平坦区防「串珠」
• 颜料盘 — 鼠标搅动的流体颜料：滑过搅动、点击径向扩散、停手自行消散
• 聚光灯 — 全屏压暗 + 鼠标处柔边透明圆洞
• 窗口水波 — 窗口移动时沿四边荡开涟漪，松手补一次大爆发
• 鼠标涟漪 / 随机闪电

控制面板：深色玻璃风，所有参数实时可调；23 个内置预设 + 自定义预设（可保存 / 删除）；颜色项支持预设色块、系统调色板、屏幕取色器；窗口高度按内容自适应。

零侵入：覆盖层是 WS_EX_LAYERED | WS_EX_TRANSPARENT 置顶窗，鼠标事件完全穿透，不拦截任何点击。高 DPI 友好（PER_MONITOR_AWARE_V2）。

性能（1080p 单层）

雪花约 5 ms/帧、流星雨约 5.4 ms/帧、颜料盘约 11 ms/帧（交互特效，默认关闭 —— 不吃指针时整帧接近 0）。4K 双屏多图层全开仍高于 80 FPS。

许可

AGPL-3.0 —— 见 LICENSE。