dsh-browser-view 0.7.2 → 0.7.4

package/lib/index.js

@@ -572,12 +572,12 @@ function __walkerCore() {
 		}
 		if (el.id) {
 			const t = document.querySelector(`label[for="${CSS.escape(el.id)}"]`)?.textContent?.trim();
-			if (t) return t.slice(0, 60);
+			if (t) return t.replace(/^[*：:\s]+|[*：:\s]+$/g, "").slice(0, 60);
 		}
 		const wrapLabel = el.closest("label");
 		if (wrapLabel) {
 			const t = wrapLabel.textContent?.trim();
-			if (t) return t.slice(0, 60);
+			if (t) return t.replace(/^[*：:\s]+|[*：:\s]+$/g, "").slice(0, 60);
 		}
 		if ([
 			"checkbox",
@@ -587,17 +587,45 @@ function __walkerCore() {
 			const container = el.closest("label, [class*='wrapper'], [class*='item'], li");
 			if (container) {
 				const t = container.textContent?.trim();
-				if (t) return t.replace(/\s+/g, " ").slice(0, 60);
+				if (t) return t.replace(/\s+/g, " ").replace(/^[*：:\s]+|[*：:\s]+$/g, "").slice(0, 60);
 			}
 		}
 		if ([
 			"textbox",
 			"searchbox",
 			"combobox",
-			"spinbutton"
+			"spinbutton",
+			"slider",
+			"listbox"
 		].includes(role)) {
+			const formItem = el.closest("[class*='form-item'], [class*='form__item'], [class*='form-group'], [role='group']");
+			if (formItem) {
+				const lab = formItem.querySelector("label, [class*='form-item-label'], [class*='form-item__label'], [class*='label']");
+				if (lab) {
+					const t = (lab.getAttribute("title") || lab.textContent || "").trim().replace(/^[*：:\s]+|[*：:\s]+$/g, "");
+					if (t) return t.slice(0, 60);
+				}
+			}
+			const selectHost = el.closest("[class*='select'], [class*='cascader'], [class*='picker']");
+			if (selectHost) {
+				const ph = selectHost.querySelector("[class*='placeholder'], [class*='selection-placeholder']")?.textContent?.trim();
+				if (ph) return ph.slice(0, 60);
+				const selVal = selectHost.querySelector("[class*='selection-item'], [class*='selected-value']")?.textContent?.trim();
+				if (selVal) return selVal.slice(0, 60);
+			}
 			const ph = el.getAttribute("placeholder");
 			if (ph && ph.trim()) return ph.trim().slice(0, 60);
+			const host = selectHost || el;
+			const prevEl = host.previousElementSibling;
+			if (prevEl) {
+				const prevText = (prevEl.textContent || "").trim().replace(/^[*：:\s]+|[*：:\s]+$/g, "");
+				if (prevText && prevText.length <= 30) return prevText.slice(0, 60);
+			}
+			const td = host.closest("td");
+			if (td && td.previousElementSibling) {
+				const tdText = (td.previousElementSibling.textContent || "").trim().replace(/^[*：:\s]+|[*：:\s]+$/g, "");
+				if (tdText && tdText.length <= 30) return tdText.slice(0, 60);
+			}
 		}
 		const text = (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ");
 		if (text) return text.slice(0, 60);
@@ -1376,8 +1404,38 @@ async function executeUniversalSelect(ctx) {
 		const options = await withTimeout(target.locator("option").allTextContents(), probe, "读取原生下拉选项").catch(() => []);
 		throw new Error(`原生下拉无选项 "${want}"; 可用选项: ${options.map((t) => t.trim()).join(" / ")}`);
 	}
-	const hostLocator = target.locator("xpath=ancestor-or-self::*[@role='combobox' or contains(@class, 'select') or contains(@class, 'selector')][last()]");
-	const actualTarget = await hostLocator.count().catch(() => 0) > 0 ? hostLocator.first() : target;
+	let resolvedTarget = target;
+	if (await withTimeout(target.evaluate((el) => {
+		if (el.tagName.toLowerCase() === "label") return true;
+		const cls = typeof el.className === "string" ? el.className : "";
+		if (/(?:form-item|form__item|form-group)/i.test(cls)) return true;
+		if (el.closest("label, [class*='form-item'], [class*='form__item'], [class*='form-group']")) return !el.matches("[role='combobox'], select, [class*='select-selector']");
+		if (!el.matches("[role='combobox'], select, [class*='select'], [class*='selector']")) return true;
+		return false;
+	}), 1500, "探测 label 或非标文本容器").catch(() => false)) {
+		const descendantSelect = target.locator("xpath=.//*[@role='combobox' or self::select or contains(@class, 'select-selector') or contains(@class, 'select')][not(self::label)]").first();
+		if (await descendantSelect.count().catch(() => 0) > 0) resolvedTarget = descendantSelect;
+		else {
+			const forId = await target.getAttribute("for").catch(() => null);
+			if (forId) {
+				const forTarget = page.locator(`[id="${forId.replace(/"/g, "\\\"")}"]`).first();
+				if (await forTarget.count().catch(() => 0) > 0) resolvedTarget = forTarget;
+			} else {
+				const nextSiblingSelect = target.locator("xpath=following-sibling::*[self::select or @role='combobox' or contains(@class, 'select') or contains(@class, 'selector')][1] | following-sibling::*[1]//*[@role='combobox' or self::select or contains(@class, 'select')]").first();
+				if (await nextSiblingSelect.count().catch(() => 0) > 0) resolvedTarget = nextSiblingSelect;
+				else {
+					const tdSiblingSelect = target.locator("xpath=ancestor-or-self::td[1]/following-sibling::td[1]//*[@role='combobox' or self::select or contains(@class, 'select')]").first();
+					if (await tdSiblingSelect.count().catch(() => 0) > 0) resolvedTarget = tdSiblingSelect;
+					else {
+						const siblingSelect = target.locator("xpath=ancestor-or-self::*[contains(@class, 'form-item') or contains(@class, 'form__item') or contains(@class, 'form-group')][1]//*[@role='combobox' or self::select or contains(@class, 'select-selector') or contains(@class, 'select')][not(self::label)] | ..//*[@role='combobox' or self::select or contains(@class, 'select-selector') or contains(@class, 'select')][not(self::label)]").first();
+						if (await siblingSelect.count().catch(() => 0) > 0) resolvedTarget = siblingSelect;
+					}
+				}
+			}
+		}
+	}
+	const hostLocator = resolvedTarget.locator("xpath=ancestor-or-self::*[@role='combobox' or contains(@class, 'select') or contains(@class, 'selector')][last()]");
+	const actualTarget = await hostLocator.count().catch(() => 0) > 0 ? hostLocator.first() : resolvedTarget;
 	if (clear) try {
 		const clearBtn = actualTarget.locator("[class*='clear'], [aria-label*='clear']").first();
 		if (await clearBtn.count().catch(() => 0) > 0 && await clearBtn.isVisible().catch(() => false)) await clearBtn.click({ timeout: 1e3 }).catch(() => {});
@@ -1430,13 +1488,17 @@ async function executeUniversalSelect(ctx) {
 	const optionSelector = "[role='option']:not([style*='height: 0px']):not([class*='empty']), [class*='item-option']:not([class*='empty']), [class*='select-dropdown'] li:not([class*='empty'])";
 	const dropdownSelector = "[role='listbox']:not([style*='display: none']), [class*='select-dropdown']:not([style*='display: none']):not([class*='hidden']), [class*='popper']:not([style*='display: none'])";
 	let options;
+	let targetDropdown = null;
 	if (controlsId) {
 		const parentDropdown = page.locator(`xpath=//*[@id='${controlsId}']/ancestor-or-self::*[contains(@class, 'dropdown') or contains(@class, 'popper') or @role='listbox'][1] | //*[contains(@class, 'dropdown') or @role='listbox'][.//*[@id='${controlsId}']]`);
+		targetDropdown = parentDropdown.first();
 		const visual = parentDropdown.locator(optionSelector).locator("visible=true");
 		options = await visual.count().catch(() => 0) > 0 ? visual : parentDropdown.locator(optionSelector);
 	} else {
-		const activeDropdowns = page.locator(dropdownSelector);
-		const dropdown = await activeDropdowns.count().catch(() => 0) > 1 ? activeDropdowns.last() : activeDropdowns.first();
+		const activeVisualDropdowns = page.locator(dropdownSelector).locator("visible=true");
+		const visualCount = await activeVisualDropdowns.count().catch(() => 0);
+		const dropdown = visualCount > 1 ? activeVisualDropdowns.last() : visualCount === 1 ? activeVisualDropdowns.first() : page.locator(dropdownSelector).last();
+		targetDropdown = dropdown;
 		const visual = dropdown.locator(optionSelector).locator("visible=true");
 		options = await visual.count().catch(() => 0) > 0 ? visual : dropdown.locator(optionSelector);
 	}
@@ -1452,7 +1514,7 @@ async function executeUniversalSelect(ctx) {
 		};
 	})).catch(() => [])).map((e) => e.text || e.title || e.aria).filter(Boolean);
 	if (visibleTexts.length === 0) {
-		const isEmpty = await page.locator("[class*='empty'], [class*='no-data'], [role='status'], [class*='item-empty']").first().isVisible().catch(() => false);
+		const isEmpty = targetDropdown !== null ? await targetDropdown.locator("[class*='empty'], [class*='no-data'], [role='status'], [class*='item-empty']").first().isVisible().catch(() => false) : false;
 		await actualTarget.click({ timeout: 1e3 }).catch(() => {});
 		if (isEmpty) throw new Error(`下拉浮层当前无选项(数据为空态/无可选数据): ${label}`);
 		throw new Error(`点击 ${label} 后未出现下拉选项(选项列表为空态)`);
@@ -1761,6 +1823,7 @@ const scanInteractive = injectWalker((payload, w) => {
 			}
 			const hit = payload.exact ? legacyHit : legacyHit || tokens.length > 0 && tokenHit;
 			if (legacyHit && name !== "" && name.toLowerCase() === q) score += 50;
+			if (payload.preferredRoles && payload.preferredRoles.includes(role)) score += 40;
 			scanned += 1;
 			if (name !== "" && candidates.length < 50) candidates.push({
 				role,
@@ -1857,7 +1920,8 @@ async function resolveSemanticTarget(page, what, opts = {}) {
 			exact: opts.exact === true,
 			scope: typeof opts.scope === "string" && opts.scope !== "" ? opts.scope : "",
 			limit: Math.min(Math.max(opts.limit ?? 5, 1), 20),
-			dialogSelector: ACTIVE_DIALOG_SELECTORS
+			dialogSelector: ACTIVE_DIALOG_SELECTORS,
+			preferredRoles: opts.preferredRoles
 		});
 	} catch {
 		return {
@@ -2034,7 +2098,7 @@ function nameSimilar(a, b) {
 * 自动识别 selector 或 ref；若 ref 标记位于子 Frame，自动绑定到对应子 Frame 上下文。
 * 具备路径防漂移校验与 getByRole 自愈降级能力。
 */
-async function resolveTargetLocator(page, args) {
+async function resolveTargetLocator(page, args, opts = {}) {
 	{
 		const present = [];
 		if (args.ref !== void 0 && args.ref !== "") present.push("ref");
@@ -2224,7 +2288,10 @@ async function resolveTargetLocator(page, args) {
 	}
 	const what = args.what;
 	if (typeof what === "string" && what.trim() !== "" && args.selector === void 0 && args.ref === void 0 && args.mark === void 0 && rowPattern === void 0) {
-		const res = await resolveSemanticTarget(page, what, { scope: typeof args.scope === "string" && args.scope !== "" ? args.scope : void 0 });
+		const res = await resolveSemanticTarget(page, what, {
+			scope: typeof args.scope === "string" && args.scope !== "" ? args.scope : void 0,
+			preferredRoles: opts.preferredRoles
+		});
 		if (!("candidates" in res)) return res;
 		for (const role of [
 			"button",
@@ -4261,7 +4328,11 @@ async function clickTool(config, args, exec) {
 }
 async function typeTool(config, args) {
 	const page = await getPage(config);
-	const targetRes = await resolveTargetLocator(page, args);
+	const targetRes = await resolveTargetLocator(page, args, { preferredRoles: [
+		"textbox",
+		"searchbox",
+		"spinbutton"
+	] });
 	const target = targetRes.locator;
 	const strictErr = strictReject(args, targetRes);
 	if (strictErr !== null) throw strictErr;
@@ -4352,7 +4423,11 @@ async function pressTool(config, args) {
 */
 async function selectTool(config, args) {
 	const page = await getPage(config);
-	const targetRes = await resolveTargetLocator(page, args);
+	const targetRes = await resolveTargetLocator(page, args, { preferredRoles: [
+		"combobox",
+		"select",
+		"listbox"
+	] });
 	const target = targetRes.locator;
 	const strictErr = strictReject(args, targetRes);
 	if (strictErr !== null) throw strictErr;
@@ -5308,25 +5383,187 @@ function previewHighlight(page, selector, label) {
 	}).catch(() => {});
 }
 /**
+* 常见认证/登录相关的 URL 特征正则，用于防止跳板页提前误判。
+*/
+const AUTH_URL_PATTERN = /login|signin|sign-in|oauth|passport|sso|cas|challenge|captcha|verify|auth\b/i;
+/**
+* 等待人工登录底层执行(独立导出供测试注入 fake page)。
+* 协同机制:
+* 1. 挂起等待期间置入 instruction 至实时画面面板(setPauseInstruction),结束后统一清理;
+* 2. 存活标签感知:感知 context 内所有存活页面,原标签关闭时自动迁移至存活页,新标签出现时通知外层注册;
+* 3. 稳态判定:
+*    - 显式 successSelector / successUrl 优先;
+*    - 缺省时,检测 URL 离开登录页(非 AUTH_URL_PATTERN)、登录密码框消除、或 SPA 内容签名稳态变化,防范跳板页误判与 SPA 弹窗漏判。
+*/
+async function runWaitForLoginOnPage(initialPage, args, onNewPageDetected) {
+	const instruction = typeof args.instruction === "string" && args.instruction.trim() ? args.instruction.trim() : "请在浏览器窗口中完成登录";
+	const timeoutMs = Math.min(Math.max(Number(args.timeoutMs ?? 12e4) || 12e4, 1e3), 6e5);
+	const pollIntervalMs = Math.min(Math.max(Number(args.pollIntervalMs ?? 2e3) || 2e3, 100), 5e3);
+	let currentPage = initialPage;
+	let startUrl = "";
+	try {
+		startUrl = initialPage.url();
+	} catch {}
+	const checkHasPassword = async (p) => {
+		try {
+			return await p.evaluate(() => !!document.querySelector("input[type=\"password\"]"));
+		} catch {
+			return false;
+		}
+	};
+	const getPageSig = async (p) => {
+		try {
+			return await p.evaluate(() => {
+				const body = document.body;
+				return `${location.href}|${body ? body.innerText.length : 0}|${document.querySelectorAll("input,button,a").length}`;
+			});
+		} catch {
+			try {
+				return p.url();
+			} catch {
+				return "";
+			}
+		}
+	};
+	const startHasPassword = await checkHasPassword(initialPage);
+	const startSig = args.successSelector || args.successUrl ? "" : await getPageSig(initialPage);
+	const startedAt = Date.now();
+	let loggedIn = false;
+	let detail = `等待登录超时(${timeoutMs}ms)`;
+	setPauseInstruction(instruction);
+	try {
+		const deadline = startedAt + timeoutMs;
+		while (Date.now() < deadline) {
+			let candidatePages = [];
+			try {
+				const context = typeof currentPage.context === "function" ? currentPage.context() : null;
+				if (context && typeof context.pages === "function") candidatePages = context.pages().filter((p) => {
+					try {
+						return !p.isClosed();
+					} catch {
+						return false;
+					}
+				});
+			} catch {}
+			let isCurrentClosed = false;
+			try {
+				isCurrentClosed = currentPage.isClosed();
+			} catch {
+				isCurrentClosed = true;
+			}
+			if (candidatePages.length > 0) {
+				for (const p of candidatePages) if (p !== currentPage && onNewPageDetected) onNewPageDetected(p);
+				if (isCurrentClosed) {
+					currentPage = candidatePages[candidatePages.length - 1];
+					isCurrentClosed = false;
+				}
+			}
+			try {
+				if (args.successSelector) {
+					const targets = candidatePages.length > 0 ? candidatePages : isCurrentClosed ? [] : [currentPage];
+					for (const p of targets) try {
+						if (await p.locator(String(args.successSelector)).first().isVisible()) {
+							loggedIn = true;
+							currentPage = p;
+							detail = `命中 successSelector: ${args.successSelector}`;
+							break;
+						}
+					} catch {}
+				} else if (args.successUrl) {
+					const re = new RegExp(String(args.successUrl));
+					const targets = candidatePages.length > 0 ? candidatePages : isCurrentClosed ? [] : [currentPage];
+					for (const p of targets) try {
+						const u = p.url();
+						if (re.test(u)) {
+							loggedIn = true;
+							currentPage = p;
+							detail = `命中 successUrl: ${args.successUrl}`;
+							break;
+						}
+					} catch {}
+				} else {
+					const target = !isCurrentClosed ? currentPage : candidatePages[0];
+					if (target) {
+						let curUrl = "";
+						try {
+							curUrl = target.url();
+						} catch {}
+						if (curUrl && curUrl !== "about:blank") {
+							if (curUrl !== startUrl) {
+								if (!AUTH_URL_PATTERN.test(curUrl)) {
+									loggedIn = true;
+									currentPage = target;
+									detail = `URL 离开登录页跳转至 ${curUrl}`;
+								} else {
+									const hasPwd = await checkHasPassword(target);
+									if (startHasPassword && !hasPwd) {
+										loggedIn = true;
+										currentPage = target;
+										detail = `登录密码输入框已消除，页面跳转至 ${curUrl}`;
+									}
+								}
+							} else {
+								const hasPwd = await checkHasPassword(target);
+								if (startHasPassword && !hasPwd) {
+									loggedIn = true;
+									currentPage = target;
+									detail = "登录密码输入框已消除(SPA 登录完成)";
+								} else if (await getPageSig(target) !== startSig && (!startHasPassword || !hasPwd)) {
+									loggedIn = true;
+									currentPage = target;
+									detail = "页面内容签名变更(SPA 登录完成)";
+								}
+							}
+						}
+					}
+				}
+			} catch (e) {
+				detail = `检查登录状态出错: ${e instanceof Error ? e.message : String(e)}`;
+			}
+			if (loggedIn) break;
+			try {
+				await currentPage.waitForTimeout(pollIntervalMs);
+			} catch {
+				await sleep$1(pollIntervalMs);
+			}
+		}
+	} finally {
+		clearPauseInstruction();
+	}
+	return {
+		loggedIn,
+		waitedMs: Date.now() - startedAt,
+		detail,
+		targetPage: currentPage
+	};
+}
+/**
 * 等待人工登录完成(配合 headless:false 使用):agent 打开登录页后调用本工具,
-* 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。基于通用条件引擎:
-* successSelector / successUrl 指定完成条件,两者都不给则以 URL 跳转视为完成。
-* 超时返回 loggedIn:false(不抛错)。
+* 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。支持 instruction 提示语
+* 与右下角实时画面面板联动显示横幅,支持多标签感知与 SPA 签名自适应判定。
+* 超时返回 loggedIn:false(附 waitedMs 与 detail,不抛错)。
 */
 async function waitForLoginTool(config, args) {
 	const page = await getPage(config);
-	const startUrl = page.url();
-	let condition;
-	if (args.successSelector) condition = {
-		selector: String(args.successSelector),
-		state: "visible"
-	};
-	else if (args.successUrl) condition = { url: String(args.successUrl) };
-	else condition = { eval: `location.href !== ${JSON.stringify(startUrl)} && location.href !== "about:blank"` };
-	const timeoutMs = Math.min(Math.max(Number(args.timeoutMs ?? 12e4) || 12e4, 5e3), 6e5);
+	const state = stateOf();
+	const result = await runWaitForLoginOnPage(page, args, (newPage) => {
+		if (![...state.pages.values()].includes(newPage)) {
+			attachPage(newPage, profileConfig(config, currentProfile));
+			registerTabPage(state, newPage);
+		}
+	});
+	if (result.targetPage !== page) {
+		for (const [id, p] of state.pages) if (p === result.targetPage) {
+			state.activeId = id;
+			break;
+		}
+	}
+	const identity = await pageIdentity(result.targetPage);
 	return {
-		loggedIn: (await pollCondition(page, condition, timeoutMs, 2e3)).ok,
-		...await pageIdentity(page)
+		loggedIn: result.loggedIn,
+		waitedMs: result.waitedMs,
+		detail: result.detail,
+		...identity
 	};
 }
 /**
@@ -8373,10 +8610,14 @@ function getCollaborationTools(config, timeout, stepImpls) {
 	return [
 		definePlainTool({
 			name: "browser_wait_for_login",
-			description: "等待人工登录完成。agent 在登录页调用本工具后,提示用户在浏览器窗口中完成登录(有头模式 headless:false 时用户可直接操作;配 userDataDir 登录态会持久化)。成功条件三选一:successSelector(登录后出现的元素,如 '#avatar')或 successUrl(登录后 URL 正则,如 'https://\\\\.app\\\\.example\\\\.com')都不给则 URL 发生变化即视为完成。轮询间隔 2 秒,超时返回 loggedIn:false。",
+			description: "等待人工登录完成。agent 在登录页调用本工具后,提示用户在浏览器窗口中完成登录(有头模式 headless:false 时用户可直接操作;配 userDataDir 登录态会持久化)。支持 instruction 提示语(将显示在右下角实时画面面板);成功条件:优先取 successSelector(登录后出现的元素,如 '#avatar')或 successUrl(登录后 URL 正则);两者未指定时,结合 URL 变化、登录特征消除(密码框等)与页面签名稳态综合判定。轮询间隔 2 秒,超时返回 loggedIn:false(附 waitedMs 与 detail)。",
 			parameters: {
 				type: "object",
 				properties: {
+					instruction: {
+						type: "string",
+						description: "可选:给用户看的提示说明(默认「请在浏览器窗口中完成登录」)。"
+					},
 					timeoutMs: {
 						type: "integer",
 						description: "等待上限(毫秒,默认 120000,上限 600000)。"
@@ -8397,11 +8638,15 @@ function getCollaborationTools(config, timeout, stepImpls) {
 				additionalProperties: false,
 				properties: {
 					loggedIn: { type: "boolean" },
+					waitedMs: { type: "integer" },
+					detail: { type: "string" },
 					url: { type: "string" },
 					title: { type: "string" }
 				},
 				required: [
 					"loggedIn",
+					"waitedMs",
+					"detail",
 					"url",
 					"title"
 				]

package/lib/types/browser/session/semantic.d.ts

@@ -35,6 +35,7 @@ export declare const scanInteractive: (payload: {
     scope: string;
     limit: number;
     dialogSelector?: string;
+    preferredRoles?: string[];
 }) => {
     matches: SemanticMatch[];
     candidates: {
@@ -65,6 +66,7 @@ export declare function resolveSemanticTarget(page: Page, what: string, opts?: {
     scope?: string;
     limit?: number;
     maxRefs?: number;
+    preferredRoles?: string[];
 }): Promise<TargetResolution | SemanticMiss>;
 /**
  * 全量可交互元素扫描(SPA ref 重锚定的数据源):返回页面(或 scope 内)全部

package/lib/types/browser/session/target.d.ts

@@ -10,7 +10,9 @@ export declare function buildFlexibleTextPattern(text: string): RegExp;
  * 自动识别 selector 或 ref；若 ref 标记位于子 Frame，自动绑定到对应子 Frame 上下文。
  * 具备路径防漂移校验与 getByRole 自愈降级能力。
  */
-export declare function resolveTargetLocator(page: Page, args: Record<string, any>): Promise<TargetResolution>;
+export declare function resolveTargetLocator(page: Page, args: Record<string, any>, opts?: {
+    preferredRoles?: string[];
+}): Promise<TargetResolution>;
 /** 兼容旧版签名的目标定位快捷方式 */
 export declare function targetLocator(page: Page, args: Record<string, any>): Promise<Locator>;
 //# sourceMappingURL=target.d.ts.map

package/lib/types/browser/tools/collaboration.d.ts

@@ -5,16 +5,38 @@ import type { BrowserConfig } from "../types.js";
  * ~1.5 秒。异步不阻塞(fire-and-forget,任何失败静默),不影响操作时序。
  */
 export declare function previewHighlight(page: Page | null, selector: string, label: string): void;
+/**
+ * 常见认证/登录相关的 URL 特征正则，用于防止跳板页提前误判。
+ */
+export declare const AUTH_URL_PATTERN: RegExp;
+export interface WaitForLoginResult {
+    loggedIn: boolean;
+    waitedMs: number;
+    detail: string;
+    targetPage: Page;
+}
+/**
+ * 等待人工登录底层执行(独立导出供测试注入 fake page)。
+ * 协同机制:
+ * 1. 挂起等待期间置入 instruction 至实时画面面板(setPauseInstruction),结束后统一清理;
+ * 2. 存活标签感知:感知 context 内所有存活页面,原标签关闭时自动迁移至存活页,新标签出现时通知外层注册;
+ * 3. 稳态判定:
+ *    - 显式 successSelector / successUrl 优先;
+ *    - 缺省时,检测 URL 离开登录页(非 AUTH_URL_PATTERN)、登录密码框消除、或 SPA 内容签名稳态变化,防范跳板页误判与 SPA 弹窗漏判。
+ */
+export declare function runWaitForLoginOnPage(initialPage: Page, args: Record<string, any>, onNewPageDetected?: (page: Page) => void): Promise<WaitForLoginResult>;
 /**
  * 等待人工登录完成(配合 headless:false 使用):agent 打开登录页后调用本工具,
- * 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。基于通用条件引擎:
- * successSelector / successUrl 指定完成条件,两者都不给则以 URL 跳转视为完成。
- * 超时返回 loggedIn:false(不抛错)。
+ * 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。支持 instruction 提示语
+ * 与右下角实时画面面板联动显示横幅,支持多标签感知与 SPA 签名自适应判定。
+ * 超时返回 loggedIn:false(附 waitedMs 与 detail,不抛错)。
  */
 export declare function waitForLoginTool(config: BrowserConfig, args: Record<string, any>): Promise<{
     url: string;
     title: string;
     loggedIn: boolean;
+    waitedMs: number;
+    detail: string;
 }>;
 /**
  * 人工接管等待(通用版 wait_for_login):agent 把控制权交还给用户(验证码 /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-view",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "DSH 插件:共享 Playwright 浏览器自动化(38 个 browser_* 工具,含 what 意图语义定位(一次调用替代快照→查找→点击)、SoM 标徽看图点击与零命中截图兜底、SPA ref 软失效重锚定、open Shadow DOM 组合树穿透、跨 Frame/IFrame 定位、视口感知动态快照、批量表单智能填充、点击效果验证与定位失败遥测、Playwright 规范代码导出、批处理、视觉回归、选择器自愈、增量快照)+ 人机协作(面板点选教学 browser_pick_element、人工接管等待、敏感操作审批硬拦截、人机混合录制、面板一键重跑)+ CDP 流式推流、拟人化轨迹与高斯击键、全景时光机、企业富控件矩阵。仅依赖 playwright-core。",
   "type": "module",
   "main": "./lib/index.js",