PyPI - mobile-mcp-ai - Versions diffs - 2.5.9__py3-none-any.whl → 2.6.5__py3-none-any.whl - Mend

mobile-mcp-ai 2.5.9py3-none-any.whl → 2.6.5py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

mobile_mcp/core/basic_tools_lite.py CHANGED Viewed

@@ -8,6 +8,7 @@
 - 核心功能精简
 - 保留 pytest 脚本生成
 - 支持操作历史记录
+- Token 优化模式（省钱）
 """
 import asyncio
@@ -17,6 +18,19 @@ from pathlib import Path
 from typing import Dict, List, Optional
 from datetime import datetime
+# Token 优化配置（只精简格式，不限制数量，确保准确度）
+try:
+    from mobile_mcp.config import Config
+    TOKEN_OPTIMIZATION = Config.TOKEN_OPTIMIZATION_ENABLED
+    MAX_ELEMENTS = Config.MAX_ELEMENTS_RETURN
+    MAX_SOM_ELEMENTS = Config.MAX_SOM_ELEMENTS_RETURN
+    COMPACT_RESPONSE = Config.COMPACT_RESPONSE
+except ImportError:
+    TOKEN_OPTIMIZATION = True
+    MAX_ELEMENTS = 0  # 0 = 不限制
+    MAX_SOM_ELEMENTS = 0  # 0 = 不限制
+    COMPACT_RESPONSE = True
 class BasicMobileToolsLite:
     """精简版移动端工具"""
@@ -31,6 +45,9 @@ class BasicMobileToolsLite:
         # 操作历史（用于生成 pytest 脚本）
         self.operation_history: List[Dict] = []
+        # 目标应用包名（用于监测应用跳转）
+        self.target_package: Optional[str] = None
     def _is_ios(self) -> bool:
         """判断当前是否为 iOS 平台"""
@@ -45,7 +62,7 @@ class BasicMobileToolsLite:
         return None
     def _record_operation(self, action: str, **kwargs):
-        """记录操作到历史"""
+        """记录操作到历史（旧接口，保持兼容）"""
         record = {
             'action': action,
             'timestamp': datetime.now().isoformat(),
@@ -53,34 +70,232 @@ class BasicMobileToolsLite:
         }
         self.operation_history.append(record)
-    def _get_full_hierarchy(self) -> str:
-        """获取完整的 UI 层级 XML（包含 NAF 元素）
+    def _record_click(self, locator_type: str, locator_value: str,
+                      x_percent: float = 0, y_percent: float = 0,
+                      element_desc: str = '', locator_attr: str = ''):
+        """记录点击操作（标准格式）
+        Args:
+            locator_type: 定位类型 'text' | 'id' | 'percent' | 'coords'
+            locator_value: 定位值（文本内容、resource-id、或坐标描述）
+            x_percent: 百分比 X 坐标（兜底方案）
+            y_percent: 百分比 Y 坐标（兜底方案）
+            element_desc: 元素描述（用于脚本注释）
+            locator_attr: Android 选择器属性 'text'|'textContains'|'description'|'descriptionContains'
+        """
+        record = {
+            'action': 'click',
+            'timestamp': datetime.now().isoformat(),
+            'locator_type': locator_type,
+            'locator_value': locator_value,
+            'locator_attr': locator_attr or locator_type,  # 默认与 type 相同
+            'x_percent': x_percent,
+            'y_percent': y_percent,
+            'element_desc': element_desc or locator_value,
+        }
+        self.operation_history.append(record)
+    def _record_long_press(self, locator_type: str, locator_value: str,
+                           duration: float = 1.0,
+                           x_percent: float = 0, y_percent: float = 0,
+                           element_desc: str = '', locator_attr: str = ''):
+        """记录长按操作（标准格式）"""
+        record = {
+            'action': 'long_press',
+            'timestamp': datetime.now().isoformat(),
+            'locator_type': locator_type,
+            'locator_value': locator_value,
+            'locator_attr': locator_attr or locator_type,
+            'duration': duration,
+            'x_percent': x_percent,
+            'y_percent': y_percent,
+            'element_desc': element_desc or locator_value,
+        }
+        self.operation_history.append(record)
+    def _record_input(self, text: str, locator_type: str = '', locator_value: str = '',
+                      x_percent: float = 0, y_percent: float = 0):
+        """记录输入操作（标准格式）"""
+        record = {
+            'action': 'input',
+            'timestamp': datetime.now().isoformat(),
+            'text': text,
+            'locator_type': locator_type,
+            'locator_value': locator_value,
+            'x_percent': x_percent,
+            'y_percent': y_percent,
+        }
+        self.operation_history.append(record)
+    def _record_swipe(self, direction: str):
+        """记录滑动操作"""
+        record = {
+            'action': 'swipe',
+            'timestamp': datetime.now().isoformat(),
+            'direction': direction,
+        }
+        self.operation_history.append(record)
+    def _record_key(self, key: str):
+        """记录按键操作"""
+        record = {
+            'action': 'press_key',
+            'timestamp': datetime.now().isoformat(),
+            'key': key,
+        }
+        self.operation_history.append(record)
+    def _get_current_package(self) -> Optional[str]:
+        """获取当前前台应用的包名/Bundle ID"""
+        try:
+            if self._is_ios():
+                ios_client = self._get_ios_client()
+                if ios_client and hasattr(ios_client, 'wda'):
+                    app_info = ios_client.wda.session().app_current()
+                    return app_info.get('bundleId')
+            else:
+                info = self.client.u2.app_current()
+                return info.get('package')
+        except Exception:
+            return None
+    def _check_app_switched(self) -> Dict:
+        """检查是否已跳出目标应用
-        优先使用 ADB 直接 dump，比 uiautomator2.dump_hierarchy 更完整
+        Returns:
+            {
+                'switched': bool,  # 是否跳转
+                'current_package': str,  # 当前应用包名
+                'target_package': str,  # 目标应用包名
+                'message': str  # 提示信息
+            }
         """
-        import sys
+        if not self.target_package:
+            return {
+                'switched': False,
+                'current_package': None,
+                'target_package': None,
+                'message': '⚠️ 未设置目标应用，无法监测应用跳转'
+            }
-        if self._is_ios():
-            # iOS 使用 page_source
-            ios_client = self._get_ios_client()
-            if ios_client and hasattr(ios_client, 'wda'):
-                return ios_client.wda.source()
-            return ""
+        current = self._get_current_package()
+        if not current:
+            return {
+                'switched': False,
+                'current_package': None,
+                'target_package': self.target_package,
+                'message': '⚠️ 无法获取当前应用包名'
+            }
+        if current != self.target_package:
+            return {
+                'switched': True,
+                'current_package': current,
+                'target_package': self.target_package,
+                'message': f'⚠️ 应用已跳转！当前应用: {current}，目标应用: {self.target_package}'
+            }
+        return {
+            'switched': False,
+            'current_package': current,
+            'target_package': self.target_package,
+            'message': f'✅ 仍在目标应用: {current}'
+        }
+    def _return_to_target_app(self) -> Dict:
+        """返回到目标应用
+        策略：
+        1. 先按返回键（可能关闭弹窗或返回上一页）
+        2. 如果还在其他应用，启动目标应用
+        3. 验证是否成功返回
+        Returns:
+            {
+                'success': bool,
+                'message': str,
+                'method': str  # 使用的返回方法
+            }
+        """
+        if not self.target_package:
+            return {
+                'success': False,
+                'message': '❌ 未设置目标应用，无法返回',
+                'method': None
+            }
-        # Android: 优先使用 ADB 直接 dump
         try:
-            # 方法1: ADB dump（获取最完整的 UI 树，包括 NAF 元素）
-            self.client.u2.shell('uiautomator dump /sdcard/ui_dump.xml')
-            result = self.client.u2.shell('cat /sdcard/ui_dump.xml')
-            if result and isinstance(result, str) and result.strip().startswith('<?xml'):
-                xml_string = result.strip()
-                self.client.u2.shell('rm /sdcard/ui_dump.xml')
-                return xml_string
+            # 先检查当前应用
+            current = self._get_current_package()
+            if not current:
+                return {
+                    'success': False,
+                    'message': '❌ 无法获取当前应用包名',
+                    'method': None
+                }
+            # 如果已经在目标应用，不需要返回
+            if current == self.target_package:
+                return {
+                    'success': True,
+                    'message': f'✅ 已在目标应用: {self.target_package}',
+                    'method': 'already_in_target'
+                }
+            # 策略1: 先按返回键（可能关闭弹窗或返回）
+            if self._is_ios():
+                ios_client = self._get_ios_client()
+                if ios_client and hasattr(ios_client, 'wda'):
+                    # iOS 返回键
+                    ios_client.wda.press('home')  # iOS 先按 home
+                    time.sleep(0.5)
+                    # 然后启动目标应用
+                    ios_client.wda.app_activate(self.target_package)
+                else:
+                    return {
+                        'success': False,
+                        'message': '❌ iOS 客户端未初始化',
+                        'method': None
+                    }
+            else:
+                # Android: 先按返回键
+                self.client.u2.press('back')
+                time.sleep(0.5)
+                # 检查是否已返回
+                current = self._get_current_package()
+                if current == self.target_package:
+                    return {
+                        'success': True,
+                        'message': f'✅ 已返回目标应用: {self.target_package}（通过返回键）',
+                        'method': 'back_key'
+                    }
+                # 如果还在其他应用，启动目标应用
+                self.client.u2.app_start(self.target_package)
+                time.sleep(1)
+            # 验证是否成功返回
+            current = self._get_current_package()
+            if current == self.target_package:
+                return {
+                    'success': True,
+                    'message': f'✅ 已返回目标应用: {self.target_package}',
+                    'method': 'app_start'
+                }
+            else:
+                return {
+                    'success': False,
+                    'message': f'❌ 返回失败：当前应用仍为 {current}，期望 {self.target_package}',
+                    'method': 'app_start'
+                }
         except Exception as e:
-            print(f"  ⚠️  ADB dump 失败: {e}", file=sys.stderr)
-        # 方法2: 回退到 uiautomator2
-        return self.client.u2.dump_hierarchy(compressed=False)
+            return {
+                'success': False,
+                'message': f'❌ 返回目标应用失败: {e}',
+                'method': None
+            }
     # ==================== 截图 ====================
@@ -134,7 +349,7 @@ class BasicMobileToolsLite:
                     size = ios_client.wda.window_size()
                     screen_width, screen_height = size[0], size[1]
                 else:
-                    return {"success": False, "message": "❌ iOS 客户端未初始化"}
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
                 self.client.u2.screenshot(str(temp_path))
                 info = self.client.u2.info
@@ -185,22 +400,14 @@ class BasicMobileToolsLite:
                 cropped_size = final_path.stat().st_size
+                # 返回结果
                 return {
                     "success": True,
                     "screenshot_path": str(final_path),
-                    "screen_width": screen_width,
-                    "screen_height": screen_height,
                     "image_width": img.width,
                     "image_height": img.height,
                     "crop_offset_x": crop_offset_x,
-                    "crop_offset_y": crop_offset_y,
-                    "file_size": f"{cropped_size/1024:.1f}KB",
-                    "message": f"🔍 局部截图已保存: {final_path}\n"
-                              f"📐 裁剪区域: ({crop_offset_x}, {crop_offset_y}) 起，{img.width}x{img.height} 像素\n"
-                              f"📦 文件大小: {cropped_size/1024:.0f}KB\n"
-                              f"🎯 【坐标换算】AI 返回坐标 (x, y) 后：\n"
-                              f"   实际屏幕坐标 = ({crop_offset_x} + x, {crop_offset_y} + y)\n"
-                              f"   或直接调用 mobile_click_at_coords(x, y, crop_offset_x={crop_offset_x}, crop_offset_y={crop_offset_y})"
+                    "crop_offset_y": crop_offset_y
                 }
             # ========== 情况2：全屏压缩截图 ==========
@@ -253,24 +460,14 @@ class BasicMobileToolsLite:
                 compressed_size = final_path.stat().st_size
                 saved_percent = (1 - compressed_size / original_size) * 100
+                # 返回结果
                 return {
                     "success": True,
                     "screenshot_path": str(final_path),
-                    "screen_width": screen_width,
-                    "screen_height": screen_height,
-                    "original_img_width": original_img_width,    # 截图原始宽度
-                    "original_img_height": original_img_height,  # 截图原始高度
-                    "image_width": image_width,                  # 压缩后宽度（AI 看到的）
-                    "image_height": image_height,                # 压缩后高度（AI 看到的）
-                    "original_size": f"{original_size/1024:.1f}KB",
-                    "compressed_size": f"{compressed_size/1024:.1f}KB",
-                    "saved_percent": f"{saved_percent:.0f}%",
-                    "message": f"📸 截图已保存: {final_path}\n"
-                              f"📐 原始尺寸: {original_img_width}x{original_img_height} → 压缩后: {image_width}x{image_height}\n"
-                              f"📦 已压缩: {original_size/1024:.0f}KB → {compressed_size/1024:.0f}KB (省 {saved_percent:.0f}%)\n"
-                              f"⚠️ 【坐标转换】AI 返回坐标后，请传入：\n"
-                              f"   image_width={image_width}, image_height={image_height},\n"
-                              f"   original_img_width={original_img_width}, original_img_height={original_img_height}"
+                    "image_width": image_width,
+                    "image_height": image_height,
+                    "original_img_width": original_img_width,
+                    "original_img_height": original_img_height
                 }
             # ========== 情况3：全屏不压缩截图 ==========
@@ -284,21 +481,12 @@ class BasicMobileToolsLite:
                 final_path = self.screenshot_dir / filename
                 temp_path.rename(final_path)
-                # 不压缩时，用截图实际尺寸（可能和 screen_width 不同）
+                # 返回结果（不压缩时尺寸相同）
                 return {
                     "success": True,
                     "screenshot_path": str(final_path),
-                    "screen_width": screen_width,
-                    "screen_height": screen_height,
-                    "original_img_width": img.width,   # 截图实际尺寸
-                    "original_img_height": img.height,
-                    "image_width": img.width,          # 未压缩，和原图一样
-                    "image_height": img.height,
-                    "file_size": f"{original_size/1024:.1f}KB",
-                    "message": f"📸 截图已保存: {final_path}\n"
-                              f"📐 截图尺寸: {img.width}x{img.height}\n"
-                              f"📦 文件大小: {original_size/1024:.0f}KB（未压缩）\n"
-                              f"💡 未压缩，坐标可直接使用"
+                    "image_width": img.width,
+                    "image_height": img.height
                 }
         except ImportError:
             # 如果没有 PIL，回退到原始方式（不压缩）
@@ -306,7 +494,7 @@ class BasicMobileToolsLite:
         except Exception as e:
             return {"success": False, "message": f"❌ 截图失败: {e}"}
