@pyrokine/mcp-chrome 2.4.4 → 3.0.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 (118) hide show
  1. package/README.md +495 -115
  2. package/README_zh.md +423 -128
  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 +105 -15
  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 +22 -4
  20. package/dist/core/errors.d.ts.map +1 -1
  21. package/dist/core/errors.js +90 -7
  22. package/dist/core/errors.js.map +1 -1
  23. package/dist/core/locator.d.ts +7 -0
  24. package/dist/core/locator.d.ts.map +1 -1
  25. package/dist/core/locator.js +54 -29
  26. package/dist/core/locator.js.map +1 -1
  27. package/dist/core/os-mouse.d.ts +15 -2
  28. package/dist/core/os-mouse.d.ts.map +1 -1
  29. package/dist/core/os-mouse.js +52 -8
  30. package/dist/core/os-mouse.js.map +1 -1
  31. package/dist/core/session.d.ts +39 -22
  32. package/dist/core/session.d.ts.map +1 -1
  33. package/dist/core/session.js +632 -153
  34. package/dist/core/session.js.map +1 -1
  35. package/dist/core/types.d.ts +2 -0
  36. package/dist/core/types.d.ts.map +1 -1
  37. package/dist/core/types.js.map +1 -1
  38. package/dist/core/unified-session.d.ts +105 -27
  39. package/dist/core/unified-session.d.ts.map +1 -1
  40. package/dist/core/unified-session.js +554 -138
  41. package/dist/core/unified-session.js.map +1 -1
  42. package/dist/core/utils.d.ts +5 -0
  43. package/dist/core/utils.d.ts.map +1 -1
  44. package/dist/core/utils.js +475 -54
  45. package/dist/core/utils.js.map +1 -1
  46. package/dist/extension/bridge.d.ts +49 -39
  47. package/dist/extension/bridge.d.ts.map +1 -1
  48. package/dist/extension/bridge.js +318 -131
  49. package/dist/extension/bridge.js.map +1 -1
  50. package/dist/extension/http-server.d.ts +3 -0
  51. package/dist/extension/http-server.d.ts.map +1 -1
  52. package/dist/extension/http-server.js +28 -2
  53. package/dist/extension/http-server.js.map +1 -1
  54. package/dist/index.js +7 -0
  55. package/dist/index.js.map +1 -1
  56. package/dist/tools/browse.d.ts.map +1 -1
  57. package/dist/tools/browse.js +248 -172
  58. package/dist/tools/browse.js.map +1 -1
  59. package/dist/tools/challenge.d.ts +1 -1
  60. package/dist/tools/challenge.d.ts.map +1 -1
  61. package/dist/tools/challenge.js +86 -51
  62. package/dist/tools/challenge.js.map +1 -1
  63. package/dist/tools/cookies.d.ts.map +1 -1
  64. package/dist/tools/cookies.js +5 -3
  65. package/dist/tools/cookies.js.map +1 -1
  66. package/dist/tools/diagnostics.d.ts +3 -3
  67. package/dist/tools/diagnostics.d.ts.map +1 -1
  68. package/dist/tools/diagnostics.js +13 -12
  69. package/dist/tools/diagnostics.js.map +1 -1
  70. package/dist/tools/evaluate.d.ts.map +1 -1
  71. package/dist/tools/evaluate.js +67 -26
  72. package/dist/tools/evaluate.js.map +1 -1
  73. package/dist/tools/extract.d.ts.map +1 -1
  74. package/dist/tools/extract.js +137 -197
  75. package/dist/tools/extract.js.map +1 -1
  76. package/dist/tools/input.d.ts +1 -1
  77. package/dist/tools/input.d.ts.map +1 -1
  78. package/dist/tools/input.js +445 -197
  79. package/dist/tools/input.js.map +1 -1
  80. package/dist/tools/logs.d.ts.map +1 -1
  81. package/dist/tools/logs.js +5 -5
  82. package/dist/tools/logs.js.map +1 -1
  83. package/dist/tools/manage.d.ts.map +1 -1
  84. package/dist/tools/manage.js +395 -86
  85. package/dist/tools/manage.js.map +1 -1
  86. package/dist/tools/page-context.d.ts +17 -0
  87. package/dist/tools/page-context.d.ts.map +1 -0
  88. package/dist/tools/page-context.js +103 -0
  89. package/dist/tools/page-context.js.map +1 -0
  90. package/dist/tools/png.d.ts +5 -0
  91. package/dist/tools/png.d.ts.map +1 -1
  92. package/dist/tools/png.js +84 -19
  93. package/dist/tools/png.js.map +1 -1
  94. package/dist/tools/post-condition.d.ts.map +1 -1
  95. package/dist/tools/post-condition.js +24 -7
  96. package/dist/tools/post-condition.js.map +1 -1
  97. package/dist/tools/schema.d.ts +9 -0
  98. package/dist/tools/schema.d.ts.map +1 -1
  99. package/dist/tools/schema.js +15 -0
  100. package/dist/tools/schema.js.map +1 -1
  101. package/dist/tools/target-diagnostics.d.ts +9 -1
  102. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  103. package/dist/tools/target-diagnostics.js +89 -33
  104. package/dist/tools/target-diagnostics.js.map +1 -1
  105. package/dist/tools/wait.d.ts.map +1 -1
  106. package/dist/tools/wait.js +38 -32
  107. package/dist/tools/wait.js.map +1 -1
  108. package/extension/dist/assets/content.ts-loader-DUWbDHRS.js +13 -0
  109. package/extension/dist/assets/content.ts-qe6IB5DK.js +13 -0
  110. package/extension/dist/assets/{index.ts-Bqcu2qiN.js → index.ts-D7_LCUoV.js} +2477 -2201
  111. package/extension/dist/assets/page-scripts-D508WLkW.js +1378 -0
  112. package/extension/dist/assets/{popup.html-B81xccfq.js → popup.html-B-eVq48O.js} +54 -5
  113. package/extension/dist/manifest.json +4 -3
  114. package/extension/dist/service-worker-loader.js +1 -1
  115. package/extension/dist/src/popup/popup.html +11 -1
  116. package/package.json +16 -8
  117. package/scripts/start-chrome.ps1 +58 -0
  118. 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,38 +95,79 @@ 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
- return {
64
- ...topology,
65
- windows: topology.windows.map((window) => ({
66
- ...window,
67
- tabs: window.tabs.map((tab) => ({
68
- ...tab,
69
- targetId: String(tab.id),
70
- type: tab.type ?? 'page',
71
- })),
105
+ const windows = topology.windows.map((window) => ({
106
+ ...window,
107
+ tabs: window.tabs.map((tab) => ({
108
+ ...tab,
109
+ targetId: String(tab.id),
110
+ type: tab.type ?? 'page',
72
111
  })),
73
- };
112
+ }));
113
+ if (Object.hasOwn(topology, 'groups') && !Array.isArray(topology.groups)) {
114
+ throw new Error('Extension tabs_topology 返回的 groups 必须是数组');
115
+ }
116
+ const groups = topology.groups?.map((group) => {
117
+ if (!group || typeof group !== 'object') {
118
+ throw new Error('Extension tabs_topology 返回了无效分组');
119
+ }
120
+ const summary = group;
121
+ if (!Object.hasOwn(summary, 'tabIds') && !Object.hasOwn(summary, 'targetIds')) {
122
+ if (!Number.isSafeInteger(summary.id) || !Number.isSafeInteger(summary.windowId)) {
123
+ throw new Error('Extension tabs_topology 的旧版分组缺少有效 id 或 windowId');
124
+ }
125
+ const members = windows
126
+ .filter((window) => window.id === summary.windowId)
127
+ .flatMap((window) => window.tabs)
128
+ .filter((tab) => tab.groupId === summary.id);
129
+ if (members.some((tab) => !Number.isSafeInteger(tab.id))) {
130
+ throw new Error('Extension tabs_topology 的分组成员包含无效 tab ID');
131
+ }
132
+ return {
133
+ ...group,
134
+ tabIds: members.map((tab) => tab.id),
135
+ targetIds: members.map((tab) => tab.targetId),
136
+ index: group.index ?? members[0]?.index,
137
+ };
138
+ }
139
+ if (!Array.isArray(group.tabIds) || !Array.isArray(group.targetIds)) {
140
+ throw new Error('Extension tabs_topology 的分组成员必须同时提供 tabIds 和 targetIds 数组');
141
+ }
142
+ return group;
143
+ });
144
+ return { ...topology, windows, ...(groups === undefined ? {} : { groups }) };
74
145
  }
75
146
  /** IBrowserDriver 接口:列出所有 tab,统一为 ListedTarget 形式(id 字符串化以保持跨 driver 兼容) */
76
- async listTargets() {
77
- const tabs = await this.listTabs();
147
+ async listTargets(timeout) {
148
+ const tabs = await this.listTabs(timeout);
78
149
  return tabs.map((tab) => this.tabToTarget(tab));
79
150
  }
80
- async createTab(url, timeout) {
81
- const rpcTimeout = timeout !== undefined ? timeout + RPC_MARGIN : undefined;
82
- const result = await this.httpServer.sendCommand('tabs_create', {
151
+ async createTab(url, timeout, options = {}) {
152
+ const rpcTimeout = (timeout ?? 30000) + RPC_MARGIN;
153
+ const result = await this.httpServer
154
+ .sendCommand('tabs_create', {
83
155
  url,
84
156
  active: false,
157
+ ...options,
85
158
  waitUntil: 'load',
86
159
  timeout,
87
- }, rpcTimeout);
160
+ }, rpcTimeout)
161
+ .catch((error) => {
162
+ throw creationError(error, {
163
+ action: 'tabs_create',
164
+ createdTargetId: null,
165
+ managed: null,
166
+ actionExecuted: 'unknown',
167
+ actionStatus: 'unknown',
168
+ failureStage: 'rpc',
169
+ });
170
+ });
88
171
  const tab = result;
89
172
  // 自动切换到新创建的 tab,后续操作立即生效
90
173
  this.currentTabId = tab.id;
@@ -92,9 +175,10 @@ export class ExtensionBridge {
92
175
  return tab;
93
176
  }
94
177
  /** IBrowserDriver 接口:新建页面(targetId 为字符串化的 chrome tab id) */
95
- async newPage(url, timeout) {
96
- const tab = await this.createTab(url, timeout);
178
+ async newPage(url, timeout, options) {
179
+ const tab = await this.createTab(url, timeout, options);
97
180
  return {
181
+ ...this.tabToTarget(tab),
98
182
  targetId: String(tab.id),
99
183
  url: tab.url,
100
184
  title: tab.title,
@@ -110,13 +194,18 @@ export class ExtensionBridge {
110
194
  }
111
195
  return this.normalizePageChange(result);
112
196
  }
113
- /** IBrowserDriver 接口:关闭页面(targetId 是 chrome tab id 的字符串形式,省略时关闭当前 tab) */
197
+ /** IBrowserDriver 接口:只能关闭明确指定的 tab */
114
198
  async closePage(targetId) {
115
- const tabId = targetId !== undefined ? this.parseTargetId(targetId) : this.currentTabId;
116
- if (tabId === null) {
117
- throw new DriverCapabilityError('没有可关闭的页面,请指定 targetId');
199
+ if (!targetId) {
200
+ throw new DriverCapabilityError('closePage 需要显式 targetId,未关闭页面');
118
201
  }
119
- return this.closeTab(tabId);
202
+ return this.closeTab(this.parseTargetId(targetId));
203
+ }
204
+ async setReadAccess(targetId, allow) {
205
+ return (await this.httpServer.sendCommand('tabs_read_access', {
206
+ tabId: this.parseTargetId(targetId),
207
+ allow,
208
+ }));
120
209
  }
121
210
  async adoptPage(targetId) {
122
211
  const tabId = this.parseTargetId(targetId);
@@ -140,6 +229,7 @@ export class ExtensionBridge {
140
229
  target: this.tabToTarget(result.tab),
141
230
  managedBefore: result.managedBefore,
142
231
  managedAfter: result.managedAfter,
232
+ ...(result.warnings?.length ? { warnings: result.warnings } : {}),
143
233
  };
144
234
  }
145
235
  async movePage(targetId, options) {
@@ -152,6 +242,43 @@ export class ExtensionBridge {
152
242
  }));
153
243
  return this.normalizePageChange(result);
154
244
  }
245
+ async updatePage(targetId, options) {
246
+ const tabId = this.parseTargetId(targetId);
247
+ const result = (await this.httpServer.sendCommand('tabs_update', {
248
+ tabId,
249
+ ...options,
250
+ }));
251
+ const after = result.after;
252
+ if (this.currentTabId === tabId && after) {
253
+ this.updateState(after);
254
+ }
255
+ return this.normalizePageChange(result);
256
+ }
257
+ async groupPages(targetIds, options) {
258
+ const tabIds = targetIds.map((id) => this.parseTargetId(id));
259
+ if (options.groupId !== undefined &&
260
+ [options.windowId, options.title, options.color, options.collapsed].some((value) => value !== undefined)) {
261
+ throw new DriverCapabilityError('加入已有分组仅接受页面列表与 groupId;修改分组请用 updateGroup/moveGroup,未执行');
262
+ }
263
+ const result = options.groupId !== undefined
264
+ ? await this.httpServer.sendCommand('tabgroup_add', { tabIds, groupId: options.groupId })
265
+ : await this.httpServer.sendCommand('tabgroup_create', { tabIds, ...options });
266
+ return this.normalizeGroupChange(result);
267
+ }
268
+ async ungroupPages(targetIds) {
269
+ const result = await this.httpServer.sendCommand('tabgroup_remove', {
270
+ tabIds: targetIds.map((id) => this.parseTargetId(id)),
271
+ });
272
+ return this.normalizeGroupChange(result);
273
+ }
274
+ async updateGroup(groupId, options) {
275
+ const result = await this.httpServer.sendCommand('tabgroup_update', { groupId, ...options });
276
+ return this.normalizeGroupChange(result);
277
+ }
278
+ async moveGroup(groupId, options) {
279
+ const result = await this.httpServer.sendCommand('tabgroup_move', { groupId, ...options });
280
+ return this.normalizeGroupChange(result);
281
+ }
155
282
  async reorderPage(targetId, index) {
156
283
  const tabId = this.parseTargetId(targetId);
157
284
  const result = (await this.httpServer.sendCommand('tabs_reorder', {
@@ -176,8 +303,31 @@ export class ExtensionBridge {
176
303
  }));
177
304
  return this.normalizePageChange(result);
178
305
  }
306
+ async updateWindow(windowId, options) {
307
+ const result = (await this.httpServer.sendCommand('window_update', {
308
+ windowId,
309
+ ...options,
310
+ }));
311
+ return this.normalizePageChange(result);
312
+ }
179
313
  async newWindow(options) {
180
- const result = (await this.httpServer.sendCommand('window_create', options));
314
+ const { targetId, ...properties } = options;
315
+ const tabId = targetId !== undefined ? this.parseTargetId(targetId) : undefined;
316
+ const result = (await this.httpServer
317
+ .sendCommand('window_create', {
318
+ ...properties,
319
+ ...(tabId !== undefined ? { tabId } : {}),
320
+ })
321
+ .catch((error) => {
322
+ throw creationError(error, {
323
+ action: 'window_create',
324
+ createdTargetId: null,
325
+ managed: null,
326
+ actionExecuted: 'unknown',
327
+ actionStatus: 'unknown',
328
+ failureStage: 'rpc',
329
+ });
330
+ }));
181
331
  if (result.targetId) {
182
332
  this.currentTabId = this.parseTargetId(result.targetId);
183
333
  const after = result.after;
@@ -197,7 +347,6 @@ export class ExtensionBridge {
197
347
  }
198
348
  return this.normalizePageChange(result);
199
349
  }
200
- // noinspection JSUnusedGlobalSymbols — UnifiedSessionManager 通过 bridge 结构类型调用
201
350
  async activatePageWithAffected(targetId) {
202
351
  const tabId = this.parseTargetId(targetId);
203
352
  const result = (await this.httpServer.sendCommand('tabs_activate_managed', {
@@ -222,9 +371,13 @@ export class ExtensionBridge {
222
371
  await this.activateTab(tabId);
223
372
  }
224
373
  /** IBrowserDriver 接口:选择操作目标 tab(不切换前台,只设置当前 currentTabId) */
225
- async selectPage(targetId) {
374
+ async selectPage(targetId, timeout) {
226
375
  const tabId = this.parseTargetId(targetId);
227
- const tabs = await this.listTabs();
376
+ const deadline = timeout === undefined ? undefined : Date.now() + timeout;
377
+ const tabs = await this.listTabs(timeout);
378
+ if (deadline !== undefined) {
379
+ remainingNavigationTimeout(deadline);
380
+ }
228
381
  const tab = tabs.find((item) => item.id === tabId);
229
382
  if (!tab) {
230
383
  throw new DriverCapabilityError(`Tab ${targetId} 不存在,请先 browse(action="list") 查看可用页面`);
@@ -236,6 +389,41 @@ export class ExtensionBridge {
236
389
  getCurrentTargetId() {
237
390
  return this.currentTabId !== null ? String(this.currentTabId) : null;
238
391
  }
392
+ async getPageSnapshot(targetId, timeout) {
393
+ const tabId = this.parseTargetId(targetId);
394
+ const deadline = timeout === undefined ? undefined : Date.now() + timeout;
395
+ try {
396
+ return (await this.httpServer.sendCommand('page_snapshot', { tabId }, timeout));
397
+ }
398
+ catch (error) {
399
+ if (error instanceof Error && error.message === 'Unknown action: page_snapshot') {
400
+ const tabs = await this.listTabs(deadline === undefined ? undefined : remainingNavigationTimeout(deadline));
401
+ if (deadline !== undefined) {
402
+ remainingNavigationTimeout(deadline);
403
+ }
404
+ const tab = tabs.find((item) => item.id === tabId);
405
+ if (!tab) {
406
+ throw new TargetNotFoundError(targetId);
407
+ }
408
+ return {
409
+ targetId,
410
+ url: tab.url,
411
+ revision: null,
412
+ warning: '当前 Extension 不支持页面 revision 或原子页面条件,仅返回当前 URL',
413
+ };
414
+ }
415
+ if (error instanceof Error &&
416
+ (error.message === `No tab with id: ${tabId}` || error.message === `No tab with id: ${tabId}.`)) {
417
+ const missing = new TargetNotFoundError(targetId);
418
+ missing.context.nativeMessage = error.message;
419
+ throw missing;
420
+ }
421
+ throw error;
422
+ }
423
+ }
424
+ setPageCondition(condition) {
425
+ this.pendingPageCondition = condition;
426
+ }
239
427
  /** IBrowserDriver 接口:设置当前操作目标 ID */
240
428
  setCurrentTargetId(targetId) {
241
429
  this.currentTabId = targetId !== null ? this.parseTargetId(targetId) : null;
@@ -244,68 +432,39 @@ export class ExtensionBridge {
244
432
  }
245
433
  }
246
434
  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 = {
435
+ const result = await this.sendBudgetedCommand('navigate', {
252
436
  tabId: this.requireCurrentTabId(),
253
437
  url,
254
438
  waitUntil: options?.wait ?? 'load',
255
- timeout: options?.timeout,
256
- };
257
- const result = await this.httpServer.sendCommand('navigate', params, rpcTimeout);
439
+ }, options?.timeout);
258
440
  const tab = result;
259
441
  this.currentTabId = tab.id;
260
442
  this.updateState(tab);
261
443
  }
262
444
  // ==================== 导航操作 ====================
263
445
  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 = {
446
+ const result = (await this.sendBudgetedCommand('go_back', {
271
447
  tabId: this.requireCurrentTabId(),
272
448
  waitUntil: 'load',
273
- timeout,
274
- };
275
- const result = (await this.httpServer.sendCommand('go_back', params, rpcTimeout));
449
+ }, timeout));
276
450
  this.updateState(result);
277
451
  return result;
278
452
  }
279
453
  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 = {
454
+ const result = (await this.sendBudgetedCommand('go_forward', {
287
455
  tabId: this.requireCurrentTabId(),
288
456
  waitUntil: 'load',
289
- timeout,
290
- };
291
- const result = (await this.httpServer.sendCommand('go_forward', params, rpcTimeout));
457
+ }, timeout));
292
458
  this.updateState(result);
293
459
  return result;
294
460
  }
295
461
  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 = {
462
+ const result = await this.sendBudgetedCommand('reload', {
301
463
  tabId: this.requireCurrentTabId(),
302
464
  ignoreCache,
303
465
  waitUntil: waitUntil ?? 'load',
304
- timeout,
305
- };
306
- const result = await this.httpServer.sendCommand('reload', params, rpcTimeout);
307
- const tab = result;
308
- this.updateState(tab);
466
+ }, timeout);
467
+ this.updateState(result);
309
468
  }
310
469
  async readPage(options) {
311
470
  return (await this.httpServer.sendCommand('read_page', {
@@ -417,29 +576,33 @@ export class ExtensionBridge {
417
576
  throw new Error(`evaluate 结果 JSON 解析失败: ${err}`, { cause: err });
418
577
  }
419
578
  }
420
- async find(selector, text, xpath, timeout) {
579
+ async find(selector, text, xpath, timeout, point, matchIndex) {
421
580
  return (await this.httpServer.sendCommand('find', {
422
581
  tabId: this.requireCurrentTabId(),
423
582
  frameId: this.currentFrameId || undefined,
424
583
  selector,
425
584
  text,
426
585
  xpath,
586
+ point,
587
+ matchIndex,
427
588
  }, timeout));
428
589
  }
429
- async getText(selector) {
590
+ async getText(selector, refId) {
430
591
  const result = (await this.httpServer.sendCommand('get_text', {
431
592
  tabId: this.requireCurrentTabId(),
432
593
  frameId: this.currentFrameId || undefined,
433
594
  selector,
595
+ refId,
434
596
  }));
435
597
  return result.text;
436
598
  }
437
- async getHtml(selector, outer = true) {
599
+ async getHtml(selector, outer = true, refId) {
438
600
  const result = (await this.httpServer.sendCommand('get_html', {
439
601
  tabId: this.requireCurrentTabId(),
440
602
  frameId: this.currentFrameId || undefined,
441
603
  selector,
442
604
  outer,
605
+ refId,
443
606
  }));
444
607
  return result.html;
445
608
  }
@@ -469,12 +632,13 @@ export class ExtensionBridge {
469
632
  ...options,
470
633
  }));
471
634
  }
472
- async getHtmlWithImages(selector, outer = true) {
635
+ async getHtmlWithImages(selector, outer = true, refId) {
473
636
  return (await this.httpServer.sendCommand('get_html_with_images', {
474
637
  tabId: this.requireCurrentTabId(),
475
638
  frameId: this.currentFrameId || undefined,
476
639
  selector,
477
640
  outer,
641
+ refId,
478
642
  }));
479
643
  }
480
644
  async getAttribute(selector, refId, attribute) {
@@ -525,10 +689,10 @@ export class ExtensionBridge {
525
689
  params,
526
690
  }, timeout);
527
691
  }
528
- async debuggerDetach(tabId) {
529
- await this.httpServer.sendCommand('debugger_detach', {
692
+ async debuggerDetach(tabId, timeout = DEFAULT_TIMEOUT) {
693
+ await this.sendBudgetedCommand('debugger_detach', {
530
694
  tabId: tabId ?? this.requireCurrentTabId(),
531
- });
695
+ }, timeout);
532
696
  }
533
697
  async getViewportMetrics(frameId) {
534
698
  const selectedFrameId = frameId ?? this.currentFrameId;
@@ -538,30 +702,29 @@ export class ExtensionBridge {
538
702
  });
539
703
  }
540
704
  async inspectChallenge(params, timeout) {
541
- const rpcTimeout = timeout !== undefined ? timeout + RPC_MARGIN : undefined;
542
- return this.httpServer.sendCommand('challenge_inspect', {
705
+ return this.sendBudgetedCommand('challenge_inspect', {
543
706
  tabId: this.requireCurrentTabId(),
544
707
  frameId: this.currentFrameId || undefined,
545
708
  ...params,
546
- }, rpcTimeout);
709
+ }, timeout);
547
710
  }
548
711
  // ==================== Debugger (CDP via Extension) ====================
549
- async inputKey(type, options = {}) {
550
- await this.httpServer.sendCommand('input_key', {
712
+ async inputKey(type, options = {}, timeout) {
713
+ await this.sendBudgetedCommand('input_key', {
551
714
  tabId: this.requireCurrentTabId(),
552
715
  type,
553
716
  ...options,
554
- });
717
+ }, timeout);
555
718
  }
556
719
  // ==================== 输入事件(通过 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
- });
720
+ async inputMouse(type, x, y, options = {}, timeout) {
721
+ const params = { tabId: this.requireCurrentTabId(), type, x, y, ...options };
722
+ if (timeout === undefined) {
723
+ await this.httpServer.sendCommand('input_mouse', params);
724
+ }
725
+ else {
726
+ await this.sendBudgetedCommand('input_mouse', params, timeout);
727
+ }
565
728
  }
566
729
  async inputTouch(type, touchPoints) {
567
730
  await this.httpServer.sendCommand('input_touch', {
@@ -570,12 +733,8 @@ export class ExtensionBridge {
570
733
  touchPoints,
571
734
  });
572
735
  }
573
- async inputType(text, delay = 0) {
574
- await this.httpServer.sendCommand('input_type', {
575
- tabId: this.requireCurrentTabId(),
576
- text,
577
- delay,
578
- });
736
+ 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);
579
738
  }
580
739
  async consoleEnable() {
581
740
  await this.httpServer.sendCommand('console_enable', {
@@ -603,7 +762,7 @@ export class ExtensionBridge {
603
762
  }));
604
763
  return result.requests;
605
764
  }
606
- async stealthType(text, delay = 0) {
765
+ async stealthType(text, delay = 0, timeout = DEFAULT_TIMEOUT) {
607
766
  if (this.currentTabId === null) {
608
767
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
609
768
  }
@@ -612,11 +771,12 @@ export class ExtensionBridge {
612
771
  frameId: this.currentFrameId !== null ? this.currentFrameId : undefined,
613
772
  text,
614
773
  delay,
774
+ deadline: Date.now() + timeout,
615
775
  };
616
- await this.httpServer.sendCommand('stealth_type', params);
776
+ await this.httpServer.sendCommand('stealth_type', params, timeout);
617
777
  }
618
778
  // ==================== Stealth 模式(JS 事件模拟,无 debugger)====================
619
- async stealthKey(key, type = 'press', modifiers = []) {
779
+ async stealthKey(key, type = 'press', modifiers = [], timeout) {
620
780
  if (this.currentTabId === null) {
621
781
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
622
782
  }
@@ -627,9 +787,9 @@ export class ExtensionBridge {
627
787
  type,
628
788
  modifiers,
629
789
  };
630
- await this.httpServer.sendCommand('stealth_key', params);
790
+ await this.sendBudgetedCommand('stealth_key', params, timeout);
631
791
  }
632
- async stealthClick(x, y, button = 'left', clickCount = 1, refId) {
792
+ async stealthClick(x, y, button = 'left', clickCount = 1, refId, timeout = DEFAULT_TIMEOUT) {
633
793
  if (this.currentTabId === null) {
634
794
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
635
795
  }
@@ -644,9 +804,9 @@ export class ExtensionBridge {
644
804
  if (typeof refId === 'string') {
645
805
  params.refId = refId;
646
806
  }
647
- await this.httpServer.sendCommand('stealth_click', params);
807
+ await this.sendBudgetedCommand('stealth_click', params, timeout);
648
808
  }
649
- async stealthMouse(type, x, y, button = 'left') {
809
+ async stealthMouse(type, x, y, button = 'left', timeout) {
650
810
  if (this.currentTabId === null) {
651
811
  throw new DriverCapabilityError('没有当前页面,请先 browse attach 或先 browse open 创建受控页面');
652
812
  }
@@ -658,7 +818,12 @@ export class ExtensionBridge {
658
818
  y,
659
819
  button,
660
820
  };
661
- await this.httpServer.sendCommand('stealth_mouse', params);
821
+ if (timeout === undefined) {
822
+ await this.httpServer.sendCommand('stealth_mouse', params);
823
+ }
824
+ else {
825
+ await this.sendBudgetedCommand('stealth_mouse', params, timeout);
826
+ }
662
827
  }
663
828
  async stealthInject() {
664
829
  if (this.currentTabId === null) {
@@ -697,11 +862,31 @@ export class ExtensionBridge {
697
862
  /**
698
863
  * 解析 iframe 选择器/索引 → frameId
699
864
  */
700
- async resolveFrame(frame) {
701
- return (await this.httpServer.sendCommand('resolve_frame', {
865
+ async resolveFrame(frame, timeout) {
866
+ return (await this.sendBudgetedCommand('resolve_frame', {
702
867
  tabId: this.requireCurrentTabId(),
703
868
  frame,
704
- }));
869
+ }, timeout));
870
+ }
871
+ async sendBudgetedCommand(action, params, timeout = DEFAULT_TIMEOUT) {
872
+ const deadline = Date.now() + timeout;
873
+ const remaining = remainingNavigationTimeout(deadline);
874
+ try {
875
+ const result = await this.httpServer.sendCommand(action, { ...params, timeout: remaining, deadline }, remaining);
876
+ remainingNavigationTimeout(deadline);
877
+ return result;
878
+ }
879
+ catch (error) {
880
+ if (error instanceof Error && error.message.startsWith(`Request timeout for action: ${action} (`)) {
881
+ throw new StructuredToolError('TIMEOUT', error.message, '请回读实际页面,勿自动重放操作', {
882
+ actionExecuted: 'unknown',
883
+ actionStatus: 'unknown',
884
+ failureStage: 'rpc',
885
+ retryable: false,
886
+ });
887
+ }
888
+ throw error;
889
+ }
705
890
  }
706
891
  requireCurrentTabId() {
707
892
  if (this.currentTabId === null) {
@@ -717,6 +902,15 @@ export class ExtensionBridge {
717
902
  after: this.normalizeAffected(result.after),
718
903
  };
719
904
  }
905
+ normalizeGroupChange(result) {
906
+ return {
907
+ groupId: result.groupId,
908
+ before: result.before,
909
+ after: result.after,
910
+ tabsBefore: result.tabsBefore.map((tab) => this.tabToTarget(tab)),
911
+ tabsAfter: result.tabsAfter.map((tab) => this.tabToTarget(tab)),
912
+ };
913
+ }
720
914
  normalizeAffected(value) {
721
915
  if (!value) {
722
916
  return value;
@@ -730,27 +924,20 @@ export class ExtensionBridge {
730
924
  };
731
925
  }
732
926
  parseTargetId(targetId) {
733
- const parsed = parseInt(targetId, 10);
734
- if (isNaN(parsed)) {
927
+ if (!/^(0|[1-9]\d*)$/.test(targetId)) {
928
+ throw new DriverCapabilityError(`无效的 Tab ID: ${targetId}`);
929
+ }
930
+ const parsed = Number(targetId);
931
+ if (!Number.isSafeInteger(parsed)) {
735
932
  throw new DriverCapabilityError(`无效的 Tab ID: ${targetId}`);
736
933
  }
737
934
  return parsed;
738
935
  }
739
936
  tabToTarget(tab) {
740
937
  return {
741
- id: tab.id,
938
+ ...tab,
742
939
  targetId: String(tab.id),
743
- url: tab.url,
744
- title: tab.title,
745
940
  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
941
  };
755
942
  }
756
943
  updateState(page) {