SOLID 原则的 AI 时代重构：从面向对象到 Agent 协作

# 传统代码：确定性
class Calculator:
    def add(self, a: int, b: int) -> int:
        return a + b  # 永远确定

# Agent：概率性
class ResearchAgent:
    async def research(self, topic: str) -> str:
        # 每次调用结果可能不同
        # 可能调用搜索引擎、数据库、API
        # 执行时间不确定
        return await self.llm.complete(f"Research: {topic}")

# 传统：封装状态
class BankAccount:
    def __init__(self):
        self._balance = 0  # 封装在对象内部

# Agent：复杂的上下文管理
class CustomerServiceAgent:
    def __init__(self):
        self.system_prompt = "You are a helpful assistant..."
        self.conversation_history = []  # 需要管理 token 预算
        self.long_term_memory = MemoryStore()  # 向量数据库
        self.current_context = {}  # 工作记忆

class DataAnalyzer(Protocol):
    def analyze(self, data: DataFrame) -> AnalysisResult: ...

@dataclass
class AnalysisIntent:
    goal: str  # "分析 Q3 销售趋势"
    constraints: List[str]  # ["使用同比数据", "排除异常值"]
    output_format: str  # "Markdown 报告"
    tools_available: List[str]  # ["sql_query", "chart_generator"]

# ❌ 违反 SCP - 上帝 Agent
class SuperAgent:
    """试图做所有事情的 Agent"""
    async def handle(self, query: str):
        # 可能处理：SQL查询、代码编写、客户投诉、图像生成...
        return await self.llm.complete(query)

# ✅ 遵循 SCP - 专业化 Agent
@dataclass
class CapabilityContract:
    name: str
    description: str
    input_schema: dict
    output_schema: dict
    tools_required: List[str]
    constraints: List[str]

class DataQueryAgent:
    """专精于数据查询的 Agent"""
    
    CAPABILITY = CapabilityContract(
        name="data_query",
        description="将自然语言转换为 SQL 查询并执行",
        input_schema={
            "query": "自然语言问题",
            "context": "可选的业务上下文"
        },
        output_schema={
            "sql": "生成的 SQL",
            "results": "查询结果",
            "explanation": "结果解释"
        },
        tools_required=["sql_executor", "schema_inspector"],
        constraints=["只读操作", "最大返回 1000 行"]
    )
    
    async def execute(self, intent: QueryIntent) -> QueryResult:
        # 只处理数据查询，其他请求交给 Router
        pass

# ❌ 违反 OCP-P - 硬编码行为
class SupportAgent:
    def __init__(self):
        self.system_prompt = """
        You are a customer support agent.
        Always be polite and professional.
        Refund policy: 30 days with receipt.
        """  # 硬编码，修改需要改代码

# ✅ 遵循 OCP-P - 模板化 + 可扩展

from jinja2 import Template

class PromptTemplate:
    """可扩展的 Prompt 模板系统"""
    
    BASE_TEMPLATE = """
    You are a {{ role }} agent.
    {% block personality %}
    Always be polite and professional.
    {% endblock %}
    
    {% block policies %}
    Refund policy: {{ refund_policy }}
    {% endblock %}
    
    {% block tools %}
    Available tools: {{ tools | join(', ') }}
    {% endblock %}
    """
    
    def __init__(self, variables: dict):
        self.template = Template(self.BASE_TEMPLATE)
        self.variables = variables
    
    def render(self, context: dict = None) -> str:
        return self.template.render(**self.variables, **(context or {}))

# 扩展而不修改
class PremiumSupportPrompt(PromptTemplate):
    """VIP 客户支持 - 通过模板继承扩展"""
    
    BASE_TEMPLATE = """
    {% extends 'base' %}
    
    {% block personality %}
    You are a premium support specialist. 
    Be extra attentive and proactive.
    Offer solutions before being asked.
    {% endblock %}
    
    {% block policies %}
    Refund policy: {{ refund_policy }}
    VIP perk: Priority processing, no questions asked returns within 60 days.
    {% endblock %}
    """

