@pyrokine/mcp-chrome 1.7.0 → 2.0.0

package/dist/tools/input.js

@@ -16,26 +16,57 @@ import { targetToFindParams, targetZodSchema } from './schema.js';
  * InputEvent schema
  */
 const inputEventSchema = z.object({
-    type: z.enum([
-        'keydown', 'keyup', 'click', 'mousedown', 'mouseup', 'mousemove',
-        'wheel', 'touchstart', 'touchmove', 'touchend', 'type', 'wait',
-        'select', 'replace',
-    ]).describe('事件类型'),
+    type: z
+        .enum([
+        'keydown',
+        'keyup',
+        'click',
+        'mousedown',
+        'mouseup',
+        'mousemove',
+        'wheel',
+        'touchstart',
+        'touchmove',
+        'touchend',
+        'type',
+        'wait',
+        'select',
+        'replace',
+        'drag',
+    ])
+        .describe('事件类型'),
     key: z.string().optional().describe('按键（keydown/keyup）'),
-    button: z.enum(['left', 'middle', 'right', 'back', 'forward'])
+    commands: z
+        .array(z.string())
         .optional()
-        .describe('鼠标按钮'),
-    target: targetZodSchema.optional().describe('目标元素（mousemove/touchstart/touchmove 必填；click/mousedown/wheel/type 可选，用于先定位再操作；select/replace 可选，用于限定搜索范围）'),
+        .describe('浏览器编辑命令（keydown 专用），如 ["selectAll"]、["copy"]、["paste"]、["cut"]、["undo"]、["redo"]，触发原生编辑命令，优先于纯键盘事件，用于跨平台快捷键场景，需要 inputMode=precise（stealth 模式无法触发 Chrome 原生编辑命令，会报错）'),
+    button: z.enum(['left', 'middle', 'right', 'back', 'forward']).optional().describe('鼠标按钮'),
+    clickCount: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('鼠标点击次数（click，默认 1，设为 2 触发双击事件，设为 3 触发三击事件）'),
+    target: targetZodSchema
+        .optional()
+        .describe('目标元素（mousemove/touchstart/touchmove 必填；click/mousedown/wheel/type/drag 可选，用于先定位再操作；select/replace 可选，用于限定搜索范围；drag 时为拖拽源）'),
+    to: targetZodSchema.optional().describe('拖拽目标元素（drag 事件必填）'),
     steps: z.number().optional().describe('移动步数（mousemove/touchmove）'),
     deltaX: z.number().optional().describe('水平滚动量'),
     deltaY: z.number().optional().describe('垂直滚动量'),
-    text: z.string().optional().describe('输入文本（type）或替换文本（replace）'),
-    delay: 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('等待毫秒'),
     find: z.string().optional().describe('要查找并选中的文本（select/replace）'),
     nth: z.number().optional().describe('第 N 个匹配（select/replace，从 0 开始，默认 0 即第一个）'),
-    dispatch: z.boolean().optional().describe('使用 dispatch 模式输入（type），直接设置 value 并触发 input/change 事件，兼容 React/Vue 等框架的受控组件，默认 false 使用键盘事件'),
-    force: z.boolean().optional().describe('强制执行（click），跳过可操作性检查（可见性、遮挡检测等），直接在目标元素上触发事件，用于已知需要绕过检查的场景'),
+    dispatch: z
+        .boolean()
+        .optional()
+        .describe('使用 dispatch 模式输入（type），直接设置 value 并触发 input/change 事件，兼容 React/Vue 等框架的受控组件，默认 false 使用键盘事件'),
+    force: z
+        .boolean()
+        .optional()
+        .describe('强制执行（click），跳过可操作性检查（可见性、遮挡检测等），直接在目标元素上触发事件，用于已知需要绕过检查的场景'),
 });
 /**
  * input 参数 schema
@@ -43,9 +74,15 @@ const inputEventSchema = z.object({
 const inputSchema = z.object({
     events: z.array(inputEventSchema).describe('事件序列'),
     humanize: z.boolean().optional().describe('启用人类行为模拟（贝塞尔曲线移动、随机延迟）'),
-    tabId: z.string().optional().describe('目标 Tab ID（可选，仅 Extension 模式）。不指定则使用当前 attach 的 tab。可操作非当前 attach 的 tab。CDP 模式下不支持此参数'),
+    tabId: z
+        .string()
+        .optional()
+        .describe('目标 Tab ID（可选，仅 Extension 模式），不指定则使用当前 attach 的 tab，可操作非当前 attach 的 tab，CDP 模式下不支持此参数'),
     timeout: z.number().optional().describe('超时毫秒'),
-    frame: z.union([z.string(), z.number()]).optional().describe('iframe 定位（可选，仅 Extension 模式）。CSS 选择器（如 "iframe#main"）或索引（如 0）。不指定则在主框架操作'),
+    frame: z
+        .union([z.string(), z.number()])
+        .optional()
+        .describe('iframe 定位（可选，仅 Extension 模式），CSS 选择器（如 "iframe#main"）或索引（如 0），不指定则在主框架操作'),
 });
 /**
  * input 工具处理器
@@ -69,7 +106,7 @@ async function handleInput(args) {
                     }
                 }
                 else {
-                    // CDP 模式：使用原有逻辑
+                    // CDP 模式：逐事件分发（无 Extension bridge）
                     const session = getSession();
                     for (const event of args.events) {
                         if (event.type === 'select' || event.type === 'replace') {
@@ -109,6 +146,27 @@ async function handleInput(args) {
  *
  * @returns 格式化标签名（如 "code"），若被替换文本在格式化节点内
  */
