单一职责的升维：从类到 Agent

# ❌ 上帝 Agent
class UniversalAgent:
    """
    你是一个万能助手，可以：
    1. 处理邮件（读取、撰写、发送、归档）
    2. 管理日程（查询、创建、修改、删除）
    3. 操作文件（创建、编辑、删除、搜索）
    4. 网络搜索（Google、百度、Bing）
    5. 数据分析（CSV、Excel、JSON）
    6. 代码编写（Python、JavaScript、Go）
    7. 代码审查（安全、性能、风格）
    8. 系统管理（SSH、Docker、K8s）
    ...
    请根据用户输入判断需要做什么。
    """

# ❌ 面条式调用
class AgentA:
    def process(self, task):
        if task.type == "X":
            return AgentB().process(task)  # A → B
        return self.handle(task)

class AgentB:
    def process(self, task):
        if task.needs_more_info:
            return AgentA().process(task)  # B → A (循环!)
        return AgentC().process(task)    # B → C

class AgentC:
    def process(self, task):
        if task.is_complex:
            return AgentA().process(task)  # C → A (另一个循环!)
        return self.handle(task)

# agents/base.py
from abc import ABC, abstractmethod
from typing import Any, Dict
from dataclasses import dataclass

@dataclass
class AgentContext:
    """Agent 执行上下文"""
    user_id: str
    session_id: str
    metadata: Dict[str, Any]

@dataclass  
class AgentResult:
    """Agent 执行结果"""
    success: bool
    data: Any
    error: str = None

class BaseAgent(ABC):
    """
    单一职责 Agent 的基类。
    
    每个子类应该：
    1. 只有一个明确的职责
    2. 只处理与之相关的工具
    3. 明确的输入输出契约
    """
    
    def __init__(self, name: str, context: AgentContext):
        self.name = name
        self.context = context
        self._tools = []
    
    @property
    @abstractmethod
    def description(self) -> str:
        """Agent 职责描述，用于编排器选择"""
        pass
    
    @property
    @abstractmethod
    def capabilities(self) -> list:
        """Agent 能力列表"""
        pass
    
    @abstractmethod
    async def execute(self, intent: str, params: Dict[str, Any]) -> AgentResult:
        """执行核心逻辑"""
        pass
    
    def can_handle(self, intent: str) -> bool:
        """判断是否能处理该意图"""
        return any(cap in intent.lower() for cap in self.capabilities)

# agents/email_agent.py
from typing import Any, Dict, List
import json
from .base import BaseAgent, AgentContext, AgentResult

