@pyrokine/mcp-chrome 2.3.1 → 2.4.0

package/dist/tools/input.js

@@ -11,8 +11,25 @@
 import { z } from 'zod';
 import { generateBezierPath, getMouseMoveDelay, getTypingDelay, randomDelay } from '../anti-detection/index.js';
 import { formatErrorResponse, formatResponse, getSession, getUnifiedSession } from '../core/index.js';
+import { appendDiagnostics, finishDiagnostics, startDiagnostics } from './diagnostics.js';
 import { postConditionSchema, waitForPostCondition } from './post-condition.js';
 import { targetToFindParams, targetZodSchema } from './schema.js';
+import { buildTargetDiagnostics } from './target-diagnostics.js';
+const INPUT_WAIT_MAX_MS = 60_000;
+const TEXT_SELECTION_INPUT_TYPES = new Set(['text', 'search', 'tel', 'url', 'password']);
+export function supportsTextSelection(tag, inputType) {
+    return (tag.toLowerCase() === 'textarea' ||
+        (tag.toLowerCase() === 'input' && TEXT_SELECTION_INPUT_TYPES.has((inputType ?? 'text').toLowerCase())));
+}
+export function replaceNthOccurrence(value, find, replacement, nth = 0) {
+    let index = -1;
+    for (let occurrence = 0; occurrence <= nth; occurrence++) {
+        index = value.indexOf(find, index + (occurrence > 0 ? 1 : 0));
+        if (index === -1)
+            return null;
+    }
+    return value.slice(0, index) + replacement + value.slice(index + find.length);
+}
 /**
  * InputEvent schema
  */
@@ -61,7 +78,13 @@ const inputEventSchema = z.object({
     deltaY: z.number().optional().describe('垂直滚动量'),
     text: z.string().max(10000).optional().describe('输入文本（type，最大 10000 字符）或替换文本（replace）'),
     delay: z.number().min(0).max(100).optional().describe('按键间隔毫秒（type 事件最大 100ms，避免长时延 DoS）'),
-    ms: z.number().optional().describe('等待毫秒'),
+    ms: z
+        .number()
+        .int()
+        .min(0)
+        .max(INPUT_WAIT_MAX_MS)
+        .optional()
+        .describe('等待毫秒（wait 事件最大 60000ms，且不能超过 input 剩余 timeout）'),
     find: z.string().optional().describe('要查找并选中的文本（select/replace）'),
     nth: z.number().optional().describe('第 N 个匹配（select/replace，从 0 开始，默认 0 即第一个）'),
     command: z.string().optional().describe('浏览器编辑命令（editorCommand），如 bold、italic、insertOrderedList'),
@@ -131,23 +154,65 @@ async function handleInput(args) {
         const humanize = args.humanize ?? false;
         return await unifiedSession.withTabId(args.tabId, async () => {
             return await unifiedSession.withFrame(args.frame, async () => {
-                const diagnosticsStart = args.diagnostics ? await captureDiagnosticsStart(unifiedSession) : undefined;
+                const diagnostics = await startDiagnostics(unifiedSession, args.diagnostics);
                 const warnings = [];
                 const eventResults = [];
                 const session = mode === 'extension' ? undefined : getSession();
-                for (const event of args.events) {
-                    const result = await executeInputEvent({ unifiedSession, session, mode, humanize, timeout: args.timeout }, event);
-                    if (typeof result === 'string') {
-                        warnings.push(result);
+                const inputStartedAt = Date.now();
+                let eventsExecuted = 0;
+                try {
+                    for (const event of args.events) {
+                        const eventTimeout = args.timeout === undefined
+                            ? undefined
+                            : Math.max(0, args.timeout - (Date.now() - inputStartedAt));
+                        if (eventTimeout !== undefined && eventTimeout <= 0) {
+                            throw new Error(`input timeout before event dispatch (${args.timeout}ms)`);
+                        }
+                        const result = await executeInputEvent({ unifiedSession, session, mode, humanize, timeout: eventTimeout, frame: args.frame }, event);
+                        ++eventsExecuted;
+                        if (typeof result === 'string') {
+                            warnings.push(result);
+                        }
+                        else if (result) {
+                            eventResults.push(result);
+                        }
                     }
-                    else if (result) {
-                        eventResults.push(result);
+                }
+                catch (error) {
+                    const response = formatErrorResponse(error);
+                    const text = response.content[0]?.text;
+                    if (text) {
+                        try {
+                            const payload = JSON.parse(text);
+                            const message = error instanceof Error ? error.message : String(error);
+                            const timedOut = /timeout|超时/i.test(message);
+                            const preActionTimeout = /timeout before event dispatch|超过 input 剩余 timeout/i.test(message);
+                            const actionMayHaveExecuted = timedOut && !preActionTimeout;
+                            payload.eventsExecuted = eventsExecuted;
+                            payload.actionExecuted = eventsExecuted > 0 || actionMayHaveExecuted;
+                            payload.actionStatus = actionMayHaveExecuted ? 'unknown' : 'failed';
+                            payload.verificationRequested = Boolean(args.postCondition);
+                            payload.verificationStatus = 'unavailable';
+                            payload.failureStage = 'action';
+                            payload.retryable = /timeout|超时|disconnect|未连接|context|debugger/i.test(message);
+                            appendDiagnostics(payload, await finishDiagnostics(unifiedSession, diagnostics));
+                            response.content[0].text = JSON.stringify(payload, null, 2);
+                        }
+                        catch {
+                            // 保留原始错误响应
+                        }
                     }
+                    return response;
                 }
                 const result = {
                     success: true,
-                    eventsExecuted: args.events.length,
+                    eventsExecuted,
                     mode,
+                    actionExecuted: true,
+                    actionStatus: 'completed',
+                    verificationRequested: Boolean(args.postCondition),
+                    verificationStatus: 'unavailable',
+                    retryable: false,
                 };
                 if (warnings.length > 0) {
                     result.warnings = warnings;
@@ -156,17 +221,46 @@ async function handleInput(args) {
                     result.eventResults = eventResults;
                 }
                 if (args.postCondition) {
-                    result.postCondition = await waitForPostCondition(unifiedSession, args.postCondition, 'input');
-                }
-                if (diagnosticsStart) {
-                    result.diagnostics = await captureDiagnosticsDelta(unifiedSession, diagnosticsStart);
+                    const postCondition = await waitForPostCondition(unifiedSession, args.postCondition, 'input');
+                    result.postCondition = postCondition;
+                    result.verificationStatus = postCondition.verificationStatus;
+                    result.retryable = postCondition.retryable;
+                    if (postCondition.verificationStatus !== 'matched') {
+                        result.success = false;
+                        result.failureStage = 'verification';
+                    }
                 }
+                appendDiagnostics(result, await finishDiagnostics(unifiedSession, diagnostics));
                 return formatResponse(result);
             }); // withFrame
         }); // withTabId
     }
     catch (error) {
-        return formatErrorResponse(error);
+        const response = formatErrorResponse(error);
+        const text = response.content[0]?.text;
+        if (text) {
+            try {
+                const payload = JSON.parse(text);
+                const message = error instanceof Error ? error.message : String(error);
+                Object.assign(payload, {
+                    actionExecuted: false,
+                    actionStatus: 'failed',
+                    verificationRequested: Boolean(args.postCondition),
+                    verificationStatus: 'unavailable',
+                    failureStage: 'action',
+                    retryable: /timeout|超时|disconnect|未连接|context|debugger|attach/i.test(message),
+                    diagnosticsStatus: args.diagnostics ? 'unavailable' : 'disabled',
+                });
+                if (args.diagnostics) {
+                    payload.diagnosticsError = 'diagnostics 未能在 tab/frame 初始化失败前启动';
+                }
+                response.content[0].text = JSON.stringify(payload, null, 2);
+            }
+            catch {
+                // 保留原始错误响应
+            }
+        }
+        return response;
     }
 }
 const unifiedOnlyEventTypes = new Set([
@@ -178,7 +272,7 @@ const unifiedOnlyEventTypes = new Set([
 ]);
 async function executeInputEvent(context, event) {
     if (context.mode === 'extension' || unifiedOnlyEventTypes.has(event.type)) {
-        return executeUnifiedEvent(context.unifiedSession, event, context.humanize, context.timeout);
+        return executeUnifiedEvent(context.unifiedSession, event, context.humanize, context.timeout, context.frame);
     }
     if (!context.session) {
         throw new Error('CDP 输入事件缺少 session');
@@ -186,27 +280,6 @@ async function executeInputEvent(context, event) {
     await executeCdpEvent(context.session, event, context.humanize, context.timeout);
     return undefined;
 }
-async function captureDiagnosticsStart(unifiedSession) {
-    await unifiedSession.enableConsole();
-    await unifiedSession.enableNetwork();
-    const consoleLogs = await unifiedSession.getConsoleLogs();
-    const network = await unifiedSession.getNetworkRequests();
-    return { consoleCount: consoleLogs.length, networkCount: network.length };
-}
-async function captureDiagnosticsDelta(unifiedSession, start) {
-    const consoleLogs = await unifiedSession.getConsoleLogs();
-    const network = await unifiedSession.getNetworkRequests();
-    return {
-        console: consoleLogs
-            .slice(start.consoleCount)
-            .filter((item) => ['error', 'warning', 'warn'].includes(item.level))
-            .slice(-20),
-        failedRequests: network
-            .slice(start.networkCount)
-            .filter((item) => item.errorText || (item.status !== undefined && item.status >= 400))
-            .slice(-20),
-    };
-}
 /**
  * 通过真实鼠标事件选中页面文本
  *
@@ -220,15 +293,20 @@ async function captureDiagnosticsDelta(unifiedSession, start) {
  * 如果 target 是选择器类型，先通过 actionableClick 聚焦
  * select/replace 事件用，保证选区建立前 activeElement 就是目标
  */
-async function focusTargetForCommands(unifiedSession, target, timeout) {
+async function focusTargetForCommands(unifiedSession, target, timeout, frame) {
     if ('x' in target || 'y' in target) {
-        return true;
+        const point = await getTargetPointExtension(unifiedSession, target, timeout, frame);
+        await unifiedSession.mouseMove(point.x, point.y);
+        await unifiedSession.mouseClick('left');
+        return;
     }
     const params = targetToFindParams(target);
     const els = await unifiedSession.find(params.selector, params.text, params.xpath, timeout);
     const nth0 = params.nth ?? 0;
     if (els.length <= nth0) {
-        return false;
+        throw new StructuredToolError(els.length === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', els.length === 0
+            ? `未找到命令目标: ${JSON.stringify(target)}`
+            : `第 ${nth0} 个命令目标不存在（共 ${els.length} 个）`, '请检查 target、frame 和 target.nth，或先用 extract type=state 查看当前候选元素', await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, timeout, '命令目标未找到', frame));
     }
     const focused = await unifiedSession.evaluate(`(() => {
             const ref = window.__mcpElementMap?.[${JSON.stringify(els[nth0].refId)}]
@@ -239,27 +317,38 @@ async function focusTargetForCommands(unifiedSession, target, timeout) {
             el.focus()
             return document.activeElement === el
         })()`, undefined, timeout);
-    return focused === true;
+    if (focused !== true) {
+        throw new StructuredToolError('TARGET_FOCUS_FAILED', '命令目标未成功聚焦', '请检查目标是否可编辑、未 disabled 并处于正确 frame', await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, timeout, '命令目标聚焦失败', frame));
+    }
 }
-async function focusTargetIfNeeded(unifiedSession, target, nth, timeout) {
-    if (!target || 'x' in target || 'y' in target) {
+async function focusTargetIfNeeded(unifiedSession, target, timeout, frame) {
+    if (!target) {
+        return;
+    }
+    if ('x' in target || 'y' in target) {
+        const point = await getTargetPointExtension(unifiedSession, target, timeout, frame);
+        await unifiedSession.mouseMove(point.x, point.y);
+        await unifiedSession.mouseClick('left');
         return;
     }
     const params = targetToFindParams(target);
     const els = await unifiedSession.find(params.selector, params.text, params.xpath, timeout);
-    const nth0 = params.nth ?? nth ?? 0;
-    if (els.length > nth0) {
-        try {
-            await unifiedSession.actionableClick(els[nth0].refId);
-        }
-        catch (err) {
-            // 失败时不中断（可能是 contenteditable 不接受 click focus），但记录 warning
-            console.warn('[MCP] focusTargetIfNeeded 聚焦失败，select/replace 将回退到 mouseClick 聚焦:', err);
-        }
+    const nth0 = params.nth ?? 0;
+    if (els.length <= nth0) {
+        throw new StructuredToolError(els.length === 0 ? 'TARGET_NOT_FOUND' : 'TARGET_INDEX_OUT_OF_RANGE', els.length === 0
+            ? `未找到目标元素: ${JSON.stringify(target)}`
+            : `第 ${nth0} 个匹配元素不存在（共 ${els.length} 个）`, '请检查 target、frame 和 target.nth，或先用 extract type=state 查看当前候选元素', await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, timeout, '聚焦目标未找到', frame));
+    }
+    const result = await unifiedSession.actionableClick(els[nth0].refId);
+    if (!result.success) {
+        throw new StructuredToolError('ACTIONABILITY_FAILED', result.error || '目标元素无法聚焦', result.suggestions?.[0] ?? '请检查元素是否可见、未被遮挡并处于正确 frame', {
+            ...result,
+            ...(await buildTargetDiagnosticContext(unifiedSession, target, els.length, nth0, timeout, result.error || '目标元素无法聚焦', frame)),
+        });
     }
 }
-async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeSelector, scopeText, scopeXpath, timeout) {
-    return await unifiedSession.evaluate(`function(findText, nth, scopeTarget, scopeSelector, scopeText, scopeXpath) {
+async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, occurrenceNth, scopeNth, scopeSelector, scopeText, scopeXpath, timeout) {
+    return await unifiedSession.evaluate(`function(findText, occurrenceNth, scopeNth, scopeTarget, scopeSelector, scopeText, scopeXpath) {
         function selectorFor(el) {
             if (!(el instanceof Element)) return null;
             if (el.id) return '#' + CSS.escape(el.id);
@@ -300,22 +389,21 @@ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTa
         }
         var root = document.body;
         if (scopeXpath) {
-            var xr = document.evaluate(scopeXpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
-            root = xr.singleNodeValue;
+            var xr = document.evaluate(scopeXpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+            root = xr.snapshotItem(scopeNth);
         } else if (scopeSelector) {
-            var candidates = document.querySelectorAll(scopeSelector);
+            var candidates = Array.from(document.querySelectorAll(scopeSelector));
             if (scopeText) {
-                for (var ci = 0; ci < candidates.length; ci++) {
-                    if ((candidates[ci].textContent || '').includes(scopeText)) { root = candidates[ci]; break; }
-                }
-            } else {
-                root = candidates[0];
+                candidates = candidates.filter(function(candidate) {
+                    return (candidate.textContent || '').includes(scopeText);
+                });
             }
+            root = candidates[scopeNth];
         } else if (scopeText) {
-            var all = document.querySelectorAll('*');
-            for (var ai = 0; ai < all.length; ai++) {
-                if ((all[ai].textContent || '').includes(scopeText)) { root = all[ai]; break; }
-            }
+            var all = Array.from(document.querySelectorAll('*')).filter(function(candidate) {
+                return (candidate.textContent || '').includes(scopeText);
+            });
+            root = all[scopeNth];
         }
         var candidateElements = [];
         if (root instanceof Element) {
@@ -327,7 +415,8 @@ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTa
         return {
             scope: {
                 target: scopeTarget,
-                nth: nth,
+                targetNth: scopeNth,
+                occurrenceNth: occurrenceNth,
                 findText: findText,
                 selector: scopeSelector,
                 text: scopeText,
@@ -348,40 +437,41 @@ async function collectTextSelectionDiagnostics(unifiedSession, findText, scopeTa
             },
             candidates: candidateElements.map(summarizeElement).filter(Boolean)
         };
-    }`, undefined, timeout, [findText, nth, scopeTarget ?? null, scopeSelector, scopeText, scopeXpath]);
+    }`, undefined, timeout, [findText, occurrenceNth, scopeNth, scopeTarget ?? null, scopeSelector, scopeText, scopeXpath]);
 }
 async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeout) {
     // 将 target 转为查询参数，传入注入脚本进行 DOM 查询
     let scopeSelector = null;
     let scopeText = null;
     let scopeXpath = null;
+    let scopeNth = 0;
     if (scopeTarget && !('x' in scopeTarget) && !('y' in scopeTarget)) {
         const params = targetToFindParams(scopeTarget);
         scopeSelector = params.selector ?? null;
         scopeText = params.text ?? null;
         scopeXpath = params.xpath ?? null;
+        scopeNth = params.nth ?? 0;
     }
     // Step 1: 注入脚本定位文本
-    const result = await unifiedSession.evaluate(`function(findText, nth, scopeSelector, scopeText, scopeXpath) {
+    const result = await unifiedSession.evaluate(`function(findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath) {
         // 确定搜索根节点
         var root = document.body;
         if (scopeXpath) {
-            var xr = document.evaluate(scopeXpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
-            root = xr.singleNodeValue;
+            var xr = document.evaluate(scopeXpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+            root = xr.snapshotItem(scopeNth);
         } else if (scopeSelector) {
-            var candidates = document.querySelectorAll(scopeSelector);
+            var candidates = Array.from(document.querySelectorAll(scopeSelector));
             if (scopeText) {
-                for (var ci = 0; ci < candidates.length; ci++) {
-                    if ((candidates[ci].textContent || '').includes(scopeText)) { root = candidates[ci]; break; }
-                }
-            } else {
-                root = candidates[0];
+                candidates = candidates.filter(function(candidate) {
+                    return (candidate.textContent || '').includes(scopeText);
+                });
             }
+            root = candidates[scopeNth];
         } else if (scopeText) {
-            var all = document.querySelectorAll('*');
-            for (var ai = 0; ai < all.length; ai++) {
-                if ((all[ai].textContent || '').includes(scopeText)) { root = all[ai]; break; }
-            }
+            var all = Array.from(document.querySelectorAll('*')).filter(function(candidate) {
+                return (candidate.textContent || '').includes(scopeText);
+            });
+            root = all[scopeNth];
         }
         if (!root) return {type: 'noscope'};
 
@@ -389,6 +479,11 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
         var tag = root.tagName;
         if (tag === 'INPUT' || tag === 'TEXTAREA') {
             var val = root.value || '';
+            var inputType = tag === 'INPUT' ? (root.type || 'text').toLowerCase() : 'textarea';
+            var selectionCapable = tag === 'TEXTAREA' || ['text', 'search', 'tel', 'url', 'password'].indexOf(inputType) !== -1;
+            if (!selectionCapable) {
+                return {type: 'unsupported', tag: tag.toLowerCase(), inputType: inputType, currentValue: String(val).slice(0, 160)};
+            }
             var pos = -1;
             for (var n = 0; n <= nth; n++) {
                 pos = val.indexOf(findText, pos + (n > 0 ? 1 : 0));
@@ -396,9 +491,7 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
             }
             // 原子化：定位到 input 同时完成 focus + setSelectionRange，避免外层 mouseClick 聚焦不可靠
             root.focus();
-            if (typeof root.setSelectionRange === 'function') {
-                root.setSelectionRange(pos, pos + findText.length);
-            }
+            root.setSelectionRange(pos, pos + findText.length);
             return {type: 'input', selectionStart: pos, selectionEnd: pos + findText.length};
         }
 
@@ -407,16 +500,19 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
         for (var k = 0; k < inputs.length; k++) {
             var inp = inputs[k];
             var v = inp.value || '';
+            var childType = inp.tagName === 'INPUT' ? (inp.type || 'text').toLowerCase() : 'textarea';
+            var childSelectionCapable = inp.tagName === 'TEXTAREA' || ['text', 'search', 'tel', 'url', 'password'].indexOf(childType) !== -1;
             var ip = -1;
             for (var n2 = 0; n2 <= nth; n2++) {
                 ip = v.indexOf(findText, ip + (n2 > 0 ? 1 : 0));
                 if (ip === -1) break;
             }
+            if (ip !== -1 && !childSelectionCapable) {
+                return {type: 'unsupported', tag: inp.tagName.toLowerCase(), inputType: childType, currentValue: String(v).slice(0, 160)};
+            }
             if (ip !== -1) {
                 inp.focus();
-                if (typeof inp.setSelectionRange === 'function') {
-                    inp.setSelectionRange(ip, ip + findText.length);
-                }
+                inp.setSelectionRange(ip, ip + findText.length);
                 return {type: 'input', selectionStart: ip, selectionEnd: ip + findText.length};
             }
         }
@@ -481,13 +577,22 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
             endY: er.y + er.height / 2,
             formatted: formatted || undefined
         };
-    }`, undefined, timeout, [findText, nth, scopeSelector, scopeText, scopeXpath]);
+    }`, undefined, timeout, [findText, nth, scopeNth, scopeSelector, scopeText, scopeXpath]);
     if (!result || result.type === 'noscope') {
-        const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeSelector, scopeText, scopeXpath, timeout);
+        const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, timeout);
         throw new StructuredToolError('TEXT_SCOPE_NOT_FOUND', `未找到目标元素: ${JSON.stringify(scopeTarget)}`, '请检查 target 是否能定位到包含目标文本的元素，或先用 extract(state) 查看可交互元素', diagnostics);
     }
+    if (result.type === 'unsupported') {
+        throw new StructuredToolError('UNSUPPORTED_SELECTION', `${result.tag}[type=${result.inputType}] 不支持文本 selection`, 'select 只支持 textarea 和 text/search/tel/url/password input；请使用 type mode="controlled" 设置完整 value', {
+            elementTag: result.tag,
+            inputType: result.inputType,
+            currentValue: result.currentValue,
+            requestedFind: findText,
+            recommendedMode: 'controlled',
+        });
+    }
     if (result.type === 'notfound') {
-        const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeSelector, scopeText, scopeXpath, timeout);
+        const diagnostics = await collectTextSelectionDiagnostics(unifiedSession, findText, scopeTarget, nth, scopeNth, scopeSelector, scopeText, scopeXpath, timeout);
         throw new StructuredToolError('TEXT_NOT_FOUND', scopeTarget
             ? `目标元素内未找到文本 "${findText}"${nth > 0 ? `（第 ${nth} 个匹配）` : ''}`
             : `未找到文本: "${findText}"${nth > 0 ? `（第 ${nth} 个匹配）` : ''}`, '请检查 find 文本、nth 序号和 target 范围；context.candidates 提供了当前范围内的候选文本和 selector', diagnostics);
@@ -596,7 +701,7 @@ function validateEvent(event) {
             }
             break;
         case 'type':
-            if (!event.text) {
+            if (event.text === undefined) {
                 requiredEventParam(event, 'text');
             }
             break;
@@ -638,13 +743,13 @@ function validateEvent(event) {
             break;
     }
 }
-async function executeUnifiedEvent(unifiedSession, event, humanize, timeout) {
+async function executeUnifiedEvent(unifiedSession, event, humanize, timeout, frame) {
     validateEvent(event);
     const handler = unifiedInputHandlers[event.type];
     if (!handler) {
         throw new Error(`未知事件类型: ${event.type}`);
     }
-    return handler({ unifiedSession, humanize, timeout }, event);
+    return handler({ unifiedSession, humanize, timeout, frame }, event);
 }
 const unifiedInputHandlers = {
     keydown: handleUnifiedKeyDown,
@@ -666,15 +771,12 @@ const unifiedInputHandlers = {
     editorCommand: handleUnifiedEditorCommand,
     drag: handleUnifiedDrag,
 };
-async function handleUnifiedKeyDown({ unifiedSession, timeout }, event) {
+async function handleUnifiedKeyDown({ unifiedSession, timeout, frame }, event) {
     if (unifiedSession.getInputMode() === 'stealth' && event.commands && event.commands.length > 0) {
         throw new Error('commands 参数不支持 stealth 输入模式，请先调用 manage action=inputMode inputMode=precise 切换后重试');
     }
     if (event.commands && event.commands.length > 0 && event.target) {
-        const focused = await focusTargetForCommands(unifiedSession, event.target, timeout);
-        if (!focused) {
-            throw new Error('commands 目标未找到或未成功聚焦');
-        }
+        await focusTargetForCommands(unifiedSession, event.target, timeout, frame);
     }
     await unifiedSession.keyDown(event.key, event.commands);
     if (event.commands && event.commands.length > 0) {
@@ -686,7 +788,7 @@ async function handleUnifiedKeyUp({ unifiedSession }, event) {
     await unifiedSession.keyUp(event.key);
     return undefined;
 }
-async function handleUnifiedClick({ unifiedSession, timeout }, event) {
+async function handleUnifiedClick({ unifiedSession, timeout, frame }, event) {
     const button = event.button ?? 'left';
     const clickCount = event.clickCount ?? 1;
     if (!event.target) {
@@ -694,7 +796,7 @@ async function handleUnifiedClick({ unifiedSession, timeout }, event) {
         return undefined;
     }
     if ('x' in event.target && 'y' in event.target) {
-        const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
+        const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
         await unifiedSession.mouseMove(point.x, point.y);
         await unifiedSession.mouseClick(button, clickCount);
         return undefined;
@@ -712,14 +814,14 @@ async function handleUnifiedClick({ unifiedSession, timeout }, event) {
             return undefined;
         }
     }
-    const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
+    const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
     await unifiedSession.mouseMove(point.x, point.y);
     await unifiedSession.mouseClick(button, clickCount, typeof point.refId === 'string' ? point.refId : undefined);
     return undefined;
 }
-async function handleUnifiedMouseDown({ unifiedSession, timeout }, event) {
+async function handleUnifiedMouseDown({ unifiedSession, timeout, frame }, event) {
     if (event.target) {
-        const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
+        const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
         await unifiedSession.mouseMove(point.x, point.y);
     }
     await unifiedSession.mouseDown(event.button ?? 'left');
@@ -729,8 +831,8 @@ async function handleUnifiedMouseUp({ unifiedSession }, event) {
     await unifiedSession.mouseUp(event.button ?? 'left');
     return undefined;
 }
-async function handleUnifiedMouseMove({ unifiedSession, humanize, timeout }, event) {
-    const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
+async function handleUnifiedMouseMove({ unifiedSession, humanize, timeout, frame }, event) {
+    const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
     if (humanize && event.steps && event.steps > 1) {
         const path = generateBezierPath(unifiedSession.getMousePosition(), point, event.steps);
         for (const p of path) {
@@ -743,7 +845,7 @@ async function handleUnifiedMouseMove({ unifiedSession, humanize, timeout }, eve
     }
     return undefined;
 }
-async function handleUnifiedWheel({ unifiedSession, timeout }, event) {
+async function handleUnifiedWheel({ unifiedSession, timeout, frame }, event) {
     if (event.target) {
         const { selector, text, xpath, nth: nthParam } = targetToFindParams(event.target);
         const elements = await unifiedSession.find(selector, text, xpath, timeout);
@@ -752,19 +854,19 @@ async function handleUnifiedWheel({ unifiedSession, timeout }, event) {
             await unifiedSession.scroll(event.deltaX ?? 0, event.deltaY ?? 0, elements[nth].refId);
             return undefined;
         }
-        const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
+        const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
         await unifiedSession.mouseMove(point.x, point.y);
     }
     await unifiedSession.mouseWheel(event.deltaX ?? 0, event.deltaY ?? 0);
     return undefined;
 }
-async function handleUnifiedTouchStart({ unifiedSession, timeout }, event) {
-    const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
+async function handleUnifiedTouchStart({ unifiedSession, timeout, frame }, event) {
+    const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
     await unifiedSession.touchStart(point.x, point.y);
     return undefined;
 }
-async function handleUnifiedTouchMove({ unifiedSession, timeout }, event) {
-    const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
+async function handleUnifiedTouchMove({ unifiedSession, timeout, frame }, event) {
+    const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
     await unifiedSession.touchMove(point.x, point.y);
     return undefined;
 }
@@ -772,13 +874,13 @@ async function handleUnifiedTouchEnd({ unifiedSession }) {
     await unifiedSession.touchEnd();
     return undefined;
 }
-async function handleUnifiedType({ unifiedSession, humanize, timeout }, event) {
+async function handleUnifiedType({ unifiedSession, humanize, timeout, frame }, event) {
     if (event.mode === 'controlled' || event.dispatch) {
-        await inputControlled(unifiedSession, event, timeout);
+        await inputControlled(unifiedSession, event, timeout, frame);
         return undefined;
     }
     if (event.target) {
-        const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
+        const point = await getTargetPointExtension(unifiedSession, event.target, timeout, frame);
         await unifiedSession.mouseMove(point.x, point.y);
         await unifiedSession.mouseClick('left');
     }
@@ -802,17 +904,90 @@ async function handleUnifiedType({ unifiedSession, humanize, timeout }, event) {
     }
     return undefined;
 }
-async function handleUnifiedWait(_context, event) {
+function ensureWaitFitsTimeout(ms, timeout) {
+    if (timeout !== undefined && ms > timeout) {
+        throw new Error(`events[].ms (${ms}ms) 超过 input 剩余 timeout (${timeout}ms)`);
+    }
+}
+async function handleUnifiedWait({ timeout }, event) {
+    ensureWaitFitsTimeout(event.ms, timeout);
     await new Promise((resolve) => setTimeout(resolve, event.ms));
     return undefined;
 }
-async function handleUnifiedSelect({ unifiedSession, timeout }, event) {
-    await focusTargetIfNeeded(unifiedSession, event.target, event.nth, timeout);
+async function handleUnifiedSelect({ unifiedSession, timeout, frame }, event) {
+    await focusTargetIfNeeded(unifiedSession, event.target, timeout, frame);
+    const selectionTarget = await unifiedSession.evaluate(`(() => {
+            const el = document.activeElement;
+            if (!(el instanceof HTMLInputElement)) return null;
+            return {tag: 'input', inputType: (el.type || 'text').toLowerCase(), value: String(el.value || '').slice(0, 160)};
+        })()`, undefined, timeout);
+    if (selectionTarget && !supportsTextSelection(selectionTarget.tag, selectionTarget.inputType)) {
+        throw new StructuredToolError('UNSUPPORTED_SELECTION', `input[type=${selectionTarget.inputType}] 不支持文本 selection`, '请改用 type mode="controlled" 设置完整 value，replace 事件会对这类 input 使用完整 value 更新路径', {
+            elementTag: selectionTarget.tag,
+            inputType: selectionTarget.inputType,
+            currentValue: selectionTarget.value,
+            requestedFind: event.find,
+            recommendedMode: 'controlled',
+        });
+    }
     await selectText(unifiedSession, event.find, event.target, event.nth, timeout);
     return undefined;
 }
-async function handleUnifiedReplace({ unifiedSession, timeout }, event) {
-    await focusTargetIfNeeded(unifiedSession, event.target, event.nth, timeout);
+async function handleUnifiedReplace({ unifiedSession, timeout, frame }, event) {
+    await focusTargetIfNeeded(unifiedSession, event.target, timeout, frame);
+    const directResult = await unifiedSession.evaluate(`function(findText, replacementText, nth) {
+            var el = document.activeElement;
+            if (!(el instanceof HTMLInputElement)) return {handled: false};
+            var type = (el.type || 'text').toLowerCase();
+            if (['text', 'search', 'tel', 'url', 'password'].indexOf(type) !== -1) return {handled: false};
+            var current = String(el.value || '');
+            var pos = -1;
+            for (var i = 0; i <= nth; i++) {
+                pos = current.indexOf(findText, pos + (i > 0 ? 1 : 0));
+                if (pos === -1) return {handled: true, success: false, tag: 'input', inputType: type, currentValue: current.slice(0, 160), reason: 'text_not_found'};
+            }
+            if (el.disabled || el.readOnly) return {handled: true, success: false, tag: 'input', inputType: type, currentValue: current.slice(0, 160), reason: 'not_editable'};
+            var requested = current.slice(0, pos) + replacementText + current.slice(pos + findText.length);
+            var setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
+            if (!setter) return {handled: true, success: false, tag: 'input', inputType: type, currentValue: current.slice(0, 160), requestedValue: requested.slice(0, 160), reason: 'no_native_setter'};
+            setter.call(el, requested);
+            el.dispatchEvent(new Event('input', {bubbles: true}));
+            el.dispatchEvent(new Event('change', {bubbles: true}));
+            var actual = String(el.value || '');
+            return {handled: true, success: actual === requested, tag: 'input', inputType: type, currentValue: current.slice(0, 160), requestedValue: requested.slice(0, 160), actualValue: actual.slice(0, 160), reason: actual === requested ? undefined : 'value_not_applied'};
+        }`, undefined, timeout, [event.find, event.text, event.nth ?? 0]);
+    if (directResult.handled) {
+        if (!directResult.success) {
+            const valueNotApplied = directResult.reason === 'value_not_applied';
+            throw new StructuredToolError(directResult.reason === 'text_not_found'
+                ? 'TEXT_NOT_FOUND'
+                : valueNotApplied
+                    ? 'VALUE_NOT_APPLIED'
+                    : 'UNSUPPORTED_SELECTION', directResult.reason === 'text_not_found'
+                ? `目标元素内未找到文本 "${event.find}"`
+                : valueNotApplied
+                    ? '浏览器没有接受 replace 计算出的完整 value'
+                    : '目标 input 不支持文本 selection，且无法安全更新完整 value', valueNotApplied
+                ? '请根据 actualValue 提供该 input type 接受的完整值，或使用 controlled type 设置合法值'
+                : '请使用 mode="controlled" 的 type 事件设置完整 value，或改用支持文本 selection 的 input 类型', {
+                elementTag: directResult.tag,
+                inputType: directResult.inputType,
+                currentValue: directResult.currentValue,
+                requestedFind: event.find,
+                requestedValue: directResult.requestedValue,
+                actualValue: directResult.actualValue,
+                recommendedMode: 'controlled',
+                reason: directResult.reason,
+            });
+        }
+        return {
+            elementTag: directResult.tag,
+            inputType: directResult.inputType,
+            requestedValue: directResult.requestedValue,
+            actualValue: directResult.actualValue,
+            normalized: directResult.actualValue !== directResult.requestedValue,
+        };
+    }
     const formatted = await selectText(unifiedSession, event.find, event.target, event.nth, timeout);
     let selectionConfirmed = false;
     for (let i = 0; i < 25; i++) {
@@ -863,18 +1038,18 @@ async function handleUnifiedReplace({ unifiedSession, timeout }, event) {
     }
     return undefined;
 }
-async function handleUnifiedEditorContext({ unifiedSession, timeout }, event) {
-    return (await editorAction(unifiedSession, 'context', event, timeout));
+async function handleUnifiedEditorContext({ unifiedSession, timeout, frame }, event) {
+    return (await editorAction(unifiedSession, 'context', event, timeout, frame));
 }
-async function handleUnifiedEditorInsert({ unifiedSession, timeout }, event) {
-    await editorAction(unifiedSession, 'insert', event, timeout);
+async function handleUnifiedEditorInsert({ unifiedSession, timeout, frame }, event) {
+    await editorAction(unifiedSession, 'insert', event, timeout, frame);
     return undefined;
 }
-async function handleUnifiedEditorCommand({ unifiedSession, timeout }, event) {
-    await editorAction(unifiedSession, 'command', event, timeout);
+async function handleUnifiedEditorCommand({ unifiedSession, timeout, frame }, event) {
+    await editorAction(unifiedSession, 'command', event, timeout, frame);
     return undefined;
 }
-async function handleUnifiedDrag({ unifiedSession, timeout }, event) {
+async function handleUnifiedDrag({ unifiedSession, timeout, frame }, event) {
     if (!event.target) {
         throw new Error('drag 事件需要 target 参数');
     }
@@ -895,10 +1070,10 @@ async function handleUnifiedDrag({ unifiedSession, timeout }, event) {
         const srcEls = await unifiedSession.find(srcParams.selector, srcParams.text, srcParams.xpath, timeout);
         const dstEls = await unifiedSession.find(dstParams.selector, dstParams.text, dstParams.xpath, timeout);
         if (srcEls.length <= srcNth) {
-            throw new Error(`drag 源元素未找到: ${JSON.stringify(event.target)}`);
+            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));
         }
         if (dstEls.length <= dstNth) {
-            throw new Error(`drag 目标元素未找到: ${JSON.stringify(event.to)}`);
+            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));
         }
         return unifiedSession.dragAndDrop(srcEls[srcNth].refId, dstEls[dstNth].refId);
     };
@@ -925,7 +1100,7 @@ async function handleUnifiedDrag({ unifiedSession, timeout }, event) {
  *   - precise 模式直接使用
  *   - stealth 模式需减 offset 转为 iframe 相对坐标
  */
-async function inputControlled(unifiedSession, event, timeout) {
+async function inputControlled(unifiedSession, event, timeout, frame) {
     if (!event.target) {
         throw new Error('controlled 输入需要 target 参数定位输入元素');
     }
@@ -936,62 +1111,25 @@ async function inputControlled(unifiedSession, event, timeout) {
     const elements = await unifiedSession.find(selector, searchText, xpath, timeout);
     const nth = nthParam ?? 0;
     if (elements.length === 0 || nth >= elements.length) {
-        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));
+        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));
     }
     const result = await unifiedSession.dispatchInput(elements[nth].refId, event.text ?? '');
     if (!result.success) {
-        throw new StructuredToolError('CONTROLLED_INPUT_FAILED', result.error || 'controlled 输入失败', '请检查目标元素是否可编辑、未 disabled，并确认当前 frame 与 target 匹配', await buildTargetDiagnosticContext(unifiedSession, event.target, elements.length, nth, timeout, result.error || 'controlled 输入失败'));
+        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));
     }
 }
-async function buildTargetDiagnosticContext(unifiedSession, target, matchCount, nth, timeout, reason = '目标元素未找到') {
-    let page;
-    try {
-        page = await unifiedSession.evaluate(`(() => {
-                const active = document.activeElement;
-                const selection = window.getSelection();
-                const candidates = Array.from(document.querySelectorAll('input, textarea, select, [contenteditable="true"], button, a, [role="button"], [role="textbox"], [role="combobox"]')).slice(0, 20);
-                return {
-                    activeElement: active ? {
-                        tag: active.tagName.toLowerCase(),
-                        id: active.id || undefined,
-                        className: typeof active.className === 'string' ? active.className : undefined,
-                        text: (active.textContent || '').trim().slice(0, 80),
-                        value: 'value' in active ? active.value : undefined,
-                        selectionStart: 'selectionStart' in active ? active.selectionStart : undefined,
-                        selectionEnd: 'selectionEnd' in active ? active.selectionEnd : undefined
-                    } : null,
-                    selection: {
-                        text: selection ? selection.toString().slice(0, 160) : '',
-                        collapsed: selection ? selection.isCollapsed : true,
-                        anchorNode: selection && selection.anchorNode ? selection.anchorNode.nodeName : null,
-                        focusNode: selection && selection.focusNode ? selection.focusNode.nodeName : null
-                    },
-                    candidates: candidates.map(function(el) {
-                        const rect = el.getBoundingClientRect();
-                        return {
-                            tag: el.tagName.toLowerCase(),
-                            id: el.id || undefined,
-                            role: el.getAttribute('role') || undefined,
-                            text: (el.textContent || el.getAttribute('aria-label') || el.getAttribute('placeholder') || '').trim().slice(0, 80),
-                            visible: rect.width > 0 && rect.height > 0,
-                            disabled: !!el.disabled || el.getAttribute('aria-disabled') === 'true',
-                            bounds: {x: rect.x, y: rect.y, width: rect.width, height: rect.height}
-                        };
-                    })
-                };
-            })()`, undefined, timeout);
-    }
-    catch (err) {
-        page = { diagnosticError: err instanceof Error ? err.message : String(err) };
-    }
-    return { reason, target, matchCount, nth, page };
+async function buildTargetDiagnosticContext(unifiedSession, target, matchCount, nth, timeout, reason = '目标元素未找到', frame) {
+    return buildTargetDiagnostics(unifiedSession, target, {
+        nth,
+        timeout,
+        frame,
+        matchCount,
+        lastState: reason,
+    });
 }
-async function editorAction(unifiedSession, action, event, timeout) {
+async function editorAction(unifiedSession, action, event, timeout, frame) {
     if (event.target) {
-        const focused = await focusTargetForCommands(unifiedSession, event.target, timeout);
-        if (!focused) {
-            throw new Error('editor 目标未找到或未成功聚焦');
-        }
+        await focusTargetForCommands(unifiedSession, event.target, timeout, frame);
     }
     return unifiedSession.evaluate(`function(action, text, command) {
             var active = document.activeElement;
@@ -1054,7 +1192,7 @@ async function editorAction(unifiedSession, action, event, timeout) {
             return {success: true, command: command};
         }`, undefined, timeout, [action, event.text ?? '', event.command ?? '']);
 }
-async function getTargetPointExtension(unifiedSession, target, timeout) {
+async function getTargetPointExtension(unifiedSession, target, timeout, frame) {
     const frameOffset = unifiedSession.getFrameOffset();
     const isStealth = unifiedSession.getInputMode() === 'stealth';
     // 原始坐标：用户意图为 iframe 相对坐标
@@ -1069,10 +1207,10 @@ async function getTargetPointExtension(unifiedSession, target, timeout) {
     const elements = await unifiedSession.find(selector, text, xpath, timeout);
     const nth = nthParam ?? 0;
     if (elements.length === 0) {
-        throw new StructuredToolError('TARGET_NOT_FOUND', `未找到目标元素: ${JSON.stringify(target)}`, '请检查 target 是否正确，或先用 extract type=state 查看 interactiveElements 候选', await buildTargetDiagnosticContext(unifiedSession, target, elements.length, nth, timeout));
+        throw new StructuredToolError('TARGET_NOT_FOUND', `未找到目标元素: ${JSON.stringify(target)}`, '请检查 target 是否正确，或先用 extract type=state 查看 interactiveElements 候选', await buildTargetDiagnosticContext(unifiedSession, target, elements.length, nth, timeout, '目标元素未找到', frame));
     }
     if (nth >= elements.length) {
-        throw new StructuredToolError('TARGET_INDEX_OUT_OF_RANGE', `第 ${nth} 个匹配元素不存在（共 ${elements.length} 个）`, '请降低 nth，或先用 extract type=state 查看当前匹配到的候选元素', await buildTargetDiagnosticContext(unifiedSession, target, elements.length, nth, timeout, '目标元素序号越界'));
+        throw new StructuredToolError('TARGET_INDEX_OUT_OF_RANGE', `第 ${nth} 个匹配元素不存在（共 ${elements.length} 个）`, '请降低 nth，或先用 extract type=state 查看当前匹配到的候选元素', await buildTargetDiagnosticContext(unifiedSession, target, elements.length, nth, timeout, '目标元素序号越界', frame));
     }
     // 视口外时滚动后重新取 rect：与 actionableClick (left+single) 行为对齐，
     // 否则非左键 / 多击的坐标路径在视口外坐标 dispatch，浏览器找不到元素，事件丢失
@@ -1227,7 +1365,8 @@ async function handleCdpType({ session, humanize, timeout }, event) {
         await session.type(event.text, delay);
     }
 }
-async function handleCdpWait(_context, event) {
+async function handleCdpWait({ timeout }, event) {
+    ensureWaitFitsTimeout(event.ms, timeout);
     await new Promise((resolve) => setTimeout(resolve, event.ms));
 }
 async function handleCdpDrag() {