mobile-mcp-ai 2.1.2__py3-none-any.whl → 2.5.8__py3-none-any.whl

{core → mobile_mcp/core}/mobile_client.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-移动端客户端 - 类似Web端的MCPClient
+
 
 功能：
 1. 设备连接管理
@@ -23,19 +23,18 @@ from .device_manager import DeviceManager
 from ..utils.xml_parser import XMLParser
 from ..utils.xml_formatter import XMLFormatter
 from .utils.smart_wait import SmartWait
+from .dynamic_config import DynamicConfig
 
 
 class MobileClient:
     """
-    移动端客户端 - 类似Web端的MCPClient
-    
     用法:
         client = MobileClient(device_id=None, platform="android")
         await client.launch_app("com.example.app")
         await client.click("登录按钮")
     """
     
-    def __init__(self, device_id: Optional[str] = None, platform: str = "android", lock_orientation: bool = True):
+    def __init__(self, device_id: Optional[str] = None, platform: str = "android", lock_orientation: bool = True, lazy_connect: bool = False):
         """
         初始化移动端客户端
         
@@ -43,21 +42,33 @@ class MobileClient:
             device_id: 设备ID，None则自动选择第一个设备
             platform: 平台类型 ("android" 或 "ios")
             lock_orientation: 是否锁定屏幕方向为竖屏（默认True，仅Android有效）
+            lazy_connect: 是否延迟连接（默认False）。如果为True，则不立即连接设备
         """
         self.platform = platform
+        self._device_id = device_id
+        self._lazy_connect = lazy_connect
         
         if platform == "android":
             self.device_manager = DeviceManager(platform="android")
-            self.u2 = self.device_manager.connect(device_id)
+            if not lazy_connect:
+                self.u2 = self.device_manager.connect(device_id)
+            else:
+                self.u2 = None
             self.driver = None  # iOS使用
             
             # 初始化智能等待工具
-            self.smart_wait = SmartWait(self)
+            if not lazy_connect:
+                self.smart_wait = SmartWait(self)
+            else:
+                self.smart_wait = None
         elif platform == "ios":
-            from .ios_device_manager import IOSDeviceManager
-            self.device_manager = IOSDeviceManager()
-            self.driver = self.device_manager.connect(device_id)
-            self.u2 = None  # Android使用
+            # 🍎 iOS 支持：使用 tidevice + facebook-wda
+            from .ios_client_wda import IOSClientWDA
+            self._ios_client = IOSClientWDA(device_id=device_id, lazy_connect=lazy_connect)
+            self.device_manager = self._ios_client.device_manager
+            self.wda = self._ios_client.wda if not lazy_connect else None
+            self.driver = None
+            self.u2 = None
         else:
             raise ValueError(f"不支持的平台: {platform}")
         
@@ -164,8 +175,22 @@ class MobileClient:
             if current_time - self._cache_timestamp < self._cache_ttl:
                 return self._snapshot_cache
         
+        # iOS平台使用不同的实现
+        if self.platform == "ios":
+            if not self.driver:
+                raise RuntimeError("iOS设备未连接")
+            # 获取iOS页面源码
+            xml_string = self.driver.page_source
+            if not isinstance(xml_string, str):
+                xml_string = str(xml_string)
+            # iOS的XML格式可能不同，直接返回或简单格式化
+            self._snapshot_cache = xml_string
+            self._cache_timestamp = time.time()
+            return xml_string
+        
+        # Android平台
         # 获取XML
-        xml_string = self.u2.dump_hierarchy()
+        xml_string = self.u2.dump_hierarchy(compressed=False)
         
         # 确保xml_string是字符串类型
         if not isinstance(xml_string, str):
@@ -296,7 +321,7 @@ class MobileClient:
                         # 🎯 改进：尝试模糊匹配（忽略空格、括号）
                         ref_normalized = ref.replace(' ', '').replace('(', '').replace(')', '').replace('（', '').replace('）', '')
                         # 获取所有元素，手动匹配
-                        xml_string = self.u2.dump_hierarchy()
+                        xml_string = self.u2.dump_hierarchy(compressed=False)
                         elements = self.xml_parser.parse(xml_string)
                         for elem in elements:
                             elem_desc = elem.get('content_desc', '')
