@pyrokine/mcp-chrome 2.4.4 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (116) hide show
  1. package/README.md +401 -102
  2. package/README_zh.md +319 -79
  3. package/dist/anti-detection/injection.js +3 -3
  4. package/dist/cdp/client.d.ts +1 -1
  5. package/dist/cdp/client.d.ts.map +1 -1
  6. package/dist/cdp/client.js +18 -7
  7. package/dist/cdp/client.js.map +1 -1
  8. package/dist/cdp/launcher.d.ts +2 -3
  9. package/dist/cdp/launcher.d.ts.map +1 -1
  10. package/dist/cdp/launcher.js +84 -24
  11. package/dist/cdp/launcher.js.map +1 -1
  12. package/dist/core/auto-wait.d.ts +3 -3
  13. package/dist/core/auto-wait.d.ts.map +1 -1
  14. package/dist/core/auto-wait.js +45 -20
  15. package/dist/core/auto-wait.js.map +1 -1
  16. package/dist/core/browser-driver.d.ts +101 -12
  17. package/dist/core/browser-driver.d.ts.map +1 -1
  18. package/dist/core/browser-driver.js.map +1 -1
  19. package/dist/core/errors.d.ts +16 -0
  20. package/dist/core/errors.d.ts.map +1 -1
  21. package/dist/core/errors.js +77 -0
  22. package/dist/core/errors.js.map +1 -1
  23. package/dist/core/locator.d.ts.map +1 -1
  24. package/dist/core/locator.js +6 -4
  25. package/dist/core/locator.js.map +1 -1
  26. package/dist/core/os-mouse.d.ts +15 -2
  27. package/dist/core/os-mouse.d.ts.map +1 -1
  28. package/dist/core/os-mouse.js +52 -8
  29. package/dist/core/os-mouse.js.map +1 -1
  30. package/dist/core/session.d.ts +34 -19
  31. package/dist/core/session.d.ts.map +1 -1
  32. package/dist/core/session.js +574 -130
  33. package/dist/core/session.js.map +1 -1
  34. package/dist/core/types.d.ts +2 -0
  35. package/dist/core/types.d.ts.map +1 -1
  36. package/dist/core/types.js.map +1 -1
  37. package/dist/core/unified-session.d.ts +95 -20
  38. package/dist/core/unified-session.d.ts.map +1 -1
  39. package/dist/core/unified-session.js +489 -117
  40. package/dist/core/unified-session.js.map +1 -1
  41. package/dist/core/utils.d.ts +5 -0
  42. package/dist/core/utils.d.ts.map +1 -1
  43. package/dist/core/utils.js +475 -54
  44. package/dist/core/utils.js.map +1 -1
  45. package/dist/extension/bridge.d.ts +46 -36
  46. package/dist/extension/bridge.d.ts.map +1 -1
  47. package/dist/extension/bridge.js +269 -112
  48. package/dist/extension/bridge.js.map +1 -1
  49. package/dist/extension/http-server.d.ts +3 -0
  50. package/dist/extension/http-server.d.ts.map +1 -1
  51. package/dist/extension/http-server.js +19 -2
  52. package/dist/extension/http-server.js.map +1 -1
  53. package/dist/index.js +7 -0
  54. package/dist/index.js.map +1 -1
  55. package/dist/tools/browse.d.ts.map +1 -1
  56. package/dist/tools/browse.js +241 -171
  57. package/dist/tools/browse.js.map +1 -1
  58. package/dist/tools/challenge.d.ts +1 -1
  59. package/dist/tools/challenge.d.ts.map +1 -1
  60. package/dist/tools/challenge.js +75 -37
  61. package/dist/tools/challenge.js.map +1 -1
  62. package/dist/tools/cookies.d.ts.map +1 -1
  63. package/dist/tools/cookies.js +5 -3
  64. package/dist/tools/cookies.js.map +1 -1
  65. package/dist/tools/diagnostics.d.ts +3 -3
  66. package/dist/tools/diagnostics.d.ts.map +1 -1
  67. package/dist/tools/diagnostics.js +13 -12
  68. package/dist/tools/diagnostics.js.map +1 -1
  69. package/dist/tools/evaluate.d.ts.map +1 -1
  70. package/dist/tools/evaluate.js +57 -26
  71. package/dist/tools/evaluate.js.map +1 -1
  72. package/dist/tools/extract.d.ts.map +1 -1
  73. package/dist/tools/extract.js +107 -175
  74. package/dist/tools/extract.js.map +1 -1
  75. package/dist/tools/input.d.ts +1 -1
  76. package/dist/tools/input.d.ts.map +1 -1
  77. package/dist/tools/input.js +380 -158
  78. package/dist/tools/input.js.map +1 -1
  79. package/dist/tools/logs.d.ts.map +1 -1
  80. package/dist/tools/logs.js +5 -5
  81. package/dist/tools/logs.js.map +1 -1
  82. package/dist/tools/manage.d.ts.map +1 -1
  83. package/dist/tools/manage.js +380 -57
  84. package/dist/tools/manage.js.map +1 -1
  85. package/dist/tools/page-context.d.ts +17 -0
  86. package/dist/tools/page-context.d.ts.map +1 -0
  87. package/dist/tools/page-context.js +103 -0
  88. package/dist/tools/page-context.js.map +1 -0
  89. package/dist/tools/png.d.ts +5 -0
  90. package/dist/tools/png.d.ts.map +1 -1
  91. package/dist/tools/png.js +84 -19
  92. package/dist/tools/png.js.map +1 -1
  93. package/dist/tools/post-condition.d.ts.map +1 -1
  94. package/dist/tools/post-condition.js +5 -2
  95. package/dist/tools/post-condition.js.map +1 -1
  96. package/dist/tools/schema.d.ts +9 -0
  97. package/dist/tools/schema.d.ts.map +1 -1
  98. package/dist/tools/schema.js +15 -0
  99. package/dist/tools/schema.js.map +1 -1
  100. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  101. package/dist/tools/target-diagnostics.js +32 -19
  102. package/dist/tools/target-diagnostics.js.map +1 -1
  103. package/dist/tools/wait.d.ts.map +1 -1
  104. package/dist/tools/wait.js +19 -25
  105. package/dist/tools/wait.js.map +1 -1
  106. package/extension/dist/assets/content.ts-C4imZ6A9.js +13 -0
  107. package/extension/dist/assets/content.ts-loader-CnJuCGhl.js +13 -0
  108. package/extension/dist/assets/{index.ts-Bqcu2qiN.js → index.ts-GeHNZBml.js} +2040 -2111
  109. package/extension/dist/assets/page-scripts-CMIY1zhd.js +1379 -0
  110. package/extension/dist/assets/{popup.html-B81xccfq.js → popup.html-CgtWL6Py.js} +48 -1
  111. package/extension/dist/manifest.json +4 -3
  112. package/extension/dist/service-worker-loader.js +1 -1
  113. package/extension/dist/src/popup/popup.html +11 -1
  114. package/package.json +9 -7
  115. package/scripts/start-chrome.ps1 +58 -0
  116. package/extension/dist/assets/content.ts-Cj_iiU2s.js +0 -25
@@ -11,16 +11,26 @@
11
11
  import { z } from 'zod';
12
12
  import { generateBezierPath, getMouseMoveDelay, getTypingDelay, randomDelay } from '../anti-detection/index.js';
13
13
  import { formatErrorResponse, formatResponse, getSession, getUnifiedSession } from '../core/index.js';
14
+ import { StructuredToolError, TimeoutError } from '../core/errors.js';
15
+ import { DEFAULT_TIMEOUT } from '../core/types.js';
14
16
  import { ChallengeDeniedError, ChallengeTimeoutError, resolveChallenge } from './challenge.js';
15
17
  import { appendDiagnostics, finishDiagnostics, startDiagnostics } from './diagnostics.js';
18
+ import { withPageContext } from './page-context.js';
16
19
  import { postConditionSchema, waitForPostCondition } from './post-condition.js';
17
- import { targetToFindParams, targetZodSchema } from './schema.js';
20
+ import { pageConditionSchema, pageTargetIdSchema, resolvePageTargetId, targetToFindParams, targetZodSchema, } from './schema.js';
18
21
  import { buildTargetDiagnostics } from './target-diagnostics.js';
19
22
  const INPUT_WAIT_MAX_MS = 60_000;
20
23
  const TEXT_SELECTION_INPUT_TYPES = new Set(['text', 'search', 'tel', 'url', 'password']);
21
24
  function throwInputTimeoutError(timeout) {
22
25
  throw new Error(`input timeout before event dispatch (${timeout}ms)`);
23
26
  }
27
+ function remainingInputTimeout(deadline) {
28
+ const remaining = deadline - Date.now();
29
+ if (remaining <= 0) {
30
+ throw new TimeoutError('input timeout during event execution');
31
+ }
32
+ return remaining;
33
+ }
24
34
  export function supportsTextSelection(tag, inputType) {
25
35
  return (tag.toLowerCase() === 'textarea' ||
26
36
  (tag.toLowerCase() === 'input' && TEXT_SELECTION_INPUT_TYPES.has((inputType ?? 'text').toLowerCase())));
@@ -126,6 +136,7 @@ const inputEventSchema = z.object({
126
136
  * input 参数 schema
127
137
  */
128
138
  const inputSchema = z.object({
139
+ ...pageConditionSchema,
129
140
  events: z.array(inputEventSchema).describe('事件序列'),
130
141
  humanize: z.boolean().optional().describe('启用人类行为模拟(贝塞尔曲线移动、随机延迟)'),
131
142
  diagnostics: z
@@ -135,49 +146,71 @@ const inputSchema = z.object({
135
146
  postCondition: postConditionSchema
136
147
  .optional()
137
148
  .describe('动作执行后要验证的页面状态;不传时 success 只表示事件已发出,不表示业务结果已达成'),
138
- tabId: z
139
- .string()
149
+ targetId: pageTargetIdSchema.describe('目标页面 ID(Extension 或 CDP),优先于默认操作目标'),
150
+ tabId: pageTargetIdSchema.describe('旧版目标 Tab ID,与 targetId 相同语义,保留兼容'),
151
+ timeout: z
152
+ .number()
140
153
  .optional()
141
- .describe('目标 Tab ID(可选,仅 Extension 模式),不指定则使用当前 attach 的 tab,可操作非当前 attach 的 tab,CDP 模式下不支持此参数'),
142
- timeout: z.number().optional().describe('超时毫秒,含 Cloudflare Challenge 等待和事件派发'),
154
+ .describe('超时毫秒,含 Cloudflare Challenge 等待、目标准备、鼠标移动、字符输入和延迟;到期后停止后续动作,不自动重放'),
143
155
  frame: z
144
156
  .union([z.string(), z.number()])
145
157
  .optional()
146
158
  .describe('iframe 定位(可选,仅 Extension 模式),CSS 选择器(如 "iframe#main")或索引(如 0),不指定则在主框架操作'),
147
159
  });
148
- class StructuredToolError extends Error {
149
- code;
150
- suggestion;
151
- context;
152
- constructor(code, message, suggestion, context) {
153
- super(message);
154
- this.code = code;
155
- this.suggestion = suggestion;
156
- this.context = context;
157
- this.name = 'StructuredToolError';
158
- }
159
- // noinspection JSUnusedGlobalSymbols — formatErrorResponse 通过结构化 toJSON 调用
160
- toJSON() {
161
- return {
162
- error: {
163
- code: this.code,
164
- message: this.message,
165
- suggestion: this.suggestion,
166
- context: this.context,
167
- },
168
- };
160
+ function sanitizeInputResponse(response, events, sensitiveInput) {
161
+ if (!response.isError && !sensitiveInput) {
162
+ return response;
169
163
  }
170
- }
171
- function sanitizeInputFailureResponse(response, events) {
172
164
  const sensitiveValues = events
173
165
  .flatMap((event) => [event.find, event.text])
174
166
  .filter((value) => !!value);
175
- if (sensitiveValues.length === 0) {
176
- return response;
177
- }
178
167
  for (const item of response.content) {
179
168
  try {
180
- item.text = JSON.stringify(redactSensitiveInputData(JSON.parse(item.text), sensitiveValues), null, 2);
169
+ const payload = JSON.parse(item.text);
170
+ for (const key of ['warnings', 'eventResults', 'diagnostics', 'diagnosticsError']) {
171
+ if (key in payload) {
172
+ payload[key] = redactSensitiveInputData(payload[key], sensitiveValues);
173
+ }
174
+ }
175
+ const pageContext = payload.pageContext;
176
+ const postCondition = payload.postCondition;
177
+ const details = [
178
+ payload.error,
179
+ pageContext,
180
+ pageContext?.before,
181
+ pageContext?.after,
182
+ postCondition,
183
+ ...(Array.isArray(postCondition?.checks) ? postCondition.checks : []),
184
+ ];
185
+ for (const detail of details) {
186
+ if (!detail || typeof detail !== 'object') {
187
+ continue;
188
+ }
189
+ const record = detail;
190
+ for (const key of [
191
+ 'message',
192
+ 'suggestion',
193
+ 'context',
194
+ 'contextError',
195
+ 'url',
196
+ 'title',
197
+ 'actual',
198
+ 'error',
199
+ ]) {
200
+ if (key in record) {
201
+ record[key] = redactSensitiveInputData(record[key], sensitiveValues);
202
+ }
203
+ }
204
+ }
205
+ if (sensitiveInput) {
206
+ if (payload.diagnostics) {
207
+ payload.diagnostics = { redacted: true, reason: 'sensitive_input_or_unresolved_target' };
208
+ }
209
+ if (payload.diagnosticsError) {
210
+ payload.diagnosticsError = '敏感输入的诊断详情已隐藏';
211
+ }
212
+ }
213
+ item.text = JSON.stringify(payload, null, 2);
181
214
  }
182
215
  catch {
183
216
  item.text = redactSensitiveInputData(item.text, sensitiveValues);
@@ -189,6 +222,13 @@ function sanitizeInputFailureResponse(response, events) {
189
222
  * input 工具处理器
190
223
  */
191
224
  async function handleInput(args) {
225
+ let eventsExecuted = 0;
226
+ let actionMayHaveExecuted = false;
227
+ const privacy = { sensitive: false };
228
+ const progress = {
229
+ actionStatus: 'not_started',
230
+ };
231
+ let failureStage = 'action';
192
232
  try {
193
233
  if (args.events.length === 0) {
194
234
  return {
@@ -210,16 +250,17 @@ async function handleInput(args) {
210
250
  }
211
251
  const unifiedSession = getUnifiedSession();
212
252
  const humanize = args.humanize ?? false;
213
- return await unifiedSession.withTabId(args.tabId, async () => {
214
- return await unifiedSession.withFrame(args.frame, async () => {
253
+ const response = await withPageContext(unifiedSession, resolvePageTargetId(args), async () => {
254
+ return unifiedSession.withPageCondition(args, () => unifiedSession.withFrame(args.frame, async () => {
215
255
  const mode = unifiedSession.getMode();
216
256
  const inputStartedAt = Date.now();
217
- await resolveChallenge(unifiedSession, 'input', 'not_started', args.timeout);
257
+ if (args.expectedUrl === undefined && args.expectedRevision === undefined) {
258
+ await resolveChallenge(unifiedSession, 'input', 'not_started', args.timeout);
259
+ }
218
260
  const diagnostics = await startDiagnostics(unifiedSession, args.diagnostics);
219
261
  const warnings = [];
220
262
  const eventResults = [];
221
263
  const session = mode === 'cdp' ? getSession() : undefined;
222
- let eventsExecuted = 0;
223
264
  try {
224
265
  for (const event of args.events) {
225
266
  const eventTimeout = args.timeout === undefined
@@ -228,7 +269,16 @@ async function handleInput(args) {
228
269
  if (eventTimeout !== undefined && eventTimeout <= 0) {
229
270
  throwInputTimeoutError(args.timeout);
230
271
  }
231
- const result = await executeInputEvent({ unifiedSession, session, mode, humanize, timeout: eventTimeout, frame: args.frame }, event);
272
+ progress.actionStatus = 'failed';
273
+ const result = await executeInputEvent({
274
+ unifiedSession,
275
+ session,
276
+ mode,
277
+ humanize,
278
+ timeout: eventTimeout,
279
+ frame: args.frame,
280
+ privacy,
281
+ }, event);
232
282
  ++eventsExecuted;
233
283
  if (typeof result === 'string') {
234
284
  warnings.push(result);
@@ -255,7 +305,7 @@ async function handleInput(args) {
255
305
  catch {
256
306
  // 保留原始 Challenge 错误响应
257
307
  }
258
- return sanitizeInputFailureResponse(response, args.events);
308
+ return response;
259
309
  }
260
310
  if (text) {
261
311
  try {
@@ -263,14 +313,28 @@ async function handleInput(args) {
263
313
  const message = error instanceof Error ? error.message : String(error);
264
314
  const timedOut = /timeout|超时/i.test(message);
265
315
  const preActionTimeout = /timeout before event dispatch|超过 input 剩余 timeout/i.test(message);
266
- const actionMayHaveExecuted = timedOut && !preActionTimeout;
316
+ actionMayHaveExecuted = timedOut && !preActionTimeout;
317
+ const preconditionFailed = error !== null &&
318
+ typeof error === 'object' &&
319
+ 'code' in error &&
320
+ error.code === 'ACTION_PRECONDITION_FAILED';
321
+ actionMayHaveExecuted = actionMayHaveExecuted && !preconditionFailed;
322
+ progress.actionStatus =
323
+ preconditionFailed && eventsExecuted === 0
324
+ ? 'not_started'
325
+ : actionMayHaveExecuted
326
+ ? 'unknown'
327
+ : 'failed';
267
328
  payload.eventsExecuted = eventsExecuted;
268
329
  payload.actionExecuted = eventsExecuted > 0 || actionMayHaveExecuted;
269
- payload.actionStatus = actionMayHaveExecuted ? 'unknown' : 'failed';
330
+ payload.actionStatus = progress.actionStatus;
270
331
  payload.verificationRequested = Boolean(args.postCondition);
271
332
  payload.verificationStatus = 'unavailable';
272
333
  payload.failureStage = 'action';
273
- payload.retryable = /timeout|超时|disconnect|未连接|context|debugger/i.test(message);
334
+ payload.retryable =
335
+ eventsExecuted === 0 &&
336
+ !actionMayHaveExecuted &&
337
+ /timeout|超时|disconnect|未连接|context|debugger/i.test(message);
274
338
  appendDiagnostics(payload, await finishDiagnostics(unifiedSession, diagnostics));
275
339
  response.content[0].text = JSON.stringify(payload, null, 2);
276
340
  }
@@ -278,8 +342,10 @@ async function handleInput(args) {
278
342
  // 保留原始错误响应
279
343
  }
280
344
  }
281
- return sanitizeInputFailureResponse(response, args.events);
345
+ return response;
282
346
  }
347
+ progress.actionStatus = 'completed';
348
+ failureStage = 'context';
283
349
  const result = {
284
350
  success: true,
285
351
  eventsExecuted,
@@ -297,7 +363,9 @@ async function handleInput(args) {
297
363
  result.eventResults = eventResults;
298
364
  }
299
365
  if (args.postCondition) {
366
+ failureStage = 'verification';
300
367
  const postCondition = await waitForPostCondition(unifiedSession, args.postCondition, 'input');
368
+ failureStage = 'context';
301
369
  result.postCondition = postCondition;
302
370
  result.verificationStatus = postCondition.verificationStatus;
303
371
  result.retryable = postCondition.retryable;
@@ -308,8 +376,9 @@ async function handleInput(args) {
308
376
  }
309
377
  appendDiagnostics(result, await finishDiagnostics(unifiedSession, diagnostics));
310
378
  return formatResponse(result);
311
- }); // withFrame
379
+ })); // withPageCondition, withFrame
312
380
  }); // withTabId
381
+ return sanitizeInputResponse(response, args.events, privacy.sensitive);
313
382
  }
314
383
  catch (error) {
315
384
  const response = formatErrorResponse(error);
@@ -318,17 +387,42 @@ async function handleInput(args) {
318
387
  try {
319
388
  const payload = JSON.parse(text);
320
389
  const message = error instanceof Error ? error.message : String(error);
390
+ const unavailableCondition = eventsExecuted === 0 &&
391
+ !actionMayHaveExecuted &&
392
+ progress.actionStatus === 'not_started' &&
393
+ error instanceof StructuredToolError &&
394
+ error.code === 'DRIVER_CAPABILITY_ERROR' &&
395
+ error.context.actionExecuted === false &&
396
+ error.context.actionStatus === 'not_started' &&
397
+ error.context.failureStage === 'precondition';
398
+ const preconditionFailed = unavailableCondition ||
399
+ (error !== null &&
400
+ typeof error === 'object' &&
401
+ 'code' in error &&
402
+ error.code === 'ACTION_PRECONDITION_FAILED');
321
403
  Object.assign(payload, {
322
- actionExecuted: false,
323
- actionStatus: 'failed',
404
+ eventsExecuted,
405
+ actionExecuted: eventsExecuted > 0 || actionMayHaveExecuted,
406
+ actionStatus: preconditionFailed && eventsExecuted === 0
407
+ ? 'not_started'
408
+ : progress.actionStatus === 'not_started'
409
+ ? 'failed'
410
+ : progress.actionStatus,
324
411
  verificationRequested: Boolean(args.postCondition),
325
412
  verificationStatus: 'unavailable',
326
- failureStage: 'action',
327
- retryable: /timeout|超时|disconnect|未连接|context|debugger|attach/i.test(message),
413
+ failureStage: unavailableCondition ? 'precondition' : failureStage,
414
+ retryable: progress.actionStatus !== 'completed' &&
415
+ eventsExecuted === 0 &&
416
+ !actionMayHaveExecuted &&
417
+ !preconditionFailed &&
418
+ /timeout|超时|disconnect|未连接|context|debugger|attach/i.test(message),
328
419
  diagnosticsStatus: args.diagnostics ? 'unavailable' : 'disabled',
329
420
  });
330
421
  if (args.diagnostics) {
331
- payload.diagnosticsError = 'diagnostics 未能在 tab/frame 初始化失败前启动';
422
+ payload.diagnosticsError =
423
+ eventsExecuted > 0 || actionMayHaveExecuted
424
+ ? 'input 执行后未能取得 diagnostics'
425
+ : 'diagnostics 未能在 tab/frame 初始化失败前启动';
332
426
  }
333
427
  response.content[0].text = JSON.stringify(payload, null, 2);
334
428
  }
@@ -336,10 +430,12 @@ async function handleInput(args) {
336
430
  // 保留原始错误响应
337
431
  }
338
432
  }
339
- return sanitizeInputFailureResponse(response, args.events);
433
+ return sanitizeInputResponse(response, args.events, privacy.sensitive);
340
434
  }
341
435
  }
342
436
  const unifiedOnlyEventTypes = new Set([
437
+ 'keydown',
438
+ 'keyup',
343
439
  'select',
344
440
  'replace',
345
441
  'editorContext',
@@ -355,6 +451,7 @@ async function executeInputEvent(context, event) {
355
451
  humanize: context.humanize,
356
452
  timeout: context.timeout,
357
453
  frame: context.frame,
454
+ privacy: context.privacy,
358
455
  }, event);
359
456
  }
360
457
  if (!context.session) {
@@ -377,14 +474,23 @@ async function executeInputEvent(context, event) {
377
474
  * select/replace 事件用,保证选区建立前 activeElement 就是目标
378
475
  */
379
476
  async function focusTargetForCommands(unifiedSession, target, timeout, frame) {
477
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
380
478
  if ('x' in target || 'y' in target) {
381
- const point = await getTargetPointExtension(unifiedSession, target, timeout, frame);
382
- await unifiedSession.mouseMove(point.x, point.y);
383
- await unifiedSession.mouseClick('left');
479
+ await handleUnifiedClick({
480
+ unifiedSession,
481
+ mode: unifiedSession.getMode(),
482
+ humanize: false,
483
+ timeout: remainingInputTimeout(deadline),
484
+ frame,
485
+ }, { type: 'click', target });
486
+ return;
487
+ }
488
+ if (unifiedSession.getMode() === 'cdp') {
489
+ await focusCdpTarget(getSession(), target, remainingInputTimeout(deadline));
384
490
  return;
385
491
  }
386
492
  const params = targetToFindParams(target);
387
- const els = await unifiedSession.find(params.selector, params.text, params.xpath, timeout);
493
+ const els = await unifiedSession.find(params.selector, params.text, params.xpath, remainingInputTimeout(deadline));
388
494
  const nth0 = params.nth ?? 0;
389
495
  if (els.length <= nth0) {
390
496
  throw new StructuredToolError(els.length === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', els.length === 0
@@ -399,7 +505,7 @@ async function focusTargetForCommands(unifiedSession, target, timeout, frame) {
399
505
  }
400
506
  el.focus()
401
507
  return document.activeElement === el
402
- })()`, undefined, timeout);
508
+ })()`, undefined, remainingInputTimeout(deadline));
403
509
  if (focused !== true) {
404
510
  throw new StructuredToolError('TARGET_FOCUS_FAILED', '命令目标未成功聚焦', '请检查目标是否可编辑、未 disabled 并处于正确 frame', await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, timeout, '命令目标聚焦失败', frame));
405
511
  }
@@ -419,27 +525,33 @@ async function focusTargetIfNeeded(unifiedSession, session, mode, target, timeou
419
525
  if (!target) {
420
526
  return;
421
527
  }
528
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
422
529
  if ('x' in target || 'y' in target) {
423
- const point = await getTargetPointExtension(unifiedSession, target, timeout, frame);
424
- await unifiedSession.mouseMove(point.x, point.y);
425
- await unifiedSession.mouseClick('left');
530
+ await handleUnifiedClick({
531
+ unifiedSession,
532
+ mode: unifiedSession.getMode(),
533
+ humanize: false,
534
+ timeout: remainingInputTimeout(deadline),
535
+ frame,
536
+ }, { type: 'click', target });
426
537
  return;
427
538
  }
428
539
  if (mode === 'cdp') {
429
540
  if (!session) {
430
541
  throw new Error('CDP locator 聚焦缺少 session');
431
542
  }
432
- await focusCdpTarget(session, target, timeout);
543
+ await focusCdpTarget(session, target, remainingInputTimeout(deadline));
433
544
  return;
434
545
  }
435
546
  const params = targetToFindParams(target);
436
- const els = await unifiedSession.find(params.selector, params.text, params.xpath, timeout);
547
+ const els = await unifiedSession.find(params.selector, params.text, params.xpath, remainingInputTimeout(deadline));
437
548
  const nth0 = params.nth ?? 0;
438
549
  if (els.length <= nth0) {
439
550
  throw new StructuredToolError(els.length === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', els.length === 0
440
551
  ? `未找到目标元素: ${JSON.stringify(target)}`
441
552
  : `第 ${nth0} 个匹配元素不存在(共 ${els.length} 个)`, '请检查 target、frame 和 target.nth,或先用 extract type=state 查看当前候选元素', await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, timeout, '聚焦目标未找到', frame));
442
553
  }
554
+ remainingInputTimeout(deadline);
443
555
  const result = await unifiedSession.actionableClick(els[nth0].refId);
444
556
  if (!result.success) {
445
557
  throw new StructuredToolError('ACTIONABILITY_FAILED', result.error || '目标元素无法聚焦', result.suggestions?.[0] ?? '请检查元素是否可见、未被遮挡并处于正确 frame', {
@@ -565,7 +677,12 @@ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTa
565
677
  };
566
678
  }`, undefined, timeout, [findText, occurrenceNth, scopeNth, scopeTarget ?? null, scopeSelector, scopeText, scopeXpath]);
567
679
  }
568
- async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeout) {
680
+ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeout, privacy) {
681
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
682
+ const sensitiveBefore = privacy?.sensitive ?? false;
683
+ if (privacy) {
684
+ privacy.sensitive = true;
685
+ }
569
686
  // 将 target 转为查询参数,传入注入脚本进行 DOM 查询
570
687
  let scopeSelector = null;
571
688
  let scopeText = null;
@@ -621,12 +738,12 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
621
738
  var pos = -1;
622
739
  for (var n = 0; n <= nth; n++) {
623
740
  pos = val.indexOf(findText, pos + (n > 0 ? 1 : 0));
624
- if (pos === -1) return {type: 'notfound'};
741
+ if (pos === -1) return {type: 'notfound', inputType: inputType};
625
742
  }
626
743
  // 原子化:定位到 input 同时完成 focus + setSelectionRange,避免外层 mouseClick 聚焦不可靠
627
744
  root.focus();
628
745
  root.setSelectionRange(pos, pos + findText.length);
629
- return {type: 'input', selectionStart: pos, selectionEnd: pos + findText.length};
746
+ return {type: 'input', inputType: inputType, selectionStart: pos, selectionEnd: pos + findText.length};
630
747
  }
631
748
 
632
749
  // 在子树中查找 input/textarea
@@ -654,7 +771,7 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
654
771
  if (ip !== -1) {
655
772
  inp.focus();
656
773
  inp.setSelectionRange(ip, ip + findText.length);
657
- return {type: 'input', selectionStart: ip, selectionEnd: ip + findText.length};
774
+ return {type: 'input', inputType: childType, selectionStart: ip, selectionEnd: ip + findText.length};
658
775
  }
659
776
  }
660
777
 
@@ -731,7 +848,13 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
731
848
  endY: er.y + er.height / 2,
732
849
  formatted: formatted || undefined
733
850
  };
734
- }`, undefined, timeout, [findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath]);
851
+ }`, undefined, remainingInputTimeout(deadline), [findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath]);
852
+ if (privacy &&
853
+ result &&
854
+ result.type !== 'noscope' &&
855
+ (result.type !== 'notfound' || result.inputType !== undefined)) {
856
+ privacy.sensitive = sensitiveBefore || ('inputType' in result && result.inputType === 'password');
857
+ }
735
858
  if (!result || result.type === 'noscope') {
736
859
  const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, timeout);
737
860
  throw new StructuredToolError('TEXT_SCOPE_NOT_FOUND', `未找到目标元素: ${JSON.stringify(scopeTarget)}`, '请检查 target 是否能定位到包含目标文本的元素,或先用 extract(state) 查看可交互元素', diagnostics);
@@ -769,11 +892,25 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
769
892
  coords.endY += frameOffset.y;
770
893
  }
771
894
  // Step 2: 模拟鼠标选择
772
- await unifiedSession.mouseMove(coords.startX, coords.startY);
773
- await unifiedSession.mouseClick('left');
774
- await unifiedSession.keyDown('Shift');
775
- await unifiedSession.mouseMove(coords.endX, coords.endY);
895
+ await unifiedSession.mouseMove(coords.startX, coords.startY, remainingInputTimeout(deadline));
896
+ remainingInputTimeout(deadline);
776
897
  await unifiedSession.mouseClick('left');
898
+ remainingInputTimeout(deadline);
899
+ try {
900
+ await unifiedSession.keyDown('Shift');
901
+ await unifiedSession.mouseMove(coords.endX, coords.endY, remainingInputTimeout(deadline));
902
+ remainingInputTimeout(deadline);
903
+ await unifiedSession.mouseClick('left');
904
+ }
905
+ catch (error) {
906
+ try {
907
+ await unifiedSession.keyUp('Shift');
908
+ }
909
+ catch (releaseError) {
910
+ console.error('[MCP] Shift release failed after selection error:', releaseError);
911
+ }
912
+ throw error;
913
+ }
777
914
  await unifiedSession.keyUp('Shift');
778
915
  return coords.formatted;
779
916
  }
@@ -784,6 +921,9 @@ function requiredEventParam(event, name) {
784
921
  throw new Error(`events[].${String(name)} 是 ${event.type} 事件的必填参数`);
785
922
  }
786
923
  function validateEvent(event) {
924
+ if (event.force && (event.type !== 'click' || !event.target || 'x' in event.target)) {
925
+ throw new StructuredToolError('INVALID_ARGUMENT', 'force 仅支持带元素 target 的 click 事件,不能使用坐标或省略 target', '请指定 CSS、role、文本或其他元素定位方式', { actionExecuted: false });
926
+ }
787
927
  if (event.commands && event.commands.length > 0 && event.type !== 'keydown') {
788
928
  throw new Error(`events[].commands 只能用于 keydown 事件,当前事件类型为 ${event.type},如需触发编辑命令,请把 commands 放在 keydown 事件上`);
789
929
  }
@@ -876,12 +1016,17 @@ const unifiedInputHandlers = {
876
1016
  drag: handleUnifiedDrag,
877
1017
  };
878
1018
  async function handleUnifiedKeyDown({ unifiedSession, timeout, frame }, event) {
879
- if (unifiedSession.getInputMode() === 'stealth' && event.commands && event.commands.length > 0) {
1019
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1020
+ if (unifiedSession.isExtensionConnected() &&
1021
+ unifiedSession.getInputMode() === 'stealth' &&
1022
+ event.commands &&
1023
+ event.commands.length > 0) {
880
1024
  throw new Error('commands 参数不支持 stealth 输入模式,请先调用 manage action=inputMode inputMode=precise 切换后重试');
881
1025
  }
882
1026
  if (event.commands && event.commands.length > 0 && event.target) {
883
- await focusTargetForCommands(unifiedSession, event.target, timeout, frame);
1027
+ await focusTargetForCommands(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
884
1028
  }
1029
+ remainingInputTimeout(deadline);
885
1030
  await unifiedSession.keyDown(event.key, event.commands);
886
1031
  return undefined;
887
1032
  }
@@ -889,42 +1034,45 @@ async function handleUnifiedKeyUp({ unifiedSession }, event) {
889
1034
  await unifiedSession.keyUp(event.key);
890
1035
  return undefined;
891
1036
  }
892
- async function handleUnifiedClick({ unifiedSession, timeout, frame }, event) {
1037
+ async function handleUnifiedClick({ unifiedSession, humanize, timeout, frame }, event) {
1038
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
893
1039
  const button = event.button ?? 'left';
894
1040
  const clickCount = event.clickCount ?? 1;
895
1041
  if (!event.target) {
896
1042
  await unifiedSession.mouseClick(button, clickCount);
897
1043
  return undefined;
898
1044
  }
899
- if ('x' in event.target && 'y' in event.target) {
900
- const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
901
- await unifiedSession.mouseMove(point.x, point.y);
902
- await unifiedSession.mouseClick(button, clickCount);
903
- return undefined;
1045
+ const point = await getTargetPointExtension(unifiedSession, event.target, remainingInputTimeout(deadline), frame, !event.force);
1046
+ if (humanize) {
1047
+ for (const p of generateBezierPath(unifiedSession.getMousePosition(), point, event.steps)) {
1048
+ await unifiedSession.mouseMove(p.x, p.y, remainingInputTimeout(deadline));
1049
+ const remaining = remainingInputTimeout(deadline);
1050
+ await randomDelay(Math.min(getMouseMoveDelay(), remaining), Math.min(getMouseMoveDelay() * 2, remaining));
1051
+ }
904
1052
  }
905
- if (button === 'left' && clickCount === 1) {
906
- const { selector, text: searchText, xpath, nth: nthParam, } = targetToFindParams(event.target);
907
- const elements = await unifiedSession.find(selector, searchText, xpath, timeout);
908
- const nth = nthParam ?? 0;
909
- if (elements.length > 0 && nth < elements.length) {
910
- const result = await unifiedSession.actionableClick(elements[nth].refId, event.force === true);
911
- if (!result.success) {
912
- throw new StructuredToolError('ACTIONABILITY_FAILED', result.error || 'Click failed', result.suggestions?.[0] ??
913
- '请根据 context.rect、context.clickPoint 和 context.coveringElement 调整 target', result);
914
- }
915
- return undefined;
1053
+ else {
1054
+ await unifiedSession.mouseMove(point.x, point.y, remainingInputTimeout(deadline));
1055
+ }
1056
+ remainingInputTimeout(deadline);
1057
+ if (point.refId) {
1058
+ const result = await unifiedSession.actionableClick(point.refId, event.force === true, button, clickCount);
1059
+ if (!result.success) {
1060
+ throw new StructuredToolError('ACTIONABILITY_FAILED', result.error || 'Click failed', result.suggestions?.[0] ??
1061
+ '请根据 context.rect、context.clickPoint 和 context.coveringElement 调整 target', result);
916
1062
  }
917
1063
  }
918
- const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
919
- await unifiedSession.mouseMove(point.x, point.y);
920
- await unifiedSession.mouseClick(button, clickCount, typeof point.refId === 'string' ? point.refId : undefined);
1064
+ else {
1065
+ await unifiedSession.mouseClick(button, clickCount);
1066
+ }
921
1067
  return undefined;
922
1068
  }
923
1069
  async function handleUnifiedMouseDown({ unifiedSession, timeout, frame }, event) {
1070
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
924
1071
  if (event.target) {
925
- const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
926
- await unifiedSession.mouseMove(point.x, point.y);
1072
+ const point = await getTargetPointExtension(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
1073
+ await unifiedSession.mouseMove(point.x, point.y, remainingInputTimeout(deadline));
927
1074
  }
1075
+ remainingInputTimeout(deadline);
928
1076
  await unifiedSession.mouseDown(event.button ?? 'left');
929
1077
  return undefined;
930
1078
  }
@@ -933,31 +1081,37 @@ async function handleUnifiedMouseUp({ unifiedSession }, event) {
933
1081
  return undefined;
934
1082
  }
935
1083
  async function handleUnifiedMouseMove({ unifiedSession, humanize, timeout, frame }, event) {
936
- const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
1084
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1085
+ const point = await getTargetPointExtension(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
937
1086
  if (humanize && event.steps && event.steps > 1) {
938
1087
  const path = generateBezierPath(unifiedSession.getMousePosition(), point, event.steps);
939
1088
  for (const p of path) {
940
- await unifiedSession.mouseMove(p.x, p.y);
941
- await randomDelay(getMouseMoveDelay(), getMouseMoveDelay() * 2);
1089
+ await unifiedSession.mouseMove(p.x, p.y, remainingInputTimeout(deadline));
1090
+ const remaining = remainingInputTimeout(deadline);
1091
+ await randomDelay(Math.min(getMouseMoveDelay(), remaining), Math.min(getMouseMoveDelay() * 2, remaining));
942
1092
  }
943
1093
  }
944
1094
  else {
945
- await unifiedSession.mouseMove(point.x, point.y);
1095
+ await unifiedSession.mouseMove(point.x, point.y, remainingInputTimeout(deadline));
946
1096
  }
1097
+ remainingInputTimeout(deadline);
947
1098
  return undefined;
948
1099
  }
949
1100
  async function handleUnifiedWheel({ unifiedSession, timeout, frame }, event) {
1101
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
950
1102
  if (event.target) {
951
1103
  const { selector, text, xpath, nth: nthParam } = targetToFindParams(event.target);
952
- const elements = await unifiedSession.find(selector, text, xpath, timeout);
1104
+ const elements = await unifiedSession.find(selector, text, xpath, remainingInputTimeout(deadline));
953
1105
  const nth = nthParam ?? 0;
954
1106
  if (elements.length > nth) {
1107
+ remainingInputTimeout(deadline);
955
1108
  await unifiedSession.scroll(event.deltaX ?? 0, event.deltaY ?? 0, elements[nth].refId);
956
1109
  return undefined;
957
1110
  }
958
- const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
959
- await unifiedSession.mouseMove(point.x, point.y);
1111
+ const point = await getTargetPointExtension(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
1112
+ await unifiedSession.mouseMove(point.x, point.y, remainingInputTimeout(deadline));
960
1113
  }
1114
+ remainingInputTimeout(deadline);
961
1115
  await unifiedSession.mouseWheel(event.deltaX ?? 0, event.deltaY ?? 0);
962
1116
  return undefined;
963
1117
  }
@@ -975,33 +1129,38 @@ async function handleUnifiedTouchEnd({ unifiedSession }) {
975
1129
  await unifiedSession.touchEnd();
976
1130
  return undefined;
977
1131
  }
978
- async function handleUnifiedType({ unifiedSession, humanize, timeout, frame }, event) {
1132
+ async function handleUnifiedType(context, event) {
1133
+ const { unifiedSession, humanize, timeout, frame } = context;
979
1134
  if (event.mode === 'controlled' || event.dispatch) {
980
1135
  await inputControlled(unifiedSession, event, timeout, frame);
981
1136
  return undefined;
982
1137
  }
1138
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
983
1139
  if (event.target) {
984
- const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
985
- await unifiedSession.mouseMove(point.x, point.y);
986
- await unifiedSession.mouseClick('left');
1140
+ await handleUnifiedClick({ ...context, timeout: remainingInputTimeout(deadline) }, { type: 'click', target: event.target });
1141
+ if (!('x' in event.target)) {
1142
+ await focusTargetForCommands(unifiedSession, event.target, remainingInputTimeout(deadline), frame);
1143
+ }
987
1144
  }
988
1145
  else {
989
1146
  const hasActiveFocus = await unifiedSession.evaluate('!!document.activeElement && ' +
990
1147
  'document.activeElement !== document.body && ' +
991
- 'document.activeElement !== document.documentElement');
1148
+ 'document.activeElement !== document.documentElement', undefined, remainingInputTimeout(deadline));
992
1149
  if (!hasActiveFocus) {
993
1150
  throw new Error('type 事件在无 target 时需要页面已有焦点元素,请提供 target 或先 click 目标元素');
994
1151
  }
995
1152
  }
996
1153
  const delay = event.delay ?? 0;
997
1154
  if (humanize) {
998
- for (const char of event.text) {
999
- await unifiedSession.typeText(char);
1000
- await randomDelay(getTypingDelay(delay), getTypingDelay(delay) * 1.5);
1155
+ for (const char of event.text.replace(/\r\n?/g, '\n')) {
1156
+ await unifiedSession.typeText(char, 0, remainingInputTimeout(deadline));
1157
+ const remaining = remainingInputTimeout(deadline);
1158
+ await randomDelay(Math.min(getTypingDelay(delay), remaining), Math.min(getTypingDelay(delay) * 1.5, remaining));
1001
1159
  }
1160
+ remainingInputTimeout(deadline);
1002
1161
  }
1003
1162
  else {
1004
- await unifiedSession.typeText(event.text, delay);
1163
+ await unifiedSession.typeText(event.text, delay, remainingInputTimeout(deadline));
1005
1164
  }
1006
1165
  return undefined;
1007
1166
  }
@@ -1015,17 +1174,25 @@ async function handleUnifiedWait({ timeout }, event) {
1015
1174
  await new Promise((resolve) => setTimeout(resolve, event.ms));
1016
1175
  return undefined;
1017
1176
  }
1018
- async function handleUnifiedSelect({ unifiedSession, session, mode, timeout, frame }, event) {
1019
- await focusTargetIfNeeded(unifiedSession, session, mode, event.target, timeout, frame);
1177
+ async function handleUnifiedSelect({ unifiedSession, session, mode, timeout, frame, privacy }, event) {
1178
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1179
+ const sensitiveBefore = privacy?.sensitive ?? false;
1180
+ if (privacy) {
1181
+ privacy.sensitive = true;
1182
+ }
1183
+ await focusTargetIfNeeded(unifiedSession, session, mode, event.target, remainingInputTimeout(deadline), frame);
1020
1184
  const selectionTarget = await unifiedSession.evaluate(`(() => {
1021
1185
  const el = document.activeElement;
1022
1186
  if (!(el instanceof HTMLInputElement)) return null;
1023
1187
  return {
1024
1188
  tag: 'input',
1025
1189
  inputType: (el.type || 'text').toLowerCase(),
1026
- value: String(el.value || '').slice(0, 160)
1190
+ value: el.type === 'password' ? undefined : String(el.value || '').slice(0, 160)
1027
1191
  };
1028
- })()`, undefined, timeout);
1192
+ })()`, undefined, remainingInputTimeout(deadline));
1193
+ if (privacy) {
1194
+ privacy.sensitive = sensitiveBefore || selectionTarget?.inputType === 'password';
1195
+ }
1029
1196
  if (selectionTarget && !supportsTextSelection(selectionTarget.tag, selectionTarget.inputType)) {
1030
1197
  throw new StructuredToolError('UNSUPPORTED_SELECTION', `input[type=${selectionTarget.inputType}] 不支持文本 selection`, '请改用 type mode="controlled" 设置完整 value,replace 事件会对这类 input 使用完整 value 更新路径', {
1031
1198
  elementTag: selectionTarget.tag,
@@ -1035,16 +1202,21 @@ async function handleUnifiedSelect({ unifiedSession, session, mode, timeout, fra
1035
1202
  recommendedMode: 'controlled',
1036
1203
  });
1037
1204
  }
1038
- await selectText(unifiedSession, event.find, event.target, event.nth, timeout);
1205
+ await selectText(unifiedSession, event.find, event.target, event.nth, remainingInputTimeout(deadline), privacy);
1039
1206
  return undefined;
1040
1207
  }
1041
- async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, frame }, event) {
1042
- await focusTargetIfNeeded(unifiedSession, session, mode, event.target, timeout, frame);
1208
+ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, frame, privacy }, event) {
1209
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1210
+ const sensitiveBefore = privacy?.sensitive ?? false;
1211
+ if (privacy) {
1212
+ privacy.sensitive = true;
1213
+ }
1214
+ await focusTargetIfNeeded(unifiedSession, session, mode, event.target, remainingInputTimeout(deadline), frame);
1043
1215
  const directResult = await unifiedSession.evaluate(`function(findText, replacementText, nth) {
1044
1216
  var el = document.activeElement;
1045
1217
  if (!(el instanceof HTMLInputElement)) return {handled: false};
1046
1218
  var type = (el.type || 'text').toLowerCase();
1047
- if (['text', 'search', 'tel', 'url', 'password'].indexOf(type) !== -1) return {handled: false};
1219
+ if (['text', 'search', 'tel', 'url', 'password'].indexOf(type) !== -1) return {handled: false, inputType: type};
1048
1220
  var current = String(el.value || '');
1049
1221
  var pos = -1;
1050
1222
  for (var i = 0; i <= nth; i++) {
@@ -1097,7 +1269,10 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1097
1269
  actualValue: actual.slice(0, 160),
1098
1270
  reason: actual === requested ? undefined : 'value_not_applied'
1099
1271
  };
1100
- }`, undefined, timeout, [event.find, event.text, event.nth ?? 0]);
1272
+ }`, undefined, remainingInputTimeout(deadline), [event.find, event.text, event.nth ?? 0]);
1273
+ if (privacy) {
1274
+ privacy.sensitive = sensitiveBefore || directResult.inputType === 'password';
1275
+ }
1101
1276
  if (directResult.handled) {
1102
1277
  if (!directResult.success) {
1103
1278
  const valueNotApplied = directResult.reason === 'value_not_applied';
@@ -1130,7 +1305,7 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1130
1305
  normalized: directResult.actualValue !== directResult.requestedValue,
1131
1306
  };
1132
1307
  }
1133
- const formatted = await selectText(unifiedSession, event.find, event.target, event.nth, timeout);
1308
+ const formatted = await selectText(unifiedSession, event.find, event.target, event.nth, remainingInputTimeout(deadline), privacy);
1134
1309
  let selectionConfirmed = false;
1135
1310
  for (let i = 0; i < 25; i++) {
1136
1311
  const hasSelection = await unifiedSession.evaluate(`(function() {
@@ -1140,12 +1315,12 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1140
1315
  }
1141
1316
  var sel = window.getSelection();
1142
1317
  return sel && !sel.isCollapsed;
1143
- })()`);
1318
+ })()`, undefined, remainingInputTimeout(deadline));
1144
1319
  if (hasSelection) {
1145
1320
  selectionConfirmed = true;
1146
1321
  break;
1147
1322
  }
1148
- await new Promise((resolve) => setTimeout(resolve, 20));
1323
+ await new Promise((resolve) => setTimeout(resolve, Math.min(20, remainingInputTimeout(deadline))));
1149
1324
  }
1150
1325
  if (!selectionConfirmed) {
1151
1326
  throw new Error(`选区同步失败:文本 "${event.find}" 已定位但未能建立选区,无法执行替换`);
@@ -1168,12 +1343,12 @@ async function handleUnifiedReplace({ unifiedSession, session, mode, timeout, fr
1168
1343
  if (!editable || !editable.isContentEditable) return 'readonly';
1169
1344
  if (document.execCommand('insertText', false, replacementText)) return 'ok';
1170
1345
  return 'fallback';
1171
- }`, undefined, timeout, [event.text]);
1346
+ }`, undefined, remainingInputTimeout(deadline), [event.text]);
1172
1347
  if (replaceResult === 'readonly') {
1173
1348
  throw new Error(`目标元素不可编辑,已选中文本 "${event.find}" 但无法替换`);
1174
1349
  }
1175
1350
  if (replaceResult === 'fallback') {
1176
- await unifiedSession.typeText(event.text);
1351
+ await unifiedSession.typeText(event.text, 0, remainingInputTimeout(deadline));
1177
1352
  }
1178
1353
  if (formatted) {
1179
1354
  return `替换的文本原在 <${formatted}> 标签内,替换后格式可能丢失`;
@@ -1336,7 +1511,16 @@ async function editorAction(unifiedSession, action, event, timeout, frame) {
1336
1511
  return {success: true, command: command};
1337
1512
  }`, undefined, timeout, [action, event.text ?? '', event.command ?? '']);
1338
1513
  }
1339
- async function getTargetPointExtension(unifiedSession, target, timeout, frame) {
1514
+ async function getTargetPointExtension(unifiedSession, target, timeout, frame, scroll = true) {
1515
+ const budget = timeout ?? DEFAULT_TIMEOUT;
1516
+ const deadline = Date.now() + budget;
1517
+ const remaining = () => {
1518
+ const value = deadline - Date.now();
1519
+ if (value <= 0) {
1520
+ throwInputTimeoutError(budget);
1521
+ }
1522
+ return value;
1523
+ };
1340
1524
  const frameOffset = unifiedSession.getFrameOffset();
1341
1525
  const isStealth = unifiedSession.getInputMode() === 'stealth';
1342
1526
  // 原始坐标:用户意图为 iframe 相对坐标
@@ -1348,7 +1532,7 @@ async function getTargetPointExtension(unifiedSession, target, timeout, frame) {
1348
1532
  return { x: target.x, y: target.y };
1349
1533
  }
1350
1534
  const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
1351
- const elements = await unifiedSession.find(selector, text, xpath, timeout);
1535
+ const elements = await unifiedSession.find(selector, text, xpath, remaining());
1352
1536
  const nth = nthParam ?? 0;
1353
1537
  if (elements.length === 0) {
1354
1538
  throw new StructuredToolError('TARGET_NOT_FOUND', `未找到目标元素: ${JSON.stringify(target)}`, '请检查 target 是否正确,或先用 extract type=state 查看 interactiveElements 候选', await buildTargetDiagnosticContext(unifiedSession, target, elements.length, nth, timeout, '目标元素未找到', frame));
@@ -1364,20 +1548,15 @@ async function getTargetPointExtension(unifiedSession, target, timeout, frame) {
1364
1548
  const el = ref?.deref();
1365
1549
  if (!el) return null;
1366
1550
  const r = el.getBoundingClientRect();
1367
- if (r.top < 0 || r.bottom > window.innerHeight || r.left < 0 || r.right > window.innerWidth) {
1551
+ if (${scroll} && (r.top < 0 || r.bottom > window.innerHeight || r.left < 0 || r.right > window.innerWidth)) {
1368
1552
  el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
1369
1553
  }
1370
1554
  const r2 = el.getBoundingClientRect();
1371
1555
  return { x: r2.x, y: r2.y, width: r2.width, height: r2.height };
1372
- })()`);
1373
- // refId 失效等异常:fallback 到原始 find rect(父视口绝对)
1556
+ })()`, undefined, remaining());
1557
+ remaining();
1374
1558
  if (!iframeRelRect) {
1375
- const rect = elements[nth].rect;
1376
- const point = { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
1377
- if (frameOffset && isStealth) {
1378
- return { x: point.x - frameOffset.x, y: point.y - frameOffset.y, refId };
1379
- }
1380
- return { ...point, refId };
1559
+ throw new StructuredToolError('TARGET_NOT_FOUND', '目标元素引用已失效,未使用旧坐标派发事件', '请重新读取页面并确认 target', { target, refId, actionExecuted: false });
1381
1560
  }
1382
1561
  // 主 frame:iframeRelRect 就是父视口绝对
1383
1562
  if (!frameOffset) {
@@ -1398,7 +1577,8 @@ async function getTargetPointExtension(unifiedSession, target, timeout, frame) {
1398
1577
  // iframe + precise:消费者(chrome.debugger)需要父视口绝对,
1399
1578
  // scrollIntoView({block:'center'}) 会 cascade 到父框架,导致 frameOffset 与父绝对 rect 都过期,
1400
1579
  // refetch find() 让 content-handler 重新计算 frameOffset 并返回最新父绝对 rect
1401
- const refreshed = await unifiedSession.find(selector, text, xpath, timeout);
1580
+ const refreshed = await unifiedSession.find(selector, text, xpath, remaining());
1581
+ remaining();
1402
1582
  const rect = refreshed[nth]?.rect ?? elements[nth].rect;
1403
1583
  return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2, refId };
1404
1584
  }
@@ -1411,8 +1591,6 @@ async function executeCdpEvent(session, event, humanize, timeout) {
1411
1591
  await handler({ session, humanize, timeout }, event);
1412
1592
  }
1413
1593
  const cdpInputHandlers = {
1414
- keydown: handleCdpKeyDown,
1415
- keyup: handleCdpKeyUp,
1416
1594
  click: handleCdpClick,
1417
1595
  mousedown: handleCdpMouseDown,
1418
1596
  mouseup: handleCdpMouseUp,
@@ -1425,13 +1603,31 @@ const cdpInputHandlers = {
1425
1603
  wait: handleCdpWait,
1426
1604
  drag: handleCdpDrag,
1427
1605
  };
1428
- async function handleCdpKeyDown({ session }, event) {
1429
- await session.keyDown(event.key, event.commands);
1430
- }
1431
- async function handleCdpKeyUp({ session }, event) {
1432
- await session.keyUp(event.key);
1433
- }
1434
1606
  async function handleCdpClick({ session, humanize, timeout }, event) {
1607
+ if (event.force) {
1608
+ const locator = session.createLocator(event.target, { timeout });
1609
+ await locator.evaluateOn(`function() {
1610
+ if (!this.isConnected) throw new Error('目标元素已移除,未执行点击');
1611
+ const button = ${JSON.stringify(event.button ?? 'left')};
1612
+ const count = ${event.clickCount ?? 1};
1613
+ const codes = {left: 0, middle: 1, right: 2, back: 3, forward: 4};
1614
+ const masks = {left: 1, middle: 4, right: 2, back: 8, forward: 16};
1615
+ const rect = this.getBoundingClientRect();
1616
+ const base = {bubbles: true, cancelable: true, composed: true, view: window,
1617
+ button: codes[button], clientX: rect.x + rect.width / 2, clientY: rect.y + rect.height / 2};
1618
+ for (let detail = 1; detail <= count; ++detail) {
1619
+ const down = this.dispatchEvent(new MouseEvent('mousedown', {...base, detail, buttons: masks[button]}));
1620
+ if (down && button === 'left' && typeof this.focus === 'function') this.focus();
1621
+ this.dispatchEvent(new MouseEvent('mouseup', {...base, detail, buttons: 0}));
1622
+ const type = button === 'left' ? 'click' : button === 'right' ? 'contextmenu' : 'auxclick';
1623
+ this.dispatchEvent(new MouseEvent(type, {...base, detail, buttons: 0}));
1624
+ if (button === 'left' && detail === 2) {
1625
+ this.dispatchEvent(new MouseEvent('dblclick', {...base, detail, buttons: 0}));
1626
+ }
1627
+ }
1628
+ }`);
1629
+ return;
1630
+ }
1435
1631
  if (event.target) {
1436
1632
  await moveToTarget(session, event.target, humanize, timeout);
1437
1633
  }
@@ -1465,18 +1661,23 @@ async function handleCdpTouchStart({ session, timeout }, event) {
1465
1661
  await session.touchStart(point.x, point.y);
1466
1662
  }
1467
1663
  async function handleCdpTouchMove({ session, humanize, timeout }, event) {
1468
- const point = await getTargetPoint(session, event.target, timeout);
1664
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1665
+ const point = await getTargetPoint(session, event.target, remainingInputTimeout(deadline));
1469
1666
  if (humanize && event.steps && event.steps > 1) {
1470
1667
  const current = session.getBehaviorSimulator().getCurrentPosition();
1471
1668
  const path = generateBezierPath(current, point, event.steps);
1472
1669
  for (const p of path) {
1670
+ remainingInputTimeout(deadline);
1473
1671
  await session.touchMove(p.x, p.y);
1474
- await randomDelay(5, 15);
1672
+ const remaining = remainingInputTimeout(deadline);
1673
+ await randomDelay(Math.min(5, remaining), Math.min(15, remaining));
1475
1674
  }
1476
1675
  }
1477
1676
  else {
1677
+ remainingInputTimeout(deadline);
1478
1678
  await session.touchMove(point.x, point.y);
1479
1679
  }
1680
+ remainingInputTimeout(deadline);
1480
1681
  }
1481
1682
  async function handleCdpTouchEnd({ session }) {
1482
1683
  await session.touchEnd();
@@ -1485,28 +1686,34 @@ async function handleCdpType({ session, humanize, timeout }, event) {
1485
1686
  if (event.dispatch || event.mode === 'controlled') {
1486
1687
  throw new Error('controlled/dispatch 输入需要 Extension 连接,当前为 CDP 模式');
1487
1688
  }
1689
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1488
1690
  if (event.target) {
1489
- await moveToTarget(session, event.target, humanize, timeout, undefined, 'input');
1691
+ await moveToTarget(session, event.target, humanize, remainingInputTimeout(deadline), undefined, 'input');
1490
1692
  await session.mouseDown('left');
1491
1693
  await session.mouseUp('left');
1694
+ if (!('x' in event.target)) {
1695
+ await focusCdpTarget(session, event.target, remainingInputTimeout(deadline));
1696
+ }
1492
1697
  }
1493
1698
  else {
1494
1699
  const hasActiveFocus = await session.evaluate('!!document.activeElement && ' +
1495
1700
  'document.activeElement !== document.body && ' +
1496
- 'document.activeElement !== document.documentElement');
1701
+ 'document.activeElement !== document.documentElement', undefined, remainingInputTimeout(deadline));
1497
1702
  if (!hasActiveFocus) {
1498
1703
  throw new Error('type 事件在无 target 时需要页面已有焦点元素,请提供 target 或先 click 目标元素');
1499
1704
  }
1500
1705
  }
1501
1706
  const delay = event.delay ?? 0;
1502
1707
  if (humanize) {
1503
- for (const char of event.text) {
1504
- await session.type(char);
1505
- await randomDelay(getTypingDelay(delay), getTypingDelay(delay) * 1.5);
1708
+ for (const char of event.text.replace(/\r\n?/g, '\n')) {
1709
+ await session.type(char, 0, remainingInputTimeout(deadline));
1710
+ const remaining = remainingInputTimeout(deadline);
1711
+ await randomDelay(Math.min(getTypingDelay(delay), remaining), Math.min(getTypingDelay(delay) * 1.5, remaining));
1506
1712
  }
1713
+ remainingInputTimeout(deadline);
1507
1714
  }
1508
1715
  else {
1509
- await session.type(event.text, delay);
1716
+ await session.type(event.text, delay, remainingInputTimeout(deadline));
1510
1717
  }
1511
1718
  }
1512
1719
  async function handleCdpWait({ timeout }, event) {
@@ -1520,14 +1727,16 @@ async function handleCdpDrag() {
1520
1727
  * 移动到目标位置
1521
1728
  */
1522
1729
  async function moveToTarget(session, target, humanize, timeout, steps, waitType = 'click') {
1523
- const point = await getTargetPoint(session, target, timeout, waitType);
1730
+ const deadline = Date.now() + (timeout ?? DEFAULT_TIMEOUT);
1731
+ const point = await getTargetPoint(session, target, remainingInputTimeout(deadline), waitType);
1524
1732
  const simulator = session.getBehaviorSimulator();
1525
1733
  if (humanize) {
1526
1734
  // 人类化鼠标移动(贝塞尔曲线)
1527
1735
  const path = generateBezierPath(simulator.getCurrentPosition(), point, steps);
1528
1736
  for (const p of path) {
1529
- await session.mouseMove(p.x, p.y);
1530
- await randomDelay(getMouseMoveDelay(), getMouseMoveDelay() * 2);
1737
+ await session.mouseMove(p.x, p.y, remainingInputTimeout(deadline));
1738
+ const remaining = remainingInputTimeout(deadline);
1739
+ await randomDelay(Math.min(getMouseMoveDelay(), remaining), Math.min(getMouseMoveDelay() * 2, remaining));
1531
1740
  }
1532
1741
  }
1533
1742
  else if (steps && steps > 1) {
@@ -1537,13 +1746,14 @@ async function moveToTarget(session, target, humanize, timeout, steps, waitType
1537
1746
  const t = i / steps;
1538
1747
  const x = current.x + (point.x - current.x) * t;
1539
1748
  const y = current.y + (point.y - current.y) * t;
1540
- await session.mouseMove(x, y);
1749
+ await session.mouseMove(x, y, remainingInputTimeout(deadline));
1541
1750
  }
1542
1751
  }
1543
1752
  else {
1544
1753
  // 直接移动
1545
- await session.mouseMove(point.x, point.y);
1754
+ await session.mouseMove(point.x, point.y, remainingInputTimeout(deadline));
1546
1755
  }
1756
+ remainingInputTimeout(deadline);
1547
1757
  }
1548
1758
  /**
1549
1759
  * 获取目标点坐标(带自动等待)
@@ -1553,12 +1763,21 @@ async function getTargetPoint(session, target, timeout, waitType = 'click') {
1553
1763
  if ('x' in target && 'y' in target) {
1554
1764
  return { x: target.x, y: target.y };
1555
1765
  }
1766
+ const budget = timeout ?? DEFAULT_TIMEOUT;
1767
+ const deadline = Date.now() + budget;
1768
+ const remaining = () => {
1769
+ const value = deadline - Date.now();
1770
+ if (value <= 0) {
1771
+ throwInputTimeoutError(budget);
1772
+ }
1773
+ return value;
1774
+ };
1556
1775
  // 使用 Locator 定位元素
1557
- const locator = session.createLocator(target, { timeout });
1776
+ const locator = session.createLocator(target, { timeout: remaining() });
1558
1777
  const nodeId = await locator.find();
1559
1778
  // 根据操作类型执行自动等待
1560
1779
  if (waitType !== 'none') {
1561
- const autoWait = session.createAutoWait({ timeout });
1780
+ const autoWait = session.createAutoWait({ timeout: remaining() });
1562
1781
  if (waitType === 'click') {
1563
1782
  await autoWait.waitForClickable(nodeId);
1564
1783
  }
@@ -1566,7 +1785,10 @@ async function getTargetPoint(session, target, timeout, waitType = 'click') {
1566
1785
  await autoWait.waitForInputReady(nodeId);
1567
1786
  }
1568
1787
  }
1569
- return locator.getClickablePoint();
1788
+ remaining();
1789
+ const point = await locator.getClickablePoint();
1790
+ remaining();
1791
+ return point;
1570
1792
  }
1571
1793
  /**
1572
1794
  * 注册 input 工具