@webskill/sdk 0.4.0 → 0.5.0

package/dist/browser.js

@@ -1,5 +1,5 @@
-import { A as parseSkillMarkdown, B as unzipWithLimits, H as verifyManifest, L as resolveInsideRoot, M as readResponseWithLimit, O as messageOf, T as isValidSkillName, V as validateSkills, _ as atomicWriteText, f as SkillDiscovery, h as assertRemoteUrlAllowed, j as parseSkillPackManifest, m as WebSkillError, o as SKILLS_LOCKFILE, r as MANIFEST_EXCLUDED_FILES, s as SKILL_MANIFEST_FILE, u as SKILL_PACK_FILE, v as buildCatalog, w as exportSkills, y as buildManifest } from "./dist-8oQRa8Xz.js";
-import { H as normalizeToolContent, O as bridgeError, R as mergeCatalogEntries, U as normalizeToolError, W as parseBridgeRequest, _ as OpenAiCompatibleClient, d as FsRunSnapshotStore, i as AgentLoop, j as createWebSkillApi, l as FsArtifactStore, o as CapabilityApproval, u as FsMemoryStore, v as ProgressiveRouter, z as networkPolicyLibSource } from "./dist-C-Sh0MDU.js";
+import { A as parseSkillMarkdown, B as unzipWithLimits, H as verifyManifest, L as resolveInsideRoot, M as readResponseWithLimit, N as readSkillSignature, O as messageOf, T as isValidSkillName, U as verifySkillSignature, V as validateSkills, _ as atomicWriteText, f as SkillDiscovery, h as assertRemoteUrlAllowed, j as parseSkillPackManifest, m as WebSkillError, o as SKILLS_LOCKFILE, r as MANIFEST_EXCLUDED_FILES, s as SKILL_MANIFEST_FILE, u as SKILL_PACK_FILE, v as buildCatalog, w as exportSkills, y as buildManifest } from "./dist-8oQRa8Xz.js";
+import { J as normalizeToolError, P as createWebSkillApi, U as mergeCatalogEntries, W as networkPolicyLibSource, Y as parseBridgeRequest, a as AnthropicClient, d as FsMemoryStore, f as FsRunSnapshotStore, g as GoogleGenAiClient, i as AgentLoop, k as bridgeError, o as CapabilityApproval, q as normalizeToolContent, u as FsArtifactStore, v as OpenAiCompatibleClient, y as ProgressiveRouter } from "./dist-6C03DShK.js";
 import { n as MockLlmClient } from "./testing-DDCJWvgA.js";
 
 //#region ../browser/dist/index.js