@@ -355,10 +380,12 @@ class MobileClient:
                                         break
                                 
                                 if not found:
-                                    # 🎯 定位失败，自动使用Cursor AI视觉识别（截图分析）
-                                    print(f"  ⚠️  元素'{ref}'未找到，自动使用Cursor AI视觉识别（截图分析）...", file=sys.stderr)
+                                    # 🎯 定位失败，提示用户
+                                    # 注意：CursorVisionHelper 是实验性功能，当前版本建议使用 MCP 方式
+                                    print(f"  ⚠️  元素'{ref}'未找到", file=sys.stderr)
                                     try:
                                         from .locator.cursor_vision_helper import CursorVisionHelper
+                                        print(f"  🔍 尝试使用Cursor AI视觉识别...", file=sys.stderr)
                                         cursor_helper = CursorVisionHelper(self)
                                         # 🎯 传递 auto_analyze=True，自动创建请求文件并等待结果
                                         cursor_result = await cursor_helper.analyze_with_cursor(element, auto_analyze=True)
@@ -390,19 +417,24 @@ class MobileClient:
                                             # 其他情况，抛出异常
                                             screenshot_path = cursor_result.get('screenshot_path', 'unknown') if cursor_result else 'unknown'
                                             raise ValueError(f"Cursor AI分析失败: {screenshot_path}")
+                                    except ImportError:
+                                        # CursorVisionHelper 模块不存在，跳过视觉识别
+                                        print(f"  💡 提示：建议使用 MCP 方式调用，Cursor AI 会自动进行视觉识别", file=sys.stderr)
                                     except ValueError as ve:
                                         if "Cursor AI" in str(ve):
                                             raise ve
                                         print(f"  ⚠️  Cursor视觉识别失败: {ve}", file=sys.stderr)
+                                    except Exception as e:
+                                        print(f"  ⚠️  视觉识别异常: {e}", file=sys.stderr)
                                     
-                                    raise ValueError(f"无法找到元素: {ref}（已等待3秒，并尝试Cursor视觉识别，可能元素不存在）")
+                                    raise ValueError(f"无法找到元素: {ref}（建议使用 MCP 方式，Cursor AI 会自动进行视觉识别）")
             
             # 验证点击（可选）
             page_changed = False
             if verify:
                 # 获取点击前页面状态
                 try:
-                    initial_xml = self.u2.dump_hierarchy()
+                    initial_xml = self.u2.dump_hierarchy(compressed=False)
                     initial_length = len(initial_xml)
                     
                     # 等待页面变化
@@ -675,6 +707,31 @@ class MobileClient:
             - verified: 是否经过验证
             - page_changed: 页面是否变化（仅 verify=True）
         """
+        # iOS平台使用不同的实现
+        if self.platform == "ios":
+            if not self.driver:
+                return {"success": False, "reason": "iOS设备未连接"}
+            try:
+                size = self.driver.get_window_size()
+                width = size['width']
+                height = size['height']
+                
+                if direction == 'up':
+                    self.driver.swipe(width // 2, int(height * 0.8), width // 2, int(height * 0.2))
+                elif direction == 'down':
+                    self.driver.swipe(width // 2, int(height * 0.2), width // 2, int(height * 0.8))
+                elif direction == 'left':
+                    self.driver.swipe(int(width * 0.8), height // 2, int(width * 0.2), height // 2)
+                elif direction == 'right':
+                    self.driver.swipe(int(width * 0.2), height // 2, int(width * 0.8), height // 2)
+                else:
+                    return {"success": False, "reason": f"不支持的滑动方向: {direction}"}
+                
+                return {"success": True, "direction": direction}
+            except Exception as e:
+                return {"success": False, "reason": str(e)}
+        
+        # Android平台
         # 获取屏幕尺寸
         width, height = self.u2.window_size()
         
@@ -700,7 +757,7 @@ class MobileClient:
             initial_length = 0
             if verify:
                 try:
-                    initial_xml = self.u2.dump_hierarchy()
+                    initial_xml = self.u2.dump_hierarchy(compressed=False)
                     initial_length = len(initial_xml)
                 except Exception as e:
                     print(f"  ⚠️  获取初始页面状态失败: {e}", file=sys.stderr)
@@ -735,23 +792,45 @@ class MobileClient:
     
     async def launch_app(self, package_name: str, wait_time: int = 3, smart_wait: bool = True):
         """
