@pyrokine/mcp-chrome 2.4.1 → 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 (141) hide show
  1. package/README.md +546 -192
  2. package/README_zh.md +490 -192
  3. package/dist/anti-detection/behavior.js +1 -1
  4. package/dist/anti-detection/behavior.js.map +1 -1
  5. package/dist/anti-detection/injection.d.ts.map +1 -1
  6. package/dist/anti-detection/injection.js +5 -4
  7. package/dist/anti-detection/injection.js.map +1 -1
  8. package/dist/cdp/client.d.ts +2 -2
  9. package/dist/cdp/client.d.ts.map +1 -1
  10. package/dist/cdp/client.js +24 -10
  11. package/dist/cdp/client.js.map +1 -1
  12. package/dist/cdp/launcher.d.ts +2 -3
  13. package/dist/cdp/launcher.d.ts.map +1 -1
  14. package/dist/cdp/launcher.js +84 -24
  15. package/dist/cdp/launcher.js.map +1 -1
  16. package/dist/core/auto-wait.d.ts +3 -3
  17. package/dist/core/auto-wait.d.ts.map +1 -1
  18. package/dist/core/auto-wait.js +45 -20
  19. package/dist/core/auto-wait.js.map +1 -1
  20. package/dist/core/browser-driver.d.ts +104 -14
  21. package/dist/core/browser-driver.d.ts.map +1 -1
  22. package/dist/core/browser-driver.js +1 -0
  23. package/dist/core/browser-driver.js.map +1 -1
  24. package/dist/core/errors.d.ts +25 -0
  25. package/dist/core/errors.d.ts.map +1 -1
  26. package/dist/core/errors.js +93 -1
  27. package/dist/core/errors.js.map +1 -1
  28. package/dist/core/locator.d.ts.map +1 -1
  29. package/dist/core/locator.js +6 -4
  30. package/dist/core/locator.js.map +1 -1
  31. package/dist/core/os-mouse.d.ts +78 -0
  32. package/dist/core/os-mouse.d.ts.map +1 -0
  33. package/dist/core/os-mouse.js +378 -0
  34. package/dist/core/os-mouse.js.map +1 -0
  35. package/dist/core/session.d.ts +46 -21
  36. package/dist/core/session.d.ts.map +1 -1
  37. package/dist/core/session.js +724 -175
  38. package/dist/core/session.js.map +1 -1
  39. package/dist/core/types.d.ts +12 -0
  40. package/dist/core/types.d.ts.map +1 -1
  41. package/dist/core/types.js +2 -0
  42. package/dist/core/types.js.map +1 -1
  43. package/dist/core/unified-session.d.ts +117 -21
  44. package/dist/core/unified-session.d.ts.map +1 -1
  45. package/dist/core/unified-session.js +619 -129
  46. package/dist/core/unified-session.js.map +1 -1
  47. package/dist/core/utils.d.ts +5 -0
  48. package/dist/core/utils.d.ts.map +1 -1
  49. package/dist/core/utils.js +475 -54
  50. package/dist/core/utils.js.map +1 -1
  51. package/dist/extension/bridge.d.ts +61 -35
  52. package/dist/extension/bridge.d.ts.map +1 -1
  53. package/dist/extension/bridge.js +290 -106
  54. package/dist/extension/bridge.js.map +1 -1
  55. package/dist/extension/http-server.d.ts +3 -0
  56. package/dist/extension/http-server.d.ts.map +1 -1
  57. package/dist/extension/http-server.js +25 -3
  58. package/dist/extension/http-server.js.map +1 -1
  59. package/dist/index.js +7 -0
  60. package/dist/index.js.map +1 -1
  61. package/dist/tools/browse.d.ts +1 -1
  62. package/dist/tools/browse.d.ts.map +1 -1
  63. package/dist/tools/browse.js +291 -175
  64. package/dist/tools/browse.js.map +1 -1
  65. package/dist/tools/challenge.d.ts +153 -0
  66. package/dist/tools/challenge.d.ts.map +1 -0
  67. package/dist/tools/challenge.js +611 -0
  68. package/dist/tools/challenge.js.map +1 -0
  69. package/dist/tools/cookies.d.ts.map +1 -1
  70. package/dist/tools/cookies.js +13 -7
  71. package/dist/tools/cookies.js.map +1 -1
  72. package/dist/tools/diagnostics.d.ts +5 -5
  73. package/dist/tools/diagnostics.d.ts.map +1 -1
  74. package/dist/tools/diagnostics.js +39 -20
  75. package/dist/tools/diagnostics.js.map +1 -1
  76. package/dist/tools/evaluate.d.ts.map +1 -1
  77. package/dist/tools/evaluate.js +106 -23
  78. package/dist/tools/evaluate.js.map +1 -1
  79. package/dist/tools/extract.d.ts.map +1 -1
  80. package/dist/tools/extract.js +199 -208
  81. package/dist/tools/extract.js.map +1 -1
  82. package/dist/tools/input.d.ts +1 -1
  83. package/dist/tools/input.d.ts.map +1 -1
  84. package/dist/tools/input.js +523 -175
  85. package/dist/tools/input.js.map +1 -1
  86. package/dist/tools/logs.d.ts.map +1 -1
  87. package/dist/tools/logs.js +7 -7
  88. package/dist/tools/logs.js.map +1 -1
  89. package/dist/tools/manage.d.ts.map +1 -1
  90. package/dist/tools/manage.js +400 -64
  91. package/dist/tools/manage.js.map +1 -1
  92. package/dist/tools/network-sanitizer.d.ts.map +1 -1
  93. package/dist/tools/network-sanitizer.js +1 -0
  94. package/dist/tools/network-sanitizer.js.map +1 -1
  95. package/dist/tools/page-context.d.ts +17 -0
  96. package/dist/tools/page-context.d.ts.map +1 -0
  97. package/dist/tools/page-context.js +103 -0
  98. package/dist/tools/page-context.js.map +1 -0
  99. package/dist/tools/png.d.ts +5 -0
  100. package/dist/tools/png.d.ts.map +1 -1
  101. package/dist/tools/png.js +89 -22
  102. package/dist/tools/png.js.map +1 -1
  103. package/dist/tools/post-condition.d.ts.map +1 -1
  104. package/dist/tools/post-condition.js +17 -5
  105. package/dist/tools/post-condition.js.map +1 -1
  106. package/dist/tools/schema.d.ts +9 -0
  107. package/dist/tools/schema.d.ts.map +1 -1
  108. package/dist/tools/schema.js +15 -0
  109. package/dist/tools/schema.js.map +1 -1
  110. package/dist/tools/target-diagnostics.d.ts +7 -0
  111. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  112. package/dist/tools/target-diagnostics.js +47 -17
  113. package/dist/tools/target-diagnostics.js.map +1 -1
  114. package/dist/tools/wait.d.ts.map +1 -1
  115. package/dist/tools/wait.js +52 -56
  116. package/dist/tools/wait.js.map +1 -1
  117. package/extension/dist/assets/content.ts-C4imZ6A9.js +13 -0
  118. package/extension/dist/assets/content.ts-loader-CnJuCGhl.js +13 -0
  119. package/extension/dist/assets/{index.ts-GG6dPUPX.js → index.ts-GeHNZBml.js} +2156 -1950
  120. package/extension/dist/assets/page-scripts-CMIY1zhd.js +1379 -0
  121. package/extension/dist/assets/{popup.html-B81xccfq.js → popup.html-CgtWL6Py.js} +48 -1
  122. package/extension/dist/manifest.json +4 -3
  123. package/extension/dist/service-worker-loader.js +1 -1
  124. package/extension/dist/src/popup/popup.html +54 -44
  125. package/package.json +11 -8
  126. package/scripts/start-chrome.ps1 +58 -0
  127. package/dist/extension/native-host-installer.d.ts +0 -21
  128. package/dist/extension/native-host-installer.d.ts.map +0 -1
  129. package/dist/extension/native-host-installer.js +0 -147
  130. package/dist/extension/native-host-installer.js.map +0 -1
  131. package/dist/extension/socket-server.d.ts +0 -32
  132. package/dist/extension/socket-server.d.ts.map +0 -1
  133. package/dist/extension/socket-server.js +0 -177
  134. package/dist/extension/socket-server.js.map +0 -1
  135. package/dist/extension/ws-server.d.ts +0 -40
  136. package/dist/extension/ws-server.d.ts.map +0 -1
  137. package/dist/extension/ws-server.js +0 -246
  138. package/dist/extension/ws-server.js.map +0 -1
  139. package/dist/native-host/index.js +0 -280
  140. package/dist/native-host/mcp-chrome-host +0 -2
  141. package/extension/dist/assets/content.ts-Cj_iiU2s.js +0 -25
@@ -9,16 +9,23 @@
9
9
  * - open: 打开 URL
10
10
  * - back/forward: 前进后退
11
11
  * - refresh: 刷新
12
- * - close: 关闭浏览器
12
+ * - close: 关闭指定页面
13
13
  */
14
14
  import { z } from 'zod';
15
15
  import { formatErrorResponse, formatResponse, getSession, getUnifiedSession } from '../core/index.js';
16
+ import { StructuredToolError } from '../core/errors.js';
16
17
  import { DEFAULT_TIMEOUT } from '../core/types.js';
18
+ import { remainingNavigationTimeout } from '../core/utils.js';
19
+ import { challengeResultFields, resolveChallenge } from './challenge.js';
17
20
  import { withDiagnosticsResponse } from './diagnostics.js';
21
+ import { withPageContext, withPageResponse } from './page-context.js';
22
+ import { pageConditionSchema } from './schema.js';
18
23
  /**
19
24
  * browse 参数 schema
20
25
  */
21
26
  const browseSchema = z.object({
27
+ expectedUrl: pageConditionSchema.expectedUrl.describe('动作执行前要求页面 URL 与此值一致;仅 open/back/forward/refresh/close 支持,不一致时不执行'),
28
+ expectedRevision: pageConditionSchema.expectedRevision.describe('动作执行前要求页面 revision 与此值一致;从 browse list 获取,仅 open/back/forward/refresh/close 支持'),
22
29
  action: z
23
30
  .enum(['launch', 'connect', 'list', 'attach', 'open', 'back', 'forward', 'refresh', 'close'])
24
31
  .describe('操作类型'),
@@ -30,83 +37,108 @@ const browseSchema = z.object({
30
37
  .enum(['off', 'safe', 'aggressive'])
31
38
  .optional()
32
39
  .describe('反检测模式(launch/connect),off=关闭,safe=最小改动(默认),aggressive=完整伪装'),
33
- port: z.coerce.number().optional().describe('调试端口(launch/connect),launch 时不指定则使用随机端口'),
40
+ port: z.coerce
41
+ .number()
42
+ .optional()
43
+ .describe('CDP 调试端口。只在 browse(action="connect") 中显式指定时选择 CDP;其他场景优先使用已连接的 Extension'),
34
44
  host: z.string().optional().describe('调试主机(connect)'),
35
45
  targetId: z
36
46
  .string()
37
47
  .optional()
38
- .describe('目标 ID(attach/close),从 list 结果中获取,Extension 模式为数字 Tab ID,CDP 模式为 WebSocket target ID,仅在当前 mode 下有效'),
48
+ .describe('目标 ID(attach/close),从 list 结果中获取。close 必填,只关闭该页面。' +
49
+ 'Extension 模式为数字 Tab ID,CDP 模式为 WebSocket target ID,仅在当前 mode 下有效'),
50
+ details: z
51
+ .enum(['summary', 'full'])
52
+ .optional()
53
+ .describe('list 默认摘要;full 返回完整原生属性,窗口仅以 targetIds 引用页面'),
54
+ targetIds: z.array(z.string().min(1)).min(1).optional().describe('list 仅返回这些页面及其窗口/分组关系'),
55
+ managedOnly: z.boolean().optional().describe('list 仅返回 managed=true 的页面,默认 false'),
39
56
  activate: z.boolean().optional().describe('是否激活 Tab(attach),默认 false 只设置操作目标不切到前台'),
40
57
  url: z.string().optional().describe('目标 URL(open)'),
41
58
  wait: z.enum(['load', 'domcontentloaded', 'networkidle']).optional().describe('等待条件(open/refresh)'),
42
59
  ignoreCache: z.boolean().optional().describe('刷新时是否忽略缓存(refresh)'),
43
- timeout: z.coerce.number().optional().describe('超时毫秒'),
44
- diagnostics: z.boolean().optional().describe('open 后返回新增 console error/warning 和失败网络请求摘要'),
60
+ timeout: z.coerce
61
+ .number()
62
+ .optional()
63
+ .describe('超时毫秒,open/back/forward/refresh 含页面加载和 Cloudflare Challenge 等待'),
64
+ diagnostics: z
65
+ .boolean()
66
+ .optional()
67
+ .describe('open 后返回新增 console error/warning 和失败网络请求摘要。访问 Cloudflare 页面时默认不传;开启后会启用 debugger 日志采集'),
45
68
  });
46
69
  /**
47
70
  * browse 工具处理器
48
71
  */
49
- function pageStateMetadata(unifiedSession, background) {
72
+ function pageStateMetadata(unifiedSession) {
50
73
  const state = unifiedSession.getState();
51
74
  return {
52
75
  url: state?.url,
53
76
  title: state?.title,
54
77
  managed: state?.managed ?? false,
55
- background,
56
78
  };
57
79
  }
58
80
  async function handleBrowse(args) {
59
81
  try {
82
+ const deadline = Date.now() + (args.timeout ?? DEFAULT_TIMEOUT);
60
83
  const unifiedSession = getUnifiedSession();
61
84
  const cdpSession = getSession();
62
85
  // 优先使用 Extension 模式(如果启用了,即使当前断开也使用,会自动等待重连)
63
86
  const useExtension = unifiedSession.isExtensionModeEnabled();
87
+ const conditional = args.expectedUrl !== undefined || args.expectedRevision !== undefined;
88
+ if (conditional && !['open', 'back', 'forward', 'refresh', 'close'].includes(args.action)) {
89
+ throw new StructuredToolError('INVALID_ARGUMENT', `${args.action} 不支持页面动作条件,未执行`, '仅 open/back/forward/refresh/close 接受 expectedUrl 和 expectedRevision', { action: args.action, actionExecuted: false });
90
+ }
64
91
  switch (args.action) {
65
92
  case 'launch': {
66
- // Extension 模式:直接创建新 Tab
67
- if (useExtension) {
93
+ return await withPageResponse(unifiedSession, undefined, async () => {
94
+ // Extension 模式:直接创建新 Tab
95
+ if (useExtension) {
96
+ const target = await unifiedSession.launch({
97
+ port: args.port,
98
+ executablePath: args.executablePath,
99
+ headless: args.headless,
100
+ userDataDir: args.userDataDir,
101
+ incognito: args.incognito,
102
+ timeout: args.timeout,
103
+ stealth: args.stealth,
104
+ });
105
+ return formatResponse({
106
+ success: true,
107
+ action: 'launch',
108
+ mode: target.mode,
109
+ note: target.mode === 'extension'
110
+ ? 'Extension 模式:使用用户浏览器,共享登录状态'
111
+ : '已启动新浏览器(Extension 未连接,fallback 到 CDP 模式)',
112
+ target,
113
+ createdTargetId: target.mode === 'extension' || target.targetCreated === true || !target.reused
114
+ ? target.targetId
115
+ : null,
116
+ });
117
+ }
118
+ // CDP 模式:启动新浏览器
68
119
  const target = await unifiedSession.launch({
69
- port: args.port,
70
120
  executablePath: args.executablePath,
71
- headless: args.headless,
121
+ port: args.port ?? 0,
122
+ incognito: args.incognito ?? false,
123
+ headless: args.headless ?? false,
72
124
  userDataDir: args.userDataDir,
73
- incognito: args.incognito,
74
- timeout: args.timeout,
125
+ timeout: args.timeout ?? DEFAULT_TIMEOUT,
75
126
  stealth: args.stealth,
76
127
  });
128
+ const reused = target.reused ?? false;
77
129
  return formatResponse({
78
130
  success: true,
79
131
  action: 'launch',
80
- mode: target.mode,
81
- note: target.mode === 'extension'
82
- ? 'Extension 模式:使用用户浏览器,共享登录状态'
83
- : '已启动新浏览器(Extension 未连接,fallback 到 CDP 模式)',
132
+ mode: 'cdp',
133
+ port: cdpSession.port,
134
+ reused,
135
+ note: reused
136
+ ? '已复用运行中的浏览器,保留登录状态'
137
+ : '已启动新浏览器,登录状态保存在 ~/.mcp-chrome/profile',
84
138
  target,
139
+ createdTargetId: (target.targetCreated ?? !reused) ? target.targetId : null,
85
140
  });
86
- }
87
- // CDP 模式:启动新浏览器
88
- const target = await cdpSession.launch({
89
- executablePath: args.executablePath,
90
- port: args.port ?? 0,
91
- incognito: args.incognito ?? false,
92
- headless: args.headless ?? false,
93
- userDataDir: args.userDataDir,
94
- timeout: args.timeout ?? DEFAULT_TIMEOUT,
95
- stealth: args.stealth,
96
- });
97
- unifiedSession.setActiveMode('cdp');
98
- const reused = target.reused ?? false;
99
- return formatResponse({
100
- success: true,
101
- action: 'launch',
102
- mode: 'cdp',
103
- port: cdpSession.port,
104
- reused,
105
- note: reused
106
- ? '已复用运行中的浏览器,保留登录状态'
107
- : '已启动新浏览器,登录状态保存在 ~/.mcp-chrome/profile',
108
- target,
109
- });
141
+ }, true);
110
142
  }
111
143
  case 'connect': {
112
144
  // 显式传 port 时走 CDP 连接(即使 Extension 服务器已启动)
@@ -143,54 +175,117 @@ async function handleBrowse(args) {
143
175
  isError: true,
144
176
  };
145
177
  }
146
- const target = await cdpSession.connect({
147
- host: args.host ?? '127.0.0.1',
148
- port: args.port,
149
- timeout: args.timeout ?? DEFAULT_TIMEOUT,
150
- stealth: args.stealth,
151
- });
152
- unifiedSession.setActiveMode('cdp');
153
- return formatResponse({
154
- success: true,
155
- action: 'connect',
156
- mode: 'cdp',
157
- port: args.port,
158
- target,
159
- });
178
+ const port = args.port;
179
+ return await withPageResponse(unifiedSession, undefined, async () => {
180
+ const target = await cdpSession.connect({
181
+ host: args.host ?? '127.0.0.1',
182
+ port,
183
+ timeout: args.timeout ?? DEFAULT_TIMEOUT,
184
+ stealth: args.stealth,
185
+ });
186
+ unifiedSession.setActiveMode('cdp', true);
187
+ return formatResponse({
188
+ success: true,
189
+ action: 'connect',
190
+ mode: 'cdp',
191
+ port: args.port,
192
+ target,
193
+ createdTargetId: null,
194
+ });
195
+ }, true);
160
196
  }
161
197
  case 'list': {
162
198
  const mode = unifiedSession.getMode();
163
- const targets = await unifiedSession.listTargets();
164
199
  const topology = await unifiedSession.listTopology();
165
- const windows = topology?.windows.map((window) => ({
166
- ...window,
167
- tabs: window.tabs.map((tab) => ({
168
- targetId: tab.targetId ?? String(tab.id),
200
+ const allTargets = topology
201
+ ? topology.windows.flatMap((window) => window.tabs.map(({ id, ...tab }) => ({
202
+ ...tab,
203
+ targetId: tab.targetId ?? String(id),
169
204
  type: tab.type ?? 'page',
205
+ mode,
206
+ isActive: tab.active ?? false,
207
+ metadata: unifiedSession.getPageMetadata(tab.targetId ?? String(id)),
208
+ })))
209
+ : await unifiedSession.listTargets();
210
+ const requestedIds = args.targetIds ? new Set(args.targetIds) : null;
211
+ const filtered = requestedIds !== null || args.managedOnly === true;
212
+ const selected = allTargets.filter((tab) => (!requestedIds || requestedIds.has(tab.targetId)) && (!args.managedOnly || tab.managed === true));
213
+ const selectedIds = new Set(selected.map((tab) => tab.targetId));
214
+ const detail = args.details ?? 'summary';
215
+ const targets = selected.map((tab) => {
216
+ const { favIconUrl, ...native } = tab;
217
+ const favicon = favIconUrl?.startsWith('data:')
218
+ ? { favIconInline: true }
219
+ : favIconUrl !== undefined
220
+ ? { favIconUrl }
221
+ : {};
222
+ if (detail === 'full')
223
+ return { ...native, ...favicon };
224
+ return {
225
+ targetId: tab.targetId,
226
+ type: tab.type,
170
227
  url: tab.url,
171
228
  title: tab.title,
172
229
  mode,
173
- isActive: tab.active ?? false,
174
- managed: tab.managed,
230
+ managed: tab.managed ?? false,
231
+ revision: tab.revision,
232
+ status: tab.status,
233
+ isActive: tab.isActive ?? false,
175
234
  windowId: tab.windowId,
176
235
  index: tab.index,
177
236
  groupId: tab.groupId,
178
237
  pinned: tab.pinned,
179
238
  incognito: tab.incognito,
180
- status: tab.status,
181
- })),
239
+ metadata: tab.metadata,
240
+ };
241
+ });
242
+ const windows = topology?.windows
243
+ .filter((window) => !filtered || window.tabs.some((tab) => selectedIds.has(tab.targetId ?? String(tab.id))))
244
+ .map(({ tabs, ...window }) => {
245
+ const targetIds = tabs
246
+ .map((tab) => tab.targetId ?? String(tab.id))
247
+ .filter((id) => selectedIds.has(id));
248
+ return {
249
+ ...(detail === 'full'
250
+ ? window
251
+ : {
252
+ id: window.id,
253
+ focused: window.focused,
254
+ type: window.type,
255
+ state: window.state,
256
+ incognito: window.incognito,
257
+ activeTabId: window.activeTabId,
258
+ }),
259
+ tabCount: targetIds.length,
260
+ totalTabCount: window.tabCount,
261
+ targetIds,
262
+ };
263
+ });
264
+ const groups = topology?.groups
265
+ .filter((group) => !filtered || group.targetIds.some((id) => selectedIds.has(id)))
266
+ .map((group) => ({
267
+ ...group,
268
+ targetIds: group.targetIds.filter((id) => selectedIds.has(id)),
269
+ tabIds: group.tabIds.filter((id) => selectedIds.has(String(id))),
270
+ totalTabCount: group.targetIds.length,
182
271
  }));
183
272
  const result = {
184
273
  success: true,
185
274
  action: 'list',
186
275
  mode,
276
+ details: detail,
277
+ targetCount: targets.length,
278
+ totalTargetCount: allTargets.length,
187
279
  targets,
280
+ defaultTargetId: unifiedSession.getCurrentTargetId(),
188
281
  ...(topology
189
282
  ? {
190
- windowCount: topology.windowCount,
283
+ windowCount: windows.length,
284
+ totalWindowCount: topology.windowCount,
191
285
  focusedWindowId: topology.focusedWindowId,
192
286
  activeTargetId: topology.activeTargetId,
193
287
  windows,
288
+ groups,
194
289
  }
195
290
  : {}),
196
291
  };
@@ -218,157 +313,169 @@ async function handleBrowse(args) {
218
313
  isError: true,
219
314
  };
220
315
  }
221
- if (args.activate) {
222
- // 激活 Tab(切到前台)
223
- await unifiedSession.activatePage(args.targetId);
224
- }
225
- else {
226
- // 只设置操作目标,不激活(不切到前台)
227
- await unifiedSession.selectPage(args.targetId);
228
- }
229
- return formatResponse({
230
- success: true,
231
- action: 'attach',
232
- mode: unifiedSession.getMode(),
233
- targetId: args.targetId,
234
- activated: args.activate ?? false,
235
- ...pageStateMetadata(unifiedSession, !(args.activate ?? false)),
316
+ return await withPageResponse(unifiedSession, args.targetId, async () => {
317
+ if (args.activate) {
318
+ await unifiedSession.activatePage(args.targetId);
319
+ }
320
+ else {
321
+ await unifiedSession.selectPage(args.targetId);
322
+ }
323
+ return formatResponse({
324
+ success: true,
325
+ action: 'attach',
326
+ mode: unifiedSession.getMode(),
327
+ targetId: args.targetId,
328
+ activated: args.activate ?? false,
329
+ ...pageStateMetadata(unifiedSession),
330
+ });
236
331
  });
237
332
  }
238
333
  case 'open': {
239
- if (!args.url) {
240
- return {
241
- content: [
242
- {
243
- type: 'text',
244
- text: JSON.stringify({
245
- error: {
246
- code: 'INVALID_ARGUMENT',
247
- message: '缺少 url 参数',
248
- suggestion: '请指定 url 参数',
249
- },
250
- }),
251
- },
252
- ],
253
- isError: true,
254
- };
255
- }
256
- const currentState = unifiedSession.getState();
257
- if (unifiedSession.getMode() === 'extension' &&
258
- currentState !== null &&
259
- currentState.managed !== true) {
260
- return {
261
- content: [
262
- {
263
- type: 'text',
264
- text: JSON.stringify({
265
- error: {
266
- code: 'UNMANAGED_TAB',
267
- message: 'open 拒绝导航非托管 tab',
268
- suggestion: '请使用 browse(action="list") 选择 managed=true 的受控 tab,或用 manage(action="newPage") 创建受控页面',
269
- context: {
270
- managed: currentState.managed ?? false,
271
- url: currentState.url,
272
- title: currentState.title,
334
+ return await withPageContext(unifiedSession, args.targetId, async () => {
335
+ if (!args.url) {
336
+ return {
337
+ content: [
338
+ {
339
+ type: 'text',
340
+ text: JSON.stringify({
341
+ error: {
342
+ code: 'INVALID_ARGUMENT',
343
+ message: '缺少 url 参数',
344
+ suggestion: '请指定 url 参数',
273
345
  },
274
- },
275
- }, null, 2),
276
- },
277
- ],
278
- isError: true,
279
- };
280
- }
281
- if (currentState === null) {
282
- await unifiedSession.newPage();
283
- }
284
- return withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
285
- await unifiedSession.navigate(args.url, {
286
- wait: args.wait,
287
- timeout: args.timeout ?? DEFAULT_TIMEOUT,
288
- });
289
- return {
290
- success: true,
291
- action: 'open',
292
- mode: unifiedSession.getMode(),
293
- ...pageStateMetadata(unifiedSession, true),
294
- };
295
- });
346
+ }),
347
+ },
348
+ ],
349
+ isError: true,
350
+ };
351
+ }
352
+ const currentState = unifiedSession.getState();
353
+ if (unifiedSession.getMode() === 'extension' &&
354
+ currentState !== null &&
355
+ currentState.managed !== true) {
356
+ return {
357
+ content: [
358
+ {
359
+ type: 'text',
360
+ text: JSON.stringify({
361
+ error: {
362
+ code: 'UNMANAGED_TAB',
363
+ message: 'open 拒绝导航非托管 tab',
364
+ suggestion: '请从 browse(action="list") 选择 managed=true 的 tab,' +
365
+ '或用 manage(action="newPage") 创建受控页面',
366
+ context: {
367
+ managed: currentState.managed ?? false,
368
+ url: currentState.url,
369
+ title: currentState.title,
370
+ },
371
+ },
372
+ }, null, 2),
373
+ },
374
+ ],
375
+ isError: true,
376
+ };
377
+ }
378
+ if (currentState === null) {
379
+ if (conditional) {
380
+ throw new Error('没有操作目标,未执行条件导航');
381
+ }
382
+ await unifiedSession.newPage(undefined, undefined, remainingNavigationTimeout(deadline));
383
+ }
384
+ return unifiedSession.withPageCondition(args, () => withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
385
+ await unifiedSession.navigate(args.url, {
386
+ wait: args.wait,
387
+ timeout: remainingNavigationTimeout(deadline),
388
+ });
389
+ const challenge = await resolveChallenge(unifiedSession, 'open', 'completed', Math.max(0, deadline - Date.now()));
390
+ return {
391
+ success: true,
392
+ action: 'open',
393
+ mode: unifiedSession.getMode(),
394
+ ...pageStateMetadata(unifiedSession),
395
+ ...challengeResultFields(challenge),
396
+ };
397
+ }, deadline), deadline);
398
+ }, deadline);
296
399
  }
297
400
  case 'back': {
298
- return withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
299
- const result = await unifiedSession.goBack(args.timeout);
401
+ return await withPageContext(unifiedSession, args.targetId, () => unifiedSession.withPageCondition(args, () => withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
402
+ const result = await unifiedSession.goBack(remainingNavigationTimeout(deadline));
403
+ const challenge = result.navigated
404
+ ? await resolveChallenge(unifiedSession, 'back', 'completed', Math.max(0, deadline - Date.now()))
405
+ : undefined;
300
406
  return {
301
407
  success: true,
302
408
  action: 'back',
303
409
  mode: unifiedSession.getMode(),
304
410
  navigated: result.navigated,
305
- ...pageStateMetadata(unifiedSession, true),
411
+ ...pageStateMetadata(unifiedSession),
306
412
  ...(result.navigated ? {} : { note: '无后退历史' }),
413
+ ...(challenge ? challengeResultFields(challenge) : {}),
307
414
  };
308
- });
415
+ }, deadline), deadline), deadline);
309
416
  }
310
417
  case 'forward': {
311
- return withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
312
- const result = await unifiedSession.goForward(args.timeout);
418
+ return await withPageContext(unifiedSession, args.targetId, () => unifiedSession.withPageCondition(args, () => withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
419
+ const result = await unifiedSession.goForward(remainingNavigationTimeout(deadline));
420
+ const challenge = result.navigated
421
+ ? await resolveChallenge(unifiedSession, 'forward', 'completed', Math.max(0, deadline - Date.now()))
422
+ : undefined;
313
423
  return {
314
424
  success: true,
315
425
  action: 'forward',
316
426
  mode: unifiedSession.getMode(),
317
427
  navigated: result.navigated,
318
- ...pageStateMetadata(unifiedSession, true),
428
+ ...pageStateMetadata(unifiedSession),
319
429
  ...(result.navigated ? {} : { note: '无前进历史' }),
430
+ ...(challenge ? challengeResultFields(challenge) : {}),
320
431
  };
321
- });
432
+ }, deadline), deadline), deadline);
322
433
  }
323
434
  case 'refresh': {
324
- return withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
435
+ return await withPageContext(unifiedSession, args.targetId, () => unifiedSession.withPageCondition(args, () => withDiagnosticsResponse(unifiedSession, args.diagnostics, async () => {
325
436
  await unifiedSession.reload({
326
437
  ignoreCache: args.ignoreCache ?? false,
327
438
  waitUntil: args.wait,
328
- timeout: args.timeout ?? DEFAULT_TIMEOUT,
439
+ timeout: remainingNavigationTimeout(deadline),
329
440
  });
441
+ const challenge = await resolveChallenge(unifiedSession, 'refresh', 'completed', Math.max(0, deadline - Date.now()));
330
442
  return {
331
443
  success: true,
332
444
  action: 'refresh',
333
445
  mode: unifiedSession.getMode(),
334
- ...pageStateMetadata(unifiedSession, true),
446
+ ...pageStateMetadata(unifiedSession),
447
+ ...challengeResultFields(challenge),
335
448
  };
336
- });
449
+ }, deadline), deadline), deadline);
337
450
  }
338
451
  case 'close': {
339
- // Extension 模式:关闭指定或当前 attach 的 tab(与 manage closePage 行为一致)
340
- // CDP 模式:关闭浏览器会话
341
- const currentMode = unifiedSession.getMode();
342
- if (currentMode === 'extension') {
452
+ if (!args.targetId) {
453
+ return {
454
+ content: [
455
+ {
456
+ type: 'text',
457
+ text: JSON.stringify({
458
+ error: {
459
+ code: 'INVALID_ARGUMENT',
460
+ message: 'close 需要 targetId 参数,避免在不同模式关闭不同范围的资源',
461
+ suggestion: '请先使用 browse(action="list") 获取页面 targetId,再指定要关闭的页面',
462
+ },
463
+ }),
464
+ },
465
+ ],
466
+ isError: true,
467
+ };
468
+ }
469
+ return await withPageResponse(unifiedSession, args.targetId, () => unifiedSession.withPageCondition(args, async () => {
343
470
  const affected = await unifiedSession.closePage(args.targetId);
344
471
  return formatResponse({
345
472
  success: true,
346
473
  action: 'close',
347
- mode: 'extension',
474
+ mode: unifiedSession.getMode(),
348
475
  targetId: args.targetId,
349
476
  ...(affected ? { affected } : {}),
350
477
  });
351
- }
352
- if (currentMode === 'cdp') {
353
- if (args.targetId) {
354
- await cdpSession.closePage(args.targetId);
355
- }
356
- else {
357
- await cdpSession.close();
358
- }
359
- return formatResponse({
360
- success: true,
361
- action: 'close',
362
- mode: 'cdp',
363
- targetId: args.targetId,
364
- });
365
- }
366
- return formatResponse({
367
- success: true,
368
- action: 'close',
369
- mode: currentMode,
370
- note: '无活跃连接',
371
- });
478
+ }));
372
479
  }
373
480
  default:
374
481
  return {
@@ -396,7 +503,16 @@ async function handleBrowse(args) {
396
503
  */
397
504
  export function registerBrowseTool(server) {
398
505
  server.registerTool('browse', {
399
- description: `浏览器管理与导航:启动、连接、列出页面、打开 URL、导航`,
506
+ description: [
507
+ '浏览器管理与导航。默认优先使用已连接的 Chrome Extension 和用户真实 Chrome;',
508
+ 'Extension 不可用时才回退 CDP。仅 browse(action="connect", port=…) 会显式选择 CDP。',
509
+ '过 Cloudflare 时,Extension 先被动等待真实 tab 标题恢复,避免先附加 debugger;',
510
+ '只有持续出现可点击 Turnstile 时才点击。同页测试按钮走页面点击;',
511
+ 'Extension inspect 走 isolated world,不先挂 debugger。',
512
+ 'Cloudflare iframe 或宿主页验证按钮只在已聚焦窗口的活动受控 tab 上用系统鼠标,',
513
+ 'Linux 用窗口原点加边距,沿路径移动、悬停后再按下抬起,混合窗口不会调用 focusWindow。',
514
+ 'open/back/forward/refresh 的 timeout 包含等待。交互式验证码和 Access denied 无法自动完成',
515
+ ].join(''),
400
516
  inputSchema: browseSchema,
401
517
  }, (args) => handleBrowse(args));
402
518
  }