-    def take_screenshot_with_grid(self, grid_size: int = 100, show_popup_hints: bool = True) -> Dict:
+    def take_screenshot_with_grid(self, grid_size: int = 100, show_popup_hints: bool = False) -> Dict:
         """截图并添加网格坐标标注（用于精确定位元素）
         在截图上绘制网格线和坐标刻度，帮助快速定位元素位置。
@@ -338,7 +526,7 @@ class BasicMobileToolsLite:
                     size = ios_client.wda.window_size()
                     screen_width, screen_height = size[0], size[1]
                 else:
-                    return {"success": False, "message": "❌ iOS 客户端未初始化"}
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
                 self.client.u2.screenshot(str(temp_path))
                 info = self.client.u2.info
@@ -374,45 +562,22 @@ class BasicMobileToolsLite:
                 # 左侧标注 Y 坐标
                 draw.text((2, y + 2), str(y), fill=text_color, font=font_small)
-            # 第3步：检测弹窗并标注
+            # 第3步：检测弹窗并标注（使用严格的置信度检测，避免误识别）
             popup_info = None
             close_positions = []
             if show_popup_hints and not self._is_ios():
                 try:
                     import xml.etree.ElementTree as ET
-                    xml_string = self._get_full_hierarchy()
+                    xml_string = self.client.u2.dump_hierarchy(compressed=False)
                     root = ET.fromstring(xml_string)
-                    # 检测弹窗区域
-                    popup_bounds = None
-                    for elem in root.iter():
-                        bounds_str = elem.attrib.get('bounds', '')
-                        class_name = elem.attrib.get('class', '')
-                        if not bounds_str:
-                            continue
-                        match = re.match(r'\[(\d+),(\d+)\]\[(\d+),(\d+)\]', bounds_str)
-                        if not match:
-                            continue
-                        x1, y1, x2, y2 = map(int, match.groups())
-                        width = x2 - x1
-                        height = y2 - y1
-                        area = width * height
-                        screen_area = screen_width * screen_height
-                        is_container = any(kw in class_name for kw in ['Layout', 'View', 'Dialog', 'Card'])
-                        area_ratio = area / screen_area if screen_area > 0 else 0
-                        is_not_fullscreen = (width < screen_width * 0.98 or height < screen_height * 0.98)
-                        is_reasonable_size = 0.08 < area_ratio < 0.85
-                        if is_container and is_not_fullscreen and is_reasonable_size and y1 > 50:
-                            if popup_bounds is None or area > (popup_bounds[2] - popup_bounds[0]) * (popup_bounds[3] - popup_bounds[1]):
-                                popup_bounds = (x1, y1, x2, y2)
+                    # 使用严格的弹窗检测（置信度 >= 0.6 才认为是弹窗）
+                    popup_bounds, popup_confidence = self._detect_popup_with_confidence(
+                        root, screen_width, screen_height
+                    )
-                    if popup_bounds:
+                    if popup_bounds and popup_confidence >= 0.6:
                         px1, py1, px2, py2 = popup_bounds
                         popup_width = px2 - px1
                         popup_height = py2 - py1
@@ -475,26 +640,16 @@ class BasicMobileToolsLite:
             result = {
                 "success": True,
                 "screenshot_path": str(final_path),
-                "screen_width": screen_width,
-                "screen_height": screen_height,
                 "image_width": img_width,
                 "image_height": img_height,
-                "grid_size": grid_size,
-                "message": f"📸 网格截图已保存: {final_path}\n"
-                          f"📐 尺寸: {img_width}x{img_height}\n"
-                          f"📏 网格间距: {grid_size}px"
+                "grid_size": grid_size
             }
             if popup_info:
-                result["popup_detected"] = True
-                result["popup_bounds"] = popup_info["bounds"]
-                result["close_button_hints"] = close_positions
-                result["message"] += f"\n🎯 检测到弹窗: {popup_info['bounds']}"
-                result["message"] += f"\n💡 可能的关闭按钮位置（绿色圆圈标注）："
-                for pos in close_positions:
-                    result["message"] += f"\n   {pos['priority']}. {pos['name']}: ({pos['x']}, {pos['y']})"
-            else:
-                result["popup_detected"] = False
+                result["popup"] = popup_info["bounds"]
+                # 只返回前3个最可能的关闭按钮位置
+                if close_positions:
+                    result["close_hints"] = [(p['x'], p['y']) for p in close_positions[:3]]
             return result
@@ -531,7 +686,7 @@ class BasicMobileToolsLite:
                     size = ios_client.wda.window_size()
                     screen_width, screen_height = size[0], size[1]
                 else:
-                    return {"success": False, "message": "❌ iOS 客户端未初始化"}
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
                 self.client.u2.screenshot(str(temp_path))
                 info = self.client.u2.info
@@ -558,7 +713,7 @@ class BasicMobileToolsLite:
             else:
                 try:
                     import xml.etree.ElementTree as ET
-                    xml_string = self._get_full_hierarchy()
+                    xml_string = self.client.u2.dump_hierarchy(compressed=False)
                     root = ET.fromstring(xml_string)
                     for elem in root.iter():
@@ -640,44 +795,24 @@ class BasicMobileToolsLite:
                     'index': i + 1,
                     'center': (cx, cy),
                     'bounds': f"[{x1},{y1}][{x2},{y2}]",
-                    'desc': elem['desc']
+                    'desc': elem['desc'],
+                    'text': elem.get('text', ''),
+                    'resource_id': elem.get('resource_id', '')
                 })
-            # 第3.5步：检测弹窗区域（用于标注）
+            # 第3.5步：检测弹窗区域（使用严格的置信度检测，避免误识别普通页面）
             popup_bounds = None
+            popup_confidence = 0
             if not self._is_ios():
                 try:
-                    # 检测弹窗区域
-                    for elem in root.iter():
-                        bounds_str = elem.attrib.get('bounds', '')
-                        class_name = elem.attrib.get('class', '')
-                        if not bounds_str:
-                            continue
-                        match = re.match(r'\[(\d+),(\d+)\]\[(\d+),(\d+)\]', bounds_str)
-                        if not match:
-                            continue
-                        px1, py1, px2, py2 = map(int, match.groups())
-                        p_width = px2 - px1
-                        p_height = py2 - py1
-                        p_area = p_width * p_height
-                        screen_area = screen_width * screen_height
-                        is_container = any(kw in class_name for kw in ['Layout', 'View', 'Dialog', 'Card', 'Frame'])
-                        area_ratio = p_area / screen_area if screen_area > 0 else 0
-                        is_not_fullscreen = (p_width < screen_width * 0.99 or p_height < screen_height * 0.95)
-                        # 放宽面积范围：5% - 95%
-                        is_reasonable_size = 0.05 < area_ratio < 0.95
-                        if is_container and is_not_fullscreen and is_reasonable_size and py1 > 30:
-                            if popup_bounds is None or p_area > (popup_bounds[2] - popup_bounds[0]) * (popup_bounds[3] - popup_bounds[1]):
-                                popup_bounds = (px1, py1, px2, py2)
+                    # 使用严格的弹窗检测（置信度 >= 0.6 才认为是弹窗）
+                    popup_bounds, popup_confidence = self._detect_popup_with_confidence(
+                        root, screen_width, screen_height
+                    )
                     # 如果检测到弹窗，标注弹窗边界（不再猜测X按钮位置）
-                    if popup_bounds:
+                    if popup_bounds and popup_confidence >= 0.6:
                         px1, py1, px2, py2 = popup_bounds
                         # 只画弹窗边框（蓝色），不再猜测X按钮位置
@@ -711,38 +846,15 @@ class BasicMobileToolsLite:
             img.save(str(final_path), "JPEG", quality=85)
             temp_path.unlink()
-            # 构建元素列表文字
-            elements_text = "\n".join([
-                f"  [{e['index']}] {e['desc']} → ({e['center'][0]}, {e['center'][1]})"
-                for e in som_elements[:15]  # 只显示前15个
-            ])
-            if len(som_elements) > 15:
-                elements_text += f"\n  ... 还有 {len(som_elements) - 15} 个元素"
-            # 构建弹窗提示文字
-            hints_text = ""
-            if popup_bounds:
-                hints_text = f"\n🎯 检测到弹窗区域（蓝色边框）\n"
-                hints_text += f"   如需关闭弹窗，请观察图片中的 X 按钮位置\n"
-                hints_text += f"   然后使用 mobile_click_by_percent(x%, y%) 点击"
+            # 返回结果（Token 优化：不返回 elements 列表，已存储在 self._som_elements）
             return {
                 "success": True,
                 "screenshot_path": str(final_path),
                 "screen_width": screen_width,
                 "screen_height": screen_height,
-                "image_width": img_width,
-                "image_height": img_height,
                 "element_count": len(som_elements),
-                "elements": som_elements,
                 "popup_detected": popup_bounds is not None,
-                "popup_bounds": f"[{popup_bounds[0]},{popup_bounds[1]}][{popup_bounds[2]},{popup_bounds[3]}]" if popup_bounds else None,
-                "message": f"📸 SoM 截图已保存: {final_path}\n"
-                          f"🏷️ 已标注 {len(som_elements)} 个可点击元素\n"
-                          f"📋 元素列表：\n{elements_text}{hints_text}\n\n"
-                          f"💡 使用方法：\n"
-                          f"   - 点击标注元素：mobile_click_by_som(编号)\n"
-                          f"   - 点击任意位置：mobile_click_by_percent(x%, y%)"
+                "hint": "查看截图上的编号，用 click_by_som(编号) 点击"
             }
         except ImportError:
@@ -788,14 +900,41 @@ class BasicMobileToolsLite:
                 ios_client = self._get_ios_client()
                 if ios_client and hasattr(ios_client, 'wda'):
                     ios_client.wda.click(cx, cy)
+                    size = ios_client.wda.window_size()
+                    screen_width, screen_height = size[0], size[1]
             else:
                 self.client.u2.click(cx, cy)
+                info = self.client.u2.info
+                screen_width = info.get('displayWidth', 0)
+                screen_height = info.get('displayHeight', 0)
             time.sleep(0.3)
+            # 计算百分比坐标用于跨设备兼容
+            x_percent = round(cx / screen_width * 100, 1) if screen_width > 0 else 0
+            y_percent = round(cy / screen_height * 100, 1) if screen_height > 0 else 0
+            # 使用标准记录格式
+            # 优先使用元素的文本/描述信息，这样生成脚本时可以用文本定位
+            elem_text = target.get('text', '')
+            elem_id = target.get('resource_id', '')
+            elem_desc = target.get('desc', '')
+            if elem_text and not elem_text.startswith('['):  # 排除类似 "[可点击]" 的描述
+                # 有文本，使用文本定位
+                self._record_click('text', elem_text, x_percent, y_percent,
+                                  element_desc=f"[{index}]{elem_desc}", locator_attr='text')
+            elif elem_id:
+                # 有 resource-id，使用 ID 定位
+                self._record_click('id', elem_id, x_percent, y_percent,
+                                  element_desc=f"[{index}]{elem_desc}")
+            else:
+                # 都没有，使用百分比定位
+                self._record_click('percent', f"{x_percent}%,{y_percent}%", x_percent, y_percent,
+                                  element_desc=f"[{index}]{elem_desc}")
             return {
                 "success": True,
-                "message": f"✅ 已点击 [{index}] {target['desc']} → ({cx}, {cy})\n💡 建议：再次截图确认操作是否成功",
                 "clicked": {
                     "index": index,
                     "desc": target['desc'],
@@ -829,7 +968,7 @@ class BasicMobileToolsLite:
                     size = ios_client.wda.window_size()
                     width, height = size[0], size[1]
                 else:
-                    return {"success": False, "message": "❌ iOS 客户端未初始化"}
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
                 self.client.u2.screenshot(str(screenshot_path))
                 info = self.client.u2.info
@@ -907,7 +1046,7 @@ class BasicMobileToolsLite:
                     size = ios_client.wda.window_size()
                     screen_width, screen_height = size[0], size[1]
                 else:
-                    return {"success": False, "message": "❌ iOS 客户端未初始化"}
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
                 info = self.client.u2.info
                 screen_width = info.get('displayWidth', 0)
@@ -951,37 +1090,45 @@ class BasicMobileToolsLite:
             x_percent = round(x / screen_width * 100, 1) if screen_width > 0 else 0
             y_percent = round(y / screen_height * 100, 1) if screen_height > 0 else 0
-            # 记录操作（包含屏幕尺寸和百分比，便于脚本生成时转换）
-            self._record_operation(
-                'click',
-                x=x,
-                y=y,
-                x_percent=x_percent,
-                y_percent=y_percent,
-                screen_width=screen_width,
-                screen_height=screen_height,
-                ref=f"coords_{x}_{y}"
-            )
+            # 使用标准记录格式：坐标点击用百分比作为定位方式（跨分辨率兼容）
+            self._record_click('percent', f"{x_percent}%,{y_percent}%", x_percent, y_percent,
+                              element_desc=f"坐标({x},{y})")
+            # 🎯 关键步骤：检查应用是否跳转，如果跳转则自动返回目标应用
+            app_check = self._check_app_switched()
+            return_result = None
+            if app_check['switched']:
+                # 应用已跳转，尝试返回目标应用
+                return_result = self._return_to_target_app()
+            # 构建返回消息
             if converted:
                 if conversion_type == "crop_offset":
-                    return {
-                        "success": True,
-                        "message": f"✅ 点击成功: ({x}, {y})\n"
-                                  f"   🔍 局部截图坐标转换: ({original_x},{original_y}) + 偏移({crop_offset_x},{crop_offset_y}) → ({x},{y})"
-                    }
+                    msg = f"✅ 点击成功: ({x}, {y})\n" \
+                          f"   🔍 局部截图坐标转换: ({original_x},{original_y}) + 偏移({crop_offset_x},{crop_offset_y}) → ({x},{y})"
                 else:
-                    return {
-                        "success": True,
-                        "message": f"✅ 点击成功: ({x}, {y})\n"
-                                  f"   📐 坐标已转换: ({original_x},{original_y}) → ({x},{y})\n"
-                                  f"   🖼️ 图片尺寸: {image_width}x{image_height} → 屏幕: {screen_width}x{screen_height}"
-                    }
+                    msg = f"✅ 点击成功: ({x}, {y})\n" \
+                          f"   📐 坐标已转换: ({original_x},{original_y}) → ({x},{y})\n" \
+                          f"   🖼️ 图片尺寸: {image_width}x{image_height} → 屏幕: {screen_width}x{screen_height}"
             else:
-                return {
-                    "success": True,
-                    "message": f"✅ 点击成功: ({x}, {y}) [相对位置: {x_percent}%, {y_percent}%]"
-                }
+                msg = f"✅ 点击成功: ({x}, {y}) [相对位置: {x_percent}%, {y_percent}%]"
+            # 如果检测到应用跳转，添加警告和返回结果
+            if app_check['switched']:
+                msg += f"\n{app_check['message']}"
+                if return_result:
+                    if return_result['success']:
+                        msg += f"\n{return_result['message']}"
+                    else:
+                        msg += f"\n❌ 自动返回失败: {return_result['message']}"
+            return {
+                "success": True,
+                "message": msg,
+                "app_check": app_check,
+                "return_to_app": return_result
+            }
         except Exception as e:
             return {"success": False, "message": f"❌ 点击失败: {e}"}
@@ -1014,14 +1161,14 @@ class BasicMobileToolsLite:
                     size = ios_client.wda.window_size()
                     width, height = size[0], size[1]
                 else:
-                    return {"success": False, "message": "❌ iOS 客户端未初始化"}
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
                 info = self.client.u2.info
                 width = info.get('displayWidth', 0)
                 height = info.get('displayHeight', 0)
             if width == 0 or height == 0:
-                return {"success": False, "message": "❌ 无法获取屏幕尺寸"}
+                return {"success": False, "msg": "无法获取屏幕尺寸"}
             # 第2步：百分比转像素坐标
             # 公式：像素 = 屏幕尺寸 × (百分比 / 100)
@@ -1036,30 +1183,29 @@ class BasicMobileToolsLite:
             time.sleep(0.3)
-            # 第4步：记录操作（同时记录百分比和像素）
-            self._record_operation(
-                'click',
-                x=x,
-                y=y,
-                x_percent=x_percent,
-                y_percent=y_percent,
-                screen_width=width,
-                screen_height=height,
-                ref=f"percent_{x_percent}_{y_percent}"
-            )
+            # 第4步：使用标准记录格式
+            self._record_click('percent', f"{x_percent}%,{y_percent}%", x_percent, y_percent,
+                              element_desc=f"百分比({x_percent}%,{y_percent}%)")
             return {
                 "success": True,
-                "message": f"✅ 百分比点击成功: ({x_percent}%, {y_percent}%) → 像素({x}, {y})",
-                "screen_size": {"width": width, "height": height},
-                "percent": {"x": x_percent, "y": y_percent},
                 "pixel": {"x": x, "y": y}
             }
         except Exception as e:
             return {"success": False, "message": f"❌ 百分比点击失败: {e}"}
-    def click_by_text(self, text: str, timeout: float = 3.0) -> Dict:
-        """通过文本点击 - 先查 XML 树，再精准匹配"""
+    def click_by_text(self, text: str, timeout: float = 3.0, position: Optional[str] = None,
+                       verify: Optional[str] = None) -> Dict:
+        """通过文本点击 - 先查 XML 树，再精准匹配
+        Args:
+            text: 元素的文本内容
+            timeout: 超时时间
+            position: 位置信息，当有多个相同文案时使用。支持：
+                - 垂直方向: "top"/"upper"/"上", "bottom"/"lower"/"下", "middle"/"center"/"中"
+                - 水平方向: "left"/"左", "right"/"右", "center"/"中"
+            verify: 可选，点击后验证的文本。如果指定，会检查该文本是否出现在页面上
+        """
         try:
             if self._is_ios():
                 ios_client = self._get_ios_client()
@@ -1070,19 +1216,53 @@ class BasicMobileToolsLite:
                     if elem.exists:
                         elem.click()
                         time.sleep(0.3)
-                        self._record_operation('click', element=text, ref=text)
-                        return {"success": True, "message": f"✅ 点击成功: '{text}'"}
-                    return {"success": False, "message": f"❌ 文本不存在: {text}"}
+                        self._record_click('text', text, element_desc=text, locator_attr='text')
+                        # 验证逻辑
+                        if verify:
+                            return self._verify_after_click(verify, ios=True)
+                        # 返回页面文本摘要，方便确认页面变化
+                        page_texts = self._get_page_texts(10)
+                        return {"success": True, "page_texts": page_texts}
+                    # 控件树找不到，提示用视觉识别
+                    return {"success": False, "fallback": "vision", "msg": f"未找到'{text}'，用截图点击"}
+                else:
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
+                # 获取屏幕尺寸用于计算百分比
+                screen_width, screen_height = self.client.u2.window_size()
                 # 🔍 先查 XML 树，找到元素及其属性
-                found_elem = self._find_element_in_tree(text)
+                found_elem = self._find_element_in_tree(text, position=position)
                 if found_elem:
                     attr_type = found_elem['attr_type']
                     attr_value = found_elem['attr_value']
                     bounds = found_elem.get('bounds')
-                    # 根据找到的属性类型，使用对应的选择器
+                    # 计算百分比坐标作为兜底
+                    x_pct, y_pct = 0, 0
+                    if bounds:
+                        cx = (bounds[0] + bounds[2]) // 2
+                        cy = (bounds[1] + bounds[3]) // 2
+                        x_pct = round(cx / screen_width * 100, 1)
+                        y_pct = round(cy / screen_height * 100, 1)
+                    # 如果有位置参数，直接使用坐标点击
+                    if position and bounds:
+                        x = (bounds[0] + bounds[2]) // 2
+                        y = (bounds[1] + bounds[3]) // 2
+                        self.client.u2.click(x, y)
+                        time.sleep(0.3)
+                        self._record_click('text', attr_value, x_pct, y_pct,
+                                          element_desc=f"{text}({position})", locator_attr=attr_type)
+                        # 验证逻辑
+                        if verify:
+                            return self._verify_after_click(verify)
+                        # 返回页面文本摘要
+                        page_texts = self._get_page_texts(10)
+                        return {"success": True, "page_texts": page_texts}
+                    # 没有位置参数时，使用选择器定位
                     if attr_type == 'text':
                         elem = self.client.u2(text=attr_value)
                     elif attr_type == 'textContains':
@@ -1097,33 +1277,98 @@ class BasicMobileToolsLite:
                     if elem and elem.exists(timeout=1):
                         elem.click()
                         time.sleep(0.3)
-                        self._record_operation('click', element=text, ref=f"{attr_type}:{attr_value}")
-                        return {"success": True, "message": f"✅ 点击成功({attr_type}): '{text}'"}
+                        self._record_click('text', attr_value, x_pct, y_pct,
+                                          element_desc=text, locator_attr=attr_type)
+                        # 验证逻辑
+                        if verify:
+                            return self._verify_after_click(verify)
+                        # 返回页面文本摘要
+                        page_texts = self._get_page_texts(10)
+                        return {"success": True, "page_texts": page_texts}
-                    # 如果选择器失败，用坐标兜底
+                    # 选择器失败，用坐标兜底
                     if bounds:
                         x = (bounds[0] + bounds[2]) // 2
                         y = (bounds[1] + bounds[3]) // 2
                         self.client.u2.click(x, y)
                         time.sleep(0.3)
-                        self._record_operation('click', element=text, x=x, y=y, ref=f"coords:{x},{y}")
-                        return {"success": True, "message": f"✅ 点击成功(坐标兜底): '{text}' @ ({x},{y})"}
+                        self._record_click('percent', f"{x_pct}%,{y_pct}%", x_pct, y_pct,
+                                          element_desc=text)
+                        # 验证逻辑
+                        if verify:
+                            return self._verify_after_click(verify)
+                        # 返回页面文本摘要
+                        page_texts = self._get_page_texts(10)
+                        return {"success": True, "page_texts": page_texts}
-                return {"success": False, "message": f"❌ 文本不存在: {text}"}
+                # 控件树找不到，提示用视觉识别
+                return {"success": False, "fallback": "vision", "msg": f"未找到'{text}'，用截图点击"}
         except Exception as e:
-            return {"success": False, "message": f"❌ 点击失败: {e}"}
+            return {"success": False, "msg": str(e)}
+    def _verify_after_click(self, verify_text: str, ios: bool = False, timeout: float = 2.0) -> Dict:
+        """点击后验证期望文本是否出现
+        Args:
+            verify_text: 期望出现的文本
+            ios: 是否是 iOS 设备
+            timeout: 验证超时时间
+        Returns:
+            {"success": True, "verified": True/False, "hint": "..."}
+        """
+        time.sleep(0.5)  # 等待页面更新
+        try:
+            if ios:
+                ios_client = self._get_ios_client()
+                if ios_client and hasattr(ios_client, 'wda'):
+                    exists = ios_client.wda(name=verify_text).exists or \
+                             ios_client.wda(label=verify_text).exists
+                else:
+                    exists = False
+            else:
+                # Android: 检查文本或包含文本
+                exists = self.client.u2(text=verify_text).exists(timeout=timeout) or \
+                         self.client.u2(textContains=verify_text).exists(timeout=0.5) or \
+                         self.client.u2(description=verify_text).exists(timeout=0.5)
+            if exists:
+                return {"success": True, "verified": True}
+            else:
+                # 验证失败，提示可以截图确认
+                return {
+                    "success": True,  # 点击本身成功
+                    "verified": False,
+                    "expect": verify_text,
+                    "hint": "验证失败，可截图确认"
+                }
+        except Exception as e:
+            return {"success": True, "verified": False, "hint": f"验证异常: {e}"}
-    def _find_element_in_tree(self, text: str) -> Optional[Dict]:
-        """在 XML 树中查找包含指定文本的元素（使用完整 UI 层级）"""
+    def _find_element_in_tree(self, text: str, position: Optional[str] = None) -> Optional[Dict]:
+        """在 XML 树中查找包含指定文本的元素，优先返回可点击的元素
+        Args:
+            text: 要查找的文本
+            position: 位置信息，用于在有多个相同文案时筛选
+        """
         try:
-            xml = self._get_full_hierarchy()
+            xml = self.client.u2.dump_hierarchy(compressed=False)
             import xml.etree.ElementTree as ET
             root = ET.fromstring(xml)
+            # 获取屏幕尺寸
+            screen_width, screen_height = self.client.u2.window_size()
+            # 存储所有匹配的元素（包括不可点击的）
+            matched_elements = []
             for elem in root.iter():
                 elem_text = elem.attrib.get('text', '')
                 elem_desc = elem.attrib.get('content-desc', '')
                 bounds_str = elem.attrib.get('bounds', '')
+                clickable = elem.attrib.get('clickable', 'false').lower() == 'true'
                 # 解析 bounds
                 bounds = None
@@ -1133,36 +1378,113 @@ class BasicMobileToolsLite:
                     if len(match) == 4:
                         bounds = [int(x) for x in match]
+                # 判断是否匹配
+                is_match = False
+                attr_type = None
+                attr_value = None
                 # 精确匹配 text
                 if elem_text == text:
-                    return {'attr_type': 'text', 'attr_value': text, 'bounds': bounds}
+                    is_match = True
+                    attr_type = 'text'
+                    attr_value = text
                 # 精确匹配 content-desc
-                if elem_desc == text:
-                    return {'attr_type': 'description', 'attr_value': text, 'bounds': bounds}
+                elif elem_desc == text:
+                    is_match = True
+                    attr_type = 'description'
+                    attr_value = text
                 # 模糊匹配 text
-                if text in elem_text:
-                    return {'attr_type': 'textContains', 'attr_value': text, 'bounds': bounds}
+                elif text in elem_text:
+                    is_match = True
+                    attr_type = 'textContains'
+                    attr_value = text
                 # 模糊匹配 content-desc
-                if text in elem_desc:
-                    return {'attr_type': 'descriptionContains', 'attr_value': text, 'bounds': bounds}
+                elif text in elem_desc:
+                    is_match = True
+                    attr_type = 'descriptionContains'
+                    attr_value = text
+                if is_match and bounds:
+                    # 计算元素的中心点坐标
+                    center_x = (bounds[0] + bounds[2]) / 2
+                    center_y = (bounds[1] + bounds[3]) / 2
+                    matched_elements.append({
+                        'attr_type': attr_type,
+                        'attr_value': attr_value,
+                        'bounds': bounds,
+                        'clickable': clickable,
+                        'center_x': center_x,
+                        'center_y': center_y
+                    })
+            if not matched_elements:
+                return None
+            # 如果有位置信息，根据位置筛选
+            if position and len(matched_elements) > 1:
+                position_lower = position.lower()
+                # 根据位置信息排序
+                if position_lower in ['top', 'upper', '上', '上方']:
+                    # 选择 y 坐标最小的（最上面的）
+                    matched_elements = sorted(matched_elements, key=lambda x: x['center_y'])
+                elif position_lower in ['bottom', 'lower', '下', '下方', '底部']:
+                    # 选择 y 坐标最大的（最下面的）
+                    matched_elements = sorted(matched_elements, key=lambda x: x['center_y'], reverse=True)
+                elif position_lower in ['left', '左', '左侧']:
+                    # 选择 x 坐标最小的（最左边的）
+                    matched_elements = sorted(matched_elements, key=lambda x: x['center_x'])
+                elif position_lower in ['right', '右', '右侧']:
+                    # 选择 x 坐标最大的（最右边的）
+                    matched_elements = sorted(matched_elements, key=lambda x: x['center_x'], reverse=True)
+                elif position_lower in ['middle', 'center', '中', '中间']:
+                    # 选择最接近屏幕中心的
+                    screen_mid_x = screen_width / 2
+                    screen_mid_y = screen_height / 2
+                    matched_elements = sorted(
+                        matched_elements,
+                        key=lambda x: abs(x['center_x'] - screen_mid_x) + abs(x['center_y'] - screen_mid_y)
+                    )
+            # 如果有位置信息，优先返回排序后的第一个元素（最符合位置要求的）
+            # 如果没有位置信息，优先返回可点击的元素
+            if position and matched_elements:
+                # 有位置信息时，直接返回排序后的第一个（最符合位置要求的）
+                first_match = matched_elements[0]
+                return {
+                    'attr_type': first_match['attr_type'],
+                    'attr_value': first_match['attr_value'],
+                    'bounds': first_match['bounds']
+                }
+            # 没有位置信息时，优先返回可点击的元素
+            for match in matched_elements:
+                if match['clickable']:
+                    return {
+                        'attr_type': match['attr_type'],
+                        'attr_value': match['attr_value'],
+                        'bounds': match['bounds']
+                    }
+            # 如果没有可点击的元素，直接返回第一个匹配元素的 bounds（使用坐标点击）
+            if matched_elements:
+                first_match = matched_elements[0]
+                return {
+                    'attr_type': first_match['attr_type'],
+                    'attr_value': first_match['attr_value'],
+                    'bounds': first_match['bounds']
+                }
             return None
-        except Exception:
+        except Exception as e:
+            import traceback
+            traceback.print_exc()
             return None
     def click_by_id(self, resource_id: str, index: int = 0) -> Dict:
-        """通过 resource-id 点击（支持点击第 N 个元素）
-        Args:
-            resource_id: 元素的 resource-id
-            index: 第几个元素（从 0 开始），默认 0 表示第一个
-        """
+        """通过 resource-id 点击"""
         try:
-            index_desc = f"[{index}]" if index > 0 else ""
             if self._is_ios():
                 ios_client = self._get_ios_client()
                 if ios_client and hasattr(ios_client, 'wda'):
@@ -1170,31 +1492,31 @@ class BasicMobileToolsLite:
                     if not elem.exists:
                         elem = ios_client.wda(name=resource_id)
                     if elem.exists:
-                        # 获取所有匹配的元素
                         elements = elem.find_elements()
                         if index < len(elements):
                             elements[index].click()
                             time.sleep(0.3)
-                            self._record_operation('click', element=f"{resource_id}{index_desc}", ref=resource_id, index=index)
-                            return {"success": True, "message": f"✅ 点击成功: {resource_id}{index_desc}"}
+                            self._record_click('id', resource_id, element_desc=resource_id)
+                            return {"success": True}
                         else:
-                            return {"success": False, "message": f"❌ 索引超出范围: 找到 {len(elements)} 个元素，但请求索引 {index}"}
-                    return {"success": False, "message": f"❌ 元素不存在: {resource_id}"}
+                            return {"success": False, "msg": f"索引{index}超出范围(共{len(elements)}个)"}
+                    return {"success": False, "fallback": "vision", "msg": f"未找到ID'{resource_id}'"}
+                else:
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
                 elem = self.client.u2(resourceId=resource_id)
                 if elem.exists(timeout=0.5):
-                    # 获取匹配元素数量
                     count = elem.count
                     if index < count:
                         elem[index].click()
                         time.sleep(0.3)
-                        self._record_operation('click', element=f"{resource_id}{index_desc}", ref=resource_id, index=index)
-                        return {"success": True, "message": f"✅ 点击成功: {resource_id}{index_desc}" + (f" (共 {count} 个)" if count > 1 else "")}
+                        self._record_click('id', resource_id, element_desc=resource_id)
+                        return {"success": True}
                     else:
-                        return {"success": False, "message": f"❌ 索引超出范围: 找到 {count} 个元素，但请求索引 {index}"}
-                return {"success": False, "message": f"❌ 元素不存在: {resource_id}"}
+                        return {"success": False, "msg": f"索引{index}超出范围(共{count}个)"}
+                return {"success": False, "fallback": "vision", "msg": f"未找到ID'{resource_id}'"}
         except Exception as e:
-            return {"success": False, "message": f"❌ 点击失败: {e}"}
+            return {"success": False, "msg": str(e)}
     # ==================== 长按操作 ====================
@@ -1228,7 +1550,7 @@ class BasicMobileToolsLite:
                     size = ios_client.wda.window_size()
                     screen_width, screen_height = size[0], size[1]
                 else:
-                    return {"success": False, "message": "❌ iOS 客户端未初始化"}
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
                 info = self.client.u2.info
                 screen_width = info.get('displayWidth', 0)
@@ -1275,38 +1597,17 @@ class BasicMobileToolsLite:
             x_percent = round(x / screen_width * 100, 1) if screen_width > 0 else 0
             y_percent = round(y / screen_height * 100, 1) if screen_height > 0 else 0
-            # 记录操作
-            self._record_operation(
-                'long_press',
-                x=x,
-                y=y,
-                x_percent=x_percent,
-                y_percent=y_percent,
-                duration=duration,
-                screen_width=screen_width,
-                screen_height=screen_height,
-                ref=f"coords_{x}_{y}"
-            )
+            # 使用标准记录格式
+            self._record_long_press('percent', f"{x_percent}%,{y_percent}%", duration,
+                                   x_percent, y_percent, element_desc=f"坐标({x},{y})")
             if converted:
                 if conversion_type == "crop_offset":
-                    return {
-                        "success": True,
-                        "message": f"✅ 长按成功: ({x}, {y}) 持续 {duration}s\n"
-                                  f"   🔍 局部截图坐标转换: ({original_x},{original_y}) + 偏移({crop_offset_x},{crop_offset_y}) → ({x},{y})"
-                    }
+                    return {"success": True}
                 else:
-                    return {
-                        "success": True,
-                        "message": f"✅ 长按成功: ({x}, {y}) 持续 {duration}s\n"
-                                  f"   📐 坐标已转换: ({original_x},{original_y}) → ({x},{y})\n"
-                                  f"   🖼️ 图片尺寸: {image_width}x{image_height} → 屏幕: {screen_width}x{screen_height}"
-                    }
+                    return {"success": True}
             else:
-                return {
-                    "success": True,
-                    "message": f"✅ 长按成功: ({x}, {y}) 持续 {duration}s [相对位置: {x_percent}%, {y_percent}%]"
-                }
+                return {"success": True}
         except Exception as e:
             return {"success": False, "message": f"❌ 长按失败: {e}"}
@@ -1335,14 +1636,14 @@ class BasicMobileToolsLite:
                     size = ios_client.wda.window_size()
                     width, height = size[0], size[1]
                 else:
-                    return {"success": False, "message": "❌ iOS 客户端未初始化"}
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
                 info = self.client.u2.info
                 width = info.get('displayWidth', 0)
                 height = info.get('displayHeight', 0)
             if width == 0 or height == 0:
-                return {"success": False, "message": "❌ 无法获取屏幕尺寸"}
+                return {"success": False, "msg": "无法获取屏幕尺寸"}
             # 第2步：百分比转像素坐标
             x = int(width * x_percent / 100)
@@ -1360,26 +1661,11 @@ class BasicMobileToolsLite:
             time.sleep(0.3)
-            # 第4步：记录操作
-            self._record_operation(
-                'long_press',
-                x=x,
-                y=y,
-                x_percent=x_percent,
-                y_percent=y_percent,
-                duration=duration,
-                screen_width=width,
-                screen_height=height,
-                ref=f"percent_{x_percent}_{y_percent}"
-            )
+            # 第4步：使用标准记录格式
+            self._record_long_press('percent', f"{x_percent}%,{y_percent}%", duration,
+                                   x_percent, y_percent, element_desc=f"百分比({x_percent}%,{y_percent}%)")
-            return {
-                "success": True,
-                "message": f"✅ 百分比长按成功: ({x_percent}%, {y_percent}%) → 像素({x}, {y}) 持续 {duration}s",
-                "screen_size": {"width": width, "height": height},
-                "percent": {"x": x_percent, "y": y_percent},
-                "pixel": {"x": x, "y": y},
-                "duration": duration
+            return {"success": True
             }
         except Exception as e:
             return {"success": False, "message": f"❌ 百分比长按失败: {e}"}
@@ -1408,10 +1694,13 @@ class BasicMobileToolsLite:
                         else:
                             ios_client.wda.swipe(x, y, x, y, duration=duration)
                         time.sleep(0.3)
-                        self._record_operation('long_press', element=text, duration=duration, ref=text)
-                        return {"success": True, "message": f"✅ 长按成功: '{text}' 持续 {duration}s"}
-                    return {"success": False, "message": f"❌ 文本不存在: {text}"}
+                        self._record_long_press('text', text, duration, element_desc=text, locator_attr='text')
+                        return {"success": True}
+                    return {"success": False, "msg": f"未找到'{text}'"}
             else:
+                # 获取屏幕尺寸用于计算百分比
+                screen_width, screen_height = self.client.u2.window_size()
                 # 先查 XML 树，找到元素
                 found_elem = self._find_element_in_tree(text)
@@ -1420,6 +1709,14 @@ class BasicMobileToolsLite:
                     attr_value = found_elem['attr_value']
                     bounds = found_elem.get('bounds')
+                    # 计算百分比坐标作为兜底
+                    x_pct, y_pct = 0, 0
+                    if bounds:
+                        cx = (bounds[0] + bounds[2]) // 2
+                        cy = (bounds[1] + bounds[3]) // 2
+                        x_pct = round(cx / screen_width * 100, 1)
+                        y_pct = round(cy / screen_height * 100, 1)
                     # 根据找到的属性类型，使用对应的选择器
                     if attr_type == 'text':
                         elem = self.client.u2(text=attr_value)
@@ -1435,8 +1732,9 @@ class BasicMobileToolsLite:
                     if elem and elem.exists(timeout=1):
                         elem.long_click(duration=duration)
                         time.sleep(0.3)
-                        self._record_operation('long_press', element=text, duration=duration, ref=f"{attr_type}:{attr_value}")
-                        return {"success": True, "message": f"✅ 长按成功({attr_type}): '{text}' 持续 {duration}s"}
+                        self._record_long_press('text', attr_value, duration, x_pct, y_pct,
+                                               element_desc=text, locator_attr=attr_type)
+                        return {"success": True}
                     # 如果选择器失败，用坐标兜底
                     if bounds:
@@ -1444,10 +1742,11 @@ class BasicMobileToolsLite:
                         y = (bounds[1] + bounds[3]) // 2
                         self.client.u2.long_click(x, y, duration=duration)
                         time.sleep(0.3)
-                        self._record_operation('long_press', element=text, x=x, y=y, duration=duration, ref=f"coords:{x},{y}")
-                        return {"success": True, "message": f"✅ 长按成功(坐标兜底): '{text}' @ ({x},{y}) 持续 {duration}s"}
+                        self._record_long_press('percent', f"{x_pct}%,{y_pct}%", duration, x_pct, y_pct,
+                                               element_desc=text)
+                        return {"success": True}
-                return {"success": False, "message": f"❌ 文本不存在: {text}"}
+                return {"success": False, "msg": f"未找到'{text}'"}
         except Exception as e:
             return {"success": False, "message": f"❌ 长按失败: {e}"}
@@ -1474,17 +1773,17 @@ class BasicMobileToolsLite:
                         else:
                             ios_client.wda.swipe(x, y, x, y, duration=duration)
                         time.sleep(0.3)
-                        self._record_operation('long_press', element=resource_id, duration=duration, ref=resource_id)
-                        return {"success": True, "message": f"✅ 长按成功: {resource_id} 持续 {duration}s"}
-                    return {"success": False, "message": f"❌ 元素不存在: {resource_id}"}
+                        self._record_long_press('id', resource_id, duration, element_desc=resource_id)
+                        return {"success": True}
+                    return {"success": False, "msg": f"未找到'{resource_id}'"}
             else:
                 elem = self.client.u2(resourceId=resource_id)
                 if elem.exists(timeout=0.5):
                     elem.long_click(duration=duration)
                     time.sleep(0.3)
-                    self._record_operation('long_press', element=resource_id, duration=duration, ref=resource_id)
+                    self._record_long_press('id', resource_id, duration, element_desc=resource_id)
                     return {"success": True, "message": f"✅ 长按成功: {resource_id} 持续 {duration}s"}
-                return {"success": False, "message": f"❌ 元素不存在: {resource_id}"}
+                return {"success": False, "msg": f"未找到'{resource_id}'"}
         except Exception as e:
             return {"success": False, "message": f"❌ 长按失败: {e}"}
@@ -1509,8 +1808,29 @@ class BasicMobileToolsLite:
                     if elem.exists:
                         elem.set_text(text)
                         time.sleep(0.3)
-                        self._record_operation('input', element=resource_id, ref=resource_id, text=text)
-                        return {"success": True, "message": f"✅ 输入成功: '{text}'"}
+                        self._record_input(text, 'id', resource_id)
+                        # 🎯 关键步骤：检查应用是否跳转，如果跳转则自动返回目标应用
+                        app_check = self._check_app_switched()
+                        return_result = None
+                        if app_check['switched']:
+                            return_result = self._return_to_target_app()
+                        msg = f"✅ 输入成功: '{text}'"
+                        if app_check['switched']:
+                            msg += f"\n{app_check['message']}"
+                            if return_result:
+                                if return_result['success']:
+                                    msg += f"\n{return_result['message']}"
+                                else:
+                                    msg += f"\n❌ 自动返回失败: {return_result['message']}"
+                        return {
+                            "success": True,
+                            "message": msg,
+                            "app_check": app_check,
+                            "return_to_app": return_result
+                        }
                     return {"success": False, "message": f"❌ 输入框不存在: {resource_id}"}
             else:
                 elements = self.client.u2(resourceId=resource_id)
@@ -1523,8 +1843,29 @@ class BasicMobileToolsLite:
                     if count == 1:
                         elements.set_text(text)
                         time.sleep(0.3)
-                        self._record_operation('input', element=resource_id, ref=resource_id, text=text)
-                        return {"success": True, "message": f"✅ 输入成功: '{text}'"}
+                        self._record_input(text, 'id', resource_id)
+                        # 🎯 关键步骤：检查应用是否跳转，如果跳转则自动返回目标应用
+                        app_check = self._check_app_switched()
+                        return_result = None
+                        if app_check['switched']:
+                            return_result = self._return_to_target_app()
+                        msg = f"✅ 输入成功: '{text}'"
+                        if app_check['switched']:
+                            msg += f"\n{app_check['message']}"
+                            if return_result:
+                                if return_result['success']:
+                                    msg += f"\n{return_result['message']}"
+                                else:
+                                    msg += f"\n❌ 自动返回失败: {return_result['message']}"
+                        return {
+                            "success": True,
+                            "message": msg,
+                            "app_check": app_check,
+                            "return_to_app": return_result
+                        }
                     # 多个相同 ID（<=5个），尝试智能选择
                     if count <= 5:
@@ -1536,15 +1877,57 @@ class BasicMobileToolsLite:
                                 if info.get('editable') or info.get('focusable'):
                                     elem.set_text(text)
                                     time.sleep(0.3)
-                                    self._record_operation('input', element=resource_id, ref=resource_id, text=text)
-                                    return {"success": True, "message": f"✅ 输入成功: '{text}'"}
+                                    self._record_input(text, 'id', resource_id)
+                                    # 🎯 关键步骤：检查应用是否跳转，如果跳转则自动返回目标应用
+                                    app_check = self._check_app_switched()
+                                    return_result = None
+                                    if app_check['switched']:
+                                        return_result = self._return_to_target_app()
+                                    msg = f"✅ 输入成功: '{text}'"
+                                    if app_check['switched']:
+                                        msg += f"\n{app_check['message']}"
+                                        if return_result:
+                                            if return_result['success']:
+                                                msg += f"\n{return_result['message']}"
+                                            else:
+                                                msg += f"\n❌ 自动返回失败: {return_result['message']}"
+                                    return {
+                                        "success": True,
+                                        "message": msg,
+                                        "app_check": app_check,
+                                        "return_to_app": return_result
+                                    }
                             except:
                                 continue
                         # 没找到可编辑的，用第一个
                         elements[0].set_text(text)
                         time.sleep(0.3)
-                        self._record_operation('input', element=resource_id, ref=resource_id, text=text)
-                        return {"success": True, "message": f"✅ 输入成功: '{text}'"}
+                        self._record_input(text, 'id', resource_id)
+                        # 🎯 关键步骤：检查应用是否跳转，如果跳转则自动返回目标应用
+                        app_check = self._check_app_switched()
+                        return_result = None
+                        if app_check['switched']:
+                            return_result = self._return_to_target_app()
+                        msg = f"✅ 输入成功: '{text}'"
+                        if app_check['switched']:
+                            msg += f"\n{app_check['message']}"
+                            if return_result:
+                                if return_result['success']:
+                                    msg += f"\n{return_result['message']}"
+                                else:
+                                    msg += f"\n❌ 自动返回失败: {return_result['message']}"
+                        return {
+                            "success": True,
+                            "message": msg,
+                            "app_check": app_check,
+                            "return_to_app": return_result
+                        }
                 # ID 不可靠（不存在或太多），改用 EditText 类型定位
                 edit_texts = self.client.u2(className='android.widget.EditText')
@@ -1553,8 +1936,29 @@ class BasicMobileToolsLite:
                     if et_count == 1:
                         edit_texts.set_text(text)
                         time.sleep(0.3)
-                        self._record_operation('input', element='EditText', ref='EditText', text=text)
-                        return {"success": True, "message": f"✅ 输入成功: '{text}' (通过 EditText 定位)"}
+                        self._record_input(text, 'class', 'EditText')
+                        # 🎯 关键步骤：检查应用是否跳转，如果跳转则自动返回目标应用
+                        app_check = self._check_app_switched()
+                        return_result = None
+                        if app_check['switched']:
+                            return_result = self._return_to_target_app()
+                        msg = f"✅ 输入成功: '{text}' (通过 EditText 定位)"
+                        if app_check['switched']:
+                            msg += f"\n{app_check['message']}"
+                            if return_result:
+                                if return_result['success']:
+                                    msg += f"\n{return_result['message']}"
+                                else:
+                                    msg += f"\n❌ 自动返回失败: {return_result['message']}"
+                        return {
+                            "success": True,
+                            "message": msg,
+                            "app_check": app_check,
+                            "return_to_app": return_result
+                        }
                     # 多个 EditText，选择最靠上的
                     best_elem = None
@@ -1572,9 +1976,30 @@ class BasicMobileToolsLite:
                     if best_elem:
                         best_elem.set_text(text)
                         time.sleep(0.3)
-                        self._record_operation('input', element='EditText', ref='EditText', text=text)
-                        return {"success": True, "message": f"✅ 输入成功: '{text}' (通过 EditText 定位，选择最顶部的)"}
+                        self._record_input(text, 'class', 'EditText')
+                        # 🎯 关键步骤：检查应用是否跳转，如果跳转则自动返回目标应用
+                        app_check = self._check_app_switched()
+                        return_result = None
+                        if app_check['switched']:
+                            return_result = self._return_to_target_app()
+                        msg = f"✅ 输入成功: '{text}' (通过 EditText 定位，选择最顶部的)"
+                        if app_check['switched']:
+                            msg += f"\n{app_check['message']}"
+                            if return_result:
+                                if return_result['success']:
+                                    msg += f"\n{return_result['message']}"
+                                else:
+                                    msg += f"\n❌ 自动返回失败: {return_result['message']}"
+                        return {
+                            "success": True,
+                            "message": msg,
+                            "app_check": app_check,
+                            "return_to_app": return_result
+                        }
                 return {"success": False, "message": f"❌ 输入框不存在: {resource_id}"}
         except Exception as e:
@@ -1615,17 +2040,32 @@ class BasicMobileToolsLite:
             x_percent = round(x / screen_width * 100, 1) if screen_width > 0 else 0
             y_percent = round(y / screen_height * 100, 1) if screen_height > 0 else 0
-            self._record_operation(
-                'input',
-                x=x,
-                y=y,
-                x_percent=x_percent,
-                y_percent=y_percent,
-                ref=f"coords_{x}_{y}",
-                text=text
-            )
+            # 使用标准记录格式
+            self._record_input(text, 'percent', f"{x_percent}%,{y_percent}%", x_percent, y_percent)
-            return {"success": True, "message": f"✅ 输入成功: ({x}, {y}) [相对位置: {x_percent}%, {y_percent}%] -> '{text}'"}
+            # 🎯 关键步骤：检查应用是否跳转，如果跳转则自动返回目标应用
+            app_check = self._check_app_switched()
+            return_result = None
+            if app_check['switched']:
+                # 应用已跳转，尝试返回目标应用
+                return_result = self._return_to_target_app()
+            msg = f"✅ 输入成功: ({x}, {y}) [相对位置: {x_percent}%, {y_percent}%] -> '{text}'"
+            if app_check['switched']:
+                msg += f"\n{app_check['message']}"
+                if return_result:
+                    if return_result['success']:
+                        msg += f"\n{return_result['message']}"
+                    else:
+                        msg += f"\n❌ 自动返回失败: {return_result['message']}"
+            return {
+                "success": True,
+                "message": msg,
+                "app_check": app_check,
+                "return_to_app": return_result
+            }
         except Exception as e:
             return {"success": False, "message": f"❌ 输入失败: {e}"}
@@ -1646,7 +2086,7 @@ class BasicMobileToolsLite:
                     size = ios_client.wda.window_size()
                     width, height = size[0], size[1]
                 else:
-                    return {"success": False, "message": "❌ iOS 客户端未初始化"}
+                    return {"success": False, "msg": "iOS未初始化"}
             else:
                 width, height = self.client.u2.window_size()
@@ -1684,13 +2124,16 @@ class BasicMobileToolsLite:
             else:
                 self.client.u2.swipe(x1, y1, x2, y2, duration=0.5)
-            # 记录操作信息
-            record_info = {'direction': direction}
-            if y is not None:
-                record_info['y'] = y
-            if y_percent is not None:
-                record_info['y_percent'] = y_percent
-            self._record_operation('swipe', **record_info)
+            # 使用标准记录格式
+            self._record_swipe(direction)
+            # 🎯 关键步骤：检查应用是否跳转，如果跳转则自动返回目标应用
+            app_check = self._check_app_switched()
+            return_result = None
+            if app_check['switched']:
+                # 应用已跳转，尝试返回目标应用
+                return_result = self._return_to_target_app()
             # 构建返回消息
             msg = f"✅ 滑动成功: {direction}"
@@ -1700,7 +2143,21 @@ class BasicMobileToolsLite:
                 elif y is not None:
                     msg += f" (高度: {y}px)"
-            return {"success": True, "message": msg}
+            # 如果检测到应用跳转，添加警告和返回结果
+            if app_check['switched']:
+                msg += f"\n{app_check['message']}"
+                if return_result:
+                    if return_result['success']:
+                        msg += f"\n{return_result['message']}"
+                    else:
+                        msg += f"\n❌ 自动返回失败: {return_result['message']}"
+            return {
+                "success": True,
+                "message": msg,
+                "app_check": app_check,
+                "return_to_app": return_result
+            }
         except Exception as e:
             return {"success": False, "message": f"❌ 滑动失败: {e}"}
@@ -1725,22 +2182,22 @@ class BasicMobileToolsLite:
                             ios_client.wda.send_keys('\n')
                         elif ios_key == 'home':
                             ios_client.wda.home()
-                        return {"success": True, "message": f"✅ 按键成功: {key}"}
-                return {"success": False, "message": f"❌ iOS 不支持: {key}"}
+                        return {"success": True}
+                return {"success": False, "msg": f"iOS不支持{key}"}
             else:
                 keycode = key_map.get(key.lower())
                 if keycode:
                     self.client.u2.shell(f'input keyevent {keycode}')
-                    self._record_operation('press_key', key=key)
-                    return {"success": True, "message": f"✅ 按键成功: {key}"}
-                return {"success": False, "message": f"❌ 不支持的按键: {key}"}
+                    self._record_key(key)
+                    return {"success": True}
+                return {"success": False, "msg": f"不支持按键{key}"}
         except Exception as e:
             return {"success": False, "message": f"❌ 按键失败: {e}"}
     def wait(self, seconds: float) -> Dict:
         """等待指定时间"""
         time.sleep(seconds)
-        return {"success": True, "message": f"✅ 已等待 {seconds} 秒"}
+        return {"success": True}
     # ==================== 应用管理 ====================
@@ -1756,12 +2213,20 @@ class BasicMobileToolsLite:
             await asyncio.sleep(2)
+            # 记录目标应用包名（用于后续监测应用跳转）
+            self.target_package = package_name
+            # 验证是否成功启动到目标应用
+            current = self._get_current_package()
+            if current and current != package_name:
+                return {
+                    "success": False,
+                    "message": f"❌ 启动失败：当前应用为 {current}，期望 {package_name}"
+                }
             self._record_operation('launch_app', package_name=package_name)
-            return {
-                "success": True,
-                "message": f"✅ 已启动: {package_name}\n💡 建议等待 2-3 秒让页面加载"
-            }
+            return {"success": True}
         except Exception as e:
             return {"success": False, "message": f"❌ 启动失败: {e}"}
@@ -1774,9 +2239,9 @@ class BasicMobileToolsLite:
                     ios_client.wda.app_terminate(package_name)
             else:
                 self.client.u2.app_stop(package_name)
-            return {"success": True, "message": f"✅ 已终止: {package_name}"}
+            return {"success": True}
         except Exception as e:
-            return {"success": False, "message": f"❌ 终止失败: {e}"}
+            return {"success": False, "msg": str(e)}
     def list_apps(self, filter_keyword: str = "") -> Dict:
         """列出已安装应用"""
@@ -1850,7 +2315,7 @@ class BasicMobileToolsLite:
     # ==================== 辅助工具 ====================
     def list_elements(self) -> List[Dict]:
-        """列出页面元素"""
+        """列出页面元素（已优化：过滤排版容器，保留功能控件）"""
         try:
             if self._is_ios():
                 ios_client = self._get_ios_client()
@@ -1858,23 +2323,271 @@ class BasicMobileToolsLite:
                     return ios_client.list_elements()
                 return [{"error": "iOS 暂不支持元素列表，建议使用截图"}]
             else:
-                xml_string = self._get_full_hierarchy()
+                xml_string = self.client.u2.dump_hierarchy(compressed=False)
                 elements = self.client.xml_parser.parse(xml_string)
+                # 功能控件类型（需要保留）
+                FUNCTIONAL_WIDGETS = {
+                    'TextView', 'Text', 'Label',  # 文本类
+                    'ImageView', 'Image', 'ImageButton',  # 图片类
+                    'Button', 'CheckBox', 'RadioButton', 'Switch',  # 交互类
+                    'SeekBar', 'ProgressBar', 'RatingBar',  # 滑动/进度类
+                    'EditText', 'TextInput',  # 输入类
+                    'VideoView', 'WebView',  # 特殊功能类
+                    'RecyclerView', 'ListView', 'GridView',  # 列表类
+                    'ScrollView', 'NestedScrollView',  # 滚动容器（有实际功能）
+                }
+                # 容器控件类型（需要过滤，除非有业务ID）
+                CONTAINER_WIDGETS = {
+                    'FrameLayout', 'LinearLayout', 'RelativeLayout',
+                    'ViewGroup', 'ConstraintLayout', 'CoordinatorLayout',
+                    'CardView', 'View',  # 基础View也可能只是容器
+                }
+                # 装饰类控件关键词（resource_id中包含这些关键词的通常可以过滤）
+                # 支持匹配如 qylt_item_short_video_shadow_one 这样的命名
+                DECORATIVE_KEYWORDS = {
+                    'shadow', 'divider', 'separator', 'line', 'border',
+                    'background', 'bg_', '_bg', 'decorative', 'decoration',
+                    '_shadow', 'shadow_', '_divider', 'divider_', '_line', 'line_'
+                }
+                # Token 优化：构建精简元素（只返回非空字段）
+                def build_compact_element(resource_id, text, content_desc, bounds, likely_click, class_name):
+                    """只返回有值的字段，节省 token"""
+                    item = {}
+                    if resource_id:
+                        # 精简 resource_id，只保留最后一段
+                        item['id'] = resource_id.split('/')[-1] if '/' in resource_id else resource_id
+                    if text:
+                        item['text'] = text
+                    if content_desc:
+                        item['desc'] = content_desc
+                    if bounds:
+                        item['bounds'] = bounds
+                    if likely_click:
+                        item['click'] = True  # 启发式判断可点击
+                    # class 精简：只保留关键类型
+                    if class_name in ('EditText', 'TextInput', 'Button', 'ImageButton', 'CheckBox', 'Switch'):
+                        item['type'] = class_name
+                    return item
                 result = []
                 for elem in elements:
-                    if elem.get('clickable') or elem.get('focusable'):
-                        result.append({
-                            'resource_id': elem.get('resource_id', ''),
-                            'text': elem.get('text', ''),
-                            'content_desc': elem.get('content_desc', ''),
-                            'bounds': elem.get('bounds', ''),
-                            'clickable': elem.get('clickable', False)
-                        })
+                    # 获取元素属性
+                    class_name = elem.get('class_name', '')
+                    resource_id = elem.get('resource_id', '').strip()
+                    text = elem.get('text', '').strip()
+                    content_desc = elem.get('content_desc', '').strip()
+                    bounds = elem.get('bounds', '')
+                    clickable = elem.get('clickable', False)
+                    focusable = elem.get('focusable', False)
+                    scrollable = elem.get('scrollable', False)
+                    enabled = elem.get('enabled', True)
+                    # 1. 过滤 bounds="[0,0][0,0]" 的视觉隐藏元素
+                    if bounds == '[0,0][0,0]':
+                        continue
+                    # 2. 检查是否是功能控件（直接保留）
+                    if class_name in FUNCTIONAL_WIDGETS:
+                        # 使用启发式判断可点击性（替代不准确的 clickable 属性）
+                        likely_click = self._is_likely_clickable(class_name, resource_id, text, content_desc, clickable, bounds)
+                        item = build_compact_element(resource_id, text, content_desc, bounds, likely_click, class_name)
+                        if item:
+                            result.append(item)
+                        continue
+                    # 3. 检查是否是容器控件
+                    if class_name in CONTAINER_WIDGETS:
+                        # 容器控件需要检查是否有业务相关的ID
+                        has_business_id = self._has_business_id(resource_id)
+                        if not has_business_id:
+                            # 无业务ID的容器控件，检查是否有其他有意义属性
+                            if not (clickable or focusable or scrollable or text or content_desc):
+                                # 所有属性都是默认值，过滤掉
+                                continue
+                        # 有业务ID或其他有意义属性，保留
+                        likely_click = self._is_likely_clickable(class_name, resource_id, text, content_desc, clickable, bounds)
+                        item = build_compact_element(resource_id, text, content_desc, bounds, likely_click, class_name)
+                        if item:
+                            result.append(item)
+                        continue
+                    # 4. 检查是否是装饰类控件
+                    if resource_id:
+                        resource_id_lower = resource_id.lower()
+                        if any(keyword in resource_id_lower for keyword in DECORATIVE_KEYWORDS):
+                            # 是装饰类控件，且没有交互属性，过滤掉
+                            if not (clickable or focusable or text or content_desc):
+                                continue
+                    # 5. 检查是否所有属性均为默认值
+                    if not (text or content_desc or resource_id or clickable or focusable or scrollable):
+                        # 所有属性都是默认值，过滤掉
+                        continue
+                    # 6. 其他情况：有意义的元素保留
+                    likely_click = self._is_likely_clickable(class_name, resource_id, text, content_desc, clickable, bounds)
+                    item = build_compact_element(resource_id, text, content_desc, bounds, likely_click, class_name)
+                    if item:
+                        result.append(item)
+                # Token 优化：可选限制返回元素数量（默认不限制，确保准确度）
+                if TOKEN_OPTIMIZATION and MAX_ELEMENTS > 0 and len(result) > MAX_ELEMENTS:
+                    # 仅在用户明确设置 MAX_ELEMENTS_RETURN 时才截断
+                    truncated = result[:MAX_ELEMENTS]
+                    truncated.append({
+                        '_truncated': True,
+                        '_total': len(result),
+                        '_shown': MAX_ELEMENTS
+                    })
+                    return truncated
                 return result
         except Exception as e:
             return [{"error": f"获取元素失败: {e}"}]
+    def _get_page_texts(self, max_count: int = 15) -> List[str]:
+        """获取页面关键文本列表（用于点击后快速确认页面变化）
+        Args:
+            max_count: 最多返回的文本数量
+        Returns:
+            页面上的关键文本列表（去重）
+        """
+        try:
+            if self._is_ios():
+                ios_client = self._get_ios_client()
+                if ios_client and hasattr(ios_client, 'wda'):
+                    # iOS: 获取所有 StaticText 的文本
+                    elements = ios_client.wda(type='XCUIElementTypeStaticText').find_elements()
+                    texts = set()
+                    for elem in elements[:50]:  # 限制扫描数量
+                        try:
+                            name = elem.name or elem.label
+                            if name and len(name) > 1 and len(name) < 50:
+                                texts.add(name)
+                        except:
+                            pass
+                    return list(texts)[:max_count]
+                return []
+            else:
+                # Android: 快速扫描 XML 获取文本
+                xml_string = self.client.u2.dump_hierarchy(compressed=True)
+                import xml.etree.ElementTree as ET
+                root = ET.fromstring(xml_string)
+                texts = set()
+                for elem in root.iter():
+                    text = elem.get('text', '').strip()
+                    desc = elem.get('content-desc', '').strip()
+                    # 只收集有意义的文本（长度2-30，非纯数字）
+                    for t in [text, desc]:
+                        if t and 2 <= len(t) <= 30 and not t.isdigit():
+                            texts.add(t)
+                    if len(texts) >= max_count * 2:  # 收集足够后停止
+                        break
+                return list(texts)[:max_count]
+        except Exception:
+            return []
+    def _has_business_id(self, resource_id: str) -> bool:
+        """
+        判断resource_id是否是业务相关的ID
+        业务相关的ID通常包含：
+        - 有意义的命名（不是自动生成的）
+        - 不包含常见的自动生成模式
+        """
+        if not resource_id:
+            return False
+        # 自动生成的ID模式（通常可以忽略）
+        auto_generated_patterns = [
+            r'^android:id/',  # 系统ID
+            r':id/\d+',  # 数字ID
+            r':id/view_\d+',  # view_数字
+            r':id/item_\d+',  # item_数字
+        ]
+        for pattern in auto_generated_patterns:
+            if re.search(pattern, resource_id):
+                return False
+        # 如果resource_id有实际内容且不是自动生成的，认为是业务ID
+        # 排除一些常见的系统ID
+        system_ids = ['android:id/content', 'android:id/statusBarBackground']
+        if resource_id in system_ids:
+            return False
+        return True
+    def _is_likely_clickable(self, class_name: str, resource_id: str, text: str,
+                             content_desc: str, clickable: bool, bounds: str) -> bool:
+        """
+        启发式判断元素是否可能可点击
+        Android 的 clickable 属性经常不准确，因为：
+        1. 点击事件可能设置在父容器上
+        2. 使用 onTouchListener 而不是 onClick
+        3. RecyclerView item 通过 ItemClickListener 处理
+        此方法通过多种规则推断元素的真实可点击性
+        """
+        # 规则1：clickable=true 肯定可点击
+        if clickable:
+            return True
+        # 规则2：特定类型的控件通常可点击
+        TYPICALLY_CLICKABLE = {
+            'Button', 'ImageButton', 'CheckBox', 'RadioButton', 'Switch',
+            'ToggleButton', 'FloatingActionButton', 'Chip', 'TabView',
+            'EditText', 'TextInput',  # 输入框可点击获取焦点
+        }
+        if class_name in TYPICALLY_CLICKABLE:
+            return True
+        # 规则3：resource_id 包含可点击关键词
+        if resource_id:
+            id_lower = resource_id.lower()
+            CLICK_KEYWORDS = [
+                'btn', 'button', 'click', 'tap', 'submit', 'confirm',
+                'cancel', 'close', 'back', 'next', 'prev', 'more',
+                'action', 'link', 'menu', 'tab', 'item', 'cell',
+                'card', 'avatar', 'icon', 'entry', 'option', 'arrow'
+            ]
+            for kw in CLICK_KEYWORDS:
+                if kw in id_lower:
+                    return True
+        # 规则4：content_desc 包含可点击暗示
+        if content_desc:
+            desc_lower = content_desc.lower()
+            CLICK_HINTS = ['点击', '按钮', '关闭', '返回', '更多', 'click', 'tap', 'button', 'close']
+            for hint in CLICK_HINTS:
+                if hint in desc_lower:
+                    return True
+        # 规则5：有 resource_id 或 content_desc 的小图标可能可点击
+        # （纯 ImageView 不加判断，误判率太高）
+        if class_name in ('ImageView', 'Image') and (resource_id or content_desc) and bounds:
+            match = re.match(r'\[(\d+),(\d+)\]\[(\d+),(\d+)\]', bounds)
+            if match:
+                x1, y1, x2, y2 = map(int, match.groups())
+                w, h = x2 - x1, y2 - y1
+                # 小图标（20-100px）更可能是按钮
+                if 20 <= w <= 100 and 20 <= h <= 100:
+                    return True
+        # 规则6：移除（TextView 误判率太高，只依赖上面的规则）
+        # 如果有 clickable=true 或 ID/desc 中有关键词，前面的规则已经覆盖
+        return False
     def find_close_button(self) -> Dict:
         """智能查找关闭按钮（不点击，只返回位置）
