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

QtDesktopPet 测试清单与验收标准

本文档用于全功能统一手测验收。Codex 不调用 CMake 或构建命令；需要编译验证时由用户手动构建并反馈结果。

每次实际执行结果保存到 docs/test-records/，不得直接用某次结果覆盖本验收标准。内部自动化入口见 internal/qa/README.md。

验收记录格式

每个用例建议记录：

测试日期：
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
开机自启动	在应用页依次开启、重启检查、再关闭	开启时写入当前用户 Run 项且路径正确；关闭时移除；默认关闭	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
关闭历史保存	关闭本地保存后聊天并重启	本轮消息只在内存存在，重启后不写入本地历史	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
睡眠与时间变化	睡眠跨过提醒时间；再分别模拟系统时间向前和向后变化	唤醒或向前跳变后补扫一次；向后跳变不提前触发	TODO
提醒保存失败	在隔离测试数据上模拟提醒文件不可写并等待到期	保持 pending，不播放、不通知、不显示气泡，后续仍可重试	TODO

天气查询

用例	步骤	预期结果	结论
明确城市	西安天气怎么样	返回 Open-Meteo 模板结果	TODO
明天	明天西安天气怎么样	返回明天预报	TODO
后天	后天纽约天气	返回后天预报	TODO
未来三天	未来三天北京天气	返回 1-3 天摘要	TODO
默认城市	设置默认城市后输入 今天天气怎么样	使用默认城市并说明来源	TODO
IP fallback	清空默认城市并启用 IP 定位	使用公网 IP 城市并说明来源	TODO
禁用 IP fallback	清空默认城市并关闭 IP 定位	提示配置默认城市或在问题中带城市	TODO
多候选	查询同名城市	使用首项并提示其他候选	TODO
默认城市测试	设置页点击测试默认城市	显示匹配城市/行政区/国家，不自动保存	TODO
未知城市	输入无法解析城市	明确错误，不崩溃	TODO
不支持项	查询空气质量/预警/穿衣指数	明确提示 v1 暂不支持	TODO
天气网络失败	断网或阻断天气请求后查询	明确提示网络/超时错误，UI 不阻塞，恢复网络后可再次查询	TODO

已移除本地能力回归

用例	步骤	预期结果	结论
文件操作已移除	输入 读取文件、创建 test.txt、复制文件	不弹文件选择框，不读取或修改本地文件；按普通 AI 对话处理	TODO
应用启动已移除	输入 打开 Codex、启动酷狗音乐	不弹 exe 选择框或确认框，不启动任何程序；按普通 AI 对话处理	TODO
工作区 Agent 已移除	输入 打开工作区、分析这个项目、含 class 的文件	不扫描目录、不弹 Agent 窗口、不访问本地项目；按普通 AI 对话处理	TODO
菜单入口清理	检查桌宠右键菜单和托盘菜单	不再出现 Agent 工作区 入口	TODO
设置页清理	打开设置页	不再出现 应用启动 和 Agent 页面；应用页仍有 开机自启动	TODO
快捷键清理	按 Alt+A	不再呼出 Agent 窗口，不影响其他快捷键或输入	TODO
旧配置兼容	用户目录保留旧 launcher_config.json，app_config.json 保留 agent 对象后启动	程序不崩溃，不读取旧能力配置；保存应用配置后不再写入 agent	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
联网开关双向记忆	启用记忆后分别执行关到开、开到关，不发送消息直接关闭并重开输入框	两个方向都保存最后状态；关闭记忆后使用默认开关值	TODO
联网网络失败	支持 Provider 下模拟断网、超时或服务端错误	明确提示失败，状态恢复，可重新发起请求，不泄露完整错误正文	TODO

配置兼容与隐私

所有损坏测试都必须先备份用户数据，优先使用隔离测试账户或临时配置副本。

用例	步骤	预期结果	结论
App 配置损坏	写入非法 app_config.json 后启动	原文件备份为带时间戳的 broken 文件，程序使用默认配置启动	TODO
AI 配置损坏	写入非法 ai_config.json 后启动	备份损坏文件，AI 回退未配置状态，不泄露旧 Key	TODO
天气配置损坏	写入非法 weather_config.json 后启动	备份损坏文件，天气使用默认配置	TODO
联网配置损坏	写入非法 web_config.json 后启动	备份损坏文件，联网开关使用默认配置	TODO
提醒数据损坏	写入非法 reminders.json 后启动	备份损坏文件，不崩溃、不触发错误数据	TODO
历史数据损坏	写入非法 conversation_history.json 后打开历史	备份损坏文件并忽略，历史面板可继续使用	TODO
日志隐私	覆盖正常请求、错误 Key、错误 Base URL、天气和联网失败	日志不含 API Key、Authorization、完整消息或完整错误响应	TODO

自动化验证

内部 QA 与发布构建隔离。用户配置好 Qt 测试构建后执行核心逻辑测试；不需要编译的静态检查可直接执行：

powershell -NoProfile -ExecutionPolicy Bypass -File internal/qa/scripts/Invoke-StaticChecks.ps1

当前自动化覆盖意图分发、提醒解析和类型、天气解析和模板、联网能力检测、聊天历史兼容，以及源码登记、废弃模块残留、默认资源和 GitHub 导出隔离。真实窗口、托盘通知、音效、网络 Provider、安装卸载仍按手测执行。

发布与性能

用例	步骤	预期结果	结论
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

静态推演记录

每个模块完成后记录：

模块：
入口：
成功路径：
失败路径：
数据兼容：
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 -> Reminder / Weather / Chat	本地文件、应用启动和工作区 Agent 文本不再进入系统工具链，且旧配置只被忽略	AI 仍可能解释如何手动操作，但不得声称已访问文件、启动程序或执行命令	重点防止残留入口、旧配置读取和意图枚举引用	三个本地高权限模块已从当前产品中移除
联网模式	ChatInputDialog -> PetWindow::submitWebChatMessage() -> WebChatManager	输入框联网开关开启后，支持 OpenAI 官方 Web Search 和 Gemini Google Search grounding；记住开关状态时用户切换会立即保存	AI 未配置、Provider 不支持、超时、网络失败、无来源均明确提示；Web 忙时不启动第二个请求	不再维护旧搜索源聚合或 SearXNG 旧配置	联网模式完成，结构化搜索 API/自建后端延期
发布/性能	tools/package_release.ps1 和 docs/performance_stability_check.md	发布脚本复制 exe、Qt runtime、角色/图标/音效资源、README、LICENSE；性能文档覆盖静置、AI、提醒、天气和联网模式	windeployqt、Inno Setup、安装/卸载验证需用户手动执行并记录	未经手动构建和实机安装不能确认二进制运行	验收入口已补齐，本轮不运行 CMake 或构建命令