agentpage 0.0.33 → 0.0.34

package/dist/index.mjs

@@ -10,7 +10,25 @@ const DEFAULT_MAX_ROUNDS = 40;
 const DEFAULT_RECOVERY_WAIT_MS = 100;
 const DEFAULT_ACTION_RECOVERY_ROUNDS = 2;
 const DEFAULT_NOT_FOUND_RETRY_ROUNDS = 2;
-const DEFAULT_NOT_FOUND_RETRY_WAIT_MS = 2e3;
+const DEFAULT_NOT_FOUND_RETRY_WAIT_MS = 1e3;
+const DEFAULT_ROUND_STABILITY_WAIT_TIMEOUT_MS = 4e3;
+const DEFAULT_ROUND_STABILITY_WAIT_QUIET_MS = 200;
+const DEFAULT_ROUND_STABILITY_WAIT_LOADING_SELECTORS = [
+	".ant-spin",
+	".ant-spin-spinning",
+	".ant-skeleton",
+	".el-loading-mask",
+	".bk-loading",
+	".bk-spin-loading",
+	".bk-skeleton",
+	".bk-sideslider-loading",
+	".t-loading",
+	".t-skeleton",
+	".t-skeleton__row",
+	"[aria-busy=\"true\"]",
+	".skeleton",
+	".loading"
+];
 /** 快照起始标记 — 用于在消息中识别快照边界 */
 const SNAPSHOT_START = "<!-- SNAPSHOT_START -->";
 /** 快照结束标记 */
@@ -163,6 +181,36 @@ function shouldForceRoundBreak(toolName, toolInput) {
 	return toolName === "evaluate";
 }
 /**
+* 判定动作是否可能引发页面结构或状态变化。
+*
+* 用于“轮次后稳定等待”触发条件：
+* - 命中 true：本轮结束后执行加载态 + DOM 静默双重等待
+* - 命中 false：跳过等待，直接进入下一轮
+*/
+function isPotentialDomMutation(toolName, toolInput) {
+	const action = getToolAction(toolInput);
+	if (toolName === "navigate") return true;
+	if (toolName === "evaluate") return true;
+	if (toolName !== "dom") return false;
+	if (!action) return false;
+	return [
+		"click",
+		"fill",
+		"select_option",
+		"clear",
+		"check",
+		"uncheck",
+		"type",
+		"focus",
+		"hover",
+		"scroll",
+		"press",
+		"set_attr",
+		"add_class",
+		"remove_class"
+	].includes(action);
+}
+/**
 * 采集找不到元素任务。
 *
 * 返回 null 表示当前结果不属于“元素未找到”，
@@ -247,7 +295,7 @@ function hasToolError(result) {
 * 4) 返回稳定字符串给 loop，供后续注入消息与统计。
 *
 * 默认参数意图：
-* - `maxDepth=8`: 保留足够层级，减少关键控件被截断。
+* - `maxDepth=12`: 保留更深层级，减少深层组件控件被截断。
 * - `viewportOnly=false`: 优先完整性，避免误判“元素不存在”。
 * - `pruneLayout=true`: 抑制纯布局噪声，降低 token 压力。
 * - `maxNodes=500` / `maxChildren=30`: 控制体积上限，兼顾可读性。
@@ -272,7 +320,7 @@ function hasToolError(result) {
 async function readPageSnapshot(registry, options) {
 	return toContentString((await registry.dispatch("page_info", {
 		action: "snapshot",
-		maxDepth: options?.maxDepth ?? 8,
+		maxDepth: options?.maxDepth ?? 12,
 		viewportOnly: options?.viewportOnly ?? false,
 		pruneLayout: options?.pruneLayout ?? true,
 		maxNodes: options?.maxNodes ?? 500,
@@ -696,7 +744,7 @@ function detectIdleLoop(toolCalls, consecutiveReadOnlyRounds) {
 * - 达到 `maxRounds`
 */
 async function executeAgentLoop(params) {
-	const { client, registry, systemPrompt, message, initialSnapshot, history, dryRun = false, maxRounds = DEFAULT_MAX_ROUNDS, callbacks } = params;
+	const { client, registry, systemPrompt, message, initialSnapshot, history, dryRun = false, maxRounds = DEFAULT_MAX_ROUNDS, roundStabilityWait, callbacks } = params;
 	const tools = registry.getDefinitions();
 	const allToolCalls = [];
 	const fullToolTrace = [];
@@ -717,6 +765,12 @@ async function executeAgentLoop(params) {
 	let lastRoundHadError = false;
 	let protocolViolationHint;
 	const snapshotExpandRefIds = /* @__PURE__ */ new Set();
+	const effectiveRoundStabilityWait = {
+		enabled: roundStabilityWait?.enabled ?? true,
+		timeoutMs: Math.max(200, Math.floor(roundStabilityWait?.timeoutMs ?? DEFAULT_ROUND_STABILITY_WAIT_TIMEOUT_MS)),
+		quietMs: Math.max(50, Math.floor(roundStabilityWait?.quietMs ?? DEFAULT_ROUND_STABILITY_WAIT_QUIET_MS)),
+		loadingSelectors: [...new Set([...DEFAULT_ROUND_STABILITY_WAIT_LOADING_SELECTORS, ...roundStabilityWait?.loadingSelectors ?? []].map((selector) => selector.trim()).filter(Boolean))]
+	};
 	let recoveryCount = 0;
 	let redundantInterceptCount = 0;
 	let pendingNotFoundRetry;
@@ -748,6 +802,30 @@ async function executeAgentLoop(params) {
 		} : void 0);
 		recordSnapshotStats(pageContext.latestSnapshot);
 	};
