@pyrokine/mcp-chrome 1.1.0 → 1.4.0

package/dist/tools/extract.js

@@ -3,80 +3,44 @@
  *
  * 提取页面内容：
  * - text: 文本内容
- * - html: HTML 源码
+ * - html: HTML 源码（可选附带图片元信息或图片数据）
  * - attribute: 元素属性
  * - screenshot: 截图
  * - state: 页面状态（精简的可交互元素列表）
+ * - metadata: 页面元信息（title/og/jsonLd 等）
  */
-import { writeFile } from 'fs/promises';
+import { mkdir, writeFile } from 'fs/promises';
+import { basename, dirname, extname, join } from 'path';
 import { z } from 'zod';
-import { formatErrorResponse, getSession, getUnifiedSession } from '../core/index.js';
-import { targetJsonSchema, targetToFindParams, targetZodSchema } from './schema.js';
-/**
- * extract 工具定义
- */
-export const extractToolDefinition = {
-    name: 'extract',
-    description: '提取页面内容：文本、HTML、属性、截图、状态',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            type: {
-                type: 'string',
-                enum: ['text', 'html', 'attribute', 'screenshot', 'state'],
-                description: '提取类型',
-            },
-            target: {
-                ...targetJsonSchema,
-                description: '目标元素（attribute 必填；text/html 可选，省略则提取整个页面；screenshot/state 不需要）',
-            },
-            attribute: {
-                type: 'string',
-                description: '属性名（attribute）',
-            },
-            fullPage: {
-                type: 'boolean',
-                description: '是否全页面截图（screenshot）',
-            },
-            output: {
-                type: 'string',
-                description: '输出文件路径（可选）。若指定，结果写入文件；否则返回内容',
-            },
-            tabId: {
-                type: 'string',
-                description: '目标 Tab ID（可选，仅 Extension 模式）。不指定则使用当前 attach 的 tab。可操作非当前 attach 的 tab。CDP 模式下忽略此参数',
-            },
-            timeout: {
-                type: 'number',
-                description: '等待目标元素超时',
-            },
-            frame: {
-                oneOf: [{ type: 'string' }, { type: 'number' }],
-                description: 'iframe 定位（可选，仅 Extension 模式）。CSS 选择器（如 "iframe#main"）或索引（如 0）。不指定则在主框架操作',
-            },
-        },
-        required: ['type'],
-    },
-};
+import { formatErrorResponse, formatResponse, getSession, getUnifiedSession } from '../core/index.js';
+import { targetToFindParams, targetZodSchema } from './schema.js';
+/** 无 output 时附录返回的最大图片数 */
+const MAX_APPENDIX_IMAGES = 20;
 /**
  * extract 参数 schema
  */
 const extractSchema = z.object({
-    type: z.enum(['text', 'html', 'attribute', 'screenshot', 'state']),
-    target: targetZodSchema.optional(),
-    attribute: z.string().optional(),
-    fullPage: z.boolean().optional(),
-    output: z.string().optional(),
-    tabId: z.string().optional(),
-    timeout: z.number().optional(),
-    frame: z.union([z.string(), z.number()]).optional(),
+    type: z.enum(['text', 'html', 'attribute', 'screenshot', 'state', 'metadata'])
+        .describe('提取类型'),
+    target: targetZodSchema.optional().describe('目标元素（attribute 必填；text/html 可选，省略则提取整个页面；screenshot/state/metadata 不需要）'),
+    attribute: z.string().optional().describe('属性名（attribute）'),
+    images: z.enum(['info', 'data']).optional().describe('图片提取模式（仅 html 类型有效）。info: 元信息（src/alt/尺寸）；data: 含图片数据'),
+    fullPage: z.boolean().optional().describe('是否全页面截图（screenshot）'),
+    scale: z.number().optional().describe('截图缩放比例（screenshot fullPage）。默认 1，设为 0.5 可降低分辨率加速大页面截图'),
+    format: z.enum(['png', 'jpeg', 'webp']).optional().describe('截图格式（screenshot）。默认 png，jpeg/webp 体积更小，复杂页面推荐 jpeg 减少超时'),
+    quality: z.number().min(0).max(100).optional().describe('截图质量（screenshot，仅 jpeg/webp 有效）。0-100，推荐 80'),
+    output: z.string()
+        .optional()
+        .describe('输出文件路径（可选）。若指定，结果写入文件；否则返回内容。images=data 时作为输出目录路径'),
+    tabId: z.string().optional().describe('目标 Tab ID（可选，仅 Extension 模式）。不指定则使用当前 attach 的 tab。可操作非当前 attach 的 tab。CDP 模式下忽略此参数'),
+    timeout: z.number().optional().describe('等待目标元素超时'),
+    frame: z.union([z.string(), z.number()]).optional().describe('iframe 定位（可选，仅 Extension 模式）。CSS 选择器（如 "iframe#main"）或索引（如 0）。不指定则在主框架操作'),
 });
 /**
  * extract 工具处理器
  */