# 运行时动态扩展
async def create_agent_with_behavior(behavior_profile: str):
    """根据配置动态加载 Prompt 模板"""
    template = await load_template(f"behaviors/{behavior_profile}.j2")
    return SupportAgent(prompt_template=template)

# ❌ 违反 LAP - 黑盒输出
class BlackBoxAgent:
    async def answer(self, question: str) -> str:
        # 不知道 Agent 如何得出这个答案
        return await self.llm.complete(question)

# ✅ 遵循 LAP - 透明推理
from typing import Literal
from pydantic import BaseModel

class ReasoningStep(BaseModel):
    step_number: int
    thought: str
    action: Literal["think", "search", "calculate", "query"]
    observation: str

class TransparentResponse(BaseModel):
    reasoning_chain: List[ReasoningStep]
    confidence_score: float
    final_answer: str
    sources_used: List[str]
    uncertainty_acknowledged: bool

class TransparentAgent:
    """遵循忠实表达原则的 Agent"""
    
    async def answer(self, question: str) -> TransparentResponse:
        reasoning = []
        
        # Step 1: 分析问题
        analysis = await self.llm.think(f"Analyze: {question}")
        reasoning.append(ReasoningStep(
            step_number=1,
            thought=analysis,
            action="think",
            observation="Question categorized as technical"
        ))
        
        # Step 2: 搜索相关信息
        search_results = await self.tools.search(question)
        reasoning.append(ReasoningStep(
            step_number=2,
            thought="Need to verify facts",
            action="search",
            observation=f"Found {len(search_results)} relevant documents"
        ))
        
        # Step 3: 综合答案
        final = await self.llm.synthesize(
            question=question,
            context=search_results,
            reasoning=reasoning
        )
        
        return TransparentResponse(
            reasoning_chain=reasoning,
            confidence_score=self._calculate_confidence(reasoning),
            final_answer=final,
            sources_used=[r.url for r in search_results],
            uncertainty_acknowledged=final.contains("uncertain") or final.contains("not sure")
        )

from enum import Enum
from dataclasses import dataclass
from typing import Optional

class IntentType(Enum):
    DATA_QUERY = "data_query"
    CODE_GENERATION = "code_generation"
    DOCUMENT_ANALYSIS = "document_analysis"
    CONVERSATION = "conversation"
    TASK_ORCHESTRATION = "task_orchestration"

@dataclass
class Intent:
    type: IntentType
    confidence: float
    entities: dict
    original_query: str
    requires_tools: List[str]

class IntentRouter:
    """遵循意图隔离原则的路由器"""
    
    def __init__(self):
        self.agents: Dict[IntentType, Agent] = {
            IntentType.DATA_QUERY: DataQueryAgent(),
            IntentType.CODE_GENERATION: CodeGenAgent(),
            IntentType.DOCUMENT_ANALYSIS: DocumentAgent(),
            IntentType.CONVERSATION: ChatAgent(),
            IntentType.TASK_ORCHESTRATION: OrchestratorAgent(),
        }
    
    async def route(self, user_query: str) -> Intent:
        """将用户查询分解为明确的 Intent"""
        
        # 使用 LLM 进行意图识别
        classification = await self.llm.classify(
            query=user_query,
            intents=[t.value for t in IntentType]
        )
        
        # 如果是复合意图，进一步分解
        if classification["is_composite"]:
            sub_intents = await self._decompose(user_query)
            return Intent(
                type=IntentType.TASK_ORCHESTRATION,
                confidence=0.9,
                entities={"sub_intents": sub_intents},
                original_query=user_query,
                requires_tools=["workflow_engine"]
            )
        
        return Intent(
            type=IntentType(classification["intent"]),
            confidence=classification["confidence"],
            entities=classification["entities"],
            original_query=user_query,
            requires_tools=classification["tools"]
        )
    
    async def execute(self, user_query: str):
        intent = await self.route(user_query)
        
        # 将请求路由到专门的 Agent
        agent = self.agents.get(intent.type)
        if not agent:
            raise UnknownIntentError(f"No agent for intent: {intent.type}")
        
        # 检查能力匹配
        if not self._capability_match(agent, intent):
            raise CapabilityMismatchError(
                f"Agent {agent.__class__.__name__} cannot handle {intent.requires_tools}"
            )
        
        return await agent.execute(intent)

