@pyrokine/mcp-chrome 2.4.4 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.md +495 -115
  2. package/README_zh.md +423 -128
  3. package/dist/anti-detection/injection.js +3 -3
  4. package/dist/cdp/client.d.ts +1 -1
  5. package/dist/cdp/client.d.ts.map +1 -1
  6. package/dist/cdp/client.js +18 -7
  7. package/dist/cdp/client.js.map +1 -1
  8. package/dist/cdp/launcher.d.ts +2 -3
  9. package/dist/cdp/launcher.d.ts.map +1 -1
  10. package/dist/cdp/launcher.js +84 -24
  11. package/dist/cdp/launcher.js.map +1 -1
  12. package/dist/core/auto-wait.d.ts +3 -3
  13. package/dist/core/auto-wait.d.ts.map +1 -1
  14. package/dist/core/auto-wait.js +45 -20
  15. package/dist/core/auto-wait.js.map +1 -1
  16. package/dist/core/browser-driver.d.ts +105 -15
  17. package/dist/core/browser-driver.d.ts.map +1 -1
  18. package/dist/core/browser-driver.js.map +1 -1
  19. package/dist/core/errors.d.ts +22 -4
  20. package/dist/core/errors.d.ts.map +1 -1
  21. package/dist/core/errors.js +90 -7
  22. package/dist/core/errors.js.map +1 -1
  23. package/dist/core/locator.d.ts +7 -0
  24. package/dist/core/locator.d.ts.map +1 -1
  25. package/dist/core/locator.js +54 -29
  26. package/dist/core/locator.js.map +1 -1
  27. package/dist/core/os-mouse.d.ts +15 -2
  28. package/dist/core/os-mouse.d.ts.map +1 -1
  29. package/dist/core/os-mouse.js +52 -8
  30. package/dist/core/os-mouse.js.map +1 -1
  31. package/dist/core/session.d.ts +39 -22
  32. package/dist/core/session.d.ts.map +1 -1
  33. package/dist/core/session.js +632 -153
  34. package/dist/core/session.js.map +1 -1
  35. package/dist/core/types.d.ts +2 -0
  36. package/dist/core/types.d.ts.map +1 -1
  37. package/dist/core/types.js.map +1 -1
  38. package/dist/core/unified-session.d.ts +105 -27
  39. package/dist/core/unified-session.d.ts.map +1 -1
  40. package/dist/core/unified-session.js +554 -138
  41. package/dist/core/unified-session.js.map +1 -1
  42. package/dist/core/utils.d.ts +5 -0
  43. package/dist/core/utils.d.ts.map +1 -1
  44. package/dist/core/utils.js +475 -54
  45. package/dist/core/utils.js.map +1 -1
  46. package/dist/extension/bridge.d.ts +49 -39
  47. package/dist/extension/bridge.d.ts.map +1 -1
  48. package/dist/extension/bridge.js +318 -131
  49. package/dist/extension/bridge.js.map +1 -1
  50. package/dist/extension/http-server.d.ts +3 -0
  51. package/dist/extension/http-server.d.ts.map +1 -1
  52. package/dist/extension/http-server.js +28 -2
  53. package/dist/extension/http-server.js.map +1 -1
  54. package/dist/index.js +7 -0
  55. package/dist/index.js.map +1 -1
  56. package/dist/tools/browse.d.ts.map +1 -1
  57. package/dist/tools/browse.js +248 -172
  58. package/dist/tools/browse.js.map +1 -1
  59. package/dist/tools/challenge.d.ts +1 -1
  60. package/dist/tools/challenge.d.ts.map +1 -1
  61. package/dist/tools/challenge.js +86 -51
  62. package/dist/tools/challenge.js.map +1 -1
  63. package/dist/tools/cookies.d.ts.map +1 -1
  64. package/dist/tools/cookies.js +5 -3
  65. package/dist/tools/cookies.js.map +1 -1
  66. package/dist/tools/diagnostics.d.ts +3 -3
  67. package/dist/tools/diagnostics.d.ts.map +1 -1
  68. package/dist/tools/diagnostics.js +13 -12
  69. package/dist/tools/diagnostics.js.map +1 -1
  70. package/dist/tools/evaluate.d.ts.map +1 -1
  71. package/dist/tools/evaluate.js +67 -26
  72. package/dist/tools/evaluate.js.map +1 -1
  73. package/dist/tools/extract.d.ts.map +1 -1
  74. package/dist/tools/extract.js +137 -197
  75. package/dist/tools/extract.js.map +1 -1
  76. package/dist/tools/input.d.ts +1 -1
  77. package/dist/tools/input.d.ts.map +1 -1
  78. package/dist/tools/input.js +445 -197
  79. package/dist/tools/input.js.map +1 -1
  80. package/dist/tools/logs.d.ts.map +1 -1
  81. package/dist/tools/logs.js +5 -5
  82. package/dist/tools/logs.js.map +1 -1
  83. package/dist/tools/manage.d.ts.map +1 -1
  84. package/dist/tools/manage.js +395 -86
  85. package/dist/tools/manage.js.map +1 -1
  86. package/dist/tools/page-context.d.ts +17 -0
  87. package/dist/tools/page-context.d.ts.map +1 -0
  88. package/dist/tools/page-context.js +103 -0
  89. package/dist/tools/page-context.js.map +1 -0
  90. package/dist/tools/png.d.ts +5 -0
  91. package/dist/tools/png.d.ts.map +1 -1
  92. package/dist/tools/png.js +84 -19
  93. package/dist/tools/png.js.map +1 -1
  94. package/dist/tools/post-condition.d.ts.map +1 -1
  95. package/dist/tools/post-condition.js +24 -7
  96. package/dist/tools/post-condition.js.map +1 -1
  97. package/dist/tools/schema.d.ts +9 -0
  98. package/dist/tools/schema.d.ts.map +1 -1
  99. package/dist/tools/schema.js +15 -0
  100. package/dist/tools/schema.js.map +1 -1
  101. package/dist/tools/target-diagnostics.d.ts +9 -1
  102. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  103. package/dist/tools/target-diagnostics.js +89 -33
  104. package/dist/tools/target-diagnostics.js.map +1 -1
  105. package/dist/tools/wait.d.ts.map +1 -1
  106. package/dist/tools/wait.js +38 -32
  107. package/dist/tools/wait.js.map +1 -1
  108. package/extension/dist/assets/content.ts-loader-DUWbDHRS.js +13 -0
  109. package/extension/dist/assets/content.ts-qe6IB5DK.js +13 -0
  110. package/extension/dist/assets/{index.ts-Bqcu2qiN.js → index.ts-D7_LCUoV.js} +2477 -2201
  111. package/extension/dist/assets/page-scripts-D508WLkW.js +1378 -0
  112. package/extension/dist/assets/{popup.html-B81xccfq.js → popup.html-B-eVq48O.js} +54 -5
  113. package/extension/dist/manifest.json +4 -3
  114. package/extension/dist/service-worker-loader.js +1 -1
  115. package/extension/dist/src/popup/popup.html +11 -1
  116. package/package.json +16 -8
  117. package/scripts/start-chrome.ps1 +58 -0
  118. package/extension/dist/assets/content.ts-Cj_iiU2s.js +0 -25