-export async function handleExtract(params) {
+async function handleExtract(args) {
     try {
-        const args = extractSchema.parse(params);
         const unifiedSession = getUnifiedSession();
         const useExtension = unifiedSession.isExtensionConnected();
         const session = getSession();
@@ -93,66 +57,43 @@ export async function handleExtract(params) {
                             ? await extractTextExtension(unifiedSession, args.target)
                             : await extractText(session, args.target, args.timeout);
                         if (args.output) {
-                            await writeFile(args.output, text, 'utf-8');
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            success: true,
-                                            type: 'text',
-                                            output: args.output,
-                                            size: text.length,
-                                        }),
-                                    },
-                                ],
-                            };
+                            await writeOutputFile(args.output, text, 'utf-8');
+                            return formatResponse({
+                                success: true,
+                                type: 'text',
+                                output: args.output,
+                                size: text.length,
+                            });
                         }
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        success: true,
-                                        type: 'text',
-                                        content: text,
-                                    }),
-                                },
-                            ],
-                        };
+                        return formatResponse({
+                            success: true,
+                            type: 'text',
+                            content: text,
+                        });
                     }
                     case 'html': {
+                        // 带图片提取的增强路径
+                        if (args.images) {
+                            return await handleHtmlWithImages(unifiedSession, session, useExtension, args);
+                        }
+                        // 原有路径：纯 HTML
                         const html = useExtension
                             ? await extractHtmlExtension(unifiedSession, args.target)
                             : await extractHTML(session, args.target, args.timeout);
                         if (args.output) {
-                            await writeFile(args.output, html, 'utf-8');
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            success: true,
-                                            type: 'html',
-                                            output: args.output,
-                                            size: html.length,
-                                        }),
-                                    },
-                                ],
-                            };
+                            await writeOutputFile(args.output, html, 'utf-8');
+                            return formatResponse({
+                                success: true,
+                                type: 'html',
+                                output: args.output,
+                                size: html.length,
+                            });
                         }
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        success: true,
-                                        type: 'html',
-                                        content: html,
-                                    }),
-                                },
-                            ],
-                        };
+                        return formatResponse({
+                            success: true,
+                            type: 'html',
+                            content: html,
+                        });
                     }
                     case 'attribute': {
                         if (!args.target) {
@@ -194,37 +135,106 @@ export async function handleExtract(params) {
                         else {
                             value = await extractAttribute(session, args.target, args.attribute, args.timeout);
                         }
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        success: true,
-                                        type: 'attribute',
-                                        attribute: args.attribute,
-                                        value,
-                                    }),
-                                },
-                            ],
-                        };
+                        return formatResponse({
+                            success: true,
+                            type: 'attribute',
+                            attribute: args.attribute,
+                            value,
+                        });
                     }
                     case 'screenshot': {
-                        const base64 = await unifiedSession.screenshot({ fullPage: args.fullPage ?? false });
+                        // 有 target 时获取元素区域用于裁剪（支持所有 target 类型）
+                        let clip;
+                        if (args.target) {
+                            if (useExtension) {
+                                const { selector, text, xpath, nth: nthParam } = targetToFindParams(args.target);
+                                const nth = nthParam ?? 0;
+                                const found = await unifiedSession.find(selector, text, xpath);
+                                if (found.length > nth) {
+                                    const rect = found[nth].rect;
+                                    if (rect.width > 0 && rect.height > 0) {
+                                        // find() 返回视口绝对坐标（已包含 iframe 坐标修正）
+                                        clip = rect;
+                                    }
+                                }
+                            }
+                            else {
+                                const { selector, text, xpath, nth: nthParam } = targetToFindParams(args.target);
+                                const nth = nthParam ?? 0;
+                                const rect = await session.evaluate(`function(selector, text, xpath, nth) {
+                                        function toRect(el) {
+                                            var r = el.getBoundingClientRect();
+                                            return {x: r.x, y: r.y, width: r.width, height: r.height};
+                                        }
+
+                                        function findByXPath(xp, n) {
+                                            var r = document.evaluate(xp, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+                                            return r.snapshotLength > n ? r.snapshotItem(n) : null;
+                                        }
+
+                                        function findBySelector(sel, txt, n) {
+                                            var els = document.querySelectorAll(sel);
+                                            var matchCount = 0;
+                                            for (var i = 0; i < els.length; ++i) {
+                                                var el = els[i];
+                                                if (txt) {
+                                                    var content = (el.textContent || '').trim();
+                                                    if (!content.includes(txt)) continue;
+                                                }
+                                                if (matchCount < n) { ++matchCount; continue; }
+                                                return el;
+                                            }
+                                            return null;
+                                        }
+
+                                        function findByText(txt, n) {
+                                            var root = document.body || document.documentElement;
+                                            if (!root) return null;
+                                            var walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+                                            var matchCount = 0;
+                                            var el = walker.currentNode;
+                                            while (el) {
+                                                var content = (el.textContent || '').trim();
+                                                if (content && content.includes(txt)) {
+                                                    if (matchCount < n) { ++matchCount; }
+                                                    else { return el; }
+                                                }
+                                                el = walker.nextNode();
+                                            }
+                                            return null;
+                                        }
+
+                                        var el = null;
+                                        if (xpath) {
+                                            el = findByXPath(xpath, nth);
+                                        } else if (selector) {
+                                            el = findBySelector(selector, text, nth);
+                                        } else if (text) {
+                                            el = findByText(text, nth);
+                                        }
+
+                                        return el ? toRect(el) : null;
+                                    }`, [selector ?? null, text ?? null, xpath ?? null, nth]);
+                                if (rect && rect.width > 0 && rect.height > 0) {
+                                    clip = rect;
+                                }
+                            }
+                        }
+                        const base64 = await unifiedSession.screenshot({
+                            fullPage: clip ? false : (args.fullPage ?? false),
+                            scale: args.scale,
+                            format: args.format,
+                            quality: args.quality,
+                            clip,
+                        });
                         if (args.output) {
                             // 写入文件
-                            await writeFile(args.output, Buffer.from(base64, 'base64'));
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            success: true,
-                                            type: 'screenshot',
-                                            output: args.output,
-                                        }),
-                                    },
-                                ],
-                            };
+                            await writeOutputFile(args.output, Buffer.from(base64, 'base64'));
+                            return formatResponse({
+                                success: true,
+                                type: 'screenshot',
+                                output: args.output,
+                            });
                         }
                         // 返回 base64 图片
                         return {
@@ -232,40 +242,52 @@ export async function handleExtract(params) {
                                 {
                                     type: 'image',
                                     data: base64,
-                                    mimeType: 'image/png',
+                                    mimeType: `image/${args.format === 'jpeg' ? 'jpeg' : args.format ?? 'png'}`,
                                 },
                             ],
                         };
                     }
                     case 'state': {
-                        const state = await unifiedSession.readPage();
+                        // 有 target 时获取子树的无障碍状态
+                        let refId;
+                        if (args.target && useExtension) {
+                            const { selector, text, xpath, nth: nthParam } = targetToFindParams(args.target);
+                            const nth = nthParam ?? 0;
+                            const elements = await unifiedSession.find(selector, text, xpath);
+                            if (elements.length > 0 && nth < elements.length) {
+                                refId = elements[nth].refId;
+                            }
+                        }
+                        const state = await unifiedSession.readPage(refId ? { refId } : undefined);
                         if (args.output) {
-                            await writeFile(args.output, JSON.stringify(state, null, 2), 'utf-8');
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            success: true,
-                                            type: 'state',
-                                            output: args.output,
-                                        }),
-                                    },
-                                ],
-                            };
+                            await writeOutputFile(args.output, JSON.stringify(state, null, 2), 'utf-8');
+                            return formatResponse({
+                                success: true,
+                                type: 'state',
+                                output: args.output,
+                            });
                         }
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        success: true,
-                                        type: 'state',
-                                        state,
-                                    }, null, 2),
-                                },
-                            ],
-                        };
+                        return formatResponse({
+                            success: true,
+                            type: 'state',
+                            state,
+                        });
+                    }
+                    case 'metadata': {
+                        const metadata = await unifiedSession.getMetadata();
+                        if (args.output) {
+                            await writeOutputFile(args.output, JSON.stringify(metadata, null, 2), 'utf-8');
+                            return formatResponse({
+                                success: true,
+                                type: 'metadata',
+                                output: args.output,
+                            });
+                        }
+                        return formatResponse({
+                            success: true,
+                            type: 'metadata',
+                            ...metadata,
+                        });
                     }
                     default:
                         return {
@@ -290,6 +312,354 @@ export async function handleExtract(params) {
         return formatErrorResponse(error);
     }
 }
