From c2ffc26b899b3edc5d76025a177277d240dfab8c Mon Sep 17 00:00:00 2001
From: Ysm-04 <ysm3150131407@gmail.com>
Date: Thu, 28 May 2026 21:28:15 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=20README=20=E5=92=8C=20MIT?=
 =?UTF-8?q?=20=E8=AE=B8=E5=8F=AF=E8=AF=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 LICENSE   |  21 ++++++++
 README.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 173 insertions(+)
 create mode 100644 LICENSE
 create mode 100644 README.md

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..240a8b8
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Make
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c5851a1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,152 @@
+# QtDesktopPet
+
+QtDesktopPet 是一个基于 Qt Widgets / C++17 的 Windows 桌面宠物原型项目。当前目标是先完成轻量桌宠内核：透明无边框窗口、PNG 序列帧动画、多状态切换、托盘隐藏、配置保存和基础日志。
+
+## 当前状态
+
+已实现：
+
+- 透明无边框桌宠窗口
+- 鼠标拖动
+- 右键菜单退出和状态测试
+- 置顶切换
+- `shiroko` 角色包读取
+- PNG 序列帧动画播放
+- `idle` / `talk` / `think` / `sleep` / `happy` / `drag` / `error` 状态
+- 托盘显示、隐藏、退出
+- 隐藏时暂停动画，显示时恢复动画
+- 保存窗口位置和置顶状态
+- 文件日志和基础轮转
+
+尚未实现：
+
+- AI 对话
+- AI 配置界面
+- ChatBubble 气泡
+- SettingsDialog
+- 角色导入/切换界面
+- 打包发布脚本
+
+## 技术栈
+
+- C++17
+- Qt 6 Widgets
+- CMake
+- PNG 图片序列帧
+- JSON 配置文件
+- Windows 10 / Windows 11 优先
+
+## 构建
+
+推荐环境：
+
+- Qt 6.5.3
+- CMake 3.20+
+- Ninja
+- MinGW 11.2.0 或已配置好的 Qt MSVC Kit
+
+MinGW 示例：
+
+```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
+
+cmake --build build/mingw-debug
+```
+
+如果使用 Qt Creator，也可以直接打开根目录 `CMakeLists.txt`，选择合适的 Qt Kit 后构建。
+
+## 角色包
+
+当前默认角色包位于：
+
+```text
+shiroko/
+```
+
+基本结构：
+
+```text
+shiroko/
+  character.json
+  preview.png
+  idle/
+  talk/
+  think/
+  sleep/
+  happy/
+  drag/
+  error/
+```
+
+当前素材版本为 `2.1.0-stable`，所有帧使用 512x512 透明画布。当前实现会加载当前角色包的各状态帧并按 `character.json` 中的 FPS 播放。
+
+后续计划将默认角色包位置整理为：
+
+```text
+resources/characters/shiroko/
+```
+
+## 配置和日志
+
+应用配置保存到 Qt 标准配置目录：
+
+```text
+QStandardPaths::AppConfigLocation/app_config.json
+```
+
+配置损坏时会备份为：
+
+```text
+app_config.broken.json
+```
+
+日志输出到文件，不输出到控制台：
+
+```text
+QStandardPaths::AppConfigLocation/logs/QtDesktopPet.log
+```
+
+如果 Qt 无法取得标准配置目录，则回退到当前工作目录下的 `logs/QtDesktopPet.log`。
+
+日志轮转规则：
+
+- 单个日志文件超过 2MB 时轮转
+- 最多保留 3 个旧日志文件
+- 文件名为 `QtDesktopPet.log.1`、`QtDesktopPet.log.2`、`QtDesktopPet.log.3`
+
+## AI 计划
+
+项目计划支持 OpenAI Compatible API，但当前尚未接入 AI。
+
+后续目标：
+
+- 用户自定义 Base URL
+- 用户自定义 API Key
+- 用户自定义 Model
+- 非流式对话请求
+- 请求中切换 `think`
+- 回复时切换 `talk`
+- 失败时切换 `error`
+- API Key 不写入日志，不在错误提示中完整显示
+
+## 隐私说明
+
+当前版本没有 AI 网络请求。
+
+后续接入 AI 后，程序只会把用户消息发送到用户自己配置的接口。用户需要自行判断第三方代理、中转服务或自建服务是否可信。项目不会默认承诺第三方接口的隐私安全。
+
+## 素材版权说明
+
+源码采用 MIT License。
+
+角色素材、图片、图标等资源需要单独确认授权。当前 `shiroko` 素材用于桌宠加载器、动画和状态切换测试；在公开发布或正式分发前，需要确认素材的版权、再分发权限和适用范围。
+
+用户导入或替换的素材，其版权责任由用户自行承担。
+
+## 许可证
+
+项目源码使用 MIT License，见 [LICENSE](LICENSE)。