@@ -10,14 +10,17 @@
10
10
  * - state: 页面状态(精简的可交互元素列表)
11
11
  * - metadata: 页面元信息(title/og/jsonLd 等)
12
12
  */
13
- import { readFile } from 'fs/promises';
13
+ import { readFile, stat } from 'fs/promises';
14
14
  import { basename, extname, join } from 'path';
15
15
  import { z } from 'zod';
16
- import { CWD_PATH_PREFIX, formatErrorResponse, formatResponse, getSession, getUnifiedSession, resolveScopedOutputPath, TMP_PATH_PREFIX, writePrivateFile, } from '../core/index.js';
16
+ import { CWD_PATH_PREFIX, formatErrorResponse, formatResponse, getSession, getUnifiedSession, resolveScopedOutputPath, StructuredToolError, TMP_PATH_PREFIX, writePrivateFile, } from '../core/index.js';
17
+ import { ElementNotFoundError } from '../core/errors.js';
18
+ import { DEFAULT_TIMEOUT } from '../core/types.js';
17
19
  import { sanitizeUrlRecords } from './network-sanitizer.js';
18
- import { comparePngImages, MAX_COMPARE_PIXELS, MAX_COMPARE_PNG_BYTES, readPngHeader } from './png.js';
19
- import { targetToFindParams, targetZodSchema } from './schema.js';
20
- import { buildTargetDiagnostics, TargetNotFoundError, TargetTimeoutError } from './target-diagnostics.js';
20
+ import { withPageContext } from './page-context.js';
21
+ import { assertPngFileBudget, assertScreenshotBase64Budget, assertScreenshotBudget, comparePngImages, MAX_COMPARE_PIXELS, MAX_COMPARE_PNG_BYTES, readPngHeader, } from './png.js';
22
+ import { pageTargetIdSchema, resolvePageTargetId, targetToFindParams, targetZodSchema } from './schema.js';
23
+ import { buildTargetDiagnostics, enrichTargetError, targetLookupTimeout, TargetNotFoundError, TargetTimeoutError, } from './target-diagnostics.js';
21
24
  /** 无 output 时附录返回的最大图片数 */
22
25
  const MAX_APPENDIX_IMAGES = 20;
