📊 邮件智能分类功能 - 技术方案

🎯 功能目标

使用 AI 自动将邮件分类到预定义或自动发现的类别中，提高邮件管理效率。

📋 核心功能

1️⃣ 自动分类

# 新增 MCP 工具
classify_email(email_id: str, account_id: str = None) -> Dict
# 返回：
{
  "category": "work",           # 主分类
  "subcategory": "meeting",    # 子分类
  "confidence": 0.95,           # 置信度
  "tags": ["urgent", "项目A"], # 自动标签
  "reasoning": "邮件包含会议邀请..." # 分类理由
}

2️⃣ 批量分类

batch_classify_emails(
    account_id: str = None, 
    folder: str = "INBOX",
    limit: int = 50,
    unread_only: bool = False
) -> Dict
# 返回分类统计和建议

3️⃣ 自定义分类规则

manage_classification_rules(
    action: str,  # "add", "remove", "list"
    rule: Dict = None
) -> Dict

# 规则示例：
{
  "name": "项目邮件",
  "category": "work",
  "conditions": {
    "subject_contains": ["项目", "Project"],
    "from_domain": ["company.com"],
    "has_attachments": true
  },
  "priority": 1
}

🏗️ 技术架构

分类引擎

┌─────────────────────────────────────────┐
│         Email Classification            │
│                                         │
│  ┌──────────────────────────────────┐  │
│  │  1. 特征提取                      │  │
│  │    • 主题关键词                   │  │
│  │    • 发件人域名                   │  │
│  │    • 邮件正文摘要                 │  │
│  │    • 附件类型                     │  │
│  │    • 时间模式                     │  │
│  └──────────────────────────────────┘  │
│                 ⬇️                       │
│  ┌──────────────────────────────────┐  │
│  │  2. 规则匹配（优先级 1）          │  │
│  │    • 用户自定义规则               │  │
│  │    • 精确匹配                     │  │
│  └──────────────────────────────────┘  │
│                 ⬇️                       │
│  ┌──────────────────────────────────┐  │
│  │  3. AI 分类（优先级 2）           │  │
│  │    • Claude API 调用              │  │
│  │    • 语义理解                     │  │
│  │    • 上下文分析                   │  │
│  └──────────────────────────────────┘  │
│                 ⬇️                       │
│  ┌──────────────────────────────────┐  │
│  │  4. 结果合并和优化                │  │
│  │    • 置信度计算                   │  │
│  │    • 多标签支持                   │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘

📊 预定义分类体系

主分类（Category）

📧 personal       - 个人邮件
💼 work          - 工作邮件
🛒 shopping      - 购物/交易
📰 newsletter    - 订阅/通知
🤖 automated     - 自动化邮件
🗑️ spam          - 垃圾邮件
📝 other         - 其他

子分类示例（Subcategory）

work:
  • meeting       - 会议邀请
  • project       - 项目相关
  • report        - 报告/总结
  • urgent        - 紧急事项
  
shopping:
  • order         - 订单确认
  • shipping      - 物流更新
  • invoice       - 发票/账单
  • promotion     - 促销信息
  
newsletter:
  • tech          - 技术资讯
  • news          - 新闻
  • social        - 社交媒体

💡 实现方案

Phase 1: 基础规则引擎（Week 1）

# src/operations/email_classification.py

class EmailClassifier:
    def __init__(self):
        self.rules = self._load_default_rules()
    
    def classify_by_rules(self, email_data: Dict) -> Optional[Dict]:
        """基于规则的快速分类"""
        for rule in sorted(self.rules, key=lambda r: r['priority']):
            if self._match_rule(email_data, rule):
                return {
                    "category": rule['category'],
                    "subcategory": rule.get('subcategory'),
                    "confidence": 1.0,
                    "method": "rule-based"
                }
        return None
    
    def _match_rule(self, email_data: Dict, rule: Dict) -> bool:
        """规则匹配逻辑"""
        conditions = rule['conditions']
        
        # 主题匹配
        if 'subject_contains' in conditions:
            if not any(kw in email_data['subject'] 
                      for kw in conditions['subject_contains']):
                return False
        
        # 发件人域名匹配
        if 'from_domain' in conditions:
            domain = email_data['from'].split('@')[-1]
            if domain not in conditions['from_domain']:
                return False
        
        # 附件检查
        if 'has_attachments' in conditions:
            has_attach = len(email_data.get('attachments', [])) > 0
            if has_attach != conditions['has_attachments']:
                return False
        
        return True

Phase 2: AI 增强分类（Week 2）

