EzVibe/docs/v2_design/DESIGN_DECISIONS.md

EzVibe 关键设计决策记录

本文档记录 EzVibe 项目中的关键设计决策及其理由。

---

1. 技术栈选择

1.1 为什么用 SQLite + NumPy 而非 ChromaDB

决策：使用 MemoryStore(SQLite) + VectorEngine(NumPy) 实现向量检索。

原因：

• 轻量：ChromaDB 需要额外的服务端进程，SQLite 是单文件零依赖
• 隐私：所有数据存储在本地，不经过任何第三方服务
• 可控：向量维度、索引策略完全可控，便于调试
• 测试友好：SQLite 路径可配置，单元测试使用内存数据库 :memory:

备选方案考虑：

• ChromaDB：功能更完善，但增加了运行时复杂度
• FAISS：大规模场景性能更好，但当前规模（< 1000 条记忆）NumPy 足够

结论：当前阶段 SQLite + NumPy 是最优解，FAISS 作为预留（vector_mode="faiss" 接口已预留）。

---

1.2 为什么用 TF-IDF DummyEmbedder 而非 Ollama

决策：DummyEmbedder 使用 TF-IDF 实现，开发者/测试环境不依赖 Ollama 服务。

原因：

• 离线可用：开发者在没有运行 Ollama 的情况下也能跑测试
• 启动快：不需要等待 Ollama 服务启动
• 确定性：TF-IDF 输出固定（给定相同语料库），有利于单元测试复现

限制：

• TF-IDF 是词袋模型，不理解语义（"奶茶"和"咖啡"在向量空间可能很远）
• 不适用于生产环境（请使用 OllamaEmbedder 或 OpenAIEmbedder）

结论：开发测试用 Dummy，生产部署用 Ollama/OpenAI。接口已统一为 EmbedderBase。

---

1.3 为什么延迟构造 PetWindow 类

决策：ui/pet_window.py 使用 type() 动态构造 PetWindow 类，而非模块级导入。

原因：

• Dummy 模式兼容：headless 测试不导入 Qt，避免 ImportError
• Qt 版本兼容：PySide6 和 PyQt6 API 略有差异，延迟构造可以在运行时检测
• 避免循环导入：模块级导入 from PySide6 import QtWidgets 会触发 Qt 初始化

代码示例：

# 旧方案（有问题）
from PySide6 import QtWidgets  # 模块级导入，PySide6 不可用时直接崩溃

# 新方案（当前）
def _make_pet_window_class():
    if _load_qt() is None:
        raise ImportError("需要 PySide6 或 PyQt6")
    # 动态构造...

PetWindow = None  # 占位符

def create_pet_window(...):
    global PetWindow
    if force_dummy or _load_qt() is None:
        return DummyPetWindow(...)
    if PetWindow is None:
        PetWindow = _make_pet_window_class()
    return PetWindow(...)

---

2. 架构设计

2.1 为什么分离感知层和调度器中的 ActivityDetector

现状：感知层（KeyboardMouseMonitor._activity）和调度器（BehaviorScheduler._activity）各有一个 ActivityDetector 实例。

原因：

• 解耦：感知层负责数据采集，调度器负责行为决策，职责分离
• 独立测试：两个组件可以独立单元测试

问题：

• 两处逻辑略有差异（窗口大小、基准计算）
• 可能导致数据不一致

改进方向（见 EVOLUTION_ROADMAP.md）：

• 统一使用感知层的单例 get_global_monitor()._activity
• 调度器引用而非独立实例

---

2.2 为什么 brain 和 scheduler 都有主动行为决策

现状：

• AgentBrain.decide_action()：对话中触发的主动行为
• BehaviorScheduler.check_and_trigger()：定时调度触发的主动行为

原因：

• 触发源不同：brain 响应用户输入，scheduler 响应时间/活跃度
• 优先级不同：scheduler 的 P0 提醒需要打断，brain 的行为是 P3

问题：

• 边界模糊，可能导致行为重复触发
• decide_action() 和 check_and_trigger() 可能同时返回同一个行为

改进方向：

• 明确分工：brain 负责对话触发的闲聊行为（P3），scheduler 负责定时触发的健康提醒（P0/P1）
• 共享冷却时间：两个模块的行为共享 _action_cooldown

---

2.3 为什么不使用消息队列中间件

决策：使用 Python 内置 queue.Queue 而非 Redis/RabbitMQ。

原因：

• 轻量：不需要额外的进程和服务
• 本地优先：桌宠是本地应用，不需要分布式架构
• 延迟可接受：事件传递延迟 < 10ms，完全满足需求

结论：当前规模不需要消息队列中间件。如果未来需要跨进程通信，可以引入 asyncio.Queue。

---

3. 行为设计

3.1 为什么用蒙特卡洛采样而非确定性转移

决策：EmotionEngine 使用蒙特卡洛随机采样选择下一状态。

原因：

• 自然感：桌宠不会每次都以相同方式反应，增加变化和惊喜
• 符合文档：设计文档明确要求"概率转移"
• 可调节：随机种子可配置，单元测试可复现

代价：

• 行为不完全可预测
• 可能导致情绪频繁切换（已通过 min_residence_seconds 缓解）

---

3.2 为什么 annoyed 状态禁止 P0 打扰

现状：emotion == "annoyed" and behavior.priority <= 1 → 禁止打扰

问题：

• 用户连续工作 3 小时不休息，情绪可能变为 annoyed
• 此时屏蔽久坐提醒，失去健康监测意义

改进方向：见 ARCHITECTURE_REVIEW.md 的"柔性降级"方案。

---

3.3 为什么用 [ACTION: type:description] 标签

决策：从 LLM 回复中解析 [ACTION: type:description] 标签来触发主动行为。

原因：

• 灵活性：LLM 可以根据上下文决定是否触发行为、触发什么行为
• 可读性：标签格式人类可读，便于调试
• 解耦：行为决策在 LLM 端，行为执行在本地端

限制：

• 依赖 LLM 按格式输出（可能不听话）
• 正则解析可能匹配到用户输入中的类似文本

改进方向：

• 严格模式：LLM 必须按格式输出，否则忽略
• 容错模式：优先匹配 [ACTION: 开头的内容

---

4. 性能与资源

4.1 为什么 OCR 使用 pytesseract 而非云服务

决策：OCR 使用本地 pytesseract，不依赖云服务。

原因：

• 隐私：屏幕截图不经过任何第三方
• 离线可用：不需要网络连接
• 成本：无 API 调用费用

代价：

• CPU 密集，电池消耗
• 准确率不如云端服务

改进方向：用焦点窗口提取替代全屏 OCR（见 ARCHITECTURE_REVIEW.md）。

---

4.2 为什么用 pynput 而非其他监听方案

决策：使用 pynput 实现全局键鼠监听。

原因：

• 跨平台：支持 Windows/macOS/Linux
• 活跃维护：pynput 是当前最活跃的全局监听库
• 简单 API：回调式设计，易于使用

替代方案：

• pyhook（Windows only）
• keyboard（仅键盘，无鼠标）
• appnope（macOS only）

结论：pynput 是当前最优解。

---

5. 未来决策预留

以下决策暂未落地，但在代码中已预留接口：

决策	预留方式
FAISS 向量检索	VectorEngine(mode="faiss") 接口已预留
多后端 LLM	LLMBackend 策略模式，支持 Ollama/OpenAI/Dummy
多语言	System Prompt 支持中文，当前固定 zh_CN
番茄钟模式	EmotionState 预留 TOMATO 状态（未启用）
系统通知	show_reminder() 预留 show_system_notification() 接口