mobile-mcp-ai 2.6.10__py3-none-any.whl → 2.6.12__py3-none-any.whl

mobile_mcp/core/tool_selection_helper.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+工具选择辅助函数 - 帮助 AI 选择正确的工具
+
+这个模块提供工具选择建议，帮助 AI 在执行用例时遵循最佳实践。
+"""
+
+from typing import Dict, List, Optional, Tuple
+
+
+class ToolSelectionHelper:
+    """工具选择辅助类"""
+    
+    @staticmethod
+    def should_use_list_elements(scenario: str) -> Tuple[bool, str]:
+        """判断是否应该使用 mobile_list_elements()
+        
+        Args:
+            scenario: 使用场景描述
+            
+        Returns:
+            (should_use, reason) 元组
+        """
+        scenarios_should_use = [
+            "查找元素", "定位元素", "点击元素", "查找按钮", "查找文本",
+            "检查元素", "验证元素", "确认元素", "获取元素",
+            "进入页面", "新页面", "页面加载",
+        ]
+        
+        scenario_lower = scenario.lower()
+        for keyword in scenarios_should_use:
+            if keyword in scenario_lower:
+                return True, f"场景'{scenario}'应该优先使用 mobile_list_elements() 获取元素列表"
+        
+        return False, ""
+    
+    @staticmethod
+    def should_use_screenshot(scenario: str) -> Tuple[bool, str]:
+        """判断是否应该使用截图
+        
+        Args:
+            scenario: 使用场景描述
+            
+        Returns:
+            (should_use, reason) 元组
+        """
+        scenarios_should_use = [
+            "视觉确认", "查看页面", "页面截图", "展示页面",
+            "控件树找不到", "元素不存在", "游戏", "Unity",
+        ]
+        
+        scenario_lower = scenario.lower()
+        for keyword in scenarios_should_use:
+            if keyword in scenario_lower:
+                return True, f"场景'{scenario}'可以使用截图作为兜底方案"
+        
+        return False, ""
+    
+    @staticmethod
+    def get_tool_selection_advice(action: str, elements: Optional[List[Dict]] = None) -> str:
+        """获取工具选择建议
+        
+        Args:
+            action: 要执行的操作（如"点击设置按钮"）
+            elements: 已有的元素列表（如果有）
+            
+        Returns:
+            工具选择建议文本
+        """
+        advice = []
+        
+        # 如果还没有元素列表，建议先获取
+        if not elements:
+            advice.append("💡 建议：先调用 mobile_list_elements() 获取元素列表")
+            advice.append("   然后使用 mobile_click_by_text() 或 mobile_click_by_id() 点击")
+            advice.append("   仅在控件树找不到元素时，才使用 mobile_screenshot_with_som()")
+        else:
+            advice.append("✅ 已有元素列表，可以直接使用 mobile_click_by_text() 或 mobile_click_by_id()")
+            advice.append("   无需再次调用 mobile_list_elements() 或截图")
+        
+        return "\n".join(advice)
+    
+    @staticmethod
+    def find_element_in_list(elements: List[Dict], 
+                             text: Optional[str] = None,
+                             resource_id: Optional[str] = None,
+                             content_desc: Optional[str] = None) -> Optional[Dict]:
+        """在元素列表中查找元素
+        
+        Args:
+            elements: 元素列表
+            text: 要查找的文本
+            resource_id: 要查找的 resource_id
+            content_desc: 要查找的 content_desc
+            
+        Returns:
+            找到的元素，如果未找到返回 None
+        """
+        for elem in elements:
+            if text and elem.get("text") == text:
+                return elem
+            if resource_id and elem.get("resource_id") == resource_id:
+                return elem
+            if content_desc and elem.get("content_desc") == content_desc:
+                return elem
+        
+        return None
+    
+    @staticmethod
+    def suggest_click_method(elements: List[Dict], target_text: str) -> Dict:
+        """建议点击方法
+        
+        Args:
+            elements: 元素列表
+            target_text: 目标文本
+            
+        Returns:
+            建议信息字典
+        """
+        # 查找元素
+        target_elem = ToolSelectionHelper.find_element_in_list(elements, text=target_text)
+        
+        if target_elem:
+            # 元素存在，建议使用文本点击
+            return {
+                "found": True,
+                "method": "mobile_click_by_text",
+                "params": {"text": target_text},
+                "reason": f"元素'{target_text}'在控件树中找到，建议使用 mobile_click_by_text('{target_text}')"
+            }
+        else:
+            # 元素不存在，建议使用截图
+            return {
+                "found": False,
+                "method": "mobile_screenshot_with_som",
+                "params": {},
+                "reason": f"元素'{target_text}'在控件树中未找到，建议使用 mobile_screenshot_with_som() 作为兜底方案"
+            }
+
+
+# 导出辅助函数
+def should_use_list_elements_first(action: str) -> bool:
+    """判断是否应该优先使用 list_elements
+    
+    Args:
+        action: 要执行的操作描述
+        
+    Returns:
+        是否应该优先使用 list_elements
+    """
+    helper = ToolSelectionHelper()
+    should_use, _ = helper.should_use_list_elements(action)
+    return should_use
+
+
+def get_click_suggestion(elements: List[Dict], target_text: str) -> Dict:
+    """获取点击建议
+    
+    Args:
+        elements: 元素列表
+        target_text: 目标文本
+        
+    Returns:
+        点击建议字典
+    """
+    helper = ToolSelectionHelper()
+    return helper.suggest_click_method(elements, target_text)