@pyrokine/mcp-chrome 1.1.0 → 1.4.0

package/dist/cdp/launcher.js

@@ -8,6 +8,7 @@ import { existsSync, mkdirSync } from 'fs';
 import { homedir, platform } from 'os';
 import { join } from 'path';
 import { BrowserNotFoundError, TimeoutError } from '../core/errors.js';
+import { DEFAULT_TIMEOUT } from '../core/types.js';
 /**
  * 默认 profile 目录（固定路径，保留 cookies 和登录状态）
  */
@@ -54,18 +55,11 @@ export class BrowserLauncher {
     get port() {
         return this._port;
     }
-    _endpoint = '';
-    get endpoint() {
-        return this._endpoint;
-    }
-    get isRunning() {
-        return this.process !== null && !this.process.killed;
-    }
     /**
      * 启动浏览器
      */
     async launch(options = {}) {
-        const { executablePath, port = 0, incognito = false, headless = false, userDataDir, timeout = 30000, } = options;
+        const { executablePath, port = 0, incognito = false, headless = false, userDataDir, timeout = DEFAULT_TIMEOUT, } = options;
         // 查找 Chrome
         const chromePath = executablePath ?? findChrome();
         if (!chromePath) {
@@ -79,8 +73,7 @@ export class BrowserLauncher {
             stdio: ['ignore', 'pipe', 'pipe'],
         });
         // 等待 CDP 端点就绪
-        this._endpoint = await this.waitForEndpoint(timeout);
-        return this._endpoint;
+        return this.waitForEndpoint(timeout);
     }
     /**
      * 关闭浏览器
@@ -91,15 +84,6 @@ export class BrowserLauncher {
             this.process = null;
         }
     }
-    /**
-     * 强制关闭浏览器
-     */
-    forceClose() {
-        if (this.process && !this.process.killed) {
-            this.process.kill('SIGKILL');
-            this.process = null;
-        }
-    }
     /**
      * 构建启动参数
      */
@@ -164,7 +148,7 @@ export class BrowserLauncher {
             this.process.stderr?.on('data', (data) => {
                 stderr += data.toString();
                 // 解析 DevTools listening on ws://...
-                const match = stderr.match(/DevTools listening on (ws:\/\/[^\s]+)/);
+                const match = stderr.match(/DevTools listening on (ws:\/\/\S+)/);
                 if (match) {
                     clearTimeout(timer);
                     // 解析端口
@@ -181,7 +165,13 @@ export class BrowserLauncher {
             });
             this.process.on('exit', (code) => {
                 clearTimeout(timer);
-                if (code !== 0 && code !== null) {
+                if (code === 0) {
+                    // Chrome 退出码 0：通常是把请求委托给了已运行的实例后自行退出，
+                    // 此时没有 DevTools 端点可连接
+                    reject(new Error('浏览器进程已退出（code 0），可能已有相同 profile 的 Chrome 实例在运行。\n'
+                        + '请关闭已运行的 Chrome 或指定不同的 userDataDir'));
+                }
+                else if (code !== null) {
                     reject(new Error(`浏览器进程退出，代码: ${code}\n${stderr}`));
                 }
             });

package/dist/cdp/launcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../src/cdp/launcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../src/cdp/launcher.ts"],"names":[],"mappings":"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"}

package/dist/core/auto-wait.d.ts

@@ -22,8 +22,8 @@ export interface AutoWaitOptions {
 export declare class AutoWait {
     private cdp;
     private sessionId;
-    private timeout;
-    private deadline;
+    private readonly timeout;
+    private readonly deadline;
     constructor(cdp: CDPClient, sessionId: string, options?: AutoWaitOptions);
     /**
      * 等待元素可用（非禁用状态）

package/dist/core/auto-wait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-wait.d.ts","sourceRoot":"","sources":["../../src/core/auto-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,kBAAkB,CAAA;AAG/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;GAEG;AACH,qBAAa,QAAQ;IAKb,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,SAAS;IALrB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAQ;gBAGZ,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,MAAM,EACzB,OAAO,GAAE,eAAoB;IAMjC;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnD;;;;;OAKG;IACG,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmC7D;;;;;OAKG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BrD;;;;OAIG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BnD;;;;OAIG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrD;;;;OAIG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtD;;;;OAIG;IACH,OAAO,CAAC,IAAI;IAIZ;;OAEG;IACH,OAAO,CAAC,SAAS;CAGpB"}
+{"version":3,"file":"auto-wait.d.ts","sourceRoot":"","sources":["../../src/core/auto-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,kBAAkB,CAAA;AAI/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,QAAQ;IAKb,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,SAAS;IALrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;gBAGrB,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,MAAM,EACzB,OAAO,GAAE,eAAoB;IAMjC;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnD;;;;;OAKG;IACG,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmC7D;;;;;OAKG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BrD;;;;OAIG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BnD;;;;OAIG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrD;;;;OAIG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtD;;;;OAIG;IACH,OAAO,CAAC,IAAI;IAIZ;;OAEG;IACH,OAAO,CAAC,SAAS;CAGpB"}

package/dist/core/auto-wait.js

@@ -9,7 +9,7 @@
  * 核心思想：操作前自动检查元素状态，失败则重试，而非立即报错。
  */
 import { withRetry } from './retry.js';
-const DEFAULT_TIMEOUT = 30000;
+import { DEFAULT_TIMEOUT } from './types.js';
 /**
  * 自动等待类
  */

package/dist/core/auto-wait.js.map

@@ -1 +1 @@
-{"version":3,"file":"auto-wait.js","sourceRoot":"","sources":["../../src/core/auto-wait.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auto-wait.js","sourceRoot":"","sources":["../../src/core/auto-wait.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.d.ts

@@ -21,7 +21,7 @@ export declare abstract class BrowserError extends Error {
     abstract readonly code: string;
     abstract readonly suggestion: string;
     readonly context: ErrorContext;
-    constructor(message: string);
+    protected constructor(message: string);
     /**
      * 转换为 JSON 格式，用于 MCP 响应
      */
@@ -89,14 +89,6 @@ export declare class TimeoutError extends BrowserError {
     readonly suggestion = "\u8BF7\u589E\u52A0\u8D85\u65F6\u65F6\u95F4\uFF0C\u6216\u68C0\u67E5\u64CD\u4F5C\u6761\u4EF6\u662F\u5426\u80FD\u6EE1\u8DB3";
     constructor(message: string);
 }
-/**
- * 无效参数错误
- */
-export declare class InvalidArgumentError extends BrowserError {
-    readonly code = "INVALID_ARGUMENT";
-    readonly suggestion: string;
-    constructor(message: string, suggestion?: string);
-}
 /**
  * CDP 协议错误
  */
@@ -105,10 +97,6 @@ export declare class CDPError extends BrowserError {
     readonly suggestion = "\u8FD9\u662F\u4E00\u4E2A CDP \u534F\u8BAE\u9519\u8BEF\uFF0C\u8BF7\u68C0\u67E5\u64CD\u4F5C\u662F\u5426\u6B63\u786E";
     constructor(message: string);
 }
-/**
- * 格式化日志记录（参考 Playwright Waiter）
- */
-export declare function formatLogRecording(logs: string[]): string;
 /**
  * 格式化错误为 MCP 工具响应
  * 特别处理 ZodError，转换为结构化的 INVALID_ARGUMENT 错误
@@ -121,4 +109,13 @@ export declare function formatErrorResponse(error: unknown): {
     }>;
     isError: boolean;
 };
+/**
+ * 格式化成功响应为 MCP 工具响应
+ */
+export declare function formatResponse(data: unknown): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
 //# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,YAAY,CAAA;AAEtC;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,8BAAsB,YAAa,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAK;IAEnC,SAAS,aAAa,OAAO,EAAE,MAAM;IAKrC;;OAEG;IAEH,MAAM,IAAI,MAAM;CAsBnB;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IACpD,QAAQ,CAAC,IAAI,wBAAuB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,SAAkB,OAAO,EAAE,YAAY,CAAA;gBAE3B,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAQzC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IAClD,QAAQ,CAAC,IAAI,uBAA4B;IACzC,QAAQ,CAAC,UAAU,6KACqC;;CAK3D;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IAClD,QAAQ,CAAC,IAAI,uBAA4B;IACzC,QAAQ,CAAC,UAAU,yHACyD;;CAK/E;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACjD,QAAQ,CAAC,IAAI,sBAA2B;IACxC,QAAQ,CAAC,UAAU,qFAAqC;IACxD,SAAkB,OAAO,EAAE,YAAY,CAAA;gBAE3B,QAAQ,EAAE,MAAM;CAI/B;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IAClD,QAAQ,CAAC,IAAI,uBAAsB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;IACvB,SAAkB,OAAO,EAAE,YAAY,CAAA;gBAE3B,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,EAAE,GAAG,CAAC,EAAE,MAAM;IAUrE,MAAM,IAAI,MAAM;CAkB5B;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IACpD,QAAQ,CAAC,IAAI,wBAA6B;IAC1C,QAAQ,CAAC,UAAU,gGAAoB;IACvC,SAAkB,OAAO,EAAE,YAAY,CAAA;gBAE3B,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI3C;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAC1C,QAAQ,CAAC,IAAI,aAAkB;IAC/B,QAAQ,CAAC,UAAU,8HAAyB;gBAEhC,OAAO,EAAE,MAAM;CAG9B;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,YAAY;IACtC,QAAQ,CAAC,IAAI,eAAoB;IACjC,QAAQ,CAAC,UAAU,uHAA4B;gBAEnC,OAAO,EAAE,MAAM;CAG9B;AA8CD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG;IACjD,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,OAAO,CAAC;CACpB,CAsDA;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG;IAC3C,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD,CAIA"}

package/dist/core/errors.js

@@ -19,6 +19,7 @@ export class BrowserError extends Error {
     /**
      * 转换为 JSON 格式，用于 MCP 响应
      */
+    // noinspection JSUnusedGlobalSymbols — 被 formatErrorResponse 动态调用
     toJSON() {
         const result = {
             error: {
@@ -139,17 +140,6 @@ export class TimeoutError extends BrowserError {
         super(message);
     }
 }
-/**
- * 无效参数错误
- */
-export class InvalidArgumentError extends BrowserError {
-    code = 'INVALID_ARGUMENT';
-    suggestion;
-    constructor(message, suggestion) {
-        super(message);
-        this.suggestion = suggestion ?? '请检查参数是否正确';
-    }
-}
 /**
  * CDP 协议错误
  */
@@ -160,19 +150,6 @@ export class CDPError extends BrowserError {
         super(message);
     }
 }
-/**
- * 格式化日志记录（参考 Playwright Waiter）
- */
-export function formatLogRecording(logs) {
-    if (logs.length === 0) {
-        return '';
-    }
-    const header = ' logs ';
-    const width = 60;
-    const leftPad = '='.repeat(Math.floor((width - header.length) / 2));
-    const rightPad = '='.repeat(width - header.length - leftPad.length);
-    return `\n${leftPad}${header}${rightPad}\n${logs.join('\n')}\n${'='.repeat(width)}`;
-}
 /**
  * ZodError 类型检测
  */
@@ -189,7 +166,16 @@ function isZodError(error) {
  */
 function detectVisibilityHint(errorMessage) {
     const msg = errorMessage.toLowerCase();
-    const keywords = ['hidden', 'visible', 'visibility', 'focus', 'blur', 'active tab', 'not active', 'capturevisibletab'];
+    const keywords = [
+        'hidden',
+        'visible',
+        'visibility',
+        'focus',
+        'blur',
+        'active tab',
+        'not active',
+        'capturevisibletab',
+    ];
     if (keywords.some(kw => msg.includes(kw))) {
         return '此操作可能需要 tab 在前台。请使用 browse(action="attach", targetId="<id>", activate=true) 激活目标 tab';
     }
@@ -248,4 +234,12 @@ export function formatErrorResponse(error) {
         isError: true,
     };
 }
+/**
+ * 格式化成功响应为 MCP 工具响应
+ */
+export function formatResponse(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
 //# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH;;GAEG;AACH,MAAM,OAAgB,YAAa,SAAQ,KAAK;IAGnC,OAAO,GAAiB,EAAE,CAAA;IAEnC,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAA;IACrC,CAAC;IAED;;OAEG;IACH,MAAM;QACF,MAAM,MAAM,GAOR;YACA,KAAK,EAAE;gBACH,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,UAAU,EAAE,IAAI,CAAC,UAAU;aAC9B;SACJ,CAAA;QAED,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;QACvC,CAAC;QAED,OAAO,MAAM,CAAA;IACjB,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,YAAY;IAC3C,IAAI,GAAG,oBAAoB,CAAA;IAC3B,UAAU,CAAQ;IACT,OAAO,CAAc;IAEvC,YAAY,IAAY,EAAE,IAAY;QAClC,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,CAAA;QAC9B,IAAI,CAAC,UAAU,GAAG;0CACgB,IAAI;;mDAEK,CAAA;QAC3C,IAAI,CAAC,OAAO,GAAM,EAAC,IAAI,EAAE,IAAI,EAAC,CAAA;IAClC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACzC,IAAI,GAAS,mBAAmB,CAAA;IAChC,UAAU,GAAG;4DACkC,CAAA;IAExD;QACI,KAAK,CAAC,gBAAgB,CAAC,CAAA;IAC3B,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACzC,IAAI,GAAS,mBAAmB,CAAA;IAChC,UAAU,GACN,+DAA+D,CAAA;IAE5E;QACI,KAAK,CAAC,UAAU,CAAC,CAAA;IACrB,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACxC,IAAI,GAAS,kBAAkB,CAAA;IAC/B,UAAU,GAAG,kCAAkC,CAAA;IACtC,OAAO,CAAc;IAEvC,YAAY,QAAgB;QACxB,KAAK,CAAC,UAAU,QAAQ,EAAE,CAAC,CAAA;QAC3B,IAAI,CAAC,OAAO,GAAG,EAAC,QAAQ,EAAC,CAAA;IAC7B,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACzC,IAAI,GAAG,mBAAmB,CAAA;IAC1B,UAAU,CAAQ;IAClB,IAAI,CAAU;IACL,OAAO,CAAc;IAEvC,YAAY,MAAc,EAAE,OAAe,EAAE,OAAiB,EAAE,EAAE,GAAY;QAC1E,KAAK,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACzC,IAAI,CAAC,UAAU,GAAG,mCAAmC,OAAO,KAAK,CAAA;QACjE,IAAI,CAAC,IAAI,GAAS,IAAI,CAAA;QACtB,IAAI,CAAC,OAAO,GAAM,EAAC,MAAM,EAAE,OAAO,EAAC,CAAA;QACnC,IAAI,GAAG,EAAE,CAAC;YACN,IAAI,CAAC,OAAO,CAAC,GAAG,GAAG,GAAG,CAAA;QAC1B,CAAC;IACL,CAAC;IAEQ,MAAM;QACX,uBAAuB;QACvB,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;QAC1C,MAAM,OAAO,GAAM,EAAE,CAAA;QACrB,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,GAAG,OAAO;YAC3B,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,SAAS,UAAU,CAAC,MAAM,SAAS,CAAC;YACxE,CAAC,CAAC,UAAU,CAAA;QAE/B,OAAO;YACH,KAAK,EAAE;gBACH,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,IAAI,EAAE,UAAU;aACnB;SACJ,CAAA;IACL,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,YAAY;IAC3C,IAAI,GAAS,oBAAoB,CAAA;IACjC,UAAU,GAAG,iBAAiB,CAAA;IACrB,OAAO,CAAc;IAEvC,YAAY,GAAW,EAAE,OAAe;QACpC,KAAK,CAAC,SAAS,GAAG,KAAK,OAAO,KAAK,CAAC,CAAA;QACpC,IAAI,CAAC,OAAO,GAAG,EAAC,GAAG,EAAE,OAAO,EAAC,CAAA;IACjC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,YAAY;IACjC,IAAI,GAAS,SAAS,CAAA;IACtB,UAAU,GAAG,sBAAsB,CAAA;IAE5C,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAA;IAClB,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACzC,IAAI,GAAG,kBAAkB,CAAA;IACzB,UAAU,CAAQ;IAE3B,YAAY,OAAe,EAAE,UAAmB;QAC5C,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,UAAU,GAAG,UAAU,IAAI,WAAW,CAAA;IAC/C,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,YAAY;IAC7B,IAAI,GAAS,WAAW,CAAA;IACxB,UAAU,GAAG,yBAAyB,CAAA;IAE/C,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAA;IAClB,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC7C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,CAAA;IACb,CAAC;IACD,MAAM,MAAM,GAAK,QAAQ,CAAA;IACzB,MAAM,KAAK,GAAM,EAAE,CAAA;IACnB,MAAM,OAAO,GAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACpE,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE,OAAO,KAAK,OAAO,GAAG,MAAM,GAAG,QAAQ,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;AACvF,CAAC;AAWD;;GAEG;AACH,SAAS,UAAU,CAAC,KAAc;IAC9B,OAAO,CACH,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,IAAI,KAAK;QACd,KAAe,CAAC,IAAI,KAAK,UAAU;QACpC,QAAQ,IAAI,KAAK;QACjB,KAAK,CAAC,OAAO,CAAE,KAA6B,CAAC,MAAM,CAAC,CACvD,CAAA;AACL,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,YAAoB;IAC9C,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,EAAE,CAAA;IACtC,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,CAAC,CAAA;IACtH,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACxC,OAAO,sFAAsF,CAAA;IACjG,CAAC;IACD,OAAO,IAAI,CAAA;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAI9C,cAAc;IACd,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC7C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI;SACnB,CAAC,CAAC,CAAA;QACH,OAAO;YACH,OAAO,EAAE;gBACL;oBACI,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAChB;wBACI,KAAK,EAAE;4BACH,IAAI,EAAE,kBAAkB;4BACxB,OAAO,EAAE,QAAQ;4BACjB,MAAM,EAAE,WAAW;yBACtB;qBACJ,EACD,IAAI,EACJ,CAAC,CACJ;iBACJ;aACJ;YACD,OAAO,EAAE,IAAI;SAChB,CAAA;IACL,CAAC;IAED,+BAA+B;IAC/B,MAAM,GAAG,GAAG,KAA0C,CAAA;IACtD,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,EAAE,IAAI;QAChC,KAAK,EAAE;YACH,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC;SACxC;KACJ,CAAA;IAED,6BAA6B;IAC7B,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAA;IACjD,MAAM,IAAI,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAA;IAC/C,IAAI,IAAI,EAAE,CAAC;QACN,SAAqC,CAAC,IAAI,GAAG,IAAI,CAAA;IACtD,CAAC;IAED,OAAO;QACH,OAAO,EAAE;YACL;gBACI,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;aAC3C;SACJ;QACD,OAAO,EAAE,IAAI;KAChB,CAAA;AACL,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/core/locator.d.ts

@@ -24,6 +24,8 @@ type NodeId = number;
 export interface LocatorOptions {
     /** 超时时间（毫秒），默认 30000 */
     timeout?: number;
+    /** 第 N 个匹配元素（从 0 开始，默认 0 即第一个） */
+    nth?: number;
     /** 获取当前 URL 的回调（用于错误上下文） */
     getUrl?: () => string | undefined;
 }
@@ -35,9 +37,10 @@ export declare class Locator {
     private target;
     private sessionId?;
     private logs;
-    private timeout;
-    private deadline;
-    private getUrl?;
+    private readonly timeout;
+    private readonly deadline;
+    private readonly nth;
+    private readonly getUrl?;
     constructor(cdp: CDPClient, target: Target, sessionId?: string | undefined, options?: LocatorOptions);
     /**
      * 查找元素，返回节点 ID（带重试）
@@ -58,10 +61,6 @@ export declare class Locator {
      * @returns 函数返回值
      */
     evaluateOn<T>(fn: string): Promise<T>;
-    /**
-     * 获取定位日志
-     */
-    getLogs(): string[];
     /**
      * 查找元素的内部实现（单次尝试）
      */

package/dist/core/locator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locator.d.ts","sourceRoot":"","sources":["../../src/core/locator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,kBAAkB,CAAA;AAG/C,OAAO,EACH,KAAK,GAAG,EAYR,KAAK,KAAK,EACV,KAAK,MAAM,EACd,MAAM,YAAY,CAAA;AAEnB;;GAEG;AACH,KAAK,MAAM,GAAG,MAAM,CAAC;AAOrB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CACrC;AA2DD;;GAEG;AACH,qBAAa,OAAO;IAOZ,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,SAAS,CAAC;IARtB,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,MAAM,CAAC,CAA0B;gBAG7B,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,YAAA,EAC1B,OAAO,GAAE,cAAmB;IAOhC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAY7B;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,KAAK,CAAC;IAczC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IASpC;;;;;OAKG;IACG,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IA6B3C;;OAEG;IACH,OAAO,IAAI,MAAM,EAAE;IAInB;;OAEG;YACW,YAAY;IAoC1B;;OAEG;YACW,mBAAmB;IAwCjC;;OAEG;YACW,UAAU;IAiBxB;;OAEG;YACW,WAAW;IA2DzB;;OAEG;YACW,iBAAiB;IAe/B;;OAEG;YACW,WAAW;IAazB;;OAEG;YACW,SAAS;IAavB;;OAEG;YACW,YAAY;IAQ1B;;OAEG;YACW,SAAS;IAOvB;;OAEG;YACW,gBAAgB;IAgC9B;;OAEG;YACW,WAAW;IAOzB;;OAEG;YACW,iBAAiB;IAoB/B;;OAEG;YACW,mBAAmB;IAejC;;OAEG;YACW,gBAAgB;IAgB9B;;OAEG;YACW,WAAW;IAgBzB;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IAIZ;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,GAAG;CAGd"}
+{"version":3,"file":"locator.d.ts","sourceRoot":"","sources":["../../src/core/locator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,kBAAkB,CAAA;AAG/C,OAAO,EACH,KAAK,GAAG,EAaR,KAAK,KAAK,EACV,KAAK,MAAM,EACd,MAAM,YAAY,CAAA;AAEnB;;GAEG;AACH,KAAK,MAAM,GAAG,MAAM,CAAC;AAOrB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CACrC;AAyDD;;GAEG;AACH,qBAAa,OAAO;IAQZ,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,SAAS,CAAC;IATtB,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAA0B;gBAGtC,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,YAAA,EAC1B,OAAO,GAAE,cAAmB;IAQhC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAY7B;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,KAAK,CAAC;IAczC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IASpC;;;;;OAKG;IACG,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IA6B3C;;OAEG;YACW,YAAY;IAoC1B;;OAEG;YACW,mBAAmB;IA+CjC;;OAEG;YACW,UAAU;IAiBxB;;OAEG;YACW,WAAW;IAsEzB;;OAEG;YACW,iBAAiB;IAiB/B;;OAEG;YACW,WAAW;IAazB;;OAEG;YACW,SAAS;IAavB;;OAEG;YACW,YAAY;IAQ1B;;OAEG;YACW,SAAS;IAOvB;;OAEG;YACW,gBAAgB;IAqC9B;;OAEG;YACW,WAAW;IAOzB;;OAEG;YACW,iBAAiB;IAoC/B;;OAEG;YACW,mBAAmB;IAgCjC;;OAEG;YACW,gBAAgB;IAgB9B;;OAEG;YACW,WAAW;IAgBzB;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IAIZ;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,GAAG;CAGd"}

package/dist/core/locator.js

@@ -14,8 +14,7 @@
  */
 import { ElementNotFoundError } from './errors.js';
 import { withRetry } from './retry.js';
-import { isAltTarget, isCoordinateTarget, isCSSTarget, isCSSTextTarget, isLabelTarget, isPlaceholderTarget, isRoleTarget, isTestIdTarget, isTextTarget, isTitleTarget, isXPathTarget, } from './types.js';
-const DEFAULT_TIMEOUT = 30000;
+import { DEFAULT_TIMEOUT, isAltTarget, isCoordinateTarget, isCSSTarget, isCSSTextTarget, isLabelTarget, isPlaceholderTarget, isRoleTarget, isTestIdTarget, isTextTarget, isTitleTarget, isXPathTarget, } from './types.js';
 /**
  * 转义 XPath 字符串中的引号
  * XPath 1.0 没有转义机制，需要用 concat() 拼接单双引号
@@ -79,6 +78,7 @@ export class Locator {
     logs = [];
     timeout;
     deadline;
+    nth;
     getUrl;
     constructor(cdp, target, sessionId, options = {}) {
         this.cdp = cdp;
@@ -86,6 +86,7 @@ export class Locator {
         this.sessionId = sessionId;
         this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
         this.deadline = Date.now() + this.timeout;
+        this.nth = options.nth ?? 0;
         this.getUrl = options.getUrl;
     }
     /**
@@ -150,12 +151,6 @@ export class Locator {
         }
         return result.value;
     }
-    /**
-     * 获取定位日志
-     */
-    getLogs() {
-        return this.logs;
-    }
     /**
      * 查找元素的内部实现（单次尝试）
      */
@@ -198,12 +193,13 @@ export class Locator {
      */
     async findByAccessibility() {
         const { role, name } = this.target;
-        this.log(`使用可访问性树定位: role=${role}, name=${name ?? '(any)'}`);
+        this.log(`使用可访问性树定位: role=${role}, name=${name ?? '(any)'}${this.nth > 0 ? `, nth=${this.nth}` : ''}`);
         // 启用可访问性
         await this.send('Accessibility.enable');
         // 获取整个可访问性树
         const { nodes } = (await this.send('Accessibility.getFullAXTree'));
-        // 查找匹配的节点
+        // 查找匹配的节点，跳过前 nth 个
+        let matchCount = 0;
         for (const node of nodes) {
             if (node.role?.value?.toLowerCase() !== role.toLowerCase()) {
                 continue;
@@ -212,7 +208,13 @@ export class Locator {
                 continue;
             }
             if (node.backendDOMNodeId) {
-                this.log(`找到元素: backendDOMNodeId=${node.backendDOMNodeId}`);
+                if (matchCount < this.nth) {
+                    ++matchCount;
+                    continue;
+                }
+                this.log(`找到元素: backendDOMNodeId=${node.backendDOMNodeId}${this.nth > 0 ?
+                    `（第 ${this.nth} 个）` :
+                    ''}`);
                 // 将 backendDOMNodeId 转换为 nodeId
                 const { nodeIds } = (await this.send('DOM.pushNodesByBackendIdsToFrontend', {
                     backendNodeIds: [node.backendDOMNodeId],
@@ -229,7 +231,7 @@ export class Locator {
      */
     async findByText() {
         const { text, exact = false } = this.target;
-        this.log(`使用文本内容定位: text=${text}, exact=${exact}`);
+        this.log(`使用文本内容定位: text=${text}, exact=${exact}${this.nth > 0 ? `, nth=${this.nth}` : ''}`);
         // 使用 XPath 查找包含文本的元素（正确转义引号）
         // 用 . 而非 text()：text() 只匹配直接子文本节点，. 匹配完整 textContent
         const escapedText = escapeXPathString(text);
@@ -243,7 +245,7 @@ export class Locator {
      */
     async findByLabel() {
         const { label, exact = false } = this.target;
-        this.log(`使用 label 定位: label=${label}, exact=${exact}`);
+        this.log(`使用 label 定位: label=${label}, exact=${exact}${this.nth > 0 ? `, nth=${this.nth}` : ''}`);
         // 转义 JS 字符串
         const escapedLabel = escapeJSString(label);
         // 使用 Runtime.evaluate 执行复杂查询
@@ -252,34 +254,45 @@ export class Locator {
         (function() {
           const targetLabel = "${escapedLabel}";
           const isExact = ${exact};
+          const nth = ${this.nth};
           const labels = document.querySelectorAll('label');
+          let matchCount = 0;
           for (const label of labels) {
             const text = label.textContent?.trim() ?? '';
             const match = isExact ? text === targetLabel : text.includes(targetLabel);
             if (match) {
+              let found = null;
               // 1. 通过 for 属性找关联元素
               if (label.htmlFor) {
                 const input = document.getElementById(label.htmlFor);
-                if (input) return input;
+                if (input) found = input;
               }
               // 2. 找 label 内部的 input
-              const inner = label.querySelector('input, select, textarea');
-              if (inner) return inner;
+              if (!found) {
+                const inner = label.querySelector('input, select, textarea');
+                if (inner) found = inner;
+              }
               // 3. 通过 label.id 推断（如 userName-label → #userName）
-              if (label.id && label.id.endsWith('-label')) {
+              if (!found && label.id && label.id.endsWith('-label')) {
                 const inputId = label.id.slice(0, -6);
                 const input = document.getElementById(inputId);
-                if (input) return input;
+                if (input) found = input;
               }
               // 4. 在父元素的相邻兄弟中查找 input
-              const parent = label.parentElement;
-              if (parent) {
-                for (const sibling of parent.parentElement?.children ?? []) {
-                  if (sibling === parent) continue;
-                  const input = sibling.querySelector('input, select, textarea');
-                  if (input) return input;
+              if (!found) {
+                const parent = label.parentElement;
+                if (parent) {
+                  for (const sibling of parent.parentElement?.children ?? []) {
+                    if (sibling === parent) continue;
+                    const input = sibling.querySelector('input, select, textarea');
+                    if (input) { found = input; break; }
+                  }
                 }
               }
+              if (found) {
+                if (matchCount < nth) { ++matchCount; continue; }
+                return found;
+              }
             }
           }
           return null;
@@ -297,7 +310,9 @@ export class Locator {
      */
     async findByPlaceholder() {
         const { placeholder, exact = false } = this.target;
-        this.log(`使用 placeholder 定位: placeholder=${placeholder}, exact=${exact}`);
+        this.log(`使用 placeholder 定位: placeholder=${placeholder}, exact=${exact}${this.nth > 0 ?
+            `, nth=${this.nth}` :
+            ''}`);
         const escaped = escapeCSSAttributeValue(placeholder);
         const css = exact
             ? `[placeholder="${escaped}"]`
@@ -309,7 +324,7 @@ export class Locator {
      */
     async findByTitle() {
         const { title, exact = false } = this.target;
-        this.log(`使用 title 属性定位: title=${title}, exact=${exact}`);
+        this.log(`使用 title 属性定位: title=${title}, exact=${exact}${this.nth > 0 ? `, nth=${this.nth}` : ''}`);
         const escaped = escapeCSSAttributeValue(title);
         const css = exact ? `[title="${escaped}"]` : `[title*="${escaped}"]`;
         return this.findByCSSInternal(css);
@@ -319,7 +334,7 @@ export class Locator {
      */
     async findByAlt() {
         const { alt, exact = false } = this.target;
-        this.log(`使用 alt 属性定位: alt=${alt}, exact=${exact}`);
+        this.log(`使用 alt 属性定位: alt=${alt}, exact=${exact}${this.nth > 0 ? `, nth=${this.nth}` : ''}`);
         const escaped = escapeCSSAttributeValue(alt);
         const css = exact ? `[alt="${escaped}"]` : `[alt*="${escaped}"]`;
         return this.findByCSSInternal(css);
@@ -329,7 +344,7 @@ export class Locator {
      */
     async findByTestId() {
         const { testId } = this.target;
-        this.log(`使用 data-testid 定位: testId=${testId}`);
+        this.log(`使用 data-testid 定位: testId=${testId}${this.nth > 0 ? `, nth=${this.nth}` : ''}`);
         const escaped = escapeCSSAttributeValue(testId);
         return this.findByCSSInternal(`[data-testid="${escaped}"]`);
     }
@@ -346,7 +361,9 @@ export class Locator {
      */
     async findByCSSAndText() {
         const { css, text, exact = false } = this.target;
-        this.log(`使用 CSS+text 组合定位: css=${css}, text=${text}, exact=${exact}`);
+        this.log(`使用 CSS+text 组合定位: css=${css}, text=${text}, exact=${exact}${this.nth > 0 ?
+            `, nth=${this.nth}` :
+            ''}`);
         const escapedCSS = escapeJSString(css);
         const escapedText = escapeJSString(text);
         const { result } = (await this.send('Runtime.evaluate', {
@@ -355,9 +372,12 @@ export class Locator {
           const elements = document.querySelectorAll("${escapedCSS}");
           const target = "${escapedText}";
           const isExact = ${exact};
+          const nth = ${this.nth};
+          let matchCount = 0;
           for (const el of elements) {
             const content = (el.textContent ?? '').trim();
             if (isExact ? content === target : content.includes(target)) {
+              if (matchCount < nth) { ++matchCount; continue; }
               return el;
             }
           }
@@ -385,6 +405,19 @@ export class Locator {
     async findByCSSInternal(css) {
         // 确保 DOM 已启用
         const { root } = (await this.send('DOM.getDocument'));
+        if (this.nth > 0) {
+            // nth > 0：用 querySelectorAll 取第 nth 个
+            const { nodeIds } = (await this.send('DOM.querySelectorAll', {
+                nodeId: root.nodeId,
+                selector: css,
+            }));
+            if (this.nth >= nodeIds.length) {
+                this.log(`第 ${this.nth} 个匹配元素不存在（共 ${nodeIds.length} 个）: ${css}`);
+                throw new ElementNotFoundError(this.target, this.timeout, this.logs, this.getUrl?.());
+            }
+            this.log(`找到元素: nodeId=${nodeIds[this.nth]}（第 ${this.nth} 个）`);
+            return nodeIds[this.nth];
+        }
         const { nodeId } = (await this.send('DOM.querySelector', {
             nodeId: root.nodeId,
             selector: css,
@@ -400,9 +433,22 @@ export class Locator {
      * XPath 定位内部实现
      */
     async findByXPathInternal(xpath) {
+        const escapedXPath = escapeJSString(xpath);
+        if (this.nth > 0) {
+            // nth > 0：用 ORDERED_NODE_SNAPSHOT_TYPE 取第 nth 个
+            const { result } = (await this.send('Runtime.evaluate', {
+                expression: `(function() { var r = document.evaluate('${escapedXPath}', document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null); return r.snapshotLength > ${this.nth} ? r.snapshotItem(${this.nth}) : null })()`,
+                returnByValue: false,
+            }));
+            if (!result.objectId || result.subtype === 'null') {
+                this.log(`第 ${this.nth} 个匹配元素不存在: ${xpath}`);
+                throw new ElementNotFoundError(this.target, this.timeout, this.logs, this.getUrl?.());
+            }
+            return this.objectIdToNodeId(result.objectId);
+        }
         // 使用 Runtime.evaluate 执行 XPath
         const { result } = (await this.send('Runtime.evaluate', {
-            expression: `document.evaluate('${escapeJSString(xpath)}', document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue`,
+            expression: `document.evaluate('${escapedXPath}', document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue`,
             returnByValue: false,
         }));
         if (!result.objectId) {
@@ -432,7 +478,7 @@ export class Locator {
     async getBoxModel(nodeId) {
         const { model } = (await this.send('DOM.getBoxModel', { nodeId }));
         // content 是 [x1,y1, x2,y2, x3,y3, x4,y4] 格式的四个角坐标
-        const [x1, y1, x2, , , , x4, y4] = model.content;
+        const [x1, y1, x2, , , , , y4] = model.content;
         return {
             x: x1,
             y: y1,