shellx-ai 1.0.12 → 1.1.0

package/dist/shellx.js

@@ -1,1222 +1,825 @@
-"use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ShellX = void 0;
-exports.createShellX = createShellX;
-exports.createShellXWithShellMonitoring = createShellXWithShellMonitoring;
-const uuid_1 = require("uuid");
-const index_1 = __importDefault(require("./index"));
-const COMMAND_PTY_SID = 999;
 /**
- * ShellX automation utilities for common patterns
+ * ShellX - High-level automation utilities for Android device control
+ *
+ * This module provides a comprehensive API for automating Android devices,
+ * including UI actions, shell commands, element finding, and device information.
+ *
+ * @module shellx
  */
-class ShellX {
-    constructor(client) {
-        this.client = client;
-        this.shellOutputBuffers = new Map();
-        this.shellCommandPromises = new Map();
-        // 注意：由于 WebSocketTaskClient 的 config 是私有的，
-        // 监听 shell 输出需要在创建 WebSocketTaskClient 时设置 onMessage 回调
-        console.log('⚠️ [Shell] 注意：要监听 shell 输出，请在创建 WebSocketTaskClient 时设置 onMessage 回调');
-    }
-    /**
-     * Get the WebSocket client instance
+// Import refactored modules
+import { UIActionHandler } from "./automation/ui-action-handler.js";
+import { ElementFinder } from "./automation/element-finder.js";
+import { ShellCommandExecutor } from "./shell/shell-command-executor.js";
+// Import client
+import ConnectionClient from "./index.js";
+import { createLogger } from "./logger.js";
+/**
+ * ShellX - High-level Android automation SDK (Recommended API)
+ *
+ * **This is the recommended API for 95% of users.**
+ *
+ * ShellX provides a simple, intuitive interface for Android automation with:
+ *
+ * - ✅ Automatic error handling and retry logic
+ * - ✅ Type-safe TypeScript API
+ * - ✅ Consistent method signatures
+ * - ✅ Built-in timing and performance tracking
+ * - ✅ Simplified element selection
+ *
+ * **Key Features:**
+ * - UI interaction: click, input, swipe, press, wait
+ * - Element finding with smart selectors
+ * - Shell command execution
+ * - Screen info and screenshots
+ * - Batch operations
+ *
+ * **Quick Start:**
+ * ```typescript
+ * import { ShellX } from '@shellx-ai/sdk';
+ *
+ * // Initialize
+ * const shellx = new ShellX({ deviceId: 'your-device-id' });
+ *
+ * // Connect
+ * await shellx.connect();
+ *
+ * // Automate
+ * await shellx.click('Submit');
+ * await shellx.input({ text: 'Hello World' });
+ * await shellx.swipe({ fromX: 500, fromY: 1000, toX: 500, toY: 500 });
+ *
+ * // Get info
+ * const screen = await shellx.getScreenInfo();
+ * console.log(`Screen: ${screen.width}x${screen.height}`);
+ * ```
+ *
+ * **Note:** For low-level WebSocket access, see ConnectionClient (advanced users only).
+ *
+ * @see API-GUIDE.md for comprehensive documentation
+ * @see ConnectionClient for low-level protocol access
+ */
+export class ShellX {
+    /** Logger instance for ShellX */
+    logger;
+    /** UI action handler for executing UI operations */
+    uiActionHandler;
+    /** Element finder for locating UI elements */
+    elementFinder;
+    /** Shell command executor for running shell commands */
+    shellCommandExecutor;
+    /** Connection client for device communication */
+    client;
+    /**
+     * Creates a ShellX instance
+     *
+     * @param options - Configuration options for ShellX instance
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({
+     *   deviceId: 'device-id',
+     *   onOpen: () => console.log('Connected!'),
+     *   onMessage: (msg) => console.log(msg)
+     * });
+     *
+     * // Optionally wait for connection
+     * await shellx.ready();
+     *
+     * // Start using ShellX
+     * await shellx.click('Settings');
+     * ```
+     */
+    constructor(options) {
+        // Initialize logger with provided log level
+        this.logger = createLogger("ShellX", options.logLevel);
+        // Create ConnectionClient with options and logger
+        this.client = new ConnectionClient(options.deviceId, {
+            timeout: options.timeout ?? 5000,
+            reconnect: options.reconnect ?? true,
+            reconnectMaxAttempts: options.reconnectMaxAttempts ?? 5,
+            reconnectInterval: options.reconnectInterval ?? 1000,
+            pingInterval: options.pingInterval ?? 2000,
+            onOpen: () => {
+                this.logger.info("✅ WebSocket connection opened");
+                options.onOpen?.();
+            },
+            onClose: () => {
+                options.onClose?.();
+            },
+            onError: (error) => {
+                options.onError?.(error);
+            },
+            onReconnectFailed: () => {
+                options.onReconnectFailed?.();
+            },
+            onMessage: (message) => {
+                // Forward shell output to ShellX instance
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+                const wsMessage = message;
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                if (wsMessage.chunks) {
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access
+                    this.handleShellOutput(wsMessage.chunks);
+                }
+                // Call user's onMessage callback
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any
+                options.onMessage?.(message);
+            },
+        }, this.logger);
+        // Initialize handlers
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+        this.uiActionHandler = new UIActionHandler(this.client);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+        this.elementFinder = new ElementFinder(this.client);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+        this.shellCommandExecutor = new ShellCommandExecutor(this.client);
+        // Link client and shellx
+        this.client.setShellX(this);
+        this.logger.info("⏳ Initializing connection...");
+    }
+    /**
+     * Wait for connection to be ready
+     *
+     * This method waits for the WebSocket connection to be established.
+     * Most operations will automatically wait for connection, but you can
+     * call this method explicitly if you need to ensure connection before
+     * performing operations.
+     *
+     * @returns Promise that resolves when connection is ready
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * await shellx.ready();
+     * console.log('Connection is ready!');
+     * ```
+     */
+    async ready() {
+        await this.client.waitForInitialization();
+        this.logger.info("✅ Connection is ready");
+    }
+    /**
+     * Get the underlying ConnectionClient instance
+     *
+     * @returns The ConnectionClient instance
      */
     getClient() {
         return this.client;
     }
     /**
-     * 设置 shell 输出监听器（需要在创建 WebSocketTaskClient 时调用）
+     * Get the current log level
+     *
+     * @returns Current log level
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * console.log('Current log level:', shellx.getLogLevel());
+     * ```
      */
-    static createShellOutputHandler(helpers) {
-        return (message) => {
-            // 处理 chunks 数据（pty 终端输出）
-            if (message.chunks) {
-                helpers.handleShellOutput(message.chunks);
-            }
-        };
+    getLogLevel() {
+        return this.logger.getLogLevel();
     }
     /**
-     * 处理 shell 输出数据
+     * Set the log level
+     *
+     * @param level - Log level to set
+     *
+     * @example
+     * ```typescript
+     * import { ShellX, LogLevel } from '@shellx-ai/sdk';
+     *
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * shellx.setLogLevel(LogLevel.NONE);  // Disable all logging
+     * shellx.setLogLevel(LogLevel.ERROR); // Only errors
+     * shellx.setLogLevel(LogLevel.DEBUG); // All logs
+     * ```
      */
-    handleShellOutput(chunks) {
-        const [sessionId, len, dataArrays] = chunks;
-        if (sessionId === COMMAND_PTY_SID) {
-            try {
-                // 将 Uint8Array 数组转换为字符串
-                let output = '';
-                for (const data of dataArrays) {
-                    output += new TextDecoder().decode(data);
-                }
-                /*console.log(
-                  `📟 [Shell] 收到输出 (Session ${sessionId}): ${output.trim()}`,
-                );*/
-                // 为每个等待的命令累积输出
-                for (const [commandKey, commandPromise,] of this.shellCommandPromises.entries()) {
-                    if (!commandPromise.sessionOutputs.has(sessionId)) {
-                        commandPromise.sessionOutputs.set(sessionId, '');
-                    }
-                    const currentSessionOutput = commandPromise.sessionOutputs.get(sessionId) || '';
-                    commandPromise.sessionOutputs.set(sessionId, currentSessionOutput + output);
-                    commandPromise.output = this.combineSessionOutputs(commandPromise.sessionOutputs);
-                    /*console.log(
-                      `📊 [Shell] 命令 ${commandKey} 累积输出长度: ${commandPromise.output.length}`,
-                    );*/
-                    // 调用输出回调（传递清理后的输出）
-                    if (commandPromise.options.onOutput) {
-                        const cleanOutput = this.cleanCommandOutput(output, commandPromise.command);
-                        commandPromise.options.onOutput(cleanOutput);
-                    }
-                }
-            }
-            catch (error) {
-                console.error(`❌ [Shell] 处理输出数据失败:`, error);
-            }
-        }
+    setLogLevel(level) {
+        this.logger.setLogLevel(level);
     }
     /**
-     * 清理命令输出，去除输入的命令内容
+     * Enable all logging (equivalent to setLogLevel(LogLevel.DEBUG))
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * shellx.enableDebugLogging();
+     * ```
      */
-    cleanCommandOutput(output, command) {
-        return output.replace(command, '');
+    enableDebugLogging() {
+        this.logger.enableDebugLogging();
     }
     /**
-     * 合并多个 session 的输出
+     * Disable all logging (equivalent to setLogLevel(LogLevel.NONE))
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * shellx.disableLogging();
+     * ```
      */
-    combineSessionOutputs(sessionOutputs) {
-        const sessions = Array.from(sessionOutputs.keys()).sort();
-        let combined = '';
-        for (const sessionId of sessions) {
-            const sessionOutput = sessionOutputs.get(sessionId) || '';
-            combined += sessionOutput;
-        }
-        return combined;
+    disableLogging() {
+        this.logger.disableLogging();
     }
     /**
-     * 通用重试机制 - 失败时返回 undefined 而不是抛出异常
+     * Ensure connection is ready before executing device operations
+     *
+     * @param timeout - Timeout in milliseconds (default: 10000ms)
+     * @throws Error if connection timeout
      */
-    withRetry(operation_1) {
-        return __awaiter(this, arguments, void 0, function* (operation, options = {}) {
-            const { retry = 3, delay = 1000, onRetry } = options;
-            for (let attempt = 1; attempt <= retry; attempt++) {
-                try {
-                    return yield operation();
-                }
-                catch (error) {
-                    if (attempt === retry) {
-                        console.log(`❌ [Retry] 重试 ${retry} 次后仍然失败，返回 undefined:`, error);
-                        return undefined;
-                    }
-                    if (onRetry) {
-                        onRetry(attempt, error);
-                    }
-                    console.log(`🔄 [Retry] 第 ${attempt} 次尝试失败，${delay}ms 后重试...`);
-                    yield new Promise(resolve => setTimeout(resolve, delay));
-                }
-            }
-            return undefined;
-        });
+    async ensureConnectionReady(timeout = 10000) {
+        await this.client.ensureConnected(timeout);
     }
     /**
-     * 转换精简选择器为原始选择器
+     * Send chat message through ShellX
+     *
+     * @param message - The chat message to send
+     * @returns Promise that resolves when the message is sent
      */
-    convertSelector(selector) {
+    async sendChat(message) {
+        return this.client.sendChat(message);
+    }
+    async click(selectorOrData, options) {
+        await this.ensureConnectionReady();
+        if (typeof selectorOrData === "string") {
+            return this.uiActionHandler.click({ text: selectorOrData, ...options });
+        }
+        return this.uiActionHandler.click(selectorOrData);
+    }
+    /**
+     * Execute an input action
+     *
+     * @param inputData - Input configuration
+     * @returns Promise resolving to InputResult
+     *
+     * @example
+     * ```typescript
+     * const result = await shellx.input({
+     *   elementId: 'field123',
+     *   text: 'Hello World',
+     *   clear: true
+     * });
+     * ```
+     */
+    async input(inputData) {
+        await this.ensureConnectionReady();
+        return this.uiActionHandler.input(inputData);
+    }
+    /**
+     * Execute a swipe action
+     *
+     * @param swipeData - Swipe configuration
+     * @returns Promise resolving to SwipeResult
+     *
+     * @example
+     * ```typescript
+     * const result = await shellx.swipe({
+     *   fromX: 500,
+     *   fromY: 1000,
+     *   toX: 500,
+     *   toY: 500,
+     *   duration: 800
+     * });
+     * ```
+     */
+    async swipe(swipeData) {
+        await this.ensureConnectionReady();
+        return this.uiActionHandler.swipe(swipeData);
+    }
+    async press(keyOrData, options) {
+        await this.ensureConnectionReady();
+        if (typeof keyOrData === "string") {
+            return this.uiActionHandler.pressKey({ key: keyOrData, ...options });
+        }
+        return this.uiActionHandler.pressKey(keyOrData);
+    }
+    async wait(selectorOrData, options) {
+        await this.ensureConnectionReady();
+        if (typeof selectorOrData === "string") {
+            return this.uiActionHandler.wait({ text: selectorOrData, ...options });
+        }
+        return this.uiActionHandler.wait(selectorOrData);
+    }
+    async find(selectorOrData, options) {
+        await this.ensureConnectionReady();
+        const startTime = Date.now();
+        const findData = typeof selectorOrData === "string" ? { text: selectorOrData, ...options } : selectorOrData;
+        const selector = this.uiActionHandler["convertSelector"](findData);
+        const result = await this.client.findElement(selector, {
+            pressClick: findData.pressClick,
+            waitAfterMs: findData.waitAfterMs || 5000,
+            maxResults: findData.maxResults || 1000,
+            visibleOnly: true,
+            clickableOnly: false,
+            multiple: findData.multiple || false,
+        });
+        if (!result || result.success === false || !result.elements) {
+            return {
+                elements: [],
+                count: 0,
+                success: false,
+                found: false,
+                duration: 0,
+                timestamp: startTime,
+            };
+        }
         return {
-            elementId: selector.targetElementId,
-            resourceId: selector.targetResourceId,
-            className: selector.targetClass,
-            text: selector.targetText,
-            textContains: undefined,
-            visible: selector.visible,
-            clickable: selector.clickable
+            elements: result.elements.map((el) => ({
+                id: el.elementId,
+                text: el.text,
+                class: el.className,
+                left: el.bounds.left,
+                top: el.bounds.top,
+                right: el.bounds.right,
+                bottom: el.bounds.bottom,
+                visible: el.visible,
+                clickable: el.clickable,
+            })),
+            count: result.elements.length,
+            success: true,
+            found: true,
+            duration: 0,
+            timestamp: startTime,
         };
     }
-    /**
-     * 转换精简元素为原始元素
-     */
-    convertElement(uiElement) {
+    async command(cmdOrData, options) {
+        await this.ensureConnectionReady();
+        const startTime = Date.now();
+        const commandData = typeof cmdOrData === "string" ? { cmd: cmdOrData, ...options } : cmdOrData;
+        const result = await this.shellCommandExecutor.executeShellCommand(commandData.cmd, {
+            title: `Execute command: ${commandData.cmd}`,
+            timeout: commandData.timeout,
+            waitAfterMs: commandData.wait,
+        });
+        this.getClient().appendExecutionLog(`✅ Command executed successfully - Output: ${result.output}`);
         return {
-            id: uiElement.elementId,
-            text: uiElement.text,
-            class: uiElement.className,
-            left: uiElement.bounds.left,
-            top: uiElement.bounds.top,
-            right: uiElement.bounds.right,
-            bottom: uiElement.bounds.bottom,
-            visible: uiElement.visible,
-            clickable: uiElement.clickable
+            success: result.success,
+            output: result.output,
+            error: result.error,
+            exitCode: result.exitCode,
+            duration: result.duration,
+            cmd: commandData.cmd,
+            timestamp: startTime,
         };
     }
-    // ==================== 精简 Action 封装函数 ====================
     /**
-     * 点击操作 - 支持元素ID、坐标或选择器
-     */
-    click(clickData) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const startTime = Date.now();
-            const result = yield this.withRetry(() => __awaiter(this, void 0, void 0, function* () {
-                try {
-                    let target;
-                    if (clickData.targetElementId) {
-                        // 元素ID
-                        target = { type: "elementId", value: clickData.targetElementId };
-                    }
-                    else if (clickData.targetResourceId) {
-                        // 精简元素
-                        target = { type: "resourceId", value: clickData.targetResourceId };
-                    }
-                    else if (clickData.targetX !== undefined && clickData.targetY !== undefined) {
-                        // 坐标
-                        target = { type: "coordinate", value: { x: clickData.targetX, y: clickData.targetY } };
-                    }
-                    else if (clickData.targetText || clickData.targetClass) {
-                        // 选择器
-                        const element = yield this.findElementWithRetry(this.convertSelector(clickData), clickData.retry || 3);
-                        if (!element) {
-                            throw new Error('未找到目标元素');
-                        }
-                        target = { type: "elementId", value: element.elementId };
-                    }
-                    else {
-                        throw new Error('必须指定目标：targetElementId、targetResourceId、坐标(targetX/targetY)或选择器(targetText/targetClass)');
-                    }
-                    const action = {
-                        title: `点击操作: ${clickData.clickType || 'single'}`,
-                        actions: [{
-                                type: "click",
-                                target,
-                                options: {
-                                    clickType: clickData.clickType || 'single',
-                                    waitAfterMs: clickData.wait || 1000
-                                }
-                            }]
-                    };
-                    yield this.client.executeAction(action);
-                    return {
-                        success: true,
-                        data: {
-                            targetElementId: clickData.targetElementId,
-                            targetResourceId: clickData.targetResourceId,
-                            targetText: clickData.targetText,
-                            targetClass: clickData.targetClass,
-                            targetX: clickData.targetX,
-                            targetY: clickData.targetY,
-                            clickType: clickData.clickType
-                        },
-                        duration: Date.now() - startTime
-                    };
-                }
-                catch (error) {
-                    throw new Error(`点击操作失败: ${error instanceof Error ? error.message : String(error)}`);
-                }
-            }), { retry: clickData.retry, delay: 500 });
-            // 如果 withRetry 返回 undefined，返回失败的 ActionResult
-            if (!result) {
-                return {
-                    success: false,
-                    error: '点击操作失败',
-                    duration: Date.now() - startTime
-                };
-            }
-            return result;
-        });
+     * Execute a clipboard action
+     *
+     * @param clipboardData - Clipboard configuration
+     * @returns Promise resolving to ClipboardResult
+     *
+     * @example
+     * ```typescript
+     * // Get clipboard content
+     * const result = await shellx.clipboard({ get: true });
+     * console.log(result.text);
+     *
+     * // Set clipboard content
+     * await shellx.clipboard({ text: 'Hello' });
+     *
+     * // Paste clipboard content
+     * await shellx.clipboard({ paste: true });
+     * ```
+     */
+    async clipboard(clipboardData) {
+        await this.ensureConnectionReady();
+        const result = await this.uiActionHandler.clipboard(clipboardData);
+        return {
+            ...result,
+            text: result.text,
+            pasted: clipboardData.paste ? result.success : undefined,
+            getCopied: clipboardData.get ? result.success : undefined,
+        };
     }
-    /**
-     * 输入操作 - 支持元素ID、资源ID或选择器
-     */
-    input(inputData) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const startTime = Date.now();
-            const result = yield this.withRetry(() => __awaiter(this, void 0, void 0, function* () {
-                var _a, _b;
-                try {
-                    let target;
-                    if (inputData.targetElementId) {
-                        target = { type: "elementId", value: inputData.targetElementId };
-                    }
-                    else if (inputData.targetResourceId) {
-                        target = { type: "resourceId", value: inputData.targetResourceId };
-                    }
-                    else if (inputData.targetText || inputData.targetClass) {
-                        const element = yield this.findElementWithRetry(this.convertSelector(inputData), inputData.retry || 3);
-                        if (!element) {
-                            throw new Error('未找到目标元素');
-                        }
-                        target = { type: "elementId", value: element.elementId };
-                    }
-                    else {
-                        throw new Error('必须指定目标：targetElementId、targetResourceId、targetText或targetClass');
-                    }
-                    const action = {
-                        title: `输入文本: ${inputData.text}`,
-                        actions: [{
-                                type: "input",
-                                text: inputData.text,
-                                target,
-                                options: {
-                                    replaceExisting: (_a = inputData.clear) !== null && _a !== void 0 ? _a : true,
-                                    hideKeyboardAfter: (_b = inputData.hideKeyboard) !== null && _b !== void 0 ? _b : false,
-                                    waitAfterMs: inputData.wait || 500
-                                }
-                            }]
-                    };
-                    yield this.client.executeAction(action);
-                    return {
-                        success: true,
-                        data: {
-                            text: inputData.text,
-                            targetElementId: inputData.targetElementId,
-                            targetResourceId: inputData.targetResourceId,
-                            targetText: inputData.targetText,
-                            targetClass: inputData.targetClass
-                        },
-                        duration: Date.now() - startTime
-                    };
-                }
-                catch (error) {
-                    throw new Error(`输入操作失败: ${error instanceof Error ? error.message : String(error)}`);
-                }
-            }), { retry: inputData.retry, delay: 500 });
-            if (!result) {
-                return {
-                    success: false,
-                    error: '输入操作失败',
-                    duration: Date.now() - startTime
-                };
-            }
-            return result;
-        });
+    async getAppInfo(pkgOrData, options) {
+        await this.ensureConnectionReady();
+        const appInfoData = typeof pkgOrData === "string" ? { package: pkgOrData, ...options } : pkgOrData;
+        const result = await this.uiActionHandler.getAppInfo(appInfoData);
+        return result;
+    }
+    /**
+     * Get list of installed applications
+     *
+     * @param options - Options for filtering app list
+     * @returns Promise resolving to app list response
+     *
+     * @example
+     * ```typescript
+     * // Get all user apps
+     * const result = await shellx.getAppList();
+     * console.log(`Found ${result.userAppCount} user apps`);
+     * result.apps.forEach(app => {
+     *   console.log(`${app.appName} (${app.packageName})`);
+     * });
+     *
+     * // Get user and system apps
+     * const allApps = await shellx.getAppList({
+     *   includeSystemApps: true,
+     *   includeDisabledApps: false
+     * });
+     * ```
+     */
+    async getAppList(options) {
+        await this.ensureConnectionReady();
+        return this.uiActionHandler.getAppList(options);
+    }
+    /**
+     * Take a screenshot
+     *
+     * @param screenshotData - Screenshot configuration
+     * @returns Promise resolving to ScreenshotResult
+     *
+     * @example
+     * ```typescript
+     * const result = await shellx.takeScreenshot({
+     *   format: 'png',
+     *   quality: 100,
+     *   saveToFile: true
+     * });
+     *
+     * console.log(result.imagePath);
+     * ```
+     */
+    async takeScreenshot(screenshotData = {}) {
+        await this.ensureConnectionReady();
+        return await this.uiActionHandler.takeScreenshot(screenshotData);
+    }
+    /**
+     * Get screen information
+     *
+     * @returns Promise resolving to ScreenInfoResult
+     *
+     * @example
+     * ```typescript
+     * const screenInfo = await shellx.getScreenInfo();
+     * console.log(`Screen: ${screenInfo.width}x${screenInfo.height}`);
+     * console.log(`Current app: ${screenInfo.foregroundApp}`);
+     * ```
+     */
+    async getScreenInfo() {
+        await this.ensureConnectionReady();
+        const startTime = Date.now();
+        const info = await this.uiActionHandler.getScreenInfo();
+        if (!info || info.success === false) {
+            throw new Error(info?.error || "Failed to get screen info");
+        }
+        return {
+            success: true,
+            duration: Date.now() - startTime,
+            timestamp: startTime,
+            width: info.width,
+            height: info.height,
+            density: info.density,
+            screenOn: info.screenOn,
+            screenUnlocked: info.screenUnlocked,
+            foregroundApp: info.accurateForegroundApp,
+            foregroundActivity: info.accurateForegroundActivity,
+            model: info.model,
+            androidVersion: info.androidVersion,
+            manufacturer: info.manufacturer,
+        };
     }
     /**
-     * 滑动操作 - 支持坐标点
-     */
-    swipe(swipeData) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const startTime = Date.now();
-            const result = yield this.withRetry(() => __awaiter(this, void 0, void 0, function* () {
-                try {
-                    const from = { x: swipeData.fromX, y: swipeData.fromY };
-                    const to = { x: swipeData.toX, y: swipeData.toY };
-                    const action = {
-                        title: `滑动操作: ${from.x},${from.y} → ${to.x},${to.y}`,
-                        actions: [{
-                                type: "swipe",
-                                from,
-                                to,
-                                options: {
-                                    durationMs: swipeData.duration || 800,
-                                    waitAfterMs: swipeData.wait || 500
-                                }
-                            }]
-                    };
-                    yield this.client.executeAction(action);
-                    return {
-                        success: true,
-                        data: { from, to, duration: swipeData.duration },
-                        duration: Date.now() - startTime
-                    };
-                }
-                catch (error) {
-                    throw new Error(`滑动操作失败: ${error instanceof Error ? error.message : String(error)}`);
+     * Execute multiple actions in sequence
+     *
+     * @param actions - Array of actions to execute
+     * @returns Promise resolving to ExecuteActionsResult
+     *
+     * @example
+     * ```typescript
+     * const result = await shellx.executeActions([
+     *   { text: 'Settings' },
+     *   { text: 'Accounts' },
+     *   { cmd: 'ls -la' }
+     * ]);
+     *
+     * console.log(`Success: ${result.successCount}, Failed: ${result.failureCount}`);
+     * result.results.forEach((res, index) => {
+     *   console.log(`Action ${index + 1}: ${res.success ? 'Success' : 'Failed'}`);
+     * });
+     * ```
+     */
+    async executeActions(actions) {
+        await this.ensureConnectionReady();
+        const startTime = Date.now();
+        const results = [];
+        let successCount = 0;
+        let failureCount = 0;
+        for (const [index, action] of actions.entries()) {
+            try {
+                this.logger.info(`🔨 Executing action ${index + 1}/${actions.length}`);
+                let result;
+                // Check for clipboard first (before click/input which also have text)
+                if ("get" in action || "paste" in action) {
+                    result = await this.clipboard(action);
                 }
-            }), { retry: swipeData.retry, delay: 500 });
-            if (!result) {
-                return {
-                    success: false,
-                    error: '滑动操作失败',
-                    duration: Date.now() - startTime
-                };
-            }
-            return result;
-        });
-    }
-    /**
-     * 按键操作
-     */
-    pressKey(keyData) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const startTime = Date.now();
-            const result = yield this.withRetry(() => __awaiter(this, void 0, void 0, function* () {
-                try {
-                    const action = {
-                        title: `按键操作: ${keyData.key}${keyData.longPress ? ' (长按)' : ''}`,
-                        actions: [{
-                                type: "key",
-                                keyCode: keyData.key,
-                                options: {
-                                    longPress: keyData.longPress || false
-                                }
-                            }]
-                    };
-                    yield this.client.executeAction(action);
-                    if (keyData.wait) {
-                        yield new Promise(resolve => setTimeout(resolve, keyData.wait));
-                    }
-                    return {
-                        success: true,
-                        data: { key: keyData.key, longPress: keyData.longPress },
-                        duration: Date.now() - startTime
-                    };
+                else if ("text" in action && ("elementId" in action || "resourceId" in action)) {
+                    result = await this.input(action);
                 }
-                catch (error) {
-                    throw new Error(`按键操作失败: ${error instanceof Error ? error.message : String(error)}`);
+                else if ("elementId" in action ||
+                    "resourceId" in action ||
+                    "class" in action ||
+                    "x" in action ||
+                    "y" in action) {
+                    result = await this.click(action);
                 }
-            }), { retry: keyData.retry, delay: 500 });
-            if (!result) {
-                return {
-                    success: false,
-                    error: '按键操作失败',
-                    duration: Date.now() - startTime
-                };
-            }
-            return result;
-        });
-    }
-    /**
-     * 等待操作 - 等待元素出现或消失
-     */
-    wait(waitData) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const startTime = Date.now();
-            const result = yield this.withRetry(() => __awaiter(this, void 0, void 0, function* () {
-                try {
-                    const selector = this.convertSelector(waitData);
-                    const timeout = waitData.timeout || 10000;
-                    const interval = 500;
-                    const maxAttempts = Math.floor(timeout / interval);
-                    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-                        try {
-                            const result = yield this.client.findElement(selector, {
-                                timeout: interval,
-                                maxResults: 1,
-                                visibleOnly: waitData.condition === 'visible',
-                                clickableOnly: waitData.condition === 'clickable'
-                            });
-                            // 如果服务器返回失败，跳过本次尝试
-                            if (!result || result.success === false) {
-                                yield new Promise(resolve => setTimeout(resolve, interval));
-                                continue;
-                            }
-                            if (result.elements && result.elements.length > 0) {
-                                if (waitData.condition === 'gone') {
-                                    // 等待元素消失，继续等待
-                                    yield new Promise(resolve => setTimeout(resolve, interval));
-                                    continue;
-                                }
-                                else {
-                                    // 等待元素出现，已找到
-                                    return {
-                                        success: true,
-                                        data: { element: this.convertElement(result.elements[0]) },
-                                        duration: Date.now() - startTime
-                                    };
-                                }
-                            }
-                            else if (waitData.condition === 'gone') {
-                                // 等待元素消失，已消失
-                                return {
-                                    success: true,
-                                    data: { element: null },
-                                    duration: Date.now() - startTime
-                                };
-                            }
-                        }
-                        catch (error) {
-                            // 查找失败，继续等待
-                        }
-                        yield new Promise(resolve => setTimeout(resolve, interval));
-                    }
-                    throw new Error(`等待超时: ${waitData.condition || 'visible'}`);
+                else if ("fromX" in action && "fromY" in action && "toX" in action && "toY" in action) {
+                    result = await this.swipe(action);
                 }
-                catch (error) {
-                    throw new Error(`等待操作失败: ${error instanceof Error ? error.message : String(error)}`);
+                else if ("key" in action) {
+                    result = await this.press(action);
                 }
-            }), { retry: waitData.retry, delay: 500 });
-            if (!result) {
-                return {
-                    success: false,
-                    error: '等待操作失败',
-                    duration: Date.now() - startTime
-                };
-            }
-            return result;
-        });
-    }
-    /**
-     * 查找操作 - 查找元素
-     */
-    find(findData) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const result = yield this.withRetry(() => __awaiter(this, void 0, void 0, function* () {
-                try {
-                    const selector = this.convertSelector(findData);
-                    const result = yield this.client.findElement(selector, {
-                        pressClick: findData.pressClick,
-                        waitAfterMs: findData.waitAfterMs || 5000,
-                        maxResults: findData.maxResults || 1000,
-                        visibleOnly: true,
-                        clickableOnly: false,
-                        multiple: findData.multiple || false
-                    });
-                    // 检查服务器是否返回了失败响应
-                    if (!result || result.success === false) {
-                        throw new Error((result === null || result === void 0 ? void 0 : result.errorMessage) || '查找元素失败');
-                    }
-                    if (!result.elements) {
-                        throw new Error('未找到元素');
-                    }
-                    const elements = result.elements.map(element => this.convertElement(element));
-                    return {
-                        elements,
-                        count: elements.length,
-                        success: true,
-                        found: result.found,
-                    };
+                else if ("condition" in action &&
+                    ("elementId" in action || "resourceId" in action || "text" in action || "class" in action)) {
+                    result = await this.wait(action);
                 }
-                catch (error) {
-                    throw new Error(`查找操作失败: ${error instanceof Error ? error.message : String(error)}`);
+                else if ("multiple" in action &&
+                    ("elementId" in action || "resourceId" in action || "text" in action || "class" in action)) {
+                    result = await this.find(action);
                 }
-            }), { retry: findData.retry, delay: 500 });
-            if (!result) {
-                return {
-                    elements: [],
-                    count: 0,
-                    success: false,
-                    found: false
-                };
-            }
-            return result;
-        });
-    }
-    /**
-     * 执行命令 - 兼容现有的 shell 命令执行
-     */
-    executeCommand(commandData) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const result = yield this.withRetry(() => __awaiter(this, void 0, void 0, function* () {
-                try {
-                    const result = yield this.executeShellCommand(commandData.cmd, {
-                        title: `执行命令: ${commandData.cmd}`,
-                        timeout: commandData.timeout,
-                        waitAfterMs: commandData.wait
-                    });
-                    return result;
+                else if ("cmd" in action) {
+                    result = await this.command(action);
                 }
-                catch (error) {
-                    throw new Error(`命令执行失败: ${error instanceof Error ? error.message : String(error)}`);
+                else if ("package" in action) {
+                    result = await this.getAppInfo(action);
                 }
-            }), { retry: commandData.retry, delay: 1000 });
-            if (!result) {
-                return {
-                    success: false,
-                    output: '',
-                    error: '命令执行失败',
-                    duration: 0
-                };
-            }
-            return result;
-        });
-    }
-    executeCodeEval(context, code, timeout) {
-        const evalInstance = require('eval');
-        return evalInstance(code, context, true);
-    }
-    executeCode(agentCode, context, timeout) {
-        return __awaiter(this, void 0, void 0, function* () {
-            // console.log('executeCode', agentCode);
-            // Interpreter.global = context;
-            // const evalFunc = getEvalInstance(context);
-            // 如果没有指定 timeout，直接执行
-            if (!timeout) {
-                return yield this.executeCodeEval(context, agentCode);
-            }
-            // 使用 timeout 执行 - 修复：await 应该在 Promise.race 上，而不是在内部的 promise 上
-            return yield Promise.race([
-                this.executeCodeEval(context, agentCode),
-                new Promise((_, reject) => setTimeout(() => reject(new Error(`代码执行超时: ${timeout}ms`)), timeout))
-            ]);
-        });
-    }
-    /**
-     * 获取应用信息
-     */
-    getAppInfo(appInfoData) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const startTime = Date.now();
-            const result = yield this.withRetry(() => __awaiter(this, void 0, void 0, function* () {
-                try {
-                    const action = {
-                        title: `获取应用信息: ${appInfoData.package}`,
-                        actions: [{
-                                type: "get_app_info",
-                                packageName: appInfoData.package
-                            }]
-                    };
-                    yield this.client.executeAction(action);
-                    return {
-                        success: true,
-                        data: { package: appInfoData.package },
-                        duration: Date.now() - startTime
-                    };
+                else if ("text" in action) {
+                    // Text-only action (without elementId/resourceId) is for clipboard
+                    result = await this.clipboard(action);
                 }
-                catch (error) {
-                    throw new Error(`获取应用信息失败: ${error instanceof Error ? error.message : String(error)}`);
+                else {
+                    result = await this.takeScreenshot(action);
                 }
-            }), { retry: appInfoData.retry, delay: 500 });
-            if (!result) {
-                return {
-                    success: false,
-                    error: '获取应用信息失败',
-                    duration: Date.now() - startTime
-                };
-            }
-            return result;
-        });
-    }
-    /**
-     * 截图操作
-     */
-    takeScreenshot() {
-        return __awaiter(this, arguments, void 0, function* (screenshotData = {}) {
-            const startTime = Date.now();
-            const result = yield this.withRetry(() => __awaiter(this, void 0, void 0, function* () {
-                try {
-                    const options = {
-                        format: screenshotData.format || 'png',
-                        quality: screenshotData.quality,
-                        scale: 0.10,
-                    };
-                    if (screenshotData.regionX !== undefined && screenshotData.regionY !== undefined &&
-                        screenshotData.regionWidth !== undefined && screenshotData.regionHeight !== undefined) {
-                        options.region = {
-                            left: screenshotData.regionX,
-                            top: screenshotData.regionY,
-                            width: screenshotData.regionWidth,
-                            height: screenshotData.regionHeight
-                        };
-                    }
-                    const screenshot = yield this.client.screenShot(options);
-                    // 检查服务器是否返回了失败响应
-                    if (!screenshot || screenshot.success === false) {
-                        throw new Error((screenshot === null || screenshot === void 0 ? void 0 : screenshot.errorMessage) || '截图失败');
-                    }
-                    return {
-                        success: true,
-                        data: screenshot,
-                        duration: Date.now() - startTime
-                    };
+                results.push(result);
+                if (!result.success) {
+                    failureCount++;
+                    this.logger.warn(`⚠️ Action ${index + 1} failed: ${result.error}`);
                 }
-                catch (error) {
-                    throw new Error(`截图操作失败: ${error instanceof Error ? error.message : String(error)}`);
+                else {
+                    successCount++;
+                    this.logger.info(`✅ Action ${index + 1} succeeded`);
                 }
-            }), { retry: screenshotData.retry, delay: 500 });
-            if (!result) {
-                return {
+            }
+            catch (error) {
+                const errorResult = {
                     success: false,
-                    error: '截图操作失败',
-                    duration: Date.now() - startTime
+                    error: error instanceof Error ? error.message : String(error),
+                    duration: 0,
+                    timestamp: Date.now(),
                 };
+                results.push(errorResult);
+                failureCount++;
+                this.logger.error(`❌ Action ${index + 1} failed:`, error);
             }
-            return result;
-        });
-    }
-    /**
-     * 执行操作序列 - 支持多个操作连续执行
-     */
-    executeActions(actions) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const results = [];
-            for (const [index, action] of actions.entries()) {
-                try {
-                    console.log(`🔨 [Actions] 执行第 ${index + 1}/${actions.length} 个操作`);
-                    let result;
-                    if ('text' in action && ('targetElementId' in action || 'targetResourceId' in action || 'targetText' in action || 'targetClass' in action)) {
-                        result = yield this.input(action);
-                    }
-                    else if ('targetElementId' in action || 'targetResourceId' in action || 'targetText' in action || 'targetClass' in action || 'targetX' in action || 'targetY' in action) {
-                        result = yield this.click(action);
-                    }
-                    else if ('fromX' in action && 'fromY' in action && 'toX' in action && 'toY' in action) {
-                        result = yield this.swipe(action);
-                    }
-                    else if ('key' in action) {
-                        result = yield this.pressKey(action);
-                    }
-                    else if ('condition' in action && ('targetElementId' in action || 'targetResourceId' in action || 'targetText' in action || 'targetClass' in action)) {
-                        result = yield this.wait(action);
-                    }
-                    else if ('multiple' in action && ('targetElementId' in action || 'targetResourceId' in action || 'targetText' in action || 'targetClass' in action)) {
-                        const findResult = yield this.find(action);
-                        result = {
-                            success: findResult.success,
-                            data: findResult,
-                            duration: 0
-                        };
-                    }
-                    else if ('cmd' in action) {
-                        const cmdResult = yield this.executeCommand(action);
-                        result = {
-                            success: cmdResult.success,
-                            data: cmdResult,
-                            duration: cmdResult.duration
-                        };
-                    }
-                    else if ('package' in action) {
-                        result = yield this.getAppInfo(action);
-                    }
-                    else {
-                        result = yield this.takeScreenshot(action);
-                    }
-                    results.push(result);
-                    // 记录操作结果但不抛出错误，让调用者决定如何处理失败的操作
-                    if (!result.success) {
-                        console.warn(`⚠️ [Actions] 第 ${index + 1} 个操作失败: ${result.error}`);
-                    }
-                    else {
-                        console.log(`✅ [Actions] 第 ${index + 1} 个操作执行成功`);
-                    }
-                }
-                catch (error) {
-                    const errorResult = {
-                        success: false,
-                        error: error instanceof Error ? error.message : String(error),
-                        duration: 0
-                    };
-                    results.push(errorResult);
-                    console.error(`❌ [Actions] 第 ${index + 1} 个操作执行失败:`, error);
-                    // 不再抛出错误，继续执行后续操作
-                }
-            }
-            return results;
-        });
-    }
-    /**
-     * Smart element finder with retry logic
-     */
-    findElementWithRetry(selector_1) {
-        return __awaiter(this, arguments, void 0, function* (selector, maxRetries = 3, retryDelay = 1000) {
-            for (let i = 0; i < maxRetries; i++) {
-                try {
-                    const result = yield this.client.findElement(selector, {
-                        timeout: 3000,
-                        visibleOnly: true,
-                        maxResults: 1
-                    });
-                    if (result.elements.length > 0) {
-                        return result.elements[0];
-                    }
-                }
-                catch (error) {
-                    console.log(`查找尝试 ${i + 1}/${maxRetries} 失败:`, error);
-                }
-                if (i < maxRetries - 1) {
-                    yield new Promise(resolve => setTimeout(resolve, retryDelay));
-                }
-            }
-            return null;
-        });
-    }
-    /**
-     * Smart multiple elements finder with retry logic
-     */
-    findElementsWithRetry(selector_1) {
-        return __awaiter(this, arguments, void 0, function* (selector, maxRetries = 3, retryDelay = 1000, options) {
-            var _a, _b, _c;
-            for (let i = 0; i < maxRetries; i++) {
-                try {
-                    const result = yield this.client.findElement(selector, {
-                        timeout: 3000,
-                        visibleOnly: (_a = options === null || options === void 0 ? void 0 : options.visibleOnly) !== null && _a !== void 0 ? _a : true,
-                        clickableOnly: (_b = options === null || options === void 0 ? void 0 : options.clickableOnly) !== null && _b !== void 0 ? _b : false,
-                        multiple: true,
-                        maxResults: (_c = options === null || options === void 0 ? void 0 : options.maxResults) !== null && _c !== void 0 ? _c : 10
-                    });
-                    if (result.elements.length > 0) {
-                        console.log(`🔍 [FindElements] 找到 ${result.elements.length} 个元素`);
-                        return result.elements;
-                    }
-                }
-                catch (error) {
-                    console.log(`查找尝试 ${i + 1}/${maxRetries} 失败:`, error);
-                }
-                if (i < maxRetries - 1) {
-                    yield new Promise(resolve => setTimeout(resolve, retryDelay));
-                }
-            }
-            console.log(`❌ [FindElements] 未找到任何元素`);
-            return [];
-        });
-    }
-    /**
-     * 打印元素信息的工具方法
-     */
-    printElementInfo(element, index) {
-        const prefix = index !== undefined ? `📋 元素 ${index + 1}:` : `📋 元素信息:`;
-        console.log(`\n${prefix}`);
-        console.log(`  - Element ID: ${element.elementId}`);
-        console.log(`  - Class Name: ${element.className}`);
-        console.log(`  - Resource ID: ${element.resourceId}`);
-        console.log(`  - Text: "${element.text}"`);
-        console.log(`  - Describe: "${element.describe}"`);
-        console.log(`  - Visible: ${element.visible}`);
-        console.log(`  - Clickable: ${element.clickable}`);
-        console.log(`  - Bounds: {left: ${element.bounds.left}, top: ${element.bounds.top}, right: ${element.bounds.right}, bottom: ${element.bounds.bottom}}`);
-        console.log(`  - Size: ${element.bounds.right - element.bounds.left} x ${element.bounds.bottom - element.bounds.top}`);
-    }
-    /**
-     * 打印多个元素信息的工具方法
-     */
-    printElementsInfo(elements, title) {
-        if (elements.length === 0) {
-            console.log('❌ 没有元素可以打印');
-            return;
         }
-        console.log(`\n${title || `✅ 找到 ${elements.length} 个元素`}:`);
-        /*
-            elements.forEach((element, index) => {
-              this.printElementInfo(element, index);
-            });*/
-        // 统计信息
-        const visibleCount = elements.filter(e => e.visible).length;
-        const clickableCount = elements.filter(e => e.clickable).length;
-        const withTextCount = elements.filter(e => e.text && e.text.trim().length > 0).length;
-        console.log(`\n📊 统计信息:`);
-        console.log(`  - 总共元素: ${elements.length}`);
-        console.log(`  - 可见元素: ${visibleCount}`);
-        console.log(`  - 可点击元素: ${clickableCount}`);
-        console.log(`  - 有文本内容元素: ${withTextCount}`);
-        // 展示不同的文本内容
-        const uniqueTexts = [...new Set(elements.map(e => e.text).filter(text => text && text.trim().length > 0))];
-        if (uniqueTexts.length > 0) {
-            console.log(`\n📝 不同的文本内容:`);
-            uniqueTexts.forEach((text, index) => {
-                console.log(`  ${index + 1}. "${text}"`);
-            });
-        }
-    }
-    /**
-     * Click element by text content
-     */
-    clickByText(text_1) {
-        return __awaiter(this, arguments, void 0, function* (text, exact = false) {
-            const selector = exact
-                ? { text, clickable: false, visible: true }
-                : { textContains: text, clickable: false, visible: true };
-            const element = yield this.findElementWithRetry(selector);
-            if (!element) {
-                return false;
-            }
-            const clickAction = {
-                title: `点击文本: ${text}`,
-                actions: [{
-                        type: "click",
-                        target: { type: "elementId", value: element.elementId },
-                        options: { waitAfterMs: 2000 }
-                    }]
-            };
-            yield this.client.executeAction(clickAction);
-            return true;
-        });
-    }
-    /**
-     * Input text into field
-     */
-    inputText(selector, text, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
-            const element = yield this.findElementWithRetry(selector);
-            if (!element) {
-                return false;
-            }
-            const inputAction = {
-                title: `输入文本: ${text}`,
-                actions: [{
-                        type: "input",
-                        text,
-                        target: { type: "elementId", value: element.elementId },
-                        options: {
-                            replaceExisting: (_a = options === null || options === void 0 ? void 0 : options.clear) !== null && _a !== void 0 ? _a : true,
-                            hideKeyboardAfter: (_b = options === null || options === void 0 ? void 0 : options.hideKeyboard) !== null && _b !== void 0 ? _b : false
-                        }
-                    }]
-            };
-            yield this.client.executeAction(inputAction);
-            return true;
-        });
+        return {
+            results,
+            successCount,
+            failureCount,
+            totalDuration: Date.now() - startTime,
+        };
     }
-    /**
-     * Take screenshot and save info
-     */
-    captureScreen(options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const screenshot = yield this.client.screenShot(options);
-            if (options === null || options === void 0 ? void 0 : options.saveInfo) {
-                console.log('截图信息:', {
-                    格式: screenshot.format,
-                    尺寸: screenshot.dimensions,
-                    大小: `${Math.round(screenshot.imageData.length / 1024)}KB`,
-                    时间: new Date(Number(screenshot.timestamp)).toLocaleString()
-                });
-            }
-            return screenshot;
+    // ==================== Element Finder Methods ====================
+    /**
+     * Find a single element with retry logic
+     *
+     * @param selector - Element selector
+     * @param maxRetries - Maximum retry attempts (default: 3)
+     * @param retryDelay - Delay between retries in milliseconds (default: 1000)
+     * @returns Promise resolving to UIElement or null
+     *
+     * @example
+     * ```typescript
+     * const element = await shellx.findElement(
+     *   { text: 'Submit', visible: true },
+     *   3,
+     *   1000
+     * );
+     * ```
+     */
+    async findElementWithRetry(selector, maxRetries = 3, retryDelay = 1000) {
+        return this.elementFinder.findElement(selector, { maxRetries, retryDelay });
+    }
+    /**
+     * Find multiple elements with retry logic
+     *
+     * @param selector - Element selector
+     * @param maxRetries - Maximum retry attempts (default: 3)
+     * @param retryDelay - Delay between retries in milliseconds (default: 1000)
+     * @param options - Additional find options
+     * @returns Promise resolving to array of UIElements
+     *
+     * @example
+     * ```typescript
+     * const elements = await shellx.findElementsWithRetry(
+     *   { className: 'Button', visible: true },
+     *   3,
+     *   1000,
+     *   { maxResults: 10 }
+     * );
+     * ```
+     */
+    async findElementsWithRetry(selector, maxRetries = 3, retryDelay = 1000, options) {
+        return this.elementFinder.findElements(selector, {
+            maxRetries,
+            retryDelay,
+            ...options,
         });
     }
     /**
      * Wait for any of multiple elements to appear
+     * @deprecated Use waitAnyElement() instead for consistency
      */
-    waitForAnyElement(selectors_1) {
-        return __awaiter(this, arguments, void 0, function* (selectors, timeout = 10000) {
-            const startTime = Date.now();
-            while (Date.now() - startTime < timeout) {
-                for (let i = 0; i < selectors.length; i++) {
-                    try {
-                        const result = yield this.client.findElement(selectors[i], {
-                            timeout: 1000,
-                            maxResults: 1,
-                            visibleOnly: true
-                        });
-                        if (result.elements.length > 0) {
-                            return { element: result.elements[0], selectorIndex: i };
-                        }
-                    }
-                    catch (error) {
-                        // Continue to next selector
-                    }
-                }
-                yield new Promise(resolve => setTimeout(resolve, 500));
-            }
-            return null;
-        });
-    }
-    /**
-     * Navigate through app using a series of clicks
-     */
-    navigateByPath(textPath) {
-        return __awaiter(this, void 0, void 0, function* () {
-            try {
-                console.log('开始导航路径:', textPath.join(' → '));
-                for (const [index, text] of textPath.entries()) {
-                    console.log(`导航步骤 ${index + 1}/${textPath.length}: 点击 "${text}"`);
-                    yield this.clickByText(text);
-                    // Wait a bit between clicks
-                    yield new Promise(resolve => setTimeout(resolve, 1000));
-                }
-                console.log('✅ 导航完成');
-                return true;
-            }
-            catch (error) {
-                console.error('❌ 导航失败:', error);
-                return false;
-            }
-        });
-    }
-    /**
-     * Scroll to find element
-     */
-    scrollToFindElement(selector_1) {
-        return __awaiter(this, arguments, void 0, function* (selector, maxScrolls = 5, direction = 'down') {
-            // First try to find without scrolling
-            let element = yield this.findElementWithRetry(selector, 1, 0);
-            if (element)
-                return element;
-            // Try scrolling to find
-            for (let i = 0; i < maxScrolls; i++) {
-                console.log(`滚动查找第 ${i + 1} 次...`);
-                // 获取屏幕信息来计算坐标
-                const screenInfo = yield this.client.getScreenInfo();
-                const centerX = (screenInfo.width || 1080) / 2;
-                const centerY = (screenInfo.height || 1920) / 2;
-                let from, to;
-                const distance = 400;
-                if (direction === 'up') {
-                    from = { x: centerX, y: centerY + distance / 2 };
-                    to = { x: centerX, y: centerY - distance / 2 };
-                }
-                else if (direction === 'down') {
-                    from = { x: centerX, y: centerY - distance / 2 };
-                    to = { x: centerX, y: centerY + distance / 2 };
-                }
-                else if (direction === 'left') {
-                    from = { x: centerX + distance / 2, y: centerY };
-                    to = { x: centerX - distance / 2, y: centerY };
-                }
-                else {
-                    from = { x: centerX - distance / 2, y: centerY };
-                    to = { x: centerX + distance / 2, y: centerY };
-                }
-                yield this.swipe({
-                    fromX: from.x,
-                    fromY: from.y,
-                    toX: to.x,
-                    toY: to.y,
-                    duration: 800
-                });
-                element = yield this.findElementWithRetry(selector, 1, 0);
-                if (element) {
-                    console.log('✅ 滚动后找到元素');
-                    return element;
-                }
-            }
-            console.log('❌ 滚动后仍未找到元素');
-            return null;
-        });
-    }
-    /**
-     * Execute shell command action with output monitoring
-     */
-    executeShellCommand(command_1) {
-        return __awaiter(this, arguments, void 0, function* (command, options = {}) {
-            const startTime = Date.now();
-            const title = options.title || `执行命令: ${command}`;
-            const timeout = options.timeout || 20000; // 增加默认超时时间到20秒
-            console.log(`🔨 [Shell] ${title}`);
-            console.log(`⏱️  超时时间: ${timeout}ms`);
-            return new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
-                const commandKey = (0, uuid_1.v4)();
-                console.log(`🔑 [Shell] 生成命令键: ${commandKey}`);
-                // 注册命令 Promise
-                this.shellCommandPromises.set(commandKey, {
-                    resolve,
-                    reject,
-                    startTime,
-                    options,
-                    output: '',
-                    sessionOutputs: new Map(),
-                    command
-                });
-                console.log(`📋 [Shell] 当前待处理命令数: ${this.shellCommandPromises.size}`);
-                // 设置超时
-                const timeoutId = setTimeout(() => {
-                    if (this.shellCommandPromises.has(commandKey)) {
-                        console.log(`✅ [Shell] 命令  ${command} 执行完成`);
-                        const commandPromise = this.shellCommandPromises.get(commandKey);
-                        this.shellCommandPromises.delete(commandKey);
-                        resolve({
-                            success: true,
-                            output: commandPromise ? commandPromise.output.trim() : "",
-                            duration: Date.now() - startTime
-                        });
-                    }
-                }, timeout);
-                try {
-                    const shellAction = {
-                        title,
-                        actions: [{
-                                type: "command",
-                                command,
-                                title: options.title
-                            }],
-                        options: {
-                            timeoutMs: timeout
-                        }
-                    };
-                    // 发送命令
-                    yield this.client.sendMessageWithTaskId({ actions: shellAction }, 'command', commandKey, timeout);
-                    console.log(`📤 [Shell] 命令已发送: ${commandKey}`);
-                }
-                catch (error) {
-                    clearTimeout(timeoutId);
-                    this.shellCommandPromises.delete(commandKey);
-                    console.error(`❌ [Shell] 命令发送失败: ${command}`, error);
-                    reject(error);
-                }
-            }));
-        });
+    async waitForAnyElement(selectors, timeout = 10000) {
+        return this.waitAnyElement(selectors, timeout);
     }
     /**
-     * Execute shell command with simple output (for backward compatibility)
-     */
-    executeSimpleShellCommand(command, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            try {
-                const result = yield this.executeShellCommand(command, {
-                    title: options === null || options === void 0 ? void 0 : options.title,
-                    timeout: options === null || options === void 0 ? void 0 : options.timeout
-                });
-                // 如果设置了等待时间，则等待
-                if (options === null || options === void 0 ? void 0 : options.waitAfterMs) {
-                    yield new Promise(resolve => setTimeout(resolve, options.waitAfterMs));
-                }
-                console.log(`✅ [Shell] 命令执行完成: ${command}`);
-                return result;
-            }
-            catch (error) {
-                console.error(`❌ [Shell] 命令执行失败: ${command}`, error);
-                throw error;
-            }
-        });
-    }
-    /**
-     * Execute multiple shell commands in sequence
-     */
-    executeShellCommands(commands, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const results = [];
-            try {
-                console.log(`🔨 [Shell] 开始执行 ${commands.length} 个命令`);
-                for (const [index, cmd] of commands.entries()) {
-                    try {
-                        const title = cmd.title || `命令 ${index + 1}/${commands.length}: ${cmd.command}`;
-                        console.log(`🔨 [Shell] ${title}`);
-                        const result = yield this.executeShellCommand(cmd.command, {
-                            title,
-                            timeout: options === null || options === void 0 ? void 0 : options.timeout,
-                            waitAfterMs: cmd.waitAfterMs
-                        });
-                        results.push(result);
-                    }
-                    catch (error) {
-                        console.error(`❌ [Shell] 命令 ${index + 1} 执行失败:`, error);
-                        if (options === null || options === void 0 ? void 0 : options.continueOnError) {
-                            results.push({
-                                success: false,
-                                output: '',
-                                error: error instanceof Error ? error.message : String(error),
-                                duration: Date.now() - Date.now() // 简单的时间戳
-                            });
-                            continue;
-                        }
-                        else {
-                            throw error;
-                        }
-                    }
-                }
-                console.log(`✅ [Shell] 所有命令执行完成`);
-                return results;
-            }
-            catch (error) {
-                console.error(`❌ [Shell] 批量命令执行失败:`, error);
-                throw error;
-            }
-        });
-    }
-    /**
-     * Common ADB commands helper
-     */
-    adbCommand(command, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const adbCmd = command;
-            return this.executeShellCommand(adbCmd, {
-                title: (options === null || options === void 0 ? void 0 : options.title) || `ADB命令: ${command}`,
-                timeout: options === null || options === void 0 ? void 0 : options.timeout,
-                waitAfterMs: options === null || options === void 0 ? void 0 : options.waitAfterMs,
-                onOutput: options === null || options === void 0 ? void 0 : options.onOutput,
-                onError: options === null || options === void 0 ? void 0 : options.onError,
-                expectedOutput: options === null || options === void 0 ? void 0 : options.expectedOutput,
-                successPattern: options === null || options === void 0 ? void 0 : options.successPattern,
+     * Wait for any of multiple elements to appear
+     *
+     * @param selectors - Array of element selectors
+     * @param timeout - Maximum wait time in milliseconds (default: 10000)
+     * @returns Promise resolving to the first found element and its index, or null
+     *
+     * @example
+     * ```typescript
+     * const result = await shellx.waitAnyElement(
+     *   [
+     *     { text: 'Submit' },
+     *     { text: 'OK' },
+     *     { text: 'Confirm' }
+     *   ],
+     *   10000
+     * );
+     * ```
+     */
+    async waitAnyElement(selectors, timeout = 10000) {
+        return this.elementFinder.waitAnyElement(selectors, timeout);
+    }
+    /**
+     * Scroll to find an element
+     *
+     * @param selector - Element selector
+     * @param maxScrolls - Maximum scroll attempts (default: 5)
+     * @param direction - Scroll direction (default: 'down')
+     * @returns Promise resolving to UIElement or null
+     *
+     * @example
+     * ```typescript
+     * const element = await shellx.scrollToFindElement(
+     *   { text: 'Target' },
+     *   5,
+     *   'down'
+     * );
+     * ```
+     */
+    async scrollToFindElement(selector, maxScrolls = 5, direction = "down") {
+        return this.elementFinder.scrollToFindElement(selector, async (from, to) => {
+            await this.swipe({
+                fromX: from.x,
+                fromY: from.y,
+                toX: to.x,
+                toY: to.y,
+                duration: 800,
             });
-        });
-    }
-    /**
-     * Device info commands
+        }, { maxScrolls, direction });
+    }
+    // ==================== Shell Command Methods ====================
+    /**
+     * Handle shell output from WebSocket messages
+     *
+     * This method should be called in the WebSocket message handler.
+     *
+     * @param chunks - Shell output chunks
+     *
+     * @example
+     * ```typescript
+     * const client = new ConnectionClient(deviceId, {
+     *   onMessage: (message) => {
+     *     if (message.chunks) {
+     *       shellx.handleShellOutput(message.chunks);
+     *     }
+     *   }
+     * });
+     * ```
      */
-    getDeviceInfo() {
-        return __awaiter(this, void 0, void 0, function* () {
-            const commands = [
-                { command: 'getprop ro.product.model', title: '获取设备型号' },
-                { command: 'getprop ro.build.version.release', title: '获取Android版本' },
-                { command: 'wm size', title: '获取屏幕尺寸' },
-                { command: 'dumpsys battery', title: '获取电池信息' }
-            ];
-            console.log('📱 [Device] 开始获取设备信息...');
-            try {
-                const results = yield this.executeShellCommands(commands, {
-                    continueOnError: true,
-                    timeout: 5000
-                });
-                console.log('📱 [Device] 设备信息获取完成');
-                return results;
-            }
-            catch (error) {
-                console.error('❌ [Device] 获取设备信息失败:', error);
-                throw error;
-            }
-        });
-    }
-    /**
-     * Execute key action (press a key)
-     */
-    executeKeyAction(keyCode_1) {
-        return __awaiter(this, arguments, void 0, function* (keyCode, options = {}) {
-            try {
-                console.log(`🔑 [Key] 执行按键操作: ${keyCode}${options.longPress ? ' (长按)' : ''}`);
-                const keyAction = {
-                    title: `按键: ${keyCode}${options.longPress ? ' (长按)' : ''}`,
-                    actions: [{
-                            type: "key",
-                            keyCode,
-                            options: {
-                                longPress: options.longPress
-                            }
-                        }]
-                };
-                yield this.client.executeAction(keyAction);
-                // 如果设置了等待时间，则等待
-                if (options.waitAfterMs) {
-                    yield new Promise(resolve => setTimeout(resolve, options.waitAfterMs));
-                }
-                console.log(`✅ [Key] 按键操作完成: ${keyCode}`);
-                return true;
-            }
-            catch (error) {
-                console.error(`❌ [Key] 按键操作失败: ${keyCode}`, error);
-                return false;
+    handleShellOutput(chunks) {
+        this.shellCommandExecutor.handleShellOutput(chunks);
+    }
+    /**
+     * Send raw WebSocket message (for advanced use cases)
+     *
+     * This method allows you to send raw WebSocket protocol messages directly,
+     * bypassing the high-level ShellX API. This is useful for:
+     * - Custom protocol operations not exposed by ShellX
+     * - Testing and debugging
+     * - Advanced integrations requiring low-level control
+     *
+     * @param message - Raw WebSocket client message (WsClient type)
+     * @returns Promise resolving to the server response
+     *
+     * @example
+     * ```typescript
+     * // Send a custom find element request
+     * await shellx.sendRawMessage({
+     *   findElement: {
+     *     type: 'find',
+     *     selector: { text: 'Submit' },
+     *     options: { maxResults: 10 }
+     *   }
+     * });
+     *
+     * // Send a custom action sequence
+     * await shellx.sendRawMessage({
+     *   actions: [
+     *     { action: 'Launch', app: 'com.example.app' },
+     *     { action: 'Tap', element: [500, 1000] }
+     *   ]
+     * });
+     *
+     * // Send screen info request
+     * await shellx.sendRawMessage({
+     *   screenInfo: { keepScreenOn: true, wakeApp: true }
+     * });
+     * ```
+     */
+    async sendRawMessage(message) {
+        await this.ensureConnectionReady();
+        return this.client.sendRawMessage(message);
+    }
+    /**
+     * Start ASR (Automatic Speech Recognition)
+     * @returns Promise that resolves when speech recognition has started
+     *
+     * @example
+     * ```typescript
+     * await shellx.startSpeechRecognition();
+     * console.log('Speech recognition started');
+     * ```
+     */
+    async startSpeechRecognition() {
+        await this.ensureConnectionReady();
+        return this.client.startAsr();
+    }
+    /**
+     * Stop ASR (Automatic Speech Recognition)
+     * @returns Promise that resolves when speech recognition has stopped
+     *
+     * @example
+     * ```typescript
+     * await shellx.stopSpeechRecognition();
+     * console.log('Speech recognition stopped');
+     * ```
+     */
+    async stopSpeechRecognition() {
+        await this.ensureConnectionReady();
+        return this.client.stopAsr();
+    }
+    /**
+     * Speak text aloud using TTS (Text-to-Speech)
+     * @param text - The text to speak
+     * @returns Promise that resolves when TTS has started speaking
+     *
+     * @example
+     * ```typescript
+     * await shellx.speak('Hello, world!');
+     * ```
+     */
+    async speak(text) {
+        await this.ensureConnectionReady();
+        return this.client.speak(text);
+    }
+    /**
+     * Stop TTS (Text-to-Speech)
+     * @returns Promise that resolves when TTS has stopped speaking
+     *
+     * @example
+     * ```typescript
+     * await shellx.stopSpeaking();
+     * ```
+     */
+    async stopSpeaking() {
+        await this.ensureConnectionReady();
+        return this.client.stopTts();
+    }
+    /**
+     * Static factory method to create shell output handler
+     * @deprecated This method is kept for backward compatibility but is no longer needed
+     * @param shellx - The ShellX instance
+     * @returns Message handler function
+     *
+     * @example
+     * ```typescript
+     * const shellx = new ShellX({ deviceId: 'device-id' });
+     * const handler = ShellX.createShellOutputHandler(shellx);
+     * ```
+     */
+    static createShellOutputHandler(shellx) {
+        return (message) => {
+            if (message.chunks) {
+                shellx.handleShellOutput(message.chunks);
             }
-        });
+        };
     }
 }
-exports.ShellX = ShellX;
-/**
- * Create ShellX instance
- */
-function createShellX(client) {
-    return new ShellX(client);
-}
-/**
- * Create ShellX instance with automatic authentication and shell output monitoring
- * 自动处理ShellX.ai认证和连接，无需外部提供连接地址
- */
-function createShellXWithShellMonitoring() {
-    return __awaiter(this, arguments, void 0, function* (config = {}) {
-        try {
-            const shellx = new ShellX(null);
-            const client = new index_1.default(config.deviceId, Object.assign(Object.assign({}, config), { onMessage: (message) => {
-                    if (message.chunks) {
-                        shellx.handleShellOutput(message.chunks);
-                    }
-                    if (config.onMessage) {
-                        config.onMessage(message);
-                    }
-                }, onOpen: () => {
-                    // 调用原始的onOpen处理器
-                    if (config.onOpen) {
-                        config.onOpen();
-                    }
-                } }));
-            // 等待ShellX.ai服务连接完成
-            console.log('⏳ [ShellX] 等待ShellX.ai服务连接...');
-            yield client.waitForInitialization();
-            // 绑定客户端到 shellx
-            shellx.client = client;
-            // 将 shellx 实例关联到客户端
-            client.setShellX(shellx);
-            console.log('🚀 [ShellX] 初始化完成，等待ShellX.ai服务响应...');
-            return shellx;
-        }
-        catch (error) {
-            console.error('❌ [ShellX] 初始化失败:', error);
-            throw error;
-        }
-    });
-}
+//# sourceMappingURL=shellx.js.map