Files

T

Make 4a7b739eea Add intent dispatch scaffold

2026-06-01 18:35:28 +08:00

20 KiB

Raw Blame History

QtDesktopPet 后续功能开发与当前结构审查文档

适用仓库：https://git.emoera.com/Make/Qt_DesktopPet
目的：在继续新增功能前，先收口当前结构风险，并为后续功能扩展确定统一入口和实现边界。
注意：本文档不是让 Codex 一次性实现所有功能，而是作为后续开发路线和代码审查依据。

1. 当前项目状态概览

根据当前 README 和仓库结构，项目已经具备较完整的桌宠应用基础：

透明无边框桌宠窗口
鼠标拖动、置顶、右键菜单
托盘显示、隐藏、退出
单实例限制
PNG 序列帧动画播放
idle / talk / think / sleep / happy / drag / error 多状态动画
隐藏时暂停动画，显示时恢复
窗口位置、置顶、缩放、性能设置保存
文件日志和日志轮转
AI Provider 分组配置
OpenAI Compatible 聊天请求
Google Gemini 原生聊天请求
SSE 流式输出
AI 回复气泡
聊天输入框
对话历史面板
本地历史保存和历史上限
AI 请求取消和对话清空
角色文件夹导入和角色切换
删除用户导入角色
Windows 打包脚本和 Inno Setup 安装器脚本
Release exe 双击不弹控制台窗口

项目已经从早期 MVP 进入到“可扩展桌面应用原型”阶段，可以开始规划工具能力扩展。

但是，在正式加入定时提醒、天气、本地文件操作、联网搜索之前，建议先做一轮结构收口。

2. 当前需要优先审查或优化的地方

2.1 审查角色切换是否保存后立即生效

当前已经支持角色导入和角色切换。经当前测试确认：

设置页选择新角色
保存设置
当前桌宠窗口是否立即重新加载新角色包

结论：保存后会立即切换，不依赖重启。

当前代码路径：

PetWindow::openSettingsDialog()
↓
applyAppConfig(dialog.appConfig())
↓
PetWindow::applyAppConfig() 比较旧 characterId 与新 characterId
↓
characterId 变化时停止当前动画并调用 loadCharacterPackage()
↓
loadCharacterPackage() 重新构建动画状态并从 idle 状态开始播放

后续不需要围绕 2.1 做修复，只需要保留为回归检查项：

设置页切换角色后点击保存，桌宠应立即显示新角色
不需要关闭或重启程序
切换后动画状态应可继续正常播放

2.2 不要继续向 PetWindow 堆功能

目前 PetWindow 已经承担了过多职责，后续不能继续把所有新功能塞进去。

PetWindow 应该主要负责：

窗口显示
拖动
菜单
子组件组织
基础 UI 信号转发

不建议继续负责：

提醒解析
天气查询
联网搜索
本地文件读写
AI 工具调度
复杂业务状态管理

后续应逐步拆出：

ChatController
ReminderController
WeatherController
FileOperationController
ToolCommandDispatcher

即使暂时不大规模重构，也至少要为后续功能增加统一调度层，不要直接把新逻辑写进 PetWindow::submitChatMessage()。

2.3 新增 IntentRouter / CommandDispatcher

后续功能包括：

定时提醒
天气查询
本地文件操作
联网搜索
普通 AI 对话

这些都来自用户输入框。如果没有统一入口，逻辑会混乱。

可拆成两个模块：

src/intent/
 ├── IntentTypes.h
 ├── IntentRouter.h
 └── IntentRouter.cpp

src/command/
 ├── CommandDispatcher.h
 └── CommandDispatcher.cpp

当前阶段已选择合并为一个轻量模块：

src/assistant/
 ├── UserIntent.h
 ├── IntentRouter.h
 ├── IntentRouter.cpp
 ├── CommandDispatcher.h
 └── CommandDispatcher.cpp

当前意图枚举：

enum class UserIntentType
{
    Chat,
    Reminder,
    Weather,
    FileOperation,
    Search
};

建议入口流程：

用户输入
↓
IntentRouter 判断意图
↓
CommandDispatcher 分发
↓
ReminderManager / WeatherManager / FileOperationManager / WebSearchManager / ConversationManager

第一版意图识别不需要复杂，规则优先即可。

2.4 意图优先级建议

多个意图可能同时出现，需要固定优先级。

2.5 检查 CMAKE_AUTOMOC 设置

如果后续新增的 Manager 使用 QObject、signals、slots，建议开启：

