weixin-devtools-mcp 0.0.1 → 0.1.1

package/build/tools.js

@@ -2,21 +2,40 @@
  * 微信开发者工具 MCP 工具函数
  * 提供可测试的纯函数实现
  */
-import automator from "miniprogram-automator";
-import path from "path";
-import fs from "fs";
 import { spawn } from "child_process";
+import fs from "fs";
+import path from "path";
 import { promisify } from "util";
+import automator from "miniprogram-automator";
 const sleep = promisify(setTimeout);
 /**
  * 开发者工具连接错误类
  */
-export class DevToolsConnectionError extends Error {
+import { DevToolsError, ErrorCode, ErrorCategory } from './types/errors.js';
+/**
+ * @deprecated 使用 DevToolsError 替代
+ * 保留此类以保持向后兼容性
+ */
+export class DevToolsConnectionError extends DevToolsError {
     phase;
     originalError;
     details;
     constructor(message, phase, originalError, details) {
-        super(message);
+        // 根据阶段选择错误代码
+        const code = phase === 'startup'
+            ? ErrorCode.CONNECTION_FAILED
+            : phase === 'connection'
+                ? ErrorCode.CONNECTION_FAILED
+                : ErrorCode.CONNECTION_TIMEOUT;
+        const context = {
+            operation: phase,
+            details,
+            cause: originalError,
+        };
+        super(message, code, {
+            category: ErrorCategory.CONNECTION,
+            context,
+        });
         this.phase = phase;
         this.originalError = originalError;
         this.details = details;
@@ -31,7 +50,7 @@ export class DevToolsConnectionError extends Error {
  * @throws 连接失败时抛出错误
  */
 export async function connectDevtools(options) {
-    const { projectPath, cliPath, port } = options;
+    const { projectPath, cliPath, port, autoAudits } = options;
     if (!projectPath) {
         throw new Error("项目路径是必需的");
     }
@@ -57,6 +76,15 @@ export async function connectDevtools(options) {
             launchOptions.cliPath = cliPath;
         if (port)
             launchOptions.port = port;
+        if (typeof autoAudits === 'boolean') {
+            launchOptions.projectConfig = {
+                ...(launchOptions.projectConfig || {}),
+                setting: {
+                    ...(launchOptions.projectConfig?.setting || {}),
+                    autoAudits
+                }
+            };
+        }
         // 启动并连接微信开发者工具
         const miniProgram = await automator.launch(launchOptions);
         // 获取当前页面
@@ -218,12 +246,12 @@ export async function connectDevtools(options) {
                     hasInterceptors: !!(app && app.$xfetch && app.$xfetch.interceptors),
                     hasMpxFetch: hasMpxFetch
                 };
-                console.log('[MCP-DEBUG] Mpx检测:', debugInfo);
+                console.error('[MCP-DEBUG] Mpx检测:', debugInfo);
                 // 强制安装 Mpx 拦截器（不检查标志，每次都重新安装以覆盖旧的）
                 // 这样可以解决小程序未重新加载导致标志残留的问题
                 // @ts-ignore
                 if (hasMpxFetch) {
-                    console.log('[MCP] 正在安装 Mpx $xfetch 拦截器（强制覆盖）...');
+                    console.error('[MCP] 正在安装 Mpx $xfetch 拦截器（强制覆盖）...');
                     // 安装 Mpx 请求拦截器
                     // @ts-ignore
                     app.$xfetch.interceptors.request.use(function (config) {
@@ -282,12 +310,12 @@ export async function connectDevtools(options) {
                         });
                         throw error;
                     });
-                    console.log('[MCP] Mpx $xfetch 拦截器安装完成');
+                    console.error('[MCP] Mpx $xfetch 拦截器安装完成');
                 }
                 // @ts-ignore
                 wx.__networkInterceptorsInstalled = true;
             });
-            console.log('[connectDevtools] 网络监听已自动启动（包含 Mpx 框架支持）');
+            console.error('[connectDevtools] 网络监听已自动启动（包含 Mpx 框架支持）');
         }
         catch (err) {
             console.warn('[connectDevtools] 网络监听启动失败:', err);
@@ -311,7 +339,7 @@ export async function connectDevtools(options) {
  * @returns 详细连接结果
  */
 export async function connectDevtoolsEnhanced(options) {
-    const { mode = 'auto', fallbackMode = true, healthCheck = true, verbose = false } = options;
+    const { mode = 'auto', verbose = false } = options;
     const startTime = Date.now();
     // 验证项目路径（在所有模式执行前统一验证）
     if (!options.projectPath) {
@@ -330,8 +358,8 @@ export async function connectDevtoolsEnhanced(options) {
         throw new Error(`Project path '${resolvedProjectPath}' doesn't exist`);
     }
     if (verbose) {
-        console.log(`开始连接微信开发者工具，模式: ${mode}`);
-        console.log(`项目路径: ${resolvedProjectPath}`);
+        console.error(`开始连接微信开发者工具，模式: ${mode}`);
+        console.error(`项目路径: ${resolvedProjectPath}`);
     }
     try {
         switch (mode) {
@@ -377,7 +405,7 @@ function isSessionConflictError(error) {
  */
 async function intelligentConnect(options, startTime) {
     if (options.verbose) {
-        console.log('🎯 智能连接策略: 优先使用 launchMode（自动处理项目验证和会话复用）');
+        console.error('🎯 智能连接策略: 优先使用 launchMode（自动处理项目验证和会话复用）');
     }
     try {
         // 默认使用 launchMode
@@ -389,12 +417,12 @@ async function intelligentConnect(options, startTime) {
     }
     catch (error) {
         if (options.verbose) {
-            console.log('⚠️ launchMode 失败，分析错误类型...');
+            console.error('⚠️ launchMode 失败，分析错误类型...');
         }
         // 仅在特定可恢复错误时回退到 connectMode
         if (options.fallbackMode && isSessionConflictError(error)) {
             if (options.verbose) {
-                console.log('🔄 检测到会话冲突，尝试回退到 connectMode');
+                console.error('🔄 检测到会话冲突，尝试回退到 connectMode');
             }
             return await connectMode(options, startTime);
         }
@@ -430,7 +458,7 @@ async function connectMode(options, startTime) {
             error.phase === 'startup' &&
             error.details?.reason === 'session_conflict') {
             if (options.verbose) {
-                console.log('🔄 检测到会话冲突，自动回退到传统连接模式（launch）...');
+                console.error('🔄 检测到会话冲突，自动回退到传统连接模式（launch）...');
             }
             // 如果允许回退，自动使用launch模式
             if (options.fallbackMode) {
@@ -448,7 +476,8 @@ async function launchMode(options, startTime) {
     const connectOptions = {
         projectPath: options.projectPath,
         cliPath: options.cliPath,
-        port: options.autoPort || options.port
+        port: options.autoPort || options.port,
+        autoAudits: options.autoAudits
     };
     const result = await connectDevtools(connectOptions);
     // 健康检查
@@ -470,7 +499,7 @@ async function startupPhase(options) {
     const port = options.autoPort || 9420;
     const cliCommand = buildCliCommand(options);
     if (options.verbose) {
-        console.log('执行CLI命令:', cliCommand.join(' '));
+        console.error('执行CLI命令:', cliCommand.join(' '));
     }
     // 执行CLI命令
     const process = await executeCliCommand(cliCommand);
@@ -490,7 +519,7 @@ async function startupPhase(options) {
 async function connectionPhase(options, startupResult) {
     const wsEndpoint = `ws://localhost:${startupResult.processInfo.port}`;
     if (options.verbose) {
-        console.log('连接WebSocket端点:', wsEndpoint);
+        console.error('连接WebSocket端点:', wsEndpoint);
     }
     // 连接到WebSocket端点
     const miniProgram = await connectWithRetry(wsEndpoint, 3);
@@ -530,8 +559,19 @@ function buildCliCommand(options) {
 }
 /**
  * 查找默认CLI路径
+ * 优先级：环境变量 > 默认路径
  */
 function findDefaultCliPath() {
+    // 1. 优先使用环境变量
+    const envCliPath = process.env.WECHAT_DEVTOOLS_CLI;
+    if (envCliPath) {
+        if (envCliPath.startsWith('@playground/')) {
+            // @playground/ 格式需要转换为实际路径
+            const relativePath = envCliPath.replace('@playground/', 'playground/');
+            return path.resolve(process.cwd(), relativePath);
+        }
+        return path.resolve(process.cwd(), envCliPath);
+    }
     const platform = process.platform;
     if (platform === 'darwin') {
         return '/Applications/wechatwebdevtools.app/Contents/MacOS/cli';
@@ -540,7 +580,18 @@ function findDefaultCliPath() {
         return 'C:/Program Files (x86)/Tencent/微信web开发者工具/cli.bat';
     }
     else {
-        throw new Error(`不支持的平台: ${platform}`);
+        // Linux: 尝试常见的 Linux 版开发者工具路径
+        const linuxPaths = [
+            '/opt/apps/io.github.msojocs.wechat-devtools-linux/files/bin/bin/wechat-devtools-cli',
+            '/usr/share/wechat-devtools/bin/cli',
+            '/usr/local/bin/wechat-devtools-cli',
+        ];
+        for (const p of linuxPaths) {
+            if (fs.existsSync(p)) {
+                return p;
+            }
+        }
+        throw new Error(`不支持的平台: ${platform}。可在 Linux 上设置环境变量 WECHAT_DEVTOOLS_CLI 指定 CLI 路径`);
     }
 }
 /**
@@ -572,14 +623,14 @@ async function executeCliCommand(command) {
             process.stdout.on('data', (data) => {
                 const text = data.toString();
                 output += text;
-                console.log('[CLI stdout]:', text.trim());
+                console.error('[CLI stdout]:', text.trim());
             });
         }
         if (process.stderr) {
             process.stderr.on('data', (data) => {
                 const text = data.toString();
                 errorOutput += text;
-                console.log('[CLI stderr]:', text.trim());
+                console.error('[CLI stderr]:', text.trim());
                 // 检测端口冲突错误
                 if (text.includes('must be restarted on port')) {
                     const match = text.match(/started on .+:(\d+) and must be restarted on port (\d+)/);
@@ -619,7 +670,7 @@ async function executeCliCommand(command) {
                 // 检测 CLI 命令失败（通用）
                 if (text.includes('error') || text.includes('failed') || text.includes('失败')) {
                     if (!resolved && text.length > 10) { // 确保不是误报
-                        console.log('[CLI 警告] 检测到潜在错误:', text.trim());
+                        console.error('[CLI 警告] 检测到潜在错误:', text.trim());
                     }
                 }
             });
@@ -661,22 +712,21 @@ async function executeCliCommand(command) {
 export async function waitForWebSocketReady(port, timeout, verbose = false) {
     const startTime = Date.now();
     let attempt = 0;
-    const maxAttempts = Math.ceil(timeout / 1000); // 每秒检查一次
     if (verbose) {
-        console.log(`等待WebSocket服务启动，端口: ${port}，超时: ${timeout}ms`);
+        console.error(`等待WebSocket服务启动，端口: ${port}，超时: ${timeout}ms`);
     }
     while (Date.now() - startTime < timeout) {
         attempt++;
         if (verbose && attempt % 5 === 0) { // 每5秒显示一次进度
             const elapsed = Date.now() - startTime;
-            console.log(`WebSocket检测进度: ${Math.round(elapsed / 1000)}s / ${Math.round(timeout / 1000)}s`);
+            console.error(`WebSocket检测进度: ${Math.round(elapsed / 1000)}s / ${Math.round(timeout / 1000)}s`);
         }
         // 尝试多种检测方式
         const isReady = await checkDevToolsRunning(port) || await checkWebSocketDirectly(port);
         if (isReady) {
             if (verbose) {
                 const elapsed = Date.now() - startTime;
-                console.log(`WebSocket服务已启动，耗时: ${elapsed}ms`);
+                console.error(`WebSocket服务已启动，耗时: ${elapsed}ms`);
             }
             return;
         }
@@ -737,16 +787,16 @@ export async function detectIDEPort(verbose = false) {
     // 常用端口列表
     const commonPorts = [9420, 9440, 9430, 9450, 9460];
     if (verbose) {
-        console.log('🔍 检测微信开发者工具运行端口...');
+        console.error('🔍 检测微信开发者工具运行端口...');
     }
     // 策略1: 尝试常用端口
     for (const port of commonPorts) {
         if (verbose) {
-            console.log(`  检测端口 ${port}...`);
+            console.error(`  检测端口 ${port}...`);
         }
         if (await checkDevToolsRunning(port)) {
             if (verbose) {
-                console.log(`✅ 检测到IDE运行在端口 ${port}`);
+                console.error(`✅ 检测到IDE运行在端口 ${port}`);
             }
             return port;
         }
@@ -760,14 +810,14 @@ export async function detectIDEPort(verbose = false) {
             if (output) {
                 const ports = output.split('\n').map((p) => parseInt(p, 10)).filter((p) => !isNaN(p));
                 if (verbose && ports.length > 0) {
-                    console.log(`  lsof检测到端口: ${ports.join(', ')}`);
+                    console.error(`  lsof检测到端口: ${ports.join(', ')}`);
                 }
                 // 遍历检测到的端口，验证是否为有效的自动化端口
                 for (const port of ports) {
                     if (port >= 9400 && port <= 9500) {
                         if (await checkDevToolsRunning(port)) {
                             if (verbose) {
-                                console.log(`✅ 通过lsof检测到IDE运行在端口 ${port}`);
+                                console.error(`✅ 通过lsof检测到IDE运行在端口 ${port}`);
                             }
                             return port;
                         }
@@ -778,12 +828,12 @@ export async function detectIDEPort(verbose = false) {
         catch (error) {
             // lsof 失败，继续
             if (verbose) {
-                console.log('  lsof检测失败');
+                console.error('  lsof检测失败');
             }
         }
     }
     if (verbose) {
-        console.log('❌ 未检测到IDE运行端口');
+        console.error('❌ 未检测到IDE运行端口');
     }
     return null;
 }
@@ -838,30 +888,69 @@ async function executeWithDetailedError(operation, phase) {
         throw new DevToolsConnectionError(originalError.message, phase, originalError, { timestamp: new Date().toISOString() });
     }
 }
+/**
+ * 生成简单的文本哈希（用于增强 UID 唯一性）
+ */
+function simpleTextHash(text) {
+    if (!text || text.length === 0)
+        return '';
+    // 取文本的前 8 个字符，过滤特殊字符
+    const sanitized = text.replace(/[^a-zA-Z0-9\u4e00-\u9fa5]/g, '').slice(0, 8);
+    if (sanitized.length === 0)
+        return '';
+    return `_${sanitized}`;
+}
 /**
  * 生成元素的唯一标识符 (uid)
+ *
+ * 优先级顺序（稳定性从高到低）：
+ * 1. data-testid（专门用于测试，最稳定）
+ * 2. id 属性
+ * 3. data-id（自定义数据属性）
+ * 4. class + 文本哈希（中等稳定性）
+ * 5. class:eq(index)
+ * 6. nth-child（兜底）
  */
 export async function generateElementUid(element, index) {
     try {
         const tagName = element.tagName;
-        const className = await element.attribute('class').catch(() => '');
-        const id = await element.attribute('id').catch(() => '');
-        console.log(`[generateElementUid] tagName=${tagName}, className="${className}", id="${id}", index=${index}`);
+        // 并行获取所有可能的标识属性
+        const [className, id, testId, dataId, text] = await Promise.all([
+            element.attribute('class').catch(() => ''),
+            element.attribute('id').catch(() => ''),
+            element.attribute('data-testid').catch(() => ''),
+            element.attribute('data-id').catch(() => ''),
+            element.text().catch(() => '')
+        ]);
+        console.error(`[generateElementUid] tagName=${tagName}, id="${id}", testId="${testId}", dataId="${dataId}", className="${className}", index=${index}`);
         let selector = tagName;
-        if (id) {
+        // 优先级1: data-testid（最稳定）
+        if (testId) {
+            selector += `[data-testid="${testId}"]`;
+        }
+        // 优先级2: id 属性
+        else if (id) {
             selector += `#${id}`;
         }
+        // 优先级3: data-id
+        else if (dataId) {
+            selector += `[data-id="${dataId}"]`;
+        }
+        // 优先级4: class + 文本哈希
         else if (className) {
-            selector += `.${className.split(' ')[0]}`;
+            const firstClass = className.split(' ')[0];
+            const textHash = simpleTextHash(text);
+            selector += `.${firstClass}${textHash}`;
         }
+        // 优先级5: nth-child（兜底）
         else {
             selector += `:nth-child(${index + 1})`;
         }
-        console.log(`[generateElementUid] Generated UID: ${selector}`);
+        console.error(`[generateElementUid] Generated UID: ${selector}`);
         return selector;
     }
     catch (error) {
-        console.log(`[generateElementUid] Error:`, error);
+        console.error(`[generateElementUid] Error:`, error);
         return `${element.tagName || 'unknown'}:nth-child(${index + 1})`;
     }
 }
@@ -882,16 +971,21 @@ export async function getPageSnapshot(page) {
         await new Promise(resolve => setTimeout(resolve, 1000));
         // 尝试多种选择器策略获取元素
         let childElements = [];
-        // 策略1: 尝试获取所有元素
+        let usedStrategy = 'unknown';
+        // 策略1: 优先使用通配符（最快，一次API调用）
         try {
             childElements = await page.$$('*');
-            console.log(`策略1 (*) 获取到 ${childElements.length} 个元素`);
+            if (childElements.length > 0) {
+                usedStrategy = 'wildcard(*)';
+                console.error(`✅ 策略1成功: 通配符查询获取到 ${childElements.length} 个元素`);
+            }
         }
         catch (error) {
-            console.log('策略1 (*) 失败:', error);
+            console.warn('⚠️  策略1失败 (*)', error);
         }
-        // 策略2: 如果策略1失败，尝试小程序常用组件
+        // 策略2: 降级到常用组件选择器（仅当策略1失败时）
         if (childElements.length === 0) {
+            console.error('🔄 策略1无结果，降级到策略2（常用组件选择器）');
             const commonSelectors = [
                 'view', 'text', 'button', 'image', 'input', 'textarea', 'picker', 'switch',
                 'slider', 'scroll-view', 'swiper', 'icon', 'rich-text', 'progress',
@@ -901,51 +995,108 @@ export async function getPageSnapshot(page) {
                 try {
                     const elements = await page.$$(selector);
                     childElements.push(...elements);
-                    console.log(`策略2 (${selector}) 获取到 ${elements.length} 个元素`);
+                    if (elements.length > 0) {
+                        console.error(`  - ${selector}: ${elements.length} 个元素`);
+                    }
                 }
                 catch (error) {
-                    console.log(`策略2 (${selector}) 失败:`, error);
+                    // 忽略单个选择器失败
                 }
             }
+            if (childElements.length > 0) {
+                usedStrategy = 'common-selectors';
+                console.error(`✅ 策略2成功: 获取到 ${childElements.length} 个元素`);
+            }
         }
-        // 策略3: 如果还是没有元素，尝试根据层级查找
+        // 策略3: 最后尝试层级选择器
         if (childElements.length === 0) {
+            console.error('🔄 策略2无结果，降级到策略3（层级选择器）');
             try {
                 const rootElements = await page.$$('page > *');
                 childElements = rootElements;
-                console.log(`策略3 (page > *) 获取到 ${childElements.length} 个元素`);
+                if (childElements.length > 0) {
+                    usedStrategy = 'hierarchical(page>*)';
+                    console.error(`✅ 策略3成功: 获取到 ${childElements.length} 个元素`);
+                }
             }
             catch (error) {
-                console.log('策略3 (page > *) 失败:', error);
+                console.warn('⚠️  策略3失败 (page > *)', error);
             }
         }
-        console.log(`最终获取到 ${childElements.length} 个元素`);
+        if (childElements.length === 0) {
+            console.warn('❌ 所有策略均未获取到元素');
+            return {
+                snapshot: { path: await page.path, elements: [] },
+                elementMap: new Map()
+            };
+        }
+        console.error(`📊 最终获取到 ${childElements.length} 个元素（策略：${usedStrategy}）`);
         // 用于跟踪每个基础选择器的元素计数
         const selectorIndexMap = new Map();
+        // 优化：批量并行处理元素属性
+        const startTime = Date.now();
         for (let i = 0; i < childElements.length; i++) {
             const element = childElements[i];
             try {
-                const uid = await generateElementUid(element, i);
+                // 🚀 优化点1: 使用 Promise.allSettled 并行获取所有元素属性
+                // 减少API调用往返次数：从 6次串行 → 1次并行
+                // 新增 data-testid 和 data-id 属性用于增强 UID 稳定性
+                const [tagNameResult, textResult, classResult, idResult, testIdResult, dataIdResult, sizeResult, offsetResult] = await Promise.allSettled([
+                    Promise.resolve(element.tagName || 'unknown'),
+                    element.text().catch(() => ''),
+                    element.attribute('class').catch(() => ''),
+                    element.attribute('id').catch(() => ''),
+                    element.attribute('data-testid').catch(() => ''),
+                    element.attribute('data-id').catch(() => ''),
+                    element.size().catch(() => null),
+                    element.offset().catch(() => null)
+                ]);
+                // 提取结果
+                const tagName = tagNameResult.status === 'fulfilled' ? tagNameResult.value : 'unknown';
+                const text = textResult.status === 'fulfilled' ? textResult.value : '';
+                const className = classResult.status === 'fulfilled' ? classResult.value : '';
+                const id = idResult.status === 'fulfilled' ? idResult.value : '';
+                const testId = testIdResult.status === 'fulfilled' ? testIdResult.value : '';
+                const dataId = dataIdResult.status === 'fulfilled' ? dataIdResult.value : '';
+                const size = sizeResult.status === 'fulfilled' ? sizeResult.value : null;
+                const offset = offsetResult.status === 'fulfilled' ? offsetResult.value : null;
+                // 生成 UID（增强版优先级顺序）
+                // 优先级：data-testid > id > data-id > class+文本哈希 > nth-child
+                let selector = tagName;
+                if (testId) {
+                    // 优先级1: data-testid（专门用于测试，最稳定）
+                    selector += `[data-testid="${testId}"]`;
+                }
+                else if (id) {
+                    // 优先级2: id 属性
+                    selector += `#${id}`;
+                }
+                else if (dataId) {
+                    // 优先级3: data-id
+                    selector += `[data-id="${dataId}"]`;
+                }
+                else if (className) {
+                    // 优先级4: class + 文本哈希（中等稳定性）
+                    const firstClass = className.split(' ')[0];
+                    const textHash = simpleTextHash(text);
+                    selector += `.${firstClass}${textHash}`;
+                }
+                else {
+                    // 优先级5: nth-child（兜底）
+                    selector += `:nth-child(${i + 1})`;
+                }
+                const uid = selector;
+                // 构建快照
                 const snapshot = {
                     uid,
-                    tagName: element.tagName || 'unknown',
+                    tagName,
                 };
-                // 获取元素文本
-                try {
-                    const text = await element.text();
-                    if (text && text.trim()) {
-                        snapshot.text = text.trim();
-                    }
-                }
-                catch (error) {
-                    // 忽略无法获取文本的元素
+                // 添加文本内容
+                if (text && text.trim()) {
+                    snapshot.text = text.trim();
                 }
-                // 获取元素位置信息
-                try {
-                    const [size, offset] = await Promise.all([
-                        element.size(),
-                        element.offset()
-                    ]);
+                // 添加位置信息
+                if (size && offset) {
                     snapshot.position = {
                         left: offset.left,
                         top: offset.top,
@@ -953,56 +1104,38 @@ export async function getPageSnapshot(page) {
                         height: size.height
                     };
                 }
-                catch (error) {
-                    // 忽略无法获取位置的元素
-                }
-                // 获取常用属性
-                try {
-                    const attributes = {};
-                    const commonAttrs = ['class', 'id', 'data-*'];
-                    for (const attr of commonAttrs) {
-                        try {
-                            const value = await element.attribute(attr);
-                            if (value) {
-                                attributes[attr] = value;
-                            }
-                        }
-                        catch (error) {
-                            // 忽略不存在的属性
-                        }
-                    }
-                    if (Object.keys(attributes).length > 0) {
-                        snapshot.attributes = attributes;
-                    }
-                }
-                catch (error) {
-                    // 忽略属性获取错误
-                }
+                // 添加属性信息（可选，目前不收集）
+                // 如果需要属性，可以在上面的 Promise.allSettled 中添加更多属性查询
                 elements.push(snapshot);
-                // 生成可查询的基础选择器（不包含伪类）
-                const tagName = element.tagName;
-                const className = await element.attribute('class').catch(() => '');
-                const id = await element.attribute('id').catch(() => '');
+                // 生成可查询的基础选择器（与 UID 优先级一致）
                 let baseSelector = tagName;
-                if (id) {
+                if (testId) {
+                    baseSelector = `${tagName}[data-testid="${testId}"]`;
+                }
+                else if (id) {
                     baseSelector = `${tagName}#${id}`;
                 }
+                else if (dataId) {
+                    baseSelector = `${tagName}[data-id="${dataId}"]`;
+                }
                 else if (className) {
                     baseSelector = `${tagName}.${className.split(' ')[0]}`;
                 }
                 // 计算该选择器的元素索引（递增计数）
                 const currentIndex = selectorIndexMap.get(baseSelector) || 0;
                 selectorIndexMap.set(baseSelector, currentIndex + 1);
-                // 存储 ElementMapInfo，使用可查询的基础选择器和索引
+                // 存储 ElementMapInfo
                 elementMap.set(uid, {
-                    selector: baseSelector, // 使用可查询的基础选择器
-                    index: currentIndex // 使用该选择器的当前计数
+                    selector: baseSelector,
+                    index: currentIndex
                 });
             }
             catch (error) {
-                console.warn(`Error processing element ${i}:`, error);
+                console.warn(`⚠️  处理元素 ${i} 时出错:`, error);
             }
         }
+        const processingTime = Date.now() - startTime;
+        console.error(`⏱️  元素处理耗时: ${processingTime}ms (平均 ${(processingTime / childElements.length).toFixed(2)}ms/元素)`);
         const pagePath = await page.path;
         const snapshot = {
             path: pagePath,
@@ -1036,7 +1169,7 @@ export async function clickElement(page, elementMap, options) {
         if (!mapInfo) {
             throw new Error(`找不到uid为 ${uid} 的元素，请先获取页面快照`);
         }
-        console.log(`[Click] 准备点击元素 - UID: ${uid}, Selector: ${mapInfo.selector}, Index: ${mapInfo.index}`);
+        console.error(`[Click] 准备点击元素 - UID: ${uid}, Selector: ${mapInfo.selector}, Index: ${mapInfo.index}`);
         // 使用选择器获取所有匹配元素
         const elements = await page.$$(mapInfo.selector);
         if (!elements || elements.length === 0) {
@@ -1053,27 +1186,27 @@ export async function clickElement(page, elementMap, options) {
         }
         // 记录点击前的页面路径
         const beforePath = await page.path;
-        console.log(`[Click] 点击前页面: ${beforePath}`);
+        console.error(`[Click] 点击前页面: ${beforePath}`);
         // 执行点击操作
         await element.tap();
-        console.log(`[Click] 已执行 tap() 操作`);
+        console.error(`[Click] 已执行 tap() 操作`);
         // 如果是双击，再点击一次
         if (dblClick) {
             await new Promise(resolve => setTimeout(resolve, 100)); // 短暂延迟
             await element.tap();
-            console.log(`[Click] 已执行第二次 tap() (双击)`);
+            console.error(`[Click] 已执行第二次 tap() (双击)`);
         }
         // 等待一小段时间，让页面有机会响应
         await new Promise(resolve => setTimeout(resolve, 300));
         // 记录点击后的页面路径
         try {
             const afterPath = await page.path;
-            console.log(`[Click] 点击后页面: ${afterPath}`);
+            console.error(`[Click] 点击后页面: ${afterPath}`);
             if (beforePath !== afterPath) {
-                console.log(`[Click] ✅ 页面已切换: ${beforePath} → ${afterPath}`);
+                console.error(`[Click] ✅ 页面已切换: ${beforePath} → ${afterPath}`);
             }
             else {
-                console.log(`[Click] ⚠️  页面未切换，可能是同页面操作或导航延迟`);
+                console.error(`[Click] ⚠️  页面未切换，可能是同页面操作或导航延迟`);
             }
         }
         catch (error) {
@@ -1101,12 +1234,12 @@ export async function takeScreenshot(miniProgram, options = {}) {
         const { path } = options;
         // 确保页面完全加载和稳定
         try {
-            console.log('获取当前页面并等待稳定...');
+            console.error('获取当前页面并等待稳定...');
             const currentPage = await miniProgram.currentPage();
             if (currentPage && typeof currentPage.waitFor === 'function') {
                 // 等待页面稳定，增加等待时间
                 await currentPage.waitFor(1000);
-                console.log('页面等待完成');
+                console.error('页面等待完成');
             }
         }
         catch (waitError) {
@@ -1114,24 +1247,30 @@ export async function takeScreenshot(miniProgram, options = {}) {
         }
         // 重试机制执行截图
         let result;
+        let screenshotSucceeded = false;
         let lastError;
         for (let attempt = 1; attempt <= 3; attempt++) {
             try {
-                console.log(`截图尝试 ${attempt}/3`);
+                console.error(`截图尝试 ${attempt}/3`);
                 if (path) {
                     // 保存到指定路径
                     await miniProgram.screenshot({ path });
+                    if (!fs.existsSync(path)) {
+                        throw new Error(`截图命令返回成功，但目标文件不存在: ${path}`);
+                    }
+                    screenshotSucceeded = true;
                     result = undefined;
-                    console.log(`截图保存成功: ${path}`);
+                    console.error(`截图保存成功: ${path}`);
                     break;
                 }
                 else {
                     // 返回base64数据
                     const base64Data = await miniProgram.screenshot();
-                    console.log('截图API调用完成，检查返回数据...');
+                    console.error('截图API调用完成，检查返回数据...');
                     if (base64Data && typeof base64Data === 'string' && base64Data.length > 0) {
+                        screenshotSucceeded = true;
                         result = base64Data;
-                        console.log(`截图成功，数据长度: ${base64Data.length}`);
+                        console.error(`截图成功，数据长度: ${base64Data.length}`);
                         break;
                     }
                     else {
@@ -1144,12 +1283,12 @@ export async function takeScreenshot(miniProgram, options = {}) {
                 console.warn(`截图尝试 ${attempt} 失败:`, lastError.message);
                 if (attempt < 3) {
                     // 重试前等待更长时间，让页面稳定
-                    console.log(`等待 ${1000 + attempt * 500}ms 后重试...`);
+                    console.error(`等待 ${1000 + attempt * 500}ms 后重试...`);
                     await new Promise(resolve => setTimeout(resolve, 1000 + attempt * 500));
                 }
             }
         }
-        if (!result && !path) {
+        if (!screenshotSucceeded) {
             const troubleshootingTips = `
 
 ⚠️  截图功能故障排除建议：
@@ -2129,3 +2268,4 @@ export async function reLaunch(miniProgram, options) {
         throw new Error(`重新启动失败: ${errorMessage}`);
     }
 }
+//# sourceMappingURL=tools.js.map