@tanzerfe/page-use 0.0.5 → 0.0.7

package/dist/{src-tOb9oqjb.mjs → src-ChJ6q7jl.mjs}

@@ -1,8 +1,64 @@
-import { PageAgent } from "page-agent";
+import { PageAgent, tool } from "page-agent";
+import { clickElement } from "@page-agent/page-controller";
+import * as z from "zod/v4";
 import { LitElement, css, html, nothing, svg } from "lit";
 import { keyed } from "lit/directives/keyed.js";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
 
+//#region src/tour/styles.ts
+/** 内置风格 key：日常使用者 */
+const TOUR_STYLE_USER = "user";
+/** 内置风格 key：培训讲师 */
+const TOUR_STYLE_TRAINER = "trainer";
+/** 内置风格；宿主以相同 key 配置时覆盖对应项 */
+const DEFAULT_TOUR_STYLES = [{
+	key: TOUR_STYLE_USER,
+	label: "日常使用者",
+	prompt: [
+		"- 受众：日常使用本系统的业务人员。",
+		"- 侧重：这个模块能做什么、怎么操作（入口按钮、筛选方式、常用动作）。",
+		"- 篇幅：每个模块一到两句，语气简洁直接，不讲背景与原理。"
+	].join("\n")
+}, {
+	key: TOUR_STYLE_TRAINER,
+	label: "培训讲师",
+	prompt: [
+		"- 场景：讲解人边演示边讲解，听众可能是学员、领导或客户。",
+		"- 称呼：保持通用，开场可用「大家好」；不要使用「各位学员」「同学们」等指定听众身份的称呼。",
+		"- 侧重：模块的业务含义、指标或字段的统计口径、典型操作流程与注意事项；开场说明页面在业务流程中的作用。",
+		"- 篇幅：每个模块二到四句，条理清晰、用语规范；可结合按页提示中的业务说明，不编造页面上没有的数据与规则。"
+	].join("\n")
+}];
+/** 合并内置与宿主风格：同 key 覆盖（保持内置顺序），新 key 追加；丢弃 key / label / prompt 为空的项 */
+function mergeTourStyles(custom) {
+	const result = DEFAULT_TOUR_STYLES.map((style) => ({ ...style }));
+	for (const style of custom ?? []) {
+		const key = style?.key?.trim();
+		const label = style?.label?.trim();
+		const prompt = style?.prompt?.trim();
+		if (!key || !label || !prompt) continue;
+		const item = {
+			key,
+			label,
+			prompt
+		};
+		const index = result.findIndex((s) => s.key === key);
+		if (index >= 0) result[index] = item;
+		else result.push(item);
+	}
+	return result;
+}
+/** 按候选 key 依次查找第一个存在的风格；都不存在时返回 null */
+function resolveTourStyle(styles, ...keys) {
+	for (const key of keys) {
+		if (!key) continue;
+		const style = styles.find((s) => s.key === key);
+		if (style) return style;
+	}
+	return null;
+}
+
+//#endregion
 //#region src/voice/browserEngine.ts
 /** 内置浏览器引擎的保留 id；注入引擎使用该 id 会被忽略 */
 const BROWSER_ENGINE_ID = "browser";
@@ -203,6 +259,39 @@ const DEFAULT_MAX_STEPS = 20;
 const DEFAULT_SESSION_HEADER = "x-opencode-session";
 /** localStorage / sessionStorage 键前缀，可通过 storageKeyPrefix 覆盖 */
 const DEFAULT_STORAGE_KEY_PREFIX = "tz-page-use";
+/** 页面讲解单次最多切换 Tab 的次数（不含结束时切回）；每次切换多一次 LLM 调用，限制演示时长 */
+const DEFAULT_TOUR_MAX_TAB_SWITCHES = 5;
+/** 未指定内容区时的回退顺序 */
+const CONTENT_ROOT_FALLBACKS = ["main", "[role=main]"];
+function resolveContentRoot(getter) {
+	return () => {
+		let el;
+		try {
+			el = getter?.();
+		} catch (err) {
+			console.warn("[PageUse] getContentRoot 执行异常，使用默认内容区", err);
+		}
+		if (el) return el;
+		if (typeof document === "undefined") return null;
+		for (const selector of CONTENT_ROOT_FALLBACKS) {
+			const found = document.querySelector(selector);
+			if (found) return found;
+		}
+		return document.body;
+	};
+}
+function normalizeTour(value) {
+	const config = typeof value === "object" && value ? value : {};
+	const max = config.maxTabSwitches;
+	const styles = mergeTourStyles(config.styles);
+	const preferred = config.defaultStyle?.trim() || "user";
+	return {
+		enabled: value !== false,
+		maxTabSwitches: typeof max === "number" && Number.isInteger(max) && max > 0 ? max : 5,
+		styles,
+		defaultStyle: styles.some((s) => s.key === preferred) ? preferred : styles[0].key
+	};
+}
 /** 相对路径补齐为当前 origin 的绝对地址并去掉末尾 /；无法解析时返回空串 */
 function toAbsoluteUrl(input) {
 	const base = typeof window !== "undefined" ? window.location.origin : void 0;
@@ -248,7 +337,9 @@ function normalizeOptions(options) {
 		storageKeyPrefix: options.storageKeyPrefix || "tz-page-use",
 		pageAgentOptions: options.pageAgentOptions ?? {},
 		exposeGlobal: options.exposeGlobal !== false,
-		ttsEngines: listTtsEngines(options.tts)
+		ttsEngines: listTtsEngines(options.tts),
+		getContentRoot: resolveContentRoot(options.getContentRoot),
+		pageTour: normalizeTour(options.pageTour)
 	};
 }
 /** URL 查询参数：?pageUseDebug=1 打开调试面板，?pageUseDebug=0 关闭；结果记入 sessionStorage */
@@ -343,6 +434,7 @@ const DEFAULT_PAGE_USE_SETTINGS = {
 	voiceRate: 1.1,
 	voiceEngineId: "",
 	voiceNames: {},
+	tourStyle: "",
 	launcherVisible: null,
 	fabPos: null
 };
@@ -457,6 +549,11 @@ const pageUseSettings = {
 	}
 };
 
+//#endregion
+//#region src/tour/constants.ts
+/** 页面讲解工具名：大纲文本、工具注册与播报静默列表共用 */
+const PRESENT_PAGE_TOOL_NAME = "present_page";
+
 //#endregion
 //#region src/voice/preview.ts
 /**
@@ -509,6 +606,7 @@ function stopPreview() {
 * 队列只有两部分：当前正在播报的一组文本，以及一条待播的步骤文本。
 * - 步骤播报不打断当前播报，只覆盖待播槽（语音跟不上执行时丢弃中间步骤）；
 * - 提问 / 结论先清空再播报；
+* - 页面讲解（speakAndWait）先清空再播报，返回的 Promise 在整组结束时 resolve，用于光标与语音同步；
 * - 每组开始时读取一次引擎并在组内固定使用（splitSentences 与中止对象保持一致）；
 * - 每组持有一个 AbortController，清空时中止，引擎据此停止自身的合成与播放；
 * - 每次清空递增代次，旧代次 speak() 的迟到 resolve 一律忽略，避免中止后误触发下一条。
@@ -528,9 +626,20 @@ function createSpeaker(getSettings, getEngine = () => browserTtsEngine) {
 	let controller = null;
 	/** 当前组使用的引擎；组内不随设置切换 */
 	let engine = getEngine();
