@pyrokine/mcp-chrome 3.0.1 → 3.1.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 (150) hide show
  1. package/README.md +1060 -432
  2. package/README_zh.md +936 -349
  3. package/dist/cdp/client.d.ts +8 -3
  4. package/dist/cdp/client.d.ts.map +1 -1
  5. package/dist/cdp/client.js +260 -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 +73 -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 +105 -0
  22. package/dist/core/browser-events.d.ts.map +1 -0
  23. package/dist/core/browser-events.js +1482 -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 +231 -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/error-sanitizer.d.ts.map +1 -1
  34. package/dist/core/error-sanitizer.js +2 -1
  35. package/dist/core/error-sanitizer.js.map +1 -1
  36. package/dist/core/errors.d.ts +4 -0
  37. package/dist/core/errors.d.ts.map +1 -1
  38. package/dist/core/errors.js +57 -9
  39. package/dist/core/errors.js.map +1 -1
  40. package/dist/core/file-upload.d.ts +22 -0
  41. package/dist/core/file-upload.d.ts.map +1 -0
  42. package/dist/core/file-upload.js +194 -0
  43. package/dist/core/file-upload.js.map +1 -0
  44. package/dist/core/locator.d.ts +11 -2
  45. package/dist/core/locator.d.ts.map +1 -1
  46. package/dist/core/locator.js +135 -206
  47. package/dist/core/locator.js.map +1 -1
  48. package/dist/core/os-mouse.d.ts +11 -0
  49. package/dist/core/os-mouse.d.ts.map +1 -1
  50. package/dist/core/os-mouse.js +104 -29
  51. package/dist/core/os-mouse.js.map +1 -1
  52. package/dist/core/retry.d.ts.map +1 -1
  53. package/dist/core/retry.js +4 -1
  54. package/dist/core/retry.js.map +1 -1
  55. package/dist/core/session.d.ts +62 -12
  56. package/dist/core/session.d.ts.map +1 -1
  57. package/dist/core/session.js +1174 -304
  58. package/dist/core/session.js.map +1 -1
  59. package/dist/core/types.d.ts +5 -1
  60. package/dist/core/types.d.ts.map +1 -1
  61. package/dist/core/types.js +16 -1
  62. package/dist/core/types.js.map +1 -1
  63. package/dist/core/unified-session.d.ts +48 -37
  64. package/dist/core/unified-session.d.ts.map +1 -1
  65. package/dist/core/unified-session.js +982 -294
  66. package/dist/core/unified-session.js.map +1 -1
  67. package/dist/core/utils.d.ts +8 -4
  68. package/dist/core/utils.d.ts.map +1 -1
  69. package/dist/core/utils.js +76 -18
  70. package/dist/core/utils.js.map +1 -1
  71. package/dist/extension/bridge.d.ts +48 -17
  72. package/dist/extension/bridge.d.ts.map +1 -1
  73. package/dist/extension/bridge.js +288 -46
  74. package/dist/extension/bridge.js.map +1 -1
  75. package/dist/extension/http-server.d.ts +8 -2
  76. package/dist/extension/http-server.d.ts.map +1 -1
  77. package/dist/extension/http-server.js +211 -49
  78. package/dist/extension/http-server.js.map +1 -1
  79. package/dist/index.js +15 -1
  80. package/dist/index.js.map +1 -1
  81. package/dist/tools/browse.d.ts.map +1 -1
  82. package/dist/tools/browse.js +56 -28
  83. package/dist/tools/browse.js.map +1 -1
  84. package/dist/tools/browser-event-output.d.ts +7 -0
  85. package/dist/tools/browser-event-output.d.ts.map +1 -0
  86. package/dist/tools/browser-event-output.js +19 -0
  87. package/dist/tools/browser-event-output.js.map +1 -0
  88. package/dist/tools/challenge.d.ts +18 -5
  89. package/dist/tools/challenge.d.ts.map +1 -1
  90. package/dist/tools/challenge.js +217 -200
  91. package/dist/tools/challenge.js.map +1 -1
  92. package/dist/tools/cookies.d.ts.map +1 -1
  93. package/dist/tools/cookies.js +34 -8
  94. package/dist/tools/cookies.js.map +1 -1
  95. package/dist/tools/diagnostics.d.ts.map +1 -1
  96. package/dist/tools/diagnostics.js +15 -0
  97. package/dist/tools/diagnostics.js.map +1 -1
  98. package/dist/tools/evaluate.d.ts +6 -5
  99. package/dist/tools/evaluate.d.ts.map +1 -1
  100. package/dist/tools/evaluate.js +94 -52
  101. package/dist/tools/evaluate.js.map +1 -1
  102. package/dist/tools/extract.d.ts.map +1 -1
  103. package/dist/tools/extract.js +293 -153
  104. package/dist/tools/extract.js.map +1 -1
  105. package/dist/tools/input.d.ts.map +1 -1
  106. package/dist/tools/input.js +747 -282
  107. package/dist/tools/input.js.map +1 -1
  108. package/dist/tools/logs.d.ts.map +1 -1
  109. package/dist/tools/logs.js +50 -11
  110. package/dist/tools/logs.js.map +1 -1
  111. package/dist/tools/manage.d.ts.map +1 -1
  112. package/dist/tools/manage.js +123 -18
  113. package/dist/tools/manage.js.map +1 -1
  114. package/dist/tools/network-sanitizer.d.ts +2 -0
  115. package/dist/tools/network-sanitizer.d.ts.map +1 -1
  116. package/dist/tools/network-sanitizer.js +53 -10
  117. package/dist/tools/network-sanitizer.js.map +1 -1
  118. package/dist/tools/page-context.d.ts +4 -3
  119. package/dist/tools/page-context.d.ts.map +1 -1
  120. package/dist/tools/page-context.js +57 -14
  121. package/dist/tools/page-context.js.map +1 -1
  122. package/dist/tools/png.d.ts.map +1 -1
  123. package/dist/tools/png.js +12 -3
  124. package/dist/tools/png.js.map +1 -1
  125. package/dist/tools/post-condition.d.ts +1 -1
  126. package/dist/tools/post-condition.d.ts.map +1 -1
  127. package/dist/tools/post-condition.js +163 -47
  128. package/dist/tools/post-condition.js.map +1 -1
  129. package/dist/tools/schema.d.ts +7 -4
  130. package/dist/tools/schema.d.ts.map +1 -1
  131. package/dist/tools/schema.js +32 -122
  132. package/dist/tools/schema.js.map +1 -1
  133. package/dist/tools/target-diagnostics.d.ts +3 -3
  134. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  135. package/dist/tools/target-diagnostics.js +64 -34
  136. package/dist/tools/target-diagnostics.js.map +1 -1
  137. package/dist/tools/wait.d.ts.map +1 -1
  138. package/dist/tools/wait.js +94 -40
  139. package/dist/tools/wait.js.map +1 -1
  140. package/extension/dist/assets/{content.ts-qe6IB5DK.js → content.ts-C9QgtUYe.js} +1 -1
  141. package/extension/dist/assets/{content.ts-loader-DUWbDHRS.js → content.ts-loader-yqB_P8vu.js} +1 -1
  142. package/extension/dist/assets/index.ts-DBFNh8mZ.js +20275 -0
  143. package/extension/dist/assets/{page-scripts-D508WLkW.js → page-scripts-BjqQ0zXt.js} +258 -367
  144. package/extension/dist/assets/{popup.html-B-eVq48O.js → popup.html-DwwHo00N.js} +2 -2
  145. package/extension/dist/manifest.json +4 -4
  146. package/extension/dist/service-worker-loader.js +1 -1
  147. package/extension/dist/src/popup/popup.html +3 -3
  148. package/package.json +9 -7
  149. package/scripts/start-chrome.ps1 +9 -1
  150. package/extension/dist/assets/index.ts-D7_LCUoV.js +0 -9319
