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

QtDesktopPet 测试清单与验收标准

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

验收记录格式

每个用例建议记录：

测试日期：
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

静态推演记录

每个模块完成后记录：

模块：
入口：
成功路径：
失败路径：
数据兼容：
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 或构建命令