# 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 天** |