dsh-browser-view 0.2.0 → 0.3.1

package/lib/index.js

@@ -1,5 +1,5 @@
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, appendFileSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 //#region lib/types/lib/config.js
 function typeOf(value) {
@@ -217,6 +217,17 @@ function pageRef(page, ref) {
 function clearPageRefs(page) {
 	refRegistry.delete(page);
 }
+/** 取页面当前完整 ref 表(browser_find 增量续号合并用;无则空 Map)。 */
+function pageRefsOf(page) {
+	return refRegistry.get(page) ?? /* @__PURE__ */ new Map();
+}
+const snapshotCaches = /* @__PURE__ */ new WeakMap();
+function snapshotCacheOf(page) {
+	return snapshotCaches.get(page);
+}
+function setSnapshotCache(page, cache) {
+	snapshotCaches.set(page, cache);
+}
 /** 已保存的录制脚本:name → 步骤数组。 */
 const savedRecordings = /* @__PURE__ */ new Map();
 /** 当前录制中的 buffer(非空 = 录制中)。 */
@@ -256,6 +267,195 @@ function recordCall(call) {
 function testLogOf() {
 	return [...testLog].reverse();
 }
+/**
+* 当前人工接管等待状态(browser_pause_for_human 等待期间非空),
+* 供实时画面面板展示「等待人工操作」提示。
+*/
+let pauseState = null;
+function setPauseInstruction(instruction) {
+	pauseState = {
+		instruction,
+		startedAt: Date.now()
+	};
+}
+function clearPauseInstruction() {
+	pauseState = null;
+}
+function currentPause() {
+	return pauseState;
+}
+let pendingConfirm = null;
+function setPendingConfirm(entry) {
+	pendingConfirm = entry;
+}
+function getPendingConfirm() {
+	return pendingConfirm;
+}
+function clearPendingConfirm() {
+	pendingConfirm = null;
+}
+/** 面板提交审批决策;id 不匹配(已被新审批取代/超时清理)时返回 false。 */
+function resolveConfirm(id, decision) {
+	if (pendingConfirm === null || pendingConfirm.id !== id) return false;
+	pendingConfirm.decision = decision;
+	return true;
+}
+/** window 上的回传 binding 名(须为合法 JS 标识符)。 */
+const HUMAN_BINDING = "__dshBrowserHumanEvent";
+/** 最近一次 agent DOM 操作(点击/输入/选择)的时间戳;用于区分人手与工具回声。 */
+let lastAgentActionAt = 0;
+/** agent 即将/刚刚执行了 DOM 操作(register 包装层调用);1.5s 内的页内事件视为工具回声。 */
+function noteAgentAction() {
+	lastAgentActionAt = Date.now();
+}
+/** 导出供测试:距上次 agent 操作是否在去重窗口内。 */
+function agentActionRecent(now = Date.now(), windowMs = 1500) {
+	return now - lastAgentActionAt < windowMs;
+}
+/**
+* 页内人工操作事件 → 录制步骤(纯函数,导出供测试)。
+* payload 由 installHumanRecorder 生成:{ kind, selector, value?, testid?, role?, name?, id?, text?, tag? }。
+* 无法映射(缺 selector / 未知 kind / 空输入)返回 null。
+*/
+function humanEventToStep(payload) {
+	if (payload === null || typeof payload !== "object") return null;
+	const p = payload;
+	const selector = typeof p.selector === "string" ? p.selector : "";
+	if (!selector) return null;
+	const hint = {
+		...p.testid !== void 0 && p.testid !== "" ? { testid: String(p.testid) } : {},
+		...p.role !== void 0 && p.role !== "" ? { role: String(p.role) } : {},
+		...p.name !== void 0 && p.name !== "" ? { name: String(p.name) } : {},
+		...p.id !== void 0 && p.id !== "" ? { id: String(p.id) } : {},
+		...p.text !== void 0 && p.text !== "" ? { text: String(p.text) } : {},
+		...p.tag !== void 0 && p.tag !== "" ? { tag: String(p.tag) } : {}
+	};
+	if (p.kind === "click") return {
+		tool: "browser_click",
+		args: { selector },
+		meta: {
+			hint,
+			source: "human"
+		}
+	};
+	if (p.kind === "input") {
+		const text = typeof p.value === "string" ? p.value : "";
+		if (text === "") return null;
+		return {
+			tool: "browser_type",
+			args: {
+				selector,
+				text
+			},
+			meta: {
+				hint,
+				source: "human"
+			}
+		};
+	}
+	if (p.kind === "select") {
+		const option = typeof p.value === "string" ? p.value.trim() : "";
+		if (!option) return null;
+		return {
+			tool: "browser_select",
+			args: {
+				selector,
+				option
+			},
+			meta: {
+				hint,
+				source: "human"
+			}
+		};
+	}
+	return null;
+}
+/** binding 回调入站口:仅录制中生效;去重窗口内(agent 工具回声)丢弃。 */
+function handleHumanEvent(payload) {
+	if (!isRecording()) return;
+	if (agentActionRecent()) return;
+	const step = humanEventToStep(payload);
+	if (step === null) return;
+	recordCall({
+		tool: step.tool,
+		args: step.args,
+		ok: true,
+		ms: 0,
+		ts: Date.now(),
+		meta: step.meta,
+		source: "human"
+	});
+}
+/**
+* 页内注入的人工操作监听(addInitScript 序列化;每次导航自动重装)。
+* 监听常驻但 node 侧只在录制中生效,关闭录制等价于"移除"。
+* 只上报可交互元素上的 click 与表单控件的 change,避免逐键噪音。
+*/
+function installHumanRecorder() {
+	const w = window;
+	if (w.__dshHumanRecorder === true) return;
+	w.__dshHumanRecorder = true;
+	const BINDING = "__dshBrowserHumanEvent";
+	const INTERACTIVE = "a,button,input,select,textarea,summary,[role='button'],[role='tab'],[role='menuitem'],[role='option'],[role='switch'],[role='checkbox']";
+	function cssPath(el) {
+		if (el.id) return `#${CSS.escape(el.id)}`;
+		const testid = el.getAttribute("data-testid") ?? el.getAttribute("data-test-id");
+		if (testid) return `[data-testid="${testid.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"]`;
+		const parts = [];
+		let cur = el;
+		while (cur && cur !== document.body && parts.length < 6) {
+			const tag = cur.tagName.toLowerCase();
+			const parent = cur.parentElement;
+			if (!parent) {
+				parts.unshift(tag);
+				break;
+			}
+			const sameTag = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);
+			const idx = sameTag.indexOf(cur) + 1;
+			parts.unshift(sameTag.length > 1 ? `${tag}:nth-of-type(${idx})` : tag);
+			cur = parent;
+		}
+		return parts.join(" > ");
+	}
+	function payloadOf(el, kind, value) {
+		const aria = el.getAttribute("aria-label");
+		return {
+			kind,
+			selector: cssPath(el),
+			...value !== void 0 ? { value } : {},
+			testid: el.getAttribute("data-testid") ?? el.getAttribute("data-test-id") ?? "",
+			role: el.getAttribute("role") ?? "",
+			name: aria && aria.trim() ? aria.trim().slice(0, 40) : "",
+			id: el.id ?? "",
+			text: (el.innerText || el.textContent || "").trim().slice(0, 40),
+			tag: el.tagName.toLowerCase()
+		};
+	}
+	function send(payload) {
+		try {
+			const fn = w[BINDING];
+			if (typeof fn === "function") Promise.resolve(fn(payload)).catch(() => {});
+		} catch {}
+	}
+	document.addEventListener("click", (e) => {
+		const target = e.target instanceof Element ? e.target.closest(INTERACTIVE) : null;
+		if (target === null) return;
+		send(payloadOf(target, "click"));
+	}, true);
+	document.addEventListener("change", (e) => {
+		const t = e.target instanceof Element ? e.target : null;
+		if (t === null) return;
+		if (t.tagName === "SELECT") {
+			const opt = t.selectedOptions[0];
+			send(payloadOf(t, "select", (opt ? opt.textContent : "").trim()));
+		} else if (t.tagName === "INPUT" || t.tagName === "TEXTAREA") {
+			const type = (t.getAttribute("type") ?? "text").toLowerCase();
+			if (type === "checkbox" || type === "radio") return;
+			if (type === "file") return;
+			send(payloadOf(t, "input", t.value));
+		}
+	}, true);
+}
 const networkByProfile = /* @__PURE__ */ new Map();
 function networkOf(name) {
 	let list = networkByProfile.get(name);
@@ -419,6 +619,10 @@ function attachPage(page, config) {
 			durationMs: Date.now() - info.startedAt
 		});
 	});