@@ -1888,17 +2601,25 @@ class BasicMobileToolsLite:
             import re
             if self._is_ios():
-                return {"success": False, "message": "iOS 暂不支持，请使用截图+坐标点击"}
+                return {"success": False, "msg": "iOS暂不支持"}
             # 获取屏幕尺寸
             screen_width = self.client.u2.info.get('displayWidth', 720)
             screen_height = self.client.u2.info.get('displayHeight', 1280)
-            # 获取元素列表（使用完整 UI 层级）
-            xml_string = self._get_full_hierarchy()
+            # 获取元素列表
+            xml_string = self.client.u2.dump_hierarchy(compressed=False)
             import xml.etree.ElementTree as ET
             root = ET.fromstring(xml_string)
+            # 🔴 先检测是否有弹窗，避免误识别普通页面的按钮
+            popup_bounds, popup_confidence = self._detect_popup_with_confidence(
+                root, screen_width, screen_height
+            )
+            if popup_bounds is None or popup_confidence < 0.5:
+                return {"success": True, "popup": False}
             # 关闭按钮特征
             close_texts = ['×', 'X', 'x', '关闭', '取消', 'close', 'Close', '跳过', '知道了', '我知道了']
             candidates = []
@@ -2000,27 +2721,16 @@ class BasicMobileToolsLite:
             candidates.sort(key=lambda x: x['score'], reverse=True)
             best = candidates[0]