@@ -371,17 +371,26 @@ self.onmessage = async function (event) {
   }
 };
 `;
-let esbuildPromise;
+/** 按资源地址缓存，而不是全局单例：不同地址必须各自加载，否则先到的实例会顶替后来的配置 */
+const esbuildCache = /* @__PURE__ */ new Map();
 async function loadEsbuild(options) {
-	esbuildPromise ??= (async () => {
-		const mod = await import(
-			/* @vite-ignore */
-			options.esbuildUrl
+	const key = `${options.esbuildUrl}\n${options.wasmUrl ?? ""}`;
+	let pending = esbuildCache.get(key);
+	if (!pending) {
+		pending = (async () => {
+			const mod = await import(
+				/* @vite-ignore */
+				options.esbuildUrl
 );
-		await mod.initialize(options.wasmUrl ? { wasmURL: options.wasmUrl } : {});
-		return mod;
-	})();
-	return esbuildPromise;
+			await mod.initialize(options.wasmUrl ? { wasmURL: options.wasmUrl } : {});
+			return mod;
+		})().catch((e) => {
+			esbuildCache.delete(key);
+			throw e;
+		});
+		esbuildCache.set(key, pending);
+	}
+	return pending;
 }
 async function sha256Hex(data) {
 	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(data));
@@ -400,19 +409,25 @@ var TsTranspiler = class {
 		this.#options = deps.options;
 		this.#cacheDir = deps.cacheDir ?? ".webskill/ts-cache";
 	}
-	/** 返回 JS 源码；转译失败 → TOOL_EXECUTION_FAILED（带 esbuild 诊断） */
+	/** 返回 JS 源码；转译器不可用 → TS_TRANSPILER_UNAVAILABLE，语法错 → TS_TRANSPILE_FAILED */
 	async transpile(scriptPath, source) {
 		const cacheKey = `${this.#cacheDir}/${await sha256Hex(`${scriptPath}\n${source}`)}.js`;
 		if (await this.#fs.exists(cacheKey)) return this.#fs.readText(cacheKey);
+		let esbuild;
+		try {
+			esbuild = await loadEsbuild(this.#options);
+		} catch (e) {
+			throw new WebSkillError("TS_TRANSPILER_UNAVAILABLE", `Failed to load the TypeScript transpiler from "${this.#options.esbuildUrl}": ${messageOf(e)}`, e);
+		}
 		let code;
 		try {
-			code = (await (await loadEsbuild(this.#options)).transform(source, {
+			code = (await esbuild.transform(source, {
 				loader: "ts",
 				target: "es2022",
 				format: "esm"
 			})).code;
 		} catch (e) {
-			throw new WebSkillError("TOOL_EXECUTION_FAILED", `Failed to transpile ${scriptPath}: ${e instanceof Error ? e.message : String(e)}`, e);
+			throw new WebSkillError("TS_TRANSPILE_FAILED", `Failed to transpile ${scriptPath}: ${messageOf(e)}`, e);
 		}
 		await this.#fs.writeText(cacheKey, code);
 		return code;
@@ -461,8 +476,26 @@ async function extractZipWeb(fs, data, destRoot, limits) {
 		else await fs.writeBinary(target, content);
 	}
 }
-const asInstallFailed = (e) => e instanceof WebSkillError && (e.code === "INSTALL_FAILED" || e.code === "TOOL_UNSUPPORTED") ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf(e)}`, e);
+/**
+* 验签失败不能被折叠成 INSTALL_FAILED：四种失败的宿主处置完全不同
+* （引导选策略 / 提示重下 / 引导添加密钥 / 安全事件），与 Node 侧同口径。
+*/
+const PRESERVED_INSTALL_CODES = /* @__PURE__ */ new Set([
+	"SIGNATURE_MISSING",
+	"SIGNATURE_MALFORMED",
+	"SIGNATURE_UNTRUSTED_KEY",
+	"SIGNATURE_MISMATCH",
+	"SIGNATURE_UNSUPPORTED"
+]);
+const asInstallFailed = (e) => e instanceof WebSkillError && (e.code === "INSTALL_FAILED" || e.code === "TOOL_UNSUPPORTED" || PRESERVED_INSTALL_CODES.has(e.code)) ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf(e)}`, e);
 const lockfilePath = (root) => `${root}/${SKILLS_LOCKFILE}`;
+/** 未注入信任库时的空实现：策略仍然生效，只是没有任何受信公钥 */
+const EMPTY_TRUSTED_KEYS = {
+	list: () => Promise.resolve([]),
+	get: () => Promise.resolve(void 0),
+	add: () => Promise.reject(new WebSkillError("TOOL_UNSUPPORTED", "No trusted key store is configured")),
+	remove: () => Promise.reject(new WebSkillError("TOOL_UNSUPPORTED", "No trusted key store is configured"))
+};
 /**
 * D5：浏览器技能安装（http(s) zip / ArrayBuffer；tar/git/npm → TOOL_UNSUPPORTED）。
 * 流程与 Node 对齐：staging → 解析 name → validateSkills（失败零残留）→ managed root →
@@ -475,12 +508,34 @@ var BrowserSkillManager = class {
 	#fetchImpl;
 	#archiveLimits;
 	#onChanged;
+	#trustedKeys;
+	#unsignedPolicy;
+	#onWarning;
 	constructor(deps) {
 		this.#fs = deps.fs;
 		this.#managedRoot = deps.managedRoot.replace(/\/+$/, "");
 		this.#fetchImpl = deps.fetchImpl;
 		this.#archiveLimits = deps.archiveLimits;
 		this.#onChanged = deps.onChanged;
+		this.#trustedKeys = deps.signature?.trustedKeys ?? EMPTY_TRUSTED_KEYS;
+		this.#unsignedPolicy = deps.signature?.unsigned ?? "warn";
+		this.#onWarning = deps.onWarning;
+	}
+	/**
+	* 安装期验签：manifest 生成之后、提交 swap 之前。失败直接抛出，
+	* 暂存目录由 install 的 finally 清理，不落盘。
+	*/
+	async #verifySignature(skillDir, manifest) {
+		const verdict = await verifySkillSignature({
+			manifest,
+			signature: await readSkillSignature(this.#fs, skillDir),
+			trustedKeys: this.#trustedKeys,
+			policy: { unsigned: this.#unsignedPolicy }
+		});
+		if (verdict.warning !== void 0) this.#onWarning?.({
+			skill: manifest.name,
+			message: verdict.warning
+		});
 	}
 	async install(source, options) {
 		const fs = this.#fs;
@@ -546,6 +601,7 @@ var BrowserSkillManager = class {
 				...version ? { version } : {},
 				source
 			});
+			await this.#verifySignature(finalDir, manifest);
 			targetDir = `${this.#managedRoot}/${name}`;
 			const backupDir = `${stagingRoot}/backup`;
 			const hadPrevious = await fs.exists(targetDir);
@@ -614,6 +670,7 @@ var BrowserSkillManager = class {
 					source
 				});
 				if (manifest.integrity.digest !== entry.digest) throw new WebSkillError("INSTALL_FAILED", `Skill "${entry.name}" digest mismatch: expected ${entry.digest}, got ${manifest.integrity.digest}`);
+				await this.#verifySignature(`${finalRoot}/${entry.name}`, manifest);
 				manifests.push(manifest);
 			}
 			const swapped = [];
