桌面宠物换装引擎

解决桌面宠物形象固化的问题

如果你已经跑通了基于 v8 单窗口合成架构的桌面宠物工程，大概率会对默认的「布丁店长」产生审美疲劳。更换宠物形象听起来简单，但在 Windows 透明窗口和素材管理上却有不少坑：直接覆盖资源会丢失原始素材，手动抠图容易留下半透明像素导致渲染异常，动作动画的注册和打包流程也缺乏标准化。

本技能专为更换桌面宠物形象设计，让你可以通过提供自定义动漫或卡通 GIF，快速生成新的形象包并打包为独立 EXE。

核心工作流程

技能的核心是一个自包含的 Python 脚本 references/gen_swap.py，配合工程原有的 desktop_pet.py 完成整个换装流程：

• 素材收集与隔离：你需要准备 1 张待机 GIF（空闲图）和若干动作 GIF（如眨眼、伸懒腰）。技能会指导你复制整个工程目录（如 E:\desktop-pet-柴犬\），确保在独立副本中操作，绝不覆盖原始布丁素材。
• 智能抠图与素材生成：运行 gen_swap.py 处理收集到的 GIF。脚本内置两种背景移除算法：--method light 使用中性白连通分量法处理白底/浅色底；--method flood 则从四角进行 floodFill 填充，适合深色/纯色背景。抠图后会自动进行 alpha 二值化（np.where(bg,0,255)），生成无半透明像素的 PNG 素材。
• 特效注册与打包：修改新工程的 desktop_pet.py，将 effect_files 字典的 key 与生成的动作文件名对应。只要添加 key，_start_random_effect 会自动将其纳入每 5 秒触发的随机池。最后使用 PyInstaller 打包成 EXE 即可。

关键注意点与适用边界

在使用本技能时，有几个工程细节直接决定了最终效果成败：

• 警惕「紫边」效应：宠物窗口依赖 -transparentcolor 色键（品红 #ff00fe）实现异形透明，这是一种二值判断。任何半透明像素都会与品红底混合成无法去除的亮紫色。因此，alpha 二值化必须在 resize 之后执行，手动修图时也要避免羽化边缘。
• 首帧同源要求：空闲图与动作 GIF 的首帧必须来自同一张原图。代码通过「不透明内容底边中心」进行锚点对齐，如果素材不同源，待机与动作切换时会出现位置跳变或形变。
• 进程与构建管理：打包前务必杀掉旧的宠物进程，否则会报 PermissionError: [WinError 32]。同时，建议将测试用的 EXE 移入 dist/_old_builds/，避免用户误跑旧版本。

本技能仅适用于已配置好 Python 3.12 及依赖库（Pillow、opencv-python 等）的桌面宠物工程环境，不包含从零搭建宠物窗口的底层逻辑。