# 使用示例
async def main():
    router = IntentRouter()
    
    # 复合请求会被自动分解
    result = await router.execute(
        "查询上季度销售数据，生成可视化图表，并写一份分析报告"
    )
    # 路由器会：
    # 1. 识别出 DATA_QUERY + DOCUMENT_ANALYSIS 复合意图
    # 2. 交给 OrchestratorAgent 协调执行
    # 3. Orchestrator 依次调用 DataQueryAgent -> ChartAgent -> DocumentAgent

from abc import ABC, abstractmethod
from typing import AsyncIterator

# ========== 抽象层 ==========

class LLMCapability(ABC):
    """LLM 能力抽象"""
    
    @abstractmethod
    async def complete(self, prompt: str, context: Context) -> str:
        """完成文本生成"""
        pass
    
    @abstractmethod
    async def complete_structured(self, prompt: str, output_schema: dict) -> dict:
        """生成结构化输出"""
        pass
    
    @abstractmethod
    def stream(self, prompt: str) -> AsyncIterator[str]:
        """流式生成"""
        pass

class ToolCapability(ABC):
    """工具能力抽象"""
    
    @property
    @abstractmethod
    def name(self) -> str:
        pass
    
    @property
    @abstractmethod
    def description(self) -> str:
        pass
    
    @abstractmethod
    async def execute(self, parameters: dict) -> ToolResult:
        pass

class MemoryCapability(ABC):
    """记忆能力抽象"""
    
    @abstractmethod
    async def store(self, key: str, value: any, metadata: dict = None):
        """存储记忆"""
        pass
    
    @abstractmethod
    async def retrieve(self, query: str, limit: int = 5) -> List[Memory]:
        """检索相关记忆"""
        pass

# ========== 具体实现 ==========

class OpenAILLM(LLMCapability):
    """OpenAI 实现"""
    def __init__(self, model: str = "gpt-4"):
        self.model = model
    
    async def complete(self, prompt: str, context: Context) -> str:
        return await openai.chat.completions.create(
            model=self.model,
            messages=self._build_messages(prompt, context)
        )
    
    async def complete_structured(self, prompt: str, output_schema: dict) -> dict:
        return await openai.chat.completions.create(
            model=self.model,
            messages=[{"role": "user", "content": prompt}],
            response_format={"type": "json_object"}
        )

class AnthropicLLM(LLMCapability):
    """Anthropic 实现 - 可无缝替换"""
    def __init__(self, model: str = "claude-3-sonnet"):
        self.model = model
    
    async def complete(self, prompt: str, context: Context) -> str:
        return await anthropic.messages.create(
            model=self.model,
            messages=self._build_messages(prompt, context)
        )

class SQLTool(ToolCapability):
    """SQL 查询工具"""
    
    @property
    def name(self) -> str:
        return "sql_executor"
    
    @property
    def description(self) -> str:
        return "执行 SQL 查询并返回结果"
    
    async def execute(self, parameters: dict) -> ToolResult:
        query = parameters["query"]
        # 执行查询...
        return ToolResult(success=True, data=results)

class VectorMemory(MemoryCapability):
    """向量数据库存储"""
    
    async def store(self, key: str, value: any, metadata: dict = None):
        embedding = await self.embed(value)
        await self.db.upsert(key, embedding, value, metadata)
    
    async def retrieve(self, query: str, limit: int = 5) -> List[Memory]:
        query_embedding = await self.embed(query)
        return await self.db.search(query_embedding, limit)

# ========== 依赖抽象的 Agent ==========