23
26
  /**
@@ -30,7 +33,7 @@ const extractSchema = z
30
33
  .describe('提取类型'),
31
34
  target: targetZodSchema
32
35
  .optional()
33
- .describe('目标元素(attribute 必填;text/html 可选,省略则提取整个页面;' +
36
+ .describe('目标元素(attribute 必填;text/html 可选,省略则提取整个页面;text 对 HTML 使用 innerText,SVG/XML 使用 textContent;' +
34
37
  'screenshot 可选用于元素截图;state 可选(仅 Extension)用于返回目标子树;metadata 不需要)'),
35
38
  attribute: z.string().optional().describe('属性名(attribute)'),
36
39
  images: z
@@ -67,10 +70,8 @@ const extractSchema = z
67
70
  .string()
68
71
  .optional()
69
72
  .describe(`输出文件路径(可选),相对路径默认写入 ${TMP_PATH_PREFIX},持久化到仓库请显式写 ${CWD_PATH_PREFIX},images=data 时作为输出目录路径`),
70
- tabId: z
71
- .string()
72
- .optional()
73
- .describe('目标 Tab ID(可选,仅 Extension 模式),不指定则使用当前 attach 的 tab,可操作非当前 attach 的 tab,CDP 模式下不支持此参数'),
73
+ targetId: pageTargetIdSchema.describe('目标页面 ID(Extension 或 CDP),优先于默认操作目标'),
74
+ tabId: pageTargetIdSchema.describe('旧版目标 Tab ID,与 targetId 相同语义,保留兼容'),
74
75
  depth: z
75
76
  .number()
76
77
  .int()
@@ -81,7 +82,7 @@ const extractSchema = z
81
82
  .enum(['accessibility', 'domsnapshot'])
82
83
  .optional()
83
84
  .describe('页面状态提取模式(state 类型有效),accessibility=可访问性树(默认,与原 read_page 一致),' +
84
- 'domsnapshot=CDP DOMSnapshot 全量快照(仅 CDP 模式)'),
85
+ 'domsnapshot=DOMSnapshot 全量快照(CDP 或受控 Extension 页面,不支持 target/frame/depth 限定)'),
85
86
  timeout: z.number().optional().describe('等待目标元素超时'),
86
87
  frame: z
87
88
  .union([z.string(), z.number()])
@@ -98,10 +99,17 @@ const extractSchema = z
98
99
  }
99
100
  });
100
101
  async function handleExtract(args) {
102
+ const timeout = args.timeout ?? DEFAULT_TIMEOUT;
103
+ const deadline = Date.now() + timeout;
101
104
  try {
105
+ if (args.type === 'state' &&
106
+ args.mode === 'domsnapshot' &&
107
+ [args.target, args.frame, args.depth].some((value) => value !== undefined)) {
108
+ return formatErrorResponse(new StructuredToolError('INVALID_ARGUMENT', 'domsnapshot 返回整页快照,不支持 target、frame 或 depth 限定', '局部页面状态请使用 mode="accessibility"', { actionExecuted: false }));
109
+ }
102
110
  const unifiedSession = getUnifiedSession();
103
111
  // 多 tab 并行:临时切换到指定 tab
104
- return await unifiedSession.withTabId(args.tabId, async () => {
112
+ return await withPageContext(unifiedSession, resolvePageTargetId(args), async () => {
105
113
  return await unifiedSession.withFrame(args.frame, async () => {
106
114
  const useExtension = unifiedSession.getMode() === 'extension';
107
115
  const frameHtmlError = validateFrameHtmlArgs(args, useExtension);
@@ -113,7 +121,22 @@ async function handleExtract(args) {
113
121
  if (useExtension && args.target && args.timeout !== undefined) {
114
122
  await waitForTargetExtension(unifiedSession, args.target, args.timeout, args.frame);
115
123
  }
116
- return handleExtractInFrame({ unifiedSession, session, useExtension }, args);
124
+ try {
125
+ const scopedArgs = !useExtension && args.target
126
+ ? { ...args, timeout: targetLookupTimeout(Math.max(1, deadline - Date.now())) }
127
+ : args;
128
+ return await handleExtractInFrame({ unifiedSession, session, useExtension }, scopedArgs);
129
+ }
130
+ catch (error) {
131
+ if (!useExtension && args.target && error instanceof ElementNotFoundError) {
132
+ await enrichTargetError(error, unifiedSession, args.target, {
133
+ timeout,
134
+ deadline,
135
+ frame: args.frame,
136
+ });
137
+ }
138
+ throw error;
139
+ }
117
140
  }); // withFrame
118
141
  }); // withTabId
119
142
  }
@@ -171,7 +194,7 @@ async function handleExtractInFrame(context, args) {
171
194
  }
172
195
  async function handleTextExtract({ unifiedSession, session, useExtension }, args) {
173
196
  const text = useExtension
174
- ? await extractTextExtension(unifiedSession, args.target)
197
+ ? await extractTextExtension(unifiedSession, args.target, args.timeout)
175
198
  : await extractText(session, args.target, args.timeout);
176
199
  if (args.output) {
177
200
  const outputPath = await writeOutputFile(args.output, text, 'utf-8');
@@ -185,7 +208,7 @@ async function handleHtmlExtract(context, args) {
185
208
  return handleHtmlWithImages(unifiedSession, session, useExtension, args);
186
209
  }
187
210
  const html = useExtension
188
- ? await extractHtmlExtension(unifiedSession, args.target)
211
+ ? await extractHtmlExtension(unifiedSession, args.target, true, args.timeout)
189
212
  : await extractHTML(session, args.target, args.timeout);
190
213
  if (args.output) {
191
214
  const outputPath = await writeOutputFile(args.output, html, 'utf-8');
@@ -194,7 +217,7 @@ async function handleHtmlExtract(context, args) {
194
217
  return formatResponse({ success: true, type: 'html', content: html });
195
218
  }
196
219
  async function handleFrameHtmlExtract({ unifiedSession }, args) {
197
- const html = await extractHtmlExtension(unifiedSession, args.target);
220
+ const html = await extractHtmlExtension(unifiedSession, args.target, true, args.timeout);
198
221
  if (args.output) {
199
222
  const outputPath = await writeOutputFile(args.output, html, 'utf-8');
200
223
  return formatResponse({
@@ -215,7 +238,7 @@ async function handleAttributeExtract({ unifiedSession, session, useExtension },
215
238
  return formatErrorResponse(new Error('attribute 提取需要 attribute 参数'));
216
239
  }
217
240
  const value = useExtension
218
- ? await extractAttributeExtension(unifiedSession, args.target, args.attribute)
241
+ ? await extractAttributeExtension(unifiedSession, args.target, args.attribute, args.timeout)
219
242
  : await extractAttribute(session, args.target, args.attribute, args.timeout);
220
243
  return formatResponse({ success: true, type: 'attribute', attribute: args.attribute, value });
221
244
  }
@@ -224,8 +247,23 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
224
247
  if (args.target && !args.clip) {
225
248
  const { selector, text, xpath, nth: nthParam } = targetToFindParams(args.target);
226
249
  const nth = nthParam ?? 0;
227
- const found = await unifiedSession.find(selector, text, xpath, args.timeout);
228
- const target = found[nth];
250
+ const pointTarget = 'x' in args.target && 'y' in args.target ? args.target : null;
251
+ const found = pointTarget
252
+ ? useExtension
253
+ ? await unifiedSession.findAtPoint(pointTarget.x, pointTarget.y, nth, args.timeout)
254
+ : await unifiedSession
255
+ .evaluate(`(() => {
256
+ const element = document.elementFromPoint(${pointTarget.x}, ${pointTarget.y});
257
+ if (!element) return null;
258
+ const rect = element.getBoundingClientRect();
259
+ return {
260
+ refId: '', tag: element.tagName.toLowerCase(), text: '',
261
+ rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
262
+ };
263
+ })()`, undefined, args.timeout)
264
+ .then((element) => (element && nth === 0 ? [element] : []))
265
+ : await unifiedSession.find(selector, text, xpath, args.timeout);
266
+ const target = found[pointTarget ? 0 : nth];
229
267
  if (!target || target.rect.width <= 0 || target.rect.height <= 0) {
230
268
  throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
231
269
  nth,
@@ -237,10 +275,9 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
237
275
  }));
238
276
  }
239
277
  const scrollOffset = args.frame === undefined ? await getPageScrollOffset(unifiedSession, args.timeout) : { x: 0, y: 0 };
240
- const frameOffset = unifiedSession.getFrameOffset();
241
278
  clip = {
242
- x: target.rect.x + scrollOffset.x + (frameOffset?.x ?? 0),
243
- y: target.rect.y + scrollOffset.y + (frameOffset?.y ?? 0),
279
+ x: target.rect.x + scrollOffset.x,
280
+ y: target.rect.y + scrollOffset.y,
244
281
  width: target.rect.width,
245
282
  height: target.rect.height,
246
283
  };
@@ -248,6 +285,9 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
248
285
  clip = args.clip ?? clip;
249
286
  const fullPage = clip ? false : (args.fullPage ?? false);
250
287
  const scale = args.scale ?? 1;
288
+ if (clip) {
289
+ assertScreenshotBudget(clip.width, clip.height, scale);
290
+ }
251
291
  const screenshot = await unifiedSession.screenshot({
252
292
  fullPage,
253
293
  scale: args.scale,
@@ -255,6 +295,7 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
255
295
  quality: args.quality,
256
296
  clip,
257
297
  });
298
+ assertScreenshotBase64Budget(screenshot.data);
258
299
  const screenshotBuffer = Buffer.from(screenshot.data, 'base64');
259
300
  const encodedDimensions = readImageDimensions(screenshotBuffer, screenshot.format);
260
301
  const fallbackDimensions = encodedDimensions
@@ -271,14 +312,16 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
271
312
  clip,
272
313
  size: screenshotBuffer.length,
273
314
  byteSize: screenshotBuffer.length,
274
- capabilities: screenshotCapabilities(useExtension),
315
+ capabilities: screenshotCapabilities(),
275
316
  };
276
317
  if (args.compareWith) {
277
318
  if (screenshot.format !== 'png') {
278
319
  throw new Error('screenshot compare 仅支持 png 格式');
279
320
  }
280
321
  const baselinePath = await resolveScopedOutputPath(args.compareWith, 'mcp-chrome');
322
+ assertPngFileBudget((await stat(baselinePath.absolutePath)).size);
281
323
  const baseline = await readFile(baselinePath.absolutePath);
324
+ assertPngFileBudget(baseline.length);
282
325
  const comparison = comparePngImages(baseline, screenshotBuffer);
283
326
  metadata.comparison = {
284
327
  pixelDiffRatio: comparison.pixelDiffRatio,
@@ -309,15 +352,24 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
309
352
  }
310
353
  async function handleStateExtract({ unifiedSession, useExtension }, args) {
311
354
  if (args.mode === 'domsnapshot') {
312
- return handleDomSnapshotState(unifiedSession, useExtension, args);
355
+ return handleDomSnapshotState(unifiedSession, args);
313
356
  }
314
357
  let refId;
315
358
  if (args.target && useExtension) {
316
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(args.target);
317
- const nth = nthParam ?? 0;
318
- const elements = await unifiedSession.find(selector, text, xpath);
319
- if (elements.length > 0 && nth < elements.length) {
320
- refId = elements[nth].refId;
359
+ refId = await findTargetRefExtension(unifiedSession, args.target, args.timeout);
360
+ if (!refId) {
361
+ const { selector, text, xpath, nth: nthParam, } = targetToFindParams(args.target);
362
+ const candidates = 'x' in args.target && 'y' in args.target
363
+ ? await unifiedSession.findAtPoint(args.target.x, args.target.y)
364
+ : await unifiedSession.find(selector, text, xpath, args.timeout);
365
+ throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
366
+ nth: nthParam ?? 0,
367
+ timeout: args.timeout,
368
+ frame: args.frame,
369
+ matchCount: candidates.length,
370
+ lastState: 'not-found',
371
+ candidates,
372
+ }));
321
373
  }
322
374
  }
323
375
  const readPageOptions = {};
@@ -334,23 +386,7 @@ async function handleStateExtract({ unifiedSession, useExtension }, args) {
334
386
  }
335
387
  return formatResponse({ success: true, type: 'state', state });
336
388
  }
337
- async function handleDomSnapshotState(unifiedSession, useExtension, args) {
338
- if (useExtension) {
339
- return {
340
- content: [
341
- {
342
- type: 'text',
343
- text: JSON.stringify({
344
- error: {
345
- code: 'INVALID_ARGUMENT',
346
- message: 'mode=domsnapshot 仅 CDP 模式支持,Extension 模式请用默认 accessibility',
347
- },
348
- }),
349
- },
350
- ],
351
- isError: true,
352
- };
353
- }
389
+ async function handleDomSnapshotState(unifiedSession, args) {
354
390
  const snapshot = await unifiedSession.sendCdpCommand('DOMSnapshot.captureSnapshot', {
355
391
  computedStyles: ['display', 'visibility', 'opacity'],
356
392
  includePaintOrder: false,
@@ -362,7 +398,7 @@ async function handleDomSnapshotState(unifiedSession, useExtension, args) {
362
398
  }
363
399
  return formatResponse({ success: true, type: 'state', mode: 'domsnapshot', snapshot });
364
400
  }
365
- async function handleDiagnosticBundleExtract({ unifiedSession, useExtension }, args) {
401
+ async function handleDiagnosticBundleExtract({ unifiedSession }, args) {
366
402
  const state = await unifiedSession.getLiveState().catch(() => null);
367
403
  const metadata = await unifiedSession.getMetadata();
368
404
  const frames = await unifiedSession.getFrames();
@@ -390,7 +426,7 @@ async function handleDiagnosticBundleExtract({ unifiedSession, useExtension }, a
390
426
  },
391
427
  capabilities: {
392
428
  screenshot: true,
393
- hiddenTabScreenshot: useExtension,
429
+ hiddenTabScreenshot: false,
394
430
  frames: true,
395
431
  },
396
432
  };
@@ -473,13 +509,13 @@ async function getScreenshotFallbackDimensions(unifiedSession, clip, fullPage, s
473
509
  return undefined;
474
510
  }
475
511
  }
476
- function screenshotCapabilities(useExtension) {
512
+ function screenshotCapabilities() {
477
513
  return {
478
514
  formats: ['png', 'jpeg', 'webp'],
479
515
  clip: true,
480
516
  fullPage: true,
481
517
  scale: true,
482
- hiddenTabScreenshot: useExtension,
518
+ hiddenTabScreenshot: false,
483
519
  compare: {
484
520
  formats: ['png'],
485
521
  maxBytes: MAX_COMPARE_PNG_BYTES,
@@ -587,17 +623,35 @@ async function handleHtmlWithImages(unifiedSession, session, useExtension, args)
587
623
  if (args.target) {
588
624
  const { selector, text, xpath, nth: nthParam } = targetToFindParams(args.target);
589
625
  const nth = nthParam ?? 0;
590
- const matches = await unifiedSession.find(selector, text, xpath, args.timeout);
591
- if (matches.length <= nth) {
592
- throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
593
- nth,
594
- timeout: args.timeout,
595
- matchCount: matches.length,
596
- lastState: 'not-found',
597
- candidates: matches,
598
- }));
626
+ if (useExtension) {
627
+ const refId = await findTargetRefExtension(unifiedSession, args.target, args.timeout);
628
+ if (!refId) {
629
+ const matches = 'x' in args.target && 'y' in args.target
630
+ ? await unifiedSession.findAtPoint(args.target.x, args.target.y)
631
+ : await unifiedSession.find(selector, text, xpath, args.timeout);
632
+ throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
633
+ nth,
634
+ timeout: args.timeout,
635
+ matchCount: matches.length,
636
+ lastState: 'not-found',
637
+ candidates: matches,
638
+ }));
639
+ }
640
+ result = await unifiedSession.getHtmlWithImagesByRef(refId);
641
+ }
642
+ else {
643
+ const matches = await unifiedSession.find(selector, text, xpath, args.timeout);
644
+ if (matches.length <= nth) {
645
+ throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
646
+ nth,
647
+ timeout: args.timeout,
648
+ matchCount: matches.length,
649
+ lastState: 'not-found',
650
+ candidates: matches,
651
+ }));
652
+ }
653
+ result = await extractHtmlWithImagesByTarget(unifiedSession, selector, text, xpath, nth, args.timeout);
599
654
  }
600
- result = await extractHtmlWithImagesByTarget(unifiedSession, selector, text, xpath, nth, args.timeout);
601
655
  }
602
656
  else {
603
657
  result = useExtension
@@ -948,7 +1002,7 @@ async function extractText(session, target, timeout) {
948
1002
  if (target) {
949
1003
  const locator = session.createLocator(target, timeout !== undefined ? { timeout } : undefined);
950
1004
  const text = await locator.evaluateOn(`function() {
951
- return this.textContent ?? '';
1005
+ return this instanceof HTMLElement ? this.innerText : (this.textContent ?? '');
952
1006
  }`);
953
1007
  return text ?? '';
954
1008
  }
@@ -991,162 +1045,47 @@ async function extractAttribute(session, target, attribute, timeout) {
991
1045
  return this.getAttribute(${JSON.stringify(attribute)});
992
1046
  }`);
993
1047
  }
1048
+ async function findTargetRefExtension(unifiedSession, target, timeout) {
1049
+ const { selector, text, xpath, nth } = targetToFindParams(target);
1050
+ const matches = 'x' in target && 'y' in target
1051
+ ? await unifiedSession.findAtPoint(target.x, target.y, nth ?? 0, timeout)
1052
+ : await unifiedSession.find(selector, text, xpath, timeout, nth ?? 0);
1053
+ return matches[0]?.refId;
1054
+ }
994
1055
  /**
995
1056
  * Extension 模式:提取文本
996
1057
  * 支持所有 Target 形式(css/xpath/text/role/label 等)
997
1058
  */