set(CMAKE_AUTOMOC ON)

如果继续保持 CMAKE_AUTOMOC OFF，则后续模块应避免 Q_OBJECT，全部使用普通 C++ 回调或现有信号体系。

建议明确选择一种：

方案 A：开启 AUTOMOC，后续工具模块正常使用 QObject 信号槽
方案 B：保持 OFF，后续模块不得引入 Q_OBJECT

当前阶段选择方案 B：继续保持 CMAKE_AUTOMOC OFF，新增意图分发模块使用普通 C++ 类和同步返回值，不引入 Q_OBJECT。

后续如果 Reminder / Weather / Search 等模块需要大量跨对象异步信号，再单独评估是否切换到方案 A。

2.6 README 与实际功能保持同步

当前 README 已经比较完整，但后续每实现一个功能，应同步更新：

当前状态
配置说明
隐私说明
日志说明
用户数据目录
发布包包含内容

尤其是以下功能需要额外说明：

提醒数据保存位置
天气 API 请求说明
IP 定位隐私说明
本地文件操作权限说明
联网搜索来源和隐私说明

2.7 继续保持角色导入安全策略

当前角色导入已经有较多安全边界，比如：

只导入本地文件夹
验证失败不复制
角色 id 安全字符限制
内置角色不能被覆盖
只允许删除用户导入角色
状态路径安全检查

后续本地文件操作模块也应该沿用这种风格：

路径必须安全
不允许任意系统目录
危险操作必须确认
修改前备份
删除必须二次确认

3. 后续功能总路线

建议不要一次做完所有功能，按以下顺序推进：

阶段 0：结构收口
阶段 1：定时提醒
阶段 2：天气查询
阶段 3：本地文件操作
阶段 4：联网搜索
阶段 5：语音对话 / 更复杂 Agent 能力

当前最推荐先做：

1. IntentRouter / CommandDispatcher
2. 定时提醒
3. 天气查询

4. 阶段 0：结构收口任务

4.1 目标

在正式加新功能之前，先让用户输入有统一分发入口，避免所有功能混进聊天逻辑。

4.2 当前新增文件

src/assistant/UserIntent.h
src/assistant/IntentRouter.h
src/assistant/IntentRouter.cpp
src/assistant/CommandDispatcher.h
src/assistant/CommandDispatcher.cpp

4.3 IntentRouter 职责

判断用户输入属于什么类型：
- 普通聊天
- 定时提醒
- 天气查询
- 本地文件操作
- 联网搜索

第一版可以使用规则判断，不依赖 AI。

4.4 CommandDispatcher 职责

接收用户输入
调用 IntentRouter
根据意图分发到不同 Manager
普通聊天才交给现有 ConversationManager / LLMProvider

4.5 PetWindow 改造要求

PetWindow 只负责把用户输入交给 CommandDispatcher，不直接判断业务逻辑。

示例流程：

PetWindow::submitChatMessage()
↓
CommandDispatcher::dispatch(userText)
↓
根据返回信号更新气泡、状态机、历史

不要继续在 PetWindow 中直接写提醒、天气、搜索或文件逻辑。

5. 阶段 1：定时提醒功能

5.1 功能定位

实现本地一次性提醒功能。

用户可以输入：

晚上8点提醒我提交作业
明天9点提醒我开会
10分钟后提醒我喝水
半小时后提醒我休息
2小时后提醒我看消息

桌宠创建本地提醒，到点后气泡提示或托盘提示。

5.2 第一版范围

要做：

一次性提醒
本地保存
程序重启后提醒不丢
到点后触发气泡和托盘通知
提醒触发后标记 triggered
支持查询当前提醒列表
支持取消提醒

暂不做：

重复提醒
农历提醒
复杂日历
跨设备同步
联网日程
语音提醒

5.3 建议目录

src/reminder/
 ├── ReminderTypes.h
 ├── ReminderParser.h
 ├── ReminderParser.cpp
 ├── ReminderManager.h
 ├── ReminderManager.cpp
 ├── ReminderStore.h
 └── ReminderStore.cpp

5.4 数据结构建议

struct ReminderItem
{
    QString id;
    QString title;
    QString originalText;
    QDateTime remindAt;
    bool triggered = false;
    QDateTime createdAt;
};

5.5 存储文件

保存到：

QStandardPaths::AppConfigLocation/reminders.json

示例：

