@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
@@ -5,13 +5,15 @@
5
5
  * 使用 HTTP + WebSocket 实现
6
6
  */
7
7
  import { DriverCapabilityError, } from '../core/browser-driver.js';
8
- import { creationError, StructuredToolError, TargetNotFoundError } from '../core/errors.js';
9
- import { remainingNavigationTimeout } from '../core/utils.js';
8
+ import { eventRefTarget } from '../core/browser-events.js';
9
+ import { creationError, setErrorPageContext, setErrorSource, StructuredToolError, TargetNotFoundError, } from '../core/errors.js';
10
10
  import { DEFAULT_TIMEOUT } from '../core/types.js';
11
+ import { remainingNavigationTimeout } from '../core/utils.js';
11
12
  import { ExtensionHttpServer } from './http-server.js';
12
13
  /** RPC 传输余量(毫秒):给网络往返和 Extension 处理留出的额外时间 */
13
14
  const RPC_MARGIN = 5000;
14
15
  const CONDITIONAL_ACTIONS = new Set([
16
+ 'tabs_metadata',
15
17
  'tabs_close',
16
18
  'tabs_activate',
17
19
  'tabs_activate_managed',
@@ -34,7 +36,9 @@ const CONDITIONAL_ACTIONS = new Set([
34
36
  'scroll',
35
37
  'evaluate',
36
38
  'evaluate_in_frame',
39
+ 'prepare_frame_evaluation',
37
40
  'debugger_send',
41
+ 'keyboard_focus',
38
42
  'input_key',
39
43
  'input_mouse',
40
44
  'input_touch',
@@ -46,18 +50,24 @@ const CONDITIONAL_ACTIONS = new Set([
46
50
  'stealth_inject',
47
51
  ]);
48
52
  export class ExtensionBridge {
53
+ options;
49
54
  httpServer;
50
55
  currentTabId = null;
56
+ browserEventTargets = new Set();
51
57
  currentFrameId = 0;
58
+ currentFrameDocumentId;
52
59
  state = null;
53
60
  pendingPageCondition = null;
54
61
  constructor(options = {}) {
62
+ this.options = options;
55
63
  this.httpServer = new ExtensionHttpServer({
56
64
  port: options.port,
57
65
  autoPort: true,
66
+ requestContext: options.requestContext,
58
67
  });
59
68
  this.httpServer.setActionConditionProvider((action, params) => {
60
- const condition = this.pendingPageCondition;
69
+ const context = this.options.requestContext?.();
70
+ const condition = context ? context.pendingPageCondition : this.pendingPageCondition;
61
71
  if (!condition || !CONDITIONAL_ACTIONS.has(action)) {
62
72
  return undefined;
63
73
  }
@@ -65,7 +75,14 @@ export class ExtensionBridge {
65
75
  if (tabId === undefined || String(tabId) !== condition.targetId) {
66
76
  throw new DriverCapabilityError('条件动作的目标与请求目标不一致,未执行动作');
67
77
  }
68
- this.pendingPageCondition = null;
78
+ if (action !== 'prepare_frame_evaluation') {
79
+ if (context) {
80
+ context.pendingPageCondition = null;
81
+ }
82
+ else {
83
+ this.pendingPageCondition = null;
84
+ }
85
+ }
69
86
  return {
70
87
  ...(condition.expectedUrl !== undefined ? { expectedUrl: condition.expectedUrl } : {}),
71
88
  ...(condition.expectedRevision !== undefined ? { expectedRevision: condition.expectedRevision } : {}),
@@ -86,7 +103,7 @@ export class ExtensionBridge {
86
103
  * @param timeout 超时时间(毫秒),0 表示无限等待(默认)
87
104
  */
88
105
  async waitForConnection(timeout = 0) {
89
- return this.httpServer.waitForConnection(timeout);
106
+ return this.httpServer.waitForConnection(timeout, this.options.requestContext?.()?.signal);
90
107
  }
91
108
  getPort() {
92
109
  return this.httpServer.getPort();
@@ -95,11 +112,20 @@ export class ExtensionBridge {
95
112
  return this.httpServer.getConnectionInfo();
96
113
  }
97
114
  // ==================== Tab 操作 ====================
98
- async listTabs(timeout) {
115
+ async listTabs(timeout, options) {
116
+ const currentTabId = this.currentTabId;
99
117
  const result = await this.httpServer.sendCommand('tabs_list', {}, timeout);
100
- return result;
118
+ const tabs = result;
119
+ if (options?.preserveDefaultTarget !== true &&
120
+ currentTabId !== null &&
121
+ this.currentTabId === currentTabId &&
122
+ !tabs.some((tab) => tab.id === currentTabId)) {
123
+ this.setCurrentTargetId(null);
124
+ }
125
+ return tabs;
101
126
  }
102
- async listWindows(timeout) {
127
+ async listWindows(timeout, options) {
128
+ const currentTabId = this.currentTabId;
103
129
  const result = await this.httpServer.sendCommand('tabs_topology', {}, timeout);
104
130
  const topology = result;
105
131
  const windows = topology.windows.map((window) => ({
@@ -141,11 +167,17 @@ export class ExtensionBridge {
141
167
  }
142
168
  return group;
143
169
  });
170
+ if (options?.preserveDefaultTarget !== true &&
171
+ currentTabId !== null &&
172
+ this.currentTabId === currentTabId &&
173
+ !windows.some((window) => window.tabs.some((tab) => tab.id === currentTabId))) {
174
+ this.setCurrentTargetId(null);
175
+ }
144
176
  return { ...topology, windows, ...(groups === undefined ? {} : { groups }) };
145
177
  }
146
178
  /** IBrowserDriver 接口:列出所有 tab,统一为 ListedTarget 形式(id 字符串化以保持跨 driver 兼容) */
147
- async listTargets(timeout) {
148
- const tabs = await this.listTabs(timeout);
179
+ async listTargets(timeout, options) {
180
+ const tabs = await this.listTabs(timeout, options);
149
181
  return tabs.map((tab) => this.tabToTarget(tab));
150
182
  }
151
183
  async createTab(url, timeout, options = {}) {
@@ -155,6 +187,7 @@ export class ExtensionBridge {
155
187
  url,
156
188
  active: false,
157
189
  ...options,
190
+ sourceTabId: this.currentTabId ?? undefined,
158
191
  waitUntil: 'load',
159
192
  timeout,
160
193
  }, rpcTimeout)
@@ -201,6 +234,12 @@ export class ExtensionBridge {
201
234
  }
202
235
  return this.closeTab(this.parseTargetId(targetId));
203
236
  }
237
+ async setPageMetadata(targetId, updates) {
238
+ return (await this.httpServer.sendCommand('tabs_metadata', {
239
+ tabId: this.parseTargetId(targetId),
240
+ ...updates,
241
+ }));
242
+ }
204
243
  async setReadAccess(targetId, allow) {
205
244
  return (await this.httpServer.sendCommand('tabs_read_access', {
206
245
  tabId: this.parseTargetId(targetId),
@@ -397,7 +436,7 @@ export class ExtensionBridge {
397
436
  }
398
437
  catch (error) {
399
438
  if (error instanceof Error && error.message === 'Unknown action: page_snapshot') {
400
- const tabs = await this.listTabs(deadline === undefined ? undefined : remainingNavigationTimeout(deadline));
439
+ const tabs = await this.listTabs(deadline === undefined ? undefined : remainingNavigationTimeout(deadline), { preserveDefaultTarget: true });
401
440
  if (deadline !== undefined) {
402
441
  remainingNavigationTimeout(deadline);
403
442
  }
@@ -422,7 +461,13 @@ export class ExtensionBridge {
422
461
  }
423
462
  }
424
463
  setPageCondition(condition) {
425
- this.pendingPageCondition = condition;
464
+ const context = this.options.requestContext?.();
465
+ if (context) {
466
+ context.pendingPageCondition = condition;
467
+ }
468
+ else {
469
+ this.pendingPageCondition = condition;
470
+ }
426
471
  }
427
472
  /** IBrowserDriver 接口:设置当前操作目标 ID */
428
473
  setCurrentTargetId(targetId) {
@@ -474,24 +519,26 @@ export class ExtensionBridge {
474
519
  }));
475
520
  }
476
521
  // ==================== 页面内容 ====================
477
- async click(refId) {
522
+ async click(refId, timeout, modifiers = 0) {
478
523
  const result = (await this.httpServer.sendCommand('click', {
479
524
  tabId: this.requireCurrentTabId(),
480
525
  frameId: this.currentFrameId || undefined,
481
526
  refId,
482
- }));
527
+ modifiers,
528
+ }, timeout));
483
529
  if (!result.success) {
484
530
  throw new Error(result.error || 'Click failed');
485
531
  }
486
532
  }
487
533
  // ==================== DOM 操作 ====================
488
- async actionableClick(refId, force) {
534
+ async actionableClick(refId, force, timeout, modifiers = 0) {
489
535
  return (await this.httpServer.sendCommand('actionable_click', {
490
536
  tabId: this.requireCurrentTabId(),
491
537
  frameId: this.currentFrameId || undefined,
492
538
  refId,
493
539
  force: force ?? false,
494
- }));
540
+ modifiers,
541
+ }, timeout));
495
542
  }
496
543
  async checkActionability(refId) {
497
544
  const result = (await this.httpServer.sendCommand('check_actionability', {
@@ -502,12 +549,16 @@ export class ExtensionBridge {
502
549
  return { ...result, success: result.success ?? result.actionable === true };
503
550
  }
504
551
  async dispatchInput(refId, text) {
505
- return (await this.httpServer.sendCommand('dispatch_input', {
552
+ const result = await this.httpServer.sendCommand('dispatch_input', {
506
553
  tabId: this.requireCurrentTabId(),
507
554
  frameId: this.currentFrameId || undefined,
508
555
  refId,
509
556
  text,
510
- }));
557
+ });
558
+ if (!result || typeof result !== 'object' || !('success' in result) || typeof result.success !== 'boolean') {
559
+ throw new StructuredToolError('ACTION_RESULT_INVALID', 'controlled 输入已派发,但未返回有效的动作结果', '独立读取目标实际文本后再决定下一步,工具不会重放输入', { actionExecuted: 'unknown', actionStatus: 'unknown', retryable: false, failureStage: 'script_result' });
560
+ }
561
+ return result;
511
562
  }
512
563
  async dragAndDrop(srcRefId, dstRefId) {
513
564
  return (await this.httpServer.sendCommand('drag_and_drop', {
@@ -554,7 +605,7 @@ export class ExtensionBridge {
554
605
  scrollAt(x, y, refId) {
555
606
  return this.scroll(x, y, refId);
556
607
  }
557
- async evaluate(code, _args, timeout) {
608
+ async evaluate(code, _args, timeout, userAction) {
558
609
  // _args 参数仅满足 IBrowserDriver 接口签名;ExtensionBridge 不消费 args(stealth 路径上层已字符串拼接)
559
610
  const rpcTimeout = timeout !== undefined ? timeout + RPC_MARGIN : undefined;
560
611
  const result = (await this.httpServer.sendCommand('evaluate', {
@@ -562,21 +613,94 @@ export class ExtensionBridge {
562
613
  frameId: this.currentFrameId || undefined,
563
614
  code,
564
615
  timeout,
565
- }, rpcTimeout));
616
+ deadline: Date.now() + (timeout ?? DEFAULT_TIMEOUT),
617
+ }, rpcTimeout, userAction));
618
+ const outputError = (message, suggestion, context, cause) => {
619
+ const error = new StructuredToolError('NON_SERIALIZABLE_EVALUATE_RESULT', message, suggestion, {
620
+ ...context,
621
+ ...(result.errorMessage !== undefined ? { originalOutputError: result.errorMessage } : {}),
622
+ actionExecuted: true,
623
+ actionStatus: 'completed',
624
+ failureStage: 'output',
625
+ retryable: false,
626
+ });
627
+ if (cause !== undefined) {
628
+ Object.defineProperty(error, 'cause', { value: cause, configurable: true, writable: true });
629
+ }
630
+ if (userAction === undefined) {
631
+ setErrorPageContext(error, { contextPhase: 'preparation' });
632
+ }
633
+ return error;
634
+ };
566
635
  if (!result.success) {
567
- throw new Error(result.error || 'Evaluate failed');
636
+ if (result.errorSource === 'context' && result.actionExecuted === false) {
637
+ throw setErrorSource(new StructuredToolError(result.errorCode ?? 'UNKNOWN_ERROR', result.error ?? 'Script compilation failed', result.errorCode === 'CSP_BLOCKED'
638
+ ? '可使用 evaluate 的 mode="precise" 执行脚本;当前脚本未执行'
639
+ : '请检查脚本语法,当前脚本未执行', {
640
+ actionExecuted: false,
641
+ actionStatus: 'not_started',
642
+ failureStage: 'context',
643
+ retryable: false,
644
+ phase: 'compile',
645
+ }), 'context');
646
+ }
647
+ if (result.errorSource === 'output') {
648
+ if (result.errorCode === 'NON_SERIALIZABLE_EVALUATE_RESULT') {
649
+ throw outputError(result.error ?? 'evaluate 输出处理失败', '请检查返回值及页面的 JSON 序列化行为', {
650
+ error: result.error,
651
+ detailSerializationFailed: true,
652
+ });
653
+ }
654
+ let detail;
655
+ try {
656
+ const value = JSON.parse(result.error)?.error;
657
+ if (typeof value?.message !== 'string' ||
658
+ typeof value.suggestion !== 'string' ||
659
+ !value.context ||
660
+ typeof value.context !== 'object' ||
661
+ Array.isArray(value.context)) {
662
+ // noinspection ExceptionCaughtLocallyJS -- preserve the output-error parsing stage
663
+ throw new TypeError('浏览器返回的 evaluate 输出错误详情格式无效');
664
+ }
665
+ detail = {
666
+ message: value.message,
667
+ suggestion: value.suggestion,
668
+ context: value.context,
669
+ };
670
+ }
671
+ catch (error) {
672
+ throw outputError(`evaluate 输出错误详情解析失败: ${error}`, '请检查页面的 JSON 序列化行为', {
673
+ error: result.error,
674
+ detailParsingError: String(error),
675
+ }, error);
676
+ }
677
+ throw outputError(detail.message, detail.suggestion, detail.context);
678
+ }
679
+ const error = new Error(result.error ?? 'Evaluate failed');
680
+ throw result.errorSource === 'page' ? setErrorSource(error, 'page') : error;
568
681
  }
569
- if (!result.result) {
682
+ if (result.result === undefined) {
570
683
  return undefined;
571
684
  }
572
685
  try {
686
+ if (typeof result.result !== 'string') {
687
+ // noinspection ExceptionCaughtLocallyJS -- preserve the output-error parsing stage
688
+ throw new TypeError('浏览器返回的 evaluate 结果不是 JSON 字符串');
689
+ }
573
690
  return JSON.parse(result.result);
574
691
  }
575
692
  catch (err) {
576
- throw new Error(`evaluate 结果 JSON 解析失败: ${err}`, { cause: err });
693
+ throw outputError(`evaluate 结果 JSON 解析失败: ${err}`, '请返回可 JSON 序列化的简单数据,并检查页面的 JSON 序列化行为', { error: String(err) }, err);
577
694
  }
578
695
  }
579
- async find(selector, text, xpath, timeout, point, matchIndex) {
696
+ async find(selector, text, xpath, timeout, semanticOrPointOrMatchIndex, matchIndex, coordinateSpace) {
697
+ const point = typeof semanticOrPointOrMatchIndex === 'object' && 'x' in semanticOrPointOrMatchIndex
698
+ ? semanticOrPointOrMatchIndex
699
+ : undefined;
700
+ const semantic = typeof semanticOrPointOrMatchIndex === 'object' && !('x' in semanticOrPointOrMatchIndex)
701
+ ? semanticOrPointOrMatchIndex
702
+ : undefined;
703
+ matchIndex = typeof semanticOrPointOrMatchIndex === 'number' ? semanticOrPointOrMatchIndex : matchIndex;
580
704
  return (await this.httpServer.sendCommand('find', {
581
705
  tabId: this.requireCurrentTabId(),
582
706
  frameId: this.currentFrameId || undefined,
@@ -584,7 +708,9 @@ export class ExtensionBridge {
584
708
  text,
585
709
  xpath,
586
710
  point,
711
+ semantic,
587
712
  matchIndex,
713
+ coordinateSpace,
588
714
  }, timeout));
589
715
  }
590
716
  async getText(selector, refId) {
@@ -676,25 +802,67 @@ export class ExtensionBridge {
676
802
  ...(chromeSameSite !== undefined && { sameSite: chromeSameSite }),
677
803
  });
678
804
  }
679
- async deleteCookie(url, name) {
680
- await this.httpServer.sendCommand('cookies_delete', { url, name });
805
+ async deleteCookie(url, name, scope) {
806
+ await this.httpServer.sendCommand('cookies_delete', { url, name, ...scope });
681
807
  }
682
808
  async clearCookies(filter) {
683
809
  return (await this.httpServer.sendCommand('cookies_clear', filter ?? {}));
684
810
  }
685
- async debuggerSend(method, params, tabId, timeout) {
811
+ async browserEvents(action, command, targetId, timeout) {
812
+ const refTarget = command.ref ? eventRefTarget(command.ref) : undefined;
813
+ if (refTarget && (refTarget.backend !== 'extension' || (targetId && refTarget.targetId !== targetId))) {
814
+ throw new DriverCapabilityError('Browser event ref target mismatch');
815
+ }
816
+ const id = refTarget?.targetId ?? targetId ?? this.getCurrentTargetId();
817
+ if (!id || !/^\d+$/.test(id)) {
818
+ throw new DriverCapabilityError('Browser events require an explicit target or observed ref');
819
+ }
820
+ const result = (await this.httpServer.sendCommand('browser_events', { tabId: Number(id), action, command }, timeout));
821
+ this.browserEventTargets.add(id);
822
+ return result;
823
+ }
824
+ hasBrowserEventObservation(targetId) {
825
+ const id = targetId ?? this.getCurrentTargetId();
826
+ return id !== null && id !== undefined && this.browserEventTargets.has(id);
827
+ }
828
+ async browserFetchCommand(method, params, targetId) {
829
+ const id = targetId ?? this.getCurrentTargetId();
830
+ if (!id || !/^\d+$/.test(id)) {
831
+ throw new DriverCapabilityError('Explicit targetId required for Fetch control');
832
+ }
833
+ return this.httpServer.sendCommand('browser_events_raw', { tabId: Number(id), method, params });
834
+ }
835
+ async suspendBrowserEventsForChallenge() {
836
+ const id = String(this.requireCurrentTabId());
837
+ if (!this.browserEventTargets.has(id)) {
838
+ return { targetId: id, suspended: true, observations: [], cleanupFailures: [], fetchEnabled: false };
839
+ }
840
+ const result = (await this.httpServer.sendCommand('browser_events_suspend', { tabId: Number(id) }));
841
+ if (result.suspended === true) {
842
+ this.browserEventTargets.delete(id);
843
+ }
844
+ return result;
845
+ }
846
+ async debuggerSend(method, params, tabId, timeout, userAction) {
847
+ if (method === 'Fetch.enable') {
848
+ await this.browserEvents('read', { type: 'network', view: 'summary' }, String(tabId ?? this.requireCurrentTabId()), timeout);
849
+ }
686
850
  return await this.httpServer.sendCommand('debugger_send', {
687
851
  tabId: tabId ?? this.requireCurrentTabId(),
688
852
  method,
689
853
  params,
690
- }, timeout);
854
+ }, timeout, userAction);
691
855
  }
692
856
  async debuggerDetach(tabId, timeout = DEFAULT_TIMEOUT) {
693
857
  await this.sendBudgetedCommand('debugger_detach', {
694
858
  tabId: tabId ?? this.requireCurrentTabId(),
695
859
  }, timeout);
860
+ this.browserEventTargets.delete(String(tabId ?? this.requireCurrentTabId()));
696
861
  }
697
- async getViewportMetrics(frameId) {
862
+ async getViewportMetrics(frameId, pointerProbe, timeout) {
863
+ if (pointerProbe) {
864
+ return this.sendBudgetedCommand('viewport_metrics', { tabId: this.requireCurrentTabId(), pointerProbe }, timeout);
865
+ }
698
866
  const selectedFrameId = frameId ?? this.currentFrameId;
699
867
  return this.httpServer.sendCommand('viewport_metrics', {
700
868
  tabId: this.requireCurrentTabId(),
@@ -709,16 +877,43 @@ export class ExtensionBridge {
709
877
  }, timeout);
710
878
  }
711
879
  // ==================== Debugger (CDP via Extension) ====================
880
+ async acquireKeyboardFocus(id, timeout) {
881
+ return (await this.sendBudgetedCommand('keyboard_focus', {
882
+ operation: 'acquire',
883
+ id,
884
+ tabId: this.requireCurrentTabId(),
885
+ frameId: this.currentFrameId,
886
+ documentId: this.currentFrameDocumentId,
887
+ }, timeout));
888
+ }
889
+ async releaseKeyboardFocus(focus, releaseKeys) {
890
+ return (await this.sendBudgetedCommand('keyboard_focus', {
891
+ operation: 'release',
892
+ id: focus.id,
893
+ tabId: this.parseTargetId(focus.targetId),
894
+ releaseKeys,
895
+ }, 4000));
896
+ }
712
897
  async inputKey(type, options = {}, timeout) {
713
898
  await this.sendBudgetedCommand('input_key', {
714
899
  tabId: this.requireCurrentTabId(),
900
+ keyboardFocusId: this.options.requestContext?.()?.keyboardFocus?.id,
715
901
  type,
716
902
  ...options,
717
903
  }, timeout);
718
904
  }
719
905
  // ==================== 输入事件(通过 CDP)====================
720
906
  async inputMouse(type, x, y, options = {}, timeout) {
721
- const params = { tabId: this.requireCurrentTabId(), type, x, y, ...options };
907
+ const params = {
908
+ tabId: this.requireCurrentTabId(),
909
+ frameId: this.currentFrameId,
910
+ documentId: this.currentFrameDocumentId,
911
+ ...(type !== 'mouseWheel' && this.currentFrameId ? { coordinateSpace: 'frame' } : {}),
912
+ type,
913
+ x,
914
+ y,
915
+ ...options,
916
+ };
722
917
  if (timeout === undefined) {
723
918
  await this.httpServer.sendCommand('input_mouse', params);
724
919
  }
@@ -729,12 +924,20 @@ export class ExtensionBridge {
729
924
  async inputTouch(type, touchPoints) {
730
925
  await this.httpServer.sendCommand('input_touch', {
731
926
  tabId: this.requireCurrentTabId(),
927
+ frameId: this.currentFrameId,
928
+ documentId: this.currentFrameDocumentId,
732
929
  type,
733
930
  touchPoints,
734
931
  });
735
932
  }
736
933
  async inputType(text, delay = 0, timeout = DEFAULT_TIMEOUT) {
737
- await this.httpServer.sendCommand('input_type', { tabId: this.requireCurrentTabId(), text, delay, deadline: Date.now() + timeout }, timeout);
934
+ await this.httpServer.sendCommand('input_type', {
935
+ tabId: this.requireCurrentTabId(),
936
+ keyboardFocusId: this.options.requestContext?.()?.keyboardFocus?.id,
937
+ text,
938
+ delay,
939
+ deadline: Date.now() + timeout,
940
+ }, timeout);
738
941
  }
739
942
  async consoleEnable() {
740
943
  await this.httpServer.sendCommand('console_enable', {
@@ -789,7 +992,7 @@ export class ExtensionBridge {
789
992
  };
790
993
  await this.sendBudgetedCommand('stealth_key', params, timeout);
791
994
  }
792
- async stealthClick(x, y, button = 'left', clickCount = 1, refId, timeout = DEFAULT_TIMEOUT) {
995
+ async stealthClick(x, y, button = 'left', clickCount = 1, refId, timeout = DEFAULT_TIMEOUT, modifiers = 0) {
793
996
  if (this.currentTabId === null) {
794
997
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
795
998
  }
@@ -800,13 +1003,14 @@ export class ExtensionBridge {
800
1003
  y,
801
1004
  button,
802
1005
  clickCount,
1006
+ modifiers,
803
1007
  };
804
1008
  if (typeof refId === 'string') {
805
1009
  params.refId = refId;
806
1010
  }
807
1011
  await this.sendBudgetedCommand('stealth_click', params, timeout);
808
1012
  }
809
- async stealthMouse(type, x, y, button = 'left', timeout) {
1013
+ async stealthMouse(type, x, y, button = 'left', timeout, modifiers = 0) {
810
1014
  if (this.currentTabId === null) {
811
1015
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
812
1016
  }
@@ -817,6 +1021,7 @@ export class ExtensionBridge {
817
1021
  x,
818
1022
  y,
819
1023
  button,
1024
+ modifiers,
820
1025
  };
821
1026
  if (timeout === undefined) {
822
1027
  await this.httpServer.sendCommand('stealth_mouse', params);
@@ -842,22 +1047,57 @@ export class ExtensionBridge {
842
1047
  getCurrentFrameId() {
843
1048
  return this.currentFrameId;
844
1049
  }
845
- setCurrentFrameId(frameId) {
1050
+ getCurrentFrameDocumentId() {
1051
+ return this.currentFrameDocumentId;
1052
+ }
1053
+ setCurrentFrameId(frameId, documentId) {
846
1054
  this.currentFrameId = frameId;
1055
+ this.currentFrameDocumentId = documentId;
847
1056
  }
848
1057
  /**
849
1058
  * 在指定 iframe 中以 precise 模式执行 JS(通过 contextId 绕过 CSP)
850
1059
  */
851
- async evaluateInFrame(frameId, expression, timeout, staleContextRetry = 'never') {
852
- return (await this.httpServer.sendCommand('evaluate_in_frame', {
853
- tabId: this.requireCurrentTabId(),
854
- frameId,
855
- expression,
856
- returnByValue: true,
857
- awaitPromise: true,
858
- timeout,
859
- staleContextRetry,
860
- }, timeout));
1060
+ async evaluateInFrame(frameId, expression, timeout, staleContextRetry = 'never', userAction) {
1061
+ const deadline = timeout === undefined ? undefined : Date.now() + timeout;
1062
+ const remaining = () => (deadline === undefined ? undefined : remainingNavigationTimeout(deadline));
1063
+ let preparedContext;
1064
+ try {
1065
+ const prepared = (await this.httpServer.sendCommand('prepare_frame_evaluation', { tabId: this.requireCurrentTabId(), frameId, timeout: remaining() }, remaining()));
1066
+ if (!prepared?.preparedContext ||
1067
+ typeof prepared.preparedContext !== 'object' ||
1068
+ Array.isArray(prepared.preparedContext)) {
1069
+ throw new StructuredToolError('ACTION_RESULT_INVALID', 'iframe 执行准备未返回有效上下文,未发送脚本', '请读取 frame 列表和当前连接状态', { actionExecuted: false, actionStatus: 'not_started', retryable: false });
1070
+ }
1071
+ preparedContext = prepared.preparedContext;
1072
+ }
1073
+ catch (error) {
1074
+ if (error instanceof Error && error.message === 'Unknown action: prepare_frame_evaluation') {
1075
+ console.warn('[MCP] 当前连接使用单阶段 iframe 兼容路径,准备期间取消的执行结果将标记为 unknown');
1076
+ }
1077
+ else {
1078
+ throw setErrorPageContext(error, { contextPhase: 'preparation', frameResolutionPreparation: true });
1079
+ }
1080
+ }
1081
+ try {
1082
+ this.options.requestContext?.()?.signal?.throwIfAborted();
1083
+ return (await this.httpServer.sendCommand('evaluate_in_frame', {
1084
+ tabId: this.requireCurrentTabId(),
1085
+ frameId,
1086
+ expression,
1087
+ returnByValue: true,
1088
+ awaitPromise: true,
1089
+ timeout: remaining(),
1090
+ staleContextRetry,
1091
+ ...(preparedContext ? { preparedContext } : {}),
1092
+ }, remaining(), userAction));
1093
+ }
1094
+ catch (error) {
1095
+ const action = this.options.requestContext?.()?.userAction;
1096
+ if (action && !action.dispatched) {
1097
+ throw setErrorPageContext(error, { contextPhase: 'preparation', frameResolutionPreparation: true });
1098
+ }
1099
+ throw error;
1100
+ }
861
1101
  }
862
1102
  /**
863
1103
  * 解析 iframe 选择器/索引 → frameId
@@ -877,7 +1117,9 @@ export class ExtensionBridge {
877
1117
  return result;
878
1118
  }
879
1119
  catch (error) {
880
- if (error instanceof Error && error.message.startsWith(`Request timeout for action: ${action} (`)) {
1120
+ if (error instanceof Error &&
1121
+ !(error instanceof StructuredToolError) &&
1122
+ error.message.startsWith(`Request timeout for action: ${action} (`)) {
881
1123
  throw new StructuredToolError('TIMEOUT', error.message, '请回读实际页面,勿自动重放操作', {
882
1124
  actionExecuted: 'unknown',
883
1125
  actionStatus: 'unknown',
@@ -924,7 +1166,7 @@ export class ExtensionBridge {
924
1166
  };
925
1167
  }
926
1168
  parseTargetId(targetId) {
927
- if (!/^(0|[1-9]\d*)$/.test(targetId)) {
1169
+ if (!/^(?:0|[1-9]\d*)$/.test(targetId)) {
928
1170
  throw new DriverCapabilityError(`无效的 Tab ID: ${targetId}`);
929
1171
  }
930
1172
  const parsed = Number(targetId);