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