{
  "reminders": [
    {
      "id": "reminder_001",
      "title": "提交作业",
      "originalText": "晚上8点提醒我提交作业",
      "remindAt": "2026-06-01T20:00:00",
      "triggered": false,
      "createdAt": "2026-06-01T15:20:00"
    }
  ]
}

配置损坏时备份：

reminders.broken.yyyyMMdd-HHmmss.json

5.6 时间解析策略

第一版规则解析优先，不依赖 AI。

支持：

8点
8点30
20:30
晚上8点
下午3点
明天9点
明天上午10点
10分钟后
半小时后
1小时后
2小时后

如果规则解析失败，后续可以再接 AI 解析。

5.7 AI 辅助解析的设计边界

可以后续做 AI 辅助解析，但 AI 不允许直接写文件。

正确流程：

AI 解析用户意图
↓
返回结构化 JSON
↓
程序校验
↓
ReminderManager 创建提醒
↓
ReminderStore 保存

禁止：

AI 直接读写 reminders.json
AI 直接修改本地文件

AI 解析时必须由程序提供当前本地时间：

currentLocalTime
timeZone
weekday
userText

因为 API 模型无法可靠知道用户本机时间。

5.8 到点触发

建议行为：

桌宠可见：显示 ChatBubble + 切 talk 或 happy
桌宠隐藏：系统托盘通知
用户拖动中：不打断 drag，拖动结束后显示

提醒文案：

到时间啦：提交作业

5.9 给 Codex 的阶段任务

1. 新增 reminder 模块
2. 实现一次性 ReminderItem
3. 实现 ReminderStore JSON 读写
4. 实现 ReminderParser 规则解析
5. 实现 ReminderManager 定时检查
6. 到点后发信号给 UI 层
7. UI 层显示气泡和托盘通知
8. 不要把提醒逻辑写进 PetWindow
9. 不要让 AI 直接写本地文件

6. 阶段 2：天气查询功能

6.1 功能定位

天气是独立工具能力，不放进联网搜索。

正确流程：

用户问天气
↓
程序识别 Weather 意图
↓
WeatherManager 调用天气 API
↓
拿到结构化天气数据
↓
AI 根据结构化数据自然语言回复

不要让 AI 自己搜索天气，也不要让 AI 自己拼 URL。

6.2 为什么不用联网搜索做天气

搜索天气有几个问题：

结果格式不稳定
摘要可能过期
地区解析不稳定
无法稳定提取温度、降雨、风力、湿度等字段
AI 总结容易出错

天气应该走天气 API。

6.3 第一版范围

要做：

识别天气请求
支持默认城市
支持用户指定城市
支持当前天气
支持简单今天/明天查询
AI 不可用时模板兜底回复
查询中切 think
回复时切 talk
失败时切 error

暂不做：

天气预警
空气质量详情
分钟级降水
生活指数
地图定位
GPS 定位
自动后台推送
天气提醒
多天气源自动切换

6.4 建议目录

src/weather/
 ├── WeatherTypes.h
 ├── WeatherConfig.h
 ├── WeatherStore.h
 ├── WeatherStore.cpp
 ├── WeatherProvider.h
 ├── WeatherProvider.cpp
 ├── OpenMeteoWeatherProvider.h
 ├── OpenMeteoWeatherProvider.cpp
 ├── WeatherManager.h
 └── WeatherManager.cpp

6.5 天气源建议

第一版推荐：

Open-MeteoProvider

优点：

不需要 API Key
全球可用
适合开源项目默认方案

后续再加：

AmapWeatherProvider
OpenWeatherProvider

如果主要面向国内用户，高德天气也可以作为第二个 Provider，但需要用户配置 Web 服务 Key。

6.6 WeatherConfig

struct WeatherConfig
{
    bool enabled = true;

    QString provider = "open-meteo";

    QString defaultLocationName;
    double defaultLatitude = 0.0;
    double defaultLongitude = 0.0;
    bool hasDefaultCoordinate = false;

    bool allowIpLocation = false;
    bool askBeforeIpLocation = true;

    QString apiKey;
    int timeoutMs = 10000;

    bool useAIResponse = true;
    bool showRawDataWhenAIUnavailable = true;
};

保存到：

QStandardPaths::AppConfigLocation/weather_config.json

6.7 地点策略

优先级：

用户明确输入城市
↓
用户设置的默认城市
↓
用户主动选择 IP 定位
↓
追问用户城市

不要默认静默使用 IP 定位。

6.8 IP 定位原则

IP 定位可以做，但只能作为可选辅助。

原因：