+// ==================== HTML + 图片提取 ====================
+/** 写入文件前自动创建父目录 */
+async function writeOutputFile(path, data, encoding) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, data, encoding);
+}
+/**
+ * 处理 html + images 提取
+ */
+async function handleHtmlWithImages(unifiedSession, session, useExtension, args) {
+    const { selector, nth: nthParam } = args.target
+        ? targetToFindParams(args.target)
+        : { selector: undefined, nth: undefined };
+    const nth = nthParam ?? 0;
+    let result;
+    if (selector && nth > 0) {
+        // nth > 0：用 evaluate 取第 N 个匹配元素
+        result = await unifiedSession.evaluate(`(function(s, n) {
+                var els = document.querySelectorAll(s);
+                if (n >= els.length) return {html: '', images: []};
+                var root = els[n];
+                var html = root.outerHTML;
+                var imgList = [];
+                if (root.tagName === 'IMG') imgList.push(root);
+                root.querySelectorAll('img').forEach(function(img) { imgList.push(img); });
+                var images = [];
+                for (var i = 0; i < imgList.length; i++) {
+                    var img = imgList[i];
+                    images.push({index: i, src: img.src, dataSrc: (function() { var raw = img.dataset.src || img.dataset.lazySrc || img.dataset.original || ''; if (!raw) return ''; try { return new URL(raw, location.href).href } catch(e) { return raw } })(), alt: img.alt, width: img.width, height: img.height, naturalWidth: img.naturalWidth, naturalHeight: img.naturalHeight});
+                }
+                return {html: html, images: images};
+            })`, undefined, undefined, [selector, nth]);
+    }
+    else {
+        result = useExtension
+            ? await unifiedSession.getHtmlWithImages(selector)
+            : await extractHtmlWithImagesCdp(session, selector, args.timeout);
+    }
+    if (args.images === 'info') {
+        // info 模式：HTML + 图片元信息
+        const payload = { type: 'html', content: result.html, images: result.images };
+        if (args.output) {
+            await writeOutputFile(args.output, JSON.stringify(payload, null, 2), 'utf-8');
+            return formatResponse({
+                success: true,
+                type: 'html',
+                output: args.output,
+                imageCount: result.images.length,
+            });
+        }
+        return formatResponse({
+            success: true,
+            ...payload,
+        });
+    }
+    // data 模式：获取图片数据
+    const appendixMode = !args.output;
+    const imageDataList = await fetchImageData(unifiedSession, result.images, appendixMode ? MAX_APPENDIX_IMAGES : undefined);
+    if (args.output) {
+        // 写入目录
+        await writeImageDirectory(args.output, result.html, result.images, imageDataList);
+        return formatResponse({
+            success: true,
+            type: 'html',
+            output: args.output,
+            imageCount: result.images.length,
+            index: join(args.output, 'index.json'),
+        });
+    }
+    // 无 output：MCP 附录方式返回
+    return buildImageAppendixResponse(result.html, result.images, imageDataList);
+}
+/**
+ * CDP 模式：提取 HTML + 图片元信息
+ */
+async function extractHtmlWithImagesCdp(session, selector, timeout) {
+    if (selector) {
+        const locator = session.createLocator({ css: selector }, timeout !== undefined ? { timeout } : undefined);
+        return locator.evaluateOn(`function() {
+            var html = this.outerHTML;
+            var imgList = [];
+            if (this.tagName === 'IMG') imgList.push(this);
+            this.querySelectorAll('img').forEach(function(img) { imgList.push(img); });
+            var images = [];
+            for (var i = 0; i < imgList.length; i++) {
+                var img = imgList[i];
+                images.push({index: i, src: img.src, dataSrc: (function() { var raw = img.dataset.src || img.dataset.lazySrc || img.dataset.original || ''; if (!raw) return ''; try { return new URL(raw, location.href).href } catch(e) { return raw } })(), alt: img.alt, width: img.width, height: img.height, naturalWidth: img.naturalWidth, naturalHeight: img.naturalHeight});
+            }
+            return {html: html, images: images};
+        }`);
+    }
+    return session.evaluate(`(function() {
+        var html = document.documentElement.outerHTML;
+        var imgs = document.querySelectorAll('img');
+        var images = [];
+        for (var i = 0; i < imgs.length; i++) {
+            var img = imgs[i];
+            images.push({index: i, src: img.src, dataSrc: (function() { var raw = img.dataset.src || img.dataset.lazySrc || img.dataset.original || ''; if (!raw) return ''; try { return new URL(raw, location.href).href } catch(e) { return raw } })(), alt: img.alt, width: img.width, height: img.height, naturalWidth: img.naturalWidth, naturalHeight: img.naturalHeight});
+        }
+        return {html: html, images: images};
+    })()`);
+}
+/**
+ * 获取图片数据
+ *
+ * 策略：
+ * 1. data: URL → 直接解码
+ * 2. CDP Page.getResourceContent（批量） → 从浏览器缓存读取（零网络请求）
+ * 3. Node.js fetch → fallback
+ *
+ * @param unifiedSession 会话管理器，用于 CDP 资源获取
+ * @param images 图片元信息列表
+ * @param limit 最多获取前 N 张图片数据（附录模式限流），超出的返回 null
+ */
+async function fetchImageData(unifiedSession, images, limit) {
+    const effectiveLimit = limit ?? images.length;
+    // 第一趟：解析 data: URL + 收集需要 CDP 获取的 URL（去重）
+    const preResolved = [];
+    const cdpUrlSet = new Set();
+    for (let i = 0; i < images.length; i++) {
+        const img = images[i];
+        const effectiveSrc = img.src || img.dataSrc;
+        if (i >= effectiveLimit || !effectiveSrc) {
+            preResolved.push({ base64: null, mimeType: 'image/png' });
+            continue;
+        }
+        if (effectiveSrc.startsWith('data:')) {
+            const match = effectiveSrc.match(/^data:([^;]+);base64,(.+)$/);
+            preResolved.push(match ? { base64: match[2], mimeType: match[1] } : { base64: null, mimeType: 'image/png' });
+            continue;
+        }
+        if (!effectiveSrc.startsWith('http')) {
+            preResolved.push({ base64: null, mimeType: guessMimeType(effectiveSrc) });
+            continue;
+        }
+        // 只有 src 非空（浏览器实际请求过的）才走 CDP 缓存
+        if (img.src) {
+            cdpUrlSet.add(img.src);
+        }
+        preResolved.push(null); // 需要进一步获取
+    }
+    // 第二趟：批量 CDP 获取
+    const cdpResults = await unifiedSession.getResourceContentBatch([...cdpUrlSet]);
+    // 第三趟：组装结果，CDP 未命中的走 fetch fallback（去重：相同 URL 共享结果）
+    const fetchUrlMap = new Map();
+    const results = [];
+    for (let i = 0; i < images.length; i++) {
+        if (preResolved[i] !== null) {
+            results.push(preResolved[i]);
+            continue;
+        }
+        const img = images[i];
+        const effectiveSrc = img.src || img.dataSrc;
+        const mimeType = guessMimeType(effectiveSrc);
+        // 尝试 CDP 缓存
+        if (img.src && cdpResults.has(img.src)) {
+            const resource = cdpResults.get(img.src);
+            if (resource.base64Encoded) {
+                results.push({ base64: resource.content, mimeType });
+            }
+            else {
+                results.push({ base64: Buffer.from(resource.content).toString('base64'), mimeType });
+            }
+            continue;
+        }
+        // 需要 fetch fallback — 按 URL 合并
+        results.push({ base64: null, mimeType }); // 占位
+        const existing = fetchUrlMap.get(effectiveSrc);
+        if (existing) {
+            existing.indices.push(i);
+        }
+        else {
+            fetchUrlMap.set(effectiveSrc, { mimeType, indices: [i] });
+        }
+    }
+    // 第四趟：并发 fetch fallback（限制并发，相同 URL 只下载一次）
+    if (fetchUrlMap.size > 0) {
+        const fetchTasks = [...fetchUrlMap.entries()];
+        let idx = 0;
+        const next = async () => {
+            while (idx < fetchTasks.length) {
+                const [url, { mimeType, indices }] = fetchTasks[idx++];
+                try {
+                    const response = await fetch(url, { signal: AbortSignal.timeout(5000) });
+                    if (response.ok) {
+                        const buffer = Buffer.from(await response.arrayBuffer());
+                        const contentType = response.headers.get('content-type')?.split(';')[0] ?? mimeType;
+                        const data = { base64: buffer.toString('base64'), mimeType: contentType };
+                        for (const i of indices) {
+                            results[i] = data;
+                        }
+                    }
+                }
+                catch {
+                    // fetch 失败，保持 null
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(6, fetchTasks.length) }, () => next()));
+    }
+    return results;
+}
+/**
+ * 写入图片目录
+ *
+ * 生成结构：
+ *   {output}/
+ *     content.html
+ *     images/
+ *       0-photo.jpg
+ *       1-icon.png
+ *     index.json
+ */
+async function writeImageDirectory(outputDir, html, images, imageDataList) {
+    const imagesDir = join(outputDir, 'images');
+    await mkdir(imagesDir, { recursive: true });
+    // 写入 HTML
+    await writeFile(join(outputDir, 'content.html'), html, 'utf-8');
+    // 写入图片文件 + 构建索引（相同 src 去重）
+    const indexEntries = [];
+    const writtenFiles = new Map(); // src → file path
+    for (let i = 0; i < images.length; i++) {
+        const img = images[i];
+        const data = imageDataList[i];
+        const src = img.src || img.dataSrc;
+        let file = null;
+        if (data.base64) {
+            // 相同 src 复用已写入的文件
+            const existing = writtenFiles.get(src);
+            if (existing) {
+                file = existing;
+            }
+            else {
+                const ext = mimeToExt(data.mimeType);
+                const safeName = sanitizeFilename(src);
+                const filename = `${i}-${safeName}${ext}`;
+                file = `images/${filename}`;
+                await writeFile(join(imagesDir, filename), Buffer.from(data.base64, 'base64'));
+                writtenFiles.set(src, file);
+            }
+        }
+        indexEntries.push({
+            index: img.index,
+            src: img.src || img.dataSrc,
+            alt: img.alt,
+            width: img.width,
+            height: img.height,
+            file,
+        });
+    }
+    // 写入索引
+    await writeFile(join(outputDir, 'index.json'), JSON.stringify({
+        html: 'content.html',
+        images: indexEntries,
+    }, null, 2), 'utf-8');
+}
+/**
+ * 构造附录式 MCP 响应
+ *
+ * 返回格式：
+ * [text: JSON summary]
+ * [text: --- Images ---]
+ * [text: [0] url  alt  WxH]
+ * [image: base64 data]
+ * ...
+ */
+function buildImageAppendixResponse(html, images, imageDataList) {
+    const content = [];
+    // 主体 JSON
+    content.push({
+        type: 'text',
+        text: JSON.stringify({
+            success: true,
+            type: 'html',
+            content: html,
+            imageCount: images.length,
+        }),
+    });
+    if (images.length === 0) {
+        return { content };
+    }
+    content.push({ type: 'text', text: '\n--- Images ---' });
+    /** Claude API 支持的 image block 格式 */
+    const SUPPORTED_IMAGE_MIMES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+    const limit = Math.min(images.length, MAX_APPENDIX_IMAGES);
+    for (let i = 0; i < images.length; i++) {
+        const img = images[i];
+        const data = imageDataList[i];
+        const effectiveSrc = img.src || img.dataSrc;
+        // 图片标注
+        const sizeStr = img.naturalWidth ? `${img.naturalWidth}×${img.naturalHeight}` : `${img.width}×${img.height}`;
+        const altStr = img.alt ? `  alt="${img.alt}"` : '';
+        content.push({ type: 'text', text: `\n[${img.index}] ${effectiveSrc}${altStr}  ${sizeStr}` });
+        // 在限制内且有数据时附带图片（SVG 等不支持的格式跳过 image block）
+        if (i < limit && data.base64 && SUPPORTED_IMAGE_MIMES.has(data.mimeType)) {
+            content.push({ type: 'image', data: data.base64, mimeType: data.mimeType });
+        }
+    }
+    if (images.length > MAX_APPENDIX_IMAGES) {
+        content.push({
+            type: 'text',
+            text: `\n（共 ${images.length} 张图片，仅前 ${MAX_APPENDIX_IMAGES} 张附带数据。使用 output 参数导出全部图片）`,
+        });
+    }
+    return { content };
+}
+// ==================== MIME / 文件名工具 ====================
+/** 从 URL 或扩展名推断 MIME 类型 */
+function guessMimeType(url) {
+    let ext;
+    try {
+        ext = extname(new URL(url, 'http://x').pathname).toLowerCase();
+    }
+    catch {
+        return 'image/png';
+    }
+    const map = {
+        '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+        '.png': 'image/png', '.gif': 'image/gif',
+        '.webp': 'image/webp', '.svg': 'image/svg+xml',
+        '.ico': 'image/x-icon', '.bmp': 'image/bmp',
+        '.avif': 'image/avif',
+    };
+    return map[ext] ?? 'image/png';
+}
+/** MIME 类型转文件扩展名 */
+function mimeToExt(mimeType) {
+    const map = {
+        'image/jpeg': '.jpg', 'image/png': '.png',
+        'image/gif': '.gif', 'image/webp': '.webp',
+        'image/svg+xml': '.svg', 'image/x-icon': '.ico',
+        'image/bmp': '.bmp', 'image/avif': '.avif',
+    };
+    return map[mimeType] ?? '.png';
+}
+/** 从 URL 提取安全的文件名片段 */
+function sanitizeFilename(url) {
+    try {
+        const name = basename(new URL(url, 'http://x').pathname);
+        // 去掉扩展名，只保留字母数字和连字符
+        const stem = name.replace(/\.[^.]+$/, '').replace(/[^a-zA-Z0-9_-]/g, '_');
+        return stem.substring(0, 40) || 'image';
+    }
+    catch {
+        return 'image';
+    }
+}
+// ==================== 原有提取函数 ====================
 /**
  * 提取文本内容
  */
