From 0ee797e224481013d6d4a708ede841910c8feef9 Mon Sep 17 00:00:00 2001 From: Ysm-04 Date: Mon, 1 Jun 2026 14:42:27 +0800 Subject: [PATCH] Refresh project documentation status --- .gitignore | 1 + README.md | 20 +++++++++++++++++--- docs/Qt_DesktopPet_开发文档.md | 8 ++++---- docs/implementation_plan.md | 22 ++++++++++++++++------ docs/performance_stability_check.md | 5 +++++ 5 files changed, 43 insertions(+), 13 deletions(-) diff --git a/.gitignore b/.gitignore index 9d0756a..c0189a8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ build/ dist/ +release_packages/ cmake-build-*/ .vs/ .vscode/ diff --git a/README.md b/README.md index 702cf97..7f21818 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # QtDesktopPet -QtDesktopPet 是一个基于 Qt Widgets / C++17 的 Windows 桌面宠物原型项目。当前目标是完成一个轻量桌宠内核，并在此基础上接入用户自定义的大模型对话能力。 +QtDesktopPet 是一个基于 Qt Widgets / C++17 的 Windows 桌面宠物项目，当前已具备多状态 PNG 帧动画、托盘控制、角色包导入与切换、用户自定义大模型对话、设置面板和 Windows 发布打包能力。项目现阶段重点是完善稳定性、性能回归、角色管理和发布体验。 ## 当前状态 @@ -14,10 +14,11 @@ QtDesktopPet 是一个基于 Qt Widgets / C++17 的 Windows 桌面宠物原型 - PNG 序列帧动画播放 - `idle` / `talk` / `think` / `sleep` / `happy` / `drag` / `error` 状态 - 托盘显示、隐藏、退出 +- 单实例限制，重复启动会唤醒已有实例 - 隐藏时暂停动画，显示时恢复动画 - 保存窗口位置、置顶、缩放和性能设置 - 文件日志和基础轮转 -- 设置窗口 +- 设置窗口按当前屏幕居中弹出 - 应用设置：缩放、性能模式、隐藏暂停、懒加载 - 状态级动画预热和 LRU 缓存卸载 - AI Provider 分组配置 @@ -35,6 +36,7 @@ QtDesktopPet 是一个基于 Qt Widgets / C++17 的 Windows 桌面宠物原型 - 角色文件夹导入和角色切换 - 删除用户导入角色 - Windows 发布打包脚本和 Inno Setup 安装器脚本 +- Windows GUI 子系统，Release exe 双击不弹控制台窗口 尚未实现： @@ -47,6 +49,7 @@ QtDesktopPet 是一个基于 Qt Widgets / C++17 的 Windows 桌面宠物原型 - C++17 - Qt 6 Widgets +- Qt 6 Network - CMake - PNG 图片序列帧 - JSON 配置文件 @@ -231,6 +234,17 @@ powershell -NoProfile -ExecutionPolicy Bypass -File tools/package_release.ps1 ` 如果需要改变 Inno Setup 的临时编译输出目录，可传入 `-InstallerWorkOutputDir`。 +本地生成的安装包也可以集中放到 `release_packages/`： + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -File tools/package_release.ps1 ` + -ExePath build/release/QtDesktopPet.exe ` + -BuildInstaller ` + -InstallerOutputDir release_packages +``` + +`dist/` 和 `release_packages/` 都是本地发布产物目录，不进入 Git。 + 脚本默认优先查找： ```text @@ -264,7 +278,7 @@ reports/perf/ docs/performance_stability_check.md ``` -发布包应排除 `tools/`、`docs/`、`reports/`、`build/`、`dist/` 和 `.git/`，只保留运行必需文件、`resources/characters/`、`resources/icons/`、`LICENSE` 和必要说明。 +发布包应排除 `tools/`、`docs/`、`reports/`、`build/`、`dist/`、`release_packages/` 和 `.git/`，只保留运行必需文件、`resources/characters/`、`resources/icons/`、`LICENSE` 和必要说明。 ## AI 配置和聊天 diff --git a/docs/Qt_DesktopPet_开发文档.md b/docs/Qt_DesktopPet_开发文档.md index f0f3841..c8cc519 100644 --- a/docs/Qt_DesktopPet_开发文档.md +++ b/docs/Qt_DesktopPet_开发文档.md @@ -2,7 +2,7 @@ ## 1. 项目目标 -本项目计划从零创建一个基于 **Qt / C++** 的 Windows 桌面宠物程序。 +本项目是一个基于 **Qt / C++** 的 Windows 桌面宠物程序。当前已实现轻量桌宠内核、多状态 PNG 帧动画、系统托盘、设置面板、用户角色包导入与切换，以及可配置的大模型对话能力。后续工作重点从“验证核心可行性”转向“稳定回归、体验完善、发布打包和长期维护”。 核心目标： @@ -50,7 +50,7 @@ 17. 低资源占用策略 ``` -### 2.2 第一版暂不实现 +### 2.2 第一版暂不实现或后续增强 ```text 1. 语音输入 @@ -65,10 +65,9 @@ 10. 云端同步 11. 自动更新 12. 长期记忆系统 -13. 完整安装器 ``` -第一版要控制范围，不要因为扩展功能过多导致项目失控。 +第一版要控制范围，不要因为扩展功能过多导致项目失控。当前已补齐基础 Inno Setup 安装器脚本，但仍需要继续做安装/卸载实机验证和发布体验打磨。 --- @@ -1414,6 +1413,7 @@ Windows 下不能只拷贝 exe。 6. 需要安装器时，脚本优先查找 D:\Inno Setup 7\ISCC.exe，并调用 ISCC 编译 installer/QtDesktopPet.iss 7. 安装器默认最终输出到项目根目录 8. Inno 编译阶段使用当前盘符下的纯 ASCII 临时目录，例如 D:\QtDesktopPetInstallerOutput，避免中文项目路径下出现 EndUpdateResource failed (5) +9. 如果需要集中保存安装包，可通过 -InstallerOutputDir release_packages 输出到 release_packages/ ``` 安装器卸载时需要询问用户是否删除用户数据。用户确认后，在卸载完成阶段删除当前用户的 QtDesktopPet 配置、导入角色、聊天记录和日志。 diff --git a/docs/implementation_plan.md b/docs/implementation_plan.md index 9706f28..69bb75e 100644 --- a/docs/implementation_plan.md +++ b/docs/implementation_plan.md @@ -381,7 +381,7 @@ error ：20 帧 1. AI 配置界面 2. 角色包市场 3. 自动更新 -4. 完整安装器 +4. 安装器实机验证和发布流程自动化 ``` 验收标准： @@ -505,6 +505,7 @@ docs/ reports/ build/ dist/ +release_packages/ .git/ ``` @@ -589,6 +590,8 @@ dist/ 运行时资源优先读取可执行文件同级 resources/，找不到时回退到源码目录 resources/ 已支持角色文件夹导入、角色切换和删除用户导入角色：验证通过后复制到用户数据目录，验证失败不做文件操作；内置角色不可删除 已新增 Windows 发布打包脚本和 Inno Setup 安装器脚本；脚本不负责 CMake 构建，安装器卸载时可由用户确认后清理当前用户数据目录 + 已接入单实例限制，重复启动会唤醒已有实例；设置页打开时按当前屏幕居中 + 已设置 Windows GUI 子系统，Release exe 双击不弹控制台窗口 ``` 当前实现与计划仍存在差异： @@ -607,17 +610,22 @@ dist/ 短期建议： ```text -1. 用户手测 Google Gemini Provider： +1. 用户手测单实例和窗口行为： + - 连续双击 exe 只保留一个 QtDesktopPet 进程 + - 隐藏到托盘后重复启动应唤醒已有实例 + - 设置页打开后重复启动应置前设置页 + - 多屏环境设置页应出现在当前屏幕中间 +2. 用户手测 Google Gemini Provider： - Google Provider 配置保存 - Gemini 普通回复 - Gemini 流式回复 - 错误 Key / 错误模型错误提示 -2. 用户手测流式状态修正： +3. 用户手测流式状态修正： - 发送消息后等待阶段应保持 think - 等待阶段拖动松开应回到 think - 收到首段回复后应进入 talk - 长文本流式输出期间应持续 talk -3. 用户手测应用设置： +4. 用户手测应用设置： - 缩放比例 - 标准 / 低功耗性能模式 - 隐藏到托盘时暂停动画 @@ -628,10 +636,12 @@ dist/ ```text 1. 完善设置界面： - - AI 配置和测试 - - 角色包导入和角色切换 + - 角色导出 + - 打开用户角色目录 + - 更完整的角色管理状态提示 2. 使用 tools/perf_sample.ps1 补一轮可重复的稳定性与性能测试记录 3. 使用 tools/perf_sample.ps1 验证状态级 LRU 卸载、主线程分批预热和动画缓存上限策略 +4. 做发布包安装/卸载实机验证，并确认 release_packages/ 或根目录安装包输出规则 ``` --- diff --git a/docs/performance_stability_check.md b/docs/performance_stability_check.md index 4320743..933570e 100644 --- a/docs/performance_stability_check.md +++ b/docs/performance_stability_check.md @@ -47,6 +47,8 @@ reports/perf/ | idle 连续播放 | 保持桌宠可见并播放 idle 10 分钟 | `tools/perf_sample.ps1 -DurationSeconds 600` | 动画持续播放，内存曲线稳定 | TODO | TODO | TODO | | 隐藏到托盘 | 可见采样 3 分钟，隐藏后再采样 3 分钟 | 两次采样分别记录 | 隐藏后 CPU 下降或保持低占用 | TODO | TODO | TODO | | 重复显示 / 隐藏 | 连续显示/隐藏 10 次 | `tools/perf_sample.ps1 -DurationSeconds 300` | 无崩溃，句柄数和内存无异常增长 | TODO | TODO | TODO | +| 重复启动 / 单实例 | 已运行时连续双击 exe 多次；隐藏到托盘后再双击 exe | 任务管理器或 `Get-Process QtDesktopPet` | 始终只有一个进程；隐藏状态可被重复启动唤醒 | TODO | TODO | 检查 QLocalServer 激活路径 | +| 设置页居中 / 置前 | 从托盘打开设置页；多屏环境重复打开；设置页已打开时再次启动 exe | 手工观察 | 设置页位于当前屏幕可用区域中心；重复启动时设置页置前 | TODO | TODO | 优先按宠物所在屏幕计算 | | 重复切换状态 | 通过右键状态测试切换 `idle/think/talk/error/drag` | `tools/perf_sample.ps1 -DurationSeconds 300` | 首次切换状态允许加载资源，缓存达到上限后按 LRU 卸载非保护状态 | TODO | TODO | 结合日志确认加载/卸载记录 | | 动画预热与卸载 | 默认配置启动后静置，随后隐藏到托盘再显示 | `tools/perf_sample.ps1 -DurationSeconds 600` | 日志出现有限次分批预热；隐藏后非保护动画缓存释放；显示后不会反复预热刚被卸载的状态 | TODO | TODO | 不应影响当前播放状态恢复 | | 缩放 / 置顶切换 | 设置页切换缩放，右键切换置顶 | `tools/perf_sample.ps1 -DurationSeconds 300` | 窗口尺寸和状态稳定，无崩溃 | TODO | TODO | TODO | @@ -86,6 +88,7 @@ docs/ reports/ build/ dist/ +release_packages/ .git/ ``` @@ -110,6 +113,8 @@ README.md 安装器最终文件默认放在项目根目录。Inno Setup 编译阶段使用当前盘符下的纯 ASCII 临时目录，例如 `D:\QtDesktopPetInstallerOutput`，再复制最终安装包回项目根目录，用于规避中文项目路径下可能出现的 `EndUpdateResource failed (5)`。 +如果需要把本地安装包集中保存，可通过 `-InstallerOutputDir release_packages` 输出到 `release_packages/`。该目录属于本地发布产物，不进入 Git。 + 运行时资源查找顺序： ```text