+	page.exposeBinding(HUMAN_BINDING, (_source, payload) => {
+		handleHumanEvent(payload);
+		return null;
+	}).then(() => page.addInitScript(installHumanRecorder)).then(() => page.evaluate(installHumanRecorder).catch(() => {})).catch(() => {});
 }
 async function loadPlaywright() {
 	try {
@@ -485,6 +689,17 @@ async function launchProfile(name, config) {
 function stateOf() {
 	return getProfileState(currentProfile);
 }
+const namedContexts = /* @__PURE__ */ new Map();
+function namedContextsOf() {
+	return namedContexts;
+}
+/** 把一个已 attach 的页面注册进 profile 标签表并激活,返回分配的 tab id。 */
+function registerTabPage(state, page) {
+	const id = state.counter++;
+	state.pages.set(id, page);
+	state.activeId = id;
+	return id;
+}
 /** 新建一个页面(当前 profile 会话未启动时先启动)。 */
 async function newPage(config) {
 	const state = stateOf();
@@ -541,6 +756,7 @@ async function tabList() {
 	return tabs;
 }
 async function closeBrowser() {
+	namedContexts.clear();
 	for (const [name, state] of profileStates) {
 		const { browser, context } = state;
 		state.browser = null;
@@ -1063,7 +1279,7 @@ function compressText(text) {
 * 可交互元素分配 ref=e1..eN 并附稳定 CSS 路径;无语义容器(div/span)穿透。
 * 输出形如 `- button "登录" [ref=e3]` 的缩进树,供纯文本模型定位操作目标。
 */
-function buildAriaTree(maxRefs) {
+function buildAriaTree(payload) {
 	const INTERACTIVE = /* @__PURE__ */ new Set([
 		"link",
 		"button",
@@ -1225,7 +1441,7 @@ function buildAriaTree(maxRefs) {
 		if (INTERACTIVE.has(role)) {
 			if (!isVisible(el)) return;
 			const name = nameOf(el, role);
-			const ref = refs.length < maxRefs ? `e${refs.length + 1}` : "";
+			const ref = refs.length < payload.maxRefs ? `e${refs.length + 1}` : "";
 			if (ref !== "") refs.push({
 				ref,
 				role,
@@ -1247,51 +1463,447 @@ function buildAriaTree(maxRefs) {
 		}
 		for (const c of Array.from(el.children)) if (!SKIP_TAGS.has(c.tagName.toLowerCase())) walk(c, depth);
 	}
-	if (document.body) walk(document.body, 0);
+	if (document.body === null) return {
+		tree: "",
+		refs,
+		truncated: false,
+		scopeMissing: false
+	};
+	const root = payload.scope ? document.querySelector(payload.scope) : document.body;
+	if (root === null) return {
+		tree: "",
+		refs,
+		truncated: false,
+		scopeMissing: true
+	};
+	walk(root, 0);
 	return {
 		tree: lines.join("\n"),
 		refs,
+		truncated,
+		scopeMissing: false
+	};
+}
+/**
+* 页内语义查找:只收集匹配 query 的可交互元素(不构建全量树)。
+* role/name/cssPath/isVisible 与 buildAriaTree 保持同一套语义(此处内联副本,
+* evaluate 序列化不允许闭包引用);改动任一处时同步另一处。
+*/
+function findInteractive(payload) {
+	const INTERACTIVE = /* @__PURE__ */ new Set([
+		"link",
+		"button",
+		"textbox",
+		"checkbox",
+		"radio",
+		"combobox",
+		"listbox",
+		"searchbox",
+		"slider",
+		"spinbutton",
+		"switch",
+		"tab",
+		"menuitem",
+		"option",
+		"treeitem"
+	]);
+	const STRUCTURAL = /* @__PURE__ */ new Set([
+		"navigation",
+		"main",
+		"banner",
+		"contentinfo",
+		"form",
+		"search",
+		"complementary",
+		"region",
+		"dialog",
+		"alert",
+		"table",
+		"list",
+		"heading",
+		"toolbar",
+		"menu",
+		"menubar",
+		"tablist",
+		"tree",
+		"grid"
+	]);
+	const SKIP_TAGS = /* @__PURE__ */ new Set([
+		"script",
+		"style",
+		"template",
+		"noscript",
+		"svg",
+		"path",
+		"link",
+		"meta",
+		"br"
+	]);
+	function roleOf(el) {
+		const explicit = el.getAttribute("role");
+		if (explicit) return explicit.trim().split(/\s+/)[0] ?? "";
+		switch (el.tagName.toLowerCase()) {
+			case "a": return el.hasAttribute("href") ? "link" : "";
+			case "button": return "button";
+			case "input": {
+				const t = (el.getAttribute("type") ?? "text").toLowerCase();
+				if (t === "checkbox") return "checkbox";
+				if (t === "radio") return "radio";
+				if (t === "range") return "slider";
+				if (t === "number") return "spinbutton";
+				if (t === "search") return "searchbox";
+				if ([
+					"button",
+					"submit",
+					"reset",
+					"image"
+				].includes(t)) return "button";
+				if (["hidden", "file"].includes(t)) return "";
+				return "textbox";
+			}
+			case "textarea": return "textbox";
+			case "select": return "combobox";
+			case "summary": return "button";
+			default: return "";
+		}
+	}
+	function nameOf(el, role) {
+		const aria = el.getAttribute("aria-label");
+		if (aria && aria.trim()) return aria.trim().slice(0, 60);
+		const labelledby = el.getAttribute("aria-labelledby");
+		if (labelledby) {
+			const t = labelledby.split(/\s+/).map((id) => document.getElementById(id)?.textContent?.trim() ?? "").join(" ").trim();
+			if (t) return t.slice(0, 60);
+		}
+		if (el.id) {
+			const t = document.querySelector(`label[for="${CSS.escape(el.id)}"]`)?.textContent?.trim();
+			if (t) return t.slice(0, 60);
+		}
+		if ([
+			"textbox",
+			"searchbox",
+			"combobox",
+			"spinbutton"
+		].includes(role)) {
+			const ph = el.getAttribute("placeholder");
+			if (ph && ph.trim()) return ph.trim().slice(0, 60);
+		}
+		const text = (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ");
+		if (text) return text.slice(0, 60);
+		const title = el.getAttribute("title");
+		if (title && title.trim()) return title.trim().slice(0, 60);
+		return "";
+	}
+	function cssPath(el) {
+		if (el.id) return `#${CSS.escape(el.id)}`;
+		const testid = el.getAttribute("data-testid") ?? el.getAttribute("data-test-id");
+		if (testid) return `[data-testid="${testid.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"]`;
+		const parts = [];
+		let cur = el;
+		while (cur && cur !== document.body && parts.length < 6) {
+			const tag = cur.tagName.toLowerCase();
+			const parent = cur.parentElement;
+			if (!parent) {
+				parts.unshift(tag);
+				break;
+			}
+			const sameTag = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);
+			const idx = sameTag.indexOf(cur) + 1;
+			parts.unshift(sameTag.length > 1 ? `${tag}:nth-of-type(${idx})` : tag);
+			cur = parent;
+		}
+		return parts.join(" > ");
+	}
+	function isVisible(el) {
+		if (el.getAttribute("aria-hidden") === "true") return false;
+		const rect = el.getBoundingClientRect();
+		if (rect.width === 0 && rect.height === 0) return false;
+		const style = getComputedStyle(el);
+		return style.visibility !== "hidden" && style.display !== "none";
+	}
+	/** 最近的结构化祖先(区域上下文,帮助区分多命中)。 */
+	function ancestorsOf(el) {
+		const out = [];
+		let cur = el.parentElement;
+		while (cur && cur !== document.body && out.length < 3) {
+			const role = roleOf(cur);
+			if (STRUCTURAL.has(role)) {
+				const name = nameOf(cur, role);
+				out.push(name !== "" ? `${role} "${name.replace(/"/g, "'")}"` : role);
+			}
+			cur = cur.parentElement;
+		}
+		return out;
+	}
+	const q = payload.query.trim().toLowerCase();
+	const matches = [];
+	const candidates = [];
+	let scanned = 0;
+	const root = payload.scope ? document.querySelector(payload.scope) : document.body;
+	if (root === null) return {
+		matches: [],
+		candidates,
+		scanned: 0
+	};
+	const stack = [root];
+	while (stack.length > 0) {
+		const el = stack.pop();
+		const role = roleOf(el);
+		if (INTERACTIVE.has(role)) {
+			if (!isVisible(el)) continue;
+			const name = nameOf(el, role);
+			const idOrTestid = el.id || el.getAttribute("data-testid") || "";
+			let hit = false;
+			if (name !== "") {
+				const n = name.toLowerCase();
+				hit = payload.exact ? n === q : n.includes(q);
+			}
+			if (!hit && idOrTestid !== "" && idOrTestid.toLowerCase() === q) hit = true;
+			scanned += 1;
+			if (name !== "" && candidates.length < 50) candidates.push({
+				role,
+				name
+			});
+			if (hit && matches.length < payload.limit) matches.push({
+				role,
+				name,
+				selector: cssPath(el),
+				ancestors: ancestorsOf(el)
+			});
+			continue;
+		}
+		for (const c of Array.from(el.children)) if (!SKIP_TAGS.has(c.tagName.toLowerCase())) stack.push(c);
+	}
+	return {
+		matches,
+		candidates,
+		scanned
+	};
+}
+/** 最长公共子串长度(小写比较;零依赖,导出供测试)。 */
+function lcsScore(a, b) {
+	const x = a.toLowerCase();
+	const y = b.toLowerCase();
+	if (x === "" || y === "") return 0;
+	let best = 0;
+	const prev = new Array(y.length + 1).fill(0);
+	for (let i = 1; i <= x.length; i++) {
+		let diag = 0;
+		for (let j = 1; j <= y.length; j++) {
+			const tmp = prev[j];
+			prev[j] = x[i - 1] === y[j - 1] ? diag + 1 : 0;
+			if (prev[j] > best) best = prev[j];
+			diag = tmp;
+		}
+	}
+	return best;
+}
+/** 零命中时按相似度挑 top5 候选(导出供测试)。 */
+function topSuggestions(query, candidates, count = 5) {
+	const min = query.trim().length <= 3 ? 1 : 2;
+	return candidates.map((c) => ({
+		...c,
+		score: lcsScore(query, c.name)
+	})).filter((c) => c.score >= min).sort((a, b) => b.score - a.score).slice(0, count).map(({ role, name, score }) => ({
+		role,
+		name,
+		score
+	}));
+}
+/**
+* 为命中元素增量分配 ref:沿用既有注册表的编号继续(不与上次快照冲突),
+* 合并写回;返回带 ref 的命中列表(上限 maxRefs,超出标 truncated)。
+* 导出供测试(纯逻辑,不依赖浏览器)。
+*/
+function assignRefs(existing, matches, maxRefs) {
+	let next = 0;
+	for (const key of existing.keys()) {
+		const n = Number(key.replace(/^e/, ""));
+		if (Number.isFinite(n) && n > next) next = n;
+	}
+	const merged = new Map(existing);
+	const withRefs = [];
+	let truncated = false;
+	for (const m of matches) {
+		if (merged.size >= maxRefs) {
+			truncated = true;
+			break;
+		}
+		next += 1;
+		const ref = `e${next}`;
+		merged.set(ref, {
+			role: m.role,
+			name: m.name,
+			selector: m.selector
+		});
+		withRefs.push({
+			ref,
+			...m
+		});
+	}
+	return {
+		withRefs,
+		merged,
 		truncated
 	};
 }
+/**
+* 语义元素定位:按名称(或 id/data-testid)在可交互元素中查找,只返回命中的
+* ref + 区域上下文,不输出全量 aria 树 —— 大页面定位单个目标时 token 开销
+* 远小于 browser_snapshot { mode: "aria" }。返回的 ref 可直接用于
+* click/type/select/press。零命中不抛错,附最相近候选供二次定位。
+*/
+async function findTool(config, args) {
+	const query = typeof args.query === "string" ? args.query.trim() : "";
+	if (!query) throw new Error("缺少 query: 要找的元素名称(如「提交」「登录」,或 id/data-testid)");
+	const page = await getPage(config);
+	const maxRefs = Math.min(Math.max(Number(args.maxRefs ?? config.maxRefs ?? 200) || 200, 1), 500);
+	const data = await page.evaluate(findInteractive, {
+		query,
+		exact: args.exact === true,
+		scope: typeof args.scope === "string" && args.scope ? args.scope : "",
+		limit: 20
+	});
+	const { withRefs, merged, truncated } = assignRefs(pageRefsOf(page), data.matches, maxRefs);
+	setPageRefs(page, merged);
+	const suggestions = withRefs.length === 0 ? topSuggestions(query, data.candidates) : [];
+	return {
+		found: withRefs.length,
+		matches: withRefs.slice(0, 10).map(({ ref, role, name, ancestors }) => ({
+			ref,
+			role,
+			name,
+			ancestors
+		})),
+		...suggestions.length > 0 ? { suggestions } : {},
+		...truncated ? { truncated } : {},
+		scanned: data.scanned,
+		url: page.url(),
+		title: await page.title()
+	};
+}
+/**
+* 行级 diff:掐掉公共前缀/后缀,返回变化区。导出供测试。
+* 全等返回 { unchanged: true };否则 changedFrom 为新文本中变化区首行(1 起)。
+*/
+function diffLines(oldText, newText) {
+	const a = oldText === "" ? [] : oldText.split("\n");
+	const b = newText === "" ? [] : newText.split("\n");
+	let i = 0;
+	while (i < a.length && i < b.length && a[i] === b[i]) i += 1;
+	if (i === a.length && i === b.length) return { unchanged: true };
+	let j = 0;
+	while (j < a.length - i && j < b.length - i && a[a.length - 1 - j] === b[b.length - 1 - j]) j += 1;
+	return {
+		unchanged: false,
+		changedFrom: i + 1,
+		lines: b.slice(i, b.length - j),
+		removed: a.length - i - j
+	};
+}
 async function snapshotTool(config, args) {
 	const page = await getPage(config);
 	const maxText = args.maxTextChars ?? config.maxTextChars;
-	if (args.mode === "aria") {
+	const scope = typeof args.scope === "string" && args.scope ? args.scope : "";
+	const since = args.since !== void 0 ? Number(args.since) : void 0;
+	const ariaMode = args.mode === "aria";
+	const identity = {
+		url: page.url(),
+		title: await page.title()
+	};
+	const cache = snapshotCacheOf(page);
+	const canDiff = since !== void 0 && cache !== void 0 && cache.version === since;
+	let content;
+	let extra = {};
+	let walkerTruncated = false;
+	if (ariaMode) {
 		const maxRefs = Math.min(Math.max(Number(args.maxRefs ?? config.maxRefs ?? 200) || 200, 1), 500);
-		const data = await page.evaluate(buildAriaTree, maxRefs);
+		const data = await page.evaluate(buildAriaTree, {
+			maxRefs,
+			scope
+		});
+		if (data.scopeMissing) throw new Error(`scope 未命中: 页面中没有匹配 "${scope}" 的元素`);
 		setPageRefs(page, new Map(data.refs.map((r) => [r.ref, {
 			role: r.role,
 			name: r.name,
 			selector: r.selector
 		}])));
-		return {
-			url: page.url(),
-			title: await page.title(),
-			tree: data.tree.slice(0, maxText),
-			truncated: data.truncated || data.tree.length > maxText,
-			refs: data.refs.length
+		content = data.tree;
+		walkerTruncated = data.truncated;
+		extra = { refs: data.refs.length };
+	} else {
+		const maxLinks = args.maxLinks ?? config.maxLinks;
+		const data = await page.evaluate((payload) => {
+			const root = payload.sc ? document.querySelector(payload.sc) : document.body;
+			const text = root instanceof HTMLElement ? root.innerText : "";
+			const scopeEl = root ?? document;
+			return {
+				text,
+				links: Array.from(scopeEl.querySelectorAll("a")).slice(0, payload.maxL).map((a) => ({
+					text: (a.innerText || a.textContent || "").trim().slice(0, 200),
+					href: a.href
+				})),
+				inputs: scopeEl.querySelectorAll("input, textarea, select").length,
+				scopeMissing: payload.sc !== "" && root === null
+			};
+		}, {
+			maxL: maxLinks,
+			sc: scope
+		});
+		if (data.scopeMissing) throw new Error(`scope 未命中: 页面中没有匹配 "${scope}" 的元素`);
+		content = compressText(data.text);
+		extra = {
+			links: data.links,
+			inputs: data.inputs
 		};
 	}
-	const maxLinks = args.maxLinks ?? config.maxLinks;
-	const data = await page.evaluate(([maxT, maxL]) => {
+	const key = ariaMode ? "aria" : "text";
+	if (canDiff && cache[key] === content) return {
+		unchanged: true,
+		contentVersion: cache.version,
+		...scope !== "" ? { scope } : {},
+		...identity,
+		...extra
+	};
+	if (canDiff) {
+		const d = diffLines(cache[key], content);
+		setSnapshotCache(page, {
+			version: cache.version + 1,
+			text: ariaMode ? cache.text : content,
+			aria: ariaMode ? content : cache.aria
+		});
+		if (d.unchanged) return {
+			unchanged: true,
+			contentVersion: cache.version + 1,
+			...scope !== "" ? { scope } : {},
+			...identity,
+			...extra
+		};
 		return {
-			text: document.body ? document.body.innerText : "",
-			links: Array.from(document.querySelectorAll("a")).slice(0, maxL).map((a) => ({
-				text: (a.innerText || a.textContent || "").trim().slice(0, 200),
-				href: a.href
-			})),
-			inputs: document.querySelectorAll("input, textarea, select").length
+			diff: true,
+			contentVersion: cache.version + 1,
+			changedFrom: d.changedFrom,
+			removed: d.removed,
+			...scope !== "" ? { scope } : {},
+			[ariaMode ? "tree" : "text"]: (d.lines ?? []).join("\n").slice(0, maxText),
+			truncated: false,
+			...identity,
+			...extra
 		};
-	}, [maxText, maxLinks]);
-	const compressed = compressText(data.text);
+	}
+	setSnapshotCache(page, {
+		version: (cache?.version ?? 0) + 1,
+		text: ariaMode ? cache?.text ?? "" : content,
+		aria: ariaMode ? content : cache?.aria ?? ""
+	});
 	return {
-		url: page.url(),
-		title: await page.title(),
-		text: compressed.slice(0, maxText),
-		truncated: compressed.length > maxText,
-		links: data.links,
-		inputs: data.inputs
+		contentVersion: (cache?.version ?? 0) + 1,
+		...since !== void 0 ? { stale: true } : {},
+		...scope !== "" ? { scope } : {},
+		[ariaMode ? "tree" : "text"]: content.slice(0, maxText),
+		truncated: ariaMode ? walkerTruncated || content.length > maxText : content.length > maxText,
+		...identity,
+		...extra
 	};
 }
 /**
@@ -1499,6 +2111,305 @@ async function reloadTool(config) {
 	await page.reload({ waitUntil: "domcontentloaded" }).catch(() => {});
 	return { ...await pageIdentity(page) };
 }
+/** 面板自检探针(由 index.ts 在注册 API 后注入;fetch 本机 /status)。 */
+let doctorProbe = null;
+function setDoctorProbe(fn) {
+	doctorProbe = fn;
+}
+/** 目录可写性检查(mkdir + 写探针文件 + 删除)。导出供测试。 */
+function checkWritableDir(dir) {
+	try {
+		mkdirSync(dir, { recursive: true });
+		const probe = join(dir, `.doctor-probe-${Date.now()}`);
+		writeFileSync(probe, "ok");
+		unlinkSync(probe);
+		return {
+			ok: true,
+			detail: dir
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			detail: `${dir} — ${e instanceof Error ? e.message : String(e)}`
+		};
+	}
+}
+/** 可执行文件存在性检查(executablePath 显式配置用)。导出供测试。 */
+function checkExecutable(path) {
+	if (!existsSync(path)) return {
+		name: "executable",
+		ok: false,
+		detail: `executablePath 指向的文件不存在: ${path}`,
+		advice: "修正 cordis.patch.yml 的 browser.executablePath,或清空该字段改用 channel 自动探测"
+	};
+	try {
+		accessSync(path, constants.X_OK);
+	} catch {
+		return {
+			name: "executable",
+			ok: false,
+			detail: `文件存在但不可执行: ${path}`,
+			advice: "chmod +x 或确认路径指向浏览器主程序"
+		};
+	}
+	const st = statSync(path);
+	return {
+		name: "executable",
+		ok: st.isFile(),
+		detail: st.isFile() ? path : `不是普通文件: ${path}`,
+		...st.isFile() ? {} : { advice: "确认路径指向浏览器可执行文件而非目录" }
+	};
+}
+/**
+* 命名隔离上下文:同一浏览器进程内独立 cookies/storage 的"标签组"。
+* 页注册进 profile 标签表(所有既有工具直接可用),context 只做归属记录:
+* list / new(name?, url?) / switch(激活该组的一页,没有则新开) / close(整组关闭)。
+* 持久模式(userDataDir)浏览器只有单一 context,不支持本工具(用 profiles 替代)。
+*/
+async function contextTool(config, args) {
+	const action = args.action ?? "list";
+	const state = stateOf();
+	const contexts = namedContextsOf();
+	if (action === "list") return {
+		contexts: Array.from(contexts.entries()).map(([name, c]) => {
+			return {
+				name,
+				pages: Array.from(c.pageIds).filter((id) => state.pages.has(id)).length,
+				active: state.activeId !== null && c.pageIds.has(state.activeId),
+				createdAt: c.createdAt
+			};
+		}),
+		profile: currentProfile
+	};
+	if (action === "new") {
+		const name = String(args.name ?? "").trim() || `ctx-${contexts.size + 1}`;
+		if (contexts.has(name)) throw new Error(`context "${name}" 已存在;如需重建先 browser_context { action: "close", name }`);
+		if (state.browser === null && state.context === null) await launchProfile(currentProfile, config);
+		if (state.browser === null) throw new Error("持久模式(userDataDir)的浏览器只有单一 context,不支持多 context;需要多账号隔离请配置 profiles 多套 userDataDir");
+		const context = await state.browser.newContext();
+		const page = await context.newPage();
+		attachPage(page, profileConfig(config, currentProfile));
+		const id = registerTabPage(state, page);
+		const entry = {
+			context,
+			pageIds: /* @__PURE__ */ new Set([id]),
+			createdAt: Date.now()
+		};
+		contexts.set(name, entry);
+		page.on("close", () => {
+			entry.pageIds.delete(id);
+		});
+		let navigated;
+		if (typeof args.url === "string" && args.url) {
+			await page.goto(args.url, { waitUntil: "domcontentloaded" });
+			navigated = page.url();
+		}
+		return {
+			created: name,
+			...navigated !== void 0 ? { navigated } : {},
+			...await pageIdentity(page)
+		};
+	}
+	if (action === "switch") {
+		const name = String(args.name ?? "").trim();
+		if (!name) throw new Error("switch 需要 name(用 list 查看已有 context)");
+		const entry = contexts.get(name);
+		if (entry === void 0) throw new Error(`context "${name}" 不存在;已有: ${Array.from(contexts.keys()).join("、") || "(无)"}`);
+		for (const id of entry.pageIds) {
+			const page = state.pages.get(id);
+			if (page !== void 0) {
+				state.activeId = id;
+				return {
+					switched: name,
+					...await pageIdentity(page)
+				};
+			}
+		}
+		const page = await entry.context.newPage();
+		attachPage(page, profileConfig(config, currentProfile));
+		const id = registerTabPage(state, page);
+		entry.pageIds.add(id);
+		page.on("close", () => {
+			entry.pageIds.delete(id);
+		});
+		return {
+			switched: name,
+			pages: 1,
+			...await pageIdentity(page)
+		};
+	}
+	if (action === "close") {
+		const name = String(args.name ?? "").trim();
+		if (!name) throw new Error("close 需要 name");
+		const entry = contexts.get(name);
+		if (entry === void 0) throw new Error(`context "${name}" 不存在`);
+		for (const id of entry.pageIds) {
+			state.pages.delete(id);
+			if (state.activeId === id) state.activeId = Array.from(state.pages.keys()).pop() ?? null;
+		}
+		entry.pageIds.clear();
+		contexts.delete(name);
+		try {
+			await entry.context.close();
+		} catch {}
+		return {
+			closed: name,
+			remainingTabs: state.pages.size
+		};
+	}
+	throw new Error(`未知 action: ${action}(list | new | switch | close)`);
+}
+/**
+* 操作预告高亮:agent 即将 click/type/select/press 的元素在页面上琥珀色描边
+* ~1.5 秒。异步不阻塞(fire-and-forget,任何失败静默),不影响操作时序。
+*/
+function previewHighlight(page, selector, label) {
+	if (page === null || selector === "") return;
+	page.evaluate((arg) => {
+		const el = document.querySelector(arg.selector);
+		if (el === null) return;
+		const rect = el.getBoundingClientRect();
+		const box = document.createElement("div");
+		box.setAttribute("data-dsh-preview", "");
+		Object.assign(box.style, {
+			position: "fixed",
+			left: `${rect.left - 2}px`,
+			top: `${rect.top - 2}px`,
+			width: `${rect.width + 4}px`,
+			height: `${rect.height + 4}px`,
+			border: "2px solid #f59e0b",
+			borderRadius: "4px",
+			background: "rgba(245, 158, 11, 0.08)",
+			pointerEvents: "none",
+			zIndex: "2147483646",
+			boxSizing: "border-box",
+			transition: "opacity 0.3s"
+		});
+		const tip = document.createElement("div");
+		Object.assign(tip.style, {
+			position: "absolute",
+			left: "0",
+			top: "-20px",
+			font: "12px/1.4 -apple-system,'PingFang SC',sans-serif",
+			color: "#fff",
+			background: "#f59e0b",
+			padding: "1px 6px",
+			borderRadius: "4px",
+			whiteSpace: "nowrap"
+		});
+		tip.textContent = `agent: ${arg.label}`;
+		box.appendChild(tip);
+		document.documentElement.appendChild(box);
+		setTimeout(() => {
+			box.style.opacity = "0";
+			setTimeout(() => box.remove(), 400);
+		}, 1200);
+	}, {
+		selector,
+		label
+	}).catch(() => {});
+}
+/** 一次性健康诊断:不启动浏览器,只做静态/本地检查。 */
+async function doctorTool(config, _args, exec) {
+	const checks = [];
+	if (config.executablePath) checks.push(checkExecutable(config.executablePath));
+	else {
+		const channel = config.channel ?? "auto";
+		checks.push({
+			name: "channel",
+			ok: true,
+			detail: channel === "auto" || channel === "" ? "auto:按平台序探测已装浏览器(chrome → msedge → chromium;Windows 为 msedge 优先),启动失败会提示安装" : `channel = ${channel}(由 Playwright 在首次启动时解析)`
+		});
+		try {
+			const bundled = (await loadPlaywright()).chromium.executablePath();
+			checks.push({
+				name: "bundled-chromium",
+				ok: existsSync(bundled),
+				detail: existsSync(bundled) ? bundled : `playwright 捆绑 chromium 未安装(${bundled})`,
+				...existsSync(bundled) ? {} : { advice: "可选:npx playwright install chromium 安装兜底浏览器,或依赖系统已装的 Edge/Chrome" }
+			});
+		} catch {
+			checks.push({
+				name: "playwright-core",
+				ok: false,
+				detail: "playwright-core 不可用",
+				advice: "在 profile 中安装 playwright-core(dsh plugin --profile web add playwright-core)"
+			});
+		}
+	}
+	if (config.userDataDir) {
+		const w = checkWritableDir(config.userDataDir);
+		checks.push({
+			name: "userDataDir",
+			ok: w.ok,
+			detail: w.ok ? `${config.userDataDir}(登录态将持久化)` : w.detail,
+			...!w.ok ? { advice: "确认目录存在且当前用户可写" } : {}
+		});
+	} else checks.push({
+		name: "userDataDir",
+		ok: true,
+		detail: "未配置(登录态随会话,DSH 重启后失效)"
+	});
+	const baseDir = workspaceBaseDir(config, exec);
+	const baseWritable = checkWritableDir(baseDir);
+	checks.push({
+		name: "workspaceDir",
+		ok: baseWritable.ok,
+		detail: baseWritable.ok ? `${baseDir}(来源: ${config.workspaceDir ? "config.workspaceDir" : "会话 cwd 探测"})` : baseWritable.detail,
+		...!baseWritable.ok ? { advice: "设置 config.workspaceDir 钉死基准目录,或修正会话工作区权限" } : {}
+	});
+	for (const [name, dir] of [
+		["screenshotDir", config.screenshotDir ?? ".dsh-browser/screenshots"],
+		["downloadDir", config.downloadDir ?? ".dsh-browser/downloads"],
+		["baselineDir", config.baselineDir ?? ".dsh-browser/baselines"]
+	]) {
+		const abs = isAbsolute(dir) ? dir : resolve(baseDir, dir);
+		const w = checkWritableDir(abs);
+		checks.push({
+			name,
+			ok: w.ok,
+			detail: w.ok ? abs : w.detail,
+			...!w.ok ? { advice: `检查 ${abs} 的创建/写权限(父目录需可写)` } : {}
+		});
+	}
+	const state = stateOf();
+	checks.push({
+		name: "session",
+		ok: true,
+		detail: `当前 profile "${currentProfile}"${state.browser !== null ? " 已启动浏览器" : " 浏览器未启动(首次调用工具时自动启动)"} · ${state.pages.size} 个标签 · 共 ${profileStates.size} 个 profile`
+	});
+	const basePath = config.basePath ?? "/browser";
+	if (doctorProbe !== null) try {
+		const r = await doctorProbe(basePath);
+		checks.push({
+			name: "panel",
+			ok: r.ok,
+			detail: r.detail,
+			...r.advice ? { advice: r.advice } : {}
+		});
+	} catch (e) {
+		checks.push({
+			name: "panel",
+			ok: false,
+			detail: `探针执行失败: ${e instanceof Error ? e.message : String(e)}`,
+			advice: `在浏览器打开 http://<DSH地址>${basePath}/status 手动验证`
+		});
+	}
+	else checks.push({
+		name: "panel",
+		ok: true,
+		detail: `本进程无 webServer(工具半),面板 API 基路径 ${basePath}`
+	});
+	const failed = checks.filter((c) => !c.ok).length;
+	return {
+		checks,
+		summary: {
+			ok: failed === 0,
+			passed: checks.length - failed,
+			failed
+		}
+	};
+}
 async function statusTool() {
 	const page = activePage();
 	const state = stateOf();
@@ -1946,30 +2857,153 @@ async function waitForTool(config, args) {
 	const result = await pollCondition(page, args.condition, timeoutMs, intervalMs);
 	if (!result.ok) throw new Error(`等待条件超时(${timeoutMs}ms): ${result.detail ?? "条件未满足"}`);
 	return {
-		met: true,
+		met: true,
+		...await pageIdentity(page)
+	};
+}
+/**
+* 等待人工登录完成(配合 headless:false 使用):agent 打开登录页后调用本工具,
+* 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。基于通用条件引擎:
+* successSelector / successUrl 指定完成条件,两者都不给则以 URL 跳转视为完成。
+* 超时返回 loggedIn:false(不抛错)。
+*/
+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);
+	return {
+		loggedIn: (await pollCondition(page, condition, timeoutMs, 2e3)).ok,
+		...await pageIdentity(page)
+	};
+}
+/**
+* 人工接管等待(通用版 wait_for_login):agent 把控制权交还给用户(验证码 /
+* 二次确认 / 人工复核等)。instruction 会显示在实时画面面板;完成条件三选一:
+* successSelector(元素出现)/ successUrl(URL 正则)/ 两者都不给则以
+* URL 变化或页面内容签名变化视为完成。轮询间隔 2 秒,超时返回 completed:false
+* (不抛错)。导出 runPauseOnPage 供测试注入 fake page。
+*/
+async function runPauseOnPage(page, args) {
+	const instruction = typeof args.instruction === "string" ? args.instruction.trim() : "";
+	if (!instruction) throw new Error("缺少 instruction: 请说明需要人工完成什么操作(如「请输入短信验证码」)");
+	const timeoutMs = Math.min(Math.max(Number(args.timeoutMs ?? 3e5) || 3e5, 1e3), 6e5);
+	let startUrl = "";
+	try {
+		startUrl = page.url();
+	} catch {}
+	const startedAt = Date.now();
+	const pageSignature = async () => {
+		try {
+			return await page.evaluate(() => {
+				const body = document.body;
+				return `${location.href}|${body ? body.innerText.length : 0}|${document.querySelectorAll("input,button,a").length}`;
+			});
+		} catch {
+			return page.url();
+		}
+	};
+	const startSig = args.successSelector || args.successUrl ? "" : await pageSignature();
+	let completed = false;
+	let detail = `等待人工操作超时(${timeoutMs}ms)`;
+	setPauseInstruction(instruction);
+	try {
+		const deadline = startedAt + timeoutMs;
+		while (Date.now() < deadline) {
+			try {
+				if (args.successSelector) completed = await page.locator(String(args.successSelector)).first().isVisible();
+				else if (args.successUrl) completed = new RegExp(String(args.successUrl)).test(page.url());
+				else completed = page.url() !== startUrl || await pageSignature() !== startSig;
+			} catch (e) {
+				completed = false;
+				detail = `检查完成条件出错: ${e instanceof Error ? e.message : String(e)}`;
+			}
+			if (completed) {
+				detail = "人工操作完成";
+				break;
+			}
+			await page.waitForTimeout(2e3);
+		}
+	} finally {
+		clearPauseInstruction();
+	}
+	return {
+		completed,
+		waitedMs: Date.now() - startedAt,
+		detail
+	};
+}
+/** 人工接管等待工具入口(缺 instruction 在启动浏览器前即校验,失败更快)。 */
+async function pauseForHumanTool(config, args) {
+	const instruction = typeof args.instruction === "string" ? args.instruction.trim() : "";
+	if (!instruction) throw new Error("缺少 instruction: 请说明需要人工完成什么操作(如「请输入短信验证码」)");
+	const page = await getPage(config);
+	const result = await runPauseOnPage(page, args);
+	return {
+		completed: result.completed,
+		status: result.completed ? "completed" : "timedOut",
+		instruction,
+		detail: result.detail,
+		waitedMs: result.waitedMs,
 		...await pageIdentity(page)
 	};
 }
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
-* 等待人工登录完成(配合 headless:false 使用):agent 打开登录页后调用本工具,
-* 提示用户在浏览器窗口中完成登录(输入/扫码/双因素)。基于通用条件引擎:
-* successSelector / successUrl 指定完成条件,两者都不给则以 URL 跳转视为完成。
-* 超时返回 loggedIn:false(不抛错)。
+* 敏感操作审批:agent 在执行提交/删除/支付类动作前调用,把审批请求推到实时
+* 画面面板,挂起等待用户点「允许/拒绝」。超时视为拒绝(fail-closed)。
+* 用户允许时返回 { decision: "allowed", ... };拒绝/超时**抛错**(消息含原因),
+* 使 live 调用与 replay/batch 步骤统一按失败处理,agent 不应继续敏感动作。
+* 决策通过 session.resolveConfirm(面板 POST)写入。
 */
-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);
+async function confirmTool(config, args) {
+	const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+	if (!reason) throw new Error("缺少 reason: 请说明要执行什么敏感操作、为什么需要审批(如「提交白名单表单,会产生线上数据变更」)");
+	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({
+		id,
+		reason,
+		tool: typeof args.tool === "string" && args.tool ? args.tool : void 0,
+		args: args.args && typeof args.args === "object" ? args.args : void 0,
+		startedAt: Date.now()
+	});
+	const startedAt = Date.now();
+	let decision = "timeout";
+	let detail = `等待审批超时(${timeoutMs}ms),按拒绝处理`;
+	try {
+		const deadline = startedAt + timeoutMs;
+		while (Date.now() < deadline) {
+			await sleep(500);
+			const pending = getPendingConfirm();
+			if (pending === null || pending.id !== id) {
+				decision = "denied";
+				detail = "审批请求已被新的审批取代,按拒绝处理";
+				break;
+			}
+			if (pending.decision !== void 0) {
+				decision = pending.decision;
+				detail = decision === "allowed" ? "用户允许执行" : "用户拒绝执行";
+				break;
+			}
+		}
+	} finally {
+		const pending = getPendingConfirm();
+		if (pending !== null && pending.id === id) clearPendingConfirm();
+	}
+	if (decision !== "allowed") throw new Error(`敏感操作被拒绝: ${reason} — ${detail}`);
 	return {
-		loggedIn: (await pollCondition(page, condition, timeoutMs, 2e3)).ok,
-		...await pageIdentity(page)
+		decision,
+		id,
+		reason,
+		waitedMs: Date.now() - startedAt,
+		detail
 	};
 }
 /** 断言:条件在 timeoutMs 内成立则通过,否则失败并自动截图存证据。visual 断言走像素比对。 */
@@ -2837,27 +3871,76 @@ function registerTools(ctx, config) {
 	if (tools === void 0) return;
 	setToolsLogger((m) => ctx.logger?.info?.(m));
 	const timeout = (ms) => ms ?? config.timeoutMs;
-	/** 参数净化:大字段(script/fields 等)截断,避免操作日志膨胀。 */
-	function sanitizeArgs(args) {
-		if (typeof args !== "object" || args === null) return args;
-		const out = {};
-		for (const [k, v] of Object.entries(args)) {
-			const s = JSON.stringify(v);
-			out[k] = s && s.length > 300 ? `${s.slice(0, 300)}…(截断)` : v;
-		}
-		return out;
-	}
+	/**
+	* 打点包装:每次工具调用记录操作轨迹(测试报告 / 录制数据源)。
+	* 注意:记录必须保留完整原始 args —— 录制/回放依赖脚本、steps 数组等大字段的
+	* 完整性(截断会让回放得到损坏的 script / 空的 steps)。展示层截断在 ui.ts 做。
+	*/
+	/** 会触发真实 DOM 事件的 agent 工具:执行前后打点,混合录制时用于区分人手与工具回声。 */
+	const AGENT_DOM_TOOLS = /* @__PURE__ */ new Set([
+		"browser_click",
+		"browser_type",
+		"browser_select",
+		"browser_press",
+		"browser_upload",
+		"browser_form",
+		"browser_eval"
+	]);
+	/** 操作预告:这些工具执行前把目标元素在实时画面上高亮(异步不阻塞)。 */
+	const PREVIEW_TOOLS = /* @__PURE__ */ new Set([
+		"browser_click",
+		"browser_type",
+		"browser_select",
+		"browser_press"
+	]);
+	/**
+	* toolset: "core" 的高频核心集:浏览/定位/操作/等待/断言/人机协作。
+	* 低频的录制/回放/报告/抽取/表单回放/profile/context 等只在 "all" 注册。
+	*/
+	const CORE_TOOLS = /* @__PURE__ */ new Set([
+		"browser_open",
+		"browser_snapshot",
+		"browser_find",
+		"browser_elements",
+		"browser_click",
+		"browser_type",
+		"browser_press",
+		"browser_select",
+		"browser_eval",
+		"browser_batch",
+		"browser_wait",
+		"browser_wait_for",
+		"browser_assert",
+		"browser_screenshot",
+		"browser_wait_for_login",
+		"browser_pause_for_human",
+		"browser_confirm",
+		"browser_network",
+		"browser_tabs",
+		"browser_download",
+		"browser_upload",
+		"browser_status",
+		"browser_doctor",
+		"browser_close"
+	]);
 	/** 打点包装:每次工具调用记录操作轨迹(测试报告 / 录制数据源)。 */
 	function register(def) {
+		if (config.toolset === "core" && !CORE_TOOLS.has(def.name)) return;
 		const original = def.execute;
 		def.execute = async (args, exec) => {
 			const t0 = Date.now();
-			const sanitized = sanitizeArgs(args);
+			const domTool = AGENT_DOM_TOOLS.has(def.name);
+			if (domTool) noteAgentAction();
+			if (PREVIEW_TOOLS.has(def.name)) {
+				const page = activePage();
+				previewHighlight(page, typeof args?.selector === "string" && args.selector ? args.selector : typeof args?.ref === "string" && args.ref && page !== null ? pageRef(page, args.ref)?.selector ?? "" : "", def.name.replace("browser_", ""));
+			}
 			try {
 				const value = await original(args, exec);
+				if (domTool) noteAgentAction();
 				const call = recordCall({
 					tool: def.name,
-					args: sanitized,
+					args,
 					ok: true,
 					ms: Date.now() - t0,
 					ts: Date.now()
@@ -2873,7 +3956,7 @@ function registerTools(ctx, config) {
 			} catch (error) {
 				recordCall({
 					tool: def.name,
-					args: sanitized,
+					args,
 					ok: false,
 					ms: Date.now() - t0,
 					ts: Date.now(),
@@ -2909,6 +3992,11 @@ function registerTools(ctx, config) {
 		browser_profile: (a) => profileTool(config, a),
 		browser_elements: (a) => elementsTool(config, a),
 		browser_wait_for_login: (a) => waitForLoginTool(config, a),
+		browser_pause_for_human: (a) => pauseForHumanTool(config, a),
+		browser_confirm: (a) => confirmTool(config, a),
+		browser_find: (a) => findTool(config, a),
+		browser_doctor: (a) => doctorTool(config, a, void 0),
+		browser_context: (a) => contextTool(config, a),
 		browser_wait_for: (a) => waitForTool(config, a),
 		browser_assert: (a) => assertTool(config, a, void 0),
 		browser_network: (a) => networkTool(a),
@@ -2965,7 +4053,7 @@ function registerTools(ctx, config) {
 	}));
 	register(definePlainTool({
 		name: "browser_snapshot",
-		description: "读取当前页面快照(不截图)。mode:'text'(默认)返回压缩后的可见文本+链接清单,适合读内容;'aria' 返回可访问性树,可交互元素带 [ref=eN] 短引用,后续 browser_click/browser_type/browser_select/browser_press 可直接传 ref 代替 CSS 选择器(导航或重新快照后旧 ref 失效)。maxTextChars 默认 20000。",
+		description: "读取当前页面快照(不截图)。mode:'text'(默认)返回压缩后的可见文本+链接清单,适合读内容;'aria' 返回可访问性树,可交互元素带 [ref=eN] 短引用,后续 browser_click/browser_type/browser_select/browser_press 可直接传 ref 代替 CSS 选择器(导航或重新快照后旧 ref 失效)。maxTextChars 默认 20000。scope:可选 CSS 选择器,只对命中的容器区域提取(text/aria 两种模式都生效,scope 未命中报错)。since:增量模式,传上次快照返回的 contentVersion——内容未变返回 { unchanged: true },变了只返回变化的行(diff: true, changedFrom/removed 标注变化区),表格翻页/局部刷新后重读 token 开销可降一个量级;since 过期则回落全量并标 stale。",
 		parameters: {
 			type: "object",
 			properties: {
@@ -2974,6 +4062,14 @@ function registerTools(ctx, config) {
 					enum: ["text", "aria"],
 					description: "快照模式,默认 text。"
 				},
+				scope: {
+					type: "string",
+					description: "可选:限定提取区域的 CSS 选择器(如 '#main')。"
+				},
+				since: {
+					type: "integer",
+					description: "可选:上次快照的 contentVersion,只返回变化内容。"
+				},
 				maxTextChars: {
 					type: "integer",
 					description: "文本截断上限。"
@@ -2996,14 +4092,21 @@ function registerTools(ctx, config) {
 				url: { type: "string" },
 				title: { type: "string" },
 				text: { type: "string" },
+				tree: { type: "string" },
 				truncated: { type: "boolean" },
 				links: {
 					type: "array",
 					items: { type: "object" }
 				},
 				inputs: { type: "integer" },
-				tree: { type: "string" },
-				refs: { type: "integer" }
+				refs: { type: "integer" },
+				scope: { type: "string" },
+				contentVersion: { type: "integer" },
+				unchanged: { type: "boolean" },
+				diff: { type: "boolean" },
+				changedFrom: { type: "integer" },
+				removed: { type: "integer" },
+				stale: { type: "boolean" }
 			},
 			required: [
 				"url",
@@ -3012,8 +4115,13 @@ function registerTools(ctx, config) {
 			]
 		},
 		render: (_args, value) => {
-			if (value.tree !== void 0) return `URL: ${value.url}\nTitle: ${value.title}\nRefs: ${value.refs}\n--- aria tree ---\n${value.tree}`;
-			return `URL: ${value.url}\nTitle: ${value.title}\nInputs: ${value.inputs}\n--- text ---\n${value.text}`;
+			if (value.unchanged === true) return `页面未变化(版本 v${value.contentVersion}): ${value.url}`;
+			if (value.diff === true) {
+				const body = value.tree !== void 0 ? value.tree : value.text;
+				return `内容变化(v${value.contentVersion},第 ${value.changedFrom} 行起,删除 ${value.removed} 行):\n${body}`;
+			}
+			if (value.tree !== void 0) return `URL: ${value.url}\nTitle: ${value.title}\nRefs: ${value.refs}\nVersion: v${value.contentVersion}${value.stale === true ? "(stale)" : ""}\n--- aria tree ---\n${value.tree}`;
+			return `URL: ${value.url}\nTitle: ${value.title}\nInputs: ${value.inputs}\nVersion: v${value.contentVersion}${value.stale === true ? "(stale)" : ""}\n--- text ---\n${value.text}`;
 		},
 		timeoutMs: timeout(),
 		execute: (args) => snapshotTool(config, args)
@@ -3755,6 +4863,325 @@ function registerTools(ctx, config) {
 		timeoutMs: timeout(),
 		execute: (args) => waitForLoginTool(config, args)
 	}));
+	register(definePlainTool({
+		name: "browser_pause_for_human",
+		description: "人工接管等待:agent 把控制权暂时交还给用户,适用于验证码/短信确认/二次复核/敏感步骤人工兜底等场景。调用后提示(instruction)会显示在界面右下角实时画面面板,等待用户在浏览器窗口中完成操作。完成条件三选一:successSelector(完成后出现的元素)、successUrl(完成后 URL 匹配的正则),都不给则 URL 或页面内容发生变化即视为完成。轮询间隔 2 秒;超时不抛错,返回 completed:false,agent 可再次调用或改走其他路径。",
+		parameters: {
+			type: "object",
+			properties: {
+				instruction: {
+					type: "string",
+					description: "给用户看的提示语,如「请在浏览器中输入短信验证码」。"
+				},
+				timeoutMs: {
+					type: "integer",
+					description: "等待上限(毫秒,默认 300000,下限 1000,上限 600000)。"
+				},
+				successSelector: {
+					type: "string",
+					description: "完成后应出现的 CSS 选择器。"
+				},
+				successUrl: {
+					type: "string",
+					description: "完成后 URL 应匹配的正则。"
+				}
+			},
+			required: ["instruction"],
+			additionalProperties: false
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				completed: { type: "boolean" },
+				status: {
+					type: "string",
+					enum: ["completed", "timedOut"]
+				},
+				instruction: { type: "string" },
+				detail: { type: "string" },
+				waitedMs: { type: "integer" },
+				url: { type: "string" },
+				title: { type: "string" }
+			},
+			required: [
+				"completed",
+				"status",
+				"instruction",
+				"detail",
+				"waitedMs",
+				"url",
+				"title"
+			]
+		},
+		render: (_args, value) => value.completed ? `人工操作完成(${value.waitedMs}ms): ${value.url}` : `等待人工操作超时(${value.waitedMs}ms): ${value.instruction} — ${value.detail}`,
+		timeoutMs: timeout(6e5),
+		execute: (args) => pauseForHumanTool(config, args)
+	}));
+	register(definePlainTool({
+		name: "browser_confirm",
+		description: "敏感操作审批:在执行提交/删除/支付等不可逆或影响线上数据的动作前调用,审批请求(含 reason 与将执行的操作)会推送到界面右下角实时画面面板,等待用户点「允许/拒绝」。用户允许时返回 decision:'allowed';用户拒绝或等待超时(默认 60s,fail-closed)**抛错**,live 调用与 replay/batch 步骤统一按失败处理。confirmMode:'manual' 时 systemPrompt 会要求所有敏感动作前必须先过本工具。",
+		parameters: {
+			type: "object",
+			properties: {
+				reason: {
+					type: "string",
+					description: "给用户看的审批理由:要执行什么操作、影响是什么。"
+				},
+				tool: {
+					type: "string",
+					description: "可选:即将执行的工具名,如 'browser_click'。"
+				},
+				args: {
+					type: "object",
+					description: "可选:即将执行的工具参数(如 { selector: '#submit' }),供面板展示。"
+				},
+				timeoutMs: {
+					type: "integer",
+					description: "等待决策上限(毫秒,默认取配置 confirmTimeoutMs=60000,下限 1000,上限 600000)。"
+				}
+			},
+			required: ["reason"],
+			additionalProperties: false
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				decision: {
+					type: "string",
+					enum: ["allowed"]
+				},
+				id: { type: "string" },
+				reason: { type: "string" },
+				waitedMs: { type: "integer" },
+				detail: { type: "string" }
+			},
+			required: [
+				"decision",
+				"id",
+				"reason",
+				"waitedMs",
+				"detail"
+			]
+		},
+		render: (_args, value) => `用户允许执行(${value.waitedMs}ms): ${value.reason}`,
+		timeoutMs: timeout(6e5),
+		execute: (args) => confirmTool(config, args)
+	}));
+	register(definePlainTool({
+		name: "browser_find",
+		description: "按名称/id/data-testid 语义定位页面元素,只返回命中的 ref + 区域上下文,不输出全量 aria 树 —— 在大页面定位单个操作目标时比 browser_snapshot { mode: \"aria\" } 省 95% 以上 token。返回的 ref 可直接传给 browser_click / browser_type / browser_select / browser_press。默认包含匹配(query 是名称子串,忽略大小写;exact:true 精确匹配);scope 限定查找容器;多命中全部返回并附 ancestors 区域链供二次定位;零命中不抛错,返回最相近的 suggestions 候选。",
+		parameters: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					description: "要找的元素名称(如「提交」「登录」),或元素 id / data-testid。"
+				},
+				exact: {
+					type: "boolean",
+					description: "true 时名称需完全相等(默认 false 包含匹配)。"
+				},
+				scope: {
+					type: "string",
+					description: "可选:限定查找的容器 CSS 选择器(如 '#login-form')。"
+				}
+			},
+			required: ["query"],
+			additionalProperties: false
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				found: { type: "integer" },
+				matches: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							ref: { type: "string" },
+							role: { type: "string" },
+							name: { type: "string" },
+							ancestors: {
+								type: "array",
+								items: { type: "string" }
+							}
+						},
+						required: [
+							"ref",
+							"role",
+							"name",
+							"ancestors"
+						],
+						additionalProperties: false
+					}
+				},
+				suggestions: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							role: { type: "string" },
+							name: { type: "string" },
+							score: { type: "integer" }
+						},
+						required: [
+							"role",
+							"name",
+							"score"
+						],
+						additionalProperties: false
+					}
+				},
+				truncated: { type: "boolean" },
+				scanned: { type: "integer" },
+				url: { type: "string" },
+				title: { type: "string" }
+			},
+			required: [
+				"found",
+				"matches",
+				"scanned",
+				"url",
+				"title"
+			]
+		},
+		render: (args, value) => {
+			const hits = value.matches.map((m) => `${m.ref}=${m.role} "${m.name}"`).join(", ");
+			if (value.found > 0) return `找到 ${value.found} 个「${args.query}」: ${hits}${value.found > 10 ? " …" : ""}`;
+			const sugg = (value.suggestions ?? []).map((s) => `${s.role} "${s.name}"`).join("、");
+			return `未找到「${args.query}」(扫描 ${value.scanned} 个元素)${sugg ? `;相近候选: ${sugg}` : ""}`;
+		},
+		timeoutMs: timeout(),
+		execute: (args) => findTool(config, args)
+	}));
+	register(definePlainTool({
+		name: "browser_doctor",
+		description: "浏览器环境健康诊断(不启动浏览器):检查可执行文件/channel、playwright-core 可用性、userDataDir 与截图/下载/基线目录写权限、工作区基准目录解析来源、当前会话状态、面板 API 可达性。环境异常(文件落错位置/浏览器起不来)时先跑本工具定位,每项失败检查附修复建议。",
+		parameters: {
+			type: "object",
+			properties: {},
+			additionalProperties: false
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				checks: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							name: { type: "string" },
+							ok: { type: "boolean" },
+							detail: { type: "string" },
+							advice: { type: "string" }
+						},
+						required: [
+							"name",
+							"ok",
+							"detail"
+						],
+						additionalProperties: false
+					}
+				},
+				summary: {
+					type: "object",
+					properties: {
+						ok: { type: "boolean" },
+						passed: { type: "integer" },
+						failed: { type: "integer" }
+					},
+					required: [
+						"ok",
+						"passed",
+						"failed"
+					],
+					additionalProperties: false
+				}
+			},
+			required: ["checks", "summary"]
+		},
+		render: (_args, value) => {
+			const lines = value.checks.map((c) => `${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail}${c.advice ? `\n    建议: ${c.advice}` : ""}`);
+			return `诊断 ${value.summary.ok ? "通过" : "发现问题"}(${value.summary.passed}/${value.checks.length})\n${lines.join("\n")}`;
+		},
+		timeoutMs: timeout(15e3),
+		execute: (args, exec) => doctorTool(config, args, exec)
+	}));
+	register(definePlainTool({
+		name: "browser_context",
+		description: "命名隔离上下文:同一浏览器进程内 cookies/storage 完全隔离的\"标签组\"。action:new(name 可省略自动编号,可选 url 直接打开)/ list / switch(name,激活该组页面,组内页全关则在原 context 新开,登录态仍在)/ close(name,整组关闭)。适合多账号并行验证、需要干净会话的抓取。页注册进普通标签表,所有浏览器工具直接可用;browser_tabs 也能看到/切换这些页。持久模式(userDataDir)不支持,请改用 profiles。",
+		parameters: {
+			type: "object",
+			properties: {
+				action: {
+					type: "string",
+					enum: [
+						"list",
+						"new",
+						"switch",
+						"close"
+					],
+					description: "默认 list。"
+				},
+				name: {
+					type: "string",
+					description: "上下文名(new 自动编号时可省略;switch/close 必填)。"
+				},
+				url: {
+					type: "string",
+					description: "new 时可选:新页直接打开的 URL。"
+				}
+			},
+			additionalProperties: false
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				contexts: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							name: { type: "string" },
+							pages: { type: "integer" },
+							active: { type: "boolean" },
+							createdAt: { type: "integer" }
+						},
+						required: [
+							"name",
+							"pages",
+							"active",
+							"createdAt"
+						],
+						additionalProperties: false
+					}
+				},
+				profile: { type: "string" },
+				created: { type: "string" },
+				navigated: { type: "string" },
+				switched: { type: "string" },
+				closed: { type: "string" },
+				remainingTabs: { type: "integer" },
+				pages: { type: "integer" },
+				url: { type: "string" },
+				title: { type: "string" }
+			},
+			required: []
+		},
+		render: (args, value) => {
+			if (args.action === "new" || value.created) return `新建隔离上下文 "${value.created}"${value.navigated ? ` → ${value.navigated}` : ""}`;
+			if (args.action === "switch" || value.switched) return `切换到上下文 "${value.switched}": ${value.url}`;
+			if (args.action === "close" || value.closed) return `关闭上下文 "${value.closed}"(剩余 ${value.remainingTabs} 标签)`;
+			return value.contexts.map((c) => `${c.active ? "▶" : " "} ${c.name}(${c.pages} 页)`).join("\n") || "(无隔离上下文;browser_context { action: \"new\" } 创建)";
+		},
+		timeoutMs: timeout(),
+		execute: (args) => contextTool(config, args)
+	}));
 	register(definePlainTool({
 		name: "browser_elements",
 		description: "列出当前页面可交互元素(input/textarea/select/button/链接)的结构化清单:类型、name/id、关联 label(aria-label/label[for]/form-item)、placeholder、可见文本、可直接用于 browser_click/browser_type/browser_select 的 CSS 选择器。页面有展开的下拉时,dropdownOptions 会列出可见选项。比 browser_snapshot 更适合定位表单。",
@@ -4291,6 +5718,16 @@ function registerTools(ctx, config) {
 }
 //#endregion
 //#region lib/types/browser/ui.js
+/** 展示层参数截断:单字段 JSON 超过 300 字符截断(仅用于面板轨迹显示,不进录制)。 */
+function truncateForDisplay(args) {
+	if (typeof args !== "object" || args === null) return args;
+	const out = {};
+	for (const [k, v] of Object.entries(args)) {
+		const s = JSON.stringify(v);
+		out[k] = s && s.length > 300 ? `${s.slice(0, 300)}…(截断)` : v;
+	}
+	return out;
+}
 function registerBrowserApi(ctx, config, base) {
 	const webServer = ctx.get("webServer");
 	if (webServer === void 0) return;
@@ -4301,7 +5738,10 @@ function registerBrowserApi(ctx, config, base) {
 		handler: async (req, res) => {
 			const path = urlPath(req);
 			if (path === `${base}/status`) {
-				sendJson(res, 200, await statusTool());
+				sendJson(res, 200, {
+					...await statusTool(),
+					pause: currentPause()
+				});
 				return;
 			}
 			if (path === `${base}/history`) {
@@ -4314,7 +5754,10 @@ function registerBrowserApi(ctx, config, base) {
 			if (path === `${base}/log`) {
 				sendJson(res, 200, {
 					profile: currentProfile,
-					calls: testLogOf().slice(0, 50)
+					calls: testLogOf().slice(0, 50).map((c) => ({
+						...c,
+						args: truncateForDisplay(c.args)
+					}))
 				});
 				return;
 			}
@@ -4322,6 +5765,21 @@ function registerBrowserApi(ctx, config, base) {
 				sendJson(res, 200, { run: latestRun() });
 				return;
 			}
+			if (path === `${base}/runs/report`) {
+				let source = "";
+				try {
+					source = new URL(req.url ?? "/", "http://x").searchParams.get("source") ?? "";
+				} catch {}
+				if (source === "") source = latestRun()?.source ?? "";
+				const html = renderHtmlReport(listRuns(50).filter((r) => source === "" ? true : r.source === source), source === "" ? void 0 : source);
+				res.writeHead(200, {
+					"content-type": "text/html; charset=utf-8",
+					"cache-control": "no-store",
+					"content-length": Buffer.byteLength(html)
+				});
+				res.end(html);
+				return;
+			}
 			if (path === `${base}/recordings`) {
 				if ((req.method ?? "GET") === "POST") {
 					const body = await readJsonBody(req).catch(() => void 0);
@@ -4352,6 +5810,25 @@ function registerBrowserApi(ctx, config, base) {
 				sendJson(res, 200, detail);
 				return;
 			}
+			if (path === `${base}/confirm`) {
+				if ((req.method ?? "GET") === "POST") {
+					const body = await readJsonBody(req).catch(() => void 0);
+					const id = typeof body?.id === "string" ? body.id : "";
+					const decision = body?.decision === "allowed" || body?.decision === "denied" ? body.decision : void 0;
+					if (!id || decision === void 0) {
+						sendText(res, 400, "id and decision (allowed|denied) required");
+						return;
+					}
+					sendJson(res, 200, {
+						resolved: resolveConfirm(id, decision),
+						id,
+						decision
+					});
+					return;
+				}
+				sendJson(res, 200, { confirm: getPendingConfirm() });
+				return;
+			}
 			if (path === `${base}/screenshot`) {
 				const page = activePage();
 				if (page === null || page.isClosed()) {
@@ -4684,6 +6161,18 @@ const SCHEMA = {
 	maxRows: {
 		type: "number",
 		min: 1
+	},
+	confirmMode: {
+		type: "string",
+		enum: ["off", "manual"]
+	},
+	confirmTimeoutMs: {
+		type: "number",
+		min: 1e3
+	},
+	toolset: {
+		type: "string",
+		enum: ["core", "all"]
 	}
 };
 const DEFAULT_CONFIG = {
@@ -4706,7 +6195,10 @@ const DEFAULT_CONFIG = {
 	selectorHealing: true,
 	healTimeoutMs: 3e3,
 	maxRefs: 200,
-	maxRows: 1e3
+	maxRows: 1e3,
+	confirmMode: "off",
+	confirmTimeoutMs: 6e4,
+	toolset: "all"
 };
 function apply(ctx, rawConfig) {
 	const resolved = resolveConfig("dsh-browser-view", SCHEMA, DEFAULT_CONFIG, rawConfig);
@@ -4716,16 +6208,41 @@ function apply(ctx, rawConfig) {
 	const loadedRecordings = loadRecordings();
 	if (loadedRecordings > 0) ctx.logger?.info?.(`dsh-browser-view: loaded ${loadedRecordings} saved recording(s)`);
 	registerTools(ctx, config);
-	const sectionDispose = ctx.get("systemPrompt")?.section?.({
+	const systemPrompt = ctx.get("systemPrompt");
+	const confirmGuidance = config.confirmMode === "manual" ? "本环境 confirmMode 为 manual:凡提交/删除/支付等不可逆或影响线上数据的敏感动作,执行前必须先调用 browser_confirm(reason 说明操作与影响,等待用户在实时画面面板点允许/拒绝;拒绝或超时即放弃该动作,不得换路径绕过)。" : "";
+	const sectionDispose = systemPrompt?.section?.({
 		name: "tool:browser",
 		order: 200,
-		text: "浏览器工具操作一个共享浏览器会话,支持多标签页与多配置文件。打开页面后先用 browser_snapshot 读文本与链接、browser_elements 读表单结构(含关联 label 与展开的下拉选项),再决定 browser_click / browser_type / browser_form;定位操作元素优先用 browser_snapshot { mode: \"aria\" }(可交互元素带 ref=eN,click/type/select/press 直接传 ref 代替 CSS 选择器);下拉选择(原生 select 与 antd/element 组件库)用 browser_select 传 selector/ref + 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);配置 userDataDir 时登录态会持久化。用户可通过界面右下角面板的实时画面查看浏览器。"
+		text: (config.toolset === "core" ? "浏览器工具操作一个共享浏览器会话(toolset=core:已精简工具集)。打开页面后用 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_snapshot 读文本与链接、browser_elements 读表单结构(含关联 label 与展开的下拉选项),再决定 browser_click / browser_type / browser_form;定位操作元素优先用 browser_find(query 传名称,只返回命中 ref+区域上下文,大页面最省 token;零命中会给相近候选),需要全页结构时再用 browser_snapshot { mode: \"aria\" }(可交互元素带 ref=eN,click/type/select/press 直接传 ref 代替 CSS 选择器);下拉选择(原生 select 与 antd/element 组件库)用 browser_select 传 selector/ref + 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
 	});
 	if (sectionDispose !== void 0) ctx.effect(() => sectionDispose);
 	registerBrowserApi(ctx, config, base);
 	const webServer = ctx.get("webServer");
 	if (webServer !== void 0) {
 		applyEmbed(ctx, webServer, base);
+		const port = webServer.port;
+		setDoctorProbe(port !== void 0 ? async (basePath) => {
+			try {
+				const res = await fetch(`http://127.0.0.1:${port}${basePath}/status`, {
+					signal: AbortSignal.timeout(2e3),
+					cache: "no-store"
+				});
+				return res.ok ? {
+					ok: true,
+					detail: `面板 API 可达(/status → 200,端口 ${port})`
+				} : {
+					ok: false,
+					detail: `面板 API 异常(/status → ${res.status})`,
+					advice: "查看 DSH 日志中 webServer 的注册错误"
+				};
+			} catch (e) {
+				return {
+					ok: false,
+					detail: `本机 127.0.0.1:${port} 请求失败: ${e instanceof Error ? e.message : String(e)}`,
+					advice: "确认 DSH web 端口未被防火墙/代理拦截"
+				};
+			}
+		} : null);
 		const disposeConfig = webServer.register({
 			kind: "exact",
 			path: "/__dsh-browser-view__/config",