@@ -309,10 +679,9 @@ async function extractText(session, target, timeout) {
 async function extractHTML(session, target, timeout) {
     if (target) {
         const locator = session.createLocator(target, timeout !== undefined ? { timeout } : undefined);
-        const html = await locator.evaluateOn(`function() {
+        return await locator.evaluateOn(`function() {
       return this.outerHTML;
     }`);
-        return html;
     }
     return session.evaluate('document.documentElement.outerHTML');
 }
@@ -331,17 +700,23 @@ async function extractAttribute(session, target, attribute, timeout) {
  * 支持所有 Target 形式（css/xpath/text/role/label 等）
  */
 async function extractTextExtension(unifiedSession, target) {
-    if (!target)
+    if (!target) {
         return unifiedSession.getText();
-    const { selector, text, xpath } = targetToFindParams(target);
-    if (selector)
+    }
+    const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
+    const nth = nthParam ?? 0;
+    if (selector) {
+        if (nth > 0) {
+            return unifiedSession.evaluate(`(function(s, n) { var els = document.querySelectorAll(s); return n < els.length ? (els[n].textContent || '') : '' })`, undefined, undefined, [selector, nth]);
+        }
         return unifiedSession.getText(selector);
+    }
     // xpath/text 定位：通过 evaluate 在页面上下文中查找
     if (xpath) {
-        return unifiedSession.evaluate(`(function(xp) { var r = document.evaluate(xp, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); return r.singleNodeValue ? r.singleNodeValue.textContent || '' : '' })`, undefined, undefined, [xpath]);
+        return unifiedSession.evaluate(`(function(xp, n) { var r = document.evaluate(xp, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null); return n < r.snapshotLength ? (r.snapshotItem(n).textContent || '') : '' })`, undefined, undefined, [xpath, nth]);
     }
     if (text) {
-        return unifiedSession.evaluate(`(function(t) { var els = document.querySelectorAll('*'); for (var i = 0; i < els.length; i++) { var cn = els[i].childNodes; for (var j = 0; j < cn.length; j++) { if (cn[j].nodeType === 3 && cn[j].textContent && cn[j].textContent.includes(t)) return els[i].textContent || '' } } return '' })`, undefined, undefined, [text]);
+        return unifiedSession.evaluate(`(function(t, n) { var els = document.querySelectorAll('*'); var found = []; for (var i = 0; i < els.length; i++) { var cn = els[i].childNodes; for (var j = 0; j < cn.length; j++) { if (cn[j].nodeType === 3 && cn[j].textContent && cn[j].textContent.includes(t)) { found.push(els[i]); break; } } } return n < found.length ? (found[n].textContent || '') : '' })`, undefined, undefined, [text, nth]);
     }
     return unifiedSession.getText();
 }
@@ -350,17 +725,23 @@ async function extractTextExtension(unifiedSession, target) {
  * 支持所有 Target 形式（css/xpath/text/role/label 等）
  */
 async function extractHtmlExtension(unifiedSession, target, outer = true) {
-    if (!target)
+    if (!target) {
         return unifiedSession.getHtml(undefined, outer);
-    const { selector, text, xpath } = targetToFindParams(target);
-    if (selector)
-        return unifiedSession.getHtml(selector, outer);
+    }
+    const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
+    const nth = nthParam ?? 0;
     const prop = outer ? 'outerHTML' : 'innerHTML';
+    if (selector) {
+        if (nth > 0) {
+            return unifiedSession.evaluate(`(function(s, n, p) { var els = document.querySelectorAll(s); return n < els.length ? (els[n][p] || '') : '' })`, undefined, undefined, [selector, nth, prop]);
+        }
+        return unifiedSession.getHtml(selector, outer);
+    }
     if (xpath) {
-        return unifiedSession.evaluate(`(function(xp, p) { var r = document.evaluate(xp, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); return r.singleNodeValue ? r.singleNodeValue[p] || '' : '' })`, undefined, undefined, [xpath, prop]);
+        return unifiedSession.evaluate(`(function(xp, n, p) { var r = document.evaluate(xp, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null); return n < r.snapshotLength ? (r.snapshotItem(n)[p] || '') : '' })`, undefined, undefined, [xpath, nth, prop]);
     }
     if (text) {
-        return unifiedSession.evaluate(`(function(t, p) { var els = document.querySelectorAll('*'); for (var i = 0; i < els.length; i++) { var cn = els[i].childNodes; for (var j = 0; j < cn.length; j++) { if (cn[j].nodeType === 3 && cn[j].textContent && cn[j].textContent.includes(t)) return els[i][p] || '' } } return '' })`, undefined, undefined, [text, prop]);
+        return unifiedSession.evaluate(`(function(t, n, p) { var els = document.querySelectorAll('*'); var found = []; for (var i = 0; i < els.length; i++) { var cn = els[i].childNodes; for (var j = 0; j < cn.length; j++) { if (cn[j].nodeType === 3 && cn[j].textContent && cn[j].textContent.includes(t)) { found.push(els[i]); break; } } } return n < found.length ? (found[n][p] || '') : '' })`, undefined, undefined, [text, nth, prop]);
     }
     return unifiedSession.getHtml(undefined, outer);
 }
@@ -368,16 +749,24 @@ async function extractHtmlExtension(unifiedSession, target, outer = true) {
  * Extension 模式：提取属性
  */
 async function extractAttributeExtension(unifiedSession, target, attribute) {
-    const { selector, text, xpath } = targetToFindParams(target);
+    const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
     // xpath/text 定位需要先 find 得到 refId，再获取属性
     if (xpath || text) {
         const elements = await unifiedSession.find(selector, text, xpath);
         if (elements.length > 0) {
-            return unifiedSession.getAttribute(undefined, elements[0].refId, attribute);
+            const nth = nthParam ?? 0;
+            if (nth >= elements.length) {
+                throw new Error(`第 ${nth} 个匹配元素不存在（共 ${elements.length} 个）`);
+            }
+            return unifiedSession.getAttribute(undefined, elements[nth].refId, attribute);
         }
         return null;
     }
     if (selector) {
+        const nth = nthParam ?? 0;
+        if (nth > 0) {
+            return unifiedSession.evaluate(`(function(s, n, a) { var els = document.querySelectorAll(s); return n < els.length ? els[n].getAttribute(a) : null })`, undefined, undefined, [selector, nth, attribute]);
+        }
         return unifiedSession.getAttribute(selector, undefined, attribute);
     }
     return null;
@@ -391,7 +780,8 @@ async function extractAttributeExtension(unifiedSession, target, attribute) {
 async function waitForTargetExtension(unifiedSession, target, timeout) {
     const startTime = Date.now();
     const retryDelay = 100;
-    const { selector, text, xpath } = targetToFindParams(target);
+    const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
+    const nth = nthParam ?? 0;
     let lastError = null;
     while (true) {
         const elapsed = Date.now() - startTime;
@@ -407,12 +797,15 @@ async function waitForTargetExtension(unifiedSession, target, timeout) {
         try {
             const remaining = timeout - elapsed;
             const elements = await unifiedSession.find(selector, text, xpath, remaining);
-            if (elements.length > 0)
+            if (elements.length > nth) {
                 return;
+            }
         }
         catch (err) {
             // 暂时性错误（RPC 超时、发送失败、连接断开）可重试，其他确定性错误立即抛出
-            if (err instanceof Error && /Request timeout|Failed to send|disconnect|未连接|stopped|replaced/i.test(err.message)) {
+            if (err instanceof
+                Error &&
+                /Request timeout|Failed to send|disconnect|未连接|stopped|replaced/i.test(err.message)) {
                 lastError = err;
                 await new Promise(r => setTimeout(r, retryDelay));
                 continue;
@@ -422,4 +815,13 @@ async function waitForTargetExtension(unifiedSession, target, timeout) {
         await new Promise(r => setTimeout(r, retryDelay));
     }
 }
+/**
+ * 注册 extract 工具
+ */
+export function registerExtractTool(server) {
+    server.registerTool('extract', {
+        description: '提取页面内容：文本、HTML（可附带图片）、属性、截图、状态、页面元信息',
+        inputSchema: extractSchema,
+    }, (args) => handleExtract(args));
+}
 //# sourceMappingURL=extract.js.map