Make/Qt_DesktopPet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Finalize desktop pet feature set and GitHub export

Browse Source
This commit is contained in:
Make
2026-06-17 04:50:25 +08:00
parent 6c2926b57a
commit 6812dbb110
62 changed files with 7774 additions and 504 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+183 -358
View File
@@ -1,297 +1,127 @@
# QtDesktopPet
QtDesktopPet 是一个基于 Qt Widgets / C++17 的 Windows 桌面宠物项目，当前已具备多状态 PNG 帧动画、托盘控制、角色包导入与切换、用户自定义大模型对话、设置面板和 Windows 发布打包能力。项目现阶段重点是完善稳定性、性能回归、角色管理和发布体验。
一个基于 **Qt 6 Widgets / C++17** 的 Windows 桌面宠物项目。它提供透明桌宠窗口、PNG 序列帧动画、多状态切换、托盘控制、AI 对话、本地提醒、天气查询、简单文件操作和本地应用启动等能力。
## 当前状态
> 当前仓库仍处于活跃开发阶段。角色素材、图标和音效的再分发权限需要在正式公开发布前单独确认。
已实现：
![Preview](resources/characters/shiroko/preview.png)
- 透明无边框桌宠窗口
- 鼠标拖动
- 右键菜单退出和状态测试
- 置顶切换
- `resources/characters/shiroko` 默认角色包读取
- PNG 序列帧动画播放
- `idle` / `talk` / `think` / `sleep` / `happy` / `drag` / `error` 状态
- 托盘显示、隐藏、退出
- 单实例限制，重复启动会唤醒已有实例
- 隐藏时暂停动画，显示时恢复动画
- 保存窗口位置、置顶、缩放和性能设置
- 文件日志和基础轮转
- 设置窗口按当前屏幕居中弹出
- 应用设置：缩放、性能模式、隐藏暂停、懒加载
- 状态级动画预热和 LRU 缓存卸载
- AI Provider 分组配置
- 设置页内 AI 连通性测试
- Windows DPAPI 加密保存 API Key
- 非 Windows 环境经用户确认后明文保存 API Key
- OpenAI Compatible 聊天请求
- SSE 流式输出
- 聊天输入框
- AI 回复气泡
- 对话历史面板
- 内存历史上限和可选本地历史保存
- AI 请求取消和对话清空
- Google Gemini 原生聊天请求
- 角色文件夹导入和角色切换
- 删除用户导入角色
- 本地一次性和重复提醒：聊天创建、查询、取消，重启后 pending 提醒不丢
- 提醒到点气泡提示、稍后提醒、拖动后延迟提示和隐藏时托盘通知
- 提醒音效切换、试听、用户 wav 导入和删除
- Windows 发布打包脚本和 Inno Setup 安装器脚本
- Windows GUI 子系统，Release exe 双击不弹控制台窗口
## Features
尚未实现：
- 透明无边框桌宠窗口，支持拖动、置顶、托盘隐藏和单实例唤醒。
- 多状态 PNG 序列帧动画：`idle`、`talk`、`think`、`sleep`、`happy`、`drag`、`error`。
- 角色包导入、切换、导出和用户角色目录管理。
- AI 对话：
- OpenAI-compatible API
- Google Gemini API
- DeepSeek / Custom Provider 配置
- 流式输出、请求取消、对话历史面板
- Windows DPAPI 加密保存 API Key
- 联网模式：
- 输入框“联网”开关
- OpenAI 官方 Responses API Web Search
- Gemini Google Search grounding
- DeepSeek / Custom 默认提示不支持或无法确认原生联网
- 本地提醒：
- 一次性提醒
- 每天 / 每周 / 每月重复提醒
- 提醒音效导入、试听、切换
- 桌宠可见时气泡提示，隐藏或 AI 忙时系统通知
- 天气查询：
- Open-Meteo Forecast API
- Open-Meteo Geocoding API
- 默认城市、公网 IP 定位兜底、多候选提示
- 本地文件操作 v1：
- 读取文本文件
- 列出文件夹
- 复制、备份、重命名
- 写操作前二次确认
- 应用启动 v1：
- 聊天触发打开本地应用
- 支持已登记应用、开始菜单快捷方式和用户手选 `.exe`
- 启动前二次确认
- Windows 发布脚本和 Inno Setup 安装器脚本。
- 角色导出和更完整的管理界面
- 对话历史导出/管理界面
- 长期性能压测记录
- 发布包实机安装/卸载验证
## Platform
## 技术栈
当前主要目标平台是 Windows 10 / Windows 11。
项目中已有部分跨平台基础代码，但托盘通知、开机自启动、应用发现和安装器体验目前按 Windows 优先实现。
## Tech Stack
- C++17
- Qt 6 Widgets
- Qt 6 Network
- Qt 6 Multimedia
- CMake
- PNG 图片序列帧
- JSON 配置文件
- Windows 10 / Windows 11 优先
- JSON 配置
- PNG 序列帧动画
- Inno Setup
## 构建
## Repository Layout
推荐环境：
```text
.
├── CMakeLists.txt
├── main.cpp
├── installer/ # Inno Setup script
├── resources/
│ ├── characters/ # Built-in character packages
│ ├── icons/
│ └── sounds/
├── src/
│ ├── ai/ # AI providers and conversation state
│ ├── assistant/ # Intent routing and command dispatch
│ ├── character/ # Character package loading and animation
│ ├── config/ # Config persistence
│ ├── fileops/ # Local file operations
│ ├── launcher/ # Local application launcher
│ ├── notification/ # Notification dispatch
│ ├── reminder/ # Reminder parser/store/scheduler/sounds
│ ├── state/ # Pet state machine
│ ├── system/ # Windows startup integration
│ ├── tray/ # System tray controller
│ ├── ui/ # Widgets and main pet window
│ ├── util/
│ ├── weather/
│ └── web/ # AI-native web mode
└── tools/ # Packaging and diagnostic scripts
```
- Qt 6.5.3
## Build
Recommended environment:
- Qt 6.5+
- CMake 3.20+
- Ninja
- MinGW 11.2.0 或已配置好的 Qt MSVC Kit
- MinGW 11.2.0 or a configured Qt MSVC Kit
MinGW 示例：
Example with MinGW:
```powershell
cmake -S . -B build/mingw-debug -G Ninja `
-DCMAKE_BUILD_TYPE=Debug `
cmake -S . -B build/mingw-release -G Ninja `
-DCMAKE_BUILD_TYPE=Release `
-DCMAKE_PREFIX_PATH=D:/Qt/6.5.3/mingw_64 `
-DCMAKE_C_COMPILER=D:/Qt/Tools/mingw1120_64/bin/gcc.exe `
-DCMAKE_CXX_COMPILER=D:/Qt/Tools/mingw1120_64/bin/g++.exe
cmake --build build/mingw-debug
cmake --build build/mingw-release
```
如果使用 Qt Creator，也可以直接打开根目录 `CMakeLists.txt`，选择合适的 Qt Kit 后构建。
Qt Creator users can open `CMakeLists.txt` directly and build with a matching Qt Kit.
## 应用图标
## Package
当前应用图标位于：
```text
resources/icons/app_icon.ico
resources/icons/app_icon_1024.png
```
`app_icon.ico` 用于窗口图标、托盘图标和 Windows exe 资源图标；托盘图标加载失败时会回退到默认角色包的 `preview.png`。`app_icon_1024.png` 作为高分辨率源图保留。
运行时会优先读取可执行文件同级的 `resources/icons/`，找不到时回退到源码目录下的 `resources/icons/`。Windows exe 图标需要重新构建后生效。
## 角色包
当前默认角色包位于：
```text
resources/characters/shiroko/
```
内置角色包按 `resources/characters/<characterId>/` 组织。用户导入的角色包不会写入安装目录，而是复制到用户数据目录：
```text
QStandardPaths::AppDataLocation/characters/<characterId>/
```
角色包基本结构：
```text
resources/characters/shiroko/
character.json
preview.png
idle/
talk/
think/
sleep/
happy/
drag/
error/
```
当前素材版本为 `2.1.0-stable`，所有帧使用 512x512 透明画布。当前实现会读取当前角色包的各状态配置，并按 `character.json` 中的 FPS 播放。
运行时会合并内置角色和用户导入角色；内置资源优先读取可执行文件同级的 `resources/characters/`，找不到时回退到源码目录下的 `resources/characters/`。
角色导入：
- 只支持导入本地文件夹，不支持 zip
- 导入前先验证源文件夹；验证失败只弹窗提示，不复制、不创建、不覆盖文件
- 验证通过后复制到用户数据目录
- 角色 id 优先读取 `character.json` 的 `id`；为空时使用文件夹名
- 角色 id 只允许 ASCII 字母、数字、点、下划线和短横线，且不能以点开头或结尾
- 用户角色同名时会询问是否覆盖
- 内置角色 id 不能被导入包覆盖
- 验证要求：`character.json` 可解析、id 安全、存在 `idle` 和 `defaultState`、状态路径安全、fps 合法、每个声明状态至少有一张可读 PNG
- 如果 `base.anchorY + bubble.offsetY` 计算出的气泡锚点明显偏低，导入时会提示用户检查配置，但不强制阻止导入
- 只允许删除用户导入角色；选择内置角色删除时只会提示“不能删除内置角色”，不做文件操作
懒加载现状：
- `enableLazyLoad=true` 时，启动阶段只建立状态到帧路径的索引
- 某个状态首次播放时加载该状态的 PNG 帧
- 启动后会在主线程按批次预热常用状态，避免一次性加载全部帧
- 已加载状态按状态级 LRU 策略管理，超过动画缓存上限时卸载非保护状态
- 单轮预热不会反复重新加载刚被 LRU 卸载的状态，避免缓存上限较低时出现加载/卸载循环
- 隐藏到托盘时可释放非保护动画缓存
- `enableLazyLoad=false` 时仍保持启动阶段加载全部状态帧的兼容行为
## 定时提醒和音效
当前支持通过聊天输入创建一次性和重复本地提醒，例如：
```text
10分钟后提醒我喝水
半小时后提醒我休息
一个半小时后提醒我喝水
明天9点提醒我开会
后天9点提醒我开会
6月3日9点提醒我提交
下周一上午10点提醒我周会
每天9点提醒我打卡
每天提醒我9点打卡
每日晚上8点提醒我吃药
每周一上午10点提醒我周会
每周一提醒我上午10点周会
每星期五下午3点提醒我提交周报
每月3号9点提醒我交报告
每月3号提醒我9点交报告
提醒列表
取消喝水提醒
```
提醒数据保存到：
```text
QStandardPaths::AppConfigLocation/reminders.json
```
提醒数据使用原子写入，写入失败时不会触发到点 UI，也不会覆盖旧的有效提醒文件。已触发和已取消记录会写入 `finishedAt`；旧版数据没有该字段时按 `remindAt` 兼容读取。
提醒调度保留最近提醒的精确 timer，同时每 60 秒做一次兜底扫描；程序显示、外部激活或系统睡眠唤醒后，都会重新检查已到期 pending 提醒。
设置页支持编辑 pending 提醒的标题、下一次时间和重复规则；已触发/已取消历史只读。历史记录默认只保留最近 20 天，设置页“清理20天前历史”只删除超过 20 天的已触发/已取消记录，不影响 pending。
提醒文件损坏时会备份为：
```text
reminders.broken.yyyyMMdd-HHmmss.json
```
内置提醒音效位于：
```text
resources/sounds/reminders/
```
用户导入的提醒音效保存到：
```text
QStandardPaths::AppDataLocation/sounds/reminders/
```
音效规则：
- 默认音效为 `reminder_default`
- 提醒触发时使用当前设置页选择的全局音效；修改音效后对所有未触发提醒立即生效
- 内置音效可切换、可试听，但不能在设置页删除
- 用户音效只支持导入 PCM wav
- 用户导入音效可切换、可试听、可删除
- 删除当前用户音效后会回退到 `reminder_default`
触发规则：
- 桌宠可见时显示气泡，不发系统通知
- 桌宠隐藏时发 Windows 托盘通知，不在下次显示时补气泡
- AI 正在请求或流式回复时，按隐藏场景处理：播放音效并发 Windows 托盘通知，不显示气泡
- 托盘或系统通知后端不可用时只记录日志，不补气泡
- 用户拖动中不打断 `drag`，拖动结束后显示气泡
- 多条提醒同时触发时，可见状态下会按队列逐条展示
- 桌宠可见触发时显示 `知道了` 和 `5分钟后再提醒`
- `5分钟后再提醒` 会创建一条新的一次性提醒，不影响原重复规则
- 重复提醒支持 `每天 / 每周 / 每月`；`工作日 / 每两天 / 每月最后一天 / 自定义间隔 / 农历` 等复杂规则暂不支持
- 每月 31 号这类规则会跳过不存在该日期的月份，寻找下一个有效月份
- 用户音效删除仅允许删除用户音效目录内的安全 sound id，内置音效和非法路径不会被删除
## 配置和日志
应用配置保存到 Qt 标准配置目录：
```text
QStandardPaths::AppConfigLocation/app_config.json
```
配置损坏时会备份为带时间戳的文件：
```text
app_config.broken.yyyyMMdd-HHmmss.json
ai_config.broken.yyyyMMdd-HHmmss.json
conversation_history.broken.yyyyMMdd-HHmmss.json
```
日志输出到文件，不输出到控制台：
```text
QStandardPaths::AppConfigLocation/logs/QtDesktopPet.log
```
如果 Qt 无法取得标准配置目录，则回退到当前工作目录下的 `logs/QtDesktopPet.log`。
日志轮转规则：
- 单个日志文件超过 2MB 时轮转
- 最多保留 3 个旧日志文件
- 文件名为 `QtDesktopPet.log.1`、`QtDesktopPet.log.2`、`QtDesktopPet.log.3`
## 发布打包
仓库提供 Windows Release 打包脚本。脚本不负责 CMake 构建，先手动完成 Release 构建，再把 exe 路径传给脚本：
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools/package_release.ps1 -ExePath build/release/QtDesktopPet.exe
```
脚本会生成目录包和 zip：
```text
dist/QtDesktopPet-<version>-windows-x64/
dist/QtDesktopPet-<version>-windows-x64.zip
```
发布目录包含：
```text
QtDesktopPet.exe
Qt runtime
resources/characters/
resources/icons/
resources/sounds/
LICENSE
README.md
```
脚本会调用 `windeployqt.exe` 收集 Qt 运行库。若当前 PATH 找不到 `windeployqt.exe`，需要指定 Qt bin 目录下的工具路径：
After building a Release executable, package it with:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools/package_release.ps1 `
-ExePath build/release/QtDesktopPet.exe `
-WindeployQtPath D:\Qt\6.x.x\msvcXXXX_64\bin\windeployqt.exe
-ExePath build/release/QtDesktopPet.exe
```
生成 Inno Setup 安装器：
To generate the Inno Setup installer:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools/package_release.ps1 `
@@ -299,113 +129,108 @@ powershell -NoProfile -ExecutionPolicy Bypass -File tools/package_release.ps1 `
-BuildInstaller
```
安装器最终默认输出到项目根目录：
The installer supports optional desktop shortcut creation and optional Windows startup launch. Both are disabled by default.
## Runtime Data
Runtime configuration and user data are stored under Qt standard user directories:
- `QStandardPaths::AppConfigLocation`
- `QStandardPaths::AppDataLocation`
Examples:
- AI config: `ai_config.json`
- App config: `app_config.json`
- Conversation history: `conversation_history.json`
- Reminders: `reminders.json`
- Weather config: `weather_config.json`
- Web mode config: `web_config.json`
- Launcher config: `launcher_config.json`
The app writes rotating logs under:
```text
QtDesktopPet-<version>-windows-x64-setup.exe
QStandardPaths::AppConfigLocation/logs/QtDesktopPet.log
```
脚本会先让 Inno Setup 输出到当前盘符下的纯 ASCII 临时目录，例如 `D:\QtDesktopPetInstallerOutput`，再把最终安装包复制回项目根目录，避免中文项目路径下出现 `EndUpdateResource failed (5)`。如果需要改变最终安装包目录，可传入 `-InstallerOutputDir`：
## AI And Privacy
QtDesktopPet only sends chat content to the AI endpoint configured by the user.
Important notes:
- API keys are not logged.
- Authorization headers are not logged.
- Full user messages and full error bodies should not be logged.
- On Windows, API keys are saved with DPAPI when available.
- Third-party compatible APIs and proxy services are controlled by the user; this project cannot guarantee their privacy behavior.
## Safety Boundaries
The project intentionally keeps local automation conservative:
- File operations require user-selected paths.
- Write operations require confirmation.
- File operations do not execute scripts or commands.
- Application launch only supports `.exe` and Start Menu `.lnk` shortcuts.
- Chat text is not converted into shell commands.
- Startup integration writes only the current user's Windows `Run` entry.
## Web Mode
Web mode is an AI-native conversation feature, not a search engine scraper.
Supported:
- OpenAI official API with Responses API Web Search.
- Google Gemini API with Google Search grounding.
Not treated as supported native web access:
- DeepSeek official API
- Custom OpenAI-compatible endpoints
- Third-party relay APIs
Unsupported providers show an explicit message instead of falling back to unreliable search-page scraping.
## Character Packages
Built-in characters are placed under:
```text
resources/characters/<characterId>/
```
A character package contains:
```text
character.json
preview.png
idle/
talk/
think/
sleep/
happy/
drag/
error/
```
User-imported characters are copied to the user's app data directory instead of the installation directory.
## Public Export
This development workspace may contain internal planning and test documents. To create a clean public GitHub export, use:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools/package_release.ps1 `
-ExePath build/release/QtDesktopPet.exe `
-BuildInstaller `
-InstallerOutputDir D:\ReleaseOutput
powershell -NoProfile -ExecutionPolicy Bypass -File tools/prepare_github_export.ps1 `
-OutputDir D:\DesktopPet-github-export
```
如果需要改变 Inno Setup 的临时编译输出目录，可传入 `-InstallerWorkOutputDir`。
The export excludes internal docs, reports, build outputs, release packages, local config, logs and Git metadata.
本地生成的安装包也可以集中放到 `release_packages/`：
## License
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools/package_release.ps1 `
-ExePath build/release/QtDesktopPet.exe `
-BuildInstaller `
-InstallerOutputDir release_packages
```
Source code is released under the MIT License. See [LICENSE](LICENSE).
`dist/` 和 `release_packages/` 都是本地发布产物目录，不进入 Git。
脚本默认优先查找：
```text
D:\Inno Setup 7\ISCC.exe
D:\Inno Setup 6\ISCC.exe
C:\Program Files (x86)\Inno Setup 7\ISCC.exe
C:\Program Files (x86)\Inno Setup 6\ISCC.exe
```
如果 Inno Setup 安装在其他位置，可传入 `-InnoCompilerPath`。
安装器卸载时会询问是否同时删除用户配置、导入角色、聊天记录和日志；用户确认后会在卸载完成阶段删除当前用户下的 QtDesktopPet 数据目录。
## 开发诊断
仓库提供开发用性能采样脚本，不进入普通用户发布包：
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools/perf_sample.ps1
```
默认采样当前 `QtDesktopPet` 进程 5 分钟，每 5 秒一条，CSV 输出到：
```text
reports/perf/
```
`reports/perf/` 已加入 `.gitignore`。稳定性检查记录模板见：
```text
docs/performance_stability_check.md
```
发布包应排除 `tools/`、`docs/`、`reports/`、`build/`、`dist/`、`release_packages/` 和 `.git/`，只保留运行必需文件、`resources/characters/`、`resources/icons/`、`resources/sounds/`、`LICENSE` 和必要说明。
## AI 配置和聊天
当前正式聊天支持 OpenAI Compatible 和 Google Gemini 两类协议。已提供以下 Provider 配置入口：
- OpenAI
- Google
- DeepSeek
- Custom
其中 OpenAI、DeepSeek、Custom 走 OpenAI Compatible 形式配置；Google 走 Gemini 原生 REST 接口。旧版保存过的已废弃 Provider 配置会在读取 AI 配置时清理，废弃 Provider 被选中时会回退为 `custom`。
已支持：
- 用户自定义 Base URL
- 用户自定义 API Key
- 用户自定义 Model
- 用户自定义 Path
- 超时、Temperature、Max Tokens
- 流式输出
- Google Gemini `generateContent` / `streamGenerateContent`
- 请求中切换 `think`
- 收到首段输出后切换并保持 `talk`
- 失败时切换 `error`
- API Key 不写入日志，不在错误提示中完整显示
- 对话历史面板记录用户消息和 AI 最终回复
AI 测试入口已从角色右键菜单移除，并迁移到设置页。
## 隐私说明
程序只会把用户消息发送到用户自己配置的接口。用户需要自行判断第三方代理、中转服务或自建服务是否可信。项目不会默认承诺第三方接口的隐私安全。
日志会记录请求诊断信息，例如 Provider、Base URL 主机、Path、HTTP 状态码、响应大小、错误摘要等；日志不应记录完整 API Key、Authorization Header、完整消息正文或完整错误响应正文。错误响应只保留脱敏摘要。
当前对话历史默认保存在内存中，已支持内存历史上限、请求上下文截取和可选本地历史保存；相关上限可在设置页调整。
## 素材版权说明
源码采用 MIT License。
角色素材、图片、图标等资源需要单独确认授权。当前 `shiroko` 素材用于桌宠加载器、动画和状态切换测试；在公开发布或正式分发前，需要确认素材的版权、再分发权限和适用范围。
用户导入或替换的素材，其版权责任由用户自行承担。
## 许可证
项目源码使用 MIT License，见 [LICENSE](LICENSE)。
Character art, icons, sounds and other media assets may have separate copyright requirements. Confirm asset licensing before public redistribution.