class BusinessAnalystAgent:
    """
    遵循 D 原则的 Agent
    依赖抽象接口，而非具体实现
    """
    
    def __init__(
        self,
        llm: LLMCapability,  # 依赖抽象
        tools: List[ToolCapability],  # 依赖抽象
        memory: MemoryCapability,  # 依赖抽象
        config: AgentConfig
    ):
        self.llm = llm
        self.tools = {t.name: t for t in tools}
        self.memory = memory
        self.config = config
    
    async def analyze(self, request: AnalysisRequest) -> AnalysisResult:
        # 检索相关记忆
        relevant_memories = await self.memory.retrieve(request.topic)
        
        # 构建上下文
        context = self._build_context(request, relevant_memories)
        
        # 使用 LLM 进行分析
        analysis = await self.llm.complete_structured(
            prompt=self._build_analysis_prompt(request),
            output_schema=ANALYSIS_SCHEMA
        )
        
        # 执行必要的工具调用
        if analysis["requires_data"]:
            data = await self.tools["sql_executor"].execute(
                {"query": analysis["sql_query"]}
            )
            analysis["data"] = data
        
        # 存储结果到记忆
        await self.memory.store(
            key=f"analysis:{request.id}",
            value=analysis,
            metadata={"topic": request.topic, "timestamp": now()}
        )
        
        return AnalysisResult(**analysis)

# ========== 使用示例：灵活替换实现 ==========

# 配置 1：使用 OpenAI + PostgreSQL
agent_v1 = BusinessAnalystAgent(
    llm=OpenAILLM(model="gpt-4"),
    tools=[SQLTool(connection="postgresql://...")],
    memory=VectorMemory(db=PGVector(...)),
    config=AgentConfig()
)

# 配置 2：使用 Claude + 不同的工具集（无需修改 Agent 代码）
agent_v2 = BusinessAnalystAgent(
    llm=AnthropicLLM(model="claude-3-opus"),
    tools=[
        SQLTool(connection="snowflake://..."),
        ChartTool(renderer="matplotlib")
    ],
    memory=VectorMemory(db=ChromaDB(...)),
    config=AgentConfig()
)

# 配置 3：本地模型（隐私敏感场景）
agent_v3 = BusinessAnalystAgent(
    llm=LocalLLM(model_path="./models/llama-3-70b.gguf"),
    tools=[SQLTool(connection="sqlite:///:memory:")],
    memory=LocalVectorStore(path="./memory"),
    config=AgentConfig(offline_mode=True)
)

"""
智能客服系统 - 新 SOLID 原则实战示例
"""

from __future__ import annotations
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from enum import Enum, auto
from typing import Dict, List, Optional, Any, AsyncIterator, Protocol
from datetime import datetime
import json
from pydantic import BaseModel, Field

# ============================================================================
# 抽象层 (DIP - Dependency Inversion Principle)
# ============================================================================

class LLMProvider(ABC):
    """LLM 能力抽象"""
    
    @abstractmethod
    async def complete(self, messages: List[dict], **kwargs) -> str:
        pass
    
    @abstractmethod
    async def complete_structured(self, messages: List[dict], schema: dict) -> dict:
        pass

class ToolProvider(ABC):
    """工具能力抽象"""
    
    @property
    @abstractmethod
    def spec(self) -> ToolSpec:
        pass
    
    @abstractmethod
    async def execute(self, params: dict) -> ToolResult:
        pass

class MemoryProvider(ABC):
    """记忆能力抽象"""
    
    @abstractmethod
    async def store(self, session_id: str, entry: MemoryEntry):
        pass
    
    @abstractmethod
    async def retrieve(self, session_id: str, query: str, k: int = 3) -> List[MemoryEntry]:
        pass

# ============================================================================
# 领域模型
# ============================================================================

class IntentType(Enum):
    ORDER_QUERY = auto()
    REFUND_REQUEST = auto()
    TECH_SUPPORT = auto()
    PRODUCT_RECOMMENDATION = auto()
    GENERAL_INQUIRY = auto()

@dataclass
class Intent:
    type: IntentType
    confidence: float
    entities: Dict[str, Any]
    raw_query: str
    required_capabilities: List[str]

@dataclass
class ToolSpec:
    name: str
    description: str
    parameters: dict

@dataclass
class ToolResult:
    success: bool
    data: Any
    error: Optional[str] = None

@dataclass
class MemoryEntry:
    timestamp: datetime
    role: str
    content: str
    metadata: Dict[str, Any] = field(default_factory=dict)