-        启动App
+        启动App（快速模式：最多等待3秒+截图验证）
         
         Args:
-            package_name: App包名（如 "com.example.app"）
-            wait_time: 等待App启动的时间（秒）- 仅在smart_wait=False时使用
-            smart_wait: 是否启用智能等待（自动关闭广告、等待主页加载）
+            package_name: App包名（Android）或Bundle ID（iOS），如 "com.example.app"
+            wait_time: 等待App启动的时间（秒）- 默认3秒
+            smart_wait: 是否启用智能等待（自动关闭广告、截图验证）- 仅Android
             
         Returns:
-            操作结果
+            操作结果（包含screenshot_path字段供AI验证）
         """
         try:
+            # iOS平台使用不同的实现
+            if self.platform == "ios":
+                if not self.driver:
+                    return {"success": False, "reason": "iOS设备未连接"}
+                try:
+                    print(f"  📱 启动iOS App: {package_name}", file=sys.stderr)
+                    self.driver.activate_app(package_name)
+                    await asyncio.sleep(wait_time)
+                    
+                    # 验证是否启动成功
+                    current = await self.get_current_package()
+                    if current == package_name:
+                        print(f"  ✅ iOS App启动成功: {package_name}", file=sys.stderr)
+                        return {"success": True, "package": package_name}
+                    else:
+                        print(f"  ⚠️  iOS App可能未启动成功，当前App: {current}，期望: {package_name}", file=sys.stderr)
+                        return {"success": True, "package": package_name, "warning": f"当前App: {current}"}
+                except Exception as e:
+                    print(f"  ❌ iOS App启动异常: {e}", file=sys.stderr)
+                    return {"success": False, "reason": str(e)}
+            
+            # Android平台
             # 🎯 优先使用智能启动（推荐）
             if smart_wait:
                 from .smart_app_launcher import SmartAppLauncher
                 launcher = SmartAppLauncher(self)
-                # 优化：默认5秒，最多不超过8秒
-                smart_wait_time = min(max(5, wait_time), 8)
+                # 优化：快速模式，最多3秒
+                smart_wait_time = min(wait_time, 3)
                 
                 # 🎯 从环境变量读取是否自动关闭广告（默认True）
                 import os
@@ -762,6 +841,12 @@ class MobileClient:
                     max_wait=smart_wait_time,
                     auto_close_ads=auto_close_ads
                 )
+                
+                # 打印截图路径（供Cursor AI查看验证）
+                if result.get('screenshot_path'):
+                    print(f"\n📸 启动截图已保存: {result['screenshot_path']}", file=sys.stderr)
+                    print(f"💡 提示: 请查看截图确认App是否已正确进入主页", file=sys.stderr)
+                
                 return result
             
             # 传统方式（快速启动，不等待加载）
@@ -802,13 +887,27 @@ class MobileClient:
         停止App
         
         Args:
-            package_name: App包名
+            package_name: App包名（Android）或Bundle ID（iOS）
             
         Returns:
             操作结果
         """
         try:
             print(f"  📱 停止App: {package_name}", file=sys.stderr)
+            
+            # iOS平台使用不同的实现
+            if self.platform == "ios":
+                if not self.driver:
+                    return {"success": False, "reason": "iOS设备未连接"}
+                try:
+                    self.driver.terminate_app(package_name)
+                    print(f"  ✅ iOS App已停止: {package_name}", file=sys.stderr)
+                    return {"success": True}
+                except Exception as e:
+                    print(f"  ❌ iOS App停止失败: {e}", file=sys.stderr)
+                    return {"success": False, "reason": str(e)}
+            
+            # Android平台
             self.u2.app_stop(package_name)
             print(f"  ✅ App已停止: {package_name}", file=sys.stderr)
             return {"success": True}
@@ -818,14 +917,19 @@ class MobileClient:
     
     async def get_current_package(self) -> Optional[str]:
         """
-        获取当前App包名
+        获取当前App包名（Android）或Bundle ID（iOS）
         
         Returns:
-            包名或None
+            包名/Bundle ID或None
         """
         try:
