EzVibe/docs/v2_design/ARCHITECTURE.md

EzVibe v2 架构设计文档

本文档描述 EzVibe 系统当前（v1.x）的整体架构设计。

---

1. 系统概览

EzVibe 是一个运行在用户桌面上的 AI 桌宠系统，核心目标是健康监测与提醒（久坐提醒、喝水提醒）。

技术栈：

• Python 3.10+
• PySide6 / PyQt6（Qt 图形界面）
• SQLite + NumPy（本地持久化 + 向量检索）
• Ollama / OpenAI（LLM 推理）
• pynput（全局键鼠监听）

运行模式：

• 完整 GUI 模式（python main.py）
• Headless Dummy 模式（python main.py --dummy）
• API Server 模式（python main.py --server）

---

2. 分层架构

┌─────────────────────────────────────────────┐
│              表现层 (UI)                     │
│         ui/pet_window.py                    │
│    - PetWindow / DummyPetWindow             │
│    - 情绪动画渲染、右键菜单、托盘            │
└────────────────────┬────────────────────────┘
                     │
┌────────────────────▼────────────────────────┐
│              智能层 (Agent)                  │
│                                             │
│  ┌─────────┐ ┌─────────┐ ┌──────────────┐  │
│  │ brain   │ │ emotion │ │   scheduler  │  │
│  │ .py     │ │ .py     │ │   .py        │  │
│  │ LLM决策 │ │ 状态机  │ │   行为调度    │  │
│  └────┬────┘ └────┬────┘ └──────┬───────┘  │
│       └───────┬──┴────────────┘          │
│        ┌──────▼──────┐                   │
│        │   memory    │                   │
│        │   .py       │                   │
│        │ RAG向量记忆  │                   │
│        └─────────────┘                   │
└────────────────────┬────────────────────────┘
                     │
┌────────────────────▼────────────────────────┐
│              感知层 (Perception)              │
│     perception/keyboard_mouse_monitor.py   │
│    - 键鼠事件监听、活跃度检测               │
│    - ScreenCapture（截图+OCR）              │
└─────────────────────────────────────────────┘

---

3. 模块职责

3.1 表现层 — ui/pet_window.py

职责：

• 渲染桌宠窗口（无边框、置顶、透明背景）
• 情绪状态驱动动画（idle/happy/focused/annoyed/sleepy）
• 提醒通知弹窗（健康喝水/伸展提醒）
• 拖拽移动、右键菜单、最小化到托盘

关键类：

• PetWindow：PySide6/PyQt6 实现，延迟构造避免导入冲突
• DummyPetWindow：headless 测试替代，不依赖 Qt

图像资源：

assets/pet/
├── idle/
├── happy/
├── focused/
├── annoyed/
└── sleepy/

每个情绪目录下存放 16 帧 PNG 动画（180×180px）。无图像时回退到 emoji 显示。

设计亮点：

• _make_pet_window_class() 使用 type() 动态构造类，避免模块级导入 QtWidgets
• create_pet_window() 工厂函数，支持 force_dummy 强制降级

---

3.2 智能层 — agent/

3.2.1 brain.py — AgentBrain（LLM 推理引擎）

职责：

• 整合记忆上下文 + 情绪状态 + 用户输入
• 调用 LLM（Ollama/OpenAI/Dummy）生成回复
• 决策是否触发主动行为
• 管理会话历史（短期上下文窗口）

LLM 后端适配器（策略模式）：

LLMBackend (基类)
├── OllamaBackend    — http://localhost:11434
├── OpenAIBackend    — OpenAI API / 兼容第三方
└── DummyLLMBackend  — 测试用固定回复

核心方法：

• think(user_input)：接收用户输入，返回 {"text", "emotion_state", "action"}
• decide_action()：异步决策是否触发主动行为
• _parse_action()：从 LLM 回复中解析 [ACTION: type:description] 标签

System Prompt 模板：

DEFAULT_SYSTEM_PROMPT = """你是「EzVibe」，一个运行在用户桌面上的 AI 桌宠。
【当前情绪状态】{emotion_display}
【性格设定】友善、活泼，偶尔会犯懒或闹小脾气...
【主动行为能力】可以提醒喝水/休息，或做出可爱小动作。
请用自然对话风格回复。如果想触发主动行为，在回复末尾加上：
[ACTION: <action_type>:<description>]
"""

3.2.2 emotion.py — EmotionEngine（情绪状态机）

