mobile-mcp-ai 2.2.6__py3-none-any.whl → 2.5.3__py3-none-any.whl

mobile_mcp/core/ios_device_manager_wda.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+iOS设备连接管理 - 使用 tidevice + facebook-wda
+
+优势：
+1. API风格和 uiautomator2 几乎一样
+2. 不需要启动 Appium Server
+3. tidevice 简化设备管理
+
+前置条件：
+1. 安装 tidevice: pip install tidevice
+2. 安装 facebook-wda: pip install facebook-wda
+3. 首次需要用 Xcode 编译 WebDriverAgent 到设备上
+
+用法:
+    manager = IOSDeviceManagerWDA()
+    devices = manager.list_devices()
+    client = manager.connect(device_id="xxx")
+    client(text="登录").click()  # 和 uiautomator2 风格一样！
+"""
+import sys
+import subprocess
+from typing import List, Optional, Dict
+
+
+class IOSDeviceManagerWDA:
+    """
+    iOS设备管理器 - 使用 tidevice + facebook-wda
+    
+    用法:
+        manager = IOSDeviceManagerWDA()
+        devices = manager.list_devices()
+        client = manager.connect()
+        client(text="登录").click()
+    """
+    
+    def __init__(self):
+        """初始化iOS设备管理器"""
+        self.client = None
+        self.current_device_id = None
+        self._wda_proxy_process = None
+        self._check_dependencies()
+    
+    def _check_dependencies(self):
+        """检查依赖是否安装"""
+        try:
+            import tidevice
+            import wda
+        except ImportError as e:
+            raise ImportError(
+                f"缺少iOS自动化依赖: {e}\n"
+                f"请运行以下命令安装:\n"
+                f"  pip install tidevice facebook-wda\n"
+            )
+    
+    def list_devices(self) -> List[Dict[str, str]]:
+        """
+        列出所有连接的iOS设备
+        
+        Returns:
+            设备列表，每个设备包含 id, name, type 等信息
+        """
+        devices = []
+        
+        try:
+            # 优先使用 tidevice Python API
+            try:
+                import tidevice
+                for d in tidevice.Usbmux().device_list():
+                    devices.append({
+                        'id': d.udid,
+                        'name': d.name if hasattr(d, 'name') else 'iOS Device',
+                        'type': 'device',
+                        'state': 'connected'
+                    })
+                if devices:
+                    return devices
+            except Exception:
+                pass
+            
+            # 回退：使用 subprocess 调用 tidevice
+            result = subprocess.run(
+                [sys.executable, '-m', 'tidevice', 'list', '--json'],
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+            
+            if result.returncode == 0 and result.stdout.strip():
+                import json
+                try:
+                    device_list = json.loads(result.stdout)
+                    for device in device_list:
+                        devices.append({
+                            'id': device.get('udid', ''),
+                            'name': device.get('name', 'iOS Device'),
+                            'type': 'device',
+                            'model': device.get('model', 'Unknown'),
+                            'ios_version': device.get('version', 'Unknown'),
+                            'state': 'connected'
+                        })
+                except json.JSONDecodeError:
+                    # 尝试纯文本解析
+                    for line in result.stdout.strip().split('\n'):
+                        if line.strip():
+                            parts = line.split()
+                            if len(parts) >= 1:
+                                devices.append({
+                                    'id': parts[0],
+                                    'name': ' '.join(parts[1:]) if len(parts) > 1 else 'iOS Device',
+                                    'type': 'device',
+                                    'state': 'connected'
+                                })
+            
+            # 如果 tidevice 没有找到设备，尝试使用 xcrun simctl 列出模拟器
+            if not devices:
+                sim_result = subprocess.run(
+                    ['xcrun', 'simctl', 'list', 'devices', 'booted', '--json'],
+                    capture_output=True,
+                    text=True,
+                    timeout=10
+                )
+                
+                if sim_result.returncode == 0 and sim_result.stdout.strip():
+                    import json
+                    sim_data = json.loads(sim_result.stdout)
+                    for runtime, sims in sim_data.get('devices', {}).items():
+                        for sim in sims:
+                            if sim.get('state') == 'Booted':
+                                devices.append({
+                                    'id': sim.get('udid', ''),
+                                    'name': sim.get('name', 'Simulator'),
+                                    'type': 'simulator',
+                                    'runtime': runtime,
+                                    'state': 'Booted'
+                                })
+            
+            return devices
+            
+        except FileNotFoundError:
+            print("⚠️  tidevice 未安装，请运行: pip install tidevice", file=sys.stderr)
+            return []
+        except Exception as e:
+            print(f"⚠️  获取设备列表失败: {e}", file=sys.stderr)
+            return []
+    
+    def start_wda_proxy(self, device_id: str, port: int = 8100) -> bool:
+        """
+        启动 WDA 代理（如果尚未启动）
+        
+        Args:
+            device_id: 设备UDID
+            port: WDA代理端口，默认8100
+            
+        Returns:
+            是否成功启动
+        """
+        try:
+            import socket
+            
+            # 检查端口是否已被占用（可能WDA已在运行）
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            result = sock.connect_ex(('localhost', port))
+            sock.close()
+            
+            if result == 0:
+                print(f"  ✅ WDA代理已在运行 (端口 {port})", file=sys.stderr)
+                return True
+            
+            # 启动 WDA 代理
+            print(f"  🚀 启动 WDA 代理...", file=sys.stderr)
+            
+            # 使用 tidevice 启动 WDA（后台运行）
+            self._wda_proxy_process = subprocess.Popen(
+                [sys.executable, '-m', 'tidevice', '-u', device_id, 'wdaproxy', '-B', 
+                 'com.facebook.WebDriverAgentRunner.xctrunner', '--port', str(port)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL
+            )
+            
+            # 等待 WDA 启动
+            import time
+            for i in range(10):  # 最多等待10秒
+                time.sleep(1)
+                sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                result = sock.connect_ex(('localhost', port))
+                sock.close()
+                
+                if result == 0:
+                    print(f"  ✅ WDA代理启动成功 (端口 {port})", file=sys.stderr)
+                    return True
+                    
+                print(f"  ⏳ 等待WDA启动... ({i+1}/10)", file=sys.stderr)
+            
+            print(f"  ❌ WDA代理启动超时", file=sys.stderr)
+            return False
+            
+        except Exception as e:
+            print(f"  ❌ 启动WDA代理失败: {e}", file=sys.stderr)
+            return False
+    
+    def connect(self, device_id: Optional[str] = None, port: int = 8100) -> 'wda.Client':
+        """
+        连接iOS设备
+        
+        Args:
+            device_id: 设备UDID，None则自动选择第一个设备
+            port: WDA代理端口，默认8100
+            
+        Returns:
+            wda.Client 对象（API类似 uiautomator2）
+        """
+        try:
+            import wda
+            
+            # 如果没有指定设备ID，自动选择第一个
+            if device_id is None:
+                devices = self.list_devices()
+                if not devices:
+                    raise RuntimeError(
+                        "未找到连接的iOS设备\n"
+                        "请确保:\n"
+                        "1. iOS设备已通过USB连接\n"
+                        "2. 设备已信任此电脑\n"
+                        "3. tidevice已安装: pip install tidevice"
+                    )
+                device_id = devices[0]['id']
+                print(f"  📱 自动选择设备: {device_id}", file=sys.stderr)
+            
+            self.current_device_id = device_id
+            
+            # 尝试启动 WDA 代理
+            self.start_wda_proxy(device_id, port)
+            
+            # 连接到 WDA
+            self.client = wda.Client(f'http://localhost:{port}')
+            
+            # 测试连接
+            try:
+                status = self.client.status()
+                print(f"  ✅ iOS设备连接成功: {device_id}", file=sys.stderr)
+                print(f"     iOS版本: {status.get('os', {}).get('version', 'Unknown')}", file=sys.stderr)
+            except Exception as e:
+                print(f"  ⚠️  连接可能不稳定: {e}", file=sys.stderr)
+            
+            return self.client
+            
+        except ImportError:
+            raise ImportError(
+                "facebook-wda 未安装\n"
+                "请运行: pip install facebook-wda"
+            )
+        except Exception as e:
+            error_msg = str(e)
+            if "Connection refused" in error_msg:
+                raise RuntimeError(
+                    f"无法连接到WDA (端口 {port})\n"
+                    f"请确保:\n"
+                    f"1. WebDriverAgent 已安装到设备上（需要用Xcode首次编译）\n"
+                    f"2. 运行: tidevice -u {device_id} wdaproxy -B com.facebook.WebDriverAgentRunner.xctrunner\n"
+                    f"3. 或者检查端口 {port} 是否被占用"
+                )
+            raise RuntimeError(f"连接iOS设备失败: {e}")
+    
+    def check_device_status(self) -> Dict:
+        """
+        检查设备连接状态
+        
+        Returns:
+            设备状态信息
+        """
+        if not self.client:
+            return {'connected': False, 'reason': '设备未连接'}
+        
+        try:
+            status = self.client.status()
+            return {
+                'connected': True,
+                'device_id': self.current_device_id,
+                'ios_version': status.get('os', {}).get('version', 'Unknown'),
+                'wda_version': status.get('build', {}).get('productBundleIdentifier', 'Unknown'),
+            }
+        except Exception as e:
+            return {
+                'connected': False,
+                'reason': str(e)
+            }
+    
+    def disconnect(self):
+        """断开设备连接"""
+        if self._wda_proxy_process:
+            try:
+                self._wda_proxy_process.terminate()
+                self._wda_proxy_process.wait(timeout=5)
+            except:
+                pass
+            self._wda_proxy_process = None
+        
+        self.client = None
+        self.current_device_id = None
+        print("  📱 iOS设备已断开连接", file=sys.stderr)
+
+
+
+

mobile_mcp/core/mobile_client.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-移动端客户端 - 类似Web端的MCPClient
+
 
 功能：
 1. 设备连接管理
@@ -28,15 +28,13 @@ 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):
         """
         初始化移动端客户端
         
@@ -44,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}")
         
@@ -165,6 +175,20 @@ 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()
         
@@ -356,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)
@@ -391,12 +417,17 @@ 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
@@ -676,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()
         
@@ -739,14 +795,36 @@ class MobileClient:
         启动App（快速模式：最多等待3秒+截图验证）
         
         Args:
-            package_name: App包名（如 "com.example.app"）
+            package_name: App包名（Android）或Bundle ID（iOS），如 "com.example.app"
             wait_time: 等待App启动的时间（秒）- 默认3秒
-            smart_wait: 是否启用智能等待（自动关闭广告、截图验证）
+            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
@@ -809,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}
@@ -825,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
     
@@ -860,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,
@@ -1094,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)}