-	function playGroup(sentences) {
+	/** 当前组结束（播完或被清空）时的回调；仅 speakAndWait 的组设置 */
+	let groupDone = null;
+	function finishGroup() {
+		const done = groupDone;
+		groupDone = null;
+		done?.();
+	}
+	function playGroup(sentences, onDone) {
 		engine = getEngine();
-		if (!engine.isAvailable()) return;
+		if (!engine.isAvailable()) {
+			onDone?.();
+			return;
+		}
+		groupDone = onDone ?? null;
 		current = engine.splitSentences ? [...sentences] : [sentences.join("")];
 		controller = new AbortController();
 		playNext();
@@ -540,6 +649,7 @@ function createSpeaker(getSettings, getEngine = () => browserTtsEngine) {
 		if (text === void 0 || !controller) {
 			current = null;
 			controller = null;
+			finishGroup();
 			if (pending) {
 				const next = pending;
 				pending = null;
@@ -569,6 +679,7 @@ function createSpeaker(getSettings, getEngine = () => browserTtsEngine) {
 		controller = null;
 		current = null;
 		pending = null;
+		finishGroup();
 	}
 	return {
 		enqueue(sentences) {
@@ -583,7 +694,19 @@ function createSpeaker(getSettings, getEngine = () => browserTtsEngine) {
 			clear();
 			if (sentences.length) playGroup(sentences);
 		},
-		clear
+		clear,
+		speakAndWait(sentences, signal) {
+			clear();
+			if (!sentences.length || signal?.aborted) return Promise.resolve();
+			return new Promise((resolve) => {
+				const onAbort = () => clear();
+				signal?.addEventListener("abort", onAbort, { once: true });
+				playGroup(sentences, () => {
+					signal?.removeEventListener("abort", onAbort);
+					resolve();
+				});
+			});
+		}
 	};
 }
 
@@ -669,7 +792,7 @@ function joinLines(lines) {
 	return result.replace(/([。！？!?；;，,、：:])[。！？!?；;，,、：:\s]+/g, "$1").replace(/^[。！？!?；;，,、：:\s]+/, "").trim();
 }
 /** 超过上限时在上限内最后一个句末标点处截断，找不到则硬截断，并追加提示语 */
-function truncate(text, maxChars, hint) {
+function truncate$1(text, maxChars, hint) {
 	if (text.length <= maxChars) return text;
 	const head = text.slice(0, maxChars);
 	let cut = -1;
@@ -712,7 +835,7 @@ function toSpeechText(text, options = {}) {
 	const maxChars = options.maxChars ?? 240;
 	const joined = joinLines(toLines((text || "").replace(/```[\s\S]*?(?:```|$)/g, "\n").replace(/<\/?[a-zA-Z][^>]*>/g, "")));
 	if (!joined) return [];
-	return splitSentences(truncate(joined, maxChars, options.truncatedHint ?? "详细内容请查看面板"));
+	return splitSentences(truncate$1(joined, maxChars, options.truncatedHint ?? "详细内容请查看面板"));
 }
 
 //#endregion
@@ -720,6 +843,7 @@ function toSpeechText(text, options = {}) {
 /**
 * 演示播报：订阅进度事件，按设置把步骤描述、提问与结论交给 speaker 播报。
 * 只订阅事件，不影响任务执行节奏；对所有任务来源生效。
+* 例外：页面讲解经 narrate() 逐段播报并等待播完，由讲解工具控制光标移动的节奏。
 * 是否播报 = 设置 voiceEnabled（总开关，持久化）且未处于本次任务静音（narrationMute，运行期）。
 */
 /**
@@ -733,8 +857,15 @@ const SILENT_STEP_TOOLS = /* @__PURE__ */ new Set([
 	"done",
 	"ask_user",
 	"error",
-	"retry"
+	"retry",
+	PRESENT_PAGE_TOOL_NAME
 ]);
+/** 页面讲解在语音关闭 / 静音 / 未启动播报时，每个模块的停留时长（ms），供观众看清光标位置 */
+const SILENT_DWELL_MS = 2500;
+/** 讲解词的播报字数上限：高于讲解工具的讲解词上限，正常不截断 */
+const TOUR_SPEECH_MAX_CHARS$1 = 400;
+/** 当前运行的播报（startNarration 期间有效），供页面讲解逐段播报 */
+let active = null;
 /**
 * 调试面板名称（PageUseLauncherConfig.title），用于截断提示语「详细内容请查看「名称」」。
 * 由 launcher 挂载时登记、卸载时撤销；未挂载面板时为 null，提示语回退为「详细内容请查看面板」。
@@ -763,7 +894,11 @@ function startNarration({ subscribe, engines, speaker: injected }) {
 		};
 	}, () => resolveTtsEngine(available, pageUseSettings.get().voiceEngineId));
 	const enabled = () => pageUseSettings.get().voiceEnabled && !narrationMute.get().muted;
-	const speech = (text) => toSpeechText(text, { truncatedHint: buildTruncatedHint(panelName ?? void 0) });
+	const current = {
+		speaker,
+		enabled
+	};
+	active = current;
 	const offEvents = subscribe((event) => {
 		switch (event.type) {
 			case "started":
@@ -791,12 +926,675 @@ function startNarration({ subscribe, engines, speaker: injected }) {
 		if (muted) speaker.clear();
 	});
 	return () => {
+		if (active === current) active = null;
 		offEvents();
 		offSettings();
 		offMute();
 		speaker.clear();
 	};
 }
+function speech(text) {
+	return toSpeechText(text, { truncatedHint: buildTruncatedHint(panelName ?? void 0) });
+}
+/** 等待 ms 毫秒，signal 中止时立即 resolve */
+function dwell(ms, signal) {
+	if (ms <= 0 || signal?.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const finish = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", finish);
+			resolve();
+		};
+		const timer = setTimeout(finish, ms);
+		signal?.addEventListener("abort", finish, { once: true });
+	});
+}
+/**
+* 页面讲解的一段讲解词：播报开启时完整播完再 resolve；
+* 语音关闭、静音或未启动播报时按 SILENT_DWELL_MS 停留；
+* 播报中途被静音 / 关闭而提前结束时补足停留时间，避免光标立即跳走。signal 中止时立即 resolve。
+*/
+async function narrate(text, signal) {
+	if (signal?.aborted) return;
+	const startedAt = Date.now();
+	const narration = active;
+	if (narration?.enabled()) {
+		const sentences = toSpeechText(text, { maxChars: TOUR_SPEECH_MAX_CHARS$1 });
+		await narration.speaker.speakAndWait(sentences, signal);
+		if (signal?.aborted || narration.enabled()) return;
+		await dwell(SILENT_DWELL_MS - (Date.now() - startedAt), signal);
+		return;
+	}
+	await dwell(SILENT_DWELL_MS, signal);
+}
+
+//#endregion
+//#region src/tour/highlight.ts
+/**
+* 页面讲解的模块高亮框：fixed 定位的描边层，位于 SimulatorMask 之上、不拦截指针。
+* 同一时间只存在一个；仅在窗口尺寸变化时重算位置（讲解期间蒙层拦截用户滚动）。
+*/
+/** 高亮框元素 id，便于宿主覆盖样式或排查 */
+const TOUR_HIGHLIGHT_ID = "tz-page-use-tour-highlight";
+/** 比 page-agent SimulatorMask 的 z-index（2147483641）高一层，保证在蒙层上方可见 */
+const HIGHLIGHT_Z_INDEX = 2147483642;
+/** 高亮框相对模块的外扩像素，避免描边压住模块边缘内容 */
+const HIGHLIGHT_PADDING = 6;
+let current = null;
+function place(el, target) {
+	const rect = target.getBoundingClientRect();
+	el.style.left = `${rect.left - HIGHLIGHT_PADDING}px`;
+	el.style.top = `${rect.top - HIGHLIGHT_PADDING}px`;
+	el.style.width = `${rect.width + 12}px`;
+	el.style.height = `${rect.height + 12}px`;
+}
+function showTourHighlight(target) {
+	hideTourHighlight();
+	const el = document.createElement("div");
+	el.id = TOUR_HIGHLIGHT_ID;
+	el.setAttribute("aria-hidden", "true");
+	Object.assign(el.style, {
+		position: "fixed",
+		pointerEvents: "none",
+		zIndex: String(HIGHLIGHT_Z_INDEX),
+		boxSizing: "border-box",
+		borderRadius: "8px",
+		border: "2px solid var(--tz-page-use-primary, #0879ff)",
+		boxShadow: "0 0 0 4px rgba(8, 121, 255, 0.18), 0 0 18px rgba(8, 121, 255, 0.35)",
+		transition: "left 0.25s ease, top 0.25s ease, width 0.25s ease, height 0.25s ease"
+	});
+	place(el, target);
+	document.body.appendChild(el);
+	const onResize = () => place(el, target);
+	window.addEventListener("resize", onResize);
+	current = {
+		el,
+		target,
+		onResize
+	};
+}
+function hideTourHighlight() {
+	if (!current) return;
+	window.removeEventListener("resize", current.onResize);
+	current.el.remove();
+	current = null;
+}
+
+//#endregion
+//#region src/tour/sections.ts
+/**
+* 页面模块识别：在内容区根节点内，按标题（h1–h3）与带 aria-label 的区域划分讲解模块。
+*
+* - 标题模块的根节点：从标题逐级向上，父元素一旦还包含另一个「级别不低于自身」的标题即停止，
+*   取停止前一层；这样 h2 模块能包住其下的 h3，又不会扩到并列 h2 的公共容器。
+* - 第一个 h1 作为页面概述，不进入可指向的模块清单，但仍参与边界判断。
+* - 纯 DOM 函数，可见性判断可注入（jsdom 不计算布局）。
+*/
+/** 模块清单条数上限：清单会追加到每一步的按页提示，控制 token 增量 */
+const SECTION_LIMIT = 20;
+/** 模块说明的最大字符数（超出截断并加省略号） */
+const SECTION_DESC_MAX_CHARS = 60;
+/** 默认可见性：已渲染、尺寸非 0、visibility 不为 hidden（aria-hidden 由扫描统一处理） */
+function isElementVisible(el) {
+	if (el.getClientRects().length === 0) return false;
+	const rect = el.getBoundingClientRect();
+	if (rect.width <= 0 || rect.height <= 0) return false;
+	return getComputedStyle(el).visibility !== "hidden";
+}
+/** 在 aria-hidden 子树内的元素不对外呈现，也不作为讲解对象 */
+function isAriaHidden(el) {
+	return el.closest("[aria-hidden=\"true\"]") !== null;
+}
+function normalizeText(text) {
+	return (text || "").replace(/\s+/g, " ").trim();
+}
+function truncate(text, max) {
+	return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+/** a 在文档中位于 b 之前 */
+function precedes(a, b) {
+	return (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0;
+}
+function collectHeadings(root, isVisible) {
+	const result = [];
+	for (const el of root.querySelectorAll("h1, h2, h3")) {
+		const name = normalizeText(el.textContent);
+		if (!name || isAriaHidden(el) || !isVisible(el)) continue;
+		result.push({
+			el,
+			level: Number(el.tagName.charAt(1)),
+			name
+		});
+	}
+	return result;
+}
+/** 从标题向上找模块根节点，不越过内容区根节点 */
+function findSectionRoot(heading, all, root) {
+	let node = heading.el;
+	while (node.parentElement && node.parentElement !== root) {
+		const parent = node.parentElement;
+		if (all.some((c) => c !== heading && c.level <= heading.level && parent.contains(c.el))) break;
+		node = parent;
+	}
+	return node;
+}
+/** container 内位于 after 之后（且不在 after 内部）的第一个非空 <p> */
+function firstParagraphAfter(container, after, scope, isVisible) {
+	for (const p of container.querySelectorAll("p")) {
+		if (!scope.contains(p) || after.contains(p) || !precedes(after, p)) continue;
+		if (isAriaHidden(p) || !isVisible(p)) continue;
+		const text = normalizeText(p.textContent);
+		if (text) return text;
+	}
+	return "";
+}
+/**
+* 说明文字：先在标题的父元素内找标题之后的 <p>（`<div><h2/><p/></div>`）；
+* 找不到再到祖父元素内找标题所在分支之后的 <p>（`<header><h2/></header><p/>`）。
+* 只在 scope（模块根节点或内容区）内查找，避免取到相邻模块的文字。
+*/
+function findDescription(heading, scope, isVisible) {
+	const parent = heading.parentElement;
+	if (!parent) return "";
+	const own = firstParagraphAfter(parent, heading, scope, isVisible);
+	if (own) return own;
+	const grand = parent.parentElement;
+	if (!grand || !scope.contains(parent) || parent === scope) return "";
+	return firstParagraphAfter(grand, parent, scope, isVisible);
+}
+function scanPageSections(root, isVisible = isElementVisible) {
+	const headings = collectHeadings(root, isVisible);
+	const overviewHeading = headings.find((h) => h.level === 1) ?? null;
+	const overview = overviewHeading ? {
+		name: overviewHeading.name,
+		desc: truncate(findDescription(overviewHeading.el, root, isVisible), 60),
+		anchor: overviewHeading.el
+	} : null;
+	const found = [];
+	for (const heading of headings) {
+		if (heading === overviewHeading) continue;
+		const sectionRoot = findSectionRoot(heading, headings, root);
+		found.push({
+			name: heading.name,
+			desc: truncate(findDescription(heading.el, sectionRoot, isVisible), 60),
+			level: heading.level,
+			root: sectionRoot,
+			anchor: heading.el
+		});
+	}
+	for (const el of root.querySelectorAll("section[aria-label], [role=\"region\"][aria-label]")) {
+		const name = normalizeText(el.getAttribute("aria-label"));
+		if (!name || isAriaHidden(el) || !isVisible(el)) continue;
+		if (headings.some((h) => el.contains(h.el))) continue;
+		found.push({
+			name,
+			desc: "",
+			level: 0,
+			root: el,
+			anchor: el
+		});
+	}
+	found.sort((a, b) => a.root === b.root ? 0 : precedes(a.root, b.root) ? -1 : 1);
+	const sections = [];
+	for (const [i, item] of found.slice(0, 20).entries()) {
+		let parentId = null;
+		for (const prev of sections) if (prev.root !== item.root && prev.root.contains(item.root)) parentId = prev.id;
+		sections.push({
+			...item,
+			id: `s${i + 1}`,
+			parentId
+		});
+	}
+	return {
+		overview,
+		sections
+	};
+}
+
+//#endregion
+//#region src/tour/tabs.ts
+/** Tab 组数量上限：随模块清单进入每一步的按页提示 */
+const TAB_GROUP_LIMIT = 10;
+/** 单组列出的 Tab 数量上限 */
+const TAB_PER_GROUP_LIMIT = 12;
+/** Tab 文本最大字符数（去掉角标等冗余后仍过长时截断） */
+const TAB_TEXT_MAX_CHARS = 20;
+/** Tab 结构适配表；新增组件库时在此追加 */
+const TAB_ADAPTERS = [{
+	list: "[role=\"tablist\"]",
+	tab: "[role=\"tab\"]",
+	isActive: (tab) => tab.getAttribute("aria-selected") === "true",
+	isDisabled: (tab) => tab.getAttribute("aria-disabled") === "true" || tab.hasAttribute("disabled")
+}, {
+	list: ".n-tabs-nav",
+	tab: ".n-tabs-tab",
+	isActive: (tab) => tab.classList.contains("n-tabs-tab--active"),
+	isDisabled: (tab) => tab.classList.contains("n-tabs-tab--disabled")
+}];
+function tabText(tab) {
+	const text = normalizeText(tab.getAttribute("aria-label")) || normalizeText(tab.textContent);
+	return text.length > TAB_TEXT_MAX_CHARS ? `${text.slice(0, TAB_TEXT_MAX_CHARS)}…` : text;
+}
+/** 包含元素的最内层模块：嵌套模块的根节点在文档顺序上位于外层之后，取最后一个命中项 */
+function findOwnerSection(el, sections) {
+	let owner = null;
+	for (const section of sections) if (section.root.contains(el)) owner = section.id;
+	return owner;
+}
+function scanTabGroups(root, sections, isVisible = isElementVisible) {
+	const seen = /* @__PURE__ */ new Set();
+	const found = [];
+	for (const adapter of TAB_ADAPTERS) for (const list of root.querySelectorAll(adapter.list)) {
+		if (seen.has(list)) continue;
+		seen.add(list);
+		if (isAriaHidden(list) || !isVisible(list)) continue;
+		found.push({
+			list,
+			adapter
+		});
+	}
+	found.sort((a, b) => a.list.compareDocumentPosition(b.list) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1);
+	const groups = [];
+	for (const { list, adapter } of found) {
+		const tabs = Array.from(list.querySelectorAll(adapter.tab)).filter((tab) => tab.closest(adapter.list) === list && isVisible(tab)).map((el) => ({
+			el,
+			text: tabText(el),
+			active: adapter.isActive(el),
+			disabled: adapter.isDisabled(el)
+		})).filter((tab) => tab.text);
+		if (tabs.length < 2) continue;
+		const id = `g${groups.length + 1}`;
+		groups.push({
+			id,
+			label: normalizeText(list.getAttribute("aria-label")),
+			ownerSectionId: findOwnerSection(list, sections),
+			list,
+			tabs: tabs.slice(0, 12).map((tab, i) => ({
+				...tab,
+				id: `${id}-${i + 1}`
+			}))
+		});
+		if (groups.length >= 10) break;
+	}
+	return groups;
+}
+
+//#endregion
+//#region src/tour/outline.ts
+/**
+* 页面大纲：模块 + Tab 组的一次扫描结果，以及提供给模型的精简文本。
+* 文本追加到每一步的按页提示，模型据此在一次 present_page 调用中给出全部讲解词。
+*/
+const EMPTY_OUTLINE = {
+	overview: null,
+	sections: [],
+	tabGroups: []
+};
+function scanPageOutline(root, isVisible = isElementVisible) {
+	if (!root) return EMPTY_OUTLINE;
+	const { overview, sections } = scanPageSections(root, isVisible);
+	return {
+		overview,
+		sections,
+		tabGroups: scanTabGroups(root, sections, isVisible)
+	};
+}
+/** 没有可指向模块时给模型的说明：避免按屏幕内容自拟模块名导致全部跳过 */
+const EMPTY_SECTIONS_HINT = "（未识别到可指向的模块：介绍页面时 sections 传空数组，只用 intro 讲解页面概述，不要自拟模块名）";
+/** 存在嵌套模块时的说明：父模块已覆盖子模块内容，避免重复讲解 */
+const NESTED_HINT = "（缩进的是所属模块内的子模块：讲了所属模块后，子模块只在有额外内容时再单独讲，避免重复）";
+/**
+* 大纲文本；没有概述、模块与 Tab 组时返回空串（不追加到提示）。
+* 子模块按层级缩进；同名模块标注序号，便于模型区分（如多个「数据列表」）。
+*/
+function formatOutline(outline) {
+	const { overview, sections, tabGroups } = outline;
+	if (!overview && !sections.length && !tabGroups.length) return "";
+	const lines = [`## 页面模块（介绍页面时用 ${PRESENT_PAGE_TOOL_NAME} 按编号讲解）`];
+	if (overview) lines.push(`页面概述：「${overview.name}」${overview.desc}`);
+	if (sections.length) {
+		const nameTotals = /* @__PURE__ */ new Map();
+		for (const s of sections) nameTotals.set(s.name, (nameTotals.get(s.name) ?? 0) + 1);
+		const nameSeen = /* @__PURE__ */ new Map();
+		const depth = /* @__PURE__ */ new Map();
+		for (const s of sections) {
+			const level = s.parentId ? (depth.get(s.parentId) ?? 0) + 1 : 0;
+			depth.set(s.id, level);
+			const nth = (nameSeen.get(s.name) ?? 0) + 1;
+			nameSeen.set(s.name, nth);
+			const dup = (nameTotals.get(s.name) ?? 0) > 1 ? `（同名第 ${nth} 个）` : "";
+			lines.push(`${"  ".repeat(level)}- ${s.id} 「${s.name}」${dup}${s.desc ? ` ${s.desc}` : ""}`);
+		}
+		if (sections.some((s) => s.parentId)) lines.push(NESTED_HINT);
+	} else lines.push(EMPTY_SECTIONS_HINT);
+	if (tabGroups.length) {
+		lines.push("## 页面 Tab（g 为 Tab 组编号，* 为当前 Tab）");
+		for (const g of tabGroups) {
+			const label = g.label ? `「${g.label}」` : "";
+			const owner = g.ownerSectionId ? `（属于 ${g.ownerSectionId}）` : "（页面级）";
+			const tabs = g.tabs.map((t) => `${t.active ? "*" : ""}${t.id}「${t.text}」${t.disabled ? "（禁用）" : ""}`).join(" / ");
+			lines.push(`- ${g.id}${label}${owner}: ${tabs}`);
+		}
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+//#region src/tour/presentTool.ts
+/**
+* 页面讲解控制器：维护提供给模型的页面大纲，并提供 present_page 工具。
+*
+* 一次讲解可由多次工具调用组成：每轮讲当前可见的模块，带 next_tab 时讲完切换 Tab 并返回新大纲；
+* 不带 next_tab 的一轮为结束轮，切回讲解中切换过的 Tab。除切换已识别的 Tab 外不点击任何元素。
+* 光标、点击动画经 page-agent SimulatorMask 监听的窗口事件驱动；用户关闭蒙层时由工具临时创建蒙层。
+*/
+/** 讲解词最大长度：培训风格每段需要二到四句，超出由模型精简 */
+const TOUR_SPEECH_MAX_CHARS = 300;
+/** 滚动后等待平滑滚动结束的时间（ms） */
+const SCROLL_SETTLE_MS = 400;
+/** 派发光标移动后等待光标动画到位的时间（ms），与 page-agent 点击前的等待一致 */
+const POINTER_SETTLE_MS = 300;
+/** 切换 Tab 后判定渲染稳定：连续该时长无 DOM 变化（ms） */
+const DOM_SETTLE_IDLE_MS = 300;
+/** 切换 Tab 后等待渲染稳定的上限（ms）；超时仍继续扫描 */
+const DOM_SETTLE_MAX_MS = 3e3;
+/** page-agent SimulatorMask 监听的窗口事件 */
+const MOVE_POINTER_EVENT = "PageAgent::MovePointerTo";
+const CLICK_POINTER_EVENT = "PageAgent::ClickPointer";
+function abortError() {
+	const error = /* @__PURE__ */ new Error("Task aborted");
+	error.name = "AbortError";
+	return error;
+}
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw abortError();
+}
+function sleep(ms, signal) {
+	if (ms <= 0 || signal?.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const finish = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", finish);
+			resolve();
+		};
+		const timer = setTimeout(finish, ms);
+		signal?.addEventListener("abort", finish, { once: true });
+	});
+}
+/** 连续 DOM_SETTLE_IDLE_MS 无变化或达到 DOM_SETTLE_MAX_MS 时 resolve；中止时立即 resolve */
+function waitForDomSettled(root, signal) {
+	if (!root || signal?.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		let idleTimer;
+		const finish = () => {
+			clearTimeout(idleTimer);
+			clearTimeout(maxTimer);
+			observer.disconnect();
+			signal?.removeEventListener("abort", finish);
+			resolve();
+		};
+		const resetIdle = () => {
+			clearTimeout(idleTimer);
+			idleTimer = setTimeout(finish, 300);
+		};
+		const observer = new MutationObserver(resetIdle);
+		observer.observe(root, {
+			subtree: true,
+			childList: true,
+			attributes: true,
+			characterData: true
+		});
+		const maxTimer = setTimeout(finish, DOM_SETTLE_MAX_MS);
+		signal?.addEventListener("abort", finish, { once: true });
+		resetIdle();
+	});
+}
+function movePointerTo(el) {
+	const rect = el.getBoundingClientRect();
+	window.dispatchEvent(new CustomEvent(MOVE_POINTER_EVENT, { detail: {
+		x: rect.left + rect.width / 2,
+		y: rect.top + rect.height / 2
+	} }));
+}
+/** 不在视口内时滚动到可见；返回是否发生滚动。高于视口的模块对齐顶部，否则居中 */
+function scrollIntoViewIfNeeded(el) {
+	const rect = el.getBoundingClientRect();
+	const viewport = window.innerHeight || document.documentElement.clientHeight;
+	if (rect.top >= 0 && rect.bottom <= viewport) return false;
+	el.scrollIntoView?.({
+		block: rect.height > viewport ? "start" : "center",
+		behavior: "smooth"
+	});
+	return true;
+}
+function describeTab(tab) {
+	return `「${tab.text}」`;
+}
+function buildDescription(maxTabSwitches) {
+	return [
+		"页面讲解：按编号依次把光标移到页面模块并语音讲解，只移动光标，不点击模块内容。",
+		"- 调用条件：用户明确要求介绍、讲解、演示页面或页面功能时调用。",
+		"- 以下情况不调用：打开或进入页面、查找、查询、填写、筛选等操作类指令；询问具体数据或某个字段含义时，读取页面后在 done 中以文字回答；无法确定用户是否要求讲解时，按原方式以文字回答。",
+		"- 指令同时包含导航与讲解（如「打开某页面并介绍一下」）时，先导航到目标页面并确认到达，再调用。",
+		"- sections：按讲解顺序列出按页提示「页面模块」中的编号，并为每个模块写一两句面向演示观众的讲解词，说明模块用途和能看到的内容；不编造具体数值，不包含编号。",
+		"- intro：本轮开场，可省略。首轮可概述页面，后续轮次可写切换 Tab 后的过渡语。",
+		"- 页面有 Tab 时逐轮调用：每轮只讲当前 Tab 下可见的模块，用 next_tab 指定下一个要切换的 Tab 编号。按深度优先顺序：先讲完当前 Tab 内的子 Tab，再切换同级的下一个 Tab。工具会返回切换后的模块清单，据此继续下一轮。",
+		`- 单次讲解最多切换 ${maxTabSwitches} 次 Tab，其余 Tab 在讲解词中概括说明。`,
+		"- 最后一轮不传 next_tab，工具会恢复讲解开始时的 Tab；之后调用 done 简短收尾，不重复讲解内容。",
+		"- 称呼保持通用（如「大家好」），不要假定听众身份（如「各位学员」「同学们」）。",
+		"- 按页提示中的「讲解风格」决定讲解的受众、侧重点和详略（用户未选择风格时该处为默认风格）；用户指令中另有讲解要求（如面向新员工、侧重操作步骤）时，以用户指令为准。",
+		"- 页面没有可指向的模块时，sections 传空数组，只用 intro 讲解页面概述，不要自拟模块名。"
+	].join("\n");
+}
+function createPageTour(deps) {
+	const scan = deps.scan ?? scanPageOutline;
+	const narrateText = deps.narrate ?? narrate;
+	const click = deps.click ?? clickElement;
+	const wait = deps.sleep ?? sleep;
+	const settle = deps.waitForDomSettled ?? waitForDomSettled;
+	let outline = EMPTY_OUTLINE;
+	let switchCount = 0;
+	let initialTabs = [];
+	let maskForced = false;
+	/** 任务级中止信号（page-agent 每个任务一个，传给该任务内的所有工具调用） */
+	let taskSignal;
+	const rescan = () => scan(deps.getContentRoot());
+	function styleText() {
+		const style = deps.getStyle?.();
+		if (!style) return "";
+		return `## 讲解风格：${style.label}（介绍页面时使用）\n${style.prompt}`;
+	}
+	function outlineText() {
+		try {
+			outline = rescan();
+		} catch (err) {
+			console.warn("[PageUse] 页面模块识别异常", err);
+			outline = EMPTY_OUTLINE;
+		}
+		const text = formatOutline(outline);
+		const style = text ? styleText() : "";
+		return style ? `${text}\n${style}` : text;
+	}
+	/**
+	* 解析模块：按编号，模型误传模块名时按名称（同名取第一个）。
+	* 元素已被替换时重新扫描，按「名称 + 同名序号」匹配，避免多个同名模块（如多个「数据列表」）错位。
+	*/
+	function resolveSection(key) {
+		const list = outline.sections;
+		const known = list.find((s) => s.id === key) ?? list.find((s) => s.name === key);
+		if (!known) return null;
+		if (known.root.isConnected && known.anchor.isConnected) return {
+			id: known.id,
+			section: known
+		};
+		const nth = list.filter((s) => s.name === known.name).indexOf(known);
+		const fresh = rescan().sections.filter((s) => s.name === known.name)[nth];
+		return fresh ? {
+			id: known.id,
+			section: fresh
+		} : null;
+	}
+	/** 按编号解析 Tab；元素已被替换时按「组 label + Tab 文本」匹配 */
+	function resolveTab(id) {
+		for (const group of outline.tabGroups) {
+			const tab = group.tabs.find((t) => t.id === id);
+			if (!tab) continue;
+			if (tab.el.isConnected) return {
+				group,
+				tab
+			};
+			for (const freshGroup of rescan().tabGroups) {
+				if (freshGroup.label !== group.label) continue;
+				const freshTab = freshGroup.tabs.find((t) => t.text === tab.text);
+				if (freshTab) return {
+					group: freshGroup,
+					tab: freshTab
+				};
+			}
+			return null;
+		}
+		return null;
+	}
+	async function ensureMask(agent) {
+		if (deps.maskEnabled || maskForced) return;
+		maskForced = true;
+		agent.pageController.initMask();
+		await agent.pageController.showMask();
+		deps.onMaskForced?.();
+	}
+	/** 光标移到 Tab、播放点击动画并点击，等待渲染稳定 */
+	async function clickTab(el, signal) {
+		if (scrollIntoViewIfNeeded(el)) await wait(400, signal);
+		throwIfAborted(signal);
+		movePointerTo(el);
+		await wait(300, signal);
+		throwIfAborted(signal);
+		window.dispatchEvent(new CustomEvent(CLICK_POINTER_EVENT));
+		await click(el);
+		await settle(deps.getContentRoot(), signal);
+	}
+	/** 按记录的逆序切回：先恢复后切换的组（外层 Tab 或当前 Tab 内的子 Tab），已不存在的组跳过 */
+	async function restoreTabs(signal) {
+		const restored = [];
+		const pending = initialTabs;
+		initialTabs = [];
+		for (const initial of [...pending].reverse()) {
+			throwIfAborted(signal);
+			const groups = rescan().tabGroups;
+			const tab = (groups.find((g) => g.list === initial.list) ?? (initial.label ? groups.find((g) => g.label === initial.label) : void 0))?.tabs.find((t) => t.text === initial.text);
+			if (!tab || tab.active) continue;
+			await clickTab(tab.el, signal);
+			restored.push(describeTab(tab));
+		}
+		return restored;
+	}
+	async function presentSections(items, signal) {
+		const done = [];
+		const skipped = [];
+		for (const item of items) {
+			throwIfAborted(signal);
+			const resolved = resolveSection(item.id);
+			if (!resolved) {
+				skipped.push(item.id);
+				continue;
+			}
+			const { section } = resolved;
+			if (scrollIntoViewIfNeeded(section.root)) await wait(400, signal);
+			throwIfAborted(signal);
+			movePointerTo(section.anchor);
+			await wait(300, signal);
+			throwIfAborted(signal);
+			showTourHighlight(section.root);
+			await narrateText(item.speech, signal);
+			hideTourHighlight();
+			throwIfAborted(signal);
+			done.push(`${resolved.id}「${section.name}」`);
+		}
+		return {
+			done,
+			skipped
+		};
+	}
+	/** 校验并切换 Tab；返回结果说明（含新大纲），不满足条件时返回原因且不点击 */
+	async function switchTab(id, signal) {
+		const target = resolveTab(id);
+		if (!target) return `未切换 Tab：${id} 不在当前 Tab 清单中。`;
+		const { group, tab } = target;
+		if (tab.disabled) return `未切换 Tab：${describeTab(tab)}已禁用。`;
+		if (tab.active) return `未切换 Tab：${describeTab(tab)}已是当前 Tab。`;
+		if (switchCount >= deps.maxTabSwitches) return `未切换 Tab：已达到单次讲解的切换上限（${deps.maxTabSwitches} 次），请在讲解词中概括其余 Tab，并以不带 next_tab 的调用结束讲解。`;
+		const active = group.tabs.find((t) => t.active);
+		if (active && !initialTabs.some((t) => t.list === group.list)) initialTabs.push({
+			list: group.list,
+			label: group.label,
+			text: active.text
+		});
+		await clickTab(tab.el, signal);
+		switchCount += 1;
+		outlineText();
+		const text = formatOutline(outline) || "（切换后未识别到模块）";
+		return `已切换到 Tab ${describeTab(tab)}。以下为切换后的页面模块，请继续讲解：\n${text}`;
+	}
+	return {
+		outlineText,
+		tool: tool({
+			description: buildDescription(deps.maxTabSwitches),
+			inputSchema: z.object({
+				intro: z.string().max(300).optional().describe("本轮开场讲解词，可省略"),
+				sections: z.array(z.object({
+					id: z.string().describe("模块编号，如 s1"),
+					speech: z.string().min(1).max(300).describe("该模块的讲解词")
+				})).max(20).describe("按讲解顺序排列的模块"),
+				next_tab: z.string().optional().describe("讲完本轮后切换到的 Tab 编号，如 g1-2；最后一轮不传")
+			}),
+			async execute(input, ctx) {
+				const { signal } = ctx;
+				taskSignal = signal;
+				try {
+					await ensureMask(this);
+					throwIfAborted(signal);
+					if (input.intro?.trim()) {
+						const overview = outline.overview?.anchor;
+						if (overview?.isConnected) {
+							movePointerTo(overview);
+							await wait(300, signal);
+							throwIfAborted(signal);
+						}
+						await narrateText(input.intro, signal);
+					}
+					const { done, skipped } = await presentSections(input.sections, signal);
+					const lines = [done.length ? `已讲解：${done.join("、")}。` : "本轮未讲解模块。"];
+					if (skipped.length) lines.push(outline.sections.length ? `跳过：${skipped.join("、")}（不在当前模块清单中，请只使用清单中的编号，如 s1）。` : `跳过：${skipped.join("、")}。本页没有可指向的模块，不要自拟模块名；如需讲解，只用 intro 讲解页面概述。`);
+					if (input.next_tab) lines.push(await switchTab(input.next_tab, signal));
+					else {
+						const restored = await restoreTabs(signal);
+						lines.push(restored.length ? `讲解结束，已恢复初始 Tab ${restored.join("、")}。` : "讲解结束。", "请调用 done 简短收尾，不要重复讲解内容。");
+					}
+					throwIfAborted(signal);
+					return lines.join("\n");
+				} finally {
+					hideTourHighlight();
+				}
+			}
+		}),
+		onBeforeTask() {
+			switchCount = 0;
+			initialTabs = [];
+			taskSignal = void 0;
+		},
+		async onAfterTask() {
+			if (!initialTabs.length || taskSignal?.aborted) {
+				initialTabs = [];
+				return;
+			}
+			try {
+				await restoreTabs();
+			} catch (err) {
+				console.warn("[PageUse] 讲解结束后恢复 Tab 失败", err);
+			}
+		}
+	};
+}
 
 //#endregion
 //#region src/core/siteMap.ts
@@ -888,9 +1686,10 @@ function buildSystemInstruction(options, flags = {}) {
 }
 /**
 * 按页提示：page-agent 每步调用一次。
-* 路由名命中 routeHints 优先，其次按路径命中；返回 null 表示不追加。
+* 路由名命中 routeHints 优先，其次按路径命中；outlineText（页面讲解的模块清单）追加在末尾。
+* 返回 null 表示不追加。
 */
-function buildPageInstruction(options) {
+function buildPageInstruction(options, outlineText = "") {
 	const path = options.getCurrentPath();
 	const parts = [];
 	const menu = findMenuByPath(path, options.getMenus());
@@ -903,6 +1702,7 @@ function buildPageInstruction(options) {
 	}
 	const hint = routeName && options.routeHints[routeName] || options.routeHints[normalizePath(path)];
 	if (hint) parts.push(hint);
+	if (outlineText) parts.push(outlineText);
 	return parts.length ? parts.join("\n") : null;
 }
 
@@ -913,6 +1713,7 @@ function buildPageInstruction(options) {
 * - LLM：浏览器请求 OpenAI 兼容端点，参数来自宿主选项
 * - 站点知识：菜单树写入 system 提示，按页提示按当前路径动态注入
 * - 任务开始前按设置执行宿主的 beforeTask（如展开折叠的侧栏）
+* - 页面讲解：按页提示附带页面模块清单，并注册 present_page 工具（pageTour 关闭时均不启用）
 */
 /** DOM 文本超过该长度时截断，避免大表格页把上下文撑爆 */
 const PAGE_CONTENT_MAX_CHARS = 6e4;
@@ -922,7 +1723,7 @@ const STEP_DELAY_SECONDS = .6;
 function newSessionId() {
 	return typeof crypto !== "undefined" && crypto.randomUUID?.() || `page-use-${Date.now()}`;
 }
-function createPageUseAgent({ options, enableMask, narration = false, shouldRunBeforeTask, onTaskFinished }) {
+function createPageUseAgent({ options, enableMask, narration = false, shouldRunBeforeTask, onTaskFinished, onMaskForced, getTourStyle }) {
 	const { llm } = options;
 	if (!llm.baseURL) throw new Error("[PageUse] 未配置 llm.baseURL");
 	let sessionId = newSessionId();
@@ -940,6 +1741,14 @@ function createPageUseAgent({ options, enableMask, narration = false, shouldRunB
 	} : void 0;
 	const extraBody = llm.extraBody;
 	const hostBeforeTask = options.beforeTask;
+	const hostPageAgent = options.pageAgentOptions;
+	const tour = options.pageTour.enabled ? createPageTour({
+		getContentRoot: options.getContentRoot,
+		maxTabSwitches: options.pageTour.maxTabSwitches,
+		maskEnabled: enableMask,
+		onMaskForced,
+		getStyle: getTourStyle
+	}) : null;
 	return new PageAgent({
 		baseURL: llm.baseURL,
 		apiKey: llm.apiKey || void 0,
@@ -958,25 +1767,31 @@ function createPageUseAgent({ options, enableMask, narration = false, shouldRunB
 		experimentalScriptExecutionTool: false,
 		instructions: {
 			system: buildSystemInstruction(options, { narration }),
-			getPageInstructions: () => buildPageInstruction(options)
+			getPageInstructions: () => buildPageInstruction(options, tour?.outlineText() ?? "")
 		},
 		transformPageContent: (content) => {
 			if (content.length <= PAGE_CONTENT_MAX_CHARS) return content;
 			return `${content.slice(0, PAGE_CONTENT_MAX_CHARS)}\n...（页面内容过长已截断，可滚动后再观察）`;
 		},
-		...options.pageAgentOptions,
+		...hostPageAgent,
+		customTools: {
+			...tour ? { [PRESENT_PAGE_TOOL_NAME]: tour.tool } : {},
+			...hostPageAgent.customTools
+		},
 		onBeforeTask: async (...args) => {
 			sessionId = newSessionId();
+			tour?.onBeforeTask();
 			if (hostBeforeTask && shouldRunBeforeTask()) try {
 				await hostBeforeTask();
 			} catch (err) {
 				console.warn("[PageUse] beforeTask 执行异常", err);
 			}
-			await options.pageAgentOptions.onBeforeTask?.(...args);
+			await hostPageAgent.onBeforeTask?.(...args);
 		},
 		onAfterTask: async (...args) => {
+			await tour?.onAfterTask(args[1]);
 			onTaskFinished?.(args[1]);
-			await options.pageAgentOptions.onAfterTask?.(...args);
+			await hostPageAgent.onAfterTask?.(...args);
 		}
 	});
 }
@@ -1060,19 +1875,37 @@ function storageKey(prefix) {
 function createId() {
 	return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
-/** 结构校验：丢弃缺少字符串 label / task 的项，缺 id 时补生成；hidden 只保留字符串并去重 */
+/** 讲解风格 key 去除首尾空白；非字符串或空白视为未指定（跟随面板设置），返回 undefined */
+function normalizeTourStyle(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+/** 保存用的规范化结果：label / task 去除首尾空白；未指定讲解风格时不出现 tourStyle 键 */
+function normalize(preset) {
+	const tourStyle = normalizeTourStyle(preset.tourStyle);
+	return {
+		label: preset.label.trim(),
+		task: preset.task.trim(),
+		...tourStyle ? { tourStyle } : {}
+	};
+}
+/**
+* 结构校验：丢弃缺少字符串 label / task 的项，缺 id 时补生成；
+* tourStyle 非字符串或空白时只丢弃该字段，指令本身保留；hidden 只保留字符串并去重
+*/
 function sanitize(raw) {
 	if (!raw || typeof raw !== "object") return { ...EMPTY_STATE };
 	const { custom, hidden } = raw;
 	return {
 		custom: (Array.isArray(custom) ? custom : []).flatMap((item) => {
 			if (!item || typeof item !== "object") return [];
-			const { id, label, task } = item;
+			const { id, label, task, tourStyle } = item;
 			if (typeof label !== "string" || typeof task !== "string") return [];
+			const style = normalizeTourStyle(tourStyle);
 			return [{
 				id: typeof id === "string" && id ? id : createId(),
 				label,
-				task
+				task,
+				...style ? { tourStyle: style } : {}
 			}];
 		}),
 		hidden: Array.isArray(hidden) ? [...new Set(hidden.filter((item) => typeof item === "string"))] : []
@@ -1099,7 +1932,10 @@ function persist(patch) {
 		window.localStorage.setItem(storageKey(prefix), JSON.stringify(current.get()));
 	} catch {}
 }
-/** 必填与重复校验；excludeId 为编辑中的自身，与自身相同不算重复 */
+/**
+* 必填与重复校验；excludeId 为编辑中的自身，与自身相同不算重复。
+* 重复按 task + 讲解风格组合判断：同一指令可按不同风格各存一条，未指定风格以空串参与比较
+*/
 function validate(preset, excludeId) {
 	if (!preset.label.trim()) return {
 		ok: false,
@@ -1110,7 +1946,8 @@ function validate(preset, excludeId) {
 		ok: false,
 		reason: "task-empty"
 	};
-	return ensureStore().get().custom.some((item) => item.id !== excludeId && item.task.trim() === task) ? {
+	const tourStyle = normalizeTourStyle(preset.tourStyle) ?? "";
+	return ensureStore().get().custom.some((item) => item.id !== excludeId && item.task.trim() === task && (item.tourStyle ?? "") === tourStyle) ? {
 		ok: false,
 		reason: "duplicate"
 	} : { ok: true };
@@ -1129,18 +1966,17 @@ const pageUsePresets = {
 	get() {
 		return ensureStore().get();
 	},
-	/** 新增自定义指令，排在最前；label / task 去除首尾空白后保存 */
+	/** 新增自定义指令，排在最前；label / task / tourStyle 去除首尾空白后保存 */
 	add(preset) {
 		const result = validate(preset);
 		if (!result.ok) return result;
 		persist({ custom: [{
 			id: createId(),
-			label: preset.label.trim(),
-			task: preset.task.trim()
+			...normalize(preset)
 		}, ...ensureStore().get().custom] });
 		return result;
 	},
-	/** 编辑自定义指令，位置不变 */
+	/** 编辑自定义指令，位置不变；整条替换，未传 tourStyle 即清除原风格 */
 	update(id, preset) {
 		const { custom } = ensureStore().get();
 		if (!custom.some((item) => item.id === id)) return {
@@ -1151,8 +1987,7 @@ const pageUsePresets = {
 		if (!result.ok) return result;
 		persist({ custom: custom.map((item) => item.id === id ? {
 			id,
-			label: preset.label.trim(),
-			task: preset.task.trim()
+			...normalize(preset)
 		} : item) });
 		return result;
 	},
@@ -1184,6 +2019,11 @@ function summarizeActionInput(name, input) {
 		case "wait": return `等待 ${record.seconds ?? 1} 秒`;
 		case "done": return record.success === false ? "结束任务（未达成）" : "结束任务";
 		case "ask_user": return "向用户提问";
+		case PRESENT_PAGE_TOOL_NAME: {
+			const count = Array.isArray(record.sections) ? record.sections.length : 0;
+			const base = count ? `讲解页面（${count} 个模块）` : "讲解页面";
+			return record.next_tab ? `${base}，随后切换 Tab` : base;
+		}
 		default: return name;
 	}
 }
@@ -1379,7 +2219,13 @@ function ensureAgent(options) {
 		options,
 		enableMask: settings.enableMask,
 		narration: settings.voiceEnabled,
-		shouldRunBeforeTask: () => pageUseSettings.get().enableBeforeTask
+		shouldRunBeforeTask: () => pageUseSettings.get().enableBeforeTask,
+		onMaskForced: () => {
+			if (agent !== created) return;
+			agentMaskFlag = null;
+			store.set({ maskEnabled: true });
+		},
+		getTourStyle: () => resolveTourStyle(options.pageTour.styles, activeOptions?.tourStyle, pageUseSettings.get().tourStyle, options.pageTour.defaultStyle)
 	});
 	bindAgentEvents(created);
 	created.onAskUser = (question, askOptions) => handleAskUser(question, askOptions?.signal);
@@ -2058,7 +2904,7 @@ var PageUseGlowElement = class extends LitElement {
 
 //#endregion
 //#region package.json
-var version = "0.0.5";
+var version = "0.0.7";
 
 //#endregion
 //#region src/ui/drag.ts
@@ -2215,21 +3061,10 @@ const robotIcon = html`${unsafeHTML(PAGE_USE_ROBOT_ICON_SVG)}`;
 
 //#endregion
 //#region src/ui/presets.ts
-/** 通用示例：不依赖具体站点，覆盖详情、标签、返回等典型操作 */
-const PAGE_USE_STATIC_PRESETS = [
-	{
-		label: "看第一条详情",
-		task: "在当前列表页打开第一条记录的详情"
-	},
-	{
-		label: "切到下一个标签",
-		task: "切换到当前页面的下一个标签页"
-	},
-	{
-		label: "总结当前页",
-		task: "概括当前页面展示的主要内容与可执行的操作"
-	}
-];
+/**
+* 通用示例：预留。
+*/
+const PAGE_USE_STATIC_PRESETS = [];
 /**
 * 取前 N 个可见叶子菜单，生成「打开 XX」快捷指令。
 * exclude 中的 task 被跳过且不占名额，由后续菜单补位（用户隐藏菜单指令时使用）。
@@ -2260,12 +3095,13 @@ function resolvePresetGroups(input) {
 	const visible = (list) => (list || []).filter((preset) => !hidden.has(preset.task));
 	const limit = input.menuPresetLimit;
 	const menu = limit > 0 ? buildMenuPresets(input.menus, limit, hidden) : [];
-	const builtin = visible(PAGE_USE_STATIC_PRESETS);
+	const builtinSource = input.builtinPresets === false ? [] : PAGE_USE_STATIC_PRESETS;
+	const builtin = visible(builtinSource);
 	const host = visible(input.presets);
 	const scenarios = visible(input.scenarios);
 	const allSourceTasks = new Set([
 		...limit > 0 ? buildMenuPresets(input.menus, Number.POSITIVE_INFINITY) : [],
-		...PAGE_USE_STATIC_PRESETS,
+		...builtinSource,
 		...input.presets || [],
 		...input.scenarios || []
 	].map((preset) => preset.task));
@@ -2922,13 +3758,6 @@ const launcherStyles = css`
     border-radius: 0 0 10px 10px;
     background: rgba(250, 251, 252, 0.5);
   }
-  /* 悬浮在输入区上沿（以 .composer 为定位参照） */
-  .jump-latest {
-    position: absolute;
-    right: 16px;
-    bottom: calc(100% + 8px);
-    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-  }
   .input,
   .textarea {
     width: 100%;
@@ -3070,6 +3899,15 @@ const launcherStyles = css`
     color: var(--text-3);
     font-size: 12px;
   }
+  .field-hint {
+    color: var(--text-3);
+    font-size: 11px;
+    line-height: 1.5;
+  }
+  /* 讲解风格：与复选框文字、播报选项输入框左对齐（同 21px 缩进） */
+  .tour-style-field {
+    margin-left: 21px;
+  }
   .range {
     width: 100%;
     margin: 0;
@@ -3220,7 +4058,7 @@ const PARENT_VIEW = {
 const PRESET_SAVE_ERRORS = {
 	"label-empty": "请填写名称",
 	"task-empty": "请填写指令内容",
-	duplicate: "已存在指令内容相同的自定义指令",
+	duplicate: "已存在相同的自定义指令",
 	"not-found": "该指令已被删除，请重新新增"
 };
 /** 播报语速倍率的调节范围与步长（1 为正常语速，过快或过慢时中文语音难以听清；注入引擎自行换算为服务参数） */
@@ -3273,12 +4111,12 @@ var PageUseLauncherElement = class extends LitElement {
 	toastTimer = null;
 	/**
 	* 日志区跟随滚动：默认贴底跟随新内容；用户上翻后停止跟随，
-	* 回到底部附近（阈值内）或点击「最新」后恢复。
+	* 回到底部附近（阈值内）后恢复。
 	*/
 	stickToBottom = true;
 	/** 上次渲染时日志内容的摘要；仅内容变化时才贴底，避免每秒的耗时刷新把用户拉回底部 */
 	logSignature = "";
-	/** 下次渲染强制滚到底部（点击「最新」、任务开始） */
+	/** 下次渲染强制滚到底部（任务开始） */
 	forceScroll = false;
 	/**
 	* 入口尺寸缓存：入口在面板展开时被隐藏，offsetWidth 为 0，
@@ -3598,16 +4436,20 @@ var PageUseLauncherElement = class extends LitElement {
 		this.measureFab();
 		this.fabDrag.reclamp();
 	}
-	async submit() {
+	/** tourStyle：快捷指令携带的讲解风格；输入框提交时不传，按面板设置与宿主默认 */
+	async submit(tourStyle) {
 		const text = this.task.trim();
 		if (isRunning() || !text) return;
 		this.task = "";
 		this.requestUpdate();
-		await runTask(text, { source: LAUNCHER_SOURCE });
+		await runTask(text, {
+			source: LAUNCHER_SOURCE,
+			...tourStyle ? { tourStyle } : {}
+		});
 	}
-	applyPreset(text) {
+	applyPreset(text, tourStyle) {
 		this.task = text;
-		this.submit();
+		this.submit(tourStyle);
 	}
 	lastTaskText(state) {
 		return state.currentTask || pageUseHistory.entries()[0]?.task || "";
@@ -3644,23 +4486,18 @@ var PageUseLauncherElement = class extends LitElement {
 	onLogScroll(event) {
 		const el = event.target;
 		const stick = el.scrollHeight - el.scrollTop - el.clientHeight < STICK_THRESHOLD;
-		if (stick === this.stickToBottom) return;
 		this.stickToBottom = stick;
-		this.requestUpdate();
 	}
 	/**
 	* 滚轮上翻立即停止跟随：平滑滚动的首个 scroll 事件位移可能小于阈值，
 	* 若此时仍判定为贴底，内容刷新会把视图拉回底部，表现为上翻时抖动。
+	* 内容不足一屏（或已在顶部）时无法上翻，也不会触发 scroll 事件来恢复跟随，
+	* 因此 scrollTop 为 0 时忽略，否则后续内容增长时不再贴底。
 	*/
 	onLogWheel(event) {
 		if (event.deltaY >= 0 || !this.stickToBottom) return;
+		if (event.currentTarget.scrollTop <= 0) return;
 		this.stickToBottom = false;
-		this.requestUpdate();
-	}
-	scrollLogToBottom() {
-		this.stickToBottom = true;
-		this.forceScroll = true;
-		this.requestUpdate();
 	}
 	toggleTray(kind) {
 		this.tray = this.tray === kind ? null : kind;
@@ -3685,6 +4522,7 @@ var PageUseLauncherElement = class extends LitElement {
 		return resolvePresetGroups({
 			menus: getPageUseConfig()?.getMenus(),
 			menuPresetLimit: this._config.menuPresetLimit ?? 6,
+			builtinPresets: this._config.builtinPresets,
 			presets: this._config.presets,
 			scenarios: this._config.scenarios,
 			state: pageUsePresets.get()
@@ -3695,7 +4533,7 @@ var PageUseLauncherElement = class extends LitElement {
         type="button"
         class="btn tiny round secondary ${accent ? "accent" : ""}"
         title=${preset.task}
-        @click=${() => this.applyPreset(preset.task)}
+        @click=${() => this.applyPreset(preset.task, preset.tourStyle)}
       >
         ${preset.label}
       </button>`);
@@ -3750,6 +4588,7 @@ var PageUseLauncherElement = class extends LitElement {
         ${config?.beforeTask ? this.renderCheckbox("enableBeforeTask", config.beforeTaskLabel) : nothing}
         ${this.renderCheckbox("showStepDetails", "步骤显示模型思考与返回")}
         ${this.renderVoiceSettings(settings)}
+        ${config?.pageTour.enabled ? this.renderTourStyleSetting(settings, config) : nothing}
         <div class="row settings-actions">
           <button type="button" class="btn" @click=${() => pageUseSettings.resetPositions()}>
             复位窗口
@@ -3771,6 +4610,7 @@ var PageUseLauncherElement = class extends LitElement {
 			id,
 			label: item?.label ?? "",
 			task: item?.task ?? "",
+			tourStyle: item?.tourStyle ?? "",
 			error: ""
 		};
 		this.requestUpdate();
@@ -3780,7 +4620,8 @@ var PageUseLauncherElement = class extends LitElement {
 		if (!draft) return;
 		const preset = {
 			label: draft.label,
-			task: draft.task
+			task: draft.task,
+			tourStyle: draft.tourStyle
 		};
 		const result = draft.id === null ? pageUsePresets.add(preset) : pageUsePresets.update(draft.id, preset);
 		this.presetDraft = result.ok ? null : {
@@ -3808,6 +4649,7 @@ var PageUseLauncherElement = class extends LitElement {
 			draft.task = e.target.value;
 		}}
       ></textarea>
+      ${this.renderPresetTourStyle(draft)}
       ${draft.error ? html`<div class="alert error preset-error">${draft.error}</div>` : nothing}
       <div class="row preset-form-actions">
         <button
@@ -3825,6 +4667,32 @@ var PageUseLauncherElement = class extends LitElement {
         </button>
       </div>
     </div>`;
+	}
+	/**
+	* 表单中的讲解风格（可选）：仅页面讲解启用时显示，选项与设置页一致。
+	* 已保存的 key 不在当前风格列表中（宿主移除了该风格）时追加「已失效」项并选中，
+	* 不改选直接保存会保留原值；执行时由 resolveTourStyle 回退到面板设置与宿主默认
+	*/
+	renderPresetTourStyle(draft) {
+		const config = getPageUseConfig();
+		if (!config?.pageTour.enabled) return nothing;
+		const { styles } = config.pageTour;
+		const stale = draft.tourStyle && !styles.some((style) => style.key === draft.tourStyle);
+		return html`<label class="field preset-tour-style">
+      <span class="field-label">讲解风格</span>
+      <select
+        class="input preset-tour-style-select"
+        @change=${(e) => {
+			draft.tourStyle = e.target.value;
+		}}
+      >
+        <option value="" ?selected=${!draft.tourStyle}>跟随面板设置</option>
+        ${styles.map((style) => html`<option value=${style.key} ?selected=${style.key === draft.tourStyle}>
+              ${style.label}
+            </option>`)}
+        ${stale ? html`<option value=${draft.tourStyle} selected>已失效（${draft.tourStyle}）</option>` : nothing}
+      </select>
+    </label>`;
 	}
 	/** 列表项：名称一行，指令内容灰色单行省略（悬停查看全文），右侧为操作按钮 */
 	renderPresetItem(preset, actions) {
@@ -3906,6 +4774,24 @@ var PageUseLauncherElement = class extends LitElement {
 	* 演示播报：总开关关闭时只显示开关；开启后依次为引擎下拉（可选引擎多于一个时）、
 	* 语速、音色下拉与试听按钮（无音色列表时只有试听按钮）、不可用 / 无中文语音提示。
 	*/
+	/** 页面讲解风格：面板中未指定风格的讲解任务使用；快捷指令携带的风格优先 */
+	renderTourStyleSetting(settings, config) {
+		const { styles, defaultStyle } = config.pageTour;
+		const defaultLabel = styles.find((style) => style.key === defaultStyle)?.label ?? defaultStyle;
+		return html`<label class="field tour-style-field">
+      <span class="field-label">讲解风格</span>
+      <select
+        class="input tour-style-select"
+        @change=${(e) => pageUseSettings.update({ tourStyle: e.target.value })}
+      >
+        <option value="" ?selected=${!settings.tourStyle}>默认（${defaultLabel}）</option>
+        ${styles.map((style) => html`<option value=${style.key} ?selected=${style.key === settings.tourStyle}>
+              ${style.label}
+            </option>`)}
+      </select>
+      <span class="field-hint">用于「介绍当前页面」；也可以直接在指令中写明讲解要求，如「面向新员工介绍当前页面，侧重操作步骤」</span>
+    </label>`;
+	}
 	renderVoiceSettings(settings) {
 		const toggle = this.renderCheckbox("voiceEnabled", "语音播报", "演示时播报执行步骤、提问与结论");
 		if (!settings.voiceEnabled) return toggle;
@@ -3921,7 +4807,7 @@ var PageUseLauncherElement = class extends LitElement {
       type="button"
       class="btn preview-btn"
       ?disabled=${!available || running}
-      title=${running ? "任务执行中不可试听" : "用当前引擎、音色与语速试听"}
+      title=${running ? "任务执行中不可试听" : "按当前设置试听"}
       @click=${() => playing ? stopPreview() : startPreview(engine, {
 			rate: settings.voiceRate,
 			voice: voiceName
@@ -4086,13 +4972,6 @@ var PageUseLauncherElement = class extends LitElement {
 		const historyCount = pageUseHistory.entries().length;
 		const question = state.pendingQuestion;
 		return html`<footer class="composer">
-      ${!this.stickToBottom && !isLogEmpty ? html`<button
-            type="button"
-            class="btn tiny round jump-latest"
-            @click=${() => this.scrollLogToBottom()}
-          >
-            ↓ 最新
-          </button>` : nothing}
       ${question ? html`<div class="alert warning">
             <div class="alert-title">${question.question}</div>
             <div class="input-group">
@@ -4231,7 +5110,7 @@ var PageUseLauncherElement = class extends LitElement {
             <button
               type="button"
               class="icon-btn close"
-              title="关闭（可调用 showPageUseLauncher 或加 URL 参数 pageUseDebug=1 重新打开）"
+              title="关闭"
               @click=${() => this.close()}
             >
               ${closeIcon}
@@ -4282,4 +5161,4 @@ function mountPageUseUI(options = {}) {
 }
 
 //#endregion
-export { pageUseSettings as A, browserTtsEngine as B, getPageUseConfig as C, pageUsePresets as D, pageUseStore as E, normalizeOptions as F, readLauncherSwitch as I, PAGE_USE_MASK_COLORS as L, DEFAULT_MODEL as M, DEFAULT_SESSION_HEADER as N, pageUseHistory as O, DEFAULT_STORAGE_KEY_PREFIX as P, SIMULATOR_MASK_ID as R, getElapsedSeconds as S, isRunning as T, runPageUseTool as _, PAGE_USE_STATIC_PRESETS as a, pageUseCapability as b, PAGE_USE_GLOW_TAG as c, PAGE_USE_GLOBAL_KEY as d, PAGE_USE_COMMAND_TYPE as f, isPageUseCommand as g, formatPageUseResultForModel as h, PageUseLauncherElement as i, DEFAULT_MAX_STEPS as j, DEFAULT_PAGE_USE_SETTINGS as k, PageUseGlowElement as l, PAGE_USE_TOOL_NAME as m, mountPageUseUI as n, buildMenuPresets as o, PAGE_USE_TOOL as p, PAGE_USE_LAUNCHER_TAG as r, PAGE_USE_ROBOT_ICON_SVG as s, definePageUseElements as t, createPageUse as u, hidePageUseLauncher as v, isPageUseConfigured as w, clearPageUseLog as x, showPageUseLauncher as y, BROWSER_ENGINE_ID as z };
+export { pageUseSettings as A, BROWSER_ENGINE_ID as B, getPageUseConfig as C, pageUsePresets as D, pageUseStore as E, DEFAULT_TOUR_MAX_TAB_SWITCHES as F, DEFAULT_TOUR_STYLES as H, normalizeOptions as I, readLauncherSwitch as L, DEFAULT_MODEL as M, DEFAULT_SESSION_HEADER as N, pageUseHistory as O, DEFAULT_STORAGE_KEY_PREFIX as P, PAGE_USE_MASK_COLORS as R, getElapsedSeconds as S, isRunning as T, TOUR_STYLE_TRAINER as U, browserTtsEngine as V, TOUR_STYLE_USER as W, runPageUseTool as _, PAGE_USE_STATIC_PRESETS as a, pageUseCapability as b, PAGE_USE_GLOW_TAG as c, PAGE_USE_GLOBAL_KEY as d, PAGE_USE_COMMAND_TYPE as f, isPageUseCommand as g, formatPageUseResultForModel as h, PageUseLauncherElement as i, DEFAULT_MAX_STEPS as j, DEFAULT_PAGE_USE_SETTINGS as k, PageUseGlowElement as l, PAGE_USE_TOOL_NAME as m, mountPageUseUI as n, buildMenuPresets as o, PAGE_USE_TOOL as p, PAGE_USE_LAUNCHER_TAG as r, PAGE_USE_ROBOT_ICON_SVG as s, definePageUseElements as t, createPageUse as u, hidePageUseLauncher as v, isPageUseConfigured as w, clearPageUseLog as x, showPageUseLauncher as y, SIMULATOR_MASK_ID as z };