Initial project documentation and character package

2026-05-27 15:19:32 +08:00
commit 6ecb3ac494
33 changed files with 2209 additions and 0 deletions
@@ -0,0 +1,464 @@
+# QtDesktopPet 实施计划
+
+本文档用于把 `Qt_DesktopPet_开发文档.md` 中的总体目标拆成可执行阶段。
+
+总原则：
+
+```text
+1. 先让程序跑起来，再逐步完善架构和功能
+2. AI 接入放到桌宠内核稳定之后
+3. UI 优化作为项目收尾，不阻塞早期功能验证
+4. 每个阶段结束后做最小验收，避免问题堆到后期
+5. 修改、删除、移动文件前需要先说明风险并获得确认
+```
+
+---
+
+## 1. 已确认约定
+
+```text
+项目名：QtDesktopPet
+当前目录：Qt_DesktopPet
+主要平台：Windows 10 / Windows 11
+界面框架：Qt Widgets
+构建系统：CMake
+优先编译链：Qt 6.5.3 + MinGW 11.2.0 + Ninja
+默认角色包：shiroko
+AI 接入：放到后期阶段
+UI 优化：所有核心功能调试正常后再做
+远程仓库：https://git.emoera.com/Make/Qt_DesktopPet.git
+```
+
+---
+
+## 2. 本机工具检查结果
+
+当前已检查到：
+
+```text
+Git：2.51.0.windows.1
+CMake：3.29.3
+Qt：6.5.3
+Ninja：1.12.0
+MinGW g++：11.2.0
+MinGW mingw32-make：4.2.1
+```
+
+相关路径：
+
+```text
+Qt MinGW Kit：D:/Qt/6.5.3/mingw_64
+Qt MSVC Kit：D:/Qt/6.5.3/msvc2019_64
+MinGW 工具链：D:/Qt/Tools/mingw1120_64/bin
+CMake：D:/Qt/Tools/CMake_64/bin/cmake.exe
+Ninja：D:/Qt/Tools/Ninja/ninja.exe
+```
+
+注意：
+
+```text
+1. 当前 PATH 中的 qmake 默认指向 msvc2019_64
+2. g++ 未直接出现在 PATH 中
+3. 使用 MinGW 构建时，应显式指定 Qt MinGW 路径和编译器路径
+```
+
+建议 CMake 配置方式：
+
+```powershell
+cmake -S . -B build/mingw-debug -G Ninja `
+  -DCMAKE_BUILD_TYPE=Debug `
+  -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
+```
+
+---
+
+## 3. 角色包约定
+
+`shiroko` 目录作为当前默认角色包。
+
+已检查到的结构：
+
+```text
+shiroko/
+ ├── character.json
+ ├── preview.png
+ ├── README.md
+ ├── idle/
+ ├── talk/
+ ├── think/
+ ├── sleep/
+ ├── happy/
+ ├── drag/
+ └── error/
+```
+
+每个状态当前包含 4 帧 PNG。
+
+需要注意：
+
+```text
+1. character.json 中 base.width/base.height 为 627x627，超过原开发文档建议的 512x512
+2. 原型阶段可以接受，但后续需要观察内存、缩放缓存和低配设备表现
+3. 如果项目公开发布或推送远程仓库，需要确认 shiroko 素材版权和再分发权限
+4. 版权不明确前，不应把它作为正式开源发布素材承诺
+```
+
+---
+
+## 4. 阶段 0：仓库与工程准备
+
+目标：
+
+```text
+建立可回滚、可构建的工程基础，不写复杂业务逻辑。
+```
+
+已确定操作：
+
+```text
+1. 初始化 Git 仓库
+2. 配置 origin 为 https://git.emoera.com/Make/Qt_DesktopPet.git
+3. 新增实施计划文档
+```
+
+后续待做：
+
+```text
+1. 创建 .gitignore
+2. 创建 CMakeLists.txt
+3. 创建 main.cpp
+4. 创建 src/、resources/ 等基础目录
+5. 决定 shiroko 是否移动到 resources/characters/shiroko
+6. 创建最小 README.md
+7. 确认 LICENSE 是否采用 MIT
+```
+
+验收标准：
+
+```text
+1. Git 仓库存在
+2. origin 配置正确
+3. CMake 能完成配置
+4. 空项目或最小窗口项目能编译
+```
+
+需要确认：
+
+```text
+1. 是否创建 .gitignore
+2. 是否创建 MIT LICENSE
+3. 是否将 shiroko 移动到 resources/characters/shiroko
+4. 是否立即创建最小 Qt 工程
+```
+
+---
+
+## 5. 阶段 1：最小可运行桌宠窗口
+
+目标：
+
+```text
+先让程序启动并显示一个可交互的透明桌宠窗口。
+```
+
+只做：
+
+```text
+1. Qt Widgets + CMake 工程
+2. main.cpp
+3. PetWindow
+4. 透明无边框窗口
+5. 显示单张占位 PNG 或 shiroko preview.png
+6. 鼠标拖动
+7. 右键退出
+8. 置顶开关
+```
+
+暂不做：
+
+```text
+1. 完整角色包加载
+2. 多状态动画
+3. 状态机
+4. 托盘
+5. 配置系统
+6. 日志系统
+7. AI 接入
+8. UI 美化
+```
+
+验收标准：
+
+```text
+1. 程序能编译
+2. 程序能启动
+3. 窗口透明无边框
+4. 图片能显示
+5. 鼠标能拖动窗口
+6. 右键菜单能退出
+7. 置顶开关生效
+```
+
+---
+
+## 6. 阶段 2：接入 shiroko 角色包与 idle 动画
+
+目标：
+
+```text
+把单图显示升级为角色包驱动的 PNG 帧动画。
+```
+
+只做：
+
+```text
+1. CharacterPackage
+2. CharacterPackageLoader
+3. AnimationClip
+4. FrameAnimator
+5. 读取 shiroko/character.json
+6. 加载 idle 状态帧
+7. 按 fps 播放 idle 动画
+8. 启动失败时回退 preview.png 或内置占位图
+```
+
+暂不做：
+
+```text
+1. 多角色切换
+2. 角色导入界面
+3. 完整状态机
+4. AI 联动
+```
+
+验收标准：
+
+```text
+1. idle 动画正常播放
+2. 不在 paintEvent 中加载图片
+3. 不每帧读取硬盘
+4. fps 使用 character.json 配置
+5. character.json 缺失或损坏时程序不崩溃
+```
+
+---
+
+## 7. 阶段 3：状态机与多状态动画
+
+目标：
+
+```text
+集中管理桌宠状态，避免状态切换逻辑散落在窗口和动画类中。
+```
+
+只做：
+
+```text
+1. PetStateMachine
+2. idle / drag / think / talk / happy / sleep / error
+3. 拖动时切换 drag
+4. 松开后回 idle
+5. 右键菜单提供模拟状态切换
+6. loop=false 的状态播放完后切 next
+7. 缺失状态回退 idle
+```
+
+暂不做：
+
+```text
+1. 真实 AI 请求
+2. 长期记忆
+3. 复杂 sleep 触发策略
+4. UI 美化
+```
+
+验收标准：
+
+```text
+1. 状态切换由 PetStateMachine 决策
+2. FrameAnimator 只负责播放动画
+3. PetWindow 不堆积复杂状态判断
+4. shiroko 的多个状态动画都能被触发
+```
+
+---
+
+## 8. 阶段 4：托盘、配置、日志
+
+目标：
+
+```text
+补齐常驻桌面应用的基础设施。
+```
+
+只做：
+
+```text
+1. TrayController
+2. 托盘显示 / 隐藏桌宠
+3. 托盘退出
+4. ConfigManager
+5. 保存窗口位置、置顶状态、缩放、性能模式
+6. Logger
+7. 基础日志轮转
+8. 配置损坏时备份为 .broken.json
+```
+
+暂不做：
+
+```text
+1. AI 配置界面
+2. 角色包市场
+3. 自动更新
+4. 完整安装器
+```
+
+验收标准：
+
+```text
+1. 隐藏到托盘后动画暂停
+2. 重新显示后动画恢复
+3. 重启后窗口位置恢复
+4. 配置损坏不会导致程序崩溃
+5. 日志不会无限增长
+```
+
+---
+
+## 9. 阶段 5：稳定性与性能检查
+
+目标：
+
+```text
+在接入 AI 前，先确认桌宠内核稳定。
+```
+
+检查内容：
+
+```text
+1. 启动后静置 CPU 和内存
+2. idle 动画连续播放
+3. 隐藏到托盘后 CPU 是否下降
+4. 重复显示 / 隐藏
+5. 重复切换状态
+6. 删除或破坏 character.json 后是否兜底
+7. 删除部分状态目录后是否回退 idle
+8. 切换窗口置顶和缩放是否稳定
+```
+
+验收标准：
+
+```text
+1. 空闲 CPU 占用低
+2. 内存不随时间持续增长
+3. 没有明显资源泄漏
+4. 常见资源损坏不会崩溃
+```
+
+---
+
+## 10. 阶段 6：AI 接入
+
+目标：
+
+```text
+在桌宠内核稳定后，实现 OpenAI Compatible 非流式对话闭环。
+```
+
+只做：
+
+```text
+1. LLMProvider
+2. OpenAICompatibleProvider
+3. ConversationManager
+4. Base URL / API Key / Model / Path 配置
+5. QNetworkAccessManager 异步请求
+6. 请求超时
+7. 同时只允许一个请求
+8. think -> talk -> idle
+9. 失败 -> error -> idle
+10. 气泡显示 AI 回复或错误提示
+```
+
+暂不做：
+
+```text
+1. 流式输出
+2. 自定义 Body Template
+3. 多 Provider 市场
+4. 语音输入
+5. 语音朗读
+6. 长期记忆
+```
+
+验收标准：
+
+```text
+1. 能发送一条消息并显示回复
+2. Base URL 为空时有提示
+3. API Key 为空时有提示
+4. Model 为空时有提示
+5. 错误 API Key 不崩溃
+6. 错误 URL 或超时不崩溃
+7. 日志不输出完整 API Key
+8. 对话历史不会无限增长
+```
+
+---
+
+## 11. 阶段 7：UI 优化与收尾
+
+目标：
+
+```text
+核心功能可用后，再统一处理视觉体验和易用性。
+```
+
+只做：
+
+```text
+1. 优化右键菜单结构
+2. 优化气泡样式
+3. 优化设置界面布局
+4. 优化错误提示文案
+5. 优化 README 截图和说明
+6. 检查 DPI 和多屏表现
+7. 整理发布包
+```
+
+暂不做：
+
+```text
+1. 新增大功能
+2. 插件系统
+3. 角色包市场
+4. 在线素材下载
+```
+
+验收标准：
+
+```text
+1. Windows 10 / Windows 11 基本体验正常
+2. 无 Qt 开发环境机器上可运行
+3. README 能指导用户构建和配置
+4. 素材版权、AI 隐私和 API Key 本地保存说明齐全
+```
+
+---
+
+## 12. 当前未决问题
+
+后续开始写代码前，需要逐项确认：
+
+```text
+1. 是否创建 .gitignore
+2. 是否创建 MIT LICENSE
+3. 是否把 shiroko 移动到 resources/characters/shiroko
+4. 是否使用 shiroko/preview.png 作为阶段 1 单图
+5. 是否立即创建最小 Qt Widgets 工程
+6. 是否将 build/、.vs/、CMake 生成目录全部加入 .gitignore
+7. shiroko 素材是否允许提交到远程仓库
+```
+