-            info = self.u2.app_current()
-            return info.get('package')
+            if self.platform == "ios":
+                if not self.driver:
+                    return None
+                return self.driver.current_package
+            else:
+                info = self.u2.app_current()
+                return info.get('package')
         except:
             return None
     
@@ -853,6 +957,34 @@ class MobileClient:
             - page_changed: 页面是否变化（仅 verify=True 时）
             - fallback_used: 是否使用了备选方案（仅搜索键）
         """
+        # iOS平台使用不同的实现
+        if self.platform == "ios":
+            if not self.driver:
+                return {"success": False, "reason": "iOS设备未连接"}
+            try:
+                # iOS按键映射（使用XCUITest的按键）
+                ios_key_map = {
+                    'enter': 'return',
+                    '回车': 'return',
+                    'back': 'back',
+                    '返回': 'back',
+                    'home': 'home',
+                }
+                
+                key_lower = key.lower()
+                if key_lower in ios_key_map:
+                    ios_key = ios_key_map[key_lower]
+                    # iOS使用execute_script发送按键
+                    self.driver.execute_script("mobile: pressButton", {"name": ios_key})
+                    print(f"  ✅ iOS按键成功: {key} ({ios_key})", file=sys.stderr)
+                    return {"success": True, "key": key, "verified": False}
+                else:
+                    return {"success": False, "reason": f"iOS不支持的按键: {key}"}
+            except Exception as e:
+                print(f"  ❌ iOS按键失败: {e}", file=sys.stderr)
+                return {"success": False, "reason": str(e)}
+        
+        # Android平台
         key_map = {
             'enter': 66,  # KEYCODE_ENTER
             '回车': 66,
@@ -876,7 +1008,7 @@ class MobileClient:
                 try:
                     if verify:
                         # 获取操作前页面状态
-                        initial_xml = self.u2.dump_hierarchy()
+                        initial_xml = self.u2.dump_hierarchy(compressed=False)
                         initial_length = len(initial_xml)
                     
                     self.u2.press(key.lower())
@@ -905,7 +1037,7 @@ class MobileClient:
             # 标准按键处理
             if verify:
                 # 获取操作前页面状态
-                initial_xml = self.u2.dump_hierarchy()
+                initial_xml = self.u2.dump_hierarchy(compressed=False)
                 initial_length = len(initial_xml)
             
             # 使用keycode按键 - uiautomator2使用shell命令
@@ -967,7 +1099,7 @@ class MobileClient:
         print(f"  🔍 智能搜索键：先尝试SEARCH键...", file=sys.stderr)
         
         # 获取初始页面状态
-        initial_xml = self.u2.dump_hierarchy()
+        initial_xml = self.u2.dump_hierarchy(compressed=False)
         initial_length = len(initial_xml)
         
         # 方案1: 尝试 SEARCH 键 (keycode=84)
@@ -994,7 +1126,7 @@ class MobileClient:
                 
                 # 方案2: 尝试 ENTER 键 (keycode=66)
                 # 重新获取当前页面状态（因为可能有轻微变化）
-                current_xml = self.u2.dump_hierarchy()
+                current_xml = self.u2.dump_hierarchy(compressed=False)
                 current_length = len(current_xml)
                 
                 self.u2.shell('input keyevent 66')
@@ -1028,25 +1160,31 @@ class MobileClient:
             print(f"  ❌ 搜索键执行失败: {e}", file=sys.stderr)
             return {"success": False, "reason": str(e)}
     
-    async def _verify_page_change(self, initial_length: int, timeout: float = 2.0, change_threshold: float = 0.05) -> bool:
+    async def _verify_page_change(self, initial_length: int, timeout: float = None, change_threshold: float = None) -> bool:
         """
         验证页面是否发生变化
         
         Args:
             initial_length: 初始页面XML长度