class EmailAgent(BaseAgent):
    """
    单一职责：处理所有与邮件相关的任务
    
    包括：
    - 读取/搜索邮件
    - 撰写邮件
    - 发送邮件
    - 管理邮件标签/归档
    
    不包括：
    - 管理日程（交给 CalendarAgent）
    - 处理文件（交给 FileAgent）
    """
    
    def __init__(self, context: AgentContext, email_client):
        super().__init__("EmailAgent", context)
        self.email_client = email_client
    
    @property
    def description(self) -> str:
        return """
        我是邮件管理专家，负责处理所有邮件相关任务：
        - 读取收件箱和特定邮件
        - 搜索历史邮件
        - 撰写和发送邮件
        - 管理邮件标签和归档
        """
    
    @property
    def capabilities(self) -> list:
        return ["email", "mail", "inbox", "send", "compose"]
    
    async def execute(self, intent: str, params: Dict[str, Any]) -> AgentResult:
        """
        根据意图路由到具体方法
        """
        try:
            action = self._classify_intent(intent)
            
            if action == "read":
                return await self._read_emails(params)
            elif action == "search":
                return await self._search_emails(params)
            elif action == "compose":
                return await self._compose_email(params)
            elif action == "send":
                return await self._send_email(params)
            elif action == "archive":
                return await self._archive_email(params)
            else:
                return AgentResult(
                    success=False,
                    data=None,
                    error=f"Unknown email action: {action}"
                )
        except Exception as e:
            return AgentResult(success=False, data=None, error=str(e))
    
    def _classify_intent(self, intent: str) -> str:
        """将自然语言意图分类为具体动作"""
        intent_lower = intent.lower()
        
        if any(w in intent_lower for w in ["read", "check", "open", "查看", "读取"]):
            return "read"
        elif any(w in intent_lower for w in ["search", "find", "look for", "搜索", "查找"]):
            return "search"
        elif any(w in intent_lower for w in ["write", "compose", "draft", "撰写", "写信"]):
            return "compose"
        elif any(w in intent_lower for w in ["send", "发送"]):
            return "send"
        elif any(w in intent_lower for w in ["archive", "归档", "存档"]):
            return "archive"
        return "unknown"
    
    async def _read_emails(self, params: Dict) -> AgentResult:
        """读取邮件"""
        limit = params.get("limit", 10)
        emails = await self.email_client.get_inbox(limit=limit)
        
        summary = self._summarize_emails(emails)
        return AgentResult(success=True, data={
            "emails": emails,
            "summary": summary
        })
    
    async def _search_emails(self, params: Dict) -> AgentResult:
        """搜索邮件"""
        query = params.get("query", "")
        emails = await self.email_client.search(query)
        
        return AgentResult(success=True, data={
            "query": query,
            "results": emails,
            "count": len(emails)
        })
    
    async def _compose_email(self, params: Dict) -> AgentResult:
        """撰写邮件（不发送）"""
        to = params.get("to")
        subject = params.get("subject", "")
        body = params.get("body", "")
        
        # 这里可以接入 LLM 来优化邮件内容
        draft = {
            "to": to,
            "subject": subject,
            "body": body,
            "draft_id": f"draft_{hash(body) % 10000}"
        }
        
        return AgentResult(success=True, data={
            "draft": draft,
            "ready_to_send": bool(to and subject and body)
        })
    
    async def _send_email(self, params: Dict) -> AgentResult:
        """发送邮件"""
        draft_id = params.get("draft_id")
        
        if draft_id:
            # 从草稿发送
            result = await self.email_client.send_draft(draft_id)
        else:
            # 直接发送
            result = await self.email_client.send(
                to=params.get("to"),
                subject=params.get("subject"),
                body=params.get("body")
            )
        
        return AgentResult(success=True, data={"sent": result})
    
    async def _archive_email(self, params: Dict) -> AgentResult:
        """归档邮件"""
        email_id = params.get("email_id")
        await self.email_client.archive(email_id)
        
        return AgentResult(success=True, data={"archived": email_id})
    
    def _summarize_emails(self, emails: List[Dict]) -> str:
        """生成邮件摘要"""
        unread = sum(1 for e in emails if not e.get("read", True))
        return f"共 {len(emails)} 封邮件，其中 {unread} 封未读"

# agents/calendar_agent.py
from datetime import datetime, timedelta
from typing import Any, Dict
from .base import BaseAgent, AgentContext, AgentResult

