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 方案

现状：

# 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 属性：

   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 增加健康数据注入区：

   【用户健康状态】
   - 今天喝水次数：{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：

   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() 时写入，检索时用历史数据