状态集合：S = {idle, happy, focused, annoyed, sleepy}

核心机制：

• 5×5 状态转移矩阵 P
• 上下文调制因子（事件驱动增益）
• 蒙特卡洛随机采样
• 最小驻留时间限制（防止抖动）

状态转移矩阵（行=当前状态，列=目标状态）：

          → idle   happy  focused annoyed sleepy
  idle   │ 0.4    0.2    0.2     0.1    0.1
  happy  │ 0.2    0.5    0.1     0.1    0.1
 focused │ 0.1    0.2    0.5     0.1    0.1
 annoyed │ 0.1    0.1    0.1     0.6    0.1
 sleepy  │ 0.2    0.1    0.1     0.1    0.5

事件增益：ContextBoost.EVENT_BOOSTS

"long_work_session"  → sleepy +2.0, focused +0.8
"user_focused"        → focused +2.5
"reminder_ignored"    → annoyed +3.0
"user_praise"         → happy +3.0
"user_healthy_action" → happy +2.0

关键方法：

• update(event)：根据事件触发状态转移
• tick()：时钟推进，触发 time_passes 事件
• force_state(state)：强制设置状态（测试用）

3.2.3 scheduler.py — BehaviorScheduler（行为调度器）

行为优先级定义：

• PRIORITY_HIGHEST = 0：健康/高危提醒（打断所有）
• PRIORITY_USER_INPUT = 1：用户主动输入响应
• PRIORITY_PROACTIVE = 2：系统主动闲聊/行为
• PRIORITY_LLM_TRIGGER = 3：LLM 自触发

内置行为：

行为	优先级	冷却	说明
remind_water	0	1800s	喝水提醒
remind_stretch	0	3600s	久坐伸展提醒
idle_nudge	2	300s	空闲闲聊触发
happy_nudge	2	600s	开心时主动搭话

核心逻辑：

• 活跃度限制：极度专注（activity < 0.15）时禁止 P2/P3 打扰
• 情绪调制：focused 状态概率×0.2，sleepy 状态概率×0.3
• 提醒队列：Reminder 延迟执行任务

3.2.4 memory.py — VectorMemory（向量记忆系统）

数据模型：

@dataclass
class MemoryEntry:
    text: str           # 记忆文本
    embedding: list[float]  # 向量嵌入
    tags: list[str]     # 标签
    metadata: dict      # 元数据
    created_at: float   # 时间戳
    id: str | None      # UUID

存储层：SQLite + MemoryStore

CREATE TABLE memories (
    id         TEXT PRIMARY KEY,
    text       TEXT NOT NULL,
    embedding  BLOB NOT NULL,  -- numpy 序列化
    tags       TEXT NOT NULL DEFAULT '[]',
    metadata   TEXT NOT NULL DEFAULT '{}',
    created_at REAL NOT NULL
);

嵌入适配器：

make_embedder(backend)
├── OllamaEmbedder   — nomic-embed-text
├── OpenAIEmbedder  — text-embedding-3-small
└── DummyEmbedder   — TF-IDF（开发/测试用）

RAG 工作流：

1. Query → Embedding
2. 向量检索 Top-k
3. 格式化上下文
4. 注入 System Prompt

---

3.3 感知层 — perception/

3.3.1 keyboard_mouse_monitor.py — KeyboardMouseMonitor

职责：全局键盘/鼠标监听，使用 pynput 全局钩子。

核心组件：

• ActivityDetector：滑动窗口活跃度统计
• KeyboardMouseMonitor：pynput listener + queue
• ScreenCapture：mss 截图 + pytesseract OCR

活跃度计算：

baseline = window_seconds / 60.0 * 30.0  # 30 events/min = normal
activity = min(raw / baseline, 1.0)

阈值定义：

• activity < 0.15：极度专注（可能深度工作/游戏）
• activity < 0.3：比较专注
• 0.3 ≤ activity < 0.7：适度活跃
• activity ≥ 0.7：非常活跃

全局单例：

_global_monitor: KeyboardMouseMonitor | None = None

def get_global_monitor(...) → KeyboardMouseMonitor
def stop_global_monitor() → None

---

4. 主入口 — main.py

4.1 EzVibeApp 初始化流程

def _init_components(self):
    1. EmotionEngine()
    2. VectorMemory(embedder_backend="dummy")  # 避免依赖 Ollama
    3. AgentBrain(llm_backend=...)
    4. KeyboardMouseMonitor + ScreenCapture
    5. BehaviorScheduler(emotion_engine, activity_detector)
    6. PetWindow（延迟到 QApplication 之后）