+            # Token 优化：只返回最必要的信息
             return {
                 "success": True,
-                "message": f"✅ 找到可能的关闭按钮",
-                "best_candidate": {
-                    "reason": best['reason'],
-                    "center": {"x": best['center_x'], "y": best['center_y']},
-                    "percent": {"x": best['x_percent'], "y": best['y_percent']},
-                    "bounds": best['bounds'],
-                    "size": best['size'],
-                    "score": best['score']
-                },
-                "click_command": f"mobile_click_by_percent({best['x_percent']}, {best['y_percent']})",
-                "other_candidates": [
-                    {"reason": c['reason'], "percent": f"({c['x_percent']}%, {c['y_percent']}%)", "score": c['score']}
-                    for c in candidates[1:4]
-                ] if len(candidates) > 1 else [],
-                "screen_size": {"width": screen_width, "height": screen_height}
+                "popup": True,
+                "close": {"x": best['x_percent'], "y": best['y_percent']},
+                "cmd": f"click_by_percent({best['x_percent']},{best['y_percent']})"
             }
         except Exception as e:
-            return {"success": False, "message": f"❌ 查找关闭按钮失败: {e}"}
+            return {"success": False, "msg": str(e)}
     def close_popup(self) -> Dict:
         """智能关闭弹窗（改进版）
@@ -2043,13 +2753,13 @@ class BasicMobileToolsLite:
             # 获取屏幕尺寸
             if self._is_ios():
-                return {"success": False, "message": "iOS 暂不支持，请使用截图+坐标点击"}
+                return {"success": False, "msg": "iOS暂不支持"}
             screen_width = self.client.u2.info.get('displayWidth', 720)
             screen_height = self.client.u2.info.get('displayHeight', 1280)
-            # 获取原始 XML（使用完整 UI 层级）
-            xml_string = self._get_full_hierarchy()
+            # 获取原始 XML
+            xml_string = self.client.u2.dump_hierarchy(compressed=False)
             # 关闭按钮的文本特征
             close_texts = ['×', 'X', 'x', '关闭', '取消', 'close', 'Close', 'CLOSE', '跳过', '知道了']
@@ -2063,53 +2773,18 @@ class BasicMobileToolsLite:
                 root = ET.fromstring(xml_string)
                 all_elements = list(root.iter())
-                # ===== 第一步：检测弹窗区域 =====
-                # 弹窗特征：非全屏、面积较大、通常在屏幕中央的容器
-                popup_containers = []
-                for idx, elem in enumerate(all_elements):
-                    bounds_str = elem.attrib.get('bounds', '')
-                    class_name = elem.attrib.get('class', '')
-                    if not bounds_str:
-                        continue
-                    match = re.match(r'\[(\d+),(\d+)\]\[(\d+),(\d+)\]', bounds_str)
-                    if not match:
-                        continue
-                    x1, y1, x2, y2 = map(int, match.groups())
-                    width = x2 - x1
-                    height = y2 - y1
-                    area = width * height
-                    screen_area = screen_width * screen_height
-                    # 弹窗容器特征：
-                    # 1. 面积在屏幕的 10%-90% 之间（非全屏）
-                    # 2. 宽度或高度不等于屏幕尺寸
-                    # 3. 是容器类型（Layout/View/Dialog）
-                    is_container = any(kw in class_name for kw in ['Layout', 'View', 'Dialog', 'Card', 'Container'])
-                    area_ratio = area / screen_area
-                    is_not_fullscreen = (width < screen_width * 0.98 or height < screen_height * 0.98)
-                    is_reasonable_size = 0.08 < area_ratio < 0.9
-                    # 排除状态栏区域（y1 通常很小）
-                    is_below_statusbar = y1 > 50
-                    if is_container and is_not_fullscreen and is_reasonable_size and is_below_statusbar:
-                        popup_containers.append({
-                            'bounds': (x1, y1, x2, y2),
-                            'bounds_str': bounds_str,
-                            'area': area,
-                            'area_ratio': area_ratio,
-                            'idx': idx,  # 元素在 XML 中的顺序（越后越上层）
-                            'class': class_name
-                        })
+                # ===== 第一步：使用严格的置信度检测弹窗区域 =====
+                popup_bounds, popup_confidence = self._detect_popup_with_confidence(
+                    root, screen_width, screen_height
+                )
+                # 如果置信度不够高，记录但继续尝试查找关闭按钮
+                popup_detected = popup_bounds is not None and popup_confidence >= 0.6
-                # 选择最可能的弹窗容器（优先选择：XML 顺序靠后 + 面积适中）
-                if popup_containers:
-                    # 按 XML 顺序倒序（后出现的在上层），然后按面积适中程度排序
-                    popup_containers.sort(key=lambda x: (x['idx'], -abs(x['area_ratio'] - 0.3)), reverse=True)
-                    popup_bounds = popup_containers[0]['bounds']
+                # 🔴 关键检查：如果没有检测到弹窗区域，直接返回"无弹窗"
+                # 避免误点击普通页面上的"关闭"、"取消"等按钮
+                if not popup_detected:
+                    return {"success": True, "popup": False}
                 # ===== 第二步：在弹窗范围内查找关闭按钮 =====
                 for idx, elem in enumerate(all_elements):
@@ -2241,73 +2916,16 @@ class BasicMobileToolsLite:
                             'content_desc': content_desc,
                             'x_percent': round(rel_x * 100, 1),
                             'y_percent': round(rel_y * 100, 1),
-                            'in_popup': popup_bounds is not None
+                            'in_popup': popup_detected
                         })
             except ET.ParseError:
                 pass
             if not close_candidates:
-                # 如果检测到弹窗区域，先尝试点击常见的关闭按钮位置
-                if popup_bounds:
-                    px1, py1, px2, py2 = popup_bounds
-                    popup_width = px2 - px1
-                    popup_height = py2 - py1
-                    # 【优化】X按钮有三种常见位置：
-                    # 1. 弹窗内靠近顶部边界（内嵌X按钮）- 最常见
-                    # 2. 弹窗边界上方（浮动X按钮）
-                    # 3. 弹窗正下方（底部关闭按钮）
-                    offset_x = max(60, int(popup_width * 0.07))   # 宽度7%
-                    offset_y_above = max(35, int(popup_height * 0.025))  # 高度2.5%，在边界之上
-                    offset_y_near = max(45, int(popup_height * 0.03))    # 高度3%，紧贴顶边界内侧
-                    try_positions = [
-                        # 【最高优先级】弹窗内紧贴顶部边界
-                        (px2 - offset_x, py1 + offset_y_near, "弹窗右上角"),
-                        # 弹窗边界上方（浮动X按钮）
-                        (px2 - offset_x, py1 - offset_y_above, "弹窗右上浮"),
-                        # 弹窗正下方中间（底部关闭按钮）
-                        ((px1 + px2) // 2, py2 + max(50, int(popup_height * 0.04)), "弹窗下方中间"),
-                        # 弹窗正上方中间
-                        ((px1 + px2) // 2, py1 - 40, "弹窗正上方"),
-                    ]
-                    for try_x, try_y, position_name in try_positions:
-                        if 0 <= try_x <= screen_width and 0 <= try_y <= screen_height:
-                            self.client.u2.click(try_x, try_y)
-                            time.sleep(0.3)
-                    # 尝试后截图，让 AI 判断是否成功
-                    screenshot_result = self.take_screenshot("尝试关闭后")
-                    return {
-                        "success": True,
-                        "message": f"✅ 已尝试点击常见关闭按钮位置",
-                        "tried_positions": [p[2] for p in try_positions],
-                        "screenshot": screenshot_result.get("screenshot_path", ""),
-                        "tip": "请查看截图确认弹窗是否已关闭。如果还在，可手动分析截图找到关闭按钮位置。"
-                    }
-                # 没有检测到弹窗区域，截图让 AI 分析
-                screenshot_result = self.take_screenshot(description="页面截图", compress=True)
-                return {
-                    "success": False,
-                    "message": "❌ 未检测到弹窗区域，已截图供 AI 分析",
-                    "action_required": "请查看截图找到关闭按钮，调用 mobile_click_at_coords 点击",
-                    "screenshot": screenshot_result.get("screenshot_path", ""),
-                    "screen_size": {"width": screen_width, "height": screen_height},
-                    "image_size": {
-                        "width": screenshot_result.get("image_width", screen_width),
-                        "height": screenshot_result.get("image_height", screen_height)
-                    },
-                    "original_size": {
-                        "width": screenshot_result.get("original_img_width", screen_width),
-                        "height": screenshot_result.get("original_img_height", screen_height)
-                    },
-                    "search_areas": ["弹窗右上角", "弹窗正上方", "弹窗下方中间", "屏幕右上角"],
-                    "time_warning": "⚠️ 截图分析期间弹窗可能自动消失。如果是定时弹窗，建议等待其自动消失。"
-                }
+                if popup_detected and popup_bounds:
+                    return {"success": False, "fallback": "vision", "popup": True}
+                return {"success": True, "popup": False}
             # 按得分排序，取最可能的
             close_candidates.sort(key=lambda x: x['score'], reverse=True)
@@ -2317,49 +2935,30 @@ class BasicMobileToolsLite:
             self.client.u2.click(best['center_x'], best['center_y'])
             time.sleep(0.5)
-            # 点击后截图，让 AI 判断是否成功
-            screenshot_result = self.take_screenshot("关闭弹窗后")
-            # 记录操作（使用百分比，跨设备兼容）
-            self._record_operation(
-                'click',
-                x=best['center_x'],
-                y=best['center_y'],
-                x_percent=best['x_percent'],
-                y_percent=best['y_percent'],
-                screen_width=screen_width,
-                screen_height=screen_height,
-                ref=f"close_popup_{best['position']}"
-            )
+            # 🎯 关键步骤：检查应用是否跳转，如果跳转说明弹窗去除失败，需要返回目标应用
+            app_check = self._check_app_switched()
+            return_result = None
-            # 返回候选按钮列表，让 AI 看截图判断
-            # 如果弹窗还在，AI 可以选择点击其他候选按钮
-            return {
-                "success": True,
-                "message": f"✅ 已点击关闭按钮 ({best['position']}): ({best['center_x']}, {best['center_y']})",
-                "clicked": {
-                    "position": best['position'],
-                    "match_type": best['match_type'],
-                    "coords": (best['center_x'], best['center_y']),
-                    "percent": (best['x_percent'], best['y_percent'])
-                },
-                "screenshot": screenshot_result.get("screenshot_path", ""),
-                "popup_detected": popup_bounds is not None,
-                "popup_bounds": f"[{popup_bounds[0]},{popup_bounds[1]}][{popup_bounds[2]},{popup_bounds[3]}]" if popup_bounds else None,
-                "other_candidates": [
-                    {
-                        "position": c['position'],
-                        "type": c['match_type'],
-                        "coords": (c['center_x'], c['center_y']),
-                        "percent": (c['x_percent'], c['y_percent'])
-                    }
-                    for c in close_candidates[1:4]  # 返回其他3个候选，AI 可以选择
-                ],
-                "tip": "请查看截图判断弹窗是否已关闭。如果弹窗还在，可以尝试点击 other_candidates 中的其他位置；如果误点跳转了，请按返回键"
-            }
+            if app_check['switched']:
+                # 应用已跳转，说明弹窗去除失败，尝试返回目标应用
+                return_result = self._return_to_target_app()
+            # 记录操作
+            self._record_click('percent', f"{best['x_percent']}%,{best['y_percent']}%",
+                              best['x_percent'], best['y_percent'],
+                              element_desc=f"关闭按钮({best['position']})")
+            # Token 优化：精简返回值
+            result = {"success": True, "clicked": True}
+            if app_check['switched']:
+                result["switched"] = True
+                if return_result:
+                    result["returned"] = return_result['success']
+            return result
         except Exception as e:
-            return {"success": False, "message": f"❌ 关闭弹窗失败: {e}"}
+            return {"success": False, "msg": str(e)}
     def _get_position_name(self, rel_x: float, rel_y: float) -> str:
         """根据相对坐标获取位置名称"""
@@ -2402,6 +3001,308 @@ class BasicMobileToolsLite:
                 return 0.8
         else:  # 中间区域
             return 0.5
+    def _detect_popup_with_confidence(self, root, screen_width: int, screen_height: int) -> tuple:
+        """严格的弹窗检测 - 使用置信度评分，避免误识别普通页面
+        真正的弹窗特征：
+        1. class 名称包含 Dialog/Popup/Alert/Modal/BottomSheet（强特征）
+        2. resource-id 包含 dialog/popup/alert/modal（强特征）
+        3. 有遮罩层（大面积半透明 View 在弹窗之前）
+        4. 居中显示且非全屏
+        5. XML 层级靠后且包含可交互元素
+        Returns:
+            (popup_bounds, confidence) 或 (None, 0)
+            confidence >= 0.6 才认为是弹窗
+        """
+        import re
+        screen_area = screen_width * screen_height
+        # 收集所有元素信息
+        all_elements = []
+        for idx, elem in enumerate(root.iter()):
+            bounds_str = elem.attrib.get('bounds', '')
+            if not bounds_str:
+                continue
+            match = re.match(r'\[(\d+),(\d+)\]\[(\d+),(\d+)\]', bounds_str)
+            if not match:
+                continue
+            x1, y1, x2, y2 = map(int, match.groups())
+            width = x2 - x1
+            height = y2 - y1
+            area = width * height
+            class_name = elem.attrib.get('class', '')
+            resource_id = elem.attrib.get('resource-id', '')
+            clickable = elem.attrib.get('clickable', 'false') == 'true'
+            all_elements.append({
+                'idx': idx,
+                'bounds': (x1, y1, x2, y2),
+                'width': width,
+                'height': height,
+                'area': area,
+                'area_ratio': area / screen_area if screen_area > 0 else 0,
+                'class': class_name,
+                'resource_id': resource_id,
+                'clickable': clickable,
+                'center_x': (x1 + x2) // 2,
+                'center_y': (y1 + y2) // 2,
+            })
+        if not all_elements:
+            return None, 0
+        # 弹窗检测关键词
+        dialog_class_keywords = ['Dialog', 'Popup', 'Alert', 'Modal', 'BottomSheet', 'PopupWindow']
+        dialog_id_keywords = ['dialog', 'popup', 'alert', 'modal', 'bottom_sheet', 'overlay', 'mask']
+        popup_candidates = []
+        has_mask_layer = False
+        mask_idx = -1
+        for elem in all_elements:
+            x1, y1, x2, y2 = elem['bounds']
+            class_name = elem['class']
+            resource_id = elem['resource_id']
+            area_ratio = elem['area_ratio']
+            # 检测遮罩层（大面积、几乎全屏、通常是 FrameLayout/View）
+            if area_ratio > 0.85 and elem['width'] >= screen_width * 0.95:
+                # 可能是遮罩层，记录位置
+                if 'FrameLayout' in class_name or 'View' in class_name:
+                    has_mask_layer = True
+                    mask_idx = elem['idx']
+            # 跳过全屏元素
+            if area_ratio > 0.9:
+                continue
+            # 跳过太小的元素
+            if area_ratio < 0.05:
+                continue
+            # 跳过状态栏区域
+            if y1 < 50:
+                continue
+            confidence = 0.0
+            # 【强特征】class 名称包含弹窗关键词 (+0.5)
+            if any(kw in class_name for kw in dialog_class_keywords):
+                confidence += 0.5
+            # 【强特征】resource-id 包含弹窗关键词 (+0.4)
+            if any(kw in resource_id.lower() for kw in dialog_id_keywords):
+                confidence += 0.4
+            # 【中等特征】居中显示 (+0.2)
+            center_x = elem['center_x']
+            center_y = elem['center_y']
+            is_centered_x = abs(center_x - screen_width / 2) < screen_width * 0.15
+            is_centered_y = abs(center_y - screen_height / 2) < screen_height * 0.25
+            if is_centered_x and is_centered_y:
+                confidence += 0.2
+            elif is_centered_x:
+                confidence += 0.1
+            # 【中等特征】非全屏但有一定大小 (+0.15)
+            if 0.15 < area_ratio < 0.75:
+                confidence += 0.15
+            # 【弱特征】XML 顺序靠后（在视图层级上层）(+0.1)
+            if elem['idx'] > len(all_elements) * 0.5:
+                confidence += 0.1
+            # 【弱特征】有遮罩层且在遮罩层之后 (+0.15)
+            if has_mask_layer and elem['idx'] > mask_idx:
+                confidence += 0.15
+            # 只有达到阈值才加入候选
+            if confidence >= 0.3:
+                popup_candidates.append({
+                    'bounds': elem['bounds'],
+                    'confidence': confidence,
+                    'class': class_name,
+                    'resource_id': resource_id,
+                    'idx': elem['idx']
+                })
+        if not popup_candidates:
+            return None, 0
+        # 选择置信度最高的
+        popup_candidates.sort(key=lambda x: (x['confidence'], x['idx']), reverse=True)
+        best = popup_candidates[0]
+        # 只有置信度 >= 0.6 才返回弹窗
+        if best['confidence'] >= 0.6:
+            return best['bounds'], best['confidence']
+        return None, best['confidence']
+    def start_toast_watch(self) -> Dict:
+        """开始监听 Toast（仅 Android）
+        ⚠️ 必须在执行操作之前调用！
+        正确流程：
+        1. 调用 mobile_start_toast_watch() 开始监听
+        2. 执行操作（如点击提交按钮）
+        3. 调用 mobile_get_toast() 获取 Toast 内容
+        Returns:
+            监听状态
+        """
+        if self._is_ios():
+            return {
+                "success": False,
+                "message": "❌ iOS 不支持 Toast 检测，Toast 是 Android 特有功能"
+            }
+        try:
+            # 清除缓存并开始监听
+            self.client.u2.toast.reset()
+            return {
+                "success": True,
+                "message": "✅ Toast 监听已开启，请立即执行操作，然后调用 mobile_get_toast 获取结果"
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"❌ 开启 Toast 监听失败: {e}"
+            }
+    def get_toast(self, timeout: float = 5.0, reset_first: bool = False) -> Dict:
+        """获取 Toast 消息（仅 Android）
+        Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果。
+        ⚠️ 推荐用法（两步走）：
+        1. 先调用 mobile_start_toast_watch() 开始监听
+        2. 执行操作（如点击提交按钮）
+        3. 调用 mobile_get_toast() 获取 Toast
+        或者设置 reset_first=True，会自动 reset 后等待（适合操作已自动触发的场景）
+        Args:
+            timeout: 等待 Toast 出现的超时时间（秒），默认 5 秒
+            reset_first: 是否先 reset（清除旧缓存），默认 False
+        Returns:
+            包含 Toast 消息的字典
+        """
+        if self._is_ios():
+            return {
+                "success": False,
+                "message": "❌ iOS 不支持 Toast 检测，Toast 是 Android 特有功能"
+            }
+        try:
+            if reset_first:
+                # 清除旧缓存，适合等待即将出现的 Toast
+                self.client.u2.toast.reset()
+            # 等待并获取 Toast 消息
+            toast_message = self.client.u2.toast.get_message(
+                wait_timeout=timeout,
+                default=None
+            )
+            if toast_message:
+                return {
+                    "success": True,
+                    "toast_found": True,
+                    "message": toast_message,
+                    "tip": "Toast 消息获取成功"
+                }
+            else:
+                return {
+                    "success": True,
+                    "toast_found": False,
+                    "message": None,
+                    "tip": f"在 {timeout} 秒内未检测到 Toast。提示：先调用 mobile_start_toast_watch，再执行操作，最后调用此工具"
+                }
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"❌ 获取 Toast 失败: {e}"
+            }
+    def assert_toast(self, expected_text: str, timeout: float = 5.0, contains: bool = True) -> Dict:
+        """断言 Toast 消息（仅 Android）
+        等待 Toast 出现并验证内容是否符合预期。
+        ⚠️ 推荐用法：先调用 mobile_start_toast_watch，再执行操作，最后调用此工具
+        Args:
+            expected_text: 期望的 Toast 文本
+            timeout: 等待超时时间（秒）
+            contains: True 表示包含匹配，False 表示精确匹配
+        Returns:
+            断言结果
+        """
+        if self._is_ios():
+            return {
+                "success": False,
+                "passed": False,
+                "message": "❌ iOS 不支持 Toast 检测"
+            }
+        try:
+            # 获取 Toast（不 reset，假设之前已经调用过 start_toast_watch）
+            toast_message = self.client.u2.toast.get_message(
+                wait_timeout=timeout,
+                default=None
+            )
+            if toast_message is None:
+                return {
+                    "success": True,
+                    "passed": False,
+                    "expected": expected_text,
+                    "actual": None,
+                    "message": f"❌ 断言失败：未检测到 Toast 消息"
+                }
+            # 匹配检查
+            if contains:
+                passed = expected_text in toast_message
+                match_type = "包含"
+            else:
+                passed = expected_text == toast_message
+                match_type = "精确"
+            if passed:
+                return {
+                    "success": True,
+                    "passed": True,
+                    "expected": expected_text,
+                    "actual": toast_message,
+                    "match_type": match_type,
+                    "message": f"✅ Toast 断言通过：'{toast_message}'"
+                }
+            else:
+                return {
+                    "success": True,
+                    "passed": False,
+                    "expected": expected_text,
+                    "actual": toast_message,
+                    "match_type": match_type,
+                    "message": f"❌ Toast 断言失败：期望 '{expected_text}'，实际 '{toast_message}'"
+                }
+        except Exception as e:
+            return {
+                "success": False,
+                "passed": False,
+                "message": f"❌ Toast 断言异常: {e}"
+            }
     def assert_text(self, text: str) -> Dict:
         """检查页面是否包含文本（支持精确匹配和包含匹配）"""
@@ -2487,11 +3388,16 @@ class BasicMobileToolsLite:
             f"生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
             "",
             "定位策略（按优先级）：",
-            "1. ID 定位 - 最稳定，跨设备兼容",
-            "2. 文本定位 - 稳定，跨设备兼容",
+            "1. 文本定位 - 最稳定，跨设备兼容",
+            "2. ID 定位 - 稳定，跨设备兼容",
             "3. 百分比定位 - 跨分辨率兼容（坐标自动转换）",
+            "",
+            "运行方式：",
+            "  pytest {filename} -v        # 使用 pytest 运行",
+            "  python {filename}           # 直接运行",
             f'"""',
             "import time",