class CalendarAgent(BaseAgent):
    """
    单一职责：处理所有与日程相关的任务
    
    包括：
    - 查询空闲时间
    - 创建/修改/删除会议
    - 处理会议冲突
    - 发送会议邀请
    """
    
    def __init__(self, context: AgentContext, calendar_client):
        super().__init__("CalendarAgent", context)
        self.calendar_client = calendar_client
    
    @property
    def description(self) -> str:
        return """
        我是日程管理专家，负责处理所有日程相关任务：
        - 查询空闲时间段
        - 创建、修改、取消会议
        - 处理日程冲突
        - 发送会议邀请
        """
    
    @property
    def capabilities(self) -> list:
        return ["calendar", "schedule", "meeting", "event", "time", "日程", "会议", "约会"]
    
    async def execute(self, intent: str, params: Dict[str, Any]) -> AgentResult:
        action = self._classify_intent(intent)
        
        handlers = {
            "check_availability": self._check_availability,
            "create_event": self._create_event,
            "modify_event": self._modify_event,
            "delete_event": self._delete_event,
            "list_events": self._list_events,
        }
        
        handler = handlers.get(action)
        if handler:
            return await handler(params)
        
        return AgentResult(success=False, data=None, error=f"Unknown action: {action}")
    
    def _classify_intent(self, intent: str) -> str:
        intent_lower = intent.lower()
        
        if any(w in intent_lower for w in ["free", "available", "busy", "空闲", "有空"]):
            return "check_availability"
        elif any(w in intent_lower for w in ["create", "schedule", "book", "创建", "安排"]):
            return "create_event"
        elif any(w in intent_lower for w in ["modify", "reschedule", "change", "修改", "改期"]):
            return "modify_event"
        elif any(w in intent_lower for w in ["delete", "cancel", "删除", "取消"]):
            return "delete_event"
        elif any(w in intent_lower for w in ["list", "show", "查看", "列出"]):
            return "list_events"
        return "unknown"
    
    async def _check_availability(self, params: Dict) -> AgentResult:
        """检查空闲时间"""
        date = params.get("date", datetime.now())
        duration_minutes = params.get("duration", 60)
        
        events = await self.calendar_client.get_events(date)
        free_slots = self._find_free_slots(events, duration_minutes)
        
        return AgentResult(success=True, data={
            "date": date,
            "free_slots": free_slots,
            "requested_duration": duration_minutes
        })
    
    async def _create_event(self, params: Dict) -> AgentResult:
        """创建会议"""
        event = {
            "title": params.get("title"),
            "start_time": params.get("start_time"),
            "end_time": params.get("end_time"),
            "attendees": params.get("attendees", []),
            "location": params.get("location"),
            "description": params.get("description")
        }
        
        # 检查冲突
        conflicts = await self._check_conflicts(event)
        if conflicts:
            return AgentResult(
                success=False,
                data={"conflicts": conflicts},
                error="Time slot conflicts detected"
            )
        
        created = await self.calendar_client.create_event(event)
        return AgentResult(success=True, data={"event": created})
    
    def _find_free_slots(self, events: list, duration: int) -> list:
        """从已有事件中找到空闲时间段"""
        # 实现空闲时间查找算法
        pass
    
    async def _check_conflicts(self, event: Dict) -> list:
        """检查时间冲突"""
        existing = await self.calendar_client.get_events(event["start_time"])
        conflicts = []
        for e in existing:
            if self._time_overlaps(e, event):
                conflicts.append(e)
        return conflicts
    
    def _time_overlaps(self, event1: Dict, event2: Dict) -> bool:
        """判断两个事件是否时间重叠"""
        start1 = event1["start_time"]
        end1 = event1["end_time"]
        start2 = event2["start_time"]
        end2 = event2["end_time"]
        return start1 < end2 and start2 < end1

# agents/orchestrator.py
from typing import List, Dict, Any
from .base import BaseAgent, AgentContext, AgentResult

