dsh-browser-view 0.8.0 → 0.8.2

package/lib/mcp.js

@@ -184,8 +184,8 @@ const BROWSER_DEFAULT_CONFIG = {
 };
 //#endregion
 //#region lib/types/lib/prompts.js
-const FULL_TOOL_PROMPT = "浏览器工具操作一个共享浏览器会话,支持多标签页与多配置文件。定位操作元素最省事的方式是意图语义定位:browser_click/browser_type/browser_select 直接传 what(元素名称/label,如 what:'登录'),页内打分匹配并自动注册 ref,一次调用替代 快照→查找→点击 三轮;零命中报错会附最相近候选。需要精确控制时再用 selector(CSS)/ref(aria 快照)。打开页面后可先 browser_snapshot 读文本与链接、browser_elements 读表单结构(含关联 label 与展开的下拉选项);browser_find(query 传名称,只返回命中 ref+区域上下文,大页面最省 token;零命中会给相近候选)适合多目标排查,需要全页结构时再用 browser_snapshot { mode: \"aria\" }(可交互元素带 ref=eN,click/type/select/press 直接传 ref 代替 CSS 选择器);下拉选择(原生 select 与 antd/element 组件库)用 browser_select 传 selector/ref/what + option 文本一步完成;固定小序列(点击→等待→输入→提交)用 browser_batch 一次执行减少往返;标签管理用 browser_tabs;下载用 browser_download(wait=true 可等新下载);登录态用 browser_cookies。做自动化测试时:用 browser_wait_for 显式等待页面稳定/元素出现,用 browser_assert 断言(失败自动截图;visual={baseline} 可做视觉回归,先用 browser_screenshot { baseline } 建基线),用 browser_network 检查接口调用与 4xx/5xx,跑完一轮可用 browser_record save 保存操作序列、browser_replay 回放做回归(选择器失效自动按指纹自愈;vars/data 支持参数化与数据驱动)。每次 replay/batch 都记入运行历史,browser_report list/export 可查看与导出回归报告。抓取结构化数据用 browser_extract(fields 定义 CSS 字段,可翻页,可导出 CSV/JSONL)。遇到需要登录的网站:先 browser_open 打开登录页,告知用户请在浏览器窗口中完成登录,再调用 browser_wait_for_login 等待(可给 successSelector/successUrl);验证码/二次确认等更广的「人补一步」场景用 browser_pause_for_human(提示语会显示在实时画面面板);配置 userDataDir 时登录态会持久化。用户可通过界面右下角面板的实时画面查看浏览器。";
-const CORE_TOOL_PROMPT = "浏览器工具操作一个共享浏览器会话(toolset=core:已精简工具集)。定位操作元素最省事的方式是意图语义定位:browser_click/browser_type/browser_select 直接传 what(元素名称/label,如 what:'登录'),一次调用替代快照→查找→点击;零命中报错附最相近候选。需要精确控制时再用 selector/ref:打开页面后用 browser_snapshot 读内容(scope 限定区域、since 增量重读省 token),browser_find(query 传名称,返回 ref),点击/输入/按键/下拉用 browser_click/browser_type/browser_press/browser_select(selector 或 ref);固定小序列用 browser_batch;等待用 browser_wait/browser_wait_for,断言用 browser_assert;接口检查用 browser_network;标签 browser_tabs;下载/上传 browser_download/browser_upload。需要人工:登录用 browser_wait_for_login,验证码/二次确认用 browser_pause_for_human,敏感动作(提交/删除/支付)前用 browser_confirm。环境异常先跑 browser_doctor 诊断。录制/回放/报告/抽取/profile/隔离 context 等工具当前未注册(toolset=core),需要时把配置改为 toolset: all 并重启 DSH。用户可通过界面右下角面板的实时画面查看浏览器。";
+const FULL_TOOL_PROMPT = "浏览器工具操作一个共享浏览器会话,支持多标签页与多配置文件。定位操作元素最省事的方式是意图语义定位:browser_click/browser_type/browser_select 直接传 what(元素名称/label,如 what:'登录'),页内打分匹配并自动注册 ref,一次调用替代 快照→查找→点击 三轮;零命中报错会附最相近候选。需要精确控制时再用 selector(CSS)/ref(aria 快照)。打开页面后可先 browser_snapshot 读文本与链接、browser_elements 读表单结构(含关联 label 与展开的下拉选项);browser_find(query 传名称,只返回命中 ref+区域上下文,大页面最省 token;零命中会给相近候选)适合多目标排查,需要全页结构时再用 browser_snapshot { mode: \"aria\" }(可交互元素带 ref=eN,click/type/select/press 直接传 ref 代替 CSS 选择器);下拉选择(原生 select 与 antd/element 组件库)用 browser_select 传 selector/ref/what + option 文本一步完成;固定小序列(点击→等待→输入→提交)用 browser_batch 一次执行减少往返;标签管理用 browser_tabs;下载用 browser_download(wait=true 可等新下载);登录态用 browser_cookies。做自动化测试时:用 browser_wait_for 显式等待页面稳定/元素出现,用 browser_assert 断言(失败自动截图;visual={baseline} 可做视觉回归,先用 browser_screenshot { baseline } 建基线),用 browser_network 检查接口调用与 4xx/5xx,跑完一轮可用 browser_record save 保存操作序列、browser_replay 回放做回归(选择器失效自动按指纹自愈;vars/data 支持参数化与数据驱动)。每次 replay/batch 都记入运行历史,browser_report list/export 可查看与导出回归报告。抓取结构化数据用 browser_extract(fields 定义 CSS 字段,可翻页,可导出 CSV/JSONL)。遇到需要登录的网站:先 browser_open 打开登录页,告知用户在浏览器窗口完成登录后点面板登录卡上的「我已完成登录」,再调用 browser_wait_for_login 等待(用户点按钮即返回,不自动猜测登录状态;也可给 successSelector/successUrl 作确定性自动条件;无面板环境必须给其一,否则调用会报错);验证码/二次确认等更广的「人补一步」场景用 browser_pause_for_human(提示语会显示在实时画面面板);配置 userDataDir 时登录态会持久化。用户可通过界面右下角面板的实时画面查看浏览器。";
+const CORE_TOOL_PROMPT = "浏览器工具操作一个共享浏览器会话(toolset=core:已精简工具集)。定位操作元素最省事的方式是意图语义定位:browser_click/browser_type/browser_select 直接传 what(元素名称/label,如 what:'登录'),一次调用替代快照→查找→点击;零命中报错附最相近候选。需要精确控制时再用 selector/ref:打开页面后用 browser_snapshot 读内容(scope 限定区域、since 增量重读省 token),browser_find(query 传名称,返回 ref),点击/输入/按键/下拉用 browser_click/browser_type/browser_press/browser_select(selector 或 ref);固定小序列用 browser_batch;等待用 browser_wait/browser_wait_for,断言用 browser_assert;接口检查用 browser_network;标签 browser_tabs;下载/上传 browser_download/browser_upload。需要人工:登录用 browser_wait_for_login(用户在面板点「我已完成登录」即返回;无面板环境必须给 successSelector/successUrl,否则调用报错),验证码/二次确认用 browser_pause_for_human,敏感动作(提交/删除/支付)前用 browser_confirm。环境异常先跑 browser_doctor 诊断。录制/回放/报告/抽取/profile/隔离 context 等工具当前未注册(toolset=core),需要时把配置改为 toolset: all 并重启 DSH。用户可通过界面右下角面板的实时画面查看浏览器。";
 /** confirmMode 附加指引(与 DSH 入口同款语义,manual 面向宿主审批、auto 说明硬闸)。 */
 function confirmGuidanceOf(confirmMode) {
 	if (confirmMode === "manual") return "本环境 confirmMode 为 manual:凡提交/删除/支付等不可逆或影响线上数据的敏感动作,执行前必须先调用 browser_confirm(reason 说明操作与影响,等待用户在实时画面面板点允许/拒绝;拒绝或超时即放弃该动作,不得换路径绕过)。";
@@ -483,6 +483,33 @@ function snapshotVersionEntry(cache, version) {
 	if (cache === void 0) return void 0;
 	return cache.history[cache.history.length - 1]?.version === version ? cache.history[cache.history.length - 1] : cache.history.find((e) => e.version === version);
 }
+const lastStableNavSeqs = /* @__PURE__ */ new WeakMap();
+/** 记录"最近一次成功操作"的导航代际(pageIdentity 打点,零成本)。 */
+function markStableNav(page) {
+	lastStableNavSeqs.set(page, pageNavSeq(page));
+}
+/** 当前代际距最近成功操作代际的差值(≥1 = 期间发生过导航)。 */
+function navSinceStable(page) {
+	return pageNavSeq(page) - (lastStableNavSeqs.get(page) ?? pageNavSeq(page));
+}
+const externalNavs = /* @__PURE__ */ new WeakMap();
+/** 记录一次疑似外部导航(非工具窗口内发生的 framenavigated)。 */
+function noteExternalNav(page, url) {
+	const list = externalNavs.get(page) ?? [];
+	list.push({
+		url,
+		at: Date.now()
+	});
+	if (list.length > 5) list.shift();
+	externalNavs.set(page, list);
+}
+/** 读取并清空疑似外部导航记录,拼装 warning 文案;无记录返回 undefined。 */
+function drainExternalNavWarning(page) {
+	const list = externalNavs.get(page);
+	if (list === void 0 || list.length === 0) return void 0;
+	externalNavs.delete(page);
+	return `检测到非工具触发的页面导航(页面自动跳转或人工操作:${list.map((n) => n.url.slice(0, 80)).join(" → ")}),此前的定位结果可能基于被切换后的页面,请核实当前页面状态`;
+}
 let interactivePanelPresent = true;
 /** 标记当前宿主环境是否挂载了交互面板(DSH 插件=true;独立 MCP 模式=false)。 */
 function setInteractivePanelPresent(present) {
@@ -501,6 +528,16 @@ function getPendingConfirm() {
 function clearPendingConfirm() {
 	pendingConfirm = null;
 }
+let pendingLoginWait = null;
+function setPendingLoginWait(entry) {
+	pendingLoginWait = entry;
+}
+function getPendingLoginWait() {
+	return pendingLoginWait;
+}
+function clearPendingLoginWait() {
+	pendingLoginWait = null;
+}
 let pendingPick = null;
 function setPendingPick(entry) {
 	pendingPick = entry;
@@ -822,6 +859,53 @@ function injectWalker(entry) {
 	const src = `"use strict"; return function (payload) { var __name = (t, v) => t; const w = (${CORE_SRC})(); return (${entry.toString()})(payload, w); };`;
 	return new Function(src)();
 }
+const pickTopDialog = injectWalker((payload, w) => {
+	const effectiveZ = (el) => {
+		let node = el;
+		while (node !== null) {
+			const cs = getComputedStyle(node);
+			if (cs.position !== "static" && cs.zIndex !== "auto") {
+				const z = Number.parseInt(cs.zIndex, 10);
+				if (Number.isFinite(z)) return z;
+			}
+			node = w.composedParent(node);
+		}
+		return 0;
+	};
+	const visible = (el) => {
+		if (!(el instanceof HTMLElement)) return false;
+		const cs = getComputedStyle(el);
+		if (cs.display === "none" || cs.visibility === "hidden") return false;
+		const r = el.getBoundingClientRect();
+		return r.width > 0 && r.height > 0;
+	};
+	const collect = (sel) => {
+		try {
+			return Array.from(document.querySelectorAll(sel)).filter(visible);
+		} catch {
+			return [];
+		}
+	};
+	let tier = "precise";
+	let nodes = collect(payload.precise);
+	if (nodes.length === 0) {
+		tier = "fuzzy";
+		nodes = collect(payload.fuzzy);
+	}
+	if (nodes.length === 0) return null;
+	const zs = nodes.map((n) => effectiveZ(n));
+	const maxZ = Math.max(...zs);
+	const top = nodes.filter((n, i) => zs[i] === maxZ);
+	const outermost = top.filter((n) => !top.some((m) => m !== n && m.contains(n)));
+	const pool = outermost.length > 0 ? outermost : top;
+	const winner = pool[pool.length - 1];
+	if (winner === void 0) return null;
+	return {
+		selector: w.cssPath(winner),
+		z: maxZ,
+		tier
+	};
+});
 //#endregion
 //#region lib/types/browser/session/recorder.js
 /** 已保存的录制脚本:name → 步骤数组。 */
@@ -1069,15 +1153,109 @@ function cleanupScreenshots(dir, opts) {
 	return removed;
 }
 //#endregion
+//#region lib/types/browser/primitives/ui-library.js
+const GENERIC = {
+	dialogWords: [
+		"modal",
+		"drawer",
+		"dialog"
+	],
+	dialogExcludedParts: [
+		"mask",
+		"wrap",
+		"root",
+		"header",
+		"footer",
+		"title",
+		"close",
+		"body",
+		"btn"
+	],
+	/** 下拉触发器内部件(点它展开) */
+	dropdownTriggerParts: "[class*='selector'], [role='combobox']",
+	/** 下拉浮层容器的子串词(portal 挂载的面板) */
+	dropdownFloatWords: ["select-dropdown", "popper"],
+	/** 通用下拉选项行(select 状态机消费;库精确层另补) */
+	dropdownOptionRows: "[class*='item-option']:not([class*='empty']), [class*='select-dropdown'] li:not([class*='empty'])",
+	/** 可交互「选项」枚举(elements 工具下拉选项清单消费) */
+	dropdownOptionEnumeration: [
+		"[role='option']",
+		"[role='menuitem']",
+		"[class*='select'][class*='dropdown'] [class*='option']",
+		"[class*='select'][class*='dropdown'] [class*='item']",
+		"[role='listbox'] [role='option']"
+	].join(", "),
+	/** 多选标签清除按钮 */
+	dropdownClearButtons: "[class*='clear'], [aria-label*='clear']",
+	/** 多选标签移除按钮 */
+	dropdownRemoveButtons: "[class*='remove'], [class*='close'], [aria-label*='close']",
+	/** 空态指示器 */
+	emptyStates: "[class*='empty'], [class*='no-data'], [role='status'], [class*='item-empty']",
+	/** 表单项容器(宽松:BEM/-item 子串 + group + form 元素;label 反查主用) */
+	formItemContainers: "[class*='form-item'], [class*='form__item'], [role='group'], form, .form-group",
+	/**
+	* 表单项容器(严格:带分隔符前缀,避免 platform-item 之类无关门类误命中;
+	* elements 工具页内 labelOf 消费)
+	*/
+	formItemContainersStrict: "[class*='-form-item'], [class*='__form-item'], form, .form-group",
+	/** 表单项宿主判定(目标是否处于表单语境;含 label 本身) */
+	formItemHosts: "label, [class*='form-item'], [class*='form__item'], [class*='form-group']",
+	/** 表单项 label(dom 原语 label 反查消费) */
+	formItemLabels: "[class*='form-item-label'], [class*='form-item__label'], [class*='label'], label",
+	/** 表单 label(简化集;elements 工具页内 labelOf 消费) */
+	formLabelSimple: "[class*='label'], label"
+};
+/**
+* 注册新库(示例:naive-ui):
+*   const naiveUi: UILibrarySpec = {
+*     name: "naive-ui",
+*     modalContainers: [".n-modal-container"],
+*     drawerContainers: [".n-drawer-container"],
+*     dropdownContainers: [".n-base-select-menu"],
+*     dropdownOptions: [".n-base-select-option"],
+*   };
+* 追加到 UI_LIBRARIES 即可,弹窗顶层仲裁与下拉浮层发现自动获得该库精确层支持;
+* 未注册的库仍由通用子串层兜底。配套要求:补一个该库真页面的 e2e
+* (playground 模式照抄 test:enterprise),防止想当然的类名污染仲裁。
+*/
+const UI_LIBRARIES = [{
+	name: "antd",
+	modalContainers: [".ant-modal", ".ant-modal-content"],
+	drawerContainers: [".ant-drawer", ".ant-drawer-content-wrapper"],
+	dropdownContainers: [".ant-select-dropdown"],
+	dropdownOptions: [".ant-select-item-option"]
+}, {
+	name: "element-plus",
+	modalContainers: [".el-dialog"],
+	drawerContainers: [".el-drawer"],
+	dropdownContainers: [".el-select-dropdown"],
+	dropdownOptions: [".el-select-dropdown__item"]
+}];
+const flatOf = (libs, key) => libs.flatMap((lib) => lib[key]);
+/** 弹窗/抽屉容器(库精确层原料,未加 display:none 预过滤)。 */
+function dialogContainersOf(libs = UI_LIBRARIES) {
+	return [...flatOf(libs, "modalContainers"), ...flatOf(libs, "drawerContainers")];
+}
+/** 弹窗模糊层选择器串:子串词 + 子节点排除(:not 双命名)+ display:none 预过滤。 */
+function composeDialogFuzzy(words = GENERIC.dialogWords, excludedParts = GENERIC.dialogExcludedParts) {
+	return words.map((word) => [`[class*='${word}']:not([style*='display: none'])`, ...excludedParts.map((part) => `:not([class*='${word}-${part}']):not([class*='${word}__${part}'])`)].join("")).join(", ");
+}
+/** 下拉浮层容器选择器列表(库精确层 + 通用子串层,均带 display:none 预过滤)。 */
+function dropdownFloatSelectors(libs = UI_LIBRARIES) {
+	return [...flatOf(libs, "dropdownContainers"), ...GENERIC.dropdownFloatWords.map((w) => `[class*='${w}']`)].map((sel) => `${sel}:not([style*='display: none']):not([class*='hidden'])`);
+}
+/** 下拉选项行选择器列表(标准层 role=option 由消费方自带 + 库精确层 + 通用子串层)。 */
+function dropdownOptionRowsOf(libs = UI_LIBRARIES) {
+	return [...flatOf(libs, "dropdownOptions").map((sel) => `${sel}:not([class*='empty'])`), GENERIC.dropdownOptionRows];
+}
+/** 预组合聚合常量(消费方直接 import)。 */
+const LIBRARY_DIALOG_CONTAINERS = dialogContainersOf();
+const LIBRARY_DROPDOWN_CONTAINERS = dropdownFloatSelectors();
+const LIBRARY_DROPDOWN_OPTIONS = dropdownOptionRowsOf();
+//#endregion
 //#region lib/types/browser/tools/common.js
-/** 组件库下拉框的可见选项选择器并集 (基于通用 WAI-ARIA 与主流组件库规范)。 */
-const DROPDOWN_OPTION_SELECTOR = [
-	"[role='option']",
-	"[role='menuitem']",
-	"[class*='select'][class*='dropdown'] [class*='option']",
-	"[class*='select'][class*='dropdown'] [class*='item']",
-	"[role='listbox'] [role='option']"
-].join(", ");
+/** 组件库下拉框的可见选项枚举(ui-library 注册表单一来源,值与抽取前等价)。 */
+const DROPDOWN_OPTION_SELECTOR = GENERIC.dropdownOptionEnumeration;
 /** 读取 PNG 文件头(IHDR)中的宽高,不解码像素(导出供测试)。 */
 function pngSize(buf) {
 	if (buf.length < 24 || buf.readUInt32BE(0) !== 2303741511) throw new Error("not a PNG file");
@@ -1212,10 +1390,216 @@ function workspaceFilePath(cwd, file) {
 	if (p !== root && !p.startsWith(root + "/") && !p.startsWith(root + "\\")) throw new Error(`文件路径越出工作区: ${file}`);
 	return p;
 }
+const AsyncFunctionConstructor = Object.getPrototypeOf(async function() {}).constructor;
+/** 编译校验(只编译不执行):语法合法返回 true。 */
+function compiles(body) {
+	try {
+		new AsyncFunctionConstructor(body);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** `/` 出现在这些字符(或关键字)之后按正则字面量处理,否则按除号。 */
+const REGEX_ALLOWED_AFTER_CHARS = /* @__PURE__ */ new Set("([{,;=:?&|!%^~*+<>-/");
+const REGEX_ALLOWED_AFTER_WORDS = /* @__PURE__ */ new Set([
+	"return",
+	"typeof",
+	"instanceof",
+	"in",
+	"of",
+	"new",
+	"delete",
+	"void",
+	"throw",
+	"case",
+	"do",
+	"else",
+	"yield",
+	"await"
+]);
+/**
+* 词法扫描(为 ② 服务,fail-safe):定位最后一个「顶层显式 ;」的结束位置,
+* 并检测顶层 return 关键字(有则说明调用方自己管理返回,不自动改写)。
+* 顶层 = 不在字符串/模板/注释/正则内,且 ()[]{} 合并深度为 0(含模板 ${} 插值内)。
+*/
+function scanTopLevel(script) {
+	let lastSemicolonEnd = null;
+	let topLevelReturn = false;
+	let state = "code";
+	let depth = 0;
+	const tplDepths = [];
+	let prevSig = "";
+	let prevWord = "";
+	const isWordChar = (c) => /[A-Za-z0-9_$]/.test(c);
+	for (let i = 0; i < script.length; i++) {
+		const ch = script[i];
+		switch (state) {
+			case "line":
+				if (ch === "\n") state = "code";
+				continue;
+			case "block":
+				if (ch === "*" && script[i + 1] === "/") {
+					state = "code";
+					i++;
+				}
+				continue;
+			case "sq":
+			case "dq":
+				if (ch === "\\") i++;
+				else if (state === "sq" && ch === "'" || state === "dq" && ch === "\"") state = "code";
+				continue;
+			case "tpl":
+				if (ch === "\\") i++;
+				else if (ch === "`") {
+					state = "code";
+					prevSig = "`";
+					prevWord = "";
+				} else if (ch === "$" && script[i + 1] === "{") {
+					tplDepths.push(depth);
+					state = "code";
+					i++;
+				}
+				continue;
+			case "regex":
+				if (ch === "\\") i++;
+				else if (ch === "[") state = "regexClass";
+				else if (ch === "/") {
+					state = "code";
+					prevSig = "/";
+					prevWord = "";
+				}
+				continue;
+			case "regexClass":
+				if (ch === "\\") i++;
+				else if (ch === "]") state = "regex";
+				continue;
+			default:
+				if (ch === "/" && script[i + 1] === "/") {
+					state = "line";
+					i++;
+					continue;
+				}
+				if (ch === "/" && script[i + 1] === "*") {
+					state = "block";
+					i++;
+					continue;
+				}
+				if (ch === "/") {
+					if (prevSig === "" || REGEX_ALLOWED_AFTER_CHARS.has(prevSig) || REGEX_ALLOWED_AFTER_WORDS.has(prevWord)) state = "regex";
+					else {
+						prevSig = "/";
+						prevWord = "";
+					}
+					continue;
+				}
+				if (ch === "'" || ch === "\"") {
+					state = ch === "'" ? "sq" : "dq";
+					prevSig = ch;
+					prevWord = "";
+					continue;
+				}
+				if (ch === "`") {
+					state = "tpl";
+					prevSig = ch;
+					prevWord = "";
+					continue;
+				}
+				if (ch === "(" || ch === "[" || ch === "{") {
+					depth++;
+					prevSig = ch;
+					prevWord = "";
+					continue;
+				}
+				if (ch === ")" || ch === "]") {
+					depth = Math.max(0, depth - 1);
+					prevSig = ch;
+					prevWord = "";
+					continue;
+				}
+				if (ch === "}") {
+					if (tplDepths.length > 0 && depth === tplDepths[tplDepths.length - 1]) {
+						tplDepths.pop();
+						state = "tpl";
+					} else depth = Math.max(0, depth - 1);
+					prevSig = ch;
+					prevWord = "";
+					continue;
+				}
+				if (ch === ";") {
+					if (depth === 0 && tplDepths.length === 0) lastSemicolonEnd = i + 1;
+					prevSig = ch;
+					prevWord = "";
+					continue;
+				}
+				if (isWordChar(ch)) {
+					let j = i;
+					while (j < script.length && isWordChar(script[j])) j++;
+					const word = script.slice(i, j);
+					if (depth === 0 && tplDepths.length === 0 && word === "return" && prevSig !== "." && !isWordChar(prevSig)) topLevelReturn = true;
+					prevWord = word;
+					prevSig = script[j - 1];
+					i = j - 1;
+					continue;
+				}
+				if (!/\s/.test(ch)) {
+					prevSig = ch;
+					prevWord = "";
+				}
+				continue;
+		}
+	}
+	return {
+		lastSemicolonEnd,
+		topLevelReturn
+	};
+}
+/**
+* 把 eval 脚本包装成可直接交给 page.evaluate 的代码串,并标明实际执行形态。
+* 语法非法时在 Node 侧抛出引擎原始错误(消息与页内 V8 同源,提前暴露)。
+*/
+function buildEvalScript(script) {
+	if (compiles(`return (\n${script}\n)`)) return {
+		code: `(async () => (\n${script}\n))()`,
+		mode: "expression"
+	};
+	try {
+		new AsyncFunctionConstructor(script);
+	} catch (err) {
+		throw new Error(`eval 脚本语法错误: ${err.message}`);
+	}
+	const { lastSemicolonEnd, topLevelReturn } = scanTopLevel(script);
+	if (!topLevelReturn && lastSemicolonEnd !== null) {
+		const head = script.slice(0, lastSemicolonEnd);
+		const tail = script.slice(lastSemicolonEnd);
+		if (tail.trim() !== "") {
+			const candidate = `${head}\nreturn (\n${tail}\n);`;
+			if (compiles(candidate)) return {
+				code: `(async () => {\n${candidate}\n})()`,
+				mode: "statements-auto-return"
+			};
+		}
+	}
+	return {
+		code: `(async () => {\n${script}\n})()`,
+		mode: "statements"
+	};
+}
 /**
 * 规则化抽取:fields 定义抽取结构,next 选择器驱动翻页(maxPages 上限),
 * 行数超 maxRows 截断;format/file 控制序列化与落盘(json/csv/jsonl/markdown)。
 */
+async function assertExpectedUrl(page, expectUrl, action) {
+	if (typeof expectUrl !== "string" || expectUrl === "") return;
+	const current = page.url();
+	let hit;
+	try {
+		hit = new RegExp(expectUrl).test(current);
+	} catch {
+		hit = current.includes(expectUrl);
+	}
+	if (!hit) throw new Error(`${action} 前置校验失败: expectUrl "${expectUrl}" 与当前页面不符(当前: ${current})——页面可能被切换/回退,请先 browser_snapshot 确认后再操作`);
+}
 //#endregion
 //#region lib/types/browser/primitives/dom.js
 /**
@@ -1233,9 +1617,9 @@ function extractElementLabel(el) {
 		const text = labelledBy.split(/\s+/).map((id) => document.getElementById(id)).filter((n) => !!n).map((n) => (n.innerText || n.textContent || "").trim()).filter(Boolean).join(" ");
 		if (text) return text;
 	}
-	const formItem = el.closest("[class*='form-item'], [class*='form__item'], [role='group'], form, .form-group");
+	const formItem = el.closest(GENERIC.formItemContainers);
 	if (formItem) {
-		const labelEl = formItem.querySelector("[class*='form-item-label'], [class*='form-item__label'], [class*='label'], label");
+		const labelEl = formItem.querySelector(GENERIC.formItemLabels);
 		if (labelEl) {
 			const txt = (labelEl.innerText || labelEl.textContent || "").trim();
 			if (txt) return txt;
@@ -1430,29 +1814,63 @@ async function endChangeWatch(page, options = {}) {
 }
 //#endregion
 //#region lib/types/browser/primitives/dialog.js
+/** 标准层:WAI-ARIA 语义,任何库与原生实现通用。 */
+const ARIA_DIALOG_SELECTORS = [
+	"[role='dialog']",
+	"[role='alertdialog']",
+	"[aria-modal='true']",
+	"dialog[open]"
+];
+/** display:none 内联样式预过滤(动画关闭中的弹窗/keep-alive 残留)。 */
+const hiddenGuard = (sel) => `${sel}:not([style*='display: none'])`;
+/** 精确层 = 标准层 + 库精确层(ui-library 注册表单一来源,新增 UI 库 = 追加 spec)。 */
+const DIALOG_PRECISE_SELECTORS = [...ARIA_DIALOG_SELECTORS, ...LIBRARY_DIALOG_CONTAINERS].map(hiddenGuard).join(", ");
+/** 通用模糊层(未注册库兜底):子串词 + :not() 排除子节点。 */
+const DIALOG_FUZZY_SELECTORS = composeDialogFuzzy();
 /**
-* 通用活动弹窗/对话框/抽屉选择器列表
-* 基于 W3C WAI-ARIA 规范 (role="dialog", aria-modal="true") 与现代 Web 通用命名规范
+* 历史并集 = 精确层 + 模糊层。semantic.ts 弹窗上下文检测与 getActiveDialog 的
+* domOrder 兜底消费(行为与抽取前的并集等价)。
 */
-const ACTIVE_DIALOG_SELECTORS = [
-	"[role='dialog']:not([style*='display: none'])",
-	"[role='alertdialog']:not([style*='display: none'])",
-	"[aria-modal='true']:not([style*='display: none'])",
-	"dialog[open]",
-	".ant-modal:not([style*='display: none'])",
-	".el-dialog:not([style*='display: none'])",
-	".ant-drawer:not([style*='display: none'])",
-	".el-drawer:not([style*='display: none'])",
-	"[class*='modal']:not([style*='display: none'])",
-	"[class*='drawer']:not([style*='display: none'])",
-	"[class*='dialog']:not([style*='display: none'])"
-].join(", ");
+const ACTIVE_DIALOG_SELECTORS = [DIALOG_PRECISE_SELECTORS, DIALOG_FUZZY_SELECTORS].join(", ");
 /**
-* 获取当前页面上处于活动状态的最顶层弹窗容器 (Locator)
+* 获取当前页面上处于活动状态的最顶层弹窗容器;无弹窗返回 null。
+* ① 快速通道——并集零命中(绝大多数无弹窗的工具调用)直接返回 null,与旧行为
+* 「空 locator + 下游 count 0」等价,零额外 evaluate 往返;
+* ② 有弹窗时走分层选择器 + 页内 z-index/可见性仲裁(walker pickTopDialog,
+* 页内逻辑单一来源),单次 round-trip;
+* ③ evaluate 失败(极端 CSP/销毁竞态)或复核计数为 0 时回退文档序 last()
+* 旧行为并标 via: "domOrder",不阻断主流程。
 */
-function getActiveDialog(page) {
+async function getActiveDialog(page) {
+	try {
+		const unionLoc = page.locator(ACTIVE_DIALOG_SELECTORS);
+		if (typeof unionLoc.count === "function") {
+			if (await withTimeout(unionLoc.count(), 800, "弹窗快速探测").catch(() => 0) === 0) return null;
+		}
+	} catch {}
+	try {
+		const pick = await withTimeout(page.evaluate(pickTopDialog, {
+			precise: DIALOG_PRECISE_SELECTORS,
+			fuzzy: DIALOG_FUZZY_SELECTORS
+		}), 1500, "活动弹窗仲裁");
+		if (pick !== null && typeof pick === "object" && typeof pick.selector === "string" && pick.selector !== "") {
+			const hit = pick;
+			const loc = page.locator(hit.selector);
+			if (typeof loc.count === "function") {
+				if (await withTimeout(loc.count(), 800, "活动弹窗复核").catch(() => 0) > 0) return {
+					locator: typeof loc.first === "function" ? loc.first() : loc,
+					via: "zIndex",
+					z: hit.z,
+					tier: hit.tier
+				};
+			}
+		}
+	} catch {}
 	const dialogLoc = page.locator(ACTIVE_DIALOG_SELECTORS);
-	return typeof dialogLoc.last === "function" ? dialogLoc.last() : dialogLoc.first();
+	return {
+		locator: typeof dialogLoc.last === "function" ? dialogLoc.last() : dialogLoc.first(),
+		via: "domOrder"
+	};
 }
 //#endregion
 //#region lib/types/browser/primitives/select.js
@@ -1471,14 +1889,14 @@ async function executeUniversalSelect(ctx) {
 		throw new Error(`原生下拉无选项 "${want}"; 可用选项: ${options.map((t) => t.trim()).join(" / ")}`);
 	}
 	let resolvedTarget = target;
-	if (await withTimeout(target.evaluate((el) => {
+	if (await withTimeout(target.evaluate((el, hosts) => {
 		if (el.tagName.toLowerCase() === "label") return true;
 		const cls = typeof el.className === "string" ? el.className : "";
 		if (/(?:form-item|form__item|form-group)/i.test(cls)) return true;
-		if (el.closest("label, [class*='form-item'], [class*='form__item'], [class*='form-group']")) return !el.matches("[role='combobox'], select, [class*='select-selector']");
+		if (el.closest(hosts)) return !el.matches("[role='combobox'], select, [class*='select-selector']");
 		if (!el.matches("[role='combobox'], select, [class*='select'], [class*='selector']")) return true;
 		return false;
-	}), 1500, "探测 label 或非标文本容器").catch(() => false)) {
+	}, GENERIC.formItemHosts), 1500, "探测 label 或非标文本容器").catch(() => false)) {
 		const descendantSelect = target.locator("xpath=.//*[@role='combobox' or self::select or contains(@class, 'select-selector') or contains(@class, 'select')][not(self::label)]").first();
 		if (await descendantSelect.count().catch(() => 0) > 0) resolvedTarget = descendantSelect;
 		else {
@@ -1503,15 +1921,15 @@ async function executeUniversalSelect(ctx) {
 	const hostLocator = resolvedTarget.locator("xpath=ancestor-or-self::*[@role='combobox' or contains(@class, 'select') or contains(@class, 'selector')][last()]");
 	const actualTarget = await hostLocator.count().catch(() => 0) > 0 ? hostLocator.first() : resolvedTarget;
 	if (clear) try {
-		const clearBtn = actualTarget.locator("[class*='clear'], [aria-label*='clear']").first();
+		const clearBtn = actualTarget.locator(GENERIC.dropdownClearButtons).first();
 		if (await clearBtn.count().catch(() => 0) > 0 && await clearBtn.isVisible().catch(() => false)) await clearBtn.click({ timeout: 1e3 }).catch(() => {});
 		else {
-			const removeBtns = actualTarget.locator("[class*='remove'], [class*='close'], [aria-label*='close']");
+			const removeBtns = actualTarget.locator(GENERIC.dropdownRemoveButtons);
 			const removeCount = await removeBtns.count().catch(() => 0);
 			for (let i = 0; i < removeCount; i++) await removeBtns.nth(0).click({ timeout: 500 }).catch(() => {});
 		}
 	} catch {}
-	if (!await withTimeout(actualTarget.evaluate((el) => {
+	const probeExpanded = () => withTimeout(actualTarget.evaluate((el) => {
 		if (el.getAttribute("aria-expanded") === "true") return true;
 		const host = el.closest("[role='combobox'], [class*='select']") || el;
 		if (host && host.getAttribute("aria-expanded") === "true") return true;
@@ -1524,8 +1942,11 @@ async function executeUniversalSelect(ctx) {
 			if (dd && dd.offsetParent !== null) return true;
 		}
 		return false;
-	}), 2e3, "检查下拉展开状态").catch(() => false)) {
-		const triggerChild = actualTarget.locator("[class*='selector'], [role='combobox']").first();
+	}), 2e3, "检查下拉展开状态").catch(() => false);
+	const isExpanded = await probeExpanded();
+	let expandSignalMissed = false;
+	if (!isExpanded) {
+		const triggerChild = actualTarget.locator(GENERIC.dropdownTriggerParts).first();
 		let clicked = false;
 		if (await triggerChild.count().catch(() => 0) > 0) {
 			await triggerChild.click({ timeout: 2e3 }).catch(async () => {
@@ -1543,7 +1964,9 @@ async function executeUniversalSelect(ctx) {
 			});
 		});
 		await page.waitForTimeout(120);
+		expandSignalMissed = !await probeExpanded();
 	}
+	const optionWaitMs = expandSignalMissed ? 1500 : Math.min(timeout, 5e3);
 	const controlsId = await withTimeout(actualTarget.evaluate((el) => {
 		const direct = el.getAttribute("aria-controls") || el.getAttribute("aria-owns");
 		if (direct) return direct;
@@ -1551,8 +1974,8 @@ async function executeUniversalSelect(ctx) {
 		const inner = host?.querySelector("input[role='combobox'], [aria-controls], [aria-owns]");
 		return inner?.getAttribute("aria-controls") || inner?.getAttribute("aria-owns") || host?.getAttribute("aria-controls") || "";
 	}), 2e3, "解析下拉关联 controlsId").catch(() => "");
-	const optionSelector = "[role='option']:not([style*='height: 0px']):not([class*='empty']), [class*='item-option']:not([class*='empty']), [class*='select-dropdown'] li:not([class*='empty'])";
-	const dropdownSelector = "[role='listbox']:not([style*='display: none']), [class*='select-dropdown']:not([style*='display: none']):not([class*='hidden']), [class*='popper']:not([style*='display: none'])";
+	const optionSelector = ["[role='option']:not([style*='height: 0px']):not([class*='empty'])", ...LIBRARY_DROPDOWN_OPTIONS].join(", ");
+	const dropdownSelector = ["[role='listbox']:not([style*='display: none'])", ...LIBRARY_DROPDOWN_CONTAINERS].join(", ");
 	let options;
 	let targetDropdown = null;
 	if (controlsId) {
@@ -1570,7 +1993,7 @@ async function executeUniversalSelect(ctx) {
 	}
 	await options.first().waitFor({
 		state: "visible",
-		timeout: Math.min(timeout, 5e3)
+		timeout: optionWaitMs
 	}).catch(() => {});
 	const visibleTexts = (await options.evaluateAll((els) => els.map((el) => {
 		return {
@@ -1580,10 +2003,12 @@ async function executeUniversalSelect(ctx) {
 		};
 	})).catch(() => [])).map((e) => e.text || e.title || e.aria).filter(Boolean);
 	if (visibleTexts.length === 0) {
-		const isEmpty = targetDropdown !== null ? await targetDropdown.locator("[class*='empty'], [class*='no-data'], [role='status'], [class*='item-empty']").first().isVisible().catch(() => false) : false;
+		const emptySelector = GENERIC.emptyStates;
+		const isEmpty = targetDropdown !== null ? await targetDropdown.locator(emptySelector).first().isVisible().catch(() => false) : false;
 		await actualTarget.click({ timeout: 1e3 }).catch(() => {});
-		if (isEmpty) throw new Error(`下拉浮层当前无选项(数据为空态/无可选数据): ${label}`);
-		throw new Error(`点击 ${label} 后未出现下拉选项(选项列表为空态)`);
+		const attribution = expandSignalMissed ? ";触发器点击疑似未生效(展开信号缺失,可能被透明遮罩拦截,建议 browser_snapshot 核实或配合 click effect 验证)" : "";
+		if (isEmpty) throw new Error(`下拉浮层当前无选项(数据为空态/无可选数据): ${label}${attribution}`);
+		throw new Error(`点击 ${label} 后未出现下拉选项(选项列表为空态)${attribution}`);
 	}
 	const wantStripped = want.replace(/\s+/g, "");
 	let index = visibleTexts.findIndex((t) => t === want);
@@ -1729,7 +2154,7 @@ async function fillFormFieldHelper(page, field, scope) {
 	const root = scope ? page.locator(scope) : page;
 	const { key, value } = field;
 	try {
-		const formItems = root.locator("[class*='form-item'], [class*='form__item'], [role='group'], .form-group");
+		const formItems = root.locator(GENERIC.formItemContainers);
 		const count = await formItems.count().catch(() => 0);
 		for (let i = 0; i < count; i++) {
 			const item = formItems.nth(i);
@@ -1791,6 +2216,45 @@ async function fillFormFieldHelper(page, field, scope) {
 	};
 }
 //#endregion
+//#region lib/types/browser/primitives/drag.js
+/**
+* 核心:在两个已解析的 Locator 之间执行拖拽。
+* 优先 Playwright dragTo(覆盖 HTML5 DnD 与多数组件库);
+* 失败或调用方指定 preferMouse(如跨 Frame,dragTo 的已知限制)时
+* 降级为物理鼠标序列。返回实际使用的通道。失败抛错(带可定位的诊断信息)。
+*/
+async function dragAndDropLocators(page, source, target, opts = {}) {
+	const timeoutMs = opts.timeoutMs ?? 3e3;
+	if (!opts.preferMouse) try {
+		if (typeof source.dragTo === "function") {
+			await source.dragTo(target, { timeout: timeoutMs });
+			return "dragTo";
+		}
+	} catch {}
+	let srcErr = null;
+	const srcBox = await source.boundingBox({ timeout: timeoutMs }).catch((e) => {
+		srcErr = e;
+		return null;
+	});
+	if (!srcBox) throw new Error(`drag 失败: 源元素不可见或未命中(等待 ${timeoutMs}ms)${srcErr instanceof Error ? `: ${srcErr.message}` : ""}`);
+	let tgtErr = null;
+	const tgtBox = await target.boundingBox({ timeout: timeoutMs }).catch((e) => {
+		tgtErr = e;
+		return null;
+	});
+	if (!tgtBox) throw new Error(`drag 失败: 目标元素不可见或未命中(等待 ${timeoutMs}ms)${tgtErr instanceof Error ? `: ${tgtErr.message}` : ""}`);
+	const viewport = typeof page.viewportSize === "function" ? page.viewportSize() : null;
+	const outsideViewport = viewport !== null && (srcBox.x + srcBox.width < 0 || srcBox.x > viewport.width || tgtBox.x + tgtBox.width < 0 || tgtBox.x > viewport.width || srcBox.y + srcBox.height < 0 || srcBox.y > viewport.height || tgtBox.y + tgtBox.height < 0 || tgtBox.y > viewport.height);
+	if (outsideViewport && typeof target.scrollIntoViewIfNeeded === "function") await target.scrollIntoViewIfNeeded({ timeout: timeoutMs }).catch(() => {});
+	const sx = (outsideViewport ? await source.boundingBox({ timeout: timeoutMs }).catch(() => null) : null) ?? srcBox;
+	const tx = (outsideViewport ? await target.boundingBox({ timeout: timeoutMs }).catch(() => null) : null) ?? tgtBox;
+	await page.mouse.move(sx.x + sx.width / 2, sx.y + sx.height / 2);
+	await page.mouse.down();
+	await page.mouse.move(tx.x + tx.width / 2, tx.y + tx.height / 2, { steps: 8 });
+	await page.mouse.up();
+	return "mouse";
+}
+//#endregion
 //#region lib/types/browser/session/semantic.js
 /**
 * 页内语义扫描:按 query 打分收集可交互元素(弹窗内优先、可见优先、高分优先)。
@@ -2149,6 +2613,37 @@ const failureContextProbe = injectWalker(() => {
 		hasShadow
 	};
 });
+/**
+* selector 零命中时的相似属性探针(best-effort):提取首个属性片段(或 #id)
+* 做包含匹配计数——直接暴露「锚点属性全失效」与「组合选择器其他部分写错」两种病因。
+* 纯提示用途,失败/无属性片段返回空串。
+*/
+const similarAttrProbe = injectWalker((rawSelector) => {
+	let attr = "";
+	let val = "";
+	const m = rawSelector.match(/\[([\w-]+)(?:\^|\$|\*|~)?=['"]([^'"]+)['"]\]/);
+	if (m !== null) {
+		attr = m[1] ?? "";
+		val = m[2] ?? "";
+	} else {
+		const idm = rawSelector.match(/^#([\w-]+)/);
+		if (idm !== null) {
+			attr = "id";
+			val = idm[1] ?? "";
+		}
+	}
+	if (attr === "" || val === "") return "";
+	try {
+		const safe = val.replace(/["\\]/g, "");
+		if (safe === "") return "";
+		const hits = Array.from(document.querySelectorAll(`[${attr}*="${safe}"]`)).slice(0, 50);
+		if (hits.length === 0) return `页面不存在任何 ${attr} 含 "${safe}" 的元素(锚点属性可能已失效或页面已切换)`;
+		const samples = hits.slice(0, 3).map((el) => el.getAttribute(attr) || "").filter((s) => s !== "").join(" | ").slice(0, 120);
+		return `页面存在 ${hits.length} 个 ${attr} 含 "${safe}" 的元素(组合选择器的其他部分可能写错)${samples !== "" ? `,如: ${samples}` : ""}`;
+	} catch {
+		return "";
+	}
+});
 /** ref 坐标兜底的名称相似判定:去空白互相包含,或 LCS 占比 ≥ 0.6。 */
 function nameSimilar(a, b) {
 	if (a === "" || b === "") return true;
@@ -2230,9 +2725,9 @@ async function resolveTargetLocator(page, args, opts = {}) {
 			};
 		}
 		if (!isIFrame) try {
-			const activeDialog = getActiveDialog(page);
-			if (activeDialog && typeof activeDialog.getByRole === "function") {
-				const inDialog = entry.name !== "" ? activeDialog.getByRole(entry.role, { name: buildFlexibleTextPattern(entry.name) }).first() : activeDialog.getByRole(entry.role).first();
+			const dlg = (await getActiveDialog(page))?.locator;
+			if (dlg && typeof dlg.getByRole === "function") {
+				const inDialog = entry.name !== "" ? dlg.getByRole(entry.role, { name: buildFlexibleTextPattern(entry.name) }).first() : dlg.getByRole(entry.role).first();
 				if (await withTimeout(inDialog.count(), 1e3, "弹窗内 role 查找").catch(() => 0) > 0) return {
 					locator: inDialog,
 					container,
@@ -2354,10 +2849,29 @@ async function resolveTargetLocator(page, args, opts = {}) {
 	}
 	const what = args.what;
 	if (typeof what === "string" && what.trim() !== "" && args.selector === void 0 && args.ref === void 0 && args.mark === void 0 && rowPattern === void 0) {
+		const navSeqBefore = pageNavSeq(page);
+		let urlBefore = null;
+		try {
+			urlBefore = page.url();
+		} catch {}
 		const res = await resolveSemanticTarget(page, what, {
 			scope: typeof args.scope === "string" && args.scope !== "" ? args.scope : void 0,
 			preferredRoles: opts.preferredRoles
 		});
+		let urlAfter = urlBefore;
+		try {
+			urlAfter = page.url();
+		} catch {}
+		if (pageNavSeq(page) !== navSeqBefore || urlAfter !== urlBefore) {
+			const raceErr = /* @__PURE__ */ new Error(`页面在语义定位过程中发生变化(${urlBefore} → ${page.url()}),本次扫描结果已作废;请重试或重新 browser_snapshot`);
+			raceErr.locationFailure = {
+				phase: "navRace",
+				candidates: 0,
+				dialogActive: false,
+				hasShadow: false
+			};
+			throw raceErr;
+		}
 		if (!("candidates" in res)) return res;
 		for (const role of [
 			"button",
@@ -2414,6 +2928,14 @@ async function resolveTargetLocator(page, args, opts = {}) {
 				...ctx
 			};
 		} catch {}
+		const navDelta = navSinceStable(page);
+		if (navDelta >= 1) {
+			let route = "";
+			try {
+				route = page.url().slice(0, 80);
+			} catch {}
+			err.message = `${err.message};页面自上次成功操作后已发生 ${navDelta} 次导航,what 目标可能在另一页面${route !== "" ? `(当前: ${route})` : ""}`;
+		}
 		throw err;
 	}
 	if (args.selector === void 0) throw new Error("需要 selector 或 ref 之一 (或指定 row 与 action 进行表格行级定界,或用 what 语义定位)");
@@ -2431,9 +2953,9 @@ async function resolveTargetLocator(page, args, opts = {}) {
 		}
 	}
 	try {
-		const activeDialog = getActiveDialog(page);
-		if (activeDialog && typeof activeDialog.locator === "function") {
-			const inDialog = activeDialog.locator(rawSelector);
+		const dlg = (await getActiveDialog(page))?.locator;
+		if (dlg && typeof dlg.locator === "function") {
+			const inDialog = dlg.locator(rawSelector);
 			if (typeof inDialog.count === "function") {
 				const inDialogCount = await withTimeout(inDialog.count(), 1e3, "弹窗内 selector 探测").catch(() => 0);
 				if (inDialogCount > 0) {
@@ -2454,7 +2976,43 @@ async function resolveTargetLocator(page, args, opts = {}) {
 	let visibleCount;
 	let target = typeof baseLocator.first === "function" ? baseLocator.first() : baseLocator;
 	if (typeof baseLocator.count === "function") {
-		totalCount = await withTimeout(baseLocator.count(), 2e3, "selector 计数").catch(() => 0);
+		try {
+			totalCount = await withTimeout(baseLocator.count(), 2e3, "selector 计数");
+		} catch {
+			const err = /* @__PURE__ */ new Error(`selector 计数超时: ${rawSelector}(页面可能正忙或 DOM 过大,可重试;若持续超时建议 browser_snapshot 核实页面状态)`);
+			err.locationFailure = {
+				phase: "countTimeout",
+				candidates: 0,
+				dialogActive: false,
+				hasShadow: false
+			};
+			throw err;
+		}
+		if (totalCount === 0) {
+			const zeroMatchErr = /* @__PURE__ */ new Error(`selector 未命中: ${rawSelector}(元素未渲染/选择器写错/页面已切换;可用 browser_elements 探查表单结构、browser_wait_for 等元素出现,或 browser_snapshot 取 ref)`);
+			zeroMatchErr.locationFailure = {
+				phase: "zeroMatch",
+				candidates: 0,
+				dialogActive: false,
+				hasShadow: false
+			};
+			try {
+				const ctx = await withTimeout(page.evaluate(failureContextProbe, void 0), 1500, "失败特征探测");
+				if (ctx !== null && typeof ctx === "object") zeroMatchErr.locationFailure = {
+					phase: "zeroMatch",
+					candidates: 0,
+					...ctx
+				};
+			} catch {}
+			try {
+				const hint = await withTimeout(page.evaluate(similarAttrProbe, rawSelector), 1500, "相似属性探测");
+				if (typeof hint === "string" && hint !== "") {
+					zeroMatchErr.similarHint = hint;
+					zeroMatchErr.message = `${zeroMatchErr.message};${hint}`;
+				}
+			} catch {}
+			throw zeroMatchErr;
+		}
 		if (totalCount > 0 && typeof baseLocator.locator === "function") {
 			const visibleLocator = baseLocator.locator("visible=true");
 			if (typeof visibleLocator.count === "function") {
@@ -2869,6 +3427,8 @@ const DOM_COMPAT_SCRIPT = `
   };
 })();
 `;
+/** 最近一次工具触碰时间戳(getPage 打点):外部导航判定基准。 */
+let lastToolTouchAt = 0;
 function attachPage(page, config) {
 	const timeoutMs = config.timeoutMs ?? 3e4;
 	page.setDefaultTimeout(timeoutMs);
@@ -2892,6 +3452,7 @@ function attachPage(page, config) {
 		const url = frame.url();
 		if (!url || url === "about:blank") return;
 		recordNav(profile, url);
+		if (Date.now() - lastToolTouchAt > 1e4) noteExternalNav(page, url);
 	});
 	page.on("load", () => {
 		const list = historyOf(profile);
@@ -3117,6 +3678,7 @@ async function newPage(config) {
 }
 /** 返回当前活动页面(没有则新建),并保证浏览器已启动。 */
 async function getPage(config) {
+	lastToolTouchAt = Date.now();
 	const state = stateOf();
 	if (state.browser === null && state.context === null) await launchProfile(currentProfile, config);
 	pruneClosedPages(state);
@@ -3180,6 +3742,7 @@ async function closeBrowser() {
 }
 /** Best-effort current page identity, safe when nothing is open.title 有界防页面忙时挂起。 */
 async function pageIdentity(page) {
+	markStableNav(page);
 	try {
 		const title = await new Promise((resolve, reject) => {
 			const t = setTimeout(() => reject(/* @__PURE__ */ new Error("title timeout")), 2e3);
@@ -3775,15 +4338,20 @@ async function snapshotTool(config, args) {
 			const isDialogScope = /modal|dialog|drawer/i.test(scope);
 			let hint = isDialogScope ? "。目标容器可能已消失（弹窗/抽屉已关闭、已提交或页面已导航）" : "";
 			if (isDialogScope && typeof page.locator === "function") try {
-				const activeDialogLoc = getActiveDialog(page);
-				if ((typeof activeDialogLoc?.count === "function" ? await withTimeout(activeDialogLoc.count(), 1e3, "活动弹窗探测").catch(() => 0) : 0) > 0 && typeof activeDialogLoc.first === "function") {
+				const activeDialogLoc = (await getActiveDialog(page))?.locator;
+				const count = activeDialogLoc !== void 0 && typeof activeDialogLoc.count === "function" ? await withTimeout(activeDialogLoc.count(), 1e3, "活动弹窗探测").catch(() => 0) : 0;
+				if (activeDialogLoc !== void 0 && count > 0 && typeof activeDialogLoc.first === "function") {
 					const alternate = await withTimeout(activeDialogLoc.first().evaluate((el) => {
-						if (el.getAttribute("role") === "dialog") return "[role='dialog']";
+						const out = [];
+						const role = el.getAttribute("role");
+						if (role === "dialog" || role === "alertdialog") out.push(`[role='${role}']`);
 						const cls = el.className;
 						if (typeof cls === "string" && cls.trim()) {
-							const parts = cls.trim().split(/\s+/);
-							return `.${parts.find((c) => /modal|dialog|drawer/i.test(c)) || parts[0]}`;
+							const tokens = cls.trim().split(/\s+/);
+							const relevant = tokens.find((c) => /modal|dialog|drawer/i.test(c)) || tokens[0];
+							out.push(`.${relevant}`);
 						}
+						if (out.length > 0) return out.join("");
 						return el.tagName.toLowerCase();
 					}), 1e3, "解析活动弹窗标识").catch(() => null);
 					if (alternate) hint += ` (检测到当前页面存在「${alternate}」容器，可能混淆了弹窗与抽屉类型)`;
@@ -4103,7 +4671,7 @@ async function somFallbackShot(config, exec) {
 async function elementsTool(config, args) {
 	const page = await getPage(config);
 	const max = Math.min(Math.max(Number(args.max ?? 60) || 60, 1), 200);
-	const data = await page.evaluate(([maxN, optionSelector]) => {
+	const data = await page.evaluate(([maxN, optionSelector, formItemSel, formLabelSel]) => {
 		/** 提取元素的关联 label:aria-label → label[for] → form-item 标签(antd/element)。 */
 		function labelOf(el) {
 			const aria = el.getAttribute("aria-label");
@@ -4112,7 +4680,7 @@ async function elementsTool(config, args) {
 				const text = document.querySelector(`label[for="${CSS.escape(el.id)}"]`)?.textContent?.trim();
 				if (text) return text;
 			}
-			const formLabel = el.closest("[class*='-form-item'], [class*='__form-item'], form, .form-group")?.querySelector("[class*='label'], label")?.textContent?.trim();
+			const formLabel = el.closest(formItemSel)?.querySelector(formLabelSel)?.textContent?.trim();
 			if (formLabel) return formLabel.replace(/[*：:]\s*$/, "");
 			return "";
 		}
@@ -4144,7 +4712,12 @@ async function elementsTool(config, args) {
 			elements: out,
 			dropdownOptions: Array.from(document.querySelectorAll(optionSelector)).map((el) => (el.textContent ?? "").trim()).filter(Boolean).slice(0, 50)
 		};
-	}, [max, DROPDOWN_OPTION_SELECTOR]);
+	}, [
+		max,
+		DROPDOWN_OPTION_SELECTOR,
+		GENERIC.formItemContainersStrict,
+		GENERIC.formLabelSimple
+	]);
 	return {
 		count: data.elements.length,
 		elements: data.elements,
@@ -4321,6 +4894,8 @@ async function enrichSemanticMiss(e, config, exec) {
 }
 async function clickTool(config, args, exec) {
 	const page = await getPage(config);
+	await assertExpectedUrl(page, args.expectUrl, "click");
+	const extWarning = drainExternalNavWarning(page);
 	let targetRes;
 	try {
 		targetRes = await resolveTargetLocator(page, args);
@@ -4423,6 +4998,7 @@ async function clickTool(config, args, exec) {
 			clicked: String(args.ref ?? args.selector ?? args.mark ?? args.what ?? (args.row ? `row: ${args.row}` : "target")),
 			effect,
 			...quiet ? { effectHint: "点击后未观察到任何 DOM/URL/网络变化,可能未生效(被遮挡/事件被吞/前置条件未满足);建议 browser_snapshot 核实或换目标" } : {},
+			...extWarning !== void 0 ? { warning: extWarning } : {},
 			...ambiguityFields(targetRes),
 			...targetRes.viaBridge === true ? { viaBridge: true } : {},
 			...await pageIdentity(page)
@@ -4430,6 +5006,7 @@ async function clickTool(config, args, exec) {
 	}
 	return {
 		clicked: String(args.ref ?? args.selector ?? args.mark ?? args.what ?? (args.row ? `row: ${args.row}` : "target")),
+		...extWarning !== void 0 ? { warning: extWarning } : {},
 		...ambiguityFields(targetRes),
 		...targetRes.viaBridge === true ? { viaBridge: true } : {},
 		...await pageIdentity(page)
@@ -4437,6 +5014,8 @@ async function clickTool(config, args, exec) {
 }
 async function typeTool(config, args) {
 	const page = await getPage(config);
+	await assertExpectedUrl(page, args.expectUrl, "type");
+	const extWarning = drainExternalNavWarning(page);
 	const targetRes = await resolveTargetLocator(page, args, { preferredRoles: [
 		"textbox",
 		"searchbox",
@@ -4451,27 +5030,54 @@ async function typeTool(config, args) {
 		const selector = String(args.ref ?? args.selector ?? "");
 		if (await fillEditorHelper(page, selector, text)) return {
 			typed: true,
-			editor: true,
+			typedVia: "editor",
 			selector,
 			...ambiguityFields(targetRes),
 			...await pageIdentity(page)
 		};
 	}
+	let typedVia = "clicked";
+	let focusedElement;
 	if (args.clear === true) {
 		if (isHuman) {
 			await target.fill("");
 			await humanType(page, text, { speed: config.humanizeSpeed });
 		} else await target.fill(text, { timeout: args.timeoutMs ?? config.timeoutMs });
+		typedVia = "fill";
 	} else {
 		const ambiguous = args.strict === true || (targetRes.matchedCount ?? 0) > 1;
+		let clickOk = false;
 		try {
 			await target.click({ timeout: Math.min(args.timeoutMs ?? config.timeoutMs, 5e3) });
+			clickOk = true;
 		} catch (e) {
 			if (ambiguous) throw new Error(`type 定位目标存在歧义(命中 ${targetRes.matchedCount ?? "?"} 个元素)且首个不可交互,已中止;请用 scope 限定或 browser_snapshot 取 ref 消歧;原始错误: ${e instanceof Error ? e.message : String(e)}`);
-			await target.click({
-				timeout: 2e3,
-				force: true
-			}).catch(() => {});
+			try {
+				await target.click({
+					timeout: 2e3,
+					force: true
+				});
+				clickOk = true;
+			} catch {}
+		}
+		if (!clickOk) {
+			const probe = await withTimeout(target.evaluate((el) => {
+				const ae = document.activeElement;
+				if (ae === null) return {
+					owns: false,
+					desc: null
+				};
+				return {
+					owns: ae === el || el.contains(ae),
+					desc: ae.outerHTML.slice(0, 200)
+				};
+			}), 2e3, "焦点归属探测").catch(() => ({
+				owns: false,
+				desc: null
+			}));
+			focusedElement = probe.desc ?? void 0;
+			if (!probe.owns) throw new Error(`type 目标不可点击且焦点不在目标上,已中止输入(避免盲打到错误输入框)。当前焦点: ${focusedElement ?? "(无法探测/无焦点)"};目标: ${String(args.ref ?? args.selector ?? args.what ?? "")}。建议 browser_snapshot 核实目标状态,或 browser_wait_for 等元素可交互`);
+			typedVia = "focus-kept";
 		}
 		if (isHuman) await humanType(page, text, { speed: config.humanizeSpeed });
 		else await page.keyboard.type(text, { delay: args.delayMs ?? 0 });
@@ -4479,6 +5085,9 @@ async function typeTool(config, args) {
 	if (args.submit === true) await page.keyboard.press("Enter");
 	return {
 		typed: true,
+		typedVia,
+		...focusedElement !== void 0 ? { focusedElement } : {},
+		...extWarning !== void 0 ? { warning: extWarning } : {},
 		selector: String(args.ref ?? args.selector),
 		submit: args.submit === true,
 		...ambiguityFields(targetRes),
@@ -4489,6 +5098,8 @@ async function pressTool(config, args) {
 	const page = await getPage(config);
 	const key = String(args.key);
 	let warning;
+	const extWarning = drainExternalNavWarning(page);
+	if (extWarning !== void 0) warning = warning !== void 0 ? `${warning};${extWarning}` : extWarning;
 	if (key === "Escape" && args.selector === void 0 && args.ref === void 0) {
 		const checkState = await page.evaluate(() => {
 			return {
@@ -4532,6 +5143,8 @@ async function pressTool(config, args) {
 */
 async function selectTool(config, args) {
 	const page = await getPage(config);
+	await assertExpectedUrl(page, args.expectUrl, "select");
+	const extWarning = drainExternalNavWarning(page);
 	const targetRes = await resolveTargetLocator(page, args, { preferredRoles: [
 		"combobox",
 		"select",
@@ -4554,6 +5167,7 @@ async function selectTool(config, args) {
 			clear: args.clear === true
 		})).selected,
 		selector: label,
+		...extWarning !== void 0 ? { warning: extWarning } : {},
 		...ambiguityFields(targetRes),
 		...await pageIdentity(page)
 	};
@@ -4561,8 +5175,8 @@ async function selectTool(config, args) {
 async function evalTool(config, args) {
 	const page = await getPage(config);
 	const { script, unwrapped } = unwrapDoubleEncodedScript(String(args.script ?? ""));
-	const wrapped = /[\n;]|^\s*return\b/.test(script) ? `(async () => {\n${script}\n})()` : `(${script})`;
-	const raw = await page.evaluate(wrapped);
+	const { code, mode } = buildEvalScript(script);
+	const raw = await page.evaluate(code);
 	let result;
 	try {
 		result = JSON.parse(JSON.stringify(raw ?? null));
@@ -4571,6 +5185,7 @@ async function evalTool(config, args) {
 	}
 	return {
 		result,
+		mode,
 		...unwrapped ? { scriptUnwrapped: true } : {}
 	};
 }
@@ -4771,6 +5386,41 @@ async function formFillTool(config, args) {
 		...submitted !== void 0 ? { submitted } : {}
 	};
 }
+/**
+* browser_drag:在页面里把源元素拖到目标元素上。
+* 源/目标各自走统一定位管线(selector / ref / what+scope / mark 四选一前缀),
+* 支持 HTML5 原生拖放(dragTo)与鼠标拖动类控件(物理鼠标序列降级);
+* 跨 Frame 拖拽自动绕过 dragTo 的同 Frame 限制。
+*/
+async function dragTool(config, args) {
+	const pickSide = (side) => {
+		const remapped = {};
+		if (typeof args[side] === "string" && args[side] !== "") remapped.selector = args[side];
+		if (typeof args[`${side}Ref`] === "string" && args[`${side}Ref`] !== "") remapped.ref = args[`${side}Ref`];
+		if (typeof args[`${side}What`] === "string" && args[`${side}What`].trim() !== "") remapped.what = args[`${side}What`];
+		if (typeof args[`${side}Mark`] === "number") remapped.mark = args[`${side}Mark`];
+		if (typeof args[`${side}Scope`] === "string" && args[`${side}Scope`] !== "") remapped.scope = args[`${side}Scope`];
+		if (Object.keys(remapped).filter((k) => k !== "scope").length === 0) throw new Error(`drag 需要 ${side} 定位: ${side}(CSS 选择器)/${side}Ref(aria ref)/${side}What(意图语义)/${side}Mark(SoM 标徽)至少给一个`);
+		return remapped;
+	};
+	const describeSide = (remapped) => remapped.what !== void 0 ? `what:"${remapped.what}"` : remapped.ref !== void 0 ? `ref:${remapped.ref}` : remapped.mark !== void 0 ? `mark:${remapped.mark}` : String(remapped.selector);
+	const srcArgs = pickSide("source");
+	const tgtArgs = pickSide("target");
+	const page = await getPage(config);
+	const srcRes = await resolveTargetLocator(page, srcArgs);
+	const tgtRes = await resolveTargetLocator(page, tgtArgs);
+	const crossFrame = srcRes.container !== tgtRes.container;
+	return {
+		dragged: true,
+		via: await dragAndDropLocators(page, srcRes.locator, tgtRes.locator, {
+			timeoutMs: typeof args.timeoutMs === "number" ? args.timeoutMs : void 0,
+			preferMouse: crossFrame
+		}),
+		source: describeSide(srcArgs),
+		target: describeSide(tgtArgs),
+		...await pageIdentity(page)
+	};
+}
 //#endregion
 //#region lib/types/browser/tools/testing.js
 async function waitTool(config, args) {
@@ -5492,56 +6142,49 @@ function previewHighlight(page, selector, label) {
 	}).catch(() => {});
 }
 /**
-* 常见认证/登录相关的 URL 特征正则，用于防止跳板页提前误判。
-*/
-const AUTH_URL_PATTERN = /login|signin|sign-in|oauth|passport|sso|cas|challenge|captcha|verify|auth\b/i;
-/**
 * 等待人工登录底层执行(独立导出供测试注入 fake page)。
-* 协同机制:
-* 1. 挂起等待期间置入 instruction 至实时画面面板(setPauseInstruction),结束后统一清理;
-* 2. 存活标签感知:感知 context 内所有存活页面,原标签关闭时自动迁移至存活页,新标签出现时通知外层注册;
-* 3. 稳态判定:
-*    - 显式 successSelector / successUrl 优先;
-*    - 缺省时,检测 URL 离开登录页(非 AUTH_URL_PATTERN)、登录密码框消除、或 SPA 内容签名稳态变化,防范跳板页误判与 SPA 弹窗漏判。
+* 完成判定(按优先级):
+* 1. **用户主动告知(主通道)**:pendingLoginWait 单槽状态机,面板常驻登录等待卡
+*    「我已完成登录」按钮 → resolveLoginWait(id),500ms 确认节拍;
+* 2. 显式确定性条件:successSelector(任一存活标签可见)/ successUrl(URL 正则,
+*    任一存活标签命中),pollIntervalMs 节拍多标签扫描,命中即把目标页切为命中页;
+* 3. 超时返回 loggedIn:false(附 waitedMs 与 detail,不抛错)。
+*
+* 登录状态不再自动猜测:URL 认证特征/密码框消除/SPA 签名启发式对「登录表单
+* 隐藏不卸载(keep-alive/微前端)」「登录后 URL 仍含 auth 子串」的 SPA 会永久
+* 漏判(用户已登录仍空转到超时),已整体移除——登录完成由用户说了算。
+* 保留:存活标签感知(原标签关闭自愈迁移、新标签经 onNewPageDetected 注册)。
 */
 async function runWaitForLoginOnPage(initialPage, args, onNewPageDetected) {
-	typeof args.instruction === "string" && args.instruction.trim() && args.instruction.trim();
+	const instruction = typeof args.instruction === "string" && args.instruction.trim() ? args.instruction.trim() : "请在浏览器窗口中完成登录";
 	const timeoutMs = Math.min(Math.max(Number(args.timeoutMs ?? 12e4) || 12e4, 1e3), 6e5);
 	const pollIntervalMs = Math.min(Math.max(Number(args.pollIntervalMs ?? 2e3) || 2e3, 100), 5e3);
+	const successSelector = typeof args.successSelector === "string" ? args.successSelector : "";
+	const successUrl = typeof args.successUrl === "string" ? args.successUrl : "";
 	let currentPage = initialPage;
-	let startUrl = "";
-	try {
-		startUrl = initialPage.url();
-	} catch {}
-	const checkHasPassword = async (p) => {
-		try {
-			return await p.evaluate(() => !!document.querySelector("input[type=\"password\"]"));
-		} catch {
-			return false;
-		}
-	};
-	const getPageSig = async (p) => {
-		try {
-			return await p.evaluate(() => {
-				const body = document.body;
-				return `${location.href}|${body ? body.innerText.length : 0}|${document.querySelectorAll("input,button,a").length}`;
-			});
-		} catch {
-			try {
-				return p.url();
-			} catch {
-				return "";
-			}
-		}
-	};
-	const startHasPassword = await checkHasPassword(initialPage);
-	const startSig = args.successSelector || args.successUrl ? "" : await getPageSig(initialPage);
+	const id = `login-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+	setPendingLoginWait({
+		id,
+		instruction,
+		startedAt: Date.now()
+	});
 	const startedAt = Date.now();
 	let loggedIn = false;
-	let detail = `等待登录超时(${timeoutMs}ms)`;
+	let detail = `等待登录超时(${timeoutMs}ms),用户未在面板确认登录完成`;
+	let lastExplicitCheck = 0;
 	try {
 		const deadline = startedAt + timeoutMs;
 		while (Date.now() < deadline) {
+			const pending = getPendingLoginWait();
+			if (pending !== null && pending.id !== id) {
+				detail = "登录等待已被新的等待请求取代";
+				break;
+			}
+			if (pending !== null && pending.done) {
+				loggedIn = true;
+				detail = "用户已在面板确认完成登录";
+				break;
+			}
 			let candidatePages = [];
 			try {
 				const context = typeof currentPage.context === "function" ? currentPage.context() : null;
@@ -5566,76 +6209,36 @@ async function runWaitForLoginOnPage(initialPage, args, onNewPageDetected) {
 					isCurrentClosed = false;
 				}
 			}
-			try {
-				if (args.successSelector) {
-					const targets = candidatePages.length > 0 ? candidatePages : isCurrentClosed ? [] : [currentPage];
-					for (const p of targets) try {
-						if (await p.locator(String(args.successSelector)).first().isVisible()) {
-							loggedIn = true;
-							currentPage = p;
-							detail = `命中 successSelector: ${args.successSelector}`;
-							break;
-						}
-					} catch {}
-				} else if (args.successUrl) {
-					const re = new RegExp(String(args.successUrl));
-					const targets = candidatePages.length > 0 ? candidatePages : isCurrentClosed ? [] : [currentPage];
-					for (const p of targets) try {
-						const u = p.url();
-						if (re.test(u)) {
+			if ((successSelector !== "" || successUrl !== "") && Date.now() - lastExplicitCheck >= pollIntervalMs) {
+				lastExplicitCheck = Date.now();
+				const targets = candidatePages.length > 0 ? candidatePages : isCurrentClosed ? [] : [currentPage];
+				for (const p of targets) try {
+					if (successSelector !== "") {
+						if (await p.locator(successSelector).first().isVisible()) {
 							loggedIn = true;
 							currentPage = p;
-							detail = `命中 successUrl: ${args.successUrl}`;
+							detail = `命中 successSelector: ${successSelector}`;
 							break;
 						}
-					} catch {}
-				} else {
-					const target = !isCurrentClosed ? currentPage : candidatePages[0];
-					if (target) {
-						let curUrl = "";
-						try {
-							curUrl = target.url();
-						} catch {}
-						if (curUrl && curUrl !== "about:blank") {
-							if (curUrl !== startUrl) {
-								if (!AUTH_URL_PATTERN.test(curUrl)) {
-									loggedIn = true;
-									currentPage = target;
-									detail = `URL 离开登录页跳转至 ${curUrl}`;
-								} else {
-									const hasPwd = await checkHasPassword(target);
-									if (startHasPassword && !hasPwd) {
-										loggedIn = true;
-										currentPage = target;
-										detail = `登录密码输入框已消除，页面跳转至 ${curUrl}`;
-									}
-								}
-							} else {
-								const hasPwd = await checkHasPassword(target);
-								if (startHasPassword && !hasPwd) {
-									loggedIn = true;
-									currentPage = target;
-									detail = "登录密码输入框已消除(SPA 登录完成)";
-								} else if (await getPageSig(target) !== startSig && (!startHasPassword || !hasPwd)) {
-									loggedIn = true;
-									currentPage = target;
-									detail = "页面内容签名变更(SPA 登录完成)";
-								}
-							}
-						}
+					} else if (new RegExp(successUrl).test(p.url())) {
+						loggedIn = true;
+						currentPage = p;
+						detail = `命中 successUrl: ${successUrl}`;
+						break;
 					}
-				}
-			} catch (e) {
-				detail = `检查登录状态出错: ${e instanceof Error ? e.message : String(e)}`;
+				} catch {}
 			}
 			if (loggedIn) break;
 			try {
-				await currentPage.waitForTimeout(pollIntervalMs);
+				await currentPage.waitForTimeout(500);
 			} catch {
-				await sleep$1(pollIntervalMs);
+				await sleep$1(500);
 			}
 		}
-	} finally {}
+	} finally {
+		const pending = getPendingLoginWait();
+		if (pending !== null && pending.id === id) clearPendingLoginWait();
+	}
 	return {
 		loggedIn,
 		waitedMs: Date.now() - startedAt,
@@ -5645,11 +6248,15 @@ async function runWaitForLoginOnPage(initialPage, args, onNewPageDetected) {
 }
 /**
 * 等待人工登录完成(配合 headless:false 使用):agent 打开登录页后调用本工具,
-* 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。支持 instruction 提示语
-* 与右下角实时画面面板联动显示横幅,支持多标签感知与 SPA 签名自适应判定。
-* 超时返回 loggedIn:false(附 waitedMs 与 detail,不抛错)。
+* 用户在浏览器窗口完成登录(输入/扫码/双因素)后,在实时画面面板的**常驻登录
+* 等待卡**上点「我已完成登录」主动告知,工具立即返回(500ms 确认节拍)。
+* 亦支持显式确定性条件 successSelector/successUrl(多标签扫描自动判定)。
+* 不做任何登录状态启发式猜测。超时返回 loggedIn:false(附 waitedMs 与
+* detail,不抛错)。无面板环境(MCP 独立模式)必须显式给条件,否则 fail-fast。
 */
 async function waitForLoginTool(config, args) {
+	const hasExplicit = typeof args.successSelector === "string" && args.successSelector !== "" || typeof args.successUrl === "string" && args.successUrl !== "";
+	if (!isInteractivePanelPresent() && !hasExplicit) throw new Error("等待人工登录失败: 当前环境无交互面板,用户无法点「我已完成登录」确认。请显式提供 successSelector(登录成功后出现的元素,如 \"#avatar\")或 successUrl(登录成功后 URL 应匹配的正则)后重试");
 	const page = await getPage(config);
 	const state = stateOf();
 	const result = await runWaitForLoginOnPage(page, args, (newPage) => {
@@ -7624,7 +8231,11 @@ function getInteractionTools(config, timeout, stepImpls) {
 						type: "boolean",
 						description: "多命中即抛错(对齐 Playwright strict),要求定位唯一;默认 false 操作第 1 个并在返回中提示命中数。"
 					},
-					timeoutMs: { type: "integer" }
+					timeoutMs: { type: "integer" },
+					expectUrl: {
+						type: "string",
+						description: "页面预期校验(opt-in):正则(非法时按子串);定位前当前 URL 不匹配直接报错,把「页面被切换/回退」从诡异失败变为一句话可诊断的错误。"
+					}
 				},
 				additionalProperties: false
 			},
@@ -7652,6 +8263,10 @@ function getInteractionTools(config, timeout, stepImpls) {
 					viaBridge: {
 						type: "boolean",
 						description: "what 未命中时经页面 __DSH_BRIDGE__(vite-plugin-dsh-bridge)兜底命中。"
+					},
+					warning: {
+						type: "string",
+						description: "执行过程中检测到的环境异常提示(如非工具触发的页面导航)。"
 					}
 				},
 				required: [
@@ -7666,7 +8281,7 @@ function getInteractionTools(config, timeout, stepImpls) {
 		}),
 		definePlainTool({
 			name: "browser_type",
-			description: "向输入框输入文本:selector(CSS)、ref 或 what(意图描述,如 '用户名'/'搜索')三选一定位目标(同时传多个会报参数错误;容器内定位用 what + scope)。clear=true 时先清空再输入(推荐用于表单);submit=true 时输入后按回车;editor=true 时适配 Monaco/CodeMirror/富文本编辑器。",
+			description: "向输入框输入文本:selector(CSS)、ref 或 what(意图描述,如 '用户名'/'搜索')三选一定位目标(同时传多个会报参数错误;容器内定位用 what + scope)。clear=true 时先清空再输入(推荐用于表单);submit=true 时输入后按回车;editor=true 时适配 Monaco/CodeMirror/富文本编辑器。定位与点击均失败时做焦点归属校验:焦点不在目标内(含子元素)则中止输入并附当前焦点线索,不会盲打到错误输入框;返回 typedVia 标明实际输入通道。expectUrl 传入时先校验当前页面 URL,不符直接报错(防页面被切换后打错位置)。",
 			parameters: {
 				type: "object",
 				properties: {
@@ -7702,7 +8317,11 @@ function getInteractionTools(config, timeout, stepImpls) {
 						description: "多命中即抛错(对齐 Playwright strict);多命中或 strict 时不再 force 降级点击,遮罩拦截会直接暴露。"
 					},
 					delayMs: { type: "integer" },
-					timeoutMs: { type: "integer" }
+					timeoutMs: { type: "integer" },
+					expectUrl: {
+						type: "string",
+						description: "页面预期校验(opt-in):正则(非法时按子串);定位前当前 URL 不匹配直接报错,把「页面被切换/回退」从诡异失败变为一句话可诊断的错误。"
+					}
 				},
 				required: ["text"],
 				additionalProperties: false
@@ -7712,6 +8331,20 @@ function getInteractionTools(config, timeout, stepImpls) {
 				additionalProperties: false,
 				properties: {
 					typed: { type: "boolean" },
+					typedVia: {
+						type: "string",
+						enum: [
+							"fill",
+							"clicked",
+							"focus-kept",
+							"editor"
+						],
+						description: "实际输入通道:fill=clear 清空重填;clicked=点击获得焦点;focus-kept=点击超时但焦点已在目标内续打;editor=编辑器适配。"
+					},
+					focusedElement: {
+						type: "string",
+						description: "focus-kept 通道下当前焦点元素 outerHTML 片段(调试线索)。"
+					},
 					selector: { type: "string" },
 					submit: { type: "boolean" },
 					url: { type: "string" },
@@ -7727,6 +8360,10 @@ function getInteractionTools(config, timeout, stepImpls) {
 					hint: {
 						type: "string",
 						description: "matchedCount>1 时的消歧指引。"
+					},
+					warning: {
+						type: "string",
+						description: "执行过程中检测到的环境异常提示(如非工具触发的页面导航)。"
 					}
 				},
 				required: [
@@ -7841,7 +8478,11 @@ function getInteractionTools(config, timeout, stepImpls) {
 						type: "boolean",
 						description: "多命中即抛错(对齐 Playwright strict)。"
 					},
-					timeoutMs: { type: "integer" }
+					timeoutMs: { type: "integer" },
+					expectUrl: {
+						type: "string",
+						description: "页面预期校验(opt-in):正则(非法时按子串);定位前当前 URL 不匹配直接报错,把「页面被切换/回退」从诡异失败变为一句话可诊断的错误。"
+					}
 				},
 				required: ["option"],
 				additionalProperties: false
@@ -7865,6 +8506,10 @@ function getInteractionTools(config, timeout, stepImpls) {
 					hint: {
 						type: "string",
 						description: "matchedCount>1 时的消歧指引。"
+					},
+					warning: {
+						type: "string",
+						description: "执行过程中检测到的环境异常提示(如非工具触发的页面导航)。"
 					}
 				},
 				required: [
@@ -7878,9 +8523,95 @@ function getInteractionTools(config, timeout, stepImpls) {
 			timeoutMs: timeout(),
 			execute: (args) => selectTool(config, args)
 		}),
+		definePlainTool({
+			name: "browser_drag",
+			description: "把源元素拖到目标元素上(拖拽/拖放):源与目标各自定位——source(CSS)/sourceRef(aria ref)/sourceWhat(意图语义,+sourceScope)/sourceMark(SoM 标徽)四选一,target/targetRef/targetWhat(+targetScope)/targetMark 同理。优先 Playwright dragTo(覆盖 HTML5 原生拖放),失败或跨 Frame 时自动降级为物理鼠标序列(覆盖看板卡片、滑块等鼠标拖动类控件),返回 via 标明实际通道。注意:dragged=true 表示拖拽序列已执行,不保证业务侧生效(drop 区拒绝、控件无响应仍为 true),需要验证请配合 browser_assert。源/目标不可见或零命中时抛错并附诊断。",
+			parameters: {
+				type: "object",
+				properties: {
+					source: {
+						type: "string",
+						description: "源元素 CSS 选择器;与 sourceRef/sourceWhat/sourceMark 互斥。"
+					},
+					sourceRef: {
+						type: "string",
+						description: "源元素 aria 快照 ref(如 'e3');与 source/sourceWhat/sourceMark 互斥。"
+					},
+					sourceWhat: {
+						type: "string",
+						description: "源元素意图描述(如 '任务卡片 A'):页内打分语义定位;与 source/sourceRef/sourceMark 互斥;配合 sourceScope。"
+					},
+					sourceMark: {
+						type: "integer",
+						description: "源元素 SoM 标徽编号(browser_screenshot { som: true });与 source/sourceRef/sourceWhat 互斥。"
+					},
+					sourceScope: {
+						type: "string",
+						description: "配合 sourceWhat 限定扫描范围的容器选择器。"
+					},
+					target: {
+						type: "string",
+						description: "目标元素 CSS 选择器;与 targetRef/targetWhat/targetMark 互斥。"
+					},
+					targetRef: {
+						type: "string",
+						description: "目标元素 aria 快照 ref;与 target/targetWhat/targetMark 互斥。"
+					},
+					targetWhat: {
+						type: "string",
+						description: "目标元素意图描述(如 '待办列'):页内打分语义定位;与 target/targetRef/targetMark 互斥;配合 targetScope。"
+					},
+					targetMark: {
+						type: "integer",
+						description: "目标元素 SoM 标徽编号;与 target/targetRef/targetWhat 互斥。"
+					},
+					targetScope: {
+						type: "string",
+						description: "配合 targetWhat 限定扫描范围的容器选择器。"
+					},
+					timeoutMs: { type: "integer" }
+				},
+				additionalProperties: false
+			},
+			outputSchema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					dragged: {
+						type: "boolean",
+						description: "拖拽序列已执行(true 不保证业务侧生效,drop 被拒绝也为 true)。"
+					},
+					via: {
+						type: "string",
+						description: "实际执行通道:'dragTo'(HTML5/组件库)或 'mouse'(物理鼠标,含跨 Frame 与降级)。"
+					},
+					source: {
+						type: "string",
+						description: "实际使用的源定位描述(what:/ref:/mark:/selector)。"
+					},
+					target: {
+						type: "string",
+						description: "实际使用的目标定位描述。"
+					},
+					url: { type: "string" },
+					title: { type: "string" }
+				},
+				required: [
+					"dragged",
+					"via",
+					"source",
+					"target",
+					"url",
+					"title"
+				]
+			},
+			render: (_args, value) => `Dragged ${value.source} → ${value.target} (via ${value.via})`,
+			timeoutMs: timeout(),
+			execute: (args) => dragTool(config, args)
+		}),
 		definePlainTool({
 			name: "browser_eval",
-			description: "在页面上下文执行一段 JavaScript。表达式直接求值(如 'document.title');含换行/分号的语句会被包进 async IIFE,可用 return 返回。结果必须是可 JSON 序列化的值。",
+			description: "在页面上下文执行一段 JavaScript。表达式(含多行对象字面量/箭头函数 IIFE/顶层 await)直接返回值;语句脚本自动 return 最后一个顶层表达式的值,也可显式 return。结果必须是可 JSON 序列化的值,返回 mode 标明实际执行形态。",
 			parameters: {
 				type: "object",
 				properties: { script: {
@@ -7895,6 +8626,15 @@ function getInteractionTools(config, timeout, stepImpls) {
 				additionalProperties: false,
 				properties: {
 					result: {},
+					mode: {
+						type: "string",
+						enum: [
+							"expression",
+							"statements-auto-return",
+							"statements"
+						],
+						description: "实际执行形态:expression=表达式直取值(支持顶层 await 与多行对象字面量);statements-auto-return=语句体自动 return 最后一个顶层表达式;statements=语句体(显式 return 或纯副作用,无返回值时 result 为 null)。"
+					},
 					scriptUnwrapped: {
 						type: "boolean",
 						description: "入参 script 疑似被 JSON 双重序列化(以引号包裹且含 \\n 字面量),已自动解码一层。"
@@ -8695,13 +9435,13 @@ function getCollaborationTools(config, timeout, stepImpls) {
 	return [
 		definePlainTool({
 			name: "browser_wait_for_login",
-			description: "等待人工登录完成。agent 在登录页调用本工具后,提示用户在浏览器窗口中完成登录(有头模式 headless:false 时用户可直接操作;配 userDataDir 登录态会持久化)。支持 instruction 提示语(将显示在右下角实时画面面板);成功条件:优先取 successSelector(登录后出现的元素,如 '#avatar')或 successUrl(登录后 URL 正则);两者未指定时,结合 URL 变化、登录特征消除(密码框等)与页面签名稳态综合判定。轮询间隔 2 秒,超时返回 loggedIn:false(附 waitedMs 与 detail)。",
+			description: "等待人工登录完成。agent 在登录页调用本工具后,用户在浏览器窗口完成登录(有头模式 headless:false;配 userDataDir 登录态会持久化),然后在实时画面面板的常驻登录等待卡上点「我已完成登录」主动告知,工具立即返回(500ms 确认节拍)——不猜测登录状态,完成与否由用户说了算。亦可显式给 successSelector(登录后出现的元素,如 '#avatar')或 successUrl(登录后 URL 正则)作为确定性自动条件(多标签扫描,轮询间隔 2 秒)。超时返回 loggedIn:false(附 waitedMs 与 detail,不抛错)。注意:无面板环境(独立 MCP 模式)用户无法点按钮确认,必须显式给 successSelector 或 successUrl,否则调用直接报错。",
 			parameters: {
 				type: "object",
 				properties: {
 					instruction: {
 						type: "string",
-						description: "可选:给用户看的提示说明(默认「请在浏览器窗口中完成登录」)。"
+						description: "可选:给用户看的提示说明,展示在面板登录等待卡上(默认「请在浏览器窗口中完成登录」)。"
 					},
 					timeoutMs: {
 						type: "integer",
@@ -8709,11 +9449,11 @@ function getCollaborationTools(config, timeout, stepImpls) {
 					},
 					successSelector: {
 						type: "string",
-						description: "登录成功后应出现的 CSS 选择器。"
+						description: "可选:登录成功后应出现的 CSS 选择器(确定性自动条件,任一标签可见即完成)。"
 					},
 					successUrl: {
 						type: "string",
-						description: "登录成功后 URL 应匹配的正则。"
+						description: "可选:登录成功后 URL 应匹配的正则(确定性自动条件)。"
 					}
 				},
 				additionalProperties: false
@@ -9373,14 +10113,16 @@ function registerTools(ctx, config) {
 		"browser_upload",
 		"browser_form",
 		"browser_form_fill",
-		"browser_eval"
+		"browser_eval",
+		"browser_drag"
 	]);
 	/** 操作预告:这些工具执行前把目标元素在实时画面上高亮(异步不阻塞)。 */
 	const PREVIEW_TOOLS = /* @__PURE__ */ new Set([
 		"browser_click",
 		"browser_type",
 		"browser_select",
-		"browser_press"
+		"browser_press",
+		"browser_drag"
 	]);
 	/**
 	* auto 审批闸(confirmMode:"auto" 硬约束):live 调用在 register 包装层拦,
@@ -9435,8 +10177,8 @@ function registerTools(ctx, config) {
 			sessionTracer.startStep(currentProfile, def.name, args, activePage());
 			if (PREVIEW_TOOLS.has(def.name)) {
 				const page = activePage();
-				const selector = typeof args?.selector === "string" && args.selector ? args.selector : typeof args?.ref === "string" && args.ref && page !== null ? pageRef(page, args.ref)?.selector ?? "" : "";
-				if (selector !== "") previewHighlight(page, selector, `${def.name.replace(/^browser_/, "")} ${args?.ref ? `[${args.ref}] ` : ""}${args?.key ?? args?.value ?? args?.text ?? ""}`.trim());
+				const selector = typeof args?.selector === "string" && args.selector ? args.selector : def.name === "browser_drag" && typeof args?.source === "string" && args.source ? args.source : typeof args?.ref === "string" && args.ref && page !== null ? pageRef(page, args.ref)?.selector ?? "" : "";
+				if (selector !== "") previewHighlight(page, selector, `${def.name.replace(/^browser_/, "")} ${args?.ref ? `[${args.ref}] ` : ""}${args?.key ?? args?.value ?? args?.text ?? args?.source ?? ""}`.trim());
 			}
 			try {
 				const result = await original(args, exec);
@@ -9481,6 +10223,7 @@ function registerTools(ctx, config) {
 		browser_type: (a) => typeTool(config, a),
 		browser_press: (a) => pressTool(config, a),
 		browser_select: (a) => selectTool(config, a),
+		browser_drag: (a) => dragTool(config, a),
 		browser_eval: (a) => evalTool(config, a),
 		browser_screenshot: (a) => screenshotTool(config, a),
 		browser_wait: (a) => waitTool(config, a),