+	/**
+	* 轮次后稳定等待（双重等待）。
+	*
+	* 顺序固定为：
+	* 1) 等待 loading 指示器隐藏
+	* 2) 等待 DOM quiet window
+	*/
+	const runRoundStabilityBarrier = async () => {
+		if (!effectiveRoundStabilityWait.enabled) return;
+		if (!registry.has("wait")) return;
+		const timeout = effectiveRoundStabilityWait.timeoutMs;
+		const loadingSelector = effectiveRoundStabilityWait.loadingSelectors.join(", ");
+		if (loadingSelector) await registry.dispatch("wait", {
+			action: "wait_for_selector",
+			selector: loadingSelector,
+			state: "hidden",
+			timeout
+		});
+		await registry.dispatch("wait", {
+			action: "wait_for_stable",
+			timeout,
+			quietMs: effectiveRoundStabilityWait.quietMs
+		});
+	};
 	if (pageContext.latestSnapshot) recordSnapshotStats(pageContext.latestSnapshot);
 	/**
 	* 追加工具轨迹。
@@ -863,6 +941,7 @@ async function executeAgentLoop(params) {
 			break;
 		}
 		let roundHasError = false;
+		let roundHasPotentialDomMutation = false;
 		const executedTaskCalls = [];
 		const roundMissingTasks = [];
 		for (const tc of response.toolCalls) {
@@ -893,6 +972,7 @@ async function executeAgentLoop(params) {
 			const missingTask = collectMissingTask(tc.name, tc.input, result);
 			if (missingTask) roundMissingTasks.push(missingTask);
 			if (result.details && typeof result.details === "object") roundHasError = roundHasError || Boolean(result.details.error);
+			if (!hasToolError(result) && isPotentialDomMutation(tc.name, tc.input)) roundHasPotentialDomMutation = true;
 			if (tc.name === "page_info" && getToolAction(tc.input) === "snapshot") {
 				pageContext.latestSnapshot = toContentString(result.content);
 				recordSnapshotStats(pageContext.latestSnapshot);
@@ -916,6 +996,11 @@ async function executeAgentLoop(params) {
 		lastRoundHadError = roundHasError;
 		previousRoundTasks = buildTaskArray(executedTaskCalls);
 		previousRoundPlannedTasks = plannedTasksCurrentRound;
+		if (parsedInstructionState.hasRemainingProtocol && remainingInstruction.trim().length === 0 && !roundHasError) {
+			finalReply = response.text?.trim() || "任务已完成。";
+			if (finalReply) callbacks?.onText?.(finalReply);
+			break;
+		}
 		const idleResult = detectIdleLoop(response.toolCalls.map((tc) => ({
 			name: tc.name,
 			input: tc.input
@@ -926,6 +1011,7 @@ async function executeAgentLoop(params) {
 			break;
 		}
 		consecutiveReadOnlyRounds = idleResult;
+		if (roundHasPotentialDomMutation) await runRoundStabilityBarrier();
 		await refreshSnapshot();
 	}
 	const resultMessages = [...history ?? [], {
@@ -1575,7 +1661,13 @@ var ToolRegistry = class {
 
 //#endregion
 //#region src/core/system-prompt.ts
-/** 规范化额外指令。 */
+/**
+* 规范化额外指令：统一转为非空字符串数组。
+*
+* - 单字符串 → 单元素数组
+* - 字符串数组 → 过滤空值
+* - undefined → 空数组
+*/
 function normalizeExtraInstructions(input) {
 	if (!input) return [];
 	return (Array.isArray(input) ? input : [input]).map((s) => s.trim()).filter(Boolean);
@@ -1583,9 +1675,32 @@ function normalizeExtraInstructions(input) {
 /**
 * 构建系统提示词。
 *
-* 约束：
-* - 输出给模型的提示词正文统一为英文。
-* - 中文仅用于源码注释，便于团队维护。
+* 输出结构（按章节顺序）：
+* 1. **Core Rules** — Agent 核心行为规则
+*    - 快照驱动决策：仅基于当前快照 + 剩余任务工作
+*    - 增量消费模型：每轮执行后输出 REMAINING 推进任务
+*    - hash ID 定位：仅交互元素携带 #hashID，非交互元素为上下文
+*    - 事件信号：listeners="..." 标注运行时事件绑定
+*    - 批量执行：同轮完成所有独立可见操作
+*    - 输入顺序：fill/type 前必须先 focus/click 同一目标
+*    - DOM 变化断轮：会改变 DOM 的动作执行后等待下一轮新快照
+*    - 停机规则：任务完成后输出 REMAINING: DONE
+*
+* 2. **Listener Abbrevs** — 事件简写对照表
+*    - 快照中 listeners="clk,inp,chg" 的简写含义
+*    - 与 page-info-tool.ts 的 EVENT_ABBREV 映射一致
+*
+* 3. **Output Contract** — 输出协议
+*    - 每轮返回工具调用 + REMAINING 文本行
+*
+* 4. **Available Tools**（可选） — 当前注册的工具及描述
+*
+* 5. **Reasoning Profile**（可选） — 思考深度配置
+*
+* 6. **Extra Instructions**（可选） — 用户自定义额外指令
+*
+* @param params - 构建参数（工具列表、思考深度、额外指令）
+* @returns 完整的系统提示词字符串（英文）
 */
 function buildSystemPrompt(params = {}) {
 	const sections = [];
@@ -1598,6 +1713,9 @@ function buildSystemPrompt(params = {}) {
 		"  Input: (1) current remaining task, (2) previous round executed actions, (3) actions you execute this round.",
 		"  Output: new remaining task after removing this-round actions.",
 		"- Use only visible targets from snapshot. Use #hashID as selector. Do not guess CSS selectors.",
+		"- Only interactive elements (with events, inputs, buttons, links, etc.) carry #hashID. Elements without #hashID are context-only (labels, headings, text) and cannot be targeted.",
+		"- Snapshot tag in brackets may show ARIA role instead of HTML tag when it better describes the interaction pattern (e.g. [combobox] for input with role=\"combobox\", [slider] for div with role=\"slider\"). Treat the bracket tag as the primary interaction hint.",
+		"- listeners=\"...\" on snapshot indicates bound event handlers (see Listener Abbrevs below). Prefer targets with relevant listeners when multiple candidates look similar.",
 		"- Batch independent visible actions in one round. Do not split one form into many rounds unnecessarily.",
 		"- 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.",
@@ -1616,6 +1734,9 @@ function buildSystemPrompt(params = {}) {
 		"- 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.",
 		"",
+		"## Listener Abbrevs",
+		"clk=click dbl=dblclick mdn=mousedown mup=mouseup mmv=mousemove mov=mouseover mot=mouseout men=mouseenter mlv=mouseleave pdn=pointerdown pup=pointerup pmv=pointermove tst=touchstart ted=touchend kdn=keydown kup=keyup inp=input chg=change sub=submit fcs=focus blr=blur scl=scroll whl=wheel drg=drag drs=dragstart dre=dragend drp=drop ctx=contextmenu",
+		"",
 		"## Output Contract",
 		"- Return tool calls for this round.",
 		"- Also include one plain text line:",
@@ -1642,6 +1763,81 @@ function buildSystemPrompt(params = {}) {
 	return sections.join("\n\n");
 }
 
+//#endregion
+//#region src/web/event-listener-tracker.ts
+const elementEventMap = /* @__PURE__ */ new WeakMap();
+let installed = false;
+let originalAddEventListener;
+let originalRemoveEventListener;
+function normalizeEventType(type) {
+	if (typeof type !== "string") return null;
+	return type.trim().toLowerCase() || null;
+}
+function canTrackElementTarget(target) {
+	if (typeof Element === "undefined") return false;
+	return target instanceof Element;
+}
+function trackElementEvent(target, type) {
+	if (!canTrackElementTarget(target)) return;
+	const prev = elementEventMap.get(target);
+	if (prev) {
+		prev.add(type);
+		return;
+	}
+	elementEventMap.set(target, new Set([type]));
+}
+function untrackElementEvent(target, type) {
+	if (!canTrackElementTarget(target)) return;
+	const prev = elementEventMap.get(target);
+	if (!prev) return;
+	prev.delete(type);
+	if (prev.size === 0) elementEventMap.delete(target);
+}
+/**
+* 安装全局监听追踪补丁（幂等）。
+*/
+function installEventListenerTracking() {
+	if (installed) return;
+	if (typeof EventTarget === "undefined") return;
+	const proto = EventTarget.prototype;
+	const nativeAdd = proto.addEventListener;
+	const nativeRemove = proto.removeEventListener;
+	if (typeof nativeAdd !== "function" || typeof nativeRemove !== "function") return;
+	originalAddEventListener = nativeAdd;
+	originalRemoveEventListener = nativeRemove;
+	proto.addEventListener = function patchedAddEventListener(type, listener, options) {
+		originalAddEventListener?.call(this, type, listener, options);
+		try {
+			const normalizedType = normalizeEventType(type);
+			if (!normalizedType || listener == null) return;
+			trackElementEvent(this, normalizedType);
+		} catch {}
+	};
+	proto.removeEventListener = function patchedRemoveEventListener(type, listener, options) {
+		originalRemoveEventListener?.call(this, type, listener, options);
+		try {
+			const normalizedType = normalizeEventType(type);
+			if (!normalizedType || listener == null) return;
+			untrackElementEvent(this, normalizedType);
+		} catch {}
+	};
+	installed = true;
+}
+/**
+* 读取元素已记录的事件名（排序后返回，便于稳定输出）。
+*/
+function getTrackedElementEvents(el) {
+	const set = elementEventMap.get(el);
+	if (!set || set.size === 0) return [];
+	return Array.from(set).sort();
+}
+/**
+* 判断元素是否存在至少一个被追踪到的事件绑定。
+*/
+function hasTrackedElementEvents(el) {
+	return (elementEventMap.get(el)?.size ?? 0) > 0;
+}
+
 //#endregion
 //#region src/web/tools/dom-tool.ts
 /**
@@ -1661,7 +1857,7 @@ function buildSystemPrompt(params = {}) {
 *
 * 运行环境：浏览器 Content Script（直接访问 DOM，无 CDP）。
 */
-const DEFAULT_WAIT_MS = 2e3;
+const DEFAULT_WAIT_MS = 1200;
 /** scrollIntoView 轮换策略（参考 Playwright dom.ts） */
 const SCROLL_OPTIONS = [
 	void 0,
@@ -1721,6 +1917,16 @@ const KEY_CODE_MAP = {
 	Alt: "AltLeft",
 	Meta: "MetaLeft"
 };
+const FILL_RELEVANT_EVENTS = new Set([
+	"input",
+	"change",
+	"focus",
+	"blur",
+	"keydown",
+	"click",
+	"mousedown",
+	"pointerdown"
+]);
 let activeRefStore;
 function setActiveRefStore(store) {
 	activeRefStore = store;
@@ -1929,15 +2135,34 @@ function ensureActionable(el, action, selector, force) {
 		"fill",
 		"type",
 		"clear"
-	].includes(action) && !isEditableElement(el)) return {
-		content: `"${selector}" 不是可编辑元素，无法执行 ${action}`,
-		details: {
-			error: true,
-			code: "UNSUPPORTED_FILL_TARGET",
-			action,
-			selector
-		}
-	};
+	].includes(action) && !isEditableElement(el)) {
+		if (action === "fill" && el.getAttribute("role") === "slider") return null;
+		return {
+			content: `"${selector}" 不是可编辑元素，无法执行 ${action}`,
+			details: {
+				error: true,
+				code: "UNSUPPORTED_FILL_TARGET",
+				action,
+				selector
+			}
+		};
+	}
+	return null;
+}
+/**
+* 为 role=slider 查找关联的数值输入框。
+* 典型场景：Element Plus slider + input-number 同属一个 form-item。
+*/
+function findAssociatedSliderInput(slider) {
+	const candidates = [];
+	const formItem = slider.closest(".el-form-item");
+	if (formItem) candidates.push(formItem);
+	let cursor = slider.parentElement;
+	for (let depth = 0; cursor && depth < 4; depth++, cursor = cursor.parentElement) candidates.push(cursor);
+	for (const scope of candidates) {
+		const input = scope.querySelector("input[type=\"number\"], input[role=\"spinbutton\"], .el-input-number input:not([type=\"hidden\"])");
+		if (input instanceof HTMLInputElement && isEditableElement(input) && isElementVisible(input)) return input;
+	}
 	return null;
 }
 function getClickPoint(el) {
@@ -2034,6 +2259,163 @@ function setNativeValue(el, value) {
 	if (desc?.set) desc.set.call(el, value);
 	else el.value = value;
 }
+function getFillEventSupportScore(el) {
+	let score = 0;
+	if (el.hasAttribute("oninput") || el.hasAttribute("onchange")) score += 80;
+	if (el.hasAttribute("onfocus") || el.hasAttribute("onblur")) score += 60;
+	if (el.hasAttribute("onclick")) score += 40;
+	const tracked = getTrackedElementEvents(el);
+	for (const eventName of tracked) {
+		if (!FILL_RELEVANT_EVENTS.has(eventName)) continue;
+		if (eventName === "input") score += 40;
+		else if (eventName === "change") score += 35;
+		else if (eventName === "focus" || eventName === "blur") score += 28;
+		else if (eventName === "keydown") score += 24;
+		else score += 14;
+	}
+	return score;
+}
+function isCandidateFillTarget(el) {
+	if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) return !isElementDisabled(el);
+	if (el instanceof HTMLElement && el.isContentEditable) return true;
+	return false;
+}
+function executeFillOnResolvedTarget(target, value, selector, action, sourceHint) {
+	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: "MALFORMED_VALUE",
+					action,
+					selector
+				}
+			};
+			dispatchInputEvents(target);
+			const suffix = sourceHint ? `（${sourceHint}）` : "";
+			return { content: `已填写 ${describeElement(target)}: "${finalVal}"${suffix}` };
+		}
+		if (type === "number" && Number.isNaN(Number(value.trim()))) return {
+			content: `"${selector}" 为 input[type=number]，无法填写非数字 "${value}"`,
+			details: {
+				error: true,
+				code: "INVALID_NUMBER",
+				action,
+				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
+			}
+		};
+		const suffix = sourceHint ? `（${sourceHint}）` : "";
+		return { content: `已填写 ${describeElement(target)}: "${value}"${suffix}` };
+	}
+	if (target instanceof HTMLTextAreaElement) {
+		scrollIntoViewIfNeeded(target);
+		target.focus();
+		selectText(target);
+		setNativeValue(target, value);
+		dispatchInputEvents(target);
+		const suffix = sourceHint ? `（${sourceHint}）` : "";
+		return { content: `已填写 ${describeElement(target)}: "${value}"${suffix}` };
+	}
+	if (target instanceof HTMLSelectElement) {
+		target.focus();
+		const options = Array.from(target.options);
+		let matched = options.find((o) => o.value === value);
+		if (!matched) {
+			const normalized = value.trim().toLowerCase();
+			matched = options.find((o) => o.text.trim().toLowerCase() === normalized);
+		}
+		if (!matched) return { content: `"${selector}" 下拉框中不存在选项 "${value}"` };
+		target.value = matched.value;
+		dispatchInputEvents(target);
+		const suffix = sourceHint ? `（${sourceHint}）` : "";
+		return { content: `已填写 ${describeElement(target)}: "${value}"${suffix}` };
+	}
+	if (target instanceof HTMLElement && target.isContentEditable) {
+		target.focus();
+		selectText(target);
+		if (value) document.execCommand("insertText", false, value);
+		else document.execCommand("delete", false, void 0);
+		const suffix = sourceHint ? `（${sourceHint}）` : "";
+		return { content: `已填写 ${describeElement(target)}: "${value}"${suffix}` };
+	}
+	return null;
+}
+function guessNearbyFillTarget(anchor, value) {
+	const preferNumeric = Number.isFinite(Number(value));
+	const scopeEntries = [];
+	const formItem = anchor.closest(".el-form-item");
+	if (formItem) scopeEntries.push({
+		scope: formItem,
+		level: 0
+	});
+	let cursor = anchor.parentElement;
+	for (let level = 1; cursor && level <= 4; level++, cursor = cursor.parentElement) scopeEntries.push({
+		scope: cursor,
+		level
+	});
+	const visited = /* @__PURE__ */ new Set();
+	let best = null;
+	for (const { scope, level } of scopeEntries) {
+		const candidates = Array.from(scope.querySelectorAll("input:not([type=\"hidden\"]), textarea, select, [contenteditable=\"true\"], [role=\"spinbutton\"]"));
+		for (const candidate of candidates) {
+			if (!(candidate instanceof Element)) continue;
+			if (visited.has(candidate)) continue;
+			visited.add(candidate);
+			if (!isCandidateFillTarget(candidate)) continue;
+			if (!isElementVisible(candidate)) continue;
+			let score = 100 - level * 18;
+			score += getFillEventSupportScore(candidate);
+			if (candidate instanceof HTMLInputElement) {
+				const type = candidate.type.toLowerCase();
+				if (preferNumeric && (type === "number" || candidate.getAttribute("role") === "spinbutton")) score += 80;
+				if (!preferNumeric && [
+					"text",
+					"",
+					"search",
+					"email",
+					"tel",
+					"url",
+					"password"
+				].includes(type)) score += 36;
+			}
+			if (candidate.getAttribute("placeholder")) score += 8;
+			if (candidate.getAttribute("aria-label")) score += 8;
+			if (!best || score > best.score) best = {
+				el: candidate,
+				score
+			};
+		}
+	}
+	return best?.el ?? null;
+}
 function selectText(el) {
 	if (el instanceof HTMLInputElement) {
 		el.select();
@@ -2253,7 +2635,7 @@ function createDomTool() {
 			deltaY: Type.Optional(Type.Number({ description: "Vertical scroll delta for scroll action. Positive = down, negative = up." })),
 			deltaX: Type.Optional(Type.Number({ description: "Horizontal scroll delta for scroll action." })),
 			steps: Type.Optional(Type.Number({ description: "Repeat count for scroll action (default 1, max 20)." })),
-			waitMs: Type.Optional(Type.Number({ description: "Wait timeout in ms before action (default: 2000)." })),
+			waitMs: Type.Optional(Type.Number({ description: "Wait timeout in ms before action (default: 1200)." })),
 			waitSeconds: Type.Optional(Type.Number({ description: "Wait timeout in seconds (fallback for waitMs)." })),
 			force: Type.Optional(Type.Boolean({ description: "Skip actionability checks (default false)." }))
 		}),
@@ -2335,87 +2717,71 @@ function createDomTool() {
 						const value = params.value;
 						if (value === void 0) return { content: "缺少 value 参数" };
 						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 (target instanceof HTMLElement && target.getAttribute("role") === "slider") {
+							const numericValue = Number(value);
+							if (!Number.isFinite(numericValue)) {
+								const guessed = guessNearbyFillTarget(target, value);
+								if (guessed) {
+									const guessedResult = executeFillOnResolvedTarget(guessed, value, selector, action, "heuristic-nearby-target");
+									if (guessedResult) return guessedResult;
 								}
-							};
-							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}）`,
+								return {
+									content: `"${selector}" 为 role=slider，未找到可推断填写目标`,
 									details: {
 										error: true,
-										code: "MALFORMED_VALUE",
+										code: "UNSUPPORTED_FILL_TARGET",
 										action,
 										selector
 									}
 								};
-								dispatchInputEvents(target);
-								return { content: `已填写 ${describeElement(target)}: "${finalVal}"` };
 							}
-							if (type === "number" && isNaN(Number(value.trim()))) return {
-								content: `"${selector}" 为 input[type=number]，无法填写非数字 "${value}"`,
-								details: {
-									error: true,
-									code: "INVALID_NUMBER",
-									action,
-									selector
-								}
-							};
-							scrollIntoViewIfNeeded(target);
-							target.focus();
-							selectText(target);
-							setNativeValue(target, value);
-							dispatchInputEvents(target);
-							if (target.value !== value) return {
-								content: `"${selector}" 填写后值不一致：期望 "${value}"，实际 "${target.value}"`,
+							const linkedInput = findAssociatedSliderInput(target);
+							if (linkedInput) {
+								const filled = executeFillOnResolvedTarget(linkedInput, String(numericValue), selector, action, `from ${describeElement(target)}`);
+								if (filled) return filled;
+							}
+							const min = Number(target.getAttribute("aria-valuemin") ?? "1");
+							const max = Number(target.getAttribute("aria-valuemax") ?? String(target.children.length || 5));
+							const discreteCount = Number.isFinite(max - min + 1) ? Math.max(1, Math.round(max - min + 1)) : target.children.length;
+							const desiredIndex = Math.round(numericValue - min);
+							const children = Array.from(target.children).filter((node) => node instanceof HTMLElement);
+							if (children.length >= discreteCount && desiredIndex >= 0 && desiredIndex < children.length) {
+								const item = children[desiredIndex];
+								scrollIntoViewIfNeeded(item);
+								dispatchClickEvents(item);
+								return { content: `已点击 ${describeElement(item)}，设置 ${describeElement(target)} 值为 ${numericValue}` };
+							}
+							const guessed = guessNearbyFillTarget(target, String(numericValue));
+							if (guessed) {
+								const guessedResult = executeFillOnResolvedTarget(guessed, String(numericValue), selector, action, "heuristic-nearby-target");
+								if (guessedResult) return guessedResult;
+							}
+							return {
+								content: `"${selector}" 为 role=slider，但未找到可写入输入框或可点击离散子项`,
 								details: {
 									error: true,
-									code: "FILL_NOT_APPLIED",
+									code: "UNSUPPORTED_FILL_TARGET",
 									action,
 									selector
 								}
 							};
-							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}"` };
+						const directFilled = executeFillOnResolvedTarget(target, value, selector, action);
+						if (directFilled) return directFilled;
+						const guessed = guessNearbyFillTarget(target, value);
+						if (guessed) {
+							const guessedResult = executeFillOnResolvedTarget(guessed, value, selector, action, "heuristic-nearby-target");
+							if (guessedResult) return guessedResult;
 						}
-						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);
+						return {
+							content: `"${selector}" 不是可编辑元素，且未在附近找到可推断填写目标`,
+							details: {
+								error: true,
+								code: "UNSUPPORTED_FILL_TARGET",
+								action,
+								selector
 							}
-							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;
@@ -2703,6 +3069,40 @@ const MAX_SNAPSHOT_ATTR_VALUE_LENGTH = 120;
 const MAX_EXPANDED_LIST_CHILDREN = 120;
 /** 定向放宽 children 的硬上限。 */
 const MAX_EXPANDED_CHILDREN_LIMIT = 300;
+/** 事件名 → 快照简写映射（压缩 token）。 */
+const EVENT_ABBREV = {
+	click: "clk",
+	dblclick: "dbl",
+	mousedown: "mdn",
+	mouseup: "mup",
+	mousemove: "mmv",
+	mouseover: "mov",
+	mouseout: "mot",
+	mouseenter: "men",
+	mouseleave: "mlv",
+	pointerdown: "pdn",
+	pointerup: "pup",
+	pointermove: "pmv",
+	touchstart: "tst",
+	touchend: "ted",
+	keydown: "kdn",
+	keyup: "kup",
+	input: "inp",
+	change: "chg",
+	submit: "sub",
+	focus: "fcs",
+	blur: "blr",
+	scroll: "scl",
+	wheel: "whl",
+	drag: "drg",
+	dragstart: "drs",
+	dragend: "dre",
+	drop: "drp",
+	contextmenu: "ctx"
+};
+function abbrevEvent(name) {
+	return EVENT_ABBREV[name] ?? name.slice(0, 3);
+}
 /**
 * 规整快照属性值，避免把长 base64/data URL 原样注入快照。
 */
@@ -2744,7 +3144,7 @@ function sanitizeSnapshotAttrValue(value) {
 */
 function generateSnapshot(root = document.body, options = {}) {
 	const opts = typeof options === "number" ? { maxDepth: options } : options;
-	const maxDepth = opts.maxDepth ?? 6;
+	const maxDepth = opts.maxDepth ?? 12;
 	const viewportOnly = opts.viewportOnly ?? true;
 	const pruneLayout = opts.pruneLayout ?? true;
 	const maxNodes = opts.maxNodes ?? 220;
@@ -2808,6 +3208,64 @@ function generateSnapshot(root = document.body, options = {}) {
 		"LABEL",
 		"SUMMARY"
 	]);
+	const INTERACTIVE_EVENTS = new Set([
+		"click",
+		"dblclick",
+		"mousedown",
+		"mouseup",
+		"pointerdown",
+		"pointerup",
+		"touchstart",
+		"touchend",
+		"input",
+		"change",
+		"keydown",
+		"keyup",
+		"submit",
+		"focus",
+		"blur"
+	]);
+	/** 交互性 ARIA role — 需要分配 hash ID 的角色集合 */
+	const INTERACTIVE_ROLES = new Set([
+		"button",
+		"link",
+		"tab",
+		"switch",
+		"slider",
+		"checkbox",
+		"radio",
+		"combobox",
+		"listbox",
+		"option",
+		"menuitem",
+		"textbox",
+		"spinbutton",
+		"searchbox",
+		"treeitem",
+		"gridcell",
+		"scrollbar"
+	]);
+	/**
+	* 事件优先级（值越大越优先）：
+	* 输入链路（input/change/focus/blur） > 点击链路（click/pointer） > 其他事件。
+	*/
+	const EVENT_PRIORITY = {
+		input: 140,
+		change: 130,
+		focus: 120,
+		blur: 110,
+		keydown: 100,
+		keyup: 90,
+		click: 80,
+		dblclick: 70,
+		pointerdown: 60,
+		pointerup: 55,
+		mousedown: 50,
+		mouseup: 45,
+		touchstart: 40,
+		touchend: 35,
+		submit: 30
+	};
 	/** 布尔状态属性 — 只在存在时输出（无值），如 disabled、checked */
 	const BOOLEAN_ATTRS = [
 		"disabled",
@@ -2856,15 +3314,75 @@ function generateSnapshot(root = document.body, options = {}) {
 		if (el.getAttribute("id")) return false;
 		if (el.getAttribute("role") || el.getAttribute("aria-label")) return false;
 		for (const attr of Array.from(el.attributes)) if (attr.name.startsWith("on")) return false;
+		if (hasTrackedElementEvents(el)) return false;
 		if (directText) return false;
 		return true;
 	}
+	function hasInteractiveTrackedEvents(el) {
+		const tracked = getTrackedElementEvents(el);
+		if (tracked.length === 0) return false;
+		return tracked.some((name) => INTERACTIVE_EVENTS.has(name));
+	}
+	function getTrackedEventPriorityScore(el) {
+		const tracked = getTrackedElementEvents(el);
+		if (tracked.length === 0) return 0;
+		let score = 0;
+		for (const name of tracked) score += EVENT_PRIORITY[name] ?? 8;
+		return score;
+	}
+	/**
+	* 元素优先级：
+	* 1) 输入控件/按钮等语义控件
+	* 2) 事件追踪优先级（输入、点击、失焦等）
+	* 3) inline 事件与可聚焦能力补充加分
+	*/
+	function getElementPriorityScore(el) {
+		let score = 0;
+		if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) score += 200;
+		else if (el instanceof HTMLButtonElement || el instanceof HTMLAnchorElement) score += 180;
+		else if (el.getAttribute("role") === "button" || el.getAttribute("role") === "switch" || el.getAttribute("role") === "slider") score += 160;
+		score += getTrackedEventPriorityScore(el);
+		if (el.hasAttribute("onclick")) score += 60;
+		if (el.hasAttribute("oninput") || el.hasAttribute("onchange")) score += 80;
+		if (el.hasAttribute("onfocus") || el.hasAttribute("onblur")) score += 70;
+		if (el.hasAttribute("tabindex")) score += 20;
+		return score;
+	}
+	function orderChildrenByPriority(children) {
+		return children.map((child, index) => ({
+			child,
+			index,
+			interactive: isInteractiveElement(child),
+			score: getElementPriorityScore(child)
+		})).sort((a, b) => {
+			if (a.interactive !== b.interactive) return a.interactive ? -1 : 1;
+			if (b.score !== a.score) return b.score - a.score;
+			return a.index - b.index;
+		}).map((entry) => entry.child);
+	}
 	function isInteractiveElement(el) {
 		if (INTERACTIVE_TAGS.has(el.tagName)) return true;
 		if (el.hasAttribute("onclick")) return true;
 		if (el.hasAttribute("role")) return true;
 		if (el.hasAttribute("tabindex")) return true;
 		if (el.hasAttribute("aria-label")) return true;
+		if (hasInteractiveTrackedEvents(el)) return true;
+		return false;
+	}
+	/**
+	* 判断元素是否需要分配 hash ID（仅交互节点分配，节省 token）。
+	*
+	* 核心依据：元素是否绑定了交互事件（INTERACTIVE_EVENTS 集合）。
+	* 辅助依据：语义交互标签、内联事件、ARIA role、tabindex 等兜底。
+	*/
+	function needsHashId(el) {
+		if (hasInteractiveTrackedEvents(el)) return true;
+		for (const attr of Array.from(el.attributes)) if (attr.name.startsWith("on")) return true;
+		if (INTERACTIVE_TAGS.has(el.tagName)) return true;
+		const role = el.getAttribute("role");
+		if (role && INTERACTIVE_ROLES.has(role)) return true;
+		if (el.hasAttribute("tabindex")) return true;
+		if (el.isContentEditable && el.getAttribute("contenteditable") !== "inherit") return true;
 		return false;
 	}
 	/** 判断是否为“选项列表”容器（时间/下拉/listbox 等）。 */
@@ -2900,8 +3418,11 @@ function generateSnapshot(root = document.body, options = {}) {
 		if (!isInViewport(el, depth)) return "";
 		const indent = "  ".repeat(depth);
 		const tag = el.tagName.toLowerCase();
+		const rawRole = el.getAttribute("role");
+		const useRoleAsTag = !!(rawRole && INTERACTIVE_ROLES.has(rawRole) && rawRole !== tag);
+		const displayTag = useRoleAsTag ? rawRole : tag;
 		const currentPath = `${parentPath}/${tag}${getSiblingIndex(el)}`;
-		const hashId = refStore ? refStore.set(el, currentPath) : void 0;
+		const hashId = refStore && needsHashId(el) ? refStore.set(el, currentPath) : void 0;
 		const attrs = [];
 		const elId = el.getAttribute("id");
 		if (elId) attrs.push(`id="${elId}"`);
@@ -2911,6 +3432,7 @@ function generateSnapshot(root = document.body, options = {}) {
 			if (cls) attrs.push(`class="${cls}"`);
 		}
 		for (const attr of INTERACTIVE_ATTRS) {
+			if (attr === "role" && useRoleAsTag) continue;
 			const val = el.getAttribute(attr);
 			if (val) {
 				const safeVal = sanitizeSnapshotAttrValue(val);
@@ -2925,6 +3447,12 @@ function generateSnapshot(root = document.body, options = {}) {
 			if (!attrs.includes("readonly")) attrs.push("readonly");
 		}
 		if (el.hasAttribute("onclick")) attrs.push("onclick");
+		const trackedEvents = getTrackedElementEvents(el);
+		if (trackedEvents.length > 0) {
+			const preview = trackedEvents.slice(0, 6).map(abbrevEvent).join(",");
+			const suffix = trackedEvents.length > 6 ? ",..." : "";
+			attrs.push(`listeners="${preview}${suffix}"`);
+		}
 		const testId = el.getAttribute("data-testid") || el.getAttribute("data-test-id");
 		if (testId) {
 			const safeTestId = sanitizeSnapshotAttrValue(testId).slice(0, 25);
@@ -2951,10 +3479,7 @@ function generateSnapshot(root = document.body, options = {}) {
 		}
 		directText = directText.trim();
 		if (isEmptyLayoutContainer(el, directText)) {
-			const allChildren = Array.from(el.children);
-			const interactiveChildren = allChildren.filter(isInteractiveElement);
-			const nonInteractiveChildren = allChildren.filter((child) => !isInteractiveElement(child));
-			const orderedChildren = [...interactiveChildren, ...nonInteractiveChildren];
+			const orderedChildren = orderChildrenByPriority(Array.from(el.children));
 			const childLimit = resolveChildLimit(el, maxChildren, hashId);
 			const selectedChildren = orderedChildren.slice(0, childLimit);
 			const omittedChildren = orderedChildren.length - selectedChildren.length;
@@ -2965,23 +3490,19 @@ function generateSnapshot(root = document.body, options = {}) {
 			}
 			if (childBlocks.length === 0 && omittedChildren <= 0) return "";
 			if (!(childBlocks.length >= 2 || omittedChildren > 0)) return childBlocks.join("\n");
-			const groupLines = [`${"  ".repeat(depth)}([${tag}] collapsed-group`];
+			const groupLines = [`${"  ".repeat(depth)}([${displayTag}] 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}]`;
+		let line = `${indent}[${displayTag}]`;
 		if (directText) line += ` "${directText.slice(0, maxTextLength)}"`;
 		if (attrs.length) line += ` ${attrs.join(" ")}`;
 		if (hashId) line += ` #${hashId}`;
-		else line += ` ref="${currentPath}"`;
 		const lines = [line];
 		emittedNodes++;
-		const allChildren = Array.from(el.children);
-		const interactiveChildren = allChildren.filter(isInteractiveElement);
-		const nonInteractiveChildren = allChildren.filter((child) => !isInteractiveElement(child));
-		const orderedChildren = [...interactiveChildren, ...nonInteractiveChildren];
+		const orderedChildren = orderChildrenByPriority(Array.from(el.children));
 		const childLimit = resolveChildLimit(el, maxChildren, hashId);
 		const selectedChildren = orderedChildren.slice(0, childLimit);
 		const omittedChildren = orderedChildren.length - selectedChildren.length;
@@ -3037,7 +3558,7 @@ function createPageInfoTool() {
 		schema: Type.Object({
 			action: Type.String({ description: "Info action: get_url | get_title | get_selection | get_viewport | snapshot | query_all" }),
 			selector: Type.Optional(Type.String({ description: "CSS selector for query_all action" })),
-			maxDepth: Type.Optional(Type.Number({ description: "Max depth for snapshot (default: 6)" })),
+			maxDepth: Type.Optional(Type.Number({ description: "Max depth for snapshot (default: 12)" })),
 			viewportOnly: Type.Optional(Type.Boolean({ description: "Only snapshot elements visible in viewport (default: true)" })),
 			pruneLayout: Type.Optional(Type.Boolean({ description: "Collapse empty layout containers like div/span (default: true)" })),
 			maxNodes: Type.Optional(Type.Number({ description: "Maximum nodes to include in snapshot (default: 220)" })),
@@ -3066,7 +3587,7 @@ function createPageInfoTool() {
 						return { content: JSON.stringify(info, null, 2) };
 					}
 					case "snapshot": {
-						const maxDepth = params.maxDepth ?? 6;
+						const maxDepth = params.maxDepth ?? 12;
 						const viewportOnly = params.viewportOnly ?? true;
 						const pruneLayout = params.pruneLayout ?? true;
 						const maxNodes = params.maxNodes ?? 220;
@@ -3220,7 +3741,7 @@ function createNavigateTool() {
 * - hash selector（如 #abc123）优先通过 RefStore 解析。
 * - 可见性语义与 dom-tool 保持一致（参考 Playwright 风格）。
 */
-const DEFAULT_TIMEOUT = 1e4;
+const DEFAULT_TIMEOUT = 6e3;
 const POLL_INTERVAL_MS = 80;
 const STABLE_TICK_MS = 50;
 const OBSERVER_OPTIONS = {
@@ -3412,7 +3933,7 @@ function createWaitTool() {
 			selector: Type.Optional(Type.String({ description: "CSS selector for wait_for_selector/wait_for_hidden" })),
 			state: Type.Optional(Type.String({ description: "Selector state for wait_for_selector: attached | visible | hidden | detached (default: attached)" })),
 			text: Type.Optional(Type.String({ description: "Text to wait for in wait_for_text" })),
-			timeout: Type.Optional(Type.Number({ description: "Timeout in milliseconds (default: 10000)" })),
+			timeout: Type.Optional(Type.Number({ description: "Timeout in milliseconds (default: 6000)" })),
 			quietMs: Type.Optional(Type.Number({ description: "Quiet window for wait_for_stable in milliseconds (default: 300)" }))
 		}),
 		execute: async (params) => {
@@ -3749,6 +4270,7 @@ function registerToolHandler(executors) {
 *   │  └──────────┘  └────────────┘  └──────────────┘ │
 *   └──────────────────────────────────────────────────┘
 */
+installEventListenerTracking();
 var WebAgent = class WebAgent {
 	/** 默认系统提示词 key（兼容旧版 setSystemPrompt(prompt)）。 */
 	static DEFAULT_SYSTEM_PROMPT_KEY = "default";
@@ -3781,6 +4303,8 @@ var WebAgent = class WebAgent {
 	autoSnapshot;
 	/** 快照选项 */
 	snapshotOptions;
+	/** 轮次后稳定等待配置 */
+	roundStabilityWait;
 	/** 工具注册表实例 — 每个 WebAgent 拥有独立的工具集 */
 	registry = new ToolRegistry();
 	/** 事件回调 — 绑定后可实时获取 Agent 进度，用于 UI 展示 */
@@ -3797,6 +4321,7 @@ var WebAgent = class WebAgent {
 		this.memory = options.memory ?? false;
 		this.autoSnapshot = options.autoSnapshot ?? true;
 		this.snapshotOptions = options.snapshotOptions ?? {};
+		this.roundStabilityWait = options.roundStabilityWait;
 		if (typeof options.systemPrompt === "string") this.setSystemPrompt(options.systemPrompt);
 		else if (options.systemPrompt && typeof options.systemPrompt === "object") this.setSystemPrompts(options.systemPrompt);
 	}
@@ -3961,7 +4486,7 @@ var WebAgent = class WebAgent {
 		let initialSnapshot;
 		try {
 			const snapshot = generateSnapshot(document.body, {
-				maxDepth: 8,
+				maxDepth: 12,
 				viewportOnly: false,
 				maxNodes: 500,
 				maxChildren: 30,
@@ -3989,6 +4514,7 @@ var WebAgent = class WebAgent {
 			history: this.memory ? this.history : void 0,
 			dryRun: this.dryRun,
 			maxRounds: this.maxRounds,
+			roundStabilityWait: this.roundStabilityWait,
 			callbacks: wrappedCallbacks
 		});
 		if (this.memory) this.history = result.messages;