EzVibe/docs/v2_design/EVOLUTION_ROADMAP.md

# EzVibe 演进路线图 (v1.x → v2.0)

> 本文档描述 EzVibe 从当前版本到 v2.0 的演进计划。

---

## 概述

当前版本（v1.x）架构坚实、测试覆盖完善（128 个单元测试），但在"健康监测与提醒"这一核心场景上仍有优化空间。

**演进目标**：把"健康数据采集"和"桌宠行为反馈"结合得更自然、更不招人烦。

---

## Phase 1：底层重构与稳定性

**目标**：解决高危隐患，降低资源消耗

**时间线**：约 1 周

### 1.1 用 qasync 替换 QTimer 方案

**现状**：
```python
# main.py:356-358
timer = QTimer(app)
timer.timeout.connect(lambda: self._loop.run_until_complete(asyncio.sleep(0)))
timer.setInterval(20)
```

**目标**：引入 qasync，实现 Qt 事件循环与 asyncio 的原生融合。

**改动点**：
1. `requirements.txt` 增加 `qasync`
2. `main.py` 重构 `_run_qt()` 为 `async def _run_qt()`
3. `ui/pet_window.py` 的 `_on_brain_tick()` 改为异步调用

**验收标准**：
- 桌宠拖动流畅，无掉帧
- CPU 占用率空闲时 < 2%
- asyncio 与 Qt 事件循环无死锁

### 1.2 屏蔽/优化 OCR，引入焦点窗口提取

**现状**：`ScreenCapture` 每分钟调用 `pytesseract` 进行 OCR。

**目标**：用轻量级的焦点窗口名字（Window Title）替代全屏 OCR。

**改动点**：
1. 新增 `perception/window_monitor.py`（平台相关）
   - Windows: `pywin32` / `win32gui`
   - macOS: `AppKit`
   - Linux: `pyatspi` 或 `xlib`
2. `KeyboardMouseMonitor` 增加 `get_active_window_title()` 方法
3. OCR 改为按需触发（仅在 `activity > 0.8` 持续 1 小时后）

**验收标准**：
- 空闲时 CPU 占用降低 50%
- 焦点窗口标题能正确识别（IDE/浏览器/文档）

### 1.3 新增 HealthTracker 模块

**现状**：健康数据混在 RAG 记忆系统中，无法精确时序统计。

**目标**：独立的结构化健康数据库。

**详见**：`HEALTH_TRACKER_SPEC.md`

---

## Phase 2：感知与决策升级

**目标**：让桌宠在健康场景下更"固执"但不招人烦

**时间线**：约 2 周

### 2.1 状态机微调 — DisplayMode 柔性降级

**现状**：`annoyed` 状态下完全禁止 P0 打扰。

**目标**：P0 提醒不屏蔽，但表现形式根据情绪状态柔化。

**改动点**：
1. `agent/scheduler.py` 的 `Behavior` 增加 `display_mode` 属性：
   ```python
   from enum import Enum
   class DisplayMode(Enum):
       NORMAL = "normal"    # 正常打扰
       QUIET = "quiet"     # 缩角落举牌子
       AGGRESSIVE = "aggressive"  # 强制弹窗
   ```
2. `BehaviorScheduler.check_and_trigger()` 根据情绪状态选择 display_mode
3. `ui/pet_window.py` 实现对应的 UI 表现（正常/安静/强制）

### 2.2 LLM Prompt 工程升级

**目标**：将 HealthTracker 的统计数据作为固定上下文注入 System Prompt。

**改动点**：
1. `agent/brain.py` 的 `DEFAULT_SYSTEM_PROMPT` 增加健康数据注入区：
   ```python
   【用户健康状态】
   - 今天喝水次数：{water_today}
   - 连续静坐时间：{sedentary_minutes} 分钟
   - 上次起身：{last_stand_time}
   ```
2. `AgentBrain.think()` 调用前从 HealthTracker 读取最新数据

### 2.3 解耦"动作触发"与"文案生成"

**现状**：`decide_action()` 等待 LLM 生成文案后才执行 UI 动作。

**目标**：P0 健康提醒立即执行 UI 动作，LLM 文案异步加载或使用 Fallback 缓存。

**改动点**：
1. `agent/brain.py` 增加 `FallbackMessageCache`：
   ```python
   FALLBACK_MESSAGES = {
       "remind_water": ["记得喝水哦～", "该补充水分了！", "喝水时间到！"],
       "remind_stretch": ["起来伸展一下吧！", "坐了好久啦，站起来动动！"],
   }
   ```
2. `BehaviorScheduler` 触发时直接返回 Fallback 消息
3. LLM 文案异步加载后替换（如果来得及）

---

## Phase 3：UI 与表现力强化

**目标**：让桌宠更有存在感，更能被注意到

**时间线**：约 2 周

### 3.1 番茄钟模式

**目标**：桌宠 UI 增加可视化倒计时状态。

**功能**：
- 用户通过右键菜单启动番茄钟（默认 25 分钟）
- 进入番茄钟时桌宠变更为 `focused` 状态（带学霸眼镜动画）
- 期间严格执行免打扰（P2/P3 完全禁止）
- 结束后主动撒花提醒休息（5 分钟）

**改动点**：
1. `ui/pet_window.py` 增加番茄钟 UI（倒计时标签）
2. `agent/emotion.py` 增加 `TOMATO` 状态
3. `agent/scheduler.py` 番茄钟期间修改活跃度限制逻辑

### 3.2 系统级通知

**现状**：仅使用 Qt 气泡通知，全屏时可能被遮挡。

**目标**：接入操作系统原生通知。

**改动点**：
1. `ui/pet_window.py` 增加 `show_system_notification()` 方法
   - Windows: `win10toast` / `plyer`
   - macOS: `osascript` / `pync`
2. P0 提醒同时发送 Qt 气泡 + 系统通知

### 3.3 微交互确认 UI

**目标**：喝水/伸展提醒增加"已做"和"等会儿"按钮。

**改动点**：
1. `ui/pet_window.py` 的 `show_reminder()` 增加按钮选项
2. 点击"已做"时：
   - 触发 `user_healthy_action` 事件 → `emotion.update("happy")`
   - 记录到 HealthTracker
3. 点击"等会儿"时：
   - 延迟 N 分钟再次提醒（可配置，默认 5 分钟）

### 3.4 隐式确认反馈机制

**目标**：基于感知数据判断用户是否真的起身了。

**逻辑**：
```
提醒起立
    ↓
等待 2 分钟
    ↓
ActivityDetector 监测键鼠完全无动作？
    ↓ 是
用户"去休息了" → emotion.update("happy") → 正向反馈
    ↓ 否
用户还在工位 → 再次提醒（或降低频率）
```

---

## 里程碑

| 阶段 | 目标 | 预计完成 |
|------|------|----------|
| v1.5 | Phase 1 完成（qasync + HealthTracker） | Week 1 |
| v1.6 | Phase 2 完成（DisplayMode + Prompt 升级） | Week 3 |
| v2.0 | Phase 3 完成（番茄钟 + 系统通知 + 微交互） | Week 5 |

---

## 附录：技术债务清理

| 序号 | 技术债务 | 处理方式 |
|------|----------|----------|
| 1 | 两处 ActivityDetector（感知层 + 调度器） | 统一使用感知层的实现，调度器引用其单例 |
| 2 | `brain.py` 和 `scheduler.py` 都有主动行为决策 | 明确分工：brain 负责对话触发的行为，scheduler 负责定时触发的行为 |
| 3 | 记忆系统每次检索都先写入 | 改为仅在 `think()` 时写入，检索时用历史数据 |