@dataclass
class AgentResponse:
    content: str
    reasoning: Optional[str] = None  # LAP: 展示推理过程
    tool_calls: List[dict] = field(default_factory=list)
    confidence: float = 1.0

# ============================================================================
# 提示模板系统 (OCP-P: Open for Extension via Prompting)
# ============================================================================

class PromptTemplate:
    """可扩展的提示模板基类"""
    
    BASE_TEMPLATE = """You are a {{ role }} assistant.
    
Current Time: {{ current_time }}
Session ID: {{ session_id }}

{% if memories %}
Relevant context from previous interactions:
{% for mem in memories %}
- {{ mem.role }}: {{ mem.content }}
{% endfor %}
{% endif %}

{% if tools %}
Available tools:
{% for tool in tools %}
- {{ tool.name }}: {{ tool.description }}
{% endfor %}
{% endif %}

{% block instructions %}{% endblock %}

User Query: {{ query }}

Respond in a helpful and professional manner."""

    def __init__(self, role: str, instructions: str = ""):
        self.role = role
        self.instructions = instructions
        self.template = self.BASE_TEMPLATE
    
    def render(self, context: dict) -> str:
        from jinja2 import Template
        template = Template(self.template)
        return template.render(
            role=self.role,
            current_time=datetime.now().isoformat(),
            instructions=self.instructions,
            **context
        )

# 可扩展的模板
class PremiumSupportTemplate(PromptTemplate):
    """VIP 客户支持模板 - 通过继承扩展"""
    
    BASE_TEMPLATE = """You are a {{ role }} assistant for PREMIUM customers.
    
⚡ VIP Service Level: Priority Support
🎁 Special perks: Extended warranty, free returns, dedicated support

Current Time: {{ current_time }}
Session ID: {{ session_id }}

{% if memories %}
Relevant context from previous interactions:
{% for mem in memories %}
- {{ mem.role }}: {{ mem.content }}
{% endfor %}
{% endif %}

{% if tools %}
Available tools:
{% for tool in tools %}
- {{ tool.name }}: {{ tool.description }}
{% endfor %}
{% endif %}

User Query: {{ query }}

As a premium support specialist, go above and beyond. Anticipate needs and offer proactive solutions."""

# ============================================================================
# Agent 基类 (SCP: Single Capability Principle)
# ============================================================================

class CapabilityContract:
    """能力契约 - 明确 Agent 的能力边界"""
    
    def __init__(
        self,
        name: str,
        description: str,
        supported_intents: List[IntentType],
        required_tools: List[str],
        constraints: List[str]
    ):
        self.name = name
        self.description = description
        self.supported_intents = supported_intents
        self.required_tools = required_tools
        self.constraints = constraints

class Agent(ABC):
    """Agent 抽象基类"""
    
    capability: CapabilityContract
    
    def __init__(
        self,
        llm: LLMProvider,
        tools: Dict[str, ToolProvider],
        memory: MemoryProvider,
        prompt_template: PromptTemplate
    ):
        self.llm = llm
        self.tools = tools
        self.memory = memory
        self.prompt_template = prompt_template
    
    @abstractmethod
    async def can_handle(self, intent: Intent) -> bool:
        """检查是否能处理该意图"""
        pass
    
    @abstractmethod
    async def execute(self, intent: Intent, session_id: str) -> AgentResponse:
        """执行意图"""
        pass
    
    async def _build_context(self, intent: Intent, session_id: str) -> dict:
        """构建上下文，包含记忆"""
        memories = await self.memory.retrieve(session_id, intent.raw_query)
        tool_specs = [t.spec for t in self.tools.values()]
        
        return {
            "session_id": session_id,
            "query": intent.raw_query,
            "entities": intent.entities,
            "memories": memories,
            "tools": tool_specs
        }

# ============================================================================
# 具体 Agent 实现 (SCP: 每个 Agent 专注单一能力)
# ============================================================================

