agentpage 0.0.16 → 0.0.17

package/dist/index.mjs

@@ -73,6 +73,34 @@ function hasToolError(result) {
 *
 * 默认关闭 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/无语义/无交互/无直接文本的布局容器会被“折叠”，
+*   子节点直接提升输出，减少无意义层级。
+* - `maxNodes`：全局节点预算，超限后停止继续遍历并追加 truncation 提示。
+* - `maxChildren`：每个父节点只保留前 N 个子元素，其余用 `... (n children omitted)` 汇总。
+* - `maxTextLength`：节点文本按长度截断，避免长段文案占满上下文。
+* - 交互优先排序：优先输出按钮/输入框/链接等交互元素，再输出普通元素。
+* - 属性压缩：仅保留关键属性（如 id、关键 class、交互属性、布尔状态、val），减少冗余 token。
+*
+* 输入/输出（中）/ I/O contract (EN):
+* - In: `ToolRegistry` + 可选快照参数
+* - Out: 归一化后的快照字符串（始终 string）
+* - Side effects: 无本地状态写入；仅依赖工具调用结果
 */
 async function readPageSnapshot(registry, options) {
 	return toContentString((await registry.dispatch("page_info", {
@@ -85,7 +113,14 @@ async function readPageSnapshot(registry, options) {
 		maxTextLength: options?.maxTextLength ?? 40
 	})).content);
 }
-/** 包裹快照（中）/ Wrap snapshot with boundary markers (EN). */
+/**
+* 包裹快照（中）/ Wrap snapshot with boundary markers (EN).
+*
+* 作用（中）/ Purpose (EN):
+* - 为快照加 `SNAPSHOT_START/END` 边界，便于后续正则定位。
+* - 支持去重与旧快照剥离，防止多轮 token 累积。
+* - 仅做纯字符串变换，不访问外部状态。
+*/
 function wrapSnapshot(snapshot) {
 	return `${SNAPSHOT_START}\n${snapshot}\n${SNAPSHOT_END}`;
 }
@@ -101,6 +136,11 @@ function containsSnapshot(text) {
 }
 /**
 * 剥离旧快照（中）/ Strip outdated snapshot blocks from system prompt (EN).
+*
+* 说明（中）/ Notes (EN):
+* - 当 prompt 中已有历史快照时，将其替换为过期占位文本。
+* - 让每轮真正生效的只有“最新注入快照”，减少冲突上下文。
+* - 这是 prompt 级清理；不会触碰 tool trace 中的原始结果对象。
 */
 function stripSnapshotFromPrompt(prompt) {
 	if (!containsSnapshot(prompt)) return prompt;
@@ -1367,10 +1407,13 @@ function buildSystemPrompt(params = {}) {
 * 替代 Playwright 的 click/fill/type 等操作，直接在页面上下文中执行。
 * 运行环境：浏览器 Content Script。
 *
-* 支持 12 种动作：
+* 支持 15 种动作：
 *   click        — 点击元素
 *   fill         — 填写可编辑控件（input/textarea/select/contenteditable）
 *   select_option — 选择下拉框选项（value/label）
+*   clear        — 清空输入控件
+*   check        — 勾选 checkbox/radio
+*   uncheck      — 取消勾选 checkbox
 *   type         — 逐字符模拟键入
 *   focus        — 聚焦元素
 *   hover        — 鼠标悬停（触发 mouseenter/mouseover）
@@ -1448,16 +1491,62 @@ function resolveWaitMs(params) {
 * 模拟真实用户输入：触发 input、change 事件，兼容 React/Vue 等框架。
 */
 function dispatchInputEvents(el) {
-	el.dispatchEvent(new Event("input", {
-		bubbles: true,
-		cancelable: true
-	}));
+	try {
+		el.dispatchEvent(new InputEvent("input", {
+			bubbles: true,
+			cancelable: true,
+			inputType: "insertText",
+			data: null
+		}));
+	} catch {
+		el.dispatchEvent(new Event("input", {
+			bubbles: true,
+			cancelable: true
+		}));
+	}
 	el.dispatchEvent(new Event("change", {
 		bubbles: true,
 		cancelable: true
 	}));
 }
 /**
+* 使用原生 setter 写入表单值，提升对受控组件（React/Vue 等）的兼容性。
+*/
+function setNativeEditableValue(el, value) {
+	const proto = el instanceof HTMLInputElement ? HTMLInputElement.prototype : el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLSelectElement.prototype;
+	const descriptor = Object.getOwnPropertyDescriptor(proto, "value");
+	if (descriptor?.set) {
+		descriptor.set.call(el, value);
+		return;
+	}
+	el.value = value;
+}
+/**
+* 读取可编辑元素当前值。
+*/
+function getEditableValue(el) {
+	return el.value ?? "";
+}
+/**
+* 将常见 key 映射为更接近浏览器语义的 KeyboardEvent.code。
+*/
+function resolveKeyboardCode(key) {
+	return {
+		Enter: "Enter",
+		Escape: "Escape",
+		Esc: "Escape",
+		Tab: "Tab",
+		Space: "Space",
+		" ": "Space",
+		Backspace: "Backspace",
+		Delete: "Delete",
+		ArrowUp: "ArrowUp",
+		ArrowDown: "ArrowDown",
+		ArrowLeft: "ArrowLeft",
+		ArrowRight: "ArrowRight"
+	}[key] ?? key;
+}
+/**
 * 生成元素的可读描述，用于在操作结果中展示实际命中的 DOM 节点。
 * 格式：<tag#id.class> "文本" [attr=val, ...]
 */
@@ -1465,7 +1554,7 @@ 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 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 [
@@ -1478,30 +1567,135 @@ function describeElement(el) {
 		const val = el.getAttribute(attr);
 		if (val) hints.push(`${attr}=${val}`);
 	}
+	if (el instanceof HTMLSelectElement && el.value) hints.push(`val=${el.value}`);
 	return `<${tag}${id}${cls}>${textHint}${hints.length > 0 ? ` [${hints.join(", ")}]` : ""}`;
 }
+function isElementVisible(el) {
+	if (!(el instanceof HTMLElement || el instanceof SVGElement)) return false;
+	if (!el.isConnected) return false;
+	const style = window.getComputedStyle(el);
+	if (style.display === "none" || style.visibility === "hidden") return false;
+	if (style.opacity === "0") return false;
+	const rect = el.getBoundingClientRect();
+	return rect.width > 0 && rect.height > 0;
+}
+function isElementDisabled(el) {
+	if (!(el instanceof HTMLElement)) return false;
+	if (el.hasAttribute("disabled")) return true;
+	if (el.getAttribute("aria-disabled") === "true") return true;
+	if ("disabled" in el && typeof el.disabled === "boolean") return Boolean(el.disabled);
+	return false;
+}
+function isEditableElement(el) {
+	if (el instanceof HTMLTextAreaElement) return !el.readOnly;
+	if (el instanceof HTMLInputElement) return !new Set([
+		"checkbox",
+		"radio",
+		"file",
+		"button",
+		"submit",
+		"reset"
+	]).has(el.type) && !el.readOnly;
+	if (el instanceof HTMLSelectElement) return true;
+	return el instanceof HTMLElement && el.isContentEditable;
+}
+function ensureActionable(el, action, selector) {
+	if (!el.isConnected) return {
+		content: `"${selector}" 元素已脱离文档，无法执行 ${action}`,
+		details: {
+			error: true,
+			code: "ELEMENT_DETACHED",
+			action,
+			selector
+		}
+	};
+	if (!new Set(["get_text", "get_attr"]).has(action) && !isElementVisible(el)) return {
+		content: `"${selector}" 元素不可见，无法执行 ${action}`,
+		details: {
+			error: true,
+			code: "ELEMENT_NOT_VISIBLE",
+			action,
+			selector
+		}
+	};
+	if (new Set([
+		"click",
+		"fill",
+		"type",
+		"press",
+		"select_option",
+		"clear",
+		"check",
+		"uncheck"
+	]).has(action) && isElementDisabled(el)) return {
+		content: `"${selector}" 元素已禁用，无法执行 ${action}`,
+		details: {
+			error: true,
+			code: "ELEMENT_DISABLED",
+			action,
+			selector
+		}
+	};
+	if ([
+		"fill",
+		"type",
+		"clear"
+	].includes(action) && !isEditableElement(el)) return {
+		content: `"${selector}" 不是可编辑元素，无法执行 ${action}`,
+		details: {
+			error: true,
+			code: "UNSUPPORTED_FILL_TARGET",
+			action,
+			selector
+		}
+	};
+	return null;
+}
+function isOptionCandidateVisible(el) {
+	if (!(el instanceof HTMLElement)) return false;
+	if (!isElementVisible(el)) return false;
+	return (el.textContent?.trim() ?? "").length > 0;
+}
+function findVisibleOptionByText(text) {
+	const target = text.trim().toLowerCase();
+	if (!target) return null;
+	const nodes = Array.from(document.querySelectorAll("[role=\"option\"], .bk-select-option, .bk-option, [data-option], li, option"));
+	for (const node of nodes) {
+		if (!isOptionCandidateVisible(node)) continue;
+		if ((node.textContent?.trim().toLowerCase() ?? "") === target) return node;
+	}
+	for (const node of nodes) {
+		if (!isOptionCandidateVisible(node)) continue;
+		if ((node.textContent?.trim().toLowerCase() ?? "").includes(target)) return node;
+	}
+	return null;
+}
 function createDomTool() {
 	return {
 		name: "dom",
 		description: [
 			"Perform DOM operations on the current page.",
-			"Actions: click, fill, select_option, type, focus, hover, press, get_text, get_attr, set_attr, add_class, remove_class.",
+			"Actions: click, fill, select_option, clear, check, uncheck, type, focus, hover, press, get_text, get_attr, set_attr, add_class, remove_class.",
 			"Use the hash ID from DOM snapshot (e.g. #a1b2c) as selector."
 		].join(" "),
 		schema: Type.Object({
-			action: Type.String({ description: "DOM action: click | fill | select_option | type | focus | hover | press | get_text | get_attr | set_attr | add_class | remove_class" }),
+			action: Type.String({ description: "DOM action: click | fill | select_option | clear | check | uncheck | type | focus | hover | press | get_text | get_attr | set_attr | add_class | remove_class" }),
 			selector: Type.String({ description: "Element ref ID from snapshot (e.g. #r0, #r5) or CSS selector" }),
 			value: Type.Optional(Type.String({ description: "Value for fill/type/set_attr actions" })),
 			key: Type.Optional(Type.String({ description: "Key name for press action (e.g. Enter, Escape, Tab, ArrowDown, ArrowUp, Backspace, Delete, Space)" })),
+			label: Type.Optional(Type.String({ description: "Label text for select_option action (fallback when value is not provided)" })),
+			index: Type.Optional(Type.Number({ description: "0-based option index for select_option action" })),
 			attribute: Type.Optional(Type.String({ description: "Attribute name for get_attr/set_attr actions" })),
 			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." }))
+			waitSeconds: Type.Optional(Type.Number({ description: "Optional wait timeout in seconds before action. Used when waitMs is not provided." })),
+			force: Type.Optional(Type.Boolean({ description: "Skip actionability checks for interaction actions (default false)." }))
 		}),
 		execute: async (params) => {
 			const action = params.action;
 			const selector = params.selector;
 			const waitMs = resolveWaitMs(params);
+			const force = params.force === true;
 			if (!selector) return { content: "缺少 selector 参数" };
 			let el;
 			if (waitMs > 0) {
@@ -1541,6 +1735,10 @@ function createDomTool() {
 				el = elOrError;
 			}
 			try {
+				if (!force) {
+					const checkResult = ensureActionable(el, action, selector);
+					if (checkResult) return checkResult;
+				}
 				switch (action) {
 					case "click":
 						if (el instanceof HTMLOptionElement) {
@@ -1554,6 +1752,22 @@ function createDomTool() {
 						}
 						if (el instanceof HTMLElement) {
 							el.focus();
+							el.dispatchEvent(new PointerEvent("pointerdown", {
+								bubbles: true,
+								cancelable: true
+							}));
+							el.dispatchEvent(new MouseEvent("mousedown", {
+								bubbles: true,
+								cancelable: true
+							}));
+							el.dispatchEvent(new PointerEvent("pointerup", {
+								bubbles: true,
+								cancelable: true
+							}));
+							el.dispatchEvent(new MouseEvent("mouseup", {
+								bubbles: true,
+								cancelable: true
+							}));
 							el.click();
 						} else el.dispatchEvent(new MouseEvent("click", { bubbles: true }));
 						return { content: `已点击 ${describeElement(el)}` };
@@ -1581,22 +1795,58 @@ function createDomTool() {
 						if (el instanceof HTMLElement) el.focus();
 						const eventInit = {
 							key,
-							code: key,
+							code: resolveKeyboardCode(key),
 							bubbles: true,
 							cancelable: true
 						};
-						el.dispatchEvent(new KeyboardEvent("keydown", eventInit));
+						const keydownAllowed = el.dispatchEvent(new KeyboardEvent("keydown", eventInit));
 						el.dispatchEvent(new KeyboardEvent("keypress", eventInit));
 						el.dispatchEvent(new KeyboardEvent("keyup", eventInit));
+						if (keydownAllowed && key === "Enter") {
+							if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) (el.form ?? el.closest("form"))?.dispatchEvent(new Event("submit", {
+								bubbles: true,
+								cancelable: true
+							}));
+						}
 						return { content: `已在 ${describeElement(el)} 上按下 ${key}` };
 					}
 					case "fill": {
 						const value = params.value;
 						if (value === void 0) return { content: "缺少 value 参数" };
 						if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+							if (el instanceof HTMLInputElement) {
+								if (new Set([
+									"checkbox",
+									"radio",
+									"file",
+									"button",
+									"submit",
+									"reset"
+								]).has(el.type)) return {
+									content: `"${selector}" 为 input[type=${el.type}]，不支持 fill；请使用 click/press/select_option 等动作。`,
+									details: {
+										error: true,
+										code: "UNSUPPORTED_FILL_TARGET",
+										action,
+										selector
+									}
+								};
+							}
 							el.focus();
-							el.value = value;
+							setNativeEditableValue(el, value);
 							dispatchInputEvents(el);
+							const actualValue = getEditableValue(el);
+							if (actualValue !== value) return {
+								content: `"${selector}" 填写后值不一致：期望 "${value}"，实际 "${actualValue}"`,
+								details: {
+									error: true,
+									code: "FILL_NOT_APPLIED",
+									action,
+									selector,
+									expected: value,
+									actual: actualValue
+								}
+							};
 						} else if (el instanceof HTMLSelectElement) {
 							el.focus();
 							let matched = false;
@@ -1615,6 +1865,18 @@ function createDomTool() {
 							}
 							if (!matched) return { content: `"${selector}" 下拉框中不存在选项 "${value}"` };
 							dispatchInputEvents(el);
+							const actualValue = getEditableValue(el);
+							if (actualValue !== el.value) return {
+								content: `"${selector}" 下拉框状态异常，未确认写入`,
+								details: {
+									error: true,
+									code: "FILL_NOT_APPLIED",
+									action,
+									selector,
+									expected: value,
+									actual: actualValue
+								}
+							};
 						} else if (el instanceof HTMLElement && el.isContentEditable) {
 							el.focus();
 							el.textContent = value;
@@ -1624,27 +1886,83 @@ function createDomTool() {
 					}
 					case "select_option": {
 						const value = params.value;
-						if (value === void 0) return { content: "缺少 value 参数" };
-						if (!(el instanceof HTMLSelectElement)) return { content: `"${selector}" 不是下拉框元素` };
+						const label = params.label;
+						const index = typeof params.index === "number" ? Math.floor(params.index) : void 0;
+						if (value === void 0 && label === void 0 && index === void 0) return { content: "缺少可选参数：value 或 label 或 index" };
+						if (!(el instanceof HTMLSelectElement)) {
+							if (!(el instanceof HTMLElement)) return { content: `"${selector}" 不是下拉框元素` };
+							el.focus();
+							el.click();
+							const wanted = (label ?? value ?? "").trim();
+							if (!wanted) return { content: `"${selector}" 为自定义下拉时，需提供 value 或 label` };
+							const option = findVisibleOptionByText(wanted);
+							if (!option) return {
+								content: `未找到与 "${wanted}" 匹配的可见下拉选项（自定义下拉）`,
+								details: {
+									error: true,
+									code: "OPTION_NOT_FOUND",
+									action,
+									selector,
+									wanted
+								}
+							};
+							option.click();
+							return { content: `已在自定义下拉中选择 "${wanted}"` };
+						}
 						el.focus();
-						let matched = false;
-						for (const option of Array.from(el.options)) if (option.value === value) {
-							el.value = option.value;
-							matched = true;
-							break;
+						const options = Array.from(el.options);
+						let selectedOption;
+						if (value !== void 0) selectedOption = options.find((option) => option.value === value);
+						if (!selectedOption && label !== void 0) {
+							const normalizedLabel = label.trim().toLowerCase();
+							selectedOption = options.find((option) => option.text.trim().toLowerCase() === normalizedLabel);
 						}
-						if (!matched) {
-							const normalized = value.trim().toLowerCase();
-							for (const option of Array.from(el.options)) if (option.text.trim().toLowerCase() === normalized) {
-								el.value = option.value;
-								matched = true;
-								break;
-							}
+						if (!selectedOption && value !== void 0) {
+							const normalizedValueAsLabel = value.trim().toLowerCase();
+							selectedOption = options.find((option) => option.text.trim().toLowerCase() === normalizedValueAsLabel);
+						}
+						if (!selectedOption && index !== void 0) {
+							if (index < 0 || index >= options.length) return { content: `"${selector}" 下拉框不存在 index=${index} 的选项` };
+							selectedOption = options[index];
 						}
-						if (!matched) return { content: `"${selector}" 下拉框中不存在选项 "${value}"` };
+						if (!selectedOption) return { content: `"${selector}" 下拉框中不存在选项 "${value ?? label ?? `index=${index}`}"` };
+						if (selectedOption.disabled) return { content: `"${selector}" 目标选项已禁用：${selectedOption.value}` };
+						if (!el.multiple) for (const option of options) option.selected = false;
+						selectedOption.selected = true;
+						el.value = selectedOption.value;
 						dispatchInputEvents(el);
-						return { content: `已选择 ${describeElement(el)}: "${el.value}"` };
+						return { content: `已选择 ${describeElement(el)}: value="${selectedOption.value}", label="${selectedOption.text.trim()}"` };
 					}
+					case "clear":
+						if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+							el.focus();
+							setNativeEditableValue(el, "");
+							dispatchInputEvents(el);
+							return { content: `已清空 ${describeElement(el)}` };
+						}
+						if (el instanceof HTMLElement && el.isContentEditable) {
+							el.focus();
+							el.textContent = "";
+							el.dispatchEvent(new Event("input", { bubbles: true }));
+							return { content: `已清空 ${describeElement(el)}` };
+						}
+						return { content: `"${selector}" 不是可清空元素` };
+					case "check":
+						if (!(el instanceof HTMLInputElement) || el.type !== "checkbox" && el.type !== "radio") return { content: `"${selector}" 不是 checkbox/radio` };
+						el.focus();
+						if (!el.checked) {
+							el.checked = true;
+							dispatchInputEvents(el);
+						}
+						return { content: `已勾选 ${describeElement(el)}` };
+					case "uncheck":
+						if (!(el instanceof HTMLInputElement) || el.type !== "checkbox") return { content: `"${selector}" 不是 checkbox` };
+						el.focus();
+						if (el.checked) {
+							el.checked = false;
+							dispatchInputEvents(el);
+						}
+						return { content: `已取消勾选 ${describeElement(el)}` };
 					case "type": {
 						const value = params.value;
 						if (value === void 0) return { content: "缺少 value 参数" };
@@ -1897,6 +2215,12 @@ function generateSnapshot(root = document.body, options = {}) {
 			if (val) attrs.push(`${attr}="${val}"`);
 		}
 		for (const attr of BOOLEAN_ATTRS) if (el.hasAttribute(attr)) attrs.push(attr);
+		if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement || el instanceof HTMLButtonElement) {
+			if (el.disabled && !attrs.includes("disabled")) attrs.push("disabled");
+		}
+		if ((el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) && el.readOnly) {
+			if (!attrs.includes("readonly")) attrs.push("readonly");
+		}
 		if (el.hasAttribute("onclick")) attrs.push("onclick");
 		const testId = el.getAttribute("data-testid") || el.getAttribute("data-test-id");
 		if (testId) attrs.push(`data-testid="${testId.slice(0, 25)}"`);
@@ -1904,6 +2228,13 @@ function generateSnapshot(root = document.body, options = {}) {
 			const currentVal = el.value.slice(0, 40);
 			if (el.getAttribute("value") !== currentVal) attrs.push(`val="${currentVal}"`);
 		}
+		if (el instanceof HTMLInputElement && (el.type === "checkbox" || el.type === "radio") && el.checked) {
+			if (!attrs.includes("checked")) attrs.push("checked");
+		}
+		if (el instanceof HTMLSelectElement && el.value) attrs.push(`val="${el.value.slice(0, 40)}"`);
+		if (el instanceof HTMLOptionElement && el.selected) {
+			if (!attrs.includes("selected")) attrs.push("selected");
+		}
 		let directText = "";
 		for (let i = 0; i < el.childNodes.length; i++) {
 			const node = el.childNodes[i];
@@ -2138,72 +2469,104 @@ function createNavigateTool() {
 * 替代 Playwright 的 waitForSelector/waitForNavigation。
 * 运行环境：浏览器 Content Script。
 *
-* 支持 3 种动作：
+* 支持 4 种动作：
 *   wait_for_selector  — 等待匹配选择器的元素出现
 *   wait_for_hidden    — 等待元素消失或隐藏
 *   wait_for_text      — 等待页面中出现指定文本
+*   wait_for_stable    — 等待 DOM 在一段时间内无变化
 */
 /** 默认超时时间（毫秒） */
 const DEFAULT_TIMEOUT = 1e4;
 /**
-* 通过 MutationObserver 等待元素出现。
-* 先检查元素是否已存在，不存在则监听 DOM 变化直到出现或超时。
+* Playwright 风格可见性判定（近似）。
+*/
+function isVisible(el) {
+	if (!(el instanceof HTMLElement || el instanceof SVGElement)) return false;
+	if (!el.isConnected) return false;
+	const style = window.getComputedStyle(el);
+	if (style.display === "none" || style.visibility === "hidden") return false;
+	if (style.opacity === "0") return false;
+	const rect = el.getBoundingClientRect();
+	return rect.width > 0 && rect.height > 0;
+}
+/**
+* 读取 selector 当前状态。
+*/
+function evaluateSelectorState(selector, state) {
+	const el = document.querySelector(selector) ?? void 0;
+	switch (state) {
+		case "attached": return {
+			matched: Boolean(el),
+			element: el
+		};
+		case "visible": return {
+			matched: Boolean(el && isVisible(el)),
+			element: el
+		};
+		case "hidden": return {
+			matched: !el || !isVisible(el),
+			element: el
+		};
+		case "detached": return {
+			matched: !el,
+			element: el
+		};
+		default: return { matched: false };
+	}
+}
+/**
+* 等待 selector 达到指定状态（近似 Playwright state 语义）。
 */
-function waitForSelector(selector, timeoutMs) {
+function waitForSelectorState(selector, state, timeoutMs) {
 	return new Promise((resolve, reject) => {
-		const existing = document.querySelector(selector);
-		if (existing) {
-			resolve(existing);
-			return;
-		}
-		const timer = setTimeout(() => {
+		let finished = false;
+		const finish = (handler) => {
+			if (finished) return;
+			finished = true;
+			clearTimeout(timer);
+			clearInterval(interval);
 			observer.disconnect();
-			reject(/* @__PURE__ */ new Error(`等待 "${selector}" 超时 (${timeoutMs}ms)`));
-		}, timeoutMs);
-		const observer = new MutationObserver(() => {
-			const el = document.querySelector(selector);
-			if (el) {
-				clearTimeout(timer);
-				observer.disconnect();
-				resolve(el);
+			handler();
+		};
+		const check = () => {
+			let result;
+			try {
+				result = evaluateSelectorState(selector, state);
+			} catch {
+				finish(() => reject(/* @__PURE__ */ new Error(`选择器语法错误: ${selector}`)));
+				return;
 			}
-		});
+			if (result.matched) finish(() => resolve({ element: result.element }));
+		};
+		const timer = setTimeout(() => {
+			finish(() => reject(/* @__PURE__ */ new Error(`等待 "${selector}" 达到状态 "${state}" 超时 (${timeoutMs}ms)`)));
+		}, timeoutMs);
+		const interval = setInterval(check, 80);
+		const observer = new MutationObserver(check);
 		observer.observe(document.body, {
 			childList: true,
 			subtree: true,
-			attributes: true
+			attributes: true,
+			characterData: true
 		});
+		check();
 	});
 }
 /**
-* 等待元素消失或变为不可见。
+* 等待页面中出现指定文本。
 */
-function waitForHidden(selector, timeoutMs) {
+function waitForText(text, timeoutMs) {
 	return new Promise((resolve, reject) => {
-		const existing = document.querySelector(selector);
-		if (!existing) {
-			resolve();
-			return;
-		}
-		const style = window.getComputedStyle(existing);
-		if (style.display === "none" || style.visibility === "hidden") {
+		if (document.body.textContent?.includes(text)) {
 			resolve();
 			return;
 		}
 		const timer = setTimeout(() => {
 			observer.disconnect();
-			reject(/* @__PURE__ */ new Error(`等待 "${selector}" 消失超时 (${timeoutMs}ms)`));
+			reject(/* @__PURE__ */ new Error(`等待文本 "${text}" 出现超时 (${timeoutMs}ms)`));
 		}, timeoutMs);
 		const observer = new MutationObserver(() => {
-			const el = document.querySelector(selector);
-			if (!el) {
-				clearTimeout(timer);
-				observer.disconnect();
-				resolve();
-				return;
-			}
-			const s = window.getComputedStyle(el);
-			if (s.display === "none" || s.visibility === "hidden") {
+			if (document.body.textContent?.includes(text)) {
 				clearTimeout(timer);
 				observer.disconnect();
 				resolve();
@@ -2212,40 +2575,40 @@ function waitForHidden(selector, timeoutMs) {
 		observer.observe(document.body, {
 			childList: true,
 			subtree: true,
-			attributes: true,
-			attributeFilter: [
-				"style",
-				"class",
-				"hidden"
-			]
+			characterData: true
 		});
 	});
 }
 /**
-* 等待页面中出现指定文本。
+* 等待页面进入稳定状态：在 quietMs 时间窗口内没有 DOM 变化。
 */
-function waitForText(text, timeoutMs) {
+function waitForDomStable(timeoutMs, quietMs) {
 	return new Promise((resolve, reject) => {
-		if (document.body.textContent?.includes(text)) {
-			resolve();
-			return;
-		}
-		const timer = setTimeout(() => {
+		const startedAt = Date.now();
+		let lastMutationAt = Date.now();
+		const finish = (ok, err) => {
+			clearInterval(tick);
 			observer.disconnect();
-			reject(/* @__PURE__ */ new Error(`等待文本 "${text}" 出现超时 (${timeoutMs}ms)`));
-		}, timeoutMs);
+			if (ok) resolve();
+			else reject(err ?? /* @__PURE__ */ new Error("等待页面稳定失败"));
+		};
 		const observer = new MutationObserver(() => {
-			if (document.body.textContent?.includes(text)) {
-				clearTimeout(timer);
-				observer.disconnect();
-				resolve();
-			}
+			lastMutationAt = Date.now();
 		});
 		observer.observe(document.body, {
 			childList: true,
 			subtree: true,
+			attributes: true,
 			characterData: true
 		});
+		const tick = setInterval(() => {
+			const now = Date.now();
+			if (now - startedAt > timeoutMs) {
+				finish(false, /* @__PURE__ */ new Error(`等待页面稳定超时 (${timeoutMs}ms)`));
+				return;
+			}
+			if (now - lastMutationAt >= quietMs) finish(true);
+		}, 50);
 	});
 }
 function createWaitTool() {
@@ -2254,13 +2617,15 @@ function createWaitTool() {
 		description: [
 			"Wait for DOM changes on the current page.",
 			"Actions: wait_for_selector (element appears), wait_for_hidden (element disappears),",
-			"wait_for_text (specific text appears in page)."
+			"wait_for_text (specific text appears in page), wait_for_stable (DOM stops changing)."
 		].join(" "),
 		schema: Type.Object({
-			action: Type.String({ description: "Wait action: wait_for_selector | wait_for_hidden | wait_for_text" }),
+			action: Type.String({ description: "Wait action: wait_for_selector | wait_for_hidden | wait_for_text | wait_for_stable" }),
 			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: 10000)" })),
+			quietMs: Type.Optional(Type.Number({ description: "Quiet window for wait_for_stable in milliseconds (default: 300)" }))
 		}),
 		execute: async (params) => {
 			const action = params.action;
@@ -2270,14 +2635,25 @@ function createWaitTool() {
 					case "wait_for_selector": {
 						const selector = params.selector;
 						if (!selector) return { content: "缺少 selector 参数" };
-						await waitForSelector(selector, timeoutMs);
-						return { content: `元素 "${selector}" 已出现` };
+						const state = params.state ?? "attached";
+						if (![
+							"attached",
+							"visible",
+							"hidden",
+							"detached"
+						].includes(state)) return { content: `无效 state: ${state}` };
+						const result = await waitForSelectorState(selector, state, timeoutMs);
+						if (state === "attached" || state === "visible") {
+							const tag = result.element?.tagName?.toLowerCase();
+							return { content: `元素 "${selector}" 已达到状态 "${state}"${tag ? ` (${tag})` : ""}` };
+						}
+						return { content: `元素 "${selector}" 已达到状态 "${state}"` };
 					}
 					case "wait_for_hidden": {
 						const selector = params.selector;
 						if (!selector) return { content: "缺少 selector 参数" };
-						await waitForHidden(selector, timeoutMs);
-						return { content: `元素 "${selector}" 已消失` };
+						await waitForSelectorState(selector, "hidden", timeoutMs);
+						return { content: `元素 "${selector}" 已隐藏或消失` };
 					}
 					case "wait_for_text": {
 						const text = params.text;
@@ -2285,6 +2661,11 @@ function createWaitTool() {
 						await waitForText(text, timeoutMs);
 						return { content: `文本 "${text}" 已出现` };
 					}
+					case "wait_for_stable": {
+						const quietMs = Math.max(50, Math.floor(params.quietMs ?? 300));
+						await waitForDomStable(timeoutMs, quietMs);
+						return { content: `页面已稳定（静默窗口 ${quietMs}ms）` };
+					}
 					default: return { content: `未知的等待动作: ${action}` };
 				}
 			} catch (err) {