@pyrokine/mcp-chrome 2.4.4 → 3.0.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 (116) hide show
  1. package/README.md +401 -102
  2. package/README_zh.md +319 -79
  3. package/dist/anti-detection/injection.js +3 -3
  4. package/dist/cdp/client.d.ts +1 -1
  5. package/dist/cdp/client.d.ts.map +1 -1
  6. package/dist/cdp/client.js +18 -7
  7. package/dist/cdp/client.js.map +1 -1
  8. package/dist/cdp/launcher.d.ts +2 -3
  9. package/dist/cdp/launcher.d.ts.map +1 -1
  10. package/dist/cdp/launcher.js +84 -24
  11. package/dist/cdp/launcher.js.map +1 -1
  12. package/dist/core/auto-wait.d.ts +3 -3
  13. package/dist/core/auto-wait.d.ts.map +1 -1
  14. package/dist/core/auto-wait.js +45 -20
  15. package/dist/core/auto-wait.js.map +1 -1
  16. package/dist/core/browser-driver.d.ts +101 -12
  17. package/dist/core/browser-driver.d.ts.map +1 -1
  18. package/dist/core/browser-driver.js.map +1 -1
  19. package/dist/core/errors.d.ts +16 -0
  20. package/dist/core/errors.d.ts.map +1 -1
  21. package/dist/core/errors.js +77 -0
  22. package/dist/core/errors.js.map +1 -1
  23. package/dist/core/locator.d.ts.map +1 -1
  24. package/dist/core/locator.js +6 -4
  25. package/dist/core/locator.js.map +1 -1
  26. package/dist/core/os-mouse.d.ts +15 -2
  27. package/dist/core/os-mouse.d.ts.map +1 -1
  28. package/dist/core/os-mouse.js +52 -8
  29. package/dist/core/os-mouse.js.map +1 -1
  30. package/dist/core/session.d.ts +34 -19
  31. package/dist/core/session.d.ts.map +1 -1
  32. package/dist/core/session.js +574 -130
  33. package/dist/core/session.js.map +1 -1
  34. package/dist/core/types.d.ts +2 -0
  35. package/dist/core/types.d.ts.map +1 -1
  36. package/dist/core/types.js.map +1 -1
  37. package/dist/core/unified-session.d.ts +95 -20
  38. package/dist/core/unified-session.d.ts.map +1 -1
  39. package/dist/core/unified-session.js +489 -117
  40. package/dist/core/unified-session.js.map +1 -1
  41. package/dist/core/utils.d.ts +5 -0
  42. package/dist/core/utils.d.ts.map +1 -1
  43. package/dist/core/utils.js +475 -54
  44. package/dist/core/utils.js.map +1 -1
  45. package/dist/extension/bridge.d.ts +46 -36
  46. package/dist/extension/bridge.d.ts.map +1 -1
  47. package/dist/extension/bridge.js +269 -112
  48. package/dist/extension/bridge.js.map +1 -1
  49. package/dist/extension/http-server.d.ts +3 -0
  50. package/dist/extension/http-server.d.ts.map +1 -1
  51. package/dist/extension/http-server.js +19 -2
  52. package/dist/extension/http-server.js.map +1 -1
  53. package/dist/index.js +7 -0
  54. package/dist/index.js.map +1 -1
  55. package/dist/tools/browse.d.ts.map +1 -1
  56. package/dist/tools/browse.js +241 -171
  57. package/dist/tools/browse.js.map +1 -1
  58. package/dist/tools/challenge.d.ts +1 -1
  59. package/dist/tools/challenge.d.ts.map +1 -1
  60. package/dist/tools/challenge.js +75 -37
  61. package/dist/tools/challenge.js.map +1 -1
  62. package/dist/tools/cookies.d.ts.map +1 -1
  63. package/dist/tools/cookies.js +5 -3
  64. package/dist/tools/cookies.js.map +1 -1
  65. package/dist/tools/diagnostics.d.ts +3 -3
  66. package/dist/tools/diagnostics.d.ts.map +1 -1
  67. package/dist/tools/diagnostics.js +13 -12
  68. package/dist/tools/diagnostics.js.map +1 -1
  69. package/dist/tools/evaluate.d.ts.map +1 -1
  70. package/dist/tools/evaluate.js +57 -26
  71. package/dist/tools/evaluate.js.map +1 -1
  72. package/dist/tools/extract.d.ts.map +1 -1
  73. package/dist/tools/extract.js +107 -175
  74. package/dist/tools/extract.js.map +1 -1
  75. package/dist/tools/input.d.ts +1 -1
  76. package/dist/tools/input.d.ts.map +1 -1
  77. package/dist/tools/input.js +380 -158
  78. package/dist/tools/input.js.map +1 -1
  79. package/dist/tools/logs.d.ts.map +1 -1
  80. package/dist/tools/logs.js +5 -5
  81. package/dist/tools/logs.js.map +1 -1
  82. package/dist/tools/manage.d.ts.map +1 -1
  83. package/dist/tools/manage.js +380 -57
  84. package/dist/tools/manage.js.map +1 -1
  85. package/dist/tools/page-context.d.ts +17 -0
  86. package/dist/tools/page-context.d.ts.map +1 -0
  87. package/dist/tools/page-context.js +103 -0
  88. package/dist/tools/page-context.js.map +1 -0
  89. package/dist/tools/png.d.ts +5 -0
  90. package/dist/tools/png.d.ts.map +1 -1
  91. package/dist/tools/png.js +84 -19
  92. package/dist/tools/png.js.map +1 -1
  93. package/dist/tools/post-condition.d.ts.map +1 -1
  94. package/dist/tools/post-condition.js +5 -2
  95. package/dist/tools/post-condition.js.map +1 -1
  96. package/dist/tools/schema.d.ts +9 -0
  97. package/dist/tools/schema.d.ts.map +1 -1
  98. package/dist/tools/schema.js +15 -0
  99. package/dist/tools/schema.js.map +1 -1
  100. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  101. package/dist/tools/target-diagnostics.js +32 -19
  102. package/dist/tools/target-diagnostics.js.map +1 -1
  103. package/dist/tools/wait.d.ts.map +1 -1
  104. package/dist/tools/wait.js +19 -25
  105. package/dist/tools/wait.js.map +1 -1
  106. package/extension/dist/assets/content.ts-C4imZ6A9.js +13 -0
  107. package/extension/dist/assets/content.ts-loader-CnJuCGhl.js +13 -0
  108. package/extension/dist/assets/{index.ts-Bqcu2qiN.js → index.ts-GeHNZBml.js} +2040 -2111
  109. package/extension/dist/assets/page-scripts-CMIY1zhd.js +1379 -0
  110. package/extension/dist/assets/{popup.html-B81xccfq.js → popup.html-CgtWL6Py.js} +48 -1
  111. package/extension/dist/manifest.json +4 -3
  112. package/extension/dist/service-worker-loader.js +1 -1
  113. package/extension/dist/src/popup/popup.html +11 -1
  114. package/package.json +9 -7
  115. package/scripts/start-chrome.ps1 +58 -0
  116. package/extension/dist/assets/content.ts-Cj_iiU2s.js +0 -25
