dsh-browser-view 0.3.4 → 0.4.1

package/lib/index.js

@@ -191,6 +191,350 @@ function genericCard(kind, title, rawInput) {
 	};
 }
 //#endregion
+//#region lib/types/browser/walker.js
+/** 页内 walker 核心(自包含;勿引用模块级变量、勿导入任何模块)。 */
+function __walkerCore() {
+	const INTERACTIVE = /* @__PURE__ */ new Set([
+		"link",
+		"button",
+		"textbox",
+		"checkbox",
+		"radio",
+		"combobox",
+		"listbox",
+		"searchbox",
+		"slider",
+		"spinbutton",
+		"switch",
+		"tab",
+		"menuitem",
+		"option",
+		"treeitem"
+	]);
+	const STRUCTURAL = /* @__PURE__ */ new Set([
+		"navigation",
+		"main",
+		"banner",
+		"contentinfo",
+		"form",
+		"search",
+		"complementary",
+		"region",
+		"dialog",
+		"alert",
+		"table",
+		"list",
+		"heading",
+		"toolbar",
+		"menu",
+		"menubar",
+		"tablist",
+		"tree",
+		"grid"
+	]);
+	const SKIP_TAGS = /* @__PURE__ */ new Set([
+		"script",
+		"style",
+		"template",
+		"noscript",
+		"svg",
+		"path",
+		"link",
+		"meta",
+		"br"
+	]);
+	function safeEscape(str) {
+		return typeof CSS !== "undefined" && typeof CSS.escape === "function" ? CSS.escape(str) : str;
+	}
+	function matches(el, sel) {
+		try {
+			return typeof el.matches === "function" && el.matches(sel);
+		} catch {
+			return false;
+		}
+	}
+	function closest(el, sel) {
+		try {
+			return typeof el.closest === "function" ? el.closest(sel) : null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* 运行时组件元数据与源码坐标反射:
+	* 支持 @xiaou66/vite-plugin-vue-mcp-next 与 vite-plugin-vue-inspector 的 data-v-inspector,
+	* 以及 Vue 3 挂载在 DOM 上的 __vueParentComponent 实例。
+	*/
+	function resolveVueAndInspector(el) {
+		let inspector = el.getAttribute("data-v-inspector") || el.getAttribute("data-v-inspect") || el.getAttribute("data-inspector-file") || "";
+		let cur = el.parentElement;
+		let depth = 0;
+		while (!inspector && cur && depth < 2) {
+			inspector = cur.getAttribute("data-v-inspector") || cur.getAttribute("data-v-inspect") || cur.getAttribute("data-inspector-file") || "";
+			cur = cur.parentElement;
+			depth += 1;
+		}
+		let componentName = "";
+		let props = {};
+		const vcomp = el.__vueParentComponent;
+		if (vcomp && typeof vcomp === "object") {
+			componentName = vcomp.type?.name || vcomp.type?.__name || "";
+			props = vcomp.props || {};
+		}
+		if (!componentName && el.parentElement) {
+			const pvcomp = el.parentElement.__vueParentComponent;
+			if (pvcomp && typeof pvcomp === "object") {
+				componentName = pvcomp.type?.name || pvcomp.type?.__name || "";
+				if (Object.keys(props).length === 0) props = pvcomp.props || {};
+			}
+		}
+		return {
+			componentName,
+			inspector,
+			props
+		};
+	}
+	/**
+	* 可扩展组件库适配体系:
+	* 抹平 Ant Design Vue、Element Plus、Naive UI、Arco Design 等组件库的外层包装与非原生标签。
+	*/
+	function resolveComponentSemantics(el) {
+		const { componentName, inspector, props } = resolveVueAndInspector(el);
+		const className = typeof el.className === "string" ? el.className : "";
+		if (className.includes("ant-") || /^A[A-Z]/.test(componentName) || !!closest(el, ".ant-form-item")) {
+			const formLabel = closest(el, ".ant-form-item")?.querySelector(".ant-form-item-label")?.textContent?.trim() || "";
+			let role = "";
+			if (matches(el, ".ant-select, .ant-cascader, .ant-tree-select") || componentName === "ASelect" || componentName === "ACascader") role = "combobox";
+			else if (matches(el, ".ant-picker") || componentName === "ADatePicker" || componentName === "ATimePicker") role = "textbox";
+			else if (matches(el, ".ant-input-number") || componentName === "AInputNumber") role = "spinbutton";
+			else if (matches(el, ".ant-switch") || componentName === "ASwitch") role = "switch";
+			else if (matches(el, ".ant-btn") || componentName === "AButton") role = "button";
+			const ph = String(props.placeholder || el.querySelector(".ant-select-selection-placeholder")?.textContent?.trim() || el.getAttribute("placeholder") || "");
+			return {
+				library: "ant-design-vue",
+				component: componentName || (role === "combobox" ? "ASelect" : ""),
+				sourceFile: inspector,
+				role,
+				formLabel,
+				placeholder: ph
+			};
+		}
+		if (className.includes("el-") || /^El[A-Z]/.test(componentName) || !!closest(el, ".el-form-item")) {
+			const formLabel = closest(el, ".el-form-item")?.querySelector(".el-form-item__label")?.textContent?.trim() || "";
+			let role = "";
+			if (matches(el, ".el-select, .el-cascader") || componentName === "ElSelect" || componentName === "ElCascader") role = "combobox";
+			else if (matches(el, ".el-date-editor") || componentName === "ElDatePicker") role = "textbox";
+			else if (matches(el, ".el-input-number") || componentName === "ElInputNumber") role = "spinbutton";
+			else if (matches(el, ".el-switch") || componentName === "ElSwitch") role = "switch";
+			else if (matches(el, ".el-button") || componentName === "ElButton") role = "button";
+			const ph = String(props.placeholder || el.querySelector(".el-select__placeholder")?.textContent?.trim() || el.getAttribute("placeholder") || "");
+			return {
+				library: "element-plus",
+				component: componentName || (role === "combobox" ? "ElSelect" : ""),
+				sourceFile: inspector,
+				role,
+				formLabel,
+				placeholder: ph
+			};
+		}
+		if (className.includes("n-") || /^N[A-Z]/.test(componentName) || !!closest(el, ".n-form-item")) {
+			const formLabel = closest(el, ".n-form-item")?.querySelector(".n-form-item-label")?.textContent?.trim() || "";
+			let role = "";
+			if (matches(el, ".n-select") || componentName === "NSelect") role = "combobox";
+			else if (matches(el, ".n-date-picker") || componentName === "NDatePicker") role = "textbox";
+			else if (matches(el, ".n-switch") || componentName === "NSwitch") role = "switch";
+			else if (matches(el, ".n-button") || componentName === "NButton") role = "button";
+			const ph = String(props.placeholder || el.getAttribute("placeholder") || "");
+			return {
+				library: "naive-ui",
+				component: componentName || "",
+				sourceFile: inspector,
+				role,
+				formLabel,
+				placeholder: ph
+			};
+		}
+		if (className.includes("arco-") || !!closest(el, ".arco-form-item")) {
+			const formLabel = closest(el, ".arco-form-item")?.querySelector(".arco-form-item-label")?.textContent?.trim() || "";
+			let role = "";
+			if (matches(el, ".arco-select") || componentName.includes("Select")) role = "combobox";
+			else if (matches(el, ".arco-picker")) role = "textbox";
+			else if (matches(el, ".arco-btn")) role = "button";
+			const ph = String(props.placeholder || el.getAttribute("placeholder") || "");
+			return {
+				library: "arco-design",
+				component: componentName || "",
+				sourceFile: inspector,
+				role,
+				formLabel,
+				placeholder: ph
+			};
+		}
+		if (componentName || inspector) return {
+			library: "custom-vue",
+			component: componentName,
+			sourceFile: inspector,
+			role: "",
+			formLabel: "",
+			placeholder: String(props.placeholder || "")
+		};
+		return {
+			library: "",
+			component: "",
+			sourceFile: "",
+			role: "",
+			formLabel: "",
+			placeholder: ""
+		};
+	}
+	function roleOf(el) {
+		const explicit = el.getAttribute("role");
+		if (explicit) return explicit.trim().split(/\s+/)[0] ?? "";
+		switch (el.tagName.toLowerCase()) {
+			case "a": return el.hasAttribute("href") ? "link" : "";
+			case "button": return "button";
+			case "input": {
+				const t = (el.getAttribute("type") ?? "text").toLowerCase();
+				if (t === "checkbox") return "checkbox";
+				if (t === "radio") return "radio";
+				if (t === "range") return "slider";
+				if (t === "number") return "spinbutton";
+				if (t === "search") return "searchbox";
+				if ([
+					"button",
+					"submit",
+					"reset",
+					"image"
+				].includes(t)) return "button";
+				if (["hidden", "file"].includes(t)) return "";
+				return "textbox";
+			}
+			case "textarea": return "textbox";
+			case "select": return "combobox";
+			case "nav": return "navigation";
+			case "main": return "main";
+			case "header": return "banner";
+			case "footer": return "contentinfo";
+			case "form": return "form";
+			case "h1":
+			case "h2":
+			case "h3":
+			case "h4":
+			case "h5":
+			case "h6": return "heading";
+			case "ul":
+			case "ol": return "list";
+			case "li": return "listitem";
+			case "table": return "table";
+			case "dialog": return "dialog";
+			case "summary": return "button";
+			default: return resolveComponentSemantics(el).role;
+		}
+	}
+	function nameOf(el, role) {
+		const sem = resolveComponentSemantics(el);
+		const aria = el.getAttribute("aria-label");
+		if (aria && aria.trim()) return aria.trim().slice(0, 60);
+		const labelledby = el.getAttribute("aria-labelledby");
+		if (labelledby) {
+			const t = labelledby.split(/\s+/).map((id) => document.getElementById(id)?.textContent?.trim() ?? "").join(" ").trim();
+			if (t) return t.slice(0, 60);
+		}
+		if (el.id) {
+			const t = document.querySelector(`label[for="${safeEscape(el.id)}"]`)?.textContent?.trim();
+			if (t) return t.slice(0, 60);
+		}
+		if (sem.formLabel) return sem.formLabel.slice(0, 60);
+		if ([
+			"textbox",
+			"searchbox",
+			"combobox",
+			"spinbutton"
+		].includes(role)) {
+			const ph = el.getAttribute("placeholder") || sem.placeholder;
+			if (ph && ph.trim()) return ph.trim().slice(0, 60);
+		}
+		const text = (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ");
+		if (text) return text.slice(0, 60);
+		const title = el.getAttribute("title");
+		if (title && title.trim()) return title.trim().slice(0, 60);
+		return "";
+	}
+	/** 稳定 CSS 路径:#id → [data-testid] → nth-of-type 链(≤6 层)。 */
+	function cssPath(el) {
+		if (el.id) return `#${safeEscape(el.id)}`;
+		const testid = el.getAttribute("data-testid") ?? el.getAttribute("data-test-id");
+		if (testid) return `[data-testid="${testid.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"]`;
+		const parts = [];
+		let cur = el;
+		while (cur && cur !== document.body && parts.length < 6) {
+			const tag = cur.tagName.toLowerCase();
+			const parent = cur.parentElement;
+			if (!parent) {
+				parts.unshift(tag);
+				break;
+			}
+			const sameTag = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);
+			const idx = sameTag.indexOf(cur) + 1;
+			parts.unshift(sameTag.length > 1 ? `${tag}:nth-of-type(${idx})` : tag);
+			cur = parent;
+		}
+		return parts.join(" > ");
+	}
+	function isVisible(el) {
+		if (el.getAttribute("aria-hidden") === "true") return false;
+		const rect = el.getBoundingClientRect();
+		if (rect.width === 0 && rect.height === 0) return false;
+		const style = getComputedStyle(el);
+		return style.visibility !== "hidden" && style.display !== "none";
+	}
+	/**
+	* 统一元素描述结构(F5 顺带统一):aria 快照 ref、find 匹配、
+	* 拾取指纹(pick hint)、录制回声(recorder payload)共用同一份字段语义。
+	*/
+	function describeElement(el) {
+		const sem = resolveComponentSemantics(el);
+		const role = roleOf(el);
+		const testid = el.getAttribute("data-testid") ?? el.getAttribute("data-test-id") ?? "";
+		return {
+			role,
+			name: nameOf(el, role),
+			selector: cssPath(el),
+			testid,
+			id: el.id ?? "",
+			tag: el.tagName.toLowerCase(),
+			text: (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ").slice(0, 60),
+			visible: isVisible(el),
+			...sem.library ? { library: sem.library } : {},
+			...sem.component ? { component: sem.component } : {},
+			...sem.sourceFile ? { sourceFile: sem.sourceFile } : {},
+			...sem.formLabel ? { formLabel: sem.formLabel } : {}
+		};
+	}
+	return {
+		INTERACTIVE,
+		STRUCTURAL,
+		SKIP_TAGS,
+		roleOf,
+		nameOf,
+		cssPath,
+		isVisible,
+		describeElement,
+		resolveComponentSemantics
+	};
+}
+/** walker 核心的序列化源码(模块加载期取一次;tsdown/vitest 均原样保留)。 */
+const CORE_SRC = __walkerCore.toString();
+/**
+* 把消费方 entry(自包含函数,签名 (payload, w: WalkerApi) => R)拼装成
+* 可被 page.evaluate 序列化的独立函数 (payload: P) => R。
+* 拼装发生在模块加载期(new Function 一次性),调用期零开销。
+*/
+function injectWalker(entry) {
+	const src = `"use strict"; return function (payload) { const w = (${CORE_SRC})(); return (${entry.toString()})(payload, w); };`;
+	return new Function(src)();
+}
+//#endregion
 //#region lib/types/browser/session.js
 /** 当前活动 profile 名(默认 "default")。 */
 let currentProfile = "default";
@@ -228,6 +572,35 @@ function snapshotCacheOf(page) {
 function setSnapshotCache(page, cache) {
 	snapshotCaches.set(page, cache);
 }
+/** 环形容量钳制(1..20,非法值回落默认 5)。导出供测试。 */
+function snapshotCapacity(k) {
+	const n = Math.floor(Number(k));
+	if (!Number.isFinite(n)) return 5;
+	return Math.min(Math.max(n, 1), 20);
+}
+/**
+* 追加一个新版本并淘汰超限的最旧版本(纯逻辑,导出供测试)。
+* cache 为 undefined 时从 version 1 开始;返回新缓存(不修改入参)。
+*/
+function pushSnapshotVersion(cache, content, capacity) {
+	const version = (cache?.version ?? 0) + 1;
+	const k = snapshotCapacity(capacity);
+	const history = [...cache?.history ?? [], {
+		version,
+		text: content.text,
+		aria: content.aria
+	}];
+	if (history.length > k) history.splice(0, history.length - k);
+	return {
+		version,
+		history
+	};
+}
+/** 按版本号取历史条目;不在环形窗口内(更旧/未知)返回 undefined。 */
+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);
+}
 /** 已保存的录制脚本:name → 步骤数组。 */
 const savedRecordings = /* @__PURE__ */ new Map();
 /** 当前录制中的 buffer(非空 = 录制中)。 */
@@ -300,6 +673,19 @@ function resolveConfirm(id, decision) {
 	pendingConfirm.decision = decision;
 	return true;
 }
+let toolInFlight = 0;
+/** live 工具调用开始(register 包装层调用)。 */
+function noteToolStart() {
+	toolInFlight++;
+}
+/** live 工具调用结束(成功/失败都算结束)。 */
+function noteToolEnd() {
+	if (toolInFlight > 0) toolInFlight--;
+}
+/** 当前在途的 live 工具调用数(0 = agent 空闲)。 */
+function activeToolCalls() {
+	return toolInFlight;
+}
 /** window 上的回传 binding 名(须为合法 JS 标识符)。 */
 const HUMAN_BINDING = "__dshBrowserHumanEvent";
 /** 最近一次 agent DOM 操作(点击/输入/选择)的时间戳;用于区分人手与工具回声。 */
@@ -390,33 +776,16 @@ function handleHumanEvent(payload) {
 * 页内注入的人工操作监听(addInitScript 序列化;每次导航自动重装)。
 * 监听常驻但 node 侧只在录制中生效,关闭录制等价于"移除"。
 * 只上报可交互元素上的 click 与表单控件的 change,避免逐键噪音。
+* F5 收敛:cssPath 等元素描述来自 walker.ts 单一来源(构建期拼装注入),
+* 不再持有内联副本;payload 字段语义与 v0.3 完全一致。
 */
-function installHumanRecorder() {
-	const w = window;
-	if (w.__dshHumanRecorder === true) return;
-	w.__dshHumanRecorder = true;
+const installHumanRecorder = injectWalker((_payload, w) => {
+	const cssPath = w.cssPath;
+	const w2 = window;
+	if (w2.__dshHumanRecorder === true) return;
+	w2.__dshHumanRecorder = true;
 	const BINDING = "__dshBrowserHumanEvent";
 	const INTERACTIVE = "a,button,input,select,textarea,summary,[role='button'],[role='tab'],[role='menuitem'],[role='option'],[role='switch'],[role='checkbox']";
-	function cssPath(el) {
-		if (el.id) return `#${CSS.escape(el.id)}`;
-		const testid = el.getAttribute("data-testid") ?? el.getAttribute("data-test-id");
-		if (testid) return `[data-testid="${testid.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"]`;
-		const parts = [];
-		let cur = el;
-		while (cur && cur !== document.body && parts.length < 6) {
-			const tag = cur.tagName.toLowerCase();
-			const parent = cur.parentElement;
-			if (!parent) {
-				parts.unshift(tag);
-				break;
-			}
-			const sameTag = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);
-			const idx = sameTag.indexOf(cur) + 1;
-			parts.unshift(sameTag.length > 1 ? `${tag}:nth-of-type(${idx})` : tag);
-			cur = parent;
-		}
-		return parts.join(" > ");
-	}
 	function payloadOf(el, kind, value) {
 		const aria = el.getAttribute("aria-label");
 		return {
@@ -433,7 +802,7 @@ function installHumanRecorder() {
 	}
 	function send(payload) {
 		try {
-			const fn = w[BINDING];
+			const fn = w2[BINDING];
 			if (typeof fn === "function") Promise.resolve(fn(payload)).catch(() => {});
 		} catch {}
 	}
@@ -455,7 +824,7 @@ function installHumanRecorder() {
 			send(payloadOf(t, "input", t.value));
 		}
 	}, true);
-}
+});
 const networkByProfile = /* @__PURE__ */ new Map();
 function networkOf(name) {
 	let list = networkByProfile.get(name);
@@ -772,12 +1141,16 @@ async function closeBrowser() {
 	profileStates.clear();
 	downloadsByProfile.clear();
 }
-/** Best-effort current page identity, safe when nothing is open. */
+/** Best-effort current page identity, safe when nothing is open.title 有界防页面忙时挂起。 */
 async function pageIdentity(page) {
 	try {
+		const title = await new Promise((resolve, reject) => {
+			const t = setTimeout(() => reject(/* @__PURE__ */ new Error("title timeout")), 2e3);
+			page.title().then(resolve, reject).finally(() => clearTimeout(t));
+		}).catch(() => "");
 		return {
 			url: page.url(),
-			title: await page.title()
+			title
 		};
 	} catch {
 		return {
@@ -1189,7 +1562,7 @@ function renderMarkdownReport(runs, source) {
 		"| 时间 | 来源 | 通过/总数 | 失败 | 自愈 | 耗时 |",
 		"| --- | --- | --- | --- | --- | --- |"
 	];
-	for (const r of runs) lines.push(`| ${fmtTs(r.ts)} | ${r.source}${r.row !== void 0 ? ` (行${r.row})` : ""} | ${r.passed}/${r.total} | ${r.failed} | ${r.healedCount} | ${(r.durationMs / 1e3).toFixed(1)}s |`);
+	for (const r of runs) lines.push(`| ${fmtTs(r.ts)} | ${r.source}${r.row !== void 0 ? ` (行${r.row})` : ""}${r.retries !== void 0 ? ` (重试挽回 ${r.retries.recovered}/${r.retries.attempted})` : ""}${r.retryOf !== void 0 ? ` ↻${r.retryOf}` : ""} | ${r.passed}/${r.total} | ${r.failed} | ${r.healedCount} | ${(r.durationMs / 1e3).toFixed(1)}s |`);
 	const { failures, healed } = analyze(runs);
 	lines.push("", "## 失败步骤 Top", "");
 	if (failures.length === 0) lines.push("全部通过 🎉");
@@ -1210,7 +1583,7 @@ function renderHtmlReport(runs, source) {
 	const { failures, healed } = analyze(runs);
 	const rowHtml = runs.map((r) => {
 		const ok = r.failed === 0;
-		return `<tr><td>${esc(fmtTs(r.ts))}</td><td>${esc(r.source)}${r.row !== void 0 ? ` (行${r.row})` : ""}</td><td class="${ok ? "ok" : "bad"}">${r.passed}/${r.total}</td><td>${r.failed}</td><td>${r.healedCount}</td><td>${(r.durationMs / 1e3).toFixed(1)}s</td></tr>`;
+		return `<tr><td>${esc(fmtTs(r.ts))}</td><td>${esc(r.source)}${r.row !== void 0 ? ` (行${r.row})` : ""}${r.retries !== void 0 ? ` <span class="meta">(重试挽回 ${r.retries.recovered}/${r.retries.attempted})</span>` : ""}${r.retryOf !== void 0 ? ` <span class="meta" title="重跑自 ${esc(r.retryOf)}">↻</span>` : ""}</td><td class="${ok ? "ok" : "bad"}">${r.passed}/${r.total}</td><td>${r.failed}</td><td>${r.healedCount}</td><td>${(r.durationMs / 1e3).toFixed(1)}s</td></tr>`;
 	}).join("\n");
 	const failRows = failures.length === 0 ? `<tr><td colspan="4" class="ok">全部通过 🎉</td></tr>` : failures.map((f) => `<tr><td>${f.count}</td><td>${esc(f.source)}</td><td>${esc(f.tool)}</td><td>${esc(f.error.slice(0, 200))}</td></tr>`).join("\n");
 	const healRows = healed.slice(0, 20).map((h) => `<tr><td>${esc(fmtTs(h.ts))}</td><td>${esc(h.source)}</td><td>${esc(h.tool)}</td><td>${esc(h.via)}</td><td><code>${esc(h.resolved)}</code></td></tr>`).join("\n");
@@ -1301,160 +1674,14 @@ function compressText(text) {
 	return out.join("\n");
 }
 /**
-* 页内 ARIA 树构建(自包含函数,page.evaluate 序列化注入;禁止引用模块级变量)。
+* 页内 ARIA 树构建(walker 单一来源:roleOf/nameOf/cssPath/isVisible 与
+* INTERACTIVE/STRUCTURAL 集合来自 walker.ts,构建期拼装注入)。
 * 遍历 DOM:结构角色(navigation/main/form/table/heading…)直接打印;
 * 可交互元素分配 ref=e1..eN 并附稳定 CSS 路径;无语义容器(div/span)穿透。
 * 输出形如 `- button "登录" [ref=e3]` 的缩进树,供纯文本模型定位操作目标。
 */
-function buildAriaTree(payload) {
-	const INTERACTIVE = /* @__PURE__ */ new Set([
-		"link",
-		"button",
-		"textbox",
-		"checkbox",
-		"radio",
-		"combobox",
-		"listbox",
-		"searchbox",
-		"slider",
-		"spinbutton",
-		"switch",
-		"tab",
-		"menuitem",
-		"option",
-		"treeitem"
-	]);
-	const STRUCTURAL = /* @__PURE__ */ new Set([
-		"navigation",
-		"main",
-		"banner",
-		"contentinfo",
-		"form",
-		"search",
-		"complementary",
-		"region",
-		"dialog",
-		"alert",
-		"table",
-		"list",
-		"heading",
-		"toolbar",
-		"menu",
-		"menubar",
-		"tablist",
-		"tree",
-		"grid"
-	]);
-	const SKIP_TAGS = /* @__PURE__ */ new Set([
-		"script",
-		"style",
-		"template",
-		"noscript",
-		"svg",
-		"path",
-		"link",
-		"meta",
-		"br"
-	]);
-	function roleOf(el) {
-		const explicit = el.getAttribute("role");
-		if (explicit) return explicit.trim().split(/\s+/)[0] ?? "";
-		switch (el.tagName.toLowerCase()) {
-			case "a": return el.hasAttribute("href") ? "link" : "";
-			case "button": return "button";
-			case "input": {
-				const t = (el.getAttribute("type") ?? "text").toLowerCase();
-				if (t === "checkbox") return "checkbox";
-				if (t === "radio") return "radio";
-				if (t === "range") return "slider";
-				if (t === "number") return "spinbutton";
-				if (t === "search") return "searchbox";
-				if ([
-					"button",
-					"submit",
-					"reset",
-					"image"
-				].includes(t)) return "button";
-				if (["hidden", "file"].includes(t)) return "";
-				return "textbox";
-			}
-			case "textarea": return "textbox";
-			case "select": return "combobox";
-			case "nav": return "navigation";
-			case "main": return "main";
-			case "header": return "banner";
-			case "footer": return "contentinfo";
-			case "form": return "form";
-			case "h1":
-			case "h2":
-			case "h3":
-			case "h4":
-			case "h5":
-			case "h6": return "heading";
-			case "ul":
-			case "ol": return "list";
-			case "li": return "listitem";
-			case "table": return "table";
-			case "dialog": return "dialog";
-			case "summary": return "button";
-			default: return "";
-		}
-	}
-	function nameOf(el, role) {
-		const aria = el.getAttribute("aria-label");
-		if (aria && aria.trim()) return aria.trim().slice(0, 60);
-		const labelledby = el.getAttribute("aria-labelledby");
-		if (labelledby) {
-			const t = labelledby.split(/\s+/).map((id) => document.getElementById(id)?.textContent?.trim() ?? "").join(" ").trim();
-			if (t) return t.slice(0, 60);
-		}
-		if (el.id) {
-			const t = document.querySelector(`label[for="${CSS.escape(el.id)}"]`)?.textContent?.trim();
-			if (t) return t.slice(0, 60);
-		}
-		if ([
-			"textbox",
-			"searchbox",
-			"combobox",
-			"spinbutton"
-		].includes(role)) {
-			const ph = el.getAttribute("placeholder");
-			if (ph && ph.trim()) return ph.trim().slice(0, 60);
-		}
-		const text = (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ");
-		if (text) return text.slice(0, 60);
-		const title = el.getAttribute("title");
-		if (title && title.trim()) return title.trim().slice(0, 60);
-		return "";
-	}
-	/** 稳定 CSS 路径:#id → [data-testid] → nth-of-type 链(≤6 层)。 */
-	function cssPath(el) {
-		if (el.id) return `#${CSS.escape(el.id)}`;
-		const testid = el.getAttribute("data-testid") ?? el.getAttribute("data-test-id");
-		if (testid) return `[data-testid="${testid.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"]`;
-		const parts = [];
-		let cur = el;
-		while (cur && cur !== document.body && parts.length < 6) {
-			const tag = cur.tagName.toLowerCase();
-			const parent = cur.parentElement;
-			if (!parent) {
-				parts.unshift(tag);
-				break;
-			}
-			const sameTag = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);
-			const idx = sameTag.indexOf(cur) + 1;
-			parts.unshift(sameTag.length > 1 ? `${tag}:nth-of-type(${idx})` : tag);
-			cur = parent;
-		}
-		return parts.join(" > ");
-	}
-	function isVisible(el) {
-		if (el.getAttribute("aria-hidden") === "true") return false;
-		const rect = el.getBoundingClientRect();
-		if (rect.width === 0 && rect.height === 0) return false;
-		const style = getComputedStyle(el);
-		return style.visibility !== "hidden" && style.display !== "none";
-	}
+const buildAriaTree = injectWalker((payload, w) => {
+	const { INTERACTIVE, STRUCTURAL, SKIP_TAGS, roleOf, nameOf, cssPath, isVisible } = w;
 	const lines = [];
 	const refs = [];
 	let truncated = false;
@@ -1468,186 +1695,62 @@ function buildAriaTree(payload) {
 		if (INTERACTIVE.has(role)) {
 			if (!isVisible(el)) return;
 			const name = nameOf(el, role);
+			const sem = w.resolveComponentSemantics(el);
 			const ref = refs.length < payload.maxRefs ? `e${refs.length + 1}` : "";
 			if (ref !== "") refs.push({
 				ref,
 				role,
 				name,
-				selector: cssPath(el)
-			});
-			const expanded = el.getAttribute("aria-expanded");
-			const disabled = el.disabled === true || el.getAttribute("aria-disabled") === "true";
-			lines.push(`${"  ".repeat(depth)}- ${role}${name !== "" ? ` "${name.replace(/"/g, "'")}"` : ""}${ref !== "" ? ` [ref=${ref}]` : ""}${expanded !== null ? ` [expanded=${expanded}]` : ""}${disabled ? " [disabled]" : ""}`);
-			return;
-		}
-		if (STRUCTURAL.has(role)) {
-			if (!isVisible(el)) return;
-			const name = nameOf(el, role);
-			const level = role === "heading" ? ` [level=${el.tagName[1] ?? "1"}]` : "";
-			lines.push(`${"  ".repeat(depth)}- ${role}${name !== "" ? ` "${name.replace(/"/g, "'")}"` : ""}${level}`);
-			for (const c of Array.from(el.children)) if (!SKIP_TAGS.has(c.tagName.toLowerCase())) walk(c, depth + 1);
-			return;
-		}
-		for (const c of Array.from(el.children)) if (!SKIP_TAGS.has(c.tagName.toLowerCase())) walk(c, depth);
-	}
-	if (document.body === null) return {
-		tree: "",
-		refs,
-		truncated: false,
-		scopeMissing: false
-	};
-	const root = payload.scope ? document.querySelector(payload.scope) : document.body;
-	if (root === null) return {
-		tree: "",
-		refs,
-		truncated: false,
-		scopeMissing: true
-	};
-	walk(root, 0);
-	return {
-		tree: lines.join("\n"),
-		refs,
-		truncated,
-		scopeMissing: false
-	};
-}
-/**
-* 页内语义查找:只收集匹配 query 的可交互元素(不构建全量树)。
-* role/name/cssPath/isVisible 与 buildAriaTree 保持同一套语义(此处内联副本,
-* evaluate 序列化不允许闭包引用);改动任一处时同步另一处。
-*/
-function findInteractive(payload) {
-	const INTERACTIVE = /* @__PURE__ */ new Set([
-		"link",
-		"button",
-		"textbox",
-		"checkbox",
-		"radio",
-		"combobox",
-		"listbox",
-		"searchbox",
-		"slider",
-		"spinbutton",
-		"switch",
-		"tab",
-		"menuitem",
-		"option",
-		"treeitem"
-	]);
-	const STRUCTURAL = /* @__PURE__ */ new Set([
-		"navigation",
-		"main",
-		"banner",
-		"contentinfo",
-		"form",
-		"search",
-		"complementary",
-		"region",
-		"dialog",
-		"alert",
-		"table",
-		"list",
-		"heading",
-		"toolbar",
-		"menu",
-		"menubar",
-		"tablist",
-		"tree",
-		"grid"
-	]);
-	const SKIP_TAGS = /* @__PURE__ */ new Set([
-		"script",
-		"style",
-		"template",
-		"noscript",
-		"svg",
-		"path",
-		"link",
-		"meta",
-		"br"
-	]);
-	function roleOf(el) {
-		const explicit = el.getAttribute("role");
-		if (explicit) return explicit.trim().split(/\s+/)[0] ?? "";
-		switch (el.tagName.toLowerCase()) {
-			case "a": return el.hasAttribute("href") ? "link" : "";
-			case "button": return "button";
-			case "input": {
-				const t = (el.getAttribute("type") ?? "text").toLowerCase();
-				if (t === "checkbox") return "checkbox";
-				if (t === "radio") return "radio";
-				if (t === "range") return "slider";
-				if (t === "number") return "spinbutton";
-				if (t === "search") return "searchbox";
-				if ([
-					"button",
-					"submit",
-					"reset",
-					"image"
-				].includes(t)) return "button";
-				if (["hidden", "file"].includes(t)) return "";
-				return "textbox";
-			}
-			case "textarea": return "textbox";
-			case "select": return "combobox";
-			case "summary": return "button";
-			default: return "";
-		}
-	}
-	function nameOf(el, role) {
-		const aria = el.getAttribute("aria-label");
-		if (aria && aria.trim()) return aria.trim().slice(0, 60);
-		const labelledby = el.getAttribute("aria-labelledby");
-		if (labelledby) {
-			const t = labelledby.split(/\s+/).map((id) => document.getElementById(id)?.textContent?.trim() ?? "").join(" ").trim();
-			if (t) return t.slice(0, 60);
-		}
-		if (el.id) {
-			const t = document.querySelector(`label[for="${CSS.escape(el.id)}"]`)?.textContent?.trim();
-			if (t) return t.slice(0, 60);
-		}
-		if ([
-			"textbox",
-			"searchbox",
-			"combobox",
-			"spinbutton"
-		].includes(role)) {
-			const ph = el.getAttribute("placeholder");
-			if (ph && ph.trim()) return ph.trim().slice(0, 60);
+				selector: cssPath(el),
+				...sem.library ? { library: sem.library } : {},
+				...sem.component ? { component: sem.component } : {},
+				...sem.sourceFile ? { sourceFile: sem.sourceFile } : {}
+			});
+			const expanded = el.getAttribute("aria-expanded");
+			const disabled = el.disabled === true || el.getAttribute("aria-disabled") === "true";
+			const compLabel = sem.component ? ` [comp=${sem.component}]` : "";
+			const srcLabel = sem.sourceFile ? ` [src=${sem.sourceFile.split("/").pop()}]` : "";
+			lines.push(`${"  ".repeat(depth)}- ${role}${name !== "" ? ` "${name.replace(/"/g, "'")}"` : ""}${ref !== "" ? ` [ref=${ref}]` : ""}${compLabel}${srcLabel}${expanded !== null ? ` [expanded=${expanded}]` : ""}${disabled ? " [disabled]" : ""}`);
+			return;
 		}
-		const text = (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ");
-		if (text) return text.slice(0, 60);
-		const title = el.getAttribute("title");
-		if (title && title.trim()) return title.trim().slice(0, 60);
-		return "";
-	}
-	function cssPath(el) {
-		if (el.id) return `#${CSS.escape(el.id)}`;
-		const testid = el.getAttribute("data-testid") ?? el.getAttribute("data-test-id");
-		if (testid) return `[data-testid="${testid.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"]`;
-		const parts = [];
-		let cur = el;
-		while (cur && cur !== document.body && parts.length < 6) {
-			const tag = cur.tagName.toLowerCase();
-			const parent = cur.parentElement;
-			if (!parent) {
-				parts.unshift(tag);
-				break;
-			}
-			const sameTag = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);
-			const idx = sameTag.indexOf(cur) + 1;
-			parts.unshift(sameTag.length > 1 ? `${tag}:nth-of-type(${idx})` : tag);
-			cur = parent;
+		if (STRUCTURAL.has(role)) {
+			if (!isVisible(el)) return;
+			const name = nameOf(el, role);
+			const level = role === "heading" ? ` [level=${el.tagName[1] ?? "1"}]` : "";
+			lines.push(`${"  ".repeat(depth)}- ${role}${name !== "" ? ` "${name.replace(/"/g, "'")}"` : ""}${level}`);
+			for (const c of Array.from(el.children)) if (!SKIP_TAGS.has(c.tagName.toLowerCase())) walk(c, depth + 1);
+			return;
 		}
-		return parts.join(" > ");
-	}
-	function isVisible(el) {
-		if (el.getAttribute("aria-hidden") === "true") return false;
-		const rect = el.getBoundingClientRect();
-		if (rect.width === 0 && rect.height === 0) return false;
-		const style = getComputedStyle(el);
-		return style.visibility !== "hidden" && style.display !== "none";
+		for (const c of Array.from(el.children)) if (!SKIP_TAGS.has(c.tagName.toLowerCase())) walk(c, depth);
 	}
+	if (document.body === null) return {
+		tree: "",
+		refs,
+		truncated: false,
+		scopeMissing: false
+	};
+	const root = payload.scope ? document.querySelector(payload.scope) : document.body;
+	if (root === null) return {
+		tree: "",
+		refs,
+		truncated: false,
+		scopeMissing: true
+	};
+	walk(root, 0);
+	return {
+		tree: lines.join("\n"),
+		refs,
+		truncated,
+		scopeMissing: false
+	};
+});
+/**
+* 页内语义查找:只收集匹配 query 的可交互元素(不构建全量树)。
+* role/name/cssPath/isVisible 与 buildAriaTree 同一来源(walker.ts 单一来源,
+* 构建期拼装注入),语义天然一致,不再需要手工同步副本。
+*/
+const findInteractive = injectWalker((payload, w) => {
+	const { INTERACTIVE, STRUCTURAL, SKIP_TAGS, roleOf, nameOf, cssPath, isVisible, resolveComponentSemantics } = w;
 	/** 最近的结构化祖先(区域上下文,帮助区分多命中)。 */
 	function ancestorsOf(el) {
 		const out = [];
@@ -1662,7 +1765,10 @@ function findInteractive(payload) {
 		}
 		return out;
 	}
-	const q = payload.query.trim().toLowerCase();
+	const q = (payload.query || "").trim().toLowerCase();
+	const filterComp = (payload.component || "").trim().toLowerCase();
+	const filterLib = (payload.library || "").trim().toLowerCase();
+	const filterFile = (payload.file || "").trim().toLowerCase();
 	const matches = [];
 	const candidates = [];
 	let scanned = 0;
@@ -1679,13 +1785,30 @@ function findInteractive(payload) {
 		if (INTERACTIVE.has(role)) {
 			if (!isVisible(el)) continue;
 			const name = nameOf(el, role);
+			const sem = resolveComponentSemantics(el);
 			const idOrTestid = el.id || el.getAttribute("data-testid") || "";
-			let hit = false;
-			if (name !== "") {
-				const n = name.toLowerCase();
-				hit = payload.exact ? n === q : n.includes(q);
+			let filterPass = true;
+			if (filterComp) {
+				const comp = (sem.component || "").toLowerCase();
+				if (filterComp.startsWith("*")) filterPass = comp.endsWith(filterComp.slice(1));
+				else if (filterComp.endsWith("*")) filterPass = comp.startsWith(filterComp.slice(0, -1));
+				else filterPass = comp === filterComp;
 			}
-			if (!hit && idOrTestid !== "" && idOrTestid.toLowerCase() === q) hit = true;
+			if (filterPass && filterLib) filterPass = (sem.library || "").toLowerCase() === filterLib;
+			if (filterPass && filterFile) filterPass = (sem.sourceFile || "").toLowerCase().includes(filterFile);
+			if (!filterPass) continue;
+			let hit = false;
+			if (q) {
+				if (name !== "") {
+					const n = name.toLowerCase();
+					hit = payload.exact ? n === q : n.includes(q);
+				}
+				if (!hit && idOrTestid !== "" && idOrTestid.toLowerCase() === q) hit = true;
+				if (!hit && sem.formLabel && sem.formLabel.toLowerCase().includes(q)) hit = true;
+				if (!hit && sem.placeholder && sem.placeholder.toLowerCase().includes(q)) hit = true;
+				if (!hit && sem.component && sem.component.toLowerCase() === q) hit = true;
+				if (!hit && sem.sourceFile && sem.sourceFile.toLowerCase().includes(q)) hit = true;
+			} else hit = true;
 			scanned += 1;
 			if (name !== "" && candidates.length < 50) candidates.push({
 				role,
@@ -1695,7 +1818,11 @@ function findInteractive(payload) {
 				role,
 				name,
 				selector: cssPath(el),
-				ancestors: ancestorsOf(el)
+				ancestors: ancestorsOf(el),
+				...sem.library ? { library: sem.library } : {},
+				...sem.component ? { component: sem.component } : {},
+				...sem.sourceFile ? { sourceFile: sem.sourceFile } : {},
+				...sem.formLabel ? { formLabel: sem.formLabel } : {}
 			});
 			continue;
 		}
@@ -1706,7 +1833,7 @@ function findInteractive(payload) {
 		candidates,
 		scanned
 	};
-}
+});
 /** 最长公共子串长度(小写比较;零依赖,导出供测试)。 */
 function lcsScore(a, b) {
 	const x = a.toLowerCase();
@@ -1761,7 +1888,10 @@ function assignRefs(existing, matches, maxRefs) {
 		merged.set(ref, {
 			role: m.role,
 			name: m.name,
-			selector: m.selector
+			selector: m.selector,
+			...m.library ? { library: m.library } : {},
+			...m.component ? { component: m.component } : {},
+			...m.sourceFile ? { sourceFile: m.sourceFile } : {}
 		});
 		withRefs.push({
 			ref,
@@ -1775,32 +1905,42 @@ function assignRefs(existing, matches, maxRefs) {
 	};
 }
 /**
-* 语义元素定位:按名称(或 id/data-testid)在可交互元素中查找,只返回命中的
+* 语义元素定位:按名称(或 id/data-testid/组件名/源码文件)在可交互元素中查找,只返回命中的
 * ref + 区域上下文,不输出全量 aria 树 —— 大页面定位单个目标时 token 开销
 * 远小于 browser_snapshot { mode: "aria" }。返回的 ref 可直接用于
 * click/type/select/press。零命中不抛错,附最相近候选供二次定位。
 */
 async function findTool(config, args) {
 	const query = typeof args.query === "string" ? args.query.trim() : "";
-	if (!query) throw new Error("缺少 query: 要找的元素名称(如「提交」「登录」,或 id/data-testid)");
+	const component = typeof args.component === "string" ? args.component.trim() : "";
+	const library = typeof args.library === "string" ? args.library.trim() : "";
+	const file = typeof args.file === "string" ? args.file.trim() : "";
+	if (!query && !component && !file) throw new Error("缺少定位参数: 请提供 query(元素名称/id/data-testid), 或 component(如 ASelect/ElSelect), 或 file(源码文件名)");
 	const page = await getPage(config);
 	const maxRefs = Math.min(Math.max(Number(args.maxRefs ?? config.maxRefs ?? 200) || 200, 1), 500);
 	const data = await page.evaluate(findInteractive, {
 		query,
 		exact: args.exact === true,
 		scope: typeof args.scope === "string" && args.scope ? args.scope : "",
-		limit: 20
+		limit: 20,
+		component,
+		library,
+		file
 	});
 	const { withRefs, merged, truncated } = assignRefs(pageRefsOf(page), data.matches, maxRefs);
 	setPageRefs(page, merged);
-	const suggestions = withRefs.length === 0 ? topSuggestions(query, data.candidates) : [];
+	const suggestions = withRefs.length === 0 ? topSuggestions(query || component || file, data.candidates) : [];
 	return {
 		found: withRefs.length,
-		matches: withRefs.slice(0, 10).map(({ ref, role, name, ancestors }) => ({
+		matches: withRefs.slice(0, 10).map(({ ref, role, name, ancestors, library, component, sourceFile, formLabel }) => ({
 			ref,
 			role,
 			name,
-			ancestors
+			ancestors,
+			...library ? { library } : {},
+			...component ? { component } : {},
+			...sourceFile ? { sourceFile } : {},
+			...formLabel ? { formLabel } : {}
 		})),
 		...suggestions.length > 0 ? { suggestions } : {},
 		...truncated ? { truncated } : {},
@@ -1839,7 +1979,9 @@ async function snapshotTool(config, args) {
 		title: await page.title()
 	};
 	const cache = snapshotCacheOf(page);
-	const canDiff = since !== void 0 && cache !== void 0 && cache.version === since;
+	const capacity = config.snapshotHistory ?? 5;
+	const base = since !== void 0 ? snapshotVersionEntry(cache, since) : void 0;
+	const canDiff = base !== void 0;
 	let content;
 	let extra = {};
 	let walkerTruncated = false;
@@ -1885,7 +2027,7 @@ async function snapshotTool(config, args) {
 		};
 	}
 	const key = ariaMode ? "aria" : "text";
-	if (canDiff && cache[key] === content) return {
+	if (canDiff && base[key] === content) return {
 		unchanged: true,
 		contentVersion: cache.version,
 		...scope !== "" ? { scope } : {},
@@ -1893,22 +2035,23 @@ async function snapshotTool(config, args) {
 		...extra
 	};
 	if (canDiff) {
-		const d = diffLines(cache[key], content);
-		setSnapshotCache(page, {
-			version: cache.version + 1,
-			text: ariaMode ? cache.text : content,
-			aria: ariaMode ? content : cache.aria
-		});
+		const d = diffLines(base[key], content);
+		const latest = cache.history[cache.history.length - 1];
+		const next = pushSnapshotVersion(cache, {
+			text: ariaMode ? latest.text : content,
+			aria: ariaMode ? content : latest.aria
+		}, capacity);
+		setSnapshotCache(page, next);
 		if (d.unchanged) return {
 			unchanged: true,
-			contentVersion: cache.version + 1,
+			contentVersion: next.version,
 			...scope !== "" ? { scope } : {},
 			...identity,
 			...extra
 		};
 		return {
 			diff: true,
-			contentVersion: cache.version + 1,
+			contentVersion: next.version,
 			changedFrom: d.changedFrom,
 			removed: d.removed,
 			...scope !== "" ? { scope } : {},
@@ -1918,13 +2061,14 @@ async function snapshotTool(config, args) {
 			...extra
 		};
 	}
-	setSnapshotCache(page, {
-		version: (cache?.version ?? 0) + 1,
-		text: ariaMode ? cache?.text ?? "" : content,
-		aria: ariaMode ? content : cache?.aria ?? ""
-	});
+	const latestEntry = cache?.history[cache.history.length - 1];
+	const next = pushSnapshotVersion(cache, {
+		text: ariaMode ? latestEntry?.text ?? "" : content,
+		aria: ariaMode ? content : latestEntry?.aria ?? ""
+	}, capacity);
+	setSnapshotCache(page, next);
 	return {
-		contentVersion: (cache?.version ?? 0) + 1,
+		contentVersion: next.version,
 		...since !== void 0 ? { stale: true } : {},
 		...scope !== "" ? { scope } : {},
 		[ariaMode ? "tree" : "text"]: content.slice(0, maxText),
@@ -1944,8 +2088,8 @@ async function targetLocator(page, args) {
 		const entry = pageRef(page, ref);
 		if (entry === void 0) throw new Error(`未知 ref: ${ref}(页面导航或重新快照后旧 ref 失效;请先 browser_snapshot { mode: "aria" })`);
 		const byPath = page.locator(entry.selector).first();
-		if (await byPath.count().catch(() => 0) > 0) {
-			if (await byPath.evaluate((el, want) => {
+		if (await withTimeout(byPath.count(), 3e3, "解析 ref 路径").catch(() => 0) > 0) {
+			if (await withTimeout(byPath.evaluate((el, want) => {
 				const tag = el.tagName.toLowerCase();
 				const type = (el.getAttribute("type") ?? "").toLowerCase();
 				const roleAttr = (el.getAttribute("role") ?? "").trim().split(/\s+/)[0] ?? "";
@@ -1967,10 +2111,10 @@ async function targetLocator(page, args) {
 			}, {
 				role: entry.role,
 				name: entry.name
-			}).catch(() => false)) return byPath;
+			}), 3e3, "校验 ref 元素").catch(() => false)) return byPath;
 		}
 		const byRole = entry.name !== "" ? page.getByRole(entry.role, { name: entry.name }).first() : page.getByRole(entry.role).first();
-		if (await byRole.count().catch(() => 0) > 0) return byRole;
+		if (await withTimeout(byRole.count(), 3e3, "解析 ref role 降级").catch(() => 0) > 0) return byRole;
 		throw new Error(`ref ${ref} 已失效(元素不存在或内容已变化);请重新 browser_snapshot { mode: "aria" }`);
 	}
 	if (args.selector === void 0) throw new Error("需要 selector 或 ref 之一");
@@ -2026,12 +2170,26 @@ async function pressTool(config, args) {
 		...await pageIdentity(page)
 	};
 }
-/** 组件库下拉框的可见选项选择器并集(antd / element-plus / 通用 ARIA listbox)。 */
+/** 组件库下拉框的可见选项选择器并集(antd / element-plus / naive-ui / arco-design / 通用 ARIA listbox)。 */
 const DROPDOWN_OPTION_SELECTOR = [
 	".ant-select-dropdown:not(.ant-select-dropdown-hidden) .ant-select-item-option",
 	".el-select-dropdown__item",
+	".n-base-select-option",
+	".arco-select-option",
 	"[role='listbox'] [role='option']"
 ].join(", ");
+/** 给本身无超时的 Playwright 调用(evaluate/allTextContents)加有界保护,防页面主线程忙时无限挂起。 */
+async function withTimeout(p, ms, what) {
+	let timer;
+	const guard = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`${what} 超时(${ms}ms;页面主线程可能正忙)`)), ms);
+	});
+	try {
+		return await Promise.race([p, guard]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
 /**
 * 下拉选择原语:原生 <select> 走 selectOption;组件库下拉(antd/element/listbox)
 * 走「点击触发框 → 等待可见选项 → 按文本点击」。找不到选项时抛出错误并附当前可见
@@ -2045,7 +2203,8 @@ async function selectTool(config, args) {
 	if (!want) throw new Error("select 需要 option(选项文本)");
 	const exact = args.exact === true;
 	const timeout = args.timeoutMs ?? config.timeoutMs;
-	if (await target.evaluate((el) => el.tagName.toLowerCase()).catch(() => "") === "select") try {
+	const probe = Math.min(timeout, 5e3);
+	if (await withTimeout(target.evaluate((el) => el.tagName.toLowerCase()), probe, "读取目标元素").catch(() => "") === "select") try {
 		await target.selectOption({ label: want }, { timeout });
 		return {
 			selected: want,
@@ -2053,7 +2212,7 @@ async function selectTool(config, args) {
 			...await pageIdentity(page)
 		};
 	} catch {
-		const options = await target.locator("option").allTextContents();
+		const options = await withTimeout(target.locator("option").allTextContents(), probe, "读取原生下拉选项").catch(() => []);
 		throw new Error(`原生下拉无选项 "${want}";可用选项: ${options.map((t) => t.trim()).join(" / ")}`);
 	}
 	const clickTimeout = Math.min(timeout, 1e4);
@@ -2074,14 +2233,14 @@ async function selectTool(config, args) {
 		state: "visible",
 		timeout: Math.min(timeout, 5e3)
 	}).catch(() => {});
-	const texts = (await options.allTextContents()).map((t) => t.trim()).filter(Boolean);
+	const texts = (await withTimeout(options.allTextContents(), probe, "读取下拉选项")).map((t) => t.trim()).filter(Boolean);
 	if (texts.length === 0) throw new Error(`点击 ${label} 后未出现下拉选项(非原生 select,也不是已知的组件库下拉)`);
 	const index = texts.findIndex((t) => exact ? t === want : t.includes(want));
 	if (index === -1) {
 		await page.keyboard.press("Escape").catch(() => {});
 		throw new Error(`下拉选项中无 "${want}";可见选项: ${texts.join(" / ")}`);
 	}
-	await options.nth(index).click();
+	await options.nth(index).click({ timeout: probe });
 	return {
 		selected: texts[index],
 		selector: label,
@@ -3081,6 +3240,69 @@ async function confirmTool(config, args) {
 		detail
 	};
 }
+/** auto 模式默认敏感文本模式(提交/删除/支付类)。 */
+const DEFAULT_SENSITIVE_PATTERNS = [
+	"提交",
+	"删除",
+	"支付"
+];
+/** auto 模式默认参与判定的工具(已决:只拦 browser_click,type 误报率高)。 */
+const DEFAULT_SENSITIVE_TOOLS = ["browser_click"];
+/** 敏感判定的页内目标描述提取(walker 统一元素描述,构建期拼装注入)。 */
+const describeTarget = injectWalker((sel, w) => {
+	const el = document.querySelector(sel);
+	return el === null ? null : w.describeElement(el);
+});
+/**
+* 纯逻辑:元素描述命中了哪些敏感模式(role/name/text/id/testid/tag 拼接后
+* 子串匹配,大小写不敏感;空白模式忽略)。返回命中的模式列表(空 = 放行)。
+* 导出供测试。
+*/
+function sensitiveHits(desc, patterns) {
+	if (desc === null) return [];
+	const hay = [
+		desc.role,
+		desc.name,
+		desc.text,
+		desc.id,
+		desc.testid,
+		desc.tag
+	].filter((s) => typeof s === "string").join(" ").toLowerCase();
+	if (hay === "") return [];
+	return patterns.filter((p) => typeof p === "string" && p.trim() !== "" && hay.includes(p.trim().toLowerCase()));
+}
+/**
+* auto 模式审批闸:命中敏感模式时经 confirmTool 弹审批等待用户决策,
+* 拒绝/超时抛错(调用方该步失败),允许则返回继续执行原工具。
+* 不满足前置条件(非 auto / 工具不在 sensitiveTools / 无模式 / 无活动页 /
+* 无目标 selector / 页内取描述失败)一律直接放行,由原工具自行处理错误。
+* page 参数仅供测试注入;缺省取当前活动页。
+*/
+async function confirmGate(config, tool, args, page) {
+	if (config.confirmMode !== "auto") return;
+	if (tool === "browser_confirm") return;
+	if (!(config.sensitiveTools ?? DEFAULT_SENSITIVE_TOOLS).includes(tool)) return;
+	const patterns = config.sensitivePatterns ?? DEFAULT_SENSITIVE_PATTERNS;
+	if (patterns.length === 0) return;
+	const active = page !== void 0 ? page : activePage();
+	if (active === null || active === void 0) return;
+	const sel = typeof args?.selector === "string" && args.selector ? args.selector : typeof args?.ref === "string" && args.ref ? pageRef(active, args.ref)?.selector ?? "" : "";
+	if (sel === "") return;
+	let desc = null;
+	try {
+		desc = await active.evaluate(describeTarget, sel);
+	} catch {
+		return;
+	}
+	const hits = sensitiveHits(desc, patterns);
+	if (hits.length === 0) return;
+	const label = desc !== null && (desc.name || desc.text) ? `(${desc.role !== "" ? `${desc.role} ` : ""}"${desc.name || desc.text}")` : "";
+	await confirmTool(config, {
+		reason: `confirmMode:auto 硬拦截:${tool} 目标元素命中敏感模式 [${hits.join(", ")}] ${label}`.trim(),
+		tool,
+		args
+	});
+}
 /** 断言:条件在 timeoutMs 内成立则通过,否则失败并自动截图存证据。visual 断言走像素比对。 */
 async function assertTool(config, args, exec) {
 	const page = await getPage(config);
@@ -3336,37 +3558,29 @@ const SELECTOR_STEP_TOOLS = /* @__PURE__ */ new Set([
 	"browser_select",
 	"browser_upload"
 ]);
+/** 拾取指纹的页内提取(walker 统一元素描述结构;构建期拼装注入)。 */
+const pickElementInjector = injectWalker((el, w) => {
+	const d = w.describeElement(el);
+	return {
+		testid: d.testid !== "" ? d.testid : void 0,
+		id: d.id !== "" ? d.id : void 0,
+		tag: d.tag,
+		role: d.role !== "" ? d.role : void 0,
+		name: d.name !== "" ? d.name : void 0,
+		text: d.text !== "" ? d.text : void 0
+	};
+});
 /**
 * 采集选择器指向元素的指纹(页内 evaluate;找不到元素返回 null)。
 * 指纹是回放自愈的降级候选来源:testid / role+name / text / id / tag+text。
+* F5 收敛:元素描述(role/name/text)改用 walker 单一来源
+* (describeElement),与 aria 快照/find/录制回声共用同一套语义;相比旧
+* 内联副本,role 推断更完整(slider/spinbutton/searchbox/heading 等),
+* name 补齐 labelledby/label[for]/title 兜底 —— 指纹只作自愈降级候选,
+* 语义增强只会让自愈命中率更高,不改变任何主链路行为。
 */
 async function captureSelectorHint(page, selector) {
-	return page.locator(selector).first().evaluate((el) => {
-		const tag = el.tagName.toLowerCase();
-		const type = (el.getAttribute("type") ?? "").toLowerCase();
-		const roleAttr = (el.getAttribute("role") ?? "").trim().split(/\s+/)[0] ?? "";
-		const implicit = tag === "a" && el.hasAttribute("href") ? "link" : tag === "button" || tag === "summary" || tag === "input" && [
-			"button",
-			"submit",
-			"reset",
-			"image"
-		].includes(type) ? "button" : tag === "textarea" || tag === "input" && ![
-			"hidden",
-			"checkbox",
-			"radio",
-			"file"
-		].includes(type) ? "textbox" : tag === "select" ? "combobox" : tag === "input" && type === "checkbox" ? "checkbox" : tag === "input" && type === "radio" ? "radio" : "";
-		const text = (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ").slice(0, 60);
-		const name = (el.getAttribute("aria-label") ?? "").trim() || (el.getAttribute("placeholder") ?? "").trim() || text;
-		return {
-			testid: el.getAttribute("data-testid") ?? el.getAttribute("data-test-id") ?? void 0,
-			id: el.id !== "" ? el.id : void 0,
-			tag,
-			role: (roleAttr || implicit) !== "" ? roleAttr || implicit : void 0,
-			name: name !== "" ? name : void 0,
-			text: text !== "" ? text : void 0
-		};
-	}).catch(() => null);
+	return page.locator(selector).first().evaluate(pickElementInjector).catch(() => null);
 }
 /** 由指纹生成自愈降级候选(按优先级排序;导出供测试)。 */
 function healCandidates(hint) {
@@ -3489,6 +3703,7 @@ async function runReplay(steps, impls, failFast, opts = {}) {
 	let stoppedAt = null;
 	let passed = 0;
 	let healedCount = 0;
+	let retryAttempted = 0;
 	for (let i = 0; i < steps.length; i++) {
 		const step = steps[i];
 		const impl = impls[step.tool];
@@ -3506,81 +3721,107 @@ async function runReplay(steps, impls, failFast, opts = {}) {
 			continue;
 		}
 		const hint = step.meta?.hint;
-		if (!(opts.healing === true && hint !== void 0 && SELECTOR_STEP_TOOLS.has(step.tool) && typeof step.args?.selector === "string")) {
-			try {
+		const canHeal = opts.healing === true && hint !== void 0 && SELECTOR_STEP_TOOLS.has(step.tool) && typeof step.args?.selector === "string";
+		/** 单次完整尝试(含自愈链);返回该次尝试的 result 行(带内部 healed 标记)。 */
+		const attempt = async () => {
+			if (!canHeal) try {
 				await impl(step.args ?? {});
-				passed++;
-				results.push({
-					index: i,
-					tool: step.tool,
-					ok: true
-				});
+				return {
+					ok: true,
+					result: {
+						index: i,
+						tool: step.tool,
+						ok: true
+					}
+				};
 			} catch (e) {
-				results.push({
-					index: i,
-					tool: step.tool,
+				return {
 					ok: false,
-					error: e instanceof Error ? e.message : String(e)
-				});
-				if (failFast) {
-					stoppedAt = i;
-					break;
-				}
-			}
-			continue;
-		}
-		const healTimeout = opts.healTimeoutMs ?? 3e3;
-		const quickArgs = {
-			...step.args,
-			timeoutMs: Math.min(Number(step.args.timeoutMs ?? Number.POSITIVE_INFINITY) || Number.POSITIVE_INFINITY, healTimeout)
-		};
-		try {
-			await impl(quickArgs);
-			passed++;
-			results.push({
-				index: i,
-				tool: step.tool,
-				ok: true
-			});
-			continue;
-		} catch (e0) {
-			const tried = [];
-			let healed = null;
-			for (const candidate of healCandidates(hint)) {
-				tried.push(`${candidate.via}: ${candidate.selector}`);
-				try {
-					await impl({
-						...step.args,
-						selector: candidate.selector,
-						timeoutMs: healTimeout
-					});
-					healed = candidate;
-					break;
-				} catch {}
+					result: {
+						index: i,
+						tool: step.tool,
+						ok: false,
+						error: e instanceof Error ? e.message : String(e)
+					}
+				};
 			}
-			if (healed !== null) {
-				passed++;
-				healedCount++;
-				results.push({
-					index: i,
-					tool: step.tool,
+			const healTimeout = opts.healTimeoutMs ?? 3e3;
+			const quickArgs = {
+				...step.args,
+				timeoutMs: Math.min(Number(step.args.timeoutMs ?? Number.POSITIVE_INFINITY) || Number.POSITIVE_INFINITY, healTimeout)
+			};
+			try {
+				await impl(quickArgs);
+				return {
 					ok: true,
-					healed: true,
-					via: healed.via,
-					resolved: healed.selector
-				});
-			} else {
+					result: {
+						index: i,
+						tool: step.tool,
+						ok: true
+					}
+				};
+			} catch (e0) {
+				const tried = [];
+				let healed = null;
+				for (const candidate of healCandidates(hint)) {
+					tried.push(`${candidate.via}: ${candidate.selector}`);
+					try {
+						await impl({
+							...step.args,
+							selector: candidate.selector,
+							timeoutMs: healTimeout
+						});
+						healed = candidate;
+						break;
+					} catch {}
+				}
+				if (healed !== null) return {
+					ok: true,
+					result: {
+						index: i,
+						tool: step.tool,
+						ok: true,
+						healed: true,
+						via: healed.via,
+						resolved: healed.selector
+					}
+				};
 				const base = e0 instanceof Error ? e0.message : String(e0);
-				results.push({
-					index: i,
-					tool: step.tool,
+				return {
 					ok: false,
-					error: `${base}${tried.length > 0 ? `; 自愈已尝试: ${tried.join(" | ")}` : ""}`
-				});
-				if (failFast) {
-					stoppedAt = i;
-					break;
-				}
+					result: {
+						index: i,
+						tool: step.tool,
+						ok: false,
+						error: `${base}${tried.length > 0 ? `; 自愈已尝试: ${tried.join(" | ")}` : ""}`
+					}
+				};
+			}
+		};
+		let outcome = await attempt();
+		let recovered = false;
+		if (!outcome.ok && (opts.retryFailed ?? 0) > 0) for (let n = 1; n <= (opts.retryFailed ?? 0); n++) {
+			await sleep(500 * n);
+			retryAttempted++;
+			const again = await attempt();
+			outcome = again;
+			if (again.ok) {
+				recovered = true;
+				break;
+			}
+		}
+		if (outcome.ok) {
+			passed++;
+			if (outcome.result.healed === true) healedCount++;
+			results.push(recovered ? {
+				...outcome.result,
+				recovered: true
+			} : outcome.result);
+		} else {
+			results.push(outcome.result);
+			if (failFast) {
+				stoppedAt = i;
+				break;
 			}
 		}
 	}
@@ -3589,6 +3830,10 @@ async function runReplay(steps, impls, failFast, opts = {}) {
 		passed,
 		failed: results.length - passed,
 		healedCount,
+		...retryAttempted > 0 ? { retries: {
+			attempted: retryAttempted,
+			recovered: results.filter((r) => r.recovered === true).length
+		} } : {},
 		...stoppedAt !== null ? { stoppedAt } : {},
 		results
 	};
@@ -3640,14 +3885,176 @@ function workspaceFilePath(cwd, file) {
 	if (p !== root && !p.startsWith(root + "/") && !p.startsWith(root + "\\")) throw new Error(`文件路径越出工作区: ${file}`);
 	return p;
 }
+/** suggest 的页内结构探测(injectWalker 注入;walker 提供 cssPath)。 */
+const suggestFieldsInPage = injectWalker((payload, w) => {
+	const root = payload.scope !== "" ? document.querySelector(payload.scope) : document.body;
+	if (root === null) return {
+		ok: false,
+		reason: `scope 未命中: 页面中没有匹配 "${payload.scope}" 的元素`
+	};
+	const cellOf = (el) => {
+		const a = el.querySelector("a[href]");
+		const img = el.querySelector("img[src]");
+		return {
+			text: (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ").slice(0, 60),
+			...a !== null ? { href: a.getAttribute("href") ?? "" } : {},
+			...img !== null ? { src: img.getAttribute("src") ?? "" } : {}
+		};
+	};
+	const rows = Array.from(root.querySelectorAll("table tr"));
+	if (rows.length >= 2) {
+		const first = rows[0];
+		let headerTexts = [];
+		let record = null;
+		if (first.querySelector("th") !== null) {
+			headerTexts = Array.from(first.querySelectorAll("th, td")).map((c) => (c.innerText || c.textContent || "").trim());
+			record = rows[1] ?? null;
+		} else record = first;
+		if (record !== null) {
+			const cells = Array.from(record.querySelectorAll("td, th")).map(cellOf);
+			if (cells.length > 0) return {
+				ok: true,
+				kind: "table",
+				rowSelector: "table tr",
+				headerTexts,
+				cells
+			};
+		}
+	}
+	const list = root.querySelector("ul, ol");
+	if (list !== null) {
+		const lis = Array.from(list.children).filter((c) => c.tagName === "LI");
+		if (lis.length >= 2) {
+			const li = lis[0];
+			return {
+				ok: true,
+				kind: "list",
+				rowSelector: `${w.cssPath(list)} > li`,
+				item: cellOf(li)
+			};
+		}
+	}
+	return {
+		ok: false,
+		reason: "未发现规律结构(无 ≥2 行的表格,也无 ≥2 项的列表);请用 browser_elements/browser_snapshot 查看结构后手写 fields",
+		overview: {
+			links: root.querySelectorAll("a").length,
+			images: root.querySelectorAll("img").length,
+			buttons: root.querySelectorAll("button, [role='button']").length,
+			headings: root.querySelectorAll("h1, h2, h3, h4").length,
+			rows: rows.length,
+			textChars: (root.innerText || "").length
+		}
+	};
+});
+/** 字段名净化:空白→下划线,限长 30,空回落 col_N。导出供测试。 */
+function suggestFieldName(header, index) {
+	const h = (header ?? "").trim().replace(/\s+/g, "_");
+	return h !== "" ? h.slice(0, 30) : `col_${index + 1}`;
+}
+/**
+* 纯逻辑:由表头与首行单元格特征推断表格 fields(单元格文本/链接 href/图片 src)。
+* 返回可直接放进 rows.fields 的嵌套字段数组。导出供测试。
+*/
+function fieldsFromCells(headerTexts, cells) {
+	const out = [];
+	cells.forEach((c, i) => {
+		const name = suggestFieldName(headerTexts[i], i);
+		const sel = `td:nth-of-type(${i + 1})`;
+		if (c.src !== void 0) out.push({
+			name: `${name}_src`,
+			selector: `${sel} img`,
+			attr: "src"
+		});
+		if (c.href !== void 0) out.push({
+			name: `${name}_href`,
+			selector: `${sel} a`,
+			attr: "href"
+		});
+		out.push({
+			name,
+			selector: sel
+		});
+	});
+	return out;
+}
+/**
+* 纯逻辑:由首条卡片信息推断列表 fields(项文本/链接/图片)。
+* 文本取第一个子元素(项自身无法用 querySelector 自选)。导出供测试。
+*/
+function fieldsFromCard(item) {
+	const out = [];
+	if (item.src !== void 0) out.push({
+		name: "image",
+		selector: "img",
+		attr: "src"
+	});
+	if (item.href !== void 0) out.push({
+		name: "link",
+		selector: "a",
+		attr: "href"
+	});
+	out.push({
+		name: "text",
+		selector: ":scope > *:nth-child(1)"
+	});
+	return out;
+}
+/** 纯逻辑:由 fields 与单元格样本拼出首行样例(与抽取输出同构;按 td 序号对位)。导出供测试。 */
+function sampleOfFields(fields, cells) {
+	const out = {};
+	for (const f of fields) {
+		const m = /td:nth-of-type\((\d+)\)/.exec(f.selector);
+		const c = cells[m !== null ? Number(m[1]) - 1 : 0];
+		if (f.attr === "href") out[f.name] = c?.href ?? null;
+		else if (f.attr === "src") out[f.name] = c?.src ?? null;
+		else out[f.name] = c?.text ?? null;
+	}
+	return out;
+}
 /**
-* 规则化抽取:fields 定义抽取结构,next 选择器驱动翻页(maxPages 上限),
-* 行数超 maxRows 截断;format/file 控制序列化与落盘(json/csv/jsonl/markdown)。
+* suggest 汇总(纯逻辑):由页内分析结果组装「可直接交给抽取模式」的顶层 fields
+* (单个 multiple rows 字段 + 行内嵌套字段)与样本。推断失败原样返回。导出供测试。
 */
+function suggestWrap(analysis) {
+	if (!analysis.ok || analysis.kind === void 0 || analysis.rowSelector === void 0) return {
+		suggested: false,
+		reason: analysis.reason ?? "结构不足以推断字段",
+		...analysis.overview !== void 0 ? { overview: analysis.overview } : {}
+	};
+	const rowFields = analysis.kind === "table" ? fieldsFromCells(analysis.headerTexts ?? [], analysis.cells ?? []) : fieldsFromCard(analysis.item ?? { text: "" });
+	if (rowFields.length === 0) return {
+		suggested: false,
+		reason: "首条记录内未发现可抽取内容(文本/链接/图片)",
+		...analysis.overview !== void 0 ? { overview: analysis.overview } : {}
+	};
+	const sample = sampleOfFields(rowFields, analysis.kind === "table" ? analysis.cells ?? [] : [analysis.item ?? { text: "" }]);
+	return {
+		suggested: true,
+		kind: analysis.kind,
+		rowSelector: analysis.rowSelector,
+		...analysis.headerTexts !== void 0 ? { headerTexts: analysis.headerTexts } : {},
+		fields: [{
+			name: "rows",
+			selector: analysis.rowSelector,
+			multiple: true,
+			fields: rowFields
+		}],
+		sample
+	};
+}
 async function extractTool(config, args, exec) {
 	const page = await getPage(config);
+	if (args.action === "suggest") {
+		const scope = typeof args.scope === "string" && args.scope !== "" ? args.scope : "";
+		return {
+			action: "suggest",
+			...suggestWrap(await page.evaluate(suggestFieldsInPage, { scope })),
+			...await pageIdentity(page)
+		};
+	}
 	const fields = args.fields;
-	if (!Array.isArray(fields) || fields.length === 0) throw new Error("extract 需要 fields:[{ name, selector, attr?, multiple?, fields? }]");
+	if (!Array.isArray(fields) || fields.length === 0) throw new Error("extract 需要 fields:[{ name, selector, attr?, multiple?, fields? }] 或 action: \"suggest\" 推断字段");
 	for (const f of fields) if (typeof f?.name !== "string" || f.name === "" || typeof f?.selector !== "string" || f.selector === "") throw new Error("fields 每项需要非空 name 与 selector");
 	const maxPages = Math.min(Math.max(Number(args.maxPages ?? 1) || 1, 1), 100);
 	const maxRows = Math.min(Math.max(Number(args.maxRows ?? config.maxRows ?? 1e3) || 1e3, 1), 1e5);
@@ -3858,9 +4265,19 @@ async function replayTool(args, impls, config, exec) {
 	else throw new Error("replay 需要 name(已保存录制)或 steps(步骤数组)");
 	if (steps.length === 0) throw new Error("步骤为空");
 	const failFast = args.failFast !== false;
+	const retryFailed = Math.min(Math.max(Math.floor(Number(args.retryFailed ?? 0)) || 0, 0), 10);
+	const retryOf = typeof args.retryOf === "string" && args.retryOf !== "" ? args.retryOf : void 0;
+	const runMeta = { ...retryFailed > 0 || retryOf !== void 0 ? {
+		...retryFailed > 0 ? { retries: {
+			attempted: 0,
+			recovered: 0
+		} } : {},
+		...retryOf !== void 0 ? { retryOf } : {}
+	} : {} };
 	const opts = {
 		healing: config?.selectorHealing !== false,
-		healTimeoutMs: config?.healTimeoutMs ?? 3e3
+		healTimeoutMs: config?.healTimeoutMs ?? 3e3,
+		...retryFailed > 0 ? { retryFailed } : {}
 	};
 	let rows = null;
 	if (Array.isArray(args.data)) rows = args.data;
@@ -3900,7 +4317,8 @@ async function replayTool(args, impls, config, exec) {
 					healedCount: 0,
 					durationMs: Date.now() - t0,
 					row: i,
-					results: []
+					results: [],
+					...runMeta
 				});
 				continue;
 			}
@@ -3920,7 +4338,9 @@ async function replayTool(args, impls, config, exec) {
 				healedCount: result.healedCount,
 				durationMs: Date.now() - t0,
 				row: i,
-				results: result.results
+				results: result.results,
+				...result.retries ?? runMeta.retries,
+				...runMeta.retryOf !== void 0 ? { retryOf: runMeta.retryOf } : {}
 			});
 		}
 		return {
@@ -3938,6 +4358,7 @@ async function replayTool(args, impls, config, exec) {
 	const t0 = Date.now();
 	const result = await runReplay(substituteVars(steps, vars), impls, failFast, opts);
 	const stoppedAt = result.stoppedAt;
+	const retries = result.retries;
 	noteRun({
 		kind: "replay",
 		source,
@@ -3946,14 +4367,42 @@ async function replayTool(args, impls, config, exec) {
 		failed: result.failed,
 		healedCount: result.healedCount,
 		durationMs: Date.now() - t0,
-		results: result.results
+		results: result.results,
+		...retries !== void 0 ? { retries } : {},
+		...retryOf !== void 0 ? { retryOf } : {}
 	});
 	return {
 		source,
 		...result,
-		summary: `${result.passed}/${result.total} 通过${result.failed > 0 ? `, ${result.failed} 失败${stoppedAt !== void 0 ? `(停在步骤 ${stoppedAt})` : ""}` : ""}${result.healedCount > 0 ? `,${result.healedCount} 步自愈(建议修复录制选择器)` : ""}`
+		summary: `${result.passed}/${result.total} 通过${result.failed > 0 ? `, ${result.failed} 失败${stoppedAt !== void 0 ? `(停在步骤 ${stoppedAt})` : ""}` : ""}${result.healedCount > 0 ? `,${result.healedCount} 步自愈(建议修复录制选择器)` : ""}${retries !== void 0 && retries.recovered > 0 ? `,重试挽回 ${retries.recovered}/${retries.attempted}` : ""}`
 	};
 }
+let rerunHandler = null;
+let rerunInFlight = false;
+/** registerTools 注册重跑入口(stepImpls 同路径);web-only 进程保持 null。 */
+function setRerunHandler(fn) {
+	rerunHandler = fn;
+}
+/** 当前可用的重跑入口(null = 本进程没有 tools 服务,无法重跑)。 */
+function getRerunHandler() {
+	return rerunHandler;
+}
+/** 重跑是否正在执行(端点互斥;导出供测试)。 */
+function rerunBusy() {
+	return rerunInFlight;
+}
+/** 执行一次面板重跑(busy 检查 + 互斥标记;返回 replayTool 结果)。 */
+async function runPanelRerun(req) {
+	if (rerunInFlight) throw Object.assign(/* @__PURE__ */ new Error("重跑进行中"), { status: 409 });
+	rerunInFlight = true;
+	try {
+		const handler = rerunHandler;
+		if (handler === null) throw Object.assign(/* @__PURE__ */ new Error("本进程无回放能力(tools 服务未注册)"), { status: 503 });
+		return await handler(req);
+	} finally {
+		rerunInFlight = false;
+	}
+}
 //#endregion
 //#region lib/types/browser/register.js
 function registerTools(ctx, config) {
@@ -3984,6 +4433,15 @@ function registerTools(ctx, config) {
 		"browser_press"
 	]);
 	/**
+	* auto 审批闸(confirmMode:"auto" 硬约束):live 调用在 register 包装层拦,
+	* replay/batch 在 stepImpls 外再包一层(默认同样拦截;confirmInReplay: false
+	* 可关,README 注明风险)。未命中模式时闸内只花一次页内 evaluate。
+	*/
+	const replayGate = (tool, fn) => async (a) => {
+		if (config.confirmMode === "auto" && config.confirmInReplay !== false) await confirmGate(config, tool, a);
+		return fn(a);
+	};
+	/**
 	* toolset: "core" 的高频核心集:浏览/定位/操作/等待/断言/人机协作。
 	* 低频的录制/回放/报告/抽取/表单回放/profile/context 等只在 "all" 注册。
 	*/
@@ -4019,8 +4477,10 @@ function registerTools(ctx, config) {
 		const original = def.execute;
 		def.execute = async (args, exec) => {
 			const t0 = Date.now();
+			noteToolStart();
 			const domTool = AGENT_DOM_TOOLS.has(def.name);
 			if (domTool) noteAgentAction();
+			if (config.confirmMode === "auto") await confirmGate(config, def.name, args);
 			if (PREVIEW_TOOLS.has(def.name)) {
 				const page = activePage();
 				previewHighlight(page, typeof args?.selector === "string" && args.selector ? args.selector : typeof args?.ref === "string" && args.ref && page !== null ? pageRef(page, args.ref)?.selector ?? "" : "", def.name.replace("browser_", ""));
@@ -4053,6 +4513,8 @@ function registerTools(ctx, config) {
 					error: error instanceof Error ? error.message : String(error)
 				});
 				throw error;
+			} finally {
+				noteToolEnd();
 			}
 		};
 		tools.register(def);
@@ -4095,6 +4557,14 @@ function registerTools(ctx, config) {
 		browser_batch: (a) => batchTool(a, stepImpls, config),
 		browser_extract: (a) => extractTool(config, a)
 	};
+	for (const name of Object.keys(stepImpls)) {
+		const fn = stepImpls[name];
+		stepImpls[name] = replayGate(name, fn);
+	}
+	setRerunHandler((req) => replayTool({
+		name: req.source,
+		...req.retryOf !== void 0 ? { retryOf: req.retryOf } : {}
+	}, stepImpls, config));
 	register(definePlainTool({
 		name: "browser_open",
 		description: "在共享浏览器中打开一个 URL。之后可用 browser_snapshot 读取页面内容,用 browser_click / browser_type / browser_eval 操作页面,用 browser_screenshot 截图。",
@@ -4143,7 +4613,7 @@ function registerTools(ctx, config) {
 	}));
 	register(definePlainTool({
 		name: "browser_snapshot",
-		description: "读取当前页面快照(不截图)。mode:'text'(默认)返回压缩后的可见文本+链接清单,适合读内容;'aria' 返回可访问性树,可交互元素带 [ref=eN] 短引用,后续 browser_click/browser_type/browser_select/browser_press 可直接传 ref 代替 CSS 选择器(导航或重新快照后旧 ref 失效)。maxTextChars 默认 20000。scope:可选 CSS 选择器,只对命中的容器区域提取(text/aria 两种模式都生效,scope 未命中报错)。since:增量模式,传上次快照返回的 contentVersion——内容未变返回 { unchanged: true },变了只返回变化的行(diff: true, changedFrom/removed 标注变化区),表格翻页/局部刷新后重读 token 开销可降一个量级;since 过期则回落全量并标 stale。",
+		description: "读取当前页面快照(不截图)。mode:'text'(默认)返回压缩后的可见文本+链接清单,适合读内容;'aria' 返回可访问性树,可交互元素带 [ref=eN] 短引用,后续 browser_click/browser_type/browser_select/browser_press 可直接传 ref 代替 CSS 选择器(导航或重新快照后旧 ref 失效)。maxTextChars 默认 20000。scope:可选 CSS 选择器,只对命中的容器区域提取(text/aria 两种模式都生效,scope 未命中报错)。since:增量模式,传之前任一次快照返回的 contentVersion——历史版本环形缓存(snapshotHistory 默认 5,可配 1-20)窗口内的任意版本都能 diff:内容未变返回 { unchanged: true },变了只返回相对该版本的变化行(diff: true, changedFrom/removed 标注变化区),表格翻页/局部刷新/轮询抓取后重读 token 开销可降一个量级;since 超出窗口(过旧/未知)则回落全量并标 stale。",
 		parameters: {
 			type: "object",
 			properties: {
@@ -4158,7 +4628,7 @@ function registerTools(ctx, config) {
 				},
 				since: {
 					type: "integer",
-					description: "可选:上次快照的 contentVersion,只返回变化内容。"
+					description: "可选:之前任一次快照的 contentVersion(历史窗口内任意版本),只返回相对该版本的变化内容。"
 				},
 				maxTextChars: {
 					type: "integer",
@@ -5067,7 +5537,7 @@ function registerTools(ctx, config) {
 	}));
 	register(definePlainTool({
 		name: "browser_find",
-		description: "按名称/id/data-testid 语义定位页面元素,只返回命中的 ref + 区域上下文,不输出全量 aria 树 —— 在大页面定位单个操作目标时比 browser_snapshot { mode: \"aria\" } 省 95% 以上 token。返回的 ref 可直接传给 browser_click / browser_type / browser_select / browser_press。默认包含匹配(query 是名称子串,忽略大小写;exact:true 精确匹配);scope 限定查找容器;多命中全部返回并附 ancestors 区域链供二次定位;零命中不抛错,返回最相近的 suggestions 候选。",
+		description: "按名称/id/data-testid/组件名/源码文件语义定位页面元素,只返回命中的 ref + 区域上下文,不输出全量 aria 树 —— 在大页面定位单个操作目标时比 browser_snapshot { mode: \"aria\" } 省 95% 以上 token。原生支持 Ant Design Vue / Element Plus / Naive UI 等组件库与 @xiaou66/vite-plugin-vue-mcp-next 源码映射。返回的 ref 可直接传给 browser_click / browser_type / browser_select / browser_press。默认包含匹配(query 是名称子串,忽略大小写;exact:true 精确匹配);scope 限定查找容器;多命中全部返回并附 ancestors 区域链供二次定位;零命中不抛错,返回最相近的 suggestions 候选。",
 		parameters: {
 			type: "object",
 			properties: {
@@ -5082,6 +5552,18 @@ function registerTools(ctx, config) {
 				scope: {
 					type: "string",
 					description: "可选:限定查找的容器 CSS 选择器(如 '#login-form')。"
+				},
+				component: {
+					type: "string",
+					description: "可选:按组件名查找(如 'ASelect', 'ElSelect', '*Select')。"
+				},
+				library: {
+					type: "string",
+					description: "可选:按组件库筛选(如 'ant-design-vue', 'element-plus')。"
+				},
+				file: {
+					type: "string",
+					description: "可选:按 Vue SFC 源码文件名筛选(如 'Login.vue')。"
 				}
 			},
 			required: ["query"],
@@ -5103,7 +5585,11 @@ function registerTools(ctx, config) {
 							ancestors: {
 								type: "array",
 								items: { type: "string" }
-							}
+							},
+							library: { type: "string" },
+							component: { type: "string" },
+							sourceFile: { type: "string" },
+							formLabel: { type: "string" }
 						},
 						required: [
 							"ref",
@@ -5562,7 +6048,7 @@ function registerTools(ctx, config) {
 	}));
 	register(definePlainTool({
 		name: "browser_replay",
-		description: "回放录制或步骤序列(回归测试):name 指定已保存录制(browser_record save),或直接传 steps 数组(每步 {tool, args})。failFast 默认 true(遇错停止);返回每步结果与汇总。选择器自愈:录制时保存了元素指纹的步骤,原 selector 失败时自动按 testid→role+name→text→id 降级重试并在结果中标 healed(建议事后修复录制选择器)。参数化:录制含 {{占位符}} 时用 vars 注入;data 传对象数组或 dataFile 传 CSV 路径(首行为变量名)可逐行数据驱动回放。运行结果自动记入回归历史(browser_report 可导出报告)。",
+		description: "回放录制或步骤序列(回归测试):name 指定已保存录制(browser_record save),或直接传 steps 数组(每步 {tool, args})。failFast 默认 true(遇错停止);返回每步结果与汇总。选择器自愈:录制时保存了元素指纹的步骤,原 selector 失败时自动按 testid→role+name→text→id 降级重试并在结果中标 healed(建议事后修复录制选择器)。参数化:录制含 {{占位符}} 时用 vars 注入;data 传对象数组或 dataFile 传 CSV 路径(首行为变量名)可逐行数据驱动回放。retryFailed: N 使失败步骤(自愈链耗尽后)自动重试 N 次(500ms×n 线性退避,重试耗尽才停),返回值 retries 标注 { attempted, recovered }。运行结果自动记入回归历史(browser_report 可导出报告)。",
 		parameters: {
 			type: "object",
 			properties: {
@@ -5591,6 +6077,10 @@ function registerTools(ctx, config) {
 				dataFile: {
 					type: "string",
 					description: "数据集 CSV 文件(工作区相对路径,首行为变量名)。"
+				},
+				retryFailed: {
+					type: "integer",
+					description: "失败步骤自动重试次数(0-10,默认 0;500ms×n 线性退避,重试耗尽才停)。偶发超时/网络抖动类失败的兜底。"
 				}
 			},
 			additionalProperties: false
@@ -5604,6 +6094,10 @@ function registerTools(ctx, config) {
 				passed: { type: "integer" },
 				failed: { type: "integer" },
 				healedCount: { type: "integer" },
+				retries: {
+					type: "object",
+					description: "自动重试统计 { attempted, recovered }(仅 retryFailed>0 时返回)。"
+				},
 				stoppedAt: { type: "integer" },
 				results: {
 					type: "array",
@@ -5629,7 +6123,7 @@ function registerTools(ctx, config) {
 			]
 		},
 		render: (_args, value) => {
-			return value.runs !== void 0 ? `${value.summary}\n${value.runs.map((r) => `${(r.failed ?? 0) === 0 ? "✓" : "✗"} 行${r.row}${r.error ? ` — ${String(r.error).slice(0, 100)}` : ` ${r.passed}/${r.total}`}`).join("\n")}` : `${value.summary}\n${(value.results ?? []).map((r) => `${r.ok ? "✓" : "✗"} #${r.index} ${r.tool}${r.healed ? ` [自愈:${r.via}]` : ""}${r.error ? ` — ${String(r.error).slice(0, 120)}` : ""}`).join("\n")}`;
+			return value.runs !== void 0 ? `${value.summary}\n${value.runs.map((r) => `${(r.failed ?? 0) === 0 ? "✓" : "✗"} 行${r.row}${r.error ? ` — ${String(r.error).slice(0, 100)}` : ` ${r.passed}/${r.total}`}`).join("\n")}` : `${value.summary}\n${(value.results ?? []).map((r) => `${r.ok ? "✓" : "✗"} #${r.index} ${r.tool}${r.healed ? ` [自愈:${r.via}]` : ""}${r.recovered ? " [重试挽回]" : ""}${r.error ? ` — ${String(r.error).slice(0, 120)}` : ""}`).join("\n")}`;
 		},
 		timeoutMs: timeout(6e5),
 		execute: (args, exec) => replayTool(args, stepImpls, config, exec)
@@ -5683,14 +6177,23 @@ function registerTools(ctx, config) {
 	}));
 	register(definePlainTool({
 		name: "browser_extract",
-		description: "规则化结构化抽取(网站信息获取):fields 定义抽取结构 [{name, selector, attr?, multiple?, fields?}](attr 缺省取可见文本,可指定 href/src 等属性;multiple=true 收集所有命中;fields 嵌套可在行内抽子字段);next 传翻页选择器自动翻页聚合(maxPages 上限,next 消失/禁用即停);format 支持 json/csv/jsonl/markdown,file 落盘到工作区(自动按扩展名推断格式,拒绝路径穿越)。语义化抽取(如「总结要点」)不在此工具范围——用 browser_snapshot 读文本后交 jev_extract。",
+		description: "规则化结构化抽取(网站信息获取):fields 定义抽取结构 [{name, selector, attr?, multiple?, fields?}](attr 缺省取可见文本,可指定 href/src 等属性;multiple=true 收集所有命中;fields 嵌套可在行内抽子字段);next 传翻页选择器自动翻页聚合(maxPages 上限,next 消失/禁用即停);format 支持 json/csv/jsonl/markdown,file 落盘到工作区(自动按扩展名推断格式,拒绝路径穿越)。action:\"suggest\"(不传 fields)自动推断字段:从命中容器首条记录(表格首行/列表卡片)推断单元格文本/链接 href/图片 src 结构,返回建议 fields + 首行样本,确认/微调后直接交给抽取模式(往返 3-4 次降到 2 次);推断不出规律结构时返回原因与容器元素概览,不猜。语义化抽取(如「总结要点」)不在此工具范围——用 browser_snapshot 读文本后交 jev_extract。",
 		parameters: {
 			type: "object",
 			properties: {
+				action: {
+					type: "string",
+					enum: ["suggest"],
+					description: "suggest:自动推断字段结构,返回建议 fields + 样本(此模式不传 fields)。"
+				},
+				scope: {
+					type: "string",
+					description: "suggest 模式的容器选择器(缺省整页;表格/列表探测在此范围内进行)。"
+				},
 				fields: {
 					type: "array",
 					items: { type: "object" },
-					description: "抽取字段定义 [{name, selector, attr?, multiple?, fields?}]。"
+					description: "抽取字段定义 [{name, selector, attr?, multiple?, fields?}](action:suggest 时不传)。"
 				},
 				next: {
 					type: "string",
@@ -5723,13 +6226,28 @@ function registerTools(ctx, config) {
 					description: "落盘路径(工作区相对或绝对,限工作区内)。"
 				}
 			},
-			required: ["fields"],
+			required: [],
 			additionalProperties: false
 		},
 		outputSchema: {
 			type: "object",
 			additionalProperties: false,
 			properties: {
+				action: { type: "string" },
+				suggested: { type: "boolean" },
+				kind: { type: "string" },
+				rowSelector: { type: "string" },
+				headerTexts: {
+					type: "array",
+					items: { type: "string" }
+				},
+				fields: {
+					type: "array",
+					items: { type: "object" }
+				},
+				sample: { type: "object" },
+				reason: { type: "string" },
+				overview: { type: "object" },
 				rows: {
 					type: "array",
 					items: { type: "object" }
@@ -5743,17 +6261,9 @@ function registerTools(ctx, config) {
 				url: { type: "string" },
 				title: { type: "string" }
 			},
-			required: [
-				"rows",
-				"count",
-				"pages",
-				"format",
-				"truncated",
-				"url",
-				"title"
-			]
+			required: ["url", "title"]
 		},
-		render: (_args, value) => `抽取 ${value.count} 行 / ${value.pages} 页${value.truncated ? "(已截断)" : ""}${value.file ? ` → ${value.file} (${value.bytes} bytes)` : ""}`,
+		render: (_args, value) => value.action === "suggest" ? value.suggested ? `字段建议(${value.kind}):行选择器 ${value.rowSelector},${value.fields[0].fields.length} 个字段;样例 ${JSON.stringify(value.sample).slice(0, 120)}` : `字段建议失败: ${String(value.reason).slice(0, 120)}` : `抽取 ${value.count} 行 / ${value.pages} 页${value.truncated ? "(已截断)" : ""}${value.file ? ` → ${value.file} (${value.bytes} bytes)` : ""}`,
 		timeoutMs: timeout(),
 		execute: (args, exec) => extractTool(config, args, exec)
 	}));
@@ -5866,7 +6376,42 @@ function registerBrowserApi(ctx, config, base) {
 				return;
 			}
 			if (path === `${base}/runs/latest`) {
-				sendJson(res, 200, { run: latestRun() });
+				sendJson(res, 200, {
+					run: latestRun(),
+					busy: activeToolCalls() > 0 || rerunBusy()
+				});
+				return;
+			}
+			if (path === `${base}/runs/rerun`) {
+				if ((req.method ?? "GET") !== "POST") {
+					sendText(res, 405, "POST only");
+					return;
+				}
+				if (activeToolCalls() > 0 || rerunBusy()) {
+					sendJson(res, 409, { error: "agent 忙碌(有工具调用或回放在进行),稍后重试" });
+					return;
+				}
+				if (getRerunHandler() === null) {
+					sendJson(res, 503, { error: "本进程无回放能力(tools 服务未注册)" });
+					return;
+				}
+				const body = await readJsonBody(req).catch(() => void 0);
+				const source = typeof body?.source === "string" ? body.source.trim() : "";
+				if (!source) {
+					sendJson(res, 400, "source required");
+					return;
+				}
+				try {
+					sendJson(res, 200, {
+						ok: true,
+						result: await runPanelRerun({
+							source,
+							...typeof body?.retryOf === "string" && body.retryOf !== "" ? { retryOf: body.retryOf } : {}
+						})
+					});
+				} catch (e) {
+					sendJson(res, 500, { error: e instanceof Error ? e.message : String(e) });
+				}
 				return;
 			}
 			if (path === `${base}/runs/report`) {
@@ -6266,14 +6811,26 @@ const SCHEMA = {
 		type: "number",
 		min: 1
 	},
+	snapshotHistory: {
+		type: "number",
+		min: 1,
+		max: 20
+	},
 	confirmMode: {
 		type: "string",
-		enum: ["off", "manual"]
+		enum: [
+			"off",
+			"manual",
+			"auto"
+		]
 	},
 	confirmTimeoutMs: {
 		type: "number",
 		min: 1e3
 	},
+	sensitivePatterns: { type: "string[]" },
+	sensitiveTools: { type: "string[]" },
+	confirmInReplay: { type: "boolean" },
 	toolset: {
 		type: "string",
 		enum: ["core", "all"]
@@ -6300,8 +6857,16 @@ const DEFAULT_CONFIG = {
 	healTimeoutMs: 3e3,
 	maxRefs: 200,
 	maxRows: 1e3,
+	snapshotHistory: 5,
 	confirmMode: "off",
 	confirmTimeoutMs: 6e4,
+	sensitivePatterns: [
+		"提交",
+		"删除",
+		"支付"
+	],
+	sensitiveTools: ["browser_click"],
+	confirmInReplay: true,
 	toolset: "all"
 };
 function apply(ctx, rawConfig) {
@@ -6313,7 +6878,7 @@ function apply(ctx, rawConfig) {
 	if (loadedRecordings > 0) ctx.logger?.info?.(`dsh-browser-view: loaded ${loadedRecordings} saved recording(s)`);
 	registerTools(ctx, config);
 	const systemPrompt = ctx.get("systemPrompt");
-	const confirmGuidance = config.confirmMode === "manual" ? "本环境 confirmMode 为 manual:凡提交/删除/支付等不可逆或影响线上数据的敏感动作,执行前必须先调用 browser_confirm(reason 说明操作与影响,等待用户在实时画面面板点允许/拒绝;拒绝或超时即放弃该动作,不得换路径绕过)。" : "";
+	const confirmGuidance = config.confirmMode === "manual" ? "本环境 confirmMode 为 manual:凡提交/删除/支付等不可逆或影响线上数据的敏感动作,执行前必须先调用 browser_confirm(reason 说明操作与影响,等待用户在实时画面面板点允许/拒绝;拒绝或超时即放弃该动作,不得换路径绕过)。" : config.confirmMode === "auto" ? "本环境 confirmMode 为 auto:宿主层已在敏感动作(命中敏感模式的目标元素)前强制弹审批卡,agent 无法绕过;审批被拒绝或超时的动作不可换路径重试,应向用户说明并等待指示。" : "";
 	const sectionDispose = systemPrompt?.section?.({
 		name: "tool:browser",
 		order: 200,