agentpage 0.0.2 → 0.0.4

package/dist/index.mjs

@@ -172,6 +172,7 @@ async function executeAgentLoop(params) {
 				}
 			}
 			if (tc.name === "dom" && pageContext.needsSnapshotBeforeDom) {
+				callbacks?.onBeforeRecoverySnapshot?.(pageContext.currentUrl);
 				const snapshotText = await readPageSnapshot(registry, 8);
 				pageContext.latestSnapshot = snapshotText;
 				pageContext.needsSnapshotBeforeDom = false;
@@ -224,6 +225,7 @@ async function executeAgentLoop(params) {
 				const recoveryWaitMs = resolveRecoveryWaitMs(tc.input);
 				if (attempts <= DEFAULT_ACTION_RECOVERY_ROUNDS) {
 					await sleep$1(recoveryWaitMs);
+					callbacks?.onBeforeRecoverySnapshot?.();
 					const snapshotText = await readPageSnapshot(registry, 8);
 					pageContext.latestSnapshot = snapshotText;
 					const originalError = toContentString(result.content);
@@ -791,7 +793,7 @@ var ToolRegistry = class {
 */
 function buildSystemPrompt(params = {}) {
 	const sections = [];
-	sections.push("You are AutoPilot, an AI agent embedded in the user's web page.\nYou can interact with the page by clicking elements, filling forms, reading content, and executing JavaScript.\nAlways confirm destructive actions with the user before executing.\n\n## 操作策略\n\n每次用户请求操作页面时，系统会自动附上当前页面的 DOM 快照。\n快照中每个元素都带有 ref 属性（基于层级位置的唯一路径，如 /body/main/form/button）。\n请严格遵循以下流程：\n1. 分析快照，理解页面结构和元素层级关系。\n2. 从快照中找到目标元素，复制其 ref 路径。\n3. 将 ref 路径作为 dom 工具的 selector 参数传入。\n4. **禁止**猜测 CSS 选择器（如 'button'、'#id'、'.class'），必须使用快照中的 ref 路径。\n5. 规划操作步骤后，按顺序逐步执行。\n\n## 元素选择原则（语义优先）\n\n页面中可能存在多个文本相似的元素（如多个「发送」按钮、多个输入框）。\n**严禁仅凭元素文本匹配来选择操作对象**，必须结合以下语义上下文综合判断：\n1. **层级归属**：元素属于哪个区域/表单/卡片？从 ref 路径的父级结构判断（如 /body/main/form 下的按钮属于该表单）。\n2. **功能关联**：元素与用户意图的功能是否匹配？一个「发送」按钮在聊天区域，另一个在表单区域，要根据用户想操作的功能区来选择。\n3. **周围元素**：查看目标元素的兄弟节点和父级容器，理解它所在的功能模块。\n4. **属性辅助**：利用 id、class、placeholder、aria-label、name 等属性辅助确认元素的用途。\n5. **操作上下文**：如果用户在一系列操作中（如先填写表单再点提交），选择与前序操作同区域的元素。\n\n示例：用户说「点击发送按钮」，页面有两个按钮都叫「发送」：\n- /body/div[1]/div/chat-area/button → 聊天发送按钮\n- /body/div[1]/div/form/button → 表单提交按钮\n你必须根据用户意图和对话上下文判断应该点击哪个，而不是随意选择。");
+	sections.push("You are AutoPilot, an AI agent embedded in the user's web page.\nYou can click, fill forms, read content, navigate, and execute JavaScript.\n\n## 操作规则\n\n1. 快照中每个元素末尾的 `#xxxx` 是 hash ID。操作时**必须**用 `#xxxx` 作为 dom 工具的 selector 参数。\n2. **禁止**猜测 CSS 选择器，只用快照中的 hash ID。\n3. 多个相似元素时，根据层级结构、所在功能区域和用户意图判断目标。\n4. 快照看不到目标时，先滚动页面或用 snapshot 获取更深层级。\n5. 破坏性操作前先与用户确认。");
 	const tools = params.tools ?? [];
 	if (tools.length > 0) {
 		const toolLines = tools.map((t) => `- **${t.name}**: ${t.description}`);
@@ -800,6 +802,271 @@ function buildSystemPrompt(params = {}) {
 	return sections.join("\n\n");
 }
 
+//#endregion
+//#region src/web/dom-tool.ts
+/**
+* DOM Tool — 基于 Web API 的 DOM 操作工具。
+*
+* 替代 Playwright 的 click/fill/type 等操作，直接在页面上下文中执行。
+* 运行环境：浏览器 Content Script。
+*
+* 支持 8 种动作：
+*   click        — 点击元素
+*   fill         — 填写输入框（清空后设值）
+*   type         — 逐字符模拟键入
+*   get_text     — 获取元素文本内容
+*   get_attr     — 获取元素属性值
+*   set_attr     — 设置元素属性
+*   add_class    — 添加 CSS 类名
+*   remove_class — 移除 CSS 类名
+*/
+const DEFAULT_WAIT_MS = 1e3;
+/** 当前活跃的 RefStore 实例（由 WebAgent 在 chat() 时设置） */
+let activeRefStore;
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* 安全地查询 DOM 元素。
+*
+* 支持两种定位方式（优先级从高到低）：
+* - hash ID（以 "#" 开头且在 RefStore 中存在）：确定性 hash 查找（最高效）
+* - CSS 选择器（其他）：传统 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 el = document.querySelector(selector);
+		if (!el) return `未找到匹配 "${selector}" 的元素`;
+		return el;
+	} catch (e) {
+		return `选择器语法错误: ${selector}`;
+	}
+}
+/**
+* 设置当前活跃的 RefStore（由 WebAgent 在 chat 开始时调用）。
+*/
+function setActiveRefStore(store) {
+	activeRefStore = store;
+}
+/** 获取当前活跃的 RefStore（供其他工具复用） */
+function getActiveRefStore() {
+	return activeRefStore;
+}
+/**
+* 在给定超时时间内轮询查找元素。
+* - 返回 Element：找到元素
+* - 返回 string：选择器语法错误
+* - 返回 null：超时未找到
+*/
+async function waitForElement(selector, timeoutMs) {
+	const start = Date.now();
+	while (Date.now() - start <= timeoutMs) {
+		const elOrError = queryElement(selector);
+		if (typeof elOrError !== "string") return elOrError;
+		if (elOrError.startsWith("选择器语法错误")) return elOrError;
+		await sleep(100);
+	}
+	return null;
+}
+function resolveWaitMs(params) {
+	const waitMs = params.waitMs;
+	if (typeof waitMs === "number" && Number.isFinite(waitMs)) return Math.max(0, Math.floor(waitMs));
+	const waitSeconds = params.waitSeconds;
+	if (typeof waitSeconds === "number" && Number.isFinite(waitSeconds)) return Math.max(0, Math.floor(waitSeconds * 1e3));
+	return DEFAULT_WAIT_MS;
+}
+/**
+* 模拟真实用户输入：触发 input、change 事件，兼容 React/Vue 等框架。
+*/
+function dispatchInputEvents(el) {
+	el.dispatchEvent(new Event("input", {
+		bubbles: true,
+		cancelable: true
+	}));
+	el.dispatchEvent(new Event("change", {
+		bubbles: true,
+		cancelable: true
+	}));
+}
+/**
+* 生成元素的可读描述，用于在操作结果中展示实际命中的 DOM 节点。
+* 格式：<tag#id.class> "文本" [attr=val, ...]
+*/
+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.textContent?.trim().slice(0, 40) ?? "";
+	const textHint = text ? ` "${text}"` : "";
+	const hints = [];
+	for (const attr of [
+		"type",
+		"name",
+		"placeholder",
+		"href",
+		"role"
+	]) {
+		const val = el.getAttribute(attr);
+		if (val) hints.push(`${attr}=${val}`);
+	}
+	return `<${tag}${id}${cls}>${textHint}${hints.length > 0 ? ` [${hints.join(", ")}]` : ""}`;
+}
+function createDomTool() {
+	return {
+		name: "dom",
+		description: [
+			"Perform DOM operations on the current page.",
+			"Actions: click, fill, type, get_text, get_attr, set_attr, add_class, remove_class.",
+			"Use the hash ID from DOM snapshot (e.g. #a1b2c) as selector."
+		].join(" "),
+		schema: Type.Object({
+			action: Type.String({ description: "DOM action: click | fill | type | get_text | get_attr | set_attr | add_class | remove_class" }),
+			selector: Type.String({ description: "Element ref ID from snapshot (e.g. #r0, #r5) or CSS selector" }),
+			value: Type.Optional(Type.String({ description: "Value for fill/type/set_attr actions" })),
+			attribute: Type.Optional(Type.String({ description: "Attribute name for get_attr/set_attr actions" })),
+			className: Type.Optional(Type.String({ description: "CSS class name for add_class/remove_class" })),
+			waitMs: Type.Optional(Type.Number({ description: "Optional wait timeout in ms before action (default: 1000). Use 0 to disable waiting." })),
+			waitSeconds: Type.Optional(Type.Number({ description: "Optional wait timeout in seconds before action. Used when waitMs is not provided." }))
+		}),
+		execute: async (params) => {
+			const action = params.action;
+			const selector = params.selector;
+			const waitMs = resolveWaitMs(params);
+			if (!selector) return { content: "缺少 selector 参数" };
+			let el;
+			if (waitMs > 0) {
+				const found = await waitForElement(selector, waitMs);
+				if (typeof found === "string") return {
+					content: found,
+					details: {
+						error: true,
+						code: "INVALID_SELECTOR",
+						action,
+						selector
+					}
+				};
+				if (!found) return {
+					content: `未找到匹配 "${selector}" 的元素`,
+					details: {
+						error: true,
+						code: "ELEMENT_NOT_FOUND",
+						action,
+						selector,
+						waitMs
+					}
+				};
+				el = found;
+			} else {
+				const elOrError = queryElement(selector);
+				if (typeof elOrError === "string") return {
+					content: elOrError,
+					details: {
+						error: true,
+						code: elOrError.startsWith("未找到") ? "ELEMENT_NOT_FOUND" : "INVALID_SELECTOR",
+						action,
+						selector,
+						waitMs
+					}
+				};
+				el = elOrError;
+			}
+			try {
+				switch (action) {
+					case "click":
+						if (el instanceof HTMLElement) {
+							el.focus();
+							el.click();
+						} else el.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+						return { content: `已点击 ${describeElement(el)}` };
+					case "fill": {
+						const value = params.value;
+						if (value === void 0) return { content: "缺少 value 参数" };
+						if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+							el.focus();
+							el.value = value;
+							dispatchInputEvents(el);
+						} else if (el instanceof HTMLElement && el.isContentEditable) {
+							el.focus();
+							el.textContent = value;
+							el.dispatchEvent(new Event("input", { bubbles: true }));
+						} else return { content: `"${selector}" 不是可编辑元素` };
+						return { content: `已填写 ${describeElement(el)}: "${value}"` };
+					}
+					case "type": {
+						const value = params.value;
+						if (value === void 0) return { content: "缺少 value 参数" };
+						if (el instanceof HTMLElement) el.focus();
+						for (const char of value) {
+							el.dispatchEvent(new KeyboardEvent("keydown", {
+								key: char,
+								bubbles: true
+							}));
+							el.dispatchEvent(new KeyboardEvent("keypress", {
+								key: char,
+								bubbles: true
+							}));
+							if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) el.value += char;
+							el.dispatchEvent(new Event("input", { bubbles: true }));
+							el.dispatchEvent(new KeyboardEvent("keyup", {
+								key: char,
+								bubbles: true
+							}));
+						}
+						return { content: `已逐字输入到 ${describeElement(el)}: "${value}"` };
+					}
+					case "get_text": {
+						const text = el.textContent?.trim() ?? "";
+						return { content: `${describeElement(el)} 的文本内容：${text || "(空)"}` };
+					}
+					case "get_attr": {
+						const attribute = params.attribute;
+						if (!attribute) return { content: "缺少 attribute 参数" };
+						const attrValue = el.getAttribute(attribute);
+						return { content: `${describeElement(el)} 的 ${attribute} = ${attrValue ?? "(不存在)"}` };
+					}
+					case "set_attr": {
+						const attribute = params.attribute;
+						const value = params.value;
+						if (!attribute || value === void 0) return { content: "缺少 attribute 或 value 参数" };
+						el.setAttribute(attribute, value);
+						return { content: `已设置 ${describeElement(el)} 的 ${attribute}="${value}"` };
+					}
+					case "add_class": {
+						const className = params.className;
+						if (!className) return { content: "缺少 className 参数" };
+						el.classList.add(className);
+						return { content: `已添加 class "${className}" 到 ${describeElement(el)}` };
+					}
+					case "remove_class": {
+						const className = params.className;
+						if (!className) return { content: "缺少 className 参数" };
+						el.classList.remove(className);
+						return { content: `已移除 ${describeElement(el)} 的 class "${className}"` };
+					}
+					default: return { content: `未知的 DOM 动作: ${action}` };
+				}
+			} catch (err) {
+				return {
+					content: `DOM 操作 "${action}" 失败: ${err instanceof Error ? err.message : String(err)}`,
+					details: {
+						error: true,
+						action,
+						selector
+					}
+				};
+			}
+		}
+	};
+}
+
 //#endregion
 //#region src/web/page-info-tool.ts
 /**
@@ -819,27 +1086,19 @@ function buildSystemPrompt(params = {}) {
 /**
 * 生成页面 DOM 快照 — 将 DOM 树转为 AI 可理解的文本描述。
 *
-* 类似 Playwright 的 ariaSnapshot()，但基于 Web API 实现。
-* 只遍历可见元素，跳过 script/style/svg 等无意义节点。
-*
-* 每个元素自动生成基于层级位置的 XPath 引用（ref），
-* AI 可以通过 ref 精确定位元素，无需猜测 CSS 选择器。
+* 基于 Web API 实现，只遍历可见元素，跳过 script/style/svg 等无意义节点。
+* 传入 RefStore 时，每个元素生成确定性 hash ID（如 #a1b2c），
+* AI 通过 hash ID 精确定位元素，无需猜测 CSS 选择器。
 *
 * 输出格式示例：
-*   [header] ref="/body/header"
-*     [nav] ref="/body/header/nav"
-*       [a] "首页" href="/" ref="/body/header/nav/a[1]"
-*       [a] "关于" href="/about" ref="/body/header/nav/a[2]"
-*   [main] ref="/body/main"
-*     [h1] "欢迎来到示例网站" ref="/body/main/h1"
-*     [input] type="text" placeholder="搜索..." ref="/body/main/input"
-*     [button] "搜索" id="search-btn" onclick ref="/body/main/button"
-*
-* 增强信息：
-* - id：元素的 id 属性
-* - placeholder：输入框的占位文本
-* - 事件绑定：onclick/onchange 等内联事件处理器
-* - 状态属性：disabled/checked/readonly/required 等
+*   [header] #k9f2a
+*     [nav] #m3d7e
+*       [a] "首页" href="/" #p1c4b
+*       [a] "关于" href="/about" #q8e5f
+*   [main] #r2a6d
+*     [h1] "欢迎" #s7g3h
+*     [input] type="text" placeholder="搜索..." #t4j8k
+*     [button] "搜索" id="search-btn" onclick #u5n2m
 *
 * @param root - 快照根元素（默认 document.body）
 * @param options - 快照选项对象，或传入数字作为 maxDepth（向后兼容）
@@ -849,6 +1108,7 @@ function generateSnapshot(root = document.body, options = {}) {
 	const maxDepth = opts.maxDepth ?? 6;
 	const viewportOnly = opts.viewportOnly ?? true;
 	const pruneLayout = opts.pruneLayout ?? true;
+	const refStore = opts.refStore;
 	const SKIP_TAGS = new Set([
 		"SCRIPT",
 		"STYLE",
@@ -967,7 +1227,7 @@ function generateSnapshot(root = document.body, options = {}) {
 		if (elId) attrs.push(`id="${elId}"`);
 		const className = el.getAttribute("class")?.trim();
 		if (className) {
-			const classes = className.split(/\s+/).filter(Boolean).slice(0, 3).join(" ");
+			const classes = className.split(/\s+/).filter((c) => c && !c.startsWith("data-v-") && c.length < 30).slice(0, 2).join(" ");
 			if (classes) attrs.push(`class="${classes}"`);
 		}
 		for (const attr of INTERACTIVE_ATTRS) {
@@ -979,11 +1239,11 @@ function generateSnapshot(root = document.body, options = {}) {
 		for (const attrObj of Array.from(el.attributes)) if (attrObj.name.startsWith(EVENT_PREFIX)) events.push(attrObj.name);
 		if (events.length > 0) attrs.push(`events=[${events.join(",")}]`);
 		const dataAttrs = [];
-		for (const attrObj of Array.from(el.attributes)) if (attrObj.name.startsWith("data-") && dataAttrs.length < 3) dataAttrs.push(`${attrObj.name}="${attrObj.value.slice(0, 30)}"`);
+		for (const attrObj of Array.from(el.attributes)) if (attrObj.name.startsWith("data-") && !attrObj.name.match(/^data-v-/) && dataAttrs.length < 2) dataAttrs.push(`${attrObj.name}="${attrObj.value.slice(0, 30)}"`);
 		if (dataAttrs.length > 0) attrs.push(...dataAttrs);
 		if ((el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) && el.value) {
 			const currentVal = el.value.slice(0, 60);
-			if (el.getAttribute("value") !== currentVal) attrs.push(`current-value="${currentVal}"`);
+			if (el.getAttribute("value") !== currentVal) attrs.push(`val="${currentVal}"`);
 		}
 		let directText = "";
 		for (let i = 0; i < el.childNodes.length; i++) {
@@ -1003,9 +1263,12 @@ function generateSnapshot(root = document.body, options = {}) {
 			return childLines.join("\n");
 		}
 		let line = `${indent}[${tag}]`;
-		if (directText) line += ` "${directText.slice(0, 80)}"`;
+		if (directText) line += ` "${directText.slice(0, 60)}"`;
 		if (attrs.length) line += ` ${attrs.join(" ")}`;
-		line += ` ref="${currentPath}"`;
+		if (refStore) {
+			const hashId = refStore.set(el, currentPath);
+			line += ` #${hashId}`;
+		} else line += ` ref="${currentPath}"`;
 		const lines = [line];
 		for (let i = 0; i < el.children.length; i++) {
 			const childResult = walk(el.children[i], depth + 1, currentPath);
@@ -1013,366 +1276,88 @@ function generateSnapshot(root = document.body, options = {}) {
 		}
 		return lines.join("\n");
 	}
-	return walk(root, 0, "") || "(空页面)";
-}
-/**
-* 查询所有匹配元素并返回摘要信息（标签、文本、关键属性）。
-*/
-function queryAllElements(selector, limit = 20) {
-	try {
-		const elements = document.querySelectorAll(selector);
-		if (elements.length === 0) return `未找到匹配 "${selector}" 的元素`;
-		const results = [`找到 ${elements.length} 个元素：`];
-		const count = Math.min(elements.length, limit);
-		for (let i = 0; i < count; i++) {
-			const el = elements[i];
-			const tag = el.tagName.toLowerCase();
-			const text = el.textContent?.trim().slice(0, 60) ?? "";
-			const id = el.id ? `#${el.id}` : "";
-			const cls = el.className && typeof el.className === "string" ? `.${el.className.split(" ").filter(Boolean).join(".")}` : "";
-			results.push(`  ${i + 1}. <${tag}${id}${cls}> "${text}"`);
-		}
-		if (elements.length > limit) results.push(`  ...还有 ${elements.length - limit} 个元素`);
-		return results.join("\n");
-	} catch (e) {
-		return `选择器语法错误: ${selector}`;
-	}
-}
-function createPageInfoTool() {
-	return {
-		name: "page_info",
-		description: [
-			"Get information about the current page.",
-			"Actions: get_url, get_title, get_selection (selected text),",
-			"get_viewport (size & scroll), snapshot (DOM structure), query_all (find all matching elements)."
-		].join(" "),
-		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)" })),
-			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)" }))
-		}),
-		execute: async (params) => {
-			const action = params.action;
-			try {
-				switch (action) {
-					case "get_url": return { content: window.location.href };
-					case "get_title": return { content: document.title || "(无标题)" };
-					case "get_selection": return { content: (window.getSelection()?.toString().trim() ?? "") || "(未选中任何文本)" };
-					case "get_viewport": {
-						const info = {
-							viewportWidth: window.innerWidth,
-							viewportHeight: window.innerHeight,
-							scrollX: window.scrollX,
-							scrollY: window.scrollY,
-							pageWidth: document.documentElement.scrollWidth,
-							pageHeight: document.documentElement.scrollHeight
-						};
-						return { content: JSON.stringify(info, null, 2) };
-					}
-					case "snapshot": {
-						const maxDepth = params.maxDepth ?? 6;
-						const viewportOnly = params.viewportOnly ?? true;
-						const pruneLayout = params.pruneLayout ?? true;
-						return { content: generateSnapshot(document.body, {
-							maxDepth,
-							viewportOnly,
-							pruneLayout
-						}) };
-					}
-					case "query_all": {
-						const selector = params.selector;
-						if (!selector) return { content: "缺少 selector 参数" };
-						return { content: queryAllElements(selector) };
-					}
-					default: return { content: `未知的页面信息动作: ${action}` };
-				}
-			} catch (err) {
-				return {
-					content: `页面信息操作 "${action}" 失败: ${err instanceof Error ? err.message : String(err)}`,
-					details: {
-						error: true,
-						action
-					}
-				};
-			}
-		}
-	};
-}
-
-//#endregion
-//#region src/web/dom-tool.ts
-/**
-* DOM Tool — 基于 Web API 的 DOM 操作工具。
-*
-* 替代 Playwright 的 click/fill/type 等操作，直接在页面上下文中执行。
-* 运行环境：浏览器 Content Script。
-*
-* 支持 8 种动作：
-*   click        — 点击元素
-*   fill         — 填写输入框（清空后设值）
-*   type         — 逐字符模拟键入
-*   get_text     — 获取元素文本内容
-*   get_attr     — 获取元素属性值
-*   set_attr     — 设置元素属性
-*   add_class    — 添加 CSS 类名
-*   remove_class — 移除 CSS 类名
-*/
-const DEFAULT_WAIT_MS = 1e3;
-function sleep(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/**
-* 通过快照 ref（XPath 路径）解析到 DOM 元素。
-*
-* ref 格式示例：/body/div[1]/main/form/input[2]
-* 每段为 tagName，可选 [n] 表示同标签兄弟中第 n 个（1-based）。
-*/
-function resolveRef(ref) {
-	const segments = ref.split("/").filter(Boolean);
-	let current = document.documentElement;
-	for (let i = 0; i < segments.length; i++) {
-		const seg = segments[i];
-		if (!current) return null;
-		const match = seg.match(/^([a-z0-9-]+)(?:\[(\d+)\])?$/i);
-		if (!match) return null;
-		const tag = match[1].toUpperCase();
-		const index = match[2] ? parseInt(match[2], 10) : 1;
-		if (i === 0 && current.tagName === tag) continue;
-		const children = Array.from(current.children).filter((c) => c.tagName === tag);
-		const sameTagCount = children.length;
-		if (sameTagCount === 0) return null;
-		if (sameTagCount === 1) current = children[0];
-		else {
-			if (index < 1 || index > sameTagCount) return null;
-			current = children[index - 1];
-		}
-	}
-	return current;
-}
-/**
-* 安全地查询 DOM 元素。
-*
-* 支持两种定位方式：
-* - ref 路径（以 "/" 开头）：使用快照生成的 XPath 精确定位
-* - CSS 选择器（其他）：传统 querySelector
-*/
-function queryElement(selector) {
-	try {
-		if (selector.startsWith("/")) {
-			const el = resolveRef(selector);
-			if (!el) return `未找到 ref "${selector}" 对应的元素`;
-			return el;
-		}
-		const el = document.querySelector(selector);
-		if (!el) return `未找到匹配 "${selector}" 的元素`;
-		return el;
-	} catch (e) {
-		return `选择器语法错误: ${selector}`;
-	}
-}
-/**
-* 在给定超时时间内轮询查找元素。
-* - 返回 Element：找到元素
-* - 返回 string：选择器语法错误
-* - 返回 null：超时未找到
-*/
-async function waitForElement(selector, timeoutMs) {
-	const start = Date.now();
-	while (Date.now() - start <= timeoutMs) {
-		const elOrError = queryElement(selector);
-		if (typeof elOrError !== "string") return elOrError;
-		if (elOrError.startsWith("选择器语法错误")) return elOrError;
-		await sleep(100);
-	}
-	return null;
-}
-function resolveWaitMs(params) {
-	const waitMs = params.waitMs;
-	if (typeof waitMs === "number" && Number.isFinite(waitMs)) return Math.max(0, Math.floor(waitMs));
-	const waitSeconds = params.waitSeconds;
-	if (typeof waitSeconds === "number" && Number.isFinite(waitSeconds)) return Math.max(0, Math.floor(waitSeconds * 1e3));
-	return DEFAULT_WAIT_MS;
-}
-/**
-* 模拟真实用户输入：触发 input、change 事件，兼容 React/Vue 等框架。
-*/
-function dispatchInputEvents(el) {
-	el.dispatchEvent(new Event("input", {
-		bubbles: true,
-		cancelable: true
-	}));
-	el.dispatchEvent(new Event("change", {
-		bubbles: true,
-		cancelable: true
-	}));
+	return walk(root, 0, "") || "(空页面)";
 }
 /**
-* 生成元素的可读描述，用于在操作结果中展示实际命中的 DOM 节点。
-* 格式：<tag#id.class> "文本" [attr=val, ...]
+* 查询所有匹配元素并返回摘要信息（标签、文本、关键属性）。
 */
-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.textContent?.trim().slice(0, 40) ?? "";
-	const textHint = text ? ` "${text}"` : "";
-	const hints = [];
-	for (const attr of [
-		"type",
-		"name",
-		"placeholder",
-		"href",
-		"role"
-	]) {
-		const val = el.getAttribute(attr);
-		if (val) hints.push(`${attr}=${val}`);
+function queryAllElements(selector, limit = 20) {
+	try {
+		const elements = document.querySelectorAll(selector);
+		if (elements.length === 0) return `未找到匹配 "${selector}" 的元素`;
+		const results = [`找到 ${elements.length} 个元素：`];
+		const count = Math.min(elements.length, limit);
+		for (let i = 0; i < count; i++) {
+			const el = elements[i];
+			const tag = el.tagName.toLowerCase();
+			const text = el.textContent?.trim().slice(0, 60) ?? "";
+			const id = el.id ? `#${el.id}` : "";
+			const cls = el.className && typeof el.className === "string" ? `.${el.className.split(" ").filter(Boolean).join(".")}` : "";
+			results.push(`  ${i + 1}. <${tag}${id}${cls}> "${text}"`);
+		}
+		if (elements.length > limit) results.push(`  ...还有 ${elements.length - limit} 个元素`);
+		return results.join("\n");
+	} catch (e) {
+		return `选择器语法错误: ${selector}`;
 	}
-	return `<${tag}${id}${cls}>${textHint}${hints.length > 0 ? ` [${hints.join(", ")}]` : ""}`;
 }
-function createDomTool() {
+function createPageInfoTool() {
 	return {
-		name: "dom",
+		name: "page_info",
 		description: [
-			"Perform DOM operations on the current page.",
-			"Actions: click, fill, type, get_text, get_attr, set_attr, add_class, remove_class.",
-			"Use the ref path from the DOM snapshot (e.g. /body/main/button) as selector to precisely target elements.",
-			"CSS selectors are also supported but ref paths are preferred for accuracy."
+			"Get information about the current page.",
+			"Actions: get_url, get_title, get_selection (selected text),",
+			"get_viewport (size & scroll), snapshot (DOM structure), query_all (find all matching elements)."
 		].join(" "),
 		schema: Type.Object({
-			action: Type.String({ description: "DOM action: click | fill | type | get_text | get_attr | set_attr | add_class | remove_class" }),
-			selector: Type.String({ description: "Element ref path from snapshot (e.g. /body/main/button[2]) or CSS selector" }),
-			value: Type.Optional(Type.String({ description: "Value for fill/type/set_attr actions" })),
-			attribute: Type.Optional(Type.String({ description: "Attribute name for get_attr/set_attr actions" })),
-			className: Type.Optional(Type.String({ description: "CSS class name for add_class/remove_class" })),
-			waitMs: Type.Optional(Type.Number({ description: "Optional wait timeout in ms before action (default: 1000). Use 0 to disable waiting." })),
-			waitSeconds: Type.Optional(Type.Number({ description: "Optional wait timeout in seconds before action. Used when waitMs is not provided." }))
+			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)" })),
+			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)" }))
 		}),
 		execute: async (params) => {
 			const action = params.action;
-			const selector = params.selector;
-			const waitMs = resolveWaitMs(params);
-			if (!selector) return { content: "缺少 selector 参数" };
-			let el;
-			if (waitMs > 0) {
-				const found = await waitForElement(selector, waitMs);
-				if (typeof found === "string") return {
-					content: found,
-					details: {
-						error: true,
-						code: "INVALID_SELECTOR",
-						action,
-						selector
-					}
-				};
-				if (!found) return {
-					content: `未找到匹配 "${selector}" 的元素`,
-					details: {
-						error: true,
-						code: "ELEMENT_NOT_FOUND",
-						action,
-						selector,
-						waitMs
-					}
-				};
-				el = found;
-			} else {
-				const elOrError = queryElement(selector);
-				if (typeof elOrError === "string") return {
-					content: elOrError,
-					details: {
-						error: true,
-						code: elOrError.startsWith("未找到") ? "ELEMENT_NOT_FOUND" : "INVALID_SELECTOR",
-						action,
-						selector,
-						waitMs
-					}
-				};
-				el = elOrError;
-			}
 			try {
 				switch (action) {
-					case "click":
-						if (el instanceof HTMLElement) {
-							el.focus();
-							el.click();
-						} else el.dispatchEvent(new MouseEvent("click", { bubbles: true }));
-						return { content: `已点击 ${describeElement(el)}` };
-					case "fill": {
-						const value = params.value;
-						if (value === void 0) return { content: "缺少 value 参数" };
-						if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
-							el.focus();
-							el.value = value;
-							dispatchInputEvents(el);
-						} else if (el instanceof HTMLElement && el.isContentEditable) {
-							el.focus();
-							el.textContent = value;
-							el.dispatchEvent(new Event("input", { bubbles: true }));
-						} else return { content: `"${selector}" 不是可编辑元素` };
-						return { content: `已填写 ${describeElement(el)}: "${value}"` };
-					}
-					case "type": {
-						const value = params.value;
-						if (value === void 0) return { content: "缺少 value 参数" };
-						if (el instanceof HTMLElement) el.focus();
-						for (const char of value) {
-							el.dispatchEvent(new KeyboardEvent("keydown", {
-								key: char,
-								bubbles: true
-							}));
-							el.dispatchEvent(new KeyboardEvent("keypress", {
-								key: char,
-								bubbles: true
-							}));
-							if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) el.value += char;
-							el.dispatchEvent(new Event("input", { bubbles: true }));
-							el.dispatchEvent(new KeyboardEvent("keyup", {
-								key: char,
-								bubbles: true
-							}));
-						}
-						return { content: `已逐字输入到 ${describeElement(el)}: "${value}"` };
-					}
-					case "get_text": {
-						const text = el.textContent?.trim() ?? "";
-						return { content: `${describeElement(el)} 的文本内容：${text || "(空)"}` };
-					}
-					case "get_attr": {
-						const attribute = params.attribute;
-						if (!attribute) return { content: "缺少 attribute 参数" };
-						const attrValue = el.getAttribute(attribute);
-						return { content: `${describeElement(el)} 的 ${attribute} = ${attrValue ?? "(不存在)"}` };
-					}
-					case "set_attr": {
-						const attribute = params.attribute;
-						const value = params.value;
-						if (!attribute || value === void 0) return { content: "缺少 attribute 或 value 参数" };
-						el.setAttribute(attribute, value);
-						return { content: `已设置 ${describeElement(el)} 的 ${attribute}="${value}"` };
+					case "get_url": return { content: window.location.href };
+					case "get_title": return { content: document.title || "(无标题)" };
+					case "get_selection": return { content: (window.getSelection()?.toString().trim() ?? "") || "(未选中任何文本)" };
+					case "get_viewport": {
+						const info = {
+							viewportWidth: window.innerWidth,
+							viewportHeight: window.innerHeight,
+							scrollX: window.scrollX,
+							scrollY: window.scrollY,
+							pageWidth: document.documentElement.scrollWidth,
+							pageHeight: document.documentElement.scrollHeight
+						};
+						return { content: JSON.stringify(info, null, 2) };
 					}
-					case "add_class": {
-						const className = params.className;
-						if (!className) return { content: "缺少 className 参数" };
-						el.classList.add(className);
-						return { content: `已添加 class "${className}" 到 ${describeElement(el)}` };
+					case "snapshot": {
+						const maxDepth = params.maxDepth ?? 6;
+						const viewportOnly = params.viewportOnly ?? true;
+						const pruneLayout = params.pruneLayout ?? true;
+						return { content: generateSnapshot(document.body, {
+							maxDepth,
+							viewportOnly,
+							pruneLayout,
+							refStore: getActiveRefStore()
+						}) };
 					}
-					case "remove_class": {
-						const className = params.className;
-						if (!className) return { content: "缺少 className 参数" };
-						el.classList.remove(className);
-						return { content: `已移除 ${describeElement(el)} 的 class "${className}"` };
+					case "query_all": {
+						const selector = params.selector;
+						if (!selector) return { content: "缺少 selector 参数" };
+						return { content: queryAllElements(selector) };
 					}
-					default: return { content: `未知的 DOM 动作: ${action}` };
+					default: return { content: `未知的页面信息动作: ${action}` };
 				}
 			} catch (err) {
 				return {
-					content: `DOM 操作 "${action}" 失败: ${err instanceof Error ? err.message : String(err)}`,
+					content: `页面信息操作 "${action}" 失败: ${err instanceof Error ? err.message : String(err)}`,
 					details: {
 						error: true,
-						action,
-						selector
+						action
 					}
 				};
 			}
@@ -1701,6 +1686,106 @@ function createEvaluateTool() {
 	};
 }
 
+//#endregion
+//#region src/web/ref-store.ts
+/**
+* RefStore — 快照 hash ID 与 DOM 元素的映射表。
+*
+* 快照生成时，根据元素的 DOM 路径 + 页面 URL 生成确定性 hash ID，
+* 同时保存 ID → Element 的映射。AI 使用 hash ID 作为 selector 定位元素，
+* 免去超长 XPath 路径，大幅减少 token 消耗。
+*
+* 优势：
+* - **确定性**：同一元素无论快照顺序，始终得到相同 ID
+* - **并发安全**：多次快照不会产生 ID 冲突
+* - **跨页面隔离**：URL hash 作为命名空间，不同页面元素 ID 互不碰撞
+*
+* 生命周期：每次 WebAgent.chat() 调用时创建，对话结束后清空。
+*
+* 使用方：
+*   page-info-tool.ts — generateSnapshot() 写入映射
+*   dom-tool.ts       — queryElement() 读取映射
+*   index.ts          — WebAgent 持有实例，管理生命周期
+*/
+/**
+* FNV-1a 32-bit hash — 简单高效的字符串散列。
+* 分布均匀，碰撞率低，适合生成短 ID。
+*/
+function fnv1a(str) {
+	let h = 2166136261;
+	for (let i = 0; i < str.length; i++) {
+		h ^= str.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return h >>> 0;
+}
+/**
+* hash ID → DOM 元素的映射存储。
+*
+* - `set(el, path)` 由快照生成时调用，返回确定性 hash ID
+* - `get(id)` 由 dom-tool 查询时调用，根据 hash ID 取回元素
+* - `has(id)` 检查 ID 是否存在（用于 selector 类型判断）
+* - `clear()` 每次对话结束后清空
+*/
+var RefStore = class {
+	map = /* @__PURE__ */ new Map();
+	/** 页面 URL 的 hash 前缀，用于跨页面命名空间隔离 */
+	urlKey;
+	/**
+	* @param url 当前页面 URL（可选）。传入后作为 hash 命名空间，
+	*            使不同页面的相同 DOM 路径产生不同 ID。
+	*/
+	constructor(url) {
+		this.urlKey = url ?? "";
+	}
+	/**
+	* 注册一个元素，返回确定性 hash ID。
+	* 相同 URL + path 始终产生相同 ID（并发安全）。
+	*
+	* @param el   DOM 元素引用
+	* @param path 元素的 XPath-like 路径（如 "/body/div[1]/main/button"）
+	*/
+	set(el, path) {
+		const baseId = fnv1a(this.urlKey + path).toString(36);
+		let id = baseId;
+		let suffix = 2;
+		while (this.map.has(id) && this.map.get(id) !== el) id = baseId + suffix++;
+		this.map.set(id, el);
+		return id;
+	}
+	/**
+	* 根据 hash ID 获取 DOM 元素。
+	* 返回 Element 或 undefined（ID 不存在或元素已被移除）。
+	*/
+	get(id) {
+		return this.map.get(id);
+	}
+	/** 检查 hash ID 是否存在 */
+	has(id) {
+		return this.map.has(id);
+	}
+	/** 清空所有映射 */
+	clear() {
+		this.map.clear();
+	}
+	/**
+	* 重置映射表：清空所有映射，并可选更新 URL 命名空间。
+	*
+	* 用于页面导航后刷新 RefStore：旧的 hash ID → Element 映射已失效，
+	* 需要用新 URL 重新生成确定性 hash。
+	*
+	* @param url 新的页面 URL（不传则保持原 URL 命名空间）
+	*/
+	reset(url) {
+		this.map.clear();
+		if (url !== void 0) this.urlKey = url;
+	}
+	/** 当前映射数量 */
+	get size() {
+		return this.map.size;
+	}
+};
+
 //#endregion
 //#region src/web/messaging.ts
 /**
@@ -1931,28 +2016,25 @@ var WebAgent = class {
 	async chat(message) {
 		const client = this.client ?? this.createBuiltinClient();
 		let systemPrompt = this.customSystemPrompt ?? buildSystemPrompt({ tools: this.registry.getDefinitions() });
+		const refStore = new RefStore(globalThis.location?.href);
+		setActiveRefStore(refStore);
 		if (this.autoSnapshot) try {
 			const snapshot = generateSnapshot(document.body, {
 				maxDepth: 8,
-				...this.snapshotOptions
+				...this.snapshotOptions,
+				refStore
 			});
 			this.callbacks.onSnapshot?.(snapshot);
-			systemPrompt += [
-				"\n\n## 当前页面 DOM 快照（实时生成）\n",
-				"每个元素末尾的 ref=\"...\" 是基于层级位置生成的唯一路径。",
-				"操作元素时，必须使用 ref 路径作为 selector 参数（如 /body/main/form/input）。\n",
-				"```",
-				snapshot,
-				"```\n",
-				"## 操作规则\n",
-				"1. 从快照中找到目标元素，复制其 ref 路径。",
-				"2. 将 ref 路径作为 dom 工具的 selector 参数传入。",
-				"3. 禁止猜测 CSS 选择器（如 \"button\"、\"#send\"），必须使用快照中的 ref。",
-				"4. 如果快照中看不到目标元素，先滚动页面或调整 maxDepth 获取更深的快照。",
-				"5. 先规划操作步骤，再按顺序逐步执行。",
-				"6. **语义选择**：当页面存在多个文本相同的元素时，严禁随意选择。必须根据 ref 路径的父级结构、周围兄弟元素、所在功能区域来判断哪个才是用户意图中的目标。例如聊天区的\"发送\"和表单的\"提交\"是不同功能，要结合用户当前操作的上下文来选择正确的元素。"
-			].join("\n");
+			systemPrompt += `\n\n## 当前页面 DOM 快照\n\n\`\`\`\n${snapshot}\n\`\`\``;
 		} catch {}
+		const wrappedCallbacks = {
+			...this.callbacks,
+			onBeforeRecoverySnapshot: (newUrl) => {
+				if (newUrl !== void 0) refStore.reset(newUrl);
+				else refStore.clear();
+				this.callbacks.onBeforeRecoverySnapshot?.(newUrl);
+			}
+		};
 		const result = await executeAgentLoop({
 			client,
 			registry: this.registry,
@@ -1961,9 +2043,11 @@ var WebAgent = class {
 			history: this.memory ? this.history : void 0,
 			dryRun: this.dryRun,
 			maxRounds: this.maxRounds,
-			callbacks: this.callbacks
+			callbacks: wrappedCallbacks
 		});
 		if (this.memory) this.history = result.messages;
+		refStore.clear();
+		setActiveRefStore(void 0);
 		return result;
 	}
 	/**