@@ -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
  */
@@ -34,7 +38,14 @@ const extractSchema = z
34
38
  target: targetZodSchema
35
39
  .optional()
36
40
  .describe('目标元素(attribute 必填;text/html 可选,省略则提取整个页面;text 对 HTML 使用 innerText,SVG/XML 使用 textContent;' +
37
- 'screenshot 可选用于元素截图;state 可选(仅 Extension)用于返回目标子树;metadata 不需要)'),
41
+ 'screenshot 可选用于元素截图;state 可选用于返回目标子树;metadata 不需要)'),
42
+ maxChars: z.number().int().positive().optional().describe('text:最多返回的 UTF-16 字符数,省略时保留完整文本'),
43
+ offset: z
44
+ .number()
45
+ .int()
46
+ .nonnegative()
47
+ .optional()
48
+ .describe('text:本次文本的 UTF-16 起始位置,默认 0,使用返回的 nextOffset 继续读取'),
38
49
  attribute: z.string().optional().describe('属性名(attribute)'),
39
50
  images: z
40
51
  .enum(['info', 'data'])
@@ -83,13 +94,16 @@ const extractSchema = z
83
94
  .optional()
84
95
  .describe('页面状态提取模式(state 类型有效),accessibility=可访问性树(默认,与原 read_page 一致),' +
85
96
  'domsnapshot=DOMSnapshot 全量快照(CDP 或受控 Extension 页面,不支持 target/frame/depth 限定)'),
86
- timeout: z.number().optional().describe('等待目标元素超时'),
87
- frame: z
88
- .union([z.string(), z.number()])
97
+ timeout: z
98
+ .number()
89
99
  .optional()
90
- .describe('iframe 定位(可选,仅 Extension 模式),CSS 选择器(如 "iframe#main")或索引(如 0),不指定则在主框架操作'),
100
+ .describe('浏览器操作总预算(毫秒,默认 30000),包含排队、页面/frame 准备、目标等待、内容读取和页面元信息读取'),
101
+ frame: frameZodSchema.describe('iframe selector/索引或逐层路径(如 ["iframe#outer", 0]),省略时使用主文档'),
91
102
  })
92
103
  .superRefine((args, context) => {
104
+ if (args.type !== 'text' && (args.maxChars !== undefined || args.offset !== undefined)) {
105
+ context.addIssue({ code: 'custom', path: ['maxChars'], message: 'maxChars 和 offset 仅用于 text' });
106
+ }
93
107
  if (args.diffOutput && !args.compareWith) {
94
108
  context.addIssue({
95
109
  code: 'custom',
@@ -98,7 +112,7 @@ const extractSchema = z
98
112
  });
99
113
  }
100
114
  });
101
- async function handleExtract(args) {
115
+ async function handleExtract(args, signal) {
102
116
  const timeout = args.timeout ?? DEFAULT_TIMEOUT;
103
117
  const deadline = Date.now() + timeout;
104
118
  try {
@@ -117,15 +131,14 @@ async function handleExtract(args) {
117
131
  return frameHtmlError;
118
132
  }
119
133
  const session = getSession();
120
- // Extension 路径:等待目标元素出现(如果指定了 target + timeout)
121
- if (useExtension && args.target && args.timeout !== undefined) {
122
- await waitForTargetExtension(unifiedSession, args.target, args.timeout, args.frame);
134
+ if (args.target && args.timeout !== undefined && (useExtension || args.type === 'screenshot')) {
135
+ await waitForTarget(unifiedSession, args.target, remainingNavigationTimeout(deadline), args.frame);
123
136
  }
124
137
  try {
125
138
  const scopedArgs = !useExtension && args.target
126
139
  ? { ...args, timeout: targetLookupTimeout(Math.max(1, deadline - Date.now())) }
127
140
  : args;
128
- return await handleExtractInFrame({ unifiedSession, session, useExtension }, scopedArgs);
141
+ return await handleExtractInFrame({ unifiedSession, session, useExtension, deadline }, scopedArgs);
129
142
  }
130
143
  catch (error) {
131
144
  if (!useExtension && args.target && error instanceof ElementNotFoundError) {
@@ -137,8 +150,8 @@ async function handleExtract(args) {
137
150
  }
138
151
  throw error;
139
152
  }
140
- }); // withFrame
141
- }); // withTabId
153
+ }, deadline); // withFrame
154
+ }, deadline, signal); // withTabId
142
155
  }
