Repository navigation
Releases: liusuan233/cursor-manager
Release list
v1.0.3
v1.0.3
修掉「没有 .inf 的光标包导入后缺 3 个角色」，重画了应用图标，
并补上两个能省时间的生成脚本（演示视频、图标）。
修复：没有 .inf 的包，17 个角色里会漏掉 3 个
Windows 光标包分两类：用安装器打包的带 install.inf，手工拼的没有。
有 .inf 时它的 [Strings] 段就是微软官方的角色映射，属于权威数据；
没有就只能按文件名猜。
实测：拿一个真实包（ZUTOMAYO）把 .inf 抽掉再导入 ——
修复前 14 / 17
漏掉 Diagonal1.ani、Diagonal2.ani、Horizontal.ani
修复后 17 / 17
根因很直接：关键词表里写的是 diag1 和 horz，但
diag1不是diagonal1的子串horz不是horizontal的子串
而原来的实现是纯子串匹配，所以这三个永远猜不出来。
反过来还有误判风险：Small.ani 会因为含 all 被猜成"移动"。
现在改成三层匹配（从严到宽）
① 与 .inf 键名归一化后完全相同 diagonal1 == diagonal1
② 与任一关键词归一化后完全相同 working == working
③ 关键词子串匹配，最长优先 precision ⊃ precise
三个字母以内的弱关键词只许整词命中
归一化是这次的关键：Diagonal-1 / diagonal_1 / Diagonal 1 / Diagonal1
现在都归一成 diagonal1；SizeNWSE 会按 camelCase 切成 size + nwse。
弱关键词（ns / we / up / all / alt / pen / no）必须整词命中，
否则 Small.ani 含 all、Normal.ani 含 no，会被硬拽到错误的角色上。
关键词表同时扩到覆盖三套命名习惯：
| 命名习惯 | 例子 |
|---|---|
| 微软官方方案 | Normal Working Precision Handwriting Horizontal Diagonal1 Pin |
| X11 习惯 | SizeNS SizeWE SizeNWSE SizeAll xterm crosshair left_ptr |
| 中文 | 正常选择 文本选择 水平调整 手写 移动 |
猜不出来时
不会乱填 —— 认不出的角色保持空缺，由系统回落到默认光标，
同时在导入结果里明确提示：
这个包没有 .inf：17 个角色里 N 个没能从文件名认出来，会继承系统默认外观。
想要精确映射，把 .inf 放进包里重新导入一次（很多包的 .inf 是通用的，也可以手工写一个）
想精确控制的话，往包里放一个最小的 install.inf 就行（左边键名固定不能改）：
[Version]
signature="$CHICAGO$"
[Strings]
SCHEME_NAME = "My Cursor"
pointer = "Normal.ani"
help = "Help.ani"
work = "Working.ani"
busy = "Busy.ani"
cross = "Precision.ani"
text = "Text.ani"
hand = "Handwriting.ani"
unavailable = "Unavailable.ani"
vert = "Vertical.ani"
horz = "Horizontal.ani"
dgn1 = "Diagonal1.ani"
dgn2 = "Diagonal2.ani"
move = "Move.ani"
alternate = "Alternate.ani"
link = "Link.ani"
loc = "Pin.cur"
person = "Person.cur"顺带一个很多人不知道的点：微软光标方案的 17 个文件名是固定的，
所以两个都用标准名的包，.inf是可以直接互借的，连文件名都不用改。
修复：图标尺寸档错配
install.sh 里原来有这么一行：
cp -f "$HERE/icons/cursor-manager.png" "$HICOLOR/256x256/apps/cursor-manager.png"cursor-manager.png 是 512px 的，塞进 256x256/ 目录会让图标加载器拿到
尺寸不符的位图，也覆盖掉了上面刚写的回退逻辑。现在每档只进自己的目录。
另外 install.sh 和 PKGBUILD 都只装 5 档（32/48/64/128/256），
缺 512（现代桌面会找它）。两处都补上了。
install.sh 还加了：清掉不属于当前档位的旧文件 + 刷新图标缓存 ——
不然换了图标可能还显示老的。
新图标
旧图标是一个深色底上的光标箭头，比较平。新的是圆角方块 + 蓝紫渐变底，
白色箭头占画布 62%，底部三个色点当主题色板。
尺寸档 32/48/64/128/256/512 全部由脚本生成，改设计跑一遍就行：
make icon # 重新生成 6 个尺寸档
make icon-preview # 只出预览图（含 32/48/64 放大 4 倍的像素对照）新增：两个生成脚本
| 脚本 | 作用 |
|---|---|
tools/make-demo.py |
make demo 自动生成演示视频（真跑命令、真解码光标，不需要录屏和剪辑软件） |
tools/make-icon.py |
make icon 重新生成应用图标（6 个尺寸档） |
两个脚本都进了源码包（MANIFEST.in 里 recursive-include tools *.py），
克隆下来就能跑。生成的 demo/*.mp4 和 icons/_preview.png 是构建产物，不进仓库。
另外新增了 docs/VIDEO-SCRIPT.md —— 想自己录介绍视频的话有分镜表和完整旁白稿。
从 v1.0.2 升级
sudo pacman -U cursor-manager-1.0.3-1-any.pkg.tar.zst已经导入过不带 .inf 的光标包的，建议重新导入一次才能拿到修好的角色映射：
cursor-manager --import <原来的包> --name <原来的名字> --overwrite下载哪个
| 文件 | 用途 |
|---|---|
cursor-manager-1.0.3-1-any.pkg.tar.zst |
Arch Linux：sudo pacman -U <文件> |
cursor-manager-1.0.3.tar.gz |
通用源码包，解包即用，也能被 pip install |
cursor_manager-1.0.3-py3-none-any.whl |
Python wheel，配合 pipx install |
SHA256SUMS |
上面三个文件的校验和 |
安装
Arch Linux
sudo pacman -U cursor-manager-1.0.3-1-any.pkg.tar.zst其他发行版（源码包，解包即用）
tar -xzf cursor-manager-1.0.3.tar.gz
cd cursor-manager-1.0.3
./cursor-manager # 直接跑
./install.sh # 或装到 ~/.local（含桌面入口和图标）pipx
pipx install cursor_manager-1.0.3-py3-none-any.whlPyGObject 无法用 pip 可靠安装，需要走发行版包管理器
（它只影响图形界面，命令行功能都不需要它）。
校验下载
sha256sum -c SHA256SUMS自检
make test # 导入器 55 + 删除 24 + 检查更新 25 + GUI 42 项四套自检都不需要人看图，退出码非 0 即失败。
这次新增的 test_guess_roles() 专门钉住角色猜测：36 个正向用例
（标准名 / X11 名 / 分隔符变体 / 中文）、7 个反向用例（无关文件名不许误判）、
一个无 .inf 的 17 角色端到端包（并断言对角线、水平/垂直没有搞反）。
已知限制
- Arch 包是按当前 Python 版本编译的（3.14）。Arch 换 Python 大版本后需等重新构建；
源码包不受影响 apply覆盖 niri / DMS / GTK / XWayland / gsettings；KDE 的kcminputrc未处理- 导入功能对 RLE 压缩的老式光标仍依赖 Pillow
- 角色映射还不能在图形界面里手动指定 —— 猜不出来只能靠补
.inf或改文件名
v1.0.2
v1.0.2
修掉一个让导入的主题直接不可用的 bug，并加上「检查更新」。
修复：调色板光标丢失透明度，整张变成黑底
如果你导入过 8bpp / 24bpp 的调色板光标包，光标会渲染成带黑色底方块的图。
根因两条：
1. Pillow 对 8bpp 调色板图像（mode=P）不应用 AND 掩码。
8bpp 是调色板格式，根本没有 alpha 通道 —— 透明度全靠 DIB 末尾的 AND 掩码。
Pillow 会把调色板直接展开成不透明 RGBA，于是整个光标变成实心方块。
而原来的解码顺序是「Pillow 优先」，所以所有调色板光标包都会中招。
（32bpp 带真 alpha 的包不受影响，纯属运气。）
现在自己实现 decode_dib()，支持 1/4/8/24/32bpp + 调色板 + AND 掩码，
解码顺序改为「自己优先，Pillow 只作后备」（后备用于 RLE 等冷门编码）。
2. IconEntry.bpp 的语义是错的。
CUR(type=2) 容器里 wPlanes / wBitCount 被复用成热点坐标，不是位深 ——
真位深得从 DIB 头读。
重写过程中我还引入了一个新 bug：32bpp 分支写成
r, g, b, a = row[si], ...，
但 DIB 里第一个字节是 B 不是 R，红蓝对调。是靠「与 Pillow 输出逐字节比对」
发现的（差异特征平均 20.267，和历史上那个通道 bug 一模一样）。
现在 32bpp 的 18 个帧与 Pillow 完全一致。
已经导入过这类主题的，需要重新导入一次才能修好：
cursor-manager --import <原来的包> --name <原来的名字> --overwrite新增：检查更新
cursor-manager --check-update # 命令行图形界面左侧的 ≡ 菜单里也有「检查更新…」。
三条刻意的设计：
- 只检查，不自动更新。 这个工具会写用户的
~/.config和~/.local，
自动下载替换出问题的代价太高。查出有新版本就告诉你怎么装，装不装由你决定 - 不在启动时联网。 只有显式执行检查时才发请求 —— 一个光标工具没必要
在每次开窗时暴露你的 IP 和启动时间 - 失败必须安静。 没网、超时、被限流、仓库还没发布过，都只返回一条提示，
不影响任何本地功能
版本比较用的是数字元组，不是字符串 —— 否则 1.0.10 会被判成小于 1.0.9。
从 v1.0.1 升级
sudo pacman -U cursor-manager-1.0.2-1-any.pkg.tar.zst下载哪个
| 文件 | 用途 |
|---|---|
cursor-manager-1.0.2-1-any.pkg.tar.zst |
Arch Linux：sudo pacman -U <文件> |
cursor-manager-1.0.2.tar.gz |
通用源码包，解包即用，也能被 pip install |
cursor_manager-1.0.2-py3-none-any.whl |
Python wheel，配合 pipx install |
SHA256SUMS |
上面三个文件的校验和 |
安装
Arch Linux
sudo pacman -U cursor-manager-1.0.2-1-any.pkg.tar.zst其他发行版（源码包，解包即用）
tar -xzf cursor-manager-1.0.2.tar.gz
cd cursor-manager-1.0.2
./cursor-manager # 直接跑
./install.sh # 或装到 ~/.local（含桌面入口和图标）pipx
pipx install cursor_manager-1.0.2-py3-none-any.whlPyGObject 无法用 pip 可靠安装，需要走发行版包管理器
（它只影响图形界面，命令行功能都不需要它）。
校验下载
sha256sum -c SHA256SUMS自检
make test # 导入器 45 + 删除 24 + 检查更新 25 + GUI 42 项四套自检都不需要人看图，退出码非 0 即失败。
selftest_update.py 全部用 mock 打桩，离线也能确定性跑。
这次新增的回归用例专门钉住黑底 bug：合成一个 8bpp + AND 掩码的 .cur，
断言「掩码标为透明的像素真的透明」且「不是 100% 不透明」。
已知限制
- Arch 包是按当前 Python 版本编译的（3.14）。Arch 换 Python 大版本后需等重新构建；
源码包不受影响 apply覆盖 niri / DMS / GTK / XWayland / gsettings；KDE 的kcminputrc未处理- 导入功能对 RLE 压缩的老式光标仍依赖 Pillow
v1.0.1
v1.0.1
新增删除主题功能，并修掉两个 v1.0.0 里的问题。
新增：删除主题
只能浏览、切换、导入确实不算"管理"，这个版本补上了删除。
因为这个操作不可逆，加了四道安全闸门：
| 闸门 | 行为 |
|---|---|
| 只删用户目录 | /usr/share/icons 里的系统主题会被拒绝，提示改用发行版包管理器 |
| 不删正在使用的 | 删掉当前主题会让所有程序静默回落到 Adwaita（正是本项目要防的坑），会拒绝并让你先切换 |
| 必须"长得像主题" | 既没有 cursors/ 也没有 index.theme 就拒绝，防止传错路径 |
| 默认进回收站 | 按 freedesktop 规范写 .trashinfo，可从文件管理器恢复；--purge 才是真删 |
cursor-manager remove <主题名> # 移入回收站
cursor-manager remove <主题名> --purge # 永久删除
cursor-manager remove <主题名> --dry-run # 只看会删什么、多大图形界面里头部多了删除按钮：删不动的时候按钮直接禁用，悬停会说明原因
（"位于系统目录…" / "它正是当前生效的主题…"），不会让你点了才被拒。
修复
在非 niri 的机器上凭空创建 ~/.config/niri/。
v1.0.0 的 apply 无条件创建 ~/.config/niri/dms/ 再写文件。
GNOME / KDE / X11 用户跑一次 apply，家目录里就多出一个 niri/ 目录。
现在会先检查 ~/.config/niri/ 是否存在，不存在则跳过并在报告里标注。
自检硬编码主题名。
selftest_gui.py 原来断言"自动选中的是 Kinomoto-Sakura"，
用户换主题后自检会莫名其妙失败（代码一行没改）。现在改为从实际状态读出当前生效的主题。
文档
README 补上了平台支持矩阵 —— 功能 × 平台、apply 到底写哪些配置、
哪些桌面只部分支持（KDE 不写 kcminputrc、sway/Hyprland 需自行设 XCURSOR_THEME 等）。
docs/NOTES.md 记录了几个测试时踩的坑，其中一个值得单独提醒：
HOME=假目录隔离不了 gsettings。 dconf 由会话总线上的服务写，
客户端只是通过 D-Bus 发变更，真正落盘的是那个已用真实环境启动的服务。
所以拿假 HOME 测apply仍然会改到你真实的org.gnome.desktop.interface cursor-theme，
而且不会报错。测试apply一律加--dry-run。
从 v1.0.0 升级
Arch 用户直接用新包覆盖：
sudo pacman -U cursor-manager-1.0.1-1-any.pkg.tar.zst其他安装方式重新执行一次安装命令即可，配置无需改动。
下载哪个
| 文件 | 用途 |
|---|---|
cursor-manager-1.0.1-1-any.pkg.tar.zst |
Arch Linux：sudo pacman -U <文件> |
cursor-manager-1.0.1.tar.gz |
通用源码包，解包即用，也能被 pip install |
cursor_manager-1.0.1-py3-none-any.whl |
Python wheel，配合 pipx install |
SHA256SUMS |
上面三个文件的校验和 |
安装
Arch Linux
sudo pacman -U cursor-manager-1.0.1-1-any.pkg.tar.zst其他发行版（源码包，解包即用）
tar -xzf cursor-manager-1.0.1.tar.gz
cd cursor-manager-1.0.1
./cursor-manager # 直接跑
./install.sh # 或装到 ~/.local（含桌面入口和图标）pipx
pipx install cursor_manager-1.0.1-py3-none-any.whlPyGObject 无法用 pip 可靠安装，需要走发行版包管理器
（它只影响图形界面，--list / --import / apply / remove 都不需要它）。
校验下载
sha256sum -c SHA256SUMS自检
make test # 导入器 38 项 + 删除 24 项 + GUI 39 项三套自检都不需要人看图，退出码非 0 即失败。
删除功能的 24 项全部在伪造的 HOME 里跑，包括"闸门拒绝时确实没动手"和
回收站 .trashinfo 的 Path 能正确还原。
已知限制
- Arch 包是按当前 Python 版本编译的（3.14）。Arch 换 Python 大版本后需等重新构建；
源码包不受影响 apply覆盖 niri / DMS / GTK / XWayland / gsettings；KDE 的kcminputrc未处理- 导入功能对非 32bpp 的老式
.cur依赖 Pillow
v1.0.0
v1.0.0
Linux 鼠标光标主题管理器 —— 在 niri / Wayland 上浏览、动画预览、一键切换光标主题，
还能直接导入 Windows 的 .ani 光标包。
亮点
- 一次写全 6 个配置点 —— niri、DMS、GTK3、GTK4、
.Xresources、gsettings。
Wayland 下没有全局光标设置，漏掉任何一处，那一类程序就会继续用 Adwaita - 把"静默失败"标红 —— 主题目录缺一层
cursors/时，Wayland 客户端会悄悄忽略它
并回落到 Adwaita，不报任何错。这个工具把布局校验做成界面上可见的 ✔/✘ - 动画预览 —— 自己解码 Xcursor 二进制格式逐帧播放，普通图片查看器打不开这种文件
- 导入 Windows 光标包 —— 优先读包内
.inf的[Strings]段拿到微软官方角色映射，
比按文件名猜可靠得多；自动从 256×256 原图降采样出多档尺寸 - CLI 不依赖 GTK ——
--list/--import/apply在无图形环境的服务器上也能用
下载哪个
| 文件 | 用途 |
|---|---|
cursor-manager-1.0.0-1-any.pkg.tar.zst |
Arch Linux 用户装这个：sudo pacman -U <文件> |
cursor-manager-1.0.0.tar.gz |
通用源码包。解包即用（./cursor-manager），也能 pip install 它 |
cursor_manager-1.0.0-py3-none-any.whl |
Python wheel，配合 pipx install 使用 |
SHA256SUMS |
上面三个文件的校验和 |
安装
Arch Linux
sudo pacman -U cursor-manager-1.0.0-1-any.pkg.tar.zst依赖会自动从仓库装（python-gobject、gtk4、python-numpy、python-pillow）。
其他发行版（源码包，解包即用）
tar -xzf cursor-manager-1.0.0.tar.gz
cd cursor-manager-1.0.0
./cursor-manager # 直接跑
./install.sh # 或者装到 ~/.local（含桌面入口和图标）pipx
pipx install cursor_manager-1.0.0-py3-none-any.whlPyGObject 无法用 pip 可靠安装，需要走发行版包管理器：
sudo pacman -S python-gobject gtk4 # Arch
sudo apt install python3-gi gir1.2-gtk-4.0 # Debian / Ubuntu
sudo dnf install python3-gobject gtk4 # Fedora用法
cursor-manager # 图形界面
cursor-manager --list [-v] # 列出已安装主题
cursor-manager apply <主题名> [尺寸] # 切换主题
cursor-manager apply <主题名> --dry-run # 只报告会改哪些文件
cursor-manager --import <路径> [选项] # 导入 Windows 光标包
cursor-manager --help切换后 niri 保存配置时会自动重载，但已经开着的程序需要重启才能换过来。
校验下载
sha256sum -c SHA256SUMS环境要求
- Linux + Wayland（niri、DMS 为最佳适配）
- Python 3.10+
- PyGObject + GTK4（仅图形界面需要，CLI 不需要）
- numpy、Pillow（可选；没有会自动退回纯 Python 实现，只是慢一些）
已知限制
- Arch 包是按当前 Python 版本编译的（3.14）。Arch 滚动更新换 Python 大版本后，
需要等包重新构建；源码包不受影响 apply目前只覆盖 niri / DMS / GTK / XWayland / gsettings 这几条链路；
KDE 的kcminputrc没有处理（KDE 用户可以用 CLI 的--dry-run看会改什么）- 导入功能对非 32bpp 的老式
.cur依赖 Pillow；没装 Pillow 时只支持 32bpp
自检
这个版本带两套机器可验证的自检，不需要人看图，退出码非 0 即失败：
make test # GUI 29 项 + 导入器 38 项selftest_import.py 会自己合成光标包，没有外部素材也能完整跑。
另有 verify_cursor.c，用 libXcursor 官方 API 验证"主题名能否真的被加载"。
首次发布。