@tanzerfe/page-use 0.0.2 → 0.0.4

package/dist/{src-C8EWDZVz.mjs → src-B9wNTD0L.mjs}

@@ -2,6 +2,634 @@ import { PageAgent } from "page-agent";
 import { LitElement, css, html, nothing } from "lit";
 import { keyed } from "lit/directives/keyed.js";
 
+//#region src/core/maskTheme.ts
+/**
+* 运行期蒙层与模拟光标的定制主题（覆盖 page-agent SimulatorMask 的默认视觉）。
+*
+* page-agent 的 CSS Module 类名带哈希（如 `_cursor_1dgwb_2`），随版本变化，
+* 因此这里只依赖稳定的结构：
+* - 蒙层根节点 id：`page-agent-runtime_simulator-mask`
+* - 子节点顺序：ai-motion 光晕层在前（初始化失败时不存在），光标节点恒为最后一个子节点
+* - 光标子节点顺序：1 点击波纹 / 2 箭头填充 / 3 箭头描边
+* - 点击态类名包含 `clicking` 子串
+* 升级 page-agent 后若光标样式失效，先核对 SimulatorMask 的 #createCursor 结构。
+*/
+/** 蒙层根节点 id（@page-agent/page-controller 内部常量） */
+const SIMULATOR_MASK_ID = "page-agent-runtime_simulator-mask";
+/** 主题色：主色 #0879ff 同系的蓝 → 青 → 靛渐变 */
+const PAGE_USE_MASK_COLORS = {
+	primary: "#0879ff",
+	cyan: "#36cfc9",
+	indigo: "#597ef7",
+	/** 误触拦截时的警示色 */
+	warning: "#fa8c16"
+};
+const CURSOR_ARROW_MASK = `url("data:image/svg+xml,${encodeURIComponent(`<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><path d='M 15 42 L 15 36.99 Q 15 31.99 23.7 31.99 L 28.05 31.99 Q 32.41 31.99 32.41 21.99 L 32.41 17 Q 32.41 12 41.09 16.95 L 76.31 37.05 Q 85 42 76.31 46.95 L 41.09 67.05 Q 32.41 72 32.41 62.01 L 32.41 57.01 Q 32.41 52.01 23.7 52.01 L 19.35 52.01 Q 15 52.01 15 47.01 Z' fill='#000'/></svg>`)}")`;
+const MASK = `#${SIMULATOR_MASK_ID}`;
+/** 光标节点：蒙层的最后一个子节点 */
+const CURSOR = `${MASK} > :last-child`;
+const { primary, cyan, indigo } = PAGE_USE_MASK_COLORS;
+const PAGE_USE_MASK_THEME_CSS = `
+/* 隐藏 ai-motion 默认光晕（光标之外的子节点），光晕改由 <tz-page-use-glow> 渲染 */
+${MASK} > :not(:last-child) { display: none !important; }
+/* 蒙层本身保持透明，仅负责拦截点击；真实鼠标由 wait 转圈改为禁止符号，明确「此时不可操作」而非「页面卡死」 */
+${MASK} { cursor: not-allowed !important; }
+
+/* 光标整体外发光 */
+${CURSOR} {
+  filter: drop-shadow(0 0 6px ${primary}8c) drop-shadow(0 2px 3px rgba(0, 0, 0, 0.25));
+}
+/* 光标尖端（节点原点）的呼吸光圈 */
+${CURSOR}::before {
+  content: '';
+  position: absolute;
+  left: -16px;
+  top: -16px;
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  background: radial-gradient(circle, ${cyan}66 0%, ${primary}26 55%, transparent 72%);
+  animation: page-use-cursor-halo 1.6s ease-in-out infinite;
+  pointer-events: none;
+}
+/* 箭头描边：主题渐变 */
+${CURSOR} > :nth-child(3) {
+  background: linear-gradient(45deg, ${primary}, ${cyan}) !important;
+}
+/* 箭头填充：用同形遮罩替换原白色 SVG 背景，改为浅色渐变 */
+${CURSOR} > :nth-child(2) {
+  background: linear-gradient(135deg, #ffffff 30%, #e6f4ff) !important;
+  -webkit-mask: ${CURSOR_ARROW_MASK} center / 100% 100% no-repeat;
+  mask: ${CURSOR_ARROW_MASK} center / 100% 100% no-repeat;
+}
+/* 点击波纹：外环改主题色 */
+${CURSOR} > :nth-child(1)::after {
+  border-color: ${cyan} !important;
+  border-width: 3px !important;
+}
+/* 点击波纹：追加一层实心扩散，增强点击反馈 */
+${CURSOR} > :nth-child(1)::before {
+  content: '';
+  position: absolute;
+  inset: 25%;
+  border-radius: 50%;
+  background: radial-gradient(circle, ${indigo}80, transparent 70%);
+  opacity: 0;
+}
+${CURSOR}[class*='clicking'] > :nth-child(1)::before {
+  animation: page-use-cursor-press 420ms ease-out forwards;
+}
+
+@keyframes page-use-cursor-halo {
+  0%, 100% { transform: scale(0.85); opacity: 0.7; }
+  50% { transform: scale(1.25); opacity: 1; }
+}
+@keyframes page-use-cursor-press {
+  0% { transform: scale(0.4); opacity: 1; }
+  100% { transform: scale(2.4); opacity: 0; }
+}
+@media (prefers-reduced-motion: reduce) {
+  ${CURSOR}::before { animation: none; }
+}
+`;
+
+//#endregion
+//#region src/core/options.ts
+/** 默认模型，仅为示例取值；接入其它端点时应通过 llm.model 显式指定支持 function calling 的模型 */
+const DEFAULT_MODEL = "deepseek-chat";
+/** 单次任务最大步数；每步一次 LLM 调用，防止死循环消耗 token */
+const DEFAULT_MAX_STEPS = 20;
+/** 默认会话头：OpenCode Go 要求每个会话带稳定的 x-opencode-session 用于路由与提示缓存 */
+const DEFAULT_SESSION_HEADER = "x-opencode-session";
+/** localStorage / sessionStorage 键前缀，可通过 storageKeyPrefix 覆盖 */
+const DEFAULT_STORAGE_KEY_PREFIX = "tz-page-use";
+/** 相对路径补齐为当前 origin 的绝对地址并去掉末尾 /；无法解析时返回空串 */
+function toAbsoluteUrl(input) {
+	const base = typeof window !== "undefined" ? window.location.origin : void 0;
+	try {
+		return new URL(input, base).toString().replace(/\/+$/, "");
+	} catch {
+		return "";
+	}
+}
+/** 按路由模式从 location 读取当前路径 */
+function readLocationPath(mode) {
+	if (typeof window === "undefined") return "/";
+	if (mode === "hash") return window.location.hash.replace(/^#/, "") || "/";
+	return `${window.location.pathname}${window.location.search}`;
+}
+function resolveSessionHeader(value) {
+	if (value === false) return "";
+	return (value ?? "").trim() || "x-opencode-session";
+}
+function normalizeOptions(options) {
+	const { llm } = options;
+	const rawBase = (llm.baseURL || "").trim();
+	const routerMode = options.routerMode ?? "hash";
+	return {
+		llm: {
+			baseURL: rawBase ? toAbsoluteUrl(rawBase) : "",
+			apiKey: (llm.apiKey || "").trim(),
+			model: (llm.model || "").trim() || "deepseek-chat",
+			maxSteps: llm.maxSteps && llm.maxSteps > 0 ? llm.maxSteps : 20,
+			disableNamedToolChoice: Boolean(llm.disableNamedToolChoice),
+			extraBody: llm.extraBody && typeof llm.extraBody === "object" ? llm.extraBody : {},
+			sessionHeader: resolveSessionHeader(llm.sessionHeader)
+		},
+		appName: options.appName,
+		getMenus: options.getMenus ?? (() => void 0),
+		routerMode,
+		getCurrentPath: options.getCurrentPath ?? (() => readLocationPath(routerMode)),
+		resolveRouteName: options.resolveRouteName,
+		routeHints: options.routeHints ?? {},
+		layoutHint: options.layoutHint,
+		beforeTask: options.beforeTask,
+		beforeTaskLabel: options.beforeTaskLabel || "任务开始前执行宿主预处理",
+		storageKeyPrefix: options.storageKeyPrefix || "tz-page-use",
+		pageAgentOptions: options.pageAgentOptions ?? {},
+		exposeGlobal: options.exposeGlobal !== false
+	};
+}
+/** URL 查询参数：?pageUseDebug=1 打开调试面板，?pageUseDebug=0 关闭；结果记入 sessionStorage */
+const LAUNCHER_QUERY_KEY = "pageUseDebug";
+/** 从 location 读取调试开关（hash 路由的查询参数在 # 之后，两处都查） */
+function readLauncherQuery() {
+	const fromSearch = new URLSearchParams(window.location.search).get(LAUNCHER_QUERY_KEY);
+	if (fromSearch !== null) return fromSearch;
+	const hashQuery = window.location.hash.split("?")[1];
+	return hashQuery ? new URLSearchParams(hashQuery).get(LAUNCHER_QUERY_KEY) : null;
+}
+/**
+* 调试面板是否显示。优先级：URL 参数（并记入本会话）> 会话记录 > fallback。
+* fallback 由宿主决定（例如「开发环境显示，生产环境隐藏」）。
+*/
+function readLauncherSwitch(fallback, storageKeyPrefix = DEFAULT_STORAGE_KEY_PREFIX) {
+	if (typeof window === "undefined") return fallback;
+	const sessionKey = `${storageKeyPrefix}-debug`;
+	try {
+		const query = readLauncherQuery();
+		if (query !== null) {
+			const enabled = query === "1" || query === "true";
+			window.sessionStorage.setItem(sessionKey, enabled ? "1" : "0");
+			return enabled;
+		}
+		const session = window.sessionStorage.getItem(sessionKey);
+		if (session !== null) return session === "1";
+	} catch {}
+	return fallback;
+}
+
+//#endregion
+//#region src/core/store.ts
+function createStore(initial) {
+	let state = initial;
+	const listeners = /* @__PURE__ */ new Set();
+	const notify = () => {
+		for (const listener of listeners) try {
+			listener(state);
+		} catch (err) {
+			console.warn("[PageUse] store 订阅回调异常", err);
+		}
+	};
+	return {
+		get: () => state,
+		set(patch) {
+			const partial = typeof patch === "function" ? patch(state) : patch;
+			if (Object.keys(partial).every((key) => Object.is(state[key], partial[key]))) return;
+			state = {
+				...state,
+				...partial
+			};
+			notify();
+		},
+		replace(next) {
+			if (Object.is(next, state)) return;
+			state = next;
+			notify();
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/core/settings.ts
+/**
+* Page Use 本地设置（localStorage 持久化，单例）。
+* 含 page-agent 内置面板/元素编号高亮开关、蒙层与光晕、演示播报、调试入口拖拽位置。
+* 存储键为 `${storageKeyPrefix}-settings`。
+*/
+/** page-agent 元素高亮容器 id（page-controller 内部常量，随版本可能变化） */
+const HIGHLIGHT_CONTAINER_ID = "playwright-highlight-container";
+const HIGHLIGHT_STYLE_ID = "page-use-hide-highlights";
+/** page-agent 内置面板根节点 id（@page-agent/ui 内部常量） */
+const BUILTIN_PANEL_ID = "page-agent-runtime_agent-panel";
+const BUILTIN_PANEL_STYLE_ID = "page-use-hide-builtin-panel";
+const MASK_THEME_STYLE_ID = "page-use-mask-theme";
+const DEFAULT_PAGE_USE_SETTINGS = {
+	showBuiltinPanel: false,
+	showHighlights: false,
+	showStepDetails: true,
+	enableBeforeTask: true,
+	enableMask: true,
+	customMaskEffect: true,
+	voiceEnabled: false,
+	voiceRate: 1.1,
+	voiceName: "",
+	fabPos: null
+};
+/**
+* 调试面板不再提供开关的设置项及其固定值。
+* 复选框已移除，本地存储中曾经改过的值无法在界面上改回，因此读取与更新时一律覆盖为固定值；
+* PageUseSettings 保留这两个字段，避免破坏调用方的类型。
+*/
+const LOCKED_SETTINGS = {
+	showBuiltinPanel: false,
+	customMaskEffect: true
+};
+function storageKey$1(prefix) {
+	return `${prefix}-settings`;
+}
+function load$1(prefix) {
+	try {
+		const raw = window.localStorage.getItem(storageKey$1(prefix));
+		if (!raw) return { ...DEFAULT_PAGE_USE_SETTINGS };
+		return {
+			...DEFAULT_PAGE_USE_SETTINGS,
+			...JSON.parse(raw),
+			...LOCKED_SETTINGS
+		};
+	} catch {
+		return { ...DEFAULT_PAGE_USE_SETTINGS };
+	}
+}
+function save(prefix, settings) {
+	try {
+		window.localStorage.setItem(storageKey$1(prefix), JSON.stringify(settings));
+	} catch {}
+}
+/** 按开关注入/移除一段覆盖样式（用于压制 page-agent 自带的 DOM，这些节点位于宿主 document 中） */
+function toggleOverrideStyle(styleId, css, show) {
+	const existing = document.getElementById(styleId);
+	if (show) {
+		existing?.remove();
+		return;
+	}
+	if (existing) return;
+	const style = document.createElement("style");
+	style.id = styleId;
+	style.textContent = css;
+	document.head.appendChild(style);
+}
+/**
+* 把设置同步到页面：
+* - 高亮：page-controller 的 doHighlightElements 内部写死为 true，只能用样式覆盖其高亮容器
+* - 内置面板：Panel 在 statuschange 到 running 时会自行 show()，因此用 !important 样式压制
+* - 蒙层主题：注入覆盖样式；关闭时移除，恢复 page-agent 默认光晕与光标
+*/
+function applyToDocument(settings, prev) {
+	if (typeof document === "undefined") return;
+	if (!prev || prev.showHighlights !== settings.showHighlights) toggleOverrideStyle(HIGHLIGHT_STYLE_ID, `#${HIGHLIGHT_CONTAINER_ID}{display:none !important;}`, settings.showHighlights);
+	if (!prev || prev.showBuiltinPanel !== settings.showBuiltinPanel) toggleOverrideStyle(BUILTIN_PANEL_STYLE_ID, `#${BUILTIN_PANEL_ID}{display:none !important;}`, settings.showBuiltinPanel);
+	if (!prev || prev.customMaskEffect !== settings.customMaskEffect) toggleOverrideStyle(MASK_THEME_STYLE_ID, PAGE_USE_MASK_THEME_CSS, !settings.customMaskEffect);
+}
+let prefix$1 = DEFAULT_STORAGE_KEY_PREFIX;
+let store$2 = null;
+/** 懒创建：首次访问时读取存储并把设置应用到页面 */
+function ensureStore$1() {
+	if (store$2) return store$2;
+	const created = createStore(load$1(prefix$1));
+	let prev = null;
+	const sync = (next) => {
+		applyToDocument(next, prev);
+		prev = next;
+	};
+	sync(created.get());
+	created.subscribe((next) => {
+		save(prefix$1, next);
+		sync(next);
+	});
+	store$2 = created;
+	return created;
+}
+/** 切换存储键前缀（createPageUse 时调用）；前缀变化时重新读取 */
+function setSettingsStoragePrefix(next) {
+	if (next === prefix$1 && store$2) return;
+	prefix$1 = next;
+	if (store$2) store$2.replace(load$1(prefix$1));
+	else ensureStore$1();
+}
+const pageUseSettings = {
+	store: {
+		get: () => ensureStore$1().get(),
+		subscribe: (listener) => ensureStore$1().subscribe(listener)
+	},
+	get() {
+		return ensureStore$1().get();
+	},
+	/** 固定项（LOCKED_SETTINGS）的修改被忽略 */
+	update(patch) {
+		ensureStore$1().set({
+			...patch,
+			...LOCKED_SETTINGS
+		});
+	},
+	/** 把浮动入口（及随之定位的面板）恢复到默认角落位置 */
+	resetPositions() {
+		ensureStore$1().set({ fabPos: null });
+	}
+};
+
+//#endregion
+//#region src/voice/speaker.ts
+/**
+* 浏览器语音合成（speechSynthesis）封装：演示播报的播放队列。
+*
+* 队列只有两部分：当前正在播报的一组句子，以及一条待播的步骤文本。
+* - 步骤播报不打断当前播报，只覆盖待播槽（语音跟不上执行时丢弃中间步骤）；
+* - 提问 / 结论先清空再播报；
+* - 每次清空递增代次，旧代次的 onend / onerror / 超时回调一律忽略，避免 cancel() 后迟到的回调误触发下一条。
+*
+* 不支持语音合成的环境中所有方法静默返回。
+*/
+/** 播报语言 */
+const SPEECH_LANG = "zh-CN";
+/** 超时兜底的语速估算：中文语音在 rate=1 时约每秒 4 字 */
+const CHARS_PER_SECOND = 4;
+/** 超时兜底的余量（毫秒）：覆盖语音引擎启动延迟；onend 不触发时按估算时长 + 余量视为播完 */
+const TIMEOUT_MARGIN_MS = 2e3;
+/** 当前环境是否支持语音合成 */
+function isSpeechSupported() {
+	return typeof globalThis.speechSynthesis !== "undefined" && typeof globalThis.SpeechSynthesisUtterance !== "undefined";
+}
+/** 可用的中文语音（lang 以 zh 开头，兼容 zh-CN / zh_CN / zh-HK 等写法）；Chrome 首次调用可能为空，需监听 voiceschanged */
+function getChineseVoices() {
+	if (!isSpeechSupported()) return [];
+	return globalThis.speechSynthesis.getVoices().filter((voice) => /^zh(?:$|[-_])/i.test(voice.lang));
+}
+/** 语音选择：指定名称 → 第一个中文语音 → undefined（浏览器默认语音） */
+function resolveVoice(voiceName) {
+	if (!isSpeechSupported()) return void 0;
+	const voices = globalThis.speechSynthesis.getVoices();
+	return voiceName && voices.find((voice) => voice.name === voiceName) || getChineseVoices()[0];
+}
+function createSpeaker(getSettings) {
+	let generation = 0;
+	/** 当前组剩余的句子；null 表示空闲 */
+	let current = null;
+	let pending = null;
+	let timer = null;
+	function clearTimer() {
+		if (timer !== null) {
+			clearTimeout(timer);
+			timer = null;
+		}
+	}
+	function playGroup(sentences) {
+		current = [...sentences];
+		playNext();
+	}
+	function playNext() {
+		clearTimer();
+		const sentence = current?.shift();
+		if (sentence === void 0) {
+			current = null;
+			if (pending) {
+				const next = pending;
+				pending = null;
+				playGroup(next);
+			}
+			return;
+		}
+		const { rate, voiceName } = getSettings();
+		const utterance = new SpeechSynthesisUtterance(sentence);
+		utterance.lang = SPEECH_LANG;
+		utterance.rate = rate > 0 ? rate : 1;
+		const voice = resolveVoice(voiceName);
+		if (voice) utterance.voice = voice;
+		const owner = generation;
+		let settled = false;
+		const finish = () => {
+			if (settled || owner !== generation) return;
+			settled = true;
+			playNext();
+		};
+		utterance.onend = finish;
+		utterance.onerror = finish;
+		timer = setTimeout(finish, sentence.length / (CHARS_PER_SECOND * utterance.rate) * 1e3 + TIMEOUT_MARGIN_MS);
+		globalThis.speechSynthesis.speak(utterance);
+	}
+	function clear() {
+		const active = current !== null;
+		generation += 1;
+		current = null;
+		pending = null;
+		clearTimer();
+		if (active && isSpeechSupported()) globalThis.speechSynthesis.cancel();
+	}
+	return {
+		enqueue(sentences) {
+			if (!isSpeechSupported() || !sentences.length) return;
+			if (current !== null) {
+				pending = sentences;
+				return;
+			}
+			playGroup(sentences);
+		},
+		interrupt(sentences) {
+			if (!isSpeechSupported()) return;
+			clear();
+			if (sentences.length) playGroup(sentences);
+		},
+		clear
+	};
+}
+
+//#endregion
+//#region src/voice/speechText.ts
+/**
+* 播报文本清洗（纯函数，无 DOM 依赖）：把模型输出的步骤描述 / 结论转成适合语音合成的句子数组。
+* 结果只用于播报，不回写任务结果与面板展示内容。
+*/
+/** 单条播报清洗后的字数上限：中文语音约 4 字/秒，120 字约 30 秒 */
+const SPEECH_MAX_CHARS = 120;
+/** 超过上限截断时追加的提示语 */
+const SPEECH_TRUNCATED_HINT = "详细内容请查看面板";
+/**
+* 单次合成的字数上限：Chrome 的在线语音单条超过约 15 秒会被截断，
+* 超过该长度的句子再按逗号等停顿切分（约 4 字/秒 × 12 秒）
+*/
+const MAX_UTTERANCE_CHARS = 50;
+/** 句末标点：截断与切句的边界（分号视为句间边界，列表项以分号连接） */
+const SENTENCE_END = "。！？!?；;";
+/** 句内停顿：长句二次切分的边界 */
+const CLAUSE_END = "，、：,:";
+/** 行尾已有这些标点时，拼接下一行不再补分隔符 */
+const TRAILING_PUNCT = /[。！？!?；;，,、：:]$/;
+/**
+* 元素编号：page-agent 以 [index] 标注可交互元素，模型常把编号写进步骤描述，
+* 如「点击索引为 23 的菜单」「点击 [23]」「点击元素 23」。
+* 不匹配「编号 / 序号」：结论中的「编号 20260809」等可能是业务数据。
+*/
+const ELEMENT_INDEX_PATTERNS = [
+	/索引\s*(?:为|是)?\s*\[?\d+\]?\s*(?:号)?\s*(?:的)?/g,
+	/元素\s*\[\d+\]\s*(?:的)?/g,
+	/元素\s*\d+\s*(?:号)?\s*(?:的)?/g,
+	/\[\d+\]/g
+];
+/** 表格分隔行：| --- | :---: | */
+const TABLE_SEPARATOR = /^\s*\|?\s*:?-{2,}:?\s*(?:\|\s*:?-{2,}:?\s*)*\|?\s*$/;
+/** 表格数据行：首尾为竖线 */
+const TABLE_ROW = /^\s*\|.*\|\s*$/;
+/** 列表项行首：- * + 或 1. 1) 1、（序号后紧跟数字时视为小数，如「2.5 吨」，不当作列表） */
+const LIST_MARKER = /^\s*(?:[-*+]\s+|\d+[.)](?!\d)\s*|\d+、\s*)/;
+/** 行内 Markdown、网址、emoji、元素编号等清理 */
+function cleanInline(text) {
+	let s = text;
+	for (const pattern of ELEMENT_INDEX_PATTERNS) s = s.replace(pattern, "");
+	s = s.replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/https?:\/\/[^\s)）]+/g, "").replace(/(\*\*|__)(.+?)\1/g, "$2").replace(/\*([^*\n]+)\*/g, "$1").replace(/~~(.+?)~~/g, "$1").replace(/`([^`]*)`/g, "$1").replace(/[*`~]/g, "").replace(/[\p{Extended_Pictographic}\u{FE0F}\u{200D}\u{2713}\u{2717}\u{2718}]/gu, "").replace(/[「」『』【】]/g, "");
+	return s.replace(/\s+/g, " ").trim();
+}
+/** 按行处理块级结构：代码块与 HTML 已在调用前移除 */
+function toLines(text) {
+	const lines = [];
+	for (const raw of text.split(/\r?\n/)) {
+		if (TABLE_SEPARATOR.test(raw)) continue;
+		if (TABLE_ROW.test(raw)) {
+			const cells = raw.split("|").map((cell) => cleanInline(cell)).filter(Boolean);
+			if (cells.length) lines.push({
+				text: cells.join("，"),
+				item: true
+			});
+			continue;
+		}
+		const item = LIST_MARKER.test(raw);
+		const cleaned = cleanInline(raw.replace(/^\s*#{1,6}\s+/, "").replace(/^\s*(?:>\s?)+/, "").replace(LIST_MARKER, ""));
+		if (cleaned) lines.push({
+			text: cleaned,
+			item
+		});
+	}
+	return lines;
+}
+/** 拼接各行：列表项之间用分号，其余行之间补句号；行尾已有标点时不补 */
+function joinLines(lines) {
+	let result = "";
+	lines.forEach((line, index) => {
+		if (index > 0 && !TRAILING_PUNCT.test(result)) result += lines[index - 1].item && line.item ? "；" : "。";
+		result += line.text;
+	});
+	return result.replace(/([。！？!?；;，,、：:])[。！？!?；;，,、：:\s]+/g, "$1").replace(/^[。！？!?；;，,、：:\s]+/, "").trim();
+}
+/** 超过上限时在上限内最后一个句末标点处截断，找不到则硬截断，并追加提示语 */
+function truncate(text, maxChars) {
+	if (text.length <= maxChars) return text;
+	const head = text.slice(0, maxChars);
+	let cut = -1;
+	for (let i = head.length - 1; i >= 0; i -= 1) if (SENTENCE_END.includes(head[i])) {
+		cut = i;
+		break;
+	}
+	let kept = cut > 0 ? head.slice(0, cut + 1) : head;
+	kept = kept.replace(/[；;，,、：:]$/, "");
+	if (!/[。！？!?]$/.test(kept)) kept += "。";
+	return `${kept}${SPEECH_TRUNCATED_HINT}`;
+}
+/** 按句末标点切句；过长的句子再按逗号等停顿切分 */
+function splitSentences(text) {
+	const sentences = text.match(new RegExp(`[^${SENTENCE_END}]+[${SENTENCE_END}]*`, "g")) || [];
+	const result = [];
+	for (const sentence of sentences) {
+		if (sentence.length <= MAX_UTTERANCE_CHARS) {
+			result.push(sentence);
+			continue;
+		}
+		const clauses = sentence.match(new RegExp(`[^${CLAUSE_END}]+[${CLAUSE_END}]*`, "g")) || [sentence];
+		let buffer = "";
+		for (const clause of clauses) {
+			if (buffer && buffer.length + clause.length > MAX_UTTERANCE_CHARS) {
+				result.push(buffer);
+				buffer = "";
+			}
+			buffer += clause;
+		}
+		if (buffer) result.push(buffer);
+	}
+	return result.map((s) => s.trim()).filter((s) => /[\p{L}\p{N}]/u.test(s));
+}
+/**
+* 模型文本 → 播报句子数组。清洗后为空时返回空数组（调用方据此跳过播报）。
+* 处理顺序：代码块 / HTML → 表格 → 行内 Markdown 与符号 → 拼行 → 截断 → 切句。
+*/
+function toSpeechText(text, options = {}) {
+	const maxChars = options.maxChars ?? 120;
+	const joined = joinLines(toLines((text || "").replace(/```[\s\S]*?(?:```|$)/g, "\n").replace(/<\/?[a-zA-Z][^>]*>/g, "")));
+	if (!joined) return [];
+	return splitSentences(truncate(joined, maxChars));
+}
+
+//#endregion
+//#region src/voice/narration.ts
+/**
+* 演示播报：订阅进度事件，按设置把步骤描述、提问与结论交给 speaker 播报。
+* 只订阅事件，不影响任务执行节奏；对所有任务来源生效。
+*/
+/**
+* 不播报的步骤：滚动、等待没有演示价值；done 由结论播报替代；
+* ask_user 的问题由 question 事件播报；error / retry 为执行出错与重试的伪工具名。
+*/
+const SILENT_STEP_TOOLS = /* @__PURE__ */ new Set([
+	"scroll",
+	"scroll_horizontally",
+	"wait",
+	"done",
+	"ask_user",
+	"error",
+	"retry"
+]);
+/** 启动播报，返回停止函数（取消订阅并停止播报） */
+function startNarration({ subscribe, speaker: injected }) {
+	const speaker = injected || createSpeaker(() => {
+		const { voiceRate, voiceName } = pageUseSettings.get();
+		return {
+			rate: voiceRate,
+			voiceName
+		};
+	});
+	const enabled = () => pageUseSettings.get().voiceEnabled;
+	const offEvents = subscribe((event) => {
+		switch (event.type) {
+			case "started":
+				speaker.clear();
+				break;
+			case "step":
+				if (!enabled() || SILENT_STEP_TOOLS.has(event.step.tool)) return;
+				speaker.enqueue(toSpeechText(event.step.goal));
+				break;
+			case "question":
+				if (enabled()) speaker.interrupt(toSpeechText(event.question));
+				break;
+			case "finished": if (event.result.status === "stopped" || !enabled()) speaker.clear();
+			else speaker.interrupt(toSpeechText(event.result.summary));
+		}
+	});
+	let wasEnabled = enabled();
+	const offSettings = pageUseSettings.store.subscribe((settings) => {
+		if (wasEnabled && !settings.voiceEnabled) speaker.clear();
+		wasEnabled = settings.voiceEnabled;
+	});
+	return () => {
+		offEvents();
+		offSettings();
+		speaker.clear();
+	};
+}
+
+//#endregion
 //#region src/core/siteMap.ts
 /** 去掉 `#`、前导 `/` 与查询串，得到用于比较的路径 */
 function normalizePath(path) {
@@ -52,8 +680,17 @@ function findMenuByPath(path, menus) {
 //#region src/core/pageInstructions.ts
 /** 未提供 layoutHint 时的通用页面结构描述 */
 const DEFAULT_LAYOUT_HINT = ["- 页面通常由导航菜单与内容区组成；内容区顶部若有面包屑或标题，可用来确认当前位置。", "- 分组菜单点击后展开/收起下级；叶子菜单点击后进入页面。"].join("\n");
-/** 全局系统提示：站点结构 + 交互约定 + 安全边界 */
-function buildSystemInstruction(options) {
+/**
+* 演示播报开启时追加的约束：page-agent 默认要求 next_goal 写「目标 + 动作」，模型常带元素编号，
+* 念出来生硬；这里只约束步骤描述，不改变 done 的 text（结论会回传给调用方）。
+*/
+const NARRATION_RULES = [
+	"## 语音播报",
+	"- 每一步的 next_goal 会被语音播报给观众：写成一句简短的中文，描述这一步要做什么，如「打开隐患台账页面」；不要包含元素编号、索引或方括号数字。",
+	"- 该要求只针对 next_goal；done 的 text 仍按原要求书写。"
+].join("\n");
+/** 全局系统提示：站点结构 + 交互约定 + 安全边界（+ 播报约束） */
+function buildSystemInstruction(options, flags = {}) {
 	const urlLabel = options.routerMode === "hash" ? "URL hash" : "URL 路径";
 	const siteMap = buildSiteMapText(options.getMenus(), options.routerMode);
 	return [
@@ -76,7 +713,8 @@ function buildSystemInstruction(options) {
 		"",
 		"## 安全边界",
 		"- 未经用户明确要求，不得执行删除、提交、审批、发布、批量修改等不可逆操作；不确定时用 ask_user 询问。",
-		"- 任务完成后调用 done，用一句话说明当前所在页面及已完成的动作；无法完成时说明卡在哪一步。"
+		"- 任务完成后调用 done，用一句话说明当前所在页面及已完成的动作；无法完成时说明卡在哪一步。",
+		...flags.narration ? ["", NARRATION_RULES] : []
 	].join("\n");
 }
 /**
@@ -115,7 +753,7 @@ const STEP_DELAY_SECONDS = .6;
 function newSessionId() {
 	return typeof crypto !== "undefined" && crypto.randomUUID?.() || `page-use-${Date.now()}`;
 }
-function createPageUseAgent({ options, enableMask, shouldRunBeforeTask, onTaskFinished }) {
+function createPageUseAgent({ options, enableMask, narration = false, shouldRunBeforeTask, onTaskFinished }) {
 	const { llm } = options;
 	if (!llm.baseURL) throw new Error("[PageUse] 未配置 llm.baseURL");
 	let sessionId = newSessionId();
@@ -150,7 +788,7 @@ function createPageUseAgent({ options, enableMask, shouldRunBeforeTask, onTaskFi
 		enableMask,
 		experimentalScriptExecutionTool: false,
 		instructions: {
-			system: buildSystemInstruction(options),
+			system: buildSystemInstruction(options, { narration }),
 			getPageInstructions: () => buildPageInstruction(options)
 		},
 		transformPageContent: (content) => {
@@ -162,139 +800,16 @@ function createPageUseAgent({ options, enableMask, shouldRunBeforeTask, onTaskFi
 			sessionId = newSessionId();
 			if (hostBeforeTask && shouldRunBeforeTask()) try {
 				await hostBeforeTask();
-			} catch (err) {
-				console.warn("[PageUse] beforeTask 执行异常", err);
-			}
-			await options.pageAgentOptions.onBeforeTask?.(...args);
-		},
-		onAfterTask: async (...args) => {
-			onTaskFinished?.(args[1]);
-			await options.pageAgentOptions.onAfterTask?.(...args);
-		}
-	});
-}
-
-//#endregion
-//#region src/core/options.ts
-/** 默认模型，仅为示例取值；接入其它端点时应通过 llm.model 显式指定支持 function calling 的模型 */
-const DEFAULT_MODEL = "deepseek-chat";
-/** 单次任务最大步数；每步一次 LLM 调用，防止死循环消耗 token */
-const DEFAULT_MAX_STEPS = 20;
-/** 默认会话头：OpenCode Go 要求每个会话带稳定的 x-opencode-session 用于路由与提示缓存 */
-const DEFAULT_SESSION_HEADER = "x-opencode-session";
-/** localStorage / sessionStorage 键前缀，可通过 storageKeyPrefix 覆盖 */
-const DEFAULT_STORAGE_KEY_PREFIX = "tz-page-use";
-/** 相对路径补齐为当前 origin 的绝对地址并去掉末尾 /；无法解析时返回空串 */
-function toAbsoluteUrl(input) {
-	const base = typeof window !== "undefined" ? window.location.origin : void 0;
-	try {
-		return new URL(input, base).toString().replace(/\/+$/, "");
-	} catch {
-		return "";
-	}
-}
-/** 按路由模式从 location 读取当前路径 */
-function readLocationPath(mode) {
-	if (typeof window === "undefined") return "/";
-	if (mode === "hash") return window.location.hash.replace(/^#/, "") || "/";
-	return `${window.location.pathname}${window.location.search}`;
-}
-function resolveSessionHeader(value) {
-	if (value === false) return "";
-	return (value ?? "").trim() || "x-opencode-session";
-}
-function normalizeOptions(options) {
-	const { llm } = options;
-	const rawBase = (llm.baseURL || "").trim();
-	const routerMode = options.routerMode ?? "hash";
-	return {
-		llm: {
-			baseURL: rawBase ? toAbsoluteUrl(rawBase) : "",
-			apiKey: (llm.apiKey || "").trim(),
-			model: (llm.model || "").trim() || "deepseek-chat",
-			maxSteps: llm.maxSteps && llm.maxSteps > 0 ? llm.maxSteps : 20,
-			disableNamedToolChoice: Boolean(llm.disableNamedToolChoice),
-			extraBody: llm.extraBody && typeof llm.extraBody === "object" ? llm.extraBody : {},
-			sessionHeader: resolveSessionHeader(llm.sessionHeader)
-		},
-		appName: options.appName,
-		getMenus: options.getMenus ?? (() => void 0),
-		routerMode,
-		getCurrentPath: options.getCurrentPath ?? (() => readLocationPath(routerMode)),
-		resolveRouteName: options.resolveRouteName,
-		routeHints: options.routeHints ?? {},
-		layoutHint: options.layoutHint,
-		beforeTask: options.beforeTask,
-		beforeTaskLabel: options.beforeTaskLabel || "任务开始前执行宿主预处理",
-		storageKeyPrefix: options.storageKeyPrefix || "tz-page-use",
-		pageAgentOptions: options.pageAgentOptions ?? {},
-		exposeGlobal: options.exposeGlobal !== false
-	};
-}
-/** URL 查询参数：?pageUseDebug=1 打开调试面板，?pageUseDebug=0 关闭；结果记入 sessionStorage */
-const LAUNCHER_QUERY_KEY = "pageUseDebug";
-/** 从 location 读取调试开关（hash 路由的查询参数在 # 之后，两处都查） */
-function readLauncherQuery() {
-	const fromSearch = new URLSearchParams(window.location.search).get(LAUNCHER_QUERY_KEY);
-	if (fromSearch !== null) return fromSearch;
-	const hashQuery = window.location.hash.split("?")[1];
-	return hashQuery ? new URLSearchParams(hashQuery).get(LAUNCHER_QUERY_KEY) : null;
-}
-/**
-* 调试面板是否显示。优先级：URL 参数（并记入本会话）> 会话记录 > fallback。
-* fallback 由宿主决定（例如「开发环境显示，生产环境隐藏」）。
-*/
-function readLauncherSwitch(fallback, storageKeyPrefix = DEFAULT_STORAGE_KEY_PREFIX) {
-	if (typeof window === "undefined") return fallback;
-	const sessionKey = `${storageKeyPrefix}-debug`;
-	try {
-		const query = readLauncherQuery();
-		if (query !== null) {
-			const enabled = query === "1" || query === "true";
-			window.sessionStorage.setItem(sessionKey, enabled ? "1" : "0");
-			return enabled;
-		}
-		const session = window.sessionStorage.getItem(sessionKey);
-		if (session !== null) return session === "1";
-	} catch {}
-	return fallback;
-}
-
-//#endregion
-//#region src/core/store.ts
-function createStore(initial) {
-	let state = initial;
-	const listeners = /* @__PURE__ */ new Set();
-	const notify = () => {
-		for (const listener of listeners) try {
-			listener(state);
-		} catch (err) {
-			console.warn("[PageUse] store 订阅回调异常", err);
-		}
-	};
-	return {
-		get: () => state,
-		set(patch) {
-			const partial = typeof patch === "function" ? patch(state) : patch;
-			if (Object.keys(partial).every((key) => Object.is(state[key], partial[key]))) return;
-			state = {
-				...state,
-				...partial
-			};
-			notify();
-		},
-		replace(next) {
-			if (Object.is(next, state)) return;
-			state = next;
-			notify();
+			} catch (err) {
+				console.warn("[PageUse] beforeTask 执行异常", err);
+			}
+			await options.pageAgentOptions.onBeforeTask?.(...args);
 		},
-		subscribe(listener) {
-			listeners.add(listener);
-			return () => {
-				listeners.delete(listener);
-			};
+		onAfterTask: async (...args) => {
+			onTaskFinished?.(args[1]);
+			await options.pageAgentOptions.onAfterTask?.(...args);
 		}
-	};
+	});
 }
 
 //#endregion
@@ -304,262 +819,59 @@ function createStore(initial) {
 * 用于快速重放上次指令，以及查看任务结果。存储键为 `${storageKeyPrefix}-history`。
 */
 const MAX_ENTRIES = 30;
-function storageKey$1(prefix) {
+function storageKey(prefix) {
 	return `${prefix}-history`;
 }
-function load$1(prefix) {
+function load(prefix) {
 	try {
-		const raw = window.localStorage.getItem(storageKey$1(prefix));
+		const raw = window.localStorage.getItem(storageKey(prefix));
 		const parsed = raw ? JSON.parse(raw) : [];
 		return Array.isArray(parsed) ? parsed : [];
 	} catch {
 		return [];
 	}
 }
-let prefix$1 = DEFAULT_STORAGE_KEY_PREFIX;
+let prefix = DEFAULT_STORAGE_KEY_PREFIX;
 /** 懒创建：避免模块加载即访问 window（SSR / 测试环境） */
-let store$2 = null;
-function ensureStore$1() {
-	if (!store$2) store$2 = createStore({ entries: load$1(prefix$1) });
-	return store$2;
+let store$1 = null;
+function ensureStore() {
+	if (!store$1) store$1 = createStore({ entries: load(prefix) });
+	return store$1;
 }
 function persist(entries) {
-	ensureStore$1().set({ entries });
+	ensureStore().set({ entries });
 	try {
-		window.localStorage.setItem(storageKey$1(prefix$1), JSON.stringify(entries));
+		window.localStorage.setItem(storageKey(prefix), JSON.stringify(entries));
 	} catch {}
 }
 /** 切换存储键前缀（createPageUse 时调用）；前缀变化时重新读取 */
 function setHistoryStoragePrefix(next) {
-	if (next === prefix$1 && store$2) return;
-	prefix$1 = next;
-	ensureStore$1().replace({ entries: load$1(prefix$1) });
+	if (next === prefix && store$1) return;
+	prefix = next;
+	ensureStore().replace({ entries: load(prefix) });
 }
 const pageUseHistory = {
 	store: {
-		get: () => ensureStore$1().get(),
-		subscribe: (listener) => ensureStore$1().subscribe(listener)
+		get: () => ensureStore().get(),
+		subscribe: (listener) => ensureStore().subscribe(listener)
 	},
 	entries() {
-		return ensureStore$1().get().entries;
+		return ensureStore().get().entries;
 	},
 	add(entry) {
 		persist([{
 			id: `${entry.at}-${Math.random().toString(36).slice(2, 8)}`,
 			...entry
-		}, ...ensureStore$1().get().entries].slice(0, MAX_ENTRIES));
+		}, ...ensureStore().get().entries].slice(0, MAX_ENTRIES));
 	},
 	remove(id) {
-		persist(ensureStore$1().get().entries.filter((item) => item.id !== id));
+		persist(ensureStore().get().entries.filter((item) => item.id !== id));
 	},
 	clear() {
 		persist([]);
 	}
 };
 
-//#endregion
-//#region src/core/maskTheme.ts
-/**
-* 运行期蒙层与模拟光标的定制主题（覆盖 page-agent SimulatorMask 的默认视觉）。
-*
-* page-agent 的 CSS Module 类名带哈希（如 `_cursor_1dgwb_2`），随版本变化，
-* 因此这里只依赖稳定的结构：
-* - 蒙层根节点 id：`page-agent-runtime_simulator-mask`
-* - 子节点顺序：ai-motion 光晕层在前（初始化失败时不存在），光标节点恒为最后一个子节点
-* - 光标子节点顺序：1 点击波纹 / 2 箭头填充 / 3 箭头描边
-* - 点击态类名包含 `clicking` 子串
-* 升级 page-agent 后若光标样式失效，先核对 SimulatorMask 的 #createCursor 结构。
-*/
-/** 蒙层根节点 id（@page-agent/page-controller 内部常量） */
-const SIMULATOR_MASK_ID = "page-agent-runtime_simulator-mask";
-/** 主题色：主色 #0879ff 同系的蓝 → 青 → 靛渐变 */
-const PAGE_USE_MASK_COLORS = {
-	primary: "#0879ff",
-	cyan: "#36cfc9",
-	indigo: "#597ef7",
-	/** 误触拦截时的警示色 */
-	warning: "#fa8c16"
-};
-const CURSOR_ARROW_MASK = `url("data:image/svg+xml,${encodeURIComponent(`<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><path d='M 15 42 L 15 36.99 Q 15 31.99 23.7 31.99 L 28.05 31.99 Q 32.41 31.99 32.41 21.99 L 32.41 17 Q 32.41 12 41.09 16.95 L 76.31 37.05 Q 85 42 76.31 46.95 L 41.09 67.05 Q 32.41 72 32.41 62.01 L 32.41 57.01 Q 32.41 52.01 23.7 52.01 L 19.35 52.01 Q 15 52.01 15 47.01 Z' fill='#000'/></svg>`)}")`;
-const MASK = `#${SIMULATOR_MASK_ID}`;
-/** 光标节点：蒙层的最后一个子节点 */
-const CURSOR = `${MASK} > :last-child`;
-const { primary, cyan, indigo } = PAGE_USE_MASK_COLORS;
-const PAGE_USE_MASK_THEME_CSS = `
-/* 隐藏 ai-motion 默认光晕（光标之外的子节点），光晕改由 <tz-page-use-glow> 渲染 */
-${MASK} > :not(:last-child) { display: none !important; }
-/* 蒙层本身保持透明，仅负责拦截点击；真实鼠标由 wait 转圈改为禁止符号，明确「此时不可操作」而非「页面卡死」 */
-${MASK} { cursor: not-allowed !important; }
-
-/* 光标整体外发光 */
-${CURSOR} {
-  filter: drop-shadow(0 0 6px ${primary}8c) drop-shadow(0 2px 3px rgba(0, 0, 0, 0.25));
-}
-/* 光标尖端（节点原点）的呼吸光圈 */
-${CURSOR}::before {
-  content: '';
-  position: absolute;
-  left: -16px;
-  top: -16px;
-  width: 32px;
-  height: 32px;
-  border-radius: 50%;
-  background: radial-gradient(circle, ${cyan}66 0%, ${primary}26 55%, transparent 72%);
-  animation: page-use-cursor-halo 1.6s ease-in-out infinite;
-  pointer-events: none;
-}
-/* 箭头描边：主题渐变 */
-${CURSOR} > :nth-child(3) {
-  background: linear-gradient(45deg, ${primary}, ${cyan}) !important;
-}
-/* 箭头填充：用同形遮罩替换原白色 SVG 背景，改为浅色渐变 */
-${CURSOR} > :nth-child(2) {
-  background: linear-gradient(135deg, #ffffff 30%, #e6f4ff) !important;
-  -webkit-mask: ${CURSOR_ARROW_MASK} center / 100% 100% no-repeat;
-  mask: ${CURSOR_ARROW_MASK} center / 100% 100% no-repeat;
-}
-/* 点击波纹：外环改主题色 */
-${CURSOR} > :nth-child(1)::after {
-  border-color: ${cyan} !important;
-  border-width: 3px !important;
-}
-/* 点击波纹：追加一层实心扩散，增强点击反馈 */
-${CURSOR} > :nth-child(1)::before {
-  content: '';
-  position: absolute;
-  inset: 25%;
-  border-radius: 50%;
-  background: radial-gradient(circle, ${indigo}80, transparent 70%);
-  opacity: 0;
-}
-${CURSOR}[class*='clicking'] > :nth-child(1)::before {
-  animation: page-use-cursor-press 420ms ease-out forwards;
-}
-
-@keyframes page-use-cursor-halo {
-  0%, 100% { transform: scale(0.85); opacity: 0.7; }
-  50% { transform: scale(1.25); opacity: 1; }
-}
-@keyframes page-use-cursor-press {
-  0% { transform: scale(0.4); opacity: 1; }
-  100% { transform: scale(2.4); opacity: 0; }
-}
-@media (prefers-reduced-motion: reduce) {
-  ${CURSOR}::before { animation: none; }
-}
-`;
-
-//#endregion
-//#region src/core/settings.ts
-/**
-* Page Use 本地设置（localStorage 持久化，单例）。
-* 含 page-agent 内置面板/元素编号高亮开关、蒙层与光晕、调试入口拖拽位置。
-* 存储键为 `${storageKeyPrefix}-settings`。
-*/
-/** page-agent 元素高亮容器 id（page-controller 内部常量，随版本可能变化） */
-const HIGHLIGHT_CONTAINER_ID = "playwright-highlight-container";
-const HIGHLIGHT_STYLE_ID = "page-use-hide-highlights";
-/** page-agent 内置面板根节点 id（@page-agent/ui 内部常量） */
-const BUILTIN_PANEL_ID = "page-agent-runtime_agent-panel";
-const BUILTIN_PANEL_STYLE_ID = "page-use-hide-builtin-panel";
-const MASK_THEME_STYLE_ID = "page-use-mask-theme";
-const DEFAULT_PAGE_USE_SETTINGS = {
-	showBuiltinPanel: false,
-	showHighlights: false,
-	showStepDetails: true,
-	enableBeforeTask: true,
-	enableMask: true,
-	customMaskEffect: true,
-	fabPos: null
-};
-function storageKey(prefix) {
-	return `${prefix}-settings`;
-}
-function load(prefix) {
-	try {
-		const raw = window.localStorage.getItem(storageKey(prefix));
-		if (!raw) return { ...DEFAULT_PAGE_USE_SETTINGS };
-		return {
-			...DEFAULT_PAGE_USE_SETTINGS,
-			...JSON.parse(raw)
-		};
-	} catch {
-		return { ...DEFAULT_PAGE_USE_SETTINGS };
-	}
-}
-function save(prefix, settings) {
-	try {
-		window.localStorage.setItem(storageKey(prefix), JSON.stringify(settings));
-	} catch {}
-}
-/** 按开关注入/移除一段覆盖样式（用于压制 page-agent 自带的 DOM，这些节点位于宿主 document 中） */
-function toggleOverrideStyle(styleId, css, show) {
-	const existing = document.getElementById(styleId);
-	if (show) {
-		existing?.remove();
-		return;
-	}
-	if (existing) return;
-	const style = document.createElement("style");
-	style.id = styleId;
-	style.textContent = css;
-	document.head.appendChild(style);
-}
-/**
-* 把设置同步到页面：
-* - 高亮：page-controller 的 doHighlightElements 内部写死为 true，只能用样式覆盖其高亮容器
-* - 内置面板：Panel 在 statuschange 到 running 时会自行 show()，因此用 !important 样式压制
-* - 蒙层主题：注入覆盖样式；关闭时移除，恢复 page-agent 默认光晕与光标
-*/
-function applyToDocument(settings, prev) {
-	if (typeof document === "undefined") return;
-	if (!prev || prev.showHighlights !== settings.showHighlights) toggleOverrideStyle(HIGHLIGHT_STYLE_ID, `#${HIGHLIGHT_CONTAINER_ID}{display:none !important;}`, settings.showHighlights);
-	if (!prev || prev.showBuiltinPanel !== settings.showBuiltinPanel) toggleOverrideStyle(BUILTIN_PANEL_STYLE_ID, `#${BUILTIN_PANEL_ID}{display:none !important;}`, settings.showBuiltinPanel);
-	if (!prev || prev.customMaskEffect !== settings.customMaskEffect) toggleOverrideStyle(MASK_THEME_STYLE_ID, PAGE_USE_MASK_THEME_CSS, !settings.customMaskEffect);
-}
-let prefix = DEFAULT_STORAGE_KEY_PREFIX;
-let store$1 = null;
-/** 懒创建：首次访问时读取存储并把设置应用到页面 */
-function ensureStore() {
-	if (store$1) return store$1;
-	const created = createStore(load(prefix));
-	let prev = null;
-	const sync = (next) => {
-		applyToDocument(next, prev);
-		prev = next;
-	};
-	sync(created.get());
-	created.subscribe((next) => {
-		save(prefix, next);
-		sync(next);
-	});
-	store$1 = created;
-	return created;
-}
-/** 切换存储键前缀（createPageUse 时调用）；前缀变化时重新读取 */
-function setSettingsStoragePrefix(next) {
-	if (next === prefix && store$1) return;
-	prefix = next;
-	if (store$1) store$1.replace(load(prefix));
-	else ensureStore();
-}
-const pageUseSettings = {
-	store: {
-		get: () => ensureStore().get(),
-		subscribe: (listener) => ensureStore().subscribe(listener)
-	},
-	get() {
-		return ensureStore().get();
-	},
-	update(patch) {
-		ensureStore().set(patch);
-	},
-	/** 把浮动入口（及随之定位的面板）恢复到默认角落位置 */
-	resetPositions() {
-		ensureStore().set({ fabPos: null });
-	}
-};
-
 //#endregion
 //#region src/core/stepLog.ts
 function summarizeActionInput(name, input) {
@@ -668,6 +980,10 @@ let everConfigured = false;
 let agent = null;
 /** 创建实例时的蒙层设置；与当前设置不一致时须重建 */
 let agentMaskFlag = null;
+/** 创建实例时的播报设置：系统提示在构造时生成，播报开关变化后须重建才能追加 / 移除步骤描述约束 */
+let agentVoiceFlag = null;
+/** 演示播报的停止函数；配置期间运行，解绑 / 重新配置时停止 */
+let stopNarration = null;
 /** 已挂载且可作答的调试面板数量；>0 时未指定 onAskUser 的提问交给面板 */
 let questionUiCount = 0;
 /** 当前任务的调用方选项（提问回调、进度回调） */
@@ -752,20 +1068,25 @@ function handleAskUser(question, signal) {
 		}, { once: true });
 	});
 }
-/** 懒创建单例；蒙层设置变化时重建（enableMask 属构造期选项） */
+/**
+* 懒创建单例；蒙层或播报设置变化时重建（enableMask 属构造期选项，系统提示在构造时生成）。
+* 在任务开始时调用，因此执行中切换开关只影响下一次任务。
+*/
 function ensureAgent(options) {
 	const settings = pageUseSettings.get();
-	if (agent && !agent.disposed && agentMaskFlag === settings.enableMask) return agent;
+	if (agent && !agent.disposed && agentMaskFlag === settings.enableMask && agentVoiceFlag === settings.voiceEnabled) return agent;
 	if (agent && !agent.disposed) agent.dispose();
 	const created = createPageUseAgent({
 		options,
 		enableMask: settings.enableMask,
+		narration: settings.voiceEnabled,
 		shouldRunBeforeTask: () => pageUseSettings.get().enableBeforeTask
 	});
 	bindAgentEvents(created);
 	created.onAskUser = (question, askOptions) => handleAskUser(question, askOptions?.signal);
 	agent = created;
 	agentMaskFlag = settings.enableMask;
+	agentVoiceFlag = settings.voiceEnabled;
 	store.set({ maskEnabled: settings.enableMask });
 	return created;
 }
@@ -804,9 +1125,13 @@ function configurePageUse(options) {
 	setSettingsStoragePrefix(options.storageKeyPrefix);
 	setHistoryStoragePrefix(options.storageKeyPrefix);
 	store.set({ ready: Boolean(options.llm.baseURL) });
+	stopNarration?.();
+	stopNarration = startNarration({ subscribe: subscribePageUse });
 	return () => {
 		if (config !== options) return;
 		config = null;
+		stopNarration?.();
+		stopNarration = null;
 		disposeAgent();
 		store.set({ ready: false });
 	};
@@ -969,6 +1294,7 @@ function disposeAgent() {
 	agent?.dispose();
 	agent = null;
 	agentMaskFlag = null;
+	agentVoiceFlag = null;
 	activeOptions = null;
 	store.set({
 		maskEnabled: false,
@@ -1974,6 +2300,36 @@ const launcherStyles = css`
     background: var(--bg-soft);
     cursor: not-allowed;
   }
+  /* ---------- 演示播报设置 ---------- */
+  .voice-warning {
+    margin-left: 21px;
+    font-size: 12px;
+  }
+  /* 与复选框文字左对齐（复选框宽 13px + 间距 8px） */
+  .voice-options {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    margin-left: 21px;
+  }
+  .field {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+  .field-label {
+    color: var(--text-3);
+    font-size: 12px;
+  }
+  .range {
+    width: 100%;
+    margin: 0;
+    accent-color: var(--primary);
+  }
+  select.input {
+    height: 28px;
+  }
+
   .input-group {
     display: flex;
     gap: 6px;
@@ -2051,7 +2407,7 @@ const launcherStyles = css`
 /**
 * <tz-page-use-launcher>：调试入口（可拖拽浮动按钮 + 指令面板）。
 * 与其它智能体共用 core/service 的单例状态：其它智能体下达的任务同样在此展示，可随时终止。
-* 默认隐藏 page-agent 自带面板与元素编号高亮，进度与提问改由本面板承接（设置里可开回）。
+* page-agent 自带面板固定隐藏、元素编号高亮默认隐藏（设置里可开回），进度与提问改由本面板承接。
 *
 * 宿主元素须带 data-page-agent-ignore="true"（由 mountPageUseUI 设置）：
 * page-controller 在该属性上直接跳过整棵子树（含 shadow root），面板不会被模型当作页面元素。
@@ -2078,6 +2434,10 @@ const PANEL_HEIGHT = 560;
 /** 日志区距底部小于该值（px）视为贴底 */
 const STICK_THRESHOLD = 24;
 const TEXTAREA_MIN_ROWS = 2;
+/** 播报语速调节范围与步长（SpeechSynthesisUtterance.rate；1 为正常语速，过快或过慢时中文语音难以听清） */
+const VOICE_RATE_MIN = .5;
+const VOICE_RATE_MAX = 2;
+const VOICE_RATE_STEP = .05;
 /**
 * 步骤 → 时间线节点颜色：失败/报错为 error，完成为 success，
 * 向用户提问与重试为 warning，其余普通操作为 info（主色）。
@@ -2185,7 +2545,8 @@ var PageUseLauncherElement = class extends LitElement {
 			pageUseStore.subscribe((state) => this.onStateChange(state)),
 			pageUseSettings.store.subscribe(() => this.requestUpdate()),
 			pageUseHistory.store.subscribe(() => this.requestUpdate()),
-			registerQuestionUi()
+			registerQuestionUi(),
+			this.watchVoices()
 		];
 		window.addEventListener("resize", this.onResize);
 	}
@@ -2195,6 +2556,14 @@ var PageUseLauncherElement = class extends LitElement {
 		this.cleanups = [];
 		window.removeEventListener("resize", this.onResize);
 	}
+	/** Chrome 的语音列表异步加载，首次读取可能为空：加载完成后刷新语音下拉框 */
+	watchVoices() {
+		if (!isSpeechSupported()) return () => {};
+		const synth = globalThis.speechSynthesis;
+		const onChange = () => this.requestUpdate();
+		synth.addEventListener?.("voiceschanged", onChange);
+		return () => synth.removeEventListener?.("voiceschanged", onChange);
+	}
 	firstUpdated() {
 		this.measureFab();
 	}
@@ -2434,12 +2803,11 @@ var PageUseLauncherElement = class extends LitElement {
 		const config = getPageUseConfig();
 		return html`<div class="fill">
       <div class="settings-body">
-        ${this.renderCheckbox("showBuiltinPanel", "显示 page-agent 自带面板", "关闭后由本面板展示进度")}
         ${this.renderCheckbox("showHighlights", "显示元素编号高亮", "运行时页面上带数字的彩色框")}
         ${this.renderCheckbox("enableMask", "运行时蒙层防误触", "下次任务开始生效")}
-        ${this.renderCheckbox("customMaskEffect", "定制光晕与光标配色", "关闭后恢复 page-agent 默认效果", !settings.enableMask)}
         ${config?.beforeTask ? this.renderCheckbox("enableBeforeTask", config.beforeTaskLabel) : nothing}
         ${this.renderCheckbox("showStepDetails", "步骤显示模型思考与返回")}
+        ${this.renderVoiceSettings(settings)}
         <div class="row">
           <button type="button" class="btn" @click=${() => pageUseSettings.resetPositions()}>
             复位窗口
@@ -2449,6 +2817,42 @@ var PageUseLauncherElement = class extends LitElement {
         <span class="meta">端点 ${this.endpointLabel()} · 模型 ${config?.llm.model ?? "-"}</span>
       </div>
     </div>`;
+	}
+	/** 演示播报：开关 + 兼容提示；开启后显示语速与中文语音选择 */
+	renderVoiceSettings(settings) {
+		const supported = isSpeechSupported();
+		const voices = getChineseVoices();
+		const warning = !supported ? "当前浏览器不支持语音合成，开启后不会播报" : voices.length ? "" : "未检测到中文语音，将使用浏览器默认语音播报";
+		return html`
+      ${this.renderCheckbox("voiceEnabled", "语音播报", "演示时播报执行步骤、提问与结论")}
+      ${warning ? html`<div class="alert warning voice-warning">${warning}</div>` : nothing}
+      ${settings.voiceEnabled && supported ? html`<div class="voice-options">
+            <label class="field">
+              <span class="field-label">语速 ${settings.voiceRate.toFixed(2)}</span>
+              <input
+                class="range"
+                type="range"
+                min=${VOICE_RATE_MIN}
+                max=${VOICE_RATE_MAX}
+                step=${VOICE_RATE_STEP}
+                .value=${String(settings.voiceRate)}
+                @input=${(e) => pageUseSettings.update({ voiceRate: Number(e.target.value) })}
+              />
+            </label>
+            <label class="field">
+              <span class="field-label">语音</span>
+              <select
+                class="input"
+                @change=${(e) => pageUseSettings.update({ voiceName: e.target.value })}
+              >
+                <option value="" ?selected=${!settings.voiceName}>自动（第一个中文语音）</option>
+                ${voices.map((voice) => html`<option value=${voice.name} ?selected=${voice.name === settings.voiceName}>
+                      ${voice.name}
+                    </option>`)}
+              </select>
+            </label>
+          </div>` : nothing}
+    `;
 	}
 	renderLog(state, isLogEmpty) {
 		const running = isRunning(state);
@@ -2690,4 +3094,4 @@ function mountPageUseUI(options = {}) {
 }
 
 //#endregion
-export { DEFAULT_MODEL as A, pageUseStore as C, SIMULATOR_MASK_ID as D, PAGE_USE_MASK_COLORS as E, DEFAULT_STORAGE_KEY_PREFIX as M, normalizeOptions as N, pageUseHistory as O, readLauncherSwitch as P, isRunning as S, pageUseSettings as T, pageUseCapability as _, PAGE_USE_STATIC_PRESETS as a, getPageUseConfig as b, PageUseGlowElement as c, PAGE_USE_COMMAND_TYPE as d, PAGE_USE_TOOL as f, runPageUseTool as g, isPageUseCommand as h, PageUseLauncherElement as i, DEFAULT_SESSION_HEADER as j, DEFAULT_MAX_STEPS as k, createPageUse as l, formatPageUseResultForModel as m, mountPageUseUI as n, buildMenuPresets as o, PAGE_USE_TOOL_NAME as p, PAGE_USE_LAUNCHER_TAG as r, PAGE_USE_GLOW_TAG as s, definePageUseElements as t, PAGE_USE_GLOBAL_KEY as u, clearPageUseLog as v, DEFAULT_PAGE_USE_SETTINGS as w, isPageUseConfigured as x, getElapsedSeconds as y };
+export { DEFAULT_STORAGE_KEY_PREFIX as A, pageUseStore as C, DEFAULT_MAX_STEPS as D, pageUseSettings as E, readLauncherSwitch as M, PAGE_USE_MASK_COLORS as N, DEFAULT_MODEL as O, SIMULATOR_MASK_ID as P, isRunning as S, DEFAULT_PAGE_USE_SETTINGS as T, pageUseCapability as _, PAGE_USE_STATIC_PRESETS as a, getPageUseConfig as b, PageUseGlowElement as c, PAGE_USE_COMMAND_TYPE as d, PAGE_USE_TOOL as f, runPageUseTool as g, isPageUseCommand as h, PageUseLauncherElement as i, normalizeOptions as j, DEFAULT_SESSION_HEADER as k, createPageUse as l, formatPageUseResultForModel as m, mountPageUseUI as n, buildMenuPresets as o, PAGE_USE_TOOL_NAME as p, PAGE_USE_LAUNCHER_TAG as r, PAGE_USE_GLOW_TAG as s, definePageUseElements as t, PAGE_USE_GLOBAL_KEY as u, clearPageUseLog as v, pageUseHistory as w, isPageUseConfigured as x, getElapsedSeconds as y };