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

mobile_mcp/mcp_tools/mcp_server.py

@@ -102,12 +102,19 @@ class MobileMCPServer:
         self.tools = None
         self._initialized = False
         self._last_error = None  # 保存最后一次连接失败的错误
+        
+        # Token 优化配置
+        try:
+            from mobile_mcp.config import Config
+            self._compact_desc = Config.COMPACT_TOOL_DESCRIPTION
+        except ImportError:
+            self._compact_desc = True  # 默认开启精简模式
     
     @staticmethod
     def format_response(result) -> str:
-        """统一格式化返回值"""
+        """统一格式化返回值（Token 优化：无缩进）"""
         if isinstance(result, (dict, list)):
-            return json.dumps(result, ensure_ascii=False, indent=2)
+            return json.dumps(result, ensure_ascii=False, separators=(',', ':'))
         return str(result)
     
     async def initialize(self):
@@ -198,42 +205,83 @@ class MobileMCPServer:
         return "android"
     
     def get_tools(self):
-        """注册 MCP 工具（20 个）"""
+        """注册 MCP 工具"""
         tools = []
         
+        # 根据配置选择精简或完整描述
+        compact = getattr(self, '_compact_desc', True)
+        
         # ==================== 元素定位（优先使用）====================
+        if compact:
+            desc_list_elements = "📋 【首选】列出页面元素(token低)。返回text/id用于点击，替代截图确认页面状态。"
+        else:
+            desc_list_elements = ("📋 【⭐首选工具】列出页面所有可交互元素\n\n"
+                       "🚀 Token 优化：返回文本数据(~500 tokens)，远小于截图(~2000 tokens)！\n\n"
+                       "✅ 推荐使用场景：\n"
+                       "- 点击前确认元素存在\n"
+                       "- 点击后确认页面变化（替代截图确认）\n"
+                       "- 获取 text/id 用于 click_by_text/click_by_id\n\n"
+                       "❌ 不要用截图确认页面，用此工具！\n"
+                       "📌 只有需要看视觉布局时才用截图")
+        
         tools.append(Tool(
             name="mobile_list_elements",
-            description="📋 列出页面所有可交互元素\n\n"
-                       "⚠️ 【重要】点击元素前必须先调用此工具！\n"
-                       "如果元素在控件树中存在，使用 click_by_text 或 click_by_id 定位。\n"
-                       "只有当此工具返回空或找不到目标元素时，才使用截图+坐标方式。\n\n"
-                       "📌 控件树定位优势：\n"
-                       "- 实时检测元素是否存在\n"
-                       "- 元素消失时会报错，不会误点击\n"
-                       "- 跨设备兼容性好",
+            description="""📋 列出页面所有可交互元素（⭐⭐ 第一优先级！）
+
+⚠️ 【核心原则】优先使用控件树定位，截图仅作为兜底方案
+
+🎯 使用场景（优先使用）：
+1. ✅ 首次进入页面时：获取所有可交互元素
+2. ✅ 查找特定元素时：检查元素是否存在
+3. ✅ 验证操作结果时：确认元素是否出现/消失
+4. ✅ 需要精确点击时：获取元素的 resource_id 或 text
+
+📌 控件树定位优势：
+- ⚡ 速度快：直接获取 XML，无需截图和图像处理（快 5-20 倍）
+- 🎯 准确：获取完整的元素属性（resource_id、text、bounds、clickable 等）
+- 💾 高效：不生成图片文件，节省存储和传输
+- 🔄 可复用：一次获取的元素列表可用于多次操作
+
+⚡ 推荐流程：
+1. 调用 mobile_list_elements() 获取元素列表
+2. 从元素列表中找到目标元素（通过 text 或 resource_id）
+3. 使用 mobile_click_by_text() 或 mobile_click_by_id() 点击
+4. 仅在控件树找不到元素时，才使用 mobile_screenshot_with_som()
+
+❌ 错误用法：
+- 每次都先截图，不先调用 list_elements
+- 重复调用 list_elements，不复用已获取的元素列表
+
+✅ 正确用法：
+elements = mobile_list_elements()  # 一次获取
+mobile_click_by_text("设置")        # 直接点击
+mobile_click_by_text("退出登录")    # 复用元素列表""",
             inputSchema={"type": "object", "properties": {}, "required": []}
         ))
         
         # ==================== 截图（视觉兜底）====================
+        if compact:
+            desc_screenshot = "📸 截图(token高~2000)。优先用list_elements(~500)确认页面状态。"
+        else:
+            desc_screenshot = ("📸 截图查看屏幕内容（⚠️ Token 消耗高 ~2000）\n\n"
+                       "❌ 【不推荐】确认页面状态请用 list_elements（Token 仅 ~500）！\n\n"
+                       "✅ 仅在以下场景使用：\n"
+                       "- 需要看视觉布局/图片内容\n"
+                       "- 元素无 text/id，只能靠位置点击\n"
+                       "- 调试问题需要可视化\n\n"
+                       "💡 compress=false 可获取原图（用于添加模板）")
+        
         tools.append(Tool(
             name="mobile_take_screenshot",
-            description="📸 截图查看屏幕内容\n\n"
-                       "⚠️ 【推荐使用 mobile_screenshot_with_som 代替！】\n"
-                       "SoM 截图会给元素标号，AI 可以直接说'点击几号'，更精准！\n\n"
-                       "🎯 本工具仅用于：\n"
-                       "- 快速确认页面状态（不需要点击时）\n"
-                       "- 操作后确认结果\n"
-                       "- compress=false 时可获取原始分辨率截图（用于添加模板）\n\n"
-                       "💡 如需点击元素，请用 mobile_screenshot_with_som + mobile_click_by_som",
+            description=desc_screenshot,
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "description": {"type": "string", "description": "截图描述（可选）"},
-                    "compress": {"type": "boolean", "description": "是否压缩，默认 true。设为 false 可获取原始分辨率（用于模板添加）", "default": True},
-                    "crop_x": {"type": "integer", "description": "局部裁剪中心 X 坐标（屏幕坐标，0 表示不裁剪）"},
-                    "crop_y": {"type": "integer", "description": "局部裁剪中心 Y 坐标（屏幕坐标，0 表示不裁剪）"},
-                    "crop_size": {"type": "integer", "description": "裁剪区域大小（推荐 200-400，0 表示不裁剪）"}
+                    "description": {"type": "string", "description": "截图描述"},
+                    "compress": {"type": "boolean", "description": "是否压缩", "default": True},
+                    "crop_x": {"type": "integer", "description": "裁剪中心 X"},
+                    "crop_y": {"type": "integer", "description": "裁剪中心 Y"},
+                    "crop_size": {"type": "integer", "description": "裁剪大小"}
                 },
                 "required": []
             }
@@ -245,22 +293,54 @@ class MobileMCPServer:
             inputSchema={"type": "object", "properties": {}, "required": []}
         ))
         
+        if compact:
+            desc_som = "📸 SoM截图(token高)。元素有text时优先用list_elements+click_by_text。"
+        else:
+            desc_som = ("📸🏷️ Set-of-Mark 截图（⚠️ Token 消耗高 ~2000）\n\n"
+                       "【智能标注】给每个可点击元素画框+编号\n\n"
+                       "❌ 【不推荐常规使用】：\n"
+                       "- 如果元素有 text，用 list_elements + click_by_text 更省 token\n"
+                       "- 确认页面状态用 list_elements，不要截图确认！\n\n"
+                       "✅ 仅在以下场景使用：\n"
+                       "- 元素无 text/id，只能看图点击\n"
+                       "- 需要视觉布局信息\n"
+                       "- 首次探索未知页面\n\n"
+                       "💡 点击后用 list_elements 确认，不要再截图！")
+        
         tools.append(Tool(
             name="mobile_screenshot_with_som",
-            description="📸🏷️ Set-of-Mark 截图（⭐⭐ 强烈推荐！默认截图方式）\n\n"
-                       "【智能标注】给每个可点击元素画框+编号。\n"
-                       "AI 看图直接说'点击 3 号'，调用 mobile_click_by_som(3) 即可！\n\n"
-                       "🎯 优势：\n"
-                       "- 元素有编号，精准点击不会误触\n"
-                       "- 适用于所有页面和所有操作\n\n"
-                       "⚡ 推荐流程：\n"
-                       "1. 找不到目标元素时，优先调用此工具\n"
-                       "2. 看标注图，找到目标元素编号\n"
-                       "3. 调用 mobile_click_by_som(编号) 精准点击\n"
-                       "4. 🔴【必须】点击后再次截图确认操作是否成功！\n\n"
-                       "💡 弹窗检测：\n"
-                       "- check_popup=True: 明确弹窗场景时使用（如调用 mobile_close_popup 前）\n"
-                       "- check_popup=False: 普通截图，不检测弹窗（默认）",
+            description="""📸🏷️ Set-of-Mark 截图（⚠️ 兜底方案，非首选）
+
+⚠️ 【重要】仅在控件树定位失败时使用！
+
+🎯 使用场景（兜底方案）：
+1. ⚠️ 控件树定位失败：
+   - mobile_list_elements() 返回空或找不到目标元素
+   - 元素不在控件树中（如游戏、Unity 应用）
+2. ✅ 需要视觉确认：
+   - 首次进入新页面，需要了解整体布局
+   - 操作后需要视觉确认页面变化
+   - 需要给用户展示页面状态
+
+⚡ 推荐流程（优先使用控件树）：
+1. 先调用 mobile_list_elements() 获取元素列表
+2. 如果找到目标元素 → 使用 mobile_click_by_text() 或 mobile_click_by_id()
+3. 如果找不到 → 才调用 mobile_screenshot_with_som()
+4. 从截图分析找到元素编号 → 使用 mobile_click_by_som(编号)
+
+❌ 错误用法：
+- 每次都先截图，不先调用 list_elements
+- 在控件树能找到元素时也使用截图
+
+✅ 正确用法：
+elements = mobile_list_elements()  # 先尝试控件树
+if not find_target(elements):
+    screenshot = mobile_screenshot_with_som()  # 控件树失败才截图
+    mobile_click_by_som(index)
+
+💡 弹窗检测：
+- check_popup=True: 明确弹窗场景时使用（如调用 mobile_close_popup 前）
+- check_popup=False: 普通截图，不检测弹窗（默认）""",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -276,17 +356,11 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_click_by_som",
-            description="🎯 根据 SoM 编号点击元素\n\n"
-                       "配合 mobile_screenshot_with_som 使用。\n"
-                       "看图后直接说'点击 3 号'，调用此函数即可。\n\n"
-                       "⚠️ 【重要】点击后建议再次截图确认操作是否成功！",
+            description="🎯 根据SoM编号点击。配合screenshot_with_som使用。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "index": {
-                        "type": "integer",
-                        "description": "元素编号（从 1 开始，对应截图中的标注数字）"
-                    }
+                    "index": {"type": "integer", "description": "元素编号(从1开始)"}
                 },
                 "required": ["index"]
             }
@@ -294,97 +368,116 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_screenshot_with_grid",
-            description="📸📏 带网格坐标的截图（精确定位神器！）\n\n"
-                       "在截图上绘制网格线和坐标刻度，帮助快速定位元素位置。\n"
-                       "如果检测到弹窗，会用绿色圆圈标注可能的关闭按钮位置。\n\n"
-                       "🎯 适用场景：\n"
-                       "- 需要精确知道某个元素的坐标\n"
-                       "- 关闭广告弹窗时定位 X 按钮\n"
-                       "- 元素不在控件树中时的视觉定位\n\n"
-                       "💡 返回信息：\n"
-                       "- 带网格标注的截图\n"
-                       "- 弹窗边界坐标（如果检测到）\n"
-                       "- 可能的关闭按钮位置列表（带优先级）\n\n"
-                       "🔴 【必须】点击后必须再次截图确认操作是否成功！",
+            description="📸 带网格坐标截图。用于精确定位元素坐标。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "grid_size": {
-                        "type": "integer", 
-                        "description": "网格间距（像素），默认 100。值越小网格越密，建议 50-200"
-                    },
-                    "show_popup_hints": {
-                        "type": "boolean",
-                        "description": "是否显示弹窗关闭按钮提示位置，默认 true"
-                    }
+                    "grid_size": {"type": "integer", "description": "网格间距(px),默认100"},
+                    "show_popup_hints": {"type": "boolean", "description": "显示弹窗提示"}
                 },
                 "required": []
             }
         ))
         
         # ==================== 点击操作 ====================
+        if compact:
+            desc_click_text = "👆 文本点击（推荐）。verify可验证点击结果，无需截图确认。position可选top/bottom/left/right。"
+        else:
+            desc_click_text = ("👆 通过文本点击元素（⭐ 最推荐）\n\n"
+                       "✅ 最稳定的定位方式，跨设备兼容\n"
+                       "✅ 元素不存在会报错，不会误点击\n\n"
+                       "🚀 Token 优化流程：\n"
+                       "1. list_elements 确认元素存在\n"
+                       "2. click_by_text 点击\n"
+                       "3. list_elements 确认页面变化（❌不要截图确认！）\n\n"
+                       "📍 position 参数：多个相同文案时指定位置\n"
+                       "   - top/bottom/left/right/center\n\n"
+                       "🔍 verify 参数：点击后自动验证文本是否出现\n"
+                       "   - 设置后无需额外调用 list_elements 确认")
+        
         tools.append(Tool(
             name="mobile_click_by_text",
-            description="👆 通过文本点击元素（最推荐）\n\n"
-                       "✅ 最稳定的定位方式，跨设备兼容\n"
-                       "✅ 实时检测元素是否存在，元素不存在会报错\n"
-                       "✅ 不会误点击到其他位置\n"
-                       "📋 使用前先调用 mobile_list_elements 确认元素文本\n"
-                       "💡 定位优先级：文本 > ID > 百分比 > 坐标\n\n"
-                       "📍 当页面有多个相同文案时，可使用 position 参数指定位置：\n"
-                       "   - 垂直方向: \"top\"/\"upper\"/\"上\", \"bottom\"/\"lower\"/\"下\", \"middle\"/\"center\"/\"中\"\n"
-                       "   - 水平方向: \"left\"/\"左\", \"right\"/\"右\", \"center\"/\"中\"\n"
-                       "   例如：点击\"底部\"的\"微剧\"tab，使用 position=\"bottom\"",
+            description="""👆 通过文本点击元素（⭐⭐ 第一优先级点击方式）
+
+✅ 最稳定的定位方式，跨设备兼容
+✅ 实时检测元素是否存在，元素不存在会报错
+✅ 不会误点击到其他位置
+
+⚡ 使用流程（必须）：
+1. 先调用 mobile_list_elements() 获取元素列表
+2. 从元素列表中找到目标元素的 text
+3. 调用 mobile_click_by_text("文本") 点击
+
+💡 定位优先级：文本 > ID > 百分比 > 坐标
+
+📍 当页面有多个相同文案时，可使用 position 参数指定位置：
+   - 垂直方向: "top"/"upper"/"上", "bottom"/"lower"/"下", "middle"/"center"/"中"
+   - 水平方向: "left"/"左", "right"/"右", "center"/"中"
+   例如：点击"底部"的"微剧"tab，使用 position="bottom"
+
+❌ 错误用法：
+- 不先调用 list_elements，直接猜测文本点击
+- 在控件树能找到元素时使用截图+坐标点击
+
+✅ 正确用法：
+elements = mobile_list_elements()  # 先获取元素列表
+mobile_click_by_text("设置")        # 从元素列表中找到后直接点击""",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "text": {"type": "string", "description": "元素的文本内容（精确匹配）"},
-                    "position": {"type": "string", "description": "位置信息（可选）。当有多个相同文案时使用，支持：top/bottom/left/right/middle 或 上/下/左/右/中"}
+                    "text": {"type": "string", "description": "元素文本"},
+                    "position": {"type": "string", "description": "位置：top/bottom/left/right"},
+                    "verify": {"type": "string", "description": "点击后验证的文本（可选）"}
                 },
                 "required": ["text"]
             }
         ))
         
+        if compact:
+            desc_click_id = "👆 通过resource-id点击。index指定第几个(从0开始)。点击后用list_elements确认。"
+        else:
+            desc_click_id = ("👆 通过 resource-id 点击元素（推荐）\n\n"
+                       "✅ 稳定的定位方式，元素不存在会报错\n"
+                       "📋 使用前 list_elements 获取元素 ID\n"
+                       "📋 点击后 list_elements 确认（❌不要截图确认！）\n"
+                       "💡 多个相同 ID 时用 index 指定第几个（从 0 开始）")
+        
         tools.append(Tool(
             name="mobile_click_by_id",
-            description="👆 通过 resource-id 点击元素（推荐）\n\n"
-                       "✅ 稳定的定位方式\n"
-                       "✅ 实时检测元素是否存在，元素不存在会报错\n"
-                       "📋 使用前先调用 mobile_list_elements 获取元素 ID\n"
-                       "💡 当有多个相同 ID 的元素时，用 index 指定第几个（从 0 开始）\n"
-                       "💡 定位优先级：文本 > ID > 百分比 > 坐标",
+            description=desc_click_id,
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "resource_id": {"type": "string", "description": "元素的 resource-id"},
-                    "index": {"type": "integer", "description": "第几个元素（从 0 开始），默认 0 表示第一个", "default": 0}
+                    "resource_id": {"type": "string", "description": "resource-id"},
+                    "index": {"type": "integer", "description": "第几个（从0开始）", "default": 0}
                 },
                 "required": ["resource_id"]
             }
         ))
         
+        if compact:
+            desc_click_coords = "👆 坐标点击(兜底)。优先用click_by_text/id，点击后用list_elements确认。"
+        else:
+            desc_click_coords = ("👆 点击指定坐标（⚠️ 兜底方案）\n\n"
+                       "❌ 优先使用 click_by_text 或 click_by_id！\n"
+                       "仅在 list_elements 无法获取元素时使用。\n\n"
+                       "📐 坐标转换：截图返回的参数直接传入即可\n"
+                       "📋 点击后用 list_elements 确认（❌不要截图确认！）")
+        
         tools.append(Tool(
             name="mobile_click_at_coords",
-            description="👆 点击指定坐标（兜底方案）\n\n"
-                       "⚠️ 【重要】优先使用 mobile_click_by_text 或 mobile_click_by_id！\n"
-                       "仅在 mobile_list_elements 无法获取元素时使用此工具。\n\n"
-                       "⚠️ 【时序限制】截图分析期间页面可能变化：\n"
-                       "- 坐标是基于截图时刻的，点击时页面可能已不同\n"
-                       "- 如果误点击，调用 mobile_press_key(back) 返回\n"
-                       "- 对于定时弹窗（如广告），建议等待其自动消失\n\n"
-                       "📐 坐标转换：截图返回的 image_width/height 等参数直接传入即可\n\n"
-                       "🔴 【必须】点击后必须再次截图确认操作是否成功！",
+            description=desc_click_coords,
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "x": {"type": "number", "description": "X 坐标（来自 AI 分析截图）"},
-                    "y": {"type": "number", "description": "Y 坐标（来自 AI 分析截图）"},
-                    "image_width": {"type": "number", "description": "压缩后图片宽度（截图返回的 image_width）"},
-                    "image_height": {"type": "number", "description": "压缩后图片高度（截图返回的 image_height）"},
-                    "original_img_width": {"type": "number", "description": "原图宽度（截图返回的 original_img_width）"},
-                    "original_img_height": {"type": "number", "description": "原图高度（截图返回的 original_img_height）"},
-                    "crop_offset_x": {"type": "number", "description": "局部截图 X 偏移（裁剪截图时传入）"},
-                    "crop_offset_y": {"type": "number", "description": "局部截图 Y 偏移（裁剪截图时传入）"}
+                    "x": {"type": "number", "description": "X 坐标"},
+                    "y": {"type": "number", "description": "Y 坐标"},
+                    "image_width": {"type": "number", "description": "图片宽度"},
+                    "image_height": {"type": "number", "description": "图片高度"},
+                    "original_img_width": {"type": "number", "description": "原图宽"},
+                    "original_img_height": {"type": "number", "description": "原图高"},
+                    "crop_offset_x": {"type": "number", "description": "裁剪X偏移"},
+                    "crop_offset_y": {"type": "number", "description": "裁剪Y偏移"}
                 },
                 "required": ["x", "y"]
             }
@@ -392,15 +485,7 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_click_by_percent",
-            description="👆 通过百分比位置点击（跨设备兼容！）。\n\n"
-                       "🎯 原理：屏幕左上角是 (0%, 0%)，右下角是 (100%, 100%)\n"
-                       "📐 示例：\n"
-                       "   - (50, 50) = 屏幕正中央\n"
-                       "   - (10, 5) = 左上角附近\n"
-                       "   - (85, 90) = 右下角附近\n\n"
-                       "✅ 优势：同样的百分比在不同分辨率设备上都能点到相同相对位置\n"
-                       "💡 录制一次，多设备回放\n\n"
-                       "🔴 【必须】点击后必须再次截图确认操作是否成功！",
+            description="👆 百分比点击。(50,50)=屏幕中心。跨设备兼容。",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -414,15 +499,12 @@ class MobileMCPServer:
         # ==================== 长按操作 ====================
         tools.append(Tool(
             name="mobile_long_press_by_id",
-            description="👆 通过 resource-id 长按（⭐⭐ 最稳定！）\n\n"
-                       "✅ 最稳定的长按定位方式，跨设备完美兼容\n"
-                       "📋 使用前请先调用 mobile_list_elements 获取元素 ID\n"
-                       "💡 生成的脚本使用 d(resourceId='...').long_click() 定位，最稳定",
+            description="👆 通过resource-id长按。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "resource_id": {"type": "string", "description": "元素的 resource-id"},
-                    "duration": {"type": "number", "description": "长按持续时间（秒），默认 1.0"}
+                    "resource_id": {"type": "string", "description": "resource-id"},
+                    "duration": {"type": "number", "description": "长按秒数,默认1.0"}
                 },
                 "required": ["resource_id"]
             }
@@ -430,15 +512,12 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_long_press_by_text",
-            description="👆 通过文本长按（⭐ 推荐！）\n\n"
-                       "✅ 优势：跨设备兼容，不受屏幕分辨率影响\n"
-                       "📋 使用前请先调用 mobile_list_elements 确认元素有文本\n"
-                       "💡 生成的脚本使用 d(text='...').long_click() 定位，稳定可靠",
+            description="👆 通过文本长按。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "text": {"type": "string", "description": "元素的文本内容（精确匹配）"},
-                    "duration": {"type": "number", "description": "长按持续时间（秒），默认 1.0"}
+                    "text": {"type": "string", "description": "文本内容"},
+                    "duration": {"type": "number", "description": "长按秒数,默认1.0"}
                 },
                 "required": ["text"]
             }
@@ -446,20 +525,13 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_long_press_by_percent",
-            description="👆 通过百分比位置长按（跨设备兼容！）\n\n"
-                       "🎯 原理：屏幕左上角是 (0%, 0%)，右下角是 (100%, 100%)\n"
-                       "📐 示例：\n"
-                       "   - (50, 50) = 屏幕正中央\n"
-                       "   - (10, 5) = 左上角附近\n"
-                       "   - (85, 90) = 右下角附近\n\n"
-                       "✅ 优势：同样的百分比在不同分辨率设备上都能长按到相同相对位置\n"
-                       "💡 录制一次，多设备回放",
+            description="👆 百分比长按。(50,50)=屏幕中心。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "x_percent": {"type": "number", "description": "X 轴百分比 (0-100)"},
-                    "y_percent": {"type": "number", "description": "Y 轴百分比 (0-100)"},
-                    "duration": {"type": "number", "description": "长按持续时间（秒），默认 1.0"}
+                    "x_percent": {"type": "number", "description": "X百分比(0-100)"},
+                    "y_percent": {"type": "number", "description": "Y百分比(0-100)"},
+                    "duration": {"type": "number", "description": "长按秒数,默认1.0"}
                 },
                 "required": ["x_percent", "y_percent"]
             }
@@ -467,28 +539,19 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_long_press_at_coords",
-            description="👆 长按指定坐标（⚠️ 兜底方案，优先用文本/ID定位！）\n\n"
-                       "🎯 仅在以下场景使用：\n"
-                       "- 游戏（Unity/Cocos）无法获取元素\n"
-                       "- mobile_list_elements 返回空\n"
-                       "- 元素没有 id 和 text\n\n"
-                       "⚠️ 【坐标转换】截图返回的参数直接传入：\n"
-                       "   - image_width/image_height: 压缩后尺寸（AI 看到的）\n"
-                       "   - original_img_width/original_img_height: 原图尺寸（用于转换）\n"
-                       "   - crop_offset_x/crop_offset_y: 局部截图偏移\n\n"
-                       "✅ 自动记录百分比坐标，生成脚本时转换为跨分辨率兼容的百分比定位",
+            description="👆 坐标长按(兜底)。优先用text/id。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "x": {"type": "number", "description": "X 坐标（来自 AI 分析截图）"},
-                    "y": {"type": "number", "description": "Y 坐标（来自 AI 分析截图）"},
-                    "duration": {"type": "number", "description": "长按持续时间（秒），默认 1.0"},
-                    "image_width": {"type": "number", "description": "压缩后图片宽度"},
-                    "image_height": {"type": "number", "description": "压缩后图片高度"},
-                    "original_img_width": {"type": "number", "description": "原图宽度"},
-                    "original_img_height": {"type": "number", "description": "原图高度"},
-                    "crop_offset_x": {"type": "number", "description": "局部截图 X 偏移"},
-                    "crop_offset_y": {"type": "number", "description": "局部截图 Y 偏移"}
+                    "x": {"type": "number", "description": "X坐标"},
+                    "y": {"type": "number", "description": "Y坐标"},
+                    "duration": {"type": "number", "description": "长按秒数"},
+                    "image_width": {"type": "number", "description": "图片宽"},
+                    "image_height": {"type": "number", "description": "图片高"},
+                    "original_img_width": {"type": "number", "description": "原图宽"},
+                    "original_img_height": {"type": "number", "description": "原图高"},
+                    "crop_offset_x": {"type": "number", "description": "裁剪X偏移"},
+                    "crop_offset_y": {"type": "number", "description": "裁剪Y偏移"}
                 },
                 "required": ["x", "y"]
             }
@@ -497,12 +560,12 @@ class MobileMCPServer:
         # ==================== 输入操作 ====================
         tools.append(Tool(
             name="mobile_input_text_by_id",
-            description="⌨️ 在输入框输入文本。需要先用 mobile_list_elements 获取输入框 ID。",
+            description="⌨️ 通过ID输入文本。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "resource_id": {"type": "string", "description": "输入框的 resource-id"},
-                    "text": {"type": "string", "description": "要输入的文本"}
+                    "resource_id": {"type": "string", "description": "resource-id"},
+                    "text": {"type": "string", "description": "输入文本"}
                 },
                 "required": ["resource_id", "text"]
             }
@@ -510,13 +573,13 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_input_at_coords",
-            description="⌨️ 点击坐标后输入文本。适合游戏等无法获取元素 ID 的场景。",
+            description="⌨️ 坐标输入文本。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "x": {"type": "number", "description": "输入框 X 坐标"},
-                    "y": {"type": "number", "description": "输入框 Y 坐标"},
-                    "text": {"type": "string", "description": "要输入的文本"}
+                    "x": {"type": "number", "description": "X坐标"},
+                    "y": {"type": "number", "description": "Y坐标"},
+                    "text": {"type": "string", "description": "输入文本"}
                 },
                 "required": ["x", "y", "text"]
             }
@@ -525,105 +588,25 @@ class MobileMCPServer:
         # ==================== 导航操作 ====================
         tools.append(Tool(
             name="mobile_swipe",
-            description="👆 滑动屏幕。方向：up/down/left/right\n\n"
-                       "🎯 适用场景：\n"
-                       "- 滑动页面（列表、页面切换）\n"
-                       "- 拖动进度条/滑块（SeekBar、ProgressBar）\n"
-                       "- 滑动选择器（Picker、Slider）\n\n"
-                       "💡 左右滑动时，可指定高度坐标或百分比：\n"
-                       "- y: 指定高度坐标（像素）\n"
-                       "- y_percent: 指定高度百分比 (0-100)\n"
-                       "- 两者都未指定时，使用屏幕中心高度\n"
-                       "- 📌 拖动进度条时，使用进度条的 Y 位置（百分比或像素）\n\n"
-                       "💡 横向滑动（left/right）时，可指定滑动距离：\n"
-                       "- distance: 滑动距离（像素）\n"
-                       "- distance_percent: 滑动距离百分比 (0-100)\n"
-                       "- 两者都未指定时，使用默认距离（屏幕宽度的 60%）\n"
-                       "- 📌 拖动进度条时，distance_percent 控制拖动幅度\n\n"
-                       "💡 拖动进度条示例：\n"
-                       "- 倒退：direction='left', y_percent=91（进度条位置）, distance_percent=30\n"
-                       "- 前进：direction='right', y_percent=91, distance_percent=30\n\n"
-                       "⚠️ **推荐使用 mobile_drag_progress_bar 拖动进度条**（自动检测进度条位置，无需手动指定）",
+            description="👆 滑动。方向:up/down/left/right。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "direction": {
-                        "type": "string",
-                        "enum": ["up", "down", "left", "right"],
-                        "description": "滑动方向"
-                    },
-                    "y": {
-                        "type": "integer",
-                        "description": "左右滑动时指定的高度坐标（像素，0-屏幕高度）"
-                    },
-                    "y_percent": {
-                        "type": "number",
-                        "description": "左右滑动时指定的高度百分比 (0-100)"
-                    },
-                    "distance": {
-                        "type": "integer",
-                        "description": "横向滑动时指定的滑动距离（像素），仅用于 left/right"
-                    },
-                    "distance_percent": {
-                        "type": "number",
-                        "description": "横向滑动时指定的滑动距离百分比 (0-100)，仅用于 left/right"
-                    }
+                    "direction": {"type": "string", "enum": ["up", "down", "left", "right"], "description": "方向"},
+                    "y": {"type": "integer", "description": "左右滑动高度(px)"},
+                    "y_percent": {"type": "number", "description": "左右滑动高度(%)"}
                 },
                 "required": ["direction"]
             }
         ))
         
-        tools.append(Tool(
-            name="mobile_drag_progress_bar",
-            description="🎯 智能拖动进度条（⭐⭐ 推荐用于拖动视频/音频进度条）\n\n"
-                       "✅ **自动检测进度条是否可见**：\n"
-                       "- 如果进度条已显示，直接拖动（无需先点击播放区域）\n"
-                       "- 如果进度条未显示，自动点击播放区域显示控制栏，再拖动\n\n"
-                       "🎯 优势：\n"
-                       "- 自动检测进度条位置，无需手动指定 y_percent\n"
-                       "- 智能判断是否需要显示控制栏\n"
-                       "- 使用 swipe 拖动，更稳定可靠\n\n"
-                       "💡 参数说明：\n"
-                       "- direction: 'left'（倒退）或 'right'（前进），默认 'right'\n"
-                       "- distance_percent: 拖动距离百分比 (0-100)，默认 30%\n"
-                       "- y_percent: 进度条位置（可选，未指定则自动检测）\n"
-                       "- y: 进度条位置坐标（可选，未指定则自动检测）\n\n"
-                       "📋 使用示例：\n"
-                       "- 前进30%：mobile_drag_progress_bar(direction='right', distance_percent=30)\n"
-                       "- 倒退30%：mobile_drag_progress_bar(direction='left', distance_percent=30)\n"
-                       "- 前进到指定位置：先点击进度条位置，或使用 mobile_swipe",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "direction": {
-                        "type": "string",
-                        "enum": ["left", "right"],
-                        "description": "拖动方向：'left'（倒退）或 'right'（前进），默认 'right'"
-                    },
-                    "distance_percent": {
-                        "type": "number",
-                        "description": "拖动距离百分比 (0-100)，默认 30%"
-                    },
-                    "y_percent": {
-                        "type": "number",
-                        "description": "进度条的垂直位置百分比 (0-100)，可选，未指定则自动检测"
-                    },
-                    "y": {
-                        "type": "integer",
-                        "description": "进度条的垂直位置坐标（像素），可选，未指定则自动检测"
-                    }
-                },
-                "required": []
-            }
-        ))
-        
         tools.append(Tool(
             name="mobile_press_key",
-            description="⌨️ 按键操作。支持：home, back, enter, search",
+            description="⌨️ 按键:home/back/enter/search。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "key": {"type": "string", "description": "按键名称：home, back, enter, search"}
+                    "key": {"type": "string", "description": "按键名"}
                 },
                 "required": ["key"]
             }
@@ -631,11 +614,11 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_wait",
-            description="⏰ 等待指定时间。用于等待页面加载、动画完成等。",
+            description="⏰ 等待指定秒数。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "seconds": {"type": "number", "description": "等待时间（秒）"}
+                    "seconds": {"type": "number", "description": "等待秒数"}
                 },
                 "required": ["seconds"]
             }
@@ -644,16 +627,11 @@ class MobileMCPServer:
         # ==================== 应用管理 ====================
         tools.append(Tool(
             name="mobile_launch_app",
-            description="""🚀 启动应用
-
-🎯 弹窗检测场景：启动应用后会自动检测弹窗（启动应用场景）
-
-启动后建议等待 2-3 秒让页面加载。
-如果检测到弹窗，返回结果中会包含 popup_detected=true，建议调用 mobile_close_popup() 关闭弹窗。""",
+            description="🚀 启动应用。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "package_name": {"type": "string", "description": "应用包名"}
+                    "package_name": {"type": "string", "description": "包名"}
                 },
                 "required": ["package_name"]
             }
@@ -665,7 +643,7 @@ class MobileMCPServer:
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "package_name": {"type": "string", "description": "应用包名"}
+                    "package_name": {"type": "string", "description": "包名"}
                 },
                 "required": ["package_name"]
             }
@@ -673,11 +651,11 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_list_apps",
-            description="📦 列出已安装的应用。可按关键词过滤。",
+            description="📦 列出应用。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "filter": {"type": "string", "description": "过滤关键词（可选）"}
+                    "filter": {"type": "string", "description": "过滤词"}
                 },
                 "required": []
             }
@@ -686,33 +664,31 @@ class MobileMCPServer:
         # ==================== 设备管理 ====================
         tools.append(Tool(
             name="mobile_list_devices",
-            description="📱 列出已连接的设备。",
+            description="📱 列出设备。",
             inputSchema={"type": "object", "properties": {}, "required": []}
         ))
         
         tools.append(Tool(
             name="mobile_check_connection",
-            description="🔌 检查设备连接状态。",
+            description="🔌 检查连接。",
             inputSchema={"type": "object", "properties": {}, "required": []}
         ))
         
         # ==================== 辅助工具 ====================
-        tools.append(Tool(
-            name="mobile_find_close_button",
-            description="""🔍 智能查找关闭按钮（只找不点，返回位置）
+        if compact:
+            desc_find_close = "🔍 查找关闭按钮（只找不点）。返回坐标和推荐的点击命令。"
+        else:
+            desc_find_close = """🔍 智能查找关闭按钮（只找不点，返回位置）
 
 ⚡ 【推荐首选】遇到弹窗时优先调用此工具！无需先截图。
 
 从元素树中找最可能的关闭按钮，返回坐标和推荐的点击命令。
 
 🎯 识别策略（优先级）：
-1. 确认性按钮文本：同意、确认、允许、好的、OK等（得分120）
-2. 确认性 resource-id：包含 confirm/accept/agree/allow（得分115）
-3. 关闭/取消按钮文本：×、X、关闭、取消、跳过等（得分100）
-4. 关闭类 resource-id：包含 close/dismiss/cancel（得分95）
-5. 小尺寸 clickable 元素（右上角优先，得分70+）
-
-⭐ 优先点击确认性按钮（同意、确认等），而不是取消/拒绝按钮
+1. 文本匹配：×、X、关闭、取消、跳过 等（得分100）
+2. resource-id 匹配：包含 close/dismiss/skip（得分95）
+3. content-desc 匹配：包含 close/关闭（得分90）
+4. 小尺寸 clickable 元素（右上角优先，得分70+）
 
 ✅ 返回内容：
 - 坐标 (x, y) 和百分比 (x%, y%)
@@ -722,100 +698,68 @@ class MobileMCPServer:
 💡 使用流程：
 1. 直接调用此工具（无需先截图/列元素）
 2. 根据返回的 click_command 执行点击
-3. 如果返回 success=false，才需要截图分析""",
+3. 如果返回 success=false，才需要截图分析"""
+        
+        tools.append(Tool(
+            name="mobile_find_close_button",
+            description=desc_find_close,
             inputSchema={"type": "object", "properties": {}, "required": []}
         ))
         
-        tools.append(Tool(
-            name="mobile_close_popup",
-            description="""🚫 智能关闭弹窗（优化版）
+        if compact:
+            desc_close_popup = "🚫 智能检测并关闭弹窗。自动查找×/关闭/跳过按钮。"
+        else:
+            desc_close_popup = """🚫 智能检测并关闭弹窗
 
-🎯 弹窗检测场景：
-- 启动应用后：mobile_launch_app 会自动检测弹窗
-- 异常情况：操作失败时会检测弹窗
-- 明确弹窗场景：调用此工具时（明确弹窗场景）
+⚡ 【自动检测】会先检测是否存在弹窗：
+- 如果没有弹窗 → 直接返回"无弹窗"，不执行任何操作
+- 如果有弹窗 → 自动查找并点击关闭按钮
 
-⭐ 按钮点击优先级（确认按钮优先）：
-1️⃣ **确认性按钮**（最高优先级）：同意、确认、允许、好的、知道了、OK等
-2️⃣ **关闭/取消按钮**（次优先级）：关闭、取消、跳过、×、X等
-3️⃣ **小尺寸可点击元素**（最低优先级）：右上角X图标等
+✅ 适用场景：
+- 启动应用后检测并关闭可能出现的弹窗
+- 页面跳转后检测并关闭弹窗
+- 无需先截图确认弹窗是否存在
 
-优化后的降级策略：
-1️⃣ **控件树优先**（最快、最可靠）：list_elements() → 查找确认/关闭按钮 → 点击
-2️⃣ **截图AI分析**（中等速度、高准确率）：如果控件树失败 → 截图 → 返回候选建议 → AI分析 → 点击
-3️⃣ **模板匹配**（最慢、最精确）：如果AI分析失败 → 模板匹配 → 点击
+🎯 检测策略：
+- 查找控件树中的关闭按钮（×、关闭、跳过等）
+- 检测弹窗区域（Dialog/Popup/Alert 等）
+- 查找小尺寸的可点击元素（优先角落位置）
 
-✅ 优先点击「同意」「确认」等确认性按钮，而不是「取消」「不同意」
-✅ 每个阶段都会使用页面指纹对比验证弹窗是否真的关闭
-✅ 复用元素列表和XML，减少重复调用开销
-✅ 支持 Android 和 iOS 双平台
-✅ 支持自动学习模板（可选）""",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "auto_learn": {
-                        "type": "boolean",
-                        "description": "是否自动学习新模板（模板匹配成功时），默认 false"
-                    },
-                    "confidence_threshold": {
-                        "type": "number",
-                        "description": "弹窗检测置信度阈值（0-1），默认 0.6。值越高越严格，减少误检但可能漏检"
-                    }
-                },
-                "required": []
-            }
+🔴 【必须】如果返回已点击，需再次截图确认弹窗是否真的关闭了！"""
+        
+        tools.append(Tool(
+            name="mobile_close_popup",
+            description=desc_close_popup,
+            inputSchema={"type": "object", "properties": {}, "required": []}
         ))
         
         tools.append(Tool(
             name="mobile_assert_text",
-            description="✅ 检查页面是否包含指定文本。用于验证操作结果。",
+            description="✅ 检查页面是否包含文本。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "text": {"type": "string", "description": "要检查的文本"}
+                    "text": {"type": "string", "description": "文本"}
                 },
                 "required": ["text"]
             }
         ))
         
-        # ==================== Toast 检测工具（仅 Android）====================
+        # ==================== Toast 检测（仅 Android）====================
         tools.append(Tool(
             name="mobile_start_toast_watch",
-            description="""🔔 开始监听 Toast（仅 Android）
-
-⚠️ 【重要】必须在执行操作之前调用！
-
-📋 正确流程（三步走）：
-1️⃣ 调用 mobile_start_toast_watch() 开始监听
-2️⃣ 执行操作（如点击提交按钮）
-3️⃣ 调用 mobile_get_toast() 或 mobile_assert_toast() 获取结果
-
-❌ 错误用法：先点击按钮，再调用此工具（Toast 可能已消失）""",
-            inputSchema={
-                "type": "object",
-                "properties": {},
-                "required": []
-            }
+            description="🔔 开始监听Toast。必须在操作前调用。",
+            inputSchema={"type": "object", "properties": {}, "required": []}
         ))
         
         tools.append(Tool(
             name="mobile_get_toast",
-            description="""🍞 获取 Toast 消息（仅 Android）
-
-Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果。
-⚠️ Toast 不在控件树中，无法通过 mobile_list_elements 获取。
-
-📋 推荐用法（三步走）：
-1️⃣ mobile_start_toast_watch() - 开始监听
-2️⃣ 执行操作（点击按钮等）
-3️⃣ mobile_get_toast() - 获取 Toast
-
-⏱️ timeout 设置等待时间，默认 5 秒。""",
+            description="🍞 获取Toast消息。配合start_toast_watch使用。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "timeout": {"type": "number", "description": "等待 Toast 出现的超时时间（秒），默认 5"},
-                    "reset_first": {"type": "boolean", "description": "是否先清除旧缓存，默认 False"}
+                    "timeout": {"type": "number", "description": "超时秒数,默认5"},
+                    "reset_first": {"type": "boolean", "description": "清除旧缓存"}
                 },
                 "required": []
             }
@@ -823,22 +767,13 @@ Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果
         
         tools.append(Tool(
             name="mobile_assert_toast",
-            description="""✅ 断言 Toast 消息（仅 Android）
-
-等待 Toast 出现并验证内容是否符合预期。
-
-📋 推荐用法（三步走）：
-1️⃣ mobile_start_toast_watch() - 开始监听
-2️⃣ 执行操作（点击按钮等）
-3️⃣ mobile_assert_toast(expected_text="成功") - 断言
-
-💡 支持包含匹配（默认）和精确匹配。""",
+            description="✅ 断言Toast内容。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "expected_text": {"type": "string", "description": "期望的 Toast 文本"},
-                    "timeout": {"type": "number", "description": "等待超时时间（秒），默认 5"},
-                    "contains": {"type": "boolean", "description": "True=包含匹配（默认），False=精确匹配"}
+                    "expected_text": {"type": "string", "description": "期望文本"},
+                    "timeout": {"type": "number", "description": "超时秒数"},
+                    "contains": {"type": "boolean", "description": "包含匹配(默认true)"}
                 },
                 "required": ["expected_text"]
             }
@@ -847,11 +782,11 @@ Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果
         # ==================== pytest 脚本生成 ====================
         tools.append(Tool(
             name="mobile_get_operation_history",
-            description="📜 获取操作历史记录。",
+            description="📜 获取操作历史。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "limit": {"type": "number", "description": "返回最近的N条记录"}
+                    "limit": {"type": "number", "description": "条数"}
                 },
                 "required": []
             }
@@ -859,50 +794,53 @@ Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果
         
         tools.append(Tool(
             name="mobile_clear_operation_history",
-            description="🗑️ 清空操作历史记录。\n\n"
-                       "⚠️ 开始新的测试录制前必须调用！\n"
-                       "📋 录制流程：清空历史 → 执行操作（优先用文本/ID定位）→ 生成脚本",
+            description="🗑️ 清空操作历史。录制前调用。",
             inputSchema={"type": "object", "properties": {}, "required": []}
         ))
         
         tools.append(Tool(
             name="mobile_generate_test_script",
-            description="📝 生成 pytest 测试脚本。基于操作历史自动生成。\n\n"
-                       "⚠️ 【重要】录制操作时请优先使用稳定定位：\n"
-                       "1️⃣ 先调用 mobile_list_elements 获取元素列表\n"
-                       "2️⃣ 优先用 mobile_click_by_text（最稳定，跨设备兼容）\n"
-                       "3️⃣ 其次用 mobile_click_by_id（稳定）\n"
-                       "4️⃣ 最后才用坐标点击（会自动转百分比，跨分辨率兼容）\n\n"
-                       "使用流程：\n"
-                       "1. 清空历史 mobile_clear_operation_history\n"
-                       "2. 执行操作（优先用文本/ID定位）\n"
-                       "3. 调用此工具生成脚本\n"
-                       "4. 脚本保存到 tests/ 目录\n\n"
-                       "💡 定位优先级：文本 > ID > 百分比 > 坐标",
+            description="📝 生成pytest脚本。基于操作历史生成。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "test_name": {"type": "string", "description": "测试用例名称"},
-                    "package_name": {"type": "string", "description": "App 包名"},
-                    "filename": {"type": "string", "description": "脚本文件名（不含 .py）"}
+                    "test_name": {"type": "string", "description": "用例名"},
+                    "package_name": {"type": "string", "description": "包名"},
+                    "filename": {"type": "string", "description": "文件名(不含.py)"}
                 },
                 "required": ["test_name", "package_name", "filename"]
             }
         ))
         
         # ==================== 广告弹窗关闭工具 ====================
-        tools.append(Tool(
-            name="mobile_close_ad",
-            description="""🚫 【推荐】智能关闭广告弹窗（已合并到 mobile_close_popup）
+        if compact:
+            desc_close_ad = "🚫 智能关闭广告弹窗。优先级：控件树→截图AI→模板匹配。"
+        else:
+            desc_close_ad = """🚫 【推荐】智能检测并关闭广告弹窗
 
-⚡ 此工具现在调用 mobile_close_popup，功能完全相同。
+⚡ 【自动检测】会先检测是否存在弹窗：
+- 如果没有弹窗 → 直接返回"无弹窗"，不执行任何操作
+- 如果有弹窗 → 自动按优先级尝试关闭
 
-内部使用统一的降级策略：
-1️⃣ **控件树优先**（最快、最可靠）
-2️⃣ **截图AI分析**（中等速度、高准确率）
-3️⃣ **模板匹配**（最精确的兜底方案，支持自动学习）
+🎯 关闭策略（优先级从高到低）：
+1️⃣ **控件树查找**（最可靠）
+   - 查找文本"关闭"、"跳过"、"×"等
+   - 查找 resource-id 包含 close/dismiss
+   
+2️⃣ **截图 AI 分析**（次优）
+   - 返回 SoM 标注截图供 AI 视觉分析
+   - AI 找到 X 按钮后用 click_by_som(编号) 点击
 
-💡 推荐使用 mobile_close_popup 代替（功能相同）""",
+3️⃣ **模板匹配**（兜底）
+   - 用 OpenCV 匹配已保存的 X 按钮模板
+
+✅ 适用场景：
+- 启动应用后检测并关闭可能出现的广告
+- 无需先截图确认弹窗是否存在"""
+        
+        tools.append(Tool(
+            name="mobile_close_ad",
+            description=desc_close_ad,
             inputSchema={
                 "type": "object",
                 "properties": {},
@@ -912,19 +850,12 @@ Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果
         
         tools.append(Tool(
             name="mobile_template_close",
-            description="""🎯 模板匹配关闭弹窗（仅模板匹配）
-
-只用 OpenCV 模板匹配，不走控件树。
-一般建议用 mobile_close_ad 代替（会自动先查控件树）。
-
-⚙️ 参数：
-- click: 是否点击，默认 true
-- threshold: 匹配阈值 0-1，默认 0.75""",
+            description="🎯 模板匹配关闭弹窗。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "click": {"type": "boolean", "description": "是否点击，默认 true"},
-                    "threshold": {"type": "number", "description": "匹配阈值 0-1，默认 0.75"}
+                    "click": {"type": "boolean", "description": "是否点击"},
+                    "threshold": {"type": "number", "description": "阈值0-1"}
                 },
                 "required": []
             }
@@ -932,32 +863,19 @@ Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果
         
         tools.append(Tool(
             name="mobile_template_add",
-            description="""➕ 添加 X 号模板
-
-遇到新样式 X 号时，截图并添加到模板库。
-
-⚙️ 两种方式（二选一）：
-1. 百分比定位（推荐）：提供 x_percent, y_percent, size
-2. 像素定位：提供 screenshot_path, x, y, width, height
-
-📋 流程：
-1. mobile_screenshot_with_grid 查看 X 号位置
-2. 调用此工具添加模板
-3. 下次同样 X 号就能自动匹配
-
-💡 百分比示例：X 在右上角 → x_percent=85, y_percent=12, size=80""",
+            description="➕ 添加X号模板。",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "template_name": {"type": "string", "description": "模板名称"},
-                    "x_percent": {"type": "number", "description": "X号中心水平百分比 (0-100)"},
-                    "y_percent": {"type": "number", "description": "X号中心垂直百分比 (0-100)"},
-                    "size": {"type": "integer", "description": "裁剪正方形边长（像素）"},
-                    "screenshot_path": {"type": "string", "description": "截图路径（像素定位时用）"},
-                    "x": {"type": "integer", "description": "左上角 X 坐标"},
-                    "y": {"type": "integer", "description": "左上角 Y 坐标"},
-                    "width": {"type": "integer", "description": "裁剪宽度"},
-                    "height": {"type": "integer", "description": "裁剪高度"}
+                    "template_name": {"type": "string", "description": "模板名"},
+                    "x_percent": {"type": "number", "description": "X百分比"},
+                    "y_percent": {"type": "number", "description": "Y百分比"},
+                    "size": {"type": "integer", "description": "裁剪大小(px)"},
+                    "screenshot_path": {"type": "string", "description": "截图路径"},
+                    "x": {"type": "integer", "description": "左上X"},
+                    "y": {"type": "integer", "description": "左上Y"},
+                    "width": {"type": "integer", "description": "宽"},
+                    "height": {"type": "integer", "description": "高"}
                 },
                 "required": ["template_name"]
             }
@@ -1009,37 +927,7 @@ Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果
                 return [TextContent(type="text", text=self.format_response(result))]
             
             elif name == "mobile_screenshot_with_som":
-                check_popup = arguments.get("check_popup", False)
-                result = self.tools.take_screenshot_with_som(check_popup=check_popup)
-                
-                # 如果结果包含截图路径，尝试返回图片内容供 AI 分析
-                screenshot_path = result.get("screenshot_path")
-                if screenshot_path:
-                    try:
-                        from pathlib import Path
-                        import base64
-                        
-                        img_path = Path(screenshot_path)
-                        if img_path.exists():
-                            # 读取图片并转换为 base64
-                            with open(img_path, 'rb') as f:
-                                image_data = f.read()
-                                image_base64 = base64.b64encode(image_data).decode('utf-8')
-                            
-                            # 检查是否有 AI 分析请求
-                            ai_analysis = result.get("ai_analysis")
-                            if ai_analysis and ai_analysis.get("needs_ai_analysis"):
-                                # 返回文本结果和图片内容
-                                # 注意：MCP 协议可能不支持 ImageContent，这里先返回文本
-                                # Cursor AI 会自动看到截图文件并分析
-                                return [
-                                    TextContent(type="text", text=self.format_response(result)),
-                                    # 如果 MCP 支持 ImageContent，可以添加：
-                                    # ImageContent(type="image", data=image_base64, mimeType="image/jpeg")
-                                ]
-                    except Exception:
-                        pass  # 图片处理失败，只返回文本
-                
+                result = self.tools.take_screenshot_with_som()
                 return [TextContent(type="text", text=self.format_response(result))]
             
             elif name == "mobile_click_by_som":
@@ -1063,7 +951,8 @@ Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果
             elif name == "mobile_click_by_text":
                 result = self.tools.click_by_text(
                     arguments["text"],
-                    position=arguments.get("position")
+                    position=arguments.get("position"),
+                    verify=arguments.get("verify")
                 )
                 return [TextContent(type="text", text=self.format_response(result))]
             
@@ -1129,9 +1018,7 @@ Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果
                 result = await self.tools.swipe(
                     arguments["direction"],
                     y=arguments.get("y"),
-                    y_percent=arguments.get("y_percent"),
-                    distance=arguments.get("distance"),
-                    distance_percent=arguments.get("distance_percent")
+                    y_percent=arguments.get("y_percent")
                 )
                 return [TextContent(type="text", text=self.format_response(result))]
             
@@ -1175,12 +1062,7 @@ Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果
                 return [TextContent(type="text", text=self.format_response(result))]
             
             elif name == "mobile_close_popup":
-                auto_learn = arguments.get("auto_learn", False)
-                confidence_threshold = arguments.get("confidence_threshold", None)
-                result = self.tools.close_popup(
-                    auto_learn=auto_learn,
-                    confidence_threshold=confidence_threshold
-                )
+                result = self.tools.close_popup()
                 return [TextContent(type="text", text=self.format_response(result))]
             
             elif name == "mobile_assert_text":
@@ -1223,9 +1105,9 @@ Toast 是 Android 系统级的短暂提示消息，常用于显示操作结果
                 )
                 return [TextContent(type="text", text=self.format_response(result))]
             
-            # 智能关闭广告弹窗（已合并到 mobile_close_popup）
+            # 智能关闭广告弹窗
             elif name == "mobile_close_ad":
-                result = self.tools.close_popup(auto_learn=False)
+                result = self.tools.close_ad_popup(auto_learn=True)
                 return [TextContent(type="text", text=self.format_response(result))]
             
             # 模板匹配（精简版）