class Orchestrator:
    """
    编排器：负责协调多个单一职责的 Agent。
    
    编排器本身也遵循 SRP：
    - 不负责具体业务逻辑
    - 只负责：意图识别、Agent 选择、结果聚合
    """
    
    def __init__(self, context: AgentContext):
        self.context = context
        self.agents: List[BaseAgent] = []
        self.execution_history: List[Dict] = []
    
    def register_agent(self, agent: BaseAgent):
        """注册 Agent"""
        self.agents.append(agent)
    
    async def process(self, user_input: str) -> AgentResult:
        """
        处理用户输入，选择合适的 Agent 执行
        """
        # 1. 意图识别
        intent = self._parse_intent(user_input)
        
        # 2. 选择合适的 Agent
        selected_agents = self._select_agents(intent)
        
        if not selected_agents:
            return AgentResult(
                success=False,
                data=None,
                error=f"No agent can handle intent: {intent['action']}"
            )
        
        # 3. 执行（简单场景：只选一个最合适的）
        if len(selected_agents) == 1:
            agent = selected_agents[0]
            result = await agent.execute(intent["action"], intent["params"])
            
            self.execution_history.append({
                "input": user_input,
                "agent": agent.name,
                "result": result
            })
            
            return result
        
        # 4. 复杂场景：需要多个 Agent 协作
        return await self._coordinate_agents(selected_agents, intent)
    
    def _parse_intent(self, user_input: str) -> Dict[str, Any]:
        """
        解析用户意图
        
        在实际系统中，这里可能使用 LLM 进行意图识别
        """
        # 简化版：关键词匹配
        intent = {"action": user_input, "params": {}}
        
        # 提取参数（简化版）
        if "明天" in user_input:
            intent["params"]["date"] = "tomorrow"
        if "10点" in user_input:
            intent["params"]["time"] = "10:00"
        
        return intent
    
    def _select_agents(self, intent: Dict) -> List[BaseAgent]:
        """选择能处理该意图的 Agent"""
        action = intent["action"].lower()
        
        candidates = []
        for agent in self.agents:
            if agent.can_handle(action):
                candidates.append(agent)
        
        # 按匹配度排序（简化版：按 capabilities 匹配数量）
        candidates.sort(
            key=lambda a: sum(1 for c in a.capabilities if c in action),
            reverse=True
        )
        
        return candidates
    
    async def _coordinate_agents(self, agents: List[BaseAgent], intent: Dict) -> AgentResult:
        """
        协调多个 Agent 完成复杂任务
        
        示例："安排一个与客户的会议，并发送确认邮件"
        
        这需要：
        1. CalendarAgent - 安排会议
        2. EmailAgent - 发送确认邮件
        """
        results = []
        
        # 按依赖顺序执行
        for agent in agents:
            result = await agent.execute(intent["action"], intent["params"])
            results.append({"agent": agent.name, "result": result})
            
            if not result.success:
                # 失败时回滚或报错
                return AgentResult(
                    success=False,
                    data={"partial_results": results},
                    error=f"Agent {agent.name} failed: {result.error}"
                )
        
        return AgentResult(success=True, data={"results": results})

# main.py
import asyncio
from agents.base import AgentContext
from agents.email_agent import EmailAgent
from agents.calendar_agent import CalendarAgent
from agents.orchestrator import Orchestrator
from tools.email_client import EmailClient
from tools.calendar_client import CalendarClient

async def main():
    # 创建上下文
    context = AgentContext(
        user_id="user_123",
        session_id="session_456",
        metadata={}
    )
    
    # 创建工具客户端
    email_client = EmailClient()
    calendar_client = CalendarClient()
    
    # 创建单一职责的 Agent
    email_agent = EmailAgent(context, email_client)
    calendar_agent = CalendarAgent(context, calendar_client)
    
    # 创建编排器并注册 Agent
    orchestrator = Orchestrator(context)
    orchestrator.register_agent(email_agent)
    orchestrator.register_agent(calendar_agent)
    
    # 处理用户请求
    
    # 场景 1：检查邮件（EmailAgent 处理）
    result1 = await orchestrator.process("帮我查看最近的邮件")
    print(f"邮件查询结果: {result1.data}")
    
    # 场景 2：查看日程（CalendarAgent 处理）
    result2 = await orchestrator.process("明天有什么会议")
    print(f"日程查询结果: {result2.data}")
    
    # 场景 3：复杂场景（需要多个 Agent 协作）
    # 编排器识别出需要两个 Agent，协调它们完成
    result3 = await orchestrator.process(
        "明天下午 3 点安排一个团队会议，然后给所有人发邮件通知"
    )
    print(f"复杂任务结果: {result3.data}")

if __name__ == "__main__":
    asyncio.run(main())