@@ -906,7 +963,7 @@ var BrowserWorkerScriptExecutor = class {
 		const [hasJs, hasTs] = await Promise.all([this.#fs.exists(jsPath), this.#fs.exists(tsPath)]);
 		if (hasJs && hasTs) throw new WebSkillError("TOOL_EXECUTION_FAILED", `Script "${scriptName}" is ambiguous: both .ts and .js exist under ${skillRoot}/scripts`);
 		if (hasTs) {
-			if (!this.#transpiler) throw new WebSkillError("TOOL_UNSUPPORTED", `Browser sandbox executes .js only unless TypeScript support is configured ("${scriptName}.ts")`);
+			if (!this.#transpiler) throw new WebSkillError("TOOL_UNSUPPORTED", `Browser sandbox executes .js only unless TypeScript support is configured ("${scriptName}.ts"). Enable it under runtime configuration sandbox.typescript and provide an esbuild-wasm URL.`);
 			return {
 				path: tsPath,
 				source: await this.#transpiler.transpile(tsPath, await this.#fs.readText(tsPath))
@@ -1123,6 +1180,389 @@ function installWebSkillNavigator(config) {
 	nav["webskill"] = api;
 	return api;
 }
+function languageModel() {
+	const candidate = globalThis.LanguageModel;
+	return typeof candidate?.availability === "function" && typeof candidate.create === "function" ? candidate : void 0;
+}
+/** 缺 API 时区分「这个浏览器根本不支持」与「Chromium 但版本/开关没到位」，两者的用户动作不同 */
+function missingReason() {
+	const nav = globalThis.navigator;
+	return nav?.userAgentData?.brands?.some((entry) => /Chromium|Google Chrome/i.test(entry.brand)) === true || /Chrome\//.test(nav?.userAgent ?? "") ? "api-missing" : "unsupported-browser";
+}
+/**
+* 进入模型配置界面时调用（FR-4.7）：不可用时给出具体原因，禁止「选了之后才失败」。
+* 模型还在下载也算不可用——这一轮对话等不到它。
+*/
+async function probeChromeBuiltinAvailability() {
+	const api = languageModel();
+	if (!api) return {
+		available: false,
+		reason: missingReason()
+	};
+	try {
+		return await api.availability() === "available" ? { available: true } : {
+			available: false,
+			reason: "model-not-ready"
+		};
+	} catch {
+		return {
+			available: false,
+			reason: "model-not-ready"
+		};
+	}
+}
+const textOf = (message) => message.content.map((part) => part.type === "text" ? part.text : `[${part.type}]`).join("").trim();
+/** tool 角色 Prompt API 不认识，降级成 user 文本——内置模型本来就不做工具调用 */
+function toInitialPrompt(message) {
+	const text = textOf(message);
+	if (message.role === "assistant") return {
+		role: "assistant",
+		content: text
+	};
+	return {
+		role: "user",
+		content: message.role === "tool" ? `Tool result: ${text}` : text
+	};
+}
+function splitInput(input) {
+	const system = input.messages.filter((m) => m.role === "system").map(textOf).filter((text) => text !== "");
+	const rest = input.messages.filter((m) => m.role !== "system");
+	const last = rest.at(-1);
+	return {
+		initialPrompts: [...system.length > 0 ? [{
+			role: "system",
+			content: system.join("\n\n")
+		}] : [], ...rest.slice(0, -1).map(toInitialPrompt)],
+		prompt: last ? toInitialPrompt(last).content : ""
+	};
+}
+/**
+* 浏览器内置模型客户端（Prompt API）。**不支持工具调用**——`input.tools` 被忽略，
+* 模型只会产出文本，因此技能里的脚本步骤在这一档跑不起来（FR-4.8 要求 UI 标注该限制）。
+* @experimental
+*/
+var ChromeBuiltinLlmClient = class {
+	#temperature;
+	constructor(options = {}) {
+		if (options.temperature !== void 0) this.#temperature = options.temperature;
+	}
+	async #session(input) {
+		const api = languageModel();
+		if (!api) throw new WebSkillError("LLM_UNAVAILABLE", "The Chrome built-in model is not available in this browser (Prompt API missing)");
+		const { initialPrompts, prompt } = splitInput(input);
+		const temperature = input.temperature ?? this.#temperature;
+		return {
+			session: await api.create({
+				...initialPrompts.length > 0 ? { initialPrompts } : {},
+				...temperature !== void 0 ? { temperature } : {},
+				...input.signal ? { signal: input.signal } : {}
+			}),
+			prompt
+		};
+	}
+	async complete(input) {
+		const { session, prompt } = await this.#session(input);
+		try {
+			return { content: [{
+				type: "text",
+				text: await session.prompt(prompt, ...input.signal ? [{ signal: input.signal }] : [])
+			}] };
+		} finally {
+			session.destroy?.();
+		}
+	}
+	async *stream(input) {
+		const { session, prompt } = await this.#session(input);
+		if (!session.promptStreaming) {
+			try {
+				const text = await session.prompt(prompt, ...input.signal ? [{ signal: input.signal }] : []);
+				yield {
+					type: "text-delta",
+					delta: text
+				};
+				yield {
+					type: "done",
+					content: text
+				};
+			} finally {
+				session.destroy?.();
+			}
+			return;
+		}
+		let content = "";
+		try {
+			const reader = session.promptStreaming(prompt, ...input.signal ? [{ signal: input.signal }] : []).getReader();
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				if (value !== void 0 && value !== "") {
+					content += value;
+					yield {
+						type: "text-delta",
+						delta: value
+					};
+				}
+			}
+			yield {
+				type: "done",
+				content
+			};
+		} finally {
+			session.destroy?.();
+		}
+	}
+	async checkAvailability() {
+		return (await probeChromeBuiltinAvailability()).available;
+	}
+};
+/**
+* 配置 → `LlmClient`。收在 SDK 里是为了让下游只跟 `RuntimeConfigStore` 打交道，
+* 不必自己维护「provider → client 类」的映射（设计 04 §5）。
+*/
+function createLlmClient(config) {
+	if (config.provider === "chrome-builtin") return new ChromeBuiltinLlmClient();
+	const common = {
+		...config.baseUrl?.trim() ? { baseUrl: config.baseUrl.trim() } : {},
+		...config.requestTimeoutMs !== void 0 ? { requestTimeoutMs: config.requestTimeoutMs } : {}
+	};
+	const apiKey = config.apiKey?.trim() ?? "";
+	if (config.provider === "anthropic") return new AnthropicClient({
+		...common,
+		apiKey,
+		model: config.model
+	});
+	if (config.provider === "google") return new GoogleGenAiClient({
+		...common,
+		apiKey,
+		model: config.model
+	});
+	return new OpenAiCompatibleClient({
+		...common,
+		...apiKey !== "" ? { apiKey } : {},
+		model: config.model
+	});
+}
+function recognitionCtor() {
+	const scope = globalThis;
+	return scope.SpeechRecognition ?? scope.webkitSpeechRecognition;
+}
+/**
+* 渲染期调用（FR-7.2）：不可用时按钮置灰并说明原因，禁止呈现为可用后才失败。
+*
+* 顺序是刻意的——构造器都不存在时谈安全上下文没有意义；
+* 构造器在但站点是 http，识别一定会被浏览器拒绝，这条原因用户能自己解决。
+* @experimental
+*/
+function checkDictationAvailability() {
+	if (recognitionCtor() === void 0) return {
+		available: false,
+		reason: "api-missing"
+	};
+	if (globalThis.isSecureContext === false) return {
+		available: false,
+		reason: "insecure-context"
+	};
+	return { available: true };
+}
+/** 浏览器的 error 码 → 稳定错误码；权限被拒要单独区分，UI 的降级提示不一样（FR-7.6） */
+function toError(code, message) {
+	if (code === "not-allowed" || code === "service-not-allowed") return new WebSkillError("DICTATION_PERMISSION_DENIED", "Microphone access was denied. Voice input is unavailable until you allow it in the browser.", { reason: code });
+	return new WebSkillError("DICTATION_FAILED", message ?? `Speech recognition failed: ${code}`, { reason: code });
+}
+/**
+* 开始一次语音识别（FR-7.1）。
+*
+* **只能由用户手势调用**（FR-7.3）。设计上的保证是它不进工具列表：
+* agent 拿不到「开始录音」这个动作，因此不存在自主开麦的路径。
+* @experimental
+*/
+function startDictation(options) {
+	const Ctor = recognitionCtor();
+	if (Ctor === void 0) throw new WebSkillError("DICTATION_UNAVAILABLE", "Speech recognition is not available in this browser.");
+	const recognition = new Ctor();
+	recognition.lang = options.lang;
+	recognition.continuous = true;
+	recognition.interimResults = true;
+	/** stop() 之后浏览器仍可能派发一轮回调；这里做一次闸门，保证「停了就不再收结果」 */
+	let stopped = false;
+	recognition.onresult = (event) => {
+		if (stopped) return;
+		let interim = "";
+		for (let index = event.resultIndex; index < event.results.length; index += 1) {
+			const result = event.results[index];
+			if (result === void 0) continue;
+			const text = result[0]?.transcript ?? "";
+			if (text === "") continue;
+			if (result.isFinal) options.onFinal(text);
+			else interim += text;
+		}
+		if (interim !== "") options.onInterim(interim);
+	};
+	recognition.onerror = (event) => {
+		if (stopped) return;
+		if (event.error === "no-speech" || event.error === "aborted") return;
+		options.onError(toError(event.error, event.message));
+	};
+	try {
+		recognition.start();
+	} catch (e) {
+		throw new WebSkillError("DICTATION_UNAVAILABLE", `Speech recognition could not start: ${String(e)}`);
+	}
+	return { stop() {
+		if (stopped) return;
+		stopped = true;
+		recognition.onresult = null;
+		recognition.onerror = null;
+		recognition.onend = null;
+		recognition.stop();
+	} };
+}
+/** 值可能是凭据的输入类型：即便宿主忘了写进 exclude 也不读值 */
+const SECRET_INPUT_TYPES = /* @__PURE__ */ new Set(["password", "hidden"]);
+/** tag → 可访问性角色的最小映射；命中不了就退到 generic，不猜 */
+const ROLE_BY_TAG = {
+	A: "link",
+	BUTTON: "button",
+	H1: "heading",
+	H2: "heading",
+	H3: "heading",
+	H4: "heading",
+	H5: "heading",
+	H6: "heading",
+	IMG: "img",
+	LI: "listitem",
+	NAV: "navigation",
+	OL: "list",
+	P: "paragraph",
+	SELECT: "combobox",
+	TABLE: "table",
+	TD: "cell",
+	TEXTAREA: "textbox",
+	TH: "columnheader",
+	TR: "row",
+	UL: "list"
+};
+const INPUT_TYPE_ROLE = {
+	button: "button",
+	checkbox: "checkbox",
+	radio: "radio",
+	submit: "button"
+};
+/** 名称与值都截断：一个超长文本节点不该把上下文吃光 */
+const MAX_TEXT = 200;
+const clip = (text) => {
+	const normalized = text.replace(/\s+/g, " ").trim();
+	return normalized.length > MAX_TEXT ? `${normalized.slice(0, MAX_TEXT)}…` : normalized;
+};
+function roleOf(element) {
+	const explicit = element.getAttribute("role");
+	if (explicit !== null && explicit.trim() !== "") return explicit.trim();
+	if (element.tagName === "INPUT") {
+		const type = (element.getAttribute("type") ?? "text").toLowerCase();
+		return INPUT_TYPE_ROLE[type] ?? "textbox";
+	}
+	return ROLE_BY_TAG[element.tagName] ?? "generic";
+}
+/** 自身直系文本（不含后代元素的文本）：后代会各自成为节点，重复没有意义 */
+function ownText(element) {
+	let text = "";
+	for (const node of element.childNodes) if (node.nodeType === 3) text += node.nodeValue ?? "";
+	return clip(text);
+}
+function nameOf(element, doc) {
+	const label = element.getAttribute("aria-label");
+	if (label !== null && label.trim() !== "") return clip(label);
+	const labelledBy = element.getAttribute("aria-labelledby");
+	if (labelledBy !== null) {
+		const parts = labelledBy.split(/\s+/).map((id) => doc.getElementById(id)?.textContent ?? "").filter((part) => part.trim() !== "");
+		if (parts.length > 0) return clip(parts.join(" "));
+	}
+	if (element.tagName === "IMG") {
+		const alt = element.getAttribute("alt");
+		if (alt !== null && alt.trim() !== "") return clip(alt);
+	}
+	const own = ownText(element);
+	return own === "" ? void 0 : own;
+}
+function valueOf(element) {
+	if (element.tagName === "INPUT") {
+		const type = (element.getAttribute("type") ?? "text").toLowerCase();
+		if (SECRET_INPUT_TYPES.has(type)) return void 0;
+		const value = element.value;
+		return value === "" ? void 0 : clip(value);
+	}
+	if (element.tagName === "TEXTAREA" || element.tagName === "SELECT") {
+		const value = element.value;
+		return value === "" ? void 0 : clip(value);
+	}
+}
+/**
+* 隐藏节点不进结果：屏幕上看不见的东西，用户没有机会发现它被读走了。
+* jsdom 里 `getComputedStyle` 可用但布局是假的，因此只看显式声明，不看尺寸。
+*/
+function hidden(element, view) {
+	if (element.hasAttribute("hidden")) return true;
+	if (element.getAttribute("aria-hidden") === "true") return true;
+	const inlineStyle = element.getAttribute("style") ?? "";
+	if (/display\s*:\s*none|visibility\s*:\s*hidden/i.test(inlineStyle)) return true;
+	if (view !== null) {
+		const computed = view.getComputedStyle(element);
+		if (computed.display === "none" || computed.visibility === "hidden") return true;
+	}
+	return false;
+}
+/** script / style 的正文是代码，不是页面内容 */
+const SKIPPED_TAGS = /* @__PURE__ */ new Set([
+	"SCRIPT",
+	"STYLE",
+	"NOSCRIPT",
+	"TEMPLATE"
+]);
+function describe(element, excluded, doc, view) {
+	if (excluded.has(element)) return void 0;
+	if (SKIPPED_TAGS.has(element.tagName)) return void 0;
+	if (hidden(element, view)) return void 0;
+	const children = [];
+	for (const child of element.children) {
+		const node = describe(child, excluded, doc, view);
+		if (node !== void 0) children.push(node);
+	}
+	const name = nameOf(element, doc);
+	const value = valueOf(element);
+	const role = roleOf(element);
+	if (role === "generic" && name === void 0 && value === void 0 && children.length === 0) return void 0;
+	return {
+		role,
+		...name !== void 0 ? { name } : {},
+		...value !== void 0 ? { value } : {},
+		...children.length > 0 ? { children } : {}
+	};
+}
+/**
+* DOM 遍历实现（设计 09 §2 的「实现层」）。产出只有角色 / 名称 / 值，
+* **不含任何 HTML 标记、class、data 属性或注释**（FR-10.4）。
+*
+* 判定顺序是先 `include` 取子树再 `exclude` 剪枝：`exclude` 命中的元素连同
+* 其整棵后代一起消失，而不是只去掉那一个节点。
+* @experimental
+*/
+function createDomPerceptionReader(options = {}) {
+	return { read(scope) {
+		const doc = options.document ?? globalThis.document;
+		if (doc === void 0 || scope.include.length === 0) return [];
+		const view = doc.defaultView;
+		const excluded = /* @__PURE__ */ new Set();
+		for (const selector of scope.exclude ?? []) for (const element of doc.querySelectorAll(selector)) excluded.add(element);
+		const roots = [];
+		for (const selector of scope.include) for (const element of doc.querySelectorAll(selector)) if (!roots.includes(element)) roots.push(element);
+		const nodes = [];
+		for (const root of roots) {
+			const node = describe(root, excluded, doc, view);
+			if (node !== void 0) nodes.push(node);
+		}
+		return nodes;
+	} };
+}
 const isRecord = (v) => typeof v === "object" && v !== null;
 const isNonEmptyString = (v) => typeof v === "string" && v !== "";
 /** Worker 侧入站校验：非法消息返回 undefined（忽略） */
@@ -1638,4 +2078,4 @@ var WorkerRuntimeClient = class {
 };
 
 //#endregion
-export { BrowserSkillManager, BrowserWorkerScriptExecutor, IframeWorkerLike, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, createIframeWorker, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, startWorkerRuntimeHost };
+export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, IframeWorkerLike, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, checkDictationAvailability, createDomPerceptionReader, createIframeWorker, createLlmClient, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };