@pyrokine/mcp-chrome 3.0.1 → 3.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/README.md +1060 -432
  2. package/README_zh.md +936 -349
  3. package/dist/cdp/client.d.ts +8 -3
  4. package/dist/cdp/client.d.ts.map +1 -1
  5. package/dist/cdp/client.js +260 -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 +73 -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 +105 -0
  22. package/dist/core/browser-events.d.ts.map +1 -0
  23. package/dist/core/browser-events.js +1482 -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 +231 -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/error-sanitizer.d.ts.map +1 -1
  34. package/dist/core/error-sanitizer.js +2 -1
  35. package/dist/core/error-sanitizer.js.map +1 -1
  36. package/dist/core/errors.d.ts +4 -0
  37. package/dist/core/errors.d.ts.map +1 -1
  38. package/dist/core/errors.js +57 -9
  39. package/dist/core/errors.js.map +1 -1
  40. package/dist/core/file-upload.d.ts +22 -0
  41. package/dist/core/file-upload.d.ts.map +1 -0
  42. package/dist/core/file-upload.js +194 -0
  43. package/dist/core/file-upload.js.map +1 -0
  44. package/dist/core/locator.d.ts +11 -2
  45. package/dist/core/locator.d.ts.map +1 -1
  46. package/dist/core/locator.js +135 -206
  47. package/dist/core/locator.js.map +1 -1
  48. package/dist/core/os-mouse.d.ts +11 -0
  49. package/dist/core/os-mouse.d.ts.map +1 -1
  50. package/dist/core/os-mouse.js +104 -29
  51. package/dist/core/os-mouse.js.map +1 -1
  52. package/dist/core/retry.d.ts.map +1 -1
  53. package/dist/core/retry.js +4 -1
  54. package/dist/core/retry.js.map +1 -1
  55. package/dist/core/session.d.ts +62 -12
  56. package/dist/core/session.d.ts.map +1 -1
  57. package/dist/core/session.js +1174 -304
  58. package/dist/core/session.js.map +1 -1
  59. package/dist/core/types.d.ts +5 -1
  60. package/dist/core/types.d.ts.map +1 -1
  61. package/dist/core/types.js +16 -1
  62. package/dist/core/types.js.map +1 -1
  63. package/dist/core/unified-session.d.ts +48 -37
  64. package/dist/core/unified-session.d.ts.map +1 -1
  65. package/dist/core/unified-session.js +982 -294
  66. package/dist/core/unified-session.js.map +1 -1
  67. package/dist/core/utils.d.ts +8 -4
  68. package/dist/core/utils.d.ts.map +1 -1
  69. package/dist/core/utils.js +76 -18
  70. package/dist/core/utils.js.map +1 -1
  71. package/dist/extension/bridge.d.ts +48 -17
  72. package/dist/extension/bridge.d.ts.map +1 -1
  73. package/dist/extension/bridge.js +288 -46
  74. package/dist/extension/bridge.js.map +1 -1
  75. package/dist/extension/http-server.d.ts +8 -2
  76. package/dist/extension/http-server.d.ts.map +1 -1
  77. package/dist/extension/http-server.js +211 -49
  78. package/dist/extension/http-server.js.map +1 -1
  79. package/dist/index.js +15 -1
  80. package/dist/index.js.map +1 -1
  81. package/dist/tools/browse.d.ts.map +1 -1
  82. package/dist/tools/browse.js +56 -28
  83. package/dist/tools/browse.js.map +1 -1
  84. package/dist/tools/browser-event-output.d.ts +7 -0
  85. package/dist/tools/browser-event-output.d.ts.map +1 -0
  86. package/dist/tools/browser-event-output.js +19 -0
  87. package/dist/tools/browser-event-output.js.map +1 -0
  88. package/dist/tools/challenge.d.ts +18 -5
  89. package/dist/tools/challenge.d.ts.map +1 -1
  90. package/dist/tools/challenge.js +217 -200
  91. package/dist/tools/challenge.js.map +1 -1
  92. package/dist/tools/cookies.d.ts.map +1 -1
  93. package/dist/tools/cookies.js +34 -8
  94. package/dist/tools/cookies.js.map +1 -1
  95. package/dist/tools/diagnostics.d.ts.map +1 -1
  96. package/dist/tools/diagnostics.js +15 -0
  97. package/dist/tools/diagnostics.js.map +1 -1
  98. package/dist/tools/evaluate.d.ts +6 -5
  99. package/dist/tools/evaluate.d.ts.map +1 -1
  100. package/dist/tools/evaluate.js +94 -52
  101. package/dist/tools/evaluate.js.map +1 -1
  102. package/dist/tools/extract.d.ts.map +1 -1
  103. package/dist/tools/extract.js +293 -153
  104. package/dist/tools/extract.js.map +1 -1
  105. package/dist/tools/input.d.ts.map +1 -1
  106. package/dist/tools/input.js +747 -282
  107. package/dist/tools/input.js.map +1 -1
  108. package/dist/tools/logs.d.ts.map +1 -1
  109. package/dist/tools/logs.js +50 -11
  110. package/dist/tools/logs.js.map +1 -1
  111. package/dist/tools/manage.d.ts.map +1 -1
  112. package/dist/tools/manage.js +123 -18
  113. package/dist/tools/manage.js.map +1 -1
  114. package/dist/tools/network-sanitizer.d.ts +2 -0
  115. package/dist/tools/network-sanitizer.d.ts.map +1 -1
  116. package/dist/tools/network-sanitizer.js +53 -10
  117. package/dist/tools/network-sanitizer.js.map +1 -1
  118. package/dist/tools/page-context.d.ts +4 -3
  119. package/dist/tools/page-context.d.ts.map +1 -1
  120. package/dist/tools/page-context.js +57 -14
  121. package/dist/tools/page-context.js.map +1 -1
  122. package/dist/tools/png.d.ts.map +1 -1
  123. package/dist/tools/png.js +12 -3
  124. package/dist/tools/png.js.map +1 -1
  125. package/dist/tools/post-condition.d.ts +1 -1
  126. package/dist/tools/post-condition.d.ts.map +1 -1
  127. package/dist/tools/post-condition.js +163 -47
  128. package/dist/tools/post-condition.js.map +1 -1
  129. package/dist/tools/schema.d.ts +7 -4
  130. package/dist/tools/schema.d.ts.map +1 -1
  131. package/dist/tools/schema.js +32 -122
  132. package/dist/tools/schema.js.map +1 -1
  133. package/dist/tools/target-diagnostics.d.ts +3 -3
  134. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  135. package/dist/tools/target-diagnostics.js +64 -34
  136. package/dist/tools/target-diagnostics.js.map +1 -1
  137. package/dist/tools/wait.d.ts.map +1 -1
  138. package/dist/tools/wait.js +94 -40
  139. package/dist/tools/wait.js.map +1 -1
  140. package/extension/dist/assets/{content.ts-qe6IB5DK.js → content.ts-C9QgtUYe.js} +1 -1
  141. package/extension/dist/assets/{content.ts-loader-DUWbDHRS.js → content.ts-loader-yqB_P8vu.js} +1 -1
  142. package/extension/dist/assets/index.ts-DBFNh8mZ.js +20275 -0
  143. package/extension/dist/assets/{page-scripts-D508WLkW.js → page-scripts-BjqQ0zXt.js} +258 -367
  144. package/extension/dist/assets/{popup.html-B-eVq48O.js → popup.html-DwwHo00N.js} +2 -2
  145. package/extension/dist/manifest.json +4 -4
  146. package/extension/dist/service-worker-loader.js +1 -1
  147. package/extension/dist/src/popup/popup.html +3 -3
  148. package/package.json +9 -7
  149. package/scripts/start-chrome.ps1 +9 -1
  150. package/extension/dist/assets/index.ts-D7_LCUoV.js +0 -9319
@@ -8,16 +8,19 @@
8
8
  * - 支持任意组合:Ctrl+Alt+A+左键+右键+拖拽
9
9
  * - humanize 可选:行为模拟是可选功能
10
10
  */
11
+ import { randomUUID } from 'node:crypto';
11
12
  import { z } from 'zod';
12
13
  import { generateBezierPath, getMouseMoveDelay, getTypingDelay, randomDelay } from '../anti-detection/index.js';
14
+ import { installDomHelpers } from '../core/dom-helpers.js';
15
+ import { BrowserError, ElementNotFoundError, getErrorPageContext, isNativeExecutionResultUnknown, StructuredToolError, TimeoutError, } from '../core/errors.js';
16
+ import { prepareUploadFiles, uploadInPage } from '../core/file-upload.js';
13
17
  import { formatErrorResponse, formatResponse, getSession, getUnifiedSession } from '../core/index.js';
14
- import { ElementNotFoundError, StructuredToolError, TimeoutError } from '../core/errors.js';
15
18
  import { DEFAULT_TIMEOUT } from '../core/types.js';
16
- import { ChallengeDeniedError, ChallengeTimeoutError, resolveChallenge } from './challenge.js';
19
+ import { ChallengeDeniedError, challengeResultFields, ChallengeTimeoutError, resolveChallenge } from './challenge.js';
17
20
  import { appendDiagnostics, finishDiagnostics, startDiagnostics } from './diagnostics.js';
18
21
  import { withPageContext } from './page-context.js';
19
22
  import { postConditionSchema, waitForPostCondition } from './post-condition.js';
20
- import { pageConditionSchema, pageTargetIdSchema, resolvePageTargetId, targetToFindParams, targetZodSchema, } from './schema.js';
23
+ import { frameZodSchema, pageConditionSchema, pageTargetIdSchema, resolvePageTargetId, targetToFindParams, targetZodSchema, } from './schema.js';
21
24
  import { buildTargetDiagnostics, enrichTargetError, targetLookupTimeout } from './target-diagnostics.js';
22
25
  const INPUT_WAIT_MAX_MS = 60_000;
23
26
  const TEXT_SELECTION_INPUT_TYPES = new Set(['text', 'search', 'tel', 'url', 'password']);
@@ -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);
286
- }
287
- else if (result) {
288
- eventResults.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
+ }
289
307
  }
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);
@@ -317,28 +333,83 @@ async function handleInput(args) {
317
333
  try {
318
334
  const payload = JSON.parse(text);
319
335
  const message = error instanceof Error ? error.message : String(error);
336
+ const inputActionAcknowledged = getErrorPageContext(error)?.inputActionAcknowledged === true;
320
337
  const timedOut = /timeout|超时/i.test(message);
321
- const preActionTimeout = /timeout before event dispatch|超过 input 剩余 timeout/i.test(message);
322
- actionMayHaveExecuted = timedOut && !preActionTimeout;
323
- const preconditionFailed = error !== null &&
338
+ const preActionTimeout = /timeout.*before|超过 input 剩余 timeout/i.test(message);
339
+ actionMayHaveExecuted =
340
+ isNativeExecutionResultUnknown(error) || (timedOut && !preActionTimeout);
341
+ const preconditionFailed = !inputActionAcknowledged &&
342
+ error !== null &&
324
343
  typeof error === 'object' &&
325
344
  'code' in error &&
326
345
  error.code === 'ACTION_PRECONDITION_FAILED';
327
- actionMayHaveExecuted = actionMayHaveExecuted && !preconditionFailed;
328
- progress.actionStatus =
329
- preconditionFailed && eventsExecuted === 0
346
+ const executionContext = error instanceof StructuredToolError || error instanceof BrowserError
347
+ ? error.context
348
+ : undefined;
349
+ const contextPhase = getErrorPageContext(error)?.contextPhase;
350
+ const preparationFailure = !inputActionAcknowledged &&
351
+ (contextPhase === 'preparation' || contextPhase === 'precondition');
352
+ const explicitNotStarted = !inputActionAcknowledged &&
353
+ (preparationFailure || executionContext?.actionExecuted === false);
354
+ actionExecutedUnknown =
355
+ !explicitNotStarted && executionContext?.actionExecuted === 'unknown';
356
+ actionMayHaveExecuted =
357
+ (actionMayHaveExecuted ||
358
+ actionExecutedUnknown ||
359
+ executionContext?.actionExecuted === true ||
360
+ inputActionAcknowledged) &&
361
+ !preconditionFailed &&
362
+ !explicitNotStarted;
363
+ const cleanupFailure = progress.actionStatus === 'completed';
364
+ const keyboardFocusCleanup = getErrorPageContext(error)?.keyboardFocusCleanup ??
365
+ executionContext?.keyboardFocusCleanup;
366
+ if (keyboardFocusCleanup) {
367
+ payload.keyboardFocusCleanup = keyboardFocusCleanup;
368
+ }
369
+ const keyboardWarning = getErrorPageContext(error)?.keyboardFocusWarning;
370
+ if (typeof keyboardWarning === 'string' &&
371
+ !warnings.includes(keyboardWarning)) {
372
+ warnings.push(keyboardWarning);
373
+ }
374
+ if (warnings.length) {
375
+ payload.warnings = warnings;
376
+ }
377
+ if (cleanupFailure) {
378
+ actionMayHaveExecuted = true;
379
+ }
380
+ progress.actionStatus = cleanupFailure
381
+ ? 'completed'
382
+ : (preconditionFailed ||
383
+ preparationFailure ||
384
+ (explicitNotStarted &&
385
+ executionContext?.actionStatus === 'not_started')) &&
386
+ eventsExecuted === 0
330
387
  ? 'not_started'
331
- : actionMayHaveExecuted
388
+ : actionMayHaveExecuted && executionContext?.actionStatus !== 'failed'
332
389
  ? 'unknown'
333
390
  : 'failed';
334
391
  payload.eventsExecuted = eventsExecuted;
335
- payload.actionExecuted = eventsExecuted > 0 || actionMayHaveExecuted;
392
+ payload.actionExecuted =
393
+ eventsExecuted > 0 || inputActionAcknowledged
394
+ ? true
395
+ : actionExecutedUnknown
396
+ ? 'unknown'
397
+ : actionMayHaveExecuted;
336
398
  payload.actionStatus = progress.actionStatus;
337
399
  payload.verificationRequested = Boolean(args.postCondition);
338
400
  payload.verificationStatus = 'unavailable';
339
- payload.failureStage = 'action';
401
+ if (preparationFailure) {
402
+ payload.remainingEventsNotExecuted = args.events.length - eventsExecuted;
403
+ }
404
+ payload.failureStage = preparationFailure
405
+ ? contextPhase === 'precondition'
406
+ ? 'precondition'
407
+ : 'context'
408
+ : (executionContext?.failureStage ?? 'action');
340
409
  payload.retryable =
341
- eventsExecuted === 0 &&
410
+ !preparationFailure &&
411
+ executionContext?.retryable !== false &&
412
+ eventsExecuted === 0 &&
342
413
  !actionMayHaveExecuted &&
343
414
  /timeout|超时|disconnect|未连接|context|debugger/i.test(message);
344
415
  appendDiagnostics(payload, await finishDiagnostics(unifiedSession, diagnostics, deadline));
@@ -351,8 +422,19 @@ async function handleInput(args) {
351
422
  return response;
352
423
  }
353
424
  progress.actionStatus = 'completed';
425
+ failureStage = 'verification';
426
+ if (deadline === undefined || Date.now() < deadline) {
427
+ Object.assign(challengeFields, challengeResultFields(await resolveChallenge(unifiedSession, 'input', 'completed', deadline === undefined ? undefined : remainingInputTimeout(deadline))));
428
+ }
429
+ else {
430
+ Object.assign(challengeFields, {
431
+ challengeVerificationStatus: 'unavailable',
432
+ challengeVerificationError: '输入已确认完成,剩余 timeout 已用尽',
433
+ });
434
+ }
354
435
  failureStage = 'context';
355
436
  const result = {
437
+ ...challengeFields,
356
438
  success: true,
357
439
  eventsExecuted,
358
440
  mode,
@@ -370,11 +452,10 @@ async function handleInput(args) {
370
452
  }
371
453
  if (args.postCondition) {
372
454
  failureStage = 'verification';
373
- const postCondition = await waitForPostCondition(unifiedSession, args.postCondition, 'input');
455
+ const postCondition = await waitForPostCondition(unifiedSession, args.postCondition, 'input', undefined, deadline, signal);
374
456
  failureStage = 'context';
375
457
  result.postCondition = postCondition;
376
458
  result.verificationStatus = postCondition.verificationStatus;
377
- result.retryable = postCondition.retryable;
378
459
  if (postCondition.verificationStatus !== 'matched') {
379
460
  result.success = false;
380
461
  result.failureStage = 'verification';
@@ -382,8 +463,8 @@ async function handleInput(args) {
382
463
  }
383
464
  appendDiagnostics(result, await finishDiagnostics(unifiedSession, diagnostics, deadline));
384
465
  return formatResponse(result);
385
- }, deadline), deadline); // withPageCondition, withFrame
386
- }, deadline); // withTabId
466
+ }, deadline), deadline); // withPageCondition, withFrame, withInputCleanup
467
+ }, deadline, signal, 'input'); // withTabId
387
468
  return sanitizeInputResponse(response, args.events, privacy.sensitive);
388
469
  }
389
470
  catch (error) {
@@ -406,18 +487,46 @@ async function handleInput(args) {
406
487
  typeof error === 'object' &&
407
488
  'code' in error &&
408
489
  error.code === 'ACTION_PRECONDITION_FAILED');
490
+ const executionContext = error instanceof StructuredToolError || error instanceof BrowserError ? error.context : undefined;
491
+ const challengeFailure = error instanceof ChallengeTimeoutError || error instanceof ChallengeDeniedError ? error : null;
492
+ const contextPhase = getErrorPageContext(error)?.contextPhase;
493
+ const preparationFailure = progress.actionStatus === 'not_started' &&
494
+ (contextPhase === 'before' || contextPhase === 'precondition' || contextPhase === 'preparation');
409
495
  Object.assign(payload, {
496
+ ...challengeFields,
410
497
  eventsExecuted,
411
- actionExecuted: eventsExecuted > 0 || actionMayHaveExecuted,
412
- actionStatus: preconditionFailed && eventsExecuted === 0
498
+ remainingEventsNotExecuted: args.events.length - eventsExecuted,
499
+ actionExecuted: preparationFailure
500
+ ? false
501
+ : eventsExecuted > 0
502
+ ? true
503
+ : actionExecutedUnknown || executionContext?.actionExecuted === 'unknown'
504
+ ? 'unknown'
505
+ : executionContext?.actionExecuted === true || actionMayHaveExecuted,
506
+ actionStatus: preparationFailure
413
507
  ? 'not_started'
414
- : progress.actionStatus === 'not_started'
415
- ? 'failed'
416
- : progress.actionStatus,
508
+ : progress.actionStatus === 'completed'
509
+ ? 'completed'
510
+ : preconditionFailed && eventsExecuted === 0
511
+ ? 'not_started'
512
+ : challengeFailure
513
+ ? challengeFailure.actionStatus
514
+ : (executionContext?.actionStatus ??
515
+ (progress.actionStatus === 'not_started' ? 'failed' : progress.actionStatus)),
417
516
  verificationRequested: Boolean(args.postCondition),
418
- verificationStatus: 'unavailable',
419
- failureStage: unavailableCondition ? 'precondition' : failureStage,
420
- retryable: progress.actionStatus !== 'completed' &&
517
+ verificationStatus: challengeFailure
518
+ ? payload.verificationStatus
519
+ : (executionContext?.verificationStatus ?? 'unavailable'),
520
+ failureStage: preparationFailure
521
+ ? contextPhase === 'precondition'
522
+ ? 'precondition'
523
+ : 'context'
524
+ : unavailableCondition
525
+ ? 'precondition'
526
+ : (executionContext?.failureStage ?? failureStage),
527
+ retryable: !preparationFailure &&
528
+ executionContext?.retryable !== false &&
529
+ progress.actionStatus !== 'completed' &&
421
530
  eventsExecuted === 0 &&
422
531
  !actionMayHaveExecuted &&
423
532
  !preconditionFailed &&
@@ -428,7 +537,7 @@ async function handleInput(args) {
428
537
  payload.diagnosticsError =
429
538
  eventsExecuted > 0 || actionMayHaveExecuted
430
539
  ? 'input 执行后未能取得 diagnostics'
431
- : 'diagnostics 未能在 tab/frame 初始化失败前启动';
540
+ : 'input 开始前未能完成 diagnostics';
432
541
  }
433
542
  response.content[0].text = JSON.stringify(payload, null, 2);
434
543
  }
@@ -440,6 +549,7 @@ async function handleInput(args) {
440
549
  }
441
550
  }
442
551
  const unifiedOnlyEventTypes = new Set([
552
+ 'upload',
443
553
  'keydown',
444
554
  'keyup',
445
555
  'select',
@@ -460,14 +570,16 @@ async function executeInputEvent(context, event) {
460
570
  humanize: context.humanize,
461
571
  timeout: context.timeout,
462
572
  frame: context.frame,
573
+ signal: context.signal,
463
574
  privacy: context.privacy,
464
575
  }, event);
465
576
  }
466
577
  if (!context.session) {
578
+ // noinspection ExceptionCaughtLocallyJS -- Report failure
467
579
  throw new Error('CDP 输入事件缺少 session');
468
580
  }
469
- await executeCdpEvent(context.session, event, context.humanize, context.timeout);
470
- return undefined;
581
+ const warning = await executeCdpEvent(context.session, event, context.humanize, context.timeout);
582
+ return typeof warning === 'string' ? warning : undefined;
471
583
  }
472
584
  catch (error) {
473
585
  if (context.mode === 'cdp' && error instanceof ElementNotFoundError) {
@@ -496,27 +608,26 @@ async function focusTargetForCommands(unifiedSession, target, timeout, frame) {
496
608
  return;
497
609
  }
498
610
  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
611
  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));
612
+ const els = 'x' in target && 'y' in target
613
+ ? await unifiedSession.findAtPoint(target.x, target.y, nth0, remainingInputTimeout(deadline), 'frame')
614
+ : await unifiedSession.find(params.selector, params.text, params.xpath, remainingInputTimeout(deadline), params.semantic, nth0, 'frame');
615
+ if (els.length === 0) {
616
+ 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
617
  }
508
618
  const focused = await unifiedSession.evaluate(`(() => {
509
619
  if (Date.now() >= ${deadline}) throw new Error('input timeout before command focus')
510
- const ref = window.__mcpElementMap?.[${JSON.stringify(els[nth0].refId)}]
620
+ const ref = window.__mcpElementMap?.[${JSON.stringify(els[0].refId)}]
511
621
  const el = ref?.deref()
512
622
  if (!(el instanceof HTMLElement)) {
513
623
  return false
514
624
  }
625
+ (${installDomHelpers.toString()})();
515
626
  el.focus({preventScroll: true})
516
- return document.activeElement === el
627
+ return globalThis.__mcpDomHelpers.activeElement() === el
517
628
  })()`, undefined, remainingInputTimeout(deadline));
518
629
  if (focused !== true) {
519
- throw new StructuredToolError('TARGET_FOCUS_FAILED', '命令目标未成功聚焦', '请检查目标是否可编辑、未 disabled 并处于正确 frame', await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, remainingInputTimeout(deadline), '命令目标聚焦失败', frame));
630
+ throw new StructuredToolError('TARGET_FOCUS_FAILED', '命令目标未成功聚焦', '请检查目标是否可编辑、未 disabled 并处于正确 frame', await buildTargetDiagnosticContext(unifiedSession, target, null, nth0, remainingInputTimeout(deadline), '命令目标聚焦失败', frame));
520
631
  }
521
632
  }
522
633
  export async function focusCdpTarget(session, target, timeout) {
@@ -524,12 +635,14 @@ export async function focusCdpTarget(session, target, timeout) {
524
635
  const focus = `function() {
525
636
  if (Date.now() >= ${deadline}) throw new Error('input timeout before command focus');
526
637
  if (!(this instanceof HTMLElement)) return false;
638
+ (${installDomHelpers.toString()})();
527
639
  this.focus({preventScroll: true});
528
- return document.activeElement === this;
640
+ return globalThis.__mcpDomHelpers.activeElement() === this;
529
641
  }`;
530
642
  const focused = 'x' in target && 'y' in target
531
643
  ? await session.evaluate(`(() => {
532
- const el = document.elementFromPoint(${target.x}, ${target.y});
644
+ (${installDomHelpers.toString()})();
645
+ const el = globalThis.__mcpDomHelpers.deepElementFromPoint(${target.x}, ${target.y});
533
646
  return el ? (${focus}).call(el) : null;
534
647
  })()`, undefined, remainingInputTimeout(deadline))
535
648
  : await session
@@ -567,24 +680,24 @@ async function focusTargetIfNeeded(unifiedSession, session, mode, target, timeou
567
680
  return;
568
681
  }
569
682
  const params = targetToFindParams(target);
570
- const els = await unifiedSession.find(params.selector, params.text, params.xpath, remainingInputTimeout(deadline));
571
683
  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));
684
+ const els = await unifiedSession.find(params.selector, params.text, params.xpath, remainingInputTimeout(deadline), params.semantic, nth0, 'frame');
685
+ if (els.length === 0) {
686
+ 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
687
  }
577
688
  remainingInputTimeout(deadline);
578
- const result = await unifiedSession.actionableClick(els[nth0].refId);
689
+ const result = await unifiedSession.actionableClick(els[0].refId);
579
690
  if (!result.success) {
580
691
  throw new StructuredToolError('ACTIONABILITY_FAILED', result.error || '目标元素无法聚焦', result.suggestions?.[0] ?? '请检查元素是否可见、未被遮挡并处于正确 frame', {
581
692
  ...result,
582
- ...(await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, timeout, result.error || '目标元素无法聚焦', frame)),
693
+ ...(await buildTargetDiagnosticContext(unifiedSession, target, null, nth0, timeout, result.error || '目标元素无法聚焦', frame)),
583
694
  });
584
695
  }
585
696
  }
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) {
697
+ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, occurrenceNth, scopeNth, scopeSelector, scopeText, scopeXpath, scopeSemantic, timeout) {
698
+ return await unifiedSession.evaluate(`function(findText, occurrenceNth, scopeNth, scopeTarget, scopeSelector, scopeText, scopeXpath, scopeSemantic) {
699
+ (${installDomHelpers.toString()})();
700
+ var helpers = globalThis.__mcpDomHelpers;
588
701
  function selectorFor(el) {
589
702
  if (!(el instanceof Element)) return null;
590
703
  if (el.id) return '#' + CSS.escape(el.id);
@@ -631,29 +744,18 @@ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTa
631
744
  hasValue: value.length > 0,
632
745
  redacted: sensitive || undefined,
633
746
  visible: rect.width > 0 && rect.height > 0,
634
- disabled: Boolean(el.disabled),
747
+ disabled: el.matches(':disabled') || Boolean(el.disabled),
635
748
  readOnly: Boolean(el.readOnly),
636
749
  contentEditable: Boolean(el.isContentEditable),
637
750
  bounds: {x: rect.x, y: rect.y, width: rect.width, height: rect.height}
638
751
  };
639
752
  }
640
- 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];
753
+ var point = scopeTarget && 'x' in scopeTarget && 'y' in scopeTarget ? scopeTarget : null;
754
+ var root = point ? helpers.deepElementFromPoint(point.x, point.y) : document.body;
755
+ if (!point && (scopeXpath || scopeSelector || scopeText || scopeSemantic)) {
756
+ root = helpers.query({
757
+ selector:scopeSelector, text:scopeText, xpath:scopeXpath, semantic:scopeSemantic
758
+ })[scopeNth];
657
759
  }
658
760
  var candidateElements = [];
659
761
  if (root instanceof Element) {
@@ -661,10 +763,10 @@ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTa
661
763
  var candidateSelector =
662
764
  'input, textarea, [contenteditable="true"], [role="textbox"], button, a';
663
765
  candidateElements = candidateElements.concat(
664
- Array.from(root.querySelectorAll(candidateSelector)).slice(0, 12)
766
+ helpers.query({selector:candidateSelector}, root).slice(0, 12)
665
767
  );
666
768
  }
667
- var active = document.activeElement;
769
+ var active = helpers.activeElement();
668
770
  var activeIsPassword =
669
771
  active instanceof HTMLInputElement &&
670
772
  (active.type || 'text').toLowerCase() === 'password';
@@ -698,7 +800,40 @@ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTa
698
800
  },
699
801
  candidates: candidateElements.map(summarizeElement).filter(Boolean)
700
802
  };
701
- }`, undefined, timeout, [findText, occurrenceNth, scopeNth, scopeTarget ?? null, scopeSelector, scopeText, scopeXpath]);
803
+ }`, undefined, timeout, [findText, occurrenceNth, scopeNth, scopeTarget ?? null, scopeSelector, scopeText, scopeXpath, scopeSemantic]);
804
+ }
805
+ function ownsTextSelection(scopeRefId, findText) {
806
+ const reference = window.__mcpElementMap?.[scopeRefId];
807
+ const scope = reference?.deref();
808
+ const original = reference?.selection;
809
+ if (!scope || !scope.isConnected || !original) {
810
+ return false;
811
+ }
812
+ const helpers = globalThis.__mcpDomHelpers;
813
+ const active = helpers.activeElement();
814
+ if (active instanceof HTMLInputElement || active instanceof HTMLTextAreaElement) {
815
+ return (active === scope &&
816
+ active.selectionStart !== null &&
817
+ active.selectionEnd !== null &&
818
+ active.selectionStart === original.startOffset &&
819
+ active.selectionEnd === original.endOffset &&
820
+ active.selectionStart !== active.selectionEnd &&
821
+ active.value.slice(active.selectionStart, active.selectionEnd) === findText);
822
+ }
823
+ const selection = window.getSelection();
824
+ const range = selection?.rangeCount === 1 ? selection.getRangeAt(0) : null;
825
+ const anchor = selection?.anchorNode;
826
+ const focus = selection?.focusNode;
827
+ return Boolean(selection &&
828
+ !selection.isCollapsed &&
829
+ range &&
830
+ range.startContainer === original.startContainer?.deref() &&
831
+ range.endContainer === original.endContainer?.deref() &&
832
+ range.startOffset === original.startOffset &&
833
+ range.endOffset === original.endOffset &&
834
+ range.toString() === findText &&
835
+ helpers.containsComposed(scope, anchor instanceof Element ? anchor : (anchor?.parentElement ?? null)) &&
836
+ helpers.containsComposed(scope, focus instanceof Element ? focus : (focus?.parentElement ?? null)));
702
837
  }
703
838
  async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeout, privacy) {
704
839
  const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
@@ -710,35 +845,50 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
710
845
  let scopeSelector = null;
711
846
  let scopeText = null;
712
847
  let scopeXpath = null;
848
+ let scopeSemantic = null;
713
849
  let scopeNth = 0;
714
850
  if (scopeTarget && !('x' in scopeTarget) && !('y' in scopeTarget)) {
715
851
  const params = targetToFindParams(scopeTarget);
716
852
  scopeSelector = params.selector ?? null;
717
853
  scopeText = params.text ?? null;
718
854
  scopeXpath = params.xpath ?? null;
855
+ scopeSemantic = params.semantic ?? null;
719
856
  scopeNth = params.nth ?? 0;
720
857
  }
721
858
  // Step 1: 注入脚本定位文本
722
859
  //noinspection SpellCheckingInspection -- 模板中的坐标字段名
723
- const result = await unifiedSession.evaluate(`function(findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath) {
724
- // 确定搜索根节点
725
- 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
- });
860
+ const result = await unifiedSession.evaluate(`function(findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath,
861
+ scopeSemantic, scopePoint, selectionId) {
862
+ (${installDomHelpers.toString()})();
863
+ var helpers = globalThis.__mcpDomHelpers;
864
+ function rememberScope(element, selectionRange) {
865
+ var refs = window.__mcpElementMap || (window.__mcpElementMap = {});
866
+ var reverse = window.__mcpElementToRefId || (window.__mcpElementToRefId = new WeakMap());
867
+ var refId = reverse.get(element) || selectionId;
868
+ reverse.set(element, refId);
869
+ var reference = new WeakRef(element);
870
+ if (typeof element.selectionStart === 'number' && typeof element.selectionEnd === 'number') {
871
+ reference.selection = {
872
+ startOffset: element.selectionStart,
873
+ endOffset: element.selectionEnd
874
+ };
875
+ } else if (selectionRange) {
876
+ reference.selection = {
877
+ startContainer: new WeakRef(selectionRange.startContainer),
878
+ endContainer: new WeakRef(selectionRange.endContainer),
879
+ startOffset: selectionRange.startOffset,
880
+ endOffset: selectionRange.endOffset
881
+ };
735
882
  }
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];
883
+ refs[refId] = reference;
884
+ return refId;
885
+ }
886
+ // 坐标目标与选择器目标分别限定搜索范围
887
+ var root = scopePoint ? helpers.deepElementFromPoint(scopePoint.x, scopePoint.y) : document.body;
888
+ if (!scopePoint && (scopeXpath || scopeSelector || scopeText || scopeSemantic)) {
889
+ root = helpers.query({
890
+ selector:scopeSelector, text:scopeText, xpath:scopeXpath, semantic:scopeSemantic
891
+ })[scopeNth];
742
892
  }
743
893
  if (!root) return {type: 'noscope'};
744
894
 
@@ -765,12 +915,16 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
765
915
  }
766
916
  // 原子化:定位到 input 同时完成 focus + setSelectionRange,避免外层 mouseClick 聚焦不可靠
767
917
  root.focus();
918
+ if (root.isConnected === false || helpers.activeElement() !== root) return {type: 'noscope'};
768
919
  root.setSelectionRange(pos, pos + findText.length);
769
- return {type: 'input', inputType: inputType, selectionStart: pos, selectionEnd: pos + findText.length};
920
+ return {
921
+ type: 'input', inputType: inputType, scopeRefId: rememberScope(root),
922
+ selectionStart: pos, selectionEnd: pos + findText.length
923
+ };
770
924
  }
771
925
 
772
926
  // 在子树中查找 input/textarea
773
- var inputs = root.querySelectorAll('input, textarea');
927
+ var inputs = helpers.query({selector:'input, textarea'}, root);
774
928
  for (var k = 0; k < inputs.length; k++) {
775
929
  var inp = inputs[k];
776
930
  var v = inp.value || '';
@@ -793,22 +947,32 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
793
947
  }
794
948
  if (ip !== -1) {
795
949
  inp.focus();
950
+ if (inp.isConnected === false || helpers.activeElement() !== inp) return {type: 'noscope'};
796
951
  inp.setSelectionRange(ip, ip + findText.length);
797
- return {type: 'input', inputType: childType, selectionStart: ip, selectionEnd: ip + findText.length};
952
+ return {
953
+ type: 'input', inputType: childType, scopeRefId: rememberScope(inp),
954
+ selectionStart: ip, selectionEnd: ip + findText.length
955
+ };
798
956
  }
799
957
  }
800
958
 
801
959
  // DOM 文本节点:TreeWalker 遍历(限制规模防止大 DOM 阻塞)
802
960
  var MAX_TEXT_NODES = 10000;
803
961
  var MAX_TEXT_LENGTH = 500000;
804
- var walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
962
+ var pendingNodes = [root];
805
963
  var textNodes = [];
806
964
  var fullText = '';
807
- var node;
808
- while (node = walker.nextNode()) {
965
+ while (pendingNodes.length) {
809
966
  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;
967
+ var node = pendingNodes.pop();
968
+ if (node.nodeType === Node.TEXT_NODE) {
969
+ textNodes.push({node: node, start: fullText.length, length: node.textContent.length});
970
+ fullText += node.textContent;
971
+ } else {
972
+ var children = Array.from(node.childNodes);
973
+ for (var ci = children.length - 1; ci >= 0; --ci) pendingNodes.push(children[ci]);
974
+ if (node.shadowRoot) pendingNodes.push(node.shadowRoot);
975
+ }
812
976
  }
813
977
 
814
978
  // 查找第 nth 个匹配
@@ -850,28 +1014,39 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
850
1014
  formatted = startNode.tagName.toLowerCase();
851
1015
  }
852
1016
 
1017
+ var selectionRange = document.createRange();
1018
+ selectionRange.setStart(s.node, s.offset);
1019
+ selectionRange.setEnd(e.node, Math.min(e.offset + 1, e.node.textContent.length));
853
1020
  // contenteditable 使用 DOM Range 建立精确选区;CDP 的 Shift+Click 会把整个编辑区选中。
854
1021
  if (root instanceof HTMLElement && root.isContentEditable) {
855
1022
  var selection = window.getSelection();
856
1023
  if (!selection) return {type: 'notfound'};
857
- var selectionRange = document.createRange();
858
- selectionRange.setStart(s.node, s.offset);
859
- selectionRange.setEnd(e.node, Math.min(e.offset + 1, e.node.textContent.length));
860
1024
  root.focus();
861
1025
  selection.removeAllRanges();
862
1026
  selection.addRange(selectionRange);
863
- return {type: 'range', formatted: formatted || undefined};
1027
+ return {type: 'range', scopeRefId: rememberScope(root, selectionRange), formatted: formatted || undefined};
864
1028
  }
865
1029
 
866
1030
  return {
867
1031
  type: 'coords',
1032
+ scopeRefId: rememberScope(root, selectionRange),
868
1033
  startX: sr.x + 1,
869
1034
  startY: sr.y + sr.height / 2,
870
1035
  endX: er.x + er.width - 1,
871
1036
  endY: er.y + er.height / 2,
872
1037
  formatted: formatted || undefined
873
1038
  };
874
- }`, undefined, remainingInputTimeout(deadline), [findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath]);
1039
+ }`, undefined, remainingInputTimeout(deadline), [
1040
+ findText,
1041
+ nth,
1042
+ scopeNth,
1043
+ scopeSelector,
1044
+ scopeText,
1045
+ scopeXpath,
1046
+ scopeSemantic,
1047
+ scopeTarget && 'x' in scopeTarget && 'y' in scopeTarget ? scopeTarget : null,
1048
+ `selection-${randomUUID()}`,
1049
+ ], { userAction: 'input' });
875
1050
  if (privacy &&
876
1051
  result &&
877
1052
  result.type !== 'noscope' &&
@@ -879,7 +1054,7 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
879
1054
  privacy.sensitive = sensitiveBefore || ('inputType' in result && result.inputType === 'password');
880
1055
  }
881
1056
  if (!result || result.type === 'noscope') {
882
- const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, timeout);
1057
+ const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, scopeSemantic, timeout);
883
1058
  throw new StructuredToolError('TEXT_SCOPE_NOT_FOUND', `未找到目标元素: ${JSON.stringify(scopeTarget)}`, '请检查 target 是否能定位到包含目标文本的元素,或先用 extract(state) 查看可交互元素', diagnostics);
884
1059
  }
885
1060
  if (result.type === 'unsupported') {
@@ -892,28 +1067,23 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
892
1067
  });
893
1068
  }
894
1069
  if (result.type === 'notfound') {
895
- const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, timeout);
1070
+ const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, scopeSemantic, timeout);
896
1071
  throw new StructuredToolError('TEXT_NOT_FOUND', scopeTarget
897
1072
  ? `目标元素内未找到文本 "${findText}"${nth > 0 ? `(第 ${nth} 个匹配)` : ''}`
898
1073
  : `未找到文本: "${findText}"${nth > 0 ? `(第 ${nth} 个匹配)` : ''}`, '请检查 find 文本、nth 序号和 target 范围;context.candidates 提供了当前范围内的候选文本和 selector', diagnostics);
899
1074
  }
1075
+ if (result.type === 'input' || result.type === 'range') {
1076
+ unifiedSession.acknowledgeInputAction();
1077
+ }
900
1078
  if (result.type === 'input') {
901
- // 注入脚本已完成 focus + setSelectionRange(原子化,避免外层 mouseClick 聚焦不可靠)
902
- return undefined;
1079
+ // 注入脚本已完成 focus + setSelectionRange,并保留后续写入所需的目标身份
1080
+ return { scopeRefId: result.scopeRefId };
903
1081
  }
904
1082
  if (result.type === 'range') {
905
- return result.formatted;
1083
+ return { scopeRefId: result.scopeRefId, formatted: result.formatted };
906
1084
  }
907
1085
  // DOM 文本节点:鼠标选择
908
1086
  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
1087
  // Step 2: 模拟鼠标选择
918
1088
  await unifiedSession.mouseMove(coords.startX, coords.startY, remainingInputTimeout(deadline));
919
1089
  remainingInputTimeout(deadline);
@@ -935,7 +1105,7 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
935
1105
  throw error;
936
1106
  }
937
1107
  await unifiedSession.keyUp('Shift');
938
- return coords.formatted;
1108
+ return { scopeRefId: coords.scopeRefId, formatted: coords.formatted };
939
1109
  }
940
1110
  /**
941
1111
  * 验证事件参数(两种执行模式共享),避免在 Extension/CDP 两个 switch 中重复校验
@@ -972,6 +1142,14 @@ function validateEvent(event) {
972
1142
  requiredEventParam(event, 'text');
973
1143
  }
974
1144
  break;
1145
+ case 'upload':
1146
+ if (!event.target ||
1147
+ 'x' in event.target ||
1148
+ !Array.isArray(event.files) ||
1149
+ event.files.some((path) => typeof path !== 'string' || !path)) {
1150
+ throw new StructuredToolError('INVALID_ARGUMENT', 'upload 需要元素 target 和 files 路径数组,空数组用于清空选择', '请指定 input[type=file] 的 CSS、label、XPath 或其他元素定位', { actionExecuted: false, actionStatus: 'not_started' });
1151
+ }
1152
+ break;
975
1153
  case 'select':
976
1154
  if (!event.find) {
977
1155
  requiredEventParam(event, 'find');
@@ -1030,6 +1208,7 @@ const unifiedInputHandlers = {
1030
1208
  touchmove: handleUnifiedTouchMove,
1031
1209
  touchend: handleUnifiedTouchEnd,
1032
1210
  type: handleUnifiedType,
1211
+ upload: handleUnifiedUpload,
1033
1212
  wait: handleUnifiedWait,
1034
1213
  select: handleUnifiedSelect,
1035
1214
  replace: handleUnifiedReplace,
@@ -1050,12 +1229,15 @@ async function handleUnifiedKeyDown({ unifiedSession, timeout, frame }, event) {
1050
1229
  await focusTargetForCommands(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
1051
1230
  }
1052
1231
  remainingInputTimeout(deadline);
1232
+ const warning = await unifiedSession.prepareKeyboardFocus(remainingInputTimeout(deadline));
1053
1233
  await unifiedSession.keyDown(event.key, event.commands, remainingInputTimeout(deadline));
1054
- return undefined;
1234
+ return warning;
1055
1235
  }
1056
1236
  async function handleUnifiedKeyUp({ unifiedSession, timeout }, event) {
1057
- await unifiedSession.keyUp(event.key, timeout);
1058
- return undefined;
1237
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1238
+ const warning = await unifiedSession.prepareKeyboardFocus(remainingInputTimeout(deadline));
1239
+ await unifiedSession.keyUp(event.key, remainingInputTimeout(deadline));
1240
+ return warning;
1059
1241
  }
1060
1242
  async function handleUnifiedClick({ unifiedSession, humanize, timeout, frame }, event) {
1061
1243
  const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
@@ -1083,6 +1265,7 @@ async function handleUnifiedClick({ unifiedSession, humanize, timeout, frame },
1083
1265
  throw new StructuredToolError('ACTIONABILITY_FAILED', result.error || 'Click failed', result.suggestions?.[0] ??
1084
1266
  '请根据 context.rect、context.clickPoint 和 context.coveringElement 调整 target', result);
1085
1267
  }
1268
+ return result.warning;
1086
1269
  }
1087
1270
  else {
1088
1271
  await unifiedSession.mouseClick(button, clickCount);
@@ -1122,29 +1305,31 @@ async function handleUnifiedMouseMove({ unifiedSession, humanize, timeout, frame
1122
1305
  }
1123
1306
  async function handleUnifiedWheel({ unifiedSession, timeout, frame }, event) {
1124
1307
  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));
1308
+ let point;
1309
+ if (event.target && 'x' in event.target && 'y' in event.target) {
1310
+ point = { x: event.target.x, y: event.target.y };
1311
+ }
1312
+ else if (event.target) {
1313
+ const { selector, text, xpath, nth: nthParam, semantic, } = targetToFindParams(event.target);
1128
1314
  const nth = nthParam ?? 0;
1129
- if (elements.length > nth) {
1315
+ const elements = await unifiedSession.find(selector, text, xpath, remainingInputTimeout(deadline), semantic, nth, 'frame');
1316
+ if (elements.length > 0) {
1130
1317
  remainingInputTimeout(deadline);
1131
- await unifiedSession.scroll(event.deltaX ?? 0, event.deltaY ?? 0, elements[nth].refId);
1318
+ await unifiedSession.scroll(event.deltaX ?? 0, event.deltaY ?? 0, elements[0].refId);
1132
1319
  return undefined;
1133
1320
  }
1134
- const point = await getTargetPointExtension(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
1135
- await unifiedSession.mouseMove(point.x, point.y, remainingInputTimeout(deadline));
1321
+ point = await getTargetPointExtension(unifiedSession, event.target, remainingInputTimeout(deadline), frame, true);
1136
1322
  }
1137
- remainingInputTimeout(deadline);
1138
- await unifiedSession.mouseWheel(event.deltaX ?? 0, event.deltaY ?? 0);
1323
+ await unifiedSession.mouseWheel(event.deltaX ?? 0, event.deltaY ?? 0, remainingInputTimeout(deadline), point);
1139
1324
  return undefined;
1140
1325
  }
1141
1326
  async function handleUnifiedTouchStart({ unifiedSession, timeout, frame }, event) {
1142
- const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
1327
+ const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame, true);
1143
1328
  await unifiedSession.touchStart(point.x, point.y);
1144
1329
  return undefined;
1145
1330
  }
1146
1331
  async function handleUnifiedTouchMove({ unifiedSession, timeout, frame }, event) {
1147
- const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
1332
+ const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame, true);
1148
1333
  await unifiedSession.touchMove(point.x, point.y);
1149
1334
  return undefined;
1150
1335
  }
@@ -1152,6 +1337,117 @@ async function handleUnifiedTouchEnd({ unifiedSession }) {
1152
1337
  await unifiedSession.touchEnd();
1153
1338
  return undefined;
1154
1339
  }
1340
+ async function handleUnifiedUpload({ unifiedSession, session, mode, timeout, signal, privacy }, event) {
1341
+ if (privacy) {
1342
+ privacy.sensitive = true;
1343
+ }
1344
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1345
+ const key = `__mcpUpload_${randomUUID()}`;
1346
+ let objectId;
1347
+ let preparationStarted = false;
1348
+ let dispatched = false;
1349
+ const active = () => {
1350
+ signal?.throwIfAborted();
1351
+ unifiedSession.assertRequestActive();
1352
+ return remainingInputTimeout(deadline);
1353
+ };
1354
+ const invoke = async (operation, refId = null, payloads = []) => {
1355
+ const args = [operation, key, refId, deadline, event.files.length, payloads];
1356
+ const budget = active();
1357
+ if (operation === 'commit') {
1358
+ dispatched = true;
1359
+ }
1360
+ if (mode !== 'cdp') {
1361
+ return unifiedSession.evaluate(uploadInPage.toString(), undefined, budget, args, {
1362
+ userAction: operation === 'commit' ? 'input' : undefined,
1363
+ });
1364
+ }
1365
+ const response = await session.send('Runtime.callFunctionOn', {
1366
+ objectId,
1367
+ functionDeclaration: uploadInPage.toString(),
1368
+ arguments: args.map((value) => ({ value })),
1369
+ returnByValue: true,
1370
+ awaitPromise: true,
1371
+ }, budget, operation === 'commit' ? 'input' : undefined);
1372
+ if (response.exceptionDetails || !response.result?.value) {
1373
+ throw new Error('上传脚本没有返回执行状态');
1374
+ }
1375
+ return response.result.value;
1376
+ };
1377
+ const checked = (result) => {
1378
+ if (!result.success) {
1379
+ throw new StructuredToolError('UPLOAD_FAILED', result.error ?? '上传失败', '请核对目标控件和页面状态后重新操作', { actionExecuted: result.actionExecuted, actionStatus: result.actionStatus, retryable: false });
1380
+ }
1381
+ return result;
1382
+ };
1383
+ try {
1384
+ active();
1385
+ let refId = null;
1386
+ if (mode === 'cdp') {
1387
+ const nodeId = await session
1388
+ .createLocator(event.target, { timeout: targetLookupTimeout(active()) })
1389
+ .find();
1390
+ const resolved = await session.send('DOM.resolveNode', { nodeId }, active());
1391
+ objectId = resolved.object.objectId;
1392
+ if (!objectId) {
1393
+ // noinspection ExceptionCaughtLocallyJS
1394
+ throw new Error('上传目标引用已失效');
1395
+ }
1396
+ }
1397
+ else {
1398
+ const params = targetToFindParams(event.target);
1399
+ const elements = await unifiedSession.find(params.selector, params.text, params.xpath, active(), params.semantic, params.nth ?? 0, 'frame');
1400
+ if (!elements.length) {
1401
+ // noinspection ExceptionCaughtLocallyJS
1402
+ throw new StructuredToolError('TARGET_NOT_FOUND', '未找到上传控件', '请检查 target、frame 和 target.nth', {});
1403
+ }
1404
+ refId = elements[0].refId;
1405
+ }
1406
+ // evaluate 要求受控页面,读取本地文件前确认写权限并固定目标
1407
+ preparationStarted = true;
1408
+ checked(await invoke('prepare', refId));
1409
+ const payloads = await prepareUploadFiles(event.files, deadline, signal);
1410
+ active();
1411
+ const result = checked(await invoke('commit', null, payloads));
1412
+ return { type: 'upload', files: result.files };
1413
+ }
1414
+ catch (error) {
1415
+ const explicit = error instanceof StructuredToolError || error instanceof BrowserError ? error.context : undefined;
1416
+ const actionExecuted = dispatched && explicit?.actionExecuted !== false;
1417
+ throw new StructuredToolError(error instanceof StructuredToolError
1418
+ ? error.code
1419
+ : actionExecuted
1420
+ ? 'UPLOAD_RESULT_UNKNOWN'
1421
+ : 'UPLOAD_PREPARATION_FAILED', actionExecuted && explicit?.actionStatus === undefined
1422
+ ? '上传提交回执未能取得,请核对页面或站点收件结果'
1423
+ : error instanceof Error
1424
+ ? error.message
1425
+ : '上传准备失败', actionExecuted ? '请检查页面实际状态,勿自动重发上传' : '请检查目标、文件和连接后重试', {
1426
+ ...explicit,
1427
+ actionExecuted,
1428
+ actionStatus: actionExecuted ? (explicit?.actionStatus ?? 'unknown') : 'not_started',
1429
+ retryable: false,
1430
+ });
1431
+ }
1432
+ finally {
1433
+ try {
1434
+ if (preparationStarted && Date.now() < deadline && !signal?.aborted) {
1435
+ await invoke('cleanup');
1436
+ }
1437
+ }
1438
+ catch {
1439
+ console.warn('[MCP] Upload target cleanup deferred to page deadline');
1440
+ }
1441
+ if (objectId) {
1442
+ try {
1443
+ await session.send('Runtime.releaseObject', { objectId }, 1000);
1444
+ }
1445
+ catch {
1446
+ console.warn('[MCP] Upload remote object cleanup failed after context loss');
1447
+ }
1448
+ }
1449
+ }
1450
+ }
1155
1451
  async function handleUnifiedType(context, event) {
1156
1452
  const { unifiedSession, humanize, timeout, frame } = context;
1157
1453
  if (event.mode === 'controlled' || event.dispatch) {
@@ -1159,20 +1455,23 @@ async function handleUnifiedType(context, event) {
1159
1455
  return undefined;
1160
1456
  }
1161
1457
  const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1458
+ if (!event.target) {
1459
+ const hasActiveFocus = await unifiedSession.evaluate(`(() => {
1460
+ (${installDomHelpers.toString()})();
1461
+ const active = globalThis.__mcpDomHelpers.activeElement();
1462
+ return !!active && active !== document.body && active !== document.documentElement;
1463
+ })()`, undefined, remainingInputTimeout(deadline));
1464
+ if (!hasActiveFocus) {
1465
+ throw new Error('type 事件在无 target 时需要页面已有焦点元素,请提供 target 或先 click 目标元素');
1466
+ }
1467
+ }
1468
+ const warning = await unifiedSession.prepareKeyboardFocus(remainingInputTimeout(deadline));
1162
1469
  if (event.target) {
1163
1470
  await handleUnifiedClick({ ...context, timeout: remainingInputTimeout(deadline) }, { type: 'click', target: event.target });
1164
1471
  if (!('x' in event.target)) {
1165
1472
  await focusTargetForCommands(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
1166
1473
  }
1167
1474
  }
1168
- else {
1169
- const hasActiveFocus = await unifiedSession.evaluate('!!document.activeElement && ' +
1170
- 'document.activeElement !== document.body && ' +
1171
- 'document.activeElement !== document.documentElement', undefined, remainingInputTimeout(deadline));
1172
- if (!hasActiveFocus) {
1173
- throw new Error('type 事件在无 target 时需要页面已有焦点元素,请提供 target 或先 click 目标元素');
1174
- }
1175
- }
1176
1475
  const delay = event.delay ?? 0;
1177
1476
  if (humanize) {
1178
1477
  for (const char of event.text.replace(/\r\n?/g, '\n')) {
@@ -1185,7 +1484,7 @@ async function handleUnifiedType(context, event) {
1185
1484
  else {
1186
1485
  await unifiedSession.typeText(event.text, delay, remainingInputTimeout(deadline));
1187
1486
  }
1188
- return undefined;
1487
+ return warning;
1189
1488
  }
1190
1489
  function ensureWaitFitsTimeout(ms, timeout) {
1191
1490
  if (timeout !== undefined && ms > timeout) {
@@ -1194,7 +1493,7 @@ function ensureWaitFitsTimeout(ms, timeout) {
1194
1493
  }
1195
1494
  async function handleUnifiedWait({ timeout }, event) {
1196
1495
  ensureWaitFitsTimeout(event.ms, timeout);
1197
- await new Promise((resolve) => setTimeout(resolve, event.ms));
1496
+ await getUnifiedSession().wait(event.ms);
1198
1497
  return undefined;
1199
1498
  }
1200
1499
  async function handleUnifiedSelect({ unifiedSession, session, mode, timeout, frame, privacy }, event) {
@@ -1205,7 +1504,8 @@ async function handleUnifiedSelect({ unifiedSession, session, mode, timeout, fra
1205
1504
  }
1206
1505
  await focusTargetIfNeeded(unifiedSession, session, mode, event.target, remainingInputTimeout(deadline), frame);
1207
1506
  const selectionTarget = await unifiedSession.evaluate(`(() => {
1208
- const el = document.activeElement;
1507
+ (${installDomHelpers.toString()})();
1508
+ const el = globalThis.__mcpDomHelpers.activeElement();
1209
1509
  if (!(el instanceof HTMLInputElement)) return null;
1210
1510
  return {
1211
1511
  tag: 'input',
@@ -1235,11 +1535,20 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1235
1535
  privacy.sensitive = true;
1236
1536
  }
1237
1537
  await focusTargetIfNeeded(unifiedSession, session, mode, event.target, remainingInputTimeout(deadline), frame);
1238
- const directResult = await unifiedSession.evaluate(`function(findText, replacementText, nth) {
1239
- var el = document.activeElement;
1538
+ const directResult = await unifiedSession.evaluate(`function(findText, replacementText, nth, point, scopeQuery) {
1539
+ (${installDomHelpers.toString()})();
1540
+ var helpers = globalThis.__mcpDomHelpers;
1541
+ var el = helpers.activeElement();
1240
1542
  if (!(el instanceof HTMLInputElement)) return {handled: false};
1241
1543
  var type = (el.type || 'text').toLowerCase();
1242
- if (['text', 'search', 'tel', 'url', 'password'].indexOf(type) !== -1) return {handled: false, inputType: type};
1544
+ if (['text', 'search', 'tel', 'url', 'password'].indexOf(type) !== -1) {
1545
+ return {handled: false, inputType: type};
1546
+ }
1547
+ var scope = point ? helpers.deepElementFromPoint(point.x, point.y) :
1548
+ scopeQuery ? helpers.query(scopeQuery)[scopeQuery.nth || 0] : el;
1549
+ if (!scope || scope.isConnected === false || !helpers.containsComposed(scope, el)) {
1550
+ return {handled: true, success: false, tag: 'input', inputType: type, reason: 'target_changed'};
1551
+ }
1243
1552
  var current = String(el.value || '');
1244
1553
  var pos = -1;
1245
1554
  for (var i = 0; i <= nth; i++) {
@@ -1279,7 +1588,7 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1279
1588
  };
1280
1589
  }
1281
1590
  setter.call(el, requested);
1282
- el.dispatchEvent(new Event('input', {bubbles: true}));
1591
+ el.dispatchEvent(new Event('input', {bubbles: true, composed: true}));
1283
1592
  el.dispatchEvent(new Event('change', {bubbles: true}));
1284
1593
  var actual = String(el.value || '');
1285
1594
  return {
@@ -1292,12 +1601,21 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1292
1601
  actualValue: actual.slice(0, 160),
1293
1602
  reason: actual === requested ? undefined : 'value_not_applied'
1294
1603
  };
1295
- }`, undefined, remainingInputTimeout(deadline), [event.find, event.text, event.nth ?? 0]);
1604
+ }`, undefined, remainingInputTimeout(deadline), [
1605
+ event.find,
1606
+ event.text,
1607
+ event.nth ?? 0,
1608
+ event.target && 'x' in event.target && 'y' in event.target ? event.target : null,
1609
+ event.target && !('x' in event.target) ? targetToFindParams(event.target) : null,
1610
+ ], { userAction: 'input' });
1296
1611
  if (privacy) {
1297
1612
  privacy.sensitive = sensitiveBefore || directResult.inputType === 'password';
1298
1613
  }
1299
1614
  if (directResult.handled) {
1300
1615
  if (!directResult.success) {
1616
+ if (directResult.reason === 'target_changed') {
1617
+ throw new StructuredToolError('TARGET_FOCUS_FAILED', '目标元素的聚焦已变化,已停止替换', '读取当前目标内容后重新定位元素', { target: event.target, reason: directResult.reason });
1618
+ }
1301
1619
  const valueNotApplied = directResult.reason === 'value_not_applied';
1302
1620
  throw new StructuredToolError(directResult.reason === 'text_not_found'
1303
1621
  ? 'TEXT_NOT_FOUND'
@@ -1328,17 +1646,13 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1328
1646
  normalized: directResult.actualValue !== directResult.requestedValue,
1329
1647
  };
1330
1648
  }
1331
- const formatted = await selectText(unifiedSession, event.find, event.target, event.nth, remainingInputTimeout(deadline), privacy);
1649
+ const selection = await selectText(unifiedSession, event.find, event.target, event.nth, remainingInputTimeout(deadline), privacy);
1332
1650
  let selectionConfirmed = false;
1333
1651
  for (let i = 0; i < 25; i++) {
1334
- const hasSelection = await unifiedSession.evaluate(`(function() {
1335
- var el = document.activeElement;
1336
- if (el && (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA')) {
1337
- return el.selectionStart !== el.selectionEnd;
1338
- }
1339
- var sel = window.getSelection();
1340
- return sel && !sel.isCollapsed;
1341
- })()`, undefined, remainingInputTimeout(deadline));
1652
+ const hasSelection = await unifiedSession.evaluate(`function(scopeRefId, findText) {
1653
+ (${installDomHelpers.toString()})();
1654
+ return (${ownsTextSelection.toString()})(scopeRefId, findText);
1655
+ }`, undefined, remainingInputTimeout(deadline), [selection.scopeRefId, event.find]);
1342
1656
  if (hasSelection) {
1343
1657
  selectionConfirmed = true;
1344
1658
  break;
@@ -1348,12 +1662,14 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1348
1662
  if (!selectionConfirmed) {
1349
1663
  throw new Error(`选区同步失败:文本 "${event.find}" 已定位但未能建立选区,无法执行替换`);
1350
1664
  }
1351
- const replaceResult = await unifiedSession.evaluate(`function(replacementText) {
1352
- var el = document.activeElement;
1665
+ const replaceResult = await unifiedSession.evaluate(`function(replacementText, scopeRefId, findText) {
1666
+ (${installDomHelpers.toString()})();
1667
+ if (!(${ownsTextSelection.toString()})(scopeRefId, findText)) return 'stale';
1668
+ var el = globalThis.__mcpDomHelpers.activeElement();
1353
1669
  if (el && (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') && el.setRangeText) {
1354
1670
  if (el.readOnly || el.disabled) return 'readonly';
1355
1671
  el.setRangeText(replacementText, el.selectionStart, el.selectionEnd, 'end');
1356
- el.dispatchEvent(new Event('input', {bubbles: true}));
1672
+ el.dispatchEvent(new Event('input', {bubbles: true, composed: true}));
1357
1673
  return 'ok';
1358
1674
  }
1359
1675
  var sel = window.getSelection();
@@ -1366,17 +1682,31 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1366
1682
  if (!editable || !editable.isContentEditable) return 'readonly';
1367
1683
  if (document.execCommand('insertText', false, replacementText)) return 'ok';
1368
1684
  return 'fallback';
1369
- }`, undefined, remainingInputTimeout(deadline), [event.text]);
1685
+ }`, undefined, remainingInputTimeout(deadline), [event.text, selection.scopeRefId, event.find], { userAction: 'input' });
1686
+ if (replaceResult === 'stale') {
1687
+ throw new StructuredToolError('TEXT_SELECTION_CHANGED', '替换前目标元素或选区已变化,已停止写入', '读取当前目标内容后重新定位文本', { target: event.target });
1688
+ }
1370
1689
  if (replaceResult === 'readonly') {
1371
1690
  throw new Error(`目标元素不可编辑,已选中文本 "${event.find}" 但无法替换`);
1372
1691
  }
1692
+ let warning;
1373
1693
  if (replaceResult === 'fallback') {
1694
+ warning = await unifiedSession.prepareKeyboardFocus(remainingInputTimeout(deadline));
1695
+ const owned = await unifiedSession.evaluate(`function(scopeRefId, findText) {
1696
+ (${installDomHelpers.toString()})();
1697
+ return (${ownsTextSelection.toString()})(scopeRefId, findText);
1698
+ }`, undefined, remainingInputTimeout(deadline), [selection.scopeRefId, event.find]);
1699
+ if (!owned) {
1700
+ throw new StructuredToolError('TEXT_SELECTION_CHANGED', '继续输入前目标元素或选区已变化,已停止写入', '读取当前目标内容后重新定位文本', { target: event.target });
1701
+ }
1374
1702
  await unifiedSession.typeText(event.text, 0, remainingInputTimeout(deadline));
1375
1703
  }
1376
- if (formatted) {
1377
- return `替换的文本原在 <${formatted}> 标签内,替换后格式可能丢失`;
1704
+ if (selection.formatted) {
1705
+ return [warning, `替换的文本原在 <${selection.formatted}> 标签内,替换后格式可能丢失`]
1706
+ .filter(Boolean)
1707
+ .join('\n');
1378
1708
  }
1379
- return undefined;
1709
+ return warning;
1380
1710
  }
1381
1711
  async function handleUnifiedEditorContext({ unifiedSession, timeout, frame }, event) {
1382
1712
  return (await editorAction(unifiedSession, 'context', event, timeout, frame));
@@ -1407,15 +1737,15 @@ async function handleUnifiedDrag({ unifiedSession, timeout, frame }, event) {
1407
1737
  const srcNth = srcParams.nth ?? 0;
1408
1738
  const dstNth = dstParams.nth ?? 0;
1409
1739
  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));
1740
+ const srcEls = await unifiedSession.find(srcParams.selector, srcParams.text, srcParams.xpath, timeout, srcParams.semantic, srcNth, 'frame');
1741
+ const dstEls = await unifiedSession.find(dstParams.selector, dstParams.text, dstParams.xpath, timeout, dstParams.semantic, dstNth, 'frame');
1742
+ if (srcEls.length === 0) {
1743
+ 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
1744
  }
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));
1745
+ if (dstEls.length === 0) {
1746
+ 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
1747
  }
1418
- return unifiedSession.dragAndDrop(srcEls[srcNth].refId, dstEls[dstNth].refId);
1748
+ return unifiedSession.dragAndDrop(srcEls[0].refId, dstEls[0].refId);
1419
1749
  };
1420
1750
  let dragResult = await attemptDrag();
1421
1751
  let retried = false;
@@ -1430,15 +1760,7 @@ async function handleUnifiedDrag({ unifiedSession, timeout, frame }, event) {
1430
1760
  return retried ? 'drag 因 refId 失效已自动重试一次(可能是 React 等框架重渲染导致)' : undefined;
1431
1761
  }
1432
1762
  /**
1433
- * Extension 模式:获取目标点坐标
1434
- *
1435
- * iframe 坐标系修正:
1436
- * - 原始坐标 {x, y}:用户意图为 iframe 相对坐标
1437
- * - precise 模式需加 offset 转为视口绝对坐标(CDP 用绝对坐标)
1438
- * - stealth 模式直接使用(在 iframe 内派发,本身就是相对坐标)
1439
- * - 元素定位:find() 返回视口绝对坐标
1440
- * - precise 模式直接使用
1441
- * - stealth 模式需减 offset 转为 iframe 相对坐标
1763
+ * 通过当前 frame 内的元素引用写入 controlled 文本
1442
1764
  */
1443
1765
  async function inputControlled(unifiedSession, event, timeout, frame) {
1444
1766
  if (!event.target) {
@@ -1447,15 +1769,15 @@ async function inputControlled(unifiedSession, event, timeout, frame) {
1447
1769
  if ('x' in event.target && 'y' in event.target) {
1448
1770
  throw new Error('controlled 输入不支持坐标型 target,请使用 CSS 选择器、role 或文本定位');
1449
1771
  }
1450
- const { selector, text: searchText, xpath, nth: nthParam, } = targetToFindParams(event.target);
1451
- const elements = await unifiedSession.find(selector, searchText, xpath, timeout);
1772
+ const { selector, text: searchText, xpath, nth: nthParam, semantic, } = targetToFindParams(event.target);
1452
1773
  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));
1774
+ const elements = await unifiedSession.find(selector, searchText, xpath, timeout, semantic, nth, 'frame');
1775
+ if (elements.length === 0) {
1776
+ 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
1777
  }
1456
- const result = await unifiedSession.dispatchInput(elements[nth].refId, event.text ?? '');
1778
+ const result = await unifiedSession.dispatchInput(elements[0].refId, event.text ?? '');
1457
1779
  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));
1780
+ 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
1781
  }
1460
1782
  }
1461
1783
  async function buildTargetDiagnosticContext(unifiedSession, target, matchCount, nth, timeout, reason = '目标元素未找到', frame) {
@@ -1473,7 +1795,8 @@ async function editorAction(unifiedSession, action, event, timeout, frame) {
1473
1795
  await focusTargetForCommands(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
1474
1796
  }
1475
1797
  return unifiedSession.evaluate(`function(action, text, command) {
1476
- var active = document.activeElement;
1798
+ (${installDomHelpers.toString()})();
1799
+ var active = globalThis.__mcpDomHelpers.activeElement();
1477
1800
  var sel = window.getSelection();
1478
1801
  var editable = active;
1479
1802
  if (!editable || editable === document.body || editable === document.documentElement) {
@@ -1519,7 +1842,7 @@ async function editorAction(unifiedSession, action, event, timeout, frame) {
1519
1842
  if (action === 'insert') {
1520
1843
  if (isInput) {
1521
1844
  active.setRangeText(text, active.selectionStart || 0, active.selectionEnd || 0, 'end');
1522
- active.dispatchEvent(new Event('input', {bubbles: true}));
1845
+ active.dispatchEvent(new Event('input', {bubbles: true, composed: true}));
1523
1846
  active.dispatchEvent(new Event('change', {bubbles: true}));
1524
1847
  return {success: true};
1525
1848
  }
@@ -1533,7 +1856,7 @@ async function editorAction(unifiedSession, action, event, timeout, frame) {
1533
1856
  throw new Error('editorCommand 执行失败: ' + command);
1534
1857
  }
1535
1858
  return {success: true, command: command};
1536
- }`, undefined, remainingInputTimeout(deadline), [action, event.text ?? '', event.command ?? '']);
1859
+ }`, undefined, remainingInputTimeout(deadline), [action, event.text ?? '', event.command ?? ''], { userAction: 'input' });
1537
1860
  }
1538
1861
  async function getTargetPointExtension(unifiedSession, target, timeout, frame, scroll = true) {
1539
1862
  const budget = timeout ?? DEFAULT_TIMEOUT;
@@ -1545,66 +1868,186 @@ async function getTargetPointExtension(unifiedSession, target, timeout, frame, s
1545
1868
  }
1546
1869
  return value;
1547
1870
  };
1548
- const frameOffset = unifiedSession.getFrameOffset();
1549
- const isStealth = unifiedSession.getInputMode() === 'stealth';
1550
- // 原始坐标:用户意图为 iframe 相对坐标
1551
1871
  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
1872
  return { x: target.x, y: target.y };
1557
1873
  }
1558
- const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
1559
- const elements = await unifiedSession.find(selector, text, xpath, remaining());
1874
+ const { selector, text, xpath, nth: nthParam, semantic } = targetToFindParams(target);
1560
1875
  const nth = nthParam ?? 0;
1876
+ const elements = await unifiedSession.find(selector, text, xpath, remaining(), semantic, nth, 'frame');
1561
1877
  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));
1878
+ 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
1879
  }
1567
- // 视口外时滚动后重新取 rect:与 actionableClick (left+single) 行为对齐,
1568
- // 否则非左键 / 多击的坐标路径在视口外坐标 dispatch,浏览器找不到元素,事件丢失
1569
- const refId = elements[nth].refId;
1570
- const iframeRelRect = await unifiedSession.evaluate(`(() => {
1880
+ // 由原生滚动处理祖先裁剪;视口外保留居中意图,可见目标使用 nearest 保持位置
1881
+ const refId = elements[0].refId;
1882
+ let rect = await unifiedSession.evaluate(`(async () => {
1571
1883
  const ref = window.__mcpElementMap?.[${JSON.stringify(refId)}];
1572
1884
  const el = ref?.deref();
1573
- if (!el) return null;
1885
+ if (!el || !el.isConnected || el.ownerDocument !== document) return null;
1574
1886
  const r = el.getBoundingClientRect();
1575
- if (${scroll} && (r.top < 0 || r.bottom > window.innerHeight || r.left < 0 || r.right > window.innerWidth)) {
1576
- el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
1887
+ if (${scroll}) {
1888
+ const alignment = r.top < 0 || r.bottom > window.innerHeight ||
1889
+ r.left < 0 || r.right > window.innerWidth ? 'center' : 'nearest';
1890
+ const positions = [];
1891
+ for (let node = el; node; node = node.assignedSlot || node.parentElement || node.getRootNode?.().host) {
1892
+ if (node !== document.scrollingElement) {
1893
+ positions.push({ target: node, x: node.scrollLeft, y: node.scrollTop });
1894
+ }
1895
+ }
1896
+ positions.push({ target: document, x: window.scrollX, y: window.scrollY });
1897
+ el.scrollIntoView({ block: alignment, inline: alignment, behavior: 'instant' });
1898
+ const changed = positions.filter(({ target, x, y }) => target === document
1899
+ ? x !== window.scrollX || y !== window.scrollY
1900
+ : x !== target.scrollLeft || y !== target.scrollTop);
1901
+ if (changed.length) {
1902
+ const channel = new MessageChannel();
1903
+ const scrollTargets = new Set([window, document, ...positions.flatMap(({ target }) =>
1904
+ [target, target.getRootNode?.() || document]),
1905
+ ...globalThis.__mcpDomHelpers.elements()
1906
+ .flatMap(node => node.shadowRoot ? [node.shadowRoot] : [])]);
1907
+ let timer, frame, visibilityChanged, scrollChanged, scrollEnded;
1908
+ try {
1909
+ await new Promise((resolve, reject) => {
1910
+ let turn = 0, previous;
1911
+ const scrollPosition = target => target === document
1912
+ ? [window.scrollX, window.scrollY] : [target.scrollLeft, target.scrollTop];
1913
+ const observedScroll = new Map();
1914
+ scrollChanged = event => {
1915
+ const { target } = event, last = observedScroll.get(target);
1916
+ if (last?.event === event && last.listenerTarget !== event.currentTarget) return;
1917
+ if (!last || positions.some(position => position.target === target)) {
1918
+ previous = undefined;
1919
+ }
1920
+ const offset = scrollPosition(target);
1921
+ const offsets = last?.offsets || new Set();
1922
+ offsets.add(offset.join(','));
1923
+ observedScroll.set(target, {
1924
+ event, listenerTarget: event.currentTarget, offset, offsets
1925
+ });
1926
+ };
1927
+ scrollEnded = ({ target }) => {
1928
+ const last = observedScroll.get(target), offset = scrollPosition(target);
1929
+ if (last && offset.some((value, index) => value !== last.offset[index]) &&
1930
+ (positions.some(position => position.target === target) ||
1931
+ !last.offsets.has(offset.join(',')))) {
1932
+ previous = undefined;
1933
+ }
1934
+ };
1935
+ const observeScroll = target => {
1936
+ target.addEventListener('scroll', scrollChanged, true);
1937
+ target.addEventListener('scrollend', scrollEnded, true);
1938
+ };
1939
+ for (const target of scrollTargets) observeScroll(target);
1940
+ const schedule = () => {
1941
+ const currentTurn = ++turn;
1942
+ if (frame !== undefined) cancelAnimationFrame(frame);
1943
+ frame = undefined;
1944
+ if (document.visibilityState === 'visible') {
1945
+ frame = requestAnimationFrame(() => {
1946
+ channel.port2.postMessage({ turn: currentTurn, rendered: true });
1947
+ });
1948
+ } else {
1949
+ channel.port2.postMessage({ turn: currentTurn, rendered: false });
1950
+ }
1951
+ };
1952
+ channel.port1.onmessage = ({ data }) => {
1953
+ if (data.turn !== turn) return;
1954
+ if (!el.isConnected || el.ownerDocument !== document) {
1955
+ resolve();
1956
+ return;
1957
+ }
1958
+ for (const node of globalThis.__mcpDomHelpers.elements()) {
1959
+ if (node.shadowRoot && !scrollTargets.has(node.shadowRoot)) {
1960
+ scrollTargets.add(node.shadowRoot);
1961
+ observeScroll(node.shadowRoot);
1962
+ previous = undefined;
1963
+ }
1964
+ }
1965
+ if (document.visibilityState === 'visible') {
1966
+ if (!data.rendered) {
1967
+ schedule();
1968
+ return;
1969
+ }
1970
+ const bounds = el.getBoundingClientRect();
1971
+ const current = [...positions.flatMap(({ target }) => scrollPosition(target)),
1972
+ bounds.x, bounds.y, bounds.width, bounds.height];
1973
+ if (!previous || !current.every((value, index) => value === previous[index])) {
1974
+ previous = current;
1975
+ schedule();
1976
+ return;
1977
+ }
1978
+ }
1979
+ if (Date.now() >= ${deadline}) {
1980
+ reject(new Error(
1981
+ 'SCROLL_SETTLEMENT_TIMEOUT: rendering did not finish before the request deadline'
1982
+ ));
1983
+ return;
1984
+ }
1985
+ const before = positions.flatMap(({ target }) => scrollPosition(target));
1986
+ el.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'instant' });
1987
+ if (positions.flatMap(({ target }) => scrollPosition(target))
1988
+ .some((value, index) => value !== before[index])) {
1989
+ previous = undefined;
1990
+ schedule();
1991
+ return;
1992
+ }
1993
+ resolve();
1994
+ };
1995
+ visibilityChanged = schedule;
1996
+ document.addEventListener('visibilitychange', visibilityChanged);
1997
+ schedule();
1998
+ timer = setTimeout(() => reject(new Error(
1999
+ 'SCROLL_SETTLEMENT_TIMEOUT: rendering did not finish before the request deadline'
2000
+ )), Math.max(1, ${deadline} - Date.now()));
2001
+ });
2002
+ } finally {
2003
+ clearTimeout(timer);
2004
+ if (frame !== undefined) cancelAnimationFrame(frame);
2005
+ if (visibilityChanged) document.removeEventListener('visibilitychange', visibilityChanged);
2006
+ if (scrollChanged) {
2007
+ for (const target of scrollTargets) {
2008
+ target.removeEventListener('scroll', scrollChanged, true);
2009
+ target.removeEventListener('scrollend', scrollEnded, true);
2010
+ }
2011
+ }
2012
+ channel.port1.close();
2013
+ channel.port2.close();
2014
+ }
2015
+ }
1577
2016
  }
1578
- const r2 = el.getBoundingClientRect();
1579
- return { x: r2.x, y: r2.y, width: r2.width, height: r2.height };
2017
+ if (!el.isConnected || el.ownerDocument !== document) return null;
2018
+ const current = el.getBoundingClientRect();
2019
+ return { x: current.x, y: current.y, width: current.width, height: current.height };
1580
2020
  })()`, undefined, remaining());
1581
2021
  remaining();
1582
- if (!iframeRelRect) {
2022
+ if (!rect) {
1583
2023
  throw new StructuredToolError('TARGET_NOT_FOUND', '目标元素引用已失效,未使用旧坐标派发事件', '请重新读取页面并确认 target', { target, refId, actionExecuted: false });
1584
2024
  }
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
- };
2025
+ if (frame !== undefined && scroll) {
2026
+ const refreshed = await unifiedSession.find(selector, text, xpath, remaining(), semantic, nth, 'frame');
2027
+ if (!refreshed[0] || refreshed[0].refId !== refId) {
2028
+ throw new StructuredToolError('TARGET_NOT_FOUND', '滚动后目标元素已失效', '重新读取目标元素', {
2029
+ actionExecuted: false,
2030
+ });
2031
+ }
2032
+ rect = await unifiedSession.evaluate(`(() => {
2033
+ const el = window.__mcpElementMap?.[${JSON.stringify(refId)}]?.deref();
2034
+ if (!el || !el.isConnected || el.ownerDocument !== document) return null;
2035
+ const r = el.getBoundingClientRect();
2036
+ return { x: r.x, y: r.y, width: r.width, height: r.height };
2037
+ })()`, undefined, remaining());
2038
+ if (!rect) {
2039
+ throw new StructuredToolError('TARGET_NOT_FOUND', '最终定位时目标元素已失效', '重新读取目标元素', {
2040
+ target,
2041
+ refId,
2042
+ actionExecuted: false,
2043
+ });
2044
+ }
1600
2045
  }
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 };
2046
+ return {
2047
+ x: rect.x + rect.width / 2,
2048
+ y: rect.y + rect.height / 2,
2049
+ refId,
2050
+ };
1608
2051
  }
1609
2052
  async function executeCdpEvent(session, event, humanize, timeout) {
1610
2053
  validateEvent(event);
@@ -1612,7 +2055,7 @@ async function executeCdpEvent(session, event, humanize, timeout) {
1612
2055
  if (!handler) {
1613
2056
  throw new Error(`未知事件类型: ${event.type}`);
1614
2057
  }
1615
- await handler({ session, humanize, timeout }, event);
2058
+ return handler({ session, humanize, timeout }, event);
1616
2059
  }
1617
2060
  const cdpInputHandlers = {
1618
2061
  click: handleCdpClick,
@@ -1628,9 +2071,22 @@ const cdpInputHandlers = {
1628
2071
  drag: handleCdpDrag,
1629
2072
  };
1630
2073
  async function handleCdpClick({ session, humanize, timeout }, event) {
1631
- if (event.force) {
2074
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
2075
+ const backgroundClick = !event.force &&
2076
+ !humanize &&
2077
+ event.target !== undefined &&
2078
+ !('x' in event.target) &&
2079
+ (event.button ?? 'left') === 'left' &&
2080
+ (event.clickCount ?? 1) === 1 &&
2081
+ session.getModifiers() === 0 &&
2082
+ (await session.evaluate('document.hidden', undefined, remainingInputTimeout(deadline)));
2083
+ if (event.force || backgroundClick) {
2084
+ if (backgroundClick) {
2085
+ const point = await getTargetPoint(session, event.target, remainingInputTimeout(deadline));
2086
+ session.getBehaviorSimulator().setCurrentPosition(point);
2087
+ }
1632
2088
  const locator = session.createLocator(event.target, {
1633
- timeout: targetLookupTimeout(timeout ?? DEFAULT_TIMEOUT),
2089
+ timeout: targetLookupTimeout(remainingInputTimeout(deadline)),
1634
2090
  });
1635
2091
  await locator.evaluateOn(`function() {
1636
2092
  if (!this.isConnected) throw new Error('目标元素已移除,未执行点击');
@@ -1640,7 +2096,9 @@ async function handleCdpClick({ session, humanize, timeout }, event) {
1640
2096
  const masks = {left: 1, middle: 4, right: 2, back: 8, forward: 16};
1641
2097
  const rect = this.getBoundingClientRect();
1642
2098
  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};
2099
+ button: codes[button], clientX: rect.x + rect.width / 2, clientY: rect.y + rect.height / 2,
2100
+ altKey: ${Boolean(session.getModifiers() & 1)}, ctrlKey: ${Boolean(session.getModifiers() & 2)},
2101
+ metaKey: ${Boolean(session.getModifiers() & 4)}, shiftKey: ${Boolean(session.getModifiers() & 8)}};
1644
2102
  for (let detail = 1; detail <= count; ++detail) {
1645
2103
  const down = this.dispatchEvent(new MouseEvent('mousedown', {...base, detail, buttons: masks[button]}));
1646
2104
  if (down && button === 'left' && typeof this.focus === 'function') this.focus();
@@ -1652,10 +2110,10 @@ async function handleCdpClick({ session, humanize, timeout }, event) {
1652
2110
  }
1653
2111
  }
1654
2112
  }`);
1655
- return;
2113
+ return backgroundClick ? '后台元素单击使用合成事件,isTrusted=false,未激活标签页' : undefined;
1656
2114
  }
1657
2115
  if (event.target) {
1658
- await moveToTarget(session, event.target, humanize, timeout);
2116
+ await moveToTarget(session, event.target, humanize, remainingInputTimeout(deadline));
1659
2117
  }
1660
2118
  const cdpButton = event.button ?? 'left';
1661
2119
  const cdpClickCount = event.clickCount ?? 1;
@@ -1722,9 +2180,11 @@ async function handleCdpType({ session, humanize, timeout }, event) {
1722
2180
  }
1723
2181
  }
1724
2182
  else {
1725
- const hasActiveFocus = await session.evaluate('!!document.activeElement && ' +
1726
- 'document.activeElement !== document.body && ' +
1727
- 'document.activeElement !== document.documentElement', undefined, remainingInputTimeout(deadline));
2183
+ const hasActiveFocus = await session.evaluate(`(() => {
2184
+ (${installDomHelpers.toString()})();
2185
+ const active = globalThis.__mcpDomHelpers.activeElement();
2186
+ return !!active && active !== document.body && active !== document.documentElement;
2187
+ })()`, undefined, remainingInputTimeout(deadline));
1728
2188
  if (!hasActiveFocus) {
1729
2189
  throw new Error('type 事件在无 target 时需要页面已有焦点元素,请提供 target 或先 click 目标元素');
1730
2190
  }
@@ -1744,7 +2204,7 @@ async function handleCdpType({ session, humanize, timeout }, event) {
1744
2204
  }
1745
2205
  async function handleCdpWait({ timeout }, event) {
1746
2206
  ensureWaitFitsTimeout(event.ms, timeout);
1747
- await new Promise((resolve) => setTimeout(resolve, event.ms));
2207
+ await getUnifiedSession().wait(event.ms);
1748
2208
  }
1749
2209
  async function handleCdpDrag() {
1750
2210
  throw new Error('drag 事件仅在 Extension 模式下可用,当前为 CDP 模式');
@@ -1785,9 +2245,10 @@ async function moveToTarget(session, target, humanize, timeout, steps, waitType
1785
2245
  * 获取目标点坐标(带自动等待)
1786
2246
  */
1787
2247
  async function getTargetPoint(session, target, timeout, waitType = 'click') {
1788
- // 如果是坐标,直接返回
1789
2248
  if ('x' in target && 'y' in target) {
1790
- return { x: target.x, y: target.y };
2249
+ return session
2250
+ .createLocator(target, { timeout: targetLookupTimeout(timeout ?? DEFAULT_TIMEOUT) })
2251
+ .getClickablePoint();
1791
2252
  }
1792
2253
  const budget = timeout ?? DEFAULT_TIMEOUT;
1793
2254
  const deadline = Date.now() + budget;
@@ -1822,7 +2283,9 @@ async function getTargetPoint(session, target, timeout, waitType = 'click') {
1822
2283
  export function registerInputTool(server) {
1823
2284
  server.registerTool('input', {
1824
2285
  description: [
1825
- '键鼠输入:键盘、鼠标及任意组合。默认优先使用已连接的 Chrome Extension;',
2286
+ '键鼠输入及文件上传:键盘、鼠标及任意组合。网页上传优先使用本工具的 upload 事件,',
2287
+ 'files 支持绝对、相对及 ~/ 路径,沿用当前页面与 Extension/CDP 连接,总大小严格小于 50 MiB;',
2288
+ '默认优先使用已连接的 Chrome Extension;',
1826
2289
  '只有 Extension 不可用或 browse(action="connect", port=…) 已显式选择 CDP 时才使用 CDP。',
1827
2290
  '访问 Cloudflare 时默认不传 diagnostics,Extension 先被动等待真实 tab 标题恢复,',
1828
2291
  '持续存在可点击 Turnstile 时才点击。同页测试按钮走页面点击;',
@@ -1856,11 +2319,13 @@ export function registerInputTool(server) {
1856
2319
  type: {events:[{type:"type",target:{css:"input[name=q]"},text:"hello"}]}
1857
2320
  controlled type: {events:[{type:"type",mode:"controlled",target:{css:"input[name=q]"},text:"hello"}]}
1858
2321
  replace: {events:[{type:"replace",target:{css:"textarea"},find:"old",text:"new"}]}
2322
+ upload: {events:[{type:"upload",target:{css:"input[type=file]"},files:["./attachment.zip"]}]}
2323
+ 文件路径在 Server 机器上解析;files:[] 清空选择,总大小须小于 50 MiB;合成 input/change 事件不保证站点已收件,使用 postCondition 验证
1859
2324
  注意:纯键盘事件(不带 commands)仅保证 JS keyboard event 可被监听,不保证触发浏览器原生编辑行为;
1860
2325
  全选/复制/粘贴等语义用 commands;"全选并替换文本"用 select/replace 事件更简洁;
1861
2326
  commands 成功表示浏览器已接受命令分发,页面结果需用 postCondition 或 extract 验证;
1862
2327
  commands 仅支持 inputMode=precise,stealth 模式下会报错`,
1863
2328
  inputSchema: inputSchema,
1864
- }, (args) => handleInput(args));
2329
+ }, (args, extra) => handleInput(args, extra?.signal));
1865
2330
  }
1866
2331
  //# sourceMappingURL=input.js.map