DesktopPet用户手册
DesktopPet 用户手册
适用版本：DesktopPet v1.0.0
平台：Windows
说明：本手册面向普通用户，介绍 DesktopPet 的安装、启动、桌宠操作、宠物管理、动作设置、AI 对话、联网搜索、对话日志、个性化、托盘菜单、图片处理工具、更新机制和数据目录。不同小版本界面文字可能略有差异，以实际程序为准。
1. 软件简介
DesktopPet 是一款桌面宠物应用。它可以在桌面上显示一个可拖动、可播放动作的宠物，并提供 AI 对话、联网搜索、动作配置、情绪动作、主题个性化、对话日志和更新检查等功能。
DesktopPet 不内置默认宠物资源。首次使用时，如果没有创建或导入宠物，桌面 player 会显示状态提示。用户需要在“宠物管理”页面中新建宠物、导入宠物，或手动恢复已有宠物资源。
DesktopPet 的核心使用流程通常是：
- 安装并启动 DesktopPet。
- 在“宠物管理”中新建或导入宠物。
- 在“动作设置”中创建、导入并配置动作。
- 在“LLM 设置”中配置 AI 模型。
- 根据需要开启“搜索设置”、查看“对话日志”、调整“个性化”。
2. 安装、启动与退出
2.1 安装
推荐使用发布页中的安装程序：
1 | DesktopPet_Setup_vX.X.X.exe |
运行安装程序后，按安装向导完成安装。安装程序只负责安装 DesktopPet 主程序、配套工具和必要依赖，不会内置默认宠物资源。
2.2 启动
启动 DesktopPet 后，通常会出现两个部分：
- 桌面 player：显示桌宠、播放动作，或在无宠物时显示状态提示。
- 设置窗口：用于管理宠物、动作、LLM、搜索、日志、个性化和关于信息。
是否启动时自动播放、是否启动时打开设置窗口，可以在“个性化”页面配置。
2.3 退出
退出方式包括：
- 右键桌宠 player，在菜单中选择“退出”。
- 右键系统托盘图标，选择“退出”。
- 关闭应用主进程。
退出程序不会删除宠物、动作、配置或对话日志。
3. 桌宠 player 基本操作
3.1 左键点击
左键单击桌宠 player，可以打开或关闭聊天面板。
如果聊天面板已经打开，再次左键单击桌宠会隐藏聊天面板。
3.2 左键拖动
按住鼠标左键并移动，可以拖动桌宠位置。DesktopPet 会尽量限制桌宠不完全移出当前屏幕可用区域。
如果动作开启了自动移动，用户拖动时会优先响应用户操作，避免拖动和自动移动冲突。
3.3 右键菜单
右键桌宠 player，会出现快捷菜单，常见选项包括：
- 开始：开始播放当前宠物动作。
- 暂停：暂停桌宠播放。
- 隐藏桌宠：隐藏桌宠 player。
- 打开设置：打开设置窗口。
- 退出：退出 DesktopPet。
3.4 状态提示
当没有宠物、宠物配置缺失、动作资源不可用或当前没有可播放动作时，player 会显示状态提示面板。例如：
- 尚未创建宠物
- 当前宠物配置缺失
- 暂无可用动作
- 宠物已暂停
状态提示只是当前状态说明，不会替代宠物资源。需要到“宠物管理”或“动作设置”中补齐配置。
4. 系统托盘菜单
DesktopPet 启动后会在 Windows 系统托盘区域显示图标。右键托盘图标可以打开托盘菜单。
托盘菜单包含：
- 显示桌宠：显示已隐藏的桌宠 player。
- 隐藏桌宠：隐藏桌宠 player。
- 开始：开始播放宠物动作。
- 暂停：暂停宠物动作。
- 打开设置：打开设置窗口。
- 退出：退出程序。
托盘菜单是正式控制入口。早期调试用的“测试情绪”菜单已经移除，情绪动作现在由 AI 回复中的 emotion 字段自动触发。
5. 设置窗口总览
设置窗口左侧为导航栏，主要页面包括：
- 宠物管理
- 动作设置
- LLM 设置
- 搜索设置
- 对话日志
- 个性化
- 关于
每个页面对应一个独立功能模块。通常建议先完成“宠物管理”和“动作设置”，再配置 AI 对话和搜索能力。
6. 宠物管理
“宠物管理”用于创建、导入、选择、启用、禁用和删除宠物。
6.1 当前宠物
页面顶部会显示当前宠物状态。如果尚未选择宠物，桌面 player 会显示无宠物提示。
6.2 宠物列表
宠物列表显示已加入宠物库的宠物。点击列表项可以查看该宠物的详细信息。
6.3 新建宠物
点击“新建”可以创建一个新的宠物配置。创建时通常需要填写：
- 宠物 ID：用于目录名，建议只使用字母、数字、下划线或短横线。
- 宠物名称：用于界面显示，可以使用中文。
- 画布尺寸：动作图片的基础画布大小。
- 显示尺寸：桌面上显示的宠物窗口大小。
创建宠物只会生成配置，不会自动生成默认动作资源。后续需要在“动作设置”中创建或导入动作。
6.4 导入宠物
点击“导入”可以选择已有宠物目录。有效宠物目录应包含：
1 | pet.json |
宠物目录规则：
1 | pets/<petId>/ |
petId 必须与 pet.json 中的 id 一致。如果目录名和 pet.json 中的 id 不一致，DesktopPet 可能会跳过该宠物，或显示配置缺失。
6.5 重新加载
“重新加载”用于重新扫描和恢复宠物库索引。当用户手动复制宠物资源到程序数据目录后，可以点击此按钮恢复 petlibrary.json。
恢复规则较保守：只有目录存在、包含 pet.json 和 playlist.json、配置可读取、且目录名与宠物 ID 一致的宠物才会被恢复。
6.6 开始与暂停
- 开始：让当前宠物开始播放动作。
- 暂停：停止当前播放状态，player 显示暂停状态或保持当前画面。
6.7 右键宠物列表
在宠物列表上右键，可以执行宠物相关操作，具体以当前版本菜单为准。常见操作包括：
- 启用或禁用宠物
- 删除宠物
- 设置或切换当前宠物
禁用宠物不会删除资源；删除宠物可能删除或移除相关配置，操作前应确认。
7. 动作设置
“动作设置”用于管理全局动作库，以及把动作配置到当前宠物的播放列表中。
页面主要由三部分组成：
- 动作库
- 动作分类配置
- 当前动作配置
7.1 动作库
动作库列出已经导入或创建的动作。动作通常对应一个 GIF 或一组图片帧。
操作包括：
- 新建动作
- 导入动作
- 右键动作添加到当前分类
- 拖拽动作到右侧分类
- 重命名动作 ID
- 移除动作
- 删除动作
“移除动作”通常表示从动作库索引中移除，但资源文件可能仍然保留。
“删除动作”通常会删除动作资源并从播放列表中清理引用，属于危险操作。
7.2 新建动作
点击“新建动作”可从 GIF 文件创建动作。通常需要配置：
- GIF 文件
- 动作 ID
- FPS
- 添加到分类
- 定时触发方式
- 情绪类型
创建后，DesktopPet 会提取 GIF 帧并生成动作资源。
7.3 导入动作
点击“导入动作”可以导入已有动作目录或动作库。导入时可选择动作文件夹，并根据检测结果导入单个动作或批量动作。
7.4 动作分类
当前宠物的播放列表分为四类：
- 日常动作
- 随机动作
- 定时动作
- 情绪动作
日常动作
日常动作是基础播放序列。宠物空闲时会按播放列表播放日常动作。
随机动作
随机动作会在运行过程中随机触发，用于增加桌宠表现的变化。
定时动作
定时动作支持两种触发方式：
- 每隔一段时间触发
- 指定时间触发
可以用来配置定期发生的动作，例如每隔若干秒播放一次，或每天某个时间播放。
情绪动作
情绪动作由 AI 回复中的 emotion 字段触发。支持的 emotion 包括：
1 | happy |
neutral 表示不播放情绪动作，不作为可配置动作类型。
情绪动作列表会显示所有情绪动作，并按固定顺序分组：
1 | happy -> sad -> angry -> surprised -> fear -> confused |
同一情绪下可以配置多个动作。触发某个 emotion 时，DesktopPet 会从该 emotion 的候选动作中随机选择一个加入播放队列。如果候选动作多于一个，会尽量避免连续重复播放同一个动作。
7.5 把动作加入分类
可以通过以下方式把动作加入右侧分类：
- 右键动作库中的动作，选择添加到当前分类。
- 从动作库拖拽动作到右侧分类列表。
情绪动作列表允许从动作库拖入动作，但不允许通过拖拽在情绪列表内部跨情绪乱序。情绪动作的排序以 emotion 分组为主，同一 emotion 内可通过“上移”“下移”调整。
7.6 当前动作配置
选中右侧分类中的动作后，可以在“当前动作配置”中调整：
- 循环：是否循环播放。
- 次数：播放次数，0 通常表示无限循环。
- 倍速：是否启用动画播放倍速。
- 速度：动作播放速度。
- 移动：播放该动作时是否移动桌宠。
- 移动速度：移动速度倍率。
- 方向：随机、水平、竖直。
- 对应情绪：仅情绪动作显示，用于设置该动作属于哪个 emotion。
- 定时触发方式：仅定时动作显示。
- 间隔：定时动作按间隔触发时使用。
- 时间：定时动作按指定时间触发时使用。
7.7 保存配置与保存并应用
- 保存配置：把当前动作配置保存到配置文件。
- 保存并应用：保存配置，并让当前运行中的宠物立即重新加载配置。
8. 配套工具：DesktopPet-resize 图片处理工具
DesktopPet 安装包会附带一个配套工具：DesktopPet-resize.exe。它用于批量处理宠物动作图片资源，适合在导入动作前整理素材。
DesktopPet-resize 只负责处理图片，不会自动创建宠物，也不会自动导入动作。处理完成后，仍需要回到 DesktopPet 主程序，在“动作设置”中导入或配置动作。
8.1 什么时候需要使用
在以下场景中可以使用 DesktopPet-resize：
- 动作图片尺寸不统一。
- 动作帧比当前宠物显示尺寸大或小很多。
- 图片边缘空白过多，需要统一画布效果。
- 动作资源体积较大，希望处理后再导入。
- 从外部素材包整理动作图片时，需要先规范尺寸。
8.2 打开方式
可以通过以下方式打开：
- 开始菜单中的 DesktopPet 图片处理工具。
- 安装目录中的
DesktopPet-resize.exe。 - release 包中的
DesktopPet-resize.exe。
8.3 界面项目
DesktopPet-resize 主要包含这些区域：
pet.json：选择当前宠物的pet.json，工具会尝试读取显示尺寸。- 动作目录：选择要处理的动作图片目录。
- 目标尺寸：设置输出图片的宽度和高度。
- 备份：处理前复制原动作目录，降低误操作风险。
- 缩放方式：选择“保持比例 + 居中填充”或“直接拉伸到目标尺寸”。
- 日志：显示处理过程、成功数量、跳过数量和失败数量。
8.4 基本使用流程
推荐流程如下：
- 准备好动作图片目录。
- 打开
DesktopPet-resize.exe。 - 选择对应宠物的
pet.json。 - 选择动作目录。
- 检查或手动设置目标宽度和高度。
- 保持“启用备份”处于开启状态。
- 选择缩放方式。
- 点击“开始处理”。
- 检查日志和输出图片。
- 回到 DesktopPet 主程序，在“动作设置”中导入或配置动作。
8.5 缩放方式说明
- 保持比例 + 居中填充：尽量保持原图比例，将图像缩放后居中放入目标画布。适合大多数宠物动作素材。
- 直接拉伸到目标尺寸：强制拉伸到目标宽高。可能导致图像变形，只有在确认素材比例匹配时再使用。
8.6 备份建议
建议先输出或备份到新目录，不要直接覆盖原始素材。
工具默认会在处理前复制原目录，避免图片处理结果不符合预期时无法恢复。关闭备份时，工具会提示确认，因为处理会直接覆盖原图片。
8.7 注意事项
- GIF 文件会被跳过，主要处理 PNG、JPG、JPEG、WEBP、BMP 等图片文件。
- 如果 Qt 环境不支持写入某些格式，例如 WEBP，日志中会提示保存失败。
- 如果图片已经是目标尺寸，工具会跳过该文件。
- 处理完成后仍需在主程序中导入或配置动作。
9. LLM 设置
“LLM 设置”用于配置 AI 对话模型和角色设定。
9.1 当前 API 配置
页面顶部显示当前选中的 API Profile。可以测试连接，也可以重新加载磁盘上的 API 配置。
9.2 配置库
配置库中保存多个 API Profile。每个配置通常包含：
- 供应商
- API Key
- Base URL
- 模型名
- Max Tokens
- Temperature
- API 格式
当前仅支持 OpenAI-compatible API。Claude / Anthropic 原生接口暂未开放。
“自定义”供应商仍按 OpenAI 兼容接口调用，模板中会说明仅支持 OpenAI 兼容格式。
9.3 新增、编辑、删除配置
- 新增配置：创建新的 API Profile。
- 编辑配置：修改当前配置内容。
- 删除配置：删除配置库中的配置。
API Key 保存在本地配置文件中，请勿在公共电脑保存。当前版本的 API Key 保存在本地 config/api_profiles.json，请妥善保管设备和配置文件。
9.4 测试连接
点击“测试连接”会使用当前 API 配置发起一个轻量请求，用于验证：
- API Key 是否可用
- Base URL 是否正确
- 模型名是否可用
测试结果会通过提示显示，不会写入聊天记录。
9.5 对话设置
“对话设置”是角色设定文本。它用于控制桌宠回复风格，例如：
- 说话语气
- 是否使用中文
- 是否扮演某个角色
- 回复是否简短
- 是否带宠物感
保存后，之后的聊天会使用新的设定。
10. 聊天面板
10.1 打开与关闭
左键单击桌宠 player 可打开或关闭聊天面板。
10.2 发送消息
输入框支持：
- Enter：发送消息
- Shift + Enter：换行
聊天面板中消息显示为：
1 | 我： 用户消息 |
10.3 上下文
DesktopPet 会保留近期对话作为短期上下文，但不会无限保留所有对话。程序退出后，聊天窗口内容不会自动恢复。
10.4 当前时间上下文
每次请求都会临时注入当前本地时间、日期、星期和时区，用于回答“现在几点”“今天星期几”等问题。
这条时间上下文不会显示在聊天窗口，不会写入聊天日志，也不会保存到对话历史。
10.5 结构化回复与情绪动作
DesktopPet 会要求模型返回结构化 JSON：
1 | { |
聊天窗口只显示 reply。emotion 用于触发情绪动作。
支持的 emotion：
1 | neutral |
其中 neutral 表示不播放动作。其他 emotion 如果在当前宠物的 playlist.json 中配置了对应情绪动作，就会自动播放；未配置时会静默跳过，不影响聊天。
11. 搜索设置与联网搜索
“搜索设置”用于配置联网搜索增强能力。
11.1 启用联网搜索
勾选“启用联网搜索”后，DesktopPet 可在需要外部实时信息时调用搜索服务。
支持的搜索服务包括：
- Tavily
- Brave Search
- Exa
需要填写对应服务的 API Key。
11.2 搜索参数
搜索设置包括：
- 搜索服务
- API Key
- 结果数量
- 搜索深度
- 超时时间
配置完成后可以保存设置，也可以测试搜索。
11.3 重新加载
“重新加载”会重新读取 config/websearch_settings.json 中的搜索配置，适合手动修改或恢复配置文件后使用。
11.4 自动触发搜索
当用户消息涉及外部实时信息时，DesktopPet 会触发搜索。例如：
- 今天有什么新闻
- 最近有什么新闻
- 最新版本
- 天气
- 股价
- 汇率
- 价格
- 发布信息
普通闲聊不会触发搜索。例如：
- 最近怎么样
- 现在几点
- 今天几号
时间类问题由本地时间上下文回答，不使用联网搜索。
11.5 手动强制搜索
/search 和 #search 可强制联网搜索。也可以使用中文指令“搜一下”“查一下”。
1 | /search |
指令可以放在开头，也可以放在消息中间。命令后的文本会作为搜索 query。
例如：
1 | /search Qt 6.11 发布信息 |
1 | 宝宝我来啦 /search 水豚喜欢吃什么零食 |
11.6 首次对话时搜索角色设定中的实时内容
搜索设置中可以启用“首次对话时搜索角色设定中的实时内容”。启用后，应用启动后的第一次聊天中，如果角色设定包含“最近、最新、当前、很火、流行”等实时内容，DesktopPet 会额外搜索一次作为背景。
该搜索只在首次对话触发一次，不会每轮都搜索。
12. 对话日志
“对话日志”用于查看已保存的聊天记录。
12.1 日志写入
DesktopPet 会把聊天窗口中可见的消息写入本地 JSONL 日志，包括：
- 用户消息
- 宠物回复
- 可见系统提示
不会写入：
- API Key
- 临时 system prompt
- 当前时间 system message
- 联网搜索上下文原文
- 模型返回 JSON 的隐藏 emotion 字段
12.2 日志路径
日志路径：
1 | logs/chat/<petId>/<yyyyMMdd>.jsonl |
如果没有当前宠物，则使用：
1 | logs/chat/_no_pet/<yyyyMMdd>.jsonl |
12.3 加载日志
在“对话日志”页面点击“加载日志”，选择 .jsonl 文件即可查看。
页面支持搜索日志内容，可以按对话内容、宠物、API 配置等关键词过滤显示。
12.4 日志与记忆的区别
对话日志不会自动作为长期记忆注入。日志只是本地查看和检索用途。当前版本不会自动把日志恢复到聊天窗口，也不会把日志作为长期记忆重新注入给模型。
13. 个性化
“个性化”用于调整外观、显示和启动行为。
13.1 外观主题
可以选择浅色主题和深色主题。主题会影响：
- 设置窗口背景
- 卡片颜色
- 按钮颜色
- 列表颜色
- 输入框颜色
- 菜单样式
13.2 桌宠显示
可调整：
- 桌宠不透明度：控制 player 的整体透明程度。
- 卡片渐变强度：控制设置界面卡片渐变效果。
- 随机渐变：启用后卡片可以使用随机渐变风格。
- 基础移动速度：控制动作移动播放时的基础移动速度。
13.3 启动行为
可配置：
- 开机自启动：Windows 登录后自动启动 DesktopPet。
- 启动后自动开始播放：程序启动后自动播放宠物动作。
- 启动时打开设置窗口：程序启动时自动显示设置窗口。
13.4 清空注册表修改
“清空注册表修改”用于清理 DesktopPet 写入的本机设置，例如启动相关设置。它不会删除宠物资源、动作资源、配置文件、日志文件。
该操作主要用于恢复本机设置状态，或排查启动项、主题、窗口设置等本机设置异常。
14. 关于、用户手册与更新
“关于”页面包含项目说明、用户手册入口、当前版本和更新检查入口。
14.1 项目信息
显示 DesktopPet 图标、名称和简要介绍。
14.2 用户手册
关于页可以提供“打开用户手册”按钮。点击后会使用默认浏览器打开用户手册页面，例如博客页面。
14.3 版本信息
显示当前版本，例如：
1 | v1.0.0 |
14.4 检查更新
点击“检查更新”会请求 GitHub Releases 最新正式版本。
如果当前已是最新版本，会显示“当前已是最新版本”。
如果发现新版本，会显示：
- 最新版本号
- 更新说明
- 下载并安装按钮
- 打开发布页按钮
14.5 下载并安装
点击“下载并安装”后，DesktopPet 会下载发布页中的安装程序：
1 | DesktopPet_Setup*.exe |
下载位置为系统临时目录。下载完成后会启动安装向导，并退出当前 DesktopPet。
更新程序只下载安装包，不会直接覆盖正在运行的 exe。文件替换由 Inno Setup 安装程序处理。
config / pets / logs 不会被主动删除。更新不会主动删除：
1 | config/ |
15. 数据目录与配置文件
DesktopPet 的运行数据主要位于程序运行目录下。
15.1 配置目录
1 | config/ |
说明：
api_profiles.json：API 配置档案，currentProfile字段保存当前选中配置。chat_settings.json：对话设置。websearch_settings.json：搜索设置。
15.2 宠物与动作目录
1 | petlibrary.json |
petId 必须与 pet.json 中的 id 一致。
15.3 日志目录
1 | logs/chat/<petId>/<yyyyMMdd>.jsonl |
15.4 不内置默认资源
DesktopPet 不内置默认宠物资源。安装包和 release 包不会打包默认 pets 资源。用户需要自行创建、导入或恢复宠物。
16. 常见问题
16.1 为什么首次打开没有宠物？
因为 DesktopPet 不内置默认宠物资源。请到“宠物管理”中新建或导入宠物。
16.2 为什么宠物不播放？
可能原因：
- 当前没有启用宠物。
- 当前宠物没有动作资源。
- 动作未加入播放列表。
- 程序处于暂停状态。
- 动作资源路径缺失。
可依次检查“宠物管理”和“动作设置”。
16.3 为什么情绪动作没有触发？
可能原因：
- 模型返回的是
neutral。 - 当前宠物没有配置对应 emotion 的动作。
- 动作资源缺失。
- 当前动作还在播放，情绪动作已入队但尚未轮到播放。
16.4 为什么 /search 没有触发？
请确认：
- 搜索设置中已启用联网搜索。
- 已配置搜索 API Key。
- 使用了
/search、#search、搜一下或查一下。 - 命令后有可搜索内容。
16.5 为什么“现在几点”没有联网搜索？
这是正常行为。时间问题使用本地系统时间上下文，不调用联网搜索。
16.6 为什么更新检查失败？
可能原因：
- 网络不可用。
- GitHub 无法访问。
- 仓库没有发布正式 release。
- release 是 draft 或 prerelease。
- release 中没有符合名称规则的安装包 asset。
16.7 更新会删除宠物和配置吗？
不会。更新程序只下载安装包并启动安装向导，不会主动删除 config、pets、logs。
16.8 DesktopPet-resize 会自动导入动作吗？
不会。DesktopPet-resize 不会自动导入资源。它只处理图片。处理完成后，需要回到 DesktopPet 主程序，在“动作设置”中导入或配置动作。
17. 使用建议
- 先创建或导入宠物，再配置动作。
- 至少配置一个日常动作，否则宠物可能没有可播放内容。
- 情绪动作建议每个 emotion 配置 1 到 3 个动作，以增加表现变化。
- API Key 请只保存在可信设备上。
- 更新前可备份
config、pets、actions和logs。 - 如果手动复制资源，使用“重新加载”恢复索引。
- 使用 DesktopPet-resize 处理图片前，建议保留备份。
18. 后续计划
后续版本可能继续补充：
- 更完善的长期记忆与摘要记忆
- 流式输出
- Tool Calling / Function Calling
- 更完整的资源编辑器
- 更完善的自动更新策略
- 更多平台适配