+            "import pytest",
             "import uiautomator2 as u2",
             "",
             f'PACKAGE_NAME = "{package_name}"',
@@ -2567,22 +3473,52 @@ class BasicMobileToolsLite:
             "    return True",
             "",
             "",
-            "def test_main():",
-            "    # 连接设备",
-            "    d = u2.connect()",
-            "    d.implicitly_wait(10)  # 设置全局等待",
-            "    ",
-            "    # 启动应用",
-            f"    d.app_start(PACKAGE_NAME)",
-            "    time.sleep(LAUNCH_WAIT)  # 等待启动（可调整）",
+            "def swipe_direction(d, direction):",
+            '    """',
+            '    通用滑动方法（兼容所有 uiautomator2 版本）',
+            '    ',
+            '    Args:',
+            '        d: uiautomator2 设备对象',
+            '        direction: 滑动方向 (up/down/left/right)',
+            '    """',
+            "    info = d.info",
+            "    width = info.get('displayWidth', 0)",
+            "    height = info.get('displayHeight', 0)",
+            "    cx, cy = width // 2, height // 2",
             "    ",
-            "    # 尝试关闭启动广告（可选，根据 App 情况调整）",
+            "    if direction == 'up':",
+            "        d.swipe(cx, int(height * 0.8), cx, int(height * 0.3))",
+            "    elif direction == 'down':",
+            "        d.swipe(cx, int(height * 0.3), cx, int(height * 0.8))",
+            "    elif direction == 'left':",
+            "        d.swipe(int(width * 0.8), cy, int(width * 0.2), cy)",
+            "    elif direction == 'right':",
+            "        d.swipe(int(width * 0.2), cy, int(width * 0.8), cy)",
+            "    return True",
+            "",
+            "",
+            "# ========== pytest fixture ==========",
+            "@pytest.fixture(scope='function')",
+            "def device():",
+            '    """pytest fixture: 连接设备并启动应用"""',
+            "    d = u2.connect()",
+            "    d.implicitly_wait(10)",
+            "    d.app_start(PACKAGE_NAME)",
+            "    time.sleep(LAUNCH_WAIT)",
             "    if CLOSE_AD_ON_LAUNCH:",
             "        close_ad_if_exists(d)",