VPN / 代理会导致定位错误
运营商出口可能定位不准
校园网 / 公司网可能不准
用户可能不希望程序自动请求定位服务

建议交互：

你还没有设置默认城市。
可以手动输入城市，也可以使用 IP 自动定位。
是否使用 IP 自动定位？

识别到城市后仍要确认：

我识别到你可能在西安，要设为默认城市吗？

6.9 天气意图关键词

天气
气温
温度
冷不冷
热不热
下雨
降雨
带伞
刮风
风力
湿度
空气质量
雾霾
适合出门
穿什么
外面怎么样

6.10 AI 回复上下文

程序应把结构化天气数据交给 AI：

用户问题：
今天西安天气怎么样？

天气数据：
城市：西安
当前天气：多云
温度：26℃
体感温度：27℃
湿度：60%
风向：东北风
风速：3级
降雨概率：20%
更新时间：2026-06-01 15:00

请根据以上数据，用简洁自然的语气回答。不要编造没有提供的数据。

6.11 AI 不可用时兜底

如果天气 API 成功但 AI 失败，则模板回复：

西安当前天气：多云，26℃，湿度 60%，风力 3 级。更新时间：15:00。

7. 阶段 3：本地文件操作功能

7.1 功能定位

本地文件操作是高风险功能，必须后置，不能早于提醒和天气。

目标是让桌宠能辅助用户处理本地文件，例如：

帮我整理这个文件夹里的图片
帮我把这些日志文件打包
帮我读取这个 txt 总结一下
帮我把这个 md 转成备份副本

7.2 基本原则

AI 不能直接操作本地文件。

正确流程：

AI 理解用户意图
↓
生成操作计划
↓
程序校验路径和权限
↓
展示计划给用户确认
↓
程序执行
↓
执行结果反馈给 AI / 用户

禁止：

AI 直接读写任意文件
AI 直接删除文件
AI 直接覆盖文件
AI 自己决定访问系统目录

7.3 安全边界

必须实现：

工作目录白名单
路径标准化
禁止符号链接逃逸
禁止访问系统目录
禁止访问用户隐私目录，除非用户显式选择
修改前备份
删除前二次确认
批量操作前显示操作计划

7.4 建议目录

src/fileops/
 ├── FileOperationTypes.h
 ├── FileOperationPlanner.h
 ├── FileOperationPlanner.cpp
 ├── FileOperationManager.h
 ├── FileOperationManager.cpp
 ├── FileSandbox.h
 ├── FileSandbox.cpp
 ├── FileBackupManager.h
 └── FileBackupManager.cpp

7.5 第一版建议只做低风险操作

第一版可做：

读取用户主动选择的文本文件
列出用户主动选择的文件夹
复制文件
创建备份
打包 zip
重命名文件，需确认

暂不做：

删除文件
覆盖文件
移动大量文件
修改源码
执行脚本
运行命令
访问系统目录

7.6 修改/删除必须二次确认

即使用户说“删掉它”，也必须确认：

即将删除：
D:/xxx/a.txt
D:/xxx/b.txt

此操作会移动到回收站/备份后删除。
是否继续？

8. 阶段 4：联网搜索功能

8.1 功能定位

联网搜索后置，不要现在优先做。

联网搜索是通用增强能力：

查询最新信息
查官网
查报错
查新闻
查版本
查文档

8.2 不要给每家模型各自配置搜索

不建议：

OpenAIProvider 自己一套搜索
GeminiProvider 自己一套搜索
DeepSeekProvider 自己一套搜索
CustomProvider 自己一套搜索

8.3 建议目录

src/search/
 ├── SearchTypes.h
 ├── SearchProvider.h
 ├── SearXNGSearchProvider.h
 ├── SearXNGSearchProvider.cpp
 ├── WebSearchManager.h
 └── WebSearchManager.cpp

第一版只做：

SearXNG + 自定义 Base URL

后续再加：

Tavily
Brave Search
CustomSearchProvider

8.4 安全边界

不要让 AI 自己生成任意 URL 给程序访问
不要做网页全文抓取第一版
不要默认每次都联网
不要把用户隐私查询写日志
搜索结果要显示来源

9. 建议最终开发顺序

9.1 第一步：收口架构

1. 角色切换保存后立即生效已确认，后续作为回归项保留
2. 新增 IntentRouter
3. 新增 CommandDispatcher
4. 调整 PetWindow 输入流程
5. 当前阶段保持 CMAKE_AUTOMOC OFF，新增模块不使用 Q_OBJECT

