@pyrokine/mcp-chrome 3.0.1 → 3.1.0

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 (144) hide show
  1. package/README.md +678 -341
  2. package/README_zh.md +694 -291
  3. package/dist/cdp/client.d.ts +7 -3
  4. package/dist/cdp/client.d.ts.map +1 -1
  5. package/dist/cdp/client.js +252 -63
  6. package/dist/cdp/client.js.map +1 -1
  7. package/dist/cdp/launcher.d.ts +1 -1
  8. package/dist/cdp/launcher.d.ts.map +1 -1
  9. package/dist/cdp/launcher.js +33 -12
  10. package/dist/cdp/launcher.js.map +1 -1
  11. package/dist/core/auto-wait.d.ts.map +1 -1
  12. package/dist/core/auto-wait.js +88 -52
  13. package/dist/core/auto-wait.js.map +1 -1
  14. package/dist/core/browser-driver.d.ts +72 -15
  15. package/dist/core/browser-driver.d.ts.map +1 -1
  16. package/dist/core/browser-driver.js.map +1 -1
  17. package/dist/core/browser-event-schema.d.ts +287 -0
  18. package/dist/core/browser-event-schema.d.ts.map +1 -0
  19. package/dist/core/browser-event-schema.js +104 -0
  20. package/dist/core/browser-event-schema.js.map +1 -0
  21. package/dist/core/browser-events.d.ts +99 -0
  22. package/dist/core/browser-events.d.ts.map +1 -0
  23. package/dist/core/browser-events.js +1312 -0
  24. package/dist/core/browser-events.js.map +1 -0
  25. package/dist/core/challenge-page.d.ts +39 -0
  26. package/dist/core/challenge-page.d.ts.map +1 -0
  27. package/dist/core/challenge-page.js +226 -0
  28. package/dist/core/challenge-page.js.map +1 -0
  29. package/dist/core/dom-helpers.d.ts +28 -0
  30. package/dist/core/dom-helpers.d.ts.map +1 -0
  31. package/dist/core/dom-helpers.js +311 -0
  32. package/dist/core/dom-helpers.js.map +1 -0
  33. package/dist/core/errors.d.ts +4 -0
  34. package/dist/core/errors.d.ts.map +1 -1
  35. package/dist/core/errors.js +51 -7
  36. package/dist/core/errors.js.map +1 -1
  37. package/dist/core/file-upload.d.ts +22 -0
  38. package/dist/core/file-upload.d.ts.map +1 -0
  39. package/dist/core/file-upload.js +194 -0
  40. package/dist/core/file-upload.js.map +1 -0
  41. package/dist/core/locator.d.ts +10 -2
  42. package/dist/core/locator.d.ts.map +1 -1
  43. package/dist/core/locator.js +121 -200
  44. package/dist/core/locator.js.map +1 -1
  45. package/dist/core/os-mouse.d.ts +11 -0
  46. package/dist/core/os-mouse.d.ts.map +1 -1
  47. package/dist/core/os-mouse.js +102 -29
  48. package/dist/core/os-mouse.js.map +1 -1
  49. package/dist/core/retry.d.ts.map +1 -1
  50. package/dist/core/retry.js +4 -1
  51. package/dist/core/retry.js.map +1 -1
  52. package/dist/core/session.d.ts +61 -12
  53. package/dist/core/session.d.ts.map +1 -1
  54. package/dist/core/session.js +1040 -259
  55. package/dist/core/session.js.map +1 -1
  56. package/dist/core/types.d.ts +5 -1
  57. package/dist/core/types.d.ts.map +1 -1
  58. package/dist/core/types.js +16 -1
  59. package/dist/core/types.js.map +1 -1
  60. package/dist/core/unified-session.d.ts +41 -35
  61. package/dist/core/unified-session.d.ts.map +1 -1
  62. package/dist/core/unified-session.js +872 -263
  63. package/dist/core/unified-session.js.map +1 -1
  64. package/dist/core/utils.d.ts +5 -4
  65. package/dist/core/utils.d.ts.map +1 -1
  66. package/dist/core/utils.js +73 -18
  67. package/dist/core/utils.js.map +1 -1
  68. package/dist/extension/bridge.d.ts +48 -17
  69. package/dist/extension/bridge.d.ts.map +1 -1
  70. package/dist/extension/bridge.js +239 -37
  71. package/dist/extension/bridge.js.map +1 -1
  72. package/dist/extension/http-server.d.ts +7 -2
  73. package/dist/extension/http-server.d.ts.map +1 -1
  74. package/dist/extension/http-server.js +211 -49
  75. package/dist/extension/http-server.js.map +1 -1
  76. package/dist/index.js +14 -1
  77. package/dist/index.js.map +1 -1
  78. package/dist/tools/browse.d.ts.map +1 -1
  79. package/dist/tools/browse.js +56 -28
  80. package/dist/tools/browse.js.map +1 -1
  81. package/dist/tools/browser-event-output.d.ts +7 -0
  82. package/dist/tools/browser-event-output.d.ts.map +1 -0
  83. package/dist/tools/browser-event-output.js +19 -0
  84. package/dist/tools/browser-event-output.js.map +1 -0
  85. package/dist/tools/challenge.d.ts +17 -5
  86. package/dist/tools/challenge.d.ts.map +1 -1
  87. package/dist/tools/challenge.js +110 -189
  88. package/dist/tools/challenge.js.map +1 -1
  89. package/dist/tools/cookies.d.ts.map +1 -1
  90. package/dist/tools/cookies.js +33 -8
  91. package/dist/tools/cookies.js.map +1 -1
  92. package/dist/tools/diagnostics.d.ts.map +1 -1
  93. package/dist/tools/diagnostics.js +14 -0
  94. package/dist/tools/diagnostics.js.map +1 -1
  95. package/dist/tools/evaluate.d.ts +6 -5
  96. package/dist/tools/evaluate.d.ts.map +1 -1
  97. package/dist/tools/evaluate.js +92 -52
  98. package/dist/tools/evaluate.js.map +1 -1
  99. package/dist/tools/extract.d.ts.map +1 -1
  100. package/dist/tools/extract.js +149 -103
  101. package/dist/tools/extract.js.map +1 -1
  102. package/dist/tools/input.d.ts.map +1 -1
  103. package/dist/tools/input.js +555 -229
  104. package/dist/tools/input.js.map +1 -1
  105. package/dist/tools/logs.d.ts.map +1 -1
  106. package/dist/tools/logs.js +50 -11
  107. package/dist/tools/logs.js.map +1 -1
  108. package/dist/tools/manage.d.ts.map +1 -1
  109. package/dist/tools/manage.js +111 -16
  110. package/dist/tools/manage.js.map +1 -1
  111. package/dist/tools/network-sanitizer.d.ts +1 -0
  112. package/dist/tools/network-sanitizer.d.ts.map +1 -1
  113. package/dist/tools/network-sanitizer.js +30 -1
  114. package/dist/tools/network-sanitizer.js.map +1 -1
  115. package/dist/tools/page-context.d.ts +4 -3
  116. package/dist/tools/page-context.d.ts.map +1 -1
  117. package/dist/tools/page-context.js +56 -14
  118. package/dist/tools/page-context.js.map +1 -1
  119. package/dist/tools/post-condition.d.ts +1 -1
  120. package/dist/tools/post-condition.d.ts.map +1 -1
  121. package/dist/tools/post-condition.js +136 -44
  122. package/dist/tools/post-condition.js.map +1 -1
  123. package/dist/tools/schema.d.ts +7 -4
  124. package/dist/tools/schema.d.ts.map +1 -1
  125. package/dist/tools/schema.js +32 -122
  126. package/dist/tools/schema.js.map +1 -1
  127. package/dist/tools/target-diagnostics.d.ts +3 -3
  128. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  129. package/dist/tools/target-diagnostics.js +17 -7
  130. package/dist/tools/target-diagnostics.js.map +1 -1
  131. package/dist/tools/wait.d.ts.map +1 -1
  132. package/dist/tools/wait.js +94 -40
  133. package/dist/tools/wait.js.map +1 -1
  134. package/extension/dist/assets/{content.ts-qe6IB5DK.js → content.ts-BAMOcF3R.js} +1 -1
  135. package/extension/dist/assets/{content.ts-loader-DUWbDHRS.js → content.ts-loader-4F9a1EWZ.js} +1 -1
  136. package/extension/dist/assets/index.ts-B79g2ikq.js +19820 -0
  137. package/extension/dist/assets/{page-scripts-D508WLkW.js → page-scripts-CSxn58h1.js} +257 -366
  138. package/extension/dist/assets/{popup.html-B-eVq48O.js → popup.html-DwwHo00N.js} +2 -2
  139. package/extension/dist/manifest.json +4 -4
  140. package/extension/dist/service-worker-loader.js +1 -1
  141. package/extension/dist/src/popup/popup.html +3 -3
  142. package/package.json +8 -6
  143. package/scripts/start-chrome.ps1 +9 -1
  144. package/extension/dist/assets/index.ts-D7_LCUoV.js +0 -9319