143
156
  catch (error) {
144
157
  return formatErrorResponse(error);
@@ -196,11 +209,21 @@ async function handleTextExtract({ unifiedSession, session, useExtension }, args
196
209
  const text = useExtension
197
210
  ? await extractTextExtension(unifiedSession, args.target, args.timeout)
198
211
  : await extractText(session, args.target, args.timeout);
212
+ const offset = args.offset ?? 0;
213
+ const content = text.slice(offset, args.maxChars === undefined ? undefined : offset + args.maxChars);
214
+ const pagination = args.maxChars === undefined && args.offset === undefined
215
+ ? {}
216
+ : {
217
+ offset,
218
+ totalLength: text.length,
219
+ nextOffset: offset + content.length < text.length ? offset + content.length : null,
220
+ truncated: offset > 0 || content.length < text.length,
221
+ };
199
222
  if (args.output) {
200
- const outputPath = await writeOutputFile(args.output, text, 'utf-8');
201
- return formatResponse({ success: true, type: 'text', output: outputPath, size: text.length });
223
+ const outputPath = await writeOutputFile(args.output, content, 'utf-8');
224
+ return formatResponse({ success: true, type: 'text', output: outputPath, size: content.length, ...pagination });
202
225
  }
203
- return formatResponse({ success: true, type: 'text', content: text });
226
+ return formatResponse({ success: true, type: 'text', content, ...pagination });
204
227
  }
205
228
  async function handleHtmlExtract(context, args) {
206
229
  const { unifiedSession, session, useExtension } = context;
@@ -242,45 +265,138 @@ async function handleAttributeExtract({ unifiedSession, session, useExtension },
242
265
  : await extractAttribute(session, args.target, args.attribute, args.timeout);
243
266
  return formatResponse({ success: true, type: 'attribute', attribute: args.attribute, value });
244
267
  }
245
- async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
268
+ async function handleScreenshotExtract({ unifiedSession, useExtension, deadline }, args) {
269
+ const remaining = () => remainingNavigationTimeout(deadline);
246
270
  let clip;
271
+ let clippedToVisibleArea = false;
247
272
  if (args.target && !args.clip) {
248
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(args.target);
273
+ const { selector, text, xpath, nth: nthParam, semantic, } = targetToFindParams(args.target);
249
274
  const nth = nthParam ?? 0;
250
275
  const pointTarget = 'x' in args.target && 'y' in args.target ? args.target : null;
251
276
  const found = pointTarget
252
277
  ? useExtension
253
- ? await unifiedSession.findAtPoint(pointTarget.x, pointTarget.y, nth, args.timeout)
278
+ ? await unifiedSession.findAtPoint(pointTarget.x, pointTarget.y, nth, remaining(), 'frame')
254
279
  : await unifiedSession
255
280
  .evaluate(`(() => {
256
- const element = document.elementFromPoint(${pointTarget.x}, ${pointTarget.y});
281
+ (${installDomHelpers.toString()})();
282
+ const element = globalThis.__mcpDomHelpers.deepElementFromPoint(
283
+ ${pointTarget.x}, ${pointTarget.y}
284
+ );
257
285
  if (!element) return null;
258
286
  const rect = element.getBoundingClientRect();
259
287
  return {
260
288
  refId: '', tag: element.tagName.toLowerCase(), text: '',
261
289
  rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
262
290
  };
263
- })()`, undefined, args.timeout)
291
+ })()`, undefined, remaining())
264
292
  .then((element) => (element && nth === 0 ? [element] : []))
265
- : await unifiedSession.find(selector, text, xpath, args.timeout);
266
- const target = found[pointTarget ? 0 : nth];
293
+ : await unifiedSession.find(selector, text, xpath, remaining(), semantic, nth, 'frame');
294
+ const target = found[0];
267
295
  if (!target || target.rect.width <= 0 || target.rect.height <= 0) {
268
296
  throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
269
297
  nth,
270
- timeout: args.timeout,
298
+ timeout: remaining(),
271
299
  frame: args.frame,
272
- matchCount: found.length,
300
+ matchCount: null,
273
301
  lastState: target ? 'zero-size' : 'not-found',
274
302
  candidates: found,
275
303
  }));
276
304
  }
277
- const scrollOffset = args.frame === undefined ? await getPageScrollOffset(unifiedSession, args.timeout) : { x: 0, y: 0 };
278
- clip = {
279
- x: target.rect.x + scrollOffset.x,
280
- y: target.rect.y + scrollOffset.y,
281
- width: target.rect.width,
282
- height: target.rect.height,
283
- };
305
+ const visible = await unifiedSession.evaluate(`(() => {
306
+ (${installDomHelpers.toString()})();
307
+ return (query, nth, point, clipViewport) => {
308
+ const helpers = globalThis.__mcpDomHelpers;
309
+ const element = point ? helpers.deepElementFromPoint(point.x, point.y) : helpers.query(query)[nth];
310
+ if (!element) return { rect: { x: 0, y: 0, width: 0, height: 0 }, clipped: true };
311
+ const original = element.getBoundingClientRect();
312
+ let left = original.left, top = original.top, right = original.right, bottom = original.bottom;
313
+ const parentOf = (node) => node.assignedSlot || node.parentElement || node.getRootNode().host || null;
314
+ let position = getComputedStyle(element).position;
315
+ let escaping = position === 'absolute' || position === 'fixed';
316
+ for (let parent = parentOf(element); parent; parent = parentOf(parent)) {
317
+ const style = getComputedStyle(parent);
318
+ if (escaping) {
319
+ const containing = style.transform !== 'none' || style.perspective !== 'none' ||
320
+ style.filter !== 'none' || /(?:paint|layout|strict|content)/.test(style.contain) ||
321
+ (position === 'absolute' && style.position !== 'static');
322
+ if (!containing) continue;
323
+ escaping = false;
324
+ }
325
+ const clipsHorizontally = /^(?:hidden|clip|scroll|auto)$/.test(style.overflowX);
326
+ const clipsVertically = /^(?:hidden|clip|scroll|auto)$/.test(style.overflowY);
327
+ if (clipsHorizontally || clipsVertically) {
328
+ for (let owner = parent; owner; owner = parentOf(owner)) {
329
+ const css = getComputedStyle(owner);
330
+ const matrix = new DOMMatrix(css.transform === 'none' ? undefined : css.transform);
331
+ if (!matrix.is2D || Math.abs(matrix.a - 1) > 1e-12 || Math.abs(matrix.d - 1) > 1e-12 ||
332
+ Math.abs(matrix.b) > 1e-12 || Math.abs(matrix.c) > 1e-12 ||
333
+ (css.rotate && css.rotate !== 'none' && Number.parseFloat(css.rotate) !== 0) ||
334
+ (css.scale && css.scale !== 'none' &&
335
+ css.scale.split(/\\s+/).some(value => Number(value) !== 1)) ||
336
+ (Number.parseFloat(css.zoom) || 1) !== 1) {
337
+ return { rect: { x: 0, y: 0, width: 0, height: 0 }, clipped: false,
338
+ error: 'Overflow clip geometry requires translation-only ancestors' };
339
+ }
340
+ }
341
+ const bounds = parent.getBoundingClientRect();
342
+ if (clipsHorizontally) {
343
+ left = Math.max(left, bounds.left + parent.clientLeft);
344
+ right = Math.min(right, bounds.left + parent.clientLeft + parent.clientWidth);
345
+ }
346
+ if (clipsVertically) {
347
+ top = Math.max(top, bounds.top + parent.clientTop);
348
+ bottom = Math.min(bottom, bounds.top + parent.clientTop + parent.clientHeight);
349
+ }
350
+ }
351
+ if (style.position === 'absolute' || style.position === 'fixed') {
352
+ position = style.position;
353
+ escaping = true;
354
+ }
355
+ }
356
+ if (clipViewport) {
357
+ left = Math.max(left, 0); top = Math.max(top, 0);
358
+ right = Math.min(right, innerWidth); bottom = Math.min(bottom, innerHeight);
359
+ }
360
+ return { rect: { x: left, y: top,
361
+ width: Math.max(0, right - left), height: Math.max(0, bottom - top) },
362
+ clipped: left !== original.left || top !== original.top ||
363
+ right !== original.right || bottom !== original.bottom };
364
+ };
365
+ })()`, undefined, remaining(), [{ selector, text, xpath, semantic }, nth, pointTarget, args.frame !== undefined]);
366
+ if (visible.error) {
367
+ throw new StructuredToolError('FRAME_GEOMETRY_UNAVAILABLE', visible.error, '使用未变换的滚动容器或显式根页面 clip', { actionExecuted: false, actionStatus: 'not_started' });
368
+ }
369
+ if (visible.rect.width <= 0 || visible.rect.height <= 0) {
370
+ throw new StructuredToolError('ELEMENT_NOT_VISIBLE', '目标元素位于滚动容器的已绘制区域之外', '滚动目标容器使元素可见后再截图', { actionExecuted: false, actionStatus: 'not_started' });
371
+ }
372
+ clippedToVisibleArea = visible.clipped;
373
+ let rect = visible.rect;
374
+ if (useExtension && args.frame !== undefined) {
375
+ const offset = unifiedSession.getFrameOffset();
376
+ if (!offset) {
377
+ throw new StructuredToolError('FRAME_GEOMETRY_UNAVAILABLE', '无法将 frame 截图区域映射到根页面', '重新读取 frame 文档和布局', { actionExecuted: false, actionStatus: 'not_started' });
378
+ }
379
+ rect = { ...rect, x: rect.x + offset.x, y: rect.y + offset.y };
380
+ }
381
+ if (!useExtension && args.frame !== undefined) {
382
+ const session = getSession();
383
+ const points = [];
384
+ for (const x of [rect.x, rect.x + rect.width]) {
385
+ for (const y of [rect.y, rect.y + rect.height]) {
386
+ points.push(await session.mapFramePoint({ x, y }, remainingNavigationTimeout(deadline)));
387
+ }
388
+ }
389
+ const left = Math.min(...points.map((point) => point.x));
390
+ const top = Math.min(...points.map((point) => point.y));
391
+ rect = {
392
+ x: left,
393
+ y: top,
394
+ width: Math.max(...points.map((point) => point.x)) - left,
395
+ height: Math.max(...points.map((point) => point.y)) - top,
396
+ };
397
+ }
398
+ const scrollOffset = await getPageScrollOffset(unifiedSession, remaining());
399
+ clip = { x: rect.x + scrollOffset.x, y: rect.y + scrollOffset.y, width: rect.width, height: rect.height };
284
400
  }
285
401
  clip = args.clip ?? clip;
286
402
  const fullPage = clip ? false : (args.fullPage ?? false);
@@ -300,16 +416,20 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
300
416
  const encodedDimensions = readImageDimensions(screenshotBuffer, screenshot.format);
301
417
  const fallbackDimensions = encodedDimensions
302
418
  ? undefined
303
- : await getScreenshotFallbackDimensions(unifiedSession, clip, fullPage, scale, args.timeout);
419
+ : await getScreenshotFallbackDimensions(unifiedSession, clip, fullPage, scale, remaining());
304
420
  const dimensions = encodedDimensions ?? fallbackDimensions;
305
421
  const metadata = {
306
422
  format: screenshot.format,
423
+ ...(screenshot.degraded !== undefined ? { degraded: screenshot.degraded } : {}),
424
+ ...(screenshot.fallback !== undefined ? { fallback: screenshot.fallback } : {}),
425
+ ...(screenshot.limitations !== undefined ? { limitations: screenshot.limitations } : {}),
307
426
  width: dimensions?.width,
308
427
  height: dimensions?.height,
309
428
  dimensionSource: dimensions?.source,
310
429
  scale,
311
430
  fullPage,
312
431
  clip,
432
+ ...(clippedToVisibleArea ? { clippedToVisibleArea: true } : {}),
313
433
  size: screenshotBuffer.length,
314
434
  byteSize: screenshotBuffer.length,
315
435
  capabilities: screenshotCapabilities(),
@@ -350,7 +470,7 @@ async function handleScreenshotExtract({ unifiedSession, useExtension }, args) {
350
470
  ],
351
471
  };
352
472
  }
353
- async function handleStateExtract({ unifiedSession, useExtension }, args) {
473
+ async function handleStateExtract({ unifiedSession, session, useExtension }, args) {
354
474
  if (args.mode === 'domsnapshot') {
355
475
  return handleDomSnapshotState(unifiedSession, args);
356
476
  }
@@ -358,15 +478,15 @@ async function handleStateExtract({ unifiedSession, useExtension }, args) {
358
478
  if (args.target && useExtension) {
359
479
  refId = await findTargetRefExtension(unifiedSession, args.target, args.timeout);
360
480
  if (!refId) {
361
- const { selector, text, xpath, nth: nthParam, } = targetToFindParams(args.target);
481
+ const { selector, text, xpath, nth: nthParam, semantic, } = targetToFindParams(args.target);
362
482
  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);
483
+ ? await unifiedSession.findAtPoint(args.target.x, args.target.y, undefined, undefined, 'frame')
484
+ : await unifiedSession.find(selector, text, xpath, args.timeout, semantic, undefined, 'frame');
365
485
  throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
366
486
  nth: nthParam ?? 0,
367
487
  timeout: args.timeout,
368
488
  frame: args.frame,
369
- matchCount: candidates.length,
489
+ matchCount: candidates.length < 50 ? candidates.length : null,
370
490
  lastState: 'not-found',
371
491
  candidates,
372
492
  }));
@@ -379,7 +499,9 @@ async function handleStateExtract({ unifiedSession, useExtension }, args) {
379
499
  if (args.depth !== undefined) {
380
500
  readPageOptions.depth = args.depth;
381
501
  }
382
- const state = await unifiedSession.readPage(Object.keys(readPageOptions).length > 0 ? readPageOptions : undefined);
502
+ const state = sanitizePageUrls(useExtension
503
+ ? await unifiedSession.readPage(Object.keys(readPageOptions).length > 0 ? readPageOptions : undefined)
504
+ : await session.readPage({ target: args.target, depth: args.depth, timeout: args.timeout }));
383
505
  if (args.output) {
384
506
  const outputPath = await writeOutputFile(args.output, JSON.stringify(state, null, 2), 'utf-8');
385
507
  return formatResponse({ success: true, type: 'state', output: outputPath });
@@ -400,15 +522,15 @@ async function handleDomSnapshotState(unifiedSession, args) {
400
522
  }
401
523
  async function handleDiagnosticBundleExtract({ unifiedSession }, args) {
402
524
  const state = await unifiedSession.getLiveState().catch(() => null);
403
- const metadata = await unifiedSession.getMetadata();
404
- const frames = await unifiedSession.getFrames();
525
+ const metadata = sanitizePageUrls(await unifiedSession.getMetadata());
526
+ const frames = sanitizePageUrls(await unifiedSession.getFrames());
405
527
  await unifiedSession.enableConsole();
406
528
  await unifiedSession.enableNetwork();
407
529
  const consoleLogs = sanitizeUrlRecords(await unifiedSession.getConsoleLogs());
408
530
  const networkRequests = sanitizeUrlRecords(await unifiedSession.getNetworkRequests());
409
531
  const bundle = {
410
532
  schema: 'mcp-chrome.diagnosticBundle.v1',
411
- url: state?.url,
533
+ ...sanitizeUrlRecord({ url: state?.url }),
412
534
  title: state?.title,
413
535
  managed: state?.managed ?? false,
414
536
  mode: unifiedSession.getMode(),
@@ -431,12 +553,12 @@ async function handleDiagnosticBundleExtract({ unifiedSession }, args) {
431
553
  },
432
554
  };
433
555
  const summary = {
434
- url: bundle.url,
556
+ ...sanitizeUrlRecord({ url: state?.url }),
435
557
  title: bundle.title,
436
558
  managed: bundle.managed,
437
559
  mode: bundle.mode,
438
560
  frameCount: Array.isArray(frames.frames) ? frames.frames.length : 0,
439
- consoleErrors: bundle.consoleSummary.recentErrors.length,
561
+ consoleErrors: bundle.consoleSummary.recentErrors.filter((item) => item.level === 'error').length,
440
562
  networkFailures: bundle.networkSummary.recentFailures.length,
441
563
  };
442
564
  if (args.output) {
@@ -453,8 +575,8 @@ async function handleDiagnosticBundleExtract({ unifiedSession }, args) {
453
575
  });
454
576
  }
455
577
  async function handleMetadataExtract({ unifiedSession }, args) {
456
- const metadata = await unifiedSession.getMetadata();
457
- const frames = await unifiedSession.getFrames();
578
+ const metadata = sanitizePageUrls(await unifiedSession.getMetadata());
579
+ const frames = sanitizePageUrls(await unifiedSession.getFrames());
458
580
  if (args.output) {
459
581
  const outputPath = await writeOutputFile(args.output, JSON.stringify({ ...metadata, ...frames }, null, 2), 'utf-8');
460
582
  return formatResponse({ success: true, type: 'metadata', output: outputPath });
@@ -477,12 +599,14 @@ function invalidExtractTypeResponse(args) {
477
599
  // ==================== HTML + 图片提取 ====================
478
600
  /** 写入文件前自动创建父目录,并收敛到受控范围 */
479
601
  async function writeOutputFile(path, data, encoding) {
602
+ const session = getUnifiedSession();
603
+ session.assertRequestActive();
480
604
  const resolvedPath = await resolveScopedOutputPath(path, 'mcp-chrome');
481
- await writePrivateFile(resolvedPath.absolutePath, data, encoding);
605
+ await writePrivateFile(resolvedPath.absolutePath, data, encoding, () => session.assertRequestActive());
482
606
  return resolvedPath.absolutePath;
483
607
  }
484
608
  async function getPageScrollOffset(unifiedSession, timeout) {
485
- return unifiedSession.evaluate('(() => ({ x: window.scrollX || 0, y: window.scrollY || 0 }))()', undefined, timeout);
609
+ return unifiedSession.getPageScrollOffset(timeout);
486
610
  }
487
611
  async function getScreenshotFallbackDimensions(unifiedSession, clip, fullPage, scale, timeout) {
488
612
  if (clip) {
@@ -621,18 +745,18 @@ function readWebpDimensions(buffer) {
621
745
  async function handleHtmlWithImages(unifiedSession, session, useExtension, args) {
622
746
  let result;
623
747
  if (args.target) {
624
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(args.target);
748
+ const { selector, text, xpath, nth: nthParam, semantic, } = targetToFindParams(args.target);
625
749
  const nth = nthParam ?? 0;
626
750
  if (useExtension) {
627
751
  const refId = await findTargetRefExtension(unifiedSession, args.target, args.timeout);
628
752
  if (!refId) {
629
753
  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);
754
+ ? await unifiedSession.findAtPoint(args.target.x, args.target.y, undefined, undefined, 'frame')
755
+ : await unifiedSession.find(selector, text, xpath, args.timeout, semantic, undefined, 'frame');
632
756
  throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
633
757
  nth,
634
758
  timeout: args.timeout,
635
- matchCount: matches.length,
759
+ matchCount: matches.length < 50 ? matches.length : null,
636
760
  lastState: 'not-found',
637
761
  candidates: matches,
638
762
  }));
@@ -640,17 +764,17 @@ async function handleHtmlWithImages(unifiedSession, session, useExtension, args)
640
764
  result = await unifiedSession.getHtmlWithImagesByRef(refId);
641
765
  }
642
766
  else {
643
- const matches = await unifiedSession.find(selector, text, xpath, args.timeout);
644
- if (matches.length <= nth) {
767
+ const matches = await unifiedSession.find(selector, text, xpath, args.timeout, semantic, nth, 'frame');
768
+ if (matches.length === 0) {
645
769
  throw new TargetNotFoundError(await buildTargetDiagnostics(unifiedSession, args.target, {
646
770
  nth,
647
771
  timeout: args.timeout,
648
- matchCount: matches.length,
772
+ matchCount: null,
649
773
  lastState: 'not-found',
650
774
  candidates: matches,
651
775
  }));
652
776
  }
653
- result = await extractHtmlWithImagesByTarget(unifiedSession, selector, text, xpath, nth, args.timeout);
777
+ result = await extractHtmlWithImagesByTarget(unifiedSession, selector, text, xpath, nth, args.timeout, semantic);
654
778
  }
655
779
  }
656
780
  else {
@@ -677,41 +801,33 @@ async function handleHtmlWithImages(unifiedSession, session, useExtension, args)
677
801
  }
678
802
  // data 模式:获取图片数据
679
803
  const appendixMode = !args.output;
680
- const imageDataList = await fetchImageData(unifiedSession, result.images, appendixMode ? MAX_APPENDIX_IMAGES : undefined);
804
+ const imageData = fetchImageData(unifiedSession, result.images, appendixMode ? MAX_APPENDIX_IMAGES : undefined, !appendixMode);
681
805
  if (args.output) {
682
806
  const outputDir = (await resolveScopedOutputPath(args.output, 'mcp-chrome')).absolutePath;
683
- // 写入目录
684
- await writeImageDirectory(outputDir, result.html, result.images, imageDataList);
807
+ const omittedImages = await writeImageDirectory(outputDir, result.html, result.images, imageData, () => unifiedSession.assertRequestActive());
685
808
  return formatResponse({
686
809
  success: true,
687
810
  type: 'html',
688
811
  output: outputDir,
689
812
  imageCount: result.images.length,
690
813
  index: join(outputDir, 'index.json'),
814
+ omittedImages,
815
+ imageByteLimit: MAX_IMAGE_BYTES,
816
+ imageRequestByteLimit: MAX_IMAGE_REQUEST_BYTES,
691
817
  });
692
818
  }
693
- // 无 output:MCP 附录方式返回
819
+ const imageDataList = [];
820
+ for await (const data of imageData) {
821
+ imageDataList.push(data);
822
+ }
694
823
  return buildImageAppendixResponse(result.html, result.images, imageDataList);
695
824
  }
696
- async function extractHtmlWithImagesByTarget(unifiedSession, selector, text, xpath, nth, timeout) {
697
- return unifiedSession.evaluate(`(function(selector, text, xpath, nth) {
698
- var candidates = [];
699
- if (xpath) {
700
- var snapshot = document.evaluate(xpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
701
- for (var i = 0; i < snapshot.snapshotLength; i++) candidates.push(snapshot.snapshotItem(i));
702
- } else if (selector) {
703
- candidates = Array.from(document.querySelectorAll(selector));
704
- } else if (text) {
705
- candidates = Array.from(document.querySelectorAll('*')).filter(function(element) {
706
- return (element.textContent || '').includes(text);
707
- });
708
- }
709
- if (text && (selector || xpath)) {
710
- candidates = candidates.filter(function(element) {
711
- return (element.textContent || '').includes(text);
712
- });
713
- }
714
- var root = candidates[nth];
825
+ async function extractHtmlWithImagesByTarget(unifiedSession, selector, text, xpath, nth, timeout, semantic) {
826
+ return unifiedSession.evaluate(`(() => { (${installDomHelpers.toString()})(); return function(selector, text, xpath, nth, semantic) {
827
+ const root = globalThis.__mcpDomHelpers.query({
828
+ selector: selector ?? undefined, text: text ?? undefined,
829
+ xpath: xpath ?? undefined, semantic: semantic ?? undefined
830
+ })[nth];
715
831
  if (!root || !root.outerHTML) return { html: '', images: [] };
716
832
  var imageNodes = [];
717
833
  if (root.tagName === 'IMG') imageNodes.push(root);
@@ -734,7 +850,7 @@ async function extractHtmlWithImagesByTarget(unifiedSession, selector, text, xpa
734
850
  };
735
851
  });
736
852
  return { html: root.outerHTML, images: images };
737
- })`, undefined, timeout, [selector ?? null, text ?? null, xpath ?? null, nth]);
853
+ }; })()`, undefined, timeout, [selector ?? null, text ?? null, xpath ?? null, nth, semantic ?? null]);
738
854
  }
739
855
  /**
740
856
  * CDP 模式:提取 HTML + 图片元信息
@@ -779,68 +895,73 @@ async function extractHtmlWithImagesCdp(session, selector, timeout) {
779
895
  *
780
896
  * 策略:
781
897
  * 1. data: URL → 直接解码
782
- * 2. CDP Page.getResourceContent(批量) → 从浏览器缓存读取(零网络请求)
898
+ * 2. CDP Page.getResourceContent → 逐图读取浏览器缓存(零网络请求)
783
899
  *
784
900
  * @param unifiedSession 会话管理器,用于 CDP 资源获取
785
901
  * @param images 图片元信息列表
786
- * @param limit 最多获取前 N 张图片数据(附录模式限流),超出的返回 null
902
+ * @param limit 最多获取前 N 张图片数据(附录模式限流),超出的图片 base64 为 null
903
+ * @param skipDuplicates 是否跳过重复图片来源
787
904
  */
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++) {
905
+ async function* fetchImageData(unifiedSession, images, limit = images.length, skipDuplicates = false) {
906
+ let usedBytes = 0;
907
+ const sources = new Set();
908
+ for (let i = 0; i < images.length; ++i) {
909
+ unifiedSession.assertRequestActive();
794
910
  const img = images[i];
795
- const effectiveSrc = img.src || img.dataSrc;
796
- if (i >= effectiveLimit || !effectiveSrc) {
797
- preResolved.push({ base64: null, mimeType: 'image/png' });
911
+ const src = img.src || img.dataSrc;
912
+ const mimeType = guessMimeType(src);
913
+ if (skipDuplicates && sources.has(src)) {
914
+ yield { base64: null, mimeType };
798
915
  continue;
799
916
  }
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' });
917
+ if (i >= limit) {
918
+ yield { base64: null, mimeType, omitted: 'appendix-limit' };
805
919
  continue;
806
920
  }
807
- if (!effectiveSrc.startsWith('http')) {
808
- preResolved.push({ base64: null, mimeType: guessMimeType(effectiveSrc) });
921
+ if (usedBytes >= MAX_IMAGE_REQUEST_BYTES) {
922
+ yield { base64: null, mimeType, omitted: 'request-byte-limit' };
809
923
  continue;
810
924
  }
811
- // 只有 src 非空(浏览器实际请求过的)才走 CDP 缓存
812
- if (img.src) {
813
- cdpUrlSet.add(img.src);
925
+ let base64;
926
+ let resolvedMime = mimeType;
927
+ if (src.startsWith('data:')) {
928
+ const match = /^data:(?<mimeType>[^;]+);base64,/.exec(src);
929
+ if (match) {
930
+ resolvedMime = match[1];
931
+ base64 = src.slice(match[0].length);
932
+ }
814
933
  }
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]);
934
+ else if (img.src && /^https?:/.test(src)) {
935
+ const resource = (await unifiedSession.getResourceContentBatch([img.src], 1)).get(img.src);
936
+ unifiedSession.assertRequestActive();
937
+ if (resource) {
938
+ if (!resource.base64Encoded && Buffer.byteLength(resource.content) > MAX_IMAGE_BYTES) {
939
+ yield { base64: null, mimeType, omitted: 'image-byte-limit' };
940
+ continue;
941
+ }
942
+ base64 = resource.base64Encoded ? resource.content : Buffer.from(resource.content).toString('base64');
943
+ }
944
+ }
945
+ if (base64 === undefined) {
946
+ yield { base64: null, mimeType: resolvedMime, omitted: 'unavailable' };
824
947
  continue;
825
948
  }
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
- }
949
+ const bytes = Buffer.byteLength(base64, 'base64');
950
+ const omitted = bytes > MAX_IMAGE_BYTES
951
+ ? 'image-byte-limit'
952
+ : usedBytes + bytes > MAX_IMAGE_REQUEST_BYTES
953
+ ? 'request-byte-limit'
954
+ : undefined;
955
+ if (omitted) {
956
+ yield { base64: null, mimeType: resolvedMime, omitted };
838
957
  continue;
839
958
  }
840
- // CDP 缓存未命中,不使用 Node.js fetch(避免绕过浏览器同源策略)
841
- results.push({ base64: null, mimeType });
959
+ usedBytes += bytes;
960
+ if (skipDuplicates) {
961
+ sources.add(src);
962
+ }
963
+ yield { base64, mimeType: resolvedMime };
842
964
  }
843
- return results;
844
965
  }
845
966
  /**
846
967
  * 写入图片目录
@@ -853,18 +974,20 @@ async function fetchImageData(unifiedSession, images, limit) {
853
974
  * 1-icon.png
854
975
  * index.json
855
976
  */
856
- async function writeImageDirectory(outputDir, html, images, imageDataList) {
977
+ async function writeImageDirectory(outputDir, html, images, imageDataList, assertActive) {
857
978
  const imagesDir = join(outputDir, 'images');
858
979
  // 写入 HTML
859
- await writePrivateFile(join(outputDir, 'content.html'), html, 'utf-8');
980
+ await writePrivateFile(join(outputDir, 'content.html'), html, 'utf-8', assertActive);
860
981
  // 写入图片文件 + 构建索引(相同 src 去重)
861
982
  const indexEntries = [];
862
983
  const writtenFiles = new Map(); // src → file path
863
- for (let i = 0; i < images.length; i++) {
984
+ let i = 0;
985
+ let omittedImages = 0;
986
+ for await (const data of imageDataList) {
987
+ assertActive?.();
864
988
  const img = images[i];
865
- const data = imageDataList[i];
866
989
  const src = img.src || img.dataSrc;
867
- let file = null;
990
+ let file = writtenFiles.get(src) ?? null;
868
991
  if (data.base64) {
869
992
  // 相同 src 复用已写入的文件
870
993
  const existing = writtenFiles.get(src);
@@ -876,7 +999,7 @@ async function writeImageDirectory(outputDir, html, images, imageDataList) {
876
999
  const safeName = sanitizeFilename(src);
877
1000
  const filename = `${i}-${safeName}${ext}`;
878
1001
  file = `images/${filename}`;
879
- await writePrivateFile(join(imagesDir, filename), Buffer.from(data.base64, 'base64'));
1002
+ await writePrivateFile(join(imagesDir, filename), Buffer.from(data.base64, 'base64'), undefined, assertActive);
880
1003
  writtenFiles.set(src, file);
881
1004
  }
882
1005
  }
@@ -887,13 +1010,19 @@ async function writeImageDirectory(outputDir, html, images, imageDataList) {
887
1010
  width: img.width,
888
1011
  height: img.height,
889
1012
  file,
1013
+ ...(data.omitted ? { omitted: data.omitted } : {}),
890
1014
  });
1015
+ if (data.omitted) {
1016
+ ++omittedImages;
1017
+ }
1018
+ ++i;
891
1019
  }
892
1020
  // 写入索引
893
1021
  await writePrivateFile(join(outputDir, 'index.json'), JSON.stringify({
894
1022
  html: 'content.html',
895
1023
  images: indexEntries,
896
- }, null, 2), 'utf-8');
1024
+ }, null, 2), 'utf-8', assertActive);
1025
+ return omittedImages;
897
1026
  }
898
1027
  /**
899
1028
  * 构造附录式 MCP 响应
@@ -915,6 +1044,9 @@ function buildImageAppendixResponse(html, images, imageDataList) {
915
1044
  type: 'html',
916
1045
  content: html,
917
1046
  imageCount: images.length,
1047
+ imageByteLimit: MAX_IMAGE_BYTES,
1048
+ imageRequestByteLimit: MAX_IMAGE_REQUEST_BYTES,
1049
+ omittedImages: imageDataList.filter((image) => image.omitted).length,
918
1050
  }),
919
1051
  });
920
1052
  if (images.length === 0) {
@@ -931,7 +1063,11 @@ function buildImageAppendixResponse(html, images, imageDataList) {
931
1063
  // 图片标注
932
1064
  const sizeStr = img.naturalWidth ? `${img.naturalWidth}×${img.naturalHeight}` : `${img.width}×${img.height}`;
933
1065
  const altStr = img.alt ? ` alt="${img.alt}"` : '';
934
- content.push({ type: 'text', text: `\n[${img.index}] ${effectiveSrc}${altStr} ${sizeStr}` });
1066
+ content.push({
1067
+ type: 'text',
1068
+ text: `\n[${img.index}] ${effectiveSrc}${altStr} ${sizeStr}` +
1069
+ (data.omitted ? ` omitted=${data.omitted}` : ''),
1070
+ });
935
1071
  // 在限制内且有数据时附带图片(SVG 等不支持的格式跳过 image block)
936
1072
  if (i < limit && data.base64 && SUPPORTED_IMAGE_MIMES.has(data.mimeType)) {
937
1073
  content.push({ type: 'image', data: data.base64, mimeType: data.mimeType });
@@ -940,7 +1076,7 @@ function buildImageAppendixResponse(html, images, imageDataList) {
940
1076
  if (images.length > MAX_APPENDIX_IMAGES) {
941
1077
  content.push({
942
1078
  type: 'text',
943
- text: `\n(共 ${images.length} 张图片,仅前 ${MAX_APPENDIX_IMAGES} 张附带数据,使用 output 参数导出全部图片)`,
1079
+ text: `\n(共 ${images.length} 张图片,仅前 ${MAX_APPENDIX_IMAGES} 张附带数据,使用 output 参数导出图片,字节预算仍适用)`,
944
1080
  });
945
1081
  }
946
1082
  return { content };
@@ -1046,10 +1182,10 @@ async function extractAttribute(session, target, attribute, timeout) {
1046
1182
  }`);
1047
1183
  }
1048
1184
  async function findTargetRefExtension(unifiedSession, target, timeout) {
1049
- const { selector, text, xpath, nth } = targetToFindParams(target);
1185
+ const { selector, text, xpath, nth, semantic } = targetToFindParams(target);
1050
1186
  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);
1187
+ ? await unifiedSession.findAtPoint(target.x, target.y, nth ?? 0, timeout, 'frame')
1188
+ : await unifiedSession.find(selector, text, xpath, timeout, semantic, nth ?? 0, 'frame');
1053
1189
  return matches[0]?.refId;
1054
1190
  }