@@ -5,33 +5,75 @@
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';
10
+ import { DEFAULT_TIMEOUT } from '../core/types.js';
8
11
  import { ExtensionHttpServer } from './http-server.js';
9
12
  /** RPC 传输余量(毫秒):给网络往返和 Extension 处理留出的额外时间 */
10
13
  const RPC_MARGIN = 5000;
11
- /** goBack/goForward 信号窗口(毫秒):Extension 等待导航开始的上限 */
12
- const NAV_SIGNAL_WINDOW = 5000;
14
+ const CONDITIONAL_ACTIONS = new Set([
15
+ 'tabs_close',
16
+ 'tabs_activate',
17
+ 'tabs_activate_managed',
18
+ 'tabs_adopt',
19
+ 'tabs_release',
20
+ 'tabs_read_access',
21
+ 'tabs_move',
22
+ 'tabs_reorder',
23
+ 'tabs_pin',
24
+ 'tabs_update',
25
+ 'navigate',
26
+ 'go_back',
27
+ 'go_forward',
28
+ 'reload',
29
+ 'click',
30
+ 'actionable_click',
31
+ 'dispatch_input',
32
+ 'drag_and_drop',
33
+ 'type',
34
+ 'scroll',
35
+ 'evaluate',
36
+ 'evaluate_in_frame',
37
+ 'debugger_send',
38
+ 'input_key',
39
+ 'input_mouse',
40
+ 'input_touch',
41
+ 'input_type',
42
+ 'stealth_click',
43
+ 'stealth_type',
44
+ 'stealth_key',
45
+ 'stealth_mouse',
46
+ 'stealth_inject',
47
+ ]);
13
48
  export class ExtensionBridge {
14
49
  httpServer;
15
50
  currentTabId = null;
16
51
  currentFrameId = 0;
17
52
  state = null;
53
+ pendingPageCondition = null;
18
54
  constructor(options = {}) {
19
55
  this.httpServer = new ExtensionHttpServer({
20
56
  port: options.port,
21
57
  autoPort: true,
22
58
  });
59
+ this.httpServer.setActionConditionProvider((action, params) => {
60
+ const condition = this.pendingPageCondition;
61
+ if (!condition || !CONDITIONAL_ACTIONS.has(action)) {
62
+ return undefined;
63
+ }
64
+ const tabId = params?.tabId;
65
+ if (tabId === undefined || String(tabId) !== condition.targetId) {
66
+ throw new DriverCapabilityError('条件动作的目标与请求目标不一致,未执行动作');
67
+ }
68
+ this.pendingPageCondition = null;
69
+ return {
70
+ ...(condition.expectedUrl !== undefined ? { expectedUrl: condition.expectedUrl } : {}),
71
+ ...(condition.expectedRevision !== undefined ? { expectedRevision: condition.expectedRevision } : {}),
72
+ };
73
+ });
23
74
  }
24
75
  async start() {
25
76
  await this.httpServer.start();
26
- // Extension 重连后自动恢复 attach 状态
27
- this.httpServer.on('connected', () => {
28
- if (this.currentTabId !== null) {
29
- const tabId = this.currentTabId;
30
- this.httpServer.sendCommand('debugger_attach', { tabId }).catch((err) => {
31
- console.error('[Bridge] 重连后 debugger re-attach 失败:', err.message);
32
- });
33
- }
34
- });
35
77
  }
36
78
  async stop() {
37
79
  await this.httpServer.stop();
@@ -53,12 +95,12 @@ export class ExtensionBridge {
53
95
  return this.httpServer.getConnectionInfo();
54
96
  }
55
97
  // ==================== Tab 操作 ====================
56
- async listTabs() {
57
- const result = await this.httpServer.sendCommand('tabs_list', {});
98
+ async listTabs(timeout) {
99
+ const result = await this.httpServer.sendCommand('tabs_list', {}, timeout);
58
100
  return result;
59
101
  }
60
- async listWindows() {
61
- const result = await this.httpServer.sendCommand('tabs_topology', {});
102
+ async listWindows(timeout) {
103
+ const result = await this.httpServer.sendCommand('tabs_topology', {}, timeout);
62
104
  const topology = result;
63
105
  return {
64
106
  ...topology,
@@ -73,18 +115,30 @@ export class ExtensionBridge {
73
115
  };
74
116
  }
75
117
  /** IBrowserDriver 接口:列出所有 tab,统一为 ListedTarget 形式(id 字符串化以保持跨 driver 兼容) */
76
- async listTargets() {
77
- const tabs = await this.listTabs();
118
+ async listTargets(timeout) {
119
+ const tabs = await this.listTabs(timeout);
78
120
  return tabs.map((tab) => this.tabToTarget(tab));
79
121
  }
80
- async createTab(url, timeout) {
81
- const rpcTimeout = timeout !== undefined ? timeout + RPC_MARGIN : undefined;
82
- const result = await this.httpServer.sendCommand('tabs_create', {
122
+ async createTab(url, timeout, options = {}) {
123
+ const rpcTimeout = (timeout ?? 30000) + RPC_MARGIN;
124
+ const result = await this.httpServer
125
+ .sendCommand('tabs_create', {
83
126
  url,
84
127
  active: false,
128
+ ...options,
85
129
  waitUntil: 'load',
86
130
  timeout,
87
- }, rpcTimeout);
131
+ }, rpcTimeout)
132
+ .catch((error) => {
133
+ throw creationError(error, {
134
+ action: 'tabs_create',
135
+ createdTargetId: null,
136
+ managed: null,
137
+ actionExecuted: 'unknown',
138
+ actionStatus: 'unknown',
139
+ failureStage: 'rpc',
140
+ });
141
+ });
88
142
  const tab = result;
89
143
  // 自动切换到新创建的 tab,后续操作立即生效
90
144
  this.currentTabId = tab.id;
@@ -92,9 +146,10 @@ export class ExtensionBridge {
92
146
  return tab;
93
147
  }
94
148
  /** IBrowserDriver 接口:新建页面(targetId 为字符串化的 chrome tab id) */
95
- async newPage(url, timeout) {
96
- const tab = await this.createTab(url, timeout);
149
+ async newPage(url, timeout, options) {
150
+ const tab = await this.createTab(url, timeout, options);
97
151
  return {
152
+ ...this.tabToTarget(tab),
98
153
  targetId: String(tab.id),
99
154
  url: tab.url,
100
155
  title: tab.title,
@@ -110,13 +165,18 @@ export class ExtensionBridge {
110
165
  }
111
166
  return this.normalizePageChange(result);
112
167
  }
113
- /** IBrowserDriver 接口:关闭页面(targetId 是 chrome tab id 的字符串形式,省略时关闭当前 tab) */
168
+ /** IBrowserDriver 接口:只能关闭明确指定的 tab */
114
169
  async closePage(targetId) {
115
- const tabId = targetId !== undefined ? this.parseTargetId(targetId) : this.currentTabId;
116
- if (tabId === null) {
117
- throw new DriverCapabilityError('没有可关闭的页面,请指定 targetId');
170
+ if (!targetId) {
171
+ throw new DriverCapabilityError('closePage 需要显式 targetId,未关闭页面');
118
172
  }
119
- return this.closeTab(tabId);
173
+ return this.closeTab(this.parseTargetId(targetId));
174
+ }
175
+ async setReadAccess(targetId, allow) {
176
+ return (await this.httpServer.sendCommand('tabs_read_access', {
177
+ tabId: this.parseTargetId(targetId),
178
+ allow,
179
+ }));
120
180
  }
121
181
  async adoptPage(targetId) {
122
182
  const tabId = this.parseTargetId(targetId);
@@ -140,6 +200,7 @@ export class ExtensionBridge {
140
200
  target: this.tabToTarget(result.tab),
141
201
  managedBefore: result.managedBefore,
142
202
  managedAfter: result.managedAfter,
203
+ ...(result.warnings?.length ? { warnings: result.warnings } : {}),
143
204
  };
144
205
  }
145
206
  async movePage(targetId, options) {
@@ -152,6 +213,43 @@ export class ExtensionBridge {
152
213
  }));
153
214
  return this.normalizePageChange(result);
154
215
  }
216
+ async updatePage(targetId, options) {
217
+ const tabId = this.parseTargetId(targetId);
218
+ const result = (await this.httpServer.sendCommand('tabs_update', {
219
+ tabId,
220
+ ...options,
221
+ }));
222
+ const after = result.after;
223
+ if (this.currentTabId === tabId && after) {
224
+ this.updateState(after);
225
+ }
226
+ return this.normalizePageChange(result);
227
+ }
228
+ async groupPages(targetIds, options) {
229
+ const tabIds = targetIds.map((id) => this.parseTargetId(id));
230
+ if (options.groupId !== undefined &&
231
+ [options.windowId, options.title, options.color, options.collapsed].some((value) => value !== undefined)) {
232
+ throw new DriverCapabilityError('加入已有分组仅接受页面列表与 groupId;修改分组请用 updateGroup/moveGroup,未执行');
233
+ }
234
+ const result = options.groupId !== undefined
235
+ ? await this.httpServer.sendCommand('tabgroup_add', { tabIds, groupId: options.groupId })
236
+ : await this.httpServer.sendCommand('tabgroup_create', { tabIds, ...options });
237
+ return this.normalizeGroupChange(result);
238
+ }
239
+ async ungroupPages(targetIds) {
240
+ const result = await this.httpServer.sendCommand('tabgroup_remove', {
241
+ tabIds: targetIds.map((id) => this.parseTargetId(id)),
242
+ });
243
+ return this.normalizeGroupChange(result);
244
+ }
245
+ async updateGroup(groupId, options) {
246
+ const result = await this.httpServer.sendCommand('tabgroup_update', { groupId, ...options });
247
+ return this.normalizeGroupChange(result);
248
+ }
249
+ async moveGroup(groupId, options) {
250
+ const result = await this.httpServer.sendCommand('tabgroup_move', { groupId, ...options });
251
+ return this.normalizeGroupChange(result);
252
+ }
155
253
  async reorderPage(targetId, index) {
156
254
  const tabId = this.parseTargetId(targetId);
157
255
  const result = (await this.httpServer.sendCommand('tabs_reorder', {
@@ -176,8 +274,31 @@ export class ExtensionBridge {
176
274
  }));
177
275
  return this.normalizePageChange(result);
178
276
  }
277
+ async updateWindow(windowId, options) {
278
+ const result = (await this.httpServer.sendCommand('window_update', {
279
+ windowId,
280
+ ...options,
281
+ }));
282
+ return this.normalizePageChange(result);
283
+ }
179
284
  async newWindow(options) {
180
- const result = (await this.httpServer.sendCommand('window_create', options));
285
+ const { targetId, ...properties } = options;
286
+ const tabId = targetId !== undefined ? this.parseTargetId(targetId) : undefined;
287
+ const result = (await this.httpServer
288
+ .sendCommand('window_create', {
289
+ ...properties,
290
+ ...(tabId !== undefined ? { tabId } : {}),
291
+ })
292
+ .catch((error) => {
293
+ throw creationError(error, {
294
+ action: 'window_create',
295
+ createdTargetId: null,
296
+ managed: null,
297
+ actionExecuted: 'unknown',
298
+ actionStatus: 'unknown',
299
+ failureStage: 'rpc',
300
+ });
301
+ }));
181
302
  if (result.targetId) {
182
303
  this.currentTabId = this.parseTargetId(result.targetId);
183
304
  const after = result.after;
@@ -222,9 +343,13 @@ export class ExtensionBridge {
222
343
  await this.activateTab(tabId);
223
344
  }
224
345
  /** IBrowserDriver 接口:选择操作目标 tab(不切换前台,只设置当前 currentTabId) */
225
- async selectPage(targetId) {
346
+ async selectPage(targetId, timeout) {
226
347
  const tabId = this.parseTargetId(targetId);
227
- const tabs = await this.listTabs();
348
+ const deadline = timeout === undefined ? undefined : Date.now() + timeout;
349
+ const tabs = await this.listTabs(timeout);
350
+ if (deadline !== undefined) {
351
+ remainingNavigationTimeout(deadline);
352
+ }
228
353
  const tab = tabs.find((item) => item.id === tabId);
229
354
  if (!tab) {
230
355
  throw new DriverCapabilityError(`Tab ${targetId} 不存在,请先 browse(action="list") 查看可用页面`);
@@ -236,6 +361,41 @@ export class ExtensionBridge {
236
361
  getCurrentTargetId() {
237
362
  return this.currentTabId !== null ? String(this.currentTabId) : null;
238
363
  }
364
+ async getPageSnapshot(targetId, timeout) {
365
+ const tabId = this.parseTargetId(targetId);
366
+ const deadline = timeout === undefined ? undefined : Date.now() + timeout;
367
+ try {
368
+ return (await this.httpServer.sendCommand('page_snapshot', { tabId }, timeout));
369
+ }
370
+ catch (error) {
371
+ if (error instanceof Error && error.message === 'Unknown action: page_snapshot') {
372
+ const tabs = await this.listTabs(deadline === undefined ? undefined : remainingNavigationTimeout(deadline));
373
+ if (deadline !== undefined) {
374
+ remainingNavigationTimeout(deadline);
375
+ }
376
+ const tab = tabs.find((item) => item.id === tabId);
377
+ if (!tab) {
378
+ throw new TargetNotFoundError(targetId);
379
+ }
380
+ return {
381
+ targetId,
382
+ url: tab.url,
383
+ revision: null,
384
+ warning: '当前 Extension 不支持页面 revision 或原子页面条件,仅返回当前 URL',
385
+ };
386
+ }
387
+ if (error instanceof Error &&
388
+ (error.message === `No tab with id: ${tabId}` || error.message === `No tab with id: ${tabId}.`)) {
389
+ const missing = new TargetNotFoundError(targetId);
390
+ missing.context.nativeMessage = error.message;
391
+ throw missing;
392
+ }
393
+ throw error;
394
+ }
395
+ }
396
+ setPageCondition(condition) {
397
+ this.pendingPageCondition = condition;
398
+ }
239
399
  /** IBrowserDriver 接口:设置当前操作目标 ID */
240
400
  setCurrentTargetId(targetId) {
241
401
  this.currentTabId = targetId !== null ? this.parseTargetId(targetId) : null;
@@ -244,68 +404,39 @@ export class ExtensionBridge {
244
404
  }
245
405
  }
246
406
  async navigate(url, options) {
247
- if (this.currentTabId === null) {
248
- throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
249
- }
250
- const rpcTimeout = options?.timeout !== undefined ? options.timeout + RPC_MARGIN : undefined;
251
- const params = {
407
+ const result = await this.sendBudgetedCommand('navigate', {
252
408
  tabId: this.requireCurrentTabId(),
253
409
  url,
254
410
  waitUntil: options?.wait ?? 'load',
255
- timeout: options?.timeout,
256
- };
257
- const result = await this.httpServer.sendCommand('navigate', params, rpcTimeout);
411
+ }, options?.timeout);
258
412
  const tab = result;
259
413
  this.currentTabId = tab.id;
260
414
  this.updateState(tab);
261
415
  }
262
416
  // ==================== 导航操作 ====================
263
417
  async goBack(timeout) {
264
- if (this.currentTabId === null) {
265
- throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
266
- }
267
- // 默认:NAV_SIGNAL_WINDOW + 导航等待(默认 30s)+ RPC_MARGIN = 40s
268
- // 调用方传 timeout 时:timeout 即导航超时 + 信号窗口 + 传输余量
269
- const rpcTimeout = timeout !== undefined ? timeout + NAV_SIGNAL_WINDOW + RPC_MARGIN : 30000 + NAV_SIGNAL_WINDOW + RPC_MARGIN;
270
- const params = {
418
+ const result = (await this.sendBudgetedCommand('go_back', {
271
419
  tabId: this.requireCurrentTabId(),
272
420
  waitUntil: 'load',
273
- timeout,
274
- };
275
- const result = (await this.httpServer.sendCommand('go_back', params, rpcTimeout));
421
+ }, timeout));
276
422
  this.updateState(result);
277
423
  return result;
278
424
  }
279
425
  async goForward(timeout) {
280
- if (this.currentTabId === null) {
281
- throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
282
- }
283
- // 默认:NAV_SIGNAL_WINDOW + 导航等待(默认 30s)+ RPC_MARGIN = 40s
284
- // 调用方传 timeout 时:timeout 即导航超时 + 信号窗口 + 传输余量
285
- const rpcTimeout = timeout !== undefined ? timeout + NAV_SIGNAL_WINDOW + RPC_MARGIN : 30000 + NAV_SIGNAL_WINDOW + RPC_MARGIN;
286
- const params = {
426
+ const result = (await this.sendBudgetedCommand('go_forward', {
287
427
  tabId: this.requireCurrentTabId(),
288
428
  waitUntil: 'load',
289
- timeout,
290
- };
291
- const result = (await this.httpServer.sendCommand('go_forward', params, rpcTimeout));
429
+ }, timeout));
292
430
  this.updateState(result);
293
431
  return result;
294
432
  }
295
433
  async reload(ignoreCache = false, waitUntil, timeout) {
296
- if (this.currentTabId === null) {
297
- throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
298
- }
299
- const rpcTimeout = timeout !== undefined ? timeout + RPC_MARGIN : undefined;
300
- const params = {
434
+ const result = await this.sendBudgetedCommand('reload', {
301
435
  tabId: this.requireCurrentTabId(),
302
436
  ignoreCache,
303
437
  waitUntil: waitUntil ?? 'load',
304
- timeout,
305
- };
306
- const result = await this.httpServer.sendCommand('reload', params, rpcTimeout);
307
- const tab = result;
308
- this.updateState(tab);
438
+ }, timeout);
439
+ this.updateState(result);
309
440
  }
310
441
  async readPage(options) {
311
442
  return (await this.httpServer.sendCommand('read_page', {
@@ -417,29 +548,33 @@ export class ExtensionBridge {
417
548
  throw new Error(`evaluate 结果 JSON 解析失败: ${err}`, { cause: err });
418
549
  }
419
550
  }
420
- async find(selector, text, xpath, timeout) {
551
+ async find(selector, text, xpath, timeout, point, matchIndex) {
421
552
  return (await this.httpServer.sendCommand('find', {
422
553
  tabId: this.requireCurrentTabId(),
423
554
  frameId: this.currentFrameId || undefined,
424
555
  selector,
425
556
  text,
426
557
  xpath,
558
+ point,
559
+ matchIndex,
427
560
  }, timeout));
428
561
  }
429
- async getText(selector) {
562
+ async getText(selector, refId) {
430
563
  const result = (await this.httpServer.sendCommand('get_text', {
431
564
  tabId: this.requireCurrentTabId(),
432
565
  frameId: this.currentFrameId || undefined,
433
566
  selector,
567
+ refId,
434
568
  }));
435
569
  return result.text;
436
570
  }
437
- async getHtml(selector, outer = true) {
571
+ async getHtml(selector, outer = true, refId) {
438
572
  const result = (await this.httpServer.sendCommand('get_html', {
439
573
  tabId: this.requireCurrentTabId(),
440
574
  frameId: this.currentFrameId || undefined,
441
575
  selector,
442
576
  outer,
577
+ refId,
443
578
  }));
444
579
  return result.html;
445
580
  }
@@ -469,12 +604,13 @@ export class ExtensionBridge {
469
604
  ...options,
470
605
  }));
471
606
  }
472
- async getHtmlWithImages(selector, outer = true) {
607
+ async getHtmlWithImages(selector, outer = true, refId) {
473
608
  return (await this.httpServer.sendCommand('get_html_with_images', {
474
609
  tabId: this.requireCurrentTabId(),
475
610
  frameId: this.currentFrameId || undefined,
476
611
  selector,
477
612
  outer,
613
+ refId,
478
614
  }));
479
615
  }
480
616
  async getAttribute(selector, refId, attribute) {
@@ -525,10 +661,10 @@ export class ExtensionBridge {
525
661
  params,
526
662
  }, timeout);
527
663
  }
528
- async debuggerDetach(tabId) {
529
- await this.httpServer.sendCommand('debugger_detach', {
664
+ async debuggerDetach(tabId, timeout = DEFAULT_TIMEOUT) {
665
+ await this.sendBudgetedCommand('debugger_detach', {
530
666
  tabId: tabId ?? this.requireCurrentTabId(),
531
- });
667
+ }, timeout);
532
668
  }
533
669
  async getViewportMetrics(frameId) {
534
670
  const selectedFrameId = frameId ?? this.currentFrameId;
@@ -538,12 +674,11 @@ export class ExtensionBridge {
538
674
  });
539
675
  }
540
676
  async inspectChallenge(params, timeout) {
541
- const rpcTimeout = timeout !== undefined ? timeout + RPC_MARGIN : undefined;
542
- return this.httpServer.sendCommand('challenge_inspect', {
677
+ return this.sendBudgetedCommand('challenge_inspect', {
543
678
  tabId: this.requireCurrentTabId(),
544
679
  frameId: this.currentFrameId || undefined,
545
680
  ...params,
546
- }, rpcTimeout);
681
+ }, timeout);
547
682
  }
548
683
  // ==================== Debugger (CDP via Extension) ====================
549
684
  async inputKey(type, options = {}) {
@@ -554,14 +689,14 @@ export class ExtensionBridge {
554
689
  });
555
690
  }
556
691
  // ==================== 输入事件(通过 CDP)====================
557
- async inputMouse(type, x, y, options = {}) {
558
- await this.httpServer.sendCommand('input_mouse', {
559
- tabId: this.requireCurrentTabId(),
560
- type,
561
- x,
562
- y,
563
- ...options,
564
- });
692
+ async inputMouse(type, x, y, options = {}, timeout) {
693
+ const params = { tabId: this.requireCurrentTabId(), type, x, y, ...options };
694
+ if (timeout === undefined) {
695
+ await this.httpServer.sendCommand('input_mouse', params);
696
+ }
697
+ else {
698
+ await this.sendBudgetedCommand('input_mouse', params, timeout);
699
+ }
565
700
  }
566
701
  async inputTouch(type, touchPoints) {
567
702
  await this.httpServer.sendCommand('input_touch', {
@@ -570,12 +705,8 @@ export class ExtensionBridge {
570
705
  touchPoints,
571
706
  });
572
707
  }
573
- async inputType(text, delay = 0) {
574
- await this.httpServer.sendCommand('input_type', {
575
- tabId: this.requireCurrentTabId(),
576
- text,
577
- delay,
578
- });
708
+ 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);
579
710
  }
580
711
  async consoleEnable() {
581
712
  await this.httpServer.sendCommand('console_enable', {
@@ -603,7 +734,7 @@ export class ExtensionBridge {
603
734
  }));
604
735
  return result.requests;
605
736
  }
606
- async stealthType(text, delay = 0) {
737
+ async stealthType(text, delay = 0, timeout = DEFAULT_TIMEOUT) {
607
738
  if (this.currentTabId === null) {
608
739
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
609
740
  }
@@ -612,8 +743,9 @@ export class ExtensionBridge {
612
743
  frameId: this.currentFrameId !== null ? this.currentFrameId : undefined,
613
744
  text,
614
745
  delay,
746
+ deadline: Date.now() + timeout,
615
747
  };
616
- await this.httpServer.sendCommand('stealth_type', params);
748
+ await this.httpServer.sendCommand('stealth_type', params, timeout);
617
749
  }
618
750
  // ==================== Stealth 模式(JS 事件模拟,无 debugger)====================
619
751
  async stealthKey(key, type = 'press', modifiers = []) {
@@ -629,7 +761,7 @@ export class ExtensionBridge {
629
761
  };
630
762
  await this.httpServer.sendCommand('stealth_key', params);
631
763
  }
632
- async stealthClick(x, y, button = 'left', clickCount = 1, refId) {
764
+ async stealthClick(x, y, button = 'left', clickCount = 1, refId, timeout = DEFAULT_TIMEOUT) {
633
765
  if (this.currentTabId === null) {
634
766
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
635
767
  }
@@ -644,9 +776,9 @@ export class ExtensionBridge {
644
776
  if (typeof refId === 'string') {
645
777
  params.refId = refId;
646
778
  }
647
- await this.httpServer.sendCommand('stealth_click', params);
779
+ await this.sendBudgetedCommand('stealth_click', params, timeout);
648
780
  }
649
- async stealthMouse(type, x, y, button = 'left') {
781
+ async stealthMouse(type, x, y, button = 'left', timeout) {
650
782
  if (this.currentTabId === null) {
651
783
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
652
784
  }
@@ -658,7 +790,12 @@ export class ExtensionBridge {
658
790
  y,
659
791
  button,
660
792
  };
661
- await this.httpServer.sendCommand('stealth_mouse', params);
793
+ if (timeout === undefined) {
794
+ await this.httpServer.sendCommand('stealth_mouse', params);
795
+ }
796
+ else {
797
+ await this.sendBudgetedCommand('stealth_mouse', params, timeout);
798
+ }
662
799
  }
663
800
  async stealthInject() {
664
801
  if (this.currentTabId === null) {
@@ -703,6 +840,24 @@ export class ExtensionBridge {
703
840
  frame,
704
841
  }));
705
842
  }
843
+ async sendBudgetedCommand(action, params, timeout = DEFAULT_TIMEOUT) {
844
+ const deadline = Date.now() + timeout;
845
+ const remaining = remainingNavigationTimeout(deadline);
846
+ try {
847
+ return await this.httpServer.sendCommand(action, { ...params, timeout: remaining, deadline }, remaining);
848
+ }
849
+ catch (error) {
850
+ if (error instanceof Error && error.message.startsWith(`Request timeout for action: ${action} (`)) {
851
+ throw new StructuredToolError('TIMEOUT', error.message, '请回读实际页面,勿自动重放操作', {
852
+ actionExecuted: 'unknown',
853
+ actionStatus: 'unknown',
854
+ failureStage: 'rpc',
855
+ retryable: false,
856
+ });
857
+ }
858
+ throw error;
859
+ }
860
+ }
706
861
  requireCurrentTabId() {
707
862
  if (this.currentTabId === null) {
708
863
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
@@ -717,6 +872,15 @@ export class ExtensionBridge {
717
872
  after: this.normalizeAffected(result.after),
718
873
  };
719
874
  }
875
+ normalizeGroupChange(result) {
876
+ return {
877
+ groupId: result.groupId,
878
+ before: result.before,
879
+ after: result.after,
880
+ tabsBefore: result.tabsBefore.map((tab) => this.tabToTarget(tab)),
881
+ tabsAfter: result.tabsAfter.map((tab) => this.tabToTarget(tab)),
882
+ };
883
+ }
720
884
  normalizeAffected(value) {
721
885
  if (!value) {
722
886
  return value;
@@ -730,27 +894,20 @@ export class ExtensionBridge {
730
894
  };
731
895
  }
732
896
  parseTargetId(targetId) {
733
- const parsed = parseInt(targetId, 10);
734
- if (isNaN(parsed)) {
897
+ if (!/^(0|[1-9]\d*)$/.test(targetId)) {
898
+ throw new DriverCapabilityError(`无效的 Tab ID: ${targetId}`);
899
+ }
900
+ const parsed = Number(targetId);
901
+ if (!Number.isSafeInteger(parsed)) {
735
902
  throw new DriverCapabilityError(`无效的 Tab ID: ${targetId}`);
736
903
  }
737
904
  return parsed;
738
905
  }
739
906
  tabToTarget(tab) {
740
907
  return {
741
- id: tab.id,
908
+ ...tab,
742
909
  targetId: String(tab.id),
743
- url: tab.url,
744
- title: tab.title,
745
910
  type: 'page',
746
- active: tab.active,
747
- windowId: tab.windowId,
748
- index: tab.index,
749
- groupId: tab.groupId,
750
- pinned: tab.pinned,
751
- incognito: tab.incognito,
752
- managed: tab.managed,
753
- status: tab.status,
754
911
  };
755
912
  }
756
913
  updateState(page) {