9.2 第二步：定时提醒

1. ReminderTypes
2. ReminderStore
3. ReminderParser
4. ReminderManager
5. 到点气泡和托盘通知
6. 设置页增加提醒列表，可后置

9.3 第三步：天气查询

1. WeatherTypes
2. WeatherConfig / WeatherStore
3. OpenMeteoWeatherProvider
4. WeatherManager
5. IntentRouter 天气识别
6. AI 回复 / 模板兜底

9.4 第四步：本地文件操作

1. FileSandbox
2. FileOperationTypes
3. FileOperationPlanner
4. FileOperationManager
5. 用户确认 UI
6. 备份机制

9.5 第五步：联网搜索

1. SearchTypes
2. SearchProvider
3. SearXNGSearchProvider
4. WebSearchManager
5. 来源展示

10. 给 Codex 的总提示

下面这段可以直接作为后续任务总说明：

当前不要急着直接实现提醒、天气、文件操作或联网搜索。

请先审查当前 QtDesktopPet 项目结构，并完成以下准备工作：

1. 角色切换在设置保存后已确认立即生效，后续只需保留回归检查。
2. 新增 IntentRouter / CommandDispatcher，使用户输入先经过统一意图分发。
3. 意图类型包括 Chat、Reminder、Weather、FileOperation、Search。
4. 意图优先级为 Reminder > FileOperation > Weather > Search > Chat。
5. 普通聊天继续走现有 AI 对话流程。
6. 新功能不得继续直接塞进 PetWindow。
7. 后续 Reminder、Weather、FileOperation、Search 均应作为独立模块接入。
8. 当前阶段保持 CMAKE_AUTOMOC OFF，后续模块不要使用 Q_OBJECT；确需 Qt 信号槽时再单独评估。
9. 保持现有隐私策略：API Key、Authorization、完整用户消息、完整错误响应不得写入日志。
10. 保持现有文件安全策略：路径校验、危险操作确认、修改前备份。

11. 当前结论

项目已经可以进入“工具能力扩展阶段”，但不建议直接开写业务功能。

建议先做：

结构收口 → IntentRouter / CommandDispatcher → 定时提醒 → 天气 → 本地文件操作 → 联网搜索

其中：

定时提醒：最适合第一个落地
天气：第二个落地
本地文件操作：风险较高，第三个落地
联网搜索：通用能力，最后落地

20 KiB Raw Blame History Unescape Escape

QtDesktopPet 后续功能开发与当前结构审查文档

1. 当前项目状态概览

2. 当前需要优先审查或优化的地方

2.1 审查角色切换是否保存后立即生效

2.2 不要继续向 PetWindow 堆功能

2.3 新增 IntentRouter / CommandDispatcher

2.4 意图优先级建议

2.5 检查 CMAKE_AUTOMOC 设置

2.6 README 与实际功能保持同步

2.7 继续保持角色导入安全策略

3. 后续功能总路线

4. 阶段 0：结构收口任务

4.1 目标

4.2 当前新增文件

4.3 IntentRouter 职责

4.4 CommandDispatcher 职责

4.5 PetWindow 改造要求

5. 阶段 1：定时提醒功能

5.1 功能定位

5.2 第一版范围

5.3 建议目录

5.4 数据结构建议

5.5 存储文件

5.6 时间解析策略

5.7 AI 辅助解析的设计边界

5.8 到点触发

5.9 给 Codex 的阶段任务

6. 阶段 2：天气查询功能

6.1 功能定位

6.2 为什么不用联网搜索做天气

6.3 第一版范围

6.4 建议目录

6.5 天气源建议

6.6 WeatherConfig

6.7 地点策略

6.8 IP 定位原则

6.9 天气意图关键词

6.10 AI 回复上下文

6.11 AI 不可用时兜底

7. 阶段 3：本地文件操作功能

7.1 功能定位

7.2 基本原则

7.3 安全边界

7.4 建议目录

7.5 第一版建议只做低风险操作

7.6 修改/删除必须二次确认

8. 阶段 4：联网搜索功能

8.1 功能定位

8.2 不要给每家模型各自配置搜索

8.3 建议目录

8.4 安全边界

9. 建议最终开发顺序

9.1 第一步：收口架构

9.2 第二步：定时提醒

9.3 第三步：天气查询

9.4 第四步：本地文件操作

9.5 第五步：联网搜索

10. 给 Codex 的总提示

11. 当前结论

20 KiB

Raw Blame History