4.2 运行模式

Dummy 模式（headless 测试）：

def _run_dummy(self):
    # 初始化后直接打印状态摘要，模拟行为触发

Qt 模式：

def _run_qt(self):
    app = QtWidgets.QApplication(sys.argv)
    self._window = create_pet_window(...)  # QApplication 之后才能创建
    # QTimer 20ms 驱动 asyncio 轮询（临时方案，待改进）
    timer.timeout.connect(lambda: self._loop.run_until_complete(asyncio.sleep(0)))
    app.exec()

---

5. API 服务器 — api/server.py

FastAPI 服务器，提供 REST/WebSocket 接口：

端点	方法	说明
/status	GET	返回系统状态
/emotion	GET/POST	获取/设置情绪状态
/remind	POST	添加提醒
/memory/search	POST	RAG 检索
/memory/add	POST	添加记忆
/ws	WebSocket	实时事件流

---

6. 数据流

6.1 用户交互流程

用户输入文本
    ↓
AgentBrain.think()
    ↓
┌─ 注入情绪状态到 System Prompt
├─ RAG 检索相关记忆（VectorMemory.search）
├─ 追加对话历史
└─ 调用 LLM（Ollama/OpenAI/Dummy）
    ↓
解析 [ACTION: ...] 标签
    ↓
返回 {"text": "...", "action": {...}, "emotion_state": "..."}
    ↓
PetWindow 显示回复 + 动画

6.2 健康监测流程

定时调度（每 10s）
    ↓
BehaviorScheduler.check_and_trigger()
    ↓
┌─ 冷却时间检查
├─ 活跃度限制检查（极度专注时禁止打扰）
├─ 概率触发（结合情绪调制）
└─ 执行 action_fn()
    ↓
show_reminder() → 气泡通知
    ↓
记录到记忆（VectorMemory.add）

6.3 感知数据流

pynput 全局钩子（独立线程）
    ↓
queue.Queue 传递事件
    ↓
_worker_loop 消费队列
    ↓
ActivityDetector.record() 记录到滑动窗口
    ↓
get_activity() → 0.0~1.0 活跃度

---

7. 文件结构

EzVibe/
├── main.py                 # 主入口，EzVibeApp
├── requirements.txt        # 依赖列表
├── setup_project.py        # 项目初始化脚本
│
├── agent/
│   ├── __init__.py
│   ├── brain.py           # AgentBrain + LLM后端
│   ├── emotion.py         # EmotionEngine 状态机
│   ├── scheduler.py       # BehaviorScheduler + ActivityDetector
│   ├── memory.py          # VectorMemory + MemoryStore + VectorEngine
│   └── test_*.py          # 单元测试
│
├── perception/
│   ├── __init__.py
│   ├── keyboard_mouse_monitor.py  # KeyboardMouseMonitor + ActivityDetector
│   └── test_perception.py
│
├── ui/
│   ├── __init__.py
│   ├── pet_window.py      # PetWindow + DummyPetWindow
│   └── test_pet_window.py
│
├── api/
│   ├── __init__.py
│   └── server.py          # FastAPI 服务器
│
├── data/                  # SQLite 数据库目录
├── assets/                # 桌宠图像资源
│
└── docs/
    ├── v2_design/
    │   ├── ARCHITECTURE.md         # 本文档
    │   ├── ARCHITECTURE_REVIEW.md  # 架构评审
    │   ├── EVOLUTION_ROADMAP.md    # 演进路线
    │   ├── HEALTH_TRACKER_SPEC.md  # HealthTracker 规格
    │   └── DESIGN_DECISIONS.md     # 设计决策
    └── *.md               # 其他文档

---

8. 已知限制与改进方向

问题	现状	改进方向
Qt + asyncio 融合	QTimer 轮询（不稳定）	引入 qasync
OCR 性能消耗	mss + pytesseract 每分钟执行	轻量级焦点窗口提取
LLM 延迟	同步等待 5 秒	解耦动作与文案，Fallback 缓存
annoyed 状态屏蔽 P0	完全禁止打扰	柔性降级（安静模式）
健康数据缺乏结构化	RAG 模糊检索	HealthTracker 结构化数据库
奖惩机制无闭环	单向提醒	隐式确认 + 正向反馈

详见 ARCHITECTURE_REVIEW.md。