agentpage 0.0.20 → 0.0.22

package/dist/index.mjs

@@ -90,7 +90,8 @@ function hasToolError(result) {
 * 压缩/剪枝是怎么做的（中）/ How compression & pruning works in practice (EN):
 * - `viewportOnly=true` 时：仅保留与视口相交元素（根层容器保留），完全视口外元素跳过。
 * - `pruneLayout=true` 时：无 id/无语义/无交互/无直接文本的布局容器会被“折叠”，
-*   子节点直接提升输出，减少无意义层级。
+*   子节点直接提升输出，减少无意义层级；当同一折叠容器提升出多个相邻节点时，
+*   快照会用括号分组块标记其关联来源（collapsed-group）。
 * - `maxNodes`：全局节点预算，超限后停止继续遍历并追加 truncation 提示。
 * - `maxChildren`：每个父节点只保留前 N 个子元素，其余用 `... (n children omitted)` 汇总。
 * - `maxTextLength`：节点文本按长度截断，避免长段文案占满上下文。
@@ -215,7 +216,7 @@ function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, hi
 			activeInstruction
 		];
 		if (currentUrl) parts.push("", `URL: ${currentUrl}`);
-		if (latestSnapshot) parts.push("", "## Current page snapshot", "Apply task-reduction model directly from this snapshot. Do NOT restate the task.", "Use hash IDs (e.g. #a1b2c) from the snapshot as selector params.", "Do NOT call page_info (get_url/get_title/query_all/snapshot).", "Batch independent visible actions in one round.", "If action changes DOM (open modal/navigate), stop that batch and continue next round.", "For dropdown/select fields, use dom with action=select_option (or fill on a select).", allowAgentUiInteraction ? "User explicitly asked to operate AutoPilot UI. You may interact with chat input/send/dock only as requested." : "Do NOT interact with any AI chat UI elements (chat input, send button, dock). Only operate on the actual page content.", "Output one line: REMAINING: <new remaining task after this round> or REMAINING: DONE", wrapSnapshot(latestSnapshot));
+		if (latestSnapshot) parts.push("", "## Current page snapshot", "Apply task-reduction model directly from this snapshot. Do NOT restate the task.", "Use hash IDs (e.g. #a1b2c) from the snapshot as selector params.", "Do NOT call page_info (get_url/get_title/query_all/snapshot).", "Batch independent visible actions in one round.", "Build the minimal action array from current snapshot to finish this remaining instruction in one round whenever possible.", "For deterministic increase/decrease controls, compute delta from current visible value and issue exactly that many clicks in one round (e.g., +2 => two increase clicks). Do not overshoot then undo.", "If action changes DOM (open modal/navigate), stop that batch and continue next round.", "For dropdown/select fields, use dom with action=select_option (or fill on a select).", "Stop rule: once requested state is reached, stop tool calls. If verification is needed, verify once and then output REMAINING: DONE.", allowAgentUiInteraction ? "User explicitly asked to operate AutoPilot UI. You may interact with chat input/send/dock only as requested." : "Do NOT interact with any AI chat UI elements (chat input, send button, dock). Only operate on the actual page content.", "Output one line: REMAINING: <new remaining task after this round> or REMAINING: DONE", wrapSnapshot(latestSnapshot));
 		if (protocolViolationHint) parts.push("", protocolViolationHint);
 		messages.push({
 			role: "user",
@@ -251,6 +252,9 @@ function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, hi
 		"If action changes DOM (open modal/navigate), stop after that batch and continue next round.",
 		"Do NOT call page_info (get_url/get_title/query_all/snapshot).",
 		"For dropdown/select fields, use dom with action=select_option (or fill on a select).",
+		"Build the minimal action array from current snapshot to finish this remaining instruction in one round whenever possible.",
+		"For deterministic increase/decrease controls, compute delta from current visible value and issue exactly that many clicks in one round (e.g., +2 => two increase clicks). Do not overshoot then undo.",
+		"Stop rule: once requested state is reached, stop tool calls. If verification is needed, verify once and then output REMAINING: DONE.",
 		allowAgentUiInteraction ? "User explicitly asked to operate AutoPilot UI. You may interact with chat input/send/dock only as requested." : "Do NOT interact with any AI chat UI elements (chat input, send button, dock). Only operate on the actual page content."
 	];
 	if (hasErrors) contextParts.push("", "The last step failed. Retry with a different approach, or skip and continue with other visible targets.");
@@ -372,15 +376,21 @@ async function handleNavigationUrlChange(toolName, toolInput, result, registry,
 		pageContext.latestSnapshot = await readPageSnapshot(registry);
 	}
 }
-/** 只读工具集合（中）/ Read-only tool set (EN). */
+/** 只读工具集合。 */
 const READ_ONLY_TOOLS = new Set(["page_info"]);
+/** DOM 只读动作集合。 */
+const READ_ONLY_DOM_ACTIONS = new Set(["get_text", "get_attr"]);
 /**
-* 空转检测（中）/ Detect idle loops dominated by read-only actions (EN).
+* 空转检测：识别连续只读轮次并终止。
 * 返回 -1 表示应终止循环。
-* Returns -1 when loop should terminate.
 */
-function detectIdleLoop(toolCallNames, consecutiveReadOnlyRounds) {
-	if (toolCallNames.every((name) => READ_ONLY_TOOLS.has(name))) {
+function detectIdleLoop(toolCalls, consecutiveReadOnlyRounds) {
+	if (toolCalls.length > 0 && toolCalls.every(({ name, input }) => {
+		if (READ_ONLY_TOOLS.has(name)) return true;
+		if (name !== "dom") return false;
+		const action = getToolAction(input);
+		return Boolean(action && READ_ONLY_DOM_ACTIONS.has(action));
+	})) {
 		const newCount = consecutiveReadOnlyRounds + 1;
 		return newCount >= 2 ? -1 : newCount;
 	}
@@ -390,10 +400,10 @@ function detectIdleLoop(toolCallNames, consecutiveReadOnlyRounds) {
 //#endregion
 //#region src/core/agent-loop/index.ts
 /**
-* Agent Loop 主流程（中）/ Core environment-agnostic agent loop (EN).
+* Agent Loop 主流程
 *
 * 负责消息构建、AI 决策、工具执行、恢复保护与指标汇总。
-* Orchestrates message build, AI decisions, tool execution, recovery, and metrics.
+* 
 *
 * 流程图（文本）：
 *
@@ -510,15 +520,18 @@ async function executeAgentLoop(params) {
 		return (trimmed.split(/\n\s*\n/)[0]?.trim() ?? trimmed).slice(0, 220);
 	};
 	/**
-	* 判定动作是否会触发 DOM 结构变化（中）/ Whether action may cause DOM-shape change (EN).
+	* 判定动作是否会触发 DOM 结构变化（
 	*
 	* 触发后应强制断轮，等待下一轮新快照继续。
-	* Force round break after such action and continue with refreshed snapshot next round.
+	* 
 	*/
 	const shouldForceRoundBreak = (toolName, toolInput) => {
 		const action = getToolAction(toolInput);
 		if (toolName === "navigate") return action === "goto" || action === "back" || action === "forward" || action === "reload";
-		if (toolName === "dom") return action === "click" || action === "press";
+		if (toolName === "dom") {
+			if (action === "press") return (typeof toolInput === "object" && toolInput !== null ? String(toolInput.key ?? toolInput.value ?? "") : "") === "Enter";
+			return false;
+		}
 		if (toolName === "evaluate") return true;
 		return false;
 	};
@@ -720,9 +733,12 @@ async function executeAgentLoop(params) {
 		lastRoundHadError = roundHasError;
 		previousRoundTasks = buildTaskArray(executedTaskCalls);
 		previousRoundPlannedTasks = plannedTasksCurrentRound;
-		const idleResult = detectIdleLoop(executedTaskCalls.map((tc) => tc.name), consecutiveReadOnlyRounds);
+		const idleResult = detectIdleLoop(response.toolCalls.map((tc) => ({
+			name: tc.name,
+			input: tc.input
+		})), consecutiveReadOnlyRounds);
 		if (idleResult === -1) {
-			finalReply = response.text || "任务已完成。";
+			finalReply = response.text?.trim() || "任务已完成。";
 			if (finalReply) callbacks?.onText?.(finalReply);
 			break;
 		}
@@ -1304,6 +1320,14 @@ var ToolRegistry = class {
 	getDefinitions() {
 		return Array.from(this.tools.values());
 	}
+	/** 按名称检查工具是否已注册。 */
+	has(name) {
+		return this.tools.has(name);
+	}
+	/** 按名称注销工具，返回是否删除成功。 */
+	unregister(name) {
+		return this.tools.delete(name);
+	}
 	/**
 	* 根据工具名分发并执行工具调用。
 	* - 找到工具 → 执行 execute() → 返回结果
@@ -1338,23 +1362,17 @@ var ToolRegistry = class {
 
 //#endregion
 //#region src/core/system-prompt.ts
-/**
-* 规范化额外指令（中）/ Normalize additional instructions (EN).
-*/
+/** 规范化额外指令。 */
 function normalizeExtraInstructions(input) {
 	if (!input) return [];
 	return (Array.isArray(input) ? input : [input]).map((s) => s.trim()).filter(Boolean);
 }
 /**
-* 构建系统提示词（中）/ Build system prompt (EN).
+* 构建系统提示词。
 *
 * 约束：
 * - 输出给模型的提示词正文统一为英文。
-* - 中文仅用于代码注释，便于团队维护。
-*
-* Constraints:
-* - Prompt text sent to model stays English-only.
-* - Chinese content is used in code comments only for maintainability.
+* - 中文仅用于源码注释，便于团队维护。
 */
 function buildSystemPrompt(params = {}) {
 	const sections = [];
@@ -1368,13 +1386,19 @@ function buildSystemPrompt(params = {}) {
 		"  Output: new remaining task after removing this-round actions.",
 		"- Use only visible targets from snapshot. Use #hashID as selector. Do not guess CSS selectors.",
 		"- Batch independent visible actions in one round. Do not split one form into many rounds unnecessarily.",
-		"- Strict input order: before every fill/type/select_option, first click or focus the same target in the SAME round.",
-		"- Fixed sequence examples: dom.click(#field) -> dom.fill(#field, \"text\"); dom.click(#select) -> dom.select_option(#select, ...).",
+		"- Strict input order (MANDATORY): before every fill/type/select_option, click or focus the SAME target immediately in the SAME round.",
+		"- Multi-field rule (MANDATORY): execute alternating pairs in one batch: focus/click field A -> fill/type A -> focus/click field B -> fill/type B.",
+		"- Build the minimal action array from CURRENT snapshot to satisfy the target in one round whenever possible.",
+		"- Do NOT run focus-only batches (e.g., focus A -> focus B). Each focused input/select target must be followed by its input/select action right away.",
+		"- Fixed sequence examples: dom.focus(#name) -> dom.fill(#name, \"new-name\") -> dom.focus(#desc) -> dom.fill(#desc, \"new-desc\"); dom.click(#select) -> dom.select_option(#select, ...).",
+		"- Deterministic delta rule: for increase/decrease steppers, compute target delta from visible current value and emit exactly |delta| clicks in one round (e.g., +2 => click increase twice). Never overshoot then undo.",
+		"- For check/uncheck, target the real input control (checkbox/radio), not nearby text/container nodes.",
 		"- Form batch rule: for one visible form, complete all independent fields in one round; do not fill one field then verify repeatedly.",
 		"- If an action will change DOM (open modal, navigate), stop after that action batch and continue next round with new snapshot.",
 		"- Do NOT call page_info (snapshot/query/get_url/get_title). Snapshot is already provided every round.",
 		"- For dropdown/select, use dom action=select_option (or fill on select).",
 		"- Verification whitelist: do NOT use get_text/get_attr to verify input/select values unless the user explicitly asks for verification.",
+		"- Stop rule: when the requested state is achieved, stop calling tools. If verification is requested, verify once and then return REMAINING: DONE (no repeated get_text/get_attr on the same target).",
 		"- Do NOT interact with AutoPilot UI unless user explicitly asks.",
 		"",
 		"## Output Contract",
@@ -1406,41 +1430,93 @@ function buildSystemPrompt(params = {}) {
 //#endregion
 //#region src/web/tools/dom-tool.ts
 /**
-* DOM Tool — 基于 Web API 的 DOM 操作工具。
+* DOM Tool — 浏览器 DOM 操作工具（结合 Playwright 核心交互模式增强）。
 *
-* 替代 Playwright 的 click/fill/type 等操作，直接在页面上下文中执行。
-* 运行环境：浏览器 Content Script。
+* 关键改进（参考 Playwright）：
+* 1. retarget — 点击时自动重定向到 button/link/label.control
+* 2. scrollIntoView 多策略 — 4 种 block 对齐轮换，解决 sticky 遮挡
+* 3. stable 检查 — rAF 逐帧检测元素位置稳定后再操作
+* 4. hit-target 验证 — elementsFromPoint 检查是否被遮挡
+* 5. 完整点击事件链 — pointermove→pointerdown→mousedown→pointerup→mouseup→click
+* 6. check/uncheck 通过 click — 先检查→click 切换→验证状态
+* 7. press 组合键 — 支持 Control+a, Shift+Enter 等修饰键
+* 8. fill 分类型 — date/color/range 走 setValue，text 类走 selectAll+原生写入
+* 9. 自定义下拉增强 — 更广泛的 option 选择器 + 等待弹出
+* 10. ARIA disabled — 检查祖先链 aria-disabled
 *
-* 支持 15 种动作：
-*   click        — 点击元素
-*   fill         — 填写可编辑控件（input/textarea/select/contenteditable）
-*   select_option — 选择下拉框选项（value/label）
-*   clear        — 清空输入控件
-*   check        — 勾选 checkbox/radio
-*   uncheck      — 取消勾选 checkbox
-*   type         — 逐字符模拟键入
-*   focus        — 聚焦元素
-*   hover        — 鼠标悬停（触发 mouseenter/mouseover）
-*   press        — 按下键盘按键（Enter/Escape/Tab/ArrowDown 等）
-*   get_text     — 获取元素文本内容
-*   get_attr     — 获取元素属性值
-*   set_attr     — 设置元素属性
-*   add_class    — 添加 CSS 类名
-*   remove_class — 移除 CSS 类名
+* 运行环境：浏览器 Content Script（直接访问 DOM，无 CDP）。
 */
-const DEFAULT_WAIT_MS = 1e3;
-/** 当前活跃的 RefStore 实例（由 WebAgent 在 chat() 时设置） */
+const DEFAULT_WAIT_MS = 2e3;
+/** scrollIntoView 轮换策略（参考 Playwright dom.ts） */
+const SCROLL_OPTIONS = [
+	void 0,
+	{
+		block: "end",
+		inline: "end"
+	},
+	{
+		block: "center",
+		inline: "center"
+	},
+	{
+		block: "start",
+		inline: "start"
+	}
+];
+/** fill 时直接 setValue 的 input 类型（参考 Playwright kInputTypesToSetValue） */
+const INPUT_SET_VALUE_TYPES = new Set([
+	"color",
+	"date",
+	"time",
+	"datetime-local",
+	"month",
+	"range",
+	"week"
+]);
+/** 不可 fill 的 input 类型 */
+const INPUT_BLOCKED_TYPES = new Set([
+	"checkbox",
+	"radio",
+	"file",
+	"button",
+	"submit",
+	"reset",
+	"image"
+]);
+/** 键名→code 映射 */
+const KEY_CODE_MAP = {
+	Enter: "Enter",
+	Escape: "Escape",
+	Esc: "Escape",
+	Tab: "Tab",
+	Space: "Space",
+	" ": "Space",
+	Backspace: "Backspace",
+	Delete: "Delete",
+	ArrowUp: "ArrowUp",
+	ArrowDown: "ArrowDown",
+	ArrowLeft: "ArrowLeft",
+	ArrowRight: "ArrowRight",
+	Home: "Home",
+	End: "End",
+	PageUp: "PageUp",
+	PageDown: "PageDown",
+	Control: "ControlLeft",
+	Shift: "ShiftLeft",
+	Alt: "AltLeft",
+	Meta: "MetaLeft"
+};
 let activeRefStore;
+function setActiveRefStore(store) {
+	activeRefStore = store;
+}
+function getActiveRefStore() {
+	return activeRefStore;
+}
 function sleep(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
+	return new Promise((r) => setTimeout(r, ms));
 }
-/**
-* 安全地查询 DOM 元素。
-*
-* 支持两种定位方式（优先级从高到低）：
-* - hash ID（以 "#" 开头且在 RefStore 中存在）：确定性 hash 查找（最高效）
-* - CSS 选择器（其他）：传统 querySelector
-*/
+/** 查询元素：优先 RefStore hash，回退 CSS 选择器 */
 function queryElement(selector) {
 	try {
 		if (selector.startsWith("#") && activeRefStore) {
@@ -1458,28 +1534,13 @@ function queryElement(selector) {
 		return `选择器语法错误: ${selector}`;
 	}
 }
-/**
-* 设置当前活跃的 RefStore（由 WebAgent 在 chat 开始时调用）。
-*/
-function setActiveRefStore(store) {
-	activeRefStore = store;
-}
-/** 获取当前活跃的 RefStore（供其他工具复用） */
-function getActiveRefStore() {
-	return activeRefStore;
-}
-/**
-* 在给定超时时间内轮询查找元素。
-* - 返回 Element：找到元素
-* - 返回 string：选择器语法错误
-* - 返回 null：超时未找到
-*/
+/** 轮询等待元素出现 */
 async function waitForElement(selector, timeoutMs) {
 	const start = Date.now();
 	while (Date.now() - start <= timeoutMs) {
-		const elOrError = queryElement(selector);
-		if (typeof elOrError !== "string") return elOrError;
-		if (elOrError.startsWith("选择器语法错误")) return elOrError;
+		const r = queryElement(selector);
+		if (typeof r !== "string") return r;
+		if (r.startsWith("选择器语法错误")) return r;
 		await sleep(100);
 	}
 	return null;
@@ -1491,119 +1552,128 @@ function resolveWaitMs(params) {
 	if (typeof waitSeconds === "number" && Number.isFinite(waitSeconds)) return Math.max(0, Math.floor(waitSeconds * 1e3));
 	return DEFAULT_WAIT_MS;
 }
-/**
-* 模拟真实用户输入：触发 input、change 事件，兼容 React/Vue 等框架。
-*/
-function dispatchInputEvents(el) {
-	try {
-		el.dispatchEvent(new InputEvent("input", {
-			bubbles: true,
-			cancelable: true,
-			inputType: "insertText",
-			data: null
-		}));
-	} catch {
-		el.dispatchEvent(new Event("input", {
-			bubbles: true,
-			cancelable: true
-		}));
-	}
-	el.dispatchEvent(new Event("change", {
-		bubbles: true,
-		cancelable: true
-	}));
-}
-/**
-* 使用原生 setter 写入表单值，提升对受控组件（React/Vue 等）的兼容性。
-*/
-function setNativeEditableValue(el, value) {
-	const proto = el instanceof HTMLInputElement ? HTMLInputElement.prototype : el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLSelectElement.prototype;
-	const descriptor = Object.getOwnPropertyDescriptor(proto, "value");
-	if (descriptor?.set) {
-		descriptor.set.call(el, value);
-		return;
+/** 检查元素样式可见性（处理 checkVisibility / details 折叠 / visibility） */
+function isStyleVisible(el, style) {
+	style = style ?? window.getComputedStyle(el);
+	if (typeof el.checkVisibility === "function") {
+		if (!el.checkVisibility()) return false;
+	} else {
+		const det = el.closest("details,summary");
+		if (det !== el && det?.nodeName === "DETAILS" && !det.open) return false;
 	}
-	el.value = value;
-}
-/**
-* 读取可编辑元素当前值。
-*/
-function getEditableValue(el) {
-	return el.value ?? "";
-}
-/**
-* 将常见 key 映射为更接近浏览器语义的 KeyboardEvent.code。
-*/
-function resolveKeyboardCode(key) {
-	return {
-		Enter: "Enter",
-		Escape: "Escape",
-		Esc: "Escape",
-		Tab: "Tab",
-		Space: "Space",
-		" ": "Space",
-		Backspace: "Backspace",
-		Delete: "Delete",
-		ArrowUp: "ArrowUp",
-		ArrowDown: "ArrowDown",
-		ArrowLeft: "ArrowLeft",
-		ArrowRight: "ArrowRight"
-	}[key] ?? key;
+	return style.visibility === "visible";
 }
 /**
-* 生成元素的可读描述，用于在操作结果中展示实际命中的 DOM 节点。
-* 格式：<tag#id.class> "文本" [attr=val, ...]
+* 元素可见性检查（参考 Playwright isElementVisible+computeBox）。
+* 处理 display:contents / display:none / visibility / opacity / 尺寸为 0。
 */
-function describeElement(el) {
-	const tag = el.tagName.toLowerCase();
-	const id = el.id ? `#${el.id}` : "";
-	const cls = el.className && typeof el.className === "string" ? el.className.trim().split(/\s+/).filter(Boolean).slice(0, 3).map((c) => `.${c}`).join("") : "";
-	const text = el instanceof HTMLSelectElement ? el.selectedOptions[0]?.textContent?.trim().slice(0, 40) ?? "" : el.textContent?.trim().slice(0, 40) ?? "";
-	const textHint = text ? ` "${text}"` : "";
-	const hints = [];
-	for (const attr of [
-		"type",
-		"name",
-		"placeholder",
-		"href",
-		"role"
-	]) {
-		const val = el.getAttribute(attr);
-		if (val) hints.push(`${attr}=${val}`);
-	}
-	if (el instanceof HTMLSelectElement && el.value) hints.push(`val=${el.value}`);
-	return `<${tag}${id}${cls}>${textHint}${hints.length > 0 ? ` [${hints.join(", ")}]` : ""}`;
-}
 function isElementVisible(el) {
 	if (!(el instanceof HTMLElement || el instanceof SVGElement)) return false;
 	if (!el.isConnected) return false;
 	const style = window.getComputedStyle(el);
-	if (style.display === "none" || style.visibility === "hidden") return false;
+	if (style.display === "contents") {
+		for (let child = el.firstChild; child; child = child.nextSibling) {
+			if (child.nodeType === Node.ELEMENT_NODE && isElementVisible(child)) return true;
+			if (child.nodeType === Node.TEXT_NODE) {
+				const range = document.createRange();
+				range.selectNodeContents(child);
+				const rects = range.getClientRects();
+				for (let i = 0; i < rects.length; i++) if (rects[i].width > 0 && rects[i].height > 0) return true;
+			}
+		}
+		return false;
+	}
+	if (style.display === "none") return false;
+	if (!isStyleVisible(el, style)) return false;
 	if (style.opacity === "0") return false;
 	const rect = el.getBoundingClientRect();
 	return rect.width > 0 && rect.height > 0;
 }
+/** ARIA disabled：检查元素自身 + 祖先链 aria-disabled（参考 Playwright getAriaDisabled） */
 function isElementDisabled(el) {
-	if (!(el instanceof HTMLElement)) return false;
-	if (el.hasAttribute("disabled")) return true;
-	if (el.getAttribute("aria-disabled") === "true") return true;
-	if ("disabled" in el && typeof el.disabled === "boolean") return Boolean(el.disabled);
+	if (el instanceof HTMLButtonElement || el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement) {
+		if (el.disabled) return true;
+	}
+	let cursor = el;
+	while (cursor) {
+		if (cursor.getAttribute("aria-disabled") === "true") return true;
+		cursor = cursor.parentElement;
+	}
 	return false;
 }
 function isEditableElement(el) {
 	if (el instanceof HTMLTextAreaElement) return !el.readOnly;
-	if (el instanceof HTMLInputElement) return !new Set([
-		"checkbox",
-		"radio",
-		"file",
-		"button",
-		"submit",
-		"reset"
-	]).has(el.type) && !el.readOnly;
+	if (el instanceof HTMLInputElement) return !INPUT_BLOCKED_TYPES.has(el.type) && !el.readOnly;
 	if (el instanceof HTMLSelectElement) return true;
 	return el instanceof HTMLElement && el.isContentEditable;
 }
-function ensureActionable(el, action, selector) {
+/** rAF 逐帧检查元素位置是否连续 3 帧不变 */
+function checkElementStable(el, timeoutMs = 800) {
+	return new Promise((resolve) => {
+		let lastRect;
+		let stableCount = 0;
+		const start = performance.now();
+		function check() {
+			if (performance.now() - start > timeoutMs || !el.isConnected) {
+				resolve(false);
+				return;
+			}
+			const rect = el.getBoundingClientRect();
+			if (lastRect) {
+				if (!(rect.x === lastRect.x && rect.y === lastRect.y && rect.width === lastRect.width && rect.height === lastRect.height)) stableCount = 0;
+				else if (++stableCount >= 3) {
+					resolve(true);
+					return;
+				}
+			}
+			lastRect = rect;
+			requestAnimationFrame(check);
+		}
+		requestAnimationFrame(check);
+	});
+}
+/**
+* 将目标重定向到关联的交互控件。
+* - button-link：非交互元素→最近 button/[role=button]/a/[role=link]
+* - follow-label：label→control + 非交互→button/[role=button]/[role=checkbox]/[role=radio]
+*/
+function retarget(el, mode) {
+	if (mode === "none") return el;
+	if (!el.matches("input, textarea, select") && !el.isContentEditable) if (mode === "button-link") el = el.closest("button, [role=button], a, [role=link]") || el;
+	else el = el.closest("button, [role=button], [role=checkbox], [role=radio]") || el;
+	if (mode === "follow-label") {
+		if (!el.matches("a, input, textarea, button, select, [role=link], [role=button], [role=checkbox], [role=radio]") && !el.isContentEditable) {
+			const label = el.closest("label");
+			if (label?.control) el = label.control;
+		}
+	}
+	return el;
+}
+function scrollIntoViewIfNeeded(el, retry = 0) {
+	if (retry === 0 && "scrollIntoViewIfNeeded" in el) {
+		el.scrollIntoViewIfNeeded(true);
+		return;
+	}
+	const opts = SCROLL_OPTIONS[retry % SCROLL_OPTIONS.length];
+	el.scrollIntoView(opts ?? {
+		block: "center",
+		inline: "nearest"
+	});
+}
+/** 检查元素中心点是否被遮挡，返回遮挡元素描述或 null */
+function checkHitTarget(el) {
+	const rect = el.getBoundingClientRect();
+	const x = rect.left + rect.width / 2;
+	const y = rect.top + rect.height / 2;
+	const topEl = document.elementFromPoint(x, y);
+	if (!topEl) return null;
+	if (topEl === el || el.contains(topEl) || topEl.contains(el)) return null;
+	const sharedLabel = topEl.closest("label");
+	if (sharedLabel && sharedLabel.contains(el)) return null;
+	return describeElement(topEl);
+}
+function ensureActionable(el, action, selector, force) {
+	if (force) return null;
 	if (!el.isConnected) return {
 		content: `"${selector}" 元素已脱离文档，无法执行 ${action}`,
 		details: {
@@ -1632,7 +1702,7 @@ function ensureActionable(el, action, selector) {
 		"check",
 		"uncheck"
 	]).has(action) && isElementDisabled(el)) return {
-		content: `"${selector}" 元素已禁用，无法执行 ${action}`,
+		content: `"${selector}" 元素已禁用（disabled/aria-disabled），无法执行 ${action}`,
 		details: {
 			error: true,
 			code: "ELEMENT_DISABLED",
@@ -1655,45 +1725,318 @@ function ensureActionable(el, action, selector) {
 	};
 	return null;
 }
-function isOptionCandidateVisible(el) {
-	if (!(el instanceof HTMLElement)) return false;
-	if (!isElementVisible(el)) return false;
-	return (el.textContent?.trim() ?? "").length > 0;
+function getClickPoint(el) {
+	const r = el.getBoundingClientRect();
+	return {
+		x: r.left + r.width / 2,
+		y: r.top + r.height / 2
+	};
+}
+/**
+* 完整点击事件链（参考 Playwright Mouse.click）：
+* pointermove → mousemove → (per clickCount) pointerdown → mousedown → focus → pointerup → mouseup → click
+*/
+function dispatchClickEvents(el, clickCount = 1) {
+	const { x, y } = getClickPoint(el);
+	const base = {
+		bubbles: true,
+		cancelable: true,
+		view: window,
+		clientX: x,
+		clientY: y,
+		button: 0
+	};
+	el.dispatchEvent(new PointerEvent("pointermove", {
+		...base,
+		pointerId: 1
+	}));
+	el.dispatchEvent(new MouseEvent("mousemove", base));
+	for (let cc = 1; cc <= clickCount; cc++) {
+		el.dispatchEvent(new PointerEvent("pointerdown", {
+			...base,
+			detail: cc,
+			buttons: 1,
+			pointerId: 1
+		}));
+		el.dispatchEvent(new MouseEvent("mousedown", {
+			...base,
+			detail: cc,
+			buttons: 1
+		}));
+		if (cc === 1 && el !== document.activeElement) el.focus({ preventScroll: true });
+		el.dispatchEvent(new PointerEvent("pointerup", {
+			...base,
+			detail: cc,
+			pointerId: 1
+		}));
+		el.dispatchEvent(new MouseEvent("mouseup", {
+			...base,
+			detail: cc
+		}));
+		el.dispatchEvent(new MouseEvent("click", {
+			...base,
+			detail: cc
+		}));
+	}
+}
+/** hover 事件链 */
+function dispatchHoverEvents(el) {
+	const { x, y } = getClickPoint(el);
+	const base = {
+		bubbles: true,
+		cancelable: true,
+		view: window,
+		clientX: x,
+		clientY: y
+	};
+	el.dispatchEvent(new PointerEvent("pointerenter", {
+		...base,
+		bubbles: false
+	}));
+	el.dispatchEvent(new MouseEvent("mouseenter", {
+		...base,
+		bubbles: false
+	}));
+	el.dispatchEvent(new PointerEvent("pointermove", {
+		...base,
+		pointerId: 1
+	}));
+	el.dispatchEvent(new MouseEvent("mousemove", base));
+	el.dispatchEvent(new MouseEvent("mouseover", base));
+}
+/** 派发 input + change 事件（兼容 React/Vue 受控组件） */
+function dispatchInputEvents(el) {
+	el.dispatchEvent(new Event("input", {
+		bubbles: true,
+		composed: true
+	}));
+	el.dispatchEvent(new Event("change", { bubbles: true }));
+}
+/** 原生 setter 写入表单值（绕过 React/Vue getter/setter 拦截） */
+function setNativeValue(el, value) {
+	const proto = el instanceof HTMLInputElement ? HTMLInputElement.prototype : HTMLTextAreaElement.prototype;
+	const desc = Object.getOwnPropertyDescriptor(proto, "value");
+	if (desc?.set) desc.set.call(el, value);
+	else el.value = value;
+}
+function selectText(el) {
+	if (el instanceof HTMLInputElement) {
+		el.select();
+		el.focus();
+		return;
+	}
+	if (el instanceof HTMLTextAreaElement) {
+		el.selectionStart = 0;
+		el.selectionEnd = el.value.length;
+		el.focus();
+		return;
+	}
+	const range = document.createRange();
+	range.selectNodeContents(el);
+	const sel = window.getSelection();
+	if (sel) {
+		sel.removeAllRanges();
+		sel.addRange(range);
+	}
+	if (el instanceof HTMLElement) el.focus();
+}
+function splitKeyCombo(key) {
+	const tokens = key.split("+");
+	for (let i = 0; i < tokens.length; i++) if (tokens[i] === "" && i + 1 < tokens.length) {
+		tokens[i + 1] = "+" + tokens[i + 1];
+		tokens.splice(i, 1);
+	}
+	return tokens.filter(Boolean);
+}
+function resolveKeyCode(key) {
+	return KEY_CODE_MAP[key] ?? (key.length === 1 ? `Key${key.toUpperCase()}` : key);
+}
+/**
+* 执行 press：修饰键按正序 down → 主键 down/up → 修饰键逆序 up（参考 Playwright）。
+* 修饰键按下时抑制文本输入（只发 keydown/keyup，不发 keypress）。
+*/
+function executePress(el, key) {
+	const tokens = splitKeyCombo(key);
+	const mainKey = tokens[tokens.length - 1];
+	const mods = tokens.slice(0, -1);
+	const modState = {
+		ctrlKey: mods.includes("Control"),
+		shiftKey: mods.includes("Shift"),
+		altKey: mods.includes("Alt"),
+		metaKey: mods.includes("Meta")
+	};
+	const hasNonShiftMod = modState.ctrlKey || modState.altKey || modState.metaKey;
+	for (const m of mods) el.dispatchEvent(new KeyboardEvent("keydown", {
+		key: m,
+		code: resolveKeyCode(m),
+		bubbles: true,
+		cancelable: true,
+		...modState
+	}));
+	if (el.dispatchEvent(new KeyboardEvent("keydown", {
+		key: mainKey,
+		code: resolveKeyCode(mainKey),
+		bubbles: true,
+		cancelable: true,
+		...modState
+	})) && mainKey.length === 1 && !hasNonShiftMod) el.dispatchEvent(new KeyboardEvent("keypress", {
+		key: mainKey,
+		code: resolveKeyCode(mainKey),
+		bubbles: true,
+		cancelable: true,
+		...modState
+	}));
+	el.dispatchEvent(new KeyboardEvent("keyup", {
+		key: mainKey,
+		code: resolveKeyCode(mainKey),
+		bubbles: true,
+		cancelable: true,
+		...modState
+	}));
+	for (let i = mods.length - 1; i >= 0; i--) el.dispatchEvent(new KeyboardEvent("keyup", {
+		key: mods[i],
+		code: resolveKeyCode(mods[i]),
+		bubbles: true,
+		cancelable: true,
+		...modState
+	}));
+}
+function describeElement(el) {
+	const tag = el.tagName.toLowerCase();
+	const id = el.id ? `#${el.id}` : "";
+	const cls = el.className && typeof el.className === "string" ? el.className.trim().split(/\s+/).filter(Boolean).slice(0, 3).map((c) => `.${c}`).join("") : "";
+	const text = el instanceof HTMLSelectElement ? el.selectedOptions[0]?.textContent?.trim().slice(0, 40) ?? "" : el.textContent?.trim().slice(0, 40) ?? "";
+	const textHint = text ? ` "${text}"` : "";
+	const hints = [];
+	for (const attr of [
+		"type",
+		"name",
+		"placeholder",
+		"href",
+		"role"
+	]) {
+		const v = el.getAttribute(attr);
+		if (v) hints.push(`${attr}=${v}`);
+	}
+	if (el instanceof HTMLSelectElement && el.value) hints.push(`val=${el.value}`);
+	return `<${tag}${id}${cls}>${textHint}${hints.length > 0 ? ` [${hints.join(", ")}]` : ""}`;
+}
+function getChecked(el) {
+	if (el instanceof HTMLInputElement && (el.type === "checkbox" || el.type === "radio")) return el.checked;
+	const role = el.getAttribute("role");
+	if (role === "checkbox" || role === "radio" || role === "switch") return el.getAttribute("aria-checked") === "true";
+	return "error";
+}
+/**
+* 归一化 check/uncheck 目标：允许命中文本容器/label/div，回溯到关联 checkbox/radio。
+*/
+function resolveCheckableTarget(el) {
+	if (getChecked(el) !== "error") return el;
+	if (el instanceof HTMLLabelElement && el.control && getChecked(el.control) !== "error") return el.control;
+	const ownerLabel = el.closest("label");
+	if (ownerLabel?.control && getChecked(ownerLabel.control) !== "error") return ownerLabel.control;
+	const inner = el.querySelector("input[type=\"checkbox\"], input[type=\"radio\"], [role=\"checkbox\"], [role=\"radio\"], [role=\"switch\"]");
+	if (inner && getChecked(inner) !== "error") return inner;
+	const prev = el.previousElementSibling;
+	if (prev && getChecked(prev) !== "error") return prev;
+	const next = el.nextElementSibling;
+	if (next && getChecked(next) !== "error") return next;
+	const parent = el.parentElement;
+	if (parent) {
+		const inP = parent.querySelector("input[type=\"checkbox\"], input[type=\"radio\"], [role=\"checkbox\"], [role=\"radio\"], [role=\"switch\"]");
+		if (inP && getChecked(inP) !== "error") return inP;
+	}
+	return el;
+}
+/**
+* 为 pointer 类动作（click/check/uncheck）解析可点击代理目标：
+* 当命中隐藏的原生 checkbox/radio/switch input 时，优先改点其可见 label/容器。
+*/
+function resolvePointerActionTarget(el) {
+	if (!(el instanceof HTMLInputElement)) return el;
+	const inputType = el.type?.toLowerCase() ?? "";
+	if (!(inputType === "checkbox" || inputType === "radio") && el.getAttribute("role") !== "switch") return el;
+	if (isElementVisible(el)) return el;
+	const label = el.labels?.[0] ?? el.closest("label");
+	if (label && isElementVisible(label)) return label;
+	const proxy = el.closest(".el-switch, .el-checkbox, .el-radio, [role='switch'], [role='checkbox'], [role='radio']");
+	if (proxy && isElementVisible(proxy)) return proxy;
+	const siblingProxy = el.parentElement?.querySelector(".el-switch__core, .el-checkbox__inner, .el-radio__inner, [role='switch'], [role='checkbox'], [role='radio']");
+	if (siblingProxy && isElementVisible(siblingProxy)) return siblingProxy;
+	return el;
+}
+/**
+* 当命中表单项说明 label（如 Element Plus el-form-item__label）时，
+* 自动重定向到同一表单项中的首个可交互控件。
+*/
+function resolveFormItemControlTarget(el) {
+	if (!(el instanceof HTMLElement)) return el;
+	if (!(el.tagName === "LABEL" || el.classList.contains("el-form-item__label"))) return el;
+	const htmlLabel = el;
+	if (htmlLabel.control && isElementVisible(htmlLabel.control)) return htmlLabel.control;
+	const formItem = el.closest(".el-form-item");
+	if (!formItem) return el;
+	const control = (formItem.querySelector(".el-form-item__content") ?? formItem).querySelector("input:not([type='hidden']), textarea, select, button, [role='switch'], [role='checkbox'], [role='radio'], [role='button'], .el-switch, .el-checkbox, .el-radio, [tabindex]:not([tabindex='-1'])");
+	if (control && isElementVisible(control)) return control;
+	return el;
 }
 function findVisibleOptionByText(text) {
 	const target = text.trim().toLowerCase();
 	if (!target) return null;
-	const nodes = Array.from(document.querySelectorAll("[role=\"option\"], .bk-select-option, .bk-option, [data-option], li, option"));
-	for (const node of nodes) {
-		if (!isOptionCandidateVisible(node)) continue;
-		if ((node.textContent?.trim().toLowerCase() ?? "") === target) return node;
-	}
-	for (const node of nodes) {
-		if (!isOptionCandidateVisible(node)) continue;
-		if ((node.textContent?.trim().toLowerCase() ?? "").includes(target)) return node;
-	}
+	const selectors = [
+		"[role=\"option\"]",
+		"[role=\"listbox\"] li",
+		".el-select-dropdown__item",
+		".el-option",
+		".ant-select-item-option",
+		".el-cascader-node",
+		".el-dropdown-menu__item",
+		"[class*=\"option\"]",
+		"li[data-value]",
+		"option"
+	].join(", ");
+	const visible = Array.from(document.querySelectorAll(selectors)).filter((n) => n instanceof HTMLElement && isElementVisible(n));
+	for (const n of visible) if (n.textContent?.trim().toLowerCase() === target) return n;
+	for (const n of visible) if (n.textContent?.trim().toLowerCase().includes(target)) return n;
 	return null;
 }
+async function waitForDropdownPopup(maxWait = 500) {
+	const start = Date.now();
+	while (Date.now() - start < maxWait) {
+		const popup = document.querySelector("[role=\"listbox\"], .el-select-dropdown, .el-popper, .ant-select-dropdown, [class*=\"dropdown\"]");
+		if (popup && isElementVisible(popup)) return;
+		await sleep(50);
+	}
+}
 function createDomTool() {
 	return {
 		name: "dom",
 		description: [
 			"Perform DOM operations on the current page.",
 			"Actions: click, fill, select_option, clear, check, uncheck, type, focus, hover, press, get_text, get_attr, set_attr, add_class, remove_class.",
-			"Use the hash ID from DOM snapshot (e.g. #a1b2c) as selector."
+			"Input/Select rule: before each fill/type/select_option, click or focus the same target immediately in the same round.",
+			"For multiple fields, use alternating pairs in one batch: focus/click A -> fill/type A -> focus/click B -> fill/type B.",
+			"Use the hash ID from DOM snapshot (e.g. #a1b2c) as selector.",
+			"press supports combo keys like 'Control+a', 'Shift+Enter'.",
+			"check/uncheck is done via click — state change is verified after action.",
+			"Ordinal/index rule: treat visual order as 1-based when the instruction says 'the Nth item' (e.g. 4th star = 4th visible icon from left to right), and avoid off-by-one mistakes.",
+			"Disambiguation rule: distinguish descriptive text/labels from actionable options. Do not click nearby label/help text; click the actual interactive option/control item (icon/button/option) that changes state.",
+			"Unknown/complex components: if a container element (e.g. role=slider, rating, custom widget) has multiple child icons/items in the snapshot but you don't know how to operate it directly, try clicking the appropriate child element instead. For example, a rating component with 5 star icon children — click the 4th icon child to set 4 stars. A slider with a runway — clicking the runway at the right position may work. Always prefer interacting with visible children when the parent container doesn't respond to fill/click as expected.",
+			"fill supports role=slider elements: use fill with a numeric value on a role=slider container (rating/slider) to set its value programmatically."
 		].join(" "),
 		schema: Type.Object({
-			action: Type.String({ description: "DOM action: click | fill | select_option | clear | check | uncheck | type | focus | hover | press | get_text | get_attr | set_attr | add_class | remove_class" }),
+			action: Type.String({ description: "DOM action: click | fill | select_option | clear | check | uncheck | type | focus | hover | press | get_text | get_attr | set_attr | add_class | remove_class." }),
 			selector: Type.String({ description: "Element ref ID from snapshot (e.g. #r0, #r5) or CSS selector" }),
-			value: Type.Optional(Type.String({ description: "Value for fill/type/set_attr actions" })),
-			key: Type.Optional(Type.String({ description: "Key name for press action (e.g. Enter, Escape, Tab, ArrowDown, ArrowUp, Backspace, Delete, Space)" })),
-			label: Type.Optional(Type.String({ description: "Label text for select_option action (fallback when value is not provided)" })),
+			value: Type.Optional(Type.String({ description: "Value for fill/type/set_attr actions." })),
+			key: Type.Optional(Type.String({ description: "Key for press action. Supports combo: 'Enter', 'Control+a', 'Shift+Enter', 'Meta+c'" })),
+			label: Type.Optional(Type.String({ description: "Label text for select_option action." })),
 			index: Type.Optional(Type.Number({ description: "0-based option index for select_option action" })),
-			attribute: Type.Optional(Type.String({ description: "Attribute name for get_attr/set_attr actions" })),
+			attribute: Type.Optional(Type.String({ description: "Attribute name for get_attr/set_attr" })),
 			className: Type.Optional(Type.String({ description: "CSS class name for add_class/remove_class" })),
-			waitMs: Type.Optional(Type.Number({ description: "Optional wait timeout in ms before action (default: 1000). Use 0 to disable waiting." })),
-			waitSeconds: Type.Optional(Type.Number({ description: "Optional wait timeout in seconds before action. Used when waitMs is not provided." })),
-			force: Type.Optional(Type.Boolean({ description: "Skip actionability checks for interaction actions (default false)." }))
+			clickCount: Type.Optional(Type.Number({ description: "Click count (default 1). 2 = double-click, 3 = triple-click." })),
+			waitMs: Type.Optional(Type.Number({ description: "Wait timeout in ms before action (default: 2000)." })),
+			waitSeconds: Type.Optional(Type.Number({ description: "Wait timeout in seconds (fallback for waitMs)." })),
+			force: Type.Optional(Type.Boolean({ description: "Skip actionability checks (default false)." }))
 		}),
 		execute: async (params) => {
 			const action = params.action;
@@ -1725,180 +2068,149 @@ function createDomTool() {
 				};
 				el = found;
 			} else {
-				const elOrError = queryElement(selector);
-				if (typeof elOrError === "string") return {
-					content: elOrError,
+				const r = queryElement(selector);
+				if (typeof r === "string") return {
+					content: r,
 					details: {
 						error: true,
-						code: elOrError.startsWith("未找到") ? "ELEMENT_NOT_FOUND" : "INVALID_SELECTOR",
+						code: r.startsWith("未找到") ? "ELEMENT_NOT_FOUND" : "INVALID_SELECTOR",
 						action,
 						selector,
 						waitMs
 					}
 				};
-				el = elOrError;
+				el = r;
 			}
+			if (action === "check" || action === "uncheck") el = resolveCheckableTarget(el);
+			const actionabilityTarget = action === "click" || action === "check" || action === "uncheck" ? resolvePointerActionTarget(resolveFormItemControlTarget(el)) : el;
 			try {
-				if (!force) {
-					const checkResult = ensureActionable(el, action, selector);
-					if (checkResult) return checkResult;
-				}
+				const checkResult = ensureActionable(actionabilityTarget, action, selector, force);
+				if (checkResult) return checkResult;
 				switch (action) {
-					case "click":
-						if (el instanceof HTMLOptionElement) {
-							const parent = el.parentElement;
+					case "click": {
+						const target = resolvePointerActionTarget(resolveFormItemControlTarget(retarget(el, force ? "none" : "button-link")));
+						const clickCount = typeof params.clickCount === "number" ? params.clickCount : 1;
+						if (target instanceof HTMLOptionElement) {
+							const parent = target.parentElement;
 							if (parent instanceof HTMLSelectElement) {
 								parent.focus();
-								parent.value = el.value;
+								parent.value = target.value;
 								dispatchInputEvents(parent);
-								return { content: `已选择 ${describeElement(parent)} 的选项 "${el.value}"` };
+								return { content: `已选择 ${describeElement(parent)} 的选项 "${target.value}"` };
 							}
 						}
-						if (el instanceof HTMLElement) {
-							el.focus();
-							el.dispatchEvent(new PointerEvent("pointerdown", {
-								bubbles: true,
-								cancelable: true
-							}));
-							el.dispatchEvent(new MouseEvent("mousedown", {
-								bubbles: true,
-								cancelable: true
-							}));
-							el.dispatchEvent(new PointerEvent("pointerup", {
-								bubbles: true,
-								cancelable: true
-							}));
-							el.dispatchEvent(new MouseEvent("mouseup", {
-								bubbles: true,
-								cancelable: true
-							}));
-							el.click();
-						} else el.dispatchEvent(new MouseEvent("click", { bubbles: true }));
-						return { content: `已点击 ${describeElement(el)}` };
-					case "focus":
-						if (el instanceof HTMLElement) el.focus();
-						else el.dispatchEvent(new FocusEvent("focus", { bubbles: true }));
-						return { content: `已聚焦 ${describeElement(el)}` };
-					case "hover":
-						el.dispatchEvent(new MouseEvent("mouseenter", {
-							bubbles: false,
-							cancelable: true
-						}));
-						el.dispatchEvent(new MouseEvent("mouseover", {
-							bubbles: true,
-							cancelable: true
-						}));
-						el.dispatchEvent(new MouseEvent("mousemove", {
-							bubbles: true,
-							cancelable: true
-						}));
-						return { content: `已悬停 ${describeElement(el)}` };
-					case "press": {
-						const key = params.key || params.value;
-						if (!key) return { content: "缺少 key 参数（如 Enter, Escape, Tab）" };
-						if (el instanceof HTMLElement) el.focus();
-						const eventInit = {
-							key,
-							code: resolveKeyboardCode(key),
-							bubbles: true,
-							cancelable: true
-						};
-						const keydownAllowed = el.dispatchEvent(new KeyboardEvent("keydown", eventInit));
-						el.dispatchEvent(new KeyboardEvent("keypress", eventInit));
-						el.dispatchEvent(new KeyboardEvent("keyup", eventInit));
-						if (keydownAllowed && key === "Enter") {
-							if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) (el.form ?? el.closest("form"))?.dispatchEvent(new Event("submit", {
-								bubbles: true,
-								cancelable: true
-							}));
-						}
-						return { content: `已在 ${describeElement(el)} 上按下 ${key}` };
+						if (target instanceof HTMLElement) {
+							scrollIntoViewIfNeeded(target);
+							if (!force) await checkElementStable(target, 500);
+							if (!force) {
+								if (checkHitTarget(target)) {
+									scrollIntoViewIfNeeded(target, 1);
+									await sleep(100);
+								}
+							}
+							dispatchClickEvents(target, clickCount);
+						} else target.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+						return { content: `已点击 ${describeElement(target)}` };
 					}
 					case "fill": {
 						const value = params.value;
 						if (value === void 0) return { content: "缺少 value 参数" };
-						if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
-							if (el instanceof HTMLInputElement) {
-								if (new Set([
-									"checkbox",
-									"radio",
-									"file",
-									"button",
-									"submit",
-									"reset"
-								]).has(el.type)) return {
-									content: `"${selector}" 为 input[type=${el.type}]，不支持 fill；请使用 click/press/select_option 等动作。`,
+						const target = retarget(el, "follow-label");
+						if (target instanceof HTMLInputElement) {
+							const type = target.type.toLowerCase();
+							if (INPUT_BLOCKED_TYPES.has(type)) return {
+								content: `"${selector}" 为 input[type=${type}]，不支持 fill；请使用 click/check 等动作。`,
+								details: {
+									error: true,
+									code: "UNSUPPORTED_FILL_TARGET",
+									action,
+									selector
+								}
+							};
+							if (INPUT_SET_VALUE_TYPES.has(type)) {
+								const finalVal = type === "color" ? value.toLowerCase().trim() : value.trim();
+								target.focus();
+								target.value = finalVal;
+								if (target.value !== finalVal) return {
+									content: `"${selector}" 填写格式不匹配（type=${type}）`,
 									details: {
 										error: true,
-										code: "UNSUPPORTED_FILL_TARGET",
+										code: "MALFORMED_VALUE",
 										action,
 										selector
 									}
 								};
+								dispatchInputEvents(target);
+								return { content: `已填写 ${describeElement(target)}: "${finalVal}"` };
 							}
-							el.focus();
-							setNativeEditableValue(el, value);
-							dispatchInputEvents(el);
-							const actualValue = getEditableValue(el);
-							if (actualValue !== value) return {
-								content: `"${selector}" 填写后值不一致：期望 "${value}"，实际 "${actualValue}"`,
+							if (type === "number" && isNaN(Number(value.trim()))) return {
+								content: `"${selector}" 为 input[type=number]，无法填写非数字 "${value}"`,
 								details: {
 									error: true,
-									code: "FILL_NOT_APPLIED",
+									code: "INVALID_NUMBER",
 									action,
-									selector,
-									expected: value,
-									actual: actualValue
+									selector
 								}
 							};
-						} else if (el instanceof HTMLSelectElement) {
-							el.focus();
-							let matched = false;
-							for (const option of Array.from(el.options)) if (option.value === value) {
-								el.value = option.value;
-								matched = true;
-								break;
-							}
-							if (!matched) {
-								const normalized = value.trim().toLowerCase();
-								for (const option of Array.from(el.options)) if (option.text.trim().toLowerCase() === normalized) {
-									el.value = option.value;
-									matched = true;
-									break;
-								}
-							}
-							if (!matched) return { content: `"${selector}" 下拉框中不存在选项 "${value}"` };
-							dispatchInputEvents(el);
-							const actualValue = getEditableValue(el);
-							if (actualValue !== el.value) return {
-								content: `"${selector}" 下拉框状态异常，未确认写入`,
+							scrollIntoViewIfNeeded(target);
+							target.focus();
+							selectText(target);
+							setNativeValue(target, value);
+							dispatchInputEvents(target);
+							if (target.value !== value) return {
+								content: `"${selector}" 填写后值不一致：期望 "${value}"，实际 "${target.value}"`,
 								details: {
 									error: true,
 									code: "FILL_NOT_APPLIED",
 									action,
-									selector,
-									expected: value,
-									actual: actualValue
+									selector
 								}
 							};
-						} else if (el instanceof HTMLElement && el.isContentEditable) {
-							el.focus();
-							el.textContent = value;
-							el.dispatchEvent(new Event("input", { bubbles: true }));
-						} else return { content: `"${selector}" 不是可编辑元素` };
-						return { content: `已填写 ${describeElement(el)}: "${value}"` };
+							return { content: `已填写 ${describeElement(target)}: "${value}"` };
+						}
+						if (target instanceof HTMLTextAreaElement) {
+							scrollIntoViewIfNeeded(target);
+							target.focus();
+							selectText(target);
+							setNativeValue(target, value);
+							dispatchInputEvents(target);
+							return { content: `已填写 ${describeElement(target)}: "${value}"` };
+						}
+						if (target instanceof HTMLSelectElement) {
+							target.focus();
+							const options = Array.from(target.options);
+							let matched = options.find((o) => o.value === value);
+							if (!matched) {
+								const n = value.trim().toLowerCase();
+								matched = options.find((o) => o.text.trim().toLowerCase() === n);
+							}
+							if (!matched) return { content: `"${selector}" 下拉框中不存在选项 "${value}"` };
+							target.value = matched.value;
+							dispatchInputEvents(target);
+							return { content: `已填写 ${describeElement(target)}: "${value}"` };
+						}
+						if (target instanceof HTMLElement && target.isContentEditable) {
+							target.focus();
+							selectText(target);
+							if (value) document.execCommand("insertText", false, value);
+							else document.execCommand("delete", false, void 0);
+							return { content: `已填写 ${describeElement(target)}: "${value}"` };
+						}
+						return { content: `"${selector}" 不是可编辑元素` };
 					}
 					case "select_option": {
 						const value = params.value;
 						const label = params.label;
 						const index = typeof params.index === "number" ? Math.floor(params.index) : void 0;
 						if (value === void 0 && label === void 0 && index === void 0) return { content: "缺少可选参数：value 或 label 或 index" };
-						if (!(el instanceof HTMLSelectElement)) {
-							if (!(el instanceof HTMLElement)) return { content: `"${selector}" 不是下拉框元素` };
-							el.focus();
-							el.click();
+						const target = retarget(el, "follow-label");
+						if (!(target instanceof HTMLSelectElement)) {
+							if (!(target instanceof HTMLElement)) return { content: `"${selector}" 不是下拉框元素` };
+							scrollIntoViewIfNeeded(target);
 							const wanted = (label ?? value ?? "").trim();
 							if (!wanted) return { content: `"${selector}" 为自定义下拉时，需提供 value 或 label` };
+							dispatchClickEvents(target);
+							await waitForDropdownPopup(800);
 							const option = findVisibleOptionByText(wanted);
 							if (!option) return {
 								content: `未找到与 "${wanted}" 匹配的可见下拉选项（自定义下拉）`,
@@ -1910,84 +2222,156 @@ function createDomTool() {
 									wanted
 								}
 							};
-							option.click();
+							dispatchClickEvents(option);
 							return { content: `已在自定义下拉中选择 "${wanted}"` };
 						}
-						el.focus();
-						const options = Array.from(el.options);
-						let selectedOption;
-						if (value !== void 0) selectedOption = options.find((option) => option.value === value);
-						if (!selectedOption && label !== void 0) {
-							const normalizedLabel = label.trim().toLowerCase();
-							selectedOption = options.find((option) => option.text.trim().toLowerCase() === normalizedLabel);
+						target.focus();
+						const options = Array.from(target.options);
+						let selected;
+						if (value !== void 0) selected = options.find((o) => o.value === value);
+						if (!selected && label !== void 0) {
+							const nl = label.trim().toLowerCase();
+							selected = options.find((o) => o.text.trim().toLowerCase() === nl);
 						}
-						if (!selectedOption && value !== void 0) {
-							const normalizedValueAsLabel = value.trim().toLowerCase();
-							selectedOption = options.find((option) => option.text.trim().toLowerCase() === normalizedValueAsLabel);
+						if (!selected && value !== void 0) {
+							const nv = value.trim().toLowerCase();
+							selected = options.find((o) => o.text.trim().toLowerCase() === nv);
 						}
-						if (!selectedOption && index !== void 0) {
+						if (!selected && index !== void 0) {
 							if (index < 0 || index >= options.length) return { content: `"${selector}" 下拉框不存在 index=${index} 的选项` };
-							selectedOption = options[index];
+							selected = options[index];
 						}
-						if (!selectedOption) return { content: `"${selector}" 下拉框中不存在选项 "${value ?? label ?? `index=${index}`}"` };
-						if (selectedOption.disabled) return { content: `"${selector}" 目标选项已禁用：${selectedOption.value}` };
-						if (!el.multiple) for (const option of options) option.selected = false;
-						selectedOption.selected = true;
-						el.value = selectedOption.value;
-						dispatchInputEvents(el);
-						return { content: `已选择 ${describeElement(el)}: value="${selectedOption.value}", label="${selectedOption.text.trim()}"` };
+						if (!selected) return { content: `"${selector}" 下拉框中不存在选项 "${value ?? label ?? `index=${index}`}"` };
+						if (selected.disabled) return {
+							content: `"${selector}" 目标选项已禁用：${selected.value}`,
+							details: {
+								error: true,
+								code: "OPTION_DISABLED",
+								action,
+								selector
+							}
+						};
+						if (!target.multiple) for (const o of options) o.selected = false;
+						selected.selected = true;
+						target.value = selected.value;
+						dispatchInputEvents(target);
+						return { content: `已选择 ${describeElement(target)}: value="${selected.value}", label="${selected.text.trim()}"` };
 					}
-					case "clear":
-						if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
-							el.focus();
-							setNativeEditableValue(el, "");
-							dispatchInputEvents(el);
-							return { content: `已清空 ${describeElement(el)}` };
+					case "clear": {
+						const target = retarget(el, "follow-label");
+						if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+							scrollIntoViewIfNeeded(target);
+							target.focus();
+							selectText(target);
+							setNativeValue(target, "");
+							dispatchInputEvents(target);
+							return { content: `已清空 ${describeElement(target)}` };
+						}
+						if (target instanceof HTMLSelectElement) {
+							target.focus();
+							target.value = "";
+							dispatchInputEvents(target);
+							return { content: `已清空 ${describeElement(target)}` };
 						}
-						if (el instanceof HTMLElement && el.isContentEditable) {
-							el.focus();
-							el.textContent = "";
-							el.dispatchEvent(new Event("input", { bubbles: true }));
-							return { content: `已清空 ${describeElement(el)}` };
+						if (target instanceof HTMLElement && target.isContentEditable) {
+							target.focus();
+							selectText(target);
+							document.execCommand("delete", false, void 0);
+							return { content: `已清空 ${describeElement(target)}` };
 						}
 						return { content: `"${selector}" 不是可清空元素` };
+					}
 					case "check":
-						if (!(el instanceof HTMLInputElement) || el.type !== "checkbox" && el.type !== "radio") return { content: `"${selector}" 不是 checkbox/radio` };
-						el.focus();
-						if (!el.checked) {
-							el.checked = true;
-							dispatchInputEvents(el);
-						}
-						return { content: `已勾选 ${describeElement(el)}` };
-					case "uncheck":
-						if (!(el instanceof HTMLInputElement) || el.type !== "checkbox") return { content: `"${selector}" 不是 checkbox` };
-						el.focus();
-						if (el.checked) {
-							el.checked = false;
+					case "uncheck": {
+						const wantChecked = action === "check";
+						const current = getChecked(el);
+						if (current === "error") return {
+							content: `"${selector}" 不是 checkbox/radio/[role=checkbox]/[role=radio]，无法 ${action}`,
+							details: {
+								error: true,
+								code: "NOT_CHECKABLE",
+								action,
+								selector
+							}
+						};
+						if (current === wantChecked) return { content: `${describeElement(el)} 已经是${wantChecked ? "选中" : "未选中"}状态` };
+						if (!wantChecked && el instanceof HTMLInputElement && el.type === "radio") return {
+							content: `无法取消 radio 按钮的选中状态`,
+							details: {
+								error: true,
+								code: "CANNOT_UNCHECK_RADIO",
+								action,
+								selector
+							}
+						};
+						const pointerTarget = resolvePointerActionTarget(el);
+						scrollIntoViewIfNeeded(pointerTarget);
+						if (pointerTarget instanceof HTMLElement) dispatchClickEvents(pointerTarget);
+						else pointerTarget.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+						await sleep(50);
+						if (getChecked(el) !== wantChecked && el instanceof HTMLInputElement) {
+							el.checked = wantChecked;
 							dispatchInputEvents(el);
 						}
-						return { content: `已取消勾选 ${describeElement(el)}` };
+						return { content: `已${wantChecked ? "勾选" : "取消勾选"} ${describeElement(el)}` };
+					}
 					case "type": {
 						const value = params.value;
 						if (value === void 0) return { content: "缺少 value 参数" };
-						if (el instanceof HTMLElement) el.focus();
+						const target = retarget(el, "follow-label");
+						scrollIntoViewIfNeeded(target);
+						if (target instanceof HTMLElement) target.focus();
 						for (const char of value) {
-							el.dispatchEvent(new KeyboardEvent("keydown", {
-								key: char,
-								bubbles: true
-							}));
-							el.dispatchEvent(new KeyboardEvent("keypress", {
-								key: char,
-								bubbles: true
-							}));
-							if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) el.value += char;
-							el.dispatchEvent(new Event("input", { bubbles: true }));
-							el.dispatchEvent(new KeyboardEvent("keyup", {
+							const init = {
 								key: char,
-								bubbles: true
+								code: resolveKeyCode(char),
+								bubbles: true,
+								cancelable: true
+							};
+							target.dispatchEvent(new KeyboardEvent("keydown", init));
+							target.dispatchEvent(new KeyboardEvent("keypress", init));
+							if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+								const proto = target instanceof HTMLInputElement ? HTMLInputElement.prototype : HTMLTextAreaElement.prototype;
+								const nativeSet = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+								if (nativeSet) nativeSet.call(target, target.value + char);
+								else target.value += char;
+							} else if (target instanceof HTMLElement && target.isContentEditable) document.execCommand("insertText", false, char);
+							target.dispatchEvent(new Event("input", {
+								bubbles: true,
+								composed: true
 							}));
+							target.dispatchEvent(new KeyboardEvent("keyup", init));
 						}
-						return { content: `已逐字输入到 ${describeElement(el)}: "${value}"` };
+						if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) target.dispatchEvent(new Event("change", { bubbles: true }));
+						return { content: `已逐字输入到 ${describeElement(target)}: "${value}"` };
+					}
+					case "focus": {
+						const target = retarget(el, "follow-label");
+						if (target instanceof HTMLElement || target instanceof SVGElement) {
+							target.focus();
+							target.focus();
+						}
+						return { content: `已聚焦 ${describeElement(target)}` };
+					}
+					case "hover": {
+						const target = retarget(el, "none");
+						scrollIntoViewIfNeeded(target);
+						if (!force) await checkElementStable(target, 500);
+						if (target instanceof HTMLElement) dispatchHoverEvents(target);
+						return { content: `已悬停 ${describeElement(target)}` };
+					}
+					case "press": {
+						const key = params.key || params.value;
+						if (!key) return { content: "缺少 key 参数（如 Enter, Escape, Tab, Control+a）" };
+						const target = retarget(el, "none");
+						scrollIntoViewIfNeeded(target);
+						if (target instanceof HTMLElement) target.focus();
+						executePress(target, key);
+						if (splitKeyCombo(key).pop() === "Enter") (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement ? target.form ?? target.closest("form") : target.closest("form"))?.dispatchEvent(new Event("submit", {
+							bubbles: true,
+							cancelable: true
+						}));
+						return { content: `已在 ${describeElement(target)} 上按下 ${key}` };
 					}
 					case "get_text": {
 						const text = el.textContent?.trim() ?? "";
@@ -1996,8 +2380,21 @@ function createDomTool() {
 					case "get_attr": {
 						const attribute = params.attribute;
 						if (!attribute) return { content: "缺少 attribute 参数" };
-						const attrValue = el.getAttribute(attribute);
-						return { content: `${describeElement(el)} 的 ${attribute} = ${attrValue ?? "(不存在)"}` };
+						const attrName = attribute.toLowerCase();
+						if (attrName === "checked") {
+							if (el instanceof HTMLInputElement) return { content: `${describeElement(el)} 的 checked = ${String(el.checked)}` };
+							return { content: `${describeElement(el)} 的 checked = ${el.getAttribute("aria-checked") ?? "(不存在)"}` };
+						}
+						if (attrName === "selected") {
+							if (el instanceof HTMLOptionElement) return { content: `${describeElement(el)} 的 selected = ${String(el.selected)}` };
+							return { content: `${describeElement(el)} 的 selected = ${el.getAttribute("aria-selected") ?? "(不存在)"}` };
+						}
+						if (attrName === "disabled") {
+							if (el instanceof HTMLButtonElement || el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement) return { content: `${describeElement(el)} 的 disabled = ${String(el.disabled)}` };
+						}
+						if (attrName === "readonly" && (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement)) return { content: `${describeElement(el)} 的 readonly = ${String(el.readOnly)}` };
+						if (attrName === "value" && (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement)) return { content: `${describeElement(el)} 的 value = ${el.value || "(空)"}` };
+						return { content: `${describeElement(el)} 的 ${attribute} = ${el.getAttribute(attribute) ?? "(不存在)"}` };
 					}
 					case "set_attr": {
 						const attribute = params.attribute;
@@ -2255,13 +2652,18 @@ function generateSnapshot(root = document.body, options = {}) {
 			const orderedChildren = [...interactiveChildren, ...nonInteractiveChildren];
 			const selectedChildren = orderedChildren.slice(0, maxChildren);
 			const omittedChildren = orderedChildren.length - selectedChildren.length;
-			const childLines = [];
+			const childBlocks = [];
 			for (let i = 0; i < selectedChildren.length; i++) {
 				const childResult = walk(selectedChildren[i], depth, currentPath);
-				if (childResult) childLines.push(childResult);
+				if (childResult) childBlocks.push(childResult);
 			}
-			if (omittedChildren > 0) childLines.push(`${"  ".repeat(depth)}... (${omittedChildren} children omitted)`);
-			return childLines.join("\n");
+			if (childBlocks.length === 0 && omittedChildren <= 0) return "";
+			if (!(childBlocks.length >= 2 || omittedChildren > 0)) return childBlocks.join("\n");
+			const groupLines = [`${"  ".repeat(depth)}([${tag}] collapsed-group`];
+			for (const block of childBlocks) groupLines.push(indentMultiline(block, 1));
+			if (omittedChildren > 0) groupLines.push(`${"  ".repeat(depth + 1)}... (${omittedChildren} children omitted)`);
+			groupLines.push(`${"  ".repeat(depth)})`);
+			return groupLines.join("\n");
 		}
 		let line = `${indent}[${tag}]`;
 		if (directText) line += ` "${directText.slice(0, maxTextLength)}"`;
@@ -2312,6 +2714,13 @@ function queryAllElements(selector, limit = 20) {
 		return `选择器语法错误: ${selector}`;
 	}
 }
+/**
+* 多行文本块缩进（中）/ Indent each line of a multiline block (EN).
+*/
+function indentMultiline(block, indentLevel) {
+	const prefix = "  ".repeat(indentLevel);
+	return block.split("\n").map((line) => `${prefix}${line}`).join("\n");
+}
 function createPageInfoTool() {
 	return {
 		name: "page_info",
@@ -2388,26 +2797,42 @@ function createPageInfoTool() {
 //#endregion
 //#region src/web/tools/navigate-tool.ts
 /**
-* Navigate Tool — 基于 Web API 的页面导航工具。
-*
-* 替代 Playwright 的 goto/goBack/goForward/reload。
-* 运行环境：浏览器 Content Script。
+* Navigate Tool — 页面导航工具（增强版）。
 *
 * 支持 5 种动作：
 *   goto    — 跳转到指定 URL
 *   back    — 浏览器后退
 *   forward — 浏览器前进
 *   reload  — 刷新当前页面
-*   scroll  — 滚动页面到指定位置或元素
+*   scroll  — 滚动页面到指定位置或元素（支持 RefStore hash ID + 多策略对齐）
 */
+/** 解析 selector（支持 RefStore hash ID 和 CSS 选择器） */
+function resolveElement(selector) {
+	if (selector.startsWith("#")) {
+		const store = getActiveRefStore();
+		if (store) {
+			const id = selector.slice(1);
+			if (store.has(id)) return store.get(id) ?? null;
+		}
+	}
+	try {
+		return document.querySelector(selector);
+	} catch {
+		return null;
+	}
+}
 function createNavigateTool() {
 	return {
 		name: "navigate",
-		description: ["Navigate the current page.", "Actions: goto (open URL), back, forward, reload, scroll (to position or element)."].join(" "),
+		description: [
+			"Navigate the current page.",
+			"Actions: goto (open URL), back, forward, reload, scroll (to position or element).",
+			"scroll supports hash ID from snapshot (e.g. #r0) or CSS selector."
+		].join(" "),
 		schema: Type.Object({
 			action: Type.String({ description: "Navigation action: goto | back | forward | reload | scroll" }),
 			url: Type.Optional(Type.String({ description: "URL for goto action" })),
-			selector: Type.Optional(Type.String({ description: "CSS selector for scroll action (scrolls element into view)" })),
+			selector: Type.Optional(Type.String({ description: "Element ref ID from snapshot (e.g. #r0) or CSS selector for scroll action" })),
 			x: Type.Optional(Type.Number({ description: "Horizontal scroll position (pixels)" })),
 			y: Type.Optional(Type.Number({ description: "Vertical scroll position (pixels)" }))
 		}),
@@ -2433,9 +2858,10 @@ function createNavigateTool() {
 					case "scroll": {
 						const selector = params.selector;
 						if (selector) {
-							const el = document.querySelector(selector);
+							const el = resolveElement(selector);
 							if (!el) return { content: `未找到元素 "${selector}"` };
-							el.scrollIntoView({
+							if ("scrollIntoViewIfNeeded" in el) el.scrollIntoViewIfNeeded(true);
+							else el.scrollIntoView({
 								behavior: "smooth",
 								block: "center"
 							});
@@ -2468,36 +2894,88 @@ function createNavigateTool() {
 //#endregion
 //#region src/web/tools/wait-tool.ts
 /**
-* Wait Tool — 基于 MutationObserver 的元素等待工具。
+* Wait Tool 等待工具 / Wait utility for DOM conditions.
 *
-* 替代 Playwright 的 waitForSelector/waitForNavigation。
-* 运行环境：浏览器 Content Script。
+* 支持动作 / Supported actions:
+* - wait_for_selector: 等待选择器达到状态 / wait selector state
+* - wait_for_hidden: 等待元素隐藏或移除 / wait element hidden or detached
+* - wait_for_text: 等待页面出现文本 / wait text appears in page
+* - wait_for_stable: 等待 DOM 进入静默窗口 / wait DOM quiet window
 *
-* 支持 4 种动作：
-*   wait_for_selector  — 等待匹配选择器的元素出现
-*   wait_for_hidden    — 等待元素消失或隐藏
-*   wait_for_text      — 等待页面中出现指定文本
-*   wait_for_stable    — 等待 DOM 在一段时间内无变化
+* 说明 / Notes:
+* - hash selector（如 #abc123）优先通过 RefStore 解析。
+* - 可见性语义与 dom-tool 保持一致（参考 Playwright 风格）。
 */
-/** 默认超时时间（毫秒） */
 const DEFAULT_TIMEOUT = 1e4;
+const POLL_INTERVAL_MS = 80;
+const STABLE_TICK_MS = 50;
+const OBSERVER_OPTIONS = {
+	childList: true,
+	subtree: true,
+	attributes: true,
+	characterData: true
+};
+const TEXT_OBSERVER_OPTIONS = {
+	childList: true,
+	subtree: true,
+	characterData: true
+};
 /**
-* Playwright 风格可见性判定（近似）。
+* 可见性判定 / Visibility check.
+*
+* 与 dom-tool 保持一致，处理 display:contents、visibility、opacity、零尺寸等场景。
 */
 function isVisible(el) {
 	if (!(el instanceof HTMLElement || el instanceof SVGElement)) return false;
 	if (!el.isConnected) return false;
 	const style = window.getComputedStyle(el);
-	if (style.display === "none" || style.visibility === "hidden") return false;
+	if (style.display === "contents") {
+		for (let child = el.firstChild; child; child = child.nextSibling) {
+			if (child.nodeType === Node.ELEMENT_NODE && isVisible(child)) return true;
+			if (child.nodeType === Node.TEXT_NODE) {
+				const range = document.createRange();
+				range.selectNodeContents(child);
+				const rects = range.getClientRects();
+				for (let i = 0; i < rects.length; i++) if (rects[i].width > 0 && rects[i].height > 0) return true;
+			}
+		}
+		return false;
+	}
+	if (style.display === "none") return false;
+	if (typeof el.checkVisibility === "function") {
+		if (!el.checkVisibility()) return false;
+	}
+	if (style.visibility !== "visible") return false;
 	if (style.opacity === "0") return false;
 	const rect = el.getBoundingClientRect();
 	return rect.width > 0 && rect.height > 0;
 }
 /**
-* 读取 selector 当前状态。
+* 解析选择器 / Resolve selector.
+*
+* 先尝试 RefStore hash，再回退到 document.querySelector。
+*/
+function resolveSelector(selector) {
+	if (selector.startsWith("#")) {
+		const store = getActiveRefStore();
+		if (store) {
+			const id = selector.slice(1);
+			if (store.has(id)) return store.get(id) ?? null;
+		}
+	}
+	try {
+		return document.querySelector(selector);
+	} catch {
+		return null;
+	}
+}
+/**
+* 计算选择器状态 / Evaluate selector state.
+*
+* @returns matched 表示是否达到目标状态；element 为当前命中的元素（如果存在）。
 */
 function evaluateSelectorState(selector, state) {
-	const el = document.querySelector(selector) ?? void 0;
+	const el = resolveSelector(selector) ?? void 0;
 	switch (state) {
 		case "attached": return {
 			matched: Boolean(el),
@@ -2519,7 +2997,9 @@ function evaluateSelectorState(selector, state) {
 	}
 }
 /**
-* 等待 selector 达到指定状态（近似 Playwright state 语义）。
+* 等待选择器达到指定状态 / Wait selector reaches state.
+*
+* 策略：轮询 + MutationObserver 双通道，既保证及时性也降低漏检概率。
 */
 function waitForSelectorState(selector, state, timeoutMs) {
 	return new Promise((resolve, reject) => {
@@ -2545,19 +3025,16 @@ function waitForSelectorState(selector, state, timeoutMs) {
 		const timer = setTimeout(() => {
 			finish(() => reject(/* @__PURE__ */ new Error(`等待 "${selector}" 达到状态 "${state}" 超时 (${timeoutMs}ms)`)));
 		}, timeoutMs);
-		const interval = setInterval(check, 80);
+		const interval = setInterval(check, POLL_INTERVAL_MS);
 		const observer = new MutationObserver(check);
-		observer.observe(document.body, {
-			childList: true,
-			subtree: true,
-			attributes: true,
-			characterData: true
-		});
+		observer.observe(document.body, OBSERVER_OPTIONS);
 		check();
 	});
 }
 /**
-* 等待页面中出现指定文本。
+* 等待文本出现 / Wait text appears.
+*
+* 先做一次即时检查，再监听 DOM 变化。
 */
 function waitForText(text, timeoutMs) {
 	return new Promise((resolve, reject) => {
@@ -2576,15 +3053,13 @@ function waitForText(text, timeoutMs) {
 				resolve();
 			}
 		});
-		observer.observe(document.body, {
-			childList: true,
-			subtree: true,
-			characterData: true
-		});
+		observer.observe(document.body, TEXT_OBSERVER_OPTIONS);
 	});
 }
 /**
-* 等待页面进入稳定状态：在 quietMs 时间窗口内没有 DOM 变化。
+* 等待 DOM 稳定 / Wait DOM stable.
+*
+* 定义：quietMs 窗口内没有任何 MutationObserver 事件。
 */
 function waitForDomStable(timeoutMs, quietMs) {
 	return new Promise((resolve, reject) => {
@@ -2599,12 +3074,7 @@ function waitForDomStable(timeoutMs, quietMs) {
 		const observer = new MutationObserver(() => {
 			lastMutationAt = Date.now();
 		});
-		observer.observe(document.body, {
-			childList: true,
-			subtree: true,
-			attributes: true,
-			characterData: true
-		});
+		observer.observe(document.body, OBSERVER_OPTIONS);
 		const tick = setInterval(() => {
 			const now = Date.now();
 			if (now - startedAt > timeoutMs) {
@@ -2612,7 +3082,7 @@ function waitForDomStable(timeoutMs, quietMs) {
 				return;
 			}
 			if (now - lastMutationAt >= quietMs) finish(true);
-		}, 50);
+		}, STABLE_TICK_MS);
 	});
 }
 function createWaitTool() {
@@ -2965,7 +3435,17 @@ function registerToolHandler(executors) {
 *   │  └──────────┘  └────────────┘  └──────────────┘ │
 *   └──────────────────────────────────────────────────┘
 */
-var WebAgent = class {
+var WebAgent = class WebAgent {
+	/** 默认系统提示词 key（兼容旧版 setSystemPrompt(prompt)）。 */
+	static DEFAULT_SYSTEM_PROMPT_KEY = "default";
+	/** 默认内置工具名（注册后受保护，不允许删除）。 */
+	static DEFAULT_TOOL_NAMES = [
+		"dom",
+		"navigate",
+		"page_info",
+		"wait",
+		"evaluate"
+	];
 	/** 用户传入的自定义 AI 客户端实例（优先级高于 token/provider） */
 	client;
 	token;
@@ -2975,7 +3455,10 @@ var WebAgent = class {
 	stream;
 	dryRun;
 	maxRounds;
-	customSystemPrompt;
+	/** system prompt 注册表（key -> prompt 文本）。 */
+	systemPromptRegistry = /* @__PURE__ */ new Map();
+	/** 受保护工具集合（默认工具）。 */
+	protectedToolNames = /* @__PURE__ */ new Set();
 	/** 多轮对话记忆开关 */
 	memory;
 	/** 对话历史（memory 开启时自动累积） */
@@ -2997,10 +3480,11 @@ var WebAgent = class {
 		this.stream = options.stream ?? true;
 		this.dryRun = options.dryRun ?? false;
 		this.maxRounds = options.maxRounds ?? 40;
-		this.customSystemPrompt = options.systemPrompt;
 		this.memory = options.memory ?? false;
 		this.autoSnapshot = options.autoSnapshot ?? true;
 		this.snapshotOptions = options.snapshotOptions ?? {};
+		if (typeof options.systemPrompt === "string") this.setSystemPrompt(options.systemPrompt);
+		else if (options.systemPrompt && typeof options.systemPrompt === "object") this.setSystemPrompts(options.systemPrompt);
 	}
 	/** 注册所有内置 Web 工具（dom, navigate, page_info, wait, evaluate） */
 	registerTools() {
@@ -3009,11 +3493,41 @@ var WebAgent = class {
 		this.registry.register(createPageInfoTool());
 		this.registry.register(createWaitTool());
 		this.registry.register(createEvaluateTool());
+		for (const name of WebAgent.DEFAULT_TOOL_NAMES) this.protectedToolNames.add(name);
 	}
 	/** 注册一个自定义工具 */
 	registerTool(tool) {
 		this.registry.register(tool);
 	}
+	/**
+	* 删除一个已注册工具。
+	* - 默认内置工具（registerTools 注册）不允许删除
+	* - 返回 true 表示删除成功，false 表示不存在或受保护
+	*/
+	removeTool(name) {
+		if (this.protectedToolNames.has(name)) return false;
+		return this.registry.unregister(name);
+	}
+	/** 检查工具是否已注册。 */
+	hasTool(name) {
+		return this.registry.has(name);
+	}
+	/** 获取当前所有已注册工具名。 */
+	getToolNames() {
+		return this.registry.getDefinitions().map((tool) => tool.name);
+	}
+	/**
+	* 删除所有“非默认”工具。
+	* 返回值为本次被删除的工具名数组。
+	*/
+	clearCustomTools() {
+		const removed = [];
+		for (const tool of this.registry.getDefinitions()) {
+			if (this.protectedToolNames.has(tool.name)) continue;
+			if (this.registry.unregister(tool.name)) removed.push(tool.name);
+		}
+		return removed;
+	}
 	/** 获取所有已注册的工具定义列表 */
 	getTools() {
 		return this.registry.getDefinitions();
@@ -3051,9 +3565,37 @@ var WebAgent = class {
 	setDryRun(enabled) {
 		this.dryRun = enabled;
 	}
-	/** 设置自定义系统提示词 */
-	setSystemPrompt(prompt) {
-		this.customSystemPrompt = prompt;
+	setSystemPrompt(keyOrPrompt, maybePrompt) {
+		const key = maybePrompt === void 0 ? WebAgent.DEFAULT_SYSTEM_PROMPT_KEY : keyOrPrompt.trim();
+		const prompt = maybePrompt === void 0 ? keyOrPrompt : maybePrompt;
+		if (!key) throw new Error("system prompt 的 key 不能为空");
+		const value = prompt.trim();
+		if (!value) throw new Error("system prompt 不能为空");
+		this.systemPromptRegistry.set(key, value);
+	}
+	/** 批量注册系统提示词（key -> prompt）。 */
+	setSystemPrompts(prompts) {
+		for (const [key, prompt] of Object.entries(prompts)) this.setSystemPrompt(key, prompt);
+	}
+	/** 注销指定 key 的系统提示词。 */
+	removeSystemPrompt(key) {
+		return this.systemPromptRegistry.delete(key);
+	}
+	/** 只保留指定 key 的系统提示词，其余全部删除。 */
+	keepOnlySystemPrompt(key) {
+		if (!this.systemPromptRegistry.has(key)) return false;
+		const value = this.systemPromptRegistry.get(key);
+		this.systemPromptRegistry.clear();
+		this.systemPromptRegistry.set(key, value);
+		return true;
+	}
+	/** 获取当前已注册的全部系统提示词（浅拷贝）。 */
+	getSystemPrompts() {
+		return Object.fromEntries(this.systemPromptRegistry.entries());
+	}
+	/** 删除全部系统提示词。 */
+	clearSystemPrompts() {
+		this.systemPromptRegistry.clear();
 	}
 	/** 开启或关闭多轮对话记忆 */
 	setMemory(enabled) {
@@ -3095,7 +3637,11 @@ var WebAgent = class {
 	*/
 	async chat(message) {
 		const client = this.client ?? this.createBuiltinClient();
-		let systemPrompt = this.customSystemPrompt ?? buildSystemPrompt({ tools: this.registry.getDefinitions() });
+		let systemPrompt = buildSystemPrompt({ tools: this.registry.getDefinitions() });
+		if (this.systemPromptRegistry.size > 0) {
+			const extensionText = Array.from(this.systemPromptRegistry.entries()).map(([key, prompt]) => `- [${key}]\n${prompt}`).join("\n\n");
+			systemPrompt += `\n\n## Registered System Prompt Extensions\n${extensionText}`;
+		}
 		const refStore = new RefStore(globalThis.location?.href);
 		setActiveRefStore(refStore);
 		let initialSnapshot;