# DesktopPet

**Repository Path**: oywb33/desktop-pet

## Basic Information

- **Project Name**: DesktopPet
- **Description**: # 桌面宠物（PyQt5）使用说明
一个完全透明的置顶桌面宠物：待机动画（眨眼 + 晃动）、拖拽移动、点击对话、
右键菜单、屏幕边缘来回行走，可打包成单文件 exe。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 桌面宠物（PyQt5）使用说明

一个完全透明的置顶桌面宠物：待机动画（眨眼 + 晃动）、拖拽移动、点击对话、
右键菜单、屏幕边缘来回行走，可打包成单文件 exe。

---

## 一、项目结构

```
DesktopPet/
├── main.py                桌宠主程序（完整源码，带详细注释）
├── make_sample_assets.py  一键生成示例素材（橘猫，Pillow 绘制）
├── README.md              本教程
└── assets/
    ├── idle/              待机动画帧   idle_000.png, idle_001.png …
    ├── walk/              行走动画帧   walk_000.png,  walk_001.png …
    └── app.ico            程序 / 托盘图标（打包 exe 用）
```

## 二、快速体验

```bat
:: 1. 安装依赖（只需一次）
pip install pyqt5 pillow

:: 2. 生成示例素材（一只橘猫；有自己素材可跳过）
python make_sample_assets.py

:: 3. 直接运行
python main.py
```

> 没有任何素材时程序也不会报错，会显示一个粉色占位球提示放入素材。

## 二·五、自动换装模式

当前 `assets/idle/` 里放的是 6 套「极简高级御姐」换装帧（基于一张照片由 AI 生成、
AI 抠图成透明背景），程序每 2.5 秒自动切换到下一套造型，形成自动换装循环。

- 换装节奏：改 `main.py` 顶部 CONFIG 的 `idle_frame_interval_ms`（毫秒），
  数值越大每套停留越久；
- 换回连续动作动画：把该值改回 `130`，并把多帧动作序列放进 `assets/idle/`。

### 一键自动化工具 auto_pet_maker.py

换照片 / 换服装后，不用改代码，一条命令完成全部处理：

```bat
:: ① 把换装图放进 work/ 目录（命名 out_0.png、out_1.png …）
::    —— 换装图由对话中的 AI 按 costumes.json 模板生成，或自己准备任意人物全身图
:: ② 一键全自动：AI 抠图 → 居中方形裁帧 → 替换素材(自动备份旧的) → 更新节奏 → 重新打包 exe
python auto_pet_maker.py make

:: 只抠图+替换素材（不打包）
python auto_pet_maker.py cut

:: 只重新打包 exe
python auto_pet_maker.py pack

:: 生成换装造型模板（AI 换装生成阶段使用）
python auto_pet_maker.py template
```

常用参数：`--input 目录`（换装图位置，默认 work/）、`--size 512`（帧边长）、
`--interval 2500`（每套停留毫秒数）、`--skip-pack`（跳过打包）。
自动打包前会备份旧素材到 `assets/backup_idle_时间戳/`，随时可回退。

## 三、打包成独立单文件 exe

### 3.1 一次打包

```bat
:: 建议用干净的虚拟环境打包（环境越干净，体积越小、误报越少）
py -m venv venv
venv\Scripts\activate

pip install pyqt5 pillow pyinstaller
python make_sample_assets.py

pyinstaller -F -w --noupx --clean -n DesktopPet -i assets/app.ico --add-data "assets;assets" main.py
```

- `-F`：打包成单文件 exe
- `-w`：无控制台窗口（纯 GUI）
- `--noupx`：禁用 UPX 压缩（UPX 是杀毒误报的最主要原因之一）
- `-i`：exe 图标（没有 .ico 可去掉这行参数）
- `--add-data "assets;assets"`：把素材打进 exe（Windows 用分号 `;` 分隔）

产物：`dist\DesktopPet.exe`，双击即可运行，**目标机器不需要安装 Python**。

### 3.2 常见打包问题

| 问题 | 解决 |
| --- | --- |
| 提示没有 PyInstaller | `pip install pyinstaller` |
| Python 版本太新装不上 PyQt5 | 建议用 Python 3.8 ~ 3.12（官方有预编译轮子，打包兼容性最好） |
| exe 被杀毒软件删除 | 见第四节“杀毒误报处理” |
| 运行报缺 dll | 安装微软 VC++ 运行库（Microsoft Visual C++ Redistributable） |

## 四、杀毒误报处理

PyInstaller 单文件 exe 偶尔会被杀软误报，原因是它运行时要在临时目录
解压再执行，行为类似“加壳”。按下面的顺序处理，基本都能解决：

