agentpage 0.0.26 → 0.0.28

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 -->";
 /** 快照结束标记 */
@@ -20,15 +38,201 @@ const SNAPSHOT_OUTDATED = "[此快照已过期，请参考对话中最新的快
 
 //#endregion
 //#region src/core/agent-loop/helpers.ts
-/** 异步睡眠（中）/ Async sleep utility (EN). */
+/**
+* 异步睡眠。
+*
+* 用于重试等待、节流等待等场景。
+*/
 function sleep$1(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
-/** 统一内容为字符串（中）/ Normalize tool content to string (EN). */
+/**
+* 统一内容为字符串。
+*
+* 工具返回 content 可能是 string 或 object；这里统一转成 string，
+* 便于日志、错误判定、摘要拼接。
+*/
 function toContentString(content) {
 	return typeof content === "string" ? content : JSON.stringify(content, null, 2);
 }
-/** 元素不存在判定（中）/ Detect element-not-found failure (EN). */
+/**
+* 解析快照放宽提示。
+*
+* 约定格式：`SNAPSHOT_HINT: EXPAND_CHILDREN #ref1 #ref2`
+*
+* 返回：去掉 `#` 前缀后的 ref id 列表。
+*/
+function parseSnapshotExpandHints(text) {
+	if (!text) return [];
+	const refs = [];
+	const regex = /^\s*SNAPSHOT_HINT\s*:\s*EXPAND_CHILDREN\s+(.+)$/gim;
+	let match;
+	while ((match = regex.exec(text)) !== null) {
+		const tokens = (match[1] ?? "").match(/#[A-Za-z0-9_-]+/g) ?? [];
+		for (const token of tokens) refs.push(token.replace(/^#/, ""));
+	}
+	return refs;
+}
+/**
+* 提取 hash selector 的 ref。
+*
+* 仅处理“纯 hash 选择器”，例如 `#1rv01x`。
+* 如果是复杂 CSS（如 `.x #id`）会返回 null，避免误判。
+*/
+function extractHashSelectorRef(toolInput) {
+	if (!toolInput || typeof toolInput !== "object") return null;
+	const selector = toolInput.selector;
+	if (typeof selector !== "string") return null;
+	const m = selector.trim().match(/^#([A-Za-z0-9_-]+)$/);
+	return m ? m[1] : null;
+}
+/**
+* 构建任务数组。
+*
+* 作用：把一轮工具调用规整成稳定字符串数组，
+* 用于“上一轮任务回显”和“重复批次检测”。
+*/
+function buildTaskArray(toolCalls) {
+	return toolCalls.map((tc) => `${tc.name}:${JSON.stringify(tc.input)}`);
+}
+/**
+* 规范化模型输出。
+*
+* 优先保留 REMAINING；否则保留首段摘要，避免长文本污染上下文。
+*
+* 返回字符串会被注入下一轮消息，作为“上一轮模型输出摘要”。
+*/
+function normalizeModelOutput(text) {
+	if (!text) return "";
+	const trimmed = text.trim();
+	if (!trimmed) return "";
+	const remainingMatch = trimmed.match(/REMAINING\s*:\s*([\s\S]*)$/i);
+	if (remainingMatch) return `REMAINING: ${remainingMatch[1].trim()}`;
+	return (trimmed.split(/\n\s*\n/)[0]?.trim() ?? trimmed).slice(0, 220);
+}
+/**
+* 解析 REMAINING。
+*
+* 返回值：
+* - `""` 表示 DONE
+* - 非空字符串表示新的 remaining
+* - `null` 表示协议缺失
+*
+* 注意：这里只负责解析，不负责 fallback 策略。
+*/
+function parseRemainingInstruction(text) {
+	if (!text) return null;
+	const match = text.match(/REMAINING\s*:\s*([\s\S]*)$/i);
+	if (!match) return null;
+	const value = match[1].trim();
+	return /^done$/i.test(value) ? "" : value;
+}
+/**
+* 推导下一轮 remaining。
+*
+* 策略：
+* - 有 REMAINING 协议 -> 使用模型给出的 nextInstruction
+* - 无协议 -> 保持 currentInstruction 不变（由上层决定是否启发式推进）
+*/
+function deriveNextInstruction(text, currentInstruction) {
+	const parsed = parseRemainingInstruction(text);
+	if (parsed !== null) return {
+		nextInstruction: parsed,
+		hasRemainingProtocol: true
+	};
+	return {
+		nextInstruction: currentInstruction,
+		hasRemainingProtocol: false
+	};
+}
+/**
+* 启发式剔除 remaining。
+*
+* 用于协议缺失但本轮有执行动作时，按线性步骤剔除已执行数量。
+*
+* 这是“保守推进”策略，不保证语义完美，但能避免 remaining 长期不变。
+*/
+function reduceRemainingHeuristically(currentInstruction, executedCount) {
+	if (!currentInstruction.trim() || executedCount <= 0) return currentInstruction;
+	if (!/(->|=>|→|\bthen\b|\band then\b|\bnext\b|\bafter that\b|然后|接着|随后|之后|再)/i.test(currentInstruction)) return currentInstruction;
+	const parts = currentInstruction.replace(/\s+/g, " ").replace(/(->|=>|→)/g, " 然后 ").split(/\s*(?:then|and then|next|after that|然后|接着|随后|之后|再)\s*/gi).map((part) => part.trim()).filter(Boolean);
+	if (parts.length <= 1) return currentInstruction;
+	const consumedSteps = Math.min(Math.max(1, Math.floor(executedCount)), 1);
+	const nextParts = parts.slice(Math.min(consumedSteps, parts.length));
+	if (nextParts.length === 0) return "";
+	return nextParts.join(" 然后 ");
+}
+/**
+* 判定是否强制断轮。
+*
+* 语义：潜在 DOM 结构变化动作后，等待下一轮新快照。
+*
+* 当前规则：
+* - `navigate.*` 一律断轮
+* - `dom.press` 仅 Enter 断轮
+* - `evaluate` 断轮
+* - 其他动作默认不断轮
+*/
+function shouldForceRoundBreak(toolName, toolInput) {
+	const action = getToolAction(toolInput);
+	if (toolName === "navigate") return action === "goto" || action === "back" || action === "forward" || action === "reload";
+	if (toolName === "dom") {
+		if (action === "press") return (typeof toolInput === "object" && toolInput !== null ? String(toolInput.key ?? toolInput.value ?? "") : "") === "Enter";
+		return false;
+	}
+	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 表示当前结果不属于“元素未找到”，
+* 返回对象表示可进入 not-found retry 对话流。
+*/
+function collectMissingTask(name, input, result) {
+	if (!isElementNotFoundResult(result)) return null;
+	return {
+		name,
+		input,
+		reason: toContentString(result.content).slice(0, 240)
+	};
+}
+/**
+* 元素不存在判定。
+*
+* 判定顺序：
+* 1) 优先看结构化错误码 `ELEMENT_NOT_FOUND`
+* 2) 回退看中文错误文本关键词（兼容历史结果格式）
+*/
 function isElementNotFoundResult(result) {
 	const details = result.details;
 	if (details && typeof details === "object") {
@@ -37,14 +241,19 @@ function isElementNotFoundResult(result) {
 	const content = toContentString(result.content);
 	return content.includes("未找到") && content.includes("元素");
 }
-/** 生成稳定调用键（中）/ Build stable key for a tool call (EN). */
+/**
+* 生成稳定调用键。
+*
+* 用于 recoveryAttempts 的 map key（同名 + 同参数视为同一调用）。
+*/
 function buildToolCallKey(name, input) {
 	return `${name}:${JSON.stringify(input)}`;
 }
 /**
-* 解析恢复等待时长（中）/ Resolve recovery wait duration (EN).
+* 解析恢复等待时长。
 * 优先级：waitMs > waitSeconds > 默认值。
-* Priority: waitMs > waitSeconds > default value.
+*
+* 统一返回毫秒整数，且最小为 0。
 */
 function resolveRecoveryWaitMs(input) {
 	if (!input || typeof input !== "object") return DEFAULT_RECOVERY_WAIT_MS;
@@ -55,13 +264,21 @@ function resolveRecoveryWaitMs(input) {
 	if (typeof waitSeconds === "number" && Number.isFinite(waitSeconds)) return Math.max(0, Math.floor(waitSeconds * 1e3));
 	return DEFAULT_RECOVERY_WAIT_MS;
 }
-/** 读取工具 action（中）/ Read tool action from input (EN). */
+/**
+* 读取工具 action。
+*
+* 仅在 input 是对象且 action 为字符串时返回值，否则返回 undefined。
+*/
 function getToolAction(input) {
 	if (!input || typeof input !== "object") return void 0;
 	const action = input.action;
 	return typeof action === "string" ? action : void 0;
 }
-/** 判定错误标记（中）/ Check whether result is marked as error (EN). */
+/**
+* 判定错误标记。
+*
+* 约定：`result.details.error === true` 视为错误结果。
+*/
 function hasToolError(result) {
 	return result.details && typeof result.details === "object" ? Boolean(result.details.error) : false;
 }
@@ -69,25 +286,24 @@ function hasToolError(result) {
 //#endregion
 //#region src/core/agent-loop/snapshot.ts
 /**
-* 读取页面快照（中）/ Read current page snapshot (EN).
+* 读取页面快照。
 *
 * 默认关闭 viewportOnly，优先完整性。
-* viewportOnly defaults to false to prioritize completeness.
 *
-* 步骤（中）/ Steps (EN):
+* 步骤：
 * 1) 合并调用方 options 与默认值（深度/裁剪/剪枝/节点上限等）。
 * 2) 分发 `page_info.snapshot` 获取当前 DOM 文本快照。
 * 3) 使用 `toContentString` 归一化输出，避免 provider 差异导致结构不一致。
 * 4) 返回稳定字符串给 loop，供后续注入消息与统计。
 *
-* 默认参数意图（中）/ Default parameter rationale (EN):
+* 默认参数意图：
 * - `maxDepth=8`: 保留足够层级，减少关键控件被截断。
 * - `viewportOnly=false`: 优先完整性，避免误判“元素不存在”。
 * - `pruneLayout=true`: 抑制纯布局噪声，降低 token 压力。
 * - `maxNodes=500` / `maxChildren=30`: 控制体积上限，兼顾可读性。
 * - `maxTextLength=40`: 防止长文本淹没结构信息。
 *
-* 压缩/剪枝是怎么做的（中）/ How compression & pruning works in practice (EN):
+* 压缩/剪枝是怎么做的：
 * - `viewportOnly=true` 时：仅保留与视口相交元素（根层容器保留），完全视口外元素跳过。
 * - `pruneLayout=true` 时：无 id/无语义/无交互/无直接文本的布局容器会被“折叠”，
 *   子节点直接提升输出，减少无意义层级；当同一折叠容器提升出多个相邻节点时，
@@ -98,10 +314,10 @@ function hasToolError(result) {
 * - 交互优先排序：优先输出按钮/输入框/链接等交互元素，再输出普通元素。
 * - 属性压缩：仅保留关键属性（如 id、关键 class、交互属性、布尔状态、val），减少冗余 token。
 *
-* 输入/输出（中）/ I/O contract (EN):
-* - In: `ToolRegistry` + 可选快照参数
-* - Out: 归一化后的快照字符串（始终 string）
-* - Side effects: 无本地状态写入；仅依赖工具调用结果
+* 输入/输出：
+* - 输入：`ToolRegistry` + 可选快照参数
+* - 输出：归一化后的快照字符串（始终 string）
+* - 副作用：无本地状态写入；仅依赖工具调用结果
 */
 async function readPageSnapshot(registry, options) {
 	return toContentString((await registry.dispatch("page_info", {
@@ -118,9 +334,9 @@ async function readPageSnapshot(registry, options) {
 	})).content);
 }
 /**
-* 包裹快照（中）/ Wrap snapshot with boundary markers (EN).
+* 包裹快照。
 *
-* 作用（中）/ Purpose (EN):
+* 作用：
 * - 为快照加 `SNAPSHOT_START/END` 边界，便于后续正则定位。
 * - 支持去重与旧快照剥离，防止多轮 token 累积。
 * - 仅做纯字符串变换，不访问外部状态。
@@ -128,20 +344,20 @@ async function readPageSnapshot(registry, options) {
 function wrapSnapshot(snapshot) {
 	return `${SNAPSHOT_START}\n${snapshot}\n${SNAPSHOT_END}`;
 }
-/** 转义正则字符（中）/ Escape regex special chars (EN). */
+/** 转义正则字符。 */
 function escapeRegex(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-/** 快照块匹配正则（中）/ Regex for snapshot blocks (EN). */
+/** 快照块匹配正则。 */
 const SNAPSHOT_REGEX = new RegExp(`${escapeRegex(SNAPSHOT_START)}[\\s\\S]*?${escapeRegex(SNAPSHOT_END)}`, "g");
-/** 是否包含快照标记（中）/ Check whether text includes snapshot markers (EN). */
+/** 是否包含快照标记。 */
 function containsSnapshot(text) {
-	return text.includes(SNAPSHOT_START);
+	return text.includes(SNAPSHOT_START) && text.includes(SNAPSHOT_END);
 }
 /**
-* 剥离旧快照（中）/ Strip outdated snapshot blocks from system prompt (EN).
+* 剥离旧快照。
 *
-* 说明（中）/ Notes (EN):
+* 说明：
 * - 当 prompt 中已有历史快照时，将其替换为过期占位文本。
 * - 让每轮真正生效的只有“最新注入快照”，减少冲突上下文。
 * - 这是 prompt 级清理；不会触碰 tool trace 中的原始结果对象。
@@ -154,7 +370,15 @@ function stripSnapshotFromPrompt(prompt) {
 //#endregion
 //#region src/core/agent-loop/messages.ts
 /**
-* 显式 UI 意图判定（中）/ Detect explicit intent to operate AutoPilot UI (EN).
+* 显式 UI 意图判定。
+*
+* 用途：默认禁止模型操作 AutoPilot 自己的聊天 UI（输入框/发送按钮等），
+* 只有当用户文本里“同时出现 UI 关键词 + 操作动词”时才放行。
+*
+* 判定逻辑：
+* - `hasAgentUiKeyword`：是否提到聊天面板/输入框/发送按钮等
+* - `hasActionVerb`：是否包含点击/输入/发送等动作意图
+* - 二者都满足才返回 true
 */
 function isExplicitAgentUiRequest(userMessage) {
 	const lower = userMessage.toLowerCase();
@@ -163,7 +387,12 @@ function isExplicitAgentUiRequest(userMessage) {
 	const hasActionVerb = /(press|click|type|fill|send|input|submit|enter)/i.test(lower) || /(输入|点击|发送|填写|填入|操作|提交|回车|按下)/.test(compact);
 	return hasAgentUiKeyword && hasActionVerb;
 }
-/** 输入摘要（中）/ Build brief text for tool input (EN). */
+/**
+* 输入摘要。
+*
+* 把工具输入压缩成一段短文本（用于轨迹展示），
+* 只保留高价值字段，避免日志过长。
+*/
 function formatToolInputBrief(input) {
 	if (!input || typeof input !== "object") return "";
 	const params = input;
@@ -185,7 +414,11 @@ function formatToolInputBrief(input) {
 	return ` (${parts.join(", ")})`;
 }
 /**
-* 结果摘要（中）/ Build one-line summary for tool result (EN).
+* 结果摘要。
+*
+* 读取工具结果首行，拼接错误码，生成一行可读结论：
+* - 成功：`✓ ...`
+* - 失败：`✗ ... [CODE]`
 */
 function formatToolResultBrief(result) {
 	const firstLine = toContentString(result.content).split("\n").find((l) => l.trim())?.trim().slice(0, 80) ?? "";
@@ -196,15 +429,20 @@ function formatToolResultBrief(result) {
 	return `✓ ${firstLine}`;
 }
 /**
-* 构建紧凑消息数组（中）/ Build compact AI message array (EN).
+* 构建紧凑消息数组。
 *
-* Round 0: task + snapshot.
-* Round 1+: master goal + done steps + execution context + latest snapshot.
+* 两种轮次语义：
+* - Round 0：发送“初始任务 + 当前快照 + 执行约束”
+* - Round 1+：发送“已完成步骤 + 当前 remaining + 最新快照”
 *
-* 新增渐进式语义（中）/ Progressive semantics (EN):
+* 渐进式语义：
 * - `remainingInstruction`：当前轮次仍待执行的文本。
 * - `previousRoundTasks`：上一轮已执行的任务数组，避免重复计划。
-* - 消息中要求模型输出 `REMAINING: ...` 或 `REMAINING: DONE`，供下一轮继续消费。
+* - `previousRoundModelOutput`：上一轮模型输出摘要，用于 task-reduction 输入。
+* - `previousRoundPlannedTasks`：上一轮计划数组，用于对齐“计划 vs 实际执行”。
+* - `protocolViolationHint`：协议修复提示（当 remaining 未完成但模型无动作时）。
+*
+* 输出：符合 AIMessage 结构的消息数组，可直接传给 AIClient.chat。
 */
 function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, history, remainingInstruction, previousRoundTasks, previousRoundModelOutput, previousRoundPlannedTasks, protocolViolationHint) {
 	const messages = history ? [...history] : [];
@@ -241,26 +479,10 @@ function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, hi
 		content: `Done steps (do NOT repeat):\n${traceParts.join("\n")}`
 	});
 	const hasErrors = trace.some((e) => hasToolError(e.result));
-	const contextParts = [
-		"## Execution context",
-		"Current remaining instruction:",
-		activeInstruction,
-		"",
-		"Task-reduction model:",
-		"Input: current remaining instruction + previous round executed actions + this-round actions.",
-		"Output: new remaining instruction after removing this-round actions.",
-		"Start from visible page state directly. Do NOT restate task. Do NOT output planning text.",
-		"Execute all independent visible sub-tasks in one round.",
-		"Do NOT act on elements not present in this snapshot yet.",
-		"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).",
-		"If a needed list shows `... (N children omitted)` under a specific container, output `SNAPSHOT_HINT: EXPAND_CHILDREN #<containerRef>` and wait for next round snapshot.",
-		"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."
-	];
+	const needsMasterGoalAnchor = activeInstruction.trim().toLowerCase() !== userMessage.trim().toLowerCase();
+	const contextParts = ["## Execution context"];
+	if (needsMasterGoalAnchor) contextParts.push(`Master goal (reference only — do NOT restart from scratch):`, userMessage, "");
+	contextParts.push("Current remaining instruction:", activeInstruction, "", "Task-reduction model:", "Input: current remaining instruction + previous round executed actions + this-round actions.", "Output: new remaining instruction after removing this-round actions.", "Start from visible page state directly. Do NOT restate task. Do NOT output planning text.", "Execute all independent visible sub-tasks in one round.", "Do NOT act on elements not present in this snapshot yet.", "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).", "If a needed list shows `... (N children omitted)` under a specific container, output `SNAPSHOT_HINT: EXPAND_CHILDREN #<containerRef>` and wait for next round snapshot.", "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.");
 	else contextParts.push("", "If the goal is fully done, reply with a short summary (no tool calls).");
 	if (previousRoundTasks && previousRoundTasks.length > 0) contextParts.push("", "Previous round planned task array (already executed):", ...previousRoundTasks.map((task, index) => `${index + 1}. ${task}`));
@@ -284,7 +506,7 @@ function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, hi
 
 //#endregion
 //#region src/core/agent-loop/recovery.ts
-/** 冗余 page_info 动作（中）/ Redundant page_info actions to intercept (EN). */
+/** 冗余 page_info 动作集合。 */
 const REDUNDANT_PAGE_INFO_ACTIONS = new Set([
 	"snapshot",
 	"query_all",
@@ -293,7 +515,14 @@ const REDUNDANT_PAGE_INFO_ACTIONS = new Set([
 	"get_viewport"
 ]);
 /**
-* 冗余 page_info 检查（中）/ Check whether page_info call is redundant (EN).
+* 冗余 page_info 检查。
+*
+* 场景：模型在 loop 中频繁请求 page_info，导致“只看不做”。
+* 处理：命中白名单动作时直接返回拦截结果，不真正执行工具。
+*
+* 示例：
+* - 输入：`page_info.snapshot`
+* - 输出：`REDUNDANT_PAGE_INFO_SKIPPED`
 */
 function checkRedundantSnapshot(toolName, toolInput, _latestSnapshot, round) {
 	if (toolName !== "page_info") return null;
@@ -309,7 +538,14 @@ function checkRedundantSnapshot(toolName, toolInput, _latestSnapshot, round) {
 	return null;
 }
 /**
-* 快照防抖（中）/ Debounce repeated snapshot calls (EN).
+* 快照防抖。
+*
+* 规则：连续触发 `page_info.snapshot` 时，第 2 次起标记为冗余，
+* 返回 `REDUNDANT_SNAPSHOT`，提醒模型直接使用已有快照继续执行。
+*
+* 返回值：
+* - `result`：可能被替换成防抖后的结果
+* - `consecutiveCount`：更新后的连续 snapshot 计数
 */
 function applySnapshotDebounce(toolName, toolInput, result, consecutiveCount) {
 	if (toolName === "page_info" && getToolAction(toolInput) === "snapshot") {
@@ -336,10 +572,18 @@ function applySnapshotDebounce(toolName, toolInput, result, consecutiveCount) {
 	};
 }
 /**
-* 元素未找到恢复（中）/ Recover from element-not-found failures (EN).
+* 元素未找到恢复。
+*
+* 触发条件：
+* - 工具是 `dom`
+* - 结果被识别为“元素未找到”
+*
+* 处理流程：
+* 1) 按调用键统计恢复次数（同 name + input 视为同一调用）
+* 2) 在上限内：等待 -> 刷新快照 -> 返回 `ELEMENT_NOT_FOUND_RECOVERY`
+* 3) 超过上限：返回 `ELEMENT_NOT_FOUND_MAX_RECOVERY_REACHED`
 *
-* 前两次自动恢复，超过上限后返回终止提示。
-* Auto-recovers for initial attempts, then returns max-recovery signal.
+* 说明：函数只返回“恢复后的结果描述”，是否继续下一轮由主循环决定。
 */
 async function handleElementRecovery(toolName, toolInput, result, recoveryAttempts, registry, pageContext, callbacks) {
 	if (toolName !== "dom" || !isElementNotFoundResult(result)) return null;
@@ -371,7 +615,12 @@ async function handleElementRecovery(toolName, toolInput, result, recoveryAttemp
 		}
 	};
 }
-/** 导航后快照刷新（中）/ Refresh snapshot after navigation actions (EN). */
+/**
+* 导航后快照刷新。
+*
+* 当 `navigate.goto/back/forward/reload` 成功后，立即刷新快照，
+* 防止后续动作还在旧页面上下文里决策。
+*/
 async function handleNavigationUrlChange(toolName, toolInput, result, registry, pageContext, callbacks) {
 	if (toolName !== "navigate") return;
 	const action = getToolAction(toolInput);
@@ -386,7 +635,15 @@ const READ_ONLY_TOOLS = new Set(["page_info"]);
 const READ_ONLY_DOM_ACTIONS = new Set(["get_text", "get_attr"]);
 /**
 * 空转检测：识别连续只读轮次并终止。
-* 返回 -1 表示应终止循环。
+*
+* 判定口径：
+* - `page_info.*` 视为只读
+* - `dom.get_text/get_attr` 视为只读
+*
+* 返回值语义：
+* - `-1`：触发停机（连续 2 轮纯只读）
+* - `0`：本轮有实质操作，计数清零
+* - `>0`：当前连续只读轮次
 */
 function detectIdleLoop(toolCalls, consecutiveReadOnlyRounds) {
 	if (toolCalls.length > 0 && toolCalls.every(({ name, input }) => {
@@ -404,32 +661,76 @@ function detectIdleLoop(toolCalls, consecutiveReadOnlyRounds) {
 //#endregion
 //#region src/core/agent-loop/index.ts
 /**
-* Agent Loop 主流程
-*
-* 负责消息构建、AI 决策、工具执行、恢复保护与指标汇总。
-* 
+* Agent Loop 主流程（口语版）
 *
 * 流程图（文本）：
 *
 *   轮次开始
 *      │
-*      ├─ 确保快照可用
-*      ├─ 构建紧凑消息（目标 + 剩余任务 + 执行轨迹 + 快照）
-*      ├─ 调用模型
-*      ├─ 无 toolCalls ? 结束 : 执行工具
-*      ├─ 应用保护机制（冗余拦截/恢复/导航检测/空转/防自转）
+*      ├─ 先看有没有最新快照
+*      │    └─ 没有就先拍一张（可带 expandChildrenRefs）
+*      │
+*      ├─ 组装本轮上下文消息
+*      │    └─ remaining + 上轮任务 + 最新快照 +（必要时）重试提示
+*      │
+*      ├─ 调用模型拿决策
+*      │    └─ 同时解析 `REMAINING` 和 `SNAPSHOT_HINT`
+*      │
+*      ├─ 有 toolCalls 吗？
+*      │    ├─ 没有：走收敛/协议修复判断（必要时等待后重试）
+*      │    └─ 有：逐个执行工具
+*      │         ├─ 冗余拦截（例如 page_info 空转）
+*      │         ├─ 失败恢复（元素未找到重试）
+*      │         ├─ 导航后更新快照
+*      │         └─ 命中断轮条件则提前结束本轮
+*      │
+*      ├─ 更新 remaining（优先协议，缺失时启发式剔除）
+*      │
+*      ├─ 防空转 / 防自转检查
+*      │    └─ 连续只读或重复批次会触发停机
+*      │
 *      ├─ 刷新快照
 *      ▼
 *   下一轮或停机
+*
+* 停机条件（任一命中）：
+* - `REMAINING: DONE`（或 remaining 为空）
+* - 协议修复后仍无推进
+* - 连续只读（空转）
+* - 重复批次（自转）
+* - 达到 maxRounds
 */
 /**
-* 执行 Agent 循环（中）/ Execute the agent loop (EN).
+* 执行 Agent 循环。
+*
+* 你可以把这个函数理解成“任务执行调度器”：
+* - 输入：用户任务、系统提示词、工具注册表、历史消息、初始快照
+* - 过程：按轮次持续执行“看页面 -> 让模型决策 -> 跑工具 -> 更新上下文”
+* - 输出：最终回复、完整工具调用记录、可复用消息、结构化指标
 *
-* 每轮：确保快照 → 构建消息 → 调用 AI → 执行工具 → 保护处理 → 刷新快照。
-* Per round: ensure snapshot -> build messages -> call AI -> execute tools -> apply protections -> refresh snapshot.
+* 每轮主流程（固定顺序）：
+* 1) Ensure Snapshot：确保当前有最新快照（必要时读取）
+* 2) Build Messages：构建紧凑上下文（remaining + 上轮轨迹 + 最新快照）
+* 3) Call AI：请求模型并解析协议字段（`REMAINING` / `SNAPSHOT_HINT`）
+* 4) Execute Tools：执行工具调用并应用保护机制（冗余拦截、恢复、导航刷新）
+* 5) Reduce Remaining：推进剩余任务（优先协议，缺失时启发式剔除）
+* 6) Guard & Refresh：防空转/防自转判定，并刷新快照进入下一轮
+*
+* 核心状态语义：
+* - `remainingInstruction`：当前轮还未消费完的任务文本
+* - `previousRoundTasks`：上一轮已执行动作，防止模型原样重复
+* - `previousRoundPlannedTasks`：上一轮模型计划，用于重复批次检测
+* - `protocolViolationHint`：协议修复提示（remaining 未完成却无工具调用时注入）
+*
+* 停机条件（命中任意一条即结束）：
+* - 模型无工具调用且 remaining 已收敛（`REMAINING: DONE` 或空）
+* - 协议修复后仍无推进
+* - 连续只读轮次（防空转）
+* - 连续重复计划批次（防自转）
+* - 达到 `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 = [];
@@ -450,6 +751,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;
@@ -457,7 +764,7 @@ async function executeAgentLoop(params) {
 	let snapshotSizeTotal = 0;
 	let snapshotSizeMax = 0;
 	/**
-	* 记录快照统计（中）/ Record snapshot metrics (EN).
+	* 记录快照统计。
 	*
 	* 用于输出可观测指标：读取次数、平均长度、最大长度。
 	* Used for observability metrics: read count, avg size, max size.
@@ -469,7 +776,7 @@ async function executeAgentLoop(params) {
 		if (snapshot.length > snapshotSizeMax) snapshotSizeMax = snapshot.length;
 	};
 	/**
-	* 刷新页面快照（中）/ Refresh page snapshot (EN).
+	* 刷新页面快照。
 	*
 	* 只做两件事：读取最新快照 + 更新快照统计。
 	* Does exactly two things: read latest snapshot + update metrics.
@@ -482,33 +789,32 @@ async function executeAgentLoop(params) {
 		recordSnapshotStats(pageContext.latestSnapshot);
 	};
 	/**
-	* 解析模型文本中的快照放宽指令（中）/ Parse snapshot expansion hint from model text (EN).
+	* 轮次后稳定等待（双重等待）。
 	*
-	* 约定：
-	* SNAPSHOT_HINT: EXPAND_CHILDREN #ref1 #ref2
+	* 顺序固定为：
+	* 1) 等待 loading 指示器隐藏
+	* 2) 等待 DOM quiet window
 	*/
-	const parseSnapshotExpandHints = (text) => {
-		if (!text) return [];
-		const refs = [];
-		const regex = /^\s*SNAPSHOT_HINT\s*:\s*EXPAND_CHILDREN\s+(.+)$/gim;
-		let match;
-		while ((match = regex.exec(text)) !== null) {
-			const tokens = (match[1] ?? "").match(/#[A-Za-z0-9_-]+/g) ?? [];
-			for (const token of tokens) refs.push(token.replace(/^#/, ""));
-		}
-		return refs;
-	};
-	/** 从工具输入提取 hash selector（如 #1rv01x），用于定向快照放宽。 */
-	const extractHashSelectorRef = (toolInput) => {
-		if (!toolInput || typeof toolInput !== "object") return null;
-		const selector = toolInput.selector;
-		if (typeof selector !== "string") return null;
-		const m = selector.trim().match(/^#([A-Za-z0-9_-]+)$/);
-		return m ? m[1] : null;
+	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);
 	/**
-	* 追加工具轨迹（中）/ Append tool trace entry (EN).
+	* 追加工具轨迹。
 	*
 	* 同时写入：
 	* - allToolCalls：对外返回结果
@@ -527,104 +833,6 @@ async function executeAgentLoop(params) {
 			result
 		});
 	};
-	/**
-	* 生成任务数组（中）/ Build normalized task array (EN).
-	*
-	* 将本轮 toolCalls 归一化成稳定字符串数组，便于：
-	* - 回传到下一轮消息上下文（提醒已执行计划）
-	* - 进行“是否与上一轮完全相同”的比较
-	*/
-	const buildTaskArray = (toolCalls) => toolCalls.map((tc) => {
-		const inputText = JSON.stringify(tc.input);
-		return `${tc.name}:${inputText}`;
-	});
-	/**
-	* 规范化模型文本输出（中）/ Normalize model text for next-round input (EN).
-	*
-	* 优先保留 REMAINING 行；否则截断首段文本，避免长篇规划污染下一轮输入。
-	* Prefer REMAINING line; otherwise keep a short excerpt to avoid long planning spillover.
-	*/
-	const normalizeModelOutput = (text) => {
-		if (!text) return "";
-		const trimmed = text.trim();
-		if (!trimmed) return "";
-		const remainingMatch = trimmed.match(/REMAINING\s*:\s*([\s\S]*)$/i);
-		if (remainingMatch) return `REMAINING: ${remainingMatch[1].trim()}`;
-		return (trimmed.split(/\n\s*\n/)[0]?.trim() ?? trimmed).slice(0, 220);
-	};
-	/**
-	* 判定动作是否会触发 DOM 结构变化（
-	*
-	* 触发后应强制断轮，等待下一轮新快照继续。
-	* 
-	*/
-	const shouldForceRoundBreak = (toolName, toolInput) => {
-		const action = getToolAction(toolInput);
-		if (toolName === "navigate") return action === "goto" || action === "back" || action === "forward" || action === "reload";
-		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;
-	};
-	/**
-	* 将“找不到元素”的失败任务整理成可重试清单（中）/ Build retry task list for not-found failures (EN).
-	*/
-	const collectMissingTask = (name, input, result) => {
-		if (!isElementNotFoundResult(result)) return null;
-		return {
-			name,
-			input,
-			reason: toContentString(result.content).slice(0, 240)
-		};
-	};
-	/**
-	* 解析 REMAINING 协议（中）/ Parse REMAINING protocol from model text (EN).
-	*
-	* 支持：
-	* - `REMAINING: <text>` → 继续下一轮消费该剩余文本
-	* - `REMAINING: DONE`   → 剩余任务为空
-	* 返回 null 表示本轮没有提供 REMAINING 标记。
-	*/
-	const parseRemainingInstruction = (text) => {
-		if (!text) return null;
-		const match = text.match(/REMAINING\s*:\s*([\s\S]*)$/i);
-		if (!match) return null;
-		const value = match[1].trim();
-		return /^done$/i.test(value) ? "" : value;
-	};
-	/**
-	* 推进下一轮描述（中）/ Derive next-round instruction from model text (EN).
-	*
-	* 优先 REMAINING 协议；若未提供，则保持当前 remaining 不变。
-	* Priority: REMAINING protocol first; otherwise keep current remaining instruction unchanged.
-	*/
-	const deriveNextInstruction = (text, currentInstruction) => {
-		const parsed = parseRemainingInstruction(text);
-		if (parsed !== null) return {
-			nextInstruction: parsed,
-			hasRemainingProtocol: true
-		};
-		return {
-			nextInstruction: currentInstruction,
-			hasRemainingProtocol: false
-		};
-	};
-	/**
-	* 启发式任务剔除（中）/ Heuristic remaining reduction for linear instructions (EN).
-	*
-	* 在 REMAINING 缺失但本轮有执行动作时，按“线性片段”剔除已执行步数，避免下一轮继续携带整段原任务。
-	* When REMAINING is missing but actions were executed, drop executed step count from a linearized instruction.
-	*/
-	const reduceRemainingHeuristically = (currentInstruction, executedCount) => {
-		if (!currentInstruction.trim() || executedCount <= 0) return currentInstruction;
-		const parts = currentInstruction.replace(/\s+/g, " ").replace(/(->|=>|→)/g, " 然后 ").replace(/[，,。；;]/g, " 然后 ").split(/\s*(?:然后|再|并且|并|接着|随后|之后)\s*/g).map((part) => part.trim()).filter(Boolean);
-		if (parts.length <= 1) return currentInstruction;
-		const nextParts = parts.slice(Math.min(executedCount, parts.length));
-		if (nextParts.length === 0) return "";
-		return nextParts.join(" -> ");
-	};
 	for (let round = 0; round < maxRounds; round++) {
 		callbacks?.onRound?.(round);
 		usedRounds = round + 1;
@@ -719,6 +927,7 @@ async function executeAgentLoop(params) {
 			break;
 		}
 		let roundHasError = false;
+		let roundHasPotentialDomMutation = false;
 		const executedTaskCalls = [];
 		const roundMissingTasks = [];
 		for (const tc of response.toolCalls) {
@@ -749,6 +958,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);
@@ -764,7 +974,8 @@ async function executeAgentLoop(params) {
 		else pendingNotFoundRetry = void 0;
 		if (parsedInstructionState.hasRemainingProtocol) remainingInstruction = parsedInstructionState.nextInstruction;
 		else {
-			const nextByHeuristic = reduceRemainingHeuristically(remainingInstruction, executedTaskCalls.length);
+			const heuristicProgressUnits = executedTaskCalls.length > 0 ? 1 : 0;
+			const nextByHeuristic = reduceRemainingHeuristically(remainingInstruction, heuristicProgressUnits);
 			if (nextByHeuristic !== remainingInstruction) remainingInstruction = nextByHeuristic;
 			else roundHasError = true;
 		}
@@ -782,6 +993,7 @@ async function executeAgentLoop(params) {
 			break;
 		}
 		consecutiveReadOnlyRounds = idleResult;
+		if (roundHasPotentialDomMutation) await runRoundStabilityBarrier();
 		await refreshSnapshot();
 	}
 	const resultMessages = [...history ?? [], {
@@ -828,7 +1040,9 @@ const PROVIDER_ENDPOINTS = {
 	openai: "https://api.openai.com/v1",
 	copilot: "https://models.inference.ai.azure.com",
 	anthropic: "https://api.anthropic.com",
-	deepseek: "https://api.deepseek.com"
+	deepseek: "https://api.deepseek.com",
+	doubao: "https://ark.cn-beijing.volces.com/api/v3",
+	qwen: "https://dashscope.aliyuncs.com/compatible-mode/v1"
 };
 /** 校验 provider（中）/ Validate provider support (EN). */
 function validateProvider(provider) {
@@ -1323,6 +1537,32 @@ async function parseAnthropicStream(response) {
 */
 var DeepSeekClient = class extends OpenAIClient {};
 
+//#endregion
+//#region src/core/ai-client/doubao.ts
+/**
+* Doubao 客户端封装（中）/ Doubao client wrapper (EN).
+*
+* Doubao（火山引擎 Ark）与 OpenAI Chat Completions 兼容，直接复用 OpenAIClient。
+* Doubao (Volcengine Ark) is OpenAI-compatible, so it reuses OpenAIClient behavior.
+*/
+/**
+* Doubao 客户端类（中）/ Doubao client class extending OpenAIClient (EN).
+*/
+var DoubaoClient = class extends OpenAIClient {};
+
+//#endregion
+//#region src/core/ai-client/qwen.ts
+/**
+* Qwen 客户端封装（中）/ Qwen client wrapper (EN).
+*
+* Qwen（阿里云百炼兼容模式）与 OpenAI Chat Completions 兼容，直接复用 OpenAIClient。
+* Qwen (DashScope compatible mode) is OpenAI-compatible, so it reuses OpenAIClient behavior.
+*/
+/**
+* Qwen 客户端类（中）/ Qwen client class extending OpenAIClient (EN).
+*/
+var QwenClient = class extends OpenAIClient {};
+
 //#endregion
 //#region src/core/ai-client/index.ts
 /**
@@ -1333,9 +1573,11 @@ function createAIClient(config) {
 	switch (config.provider) {
 		case "openai":
 		case "copilot": return new OpenAIClient(config);
+		case "doubao": return new DoubaoClient(config);
+		case "qwen": return new QwenClient(config);
 		case "anthropic": return new AnthropicClient(config);
 		case "deepseek": return new DeepSeekClient(config);
-		default: throw new Error(`Unknown AI provider: ${config.provider}. Supported: openai, copilot, anthropic, deepseek`);
+		default: throw new Error(`Unknown AI provider: ${config.provider}. Supported: openai, copilot, anthropic, deepseek, doubao, qwen`);
 	}
 }
 
@@ -1436,12 +1678,16 @@ function buildSystemPrompt(params = {}) {
 		"- 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).",
+		"- Always cross-check planned actions against the original goal to avoid task drift (e.g., do not confuse create issue vs create repository).",
 		"- If a required list shows `... (N children omitted)` under a specific container, request focused expansion by outputting `SNAPSHOT_HINT: EXPAND_CHILDREN #<containerRef>`.",
 		"- After outputting snapshot expansion hint, wait for the next refreshed snapshot before further scrolling/clicking on that list.",
 		"- 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.",
 		"",
+		"## 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:",
@@ -1469,25 +1715,89 @@ function buildSystemPrompt(params = {}) {
 }
 
 //#endregion
-//#region src/web/tools/dom-tool.ts
+//#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);
+}
 /**
-* DOM Tool — 浏览器 DOM 操作工具（结合 Playwright 核心交互模式增强）。
-*
-* 关键改进（参考 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
+* 安装全局监听追踪补丁（幂等）。
+*/
+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/constants.ts
+/**
+* DOM Tool 常量定义。
 *
-* 运行环境：浏览器 Content Script（直接访问 DOM，无 CDP）。
+* 包含：input 类型分类、修饰键集合、键码映射、滚动策略。
 */
-const DEFAULT_WAIT_MS = 2e3;
+/** 默认等待超时（ms） */
+const DEFAULT_WAIT_MS = 1200;
 /** scrollIntoView 轮换策略（参考 Playwright dom.ts） */
 const SCROLL_OPTIONS = [
 	void 0,
@@ -1547,6 +1857,9 @@ const KEY_CODE_MAP = {
 	Alt: "AltLeft",
 	Meta: "MetaLeft"
 };
+
+//#endregion
+//#region src/web/tools/dom-tool/query.ts
 let activeRefStore;
 function setActiveRefStore(store) {
 	activeRefStore = store;
@@ -1557,15 +1870,26 @@ function getActiveRefStore() {
 function sleep(ms) {
 	return new Promise((r) => setTimeout(r, ms));
 }
-/** 查询元素：优先 RefStore hash，回退 CSS 选择器 */
+/**
+* 查询元素：优先 RefStore hash，回退 CSS 选择器。
+* 支持复合 hash 选择器（如 "#hashID .child-class"）——先解析 hash 根，再在其子树内 querySelector。
+*/
 function queryElement(selector) {
 	try {
 		if (selector.startsWith("#") && activeRefStore) {
-			const id = selector.slice(1);
-			if (activeRefStore.has(id)) {
-				const el = activeRefStore.get(id);
-				if (!el) return `未找到 ref "${selector}" 对应的元素（可能已被移除或快照已过期）`;
-				return el;
+			const spaceIdx = selector.indexOf(" ");
+			const hashPart = spaceIdx > 0 ? selector.slice(1, spaceIdx) : selector.slice(1);
+			const rest = spaceIdx > 0 ? selector.slice(spaceIdx + 1).trim() : "";
+			if (activeRefStore.has(hashPart)) {
+				const root = activeRefStore.get(hashPart);
+				if (!root || !root.isConnected) {
+					activeRefStore.delete(hashPart);
+					return `未找到 ref "#${hashPart}" 对应的元素（可能已被移除或快照已过期）`;
+				}
+				if (!rest) return root;
+				const child = root.querySelector(rest);
+				if (!child) return `在 #${hashPart} 内未找到匹配 "${rest}" 的子元素`;
+				return child;
 			}
 		}
 		const el = document.querySelector(selector);
@@ -1593,6 +1917,30 @@ function resolveWaitMs(params) {
 	if (typeof waitSeconds === "number" && Number.isFinite(waitSeconds)) return Math.max(0, Math.floor(waitSeconds * 1e3));
 	return DEFAULT_WAIT_MS;
 }
+/** 生成元素的简洁描述字符串，用于工具调用结果的可读输出。 */
+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(", ")}]` : ""}`;
+}
+
+//#endregion
+//#region src/web/tools/dom-tool/actionability.ts
 /** 检查元素样式可见性（处理 checkVisibility / details 折叠 / visibility） */
 function isStyleVisible(el, style) {
 	style = style ?? window.getComputedStyle(el);
@@ -1673,23 +2021,6 @@ function checkElementStable(el, timeoutMs = 800) {
 		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);
@@ -1711,7 +2042,7 @@ function checkHitTarget(el) {
 	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);
+	return `<${topEl.tagName.toLowerCase()}${topEl.id ? `#${topEl.id}` : ""}>`;
 }
 function ensureActionable(el, action, selector, force) {
 	if (force) return null;
@@ -1766,6 +2097,15 @@ function ensureActionable(el, action, selector, force) {
 	};
 	return null;
 }
+
+//#endregion
+//#region src/web/tools/dom-tool/events.ts
+/**
+* DOM Tool — 事件派发与键盘操作。
+*
+* 包含：完整点击事件链、hover 事件链、input/change 派发、
+*       原生 setter 写入、selectText、组合键 press。
+*/
 function getClickPoint(el) {
 	const r = el.getBoundingClientRect();
 	return {
@@ -1774,7 +2114,7 @@ function getClickPoint(el) {
 	};
 }
 /**
-* 完整点击事件链（参考 Playwright Mouse.click）：
+* 完整点击事件链：
 * pointermove → mousemove → (per clickCount) pointerdown → mousedown → focus → pointerup → mouseup → click
 */
 function dispatchClickEvents(el, clickCount = 1) {
@@ -1942,25 +2282,31 @@ function executePress(el, key) {
 		...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}`);
+
+//#endregion
+//#region src/web/tools/dom-tool/resolve.ts
+/**
+* DOM Tool — 目标解析与归一化。
+*
+* 包含：retarget、checkable 目标归一化、pointer action 代理、
+*       表单项控件重定向、editable 穿透。
+*/
+/**
+* 将目标重定向到关联的交互控件。
+* - 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;
+		}
 	}
-	if (el instanceof HTMLSelectElement && el.value) hints.push(`val=${el.value}`);
-	return `<${tag}${id}${cls}>${textHint}${hints.length > 0 ? ` [${hints.join(", ")}]` : ""}`;
+	return el;
 }
 function getChecked(el) {
 	if (el instanceof HTMLInputElement && (el.type === "checkbox" || el.type === "radio")) return el.checked;
@@ -2021,6 +2367,35 @@ function resolveFormItemControlTarget(el) {
 	if (control && isElementVisible(control)) return control;
 	return el;
 }
+/**
+* 穿透包裹容器，查找内部可编辑子元素。
+* 覆盖 UI 框架常见模式：wrapper div 包裹真实 input/textarea。
+* 若自身已可编辑则直接返回；否则在子树中搜索第一个可编辑且可见的控件。
+* 对 role=slider/spinbutton 等 ARIA widget：向上逐级查找最近容器中的关联 input。
+*/
+function resolveEditableTarget(el) {
+	if (isEditableElement(el)) return el;
+	const inner = el.querySelector("input:not([type=\"hidden\"]), textarea, select, [contenteditable=\"true\"]");
+	if (inner && isEditableElement(inner) && isElementVisible(inner)) return inner;
+	const role = el.getAttribute("role");
+	if (role === "slider" || role === "spinbutton") {
+		let ancestor = el.parentElement;
+		for (let depth = 0; ancestor && depth < 5; depth++, ancestor = ancestor.parentElement) {
+			const input = ancestor.querySelector("input[type=\"number\"], input[role=\"spinbutton\"], input:not([type=\"hidden\"])");
+			if (input instanceof HTMLInputElement && isEditableElement(input) && isElementVisible(input)) return input;
+		}
+	}
+	return el;
+}
+
+//#endregion
+//#region src/web/tools/dom-tool/dropdown.ts
+/**
+* DOM Tool — 自定义下拉增强。
+*
+* 包含：全局可见 option 查找、下拉弹出等待。
+*/
+/** 在全局可见 option 节点中按文本匹配（精确 → 包含） */
 function findVisibleOptionByText(text) {
 	const target = text.trim().toLowerCase();
 	if (!target) return null;
@@ -2041,6 +2416,7 @@ function findVisibleOptionByText(text) {
 	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) {
@@ -2049,22 +2425,33 @@ async function waitForDropdownPopup(maxWait = 500) {
 		await sleep(50);
 	}
 }
+
+//#endregion
+//#region src/web/tools/dom-tool/index.ts
+/**
+* DOM Tool — 浏览器 DOM 操作工具入口（结合 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
+*
+* 运行环境：浏览器 Content Script（直接访问 DOM，无 CDP）。
+*/
 function createDomTool() {
 	return {
 		name: "dom",
 		description: [
 			"Perform DOM operations on the current page.",
 			"Actions: click, fill, select_option, clear, check, uncheck, type, focus, hover, scroll, press, get_text, get_attr, set_attr, add_class, remove_class.",
-			"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.",
-			"For wheel/virtualized pickers where target option is not visible yet, use scroll on the picker column first, then click/select the newly visible option. scroll supports steps for repeated scrolling in one call."
+			"fill auto-resolves wrapper → inner input. check/uncheck toggles via click. press supports combos (Control+a). scroll supports steps for repeated scrolling."
 		].join(" "),
 		schema: Type.Object({
 			action: Type.String({ description: "DOM action: click | fill | select_option | clear | check | uncheck | type | focus | hover | scroll | press | get_text | get_attr | set_attr | add_class | remove_class." }),
@@ -2079,7 +2466,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)." }))
 		}),
@@ -2127,6 +2514,11 @@ function createDomTool() {
 				el = r;
 			}
 			if (action === "check" || action === "uncheck") el = resolveCheckableTarget(el);
+			if ([
+				"fill",
+				"type",
+				"clear"
+			].includes(action)) el = resolveEditableTarget(retarget(el, "follow-label"));
 			const actionabilityTarget = action === "click" || action === "check" || action === "uncheck" ? resolvePointerActionTarget(resolveFormItemControlTarget(el)) : el;
 			try {
 				const checkResult = ensureActionable(actionabilityTarget, action, selector, force);
@@ -2160,7 +2552,7 @@ function createDomTool() {
 					case "fill": {
 						const value = params.value;
 						if (value === void 0) return { content: "缺少 value 参数" };
-						const target = retarget(el, "follow-label");
+						const target = el;
 						if (target instanceof HTMLInputElement) {
 							const type = target.type.toLowerCase();
 							if (INPUT_BLOCKED_TYPES.has(type)) return {
@@ -2303,7 +2695,7 @@ function createDomTool() {
 						return { content: `已选择 ${describeElement(target)}: value="${selected.value}", label="${selected.text.trim()}"` };
 					}
 					case "clear": {
-						const target = retarget(el, "follow-label");
+						const target = el;
 						if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
 							scrollIntoViewIfNeeded(target);
 							target.focus();
@@ -2363,7 +2755,7 @@ function createDomTool() {
 					case "type": {
 						const value = params.value;
 						if (value === void 0) return { content: "缺少 value 参数" };
-						const target = retarget(el, "follow-label");
+						const target = el;
 						scrollIntoViewIfNeeded(target);
 						if (target instanceof HTMLElement) target.focus();
 						for (const char of value) {
@@ -2530,6 +2922,50 @@ const MAX_EXPANDED_LIST_CHILDREN = 120;
 /** 定向放宽 children 的硬上限。 */
 const MAX_EXPANDED_CHILDREN_LIMIT = 300;
 /**
+* 事件名 → 快照简写映射。
+* 目的：大幅压缩 listeners="..." 占用的 token，同时保留可读性。
+* 简写规则在 system-prompt 中向模型说明。
+*/
+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",
+	pointerenter: "pen",
+	pointerleave: "plv",
+	touchstart: "tst",
+	touchend: "ted",
+	touchmove: "tmv",
+	keydown: "kdn",
+	keyup: "kup",
+	keypress: "kpr",
+	input: "inp",
+	change: "chg",
+	submit: "sub",
+	focus: "fcs",
+	blur: "blr",
+	scroll: "scl",
+	wheel: "whl",
+	drag: "drg",
+	dragstart: "drs",
+	dragend: "dre",
+	drop: "drp",
+	contextmenu: "ctx",
+	resize: "rsz"
+};
+/** 将完整事件名转为快照简写（未收录的取前 3 字符）。 */
+function abbrevEvent(name) {
+	return EVENT_ABBREV[name] ?? name.slice(0, 3);
+}
+/**
 * 规整快照属性值，避免把长 base64/data URL 原样注入快照。
 */
 function sanitizeSnapshotAttrValue(value) {
@@ -2581,6 +3017,7 @@ function generateSnapshot(root = document.body, options = {}) {
 	const expandChildrenRefSet = new Set((opts.expandChildrenRefs ?? []).map((ref) => ref.trim().replace(/^#/, "")).filter(Boolean));
 	let emittedNodes = 0;
 	let truncatedByNodeBudget = false;
+	const emittedRefIds = /* @__PURE__ */ new Set();
 	const refStore = opts.refStore;
 	const SKIP_TAGS = new Set([
 		"SCRIPT",
@@ -2617,6 +3054,9 @@ function generateSnapshot(root = document.body, options = {}) {
 		"name",
 		"role",
 		"aria-label",
+		"aria-valuenow",
+		"aria-valuemin",
+		"aria-valuemax",
 		"src",
 		"alt",
 		"title",
@@ -2634,6 +3074,25 @@ 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",
+		"keypress",
+		"submit",
+		"focus",
+		"blur"
+	]);
 	/** 布尔状态属性 — 只在存在时输出（无值），如 disabled、checked */
 	const BOOLEAN_ATTRS = [
 		"disabled",
@@ -2682,15 +3141,22 @@ 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 trackedEvents = getTrackedElementEvents(el);
+		if (trackedEvents.length === 0) return false;
+		return trackedEvents.some((eventName) => INTERACTIVE_EVENTS.has(eventName));
+	}
 	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;
 	}
 	/** 判断是否为“选项列表”容器（时间/下拉/listbox 等）。 */
@@ -2751,6 +3217,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);
@@ -2800,8 +3272,10 @@ function generateSnapshot(root = document.body, options = {}) {
 		let line = `${indent}[${tag}]`;
 		if (directText) line += ` "${directText.slice(0, maxTextLength)}"`;
 		if (attrs.length) line += ` ${attrs.join(" ")}`;
-		if (hashId) line += ` #${hashId}`;
-		else line += ` ref="${currentPath}"`;
+		if (hashId) {
+			line += ` #${hashId}`;
+			emittedRefIds.add(hashId);
+		} else line += ` ref="${currentPath}"`;
 		const lines = [line];
 		emittedNodes++;
 		const allChildren = Array.from(el.children);
@@ -2819,6 +3293,7 @@ function generateSnapshot(root = document.body, options = {}) {
 		return lines.join("\n");
 	}
 	const output = walk(root, 0, "") || "(空页面)";
+	refStore?.prune(emittedRefIds);
 	if (!truncatedByNodeBudget) return output;
 	return `${output}\n... (snapshot truncated: maxNodes=${maxNodes})`;
 }
@@ -3046,7 +3521,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 = {
@@ -3100,7 +3575,14 @@ function resolveSelector(selector) {
 		const store = getActiveRefStore();
 		if (store) {
 			const id = selector.slice(1);
-			if (store.has(id)) return store.get(id) ?? null;
+			if (store.has(id)) {
+				const el = store.get(id);
+				if (!el || !el.isConnected) {
+					store.delete(id);
+					return null;
+				}
+				return el;
+			}
 		}
 	}
 	try {
@@ -3238,7 +3720,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) => {
@@ -3444,6 +3926,29 @@ var RefStore = class {
 	has(id) {
 		return this.map.has(id);
 	}
+	/** 删除指定 hash ID 映射，返回是否删除成功。 */
+	delete(id) {
+		return this.map.delete(id);
+	}
+	/**
+	* 清理失效引用：
+	* - 仅保留 keepIds 中的映射（若提供）
+	* - 自动移除已脱离文档（isConnected=false）的元素
+	*
+	* @returns 被移除的映射数量
+	*/
+	prune(keepIds) {
+		let removed = 0;
+		for (const [id, el] of this.map.entries()) {
+			const shouldKeepById = keepIds ? keepIds.has(id) : true;
+			const isConnected = el.isConnected;
+			if (!shouldKeepById || !isConnected) {
+				this.map.delete(id);
+				removed++;
+			}
+		}
+		return removed;
+	}
 	/** 清空所有映射 */
 	clear() {
 		this.map.clear();
@@ -3575,6 +4080,7 @@ function registerToolHandler(executors) {
 *   │  └──────────┘  └────────────┘  └──────────────┘ │
 *   └──────────────────────────────────────────────────┘
 */
+installEventListenerTracking();
 var WebAgent = class WebAgent {
 	/** 默认系统提示词 key（兼容旧版 setSystemPrompt(prompt)）。 */
 	static DEFAULT_SYSTEM_PROMPT_KEY = "default";
@@ -3607,6 +4113,8 @@ var WebAgent = class WebAgent {
 	autoSnapshot;
 	/** 快照选项 */
 	snapshotOptions;
+	/** 轮次后稳定等待配置 */
+	roundStabilityWait;
 	/** 工具注册表实例 — 每个 WebAgent 拥有独立的工具集 */
 	registry = new ToolRegistry();
 	/** 事件回调 — 绑定后可实时获取 Agent 进度，用于 UI 展示 */
@@ -3623,6 +4131,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);
 	}
@@ -3815,6 +4324,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;