998
- async function extractTextExtension(unifiedSession, target) {
1059
+ async function extractTextExtension(unifiedSession, target, timeout) {
999
1060
  if (!target) {
1000
1061
  return unifiedSession.getText();
1001
1062
  }
1002
- if ('x' in target && 'y' in target && typeof target.x === 'number' && typeof target.y === 'number') {
1003
- const expr = '(function(x, y) { var el = document.elementFromPoint(x, y); ' +
1004
- "return el ? (el.textContent || '') : '' })";
1005
- return unifiedSession.evaluate(expr, undefined, undefined, [target.x, target.y]);
1006
- }
1007
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
1008
- const nth = nthParam ?? 0;
1009
- if (selector) {
1010
- if (text) {
1011
- const expr = '(function(s, t, n) { var els = Array.from(document.querySelectorAll(s))' +
1012
- '.filter(function(e) { return (e.textContent || "").includes(t); }); ' +
1013
- "return n < els.length ? (els[n].textContent || '') : '' })";
1014
- return unifiedSession.evaluate(expr, undefined, undefined, [selector, text, nth]);
1015
- }
1016
- if (nth > 0) {
1017
- const expr = '(function(s, n) { var els = document.querySelectorAll(s); ' +
1018
- "return n < els.length ? (els[n].textContent || '') : '' })";
1019
- return unifiedSession.evaluate(expr, undefined, undefined, [selector, nth]);
1020
- }
1021
- return unifiedSession.getText(selector);
1022
- }
1023
- // xpath/text 定位:通过 evaluate 在页面上下文中查找
1024
- if (xpath) {
1025
- const expr = '(function(xp, n) { var r = document.evaluate(xp, document, null, ' +
1026
- 'XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null); ' +
1027
- "return n < r.snapshotLength ? (r.snapshotItem(n).textContent || '') : '' })";
1028
- return unifiedSession.evaluate(expr, undefined, undefined, [xpath, nth]);
1029
- }
1030
- if (text) {
1031
- const expr = '(function(t, n) { var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT); ' +
1032
- 'var found = []; var seen = new WeakSet(); var node; ' +
1033
- 'while ((node = walker.nextNode())) { if (node.textContent && node.textContent.includes(t) ' +
1034
- '&& node.parentElement && !seen.has(node.parentElement)) { ' +
1035
- 'seen.add(node.parentElement); found.push(node.parentElement); } } ' +
1036
- "return n < found.length ? (found[n].textContent || '') : '' })";
1037
- return unifiedSession.evaluate(expr, undefined, undefined, [text, nth]);
1038
- }
1039
- return unifiedSession.getText();
1063
+ const refId = await findTargetRefExtension(unifiedSession, target, timeout);
1064
+ return refId ? unifiedSession.getTextByRef(refId) : '';
1040
1065
  }
1041
1066
  /**
1042
1067
  * Extension 模式:提取 HTML
1043
1068
  * 支持所有 Target 形式(css/xpath/text/role/label 等)
1044
1069
  */
1045
- async function extractHtmlExtension(unifiedSession, target, outer = true) {
1070
+ async function extractHtmlExtension(unifiedSession, target, outer = true, timeout) {
1046
1071
  if (!target) {
1047
1072
  return unifiedSession.getHtml(undefined, outer);
1048
1073
  }
1049
- const prop = outer ? 'outerHTML' : 'innerHTML';
1050
- if ('x' in target && 'y' in target && typeof target.x === 'number' && typeof target.y === 'number') {
1051
- const expr = '(function(x, y, p) { var el = document.elementFromPoint(x, y); ' + "return el ? (el[p] || '') : '' })";
1052
- return unifiedSession.evaluate(expr, undefined, undefined, [target.x, target.y, prop]);
1053
- }
1054
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
1055
- const nth = nthParam ?? 0;
1056
- if (selector) {
1057
- if (text) {
1058
- const expr = '(function(s, t, n, p) { var els = Array.from(document.querySelectorAll(s))' +
1059
- '.filter(function(e) { return (e.textContent || "").includes(t); }); ' +
1060
- "return n < els.length ? (els[n][p] || '') : '' })";
1061
- return unifiedSession.evaluate(expr, undefined, undefined, [selector, text, nth, prop]);
1062
- }
1063
- if (nth > 0) {
1064
- const expr = '(function(s, n, p) { var els = document.querySelectorAll(s); ' +
1065
- "return n < els.length ? (els[n][p] || '') : '' })";
1066
- return unifiedSession.evaluate(expr, undefined, undefined, [selector, nth, prop]);
1067
- }
1068
- return unifiedSession.getHtml(selector, outer);
1069
- }
1070
- if (xpath) {
1071
- const expr = '(function(xp, n, p) { var r = document.evaluate(xp, document, null, ' +
1072
- 'XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null); ' +
1073
- "return n < r.snapshotLength ? (r.snapshotItem(n)[p] || '') : '' })";
1074
- return unifiedSession.evaluate(expr, undefined, undefined, [xpath, nth, prop]);
1075
- }
1076
- if (text) {
1077
- const expr = '(function(t, n, p) { var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT); ' +
1078
- 'var found = []; var seen = new WeakSet(); var node; ' +
1079
- 'while ((node = walker.nextNode())) { if (node.textContent && node.textContent.includes(t) ' +
1080
- '&& node.parentElement && !seen.has(node.parentElement)) { ' +
1081
- 'seen.add(node.parentElement); found.push(node.parentElement); } } ' +
1082
- "return n < found.length ? (found[n][p] || '') : '' })";
1083
- return unifiedSession.evaluate(expr, undefined, undefined, [text, nth, prop]);
1084
- }
1085
- return unifiedSession.getHtml(undefined, outer);
1074
+ const refId = await findTargetRefExtension(unifiedSession, target, timeout);
1075
+ return refId ? unifiedSession.getHtmlByRef(refId, outer) : '';
1086
1076
  }
1087
1077
  /**
1088
1078
  * Extension 模式:提取属性
1089
1079
  */
1090
- async function extractAttributeExtension(unifiedSession, target, attribute) {
1091
- if ('x' in target && 'y' in target && typeof target.x === 'number' && typeof target.y === 'number') {
1092
- if (attribute.startsWith('computed:')) {
1093
- const prop = attribute.slice('computed:'.length);
1094
- const expr = '(function(x, y, p) { var el = document.elementFromPoint(x, y); ' +
1095
- 'return el ? window.getComputedStyle(el).getPropertyValue(p) : null })';
1096
- return unifiedSession.evaluate(expr, undefined, undefined, [target.x, target.y, prop]);
1097
- }
1098
- const expr = '(function(x, y, a) { var el = document.elementFromPoint(x, y); ' +
1099
- 'return el ? el.getAttribute(a) : null })';
1100
- return unifiedSession.evaluate(expr, undefined, undefined, [target.x, target.y, attribute]);
1101
- }
1102
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
1103
- // computed style: computed:color → getComputedStyle(el)
1104
- if (attribute.startsWith('computed:')) {
1105
- const prop = attribute.slice('computed:'.length);
1106
- return extractComputedStyleExtension(unifiedSession, selector, text, xpath, nthParam ?? 0, prop);
1107
- }
1108
- // xpath 定位(含 text+xpath)或 text 且无 selector 时:先 find 得到 refId,再获取属性
1109
- if (xpath || (text && !selector)) {
1110
- const elements = await unifiedSession.find(selector, text, xpath);
1111
- if (elements.length > 0) {
1112
- const nth = nthParam ?? 0;
1113
- if (nth >= elements.length) {
1114
- throw new Error(`第 ${nth} 个匹配元素不存在(共 ${elements.length} 个)`);
1115
- }
1116
- return unifiedSession.getAttribute(undefined, elements[nth].refId, attribute);
1117
- }
1080
+ async function extractAttributeExtension(unifiedSession, target, attribute, timeout) {
1081
+ const refId = await findTargetRefExtension(unifiedSession, target, timeout);
1082
+ if (!refId) {
1118
1083
  return null;
1119
1084
  }
1120
- if (selector) {
1121
- const nth = nthParam ?? 0;
1122
- if (text) {
1123
- // selector + text 组合:find 已实现 AND 过滤
1124
- const elements = await unifiedSession.find(selector, text, undefined);
1125
- if (nth >= elements.length) {
1126
- return null;
1127
- }
1128
- return unifiedSession.getAttribute(undefined, elements[nth].refId, attribute);
1129
- }
1130
- if (nth > 0) {
1131
- const expr = '(function(s, n, a) { var els = document.querySelectorAll(s); ' +
1132
- 'return n < els.length ? els[n].getAttribute(a) : null })';
1133
- return unifiedSession.evaluate(expr, undefined, undefined, [selector, nth, attribute]);
1134
- }
1135
- return unifiedSession.getAttribute(selector, undefined, attribute);
1136
- }
1137
- return null;
1138
- }
1139
- /**
1140
- * Extension 模式:提取 computed style
1141
- */
1142
- async function extractComputedStyleExtension(unifiedSession, selector, text, xpath, nth, prop) {
1143
- const elements = await unifiedSession.find(selector, text, xpath);
1144
- if (elements.length === 0 || nth >= elements.length) {
1145
- return null;
1085
+ if (attribute.startsWith('computed:')) {
1086
+ return unifiedSession.getComputedStyleByRef(refId, attribute.slice('computed:'.length));
1146
1087
  }
1147
- const refId = elements[nth].refId;
1148
- // 通过 Extension ISOLATED 世界执行(访问 __mcpElementMap),避免 MAIN 世界找不到 refId
1149
- return unifiedSession.getComputedStyle(refId, prop);
1088
+ return unifiedSession.getAttributeByRef(refId, attribute);
1150
1089
  }
1151
1090
  /**
1152
1091
  * Extension 模式:等待目标元素出现
@@ -1185,10 +1124,11 @@ async function waitForTargetExtension(unifiedSession, target, timeout, frame) {
1185
1124
  continue;
1186
1125
  }
1187
1126
  try {
1188
- const elements = await unifiedSession.find(selector, text, xpath, remaining);
1127
+ const indexed = nth >= 50;
1128
+ const elements = await unifiedSession.find(selector, text, xpath, remaining, indexed ? nth : undefined);
1189
1129
  matchCount = elements.length;
1190
1130
  candidates = elements;
1191
- if (elements.length > nth) {
1131
+ if (indexed ? elements.length > 0 : elements.length > nth) {
1192
1132
  return;
1193
1133
  }
1194
1134
  }