@pyrokine/mcp-chrome 3.0.0 → 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 +721 -303
  2. package/README_zh.md +750 -292
  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 +76 -18
  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 +10 -4
  34. package/dist/core/errors.d.ts.map +1 -1
  35. package/dist/core/errors.js +63 -13
  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 +17 -2
  42. package/dist/core/locator.d.ts.map +1 -1
  43. package/dist/core/locator.js +156 -212
  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 +65 -14
  53. package/dist/core/session.d.ts.map +1 -1
  54. package/dist/core/session.js +1089 -273
  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 +50 -41
  61. package/dist/core/unified-session.d.ts.map +1 -1
  62. package/dist/core/unified-session.js +938 -285
  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 +50 -19
  69. package/dist/extension/bridge.d.ts.map +1 -1
  70. package/dist/extension/bridge.js +289 -57
  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 +219 -48
  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 +66 -32
  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 +113 -195
  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 +102 -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 +178 -124
  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 +623 -271
  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 +127 -46
  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 +153 -47
  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 +10 -2
  128. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  129. package/dist/tools/target-diagnostics.js +74 -21
  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 +108 -42
  133. package/dist/tools/wait.js.map +1 -1
  134. package/extension/dist/assets/{content.ts-C4imZ6A9.js → content.ts-BAMOcF3R.js} +1 -1
  135. package/extension/dist/assets/{content.ts-loader-CnJuCGhl.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-CMIY1zhd.js → page-scripts-CSxn58h1.js} +300 -410
  138. package/extension/dist/assets/{popup.html-CgtWL6Py.js → popup.html-DwwHo00N.js} +8 -6
  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 +15 -7
  143. package/scripts/start-chrome.ps1 +9 -1
  144. package/extension/dist/assets/index.ts-GeHNZBml.js +0 -8972
@@ -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 { creationError, setErrorPageContext, setErrorSource, StructuredToolError, TargetNotFoundError, } from '../core/errors.js';
10
9
  import { DEFAULT_TIMEOUT } from '../core/types.js';
