feat(agents): Phase 8.4-10.5 built-in plugins, bundled skills, coordinator

development-doc/plan/memory-update/phase-m-1-importance-scoring.md

@@ -0,0 +1,219 @@
+# Phase M.1：重要性评分系统
+
+日期：2026-04-04
+状态：规划中
+依赖：无
+工作量：4 天
+
+---
+
+## 1. 本阶段目的
+
+建立记忆重要性评分体系，让 Jarvis 知道「什么对你重要」。
+
+核心问题：
+- 你提了 3 次同一个问题 → 这是你的痛点，应该深入解决
+- 你说「急」「很重要」「困扰我」 → 情绪标记，应该优先级高
+- 这个话题关联了多少其他话题 → 影响面越大越重要
+
+---
+
+## 2. 核心架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  ImportanceScorer                            │
+├─────────────────────────────────────────────────────────────┤
+│  calculate_score(memory) → importance_score (0.0-1.0)      │
+│                                                             │
+│  评分维度:                                                  │
+│  - frequency_score (频率)     × 0.35                       │
+│  - recency_score (时效)       × 0.20                       │
+│  - emotion_score (情绪)       × 0.25                       │
+│  - impact_score (影响面)      × 0.20                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 评分维度详解
+
+### 3.1 Frequency Score (频率)
+
+```python
+frequency_score = min(1.0, recall_count / FREQUENCY_THRESHOLD)
+# FREQUENCY_THRESHOLD = 3  # 提 3 次算高频
+
+# 同时考虑时间衰减
+time_decay = exp(-days_since_last_recall / HALF_LIFE_DAYS)
+# HALF_LIFE_DAYS = 7  # 7 天减半
+```
+
+### 3.2 Recency Score (时效性)
+
+```python
+recency_score = exp(-days_since_creation / RECENCY_HALF_LIFE)
+# RECENCY_HALF_LIFE = 30  # 30 天减半
+
+# 但重要事件例外：即使久远也保持高时效
+if is_emotion_tagged:
+    recency_score = max(recency_score, 0.7)
+```
+
+### 3.3 Emotion Score (情绪)
+
+```python
+EMOTION_KEYWORDS = {
+    "急": 1.0,
+    "很重要": 0.9,
+    "困扰": 0.8,
+    "担心": 0.7,
+    "想解决": 0.6,
+    "无所谓": 0.1,
+}
+
+emotion_score = max([EMOTION_KEYWORDS.get(kw, 0) 
+                     for kw in extracted_emotions], default=0.0)
+```
+
+### 3.4 Impact Score (影响面)
+
+```python
+# 关联多少其他记忆/话题
+impact_score = min(1.0, associated_memory_count / IMPACT_THRESHOLD)
+# IMPACT_THRESHOLD = 5  # 关联 5 个算满
+```
+
+---
+
+## 4. 核心文件
+
+### 4.1 新增文件
+
+| 文件 | 职责 |
+|------|------|
+| `services/memory/frequency_tracker.py` | 频率追踪器 |
+| `services/memory/emotion_analyzer.py` | 情绪分析器 |
+| `services/memory/impact_evaluator.py` | 影响面评估器 |
+| `services/memory/importance_scorer.py` | 综合评分器 |
+
+### 4.2 修改文件
+
+| 文件 | 修改内容 |
+|------|---------|
+| `models/memory.py` | 增加 frequency_count, last_recalled_at, emotion_tags 字段 |
+| `services/memory_service.py` | 集成 ImportanceScorer |
+
+---
+
+## 5. API 设计
+
+### 5.1 ImportanceScorer
+
+```python
+class ImportanceScorer:
+    def calculate_score(self, memory: UserMemory) -> float:
+        """返回 0.0-1.0 的重要性分数"""
+        
+    def get_importance_level(self, memory: UserMemory) -> Literal["high", "medium", "low"]:
+        """返回重要性等级"""
+        
+    def should_escalate(self, memory: UserMemory) -> bool:
+        """是否应该升级为高优先级记忆"""
+```
+
+### 5.2 集成到 MemoryService
+
+```python
+class MemoryService:
+    async def add_memory(self, user_id: int, content: str, emotion_tags: list[str] = None):
+        # 添加记忆时计算初始重要性
+        importance = self.scorer.calculate_score(new_memory)
+        
+    async def recall_memories(self, query: str, user_id: int, top_k: int = 5):
+        # 检索时考虑重要性排序
+        # 高重要性记忆排在前面
+```
+
+---
+
+## 6. 数据模型变更
+
+### 6.1 UserMemory 扩展
+
+```python
+class UserMemory:
+    # 现有字段...
+    frequency_count: int = 0  # 被回忆次数
+    last_recalled_at: DateTime = None  # 上次被回忆时间
+    emotion_tags: list[str] = []  # 情绪标签
+    importance_score: float = 0.5  # 重要性分数
+    importance_level: str = "medium"  # high/medium/low
+    associated_topics: list[str] = []  # 关联话题
+```
+
+---
+
+## 7. 测试设计
+
+### 7.1 频率追踪测试
+
+```python
+def test_frequency_increase():
+    memory = create_memory(frequency_count=0)
+    memory = tracker.increment(memory)
+    assert memory.frequency_count == 1
+
+def test_frequency_decay_over_time():
+    # 7 天后频率应该衰减
+    pass
+```
+
+### 7.2 情绪分析测试
+
+```python
+def test_emotion_extraction():
+    text = "这个问题很急，急需解决"
+    emotions = analyzer.extract(text)
+    assert "急" in emotions
+
+def test_emotion_scoring():
+    score = scorer.calculate_emotion_score(["急", "很重要"])
+    assert score >= 0.9
+```
+
+### 7.3 综合评分测试
+
+```python
+def test_importance_ranking():
+    memories = [low_freq, high_freq, emotional]
+    ranked = sorter.rank_by_importance(memories)
+    assert ranked[0] == emotional  # 情绪标签最重
+```
+
+---
+
+## 8. 验收标准
+
+| 标准 | 说明 |
+|------|------|
+| 频率追踪正常 | recall_count 每次召回 +1 |
+| 情绪识别准确 | 「急」「很重要」等能识别 |
+| 重要性分数正确 | 高频+情绪 = importance >= 0.8 |
+| 评分影响排序 | 高重要性记忆排在检索结果前面 |
+| 单元测试覆盖率 | > 80% |
+
+---
+
+## 9. 工作量估算
+
+| 任务 | 工作量 |
+|------|--------|
+| FrequencyTracker | 0.5 天 |
+| EmotionAnalyzer | 0.5 天 |
+| ImpactEvaluator | 0.5 天 |
+| ImportanceScorer | 1 天 |
+| 模型变更 | 0.5 天 |
+| 集成到 MemoryService | 0.5 天 |
+| 测试 | 1 天 |
+| **合计** | **4 天** |