1055
1191
  /**
@@ -1088,21 +1224,19 @@ async function extractAttributeExtension(unifiedSession, target, attribute, time
1088
1224
  return unifiedSession.getAttributeByRef(refId, attribute);
1089
1225
  }
1090
1226
  /**
1091
- * Extension 模式:等待目标元素出现
1092
- *
1093
- * 在 extract 操作前轮询 find(),直到找到匹配元素或超时,
1094
- * 用于实现 extract 的 timeout 参数语义
1227
+ * 在提取前轮询 find(),直到找到指定索引的元素或超时
1095
1228
  */
1096
- async function waitForTargetExtension(unifiedSession, target, timeout, frame) {
1229
+ async function waitForTarget(unifiedSession, target, timeout, frame) {
1097
1230
  if ('x' in target && 'y' in target) {
1098
1231
  return;
1099
1232
  }
1233
+ unifiedSession.preserveTargetAfterLookup();
1100
1234
  const startTime = Date.now();
1101
1235
  const retryDelay = 100;
1102
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
1236
+ const { selector, text, xpath, nth: nthParam, semantic } = targetToFindParams(target);
1103
1237
  const nth = nthParam ?? 0;
1104
1238
  let lastError = null;
1105
- let matchCount = 0;
1239
+ let matchCount = null;
1106
1240
  let candidates = [];
1107
1241
  while (true) {
1108
1242
  const elapsed = Date.now() - startTime;
@@ -1110,6 +1244,7 @@ async function waitForTargetExtension(unifiedSession, target, timeout, frame) {
1110
1244
  throw new TargetTimeoutError(await buildTargetDiagnostics(unifiedSession, target, {
1111
1245
  nth,
1112
1246
  timeout,
1247
+ deadline: startTime + timeout,
1113
1248
  frame,
1114
1249
  matchCount,
1115
1250
  lastState: 'attached',
@@ -1118,22 +1253,27 @@ async function waitForTargetExtension(unifiedSession, target, timeout, frame) {
1118
1253
  }));
1119
1254
  }
1120
1255
  const remaining = timeout - elapsed;
1121
- if (!unifiedSession.isExtensionConnected()) {
1256
+ if (unifiedSession.getMode() === 'extension' && !unifiedSession.isExtensionConnected()) {
1122
1257
  lastError = new Error('Extension 未连接');
1123
1258
  await new Promise((resolve) => setTimeout(resolve, Math.min(retryDelay, remaining)));
1124
1259
  continue;
1125
1260
  }
1126
1261
  try {
1127
- const indexed = nth >= 50;
1128
- const elements = await unifiedSession.find(selector, text, xpath, remaining, indexed ? nth : undefined);
1129
- matchCount = elements.length;
1262
+ const elements = await unifiedSession.find(selector, text, xpath, remaining, semantic, undefined, 'frame');
1263
+ matchCount = elements.length < 50 ? elements.length : null;
1130
1264
  candidates = elements;
1131
- if (indexed ? elements.length > 0 : elements.length > nth) {
1265
+ const selected = nth < 50
1266
+ ? elements[nth]
1267
+ : (await unifiedSession.find(selector, text, xpath, Math.max(1, timeout - (Date.now() - startTime)), semantic, nth, 'frame'))[0];
1268
+ if (selected) {
1132
1269
  return;
1133
1270
  }
1134
1271
  }
1135
1272
  catch (err) {
1136
- // 暂时性错误(RPC 超时、发送失败、连接断开)可重试,其他确定性错误立即抛出
1273
+ if (err instanceof StructuredToolError && err.context.actionStatus === 'unknown') {
1274
+ throw err;
1275
+ }
1276
+ // 仅重试尚未派发成功的暂时性错误
1137
1277
  if (err instanceof Error &&
1138
1278
  /Request timeout|Failed to send|disconnect|未连接|stopped|replaced/i.test(err.message)) {
1139
1279
  lastError = err;
@@ -1158,6 +1298,6 @@ export function registerExtractTool(server) {
1158
1298
  server.registerTool('extract', {
1159
1299
  description: `提取页面内容:文本、HTML(可附带图片)、iframe HTML、属性、截图、状态、页面元信息`,
1160
1300
  inputSchema: extractSchema,
1161
- }, (args) => handleExtract(args));
1301
+ }, (args, extra) => handleExtract(args, extra?.signal));
1162
1302
  }
1163
1303
  //# sourceMappingURL=extract.js.map