@@ -1 +1 @@
1
- {"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/tools/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAu8CxE;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAS3D"}
1
+ {"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/tools/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAkiDxE;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAS3D"}
@@ -13,16 +13,20 @@
13
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, StructuredToolError, TMP_PATH_PREFIX, writePrivateFile, } from '../core/index.js';
16
+ import { installDomHelpers } from '../core/dom-helpers.js';
17
17
  import { ElementNotFoundError } from '../core/errors.js';
18
+ import { CWD_PATH_PREFIX, formatErrorResponse, formatResponse, getSession, getUnifiedSession, resolveScopedOutputPath, StructuredToolError, TMP_PATH_PREFIX, writePrivateFile, } from '../core/index.js';
18
19
  import { DEFAULT_TIMEOUT } from '../core/types.js';
19
- import { sanitizeUrlRecords } from './network-sanitizer.js';
20
+ import { remainingNavigationTimeout } from '../core/utils.js';
21
+ import { sanitizePageUrls, sanitizeUrlRecord, sanitizeUrlRecords } from './network-sanitizer.js';
20
22
  import { withPageContext } from './page-context.js';
21
23
  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';
24
+ import { frameZodSchema, pageTargetIdSchema, resolvePageTargetId, targetToFindParams, targetZodSchema, } from './schema.js';
23
25
  import { buildTargetDiagnostics, enrichTargetError, targetLookupTimeout, TargetNotFoundError, TargetTimeoutError, } from './target-diagnostics.js';
