237 lines
7.2 KiB
Markdown
237 lines
7.2 KiB
Markdown
# QtDesktopPet
|
||
|
||
一个基于 **Qt 6 Widgets / C++17** 的 Windows 桌面宠物项目。它提供透明桌宠窗口、PNG 序列帧动画、多状态切换、托盘控制、AI 对话、本地提醒、天气查询、简单文件操作和本地应用启动等能力。
|
||
|
||
> 当前仓库仍处于活跃开发阶段。角色素材、图标和音效的再分发权限需要在正式公开发布前单独确认。
|
||
|
||
|
||
|
||
## 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
|
||
- 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
|
||
```
|
||
|
||
## Build
|
||
|
||
Recommended environment:
|
||
|
||
- Qt 6.5+
|
||
- CMake 3.20+
|
||
- Ninja
|
||
- MinGW 11.2.0 or a configured Qt MSVC Kit
|
||
|
||
Example with MinGW:
|
||
|
||
```powershell
|
||
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-release
|
||
```
|
||
|
||
Qt Creator users can open `CMakeLists.txt` directly and build with a matching Qt Kit.
|
||
|
||
## Package
|
||
|
||
After building a Release executable, package it with:
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File tools/package_release.ps1 `
|
||
-ExePath build/release/QtDesktopPet.exe
|
||
```
|
||
|
||
To generate the Inno Setup installer:
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File tools/package_release.ps1 `
|
||
-ExePath build/release/QtDesktopPet.exe `
|
||
-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
|
||
QStandardPaths::AppConfigLocation/logs/QtDesktopPet.log
|
||
```
|
||
|
||
## 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/prepare_github_export.ps1 `
|
||
-OutputDir D:\DesktopPet-github-export
|
||
```
|
||
|
||
The export excludes internal docs, reports, build outputs, release packages, local config, logs and Git metadata.
|
||
|
||
## License
|
||
|
||
Source code is released under the MIT License. See [LICENSE](LICENSE).
|
||
|
||
Character art, icons, sounds and other media assets may have separate copyright requirements. Confirm asset licensing before public redistribution.
|