@pyrokine/mcp-chrome 3.0.1 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/README.md +678 -341
  2. package/README_zh.md +694 -291
  3. package/dist/cdp/client.d.ts +7 -3
  4. package/dist/cdp/client.d.ts.map +1 -1
  5. package/dist/cdp/client.js +252 -63
  6. package/dist/cdp/client.js.map +1 -1
  7. package/dist/cdp/launcher.d.ts +1 -1
  8. package/dist/cdp/launcher.d.ts.map +1 -1
  9. package/dist/cdp/launcher.js +33 -12
  10. package/dist/cdp/launcher.js.map +1 -1
  11. package/dist/core/auto-wait.d.ts.map +1 -1
  12. package/dist/core/auto-wait.js +88 -52
  13. package/dist/core/auto-wait.js.map +1 -1
  14. package/dist/core/browser-driver.d.ts +72 -15
  15. package/dist/core/browser-driver.d.ts.map +1 -1
  16. package/dist/core/browser-driver.js.map +1 -1
  17. package/dist/core/browser-event-schema.d.ts +287 -0
  18. package/dist/core/browser-event-schema.d.ts.map +1 -0
  19. package/dist/core/browser-event-schema.js +104 -0
  20. package/dist/core/browser-event-schema.js.map +1 -0
  21. package/dist/core/browser-events.d.ts +99 -0
  22. package/dist/core/browser-events.d.ts.map +1 -0
  23. package/dist/core/browser-events.js +1312 -0
  24. package/dist/core/browser-events.js.map +1 -0
  25. package/dist/core/challenge-page.d.ts +39 -0
  26. package/dist/core/challenge-page.d.ts.map +1 -0
  27. package/dist/core/challenge-page.js +226 -0
  28. package/dist/core/challenge-page.js.map +1 -0
  29. package/dist/core/dom-helpers.d.ts +28 -0
  30. package/dist/core/dom-helpers.d.ts.map +1 -0
  31. package/dist/core/dom-helpers.js +311 -0
  32. package/dist/core/dom-helpers.js.map +1 -0
  33. package/dist/core/errors.d.ts +4 -0
  34. package/dist/core/errors.d.ts.map +1 -1
  35. package/dist/core/errors.js +51 -7
  36. package/dist/core/errors.js.map +1 -1
  37. package/dist/core/file-upload.d.ts +22 -0
  38. package/dist/core/file-upload.d.ts.map +1 -0
  39. package/dist/core/file-upload.js +194 -0
  40. package/dist/core/file-upload.js.map +1 -0
  41. package/dist/core/locator.d.ts +10 -2
  42. package/dist/core/locator.d.ts.map +1 -1
  43. package/dist/core/locator.js +121 -200
  44. package/dist/core/locator.js.map +1 -1
  45. package/dist/core/os-mouse.d.ts +11 -0
  46. package/dist/core/os-mouse.d.ts.map +1 -1
  47. package/dist/core/os-mouse.js +102 -29
  48. package/dist/core/os-mouse.js.map +1 -1
  49. package/dist/core/retry.d.ts.map +1 -1
  50. package/dist/core/retry.js +4 -1
  51. package/dist/core/retry.js.map +1 -1
  52. package/dist/core/session.d.ts +61 -12
  53. package/dist/core/session.d.ts.map +1 -1
  54. package/dist/core/session.js +1040 -259
  55. package/dist/core/session.js.map +1 -1
  56. package/dist/core/types.d.ts +5 -1
  57. package/dist/core/types.d.ts.map +1 -1
  58. package/dist/core/types.js +16 -1
  59. package/dist/core/types.js.map +1 -1
  60. package/dist/core/unified-session.d.ts +41 -35
  61. package/dist/core/unified-session.d.ts.map +1 -1
  62. package/dist/core/unified-session.js +872 -263
  63. package/dist/core/unified-session.js.map +1 -1
  64. package/dist/core/utils.d.ts +5 -4
  65. package/dist/core/utils.d.ts.map +1 -1
  66. package/dist/core/utils.js +73 -18
  67. package/dist/core/utils.js.map +1 -1
  68. package/dist/extension/bridge.d.ts +48 -17
  69. package/dist/extension/bridge.d.ts.map +1 -1
  70. package/dist/extension/bridge.js +239 -37
  71. package/dist/extension/bridge.js.map +1 -1
  72. package/dist/extension/http-server.d.ts +7 -2
  73. package/dist/extension/http-server.d.ts.map +1 -1
  74. package/dist/extension/http-server.js +211 -49
  75. package/dist/extension/http-server.js.map +1 -1
  76. package/dist/index.js +14 -1
  77. package/dist/index.js.map +1 -1
  78. package/dist/tools/browse.d.ts.map +1 -1
  79. package/dist/tools/browse.js +56 -28
  80. package/dist/tools/browse.js.map +1 -1
  81. package/dist/tools/browser-event-output.d.ts +7 -0
  82. package/dist/tools/browser-event-output.d.ts.map +1 -0
  83. package/dist/tools/browser-event-output.js +19 -0
  84. package/dist/tools/browser-event-output.js.map +1 -0
  85. package/dist/tools/challenge.d.ts +17 -5
  86. package/dist/tools/challenge.d.ts.map +1 -1
  87. package/dist/tools/challenge.js +110 -189
  88. package/dist/tools/challenge.js.map +1 -1
  89. package/dist/tools/cookies.d.ts.map +1 -1
  90. package/dist/tools/cookies.js +33 -8
  91. package/dist/tools/cookies.js.map +1 -1
  92. package/dist/tools/diagnostics.d.ts.map +1 -1
  93. package/dist/tools/diagnostics.js +14 -0
  94. package/dist/tools/diagnostics.js.map +1 -1
  95. package/dist/tools/evaluate.d.ts +6 -5
  96. package/dist/tools/evaluate.d.ts.map +1 -1
  97. package/dist/tools/evaluate.js +92 -52
  98. package/dist/tools/evaluate.js.map +1 -1
  99. package/dist/tools/extract.d.ts.map +1 -1
  100. package/dist/tools/extract.js +149 -103
  101. package/dist/tools/extract.js.map +1 -1
  102. package/dist/tools/input.d.ts.map +1 -1
  103. package/dist/tools/input.js +555 -229
  104. package/dist/tools/input.js.map +1 -1
  105. package/dist/tools/logs.d.ts.map +1 -1
  106. package/dist/tools/logs.js +50 -11
  107. package/dist/tools/logs.js.map +1 -1
  108. package/dist/tools/manage.d.ts.map +1 -1
  109. package/dist/tools/manage.js +111 -16
  110. package/dist/tools/manage.js.map +1 -1
  111. package/dist/tools/network-sanitizer.d.ts +1 -0
  112. package/dist/tools/network-sanitizer.d.ts.map +1 -1
  113. package/dist/tools/network-sanitizer.js +30 -1
  114. package/dist/tools/network-sanitizer.js.map +1 -1
  115. package/dist/tools/page-context.d.ts +4 -3
  116. package/dist/tools/page-context.d.ts.map +1 -1
  117. package/dist/tools/page-context.js +56 -14
  118. package/dist/tools/page-context.js.map +1 -1
  119. package/dist/tools/post-condition.d.ts +1 -1
  120. package/dist/tools/post-condition.d.ts.map +1 -1
  121. package/dist/tools/post-condition.js +136 -44
  122. package/dist/tools/post-condition.js.map +1 -1
  123. package/dist/tools/schema.d.ts +7 -4
  124. package/dist/tools/schema.d.ts.map +1 -1
  125. package/dist/tools/schema.js +32 -122
  126. package/dist/tools/schema.js.map +1 -1
  127. package/dist/tools/target-diagnostics.d.ts +3 -3
  128. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  129. package/dist/tools/target-diagnostics.js +17 -7
  130. package/dist/tools/target-diagnostics.js.map +1 -1
  131. package/dist/tools/wait.d.ts.map +1 -1
  132. package/dist/tools/wait.js +94 -40
  133. package/dist/tools/wait.js.map +1 -1
  134. package/extension/dist/assets/{content.ts-qe6IB5DK.js → content.ts-BAMOcF3R.js} +1 -1
  135. package/extension/dist/assets/{content.ts-loader-DUWbDHRS.js → content.ts-loader-4F9a1EWZ.js} +1 -1
  136. package/extension/dist/assets/index.ts-B79g2ikq.js +19820 -0
  137. package/extension/dist/assets/{page-scripts-D508WLkW.js → page-scripts-CSxn58h1.js} +257 -366
  138. package/extension/dist/assets/{popup.html-B-eVq48O.js → popup.html-DwwHo00N.js} +2 -2
  139. package/extension/dist/manifest.json +4 -4
  140. package/extension/dist/service-worker-loader.js +1 -1
  141. package/extension/dist/src/popup/popup.html +3 -3
  142. package/package.json +8 -6
  143. package/scripts/start-chrome.ps1 +9 -1
  144. package/extension/dist/assets/index.ts-D7_LCUoV.js +0 -9319
@@ -8,17 +8,20 @@
8
8
  * - 支持任意组合:Ctrl+Alt+A+左键+右键+拖拽
9
9
  * - humanize 可选:行为模拟是可选功能
10
10
  */
11
+ import { randomUUID } from 'node:crypto';
12
+ import { prepareUploadFiles, uploadInPage } from '../core/file-upload.js';
11
13
  import { z } from 'zod';
12
14
  import { generateBezierPath, getMouseMoveDelay, getTypingDelay, randomDelay } from '../anti-detection/index.js';
15
+ import { BrowserError, ElementNotFoundError, getErrorPageContext, isNativeExecutionResultUnknown, StructuredToolError, TimeoutError, } from '../core/errors.js';
13
16
  import { formatErrorResponse, formatResponse, getSession, getUnifiedSession } from '../core/index.js';
14
- import { ElementNotFoundError, StructuredToolError, TimeoutError } from '../core/errors.js';
15
17
  import { DEFAULT_TIMEOUT } from '../core/types.js';
16
- import { ChallengeDeniedError, ChallengeTimeoutError, resolveChallenge } from './challenge.js';
18
+ import { ChallengeDeniedError, challengeResultFields, ChallengeTimeoutError, resolveChallenge } from './challenge.js';
17
19
  import { appendDiagnostics, finishDiagnostics, startDiagnostics } from './diagnostics.js';
18
20
  import { withPageContext } from './page-context.js';
19
21
  import { postConditionSchema, waitForPostCondition } from './post-condition.js';
20
- import { pageConditionSchema, pageTargetIdSchema, resolvePageTargetId, targetToFindParams, targetZodSchema, } from './schema.js';
22
+ import { frameZodSchema, pageConditionSchema, pageTargetIdSchema, resolvePageTargetId, targetToFindParams, targetZodSchema, } from './schema.js';
21
23
  import { buildTargetDiagnostics, enrichTargetError, targetLookupTimeout } from './target-diagnostics.js';
24
+ import { installDomHelpers } from '../core/dom-helpers.js';
22
25
  const INPUT_WAIT_MAX_MS = 60_000;
23
26
  const TEXT_SELECTION_INPUT_TYPES = new Set(['text', 'search', 'tel', 'url', 'password']);
24
27
  function throwInputTimeoutError(timeout) {
@@ -76,6 +79,7 @@ const inputEventSchema = z.object({
76
79
  'touchmove',
77
80
  'touchend',
78
81
  'type',
82
+ 'upload',
79
83
  'wait',
80
84
  'select',
81
85
  'replace',
@@ -101,12 +105,17 @@ const inputEventSchema = z.object({
101
105
  .describe('鼠标点击次数(click,默认 1,设为 2 触发双击事件,设为 3 触发三击事件)'),
102
106
  target: targetZodSchema
103
107
  .optional()
104
- .describe('目标元素(mousemove/touchstart/touchmove 必填;click/mousedown/wheel/type/drag 可选;select/replace 可选;drag 时为拖拽源)'),
108
+ .describe('目标元素(upload/mousemove/touchstart/touchmove 必填;click/mousedown/wheel/type/drag 可选;' +
109
+ 'select/replace 可选;drag 时为拖拽源;upload 支持隐藏文件控件)'),
105
110
  to: targetZodSchema.optional().describe('拖拽目标元素(drag 事件必填)'),
106
111
  steps: z.number().optional().describe('移动步数(mousemove/touchmove)'),
107
112
  deltaX: z.number().optional().describe('水平滚动量'),
108
113
  deltaY: z.number().optional().describe('垂直滚动量'),
109
114
  text: z.string().max(10000).optional().describe('输入文本(type,最大 10000 字符)或替换文本(replace)'),
115
+ files: z
116
+ .array(z.string().min(1))
117
+ .optional()
118
+ .describe('upload 的 Server 本地文件路径,支持绝对、相对和 ~/ 路径;总大小须小于 50 MiB,空数组清空选择'),
110
119
  delay: z.number().min(0).max(100).optional().describe('按键间隔毫秒(type 事件最大 100ms,避免长时延 DoS)'),
111
120
  ms: z
112
121
  .number()
@@ -121,11 +130,12 @@ const inputEventSchema = z.object({
121
130
  mode: z
122
131
  .enum(['keyboard', 'controlled'])
123
132
  .optional()
124
- .describe('输入模式(type),keyboard=键盘事件,controlled=直接设置 value 并触发 input/change 事件'),
133
+ .describe('输入模式(type),默认 keyboard;precise 键盘换行会派发 Enter 并触发页面 Enter 行为;' +
134
+ 'controlled 替换完整文本并触发 input/change,不派发 Enter,需 Extension 和 target;选区插入用 editorInsert'),
125
135
  dispatch: z
126
136
  .boolean()
127
137
  .optional()
128
- .describe('使用 dispatch 模式输入(type),直接设置 value 并触发 input/change 事件,兼容 React/Vue 等框架的受控组件,默认 false 使用键盘事件'),
138
+ .describe('controlled 模式别名(type),替换完整文本并触发 input/change,不派发 Enter;默认 false 使用键盘事件,precise 换行会派发 Enter'),
129
139
  force: z
130
140
  .boolean()
131
141
  .optional()
@@ -152,17 +162,14 @@ const inputSchema = z.object({
152
162
  .number()
153
163
  .optional()
154
164
  .describe('超时毫秒,含 Cloudflare Challenge 等待、目标准备、鼠标移动、字符输入和延迟;到期后停止后续动作,不自动重放'),
155
- frame: z
156
- .union([z.string(), z.number()])
157
- .optional()
158
- .describe('iframe 定位(可选,仅 Extension 模式),CSS 选择器(如 "iframe#main")或索引(如 0),不指定则在主框架操作'),
165
+ frame: frameZodSchema.describe('iframe selector/索引或逐层路径(如 ["iframe#outer", 0]),省略时使用主文档'),
159
166
  });
160
167
  function sanitizeInputResponse(response, events, sensitiveInput) {
161
168
  if (!response.isError && !sensitiveInput) {
162
169
  return response;
163
170
  }
164
171
  const sensitiveValues = events
165
- .flatMap((event) => [event.find, event.text])
172
+ .flatMap((event) => [event.find, event.text, ...(event.files ?? []).filter((path) => /[/\\]/.test(path))])
166
173
  .filter((value) => !!value);
167
174
  for (const item of response.content) {
168
175
  try {
@@ -191,6 +198,7 @@ function sanitizeInputResponse(response, events, sensitiveInput) {
191
198
  'message',
192
199
  'suggestion',
193
200
  'context',
201
+ 'logs',
194
202
  'contextError',
195
203
  'url',
196
204
  'title',
@@ -221,11 +229,13 @@ function sanitizeInputResponse(response, events, sensitiveInput) {
221
229
  /**
222
230
  * input 工具处理器
223
231
  */
224
- async function handleInput(args) {
232
+ async function handleInput(args, signal) {
225
233
  const inputStartedAt = Date.now();
226
234
  const deadline = args.timeout === undefined ? undefined : inputStartedAt + args.timeout;
227
235
  let eventsExecuted = 0;
228
236
  let actionMayHaveExecuted = false;
237
+ let actionExecutedUnknown = false;
238
+ let challengeFields = {};
229
239
  const privacy = { sensitive: false };
230
240
  const progress = {
231
241
  actionStatus: 'not_started',
@@ -256,41 +266,47 @@ async function handleInput(args) {
256
266
  return unifiedSession.withPageCondition(args, () => unifiedSession.withFrame(args.frame, async () => {
257
267
  const mode = unifiedSession.getMode();
258
268
  if (args.expectedUrl === undefined && args.expectedRevision === undefined) {
259
- await resolveChallenge(unifiedSession, 'input', 'not_started', deadline === undefined ? undefined : remainingInputTimeout(deadline));
269
+ challengeFields = challengeResultFields(await resolveChallenge(unifiedSession, 'input', 'not_started', deadline === undefined ? undefined : remainingInputTimeout(deadline)));
260
270
  }
261
271
  const diagnostics = await startDiagnostics(unifiedSession, args.diagnostics, deadline);
262
272
  const warnings = [];
263
273
  const eventResults = [];
264
274
  const session = mode === 'cdp' ? getSession() : undefined;
265
275
  try {
266
- for (const event of args.events) {
267
- const eventTimeout = args.timeout === undefined
268
- ? undefined
269
- : Math.max(0, args.timeout - (Date.now() - inputStartedAt));
270
- if (eventTimeout !== undefined && eventTimeout <= 0) {
271
- throwInputTimeoutError(args.timeout);
272
- }
273
- progress.actionStatus = 'failed';
274
- const result = await executeInputEvent({
275
- unifiedSession,
276
- session,
277
- mode,
278
- humanize,
279
- timeout: eventTimeout,
280
- frame: args.frame,
281
- privacy,
282
- }, event);
283
- ++eventsExecuted;
284
- if (typeof result === 'string') {
285
- warnings.push(result);
276
+ await unifiedSession.withInputCleanup(async () => {
277
+ for (const event of args.events) {
278
+ unifiedSession.assertRequestActive();
279
+ const eventTimeout = args.timeout === undefined
280
+ ? undefined
281
+ : Math.max(0, args.timeout - (Date.now() - inputStartedAt));
282
+ if (eventTimeout !== undefined && eventTimeout <= 0) {
283
+ throwInputTimeoutError(args.timeout);
284
+ }
285
+ progress.actionStatus = 'failed';
286
+ const result = await unifiedSession.withUserAction('input', () => executeInputEvent({
287
+ unifiedSession,
288
+ session,
289
+ mode,
290
+ humanize,
291
+ timeout: eventTimeout,
292
+ frame: args.frame,
293
+ signal,
294
+ privacy,
295
+ }, event), event.type === 'keydown' &&
296
+ Boolean(event.commands?.length) &&
297
+ event.target !== undefined &&
298
+ 'x' in event.target &&
299
+ 'y' in event.target);
300
+ ++eventsExecuted;
301
+ if (typeof result === 'string') {
302
+ warnings.push(result);
303
+ }
304
+ else if (result) {
305
+ eventResults.push(result);
306
+ }
286
307
  }
287
- else if (result) {
288
- eventResults.push(result);
289
- }
290
- }
291
- if (args.timeout !== undefined && Date.now() - inputStartedAt >= args.timeout) {
292
- throw new TimeoutError('input timeout after event dispatch');
293
- }
308
+ progress.actionStatus = 'completed';
309
+ });
294
310
  }
295
311
  catch (error) {
296
312
  const response = formatErrorResponse(error);
@@ -318,27 +334,77 @@ async function handleInput(args) {
318
334
  const payload = JSON.parse(text);
319
335
  const message = error instanceof Error ? error.message : String(error);
320
336
  const timedOut = /timeout|超时/i.test(message);
321
- const preActionTimeout = /timeout before event dispatch|超过 input 剩余 timeout/i.test(message);
322
- actionMayHaveExecuted = timedOut && !preActionTimeout;
337
+ const preActionTimeout = /timeout.*before|超过 input 剩余 timeout/i.test(message);
338
+ actionMayHaveExecuted =
339
+ isNativeExecutionResultUnknown(error) || (timedOut && !preActionTimeout);
323
340
  const preconditionFailed = error !== null &&
324
341
  typeof error === 'object' &&
325
342
  'code' in error &&
326
343
  error.code === 'ACTION_PRECONDITION_FAILED';
327
- actionMayHaveExecuted = actionMayHaveExecuted && !preconditionFailed;
328
- progress.actionStatus =
329
- preconditionFailed && eventsExecuted === 0
344
+ const executionContext = error instanceof StructuredToolError || error instanceof BrowserError
345
+ ? error.context
346
+ : undefined;
347
+ const contextPhase = getErrorPageContext(error)?.contextPhase;
348
+ const preparationFailure = contextPhase === 'preparation' || contextPhase === 'precondition';
349
+ const explicitNotStarted = preparationFailure || executionContext?.actionExecuted === false;
350
+ actionExecutedUnknown =
351
+ !explicitNotStarted && executionContext?.actionExecuted === 'unknown';
352
+ actionMayHaveExecuted =
353
+ (actionMayHaveExecuted ||
354
+ actionExecutedUnknown ||
355
+ executionContext?.actionExecuted === true) &&
356
+ !preconditionFailed &&
357
+ !explicitNotStarted;
358
+ const cleanupFailure = progress.actionStatus === 'completed';
359
+ const keyboardFocusCleanup = getErrorPageContext(error)?.keyboardFocusCleanup ??
360
+ executionContext?.keyboardFocusCleanup;
361
+ if (keyboardFocusCleanup) {
362
+ payload.keyboardFocusCleanup = keyboardFocusCleanup;
363
+ }
364
+ const keyboardWarning = getErrorPageContext(error)?.keyboardFocusWarning;
365
+ if (typeof keyboardWarning === 'string' &&
366
+ !warnings.includes(keyboardWarning)) {
367
+ warnings.push(keyboardWarning);
368
+ }
369
+ if (warnings.length) {
370
+ payload.warnings = warnings;
371
+ }
372
+ if (cleanupFailure) {
373
+ actionMayHaveExecuted = true;
374
+ }
375
+ progress.actionStatus = cleanupFailure
376
+ ? 'completed'
377
+ : (preconditionFailed ||
378
+ preparationFailure ||
379
+ (explicitNotStarted &&
380
+ executionContext?.actionStatus === 'not_started')) &&
381
+ eventsExecuted === 0
330
382
  ? 'not_started'
331
- : actionMayHaveExecuted
383
+ : actionMayHaveExecuted && executionContext?.actionStatus !== 'failed'
332
384
  ? 'unknown'
333
385
  : 'failed';
334
386
  payload.eventsExecuted = eventsExecuted;
335
- payload.actionExecuted = eventsExecuted > 0 || actionMayHaveExecuted;
387
+ payload.actionExecuted =
388
+ eventsExecuted > 0
389
+ ? true
390
+ : actionExecutedUnknown
391
+ ? 'unknown'
392
+ : actionMayHaveExecuted;
336
393
  payload.actionStatus = progress.actionStatus;
337
394
  payload.verificationRequested = Boolean(args.postCondition);
338
395
  payload.verificationStatus = 'unavailable';
339
- payload.failureStage = 'action';
396
+ if (preparationFailure) {
397
+ payload.remainingEventsNotExecuted = args.events.length - eventsExecuted;
398
+ }
399
+ payload.failureStage = preparationFailure
400
+ ? contextPhase === 'precondition'
401
+ ? 'precondition'
402
+ : 'context'
403
+ : (executionContext?.failureStage ?? 'action');
340
404
  payload.retryable =
341
- eventsExecuted === 0 &&
405
+ !preparationFailure &&
406
+ executionContext?.retryable !== false &&
407
+ eventsExecuted === 0 &&
342
408
  !actionMayHaveExecuted &&
343
409
  /timeout|超时|disconnect|未连接|context|debugger/i.test(message);
344
410
  appendDiagnostics(payload, await finishDiagnostics(unifiedSession, diagnostics, deadline));
@@ -351,8 +417,19 @@ async function handleInput(args) {
351
417
  return response;
352
418
  }
353
419
  progress.actionStatus = 'completed';
420
+ failureStage = 'verification';
421
+ if (deadline === undefined || Date.now() < deadline) {
422
+ Object.assign(challengeFields, challengeResultFields(await resolveChallenge(unifiedSession, 'input', 'completed', deadline === undefined ? undefined : remainingInputTimeout(deadline))));
423
+ }
424
+ else {
425
+ Object.assign(challengeFields, {
426
+ challengeVerificationStatus: 'unavailable',
427
+ challengeVerificationError: '输入已确认完成,剩余 timeout 已用尽',
428
+ });
429
+ }
354
430
  failureStage = 'context';
355
431
  const result = {
432
+ ...challengeFields,
356
433
  success: true,
357
434
  eventsExecuted,
358
435
  mode,
@@ -370,11 +447,10 @@ async function handleInput(args) {
370
447
  }
371
448
  if (args.postCondition) {
372
449
  failureStage = 'verification';
373
- const postCondition = await waitForPostCondition(unifiedSession, args.postCondition, 'input');
450
+ const postCondition = await waitForPostCondition(unifiedSession, args.postCondition, 'input', undefined, deadline, signal);
374
451
  failureStage = 'context';
375
452
  result.postCondition = postCondition;
376
453
  result.verificationStatus = postCondition.verificationStatus;
377
- result.retryable = postCondition.retryable;
378
454
  if (postCondition.verificationStatus !== 'matched') {
379
455
  result.success = false;
380
456
  result.failureStage = 'verification';
@@ -382,8 +458,8 @@ async function handleInput(args) {
382
458
  }
383
459
  appendDiagnostics(result, await finishDiagnostics(unifiedSession, diagnostics, deadline));
384
460
  return formatResponse(result);
385
- }, deadline), deadline); // withPageCondition, withFrame
386
- }, deadline); // withTabId
461
+ }, deadline), deadline); // withPageCondition, withFrame, withInputCleanup
462
+ }, deadline, signal, 'input'); // withTabId
387
463
  return sanitizeInputResponse(response, args.events, privacy.sensitive);
388
464
  }
389
465
  catch (error) {
@@ -406,18 +482,46 @@ async function handleInput(args) {
406
482
  typeof error === 'object' &&
407
483
  'code' in error &&
408
484
  error.code === 'ACTION_PRECONDITION_FAILED');
485
+ const executionContext = error instanceof StructuredToolError || error instanceof BrowserError ? error.context : undefined;
486
+ const challengeFailure = error instanceof ChallengeTimeoutError || error instanceof ChallengeDeniedError ? error : null;
487
+ const contextPhase = getErrorPageContext(error)?.contextPhase;
488
+ const preparationFailure = progress.actionStatus === 'not_started' &&
489
+ (contextPhase === 'before' || contextPhase === 'precondition' || contextPhase === 'preparation');
409
490
  Object.assign(payload, {
491
+ ...challengeFields,
410
492
  eventsExecuted,
411
- actionExecuted: eventsExecuted > 0 || actionMayHaveExecuted,
412
- actionStatus: preconditionFailed && eventsExecuted === 0
493
+ remainingEventsNotExecuted: args.events.length - eventsExecuted,
494
+ actionExecuted: preparationFailure
495
+ ? false
496
+ : eventsExecuted > 0
497
+ ? true
498
+ : actionExecutedUnknown || executionContext?.actionExecuted === 'unknown'
499
+ ? 'unknown'
500
+ : executionContext?.actionExecuted === true || actionMayHaveExecuted,
501
+ actionStatus: preparationFailure
413
502
  ? 'not_started'
414
- : progress.actionStatus === 'not_started'
415
- ? 'failed'
416
- : progress.actionStatus,
503
+ : progress.actionStatus === 'completed'
504
+ ? 'completed'
505
+ : preconditionFailed && eventsExecuted === 0
506
+ ? 'not_started'
507
+ : challengeFailure
508
+ ? challengeFailure.actionStatus
509
+ : (executionContext?.actionStatus ??
510
+ (progress.actionStatus === 'not_started' ? 'failed' : progress.actionStatus)),
417
511
  verificationRequested: Boolean(args.postCondition),
418
- verificationStatus: 'unavailable',
419
- failureStage: unavailableCondition ? 'precondition' : failureStage,
420
- retryable: progress.actionStatus !== 'completed' &&
512
+ verificationStatus: challengeFailure
513
+ ? payload.verificationStatus
514
+ : (executionContext?.verificationStatus ?? 'unavailable'),
515
+ failureStage: preparationFailure
516
+ ? contextPhase === 'precondition'
517
+ ? 'precondition'
518
+ : 'context'
519
+ : unavailableCondition
520
+ ? 'precondition'
521
+ : (executionContext?.failureStage ?? failureStage),
522
+ retryable: !preparationFailure &&
523
+ executionContext?.retryable !== false &&
524
+ progress.actionStatus !== 'completed' &&
421
525
  eventsExecuted === 0 &&
422
526
  !actionMayHaveExecuted &&
423
527
  !preconditionFailed &&
@@ -440,6 +544,7 @@ async function handleInput(args) {
440
544
  }
441
545
  }
442
546
  const unifiedOnlyEventTypes = new Set([
547
+ 'upload',
443
548
  'keydown',
444
549
  'keyup',
445
550
  'select',
@@ -460,10 +565,12 @@ async function executeInputEvent(context, event) {
460
565
  humanize: context.humanize,
461
566
  timeout: context.timeout,
462
567
  frame: context.frame,
568
+ signal: context.signal,
463
569
  privacy: context.privacy,
464
570
  }, event);
465
571
  }
466
572
  if (!context.session) {
573
+ // noinspection ExceptionCaughtLocallyJS -- Report failure
467
574
  throw new Error('CDP 输入事件缺少 session');
468
575
  }
469
576
  await executeCdpEvent(context.session, event, context.humanize, context.timeout);
@@ -496,27 +603,26 @@ async function focusTargetForCommands(unifiedSession, target, timeout, frame) {
496
603
  return;
497
604
  }
498
605
  const params = targetToFindParams(target);
499
- const els = 'x' in target && 'y' in target
500
- ? await unifiedSession.findAtPoint(target.x, target.y, undefined, remainingInputTimeout(deadline))
501
- : await unifiedSession.find(params.selector, params.text, params.xpath, remainingInputTimeout(deadline));
502
606
  const nth0 = params.nth ?? 0;
503
- if (els.length <= nth0) {
504
- throw new StructuredToolError(els.length === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', els.length === 0
505
- ? `未找到命令目标: ${JSON.stringify(target)}`
506
- : `第 ${nth0} 个命令目标不存在(共 ${els.length} 个)`, '请检查 target、frame 和 target.nth,或先用 extract type=state 查看当前候选元素', await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, remainingInputTimeout(deadline), '命令目标未找到', frame));
607
+ const els = 'x' in target && 'y' in target
608
+ ? await unifiedSession.findAtPoint(target.x, target.y, nth0, remainingInputTimeout(deadline))
609
+ : await unifiedSession.find(params.selector, params.text, params.xpath, remainingInputTimeout(deadline), params.semantic, nth0);
610
+ if (els.length === 0) {
611
+ throw new StructuredToolError(nth0 === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', `第 ${nth0} 个命令目标不存在: ${JSON.stringify(target)}`, '请检查 target、frame 和 target.nth,或先用 extract type=state 查看当前候选元素', await buildTargetDiagnosticContext(unifiedSession, target, null, nth0, remainingInputTimeout(deadline), '命令目标未找到', frame));
507
612
  }
508
613
  const focused = await unifiedSession.evaluate(`(() => {
509
614
  if (Date.now() >= ${deadline}) throw new Error('input timeout before command focus')
510
- const ref = window.__mcpElementMap?.[${JSON.stringify(els[nth0].refId)}]
615
+ const ref = window.__mcpElementMap?.[${JSON.stringify(els[0].refId)}]
511
616
  const el = ref?.deref()
512
617
  if (!(el instanceof HTMLElement)) {
513
618
  return false
514
619
  }
620
+ (${installDomHelpers.toString()})();
515
621
  el.focus({preventScroll: true})
516
- return document.activeElement === el
622
+ return globalThis.__mcpDomHelpers.activeElement() === el
517
623
  })()`, undefined, remainingInputTimeout(deadline));
518
624
  if (focused !== true) {
519
- throw new StructuredToolError('TARGET_FOCUS_FAILED', '命令目标未成功聚焦', '请检查目标是否可编辑、未 disabled 并处于正确 frame', await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, remainingInputTimeout(deadline), '命令目标聚焦失败', frame));
625
+ throw new StructuredToolError('TARGET_FOCUS_FAILED', '命令目标未成功聚焦', '请检查目标是否可编辑、未 disabled 并处于正确 frame', await buildTargetDiagnosticContext(unifiedSession, target, null, nth0, remainingInputTimeout(deadline), '命令目标聚焦失败', frame));
520
626
  }
521
627
  }
522
628
  export async function focusCdpTarget(session, target, timeout) {
@@ -524,12 +630,14 @@ export async function focusCdpTarget(session, target, timeout) {
524
630
  const focus = `function() {
525
631
  if (Date.now() >= ${deadline}) throw new Error('input timeout before command focus');
526
632
  if (!(this instanceof HTMLElement)) return false;
633
+ (${installDomHelpers.toString()})();
527
634
  this.focus({preventScroll: true});
528
- return document.activeElement === this;
635
+ return globalThis.__mcpDomHelpers.activeElement() === this;
529
636
  }`;
530
637
  const focused = 'x' in target && 'y' in target
531
638
  ? await session.evaluate(`(() => {
532
- const el = document.elementFromPoint(${target.x}, ${target.y});
639
+ (${installDomHelpers.toString()})();
640
+ const el = globalThis.__mcpDomHelpers.deepElementFromPoint(${target.x}, ${target.y});
533
641
  return el ? (${focus}).call(el) : null;
534
642
  })()`, undefined, remainingInputTimeout(deadline))
535
643
  : await session
@@ -567,24 +675,24 @@ async function focusTargetIfNeeded(unifiedSession, session, mode, target, timeou
567
675
  return;
568
676
  }
569
677
  const params = targetToFindParams(target);
570
- const els = await unifiedSession.find(params.selector, params.text, params.xpath, remainingInputTimeout(deadline));
571
678
  const nth0 = params.nth ?? 0;
572
- if (els.length <= nth0) {
573
- throw new StructuredToolError(els.length === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', els.length === 0
574
- ? `未找到目标元素: ${JSON.stringify(target)}`
575
- : `第 ${nth0} 个匹配元素不存在(共 ${els.length} 个)`, '请检查 target、frame 和 target.nth,或先用 extract type=state 查看当前候选元素', await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, timeout, '聚焦目标未找到', frame));
679
+ const els = await unifiedSession.find(params.selector, params.text, params.xpath, remainingInputTimeout(deadline), params.semantic, nth0);
680
+ if (els.length === 0) {
681
+ throw new StructuredToolError(nth0 === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', `第 ${nth0} 个匹配元素不存在: ${JSON.stringify(target)}`, '请检查 target、frame 和 target.nth,或先用 extract type=state 查看当前候选元素', await buildTargetDiagnosticContext(unifiedSession, target, null, nth0, timeout, '聚焦目标未找到', frame));
576
682
  }
577
683
  remainingInputTimeout(deadline);
578
- const result = await unifiedSession.actionableClick(els[nth0].refId);
684
+ const result = await unifiedSession.actionableClick(els[0].refId);
579
685
  if (!result.success) {
580
686
  throw new StructuredToolError('ACTIONABILITY_FAILED', result.error || '目标元素无法聚焦', result.suggestions?.[0] ?? '请检查元素是否可见、未被遮挡并处于正确 frame', {
581
687
  ...result,
582
- ...(await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, timeout, result.error || '目标元素无法聚焦', frame)),
688
+ ...(await buildTargetDiagnosticContext(unifiedSession, target, null, nth0, timeout, result.error || '目标元素无法聚焦', frame)),
583
689
  });
584
690
  }
585
691
  }
586
- async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, occurrenceNth, scopeNth, scopeSelector, scopeText, scopeXpath, timeout) {
587
- return await unifiedSession.evaluate(`function(findText, occurrenceNth, scopeNth, scopeTarget, scopeSelector, scopeText, scopeXpath) {
692
+ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, occurrenceNth, scopeNth, scopeSelector, scopeText, scopeXpath, scopeSemantic, timeout) {
693
+ return await unifiedSession.evaluate(`function(findText, occurrenceNth, scopeNth, scopeTarget, scopeSelector, scopeText, scopeXpath, scopeSemantic) {
694
+ (${installDomHelpers.toString()})();
695
+ var helpers = globalThis.__mcpDomHelpers;
588
696
  function selectorFor(el) {
589
697
  if (!(el instanceof Element)) return null;
590
698
  if (el.id) return '#' + CSS.escape(el.id);
@@ -638,22 +746,10 @@ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTa
638
746
  };
639
747
  }
640
748
  var root = document.body;
641
- if (scopeXpath) {
642
- var xr = document.evaluate(scopeXpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
643
- root = xr.snapshotItem(scopeNth);
644
- } else if (scopeSelector) {
645
- var candidates = Array.from(document.querySelectorAll(scopeSelector));
646
- if (scopeText) {
647
- candidates = candidates.filter(function(candidate) {
648
- return (candidate.textContent || '').includes(scopeText);
649
- });
650
- }
651
- root = candidates[scopeNth];
652
- } else if (scopeText) {
653
- var all = Array.from(document.querySelectorAll('*')).filter(function(candidate) {
654
- return (candidate.textContent || '').includes(scopeText);
655
- });
656
- root = all[scopeNth];
749
+ if (scopeXpath || scopeSelector || scopeText || scopeSemantic) {
750
+ root = helpers.query({
751
+ selector:scopeSelector, text:scopeText, xpath:scopeXpath, semantic:scopeSemantic
752
+ })[scopeNth];
657
753
  }
658
754
  var candidateElements = [];
659
755
  if (root instanceof Element) {
@@ -661,10 +757,10 @@ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTa
661
757
  var candidateSelector =
662
758
  'input, textarea, [contenteditable="true"], [role="textbox"], button, a';
663
759
  candidateElements = candidateElements.concat(
664
- Array.from(root.querySelectorAll(candidateSelector)).slice(0, 12)
760
+ helpers.query({selector:candidateSelector}, root).slice(0, 12)
665
761
  );
666
762
  }
667
- var active = document.activeElement;
763
+ var active = helpers.activeElement();
668
764
  var activeIsPassword =
669
765
  active instanceof HTMLInputElement &&
670
766
  (active.type || 'text').toLowerCase() === 'password';
@@ -698,7 +794,7 @@ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTa
698
794
  },
699
795
  candidates: candidateElements.map(summarizeElement).filter(Boolean)
700
796
  };
701
- }`, undefined, timeout, [findText, occurrenceNth, scopeNth, scopeTarget ?? null, scopeSelector, scopeText, scopeXpath]);
797
+ }`, undefined, timeout, [findText, occurrenceNth, scopeNth, scopeTarget ?? null, scopeSelector, scopeText, scopeXpath, scopeSemantic]);
702
798
  }
703
799
  async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeout, privacy) {
704
800
  const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
@@ -710,35 +806,27 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
710
806
  let scopeSelector = null;
711
807
  let scopeText = null;
712
808
  let scopeXpath = null;
809
+ let scopeSemantic = null;
713
810
  let scopeNth = 0;
714
811
  if (scopeTarget && !('x' in scopeTarget) && !('y' in scopeTarget)) {
715
812
  const params = targetToFindParams(scopeTarget);
716
813
  scopeSelector = params.selector ?? null;
717
814
  scopeText = params.text ?? null;
718
815
  scopeXpath = params.xpath ?? null;
816
+ scopeSemantic = params.semantic ?? null;
719
817
  scopeNth = params.nth ?? 0;
720
818
  }
721
819
  // Step 1: 注入脚本定位文本
722
820
  //noinspection SpellCheckingInspection -- 模板中的坐标字段名
723
- const result = await unifiedSession.evaluate(`function(findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath) {
821
+ const result = await unifiedSession.evaluate(`function(findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath, scopeSemantic) {
822
+ (${installDomHelpers.toString()})();
823
+ var helpers = globalThis.__mcpDomHelpers;
724
824
  // 确定搜索根节点
725
825
  var root = document.body;
726
- if (scopeXpath) {
727
- var xr = document.evaluate(scopeXpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
728
- root = xr.snapshotItem(scopeNth);
729
- } else if (scopeSelector) {
730
- var candidates = Array.from(document.querySelectorAll(scopeSelector));
731
- if (scopeText) {
732
- candidates = candidates.filter(function(candidate) {
733
- return (candidate.textContent || '').includes(scopeText);
734
- });
735
- }
736
- root = candidates[scopeNth];
737
- } else if (scopeText) {
738
- var all = Array.from(document.querySelectorAll('*')).filter(function(candidate) {
739
- return (candidate.textContent || '').includes(scopeText);
740
- });
741
- root = all[scopeNth];
826
+ if (scopeXpath || scopeSelector || scopeText || scopeSemantic) {
827
+ root = helpers.query({
828
+ selector:scopeSelector, text:scopeText, xpath:scopeXpath, semantic:scopeSemantic
829
+ })[scopeNth];
742
830
  }
743
831
  if (!root) return {type: 'noscope'};
744
832
 
@@ -770,7 +858,7 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
770
858
  }
771
859
 
772
860
  // 在子树中查找 input/textarea
773
- var inputs = root.querySelectorAll('input, textarea');
861
+ var inputs = helpers.query({selector:'input, textarea'}, root);
774
862
  for (var k = 0; k < inputs.length; k++) {
775
863
  var inp = inputs[k];
776
864
  var v = inp.value || '';
@@ -801,14 +889,20 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
801
889
  // DOM 文本节点:TreeWalker 遍历(限制规模防止大 DOM 阻塞)
802
890
  var MAX_TEXT_NODES = 10000;
803
891
  var MAX_TEXT_LENGTH = 500000;
804
- var walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
892
+ var pendingNodes = [root];
805
893
  var textNodes = [];
806
894
  var fullText = '';
807
- var node;
808
- while (node = walker.nextNode()) {
895
+ while (pendingNodes.length) {
809
896
  if (textNodes.length >= MAX_TEXT_NODES || fullText.length >= MAX_TEXT_LENGTH) break;
810
- textNodes.push({node: node, start: fullText.length, length: node.textContent.length});
811
- fullText += node.textContent;
897
+ var node = pendingNodes.pop();
898
+ if (node.nodeType === Node.TEXT_NODE) {
899
+ textNodes.push({node: node, start: fullText.length, length: node.textContent.length});
900
+ fullText += node.textContent;
901
+ } else {
902
+ var children = Array.from(node.childNodes);
903
+ for (var ci = children.length - 1; ci >= 0; --ci) pendingNodes.push(children[ci]);
904
+ if (node.shadowRoot) pendingNodes.push(node.shadowRoot);
905
+ }
812
906
  }
813
907
 
814
908
  // 查找第 nth 个匹配
@@ -871,7 +965,7 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
871
965
  endY: er.y + er.height / 2,
872
966
  formatted: formatted || undefined
873
967
  };
874
- }`, undefined, remainingInputTimeout(deadline), [findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath]);
968
+ }`, undefined, remainingInputTimeout(deadline), [findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath, scopeSemantic], { userAction: 'input' });
875
969
  if (privacy &&
876
970
  result &&
877
971
  result.type !== 'noscope' &&
@@ -879,7 +973,7 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
879
973
  privacy.sensitive = sensitiveBefore || ('inputType' in result && result.inputType === 'password');
880
974
  }
881
975
  if (!result || result.type === 'noscope') {
882
- const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, timeout);
976
+ const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, scopeSemantic, timeout);
883
977
  throw new StructuredToolError('TEXT_SCOPE_NOT_FOUND', `未找到目标元素: ${JSON.stringify(scopeTarget)}`, '请检查 target 是否能定位到包含目标文本的元素,或先用 extract(state) 查看可交互元素', diagnostics);
884
978
  }
885
979
  if (result.type === 'unsupported') {
@@ -892,7 +986,7 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
892
986
  });
893
987
  }
894
988
  if (result.type === 'notfound') {
895
- const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, timeout);
989
+ const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, scopeSemantic, timeout);
896
990
  throw new StructuredToolError('TEXT_NOT_FOUND', scopeTarget
897
991
  ? `目标元素内未找到文本 "${findText}"${nth > 0 ? `(第 ${nth} 个匹配)` : ''}`
898
992
  : `未找到文本: "${findText}"${nth > 0 ? `(第 ${nth} 个匹配)` : ''}`, '请检查 find 文本、nth 序号和 target 范围;context.candidates 提供了当前范围内的候选文本和 selector', diagnostics);
@@ -906,14 +1000,6 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
906
1000
  }
907
1001
  // DOM 文本节点:鼠标选择
908
1002
  const coords = result;
909
- // iframe 坐标修正(precise 模式需要视口绝对坐标)
910
- const frameOffset = unifiedSession.getFrameOffset();
911
- if (frameOffset && unifiedSession.getInputMode() !== 'stealth') {
912
- coords.startX += frameOffset.x;
913
- coords.startY += frameOffset.y;
914
- coords.endX += frameOffset.x;
915
- coords.endY += frameOffset.y;
916
- }
917
1003
  // Step 2: 模拟鼠标选择
918
1004
  await unifiedSession.mouseMove(coords.startX, coords.startY, remainingInputTimeout(deadline));
919
1005
  remainingInputTimeout(deadline);
@@ -972,6 +1058,14 @@ function validateEvent(event) {
972
1058
  requiredEventParam(event, 'text');
973
1059
  }
974
1060
  break;
1061
+ case 'upload':
1062
+ if (!event.target ||
1063
+ 'x' in event.target ||
1064
+ !Array.isArray(event.files) ||
1065
+ event.files.some((path) => typeof path !== 'string' || !path)) {
1066
+ throw new StructuredToolError('INVALID_ARGUMENT', 'upload 需要元素 target 和 files 路径数组,空数组用于清空选择', '请指定 input[type=file] 的 CSS、label、XPath 或其他元素定位', { actionExecuted: false, actionStatus: 'not_started' });
1067
+ }
1068
+ break;
975
1069
  case 'select':
976
1070
  if (!event.find) {
977
1071
  requiredEventParam(event, 'find');
@@ -1030,6 +1124,7 @@ const unifiedInputHandlers = {
1030
1124
  touchmove: handleUnifiedTouchMove,
1031
1125
  touchend: handleUnifiedTouchEnd,
1032
1126
  type: handleUnifiedType,
1127
+ upload: handleUnifiedUpload,
1033
1128
  wait: handleUnifiedWait,
1034
1129
  select: handleUnifiedSelect,
1035
1130
  replace: handleUnifiedReplace,
@@ -1050,12 +1145,15 @@ async function handleUnifiedKeyDown({ unifiedSession, timeout, frame }, event) {
1050
1145
  await focusTargetForCommands(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
1051
1146
  }
1052
1147
  remainingInputTimeout(deadline);
1148
+ const warning = await unifiedSession.prepareKeyboardFocus(remainingInputTimeout(deadline));
1053
1149
  await unifiedSession.keyDown(event.key, event.commands, remainingInputTimeout(deadline));
1054
- return undefined;
1150
+ return warning;
1055
1151
  }
1056
1152
  async function handleUnifiedKeyUp({ unifiedSession, timeout }, event) {
1057
- await unifiedSession.keyUp(event.key, timeout);
1058
- return undefined;
1153
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1154
+ const warning = await unifiedSession.prepareKeyboardFocus(remainingInputTimeout(deadline));
1155
+ await unifiedSession.keyUp(event.key, remainingInputTimeout(deadline));
1156
+ return warning;
1059
1157
  }
1060
1158
  async function handleUnifiedClick({ unifiedSession, humanize, timeout, frame }, event) {
1061
1159
  const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
@@ -1083,6 +1181,7 @@ async function handleUnifiedClick({ unifiedSession, humanize, timeout, frame },
1083
1181
  throw new StructuredToolError('ACTIONABILITY_FAILED', result.error || 'Click failed', result.suggestions?.[0] ??
1084
1182
  '请根据 context.rect、context.clickPoint 和 context.coveringElement 调整 target', result);
1085
1183
  }
1184
+ return result.warning;
1086
1185
  }
1087
1186
  else {
1088
1187
  await unifiedSession.mouseClick(button, clickCount);
@@ -1122,29 +1221,31 @@ async function handleUnifiedMouseMove({ unifiedSession, humanize, timeout, frame
1122
1221
  }
1123
1222
  async function handleUnifiedWheel({ unifiedSession, timeout, frame }, event) {
1124
1223
  const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1125
- if (event.target) {
1126
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(event.target);
1127
- const elements = await unifiedSession.find(selector, text, xpath, remainingInputTimeout(deadline));
1224
+ let point;
1225
+ if (event.target && 'x' in event.target && 'y' in event.target) {
1226
+ point = { x: event.target.x, y: event.target.y };
1227
+ }
1228
+ else if (event.target) {
1229
+ const { selector, text, xpath, nth: nthParam, semantic, } = targetToFindParams(event.target);
1128
1230
  const nth = nthParam ?? 0;
1129
- if (elements.length > nth) {
1231
+ const elements = await unifiedSession.find(selector, text, xpath, remainingInputTimeout(deadline), semantic, nth);
1232
+ if (elements.length > 0) {
1130
1233
  remainingInputTimeout(deadline);
1131
- await unifiedSession.scroll(event.deltaX ?? 0, event.deltaY ?? 0, elements[nth].refId);
1234
+ await unifiedSession.scroll(event.deltaX ?? 0, event.deltaY ?? 0, elements[0].refId);
1132
1235
  return undefined;
1133
1236
  }
1134
- const point = await getTargetPointExtension(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
1135
- await unifiedSession.mouseMove(point.x, point.y, remainingInputTimeout(deadline));
1237
+ point = await getTargetPointExtension(unifiedSession, event.target, remainingInputTimeout(deadline), frame, true);
1136
1238
  }
1137
- remainingInputTimeout(deadline);
1138
- await unifiedSession.mouseWheel(event.deltaX ?? 0, event.deltaY ?? 0);
1239
+ await unifiedSession.mouseWheel(event.deltaX ?? 0, event.deltaY ?? 0, remainingInputTimeout(deadline), point);
1139
1240
  return undefined;
1140
1241
  }
1141
1242
  async function handleUnifiedTouchStart({ unifiedSession, timeout, frame }, event) {
1142
- const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
1243
+ const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame, true);
1143
1244
  await unifiedSession.touchStart(point.x, point.y);
1144
1245
  return undefined;
1145
1246
  }
1146
1247
  async function handleUnifiedTouchMove({ unifiedSession, timeout, frame }, event) {
1147
- const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
1248
+ const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame, true);
1148
1249
  await unifiedSession.touchMove(point.x, point.y);
1149
1250
  return undefined;
1150
1251
  }
@@ -1152,6 +1253,117 @@ async function handleUnifiedTouchEnd({ unifiedSession }) {
1152
1253
  await unifiedSession.touchEnd();
1153
1254
  return undefined;
1154
1255
  }
1256
+ async function handleUnifiedUpload({ unifiedSession, session, mode, timeout, signal, privacy }, event) {
1257
+ if (privacy) {
1258
+ privacy.sensitive = true;
1259
+ }
1260
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1261
+ const key = `__mcpUpload_${randomUUID()}`;
1262
+ let objectId;
1263
+ let preparationStarted = false;
1264
+ let dispatched = false;
1265
+ const active = () => {
1266
+ signal?.throwIfAborted();
1267
+ unifiedSession.assertRequestActive();
1268
+ return remainingInputTimeout(deadline);
1269
+ };
1270
+ const invoke = async (operation, refId = null, payloads = []) => {
1271
+ const args = [operation, key, refId, deadline, event.files.length, payloads];
1272
+ const budget = active();
1273
+ if (operation === 'commit') {
1274
+ dispatched = true;
1275
+ }
1276
+ if (mode !== 'cdp') {
1277
+ return unifiedSession.evaluate(uploadInPage.toString(), undefined, budget, args, {
1278
+ userAction: operation === 'commit' ? 'input' : undefined,
1279
+ });
1280
+ }
1281
+ const response = await session.send('Runtime.callFunctionOn', {
1282
+ objectId,
1283
+ functionDeclaration: uploadInPage.toString(),
1284
+ arguments: args.map((value) => ({ value })),
1285
+ returnByValue: true,
1286
+ awaitPromise: true,
1287
+ }, budget, operation === 'commit' ? 'input' : undefined);
1288
+ if (response.exceptionDetails || !response.result?.value) {
1289
+ throw new Error('上传脚本没有返回执行状态');
1290
+ }
1291
+ return response.result.value;
1292
+ };
1293
+ const checked = (result) => {
1294
+ if (!result.success) {
1295
+ throw new StructuredToolError('UPLOAD_FAILED', result.error ?? '上传失败', '请核对目标控件和页面状态后重新操作', { actionExecuted: result.actionExecuted, actionStatus: result.actionStatus, retryable: false });
1296
+ }
1297
+ return result;
1298
+ };
1299
+ try {
1300
+ active();
1301
+ let refId = null;
1302
+ if (mode === 'cdp') {
1303
+ const nodeId = await session
1304
+ .createLocator(event.target, { timeout: targetLookupTimeout(active()) })
1305
+ .find();
1306
+ const resolved = await session.send('DOM.resolveNode', { nodeId }, active());
1307
+ objectId = resolved.object.objectId;
1308
+ if (!objectId) {
1309
+ // noinspection ExceptionCaughtLocallyJS
1310
+ throw new Error('上传目标引用已失效');
1311
+ }
1312
+ }
1313
+ else {
1314
+ const params = targetToFindParams(event.target);
1315
+ const elements = await unifiedSession.find(params.selector, params.text, params.xpath, active(), params.semantic, params.nth ?? 0);
1316
+ if (!elements.length) {
1317
+ // noinspection ExceptionCaughtLocallyJS
1318
+ throw new StructuredToolError('TARGET_NOT_FOUND', '未找到上传控件', '请检查 target、frame 和 target.nth', {});
1319
+ }
1320
+ refId = elements[0].refId;
1321
+ }
1322
+ // evaluate 要求受控页面,读取本地文件前确认写权限并固定目标
1323
+ preparationStarted = true;
1324
+ checked(await invoke('prepare', refId));
1325
+ const payloads = await prepareUploadFiles(event.files, deadline, signal);
1326
+ active();
1327
+ const result = checked(await invoke('commit', null, payloads));
1328
+ return { type: 'upload', files: result.files };
1329
+ }
1330
+ catch (error) {
1331
+ const explicit = error instanceof StructuredToolError || error instanceof BrowserError ? error.context : undefined;
1332
+ const actionExecuted = dispatched && explicit?.actionExecuted !== false;
1333
+ throw new StructuredToolError(error instanceof StructuredToolError
1334
+ ? error.code
1335
+ : actionExecuted
1336
+ ? 'UPLOAD_RESULT_UNKNOWN'
1337
+ : 'UPLOAD_PREPARATION_FAILED', actionExecuted && explicit?.actionStatus === undefined
1338
+ ? '上传提交回执未能取得,请核对页面或站点收件结果'
1339
+ : error instanceof Error
1340
+ ? error.message
1341
+ : '上传准备失败', actionExecuted ? '请检查页面实际状态,勿自动重发上传' : '请检查目标、文件和连接后重试', {
1342
+ ...explicit,
1343
+ actionExecuted,
1344
+ actionStatus: actionExecuted ? (explicit?.actionStatus ?? 'unknown') : 'not_started',
1345
+ retryable: false,
1346
+ });
1347
+ }
1348
+ finally {
1349
+ try {
1350
+ if (preparationStarted && Date.now() < deadline && !signal?.aborted) {
1351
+ await invoke('cleanup');
1352
+ }
1353
+ }
1354
+ catch {
1355
+ console.warn('[MCP] Upload target cleanup deferred to page deadline');
1356
+ }
1357
+ if (objectId) {
1358
+ try {
1359
+ await session.send('Runtime.releaseObject', { objectId }, 1000);
1360
+ }
1361
+ catch {
1362
+ console.warn('[MCP] Upload remote object cleanup failed after context loss');
1363
+ }
1364
+ }
1365
+ }
1366
+ }
1155
1367
  async function handleUnifiedType(context, event) {
1156
1368
  const { unifiedSession, humanize, timeout, frame } = context;
1157
1369
  if (event.mode === 'controlled' || event.dispatch) {
@@ -1166,9 +1378,11 @@ async function handleUnifiedType(context, event) {
1166
1378
  }
1167
1379
  }
1168
1380
  else {
1169
- const hasActiveFocus = await unifiedSession.evaluate('!!document.activeElement && ' +
1170
- 'document.activeElement !== document.body && ' +
1171
- 'document.activeElement !== document.documentElement', undefined, remainingInputTimeout(deadline));
1381
+ const hasActiveFocus = await unifiedSession.evaluate(`(() => {
1382
+ (${installDomHelpers.toString()})();
1383
+ const active = globalThis.__mcpDomHelpers.activeElement();
1384
+ return !!active && active !== document.body && active !== document.documentElement;
1385
+ })()`, undefined, remainingInputTimeout(deadline));
1172
1386
  if (!hasActiveFocus) {
1173
1387
  throw new Error('type 事件在无 target 时需要页面已有焦点元素,请提供 target 或先 click 目标元素');
1174
1388
  }
@@ -1194,7 +1408,7 @@ function ensureWaitFitsTimeout(ms, timeout) {
1194
1408
  }
1195
1409
  async function handleUnifiedWait({ timeout }, event) {
1196
1410
  ensureWaitFitsTimeout(event.ms, timeout);
1197
- await new Promise((resolve) => setTimeout(resolve, event.ms));
1411
+ await getUnifiedSession().wait(event.ms);
1198
1412
  return undefined;
1199
1413
  }
1200
1414
  async function handleUnifiedSelect({ unifiedSession, session, mode, timeout, frame, privacy }, event) {
@@ -1205,7 +1419,8 @@ async function handleUnifiedSelect({ unifiedSession, session, mode, timeout, fra
1205
1419
  }
1206
1420
  await focusTargetIfNeeded(unifiedSession, session, mode, event.target, remainingInputTimeout(deadline), frame);
1207
1421
  const selectionTarget = await unifiedSession.evaluate(`(() => {
1208
- const el = document.activeElement;
1422
+ (${installDomHelpers.toString()})();
1423
+ const el = globalThis.__mcpDomHelpers.activeElement();
1209
1424
  if (!(el instanceof HTMLInputElement)) return null;
1210
1425
  return {
1211
1426
  tag: 'input',
@@ -1236,10 +1451,13 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1236
1451
  }
1237
1452
  await focusTargetIfNeeded(unifiedSession, session, mode, event.target, remainingInputTimeout(deadline), frame);
1238
1453
  const directResult = await unifiedSession.evaluate(`function(findText, replacementText, nth) {
1239
- var el = document.activeElement;
1454
+ (${installDomHelpers.toString()})();
1455
+ var el = globalThis.__mcpDomHelpers.activeElement();
1240
1456
  if (!(el instanceof HTMLInputElement)) return {handled: false};
1241
1457
  var type = (el.type || 'text').toLowerCase();
1242
- if (['text', 'search', 'tel', 'url', 'password'].indexOf(type) !== -1) return {handled: false, inputType: type};
1458
+ if (['text', 'search', 'tel', 'url', 'password'].indexOf(type) !== -1) {
1459
+ return {handled: false, inputType: type};
1460
+ }
1243
1461
  var current = String(el.value || '');
1244
1462
  var pos = -1;
1245
1463
  for (var i = 0; i <= nth; i++) {
@@ -1279,7 +1497,7 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1279
1497
  };
1280
1498
  }
1281
1499
  setter.call(el, requested);
1282
- el.dispatchEvent(new Event('input', {bubbles: true}));
1500
+ el.dispatchEvent(new Event('input', {bubbles: true, composed: true}));
1283
1501
  el.dispatchEvent(new Event('change', {bubbles: true}));
1284
1502
  var actual = String(el.value || '');
1285
1503
  return {
@@ -1292,7 +1510,7 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1292
1510
  actualValue: actual.slice(0, 160),
1293
1511
  reason: actual === requested ? undefined : 'value_not_applied'
1294
1512
  };
1295
- }`, undefined, remainingInputTimeout(deadline), [event.find, event.text, event.nth ?? 0]);
1513
+ }`, undefined, remainingInputTimeout(deadline), [event.find, event.text, event.nth ?? 0], { userAction: 'input' });
1296
1514
  if (privacy) {
1297
1515
  privacy.sensitive = sensitiveBefore || directResult.inputType === 'password';
1298
1516
  }
@@ -1332,7 +1550,8 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1332
1550
  let selectionConfirmed = false;
1333
1551
  for (let i = 0; i < 25; i++) {
1334
1552
  const hasSelection = await unifiedSession.evaluate(`(function() {
1335
- var el = document.activeElement;
1553
+ (${installDomHelpers.toString()})();
1554
+ var el = globalThis.__mcpDomHelpers.activeElement();
1336
1555
  if (el && (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA')) {
1337
1556
  return el.selectionStart !== el.selectionEnd;
1338
1557
  }
@@ -1349,11 +1568,12 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1349
1568
  throw new Error(`选区同步失败:文本 "${event.find}" 已定位但未能建立选区,无法执行替换`);
1350
1569
  }
1351
1570
  const replaceResult = await unifiedSession.evaluate(`function(replacementText) {
1352
- var el = document.activeElement;
1571
+ (${installDomHelpers.toString()})();
1572
+ var el = globalThis.__mcpDomHelpers.activeElement();
1353
1573
  if (el && (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') && el.setRangeText) {
1354
1574
  if (el.readOnly || el.disabled) return 'readonly';
1355
1575
  el.setRangeText(replacementText, el.selectionStart, el.selectionEnd, 'end');
1356
- el.dispatchEvent(new Event('input', {bubbles: true}));
1576
+ el.dispatchEvent(new Event('input', {bubbles: true, composed: true}));
1357
1577
  return 'ok';
1358
1578
  }
1359
1579
  var sel = window.getSelection();
@@ -1366,7 +1586,7 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1366
1586
  if (!editable || !editable.isContentEditable) return 'readonly';
1367
1587
  if (document.execCommand('insertText', false, replacementText)) return 'ok';
1368
1588
  return 'fallback';
1369
- }`, undefined, remainingInputTimeout(deadline), [event.text]);
1589
+ }`, undefined, remainingInputTimeout(deadline), [event.text], { userAction: 'input' });
1370
1590
  if (replaceResult === 'readonly') {
1371
1591
  throw new Error(`目标元素不可编辑,已选中文本 "${event.find}" 但无法替换`);
1372
1592
  }
@@ -1407,15 +1627,15 @@ async function handleUnifiedDrag({ unifiedSession, timeout, frame }, event) {
1407
1627
  const srcNth = srcParams.nth ?? 0;
1408
1628
  const dstNth = dstParams.nth ?? 0;
1409
1629
  const attemptDrag = async () => {
1410
- const srcEls = await unifiedSession.find(srcParams.selector, srcParams.text, srcParams.xpath, timeout);
1411
- const dstEls = await unifiedSession.find(dstParams.selector, dstParams.text, dstParams.xpath, timeout);
1412
- if (srcEls.length <= srcNth) {
1413
- throw new StructuredToolError(srcEls.length === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', `drag 源元素未找到: ${JSON.stringify(event.target)}`, '请检查 drag 源 target、frame 和 nth', await buildTargetDiagnosticContext(unifiedSession, event.target, srcEls.length, srcNth, timeout, 'drag 源元素未找到', frame));
1630
+ const srcEls = await unifiedSession.find(srcParams.selector, srcParams.text, srcParams.xpath, timeout, srcParams.semantic, srcNth);
1631
+ const dstEls = await unifiedSession.find(dstParams.selector, dstParams.text, dstParams.xpath, timeout, dstParams.semantic, dstNth);
1632
+ if (srcEls.length === 0) {
1633
+ throw new StructuredToolError(srcNth === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', `drag 源元素未找到: ${JSON.stringify(event.target)}`, '请检查 drag 源 target、frame 和 nth', await buildTargetDiagnosticContext(unifiedSession, event.target, null, srcNth, timeout, 'drag 源元素未找到', frame));
1414
1634
  }
1415
- if (dstEls.length <= dstNth) {
1416
- throw new StructuredToolError(dstEls.length === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', `drag 目标元素未找到: ${JSON.stringify(event.to)}`, '请检查 drag 目标 to、frame 和 nth', await buildTargetDiagnosticContext(unifiedSession, event.to, dstEls.length, dstNth, timeout, 'drag 目标元素未找到', frame));
1635
+ if (dstEls.length === 0) {
1636
+ throw new StructuredToolError(dstNth === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', `drag 目标元素未找到: ${JSON.stringify(event.to)}`, '请检查 drag 目标 to、frame 和 nth', await buildTargetDiagnosticContext(unifiedSession, event.to, null, dstNth, timeout, 'drag 目标元素未找到', frame));
1417
1637
  }
1418
- return unifiedSession.dragAndDrop(srcEls[srcNth].refId, dstEls[dstNth].refId);
1638
+ return unifiedSession.dragAndDrop(srcEls[0].refId, dstEls[0].refId);
1419
1639
  };
1420
1640
  let dragResult = await attemptDrag();
1421
1641
  let retried = false;
@@ -1447,15 +1667,15 @@ async function inputControlled(unifiedSession, event, timeout, frame) {
1447
1667
  if ('x' in event.target && 'y' in event.target) {
1448
1668
  throw new Error('controlled 输入不支持坐标型 target,请使用 CSS 选择器、role 或文本定位');
1449
1669
  }
1450
- const { selector, text: searchText, xpath, nth: nthParam, } = targetToFindParams(event.target);
1451
- const elements = await unifiedSession.find(selector, searchText, xpath, timeout);
1670
+ const { selector, text: searchText, xpath, nth: nthParam, semantic, } = targetToFindParams(event.target);
1452
1671
  const nth = nthParam ?? 0;
1453
- if (elements.length === 0 || nth >= elements.length) {
1454
- throw new StructuredToolError('TARGET_NOT_FOUND', `controlled 输入目标未找到: ${JSON.stringify(event.target)}`, '请检查 target 是否能定位到 input、textarea、select 或 contenteditable 元素;context.candidates 提供当前页面候选元素', await buildTargetDiagnosticContext(unifiedSession, event.target, elements.length, nth, timeout, 'controlled 输入目标未找到', frame));
1672
+ const elements = await unifiedSession.find(selector, searchText, xpath, timeout, semantic, nth);
1673
+ if (elements.length === 0) {
1674
+ throw new StructuredToolError('TARGET_NOT_FOUND', `controlled 输入目标未找到: ${JSON.stringify(event.target)}`, '请检查 target 是否能定位到 input、textarea、select 或 contenteditable 元素;context.candidates 提供当前页面候选元素', await buildTargetDiagnosticContext(unifiedSession, event.target, null, nth, timeout, 'controlled 输入目标未找到', frame));
1455
1675
  }
1456
- const result = await unifiedSession.dispatchInput(elements[nth].refId, event.text ?? '');
1676
+ const result = await unifiedSession.dispatchInput(elements[0].refId, event.text ?? '');
1457
1677
  if (!result.success) {
1458
- throw new StructuredToolError('CONTROLLED_INPUT_FAILED', result.error || 'controlled 输入失败', '请检查目标元素是否可编辑、未 disabled,并确认当前 frame 与 target 匹配', await buildTargetDiagnosticContext(unifiedSession, event.target, elements.length, nth, timeout, result.error || 'controlled 输入失败', frame));
1678
+ throw new StructuredToolError('CONTROLLED_INPUT_FAILED', result.error || 'controlled 输入失败', '请检查目标元素是否可编辑、未 disabled,并确认当前 frame 与 target 匹配', await buildTargetDiagnosticContext(unifiedSession, event.target, null, nth, timeout, result.error || 'controlled 输入失败', frame));
1459
1679
  }
1460
1680
  }
1461
1681
  async function buildTargetDiagnosticContext(unifiedSession, target, matchCount, nth, timeout, reason = '目标元素未找到', frame) {
@@ -1473,7 +1693,8 @@ async function editorAction(unifiedSession, action, event, timeout, frame) {
1473
1693
  await focusTargetForCommands(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
1474
1694
  }
1475
1695
  return unifiedSession.evaluate(`function(action, text, command) {
1476
- var active = document.activeElement;
1696
+ (${installDomHelpers.toString()})();
1697
+ var active = globalThis.__mcpDomHelpers.activeElement();
1477
1698
  var sel = window.getSelection();
1478
1699
  var editable = active;
1479
1700
  if (!editable || editable === document.body || editable === document.documentElement) {
@@ -1519,7 +1740,7 @@ async function editorAction(unifiedSession, action, event, timeout, frame) {
1519
1740
  if (action === 'insert') {
1520
1741
  if (isInput) {
1521
1742
  active.setRangeText(text, active.selectionStart || 0, active.selectionEnd || 0, 'end');
1522
- active.dispatchEvent(new Event('input', {bubbles: true}));
1743
+ active.dispatchEvent(new Event('input', {bubbles: true, composed: true}));
1523
1744
  active.dispatchEvent(new Event('change', {bubbles: true}));
1524
1745
  return {success: true};
1525
1746
  }
@@ -1533,7 +1754,7 @@ async function editorAction(unifiedSession, action, event, timeout, frame) {
1533
1754
  throw new Error('editorCommand 执行失败: ' + command);
1534
1755
  }
1535
1756
  return {success: true, command: command};
1536
- }`, undefined, remainingInputTimeout(deadline), [action, event.text ?? '', event.command ?? '']);
1757
+ }`, undefined, remainingInputTimeout(deadline), [action, event.text ?? '', event.command ?? ''], { userAction: 'input' });
1537
1758
  }
1538
1759
  async function getTargetPointExtension(unifiedSession, target, timeout, frame, scroll = true) {
1539
1760
  const budget = timeout ?? DEFAULT_TIMEOUT;
@@ -1545,66 +1766,162 @@ async function getTargetPointExtension(unifiedSession, target, timeout, frame, s
1545
1766
  }
1546
1767
  return value;
1547
1768
  };
1548
- const frameOffset = unifiedSession.getFrameOffset();
1549
- const isStealth = unifiedSession.getInputMode() === 'stealth';
1550
- // 原始坐标:用户意图为 iframe 相对坐标
1551
1769
  if ('x' in target && 'y' in target) {
1552
- if (frameOffset && !isStealth) {
1553
- // precise: 转为视口绝对坐标
1554
- return { x: target.x + frameOffset.x, y: target.y + frameOffset.y };
1555
- }
1556
1770
  return { x: target.x, y: target.y };
1557
1771
  }
1558
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
1559
- const elements = await unifiedSession.find(selector, text, xpath, remaining());
1772
+ const { selector, text, xpath, nth: nthParam, semantic } = targetToFindParams(target);
1560
1773
  const nth = nthParam ?? 0;
1774
+ const elements = await unifiedSession.find(selector, text, xpath, remaining(), semantic, nth);
1561
1775
  if (elements.length === 0) {
1562
- throw new StructuredToolError('TARGET_NOT_FOUND', `未找到目标元素: ${JSON.stringify(target)}`, '请检查 target 是否正确,或先用 extract type=state 查看 interactiveElements 候选', await buildTargetDiagnosticContext(unifiedSession, target, elements.length, nth, timeout, '目标元素未找到', frame));
1563
- }
1564
- if (nth >= elements.length) {
1565
- throw new StructuredToolError('TARGET_INDEX_OUT_OF_RANGE', `第 ${nth} 个匹配元素不存在(共 ${elements.length} 个)`, '请降低 nth,或先用 extract type=state 查看当前匹配到的候选元素', await buildTargetDiagnosticContext(unifiedSession, target, elements.length, nth, timeout, '目标元素序号越界', frame));
1776
+ throw new StructuredToolError(nth === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', `未找到目标元素: ${JSON.stringify(target)}`, '请检查 target 是否正确,或先用 extract type=state 查看 interactiveElements 候选', await buildTargetDiagnosticContext(unifiedSession, target, null, nth, timeout, '目标元素未找到', frame));
1566
1777
  }
1567
1778
  // 视口外时滚动后重新取 rect:与 actionableClick (left+single) 行为对齐,
1568
1779
  // 否则非左键 / 多击的坐标路径在视口外坐标 dispatch,浏览器找不到元素,事件丢失
1569
- const refId = elements[nth].refId;
1570
- const iframeRelRect = await unifiedSession.evaluate(`(() => {
1780
+ const refId = elements[0].refId;
1781
+ let rect = await unifiedSession.evaluate(`(async () => {
1571
1782
  const ref = window.__mcpElementMap?.[${JSON.stringify(refId)}];
1572
1783
  const el = ref?.deref();
1573
- if (!el) return null;
1784
+ if (!el || !el.isConnected || el.ownerDocument !== document) return null;
1574
1785
  const r = el.getBoundingClientRect();
1575
- if (${scroll} && (r.top < 0 || r.bottom > window.innerHeight || r.left < 0 || r.right > window.innerWidth)) {
1786
+ if (${scroll} && (r.top < 0 || r.bottom > window.innerHeight ||
1787
+ r.left < 0 || r.right > window.innerWidth)) {
1788
+ const positions = [];
1789
+ for (let node = el; node; node = node.assignedSlot || node.parentElement || node.getRootNode?.().host) {
1790
+ if (node !== document.scrollingElement) {
1791
+ positions.push({ target: node, x: node.scrollLeft, y: node.scrollTop });
1792
+ }
1793
+ }
1794
+ positions.push({ target: document, x: window.scrollX, y: window.scrollY });
1576
1795
  el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
1796
+ const changed = positions.filter(({ target, x, y }) => target === document
1797
+ ? x !== window.scrollX || y !== window.scrollY
1798
+ : x !== target.scrollLeft || y !== target.scrollTop);
1799
+ if (changed.length) {
1800
+ const channel = new MessageChannel();
1801
+ const scrollTargets = new Set([window, document, ...positions.flatMap(({ target }) =>
1802
+ [target, target.getRootNode?.() || document]),
1803
+ ...globalThis.__mcpDomHelpers.elements().flatMap(node => node.shadowRoot ? [node.shadowRoot] : [])]);
1804
+ let timer, frame, visibilityChanged, scrollChanged, scrollEnded;
1805
+ try {
1806
+ await new Promise((resolve, reject) => {
1807
+ let turn = 0, previous;
1808
+ const scrollPosition = target => target === document
1809
+ ? [window.scrollX, window.scrollY] : [target.scrollLeft, target.scrollTop];
1810
+ const observedScroll = new Map();
1811
+ scrollChanged = event => {
1812
+ const { target } = event, last = observedScroll.get(target);
1813
+ if (last?.event === event && last.listenerTarget !== event.currentTarget) return;
1814
+ if (!last || positions.some(position => position.target === target)) previous = undefined;
1815
+ const offset = scrollPosition(target);
1816
+ const offsets = last?.offsets || new Set();
1817
+ offsets.add(offset.join(','));
1818
+ observedScroll.set(target, { event, listenerTarget: event.currentTarget, offset, offsets });
1819
+ };
1820
+ scrollEnded = ({ target }) => {
1821
+ const last = observedScroll.get(target), offset = scrollPosition(target);
1822
+ if (last && offset.some((value, index) => value !== last.offset[index]) &&
1823
+ (positions.some(position => position.target === target) || !last.offsets.has(offset.join(',')))) {
1824
+ previous = undefined;
1825
+ }
1826
+ };
1827
+ const observeScroll = target => {
1828
+ target.addEventListener('scroll', scrollChanged, true);
1829
+ target.addEventListener('scrollend', scrollEnded, true);
1830
+ };
1831
+ for (const target of scrollTargets) observeScroll(target);
1832
+ const schedule = () => {
1833
+ const currentTurn = ++turn;
1834
+ if (frame !== undefined) cancelAnimationFrame(frame);
1835
+ frame = undefined;
1836
+ if (document.visibilityState === 'visible') {
1837
+ frame = requestAnimationFrame(() => {
1838
+ channel.port2.postMessage({ turn: currentTurn, rendered: true });
1839
+ });
1840
+ } else {
1841
+ channel.port2.postMessage({ turn: currentTurn, rendered: false });
1842
+ }
1843
+ };
1844
+ channel.port1.onmessage = ({ data }) => {
1845
+ if (data.turn !== turn) return;
1846
+ for (const node of globalThis.__mcpDomHelpers.elements()) {
1847
+ if (node.shadowRoot && !scrollTargets.has(node.shadowRoot)) {
1848
+ scrollTargets.add(node.shadowRoot);
1849
+ observeScroll(node.shadowRoot);
1850
+ previous = undefined;
1851
+ }
1852
+ }
1853
+ if (document.visibilityState === 'visible') {
1854
+ if (!data.rendered) {
1855
+ schedule();
1856
+ return;
1857
+ }
1858
+ const bounds = el.getBoundingClientRect();
1859
+ const current = [...positions.flatMap(({ target }) => scrollPosition(target)),
1860
+ bounds.x, bounds.y, bounds.width, bounds.height];
1861
+ if (!previous || !current.every((value, index) => value === previous[index])) {
1862
+ previous = current;
1863
+ schedule();
1864
+ return;
1865
+ }
1866
+ }
1867
+ resolve();
1868
+ };
1869
+ visibilityChanged = schedule;
1870
+ document.addEventListener('visibilitychange', visibilityChanged);
1871
+ schedule();
1872
+ timer = setTimeout(() => reject(new Error(
1873
+ 'SCROLL_SETTLEMENT_TIMEOUT: rendering did not finish before the request deadline'
1874
+ )), Math.max(1, ${deadline} - Date.now()));
1875
+ });
1876
+ } finally {
1877
+ clearTimeout(timer);
1878
+ if (frame !== undefined) cancelAnimationFrame(frame);
1879
+ if (visibilityChanged) document.removeEventListener('visibilitychange', visibilityChanged);
1880
+ if (scrollChanged) {
1881
+ for (const target of scrollTargets) {
1882
+ target.removeEventListener('scroll', scrollChanged, true);
1883
+ target.removeEventListener('scrollend', scrollEnded, true);
1884
+ }
1885
+ }
1886
+ channel.port1.close();
1887
+ channel.port2.close();
1888
+ }
1889
+ }
1577
1890
  }
1578
- const r2 = el.getBoundingClientRect();
1579
- return { x: r2.x, y: r2.y, width: r2.width, height: r2.height };
1891
+ if (!el.isConnected || el.ownerDocument !== document) return null;
1892
+ const current = el.getBoundingClientRect();
1893
+ return { x: current.x, y: current.y, width: current.width, height: current.height };
1580
1894
  })()`, undefined, remaining());
1581
1895
  remaining();
1582
- if (!iframeRelRect) {
1896
+ if (!rect) {
1583
1897
  throw new StructuredToolError('TARGET_NOT_FOUND', '目标元素引用已失效,未使用旧坐标派发事件', '请重新读取页面并确认 target', { target, refId, actionExecuted: false });
1584
1898
  }
1585
- // 主 frame:iframeRelRect 就是父视口绝对
1586
- if (!frameOffset) {
1587
- return {
1588
- x: iframeRelRect.x + iframeRelRect.width / 2,
1589
- y: iframeRelRect.y + iframeRelRect.height / 2,
1590
- refId,
1591
- };
1592
- }
1593
- // iframe + stealth:消费者(chrome.scripting in iframe)需要 iframe 相对
1594
- if (isStealth) {
1595
- return {
1596
- x: iframeRelRect.x + iframeRelRect.width / 2,
1597
- y: iframeRelRect.y + iframeRelRect.height / 2,
1598
- refId,
1599
- };
1899
+ if (frame !== undefined && scroll) {
1900
+ const refreshed = await unifiedSession.find(selector, text, xpath, remaining(), semantic, nth);
1901
+ if (!refreshed[0] || refreshed[0].refId !== refId) {
1902
+ throw new StructuredToolError('TARGET_NOT_FOUND', '滚动后目标元素已失效', '重新读取目标元素', {
1903
+ actionExecuted: false,
1904
+ });
1905
+ }
1906
+ rect = await unifiedSession.evaluate(`(() => {
1907
+ const el = window.__mcpElementMap?.[${JSON.stringify(refId)}]?.deref();
1908
+ if (!el || !el.isConnected || el.ownerDocument !== document) return null;
1909
+ const r = el.getBoundingClientRect();
1910
+ return { x: r.x, y: r.y, width: r.width, height: r.height };
1911
+ })()`, undefined, remaining());
1912
+ if (!rect) {
1913
+ throw new StructuredToolError('TARGET_NOT_FOUND', '最终定位时目标元素已失效', '重新读取目标元素', {
1914
+ target,
1915
+ refId,
1916
+ actionExecuted: false,
1917
+ });
1918
+ }
1600
1919
  }
1601
- // iframe + precise:消费者(chrome.debugger)需要父视口绝对,
1602
- // scrollIntoView({block:'center'}) 会 cascade 到父框架,导致 frameOffset 与父绝对 rect 都过期,
1603
- // refetch find() 让 content-handler 重新计算 frameOffset 并返回最新父绝对 rect
1604
- const refreshed = await unifiedSession.find(selector, text, xpath, remaining());
1605
- remaining();
1606
- const rect = refreshed[nth]?.rect ?? elements[nth].rect;
1607
- return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2, refId };
1920
+ return {
1921
+ x: rect.x + rect.width / 2,
1922
+ y: rect.y + rect.height / 2,
1923
+ refId,
1924
+ };
1608
1925
  }
1609
1926
  async function executeCdpEvent(session, event, humanize, timeout) {
1610
1927
  validateEvent(event);
@@ -1640,7 +1957,9 @@ async function handleCdpClick({ session, humanize, timeout }, event) {
1640
1957
  const masks = {left: 1, middle: 4, right: 2, back: 8, forward: 16};
1641
1958
  const rect = this.getBoundingClientRect();
1642
1959
  const base = {bubbles: true, cancelable: true, composed: true, view: window,
1643
- button: codes[button], clientX: rect.x + rect.width / 2, clientY: rect.y + rect.height / 2};
1960
+ button: codes[button], clientX: rect.x + rect.width / 2, clientY: rect.y + rect.height / 2,
1961
+ altKey: ${Boolean(session.getModifiers() & 1)}, ctrlKey: ${Boolean(session.getModifiers() & 2)},
1962
+ metaKey: ${Boolean(session.getModifiers() & 4)}, shiftKey: ${Boolean(session.getModifiers() & 8)}};
1644
1963
  for (let detail = 1; detail <= count; ++detail) {
1645
1964
  const down = this.dispatchEvent(new MouseEvent('mousedown', {...base, detail, buttons: masks[button]}));
1646
1965
  if (down && button === 'left' && typeof this.focus === 'function') this.focus();
@@ -1722,9 +2041,11 @@ async function handleCdpType({ session, humanize, timeout }, event) {
1722
2041
  }
1723
2042
  }
1724
2043
  else {
1725
- const hasActiveFocus = await session.evaluate('!!document.activeElement && ' +
1726
- 'document.activeElement !== document.body && ' +
1727
- 'document.activeElement !== document.documentElement', undefined, remainingInputTimeout(deadline));
2044
+ const hasActiveFocus = await session.evaluate(`(() => {
2045
+ (${installDomHelpers.toString()})();
2046
+ const active = globalThis.__mcpDomHelpers.activeElement();
2047
+ return !!active && active !== document.body && active !== document.documentElement;
2048
+ })()`, undefined, remainingInputTimeout(deadline));
1728
2049
  if (!hasActiveFocus) {
1729
2050
  throw new Error('type 事件在无 target 时需要页面已有焦点元素,请提供 target 或先 click 目标元素');
1730
2051
  }
@@ -1744,7 +2065,7 @@ async function handleCdpType({ session, humanize, timeout }, event) {
1744
2065
  }
1745
2066
  async function handleCdpWait({ timeout }, event) {
1746
2067
  ensureWaitFitsTimeout(event.ms, timeout);
1747
- await new Promise((resolve) => setTimeout(resolve, event.ms));
2068
+ await getUnifiedSession().wait(event.ms);
1748
2069
  }
1749
2070
  async function handleCdpDrag() {
1750
2071
  throw new Error('drag 事件仅在 Extension 模式下可用,当前为 CDP 模式');
@@ -1785,9 +2106,10 @@ async function moveToTarget(session, target, humanize, timeout, steps, waitType
1785
2106
  * 获取目标点坐标(带自动等待)
1786
2107
  */
1787
2108
  async function getTargetPoint(session, target, timeout, waitType = 'click') {
1788
- // 如果是坐标,直接返回
1789
2109
  if ('x' in target && 'y' in target) {
1790
- return { x: target.x, y: target.y };
2110
+ return session
2111
+ .createLocator(target, { timeout: targetLookupTimeout(timeout ?? DEFAULT_TIMEOUT) })
2112
+ .getClickablePoint();
1791
2113
  }
1792
2114
  const budget = timeout ?? DEFAULT_TIMEOUT;
1793
2115
  const deadline = Date.now() + budget;
@@ -1822,7 +2144,9 @@ async function getTargetPoint(session, target, timeout, waitType = 'click') {
1822
2144
  export function registerInputTool(server) {
1823
2145
  server.registerTool('input', {
1824
2146
  description: [
1825
- '键鼠输入:键盘、鼠标及任意组合。默认优先使用已连接的 Chrome Extension;',
2147
+ '键鼠输入及文件上传:键盘、鼠标及任意组合。网页上传优先使用本工具的 upload 事件,',
2148
+ 'files 支持绝对、相对及 ~/ 路径,沿用当前页面与 Extension/CDP 连接,总大小严格小于 50 MiB;',
2149
+ '默认优先使用已连接的 Chrome Extension;',
1826
2150
  '只有 Extension 不可用或 browse(action="connect", port=…) 已显式选择 CDP 时才使用 CDP。',
1827
2151
  '访问 Cloudflare 时默认不传 diagnostics,Extension 先被动等待真实 tab 标题恢复,',
1828
2152
  '持续存在可点击 Turnstile 时才点击。同页测试按钮走页面点击;',
@@ -1856,11 +2180,13 @@ export function registerInputTool(server) {
1856
2180
  type: {events:[{type:"type",target:{css:"input[name=q]"},text:"hello"}]}
1857
2181
  controlled type: {events:[{type:"type",mode:"controlled",target:{css:"input[name=q]"},text:"hello"}]}
1858
2182
  replace: {events:[{type:"replace",target:{css:"textarea"},find:"old",text:"new"}]}
2183
+ upload: {events:[{type:"upload",target:{css:"input[type=file]"},files:["./attachment.zip"]}]}
2184
+ 文件路径在 Server 机器上解析;files:[] 清空选择,总大小须小于 50 MiB;合成 input/change 事件不保证站点已收件,使用 postCondition 验证
1859
2185
  注意:纯键盘事件(不带 commands)仅保证 JS keyboard event 可被监听,不保证触发浏览器原生编辑行为;
1860
2186
  全选/复制/粘贴等语义用 commands;"全选并替换文本"用 select/replace 事件更简洁;
1861
2187
  commands 成功表示浏览器已接受命令分发,页面结果需用 postCondition 或 extract 验证;
1862
2188
  commands 仅支持 inputMode=precise,stealth 模式下会报错`,
1863
2189
  inputSchema: inputSchema,
1864
- }, (args) => handleInput(args));
2190
+ }, (args, extra) => handleInput(args, extra?.signal));
1865
2191
  }
1866
2192
  //# sourceMappingURL=input.js.map