# QtDesktopPet 当前路线与结构收口

本文档是当前有效的开发路线总览。旧版长文档已归档到 `docs/archive/QtDesktopPet_后续功能规划与结构审查_旧版.md`。

## 当前产品状态

项目当前是一个 Windows 优先的 Qt 6 Widgets 桌面宠物应用，主要能力包括：

- 透明无边框桌宠窗口、拖动、置顶、托盘和单实例唤醒。
- PNG 序列帧角色包、多状态动画、角色导入、切换、导出和用户角色目录管理。
- AI 对话，支持 OpenAI Compatible、OpenAI 官方、Google Gemini、DeepSeek、Custom 配置。
- 输入框联网模式，使用 AI Provider 原生联网能力，不再维护旧搜索引擎聚合。
- 定时提醒，支持一次性和每天/每周/每月重复提醒、音效管理、历史保留和隐藏/AI 忙通知规则。
- 天气查询，使用 Open-Meteo、默认城市、IP fallback、多候选提示和默认城市测试。
- 对话历史管理，支持本地保存、关键词搜索、Provider/模型/时间筛选、Markdown/JSON 导出。
- 本地应用启动，支持登记应用、别名、手选 `.exe`、启动前确认和开机自启动配置。
- 本地文件操作 v1，支持读取文本、列目录、复制、备份和重命名。
- 本地工作区 Agent v1b，支持选择工作区、扫描索引、搜索文件、搜索文本、读取文本文件、项目结构摘要、文件内容总结、打开普通文件、显示所在位置和独立 Agent 窗口。

## 当前结构边界

已经形成的模块边界：

| 模块 | 目录 | 状态 |
| --- | --- | --- |
| AI 对话 | `src/ai/` | 已落地 |
| 意图分发 | `src/assistant/` | 已落地 |
| 角色包 | `src/character/` | 已落地 |
| 配置与密钥 | `src/config/` | 已落地 |
| 文件操作 v1 | `src/fileops/` | 已落地，后续将被 Workspace Agent 替代 |
| 应用启动 | `src/launcher/` | 已落地 |
| 通知 | `src/notification/` | 已落地 |
| 提醒 | `src/reminder/` | 已落地 |
| 状态机 | `src/state/` | 已落地 |
| 系统能力 | `src/system/` | 已落地 |
| 天气 | `src/weather/` | 已落地 |
| 联网模式 | `src/web/` | 已落地 |
| 本地工作区 Agent | `src/workspace/` + `src/ui/WorkspaceAgentWindow.*` | v1a.1/v1b/v1b.5 独立窗口化已落地 |

`PetWindow` 仍然承担较多 UI 编排职责。后续新增大功能必须优先放在独立模块和 Controller 中，`PetWindow` 只保留入口、展示和确认交互。

## 下一阶段主线

下一阶段主线仍是本地工作区 Agent，而不是继续扩展旧 `src/fileops/`。

v1a.1/v1b/v1b.5 已完成：

- 用户选择一个本地工作区目录。
- 桌宠可以扫描、搜索、读取和分析该工作区内文件。
- 桌宠可以打开工作区内普通文件、打开文件夹、显示文件所在位置。
- 独立 Agent 窗口可以展示文件结果、文本命中、最近读取、用户任务、本地工具结果和 AI 分析结果，并对选中结果执行读取、打开、显示位置。
- 写操作误分发已收口：创建/新建/写入/修改不会再误走旧 fileops 的读取文本文件流程。
- 文本搜索误分发已收口：`含class的文件 / 包含 class 的文件 / 找一下含 class 的文件` 会走工作区全文搜索，不再弹旧文本文件选择框。

后续目标：

- 桌宠可以生成文件修改计划。
- 创建、修改、复制、移动、重命名、删除到回收站等写操作必须先展示计划并等待用户确认。
- 不允许访问工作区外路径。
- 不允许执行系统命令、脚本或聊天文本中的命令参数。
- 不允许永久删除文件。

正式施工计划见：

`docs/agent/DesktopPet_本地工作区Agent_施工计划.md`

## 功能优先级建议

当前聊天意图建议保持以下原则：

1. 提醒明确优先，例如“明天提醒我看天气”应创建提醒。
2. 天气明确问答走天气模块，例如“明天西安天气怎么样”。
3. 工作区相关文件和代码任务走 Workspace Agent，例如“搜索这个项目里的 README”“读取 main.cpp”“分析这个项目”；重命名等写操作留到后续阶段。
4. 明确应用启动走 Launcher，例如“打开 Codex”“启动酷狗音乐”。
5. 其余走普通聊天或联网聊天。

不能简单用“文件 / 打开 / 搜索”这类宽关键词吞掉所有请求。尤其要避免：

- “打开微信”误判为工作区打开文件。
- “搜索 Qt 最新版本”误判为工作区搜索。
- “把天气截图保存到桌面”误判为天气查询。

## 当前延期项

以下能力继续延期，不进入本地工作区 Agent 第一阶段：

- 语音输入和语音朗读。
- Live2D、GIF、视频形象。
- 插件系统。
- 云同步和自动更新。
- 长期记忆系统。
- 角色市场或角色包分享平台。
- Shell 命令执行、脚本执行、自动安装依赖。
- 自动 git commit、自动推送、自动联网下载并执行文件。
- 工作区外全盘搜索。
- 复杂网页抓取和旧搜索引擎聚合。

## 验收策略

- Codex 不调用 CMake、`cmake --build`、Qt Creator 构建或等价构建命令。
- 每完成一个模块，先做静态检查和逻辑推演。
- 编译和运行验证由用户手动执行。
- 功能验收按 `docs/QtDesktopPet_测试清单与验收标准.md`。
- 性能和发布验收按 `docs/performance_stability_check.md`。