class AIEmailClassifier:
    def __init__(self, anthropic_client):
        self.client = anthropic_client
        self.system_prompt = self._build_system_prompt()
    
    async def classify_with_ai(self, email_data: Dict) -> Dict:
        """使用 Claude 进行智能分类"""
        
        # 构建提示词
        prompt = f"""
        请分析以下邮件并分类：
        
        主题：{email_data['subject']}
        发件人：{email_data['from']}
        正文摘要：{email_data['body_preview'][:500]}
        附件：{len(email_data.get('attachments', []))} 个
        
        请返回 JSON 格式：
        {{
          "category": "主分类",
          "subcategory": "子分类",
          "tags": ["标签1", "标签2"],
          "reasoning": "分类理由"
        }}
        """
        
        response = await self.client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=500,
            messages=[{"role": "user", "content": prompt}]
        )
        
        result = json.loads(response.content[0].text)
        result['confidence'] = 0.85  # AI 分类置信度
        result['method'] = 'ai-based'
        
        return result

Phase 3: 混合策略（Week 2）

class HybridClassifier:
    def __init__(self):
        self.rule_classifier = EmailClassifier()
        self.ai_classifier = AIEmailClassifier()
    
    async def classify(self, email_data: Dict) -> Dict:
        """混合分类策略"""
        
        # 1. 先尝试规则匹配（快速、精确）
        rule_result = self.rule_classifier.classify_by_rules(email_data)
        if rule_result and rule_result['confidence'] >= 0.9:
            return rule_result
        
        # 2. 使用 AI 分类（智能、灵活）
        ai_result = await self.ai_classifier.classify_with_ai(email_data)
        
        # 3. 结果融合
        if rule_result:
            # 如果规则和 AI 结果一致，提高置信度
            if rule_result['category'] == ai_result['category']:
                ai_result['confidence'] = 0.95
                ai_result['method'] = 'hybrid'
        
        return ai_result

📈 性能优化

1. 缓存策略

# 缓存发件人的分类结果
sender_cache = {
    "noreply@github.com": {
        "category": "automated",
        "subcategory": "notifications",
        "ttl": 86400  # 24小时
    }
}

2. 批量处理

# 批量调用 Claude API，减少请求次数
async def batch_classify(emails: List[Dict], batch_size: int = 10):
    results = []
    for i in range(0, len(emails), batch_size):
        batch = emails[i:i+batch_size]
        batch_results = await asyncio.gather(*[
            classify(email) for email in batch
        ])
        results.extend(batch_results)
    return results

3. 本地模型（可选）

# 使用轻量级本地模型进行初步筛选
# 降低 API 调用成本
from sklearn.naive_bayes import MultinomialNB

class LocalClassifier:
    def __init__(self):
        self.model = self._load_pretrained_model()
    
    def quick_classify(self, email_text: str) -> Dict:
        """快速本地分类"""
        # 仅用于明显的分类（如垃圾邮件检测）
        # 不确定的交给 AI 处理
        pass

🧪 测试计划

# tests/test_classification.py

def test_rule_based_classification():
    """测试规则匹配"""
    classifier = EmailClassifier()
    
    # 测试会议邮件
    meeting_email = {
        "subject": "明天下午2点项目会议",
        "from": "boss@company.com",
        "body": "会议室A..."
    }
    result = classifier.classify_by_rules(meeting_email)
    assert result['category'] == 'work'
    assert result['subcategory'] == 'meeting'

def test_ai_classification():
    """测试 AI 分类"""
    # 使用 mock Claude API
    pass

def test_classification_accuracy():
    """测试分类准确率"""
    # 使用标注数据集测试
    # 目标准确率 > 90%
    pass

📅 实施时间线

Week 1 (Day 1-3):
  ✅ 设计分类体系和规则格式
  ✅ 实现规则引擎
  ✅ 添加默认分类规则
  ✅ 编写单元测试

Week 1 (Day 4-7):
  ✅ 集成 Claude API
  ✅ 实现 AI 分类逻辑
  ✅ 实现混合策略
  ✅ 添加缓存优化

Week 2 (Day 1-5):
  ✅ 实现 MCP 工具接口
  ✅ 添加批量分类功能
  ✅ 性能测试和优化
  ✅ 完善文档和示例

Week 2 (Day 6-7):
  ✅ 集成测试
  ✅ 用户测试和反馈
  ✅ Bug 修复
  ✅ 发布 v1.4.0

🎯 成功指标

✅ 分类准确率 > 90%
✅ 平均响应时间 < 2s（含 AI 调用）
✅ 规则匹配速度 < 50ms
✅ 支持自定义规则
✅ Claude 可以自然调用分类功能

🔗 相关 Issue

Week 2-3: Add smart reply suggestions #9 智能回复建议（可以基于分类结果）
Week 2-3: Add email summary generation #10 邮件摘要生成（可以按分类聚合）
Week 2-3: Add emotion analysis #11 情感分析（补充分类维度）
Long Term: Build plugin system #12 插件系统（分类规则可以作为插件）

开始时间：计划 2025 Q2
预计工期：2 周
优先级：高（为其他 AI 功能打基础）

Uh oh!

Week 2-3: Add email smart classification #8

Description

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions