selenium_cli.py

from selenium import webdriver
from selenium.webdriver.firefox.options import Options as FirefoxOptions
from selenium.common.exceptions import (
    WebDriverException, TimeoutException, NoSuchElementException,
    NoSuchWindowException, StaleElementReferenceException
)
from selenium.webdriver.common.by import By
import time
import json
import os
import re
import hashlib
import mimetypes
import requests
from urllib.parse import urlparse, unquote, urljoin
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
from concurrent.futures import ThreadPoolExecutor, as_completed
import threading

DEFAULT_IMAGE_SUFFIXES = {
    ".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp",
    ".tif", ".tiff", ".heif", ".heic", ".svg", ".ico"
}

DEFAULT_FILE_SUFFIXES = {
    ".zip", ".rar", ".7z", ".tar", ".gz", ".bz2",
    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
    ".txt", ".csv", ".json", ".xml", ".html", ".htm",
    ".mp3", ".wav", ".flac", ".aac", ".ogg",
    ".mp4", ".avi", ".mkv", ".mov", ".wmv", ".flv", ".webm",
    ".exe", ".msi", ".dmg", ".pkg", ".deb", ".rpm",
    ".apk", ".ipa",
    ".iso", ".img",
    ".epub", ".mobi", ".azw3"
}

LAZY_IMG_ATTRS = [
    "data-src", "data-original", "data-lazy-src", "data-url",
    "data-actualsrc", "data-echo", "data-defer", "data-img",
    "data-background-image", "data-lazy", "data-placeholder"
]

