dsh-browser-view 0.7.4 → 0.8.0

package/lib/index.js

@@ -47,6 +47,150 @@ function resolveConfig(moduleName, schema, defaults, raw) {
 	return config;
 }
 //#endregion
+//#region lib/types/lib/schema.js
+const BROWSER_CONFIG_SCHEMA = {
+	enabled: {
+		type: "boolean",
+		optional: true
+	},
+	channel: { type: "string" },
+	executablePath: { type: "string" },
+	headless: { type: "boolean" },
+	userDataDir: { type: "string" },
+	profiles: { type: "any" },
+	screenshotDir: { type: "string" },
+	downloadDir: { type: "string" },
+	workspaceDir: { type: "string" },
+	screenshotMaxAgeDays: {
+		type: "number",
+		min: 0
+	},
+	screenshotMaxCount: {
+		type: "number",
+		min: 0
+	},
+	basePath: { type: "string" },
+	recordBodies: { type: "boolean" },
+	maxTextChars: {
+		type: "number",
+		min: 1
+	},
+	maxLinks: {
+		type: "number",
+		min: 1
+	},
+	timeoutMs: {
+		type: "number",
+		min: 1
+	},
+	baselineDir: { type: "string" },
+	selectorHealing: { type: "boolean" },
+	healTimeoutMs: {
+		type: "number",
+		min: 100
+	},
+	maxRefs: {
+		type: "number",
+		min: 1
+	},
+	maxRows: {
+		type: "number",
+		min: 1
+	},
+	snapshotHistory: {
+		type: "number",
+		min: 1,
+		max: 20
+	},
+	confirmMode: {
+		type: "string",
+		enum: [
+			"off",
+			"manual",
+			"auto"
+		]
+	},
+	confirmTimeoutMs: {
+		type: "number",
+		min: 1e3
+	},
+	sensitivePatterns: { type: "string[]" },
+	sensitiveTools: { type: "string[]" },
+	confirmPolicies: {
+		type: "any",
+		optional: true
+	},
+	humanize: {
+		type: "any",
+		optional: true
+	},
+	humanizeSpeed: {
+		type: "string",
+		enum: [
+			"slow",
+			"normal",
+			"fast"
+		],
+		optional: true
+	},
+	confirmInReplay: { type: "boolean" },
+	somFallback: { type: "boolean" },
+	refReanchor: { type: "boolean" },
+	toolset: {
+		type: "string",
+		enum: ["core", "all"]
+	}
+};
+const BROWSER_DEFAULT_CONFIG = {
+	channel: "auto",
+	executablePath: "",
+	headless: false,
+	userDataDir: "",
+	profiles: {},
+	screenshotDir: ".dsh-browser/screenshots",
+	downloadDir: ".dsh-browser/downloads",
+	workspaceDir: "",
+	screenshotMaxAgeDays: 7,
+	screenshotMaxCount: 200,
+	basePath: "/browser",
+	recordBodies: true,
+	maxTextChars: 2e4,
+	maxLinks: 50,
+	timeoutMs: 3e4,
+	baselineDir: ".dsh-browser/baselines",
+	selectorHealing: true,
+	healTimeoutMs: 3e3,
+	maxRefs: 200,
+	maxRows: 1e3,
+	snapshotHistory: 5,
+	confirmMode: "off",
+	confirmTimeoutMs: 6e4,
+	sensitivePatterns: [
+		"提交",
+		"删除",
+		"支付"
+	],
+	sensitiveTools: ["browser_click"],
+	confirmInReplay: true,
+	somFallback: true,
+	refReanchor: true,
+	toolset: "all"
+};
+//#endregion
+//#region lib/types/lib/prompts.js
+const FULL_TOOL_PROMPT = "浏览器工具操作一个共享浏览器会话,支持多标签页与多配置文件。定位操作元素最省事的方式是意图语义定位:browser_click/browser_type/browser_select 直接传 what(元素名称/label,如 what:'登录'),页内打分匹配并自动注册 ref,一次调用替代 快照→查找→点击 三轮;零命中报错会附最相近候选。需要精确控制时再用 selector(CSS)/ref(aria 快照)。打开页面后可先 browser_snapshot 读文本与链接、browser_elements 读表单结构(含关联 label 与展开的下拉选项);browser_find(query 传名称,只返回命中 ref+区域上下文,大页面最省 token;零命中会给相近候选)适合多目标排查,需要全页结构时再用 browser_snapshot { mode: \"aria\" }(可交互元素带 ref=eN,click/type/select/press 直接传 ref 代替 CSS 选择器);下拉选择(原生 select 与 antd/element 组件库)用 browser_select 传 selector/ref/what + option 文本一步完成;固定小序列(点击→等待→输入→提交)用 browser_batch 一次执行减少往返;标签管理用 browser_tabs;下载用 browser_download(wait=true 可等新下载);登录态用 browser_cookies。做自动化测试时:用 browser_wait_for 显式等待页面稳定/元素出现,用 browser_assert 断言(失败自动截图;visual={baseline} 可做视觉回归,先用 browser_screenshot { baseline } 建基线),用 browser_network 检查接口调用与 4xx/5xx,跑完一轮可用 browser_record save 保存操作序列、browser_replay 回放做回归(选择器失效自动按指纹自愈;vars/data 支持参数化与数据驱动)。每次 replay/batch 都记入运行历史,browser_report list/export 可查看与导出回归报告。抓取结构化数据用 browser_extract(fields 定义 CSS 字段,可翻页,可导出 CSV/JSONL)。遇到需要登录的网站:先 browser_open 打开登录页,告知用户请在浏览器窗口中完成登录,再调用 browser_wait_for_login 等待(可给 successSelector/successUrl);验证码/二次确认等更广的「人补一步」场景用 browser_pause_for_human(提示语会显示在实时画面面板);配置 userDataDir 时登录态会持久化。用户可通过界面右下角面板的实时画面查看浏览器。";
+const CORE_TOOL_PROMPT = "浏览器工具操作一个共享浏览器会话(toolset=core:已精简工具集)。定位操作元素最省事的方式是意图语义定位:browser_click/browser_type/browser_select 直接传 what(元素名称/label,如 what:'登录'),一次调用替代快照→查找→点击;零命中报错附最相近候选。需要精确控制时再用 selector/ref:打开页面后用 browser_snapshot 读内容(scope 限定区域、since 增量重读省 token),browser_find(query 传名称,返回 ref),点击/输入/按键/下拉用 browser_click/browser_type/browser_press/browser_select(selector 或 ref);固定小序列用 browser_batch;等待用 browser_wait/browser_wait_for,断言用 browser_assert;接口检查用 browser_network;标签 browser_tabs;下载/上传 browser_download/browser_upload。需要人工:登录用 browser_wait_for_login,验证码/二次确认用 browser_pause_for_human,敏感动作(提交/删除/支付)前用 browser_confirm。环境异常先跑 browser_doctor 诊断。录制/回放/报告/抽取/profile/隔离 context 等工具当前未注册(toolset=core),需要时把配置改为 toolset: all 并重启 DSH。用户可通过界面右下角面板的实时画面查看浏览器。";
+/** confirmMode 附加指引(与 DSH 入口同款语义,manual 面向宿主审批、auto 说明硬闸)。 */
+function confirmGuidanceOf(confirmMode) {
+	if (confirmMode === "manual") return "本环境 confirmMode 为 manual:凡提交/删除/支付等不可逆或影响线上数据的敏感动作,执行前必须先调用 browser_confirm(reason 说明操作与影响,等待用户在实时画面面板点允许/拒绝;拒绝或超时即放弃该动作,不得换路径绕过)。";
+	if (confirmMode === "auto") return "本环境 confirmMode 为 auto:宿主层已在敏感动作(命中敏感模式的目标元素)前强制弹审批卡,agent 无法绕过;审批被拒绝或超时的动作不可换路径重试,应向用户说明并等待指示。";
+	return "";
+}
+/** 组装完整的工具使用指引文本(DSH systemPrompt 段落与 MCP instructions 共用)。 */
+function browserSystemPrompt(config) {
+	return (config.toolset === "core" ? CORE_TOOL_PROMPT : FULL_TOOL_PROMPT) + confirmGuidanceOf(config.confirmMode);
+}
+//#endregion
 //#region lib/types/lib/http.js
 /** Parse the request URL pathname (query strings are ignored). */
 function urlPath(req) {
@@ -397,6 +541,10 @@ function snapshotVersionEntry(cache, version) {
 * 供实时画面面板展示「等待人工操作」提示。
 */
 let pauseState = null;
+let interactivePanelPresent = true;
+function isInteractivePanelPresent() {
+	return interactivePanelPresent;
+}
 function setPauseInstruction(instruction) {
 	pauseState = {
 		instruction,
@@ -2533,24 +2681,43 @@ var ScreencastManager = class {
 	cdp = null;
 	currentPage = null;
 	listeners = /* @__PURE__ */ new Set();
-	isStarting = false;
 	lastFrame = null;
+	/** 期望绑定的页面(syncTo/subscribe 写入);null 表示停流。 */
+	desiredPage = null;
+	/** ensure 单飞标记:在途收敛循环会在每个 await 后重读 desiredPage,吞并并发 syncTo。 */
+	switching = false;
 	/**
 	* 注册帧监听器。返回注销函数。
-	* 当第一个监听器加入时自动激活 CDP Screencast；
-	* 当所有监听器离开时自动注销并停止 CDP，实现零空载开销。
+	* page 为订阅时的初始目标页(由调用方解析)。首个订阅者加入时激活 CDP
+	* Screencast;全部离开时注销并停止 CDP,保持零空载开销。
 	*/
-	subscribe(listener) {
+	subscribe(listener, page) {
 		this.listeners.add(listener);
+		if (page !== void 0) this.desiredPage = page;
 		if (this.lastFrame) try {
 			listener(this.lastFrame);
 		} catch {}
-		if (this.listeners.size === 1) this.start();
+		if (this.listeners.size === 1) this.ensure();
 		return () => {
 			this.listeners.delete(listener);
-			if (this.listeners.size === 0) this.stop();
+			if (this.listeners.size === 0) {
+				this.desiredPage = null;
+				this.ensure();
+			}
 		};
 	}
+	/**
+	* 通知目标页变化(换页重绑 / 置 null 停流)。无订阅者时仅记录意图,
+	* 不建 CDP 会话;快速连续换页由收敛循环合并,最终绑定最后一页。
+	*/
+	async syncTo(page) {
+		this.desiredPage = page;
+		await this.ensure();
+	}
+	/** 停止推流并释放 CDP(closeBrowser 等收尾路径)。 */
+	async stop() {
+		await this.syncTo(null);
+	}
 	get subscriberCount() {
 		return this.listeners.size;
 	}
@@ -2558,26 +2725,54 @@ var ScreencastManager = class {
 		return this.lastFrame;
 	}
 	/**
-	* 启动 CDP Screencast
+	* 收敛循环:让 (cdp, currentPage) 与 (desiredPage, listeners) 达成一致。
+	* 每轮重读 desiredPage —— await 期间到来的新 syncTo 在下一轮被吞并,
+	* 不会因启动中而丢掉换页请求。
 	*/
-	async start(targetPage) {
-		if (this.cdp !== null || this.isStarting) return true;
-		const page = targetPage ?? activePage();
-		if (!page || page.isClosed()) return false;
-		this.isStarting = true;
+	async ensure() {
+		if (this.switching) return;
+		this.switching = true;
 		try {
-			this.currentPage = page;
-			page.once("close", () => {
-				if (this.currentPage === page) this.stop();
-			});
-			const context = page.context();
-			if (typeof context.newCDPSession !== "function") {
-				this.isStarting = false;
-				return false;
+			for (let round = 0; round < 16; round++) {
+				const want = this.desiredPage;
+				if (this.listeners.size === 0 || want === null || want.isClosed()) {
+					if (this.cdp === null) return;
+					await this.teardown();
+					if (this.desiredPage === want) return;
+					continue;
+				}
+				if (this.currentPage === want && this.cdp !== null) return;
+				await this.teardown();
+				if (this.desiredPage !== want) continue;
+				if (!await this.attach(want)) return;
+				if (this.desiredPage !== want) continue;
+				return;
 			}
+		} finally {
+			this.switching = false;
+		}
+	}
+	/** 停掉当前 CDP 会话并清空绑定;lastFrame 一并清空,防新订阅者回放到旧页帧。 */
+	async teardown() {
+		const cdp = this.cdp;
+		this.cdp = null;
+		this.currentPage = null;
+		this.lastFrame = null;
+		if (cdp !== null) try {
+			await cdp.send("Page.stopScreencast").catch(() => {});
+			await cdp.detach().catch(() => {});
+		} catch {}
+	}
+	/** 为页面建立 CDP Screencast 会话;失败(非 Chromium 等)静默降级返回 false。 */
+	async attach(page) {
+		try {
+			const context = page.context();
+			if (typeof context.newCDPSession !== "function") return false;
 			const cdp = await context.newCDPSession(page);
 			this.cdp = cdp;
+			this.currentPage = page;
 			cdp.on("Page.screencastFrame", async (payload) => {
+				if (this.cdp !== cdp) return;
 				try {
 					const frame = {
 						buffer: Buffer.from(payload.data, "base64"),
@@ -2592,34 +2787,29 @@ var ScreencastManager = class {
 					await cdp.send("Page.screencastFrameAck", { sessionId: payload.sessionId }).catch(() => {});
 				} catch {}
 			});
-			await cdp.send("Page.startScreencast", {
-				format: "jpeg",
-				quality: 60,
-				maxWidth: 1280,
-				maxHeight: 800,
-				everyNthFrame: 2
+			try {
+				await cdp.send("Page.startScreencast", {
+					format: "jpeg",
+					quality: 60,
+					maxWidth: 1280,
+					maxHeight: 800,
+					everyNthFrame: 1
+				});
+			} catch (err) {
+				if (this.cdp === cdp) await this.teardown();
+				throw err;
+			}
+			page.once("close", () => {
+				if (this.currentPage === page) {
+					this.desiredPage = null;
+					this.ensure();
+				}
 			});
 			return true;
 		} catch {
-			await this.stop();
 			return false;
-		} finally {
-			this.isStarting = false;
 		}
 	}
-	/**
-	* 停止 CDP Screencast，静默释放资源
-	*/
-	async stop() {
-		const cdp = this.cdp;
-		this.cdp = null;
-		this.currentPage = null;
-		this.isStarting = false;
-		if (cdp !== null) try {
-			await cdp.send("Page.stopScreencast").catch(() => {});
-			await cdp.detach().catch(() => {});
-		} catch {}
-	}
 };
 const screencastManager = new ScreencastManager();
 //#endregion
@@ -2964,6 +3154,12 @@ function pruneClosedPages(state) {
 		if (state.activeId === id) state.activeId = null;
 	}
 }
+/** 实时画面流跟随活动页(推模型:session 层在 activeId 变化点主动通知,
+* screencast 模块不反查本 facade,避免循环依赖)。 */
+function syncScreencast(state) {
+	if (state !== stateOf()) return;
+	screencastManager.syncTo(state.pages.get(state.activeId ?? -1) ?? null);
+}
 /** 把一个已 attach 的页面注册进 profile 标签表并激活,返回分配的 tab id。
 * 唯一注册路径:同时挂 close 监听幂等摘除外部关闭的页(否则僵尸句柄会永久占用
 * activeId,所有工具连报 "Target page...closed" 而 tabs list 仍显示存活)。 */
@@ -2972,11 +3168,13 @@ function registerTabPage(state, page) {
 	state.pages.set(id, page);
 	state.activeId = id;
 	(state.tabMeta ??= /* @__PURE__ */ new Map()).set(id, { createdAt: Date.now() });
+	syncScreencast(state);
 	page.on("close", () => {
 		if (!state.pages.has(id)) return;
 		state.pages.delete(id);
 		state.tabMeta?.delete(id);
 		if (state.activeId === id) state.activeId = null;
+		syncScreencast(state);
 	});
 	return id;
 }
@@ -3087,6 +3285,8 @@ function setLastFormFields(fields) {
 /** 切换当前 profile。 */
 function setCurrentProfile(name) {
 	currentProfile = name;
+	const state = stateOf();
+	screencastManager.syncTo(state.pages.get(state.activeId ?? -1) ?? null);
 }
 //#endregion
 //#region lib/types/browser/tools/navigation.js
@@ -5647,6 +5847,7 @@ async function pauseForHumanTool(config, args) {
 async function confirmTool(config, args) {
 	const reason = typeof args.reason === "string" ? args.reason.trim() : "";
 	if (!reason) throw new Error("缺少 reason: 请说明要执行什么敏感操作、为什么需要审批(如「提交白名单表单,会产生线上数据变更」)");
+	if (!isInteractivePanelPresent()) throw new Error("敏感操作审批失败: 当前环境无前端面板支持人工审批(已按安全策略 fail-closed 拒绝)");
 	const timeoutMs = Math.min(Math.max(Number(args.timeoutMs ?? config.confirmTimeoutMs ?? 6e4) || 6e4, 1e3), 6e5);
 	const id = `cfm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
 	setPendingConfirm({
@@ -5716,6 +5917,14 @@ const describePoint = injectWalker((payload, w) => {
 */
 async function pickToolOnPage(page, config, args) {
 	const instruction = typeof args.instruction === "string" && args.instruction.trim() !== "" ? args.instruction.trim() : "请在实时画面大图上点击要教学的目标元素";
+	if (!isInteractivePanelPresent()) return {
+		picked: false,
+		status: "missed",
+		instruction,
+		detail: "面板点选教学失败: 当前环境无前端面板供用户交互式点选",
+		waitedMs: 0,
+		...await pageIdentity(page)
+	};
 	const timeoutMs = Math.min(Math.max(Number(args.timeoutMs ?? 3e5) || 3e5, 1e3), 6e5);
 	const id = `pick-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
 	const meta = screencastManager.getLastFrame()?.metadata ?? void 0;
@@ -9659,7 +9868,7 @@ function registerBrowserApi(ctx, config, base) {
 								timestamp: frame.timestamp
 							})}\n\n`);
 						} catch {}
-					});
+					}, page);
 					req.on("close", () => {
 						unsubscribe();
 					});
@@ -9677,7 +9886,7 @@ function registerBrowserApi(ctx, config, base) {
 						res.write(frame.buffer);
 						res.write("\r\n");
 					} catch {}
-				});
+				}, page);
 				req.on("close", () => {
 					unsubscribe();
 				});
@@ -9715,136 +9924,8 @@ function registerBrowserApi(ctx, config, base) {
 //#region lib/types/index.js
 const name = "dsh-browser-view";
 const inject = [];
-const SCHEMA = {
-	enabled: {
-		type: "boolean",
-		optional: true
-	},
-	channel: { type: "string" },
-	executablePath: { type: "string" },
-	headless: { type: "boolean" },
-	userDataDir: { type: "string" },
-	profiles: { type: "any" },
-	screenshotDir: { type: "string" },
-	downloadDir: { type: "string" },
-	workspaceDir: { type: "string" },
-	screenshotMaxAgeDays: {
-		type: "number",
-		min: 0
-	},
-	screenshotMaxCount: {
-		type: "number",
-		min: 0
-	},
-	basePath: { type: "string" },
-	recordBodies: { type: "boolean" },
-	maxTextChars: {
-		type: "number",
-		min: 1
-	},
-	maxLinks: {
-		type: "number",
-		min: 1
-	},
-	timeoutMs: {
-		type: "number",
-		min: 1
-	},
-	baselineDir: { type: "string" },
-	selectorHealing: { type: "boolean" },
-	healTimeoutMs: {
-		type: "number",
-		min: 100
-	},
-	maxRefs: {
-		type: "number",
-		min: 1
-	},
-	maxRows: {
-		type: "number",
-		min: 1
-	},
-	snapshotHistory: {
-		type: "number",
-		min: 1,
-		max: 20
-	},
-	confirmMode: {
-		type: "string",
-		enum: [
-			"off",
-			"manual",
-			"auto"
-		]
-	},
-	confirmTimeoutMs: {
-		type: "number",
-		min: 1e3
-	},
-	sensitivePatterns: { type: "string[]" },
-	sensitiveTools: { type: "string[]" },
-	confirmPolicies: {
-		type: "any",
-		optional: true
-	},
-	humanize: {
-		type: "any",
-		optional: true
-	},
-	humanizeSpeed: {
-		type: "string",
-		enum: [
-			"slow",
-			"normal",
-			"fast"
-		],
-		optional: true
-	},
-	confirmInReplay: { type: "boolean" },
-	somFallback: { type: "boolean" },
-	refReanchor: { type: "boolean" },
-	toolset: {
-		type: "string",
-		enum: ["core", "all"]
-	}
-};
-const DEFAULT_CONFIG = {
-	channel: "auto",
-	executablePath: "",
-	headless: false,
-	userDataDir: "",
-	profiles: {},
-	screenshotDir: ".dsh-browser/screenshots",
-	downloadDir: ".dsh-browser/downloads",
-	workspaceDir: "",
-	screenshotMaxAgeDays: 7,
-	screenshotMaxCount: 200,
-	basePath: "/browser",
-	recordBodies: true,
-	maxTextChars: 2e4,
-	maxLinks: 50,
-	timeoutMs: 3e4,
-	baselineDir: ".dsh-browser/baselines",
-	selectorHealing: true,
-	healTimeoutMs: 3e3,
-	maxRefs: 200,
-	maxRows: 1e3,
-	snapshotHistory: 5,
-	confirmMode: "off",
-	confirmTimeoutMs: 6e4,
-	sensitivePatterns: [
-		"提交",
-		"删除",
-		"支付"
-	],
-	sensitiveTools: ["browser_click"],
-	confirmInReplay: true,
-	somFallback: true,
-	refReanchor: true,
-	toolset: "all"
-};
 function apply(ctx, rawConfig) {
-	const resolved = resolveConfig("dsh-browser-view", SCHEMA, DEFAULT_CONFIG, rawConfig);
+	const resolved = resolveConfig("dsh-browser-view", BROWSER_CONFIG_SCHEMA, BROWSER_DEFAULT_CONFIG, rawConfig);
 	if (resolved.enabled === false) return;
 	const config = resolved;
 	const base = (config.basePath ?? "/browser").replace(/\/+$/, "");
@@ -9860,11 +9941,11 @@ function apply(ctx, rawConfig) {
 	const bindPrompt = (promptCtx) => {
 		const systemPrompt = promptCtx.get("systemPrompt") ?? promptCtx.systemPrompt;
 		if (systemPrompt === void 0) return;
-		const confirmGuidance = config.confirmMode === "manual" ? "本环境 confirmMode 为 manual:凡提交/删除/支付等不可逆或影响线上数据的敏感动作,执行前必须先调用 browser_confirm(reason 说明操作与影响,等待用户在实时画面面板点允许/拒绝;拒绝或超时即放弃该动作,不得换路径绕过)。" : config.confirmMode === "auto" ? "本环境 confirmMode 为 auto:宿主层已在敏感动作(命中敏感模式的目标元素)前强制弹审批卡,agent 无法绕过;审批被拒绝或超时的动作不可换路径重试,应向用户说明并等待指示。" : "";
+		const toolPrompt = browserSystemPrompt(config);
 		const sectionDispose = systemPrompt?.section?.({
 			name: "tool:browser",
 			order: 200,
-			text: (config.toolset === "core" ? "浏览器工具操作一个共享浏览器会话(toolset=core:已精简工具集)。定位操作元素最省事的方式是意图语义定位:browser_click/browser_type/browser_select 直接传 what(元素名称/label,如 what:'登录'),一次调用替代快照→查找→点击;零命中报错附最相近候选。需要精确控制时再用 selector/ref:打开页面后用 browser_snapshot 读内容(scope 限定区域、since 增量重读省 token),browser_find(query 传名称,返回 ref),点击/输入/按键/下拉用 browser_click/browser_type/browser_press/browser_select(selector 或 ref);固定小序列用 browser_batch;等待用 browser_wait/browser_wait_for,断言用 browser_assert;接口检查用 browser_network;标签 browser_tabs;下载/上传 browser_download/browser_upload。需要人工:登录用 browser_wait_for_login,验证码/二次确认用 browser_pause_for_human,敏感动作(提交/删除/支付)前用 browser_confirm。环境异常先跑 browser_doctor 诊断。录制/回放/报告/抽取/profile/隔离 context 等工具当前未注册(toolset=core),需要时把配置改为 toolset: all 并重启 DSH。用户可通过界面右下角面板的实时画面查看浏览器。" : "浏览器工具操作一个共享浏览器会话,支持多标签页与多配置文件。定位操作元素最省事的方式是意图语义定位:browser_click/browser_type/browser_select 直接传 what(元素名称/label,如 what:'登录'),页内打分匹配并自动注册 ref,一次调用替代 快照→查找→点击 三轮;零命中报错会附最相近候选。需要精确控制时再用 selector(CSS)/ref(aria 快照)。打开页面后可先 browser_snapshot 读文本与链接、browser_elements 读表单结构(含关联 label 与展开的下拉选项);browser_find(query 传名称,只返回命中 ref+区域上下文,大页面最省 token;零命中会给相近候选)适合多目标排查,需要全页结构时再用 browser_snapshot { mode: \"aria\" }(可交互元素带 ref=eN,click/type/select/press 直接传 ref 代替 CSS 选择器);下拉选择(原生 select 与 antd/element 组件库)用 browser_select 传 selector/ref/what + option 文本一步完成;固定小序列(点击→等待→输入→提交)用 browser_batch 一次执行减少往返;标签管理用 browser_tabs;下载用 browser_download(wait=true 可等新下载);登录态用 browser_cookies。做自动化测试时:用 browser_wait_for 显式等待页面稳定/元素出现,用 browser_assert 断言(失败自动截图;visual={baseline} 可做视觉回归,先用 browser_screenshot { baseline } 建基线),用 browser_network 检查接口调用与 4xx/5xx,跑完一轮可用 browser_record save 保存操作序列、browser_replay 回放做回归(选择器失效自动按指纹自愈;vars/data 支持参数化与数据驱动)。每次 replay/batch 都记入运行历史,browser_report list/export 可查看与导出回归报告。抓取结构化数据用 browser_extract(fields 定义 CSS 字段,可翻页,可导出 CSV/JSONL)。遇到需要登录的网站:先 browser_open 打开登录页,告知用户请在浏览器窗口中完成登录,再调用 browser_wait_for_login 等待(可给 successSelector/successUrl);验证码/二次确认等更广的「人补一步」场景用 browser_pause_for_human(提示语会显示在实时画面面板);配置 userDataDir 时登录态会持久化。用户可通过界面右下角面板的实时画面查看浏览器。") + confirmGuidance
+			text: toolPrompt
 		});
 		if (sectionDispose !== void 0) promptCtx.effect(() => sectionDispose);
 	};