10
+ import { remainingNavigationTimeout } from '../core/utils.js';
11
+ import { eventRefTarget } from '../core/browser-events.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',
@@ -35,6 +37,7 @@ const CONDITIONAL_ACTIONS = new Set([
35
37
  'evaluate',
36
38
  'evaluate_in_frame',
37
39
  'debugger_send',
40
+ 'keyboard_focus',
38
41
  'input_key',
39
42
  'input_mouse',
40
43
  'input_touch',
@@ -46,18 +49,24 @@ const CONDITIONAL_ACTIONS = new Set([
46
49
  'stealth_inject',
47
50
  ]);
48
51
  export class ExtensionBridge {
52
+ options;
49
53
  httpServer;
50
54
  currentTabId = null;
55
+ browserEventTargets = new Set();
51
56
  currentFrameId = 0;
57
+ currentFrameDocumentId;
52
58
  state = null;
53
59
  pendingPageCondition = null;
54
60
  constructor(options = {}) {
61
+ this.options = options;
55
62
  this.httpServer = new ExtensionHttpServer({
56
63
  port: options.port,
57
64
  autoPort: true,
65
+ requestContext: options.requestContext,
58
66
  });
59
67
  this.httpServer.setActionConditionProvider((action, params) => {
60
- const condition = this.pendingPageCondition;
68
+ const context = this.options.requestContext?.();
69
+ const condition = context ? context.pendingPageCondition : this.pendingPageCondition;
61
70
  if (!condition || !CONDITIONAL_ACTIONS.has(action)) {
62
71
  return undefined;
63
72
  }
@@ -65,7 +74,12 @@ export class ExtensionBridge {
65
74
  if (tabId === undefined || String(tabId) !== condition.targetId) {
66
75
  throw new DriverCapabilityError('条件动作的目标与请求目标不一致,未执行动作');
67
76
  }
68
- this.pendingPageCondition = null;
77
+ if (context) {
78
+ context.pendingPageCondition = null;
79
+ }
80
+ else {
81
+ this.pendingPageCondition = null;
82
+ }
69
83
  return {
70
84
  ...(condition.expectedUrl !== undefined ? { expectedUrl: condition.expectedUrl } : {}),
71
85
  ...(condition.expectedRevision !== undefined ? { expectedRevision: condition.expectedRevision } : {}),
@@ -86,7 +100,7 @@ export class ExtensionBridge {
86
100
  * @param timeout 超时时间(毫秒),0 表示无限等待(默认)
87
101
  */
88
102
  async waitForConnection(timeout = 0) {
89
- return this.httpServer.waitForConnection(timeout);
103
+ return this.httpServer.waitForConnection(timeout, this.options.requestContext?.()?.signal);
90
104
  }
91
105
  getPort() {
92
106
  return this.httpServer.getPort();
@@ -95,28 +109,72 @@ export class ExtensionBridge {
95
109
  return this.httpServer.getConnectionInfo();
96
110
  }
97
111
  // ==================== Tab 操作 ====================
98
- async listTabs(timeout) {
112
+ async listTabs(timeout, options) {
113
+ const currentTabId = this.currentTabId;
99
114
  const result = await this.httpServer.sendCommand('tabs_list', {}, timeout);
100
- return result;
115
+ const tabs = result;
116
+ if (options?.preserveDefaultTarget !== true &&
117
+ currentTabId !== null &&
118
+ this.currentTabId === currentTabId &&
119
+ !tabs.some((tab) => tab.id === currentTabId)) {
120
+ this.setCurrentTargetId(null);
121
+ }
122
+ return tabs;
101
123
  }
102
- async listWindows(timeout) {
124
+ async listWindows(timeout, options) {
125
+ const currentTabId = this.currentTabId;
103
126
  const result = await this.httpServer.sendCommand('tabs_topology', {}, timeout);
104
127
  const topology = result;
105
- return {
106
- ...topology,
107
- windows: topology.windows.map((window) => ({
108
- ...window,
109
- tabs: window.tabs.map((tab) => ({
110
- ...tab,
111
- targetId: String(tab.id),
112
- type: tab.type ?? 'page',
113
- })),
128
+ const windows = topology.windows.map((window) => ({
129
+ ...window,
130
+ tabs: window.tabs.map((tab) => ({
131
+ ...tab,
132
+ targetId: String(tab.id),
133
+ type: tab.type ?? 'page',
114
134
  })),
115
- };
135
+ }));
136
+ if (Object.hasOwn(topology, 'groups') && !Array.isArray(topology.groups)) {
137
+ throw new Error('Extension tabs_topology 返回的 groups 必须是数组');
138
+ }
139
+ const groups = topology.groups?.map((group) => {
140
+ if (!group || typeof group !== 'object') {
141
+ throw new Error('Extension tabs_topology 返回了无效分组');
142
+ }
143
+ const summary = group;
144
+ if (!Object.hasOwn(summary, 'tabIds') && !Object.hasOwn(summary, 'targetIds')) {
145
+ if (!Number.isSafeInteger(summary.id) || !Number.isSafeInteger(summary.windowId)) {
146
+ throw new Error('Extension tabs_topology 的旧版分组缺少有效 id 或 windowId');
147
+ }
148
+ const members = windows
149
+ .filter((window) => window.id === summary.windowId)
150
+ .flatMap((window) => window.tabs)
151
+ .filter((tab) => tab.groupId === summary.id);
152
+ if (members.some((tab) => !Number.isSafeInteger(tab.id))) {
153
+ throw new Error('Extension tabs_topology 的分组成员包含无效 tab ID');
154
+ }
155
+ return {
156
+ ...group,
157
+ tabIds: members.map((tab) => tab.id),
158
+ targetIds: members.map((tab) => tab.targetId),
159
+ index: group.index ?? members[0]?.index,
160
+ };
161
+ }
162
+ if (!Array.isArray(group.tabIds) || !Array.isArray(group.targetIds)) {
163
+ throw new Error('Extension tabs_topology 的分组成员必须同时提供 tabIds 和 targetIds 数组');
164
+ }
165
+ return group;
166
+ });
167
+ if (options?.preserveDefaultTarget !== true &&
168
+ currentTabId !== null &&
169
+ this.currentTabId === currentTabId &&
170
+ !windows.some((window) => window.tabs.some((tab) => tab.id === currentTabId))) {
171
+ this.setCurrentTargetId(null);
172
+ }
173
+ return { ...topology, windows, ...(groups === undefined ? {} : { groups }) };
116
174
  }
117
175
  /** IBrowserDriver 接口:列出所有 tab,统一为 ListedTarget 形式(id 字符串化以保持跨 driver 兼容) */
118
- async listTargets(timeout) {
119
- const tabs = await this.listTabs(timeout);
176
+ async listTargets(timeout, options) {
177
+ const tabs = await this.listTabs(timeout, options);
120
178
  return tabs.map((tab) => this.tabToTarget(tab));
121
179
  }
122
180
  async createTab(url, timeout, options = {}) {
@@ -172,6 +230,12 @@ export class ExtensionBridge {
172
230
  }
173
231
  return this.closeTab(this.parseTargetId(targetId));
174
232
  }
233
+ async setPageMetadata(targetId, updates) {
234
+ return (await this.httpServer.sendCommand('tabs_metadata', {
235
+ tabId: this.parseTargetId(targetId),
236
+ ...updates,
237
+ }));
238
+ }
175
239
  async setReadAccess(targetId, allow) {
176
240
  return (await this.httpServer.sendCommand('tabs_read_access', {
177
241
  tabId: this.parseTargetId(targetId),
@@ -318,7 +382,6 @@ export class ExtensionBridge {
318
382
  }
319
383
  return this.normalizePageChange(result);
320
384
  }
321
- // noinspection JSUnusedGlobalSymbols — UnifiedSessionManager 通过 bridge 结构类型调用
322
385
  async activatePageWithAffected(targetId) {
323
386
  const tabId = this.parseTargetId(targetId);
324
387
  const result = (await this.httpServer.sendCommand('tabs_activate_managed', {
@@ -369,7 +432,7 @@ export class ExtensionBridge {
369
432
  }
370
433
  catch (error) {
371
434
  if (error instanceof Error && error.message === 'Unknown action: page_snapshot') {
372
- const tabs = await this.listTabs(deadline === undefined ? undefined : remainingNavigationTimeout(deadline));
435
+ const tabs = await this.listTabs(deadline === undefined ? undefined : remainingNavigationTimeout(deadline), { preserveDefaultTarget: true });
373
436
  if (deadline !== undefined) {
374
437
  remainingNavigationTimeout(deadline);
375
438
  }
@@ -394,7 +457,13 @@ export class ExtensionBridge {
394
457
  }
395
458
  }
396
459
  setPageCondition(condition) {
397
- this.pendingPageCondition = condition;
460
+ const context = this.options.requestContext?.();
461
+ if (context) {
462
+ context.pendingPageCondition = condition;
463
+ }
464
+ else {
465
+ this.pendingPageCondition = condition;
466
+ }
398
467
  }
399
468
  /** IBrowserDriver 接口:设置当前操作目标 ID */
400
469
  setCurrentTargetId(targetId) {
@@ -446,24 +515,26 @@ export class ExtensionBridge {
446
515
  }));
447
516
  }
448
517
  // ==================== 页面内容 ====================
449
- async click(refId) {
518
+ async click(refId, timeout, modifiers = 0) {
450
519
  const result = (await this.httpServer.sendCommand('click', {
451
520
  tabId: this.requireCurrentTabId(),
452
521
  frameId: this.currentFrameId || undefined,
453
522
  refId,
454
- }));
523
+ modifiers,
524
+ }, timeout));
455
525
  if (!result.success) {
456
526
  throw new Error(result.error || 'Click failed');
457
527
  }
458
528
  }
459
529
  // ==================== DOM 操作 ====================
460
- async actionableClick(refId, force) {
530
+ async actionableClick(refId, force, timeout, modifiers = 0) {
461
531
  return (await this.httpServer.sendCommand('actionable_click', {
462
532
  tabId: this.requireCurrentTabId(),
463
533
  frameId: this.currentFrameId || undefined,
464
534
  refId,
465
535
  force: force ?? false,
466
- }));
536
+ modifiers,
537
+ }, timeout));
467
538
  }
468
539
  async checkActionability(refId) {
469
540
  const result = (await this.httpServer.sendCommand('check_actionability', {
@@ -474,12 +545,16 @@ export class ExtensionBridge {
474
545
  return { ...result, success: result.success ?? result.actionable === true };
475
546
  }
476
547
  async dispatchInput(refId, text) {
477
- return (await this.httpServer.sendCommand('dispatch_input', {
548
+ const result = await this.httpServer.sendCommand('dispatch_input', {
478
549
  tabId: this.requireCurrentTabId(),
479
550
  frameId: this.currentFrameId || undefined,
480
551
  refId,
481
552
  text,
482
- }));
553
+ });
554
+ if (!result || typeof result !== 'object' || !('success' in result) || typeof result.success !== 'boolean') {
555
+ throw new StructuredToolError('ACTION_RESULT_INVALID', 'controlled 输入已派发,但未返回有效的动作结果', '独立读取目标实际文本后再决定下一步,工具不会重放输入', { actionExecuted: 'unknown', actionStatus: 'unknown', retryable: false, failureStage: 'script_result' });
556
+ }
557
+ return result;
483
558
  }
484
559
  async dragAndDrop(srcRefId, dstRefId) {
485
560
  return (await this.httpServer.sendCommand('drag_and_drop', {
@@ -526,7 +601,7 @@ export class ExtensionBridge {
526
601
  scrollAt(x, y, refId) {
527
602
  return this.scroll(x, y, refId);
528
603
  }
529
- async evaluate(code, _args, timeout) {
604
+ async evaluate(code, _args, timeout, userAction) {
530
605
  // _args 参数仅满足 IBrowserDriver 接口签名;ExtensionBridge 不消费 args(stealth 路径上层已字符串拼接)
531
606
  const rpcTimeout = timeout !== undefined ? timeout + RPC_MARGIN : undefined;
532
607
  const result = (await this.httpServer.sendCommand('evaluate', {
@@ -534,21 +609,92 @@ export class ExtensionBridge {
534
609
  frameId: this.currentFrameId || undefined,
535
610
  code,
536
611
  timeout,
537
- }, rpcTimeout));
612
+ deadline: Date.now() + (timeout ?? DEFAULT_TIMEOUT),
613
+ }, rpcTimeout, userAction));
614
+ const outputError = (message, suggestion, context, cause) => {
615
+ const error = new StructuredToolError('NON_SERIALIZABLE_EVALUATE_RESULT', message, suggestion, {
616
+ ...context,
617
+ ...(result.errorMessage !== undefined ? { originalOutputError: result.errorMessage } : {}),
618
+ actionExecuted: true,
619
+ actionStatus: 'completed',
620
+ failureStage: 'output',
621
+ retryable: false,
622
+ });
623
+ if (cause !== undefined) {
624
+ Object.defineProperty(error, 'cause', { value: cause, configurable: true, writable: true });
625
+ }
626
+ if (userAction === undefined) {
627
+ setErrorPageContext(error, { contextPhase: 'preparation' });
628
+ }
629
+ return error;
630
+ };
538
631
  if (!result.success) {
539
- throw new Error(result.error || 'Evaluate failed');
632
+ if (result.errorSource === 'context' && result.actionExecuted === false) {
633
+ throw setErrorSource(new StructuredToolError(result.errorCode ?? 'UNKNOWN_ERROR', result.error ?? 'Script compilation failed', result.errorCode === 'CSP_BLOCKED'
634
+ ? '可使用 evaluate 的 mode="precise" 执行脚本;当前脚本未执行'
635
+ : '请检查脚本语法,当前脚本未执行', {
636
+ actionExecuted: false,
637
+ actionStatus: 'not_started',
638
+ failureStage: 'context',
639
+ retryable: false,
640
+ phase: 'compile',
641
+ }), 'context');
642
+ }
643
+ if (result.errorSource === 'output') {
644
+ if (result.errorCode === 'NON_SERIALIZABLE_EVALUATE_RESULT') {
645
+ throw outputError(result.error ?? 'evaluate 输出处理失败', '请检查返回值及页面的 JSON 序列化行为', {
646
+ error: result.error,
647
+ detailSerializationFailed: true,
648
+ });
649
+ }
650
+ let detail;
651
+ try {
652
+ const value = JSON.parse(result.error)?.error;
653
+ if (typeof value?.message !== 'string' ||
654
+ typeof value.suggestion !== 'string' ||
655
+ !value.context ||
656
+ typeof value.context !== 'object' ||
657
+ Array.isArray(value.context)) {
658
+ throw new TypeError('浏览器返回的 evaluate 输出错误详情格式无效');
659
+ }
660
+ detail = {
661
+ message: value.message,
662
+ suggestion: value.suggestion,
663
+ context: value.context,
664
+ };
665
+ }
666
+ catch (error) {
667
+ throw outputError(`evaluate 输出错误详情解析失败: ${error}`, '请检查页面的 JSON 序列化行为', {
668
+ error: result.error,
669
+ detailParsingError: String(error),
670
+ }, error);
671
+ }
672
+ throw outputError(detail.message, detail.suggestion, detail.context);
673
+ }
674
+ const error = new Error(result.error ?? 'Evaluate failed');
675
+ throw result.errorSource === 'page' ? setErrorSource(error, 'page') : error;
540
676
  }
541
- if (!result.result) {
677
+ if (result.result === undefined) {
542
678
  return undefined;
543
679
  }
544
680
  try {
681
+ if (typeof result.result !== 'string') {
682
+ throw new TypeError('浏览器返回的 evaluate 结果不是 JSON 字符串');
683
+ }
545
684
  return JSON.parse(result.result);
546
685
  }
547
686
  catch (err) {
548
- throw new Error(`evaluate 结果 JSON 解析失败: ${err}`, { cause: err });
687
+ throw outputError(`evaluate 结果 JSON 解析失败: ${err}`, '请返回可 JSON 序列化的简单数据,并检查页面的 JSON 序列化行为', { error: String(err) }, err);
549
688
  }
550
689
  }
551
- async find(selector, text, xpath, timeout, point, matchIndex) {
690
+ async find(selector, text, xpath, timeout, semanticOrPointOrMatchIndex, matchIndex) {
691
+ const point = typeof semanticOrPointOrMatchIndex === 'object' && 'x' in semanticOrPointOrMatchIndex
692
+ ? semanticOrPointOrMatchIndex
693
+ : undefined;
694
+ const semantic = typeof semanticOrPointOrMatchIndex === 'object' && !('x' in semanticOrPointOrMatchIndex)
695
+ ? semanticOrPointOrMatchIndex
696
+ : undefined;
697
+ matchIndex = typeof semanticOrPointOrMatchIndex === 'number' ? semanticOrPointOrMatchIndex : matchIndex;
552
698
  return (await this.httpServer.sendCommand('find', {
553
699
  tabId: this.requireCurrentTabId(),
554
700
  frameId: this.currentFrameId || undefined,
@@ -556,6 +702,7 @@ export class ExtensionBridge {
556
702
  text,
557
703
  xpath,
558
704
  point,
705
+ semantic,
559
706
  matchIndex,
560
707
  }, timeout));
561
708
  }
@@ -648,25 +795,67 @@ export class ExtensionBridge {
648
795
  ...(chromeSameSite !== undefined && { sameSite: chromeSameSite }),
649
796
  });
650
797
  }
651
- async deleteCookie(url, name) {
652
- await this.httpServer.sendCommand('cookies_delete', { url, name });
798
+ async deleteCookie(url, name, scope) {
799
+ await this.httpServer.sendCommand('cookies_delete', { url, name, ...scope });
653
800
  }
654
801
  async clearCookies(filter) {
655
802
  return (await this.httpServer.sendCommand('cookies_clear', filter ?? {}));
656
803
  }
657
- async debuggerSend(method, params, tabId, timeout) {
804
+ async browserEvents(action, command, targetId, timeout) {
805
+ const refTarget = command.ref ? eventRefTarget(command.ref) : undefined;
806
+ if (refTarget && (refTarget.backend !== 'extension' || (targetId && refTarget.targetId !== targetId))) {
807
+ throw new DriverCapabilityError('Browser event ref target mismatch');
808
+ }
809
+ const id = refTarget?.targetId ?? targetId ?? this.getCurrentTargetId();
810
+ if (!id || !/^\d+$/.test(id)) {
811
+ throw new DriverCapabilityError('Browser events require an explicit target or observed ref');
812
+ }
813
+ const result = (await this.httpServer.sendCommand('browser_events', { tabId: Number(id), action, command }, timeout));
814
+ this.browserEventTargets.add(id);
815
+ return result;
816
+ }
817
+ hasBrowserEventObservation(targetId) {
818
+ const id = targetId ?? this.getCurrentTargetId();
819
+ return id !== null && id !== undefined && this.browserEventTargets.has(id);
820
+ }
821
+ async browserFetchCommand(method, params, targetId) {
822
+ const id = targetId ?? this.getCurrentTargetId();
823
+ if (!id || !/^\d+$/.test(id)) {
824
+ throw new DriverCapabilityError('Explicit targetId required for Fetch control');
825
+ }
826
+ return this.httpServer.sendCommand('browser_events_raw', { tabId: Number(id), method, params });
827
+ }
828
+ async suspendBrowserEventsForChallenge() {
829
+ const id = String(this.requireCurrentTabId());
830
+ if (!this.browserEventTargets.has(id)) {
831
+ return { targetId: id, suspended: true, observations: [], cleanupFailures: [], fetchEnabled: false };
832
+ }
833
+ const result = (await this.httpServer.sendCommand('browser_events_suspend', { tabId: Number(id) }));
834
+ if (result.suspended === true) {
835
+ this.browserEventTargets.delete(id);
836
+ }
837
+ return result;
838
+ }
839
+ async debuggerSend(method, params, tabId, timeout, userAction) {
840
+ if (method === 'Fetch.enable') {
841
+ await this.browserEvents('read', { type: 'network', view: 'summary' }, String(tabId ?? this.requireCurrentTabId()), timeout);
842
+ }
658
843
  return await this.httpServer.sendCommand('debugger_send', {
659
844
  tabId: tabId ?? this.requireCurrentTabId(),
660
845
  method,
661
846
  params,
662
- }, timeout);
847
+ }, timeout, userAction);
663
848
  }
664
849
  async debuggerDetach(tabId, timeout = DEFAULT_TIMEOUT) {
665
850
  await this.sendBudgetedCommand('debugger_detach', {
666
851
  tabId: tabId ?? this.requireCurrentTabId(),
667
852
  }, timeout);
853
+ this.browserEventTargets.delete(String(tabId ?? this.requireCurrentTabId()));
668
854
  }
669
- async getViewportMetrics(frameId) {
855
+ async getViewportMetrics(frameId, pointerProbe, timeout) {
856
+ if (pointerProbe) {
857
+ return this.sendBudgetedCommand('viewport_metrics', { tabId: this.requireCurrentTabId(), pointerProbe }, timeout);
858
+ }
670
859
  const selectedFrameId = frameId ?? this.currentFrameId;
671
860
  return this.httpServer.sendCommand('viewport_metrics', {
672
861
  tabId: this.requireCurrentTabId(),
@@ -681,16 +870,43 @@ export class ExtensionBridge {
681
870
  }, timeout);
682
871
  }
683
872
  // ==================== Debugger (CDP via Extension) ====================
684
- async inputKey(type, options = {}) {
685
- await this.httpServer.sendCommand('input_key', {
873
+ async acquireKeyboardFocus(id, timeout) {
874
+ return (await this.sendBudgetedCommand('keyboard_focus', {
875
+ operation: 'acquire',
876
+ id,
877
+ tabId: this.requireCurrentTabId(),
878
+ frameId: this.currentFrameId,
879
+ documentId: this.currentFrameDocumentId,
880
+ }, timeout));
881
+ }
882
+ async releaseKeyboardFocus(focus, releaseKeys) {
883
+ return (await this.sendBudgetedCommand('keyboard_focus', {
884
+ operation: 'release',
885
+ id: focus.id,
886
+ tabId: this.parseTargetId(focus.targetId),
887
+ releaseKeys,
888
+ }, 4000));
889
+ }
890
+ async inputKey(type, options = {}, timeout) {
891
+ await this.sendBudgetedCommand('input_key', {
686
892
  tabId: this.requireCurrentTabId(),
893
+ keyboardFocusId: this.options.requestContext?.()?.keyboardFocus?.id,
687
894
  type,
688
895
  ...options,
689
- });
896
+ }, timeout);
690
897
  }
691
898
  // ==================== 输入事件(通过 CDP)====================
692
899
  async inputMouse(type, x, y, options = {}, timeout) {
693
- const params = { tabId: this.requireCurrentTabId(), type, x, y, ...options };
900
+ const params = {
901
+ tabId: this.requireCurrentTabId(),
902
+ frameId: this.currentFrameId,
903
+ documentId: this.currentFrameDocumentId,
904
+ ...(type !== 'mouseWheel' && this.currentFrameId ? { coordinateSpace: 'frame' } : {}),
905
+ type,
906
+ x,
907
+ y,
908
+ ...options,
909
+ };
694
910
  if (timeout === undefined) {
695
911
  await this.httpServer.sendCommand('input_mouse', params);
696
912
  }
@@ -701,12 +917,20 @@ export class ExtensionBridge {
701
917
  async inputTouch(type, touchPoints) {
702
918
  await this.httpServer.sendCommand('input_touch', {
703
919
  tabId: this.requireCurrentTabId(),
920
+ frameId: this.currentFrameId,
921
+ documentId: this.currentFrameDocumentId,
704
922
  type,
705
923
  touchPoints,
706
924
  });
707
925
  }
708
926
  async inputType(text, delay = 0, timeout = DEFAULT_TIMEOUT) {
709
- await this.httpServer.sendCommand('input_type', { tabId: this.requireCurrentTabId(), text, delay, deadline: Date.now() + timeout }, timeout);
927
+ await this.httpServer.sendCommand('input_type', {
928
+ tabId: this.requireCurrentTabId(),
929
+ keyboardFocusId: this.options.requestContext?.()?.keyboardFocus?.id,
930
+ text,
931
+ delay,
932
+ deadline: Date.now() + timeout,
933
+ }, timeout);
710
934
  }
711
935
  async consoleEnable() {
712
936
  await this.httpServer.sendCommand('console_enable', {
@@ -748,7 +972,7 @@ export class ExtensionBridge {
748
972
  await this.httpServer.sendCommand('stealth_type', params, timeout);
749
973
  }
750
974
  // ==================== Stealth 模式(JS 事件模拟,无 debugger)====================
751
- async stealthKey(key, type = 'press', modifiers = []) {
975
+ async stealthKey(key, type = 'press', modifiers = [], timeout) {
752
976
  if (this.currentTabId === null) {
753
977
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
754
978
  }
@@ -759,9 +983,9 @@ export class ExtensionBridge {
759
983
  type,
760
984
  modifiers,
761
985
  };
762
- await this.httpServer.sendCommand('stealth_key', params);
986
+ await this.sendBudgetedCommand('stealth_key', params, timeout);
763
987
  }
764
- async stealthClick(x, y, button = 'left', clickCount = 1, refId, timeout = DEFAULT_TIMEOUT) {
988
+ async stealthClick(x, y, button = 'left', clickCount = 1, refId, timeout = DEFAULT_TIMEOUT, modifiers = 0) {
765
989
  if (this.currentTabId === null) {
766
990
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
767
991
  }
@@ -772,13 +996,14 @@ export class ExtensionBridge {
772
996
  y,
773
997
  button,
774
998
  clickCount,
999
+ modifiers,
775
1000
  };
776
1001
  if (typeof refId === 'string') {
777
1002
  params.refId = refId;
778
1003
  }
779
1004
  await this.sendBudgetedCommand('stealth_click', params, timeout);
780
1005
  }
781
- async stealthMouse(type, x, y, button = 'left', timeout) {
1006
+ async stealthMouse(type, x, y, button = 'left', timeout, modifiers = 0) {
782
1007
  if (this.currentTabId === null) {
783
1008
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
784
1009
  }
@@ -789,6 +1014,7 @@ export class ExtensionBridge {
789
1014
  x,
790
1015
  y,
791
1016
  button,
1017
+ modifiers,
792
1018
  };
793
1019
  if (timeout === undefined) {
794
1020
  await this.httpServer.sendCommand('stealth_mouse', params);
@@ -814,13 +1040,17 @@ export class ExtensionBridge {
814
1040
  getCurrentFrameId() {
815
1041
  return this.currentFrameId;
816
1042
  }
817
- setCurrentFrameId(frameId) {
1043
+ getCurrentFrameDocumentId() {
1044
+ return this.currentFrameDocumentId;
1045
+ }
1046
+ setCurrentFrameId(frameId, documentId) {
818
1047
  this.currentFrameId = frameId;
1048
+ this.currentFrameDocumentId = documentId;
819
1049
  }
820
1050
  /**
821
1051
  * 在指定 iframe 中以 precise 模式执行 JS(通过 contextId 绕过 CSP)
822
1052
  */
823
- async evaluateInFrame(frameId, expression, timeout, staleContextRetry = 'never') {
1053
+ async evaluateInFrame(frameId, expression, timeout, staleContextRetry = 'never', userAction) {
824
1054
  return (await this.httpServer.sendCommand('evaluate_in_frame', {
825
1055
  tabId: this.requireCurrentTabId(),
826
1056
  frameId,
@@ -829,22 +1059,24 @@ export class ExtensionBridge {
829
1059
  awaitPromise: true,
830
1060
  timeout,
831
1061
  staleContextRetry,
832
- }, timeout));
1062
+ }, timeout, userAction));
833
1063
  }
834
1064
  /**
835
1065
  * 解析 iframe 选择器/索引 → frameId
836
1066
  */
837
- async resolveFrame(frame) {
838
- return (await this.httpServer.sendCommand('resolve_frame', {
1067
+ async resolveFrame(frame, timeout) {
1068
+ return (await this.sendBudgetedCommand('resolve_frame', {
839
1069
  tabId: this.requireCurrentTabId(),
840
1070
  frame,
841
- }));
1071
+ }, timeout));
842
1072
  }
843
1073
  async sendBudgetedCommand(action, params, timeout = DEFAULT_TIMEOUT) {
844
1074
  const deadline = Date.now() + timeout;
845
1075
  const remaining = remainingNavigationTimeout(deadline);
846
1076
  try {
847
- return await this.httpServer.sendCommand(action, { ...params, timeout: remaining, deadline }, remaining);
1077
+ const result = await this.httpServer.sendCommand(action, { ...params, timeout: remaining, deadline }, remaining);
1078
+ remainingNavigationTimeout(deadline);
1079
+ return result;
848
1080
  }
849
1081
  catch (error) {
850
1082
  if (error instanceof Error && error.message.startsWith(`Request timeout for action: ${action} (`)) {
@@ -894,7 +1126,7 @@ export class ExtensionBridge {
894
1126
  };
895
1127
  }
896
1128
  parseTargetId(targetId) {
897
- if (!/^(0|[1-9]\d*)$/.test(targetId)) {
1129
+ if (!/^(?:0|[1-9]\d*)$/.test(targetId)) {
898
1130
  throw new DriverCapabilityError(`无效的 Tab ID: ${targetId}`);
899
1131
  }
900
1132
  const parsed = Number(targetId);