+/**
+ * 如果 target 是选择器类型，先通过 actionableClick 聚焦
+ * select/replace 事件用，保证选区建立前 activeElement 就是目标
+ */
+async function focusTargetIfNeeded(unifiedSession, target, nth, timeout) {
+    if (!target || 'x' in target || 'y' in target) {
+        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);
+        }
+    }
+}
 async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeout) {
     // 将 target 转为查询参数，传入注入脚本进行 DOM 查询
     let scopeSelector = null;
@@ -153,6 +211,11 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
                 pos = val.indexOf(findText, pos + (n > 0 ? 1 : 0));
                 if (pos === -1) return {type: 'notfound'};
             }
+            // 原子化：定位到 input 同时完成 focus + setSelectionRange，避免外层 mouseClick 聚焦不可靠
+            root.focus();
+            if (typeof root.setSelectionRange === 'function') {
+                root.setSelectionRange(pos, pos + findText.length);
+            }
             return {type: 'input', selectionStart: pos, selectionEnd: pos + findText.length};
         }
 
@@ -167,9 +230,11 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
                 if (ip === -1) break;
             }
             if (ip !== -1) {
-                var r = inp.getBoundingClientRect();
-                return {type: 'input', selectionStart: ip, selectionEnd: ip + findText.length,
-                    focusX: r.x + r.width / 2, focusY: r.y + r.height / 2};
+                inp.focus();
+                if (typeof inp.setSelectionRange === 'function') {
+                    inp.setSelectionRange(ip, ip + findText.length);
+                }
+                return {type: 'input', selectionStart: ip, selectionEnd: ip + findText.length};
             }
         }
 
@@ -243,28 +308,7 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
             : `未找到文本: "${findText}"${nth > 0 ? `（第 ${nth} 个匹配）` : ''}`);
     }
     if (result.type === 'input') {
-        // input/textarea：聚焦 + setSelectionRange
-        const r = result;
-        if (r.focusX !== undefined && r.focusY !== undefined) {
-            let x = r.focusX;
-            let y = r.focusY;
-            const frameOffset = unifiedSession.getFrameOffset();
-            if (frameOffset && unifiedSession.getInputMode() !== 'stealth') {
-                x += frameOffset.x;
-                y += frameOffset.y;
-            }
-            await unifiedSession.mouseMove(x, y);
-            await unifiedSession.mouseClick('left');
-        }
-        else if (scopeTarget) {
-            const point = await getTargetPointExtension(unifiedSession, scopeTarget, timeout);
-            await unifiedSession.mouseMove(point.x, point.y);
-            await unifiedSession.mouseClick('left');
-        }
-        await unifiedSession.evaluate(`function(start, end) {
-            var el = document.activeElement;
-            if (el && el.setSelectionRange) el.setSelectionRange(start, end);
-        }`, undefined, timeout, [result.selectionStart, result.selectionEnd]);
+        // 注入脚本已完成 focus + setSelectionRange（原子化，避免外层 mouseClick 聚焦不可靠）
         return undefined;
     }
     // DOM 文本节点：鼠标选择
@@ -286,53 +330,77 @@ async function selectText(unifiedSession, findText, scopeTarget, nth = 0, timeou
     await unifiedSession.keyUp('Shift');
     return coords.formatted;
 }
+/**
+ * 验证事件参数（两种执行模式共享），避免在 Extension/CDP 两个 switch 中重复校验
+ */
+function validateEvent(event) {
+    if (event.commands && event.commands.length > 0 && event.type !== 'keydown') {
+        throw new Error(`commands 参数只能用于 keydown 事件，当前事件类型为 ${event.type}，如需触发编辑命令，请把 commands 放在 keydown 事件上`);
+    }
+    switch (event.type) {
+        case 'keydown':
+        case 'keyup':
+            if (!event.key) {
+                throw new Error(`${event.type} 事件需要 key 参数`);
+            }
+            break;
+        case 'wait':
+            if (event.ms === undefined) {
+                throw new Error('wait 事件需要 ms 参数');
+            }
+            break;
+    }
+}
 /**
  * Extension 模式：执行单个事件
  *
  * @returns 可选警告信息（如格式丢失提示）
  */
 async function executeEventExtension(unifiedSession, event, humanize, timeout) {
+    validateEvent(event);
     switch (event.type) {
         case 'keydown': {
-            if (!event.key) {
-                throw new Error('keydown 事件需要 key 参数');
-            }
-            await unifiedSession.keyDown(event.key);
+            await unifiedSession.keyDown(event.key, event.commands);
             break;
         }
         case 'keyup': {
-            if (!event.key) {
-                throw new Error('keyup 事件需要 key 参数');
-            }
             await unifiedSession.keyUp(event.key);
             break;
         }
         case 'click': {
+            const button = event.button ?? 'left';
+            const clickCount = event.clickCount ?? 1;
             if (event.target) {
                 // 坐标型 target：不过 actionableClick，但仍需 getTargetPointExtension 做 iframe offset 修正
                 if ('x' in event.target && 'y' in event.target) {
                     const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
                     await unifiedSession.mouseMove(point.x, point.y);
-                    await unifiedSession.mouseClick(event.button ?? 'left');
+                    await unifiedSession.mouseClick(button, clickCount);
                     break;
                 }
-                // 优先使用 actionable click（带可操作性检查、自动滚动、遮挡检测）
-                const { selector, text: searchText, xpath, nth: nthParam } = targetToFindParams(event.target);
-                const elements = await unifiedSession.find(selector, searchText, xpath, timeout);
-                const nth = nthParam ?? 0;
-                if (elements.length > 0 && nth < elements.length) {
-                    const refId = elements[nth].refId;
-                    const result = await unifiedSession.actionableClick(refId, event.force);
-                    if (!result.success) {
-                        throw new Error(result.error || 'Click failed');
+                // 左键单击：优先用 actionable click（带可操作性检查、自动滚动、遮挡检测）
+                // 非左键 / 多击：actionableClick 依赖 HTMLElement.click() 只能触发单次左键，必须走坐标路径
+                if (button === 'left' && clickCount === 1) {
+                    const { selector, text: searchText, xpath, nth: nthParam, } = targetToFindParams(event.target);
+                    const elements = await unifiedSession.find(selector, searchText, xpath, timeout);
+                    const nth = nthParam ?? 0;
+                    if (elements.length > 0 && nth < elements.length) {
+                        const refId = elements[nth].refId;
+                        const result = await unifiedSession.actionableClick(refId, event.force);
+                        if (!result.success) {
+                            throw new Error(result.error || 'Click failed');
+                        }
+                        break;
                     }
-                    break;
                 }
-                // fallback: 找不到 refId 时用坐标方式
+                // fallback: 找不到 refId 或需走坐标路径时
+                // refId 透传：stealth 模式下嵌套 iframe overlay 场景绕过 elementFromPoint
                 const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
                 await unifiedSession.mouseMove(point.x, point.y);
+                await unifiedSession.mouseClick(button, clickCount, point.refId);
+                break;
             }
-            await unifiedSession.mouseClick(event.button ?? 'left');
+            await unifiedSession.mouseClick(button, clickCount);
             break;
         }
         case 'mousedown': {
@@ -366,6 +434,15 @@ async function executeEventExtension(unifiedSession, event, humanize, timeout) {
         }
         case 'wheel': {
             if (event.target) {
+                const { selector, text, xpath, nth: nthParam, } = targetToFindParams(event.target);
+                const elements = await unifiedSession.find(selector, text, xpath, timeout);
+                const nth = nthParam ?? 0;
+                if (elements.length > nth) {
+                    // 用 refId 直接滚动目标元素（支持视口外元素）
+                    await unifiedSession.scroll(event.deltaX ?? 0, event.deltaY ?? 0, elements[nth].refId);
+                    break;
+                }
+                // 找不到元素时 fallback 到坐标方式
                 const point = await getTargetPointExtension(unifiedSession, event.target, timeout);
                 await unifiedSession.mouseMove(point.x, point.y);
             }
@@ -405,7 +482,7 @@ async function executeEventExtension(unifiedSession, event, humanize, timeout) {
                 if ('x' in event.target && 'y' in event.target) {
                     throw new Error('dispatch 模式不支持坐标型 target，请使用 CSS 选择器、role 或文本定位');
                 }
-                const { selector, text: searchText, xpath, nth: nthParam } = targetToFindParams(event.target);
+                const { selector, text: searchText, xpath, nth: nthParam, } = targetToFindParams(event.target);
                 const elements = await unifiedSession.find(selector, searchText, xpath, timeout);
                 const nth = nthParam ?? 0;
                 if (elements.length === 0 || nth >= elements.length) {
@@ -427,6 +504,12 @@ async function executeEventExtension(unifiedSession, event, humanize, timeout) {
                 await unifiedSession.mouseMove(point.x, point.y);
                 await unifiedSession.mouseClick('left');
             }
+            else {
+                const hasActiveFocus = await unifiedSession.evaluate('!!document.activeElement && document.activeElement !== document.body && document.activeElement !== document.documentElement');
+                if (!hasActiveFocus) {
+                    throw new Error('type 事件在无 target 时需要页面已有焦点元素，请提供 target 或先 click 目标元素');
+                }
+            }
             const delay = event.delay ?? 0;
             if (humanize) {
                 for (const char of event.text) {
@@ -440,16 +523,15 @@ async function executeEventExtension(unifiedSession, event, humanize, timeout) {
             break;
         }
         case 'wait': {
-            if (!event.ms) {
-                throw new Error('wait 事件需要 ms 参数');
-            }
-            await new Promise(resolve => setTimeout(resolve, event.ms));
+            await new Promise((resolve) => setTimeout(resolve, event.ms));
             break;
         }
         case 'select': {
             if (!event.find) {
                 throw new Error('select 事件需要 find 参数');
             }
+            // 自动聚焦目标元素（selectText 内 mouseClick focus 对 React 等场景不可靠）
+            await focusTargetIfNeeded(unifiedSession, event.target, event.nth, timeout);
             await selectText(unifiedSession, event.find, event.target, event.nth, timeout);
             break;
         }
@@ -460,6 +542,8 @@ async function executeEventExtension(unifiedSession, event, humanize, timeout) {
             if (event.text === undefined) {
                 throw new Error('replace 事件需要 text 参数');
             }
+            // 自动聚焦目标元素
+            await focusTargetIfNeeded(unifiedSession, event.target, event.nth, timeout);
             // Step 1: 选中文本
             const formatted = await selectText(unifiedSession, event.find, event.target, event.nth, timeout);
             // 轮询等待选区同步（最多 500ms）
@@ -477,7 +561,7 @@ async function executeEventExtension(unifiedSession, event, humanize, timeout) {
                     selectionConfirmed = true;
                     break;
                 }
-                await new Promise(resolve => setTimeout(resolve, 20));
+                await new Promise((resolve) => setTimeout(resolve, 20));
             }
             if (!selectionConfirmed) {
                 throw new Error(`选区同步失败：文本 "${event.find}" 已定位但未能建立选区，无法执行替换`);
@@ -517,6 +601,54 @@ async function executeEventExtension(unifiedSession, event, humanize, timeout) {
             }
             break;
         }
+        case 'drag': {
+            if (!event.target) {
+                throw new Error('drag 事件需要 target 参数（拖拽源）');
+            }
+            if (!event.to) {
+                throw new Error('drag 事件需要 to 参数（拖拽目标）');
+            }
+            // drag 仅支持选择器类 target（CSS/text/xpath/ARIA 等），不支持坐标
+            // 理由：drag 依赖 refId 在 Extension ISOLATED 世界 dispatchEvent，坐标无法生成 refId
+            if ('x' in event.target || 'y' in event.target) {
+                throw new Error('drag 的 target 不支持坐标类型，请使用选择器（css/text/xpath/role 等）');
+            }
+            if ('x' in event.to || 'y' in event.to) {
+                throw new Error('drag 的 to 不支持坐标类型，请使用选择器（css/text/xpath/role 等）');
+            }
+            // 用 find 定位确认元素存在（支持 ARIA/testId 等高级定位），拿 refId 传入 extension 侧 dispatchEvent
+            const srcParams = targetToFindParams(event.target);
+            const dstParams = targetToFindParams(event.to);
+            const srcNth = srcParams.nth ?? 0;
+            const dstNth = dstParams.nth ?? 0;
+            // 执行 drag，失败时重试一次（React 重渲染可能导致 refId 失效）
+            const attemptDrag = async () => {
+                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)}`);
+                }
+                if (dstEls.length <= dstNth) {
+                    throw new Error(`drag 目标元素未找到: ${JSON.stringify(event.to)}`);
+                }
+                return unifiedSession.dragAndDrop(srcEls[srcNth].refId, dstEls[dstNth].refId);
+            };
+            let dragResult = await attemptDrag();
+            let retried = false;
+            // 仅对 refId 失效（REF_STALE）重试：源/目标元素从 DOM 移除，典型是 React 重渲染
+            if (!dragResult.success && dragResult.code === 'REF_STALE') {
+                console.warn('[MCP] drag refId 失效，自动重试一次:', dragResult.error);
+                dragResult = await attemptDrag();
+                retried = true;
+            }
+            if (!dragResult.success) {
+                throw new Error(dragResult.error || 'drag 执行失败');
+            }
+            if (retried) {
+                return 'drag 因 refId 失效已自动重试一次（可能是 React 等框架重渲染导致）';
+            }
+            break;
+        }
         default:
             throw new Error(`未知事件类型: ${event.type}`);
     }
@@ -552,34 +684,63 @@ async function getTargetPointExtension(unifiedSession, target, timeout) {
     if (nth >= elements.length) {
         throw new Error(`第 ${nth} 个匹配元素不存在（共 ${elements.length} 个）`);
     }
-    const rect = elements[nth].rect;
-    const point = {
-        x: rect.x + rect.width / 2,
-        y: rect.y + rect.height / 2,
-    };
-    // 元素定位：find() 返回视口绝对坐标
-    if (frameOffset && isStealth) {
-        // stealth: 转回 iframe 相对坐标
-        return { x: point.x - frameOffset.x, y: point.y - frameOffset.y };
+    // 视口外时滚动后重新取 rect：与 actionableClick (left+single) 行为对齐，
+    // 否则非左键 / 多击的坐标路径在视口外坐标 dispatch，浏览器找不到元素，事件丢失
+    const refId = elements[nth].refId;
+    const iframeRelRect = await unifiedSession.evaluate(`(() => {
+            const ref = window.__mcpElementMap?.[${JSON.stringify(refId)}];
+            const el = ref?.deref();
+            if (!el) return null;
+            const r = el.getBoundingClientRect();
+            if (r.top < 0 || r.bottom > window.innerHeight || r.left < 0 || r.right > window.innerWidth) {
+                el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
+            }
+            const r2 = el.getBoundingClientRect();
+            return { x: r2.x, y: r2.y, width: r2.width, height: r2.height };
+        })()`);
+    // refId 失效等异常：fallback 到原始 find rect（父视口绝对）
+    if (!iframeRelRect) {
+        const rect = elements[nth].rect;
+        const point = { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+        if (frameOffset && isStealth) {
+            return { x: point.x - frameOffset.x, y: point.y - frameOffset.y, refId };
+        }
+        return { ...point, refId };
+    }
+    // 主 frame：iframeRelRect 就是父视口绝对
+    if (!frameOffset) {
+        return {
+            x: iframeRelRect.x + iframeRelRect.width / 2,
+            y: iframeRelRect.y + iframeRelRect.height / 2,
+            refId,
+        };
+    }
+    // iframe + stealth：消费者（chrome.scripting in iframe）需要 iframe 相对
+    if (isStealth) {
+        return {
+            x: iframeRelRect.x + iframeRelRect.width / 2,
+            y: iframeRelRect.y + iframeRelRect.height / 2,
+            refId,
+        };
     }
-    return point;
+    // iframe + precise：消费者（chrome.debugger）需要父视口绝对。
+    // scrollIntoView({block:'center'}) 会 cascade 到父框架，导致 frameOffset 与父绝对 rect 都过期，
+    // refetch find() 让 content-handler 重新计算 frameOffset 并返回最新父绝对 rect
+    const refreshed = await unifiedSession.find(selector, text, xpath, timeout);
+    const rect = refreshed[nth]?.rect ?? elements[nth].rect;
+    return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2, refId };
 }
 /**
  * CDP 模式：执行单个事件
  */
 async function executeEvent(session, event, humanize, timeout) {
+    validateEvent(event);
     switch (event.type) {
         case 'keydown': {
-            if (!event.key) {
-                throw new Error('keydown 事件需要 key 参数');
-            }
-            await session.keyDown(event.key);
+            await session.keyDown(event.key, event.commands);
             break;
         }
         case 'keyup': {
-            if (!event.key) {
-                throw new Error('keyup 事件需要 key 参数');
-            }
             await session.keyUp(event.key);
             break;
         }
@@ -587,8 +748,12 @@ async function executeEvent(session, event, humanize, timeout) {
             if (event.target) {
                 await moveToTarget(session, event.target, humanize, timeout);
             }
-            await session.mouseDown(event.button ?? 'left');
-            await session.mouseUp(event.button ?? 'left');
+            const cdpButton = event.button ?? 'left';
+            const cdpClickCount = event.clickCount ?? 1;
+            for (let i = 1; i <= cdpClickCount; i++) {
+                await session.mouseDown(cdpButton, i);
+                await session.mouseUp(cdpButton, i);
+            }
             break;
         }
         case 'mousedown': {
@@ -662,6 +827,12 @@ async function executeEvent(session, event, humanize, timeout) {
                 await session.mouseDown('left');
                 await session.mouseUp('left');
             }
+            else {
+                const hasActiveFocus = await session.evaluate('!!document.activeElement && document.activeElement !== document.body && document.activeElement !== document.documentElement');
+                if (!hasActiveFocus) {
+                    throw new Error('type 事件在无 target 时需要页面已有焦点元素，请提供 target 或先 click 目标元素');
+                }
+            }
             const delay = event.delay ?? 0;
             if (humanize) {
                 // 人类化打字
@@ -676,13 +847,14 @@ async function executeEvent(session, event, humanize, timeout) {
             break;
         }
         case 'wait': {
-            if (!event.ms) {
-                throw new Error('wait 事件需要 ms 参数');
-            }
             await new Promise((resolve) => setTimeout(resolve, event.ms));
             break;
         }
         default:
+            // drag 仅在 Extension 模式可用，给出明确错误而非通用"未知事件类型"
+            if (event.type === 'drag') {
+                throw new Error('drag 事件仅在 Extension 模式下可用，当前为 CDP 模式');
+            }
             throw new Error(`未知事件类型: ${event.type}`);
     }
 }
@@ -750,13 +922,22 @@ export function registerInputTool(server) {
 2. 用 CSS 选择器 + nth 精确定位元素（避免坐标点击）
 3. 再 input click/type 操作目标元素
 
-组合键需拆分为独立事件。示例（Ctrl+A 全选）：
+组合键拆分为独立事件示例（修饰键 + 字母键）：
   events: [
     {type: "keydown", key: "Control"},
     {type: "keydown", key: "a"},
     {type: "keyup", key: "a"},
     {type: "keyup", key: "Control"}
-  ]`,
+  ]
+
+浏览器编辑命令（selectAll/copy/paste/cut/undo/redo 等）需用 commands 字段，跨平台可靠：
+  events: [
+    {type: "keydown", key: "a", commands: ["selectAll"]},
+    {type: "keyup", key: "a"}
+  ]
+注意：纯键盘事件（不带 commands）仅保证 JS keyboard event 可被监听，不保证触发浏览器原生编辑行为；
+      全选/复制/粘贴等语义用 commands；"全选并替换文本"用 select/replace 事件更简洁；
+      commands 仅支持 inputMode=precise，stealth 模式下会报错`,
         inputSchema: inputSchema,
     }, (args) => handleInput(args));
 }