class FirefoxAutoBrowser:
    def __init__(self, command_executor='http://127.0.0.1:4444',
                 firefox_binary_path="C:\\Program Files\\Mozilla Firefox\\firefox.exe",
                 page_load_timeout=30, implicitly_wait=10,
                 download_max_workers=5):
        """
        Initialize browser driver and configuration
        :param command_executor: Remote driver address
        :param firefox_binary_path: Firefox executable file path
        :param page_load_timeout: Page load timeout time
        :param implicitly_wait: Element implicit wait time
        :param download_max_workers: 批量下载最大并发线程数，默认 5
        """
        self.driver = None
        self.command_executor = command_executor
        self.firefox_binary_path = firefox_binary_path
        self.page_load_timeout = page_load_timeout
        self.implicitly_wait = implicitly_wait
        self.download_max_workers = download_max_workers
        self._print_lock = threading.Lock()
        self.init_result = self._init_browser()
        self._req_session = self._create_request_session()

    def _create_request_session(self):
        """Create a requests session with automatic retries"""
        session = requests.Session()
        retry_strategy = Retry(
            total=3,
            backoff_factor=0.5,
            status_forcelist=[429, 500, 502, 503, 504]
        )
        adapter = HTTPAdapter(max_retries=retry_strategy)
        session.mount("http://", adapter)
        session.mount("https://", adapter)
        return session

    def _log(self, msg):
        with self._print_lock:
            print(msg)

    def _sync_browser_cookies(self):
        if not self.driver:
            return
        try:
            cookies = self.driver.get_cookies()
            for ck in cookies:
                self._req_session.cookies.set(
                    ck.get("name"), ck.get("value"),
                    domain=ck.get("domain"), path=ck.get("path")
                )
        except Exception:
            pass

    def _build_headers(self, referer=None, extra_headers=None):
        headers = {
            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0",
            "Accept": "*/*",
            "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
            "Connection": "keep-alive"
        }
        if referer:
            headers["Referer"] = referer
        if extra_headers and isinstance(extra_headers, dict):
            headers.update(extra_headers)
        return headers

    @staticmethod
    def _resolve_url(url, base_url):
        """
        将相对 URL 转为绝对 URL。
        :param url: 可能是相对路径的 URL
        :param base_url: 当前页面地址，作为拼接基准
        :return: 绝对 URL；若无法解析则返回原 url
        """
        if not url or not base_url:
            return url
        url = url.strip()
        if url.startswith(("http://", "https://", "//")):
            if url.startswith("//"):
                return "https:" + url
            return url
        if url.startswith("data:") or url.startswith("blob:"):
            return url
        try:
            return urljoin(base_url, url)
        except Exception:
            return url

    @staticmethod
    def _sanitize_filename(name):
        """
        清理文件名中的非法字符，兼容 Windows / Linux / macOS。
        """
        if not name:
            return "unnamed"
        # 替换路径分隔符和控制字符
        name = re.sub(r'[\\/:*?"<>|\r\n\t]+', "_", name)
        # 去除首尾空格和点
        name = name.strip(" .")
        # 限制长度
        if len(name) > 200:
            root, ext = os.path.splitext(name)
            name = root[:190] + ext
        return name if name else "unnamed"

    @staticmethod
    def _extract_filename_from_disposition(resp, fallback="download_file"):
        """
        从 HTTP 响应头 Content-Disposition 中提取文件名。
        支持 filename= 和 filename*= 两种写法。
        :return: 提取到的文件名（不含路径），提取失败返回 fallback
        """
        cd = resp.headers.get("Content-Disposition", "")
        if not cd:
            return fallback
        # 优先 filename*=UTF-8''xxx
        m = re.search(r"filename\*\s*=\s*([^;]+)", cd, re.IGNORECASE)
        if m:
            raw = m.group(1).strip().strip('"').strip("'")
            # 处理 UTF-8''编码
            if "''" in raw:
                raw = raw.split("''", 1)[1]
            try:
                return unquote(raw)
            except Exception:
                return raw
        # 其次 filename=xxx
        m = re.search(r'filename\s*=\s*"?([^";]+)"?', cd, re.IGNORECASE)
        if m:
            return m.group(1).strip()
        return fallback

    @staticmethod
    def _guess_extension_from_content_type(resp, fallback=""):
        """根据响应 Content-Type 猜测文件扩展名"""
        ct = resp.headers.get("Content-Type", "").split(";")[0].strip().lower()
        if not ct:
            return fallback
        ext = mimetypes.guess_extension(ct)
        if ext:
            # mimetypes 对 jpeg 返回 .jpe，修正一下
            if ext == ".jpe":
                ext = ".jpg"
            return ext
        # 常见映射补充
        ct_map = {
            "image/jpeg": ".jpg", "image/jpg": ".jpg",
            "image/png": ".png", "image/gif": ".gif",
            "image/webp": ".webp", "image/bmp": ".jpg",
            "image/svg+xml": ".svg",
            "application/pdf": ".pdf",
            "application/zip": ".zip",
            "application/x-rar-compressed": ".rar",
            "application/x-7z-compressed": ".7z",
            "application/gzip": ".gz",
            "application/x-tar": ".tar",
            "application/msword": ".doc",
            "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
            "application/vnd.ms-excel": ".xls",
            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
            "text/plain": ".txt", "text/csv": ".csv",
            "application/json": ".json",
            "video/mp4": ".mp4", "video/x-matroska": ".mkv",
            "audio/mpeg": ".mp3", "audio/wav": ".wav",
        }
        return ct_map.get(ct, fallback)

    def _ensure_dir(self, save_dir):
        """确保目录存在，失败抛出异常"""
        try:
            if not os.path.exists(save_dir):
                os.makedirs(save_dir, exist_ok=True)
        except PermissionError:
            raise Exception(f"No permission to create directory {save_dir}")

    def _get_unique_save_path(self, save_dir, filename):
        """
        若目标文件已存在，自动追加 _1, _2 ... 避免覆盖。
        返回最终唯一路径。
        """
        base, ext = os.path.splitext(filename)
        candidate = os.path.join(save_dir, filename)
        counter = 1
        while os.path.exists(candidate):
            candidate = os.path.join(save_dir, f"{base}_{counter}{ext}")
            counter += 1
        return candidate

    def _stream_download(self, url, save_path, headers=None, timeout=30,
                         show_progress=False, resume=False, chunk_size=8192):
        """
        通用流式下载核心方法。
        :param url: 下载地址
        :param save_path: 保存完整路径
        :param headers: 请求头
        :param timeout: 超时秒数
        :param show_progress: 是否打印进度
        :param resume: 是否启用断点续传（若文件已存在且服务器支持 Range）
        :param chunk_size: 块大小
        :return: (total_size_bytes, used_headers_dict)
        """
        existing_size = 0
        mode = "wb"
        if resume and os.path.exists(save_path):
            existing_size = os.path.getsize(save_path)
            if existing_size > 0:
                headers = dict(headers or {})
                headers["Range"] = f"bytes={existing_size}-"
                mode = "ab"

        resp = self._req_session.get(url, headers=headers, timeout=timeout, stream=True)
        # 206 表示断点续传成功；200 表示服务器不支持 Range，从头开始
        if resp.status_code == 200 and existing_size > 0:
            mode = "wb"
            existing_size = 0
        resp.raise_for_status()

        total_size = existing_size
        content_length = resp.headers.get("Content-Length")
        total_expected = None
        if content_length and content_length.isdigit():
            total_expected = int(content_length) + existing_size

        try:
            with open(save_path, mode) as f:
                downloaded = existing_size
                for chunk in resp.iter_content(chunk_size=chunk_size):
                    if chunk:
                        f.write(chunk)
                        downloaded += len(chunk)
                        total_size = downloaded
                        if show_progress and total_expected:
                            pct = min(100.0, downloaded * 100.0 / total_expected)
                            self._log(f"    下载进度: {downloaded}/{total_expected} bytes ({pct:.1f}%)")
        except OSError as e:
            raise Exception(f"Write file failed, disk full or permission denied: {str(e)}")

        return total_size, dict(resp.headers)

    def _scroll_page_to_load_lazy_images(self, scroll_step=800, wait_per_step=0.4, max_rounds=50):
        """
        缓慢滚动整个页面，触发懒加载图片加载。
        很多网站图片在滚动到可视区域时才把 data-src 赋给 src。
        """
        if not self.driver:
            return
        try:
            last_height = self.driver.execute_script("return document.body.scrollHeight")
            for _ in range(max_rounds):
                self.driver.execute_script(f"window.scrollBy(0, {scroll_step});")
                time.sleep(wait_per_step)
                new_height = self.driver.execute_script("return document.body.scrollHeight")
                # 滚到底部且高度不再变化，结束
                current_scroll = self.driver.execute_script("return window.scrollY + window.innerHeight")
                if current_scroll >= new_height - 10 and new_height == last_height:
                    break
                last_height = new_height
            # 滚回顶部
            self.driver.execute_script("window.scrollTo(0, 0);")
            time.sleep(0.3)
        except Exception:
            pass

    def _init_browser(self):
        """
        Private method: Configure Firefox options and initialize Remote driver
        Return: JSON format initialization result
        """
        try:
            firefox_options = FirefoxOptions()
            firefox_options.binary_location = self.firefox_binary_path
            custom_user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0"
            firefox_options.add_argument(f"--user-agent={custom_user_agent}")
            firefox_options.set_preference("dom.webnotifications.enabled", False)
            firefox_options.set_preference("dom.popup_maximum", -1)
            firefox_options.set_preference("browser.popups.showPopupBlocker", False)
            firefox_options.set_preference("dom.disable_open_during_load", False)
            firefox_options.set_preference("browser.link.open_newwindow", 3)
            firefox_options.set_preference("browser.link.open_newwindow.restriction", 0)
            firefox_options.add_argument("--ignore-certificate-errors")
            self.driver = webdriver.Remote(
                command_executor=self.command_executor,
                options=firefox_options
            )
            self.driver.set_page_load_timeout(self.page_load_timeout)
            self.driver.implicitly_wait(self.implicitly_wait)
            success_json = {
                "code": 200,
                "status": "success",
                "message": "Browser initialized successfully",
                "detail": None,
                "data": None
            }
            return json.dumps(success_json, ensure_ascii=False, indent=2)
        except (WebDriverException, Exception) as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Browser initialization failed: {str(e)}",
                "detail": None,
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def create_new_tab(self):
        """
        Function: Create a new blank tab
        Return: JSON format string (contains operation result and related information)
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            self.driver.execute_script("window.open('');")
            result_json = {
                "code": 200,
                "status": "success",
                "message": "New tab created successfully",
                "detail": None,
                "data": None
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except (WebDriverException, Exception) as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to create new tab: {str(e)}",
                "detail": None,
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def get_all_tabs(self):
        """
        Function: Get the list of handles of all current tabs, including detailed tab information + page title
        Return: JSON format string (contains detailed tab information and handle list data)
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            window_handles = self.driver.window_handles
            tab_count = len(window_handles)
            original_active_handle = self.driver.current_window_handle
            tabs_detail = {
                "total_tabs": tab_count,
                "tabs_info": []
            }
            for index, handle in enumerate(window_handles):
                try:
                    self.driver.switch_to.window(handle)
                    page_title = self.driver.title.strip()
                except (NoSuchWindowException, WebDriverException):
                    page_title = "[Tab window invalid, closed]"
                active_handle = original_active_handle
                tab_status = "[Currently Active]" if (active_handle and handle == active_handle) else "[Inactive]"
                tab_info = {
                    "index": index,
                    "handle": handle,
                    "handle_abbr": handle[:20] + "...",
                    "title": page_title,
                    "status": tab_status
                }
                tabs_detail["tabs_info"].append(tab_info)
            try:
                self.driver.switch_to.window(original_active_handle)
            except Exception:
                pass
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Successfully retrieved {tab_count} tabs in total",
                "detail": tabs_detail,
                "data": window_handles
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except (WebDriverException, Exception) as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to get all tabs: {str(e)}",
                "detail": None,
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def get_active_tab(self):
        """
        Function: Get the handle of the currently active (foreground display) tab, including detailed active tab information
        Return: JSON format string (contains active tab details and handle data)
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            current_window = self.driver.current_window_handle
            all_handles = self.driver.window_handles
            tab_count = len(all_handles)
            active_tab_index = all_handles.index(current_window)
            active_detail = {
                "total_tabs": tab_count,
                "active_tab_index": active_tab_index,
                "active_tab_handle": current_window
            }
            result_json = {
                "code": 200,
                "status": "success",
                "message": "Successfully retrieved current active tab information",
                "detail": active_detail,
                "data": current_window
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except (WebDriverException, Exception) as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to get active tab: {str(e)}",
                "detail": None,
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def switch_to_specific_tab(self, target):
        """
        Function: Switch to a specific tab (supports passing handle directly / passing tab index)
        :param target: Target tab (str: tab handle; int: tab index, starting from 0)
        Return: JSON format string (contains switch result and related information)
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            all_handles = self.driver.window_handles
            target_handle = None
            if isinstance(target, int):
                if 0 <= target < len(all_handles):
                    target_handle = all_handles[target]
                else:
                    raise Exception(
                        f"Tab index {target} is invalid, only {len(all_handles)} tabs exist currently (index 0~{len(all_handles) - 1})")
            elif isinstance(target, str):
                if target in all_handles:
                    target_handle = target
                else:
                    raise Exception(f"Tab handle {target} is invalid, not in the current tab list")
            else:
                raise Exception("Invalid parameter type, supports int (index) or str (handle)")
            self.driver.switch_to.window(target_handle)
            result_json = {
                "code": 200,
                "status": "success",
                "message": "Successfully switched to target tab",
                "detail": {
                    "target_param": target,
                    "target_handle": target_handle,
                    "target_handle_abbr": target_handle[:20] + "..."
                },
                "data": None
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except (WebDriverException, Exception) as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to switch to specific tab: {str(e)}",
                "detail": {
                    "input_target": target
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def open_url_in_specific_tab(self, url, target=0):
        """
        Function: Open the specified web page in a specific tab
        :param url: Web page address to open (str)
        :param target: Target tab (str: handle; int: index, default the first tab (index 0))
        Return: JSON format string (contains operation result and related information)
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            if not url or not isinstance(url, str) or url.strip() == "":
                raise Exception("Invalid web page address, empty url")
            switch_result = json.loads(self.switch_to_specific_tab(target))
            if switch_result["code"] != 200:
                raise Exception(switch_result["message"])
            self.driver.get(url.strip())
            time.sleep(0.8)
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Successfully opened web page in target tab: {url}",
                "detail": {
                    "target_tab": target,
                    "opened_url": url
                },
                "data": None
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except (TimeoutException, WebDriverException) as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Web page loading timed out or failed to open: {str(e)}",
                "detail": {
                    "target_tab": target,
                    "input_url": url
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except (Exception) as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to open web page in specific tab: {str(e)}",
                "detail": {
                    "target_tab": target,
                    "input_url": url
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def get_specific_tab_page_content(self, target=None):
        """
        Function: Get the page HTML content of the specified tab (default to get current active tab)
        :param target: Target tab (None: current active tab; str: handle; int: index)
        Return: JSON format string (contains page content length and HTML source data)
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            current_handle = None
            target_info = {}
            if target is None:
                current_handle = self.driver.current_window_handle
                target_info = {
                    "target_type": "current_active",
                    "target_handle": current_handle,
                    "target_handle_abbr": current_handle[:20] + "..."
                }
            else:
                all_handles = self.driver.window_handles
                target_handle = None
                if isinstance(target, int):
                    if 0 <= target < len(all_handles):
                        target_handle = all_handles[target]
                        target_info = {
                            "target_type": "index",
                            "input_target": target,
                            "target_handle": target_handle,
                            "target_handle_abbr": target_handle[:20] + "..."
                        }
                    else:
                        raise Exception(f"Tab index {target} is invalid, only {len(all_handles)} tabs exist currently")
                elif isinstance(target, str):
                    if target in all_handles:
                        target_handle = target
                        target_info = {
                            "target_type": "handle",
                            "input_target": target,
                            "target_handle": target_handle,
                            "target_handle_abbr": target_handle[:20] + "..."
                        }
                    else:
                        raise Exception(f"Tab handle {target} is invalid, not in the current tab list")
                else:
                    raise Exception("Invalid parameter type, supports int (index) or str (handle)")
                self.driver.switch_to.window(target_handle)
                current_handle = target_handle
            page_content = self.driver.page_source
            content_length = len(page_content)
            target_info["content_length"] = content_length
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Successfully retrieved target tab page content, content length: {content_length} characters",
                "detail": target_info,
                "data": page_content
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to get tab page content (WebDriver exception): {str(e)}",
                "detail": {
                    "input_target": target
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to get tab page content: {str(e)}",
                "detail": {
                    "input_target": target
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def scroll_mouse_wheel_down(self, scroll_distance=500, target_tab=None):
        """
        Function: Simulate mouse wheel scrolling down (supports specifying tab, default current active tab)
        :param scroll_distance: Scrolling distance (pixels, default 500 pixels, larger value means more scrolling)
        :param target_tab: Target tab (None: current active tab; str: handle; int: index)
        Return: JSON format string (contains scrolling operation result)
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            scroll_detail = {
                "scroll_direction": "down",
                "scroll_distance": scroll_distance,
                "target_tab": target_tab
            }
            if target_tab is not None:
                switch_result = json.loads(self.switch_to_specific_tab(target_tab))
                if switch_result["code"] != 200:
                    raise Exception(switch_result["message"])
                scroll_detail["switch_status"] = "Successfully switched to target tab"
            self.driver.execute_script(f"window.scrollBy(0, {scroll_distance});")
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Mouse wheel scrolled down successfully, scrolling distance: {scroll_distance} pixels",
                "detail": scroll_detail,
                "data": None
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to scroll mouse wheel down (WebDriver exception): {str(e)}",
                "detail": {
                    "scroll_distance": scroll_distance,
                    "target_tab": target_tab
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to scroll mouse wheel down: {str(e)}",
                "detail": {
                    "scroll_distance": scroll_distance,
                    "target_tab": target_tab
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def scroll_mouse_wheel_up(self, scroll_distance=500, target_tab=None):
        """
        Function: Simulate mouse wheel scrolling up (supports specifying tab, default current active tab)
        :param scroll_distance: Scrolling distance (pixels, default 500 pixels, larger value means more scrolling)
        :param target_tab: Target tab (None: current active tab; str: handle; int: index)
        Return: JSON format string (contains scrolling operation result)
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            scroll_detail = {
                "scroll_direction": "up",
                "scroll_distance": scroll_distance,
                "target_tab": target_tab
            }
            if target_tab is not None:
                switch_result = json.loads(self.switch_to_specific_tab(target_tab))
                if switch_result["code"] != 200:
                    raise Exception(switch_result["message"])
                scroll_detail["switch_status"] = "Successfully switched to target tab"
            self.driver.execute_script(f"window.scrollBy(0, -{scroll_distance});")
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Mouse wheel scrolled up successfully, scrolling distance: {scroll_distance} pixels",
                "detail": scroll_detail,
                "data": None
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to scroll mouse wheel up (WebDriver exception): {str(e)}",
                "detail": {
                    "scroll_distance": scroll_distance,
                    "target_tab": target_tab
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to scroll mouse wheel up: {str(e)}",
                "detail": {
                    "scroll_distance": scroll_distance,
                    "target_tab": target_tab
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def click_element_by_xpath(self, xpath, target_tab=None):
        """
        Function: Locate element by XPath expression and execute click operation
        :param xpath: XPath expression for targeting the element (str, required)
        :param target_tab: Target tab (None: current active tab; str: handle; int: index)
        Return: JSON format string (contains element locate and click operation result)
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            if not xpath or not isinstance(xpath, str):
                raise Exception("Invalid XPath expression: it must be a non-empty string")
            click_detail = {
                "xpath_expression": xpath,
                "target_tab": target_tab,
                "operation_status": "not_executed"
            }
            if target_tab is not None:
                switch_result = json.loads(self.switch_to_specific_tab(target_tab))
                if switch_result["code"] != 200:
                    raise Exception(f"Failed to switch to target tab: {switch_result['message']}")
                click_detail["switch_status"] = "Successfully switched to target tab"
            click_detail["operation_status"] = "locating_element"
            target_element = self.driver.find_element(By.XPATH, xpath)
            if not target_element:
                raise NoSuchElementException("Element not found even with valid XPath expression")
            click_detail["operation_status"] = "clicking_element"
            target_element.click()
            click_detail["operation_status"] = "completed_successfully"
            result_json = {
                "code": 200,
                "status": "success",
                "message": "Element located by XPath and clicked successfully",
                "detail": click_detail,
                "data": None
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except NoSuchElementException as e:
            fail_json = {
                "code": 404,
                "status": "failed",
                "message": f"Element not found by XPath: {str(e)}",
                "detail": {
                    "xpath_expression": xpath,
                    "target_tab": target_tab,
                    "error_type": "NoSuchElementException"
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except StaleElementReferenceException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Element stale, page refreshed: {str(e)}",
                "detail": {
                    "xpath_expression": xpath,
                    "target_tab": target_tab,
                    "error_type": "StaleElementReferenceException"
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to click element (WebDriver exception): {str(e)}",
                "detail": {
                    "xpath_expression": xpath,
                    "target_tab": target_tab,
                    "error_type": "WebDriverException"
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to click element by XPath: {str(e)}",
                "detail": {
                    "xpath_expression": xpath,
                    "target_tab": target_tab,
                    "error_type": "GeneralException"
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def click_element(self, locator, locator_type="xpath", target_tab=None):
        """
        Function: Universal element click function, supports multiple locator methods to click any clickable element
        (tags, buttons, links, etc.)
        :param locator: Locator expression (str, required, e.g. id value, XPath expression, CSS selector, etc.)
        :param locator_type: Locator method (str, optional, default "xpath"), support:
            "id", "xpath", "name", "class_name", "css_selector", "tag_name", "link_text", "partial_link_text"
        :param target_tab: Target tab (None: current active tab; str: handle; int: index)
        Return: JSON format string (contains element locate and click operation result)
        """
        supported_locators = {
            "id": By.ID,
            "xpath": By.XPATH,
            "name": By.NAME,
            "class_name": By.CLASS_NAME,
            "css_selector": By.CSS_SELECTOR,
            "tag_name": By.TAG_NAME,
            "link_text": By.LINK_TEXT,
            "partial_link_text": By.PARTIAL_LINK_TEXT
        }
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            if locator_type not in supported_locators:
                supported_types = ", ".join(supported_locators.keys())
                raise Exception(f"Unsupported locator type: {locator_type}. Supported types: {supported_types}")
            if not locator or not isinstance(locator, str):
                raise Exception("Invalid locator expression: it must be a non-empty string")
            click_detail = {
                "locator_type": locator_type,
                "locator_expression": locator,
                "target_tab": target_tab,
                "operation_status": "not_executed"
            }
            if target_tab is not None:
                switch_result = json.loads(self.switch_to_specific_tab(target_tab))
                if switch_result["code"] != 200:
                    raise Exception(f"Failed to switch to target tab: {switch_result['message']}")
                click_detail["switch_status"] = "Successfully switched to target tab"
            click_detail["operation_status"] = "locating_element"
            by_locator = supported_locators[locator_type]
            target_element = self.driver.find_element(by_locator, locator)
            if not target_element:
                raise NoSuchElementException(f"Element not found even with valid {locator_type} locator")
            click_detail["operation_status"] = "scrolling_to_element"
            self.driver.execute_script("arguments[0].scrollIntoView({behavior: 'smooth', block: 'center'});", target_element)
            click_detail["operation_status"] = "clicking_element"
            target_element.click()
            click_detail["operation_status"] = "completed_successfully"
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Element located by {locator_type} and clicked successfully",
                "detail": click_detail,
                "data": None
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except NoSuchElementException as e:
            fail_json = {
                "code": 404,
                "status": "failed",
                "message": f"Element not found by {locator_type}: {str(e)}",
                "detail": {
                    "locator_type": locator_type,
                    "locator_expression": locator,
                    "target_tab": target_tab,
                    "error_type": "NoSuchElementException"
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except StaleElementReferenceException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Element stale reference: {str(e)}",
                "detail": {
                    "locator_type": locator_type,
                    "locator_expression": locator,
                    "target_tab": target_tab,
                    "error_type": "StaleElementReferenceException"
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to click element (WebDriver exception): {str(e)}",
                "detail": {
                    "locator_type": locator_type,
                    "locator_expression": locator,
                    "target_tab": target_tab,
                    "error_type": "WebDriverException"
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to click element by {locator_type}: {str(e)}",
                "detail": {
                    "locator_type": locator_type,
                    "locator_expression": locator,
                    "target_tab": target_tab,
                    "error_type": "GeneralException"
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def close_specific_tab(self, target=None):
        """
        Function: Close a specific tab (default to close current active tab, supports specifying handle/index)
        :param target: Target tab (None: current active tab; str: handle; int: index)
        Return: JSON format string (contains close operation result and subsequent switch information)
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            all_handles = self.driver.window_handles
            tab_count_before_close = len(all_handles)
            if tab_count_before_close == 0:
                raise Exception("No available tabs to close currently")
            close_handle = None
            close_detail = {
                "tab_count_before_close": tab_count_before_close,
                "input_target": target
            }
            if target is None:
                close_handle = self.driver.current_window_handle
                close_detail["target_type"] = "current_active"
            else:
                if isinstance(target, int):
                    if 0 <= target < tab_count_before_close:
                        close_handle = all_handles[target]
                        close_detail["target_type"] = "index"
                    else:
                        raise Exception(f"Tab index {target} is invalid, only {tab_count_before_close} tabs exist currently")
                elif isinstance(target, str):
                    if target in all_handles:
                        close_handle = target
                        close_detail["target_type"] = "handle"
                    else:
                        raise Exception(f"Tab handle {target} is invalid, not in the current tab list")
                else:
                    raise Exception("Invalid parameter type, supports int (index) or str (handle)")
            close_detail["closed_handle"] = close_handle
            close_detail["closed_handle_abbr"] = close_handle[:20] + "..."
            self.driver.switch_to.window(close_handle)
            is_last_tab = (tab_count_before_close == 1)
            close_detail["is_last_tab"] = is_last_tab
            self.driver.close()
            if not is_last_tab:
                time.sleep(0.5)
                try:
                    remaining_handles = self.driver.window_handles
                    if len(remaining_handles) > 0:
                        self.driver.switch_to.window(remaining_handles[0])
                        close_detail["post_close_operation"] = "Automatically switched to the first remaining tab"
                        close_detail["switched_to_remaining_handle"] = remaining_handles[0]
                except Exception:
                    close_detail["post_close_operation"] = "Switch remaining tab failed, window context missing"
            else:
                self.driver = None
                close_detail["post_close_operation"] = "Closed the last tab, browser window exited, driver context invalidated"
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Successfully closed tab: {close_handle}",
                "detail": close_detail,
                "data": None
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            close_detail = {
                "input_target": target,
                "error_type": "WebDriverException"
            }
            if "Browsing context has been discarded" in str(e) or "NoSuchWindowError" in str(e):
                self.driver = None
                close_detail["error_detail"] = "Browsing context invalidated (tab/browser closed), cannot continue operation"
                message = "Browsing context invalidated (tab/browser closed), cannot continue operation"
            else:
                close_detail["error_detail"] = str(e)
                message = f"Failed to close specific tab: {str(e)}"
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": message,
                "detail": close_detail,
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to close specific tab: {str(e)}",
                "detail": {
                    "input_target": target
                },
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def quit_browser(self):
        """
        Function: Close all tabs and exit browser driver, release resources
        Return: JSON format string (contains exit operation result)
        """
        try:
            if self.driver:
                self.driver.quit()
                self.driver = None
            self._req_session.close()
            result_json = {
                "code": 200,
                "status": "success",
                "message": "Browser exited successfully, resources released",
                "detail": None,
                "data": None
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except (WebDriverException, Exception) as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to quit browser: {str(e)}",
                "detail": None,
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    # ================================================================
    #  链接 / 图片 / 文件 提取
    # ================================================================
    def get_all_a_links(self, target_tab=None):
        """
        提取页面所有 <a> 标签的超链接，仅保留 http:// 或 https:// 开头的链接，
        自动过滤 javascript:、mailto:、#锚点、相对路径等非标准链接。
        :param target_tab: 目标标签页 (None: 当前激活页; str: 句柄; int: 索引)
        :return: JSON string, data 为去重后的 http/https 链接列表
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            link_detail = {
                "target_tab_input": target_tab,
                "switch_status": None,
                "filter_rule": "only http:// and https:// links"
            }
            if target_tab is not None:
                switch_res = json.loads(self.switch_to_specific_tab(target_tab))
                if switch_res["code"] != 200:
                    raise Exception(f"Switch tab failed: {switch_res['message']}")
                link_detail["switch_status"] = "success"
            time.sleep(0.5)
            a_elements = []
            try:
                a_elements = self.driver.find_elements(By.TAG_NAME, "a")
            except StaleElementReferenceException:
                self.driver.refresh()
                time.sleep(1)
                a_elements = self.driver.find_elements(By.TAG_NAME, "a")
            raw_links = []
            filtered_out_count = 0
            for elem in a_elements:
                try:
                    href = elem.get_attribute("href")
                    if href and href.strip():
                        href = href.strip()
                        # 仅保留 http:// 或 https:// 开头的链接
                        if href.startswith(("http://", "https://")):
                            raw_links.append(href)
                        else:
                            filtered_out_count += 1
                except Exception:
                    continue
            unique_links = list(set(raw_links))
            unique_links.sort()
            link_detail["raw_link_count"] = len(raw_links)
            link_detail["filtered_out_count"] = filtered_out_count
            link_detail["unique_link_count"] = len(unique_links)
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Extracted http/https hyperlinks successfully, total unique links: {len(unique_links)}",
                "detail": link_detail,
                "data": unique_links
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to get page hyperlinks(WebDriver error): {str(e)}",
                "detail": {"target_tab": target_tab, "error_type": "WebDriverException"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to get page hyperlinks: {str(e)}",
                "detail": {"target_tab": target_tab, "error_type": "GeneralException"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def get_all_img_links(self, target_tab=None, filter_by_suffix=True,
                          include_lazy=True, include_background=True,
                          auto_scroll=True):
        """
        【增强版】提取页面所有图片链接。
        支持：<img src>、懒加载属性(data-src 等)、srcset、CSS background-image、相对路径转绝对路径。
        :param target_tab: 目标标签页
        :param filter_by_suffix: 是否按图片后缀过滤（默认 True），False 时不过滤，抓取所有疑似图片链接
        :param include_lazy: 是否包含懒加载属性（默认 True）
        :param include_background: 是否包含 CSS 背景图（默认 True）
        :param auto_scroll: 是否先滚动页面触发懒加载（默认 True）
        :return: JSON string, data contains deduplicated valid image url list
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            img_detail = {
                "target_tab_input": target_tab,
                "switch_status": None,
                "filter_by_suffix": filter_by_suffix,
                "include_lazy": include_lazy,
                "include_background": include_background,
                "auto_scroll": auto_scroll
            }
            if target_tab is not None:
                switch_res = json.loads(self.switch_to_specific_tab(target_tab))
                if switch_res["code"] != 200:
                    raise Exception(f"Switch tab failed: {switch_res['message']}")
                img_detail["switch_status"] = "success"

            # 当前页面 URL，用于相对路径拼接
            try:
                base_url = self.driver.current_url
            except Exception:
                base_url = ""

            # 先滚动触发懒加载
            if auto_scroll:
                self._scroll_page_to_load_lazy_images()
                img_detail["scroll_triggered"] = True

            time.sleep(0.5)

            # ---- 1. 提取所有 <img> 元素 ----
            img_elements = []
            try:
                img_elements = self.driver.find_elements(By.TAG_NAME, "img")
            except StaleElementReferenceException:
                self.driver.refresh()
                time.sleep(1)
                img_elements = self.driver.find_elements(By.TAG_NAME, "img")

            raw_imgs = []
            src_count = 0
            lazy_count = 0
            srcset_count = 0

            for elem in img_elements:
                try:
                    # 1.1 标准 src
                    src = elem.get_attribute("src")
                    if src and src.strip() and not src.strip().startswith("data:"):
                        raw_imgs.append(src.strip())
                        src_count += 1

                    # 1.2 懒加载属性
                    if include_lazy:
                        for attr in LAZY_IMG_ATTRS:
                            val = elem.get_attribute(attr)
                            if val and val.strip() and not val.strip().startswith("data:"):
                                raw_imgs.append(val.strip())
                                lazy_count += 1

                    # 1.3 srcset（取第一个或最大尺寸）
                    srcset = elem.get_attribute("srcset")
                    if srcset and srcset.strip():
                        # srcset 格式: url1 1x, url2 2x 或 url1 300w, url2 600w
                        parts = [p.strip().split()[0] for p in srcset.split(",") if p.strip()]
                        for p in parts:
                            if p and not p.startswith("data:"):
                                raw_imgs.append(p)
                                srcset_count += 1
                except Exception:
                    continue

            # ---- 2. 提取 CSS background-image ----
            bg_count = 0
            if include_background:
                try:
                    bg_urls = self.driver.execute_script("""
                        var results = [];
                        var all = document.querySelectorAll('*');
                        for (var i = 0; i < all.length; i++) {
                            var bg = window.getComputedStyle(all[i]).backgroundImage;
                            if (bg && bg !== 'none') {
                                var matches = bg.match(/url\\(["']?([^"')]+)["']?\\)/g);
                                if (matches) {
                                    for (var j = 0; j < matches.length; j++) {
                                        var m = matches[j].match(/url\\(["']?([^"')]+)["']?\\)/);
                                        if (m && m[1]) results.push(m[1]);
                                    }
                                }
                            }
                        }
                        return results;
                    """)
                    if bg_urls:
                        for u in bg_urls:
                            if u and not u.startswith("data:"):
                                raw_imgs.append(u.strip())
                                bg_count += 1
                except Exception:
                    pass

            # ---- 3. 相对路径转绝对路径 + 去重 ----
            resolved = []
            for u in raw_imgs:
                abs_u = self._resolve_url(u, base_url)
                if abs_u and abs_u.startswith(("http://", "https://")):
                    resolved.append(abs_u)

            # ---- 4. 可选后缀过滤 ----
            if filter_by_suffix:
                filtered = []
                for u in resolved:
                    pure = u.lower().split("?")[0].split("#")[0]
                    if any(pure.endswith(suf) for suf in DEFAULT_IMAGE_SUFFIXES):
                        filtered.append(u)
                resolved = filtered

            unique_imgs = list(set(resolved))
            unique_imgs.sort()

            img_detail["raw_img_count"] = len(raw_imgs)
            img_detail["src_attr_count"] = src_count
            img_detail["lazy_attr_count"] = lazy_count
            img_detail["srcset_count"] = srcset_count
            img_detail["background_count"] = bg_count
            img_detail["unique_img_count"] = len(unique_imgs)

            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Extracted filtered image links successfully, total unique images: {len(unique_imgs)}",
                "detail": img_detail,
                "data": unique_imgs
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to get page image links(WebDriver error): {str(e)}",
                "detail": {"target_tab": target_tab, "error_type": "WebDriverException"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to get page image links: {str(e)}",
                "detail": {"target_tab": target_tab, "error_type": "GeneralException"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def get_all_file_links(self, target_tab=None, suffix_filter=None):
        """
        【新增】从页面提取所有可下载文件链接（<a href> 中匹配文件后缀的链接）。
        :param target_tab: 目标标签页
        :param suffix_filter: 自定义后缀集合，None 使用默认 DEFAULT_FILE_SUFFIXES
        :return: JSON string, data 为去重后的文件链接列表
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            suffix_set = suffix_filter if suffix_filter else DEFAULT_FILE_SUFFIXES

            file_detail = {
                "target_tab_input": target_tab,
                "suffix_filter_count": len(suffix_set)
            }
            if target_tab is not None:
                switch_res = json.loads(self.switch_to_specific_tab(target_tab))
                if switch_res["code"] != 200:
                    raise Exception(f"Switch tab failed: {switch_res['message']}")
                file_detail["switch_status"] = "success"

            try:
                base_url = self.driver.current_url
            except Exception:
                base_url = ""

            time.sleep(0.5)
            a_elements = []
            try:
                a_elements = self.driver.find_elements(By.TAG_NAME, "a")
            except StaleElementReferenceException:
                self.driver.refresh()
                time.sleep(1)
                a_elements = self.driver.find_elements(By.TAG_NAME, "a")

            raw_files = []
            for elem in a_elements:
                try:
                    href = elem.get_attribute("href")
                    if not href or not href.strip():
                        continue
                    href = href.strip()
                    pure = href.lower().split("?")[0].split("#")[0]
                    if any(pure.endswith(suf) for suf in suffix_set):
                        abs_href = self._resolve_url(href, base_url)
                        if abs_href.startswith(("http://", "https://")):
                            raw_files.append(abs_href)
                except Exception:
                    continue

            unique_files = list(set(raw_files))
            unique_files.sort()
            file_detail["raw_file_count"] = len(raw_files)
            file_detail["unique_file_count"] = len(unique_files)

            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Extracted file download links successfully, total: {len(unique_files)}",
                "detail": file_detail,
                "data": unique_files
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to get page file links(WebDriver error): {str(e)}",
                "detail": {"target_tab": target_tab, "error_type": "WebDriverException"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Failed to get page file links: {str(e)}",
                "detail": {"target_tab": target_tab, "error_type": "GeneralException"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    # ================================================================
    #  单张图片下载（增强版）
    # ================================================================
    def download_image_from_url(self, img_url, save_dir="./download_img",
                                save_name=None, target_tab=None,
                                skip_if_exists=True, timeout=20,
                                use_browser_cookies=True, add_referer=True):
        """
        【增强版】下载单张图片。
        改进：自动携带浏览器 Cookie + Referer、支持无后缀图片（从 Content-Type 推断）、
              跳过已下载、文件名自动去重、非法字符清理。
        :param img_url: 图片链接
        :param save_dir: 保存目录
        :param save_name: 自定义文件名（不带后缀），None 自动提取
        :param target_tab: 目标标签页（用于切换上下文 + 获取 Referer）
        :param skip_if_exists: 已存在同名文件是否跳过（默认 True）
        :param timeout: 请求超时
        :param use_browser_cookies: 是否同步浏览器 Cookie
        :param add_referer: 是否自动添加当前页面为 Referer
        :return: JSON string
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            if not img_url or not isinstance(img_url, str) or img_url.strip() == "":
                raise Exception("Image url empty, skip download")
            img_url = img_url.strip()

            # 切换标签 + 获取 Referer
            referer = None
            switch_info = None
            if target_tab is not None:
                switch_res = json.loads(self.switch_to_specific_tab(target_tab))
                if switch_res["code"] != 200:
                    raise Exception(f"Switch tab failed: {switch_res['message']}")
                switch_info = f"Success switch to tab: {target_tab}"
            if add_referer:
                try:
                    referer = self.driver.current_url
                except Exception:
                    referer = None

            # 同步 Cookie
            if use_browser_cookies:
                self._sync_browser_cookies()

            # 创建目录
            self._ensure_dir(save_dir)

            # 解析 URL 中的文件名
            parsed = urlparse(unquote(img_url))
            base_file = os.path.basename(parsed.path)
            url_ext = os.path.splitext(base_file)[1].lower() if base_file else ""

            # 构造请求头
            headers = self._build_headers(referer=referer)

            # 先发 HEAD 请求确认 Content-Type（可选，失败不阻塞）
            detected_ext = url_ext
            try:
                head_resp = self._req_session.head(img_url, headers=headers, timeout=min(timeout, 10), allow_redirects=True)
                ct_ext = self._guess_extension_from_content_type(head_resp)
                if ct_ext:
                    detected_ext = ct_ext
            except Exception:
                pass

            # 确定最终文件名
            if save_name:
                final_filename = f"{self._sanitize_filename(save_name)}{detected_ext or '.jpg'}"
            elif base_file:
                final_filename = self._sanitize_filename(base_file)
                # 如果 URL 无后缀但检测到了，补上
                if not url_ext and detected_ext:
                    final_filename = f"{final_filename}{detected_ext}"
            else:
                # 用 URL hash 做文件名
                url_hash = hashlib.md5(img_url.encode()).hexdigest()[:10]
                final_filename = f"img_{url_hash}{detected_ext or '.jpg'}"

            # 检查是否已存在
            full_save_path = os.path.join(save_dir, final_filename)
            if skip_if_exists and os.path.exists(full_save_path) and os.path.getsize(full_save_path) > 0:
                detail = {
                    "img_url": img_url,
                    "save_directory": save_dir,
                    "save_full_path": full_save_path,
                    "custom_save_name": save_name,
                    "tab_switch_info": switch_info,
                    "file_size_bytes": os.path.getsize(full_save_path),
                    "skipped": True,
                    "skip_reason": "file already exists"
                }
                result_json = {
                    "code": 200,
                    "status": "success",
                    "message": f"Image already exists, skipped: {full_save_path}",
                    "detail": detail,
                    "data": full_save_path
                }
                return json.dumps(result_json, ensure_ascii=False, indent=2)

            # 若不跳过但文件存在，自动重命名
            if os.path.exists(full_save_path):
                full_save_path = self._get_unique_save_path(save_dir, final_filename)

            # 流式下载
            total_size, resp_headers = self._stream_download(
                url=img_url, save_path=full_save_path,
                headers=headers, timeout=timeout
            )

            detail = {
                "img_url": img_url,
                "save_directory": save_dir,
                "save_full_path": full_save_path,
                "custom_save_name": save_name,
                "auto_file_name": os.path.basename(full_save_path),
                "tab_switch_info": switch_info,
                "file_size_bytes": total_size,
                "detected_extension": detected_ext,
                "content_type": resp_headers.get("Content-Type", ""),
                "skipped": False
            }
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"Image download success, saved to {full_save_path}",
                "detail": detail,
                "data": full_save_path
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except requests.exceptions.RequestException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Image download network request error: {str(e)}",
                "detail": {"img_url": img_url, "save_dir": save_dir, "error_type": "RequestError"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Download image failed: {str(e)}",
                "detail": {"img_url": img_url, "save_dir": save_dir, "target_tab": target_tab,
                           "error_type": "GeneralException"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    # ================================================================
    #  通用文件下载（增强版）
    # ================================================================
    def download_file_from_url(self, file_url, save_dir="./download_file",
                               save_name=None, target_tab=None, timeout=30,
                               skip_if_exists=True, resume=True,
                               use_browser_cookies=True, add_referer=True,
                               show_progress=False):
        """
        【增强版】通用文件下载。
        改进：从 Content-Disposition 提取文件名、断点续传、进度显示、
              自动 Cookie/Referer、文件名清理与去重。
        :param file_url: 文件下载链接
        :param save_dir: 保存目录
        :param save_name: 自定义文件名（不带后缀），None 自动从 URL/响应头提取
        :param target_tab: 目标标签页
        :param timeout: 请求超时
        :param skip_if_exists: 已存在是否跳过
        :param resume: 是否启用断点续传
        :param use_browser_cookies: 是否同步浏览器 Cookie
        :param add_referer: 是否添加 Referer
        :param show_progress: 是否打印下载进度
        :return: JSON string
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            if not file_url or not isinstance(file_url, str) or file_url.strip() == "":
                raise Exception("File url empty, skip download")
            file_url = file_url.strip()

            # 切换标签 + Referer
            referer = None
            switch_info = None
            if target_tab is not None:
                switch_res = json.loads(self.switch_to_specific_tab(target_tab))
                if switch_res["code"] != 200:
                    raise Exception(f"Switch tab failed: {switch_res['message']}")
                switch_info = f"Success switch to tab: {target_tab}"
            if add_referer:
                try:
                    referer = self.driver.current_url
                except Exception:
                    referer = None

            # 同步 Cookie
            if use_browser_cookies:
                self._sync_browser_cookies()

            # 创建目录
            self._ensure_dir(save_dir)

            # 解析 URL 文件名
            parsed = urlparse(unquote(file_url))
            url_base_file = os.path.basename(parsed.path)
            url_ext = os.path.splitext(url_base_file)[1].lower() if url_base_file else ""

            headers = self._build_headers(referer=referer)

            # 先发一次请求获取响应头（用于 Content-Disposition + Content-Length）
            # 用 stream 不下载 body，只拿 header
            pre_resp = None
            try:
                pre_resp = self._req_session.get(
                    file_url, headers=headers, timeout=min(timeout, 15),
                    stream=True, allow_redirects=True
                )
                pre_resp.raise_for_status()
            except requests.exceptions.RequestException as e:
                # 预请求失败，直接报错返回
                fail_json = {
                    "code": 500,
                    "status": "failed",
                    "message": f"File download pre-request error: {str(e)}",
                    "detail": {"file_url": file_url, "save_dir": save_dir, "error_type": "RequestError"},
                    "data": None
                }
                return json.dumps(fail_json, ensure_ascii=False, indent=2)

            # 从 Content-Disposition 提取文件名
            cd_filename = self._extract_filename_from_disposition(pre_resp, fallback="")
            # 从 Content-Type 推断后缀
            ct_ext = self._guess_extension_from_content_type(pre_resp, fallback="")
            content_length = pre_resp.headers.get("Content-Length", "")

            # 确定最终文件名优先级：自定义 > Content-Disposition > URL 文件名
            if save_name:
                ext = url_ext or ct_ext or ""
                final_filename = f"{self._sanitize_filename(save_name)}{ext}"
            elif cd_filename:
                final_filename = self._sanitize_filename(cd_filename)
            elif url_base_file:
                final_filename = self._sanitize_filename(url_base_file)
                if not url_ext and ct_ext:
                    final_filename = f"{final_filename}{ct_ext}"
            else:
                url_hash = hashlib.md5(file_url.encode()).hexdigest()[:10]
                final_filename = f"file_{url_hash}{ct_ext or '.bin'}"

            # 关闭预请求连接
            try:
                pre_resp.close()
            except Exception:
                pass

            full_save_path = os.path.join(save_dir, final_filename)

            # 跳过已下载
            if skip_if_exists and os.path.exists(full_save_path) and os.path.getsize(full_save_path) > 0:
                # 如果已知 Content-Length 且文件大小匹配，确认完整
                local_size = os.path.getsize(full_save_path)
                is_complete = True
                if content_length and content_length.isdigit():
                    is_complete = (local_size >= int(content_length))
                if is_complete:
                    detail = {
                        "file_url": file_url,
                        "save_directory": save_dir,
                        "save_full_path": full_save_path,
                        "custom_save_name": save_name,
                        "auto_file_name": final_filename,
                        "tab_switch_info": switch_info,
                        "timeout_second": timeout,
                        "file_size_bytes": local_size,
                        "content_length_header": content_length,
                        "skipped": True,
                        "skip_reason": "file already exists and complete"
                    }
                    result_json = {
                        "code": 200,
                        "status": "success",
                        "message": f"File already exists, skipped: {full_save_path}",
                        "detail": detail,
                        "data": full_save_path
                    }
                    return json.dumps(result_json, ensure_ascii=False, indent=2)

            # 若不跳过但文件存在，自动重命名（断点续传模式除外）
            if not resume and os.path.exists(full_save_path):
                full_save_path = self._get_unique_save_path(save_dir, final_filename)

            # 流式下载（支持断点续传）
            total_size, resp_headers = self._stream_download(
                url=file_url, save_path=full_save_path,
                headers=headers, timeout=timeout,
                show_progress=show_progress, resume=resume
            )

            detail = {
                "file_url": file_url,
                "save_directory": save_dir,
                "save_full_path": full_save_path,
                "custom_save_name": save_name,
                "auto_file_name": os.path.basename(full_save_path),
                "tab_switch_info": switch_info,
                "timeout_second": timeout,
                "file_size_bytes": total_size,
                "content_length_header": resp_headers.get("Content-Length", ""),
                "content_type": resp_headers.get("Content-Type", ""),
                "content_disposition": resp_headers.get("Content-Disposition", ""),
                "resume_enabled": resume,
                "skipped": False
            }
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"File download success, saved to {full_save_path}",
                "detail": detail,
                "data": full_save_path
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except requests.exceptions.RequestException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"File download network request error: {str(e)}",
                "detail": {"file_url": file_url, "save_dir": save_dir, "error_type": "RequestError"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"Download file failed: {str(e)}",
                "detail": {"file_url": file_url, "save_dir": save_dir, "target_tab": target_tab,
                           "error_type": "GeneralException"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    # ================================================================
    #  批量下载页面图片（增强版：并发 + 懒加载预滚动 + 跳过已下载）
    # ================================================================
    def download_all_tab_images(self, target_tab=None, save_dir="./tab_images",
                                prefix="img", max_workers=None,
                                skip_if_exists=True, filter_by_suffix=True,
                                auto_scroll=True):
        """
        【增强版】批量下载指定标签页所有图片。
        改进：线程池并发下载、先滚动触发懒加载、跳过已下载、单张失败自动跳过。
        :param target_tab: 目标标签页
        :param save_dir: 保存目录
        :param prefix: 文件名前缀（当 URL 无法提取有效文件名时使用）
        :param max_workers: 并发数，None 使用实例默认值
        :param skip_if_exists: 已存在是否跳过
        :param filter_by_suffix: 提取图片时是否按后缀过滤
        :param auto_scroll: 是否先滚动页面触发懒加载
        :return: JSON 汇总结果
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")

            workers = max_workers or self.download_max_workers

            # 1. 获取页面所有图片链接（增强版）
            img_res_str = self.get_all_img_links(
                target_tab=target_tab,
                filter_by_suffix=filter_by_suffix,
                auto_scroll=auto_scroll
            )
            img_res = json.loads(img_res_str)
            if img_res["code"] != 200:
                raise Exception(f"获取图片链接失败：{img_res['message']}")
            img_url_list = img_res["data"]
            total = len(img_url_list)

            if total == 0:
                result_json = {
                    "code": 200,
                    "status": "success",
                    "message": "页面无符合格式的图片，无需下载",
                    "detail": {"total_count": 0, "success_count": 0, "fail_count": 0,
                               "skip_count": 0, "max_workers": workers},
                    "data": []
                }
                return json.dumps(result_json, ensure_ascii=False, indent=2)

            self._log(f"\n===== 开始批量下载，共 {total} 张图片（并发数: {workers}）=====")

            # 确保目录
            self._ensure_dir(save_dir)

            # 同步一次 Cookie（并发线程共享 session）
            self._sync_browser_cookies()

            # 获取当前页面 URL 作为 Referer
            try:
                if target_tab is not None:
                    self.switch_to_specific_tab(target_tab)
                page_referer = self.driver.current_url
            except Exception:
                page_referer = None

            # 2. 并发下载
            success_list = []
            fail_list = []
            skip_list = []
            list_lock = threading.Lock()
            completed = [0]

            def _download_one(idx, img_url):
                try:
                    # 用 URL hash 做文件名，避免重复；保留原扩展名
                    parsed = urlparse(unquote(img_url))
                    base = os.path.basename(parsed.path)
                    ext = os.path.splitext(base)[1] if base else ""
                    if not ext:
                        # 无后缀时用前缀+序号
                        save_name = f"{prefix}_{idx}"
                    else:
                        # 有后缀时用 hash 前缀避免重名
                        url_hash = hashlib.md5(img_url.encode()).hexdigest()[:8]
                        save_name = f"{prefix}_{idx}_{url_hash}"

                    down_str = self.download_image_from_url(
                        img_url=img_url,
                        save_dir=save_dir,
                        save_name=save_name,
                        target_tab=None,  # 并发时不切换标签，避免竞争
                        skip_if_exists=skip_if_exists,
                        use_browser_cookies=False,  # 已在外部同步
                        add_referer=False
                    )
                    down_res = json.loads(down_str)
                    completed[0] += 1
                    self._log(f"【进度 {completed[0]}/{total}】{'跳过' if down_res.get('detail', {}).get('skipped') else '完成'}: {img_url[:80]}")

                    with list_lock:
                        if down_res["code"] == 200:
                            if down_res.get("detail", {}).get("skipped"):
                                skip_list.append({"img_url": img_url, "save_path": down_res["data"]})
                            else:
                                success_list.append({"img_url": img_url, "save_path": down_res["data"]})
                        else:
                            fail_list.append({"img_url": img_url, "error_msg": down_res["message"]})
                except Exception as e:
                    completed[0] += 1
                    with list_lock:
                        fail_list.append({"img_url": img_url, "error_msg": f"异常: {str(e)}"})
                    self._log(f"【进度 {completed[0]}/{total}】失败: {img_url[:80]} - {e}")

            with ThreadPoolExecutor(max_workers=workers) as executor:
                futures = [
                    executor.submit(_download_one, idx, url)
                    for idx, url in enumerate(img_url_list)
                ]
                for f in as_completed(futures):
                    try:
                        f.result()
                    except Exception:
                        pass

            # 3. 汇总
            success_count = len(success_list)
            fail_count = len(fail_list)
            skip_count = len(skip_list)

            self._log(f"\n===== 批量下载全部完成 =====")
            self._log(f"总数：{total} | 新下载：{success_count} | 跳过：{skip_count} | 失败：{fail_count}")

            detail_info = {
                "target_tab": target_tab,
                "save_directory": save_dir,
                "file_prefix": prefix,
                "total_count": total,
                "success_count": success_count,
                "skip_count": skip_count,
                "fail_count": fail_count,
                "max_workers": workers
            }
            result_data = {
                "success_images": success_list,
                "skip_images": skip_list,
                "fail_images": fail_list
            }
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"批量图片下载完成，总数{total}，新下载{success_count}，跳过{skip_count}，失败{fail_count}",
                "detail": detail_info,
                "data": result_data
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"批量下载页面图片WebDriver异常：{str(e)}",
                "detail": {"target_tab": target_tab, "save_dir": save_dir},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"批量下载页面图片失败：{str(e)}",
                "detail": {"target_tab": target_tab, "save_dir": save_dir},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    # ================================================================
    #  批量下载文件（新增）
    # ================================================================
    def batch_download_files(self, file_url_list, save_dir="./batch_files",
                             max_workers=None, skip_if_exists=True,
                             resume=True, timeout=60, target_tab=None):
        """
        【新增】从 URL 列表批量下载任意文件，线程池并发，单文件失败自动跳过。
        :param file_url_list: 文件 URL 列表
        :param save_dir: 保存目录
        :param max_workers: 并发数
        :param skip_if_exists: 已存在是否跳过
        :param resume: 是否断点续传
        :param timeout: 单文件超时
        :param target_tab: 用于获取 Referer/Cookie 的标签页
        :return: JSON 汇总结果
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")
            if not file_url_list or not isinstance(file_url_list, list):
                raise Exception("file_url_list must be a non-empty list")

            workers = max_workers or self.download_max_workers
            self._ensure_dir(save_dir)

            # 同步 Cookie + 获取 Referer
            if target_tab is not None:
                switch_res = json.loads(self.switch_to_specific_tab(target_tab))
                if switch_res["code"] != 200:
                    raise Exception(f"Switch tab failed: {switch_res['message']}")
            self._sync_browser_cookies()
            try:
                page_referer = self.driver.current_url
            except Exception:
                page_referer = None

            total = len(file_url_list)
            self._log(f"\n===== 开始批量下载文件，共 {total} 个（并发数: {workers}）=====")

            success_list = []
            fail_list = []
            skip_list = []
            list_lock = threading.Lock()
            completed = [0]

            def _download_one(idx, file_url):
                try:
                    down_str = self.download_file_from_url(
                        file_url=file_url,
                        save_dir=save_dir,
                        save_name=None,
                        target_tab=None,
                        timeout=timeout,
                        skip_if_exists=skip_if_exists,
                        resume=resume,
                        use_browser_cookies=False,
                        add_referer=False,
                        show_progress=False
                    )
                    down_res = json.loads(down_str)
                    completed[0] += 1
                    status = "跳过" if down_res.get("detail", {}).get("skipped") else "完成"
                    self._log(f"【进度 {completed[0]}/{total}】{status}: {file_url[:80]}")

                    with list_lock:
                        if down_res["code"] == 200:
                            item = {"file_url": file_url, "save_path": down_res["data"],
                                    "size": down_res.get("detail", {}).get("file_size_bytes", 0)}
                            if down_res.get("detail", {}).get("skipped"):
                                skip_list.append(item)
                            else:
                                success_list.append(item)
                        else:
                            fail_list.append({"file_url": file_url, "error_msg": down_res["message"]})
                except Exception as e:
                    completed[0] += 1
                    with list_lock:
                        fail_list.append({"file_url": file_url, "error_msg": f"异常: {str(e)}"})
                    self._log(f"【进度 {completed[0]}/{total}】失败: {file_url[:80]} - {e}")

            with ThreadPoolExecutor(max_workers=workers) as executor:
                futures = [
                    executor.submit(_download_one, idx, url)
                    for idx, url in enumerate(file_url_list)
                ]
                for f in as_completed(futures):
                    try:
                        f.result()
                    except Exception:
                        pass

            success_count = len(success_list)
            fail_count = len(fail_list)
            skip_count = len(skip_list)

            self._log(f"\n===== 批量文件下载完成 =====")
            self._log(f"总数：{total} | 新下载：{success_count} | 跳过：{skip_count} | 失败：{fail_count}")

            detail_info = {
                "save_directory": save_dir,
                "total_count": total,
                "success_count": success_count,
                "skip_count": skip_count,
                "fail_count": fail_count,
                "max_workers": workers,
                "resume_enabled": resume
            }
            result_data = {
                "success_files": success_list,
                "skip_files": skip_list,
                "fail_files": fail_list
            }
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"批量文件下载完成，总数{total}，新下载{success_count}，跳过{skip_count}，失败{fail_count}",
                "detail": detail_info,
                "data": result_data
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"批量下载文件失败：{str(e)}",
                "detail": {"save_dir": save_dir, "error_type": "GeneralException"},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def download_all_tab_files(self, target_tab=None, save_dir="./tab_files",
                               suffix_filter=None, max_workers=None,
                               skip_if_exists=True, resume=True, timeout=60):
        """
        【新增】提取当前页面所有文件下载链接并批量下载。
        :param target_tab: 目标标签页
        :param save_dir: 保存目录
        :param suffix_filter: 自定义后缀过滤集合
        :param max_workers: 并发数
        :param skip_if_exists: 已存在是否跳过
        :param resume: 是否断点续传
        :param timeout: 单文件超时
        :return: JSON 汇总结果
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")

            # 1. 提取页面文件链接
            file_res_str = self.get_all_file_links(target_tab=target_tab, suffix_filter=suffix_filter)
            file_res = json.loads(file_res_str)
            if file_res["code"] != 200:
                raise Exception(f"获取文件链接失败：{file_res['message']}")
            file_url_list = file_res["data"]
            total = len(file_url_list)

            if total == 0:
                result_json = {
                    "code": 200,
                    "status": "success",
                    "message": "页面无符合格式的文件下载链接，无需下载",
                    "detail": {"total_count": 0, "success_count": 0, "fail_count": 0, "skip_count": 0},
                    "data": []
                }
                return json.dumps(result_json, ensure_ascii=False, indent=2)

            # 2. 调用批量下载
            return self.batch_download_files(
                file_url_list=file_url_list,
                save_dir=save_dir,
                max_workers=max_workers,
                skip_if_exists=skip_if_exists,
                resume=resume,
                timeout=timeout,
                target_tab=target_tab
            )
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"下载页面所有文件失败：{str(e)}",
                "detail": {"target_tab": target_tab, "save_dir": save_dir},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

    def batch_visit_links_download_all_images(self, target_tab=None,
                                              save_root="./link_img_batch",
                                              prefix="link_img",
                                              max_workers_per_page=None,
                                              skip_if_exists=True):
        """
        获取页面全部超链接，逐个打开链接并批量下载每个页面内所有图片；
        单链接访问/下载失败自动跳过，不中断整体流程。
        :param target_tab: 源页面标签
        :param save_root: 根保存目录
        :param prefix: 每个页面内图片前缀
        :param max_workers_per_page: 每页图片并发数
        :param skip_if_exists: 是否跳过已下载
        :return: JSON 汇总
        """
        try:
            if not self.driver:
                raise Exception("Browser driver not initialized")

            self._log(f"\n===== 步骤1：读取源页面所有超链接 =====")
            link_ret_str = self.get_all_a_links(target_tab)
            link_ret = json.loads(link_ret_str)
            if link_ret["code"] != 200:
                raise Exception(f"提取页面链接失败：{link_ret['message']}")
            all_links = link_ret["data"]
            total_link_num = len(all_links)

            if total_link_num == 0:
                result_json = {
                    "code": 200,
                    "status": "success",
                    "message": "当前页面无可用超链接，无需访问下载",
                    "detail": {"total_links": 0, "success_link_count": 0, "fail_link_count": 0},
                    "data": []
                }
                return json.dumps(result_json, ensure_ascii=False, indent=2)

            self._log(f"共提取到 {total_link_num} 个待访问链接")
            source_handle = self.driver.current_window_handle
            link_success_list = []
            link_fail_list = []

            for link_idx, url in enumerate(all_links):
                self._log(f"\n========================================")
                self._log(f"【链接进度 {link_idx+1}/{total_link_num}】当前访问地址：{url}")
                try:
                    tab_create_res = json.loads(self.create_new_tab())
                    if tab_create_res["code"] != 200:
                        raise Exception(f"创建新标签失败：{tab_create_res['message']}")
                    all_handles = self.driver.window_handles
                    new_tab_handle = all_handles[-1]
                    switch_res = json.loads(self.switch_to_specific_tab(new_tab_handle))
                    if switch_res["code"] != 200:
                        raise Exception(f"切换新标签失败：{switch_res['message']}")

                    open_ret = json.loads(self.open_url_in_specific_tab(url, target=new_tab_handle))
                    if open_ret["code"] != 200:
                        raise Exception(f"链接页面打开失败：{open_ret['message']}")
                    page_title = self.driver.title.strip()
                    self._log(f"页面加载完成，标题：{page_title}")

                    safe_folder_name = f"link_{link_idx}"
                    single_link_save_dir = os.path.join(save_root, safe_folder_name)
                    self._log(f"当前页面图片保存目录：{single_link_save_dir}")

                    # 调用增强版批量下载
                    down_batch_str = self.download_all_tab_images(
                        target_tab=new_tab_handle,
                        save_dir=single_link_save_dir,
                        prefix=prefix,
                        max_workers=max_workers_per_page,
                        skip_if_exists=skip_if_exists
                    )
                    down_batch_res = json.loads(down_batch_str)

                    link_success_info = {
                        "link_url": url,
                        "page_title": page_title,
                        "save_folder": single_link_save_dir,
                        "img_total": down_batch_res["detail"]["total_count"],
                        "img_success": down_batch_res["detail"]["success_count"],
                        "img_skip": down_batch_res["detail"].get("skip_count", 0),
                        "img_fail": down_batch_res["detail"]["fail_count"],
                        "batch_detail": down_batch_res
                    }
                    link_success_list.append(link_success_info)

                    close_res = json.loads(self.close_specific_tab(new_tab_handle))
                    self.driver.switch_to.window(source_handle)
                except Exception as link_err:
                    err_msg = f"当前链接处理异常，自动跳过该链接：{str(link_err)}"
                    self._log(f"【链接处理失败跳过】{err_msg}")
                    link_fail_list.append({"link_url": url, "error_message": err_msg})
                    try:
                        self.driver.switch_to.window(source_handle)
                    except Exception:
                        pass
                    continue

            success_link_count = len(link_success_list)
            fail_link_count = len(link_fail_list)
            self._log(f"\n===== 全部链接处理完成 =====")
            self._log(f"总链接数：{total_link_num} | 成功处理链接：{success_link_count} | 失败链接：{fail_link_count}")

            detail_info = {
                "source_tab": target_tab,
                "root_save_directory": save_root,
                "file_prefix": prefix,
                "total_links": total_link_num,
                "success_link_count": success_link_count,
                "fail_link_count": fail_link_count
            }
            result_data = {
                "success_links": link_success_list,
                "fail_links": link_fail_list
            }
            result_json = {
                "code": 200,
                "status": "success",
                "message": f"批量链接访问图片下载完成，总链接{total_link_num}，成功{success_link_count}，失败{fail_link_count}",
                "detail": detail_info,
                "data": result_data
            }
            return json.dumps(result_json, ensure_ascii=False, indent=2)
        except WebDriverException as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"批量访问链接下载图片WebDriver异常：{str(e)}",
                "detail": {"target_tab": target_tab, "save_root": save_root},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)
        except Exception as e:
            fail_json = {
                "code": 500,
                "status": "failed",
                "message": f"批量访问链接下载图片整体失败：{str(e)}",
                "detail": {"target_tab": target_tab, "save_root": save_root},
                "data": None
            }
            return json.dumps(fail_json, ensure_ascii=False, indent=2)

if __name__ == "__main__":
    browser = None
    print("程序启动，正在初始化浏览器...")
    try:
        browser = FirefoxAutoBrowser()
        init_res = json.loads(browser.init_result)
        if init_res["code"] != 200:
            print(f"浏览器初始化失败：{init_res['message']}")
            exit(1)

        while True:
            print("\n----------------------------------------")
            cmd_input = input("请输入操作命令：").strip()
            if not cmd_input:
                print("命令不能为空，请重新输入")
                continue
            cmd = cmd_input.lower()

            if cmd == "exit":
                print("准备关闭浏览器并退出程序...")
                quit_ret = browser.quit_browser()
                print(quit_ret)
                print("程序已退出")
                break

            if cmd == "help":
                help_text = """
==================== 可用命令清单 ====================
基础标签页操作：
  new_tab                创建新空白标签页
  all_tabs               获取所有标签页信息
  active_tab             获取当前激活标签页
  switch_tab             切换标签页，输入索引/句柄
  close_tab              关闭指定标签页（默认当前页）
  open_url               在标签页打开网页，输入url [tab索引默认0]
页面内容操作：
  get_html               获取页面HTML源码，可选输入tab索引
  scroll_down            页面向下滚动，输入像素(默认500) [tab]
  scroll_up              页面向上滚动，输入像素(默认500) [tab]
  click_xpath            通过xpath点击元素，输入xpath [tab]
  click_elem             通用点击：定位类型 定位表达式 [tab]
  get_links              提取页面所有a标签超链接(仅http/https) [tab]
  get_imgs               提取页面图片链接(增强版，含懒加载/背景图) [tab]
  get_files              提取页面所有文件下载链接 [tab]
下载功能：
  download_img           下载单张图片：图片url [保存目录] [自定义名称] [tab]
  download_file          下载通用文件：文件url [保存目录] [自定义名称] [tab]
  download_all_imgs      批量下载页面全部图片(并发)：[tab] [保存目录] [前缀] [并发数]
  download_all_files     批量下载页面全部文件(并发)：[tab] [保存目录] [并发数]
  batch_download_files   从URL列表批量下载文件：先输入URL数量，再逐个输入
  batch_link_download    批量访问页面所有链接并下载每个页面全部图片：[tab] [根目录] [前缀]
系统命令：
  help                   查看命令帮助
  exit                   关闭浏览器并退出程序
=====================================================
                """
                print(help_text)
                continue

            if cmd == "new_tab":
                ret = browser.create_new_tab()
                print(ret)
                continue

            if cmd == "all_tabs":
                ret = browser.get_all_tabs()
                print(ret)
                continue

            if cmd == "active_tab":
                ret = browser.get_active_tab()
                print(ret)
                continue

            if cmd == "switch_tab":
                target_in = input("输入目标标签索引(数字)或句柄字符串：").strip()
                try:
                    target = int(target_in)
                except ValueError:
                    target = target_in
                ret = browser.switch_to_specific_tab(target)
                print(ret)
                continue

            if cmd == "close_tab":
                target_in = input("输入要关闭的标签索引/句柄，直接回车关闭当前激活页：").strip()
                target = None
                if target_in:
                    try:
                        target = int(target_in)
                    except ValueError:
                        target = target_in
                ret = browser.close_specific_tab(target)
                print(ret)
                continue

            if cmd == "open_url":
                url = input("输入要打开的网址：").strip()
                tab_in = input("输入目标标签索引(默认0，直接回车)：").strip()
                target = 0
                if tab_in:
                    target = int(tab_in)
                ret = browser.open_url_in_specific_tab(url, target)
                print(ret)
                continue

            if cmd == "get_html":
                tab_in = input("输入目标标签索引，回车取当前激活页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                ret = browser.get_specific_tab_page_content(target)
                print(ret)
                continue

            if cmd == "scroll_down":
                dis_in = input("滚动像素(默认500，回车)：").strip()
                dis = 500
                if dis_in:
                    dis = int(dis_in)
                tab_in = input("目标标签索引，回车当前页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                ret = browser.scroll_mouse_wheel_down(dis, target)
                print(ret)
                continue

            if cmd == "scroll_up":
                dis_in = input("滚动像素(默认500，回车)：").strip()
                dis = 500
                if dis_in:
                    dis = int(dis_in)
                tab_in = input("目标标签索引，回车当前页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                ret = browser.scroll_mouse_wheel_up(dis, target)
                print(ret)
                continue

            if cmd == "click_xpath":
                xpath_str = input("输入XPath表达式：").strip()
                tab_in = input("目标标签索引，回车当前页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                ret = browser.click_element_by_xpath(xpath_str, target)
                print(ret)
                continue

            if cmd == "click_elem":
                loc_type = input("输入定位类型(id/xpath/css_selector等)：").strip()
                loc_exp = input("输入定位表达式：").strip()
                tab_in = input("目标标签索引，回车当前页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                ret = browser.click_element(loc_exp, loc_type, target)
                print(ret)
                continue

            if cmd == "get_links":
                tab_in = input("目标标签索引，回车当前页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                ret = browser.get_all_a_links(target)
                print(ret)
                continue

            if cmd == "get_imgs":
                tab_in = input("目标标签索引，回车当前页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                filter_in = input("是否按后缀过滤(y/n，默认y)：").strip().lower()
                filter_by_suffix = (filter_in != "n")
                ret = browser.get_all_img_links(target, filter_by_suffix=filter_by_suffix)
                print(ret)
                continue

            if cmd == "get_files":
                tab_in = input("目标标签索引，回车当前页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                ret = browser.get_all_file_links(target)
                print(ret)
                continue

            if cmd == "download_img":
                img_url = input("输入图片URL：").strip()
                save_dir = input("保存目录(默认./download_img，回车)：").strip() or "./download_img"
                save_name = input("自定义文件名(不带后缀，回车自动提取)：").strip() or None
                tab_in = input("目标标签索引，回车当前页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                ret = browser.download_image_from_url(img_url, save_dir, save_name, target)
                print(ret)
                continue

            if cmd == "download_file":
                file_url = input("输入文件URL：").strip()
                save_dir = input("保存目录(默认./download_file，回车)：").strip() or "./download_file"
                save_name = input("自定义文件名(不带后缀，回车自动提取)：").strip() or None
                tab_in = input("目标标签索引，回车当前页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                timeout_in = input("超时秒数(默认30，回车)：").strip()
                timeout = 30
                if timeout_in:
                    timeout = int(timeout_in)
                progress_in = input("是否显示下载进度(y/n，默认n)：").strip().lower()
                show_progress = (progress_in == "y")
                ret = browser.download_file_from_url(
                    file_url, save_dir, save_name, target, timeout,
                    show_progress=show_progress
                )
                print(ret)
                continue

            if cmd == "download_all_imgs":
                tab_in = input("目标标签索引，回车当前激活页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                save_dir = input("保存目录(默认./tab_images，回车)：").strip() or "./tab_images"
                prefix = input("批量文件名前缀(默认img，回车)：").strip() or "img"
                worker_in = input("并发线程数(默认5，回车)：").strip()
                max_workers = int(worker_in) if worker_in else None
                ret = browser.download_all_tab_images(target, save_dir, prefix, max_workers=max_workers)
                print(ret)
                continue

            if cmd == "download_all_files":
                tab_in = input("目标标签索引，回车当前激活页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                save_dir = input("保存目录(默认./tab_files，回车)：").strip() or "./tab_files"
                worker_in = input("并发线程数(默认5，回车)：").strip()
                max_workers = int(worker_in) if worker_in else None
                ret = browser.download_all_tab_files(target, save_dir, max_workers=max_workers)
                print(ret)
                continue

            if cmd == "batch_download_files":
                count_in = input("请输入要下载的文件URL数量：").strip()
                try:
                    count = int(count_in)
                except ValueError:
                    print("数量必须是数字")
                    continue
                if count <= 0:
                    print("数量必须大于0")
                    continue
                url_list = []
                for i in range(count):
                    u = input(f"输入第 {i+1}/{count} 个文件URL：").strip()
                    if u:
                        url_list.append(u)
                if not url_list:
                    print("未输入有效URL")
                    continue
                save_dir = input("保存目录(默认./batch_files，回车)：").strip() or "./batch_files"
                worker_in = input("并发线程数(默认5，回车)：").strip()
                max_workers = int(worker_in) if worker_in else None
                ret = browser.batch_download_files(url_list, save_dir, max_workers=max_workers)
                print(ret)
                continue

            if cmd == "batch_link_download":
                tab_in = input("源页面标签索引（存放链接的页面），回车当前激活页：").strip()
                target = None
                if tab_in:
                    target = int(tab_in)
                root_dir = input("图片根保存目录(默认./link_img_batch，回车)：").strip() or "./link_img_batch"
                img_prefix = input("页面内图片文件名前缀(默认link_img，回车)：").strip() or "link_img"
                ret = browser.batch_visit_links_download_all_images(target, root_dir, img_prefix)
                print("\n===== 批量链接访问下载汇总结果 =====")
                print(ret)
                continue

            else:
                print(f"未知命令：{cmd_input}，输入 help 查看可用命令")

    except Exception as global_err:
        print(f"全局运行异常：{str(global_err)}")
    finally:
        if browser and browser.driver:
            print("\n程序异常退出，正在释放浏览器资源...")
            try:
                browser.quit_browser()
            except Exception:
                pass
        print("程序结束")