24
26
  /** 无 output 时附录返回的最大图片数 */
25
27
  const MAX_APPENDIX_IMAGES = 20;
28
+ const MAX_IMAGE_BYTES = 2 * 1024 * 1024;
29
+ const MAX_IMAGE_REQUEST_BYTES = 8 * 1024 * 1024;
26
30
  /**
27
31
  * extract 参数 schema
28
32
  */
@@ -83,11 +87,11 @@ const extractSchema = z
83
87
  .optional()
84
88
  .describe('页面状态提取模式(state 类型有效),accessibility=可访问性树(默认,与原 read_page 一致),' +
85
89
  'domsnapshot=DOMSnapshot 全量快照(CDP 或受控 Extension 页面,不支持 target/frame/depth 限定)'),
86
- timeout: z.number().optional().describe('等待目标元素超时'),
87
- frame: z
88
- .union([z.string(), z.number()])
90
+ timeout: z
91
+ .number()
89
92
  .optional()
90
- .describe('iframe 定位(可选,仅 Extension 模式),CSS 选择器(如 "iframe#main")或索引(如 0),不指定则在主框架操作'),
93
+ .describe('浏览器操作总预算(毫秒,默认 30000),包含排队、页面/frame 准备、目标等待、内容读取和页面元信息读取'),
94
+ frame: frameZodSchema.describe('iframe selector/索引或逐层路径(如 ["iframe#outer", 0]),省略时使用主文档'),
91
95
  })
92
96
  .superRefine((args, context) => {
93
97
  if (args.diffOutput && !args.compareWith) {
@@ -98,7 +102,7 @@ const extractSchema = z
98
102
  });
99
103
  }
100
104
  });
101
- async function handleExtract(args) {
105
+ async function handleExtract(args, signal) {
102
106
  const timeout = args.timeout ?? DEFAULT_TIMEOUT;
103
107
  const deadline = Date.now() + timeout;
104
108
  try {
@@ -119,7 +123,7 @@ async function handleExtract(args) {
119
123
  const session = getSession();
120
124
  // Extension 路径:等待目标元素出现(如果指定了 target + timeout)
121
125
  if (useExtension && args.target && args.timeout !== undefined) {
122
- await waitForTargetExtension(unifiedSession, args.target, args.timeout, args.frame);
126
+ await waitForTargetExtension(unifiedSession, args.target, remainingNavigationTimeout(deadline), args.frame);
123
127
  }
124
128
  try {
125
129
  const scopedArgs = !useExtension && args.target
@@ -137,8 +141,8 @@ async function handleExtract(args) {
137
141
  }
138
142
  throw error;
139
143
  }
140
- }); // withFrame
141
- }); // withTabId
144
+ }, deadline); // withFrame
145
+ }, deadline, signal); // withTabId
142
146
  }
143
147
  catch (error) {
144
148
  return formatErrorResponse(error);
@@ -245,7 +249,7 @@ async function handleAttributeExtract({ unifiedSession, session, useExtension },
245
249
  async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
246
250
  let clip;
247
251
  if (args.target && !args.clip) {
248
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(args.target);
252
+ const { selector, text, xpath, nth: nthParam, semantic, } = targetToFindParams(args.target);
249
253
  const nth = nthParam ?? 0;
250
254
  const pointTarget = 'x' in args.target && 'y' in args.target ? args.target : null;
251
255
  const found = pointTarget
@@ -253,7 +257,10 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
253
257
  ? await unifiedSession.findAtPoint(pointTarget.x, pointTarget.y, nth, args.timeout)
254
258
  : await unifiedSession
255
259
  .evaluate(`(() => {
256
- const element = document.elementFromPoint(${pointTarget.x}, ${pointTarget.y});
260
+ (${installDomHelpers.toString()})();
261
+ const element = globalThis.__mcpDomHelpers.deepElementFromPoint(
262
+ ${pointTarget.x}, ${pointTarget.y}
263
+ );
257
264
  if (!element) return null;
258
265
  const rect = element.getBoundingClientRect();
259
266
  return {
@@ -262,14 +269,14 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
262
269
  };
263
270
  })()`, undefined, args.timeout)
264
271
  .then((element) => (element && nth === 0 ? [element] : []))
265
- : await unifiedSession.find(selector, text, xpath, args.timeout);
266
- const target = found[pointTarget ? 0 : nth];
272
+ : await unifiedSession.find(selector, text, xpath, args.timeout, semantic, nth);
273
+ const target = found[0];
267
274
  if (!target || target.rect.width <= 0 || target.rect.height <= 0) {
268
275
  throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
269
276
  nth,
270
277
  timeout: args.timeout,
271
278
  frame: args.frame,
272
- matchCount: found.length,
279
+ matchCount: null,
273
280
  lastState: target ? 'zero-size' : 'not-found',
274
281
  candidates: found,
275
282
  }));
@@ -304,6 +311,9 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
304
311
  const dimensions = encodedDimensions ?? fallbackDimensions;
305
312
  const metadata = {
306
313
  format: screenshot.format,
314
+ ...(screenshot.degraded !== undefined ? { degraded: screenshot.degraded } : {}),
315
+ ...(screenshot.fallback !== undefined ? { fallback: screenshot.fallback } : {}),
316
+ ...(screenshot.limitations !== undefined ? { limitations: screenshot.limitations } : {}),
307
317
  width: dimensions?.width,
308
318
  height: dimensions?.height,
309
319
  dimensionSource: dimensions?.source,
@@ -350,7 +360,7 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
350
360
  ],
351
361
  };
352
362
  }
353
- async function handleStateExtract({ unifiedSession, useExtension }, args) {
363
+ async function handleStateExtract({ unifiedSession, session, useExtension }, args) {
354
364
  if (args.mode === 'domsnapshot') {
355
365
  return handleDomSnapshotState(unifiedSession, args);
356
366
  }
@@ -358,15 +368,15 @@ async function handleStateExtract({ unifiedSession, useExtension }, args) {
358
368
  if (args.target && useExtension) {
359
369
  refId = await findTargetRefExtension(unifiedSession, args.target, args.timeout);
360
370
  if (!refId) {
361
- const { selector, text, xpath, nth: nthParam, } = targetToFindParams(args.target);
371
+ const { selector, text, xpath, nth: nthParam, semantic, } = targetToFindParams(args.target);
362
372
  const candidates = 'x' in args.target && 'y' in args.target
363
373
  ? await unifiedSession.findAtPoint(args.target.x, args.target.y)
364
- : await unifiedSession.find(selector, text, xpath, args.timeout);
374
+ : await unifiedSession.find(selector, text, xpath, args.timeout, semantic);
365
375
  throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
366
376
  nth: nthParam ?? 0,
367
377
  timeout: args.timeout,
368
378
  frame: args.frame,
369
- matchCount: candidates.length,
379
+ matchCount: candidates.length < 50 ? candidates.length : null,
370
380
  lastState: 'not-found',
371
381
  candidates,
372
382
  }));
@@ -379,7 +389,9 @@ async function handleStateExtract({ unifiedSession, useExtension }, args) {
379
389
  if (args.depth !== undefined) {
380
390
  readPageOptions.depth = args.depth;
381
391
  }
382
- const state = await unifiedSession.readPage(Object.keys(readPageOptions).length > 0 ? readPageOptions : undefined);
392
+ const state = sanitizePageUrls(useExtension
393
+ ? await unifiedSession.readPage(Object.keys(readPageOptions).length > 0 ? readPageOptions : undefined)
394
+ : await session.readPage({ target: args.target, depth: args.depth, timeout: args.timeout }));
383
395
  if (args.output) {
384
396
  const outputPath = await writeOutputFile(args.output, JSON.stringify(state, null, 2), 'utf-8');
385
397
  return formatResponse({ success: true, type: 'state', output: outputPath });
@@ -400,15 +412,15 @@ async function handleDomSnapshotState(unifiedSession, args) {
400
412
  }
401
413
  async function handleDiagnosticBundleExtract({ unifiedSession }, args) {
402
414
  const state = await unifiedSession.getLiveState().catch(() => null);
403
- const metadata = await unifiedSession.getMetadata();
404
- const frames = await unifiedSession.getFrames();
415
+ const metadata = sanitizePageUrls(await unifiedSession.getMetadata());
416
+ const frames = sanitizePageUrls(await unifiedSession.getFrames());
405
417
  await unifiedSession.enableConsole();
406
418
  await unifiedSession.enableNetwork();
407
419
  const consoleLogs = sanitizeUrlRecords(await unifiedSession.getConsoleLogs());
408
420
  const networkRequests = sanitizeUrlRecords(await unifiedSession.getNetworkRequests());
409
421
  const bundle = {
410
422
  schema: 'mcp-chrome.diagnosticBundle.v1',
411
- url: state?.url,
423
+ ...sanitizeUrlRecord({ url: state?.url }),
412
424
  title: state?.title,
413
425
  managed: state?.managed ?? false,
414
426
  mode: unifiedSession.getMode(),
@@ -431,12 +443,12 @@ async function handleDiagnosticBundleExtract({ unifiedSession }, args) {
431
443
  },
432
444
  };
433
445
  const summary = {
434
- url: bundle.url,
446
+ ...sanitizeUrlRecord({ url: state?.url }),
435
447
  title: bundle.title,
436
448
  managed: bundle.managed,
437
449
  mode: bundle.mode,
438
450
  frameCount: Array.isArray(frames.frames) ? frames.frames.length : 0,
439
- consoleErrors: bundle.consoleSummary.recentErrors.length,
451
+ consoleErrors: bundle.consoleSummary.recentErrors.filter((item) => item.level === 'error').length,
440
452
  networkFailures: bundle.networkSummary.recentFailures.length,
441
453
  };
442
454
  if (args.output) {
@@ -453,8 +465,8 @@ async function handleDiagnosticBundleExtract({ unifiedSession }, args) {
453
465
  });
454
466
  }
455
467
  async function handleMetadataExtract({ unifiedSession }, args) {
456
- const metadata = await unifiedSession.getMetadata();
457
- const frames = await unifiedSession.getFrames();
468
+ const metadata = sanitizePageUrls(await unifiedSession.getMetadata());
469
+ const frames = sanitizePageUrls(await unifiedSession.getFrames());
458
470
  if (args.output) {
459
471
  const outputPath = await writeOutputFile(args.output, JSON.stringify({ ...metadata, ...frames }, null, 2), 'utf-8');
460
472
  return formatResponse({ success: true, type: 'metadata', output: outputPath });
@@ -477,8 +489,10 @@ function invalidExtractTypeResponse(args) {
477
489
  // ==================== HTML + 图片提取 ====================
478
490
  /** 写入文件前自动创建父目录,并收敛到受控范围 */
479
491
  async function writeOutputFile(path, data, encoding) {
492
+ const session = getUnifiedSession();
493
+ session.assertRequestActive();
480
494
  const resolvedPath = await resolveScopedOutputPath(path, 'mcp-chrome');
481
- await writePrivateFile(resolvedPath.absolutePath, data, encoding);
495
+ await writePrivateFile(resolvedPath.absolutePath, data, encoding, () => session.assertRequestActive());
482
496
  return resolvedPath.absolutePath;
483
497
  }
484
498
  async function getPageScrollOffset(unifiedSession, timeout) {
@@ -621,18 +635,18 @@ function readWebpDimensions(buffer) {
621
635
  async function handleHtmlWithImages(unifiedSession, session, useExtension, args) {
622
636
  let result;
623
637
  if (args.target) {
624
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(args.target);
638
+ const { selector, text, xpath, nth: nthParam, semantic, } = targetToFindParams(args.target);
625
639
  const nth = nthParam ?? 0;
626
640
  if (useExtension) {
627
641
  const refId = await findTargetRefExtension(unifiedSession, args.target, args.timeout);
628
642
  if (!refId) {
629
643
  const matches = 'x' in args.target && 'y' in args.target
630
644
  ? await unifiedSession.findAtPoint(args.target.x, args.target.y)
631
- : await unifiedSession.find(selector, text, xpath, args.timeout);
645
+ : await unifiedSession.find(selector, text, xpath, args.timeout, semantic);
632
646
  throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
633
647
  nth,
634
648
  timeout: args.timeout,
635
- matchCount: matches.length,
649
+ matchCount: matches.length < 50 ? matches.length : null,
636
650
  lastState: 'not-found',
637
651
  candidates: matches,
638
652
  }));
@@ -640,12 +654,12 @@ async function handleHtmlWithImages(unifiedSession, session, useExtension, args)
640
654
  result = await unifiedSession.getHtmlWithImagesByRef(refId);
641
655
  }
642
656
  else {
643
- const matches = await unifiedSession.find(selector, text, xpath, args.timeout);
644
- if (matches.length <= nth) {
657
+ const matches = await unifiedSession.find(selector, text, xpath, args.timeout, semantic, nth);
658
+ if (matches.length === 0) {
645
659
  throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
646
660
  nth,
647
661
  timeout: args.timeout,
648
- matchCount: matches.length,
662
+ matchCount: null,
649
663
  lastState: 'not-found',
650
664
  candidates: matches,
651
665
  }));
@@ -677,20 +691,25 @@ async function handleHtmlWithImages(unifiedSession, session, useExtension, args)
677
691
  }
678
692
  // data 模式:获取图片数据
679
693
  const appendixMode = !args.output;
680
- const imageDataList = await fetchImageData(unifiedSession, result.images, appendixMode ? MAX_APPENDIX_IMAGES : undefined);
694
+ const imageData = fetchImageData(unifiedSession, result.images, appendixMode ? MAX_APPENDIX_IMAGES : undefined, !appendixMode);
681
695
  if (args.output) {
682
696
  const outputDir = (await resolveScopedOutputPath(args.output, 'mcp-chrome')).absolutePath;
683
- // 写入目录
684
- await writeImageDirectory(outputDir, result.html, result.images, imageDataList);
697
+ const omittedImages = await writeImageDirectory(outputDir, result.html, result.images, imageData, () => unifiedSession.assertRequestActive());
685
698
  return formatResponse({
686
699
  success: true,
687
700
  type: 'html',
688
701
  output: outputDir,
689
702
  imageCount: result.images.length,
690
703
  index: join(outputDir, 'index.json'),
704
+ omittedImages,
705
+ imageByteLimit: MAX_IMAGE_BYTES,
706
+ imageRequestByteLimit: MAX_IMAGE_REQUEST_BYTES,
691
707
  });
692
708
  }
693
- // 无 output:MCP 附录方式返回
709
+ const imageDataList = [];
710
+ for await (const data of imageData) {
711
+ imageDataList.push(data);
712
+ }
694
713
  return buildImageAppendixResponse(result.html, result.images, imageDataList);
695
714
  }
696
715
  async function extractHtmlWithImagesByTarget(unifiedSession, selector, text, xpath, nth, timeout) {
@@ -779,68 +798,73 @@ async function extractHtmlWithImagesCdp(session, selector, timeout) {
779
798
  *
780
799
  * 策略:
781
800
  * 1. data: URL → 直接解码
782
- * 2. CDP Page.getResourceContent(批量) → 从浏览器缓存读取(零网络请求)
801
+ * 2. CDP Page.getResourceContent → 逐图读取浏览器缓存(零网络请求)
783
802
  *
784
803
  * @param unifiedSession 会话管理器,用于 CDP 资源获取
785
804
  * @param images 图片元信息列表
786
- * @param limit 最多获取前 N 张图片数据(附录模式限流),超出的返回 null
805
+ * @param limit 最多获取前 N 张图片数据(附录模式限流),超出的图片 base64 为 null
806
+ * @param skipDuplicates 是否跳过重复图片来源
787
807
  */
788
- async function fetchImageData(unifiedSession, images, limit) {
789
- const effectiveLimit = limit ?? images.length;
790
- // 第一趟:解析 data: URL + 收集需要 CDP 获取的 URL(去重)
791
- const preResolved = [];
792
- const cdpUrlSet = new Set();
793
- for (let i = 0; i < images.length; i++) {
808
+ async function* fetchImageData(unifiedSession, images, limit = images.length, skipDuplicates = false) {
809
+ let usedBytes = 0;
810
+ const sources = new Set();
811
+ for (let i = 0; i < images.length; ++i) {
812
+ unifiedSession.assertRequestActive();
794
813
  const img = images[i];
795
- const effectiveSrc = img.src || img.dataSrc;
796
- if (i >= effectiveLimit || !effectiveSrc) {
797
- preResolved.push({ base64: null, mimeType: 'image/png' });
814
+ const src = img.src || img.dataSrc;
815
+ const mimeType = guessMimeType(src);
816
+ if (skipDuplicates && sources.has(src)) {
817
+ yield { base64: null, mimeType };
798
818
  continue;
799
819
  }
800
- if (effectiveSrc.startsWith('data:')) {
801
- const match = effectiveSrc.match(/^data:(?<mime>[^;]+);base64,(?<data>.+)$/);
802
- preResolved.push(match
803
- ? { base64: match.groups.data, mimeType: match.groups.mime }
804
- : { base64: null, mimeType: 'image/png' });
820
+ if (i >= limit) {
821
+ yield { base64: null, mimeType, omitted: 'appendix-limit' };
805
822
  continue;
806
823
  }
807
- if (!effectiveSrc.startsWith('http')) {
808
- preResolved.push({ base64: null, mimeType: guessMimeType(effectiveSrc) });
824
+ if (usedBytes >= MAX_IMAGE_REQUEST_BYTES) {
825
+ yield { base64: null, mimeType, omitted: 'request-byte-limit' };
809
826
  continue;
810
827
  }
811
- // 只有 src 非空(浏览器实际请求过的)才走 CDP 缓存
812
- if (img.src) {
813
- cdpUrlSet.add(img.src);
828
+ let base64;
829
+ let resolvedMime = mimeType;
830
+ if (src.startsWith('data:')) {
831
+ const match = /^data:(?<mimeType>[^;]+);base64,/.exec(src);
832
+ if (match) {
833
+ resolvedMime = match[1];
834
+ base64 = src.slice(match[0].length);
835
+ }
814
836
  }
815
- preResolved.push(null); // 需要进一步获取
816
- }
817
- // 第二趟:批量 CDP 获取
818
- const cdpResults = await unifiedSession.getResourceContentBatch([...cdpUrlSet]);
819
- // 第三趟:组装结果,CDP 未命中的返回 null
820
- const results = [];
821
- for (let i = 0; i < images.length; i++) {
822
- if (preResolved[i] !== null) {
823
- results.push(preResolved[i]);
837
+ else if (img.src && /^https?:/.test(src)) {
838
+ const resource = (await unifiedSession.getResourceContentBatch([img.src], 1)).get(img.src);
839
+ unifiedSession.assertRequestActive();
840
+ if (resource) {
841
+ if (!resource.base64Encoded && Buffer.byteLength(resource.content) > MAX_IMAGE_BYTES) {
842
+ yield { base64: null, mimeType, omitted: 'image-byte-limit' };
843
+ continue;
844
+ }
845
+ base64 = resource.base64Encoded ? resource.content : Buffer.from(resource.content).toString('base64');
846
+ }
847
+ }
848
+ if (base64 === undefined) {
849
+ yield { base64: null, mimeType: resolvedMime, omitted: 'unavailable' };
824
850
  continue;
825
851
  }
826
- const img = images[i];
827
- const effectiveSrc = img.src || img.dataSrc;
828
- const mimeType = guessMimeType(effectiveSrc);
829
- // 尝试 CDP 缓存
830
- if (img.src && cdpResults.has(img.src)) {
831
- const resource = cdpResults.get(img.src);
832
- if (resource.base64Encoded) {
833
- results.push({ base64: resource.content, mimeType });
834
- }
835
- else {
836
- results.push({ base64: Buffer.from(resource.content).toString('base64'), mimeType });
837
- }
852
+ const bytes = Buffer.byteLength(base64, 'base64');
853
+ const omitted = bytes > MAX_IMAGE_BYTES
854
+ ? 'image-byte-limit'
855
+ : usedBytes + bytes > MAX_IMAGE_REQUEST_BYTES
856
+ ? 'request-byte-limit'
857
+ : undefined;
858
+ if (omitted) {
859
+ yield { base64: null, mimeType: resolvedMime, omitted };
838
860
  continue;
839
861
  }
840
- // CDP 缓存未命中,不使用 Node.js fetch(避免绕过浏览器同源策略)
841
- results.push({ base64: null, mimeType });
862
+ usedBytes += bytes;
863
+ if (skipDuplicates) {
864
+ sources.add(src);
865
+ }
866
+ yield { base64, mimeType: resolvedMime };
842
867
  }
843
- return results;
844
868
  }
845
869
  /**
846
870
  * 写入图片目录
@@ -853,18 +877,20 @@ async function fetchImageData(unifiedSession, images, limit) {
853
877
  * 1-icon.png
854
878
  * index.json
855
879
  */
856
- async function writeImageDirectory(outputDir, html, images, imageDataList) {
880
+ async function writeImageDirectory(outputDir, html, images, imageDataList, assertActive) {
857
881
  const imagesDir = join(outputDir, 'images');
858
882
  // 写入 HTML
859
- await writePrivateFile(join(outputDir, 'content.html'), html, 'utf-8');
883
+ await writePrivateFile(join(outputDir, 'content.html'), html, 'utf-8', assertActive);
860
884
  // 写入图片文件 + 构建索引(相同 src 去重)
861
885
  const indexEntries = [];
862
886
  const writtenFiles = new Map(); // src → file path
863
- for (let i = 0; i < images.length; i++) {
887
+ let i = 0;
888
+ let omittedImages = 0;
889
+ for await (const data of imageDataList) {
890
+ assertActive?.();
864
891
  const img = images[i];
865
- const data = imageDataList[i];
866
892
  const src = img.src || img.dataSrc;
867
- let file = null;
893
+ let file = writtenFiles.get(src) ?? null;
868
894
  if (data.base64) {
869
895
  // 相同 src 复用已写入的文件
870
896
  const existing = writtenFiles.get(src);
@@ -876,7 +902,7 @@ async function writeImageDirectory(outputDir, html, images, imageDataList) {
876
902
  const safeName = sanitizeFilename(src);
877
903
  const filename = `${i}-${safeName}${ext}`;
878
904
  file = `images/${filename}`;
879
- await writePrivateFile(join(imagesDir, filename), Buffer.from(data.base64, 'base64'));
905
+ await writePrivateFile(join(imagesDir, filename), Buffer.from(data.base64, 'base64'), undefined, assertActive);
880
906
  writtenFiles.set(src, file);
881
907
  }
882
908
  }
@@ -887,13 +913,19 @@ async function writeImageDirectory(outputDir, html, images, imageDataList) {
887
913
  width: img.width,
888
914
  height: img.height,
889
915
  file,
916
+ ...(data.omitted ? { omitted: data.omitted } : {}),
890
917
  });
918
+ if (data.omitted) {
919
+ ++omittedImages;
920
+ }
921
+ ++i;
891
922
  }
892
923
  // 写入索引
893
924
  await writePrivateFile(join(outputDir, 'index.json'), JSON.stringify({
894
925
  html: 'content.html',
895
926
  images: indexEntries,
896
- }, null, 2), 'utf-8');
927
+ }, null, 2), 'utf-8', assertActive);
928
+ return omittedImages;
897
929
  }
898
930
  /**
899
931
  * 构造附录式 MCP 响应
@@ -915,6 +947,9 @@ function buildImageAppendixResponse(html, images, imageDataList) {
915
947
  type: 'html',
916
948
  content: html,
917
949
  imageCount: images.length,
950
+ imageByteLimit: MAX_IMAGE_BYTES,
951
+ imageRequestByteLimit: MAX_IMAGE_REQUEST_BYTES,
952
+ omittedImages: imageDataList.filter((image) => image.omitted).length,
918
953
  }),
919
954
  });
920
955
  if (images.length === 0) {
@@ -931,7 +966,11 @@ function buildImageAppendixResponse(html, images, imageDataList) {
931
966
  // 图片标注
932
967
  const sizeStr = img.naturalWidth ? `${img.naturalWidth}×${img.naturalHeight}` : `${img.width}×${img.height}`;
933
968
  const altStr = img.alt ? ` alt="${img.alt}"` : '';
934
- content.push({ type: 'text', text: `\n[${img.index}] ${effectiveSrc}${altStr} ${sizeStr}` });
969
+ content.push({
970
+ type: 'text',
971
+ text: `\n[${img.index}] ${effectiveSrc}${altStr} ${sizeStr}` +
972
+ (data.omitted ? ` omitted=${data.omitted}` : ''),
973
+ });
935
974
  // 在限制内且有数据时附带图片(SVG 等不支持的格式跳过 image block)
936
975
  if (i < limit && data.base64 && SUPPORTED_IMAGE_MIMES.has(data.mimeType)) {
937
976
  content.push({ type: 'image', data: data.base64, mimeType: data.mimeType });
@@ -940,7 +979,7 @@ function buildImageAppendixResponse(html, images, imageDataList) {
940
979
  if (images.length > MAX_APPENDIX_IMAGES) {
941
980
  content.push({
942
981
  type: 'text',
943
- text: `\n(共 ${images.length} 张图片,仅前 ${MAX_APPENDIX_IMAGES} 张附带数据,使用 output 参数导出全部图片)`,
982
+ text: `\n(共 ${images.length} 张图片,仅前 ${MAX_APPENDIX_IMAGES} 张附带数据,使用 output 参数导出图片,字节预算仍适用)`,
944
983
  });
945
984
  }
946
985
  return { content };
@@ -1046,10 +1085,10 @@ async function extractAttribute(session, target, attribute, timeout) {
1046
1085
  }`);
1047
1086
  }
1048
1087
  async function findTargetRefExtension(unifiedSession, target, timeout) {
1049
- const { selector, text, xpath, nth } = targetToFindParams(target);
1088
+ const { selector, text, xpath, nth, semantic } = targetToFindParams(target);
1050
1089
  const matches = 'x' in target && 'y' in target
1051
1090
  ? await unifiedSession.findAtPoint(target.x, target.y, nth ?? 0, timeout)
1052
- : await unifiedSession.find(selector, text, xpath, timeout, nth ?? 0);
1091
+ : await unifiedSession.find(selector, text, xpath, timeout, semantic, nth ?? 0);
1053
1092
  return matches[0]?.refId;
1054
1093
  }
1055
1094
  /**
@@ -1097,12 +1136,13 @@ async function waitForTargetExtension(unifiedSession, target, timeout, frame) {
1097
1136
  if ('x' in target && 'y' in target) {
1098
1137
  return;
1099
1138
  }
1139
+ unifiedSession.preserveTargetAfterLookup();
1100
1140
  const startTime = Date.now();
1101
1141
  const retryDelay = 100;
1102
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
1142
+ const { selector, text, xpath, nth: nthParam, semantic } = targetToFindParams(target);
1103
1143
  const nth = nthParam ?? 0;
1104
1144
  let lastError = null;
1105
- let matchCount = 0;
1145
+ let matchCount = null;
1106
1146
  let candidates = [];
1107
1147
  while (true) {
1108
1148
  const elapsed = Date.now() - startTime;
@@ -1110,6 +1150,7 @@ async function waitForTargetExtension(unifiedSession, target, timeout, frame) {
1110
1150
  throw new TargetTimeoutError(await buildTargetDiagnostics(unifiedSession, target, {
1111
1151
  nth,
1112
1152
  timeout,
1153
+ deadline: startTime + timeout,
1113
1154
  frame,
1114
1155
  matchCount,
1115
1156
  lastState: 'attached',
@@ -1124,16 +1165,21 @@ async function waitForTargetExtension(unifiedSession, target, timeout, frame) {
1124
1165
  continue;
1125
1166
  }
1126
1167
  try {
1127
- const indexed = nth >= 50;
1128
- const elements = await unifiedSession.find(selector, text, xpath, remaining, indexed ? nth : undefined);
1129
- matchCount = elements.length;
1168
+ const elements = await unifiedSession.find(selector, text, xpath, remaining, semantic);
1169
+ matchCount = elements.length < 50 ? elements.length : null;
1130
1170
  candidates = elements;
1131
- if (indexed ? elements.length > 0 : elements.length > nth) {
1171
+ const selected = nth < 50
1172
+ ? elements[nth]
1173
+ : (await unifiedSession.find(selector, text, xpath, Math.max(1, timeout - (Date.now() - startTime)), semantic, nth))[0];
1174
+ if (selected) {
1132
1175
  return;
1133
1176
  }
1134
1177
  }
1135
1178
  catch (err) {
1136
- // 暂时性错误(RPC 超时、发送失败、连接断开)可重试,其他确定性错误立即抛出
1179
+ if (err instanceof StructuredToolError && err.context.actionStatus === 'unknown') {
1180
+ throw err;
1181
+ }
1182
+ // 仅重试尚未派发成功的暂时性错误
1137
1183
  if (err instanceof Error &&
1138
1184
  /Request timeout|Failed to send|disconnect|未连接|stopped|replaced/i.test(err.message)) {
1139
1185
  lastError = err;
@@ -1158,6 +1204,6 @@ export function registerExtractTool(server) {
1158
1204
  server.registerTool('extract', {
1159
1205
  description: `提取页面内容:文本、HTML(可附带图片)、iframe HTML、属性、截图、状态、页面元信息`,
1160
1206
  inputSchema: extractSchema,
1161
- }, (args) => handleExtract(args));
1207
+ }, (args, extra) => handleExtract(args, extra?.signal));
1162
1208
  }
1163
1209
  //# sourceMappingURL=extract.js.map