Finalize desktop pet feature set and GitHub export

docs/QtDesktopPet_测试清单与验收标准.md

@@ -0,0 +1,198 @@
+# QtDesktopPet 测试清单与验收标准
+
+本文档用于全功能统一手测验收。Codex 不调用 CMake 或构建命令；需要编译验证时由用户手动构建并反馈结果。
+
+## 验收记录格式
+
+每个用例建议记录：
+
+```text
+测试日期：
+Git commit：
+构建类型：Debug / Release
+操作系统：
+Qt 版本：
+测试人：
+结论：通过 / 不通过 / 阻塞
+实际结果：
+备注：
+```
+
+## 总体验收标准
+
+- 程序不崩溃、不卡死，UI 主线程不被网络、文件或 AI 请求阻塞。
+- 日志不包含完整 API Key、Authorization、完整用户消息正文、完整错误响应正文或完整搜索词。
+- 设置页保存后立即生效，重启后配置仍能读取。
+- 所有损坏 JSON 配置都应备份为 `.broken.yyyyMMdd-HHmmss.json` 后回退默认或忽略损坏数据。
+- 所有涉及本地文件写入的操作必须由用户选择路径，并在执行前显示计划和二次确认。
+- 不运行 CMake 的自动验证；构建和运行由用户手动完成。
+
+## 基础窗口与托盘
+
+| 用例 | 步骤 | 预期结果 | 结论 |
+| --- | --- | --- | --- |
+| 启动 | 启动 `QtDesktopPet.exe` | 桌宠显示，透明无边框，无控制台窗口，日志创建成功 | TODO |
+| 拖动 | 按住桌宠拖动后松开 | 拖动时进入 `drag`，松开后恢复合理状态 | TODO |
+| 置顶 | 右键切换置顶 | 置顶状态立即变化，重启后保持 | TODO |
+| 隐藏托盘 | 托盘菜单隐藏/显示 | 隐藏后动画暂停，显示后恢复 | TODO |
+| 单实例 | 已运行时再次启动 exe | 只有一个进程，已有实例被唤醒 | TODO |
+| 设置页居中 | 多屏或重复打开设置页 | 设置页出现在当前屏幕可用区域内并置前 | TODO |
+
+## 角色管理
+
+| 用例 | 步骤 | 预期结果 | 结论 |
+| --- | --- | --- | --- |
+| 切换角色 | 设置页选择角色并保存 | 桌宠立即切换，不依赖重启 | TODO |
+| 导入合法角色 | 导入有效角色文件夹 | 验证通过后复制到用户数据目录，可选择使用 | TODO |
+| 导入非法角色 | 导入缺少 `character.json` 或无 idle 的角色 | 弹出错误，不复制、不覆盖 | TODO |
+| 覆盖用户角色 | 导入同 id 用户角色 | 弹出覆盖确认，取消则不操作 | TODO |
+| 内置角色保护 | 尝试删除内置角色 | 提示不能删除，不做文件操作 | TODO |
+| 删除用户角色 | 删除用户导入角色 | 二次确认后删除用户角色目录；当前角色被删时回退默认 | TODO |
+| 导出角色 | 选择任意角色并导出到目录 | 目标生成 `<characterId>/` 副本；目标存在时必须确认 | TODO |
+| 打开目录 | 点击打开用户角色目录 | 系统文件管理器打开用户角色目录 | TODO |
+
+## AI 与聊天历史
+
+| 用例 | 步骤 | 预期结果 | 结论 |
+| --- | --- | --- | --- |
+| AI 配置保存 | 设置 Provider/Base URL/API Key/Model 并保存 | 配置保存，API Key 按平台策略加密或确认明文 | TODO |
+| 连接测试 | 点击测试连接 | 成功显示成功；错误配置显示明确错误 | TODO |
+| 普通聊天 | 发送短消息 | `think` 后进入 `talk`，气泡显示回复 | TODO |
+| 流式回复 | 启用流式并发送消息 | 首段前保持 `think`，输出中保持 `talk` | TODO |
+| AI 忙 | 回复中再次发送聊天/天气/搜索 | 不启动第二个请求，显示忙提示 | TODO |
+| 取消 AI | 右键取消 AI 请求 | 请求取消，状态恢复，气泡提示取消 | TODO |
+| 历史保存 | 开启本地保存后聊天 | 重启后历史可读取 | TODO |
+| 历史搜索 | 在设置页按关键词搜索 | 只显示匹配记录 | TODO |
+| 历史筛选 | 按 Provider/模型筛选 | 只显示对应元数据记录；旧记录按未知处理 | TODO |
+| 导出 Markdown | 导出筛选结果为 `.md` | 文件包含角色、时间、Provider/模型和正文，不含 API Key | TODO |
+| 导出 JSON | 导出筛选结果为 `.json` | JSON 可解析，包含 messages 数组，不含 API Key | TODO |
+| 清空历史 | 点击清空聊天记录并确认 | 内存和本地历史清空，面板刷新 | TODO |
+
+## 定时提醒
+
+| 用例 | 步骤 | 预期结果 | 结论 |
+| --- | --- | --- | --- |
+| 一次性提醒 | `10分钟后提醒我喝水` | 创建 pending 提醒，显示标题和时间 | TODO |
+| 中文相对时间 | `半小时后提醒我休息`、`一个半小时后提醒我喝水` | 时间解析正确 | TODO |
+| 绝对日期 | `明天9点提醒我开会`、`6月3日9点提醒我提交` | 未明确日期且当天已过时顺延 | TODO |
+| 重复提醒 | `每天9点提醒我打卡`、`每周一上午10点提醒我周会`、`每月3号9点提醒我交报告` | 创建 daily/weekly/monthly | TODO |
+| 不支持规则 | `工作日9点提醒我打卡`、`农历初一提醒我` | 明确提示暂不支持，不创建一次性误提醒 | TODO |
+| 提醒列表 | `提醒列表` | 只列出 pending 提醒 | TODO |
+| 聊天取消 | `取消喝水提醒` | 唯一匹配时标记 canceled；多匹配提示去设置页处理 | TODO |
+| 设置页编辑 | 编辑 pending 标题/时间/重复规则 | 保存后列表和下一次触发时间更新 | TODO |
+| 触发可见 | 到点时桌宠可见且 AI 不忙 | 播放当前音效，显示气泡和操作区，不发系统通知 | TODO |
+| 触发隐藏 | 桌宠隐藏时到点 | 播放当前音效，只发 Windows 托盘通知，不补气泡 | TODO |
+| AI 忙触发 | AI 请求或流式回复中到点 | 播放当前音效，发系统通知，不显示提醒气泡 | TODO |
+| 拖动触发 | 拖动中到点 | 不打断 `drag`，松开后按队列显示气泡 | TODO |
+| 多提醒同时触发 | 两条同时间提醒 | 可见时逐条队列展示，后一条不覆盖前一条 | TODO |
+| 知道了 | 点击 `知道了` | 关闭当前提醒展示，队列进入下一条 | TODO |
+| 5分钟后再提醒 | 点击 `5分钟后再提醒` | 创建当前时间 + 5 分钟的一次性 pending，不影响原重复规则 | TODO |
+| 历史清理 | 构造 21 天前 triggered/canceled 后清理 | 删除 20 天前历史，保留最近 20 天和 pending | TODO |
+| 音效导入 | 导入合法 PCM wav | 可选择、试听、删除 | TODO |
+| 内置音效保护 | 选择内置音效点击删除 | 删除按钮禁用或提示不可删除 | TODO |
+
+## 天气查询
+
+| 用例 | 步骤 | 预期结果 | 结论 |
+| --- | --- | --- | --- |
+| 明确城市 | `西安天气怎么样` | 返回 Open-Meteo 模板结果 | TODO |
+| 明天 | `明天西安天气怎么样` | 返回明天预报 | TODO |
+| 后天 | `后天纽约天气` | 返回后天预报 | TODO |
+| 未来三天 | `未来三天北京天气` | 返回 1-3 天摘要 | TODO |
+| 默认城市 | 设置默认城市后输入 `今天天气怎么样` | 使用默认城市并说明来源 | TODO |
+| IP fallback | 清空默认城市并启用 IP 定位 | 使用公网 IP 城市并说明来源 | TODO |
+| 禁用 IP fallback | 清空默认城市并关闭 IP 定位 | 提示配置默认城市或在问题中带城市 | TODO |
+| 多候选 | 查询同名城市 | 使用首项并提示其他候选 | TODO |
+| 默认城市测试 | 设置页点击测试默认城市 | 显示匹配城市/行政区/国家，不自动保存 | TODO |
+| 未知城市 | 输入无法解析城市 | 明确错误，不崩溃 | TODO |
+| 不支持项 | 查询空气质量/预警/穿衣指数 | 明确提示 v1 暂不支持 | TODO |
+
+## 本地文件操作
+
+| 用例 | 步骤 | 预期结果 | 结论 |
+| --- | --- | --- | --- |
+| 读取文本 | 输入读取文本文件请求并选择 txt/md/log | 显示内容预览，最多读取前 64KB | TODO |
+| 非文本拒绝 | 选择 exe/png 等非文本 | 提示只允许常见文本文件 | TODO |
+| 列目录 | 输入列出文件夹请求并选择临时目录 | 显示前 200 项，区分目录/文件 | TODO |
+| 复制文件 | 选择源文件和目标目录 | 显示计划，确认后复制；目标存在则拒绝覆盖 | TODO |
+| 创建备份 | 选择文件备份 | 显示计划，确认后生成 `.backup.yyyyMMdd-HHmmss` 文件 | TODO |
+| 重命名 | 选择文件并输入新文件名 | 显示计划，确认后重命名；目标存在拒绝 | TODO |
+| 危险词拒绝 | 输入删除/覆盖/移动/执行脚本/运行命令 | 明确拒绝，不弹路径选择，不做文件操作 | TODO |
+| 系统目录拒绝 | 尝试选择 Windows/Program Files 下路径 | 提示不允许访问系统目录 | TODO |
+| 符号链接拒绝 | 选择符号链接或链接目录内路径 | 提示不允许操作符号链接路径 | TODO |
+| zip 延期 | 输入打包/压缩请求 | 提示 zip 打包暂不启用 | TODO |
+
+## 联网模式
+
+| 用例 | 步骤 | 预期结果 | 结论 |
+| --- | --- | --- | --- |
+| 开关关闭 | 输入框联网开关关闭，询问 `美国的首都在哪里` | 走普通 AI 对话，不调用 WebChatManager | TODO |
+| OpenAI 官方联网 | 使用 OpenAI 官方 Provider，打开联网开关，询问 `Qt 6 最新版本` | 进入联网模式，返回回答；有来源时展示来源 | TODO |
+| Gemini 官方联网 | 使用 Google Gemini Provider，打开联网开关，询问 `Qt 6 最新版本` | 进入 Gemini grounding，返回回答；有来源时展示来源 | TODO |
+| DeepSeek 不支持 | 使用 DeepSeek Provider，打开联网开关并发送问题 | 不发起伪联网请求，提示 DeepSeek 当前不支持原生联网 | TODO |
+| 第三方兼容不确认 | 使用 Custom 或第三方 Base URL，打开联网开关 | 提示当前 AI 配置无法确认联网能力 | TODO |
+| 模型未联网 | 支持联网 Provider 回答稳定常识但未返回来源 | 展示回答，并标注模型未使用联网来源 | TODO |
+| Web 忙冲突 | 联网请求中再次发送普通聊天或联网聊天 | 不启动第二个请求，提示稍后 | TODO |
+| AI 忙冲突 | 普通 AI 回复中打开联网再发送 | 不启动联网请求，提示 AI 回复正在进行 | TODO |
+| 设置页状态 | 切换 OpenAI/Gemini/DeepSeek/Custom | “联网模式”页即时显示可用/不可用/无法确认状态 | TODO |
+| 设置页测试 | 点击“测试联网模式” | 支持 Provider 发起测试，不支持 Provider 直接显示原因 | TODO |
+| 旧失败回归 | 打开联网后询问 `美国的首都在哪里` | 不再返回搜狗/360 帮助、登录、反馈页 | TODO |
+| 意图优先级 | `明天早上提醒我看天气` / `把天气截图保存到桌面` | 仍优先走提醒或文件操作，不受联网开关影响 | TODO |
+
+## 应用启动
+
+| 用例 | 步骤 | 预期结果 | 结论 |
+| --- | --- | --- | --- |
+| 设置页登记 | 添加一个 `.exe`，填写名称和别名后保存 | 重启后登记项仍存在 | TODO |
+| 已登记启动 | 输入 `打开 <别名>` | 弹出确认框，确认后启动对应 exe | TODO |
+| 未知应用手选 | 输入 `打开酷狗音乐` 且未登记 | 弹出 exe 选择器，选择 `.exe` 后弹确认框 | TODO |
+| 记住手选应用 | 手选 exe 时勾选记住 | 后续同名请求直接命中登记应用并仍需确认 | TODO |
+| 用户取消选择 | 未知应用弹出选择器后取消 | 不启动任何程序，无配置写入 | TODO |
+| 用户取消确认 | 选择或命中应用后取消确认 | 不启动任何程序 | TODO |
+| 拒绝脚本 | 尝试选择 `.bat/.cmd/.ps1/.vbs/.js/.msi` | 被拒绝，不启动 | TODO |
+| 不执行命令 | 输入“运行 powershell 命令” | 不执行聊天文本命令；按安全规则拒绝或走普通聊天 | TODO |
+| 文件操作优先 | 输入 `打开文件夹` | 走文件操作或文件操作拒绝路径，不走应用启动 | TODO |
+| 设置页测试启动 | 选中登记应用点测试启动 | 先二次确认，确认后启动 | TODO |
+| 设置页开机自启动 | 应用设置页勾选/取消“开机自启动”并保存 | 当前用户 Run 注册表项写入/移除，重开设置页状态与实际注册表一致 | TODO |
+
+## 发布与性能
+
+| 用例 | 步骤 | 预期结果 | 结论 |
+| --- | --- | --- | --- |
+| Release 构建 | 用户手动构建 Release | 构建成功，无新增编译错误 | TODO |
+| 打包 | 运行 `tools/package_release.ps1` | 包含 exe、Qt runtime、resources、README、LICENSE | TODO |
+| 安装器 | 生成并安装 Inno Setup 包 | 无 Qt 开发环境机器可运行 | TODO |
+| 安装器自启动选项 | 安装页面勾选/不勾选开机自启动分别安装 | 勾选时写入当前用户 Run 项；不勾选时不新增自启动项；选项默认不勾选 | TODO |
+| 卸载清理自启动 | 已启用开机自启动后卸载 | 当前用户 Run 项被清理，不残留开机启动入口 | TODO |
+| 卸载保留数据 | 卸载时选择不删除用户数据 | 配置、角色、历史、日志保留 | TODO |
+| 卸载删除数据 | 卸载时选择删除用户数据 | 当前用户 QtDesktopPet 数据目录被删除 | TODO |
+| 性能采样 | 按 `performance_stability_check.md` 执行 | CPU/内存无持续异常增长，摘要写入文档 | TODO |
+
+## 静态推演记录
+
+每个模块完成后记录：
+
+```text
+模块：
+入口：
+成功路径：
+失败路径：
+数据兼容：
+UI 状态：
+日志隐私：
+回归影响：
+结论：
+```
+
+本轮静态推演明细：
+
+| 模块 | 入口 | 成功路径 | 失败路径 / 兜底 | 风险点 | 结论 |
+| --- | --- | --- | --- | --- | --- |
+| 天气 | `CommandDispatcher -> PetWindow::handleWeatherChatMessage() -> WeatherManager` | 解析城市和日期，按显式城市 / 默认城市 / IP fallback 定位，请求 Open-Meteo，模板格式化后显示气泡 | AI 忙、天气忙提前拒绝；未知城市、IP 失败、超时、JSON 异常返回明确错误；默认城市测试超时会恢复测试按钮 | 网络不可用、Open-Meteo 多候选首项可能不符合预期 | v1/v1.2/v1.3 收口完成，区县精确定位和空气质量等保持延期 |
+| 提醒 | `CommandDispatcher -> ReminderCommandHandler -> ReminderManager` | 创建/查询/取消一次性和 daily/weekly/monthly；到点先保存 JSON，再播放音效和展示/通知 | 保存失败回滚内存，不播放、不通知、不气泡；隐藏和 AI 忙只发系统通知；拖动中进入可见队列；20 天前历史可清理 | 系统通知是否真正弹出受 Windows/托盘后端影响，Qt 只能确认发起状态 | v2 行为保持，复杂重复规则、跨平台通知、自定义稍后间隔延期 |
+| 角色 | 设置页角色页和 `CharacterPackageRepository` | 导入先验证再复制；切换保存后立即生效；用户角色可删除；任意角色可导出；可打开用户角色目录 | 内置角色不可删除/覆盖；导出目标存在需二次确认；损坏角色包不复制 | 目标目录权限失败、用户取消、角色包资源缺失 | 当前角色管理补全完成，角色市场/分享延期 |
+| 历史 | 设置页聊天页和 `ConversationManager/ConversationStore` | 新消息写入 `timestamp/provider/model`；旧 role/content 历史兼容读取；支持关键词、Provider、模型筛选；Markdown/JSON 导出 | 本地历史关闭时只显示内存记录；损坏历史备份后忽略；导出路径不可写时提示错误 | 超大历史由保存上限和筛选 UI 控制；导出文件由用户选择路径 | 历史管理补全完成，不导出 API Key，不记录完整聊天日志 |
+| 文件操作 | `CommandDispatcher -> PetWindow::handleFileOperationChatMessage() -> FileOperationManager` | 用户通过系统对话框选择路径；读取文本、列目录、复制、备份、重命名；写操作先展示计划并二次确认 | 删除/覆盖/移动/脚本/命令/截图保存/zip 直接拒绝；系统目录、符号链接、目标冲突、非法文件名均拒绝 | 文件选择对话框是安全边界；系统目录根据常见路径和环境变量识别 | v1 安全能力完成，zip 打包延期，不引入重依赖 |
+| 联网模式 | `ChatInputDialog -> PetWindow::submitWebChatMessage() -> WebChatManager` | 输入框联网开关开启后，支持 OpenAI 官方 Web Search 和 Gemini Google Search grounding；不支持 DeepSeek/Custom 伪联网 | AI 未配置、Provider 不支持、超时、网络失败、无来源均明确提示；Web 忙时不启动第二个请求 | 不再维护旧搜索源聚合或 SearXNG 旧配置 | 联网模式完成，结构化搜索 API/自建后端延期 |
+| 应用启动 | `CommandDispatcher -> PetWindow::handleLaunchAppChatMessage() -> AppLaunchManager` | 用户输入打开/启动应用后，按登记别名、开始菜单、App Paths、手选 exe 顺序解析，启动前二次确认 | 配置关闭、未找到应用、用户取消、非 exe/lnk、脚本/安装包、路径不存在均不启动；手选记住失败只提示，不影响已确认启动 | 启动成功由系统返回值判断，目标应用自身异常不由桌宠控制；开始菜单和注册表发现仅 Windows 优先 | v1 完成，不支持脚本、命令行参数、管理员权限、跨平台发现 |
+| 发布/性能 | `tools/package_release.ps1` 和 `docs/performance_stability_check.md` | 发布脚本复制 exe、Qt runtime、角色/图标/音效资源、README、LICENSE；性能文档覆盖静置、AI、提醒、天气、联网模式、文件操作 | `windeployqt`、Inno Setup、安装/卸载验证需用户手动执行并记录 | 未经手动构建和实机安装不能确认二进制运行 | 验收入口已补齐，本轮不运行 CMake 或构建命令 |