class OrderQueryAgent(Agent):
    """订单查询 Agent - 专精于订单相关查询"""
    
    capability = CapabilityContract(
        name="order_query",
        description="查询订单状态、物流信息、订单历史",
        supported_intents=[IntentType.ORDER_QUERY],
        required_tools=["order_api", "shipping_tracker"],
        constraints=["只读操作", "只能查询自己的订单"]
    )
    
    def __init__(self, llm, tools, memory, template=None):
        super().__init__(
            llm=llm,
            tools=tools,
            memory=memory,
            prompt_template=template or PromptTemplate(
                role="Order Management Specialist",
                instructions="""
                Help customers with their orders. You can:
                1. Check order status
                2. Track shipments
                3. View order history
                
                Always verify order numbers and protect customer privacy.
                """
            )
        )
    
    async def can_handle(self, intent: Intent) -> bool:
        return intent.type == IntentType.ORDER_QUERY
    
    async def execute(self, intent: Intent, session_id: str) -> AgentResponse:
        context = await self._build_context(intent, session_id)
        prompt = self.prompt_template.render(context)
        
        # LAP: 请求结构化输出包含推理过程
        response_schema = {
            "type": "object",
            "properties": {
                "reasoning": {"type": "string", "description": "Your thought process"},
                "needs_tool": {"type": "boolean"},
                "tool_name": {"type": "string"},
                "tool_params": {"type": "object"},
                "response": {"type": "string", "description": "Customer-facing response"},
                "confidence": {"type": "number", "minimum": 0, "maximum": 1}
            },
            "required": ["reasoning", "needs_tool", "response", "confidence"]
        }
        
        result = await self.llm.complete_structured(
            messages=[{"role": "user", "content": prompt}],
            schema=response_schema
        )
        
        # 如果需要工具调用
        if result.get("needs_tool") and result.get("tool_name") in self.tools:
            tool_result = await self.tools[result["tool_name"]].execute(
                result["tool_params"]
            )
            # 将工具结果加入上下文，再次调用 LLM
            context["tool_result"] = tool_result.data
            prompt = self.prompt_template.render(context)
            final = await self.llm.complete(
                messages=[{"role": "user", "content": prompt}]
            )
            result["response"] = final
        
        # 存储交互到记忆
        await self.memory.store(session_id, MemoryEntry(
            timestamp=datetime.now(),
            role="assistant",
            content=result["response"],
            metadata={"intent": "order_query", "confidence": result["confidence"]}
        ))
        
        return AgentResponse(
            content=result["response"],
            reasoning=result.get("reasoning"),  # LAP: 透明推理
            confidence=result["confidence"]
        )

class RefundAgent(Agent):
    """退款处理 Agent - 专精于退款相关流程"""
    
    capability = CapabilityContract(
        name="refund_processor",
        description="处理退款请求，检查退款资格",
        supported_intents=[IntentType.REFUND_REQUEST],
        required_tools=["order_api", "refund_processor", "payment_gateway"],
        constraints=["需要验证订单", "遵循退款政策", "需要确认身份"]
    )
    
    async def can_handle(self, intent: Intent) -> bool:
        return intent.type == IntentType.REFUND_REQUEST
    
    async def execute(self, intent: Intent, session_id: str) -> AgentResponse:
        # 实现退款处理逻辑
        context = await self._build_context(intent, session_id)
        
        # 首先检查退款资格
        order_id = intent.entities.get("order_id")
        eligibility = await self.tools["order_api"].execute({
            "action": "check_refund_eligibility",
            "order_id": order_id
        })
        
        if not eligibility.data["eligible"]:
            return AgentResponse(
                content=f"Sorry, this order is not eligible for refund. Reason: {eligibility.data['reason']}",
                confidence=1.0
            )
        
        # 处理退款
        # ... 实现逻辑
        
        return AgentResponse(
            content="Refund processed successfully. You should see the credit within 5-7 business days.",
            confidence=0.95
        )

# ============================================================================
# Intent Router (ISP: Intent Segregation Principle)
# ============================================================================