1. **打包时务必加 `--noupx`**：UPX 压缩最容易被误判，禁用后误报率大幅下降；
2. **用干净虚拟环境打包**：环境里只装 PyQt5 / pillow / pyinstaller，减少杂质；
3. **用 Python 官方安装包的 3.8~3.12 版本**（不要用“全家桶”整合版 Python）；
4. 仍误报时，把 exe 加入杀毒软件信任区 / 白名单；
5. 仍误报时，改用“文件夹模式”打包（去掉 `-F`），把整个 `dist\DesktopPet\`
   文件夹发给别人，文件夹模式极少误报；
6. 正式对外分发，建议购买代码签名证书对 exe 签名，或向杀软厂商申诉误报。

另外打包时 exe 名字建议用英文（`DesktopPet`），中英文都支持，但英文名在
杀软引擎里更“干净”。本程序源码没有使用任何 ctypes / 注册表 / 高危 API，
源码本身不会被误报，误报只可能发生在打包后的 exe 壳上。

## 五、素材替换教程（换角色不用改代码）

程序按“文件夹 + 文件名顺序”自动加载动画帧，所以你只需要：

### 5.1 目录与命名规则

| 目录 | 作用 | 命名 |
| --- | --- | --- |
| `assets/idle/` | 待机动画（含眨眼、晃动） | `idle_000.png`、`idle_001.png` … |
| `assets/walk/` | 行走动画（左右脚交替） | `walk_000.png`、`walk_001.png` … |
| `assets/app.ico` | 打包用的图标 | 可选 |

- 文件名**必须能按字母序排出播放顺序**，推荐 `xxx_000.png` 这种 0 填充编号；
- 所有帧建议**统一尺寸**（如 128×128 或 256×256），角色居中，四周留白；
  尺寸不一致时程序会拉伸铺满窗口，可能导致变形。

### 5.2 图片要求

- **必须是带 Alpha 通道的 PNG**（透明背景）；JPG 没有透明通道，不能直接用；
- 导出时确认背景是“棋盘格”透明，而不是白色；
- 角色不要画出窗口边界，四边至少留 4~8 像素透明边，避免被裁切。

### 5.3 怎么做出“眨眼 + 轻微晃动”

在待机动画帧序列里插几帧特殊表情即可：

```
第 0~3 帧：睁眼，身体上下偏移 0、-2、0、+2 像素   ← 轻微晃动
第 4 帧  ：半闭眼
第 5 帧  ：闭眼（画成一条线）
第 6 帧  ：半闭眼
第 7 帧  ：睁眼
```

循环播放后就是“眨一下眼 + 轻微晃动”的自然待机。参考
`make_sample_assets.py` 里的实现。

### 5.4 怎么做出“行走”

行走帧 4~8 帧即可，关键是**脚部交替**和**身体轻微起伏**：

- 奇数帧：左脚在前、右脚在后，身体上抬 2~3 像素；
- 偶数帧：右脚在前、左脚在后，身体回位。

没有 `walk/` 文件夹时，程序会自动用待机帧代替行走，照样能走。

### 5.5 更换步骤

```bat
:: 源码运行模式
1. 备份或删除旧的 assets 文件夹
2. 把新素材按 5.1 的规则放好
3. 重新运行 python main.py

:: exe 运行模式（不用重新打包！）
1. 在 DesktopPet.exe 旁边新建 assets 文件夹，放入新素材
2. 重启 exe 即可（程序优先读取 exe 同目录的 assets）
```

### 5.6 常用抠图 / 作图工具

- Photoshop / GIMP：魔棒或通道抠图，导出 PNG-24（带透明）；
- 在线抠图：remove.bg（自动抠人像/宠物）、稿定设计、美图秀秀；
- 动画帧：用剪辑软件或在线 GIF 拆帧工具，把每一帧存成独立 PNG；
- 如果素材是 GIF，可以拆成 PNG 序列后按编号命名。

## 六、常用自定义项（都在 main.py 顶部 CONFIG）

| 配置 | 说明 |
| --- | --- |
| `speed` | 行走速度（像素/步），越大越快 |
| `move_interval_ms` | 行走间隔（毫秒），越小越快 |
| `walk_after_idle_ms` | 闲置多久后开始行走 |
| `idle_frame_interval_ms` | 待机动画帧间隔 |
| `sway_pixels` | 待机晃动幅度，0 关闭 |
| `bubble_lifetime_ms` | 气泡显示时长 |
| `bubble_phrases` | 点击时随机说的话（随便增删） |

右键桌宠也可以直接调“缩放大小 / 移动速度”。

## 七、常见问题

**Q：拖拽或动画时出现残影？**
A：程序已用“Source 模式全窗清屏 + 整窗重绘”处理，正常不会有残影。
个别老显卡驱动下仍出现，请更新显卡驱动，或删除 main.py 中
`WA_NoSystemBackground` 那行再试。

**Q：点击没反应 / 拖不动？**
A：先确认是按左键。单击 = 快速按下抬起；拖拽 = 按下后移动超过 5 像素。

**Q：隐藏了怎么找回来？**
A：右下角系统托盘里有小猫图标，点击即可显示/隐藏。

**Q：多显示器下位置不对？**
A：当前默认在主显示器的可用区域（不含任务栏）内活动，多屏扩展
可按需在 `_place_on_screen` 中改用鼠标所在屏幕。