+            "    yield d",
+            "    # 测试结束后可选择关闭应用",
+            "    # d.app_stop(PACKAGE_NAME)",
+            "",
+            "",
+            f"def test_{safe_name}(device):",
+            '    """测试用例主函数"""',
+            "    d = device",
             "    ",
         ]
-        # 生成操作代码（跳过启动应用相关操作，因为脚本头部已处理）
+        # 生成操作代码（使用标准记录格式，逻辑更简洁）
         step_num = 0
         for op in self.operation_history:
             action = op.get('action')
@@ -2594,130 +3530,122 @@ class BasicMobileToolsLite:
             step_num += 1
             if action == 'click':
-                ref = op.get('ref', '')
-                element = op.get('element', '')
-                has_coords = 'x' in op and 'y' in op
-                has_percent = 'x_percent' in op and 'y_percent' in op
-                # 判断 ref 是否为坐标格式（coords_ 或 coords:）
-                is_coords_ref = ref.startswith('coords_') or ref.startswith('coords:')
-                is_percent_ref = ref.startswith('percent_')
-                # 优先级：ID > 文本 > 百分比 > 坐标（兜底）
-                if ref and (':id/' in ref or ref.startswith('com.')):
-                    # 1️⃣ 使用 resource-id（最稳定）
-                    script_lines.append(f"    # 步骤{step_num}: 点击元素 (ID定位，最稳定)")
-                    script_lines.append(f"    safe_click(d, d(resourceId='{ref}'))")
-                elif ref and not is_coords_ref and not is_percent_ref and ':' not in ref:
-                    # 2️⃣ 使用文本（稳定）- 排除 "text:xxx" 等带冒号的格式
-                    script_lines.append(f"    # 步骤{step_num}: 点击文本 '{ref}' (文本定位)")
-                    script_lines.append(f"    safe_click(d, d(text='{ref}'))")
-                elif ref and ':' in ref and not is_coords_ref and not is_percent_ref:
-                    # 2️⃣-b 使用文本（Android 的 text:xxx 或 description:xxx 格式）
-                    # 提取冒号后面的实际文本值
-                    actual_text = ref.split(':', 1)[1] if ':' in ref else ref
-                    script_lines.append(f"    # 步骤{step_num}: 点击文本 '{actual_text}' (文本定位)")
-                    script_lines.append(f"    safe_click(d, d(text='{actual_text}'))")
-                elif has_percent:
-                    # 3️⃣ 使用百分比（跨分辨率兼容）
-                    x_pct = op['x_percent']
-                    y_pct = op['y_percent']
-                    desc = f" ({element})" if element else ""
-                    script_lines.append(f"    # 步骤{step_num}: 点击位置{desc} (百分比定位，跨分辨率兼容)")
-                    script_lines.append(f"    click_by_percent(d, {x_pct}, {y_pct})  # 原坐标: ({op.get('x', '?')}, {op.get('y', '?')})")
-                elif has_coords:
-                    # 4️⃣ 坐标兜底（不推荐，仅用于无法获取百分比的情况）
-                    desc = f" ({element})" if element else ""
-                    script_lines.append(f"    # 步骤{step_num}: 点击坐标{desc} (⚠️ 坐标定位，可能不兼容其他分辨率)")
-                    script_lines.append(f"    d.click({op['x']}, {op['y']})")
+                # 新格式：使用 locator_type 和 locator_value
+                locator_type = op.get('locator_type', '')
+                locator_value = op.get('locator_value', '')
+                locator_attr = op.get('locator_attr', 'text')
+                element_desc = op.get('element_desc', '')
+                x_pct = op.get('x_percent', 0)
+                y_pct = op.get('y_percent', 0)
+                # 转义单引号
+                value_escaped = locator_value.replace("'", "\\'") if locator_value else ''
+                if locator_type == 'text':
+                    # 文本定位（最稳定）
+                    script_lines.append(f"    # 步骤{step_num}: 点击 '{element_desc}' (文本定位)")
+                    if locator_attr == 'description':
+                        script_lines.append(f"    safe_click(d, d(description='{value_escaped}'))")
+                    elif locator_attr == 'descriptionContains':
+                        script_lines.append(f"    safe_click(d, d(descriptionContains='{value_escaped}'))")
+                    elif locator_attr == 'textContains':
+                        script_lines.append(f"    safe_click(d, d(textContains='{value_escaped}'))")
+                    else:
+                        script_lines.append(f"    safe_click(d, d(text='{value_escaped}'))")
+                elif locator_type == 'id':
+                    # ID 定位（稳定）
+                    script_lines.append(f"    # 步骤{step_num}: 点击 '{element_desc}' (ID定位)")
+                    script_lines.append(f"    safe_click(d, d(resourceId='{value_escaped}'))")
+                elif locator_type == 'percent':
+                    # 百分比定位（跨分辨率兼容）
+                    script_lines.append(f"    # 步骤{step_num}: 点击 '{element_desc}' (百分比定位)")
+                    script_lines.append(f"    click_by_percent(d, {x_pct}, {y_pct})")
                 else:
-                    continue  # 无效操作，跳过
-                script_lines.append("    time.sleep(0.5)  # 等待响应")
+                    # 兼容旧格式
+                    ref = op.get('ref', '')
+                    if ref:
+                        ref_escaped = ref.replace("'", "\\'")
+                        script_lines.append(f"    # 步骤{step_num}: 点击 '{ref}'")
+                        script_lines.append(f"    safe_click(d, d(text='{ref_escaped}'))")
+                    else:
+                        continue
+                script_lines.append("    time.sleep(0.5)")
                 script_lines.append("    ")
             elif action == 'input':
                 text = op.get('text', '')
-                ref = op.get('ref', '')
-                has_coords = 'x' in op and 'y' in op
-                has_percent = 'x_percent' in op and 'y_percent' in op
-                # 判断 ref 是否为坐标格式
-                is_coords_ref = ref.startswith('coords_') or ref.startswith('coords:')
-                # 优先使用 ID，其次百分比，最后坐标
-                if ref and not is_coords_ref and (':id/' in ref or ref.startswith('com.')):
-                    # 完整格式的 resource-id
-                    script_lines.append(f"    # 步骤{step_num}: 输入文本 '{text}' (ID定位)")
-                    script_lines.append(f"    d(resourceId='{ref}').set_text('{text}')")
-                elif ref and not is_coords_ref and not has_coords:
-                    # 简短格式的 resource-id（不包含 com. 或 :id/）
-                    script_lines.append(f"    # 步骤{step_num}: 输入文本 '{text}' (ID定位)")
-                    script_lines.append(f"    d(resourceId='{ref}').set_text('{text}')")
-                elif has_percent:
-                    x_pct = op['x_percent']
-                    y_pct = op['y_percent']
-                    script_lines.append(f"    # 步骤{step_num}: 点击后输入 (百分比定位)")
+                locator_type = op.get('locator_type', '')
+                locator_value = op.get('locator_value', '')
+                x_pct = op.get('x_percent', 0)
+                y_pct = op.get('y_percent', 0)
+                text_escaped = text.replace("'", "\\'")
+                value_escaped = locator_value.replace("'", "\\'") if locator_value else ''
+                if locator_type == 'id':
+                    script_lines.append(f"    # 步骤{step_num}: 输入 '{text}' (ID定位)")
+                    script_lines.append(f"    d(resourceId='{value_escaped}').set_text('{text_escaped}')")
+                elif locator_type == 'class':
+                    script_lines.append(f"    # 步骤{step_num}: 输入 '{text}' (类名定位)")
+                    script_lines.append(f"    d(className='android.widget.EditText').set_text('{text_escaped}')")
+                elif x_pct > 0 and y_pct > 0:
+                    script_lines.append(f"    # 步骤{step_num}: 点击后输入 '{text}'")
                     script_lines.append(f"    click_by_percent(d, {x_pct}, {y_pct})")
-                    script_lines.append(f"    time.sleep(0.3)")
-                    script_lines.append(f"    d.send_keys('{text}')")
-                elif has_coords:
-                    script_lines.append(f"    # 步骤{step_num}: 点击坐标后输入 (⚠️ 可能不兼容其他分辨率)")
-                    script_lines.append(f"    d.click({op['x']}, {op['y']})")
-                    script_lines.append(f"    time.sleep(0.3)")
-                    script_lines.append(f"    d.send_keys('{text}')")
+                    script_lines.append("    time.sleep(0.3)")
+                    script_lines.append(f"    d.send_keys('{text_escaped}')")
                 else:
-                    # 兜底：无法识别的格式，跳过
-                    continue
+                    # 兼容旧格式
+                    ref = op.get('ref', '')
+                    if ref:
+                        script_lines.append(f"    # 步骤{step_num}: 输入 '{text}'")
+                        script_lines.append(f"    d(resourceId='{ref}').set_text('{text_escaped}')")
+                    else:
+                        continue
                 script_lines.append("    time.sleep(0.5)")
                 script_lines.append("    ")
             elif action == 'long_press':
-                ref = op.get('ref', '')
-                element = op.get('element', '')
+                locator_type = op.get('locator_type', '')
+                locator_value = op.get('locator_value', '')
+                locator_attr = op.get('locator_attr', 'text')
+                element_desc = op.get('element_desc', '')
                 duration = op.get('duration', 1.0)
-                has_coords = 'x' in op and 'y' in op
-                has_percent = 'x_percent' in op and 'y_percent' in op
-                # 判断 ref 是否为坐标格式
-                is_coords_ref = ref.startswith('coords_') or ref.startswith('coords:')
-                is_percent_ref = ref.startswith('percent_')
-                # 优先级：ID > 文本 > 百分比 > 坐标
-                if ref and (':id/' in ref or ref.startswith('com.')):
-                    # 使用 resource-id
-                    script_lines.append(f"    # 步骤{step_num}: 长按元素 (ID定位，最稳定)")
-                    script_lines.append(f"    d(resourceId='{ref}').long_click(duration={duration})")
-                elif ref and not is_coords_ref and not is_percent_ref and ':' not in ref:
-                    # 使用文本
-                    script_lines.append(f"    # 步骤{step_num}: 长按文本 '{ref}' (文本定位)")
-                    script_lines.append(f"    d(text='{ref}').long_click(duration={duration})")
-                elif ref and ':' in ref and not is_coords_ref and not is_percent_ref:
-                    actual_text = ref.split(':', 1)[1] if ':' in ref else ref
-                    script_lines.append(f"    # 步骤{step_num}: 长按文本 '{actual_text}' (文本定位)")
-                    script_lines.append(f"    d(text='{actual_text}').long_click(duration={duration})")
-                elif has_percent:
-                    # 使用百分比
-                    x_pct = op['x_percent']
-                    y_pct = op['y_percent']
-                    desc = f" ({element})" if element else ""
-                    script_lines.append(f"    # 步骤{step_num}: 长按位置{desc} (百分比定位，跨分辨率兼容)")
-                    script_lines.append(f"    long_press_by_percent(d, {x_pct}, {y_pct}, duration={duration})  # 原坐标: ({op.get('x', '?')}, {op.get('y', '?')})")
-                elif has_coords:
-                    # 坐标兜底
-                    desc = f" ({element})" if element else ""
-                    script_lines.append(f"    # 步骤{step_num}: 长按坐标{desc} (⚠️ 坐标定位，可能不兼容其他分辨率)")
-                    script_lines.append(f"    d.long_click({op['x']}, {op['y']}, duration={duration})")
+                x_pct = op.get('x_percent', 0)
+                y_pct = op.get('y_percent', 0)
+                value_escaped = locator_value.replace("'", "\\'") if locator_value else ''
+                if locator_type == 'text':
+                    script_lines.append(f"    # 步骤{step_num}: 长按 '{element_desc}'")
+                    if locator_attr == 'description':
+                        script_lines.append(f"    d(description='{value_escaped}').long_click(duration={duration})")
+                    else:
+                        script_lines.append(f"    d(text='{value_escaped}').long_click(duration={duration})")
+                elif locator_type == 'id':
+                    script_lines.append(f"    # 步骤{step_num}: 长按 '{element_desc}'")
+                    script_lines.append(f"    d(resourceId='{value_escaped}').long_click(duration={duration})")
+                elif locator_type == 'percent':
+                    script_lines.append(f"    # 步骤{step_num}: 长按 '{element_desc}'")
+                    script_lines.append(f"    long_press_by_percent(d, {x_pct}, {y_pct}, duration={duration})")
                 else:
-                    continue
-                script_lines.append("    time.sleep(0.5)  # 等待响应")
+                    # 兼容旧格式
+                    ref = op.get('ref', '')
+                    if ref:
+                        ref_escaped = ref.replace("'", "\\'")
+                        script_lines.append(f"    # 步骤{step_num}: 长按 '{ref}'")
+                        script_lines.append(f"    d(text='{ref_escaped}').long_click(duration={duration})")
+                    else:
+                        continue
+                script_lines.append("    time.sleep(0.5)")
                 script_lines.append("    ")
             elif action == 'swipe':
                 direction = op.get('direction', 'up')
                 script_lines.append(f"    # 步骤{step_num}: 滑动 {direction}")
-                script_lines.append(f"    d.swipe_ext('{direction}')")
+                script_lines.append(f"    swipe_direction(d, '{direction}')")
                 script_lines.append("    time.sleep(0.5)")
                 script_lines.append("    ")
@@ -2732,8 +3660,16 @@ class BasicMobileToolsLite:
             "    print('✅ 测试完成')",
             "",
             "",
+            "# ========== 直接运行入口 ==========",
             "if __name__ == '__main__':",
-            "    test_main()",
+            "    # 直接运行时，手动创建设备连接",
+            "    _d = u2.connect()",
+            "    _d.implicitly_wait(10)",
+            "    _d.app_start(PACKAGE_NAME)",
+            "    time.sleep(LAUNCH_WAIT)",
+            "    if CLOSE_AD_ON_LAUNCH:",
+            "        close_ad_if_exists(_d)",
+            f"    test_{safe_name}(_d)",
         ])
         script = '\n'.join(script_lines)
@@ -2742,8 +3678,11 @@ class BasicMobileToolsLite:
         output_dir = Path("tests")
         output_dir.mkdir(exist_ok=True)
+        # 确保文件名符合 pytest 规范（以 test_ 开头）
         if not filename.endswith('.py'):
             filename = f"{filename}.py"
+        if not filename.startswith('test_'):
+            filename = f"test_{filename}"
         file_path = output_dir / filename
         file_path.write_text(script, encoding='utf-8')
@@ -2751,7 +3690,7 @@ class BasicMobileToolsLite:
         return {
             "success": True,
             "file_path": str(file_path),
-            "message": f"✅ 脚本已生成: {file_path}",
+            "message": f"✅ 脚本已生成: {file_path}\n💡 运行方式: pytest {file_path} -v 或 python {file_path}",
             "operations_count": len(self.operation_history),
             "preview": script[:500] + "..."
         }
@@ -2920,10 +3859,28 @@ class BasicMobileToolsLite:
         try:
             import xml.etree.ElementTree as ET
-            # ========== 第1步：控件树查找关闭按钮（使用完整 UI 层级）==========
-            xml_string = self._get_full_hierarchy()
+            # ========== 第0步：先检测是否有弹窗 ==========
+            xml_string = self.client.u2.dump_hierarchy(compressed=False)
             root = ET.fromstring(xml_string)
+            screen_width = self.client.u2.info.get('displayWidth', 1440)
+            screen_height = self.client.u2.info.get('displayHeight', 3200)
+            popup_bounds, popup_confidence = self._detect_popup_with_confidence(
+                root, screen_width, screen_height
+            )
+            # 如果没有检测到弹窗，直接返回"无弹窗"
+            if popup_bounds is None or popup_confidence < 0.5:
+                result["success"] = True
+                result["method"] = None
+                result["message"] = "ℹ️ 当前页面未检测到弹窗，无需关闭"
+                result["popup_detected"] = False
+                result["popup_confidence"] = popup_confidence
+                return result
+            # ========== 第1步：控件树查找关闭按钮 ==========
             # 关闭按钮的常见特征
             close_keywords = ['关闭', '跳过', '×', 'X', 'x', 'close', 'skip', '取消']
             close_content_desc = ['关闭', '跳过', 'close', 'skip', 'dismiss']
@@ -3002,32 +3959,40 @@ class BasicMobileToolsLite:
                 cx, cy = best['center']
                 bounds = best['bounds']
-                # 点击前截图（用于自动学习）
-                pre_screenshot = None
-                if auto_learn:
-                    pre_result = self.take_screenshot(description="关闭前", compress=False)
-                    pre_screenshot = pre_result.get("screenshot_path")
-                # 点击
-                self.click_at_coords(cx, cy)
+                # 点击（click_at_coords 内部已包含应用状态检查和自动返回）
+                click_result = self.click_at_coords(cx, cy)
                 time.sleep(0.5)
+                # 🎯 再次检查应用状态（确保弹窗去除没有导致应用跳转）
+                app_check = self._check_app_switched()
+                return_result = None
+                if app_check['switched']:
+                    # 应用已跳转，说明弹窗去除失败，尝试返回目标应用
+                    return_result = self._return_to_target_app()
                 result["success"] = True
                 result["method"] = "控件树"
-                result["message"] = f"✅ 通过控件树找到关闭按钮并点击\n" \
-                                   f"   位置: ({cx}, {cy})\n" \
-                                   f"   原因: {best['reason']}"
+                msg = f"✅ 通过控件树找到关闭按钮并点击\n" \
+                      f"   位置: ({cx}, {cy})\n" \
+                      f"   原因: {best['reason']}"
-                # 自动学习：检查这个 X 是否已在模板库，不在就添加
-                if auto_learn and pre_screenshot:
-                    learn_result = self._auto_learn_template(pre_screenshot, bounds)
-                    if learn_result:
-                        result["learned_template"] = learn_result
-                        result["message"] += f"\n📚 自动学习: {learn_result}"
+                if app_check['switched']:
+                    msg += f"\n⚠️ 应用已跳转，说明弹窗去除失败"
+                    if return_result:
+                        if return_result['success']:
+                            msg += f"\n{return_result['message']}"
+                        else:
+                            msg += f"\n❌ 自动返回失败: {return_result['message']}"
+                result["message"] = msg
+                result["app_check"] = app_check
+                result["return_to_app"] = return_result
+                result["tip"] = "💡 建议调用 mobile_screenshot_with_som 确认弹窗是否已关闭"
                 return result
-            # ========== 第2步：模板匹配 ==========
+            # ========== 第2步：模板匹配（自动执行，不需要 AI 介入）==========
             screenshot_path = None
             try:
                 from .template_matcher import TemplateMatcher
@@ -3047,15 +4012,30 @@ class BasicMobileToolsLite:
                         y_pct = best["percent"]["y"]
                         # 点击
-                        self.click_by_percent(x_pct, y_pct)
+                        click_result = self.click_by_percent(x_pct, y_pct)
                         time.sleep(0.5)
+                        app_check = self._check_app_switched()
+                        return_result = None
+                        if app_check['switched']:
+                            return_result = self._return_to_target_app()
                         result["success"] = True
                         result["method"] = "模板匹配"
-                        result["message"] = f"✅ 通过模板匹配找到关闭按钮并点击\n" \
-                                           f"   模板: {best.get('template', 'unknown')}\n" \
-                                           f"   置信度: {best.get('confidence', 'N/A')}%\n" \
-                                           f"   位置: ({x_pct:.1f}%, {y_pct:.1f}%)"
+                        msg = f"✅ 通过模板匹配找到关闭按钮并点击\n" \
+                              f"   模板: {best.get('template', 'unknown')}\n" \
+                              f"   置信度: {best.get('confidence', 'N/A')}%\n" \
+                              f"   位置: ({x_pct:.1f}%, {y_pct:.1f}%)"
+                        if app_check['switched']:
+                            msg += f"\n⚠️ 应用已跳转"
+                            if return_result:
+                                msg += f"\n{return_result['message']}"
+                        result["message"] = msg
+                        result["app_check"] = app_check
+                        result["return_to_app"] = return_result
                         return result
             except ImportError:
@@ -3063,17 +4043,12 @@ class BasicMobileToolsLite:
             except Exception:
                 pass  # 模板匹配失败，继续下一步
-            # ========== 第3步：返回截图供 AI 分析 ==========
-            if not screenshot_path:
-                screenshot_result = self.take_screenshot(description="需要AI分析", compress=True)
+            # ========== 第3步：控件树和模板匹配都失败，提示 AI 使用视觉识别 ==========
             result["success"] = False
+            result["fallback"] = "vision"
             result["method"] = None
-            result["message"] = "❌ 控件树和模板匹配都未找到关闭按钮\n" \
-                               "📸 已截图，请 AI 分析图片中的 X 按钮位置\n" \
-                               "💡 找到后使用 mobile_click_by_percent(x%, y%) 点击"
-            result["screenshot"] = screenshot_result if not screenshot_path else {"screenshot_path": screenshot_path}
-            result["need_ai_analysis"] = True
+            result["popup_detected"] = True
+            result["message"] = "⚠️ 控件树和模板匹配都未找到关闭按钮，请调用 mobile_screenshot_with_som 截图后用 click_by_som 点击"
             return result

mobile-mcp-ai 2.5.9__py3-none-any.whl → 2.6.5__py3-none-any.whl

mobile-mcp-ai 2.5.9py3-none-any.whl → 2.6.5py3-none-any.whl