class IntentRouter:
    """意图路由器 - 将请求分解并路由到专门的 Agent"""
    
    def __init__(self, llm: LLMProvider):
        self.llm = llm
        self.agents: List[Agent] = []
    
    def register_agent(self, agent: Agent):
        """注册 Agent"""
        self.agents.append(agent)
    
    async def parse_intent(self, query: str) -> Intent:
        """解析用户意图"""
        
        intent_schema = {
            "type": "object",
            "properties": {
                "intent": {
                    "type": "string",
                    "enum": ["ORDER_QUERY", "REFUND_REQUEST", "TECH_SUPPORT", 
                            "PRODUCT_RECOMMENDATION", "GENERAL_INQUIRY"]
                },
                "confidence": {"type": "number", "minimum": 0, "maximum": 1},
                "entities": {"type": "object"},
                "is_composite": {"type": "boolean"},
                "sub_intents": {"type": "array"}
            },
            "required": ["intent", "confidence", "entities"]
        }
        
        result = await self.llm.complete_structured(
            messages=[{
                "role": "user",
                "content": f"""Analyze this customer service query and classify the intent.
                
Query: "{query}"

Available intents:
- ORDER_QUERY: Questions about existing orders, tracking, status
- REFUND_REQUEST: Requests to return items or get refunds
- TECH_SUPPORT: Technical issues, troubleshooting
- PRODUCT_RECOMMENDATION: Asking for product suggestions
- GENERAL_INQUIRY: General questions about store, policies, etc.
"""
            }],
            schema=intent_schema
        )
        
        intent_type = IntentType[result["intent"]]
        
        # 处理复合意图
        if result.get("is_composite"):
            return Intent(
                type=IntentType.GENERAL_INQUIRY,
                confidence=0.9,
                entities={"sub_intents": result.get("sub_intents", [])},
                raw_query=query,
                required_capabilities=["orchestration"]
            )
        
        return Intent(
            type=intent_type,
            confidence=result["confidence"],
            entities=result["entities"],
            raw_query=query,
            required_capabilities=[]
        )
    
    async def route(self, intent: Intent) -> Optional[Agent]:
        """将意图路由到合适的 Agent"""
        
        for agent in self.agents:
            if await agent.can_handle(intent):
                # 检查能力匹配
                missing_tools = [
                    tool for tool in agent.capability.required_tools
                    if tool not in agent.tools
                ]
                if missing_tools:
                    print(f"Warning: Agent {agent.capability.name} missing tools: {missing_tools}")
                    continue
                return agent
        
        return None
    
    async def handle(self, query: str, session_id: str) -> AgentResponse:
        """处理用户请求的主入口"""
        
        # 1. 解析意图 (ISP)
        intent = await self.parse_intent(query)
        
        if intent.confidence < 0.5:
            return AgentResponse(
                content="I'm not sure I understand. Could you rephrase your question?",
                confidence=0.3
            )
        
        # 2. 路由到合适的 Agent
        agent = await self.route(intent)
        
        if not agent:
            return AgentResponse(
                content="I'm sorry, I don't have the capability to handle that request yet.",
                confidence=0.5
            )
        
        # 3. 执行
        return await agent.execute(intent, session_id)

# ============================================================================
# 具体实现示例
# ============================================================================

class MockLLM(LLMProvider):
    """模拟 LLM 实现"""
    
    async def complete(self, messages: List[dict], **kwargs) -> str:
        # 实际实现会调用 OpenAI/Anthropic API
        return "Mock response"
    
    async def complete_structured(self, messages: List[dict], schema: dict) -> dict:
        # 模拟结构化输出
        return {
            "intent": "ORDER_QUERY",
            "confidence": 0.95,
            "entities": {"order_id": "12345"},
            "reasoning": "User is asking about their order",
            "needs_tool": True,
            "tool_name": "order_api",
            "tool_params": {"order_id": "12345"},
            "response": "Your order #12345 is currently being processed.",
            "confidence": 0.9
        }

class MockMemory(MemoryProvider):
    """模拟内存实现"""
    
    def __init__(self):
        self.data: Dict[str, List[MemoryEntry]] = {}
    
    async def store(self, session_id: str, entry: MemoryEntry):
        if session_id not in self.data:
            self.data[session_id] = []
        self.data[session_id].append(entry)
    
    async def retrieve(self, session_id: str, query: str, k: int = 3) -> List[MemoryEntry]:
        return self.data.get(session_id, [])[-k:]

class OrderAPITool(ToolProvider):
    """订单 API 工具"""
    
    @property
    def spec(self) -> ToolSpec:
        return ToolSpec(
            name="order_api",
            description="Query order information from the database",
            parameters={
                "type": "object",
                "properties": {
                    "action": {"type": "string", "enum": ["get_status", "get_history", "check_refund_eligibility"]},
                    "order_id": {"type": "string"}
                },
                "required": ["action", "order_id"]
            }
        )
    
    async def execute(self, params: dict) -> ToolResult:
        # 模拟 API 调用
        return ToolResult(
            success=True,
            data={"status": "processing", "estimated_delivery": "2024-03-20"}
        )

# ============================================================================
# 使用示例
# ============================================================================

async def main():
    """系统组装和使用示例"""
    
    # 1. 创建能力提供者 (DIP)
    llm = MockLLM()
    memory = MockMemory()
    
    # 2. 创建工具
    tools = {
        "order_api": OrderAPITool(),
    }
    
    # 3. 创建专业化 Agent (SCP)
    order_agent = OrderQueryAgent(llm, tools, memory)
    
    # 4. 创建路由器 (ISP)
    router = IntentRouter(llm)
    router.register_agent(order_agent)
    
    # 5. 处理请求
    response = await router.handle(
        query="Where is my order #12345?",
        session_id="session_001"
    )
    
    print(f"Response: {response.content}")
    print(f"Reasoning: {response.reasoning}")  # LAP: 展示推理
    print(f"Confidence: {response.confidence}")

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

# 不要这样做
def get_answer(question: str) -> str:
    # 试图强制确定性
    return llm.complete(question, temperature=0)  # 自欺欺人

# 而是这样
def get_answer(question: str) -> Answer:
    response = llm.complete(question)
    confidence = evaluate_confidence(response)
    
    if confidence < 0.7:
        return Answer(
            content="I'm not certain, but here's what I think...",
            confidence=confidence,
            needs_human_review=True
        )
    
    return Answer(content=response, confidence=confidence)

# Prompt 版本控制
PROMPT_REGISTRY = {
    "customer_support/v1": "You are a helpful assistant...",
    "customer_support/v2": "You are a premium support specialist...",  # A/B 测试
    "customer_support/v2.1": "...",  # 生产版本
}

# Prompt 测试
async def test_support_prompt():
    prompt = load_prompt("customer_support/v2.1")
    test_cases = load_test_cases("support_cases.yaml")
    
    for case in test_cases:
        result = await agent.handle(case.input)
        assert result.matches_expected(case.expected)

class ContextManager:
    """智能上下文管理"""
    
    def __init__(self, max_tokens: int = 8000):
        self.max_tokens = max_tokens
        self.working_memory = []  # 当前对话
        self.episodic_memory = []  # 近期相关
        self.semantic_memory = VectorStore()  # 长期知识
    
    async def prepare_context(self, query: str) -> str:
        # 1. 检索相关长期记忆
        relevant_facts = await self.semantic_memory.search(query, k=5)
        
        # 2. 总结工作记忆（如果太长）
        if self._token_count(self.working_memory) > self.max_tokens * 0.5:
            summary = await self._summarize(self.working_memory[:-5])
            self.working_memory = [summary] + self.working_memory[-5:]
        
        # 3. 组合上下文
        return self._format_context(relevant_facts, self.working_memory)

# 传统测试（不适用）
def test_calculator():
    assert calculator.add(2, 2) == 4  # 确定性

# AI 系统测试
async def test_agent_properties():
    results = []
    for case in TEST_CASES:
        response = await agent.handle(case.query)
        results.append({
            "relevant": await evaluate_relevance(response, case),
            "factual": await evaluate_factuality(response),
            "helpful": await evaluate_helpfulness(response),
            "safe": evaluate_safety(response)
        })
    
    # 统计属性
    assert mean(r["relevant"] for r in results) > 0.85
    assert mean(r["factual"] for r in results) > 0.90
    assert all(r["safe"] for r in results)  # 安全必须 100%