@agentunion/kite 1.3.2 → 1.5.0

package/extensions/services/proxy/evol/presenter/agentIdPresenter.py

@@ -0,0 +1,1031 @@
+"""
+agentIdPresenter.py - AgentID 上线统一管理模块
+
+【重要说明】
+本模块是 AgentID 上线后的统一入口点。
+无论在代码的哪个位置调用 agentId.online()，都必须在上线成功后调用本模块的 evol_agentId_online() 方法。
+
+【调用位置清单】（需要在以下位置的 agentId.online() 之后调用 evol_agentId_online）
+1. python_backend/evol/presenter/userPresenter.py:1726  - login() 用户登录
+2. python_backend/evol/presenter/userPresenter.py:1786  - load_aid() 加载AID
+3. python_backend/evol/presenter/userPresenter.py:1887  - quick_login() 快速登录
+4. python_backend/evol/presenter/agentPresenter.py:47   - set_aid() 设置AgentID
+5. python_backend/evol/server/claude_proxy_async.py:155 - full_rebuild_agentcp() 同步重建
+6. python_backend/evol/server/claude_proxy_async.py:217 - full_rebuild_agentcp() 新AID上线
+7. python_backend/evol/server/claude_proxy_async.py:333 - force_rebuild_agentcp() 异步重建
+8. python_backend/evol/server/claude_proxy_async.py:2089 - async_generate_handler() Session重试
+
+【使用示例】
+    from evol.presenter.agentIdPresenter import agentIdPresenter
+
+    # 在 agentId.online() 成功后调用
+    agentId.online()
+    if agentId.is_online_success:
+        agentIdPresenter.evol_agentId_online(agentId)
+
+【消息协议格式】
+
+AgentCP 原始消息格式（message.message 字段解析后）：
+[
+    {
+        "type": "content",                    # 固定为 "content"
+        "content": "{\"action\":\"rpc_call\",\"trace_id\":\"xxx\",...}"  # JSON 字符串
+    }
+]
+
+content 字段解析后的 RPC 请求格式：
+{
+    "action": "rpc_call",                # 动作类型，固定为 rpc_call
+    "trace_id": "uuid-xxx",              # 追踪ID，用于响应匹配
+    "presenter": "claudeCodePresenter",  # 目标 Presenter 名称
+    "method": "scan_logs",               # 要调用的方法名
+    "params": {                          # 方法参数（可选）
+        "use_cache": true,
+        "force_refresh": false
+    }
+}
+
+响应消息格式（发送时自动包装为 content 类型）：
+{
+    "action": "rpc_response",            # 响应类型
+    "trace_id": "uuid-xxx",              # 对应请求的追踪ID
+    "status": "success" | "error",       # 执行状态
+    "result": {...},                     # 成功时的返回结果
+    "error": "错误信息"                   # 失败时的错误信息
+}
+"""
+
+import asyncio
+import inspect
+import json
+import traceback
+import threading
+import uuid
+from typing import Optional, Callable, Awaitable, List, Dict, Any, Type, Iterator
+from agentcp import AgentID
+
+
+# ==================== 流管理器 ====================
+
+class StreamManager:
+    """
+    ACP 流管理器
+
+    负责创建和管理 ACP 流，用于将本地迭代器的数据推送到远程。
+
+    使用流程：
+    1. 调用 create_stream_for_iterator() 创建流
+    2. 返回 pull_url 给调用方
+    3. 后台任务将迭代器数据推送到 push_url
+    """
+
+    # 活跃的流任务: {stream_id: task_info}
+    _active_streams: Dict[str, Dict[str, Any]] = {}
+    _lock = threading.Lock()
+
+    @classmethod
+    async def create_stream_for_iterator(
+        cls,
+        agentId: 'AgentID',
+        session_id: str,
+        to_aid_list: list,
+        iterator: Iterator[dict],
+        content_type: str = "text/event-stream",
+        ref_msg_id: str = ""
+    ) -> Dict[str, Any]:
+        """
+        为迭代器创建 ACP 流
+
+        Args:
+            agentId: AgentID 实例
+            session_id: 会话 ID
+            to_aid_list: 目标 AID 列表
+            iterator: 数据迭代器
+            content_type: 内容类型
+            ref_msg_id: 引用消息 ID
+
+        Returns:
+            {
+                'success': True/False,
+                'pull_url': '拉取流的 URL',
+                'stream_id': '流 ID',
+                'error': '错误信息（如果失败）'
+            }
+        """
+        try:
+            # 1. 创建 ACP 流
+            stream_result = await agentId.create_stream(
+                session_id, to_aid_list, content_type, ref_msg_id
+            )
+            push_url, pull_url = stream_result
+
+            if push_url is None:
+                return {
+                    'success': False,
+                    'error': f"创建流失败: {pull_url}"
+                }
+
+            # 2. 生成流 ID
+            stream_id = str(uuid.uuid4())
+
+            # 3. 启动后台任务推送数据
+            task = asyncio.create_task(
+                cls._push_iterator_to_stream(
+                    agentId, session_id, push_url, iterator, stream_id, content_type
+                )
+            )
+
+            # 4. 记录活跃流
+            with cls._lock:
+                cls._active_streams[stream_id] = {
+                    'task': task,
+                    'push_url': push_url,
+                    'pull_url': pull_url,
+                    'session_id': session_id,
+                    'status': 'running'
+                }
+
+            print(f"✅ [StreamManager] 流创建成功: stream_id={stream_id}")
+            print(f"    pull_url: {pull_url}")
+
+            return {
+                'success': True,
+                'pull_url': pull_url,
+                'stream_id': stream_id
+            }
+
+        except Exception as e:
+            print(f"❌ [StreamManager] 创建流失败: {e}")
+            traceback.print_exc()
+            return {
+                'success': False,
+                'error': str(e)
+            }
+
+    @classmethod
+    async def _push_iterator_to_stream(
+        cls,
+        agentId: 'AgentID',
+        session_id: str,
+        push_url: str,
+        iterator: Iterator[dict],
+        stream_id: str,
+        content_type: str
+    ):
+        """
+        后台任务：将迭代器数据推送到流
+
+        Args:
+            agentId: AgentID 实例
+            session_id: 会话 ID
+            push_url: 推送 URL
+            iterator: 数据迭代器
+            stream_id: 流 ID
+            content_type: 内容类型
+        """
+        try:
+            print(f"🚀 [StreamManager] 开始推送数据: stream_id={stream_id}")
+
+            chunk_count = 0
+
+            # 使用线程池处理同步迭代器，避免阻塞事件循环
+            def process_iterator():
+                nonlocal chunk_count
+                for chunk in iterator:
+                    # 将 chunk 转换为 JSON 字符串
+                    if isinstance(chunk, dict):
+                        chunk_str = json.dumps(chunk, ensure_ascii=False)
+                    elif isinstance(chunk, str):
+                        chunk_str = chunk
+                    else:
+                        chunk_str = str(chunk)
+
+                    # 推送到流
+                    agentId.send_chunk_to_stream(session_id, push_url, chunk_str, type=content_type)
+                    chunk_count += 1
+
+            # 在线程池中执行同步迭代器
+            await asyncio.to_thread(process_iterator)
+
+            print(f"✅ [StreamManager] 数据推送完成: stream_id={stream_id}, chunks={chunk_count}")
+
+        except Exception as e:
+            print(f"❌ [StreamManager] 推送数据失败: stream_id={stream_id}, error={e}")
+            traceback.print_exc()
+
+            # 发送错误事件
+            try:
+                error_chunk = json.dumps({
+                    'type': 'error',
+                    'error': str(e)
+                }, ensure_ascii=False)
+                agentId.send_chunk_to_stream(session_id, push_url, error_chunk, type=content_type)
+            except:
+                pass
+
+        finally:
+            # 关闭流
+            try:
+                agentId.close_stream(session_id, push_url)
+                print(f"🔚 [StreamManager] 流已关闭: stream_id={stream_id}")
+            except Exception as e:
+                print(f"⚠️ [StreamManager] 关闭流失败: {e}")
+
+            # 更新状态
+            with cls._lock:
+                if stream_id in cls._active_streams:
+                    cls._active_streams[stream_id]['status'] = 'completed'
+
+    @classmethod
+    def get_stream_status(cls, stream_id: str) -> Optional[Dict[str, Any]]:
+        """获取流状态"""
+        with cls._lock:
+            return cls._active_streams.get(stream_id)
+
+    @classmethod
+    def cancel_stream(cls, stream_id: str) -> bool:
+        """取消流"""
+        with cls._lock:
+            stream_info = cls._active_streams.get(stream_id)
+            if stream_info and stream_info.get('task'):
+                stream_info['task'].cancel()
+                stream_info['status'] = 'cancelled'
+                return True
+            return False
+
+    @classmethod
+    def cleanup_completed_streams(cls):
+        """清理已完成的流"""
+        with cls._lock:
+            completed = [
+                sid for sid, info in cls._active_streams.items()
+                if info.get('status') in ('completed', 'cancelled')
+            ]
+            for sid in completed:
+                del cls._active_streams[sid]
+            if completed:
+                print(f"🧹 [StreamManager] 清理了 {len(completed)} 个已完成的流")
+
+
+# ==================== Presenter 注册表 ====================
+
+class PresenterRegistry:
+    """
+    Presenter 注册表
+
+    管理所有可被远程调用的 Presenter 类。
+    支持动态注册和方法白名单控制。
+    """
+
+    # 已注册的 Presenter 映射: {presenter_name: presenter_class}
+    _presenters: Dict[str, Type] = {}
+
+    # 方法白名单: {presenter_name: [allowed_methods]} 或 {presenter_name: "*"} 表示全部允许
+    _method_whitelist: Dict[str, Any] = {}
+
+    @classmethod
+    def register(cls, presenter_class: Type, name: str = None, allowed_methods: List[str] = None):
+        """
+        注册一个 Presenter
+
+        Args:
+            presenter_class: Presenter 类
+            name: 注册名称（可选，默认使用类名）
+            allowed_methods: 允许调用的方法列表（可选，默认全部允许）
+
+        Usage:
+            # 注册并允许所有方法
+            PresenterRegistry.register(claudeCodePresenter)
+
+            # 注册并只允许特定方法
+            PresenterRegistry.register(claudeCodePresenter, allowed_methods=['scan_logs', 'get_project_detail'])
+
+            # 使用自定义名称
+            PresenterRegistry.register(MyPresenter, name='customName')
+        """
+        presenter_name = name or presenter_class.__name__
+        cls._presenters[presenter_name] = presenter_class
+
+        if allowed_methods is None:
+            cls._method_whitelist[presenter_name] = "*"  # 允许所有方法
+        else:
+            cls._method_whitelist[presenter_name] = allowed_methods
+
+        print(f"📝 [PresenterRegistry] 注册 Presenter: {presenter_name}")
+
+    @classmethod
+    def unregister(cls, name: str):
+        """注销一个 Presenter"""
+        if name in cls._presenters:
+            del cls._presenters[name]
+            del cls._method_whitelist[name]
+            print(f"🗑️ [PresenterRegistry] 注销 Presenter: {name}")
+
+    @classmethod
+    def get_presenter(cls, name: str) -> Optional[Type]:
+        """获取 Presenter 类"""
+        return cls._presenters.get(name)
+
+    @classmethod
+    def is_method_allowed(cls, presenter_name: str, method_name: str) -> bool:
+        """检查方法是否在白名单中"""
+        whitelist = cls._method_whitelist.get(presenter_name)
+        if whitelist is None:
+            return False
+        if whitelist == "*":
+            return True
+        return method_name in whitelist
+
+    @classmethod
+    def list_presenters(cls) -> Dict[str, List[str]]:
+        """列出所有注册的 Presenter 及其方法"""
+        result = {}
+        for name, presenter_class in cls._presenters.items():
+            methods = []
+            whitelist = cls._method_whitelist.get(name, [])
+
+            for attr_name in dir(presenter_class):
+                if attr_name.startswith('_'):
+                    continue
+                attr = getattr(presenter_class, attr_name, None)
+                if callable(attr):
+                    if whitelist == "*" or attr_name in whitelist:
+                        methods.append(attr_name)
+
+            result[name] = methods
+        return result
+
+
+# ==================== 初始化注册 Presenter ====================
+
+def _init_presenter_registry():
+    """初始化 Presenter 注册表，注册所有可用的 Presenter"""
+
+    # 注册本项目中可用的 Presenter
+    try:
+        from evol.presenter.configPresenter import configPresenter
+        PresenterRegistry.register(configPresenter)
+    except ImportError as e:
+        print(f"⚠️ [PresenterRegistry] 导入 configPresenter 失败: {e}")
+
+    print(f"✅ [PresenterRegistry] 初始化完成，已注册 {len(PresenterRegistry._presenters)} 个 Presenter")
+
+
+# ==================== RPC 调用执行器 ====================
+
+class RPCExecutor:
+    """
+    RPC 调用执行器
+
+    负责解析消息、调用 Presenter 方法、处理同步/异步调用
+    """
+
+    @staticmethod
+    def _check_remote_access_permission(rpc_context: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        检查远程访问权限
+
+        Args:
+            rpc_context: RPC 上下文信息
+
+        Returns:
+            None 表示通过验证，否则返回错误响应字典
+        """
+        try:
+            from evol.presenter.configPresenter import configPresenter
+
+            # 检查总开关
+            if not configPresenter.get_remote_access_enabled():
+                return {
+                    "status": "error",
+                    "error": "Evol客户端禁止Web访问，请手动开启",
+                    "error_code": "REMOTE_ACCESS_DISABLED"
+                }
+
+            return None
+
+        except Exception as e:
+            print(f"⚠️ [RPCExecutor] 权限检查失败: {e}")
+            # 权限检查失败时，默认拒绝访问
+            return {
+                "status": "error",
+                "error": f"权限验证失败: {str(e)}",
+                "error_code": "PERMISSION_CHECK_FAILED"
+            }
+
+    @staticmethod
+    async def execute(
+        presenter_name: str,
+        method_name: str,
+        params: Dict[str, Any] = None,
+        rpc_context: Dict[str, Any] = None
+    ) -> Dict[str, Any]:
+        """
+        执行 Presenter 方法调用
+
+        Args:
+            presenter_name: Presenter 名称
+            method_name: 方法名
+            params: 参数字典
+            rpc_context: RPC 上下文信息（包含 sender_aid, session_id, raw_data 等）
+
+        Returns:
+            执行结果字典
+        """
+        params = params or {}
+        rpc_context = rpc_context or {}
+
+        # 0. 远程访问权限检查（所有 RPC 调用都需要验证）
+        permission_error = RPCExecutor._check_remote_access_permission(rpc_context)
+        if permission_error is not None:
+            print(f"🚫 [RPCExecutor] 远程访问被拒绝: {presenter_name}.{method_name}, 原因: {permission_error.get('error')}")
+            return permission_error
+
+        # 1. 获取 Presenter
+        presenter_class = PresenterRegistry.get_presenter(presenter_name)
+        if presenter_class is None:
+            return {
+                "status": "error",
+                "error": f"Presenter '{presenter_name}' 未注册",
+                "available_presenters": list(PresenterRegistry._presenters.keys())
+            }
+
+        # 2. 检查方法白名单
+        if not PresenterRegistry.is_method_allowed(presenter_name, method_name):
+            return {
+                "status": "error",
+                "error": f"方法 '{method_name}' 不在 '{presenter_name}' 的允许列表中"
+            }
+
+        # 3. 获取方法
+        method = getattr(presenter_class, method_name, None)
+        if method is None:
+            return {
+                "status": "error",
+                "error": f"方法 '{method_name}' 在 '{presenter_name}' 中不存在"
+            }
+
+        if not callable(method):
+            return {
+                "status": "error",
+                "error": f"'{method_name}' 不是可调用的方法"
+            }
+
+        # 4. 验证参数
+        try:
+            sig = inspect.signature(method)
+            # 过滤掉 self/cls 参数
+            valid_params = {}
+            for param_name, param in sig.parameters.items():
+                if param_name in ('self', 'cls'):
+                    continue
+                # 特殊参数 _rpc_context：自动注入 RPC 上下文
+                if param_name == '_rpc_context':
+                    valid_params['_rpc_context'] = rpc_context
+                    continue
+                if param_name in params:
+                    valid_params[param_name] = params[param_name]
+                elif param.default is inspect.Parameter.empty:
+                    # 必需参数缺失
+                    return {
+                        "status": "error",
+                        "error": f"缺少必需参数: '{param_name}'"
+                    }
+        except Exception as e:
+            # 无法获取签名，直接传入所有参数
+            print(f"⚠️ [RPCExecutor] 无法获取方法签名: {e}")
+            valid_params = params
+
+        # 5. 执行方法
+        try:
+            # 打印更详细的调用信息
+            params_preview = str(valid_params)[:500] + "..." if len(str(valid_params)) > 500 else str(valid_params)
+            print(f"🔧 [RPCExecutor] 调用 {presenter_name}.{method_name}")
+            print(f"   参数: {params_preview}")
+            if rpc_context:
+                print(f"   RPC上下文: sender={rpc_context.get('sender_aid')}, session={rpc_context.get('session_id')}")
+
+            if asyncio.iscoroutinefunction(method):
+                # 异步方法
+                result = await method(**valid_params)
+            else:
+                # 同步方法，在线程池中执行避免阻塞
+                result = await asyncio.to_thread(method, **valid_params)
+
+            print(f"✅ [RPCExecutor] {presenter_name}.{method_name} 执行成功")
+
+            return {
+                "status": "success",
+                "result": result
+            }
+
+        except Exception as e:
+            error_traceback = traceback.format_exc()
+            print(f"❌ [RPCExecutor] {presenter_name}.{method_name} 执行失败!")
+            print(f"   错误类型: {type(e).__name__}")
+            print(f"   错误信息: {e}")
+            print(f"   完整堆栈:\n{error_traceback}")
+
+            return {
+                "status": "error",
+                "error": str(e),
+                "traceback": error_traceback
+            }
+
+
+# ==================== AgentID Presenter 主类 ====================
+
+class agentIdPresenter:
+    """
+    AgentID 上线统一管理器
+
+    职责：
+    1. 统一管理 AgentID 上线后的初始化工作
+    2. 注册消息监听器
+    3. 实现 Presenter 消息分发（RPC 调用）
+    4. 管理监听器的生命周期
+
+    【重要】当前用户的 agentId 无论在哪里 online，都需要调用 evol_agentId_online() 方法
+    """
+
+    # 当前已上线的 AgentID
+    _current_agentId: Optional[AgentID] = None
+
+    # 已注册的消息处理器列表（用于追踪和清理）
+    _registered_handlers: List[Callable] = []
+
+    # 是否已初始化监听器
+    _listeners_initialized: bool = False
+
+    # Presenter 注册表是否已初始化
+    _registry_initialized: bool = False
+
+    @classmethod
+    def evol_agentId_online(cls, agentId: AgentID) -> bool:
+        """
+        AgentID 上线后的统一入口方法
+
+        【重要】当前用户的 agentId 无论在代码的哪个位置调用 online()，
+        都必须在上线成功后调用此方法。
+
+        此方法会：
+        1. 设置当前活跃的 AgentID
+        2. 初始化 Presenter 注册表
+        3. 初始化/重新初始化消息监听器
+        4. 执行其他上线后的初始化工作
+
+        Args:
+            agentId: 已成功上线的 AgentID 实例
+
+        Returns:
+            bool: 初始化是否成功
+
+        Usage:
+            # 在任何位置的 agentId.online() 之后调用
+            agentId.online()
+            if agentId.is_online_success:
+                from evol.presenter.agentIdPresenter import agentIdPresenter
+                agentIdPresenter.evol_agentId_online(agentId)
+        """
+        if agentId is None:
+            print("❌ [agentIdPresenter] agentId 为空，无法初始化")
+            return False
+
+        if not agentId.is_online_success:
+            print(f"❌ [agentIdPresenter] agentId 未成功上线: {agentId.id}")
+            return False
+
+        try:
+            print(f"🔌 [agentIdPresenter] AgentID 上线成功，开始初始化: {agentId.id}")
+
+            # 初始化 Presenter 注册表（只执行一次）
+            if not cls._registry_initialized:
+                _init_presenter_registry()
+                cls._registry_initialized = True
+
+            # 如果之前有其他 AgentID，先清理
+            if cls._current_agentId is not None and cls._current_agentId.id != agentId.id:
+                print(f"🔄 [agentIdPresenter] 切换 AgentID: {cls._current_agentId.id} -> {agentId.id}")
+                cls._cleanup_listeners()
+
+            # 设置当前 AgentID
+            cls._current_agentId = agentId
+
+            # 初始化监听器
+            cls._init_message_listeners(agentId)
+
+            print(f"✅ [agentIdPresenter] AgentID 初始化完成: {agentId.id}")
+            return True
+
+        except Exception as e:
+            print(f"❌ [agentIdPresenter] 初始化失败: {str(e)}")
+            print(traceback.format_exc())
+            return False
+
+    @classmethod
+    def get_current_agentId(cls) -> Optional[AgentID]:
+        """
+        获取当前已上线的 AgentID
+
+        Returns:
+            AgentID 或 None
+        """
+        return cls._current_agentId
+
+    @classmethod
+    def is_online(cls) -> bool:
+        """
+        检查当前 AgentID 是否在线
+
+        Returns:
+            bool: True 表示在线
+        """
+        return (cls._current_agentId is not None and
+                cls._current_agentId.is_online_success)
+
+    @classmethod
+    def _init_message_listeners(cls, agentId: AgentID):
+        """
+        初始化消息监听器
+
+        在此方法中注册 RPC 消息处理器
+
+        Args:
+            agentId: AgentID 实例
+        """
+        if cls._listeners_initialized and cls._current_agentId == agentId:
+            print(f"ℹ️ [agentIdPresenter] 监听器已初始化，跳过重复初始化")
+            return
+
+        print(f"📡 [agentIdPresenter] 初始化消息监听器: {agentId.id}")
+
+        # 清理旧的监听器
+        cls._cleanup_listeners()
+
+        # 注册 RPC 消息处理器
+        async def rpc_message_handler(data: dict):
+            """
+            RPC 消息处理器
+
+            处理所有消息，从 type="content" 的消息中解析 RPC 调用
+
+            健壮性保证：
+            - 所有操作都在多层 try-except 中，确保不会因为任何异常导致程序崩溃
+            - 即使消息格式异常、agentId离线、响应序列化失败，也只记录日志不崩溃
+            """
+            sender_aid = None
+            session_id = None
+            trace_id = None
+            try:
+                if data is None:
+                    return
+
+                if not isinstance(data, dict):
+                    print(f"⚠️ [agentIdPresenter] 收到非dict消息，类型: {type(data)}")
+                    return
+
+                # 安全获取发送者信息
+                try:
+                    sender_aid = agentId.get_sender_from_message(data)
+                except Exception as e:
+                    print(f"⚠️ [agentIdPresenter] get_sender_from_message 异常: {e}")
+                    return
+
+                try:
+                    session_id = agentId.get_session_id_from_message(data)
+                except Exception as e:
+                    print(f"⚠️ [agentIdPresenter] get_session_id_from_message 异常: {e}")
+                    return
+
+                if not sender_aid or not session_id:
+                    print(f"⚠️ [agentIdPresenter] 无法获取发送者信息或会话ID，跳过消息")
+                    return
+
+                # 安全获取消息内容数组
+                try:
+                    messages = agentId.get_content_array_from_message(data)
+                except Exception as e:
+                    print(f"⚠️ [agentIdPresenter] get_content_array_from_message 异常: {e}")
+                    return
+
+                if not messages or len(messages) == 0:
+                    return
+
+                # 遍历消息数组，查找 type="content" 的消息
+                for msg_item in messages:
+                    try:
+                        if not isinstance(msg_item, dict):
+                            continue
+
+                        msg_type = msg_item.get("type", "")
+
+                        # 只处理 type="content" 的消息
+                        if msg_type != "content":
+                            continue
+
+                        # 获取 content 字段
+                        content_str = msg_item.get("content", "")
+                        if not content_str:
+                            continue
+
+                        # 解析 content 为 JSON
+                        try:
+                            if isinstance(content_str, str):
+                                content_data = json.loads(content_str)
+                            elif isinstance(content_str, dict):
+                                content_data = content_str
+                            else:
+                                continue
+                        except json.JSONDecodeError:
+                            # 不是 JSON 格式，跳过
+                            continue
+                        except Exception as json_err:
+                            print(f"⚠️ [agentIdPresenter] JSON 解析异常: {json_err}")
+                            continue
+
+                        if not isinstance(content_data, dict):
+                            continue
+
+                        # 检查是否为 RPC 调用
+                        action = content_data.get("action", "")
+                        if action != "rpc_call":
+                            # 不是 RPC 调用，跳过
+                            continue
+
+                        # 解析 RPC 调用参数
+                        trace_id = content_data.get("trace_id", "")
+                        presenter_name = content_data.get("presenter", "")
+                        method_name = content_data.get("method", "")
+                        params = content_data.get("params", {})
+
+                        # 确保 params 是 dict
+                        if not isinstance(params, dict):
+                            params = {}
+
+                        print(f"📨 [agentIdPresenter] 收到 RPC 调用: {presenter_name}.{method_name}, trace_id: {trace_id}")
+
+                        # 参数验证
+                        if not presenter_name:
+                            await cls._send_rpc_response(
+                                agentId, sender_aid, session_id, trace_id,
+                                status="error",
+                                error="缺少 presenter 参数"
+                            )
+                            continue
+
+                        if not method_name:
+                            await cls._send_rpc_response(
+                                agentId, sender_aid, session_id, trace_id,
+                                status="error",
+                                error="缺少 method 参数"
+                            )
+                            continue
+
+                        # 构建 RPC 上下文
+                        rpc_context = {
+                            'sender_aid': sender_aid,
+                            'session_id': session_id,
+                            'raw_data': data,
+                            'trace_id': trace_id
+                        }
+
+                        # 执行 RPC 调用
+                        try:
+                            result = await RPCExecutor.execute(presenter_name, method_name, params, rpc_context)
+                        except Exception as exec_err:
+                            print(f"❌ [agentIdPresenter] RPCExecutor.execute 异常: {exec_err}")
+                            traceback.print_exc()
+                            result = {
+                                "status": "error",
+                                "error": f"RPC执行异常: {str(exec_err)}"
+                            }
+
+                        # 发送响应
+                        await cls._send_rpc_response(
+                            agentId, sender_aid, session_id, trace_id,
+                            status=result.get("status", "error"),
+                            result=result.get("result"),
+                            error=result.get("error")
+                        )
+
+                    except Exception as item_err:
+                        # 单条消息处理失败，不影响其他消息
+                        print(f"❌ [agentIdPresenter] 处理单条消息异常: {item_err}")
+                        traceback.print_exc()
+                        # 尝试发送错误响应
+                        if trace_id and sender_aid and session_id:
+                            try:
+                                await cls._send_rpc_response(
+                                    agentId, sender_aid, session_id, trace_id,
+                                    status="error",
+                                    error=f"消息处理异常: {str(item_err)}"
+                                )
+                            except Exception:
+                                pass
+                        continue
+
+            except Exception as e:
+                # 最外层兜底，确保不崩溃
+                try:
+                    print(f"❌ [agentIdPresenter] RPC 消息处理失败: {str(e)}")
+                    traceback.print_exc()
+
+                    # 尝试发送错误响应
+                    if sender_aid and session_id:
+                        await cls._send_rpc_response(
+                            agentId, sender_aid, session_id, trace_id or "",
+                            status="error",
+                            error=f"消息处理异常: {str(e)}"
+                        )
+                except Exception as final_err:
+                    # 即使异常处理也失败了，只打印日志
+                    print(f"❌❌ [agentIdPresenter] 严重错误 - 异常处理失败: {final_err}")
+
+        # 注册监听器
+        agentId.add_message_handler(rpc_message_handler)
+        cls._registered_handlers.append(rpc_message_handler)
+
+        cls._listeners_initialized = True
+        print(f"✅ [agentIdPresenter] RPC 消息监听器注册成功")
+
+    @classmethod
+    async def _send_rpc_response(
+        cls,
+        agentId: AgentID,
+        sender_aid: str,
+        session_id: str,
+        trace_id: str,
+        status: str,
+        result: Any = None,
+        error: str = None
+    ):
+        """
+        发送 RPC 响应消息
+
+        健壮性保证：
+        - JSON 序列化失败时使用降级方案
+        - 发送消息失败时只记录日志不崩溃
+        - 所有操作都在 try-except 中
+
+        响应消息格式（包装为 content 类型）：
+        {
+            "type": "content",
+            "content": "{\"action\":\"rpc_response\",\"trace_id\":\"xxx\",...}"
+        }
+        """
+        try:
+            # 安全检查参数
+            if not sender_aid or not session_id:
+                print(f"⚠️ [agentIdPresenter] _send_rpc_response: sender_aid 或 session_id 为空，跳过发送")
+                return
+
+            if agentId is None or not agentId.is_online_success:
+                print(f"⚠️ [agentIdPresenter] _send_rpc_response: agentId 不在线，跳过发送")
+                return
+
+            # 构建响应数据
+            response_data = {
+                "action": "rpc_response",
+                "trace_id": trace_id or "",
+                "status": status or "error"
+            }
+
+            if status == "success" and result is not None:
+                # 尝试安全地序列化 result
+                try:
+                    # 先测试 result 是否可序列化
+                    json.dumps(result, ensure_ascii=False)
+                    response_data["result"] = result
+                except (TypeError, ValueError) as json_err:
+                    # result 不可序列化，尝试转换
+                    print(f"⚠️ [agentIdPresenter] result 不可序列化: {json_err}，尝试转换")
+                    try:
+                        # 尝试转为字符串
+                        response_data["result"] = str(result)
+                        response_data["_result_serialization_fallback"] = True
+                    except Exception:
+                        response_data["result"] = "[无法序列化的结果]"
+                        response_data["_result_serialization_failed"] = True
+
+            if status == "error" and error:
+                response_data["error"] = str(error) if error else "未知错误"
+
+            # 安全序列化响应
+            try:
+                response_json = json.dumps(response_data, ensure_ascii=False)
+            except (TypeError, ValueError) as json_err:
+                print(f"⚠️ [agentIdPresenter] 响应序列化失败: {json_err}，使用降级方案")
+                # 降级方案：只发送基本信息
+                fallback_data = {
+                    "action": "rpc_response",
+                    "trace_id": trace_id or "",
+                    "status": "error",
+                    "error": f"响应序列化失败: {str(json_err)}"
+                }
+                response_json = json.dumps(fallback_data, ensure_ascii=False)
+
+            # 包装为 content 类型的消息
+            response_msg = {
+                "type": "content",
+                "content": response_json
+            }
+
+            print(f"📤 [agentIdPresenter] 发送 RPC 响应: trace_id={trace_id}, status={status}")
+
+            # 发送消息
+            try:
+                agentId.send_message(session_id, [sender_aid], response_msg)
+                print(f"✅ [agentIdPresenter] RPC 响应已发送")
+            except Exception as send_err:
+                print(f"❌ [agentIdPresenter] send_message 失败: {send_err}")
+                # 发送失败，可能是 agentId 已离线，只记录日志
+
+        except Exception as e:
+            # 最外层兜底
+            print(f"❌ [agentIdPresenter] 发送 RPC 响应失败: {str(e)}")
+            try:
+                traceback.print_exc()
+            except:
+                pass
+
+    @classmethod
+    def _cleanup_listeners(cls):
+        """
+        清理已注册的监听器
+
+        在切换 AgentID 或关闭时调用
+        """
+        if cls._current_agentId is not None and cls._registered_handlers:
+            print(f"🧹 [agentIdPresenter] 清理监听器: {len(cls._registered_handlers)} 个")
+            for handler in cls._registered_handlers:
+                try:
+                    cls._current_agentId.remove_message_handler(handler, session_id="")
+                except Exception as e:
+                    print(f"⚠️ [agentIdPresenter] 清理监听器失败: {str(e)}")
+
+        cls._registered_handlers.clear()
+        cls._listeners_initialized = False
+
+    @classmethod
+    def offline(cls):
+        """
+        AgentID 下线处理
+
+        清理资源和监听器
+        """
+        print(f"🔴 [agentIdPresenter] AgentID 下线")
+        cls._cleanup_listeners()
+        cls._current_agentId = None
+
+    # ==================== 对外暴露的工具方法 ====================
+
+    @classmethod
+    def list_available_presenters(cls) -> Dict[str, List[str]]:
+        """
+        列出所有可用的 Presenter 及其方法
+
+        Returns:
+            Dict: {presenter_name: [method_names]}
+        """
+        if not cls._registry_initialized:
+            _init_presenter_registry()
+            cls._registry_initialized = True
+
+        return PresenterRegistry.list_presenters()
+
+    @classmethod
+    def register_presenter(cls, presenter_class: Type, name: str = None, allowed_methods: List[str] = None):
+        """
+        动态注册一个 Presenter
+
+        Args:
+            presenter_class: Presenter 类
+            name: 注册名称（可选）
+            allowed_methods: 允许的方法列表（可选）
+        """
+        PresenterRegistry.register(presenter_class, name, allowed_methods)
+
+
+# ==================== 便捷函数 ====================
+
+def evol_agentId_online(agentId: AgentID) -> bool:
+    """
+    AgentID 上线后的便捷调用函数
+
+    【重要】当前用户的 agentId 无论在代码的哪个位置调用 online()，
+    都必须在上线成功后调用此函数。
+
+    Args:
+        agentId: 已成功上线的 AgentID 实例
+
+    Returns:
+        bool: 初始化是否成功
+
+    Usage:
+        from evol.presenter.agentIdPresenter import evol_agentId_online
+
+        agentId.online()
+        if agentId.is_online_success:
+            evol_agentId_online(agentId)
+    """
+    return agentIdPresenter.evol_agentId_online(agentId)