-            timeout: 最大等待时间（秒）
-            change_threshold: 变化阈值（百分比，默认5%）
+            timeout: 最大等待时间（秒），None则使用动态配置
+            change_threshold: 变化阈值（百分比），None则使用动态配置
         
         Returns:
             页面是否发生了明显变化
         """
+        # 使用动态配置（支持AI调整）
+        if timeout is None:
+            timeout = DynamicConfig.page_change_timeout
+        if change_threshold is None:
+            change_threshold = DynamicConfig.page_change_threshold
+        
         start_time = time.time()
         
         while time.time() - start_time < timeout:
             await asyncio.sleep(0.1)  # 每100ms检查一次
             
             try:
-                current_xml = self.u2.dump_hierarchy()
+                current_xml = self.u2.dump_hierarchy(compressed=False)
                 current_length = len(current_xml)
                 
                 # 计算变化百分比
@@ -1054,8 +1192,9 @@ class MobileClient:
                 
                 if change_percent > change_threshold:
                     print(f"  📊 页面变化检测: {change_percent*100:.1f}% (阈值: {change_threshold*100}%)", file=sys.stderr)
-                    # 等待页面稳定
-                    await asyncio.sleep(0.3)
+                    # 等待页面稳定（使用动态配置）
+                    await asyncio.sleep(DynamicConfig.wait_page_stable)
+                    print(f"  ⏳ 已等待页面稳定 {DynamicConfig.wait_page_stable}秒", file=sys.stderr)
                     return True
             except Exception as e:
                 print(f"  ⚠️  页面变化检测异常: {e}", file=sys.stderr)
@@ -1080,4 +1219,105 @@ class MobileClient:
             x1, y1, x2, y2 = map(int, match.groups())
             return ((x1 + x2) // 2, (y1 + y2) // 2)
         return (0, 0)
+    
+    async def _ios_click(self, element: str, ref: Optional[str] = None):
+        """
+        iOS平台的点击实现
+        
+        Args:
+            element: 元素描述
+            ref: 元素定位器
+            
+        Returns:
+            操作结果
+        """
+        try:
+            from selenium.webdriver.common.by import By
+            
+            # 如果提供了ref，直接使用
+            if ref:
+                if ref.startswith('//') or ref.startswith('/'):
+                    # XPath
+                    elem = self.driver.find_element(By.XPATH, ref)
+                elif ref.startswith('id='):
+                    # accessibility_id
+                    elem = self.driver.find_element(By.ID, ref.replace('id=', ''))
+                else:
+                    # 默认作为accessibility_id
+                    elem = self.driver.find_element(By.ID, ref)
+            else:
+                # 尝试多种定位方式
+                selectors = [
+                    (By.XPATH, f"//*[@name='{element}']"),
+                    (By.XPATH, f"//*[@label='{element}']"),
+                    (By.XPATH, f"//*[contains(@name, '{element}')]"),
+                ]
+                
+                elem = None
+                for by, selector in selectors:
+                    try:
+                        elem = self.driver.find_element(by, selector)
+                        break
+                    except:
+                        continue
+                
+                if not elem:
+                    raise ValueError(f"未找到元素: {element}")
+            
+            elem.click()
+            
+            # 记录操作
+            self.operation_history.append({
+                'action': 'click',
+                'element': element,
+                'ref': ref or 'auto',
+                'success': True
+            })
+            
+            return {"success": True, "ref": ref or element}
+            
+        except Exception as e:
+            return {"success": False, "reason": str(e)}
+    
+    async def _ios_type_text(self, element: str, text: str, ref: Optional[str] = None):
+        """
+        iOS平台的输入文本实现
+        
+        Args:
+            element: 元素描述
+            text: 要输入的文本
+            ref: 元素定位器
+            
+        Returns:
+            操作结果
+        """
+        try:
+            from selenium.webdriver.common.by import By
+            
+            # 定位输入框
+            if ref:
+                if ref.startswith('//'):
+                    elem = self.driver.find_element(By.XPATH, ref)
+                else:
+                    elem = self.driver.find_element(By.ID, ref)
+            else:
+                # 查找第一个输入框
+                elem = self.driver.find_element(By.XPATH, "//XCUIElementTypeTextField | //XCUIElementTypeSecureTextField")
+            
+            elem.clear()
+            elem.send_keys(text)
+            
+            # 记录操作
+            self.operation_history.append({
+                'action': 'type',
+                'element': element,
+                'text': text,
+                'ref': ref or 'auto',
+                'success': True
+            })
+            
+            return {"success": True, "ref": ref or element}
+            
+        except Exception as e:
+            return {"success": False, "reason": str(e)}