async def process_message(self, message: str, session_key: str) -> str:
    """
    处理用户消息的核心方法
    
    这是 AI 代理的"大脑"，负责：
    1. 构建上下文（加载历史对话）
    2. 调用 LLM 获取响应
    3. 执行工具调用（如果需要）
    4. 返回最终结果
    """
    # 第一步：构建上下文
    # 把历史对话、记忆信息组合成 LLM 能理解的格式
    messages = await self._build_context(session_key)
    
    # 添加用户消息
    messages.append({"role": "user", "content": message})
    
    # 第二步：调用 LLM
    # 让 AI 理解用户意图并决定如何响应
    response = await self.provider.chat(
        messages=messages,
        tools=self._get_tool_definitions(),
        model=self.model
    )
    
    # 第三步：处理工具调用
    # 如果 AI 决定要使用工具（比如查天气），执行它
    while response.has_tool_calls:
        # 执行所有工具调用
        tool_results = await self._execute_tools(response.tool_calls)
        
        # 把工具结果发回给 AI
        messages.append(response.message)
        messages.extend(tool_results)
        
        # 让 AI 根据工具结果生成最终回复
        response = await self.provider.chat(
            messages=messages,
            tools=self._get_tool_definitions(),
            model=self.model
        )
    
    # 第四步：保存对话并返回结果
    await self._save_message(session_key, "assistant", response.content)
    return response.content

class BaseTool:
    """
    所有工具的基类
    
    每个工具都需要：
    1. name: 工具名称（AI 用这个名字调用工具）
    2. description: 工具描述（告诉 AI 这个工具能做什么）
    3. parameters: 参数定义（告诉 AI 需要传什么参数）
    4. execute: 执行方法（实际干活的代码）
    """
    
    @property
    def name(self) -> str:
        """工具名称"""
        raise NotImplementedError
    
    @property
    def description(self) -> str:
        """工具描述"""
        raise NotImplementedError
    
    @property
    def parameters(self) -> dict:
        """
        参数定义（JSON Schema 格式）
        
        例如：
        {
            "type": "object",
            "properties": {
                "file_path": {
                    "type": "string",
                    "description": "要读取的文件路径"
                }
            },
            "required": ["file_path"]
        }
        """
        return {}
    
    async def execute(self, **kwargs) -> str:
        """
        执行工具
        
        参数：kwargs - AI 传递的参数
        返回：工具执行结果（字符串形式）
        """
        raise NotImplementedError

class ReadFileTool(BaseTool):
    """读取文件内容的工具"""
    
    @property
    def name(self) -> str:
        return "read_file"
    
    @property
    def description(self) -> str:
        return "读取指定文件的内容"
    
    @property
    def parameters(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "file_path": {
                    "type": "string",
                    "description": "要读取的文件路径"
                }
            },
            "required": ["file_path"]
        }
    
    async def execute(self, file_path: str) -> str:
        """执行文件读取"""
        try:
            # 安全检查：确保路径在工作区内
            if not self._is_safe_path(file_path):
                return "错误：不能访问工作区外的文件"
            
            # 读取文件内容
            with open(file_path, 'r', encoding='utf-8') as f:
                content = f.read()
            
            return f"文件内容：\n{content}"
        except Exception as e:
            return f"读取失败：{str(e)}"

class MessageBus:
    """
    消息总线：连接各个组件的"邮局"
    
    工作原理：
    1. 渠道（如 Telegram）收到用户消息 → 发布到入站队列
    2. 代理引擎从入站队列取消息 → 处理 → 发布到出站队列
    3. 渠道从出站队列取消息 → 发送给用户
    """
    
    def __init__(self):
        # 入站消息队列（用户 → AI）
        self._inbound = asyncio.Queue()
        # 出站消息队列（AI → 用户）
        self._outbound = asyncio.Queue()
    
    async def publish_inbound(self, message: InboundMessage):
        """发布入站消息（用户发给 AI）"""
        await self._inbound.put(message)
    
    async def consume_inbound(self) -> InboundMessage:
        """消费入站消息（AI 接收用户消息）"""
        return await self._inbound.get()
    
    async def publish_outbound(self, message: OutboundMessage):
        """发布出站消息（AI 发给用户）"""
        await self._outbound.put(message)
    
    async def consume_outbound(self) -> OutboundMessage:
        """消费出站消息（渠道发送给用户）"""
        return await self._outbound.get()