@webskill/sdk 0.6.0 → 0.8.0

package/dist/browser.js

@@ -1,6 +1,6 @@
-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 { H as createWebSkillApi, S as ProgressiveRouter, a as AgentLoop, at as normalizeToolContent, c as CapabilityApproval, et as mergeCatalogEntries, h as FsRunSnapshotStore, m as FsMemoryStore, nt as networkPolicyLibSource, o as AnthropicClient, ot as normalizeToolError, p as FsArtifactStore, st as parseBridgeRequest, x as OpenAiCompatibleClient, y as GoogleGenAiClient, z as bridgeError } from "./dist-DusANsrn.js";
-import { n as MockLlmClient } from "./testing-CYTFqkDm.js";
+import { A as messageOf, D as isValidSkillName, E as exportSkills, F as readSkillSignature, G as verifyManifest, K as verifySkillSignature, M as parseSkillMarkdown, N as parseSkillPackManifest, P as readResponseWithLimit, U as unzipWithLimits, W as validateSkills, _ as atomicWriteText, f as SkillDiscovery, h as assertRemoteUrlAllowed, 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 detectSkillArchiveShapeFromFs, y as buildManifest, z as resolveInsideRoot } from "./dist-59XlqDuv.js";
+import { B as bridgeError, C as ProgressiveRouter, S as OpenAiCompatibleClient, U as createWebSkillApi, a as AgentLoop, b as GoogleGenAiClient, c as CapabilityApproval, dt as parseBridgeRequest, g as FsRunSnapshotStore, h as FsMemoryStore, it as mergeCatalogEntries, lt as normalizeToolContent, m as FsArtifactStore, o as AnthropicClient, ot as networkPolicyLibSource, ut as normalizeToolError } from "./dist-DmI5SBBF.js";
+import { n as MockLlmClient } from "./testing-BCUO5gZR.js";
 
 //#region ../browser/dist/index.js
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -490,7 +490,8 @@ const PRESERVED_INSTALL_CODES = /* @__PURE__ */ new Set([
 	"SIGNATURE_MALFORMED",
 	"SIGNATURE_UNTRUSTED_KEY",
 	"SIGNATURE_MISMATCH",
-	"SIGNATURE_UNSUPPORTED"
+	"SIGNATURE_UNSUPPORTED",
+	"SKILL_DUPLICATE_NAME"
 ]);
 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}`;
@@ -510,6 +511,8 @@ const EMPTY_TRUSTED_KEYS = {
 var BrowserSkillManager = class {
 	#fs;
 	#managedRoot;
+	/** 只读技能根（宿主自带的本地技能）：参与导出与依赖存在性判定，但不可卸载 */
+	#skillRoots;
 	#fetchImpl;
 	#archiveLimits;
 	#onChanged;
@@ -519,6 +522,7 @@ var BrowserSkillManager = class {
 	constructor(deps) {
 		this.#fs = deps.fs;
 		this.#managedRoot = deps.managedRoot.replace(/\/+$/, "");
+		this.#skillRoots = (deps.skillRoots ?? []).map((root) => root.replace(/\/+$/, ""));
 		this.#fetchImpl = deps.fetchImpl;
 		this.#archiveLimits = deps.archiveLimits;
 		this.#onChanged = deps.onChanged;
@@ -572,17 +576,16 @@ var BrowserSkillManager = class {
 			const contentDir = `${stagingRoot}/content`;
 			await fs.mkdir(contentDir);
 			await extractZipWeb(fs, data, contentDir, this.#archiveLimits);
-			const packFilePath = `${contentDir}/${SKILL_PACK_FILE}`;
-			if (await fs.exists(packFilePath)) return (await this.#installPack({
-				contentDir,
-				manifest: parseSkillPackManifest(await fs.readText(packFilePath))
-			}, source, stagingRoot))[0];
-			let skillDir = contentDir;
-			if (!await fs.exists(`${contentDir}/SKILL.md`)) {
-				const dirs = (await fs.list(contentDir)).filter((e) => e.type === "directory");
-				if (dirs.length === 1 && await fs.exists(`${dirs[0]?.path}/SKILL.md`)) skillDir = dirs[0].path;
-				else throw new WebSkillError("INSTALL_FAILED", "Archive does not contain a SKILL.md at its root or in a single top-level directory");
+			const detection = await detectSkillArchiveShapeFromFs(fs, contentDir);
+			if (detection.shape === "invalid") throw new WebSkillError("INSTALL_FAILED", detection.reason ?? "Archive layout is not recognised");
+			if (detection.shape === "pack-set") {
+				const packRoot = detection.rootDir === void 0 ? contentDir : `${contentDir}/${detection.rootDir}`;
+				return (await this.#installPack({
+					contentDir: packRoot,
+					manifest: parseSkillPackManifest(await fs.readText(`${packRoot}/${SKILL_PACK_FILE}`))
+				}, source, stagingRoot))[0];
 			}
+			const skillDir = detection.rootDir === void 0 ? contentDir : `${contentDir}/${detection.rootDir}`;
 			let name;
 			let version;
 			try {
@@ -593,13 +596,18 @@ var BrowserSkillManager = class {
 				throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md: ${messageOf(e)}`, e);
 			}
 			if (!isValidSkillName(name)) throw new WebSkillError("INSTALL_FAILED", `Invalid skill name in SKILL.md (path traversal rejected): ${JSON.stringify(name)}`);
+			if (options?.replace === "reject" && await fs.exists(`${this.#managedRoot}/${name}`)) throw new WebSkillError("SKILL_DUPLICATE_NAME", `A skill named "${name}" is already installed. Installing it again replaces the existing files; use the packages flow if that is intended.`);
 			const finalRoot = `${stagingRoot}/final`;
 			const finalDir = `${finalRoot}/${name}`;
 			await copyDir(fs, skillDir, finalDir);
-			const report = await validateSkills(fs, [finalRoot]);
+			const report = await validateSkills(fs, [finalRoot], { extraKnownSkillNames: await this.listSkillNames() });
 			if (!report.ok) {
-				const errors = report.issues.filter((i) => i.severity === "error");
-				throw new WebSkillError("INSTALL_FAILED", `Skill "${name}" failed validation: ${errors.map((i) => i.message).join("; ")}`, errors);
+				const errors = report.issues.filter((i) => i.severity === "error" && i.code !== "SKILL_UNKNOWN_DEPENDENCY");
+				for (const issue of report.issues) if (issue.code === "SKILL_UNKNOWN_DEPENDENCY") this.#onWarning?.({
+					skill: name,
+					message: issue.message
+				});
+				if (errors.length > 0) throw new WebSkillError("INSTALL_FAILED", `Skill "${name}" failed validation: ${errors.map((i) => i.message).join("; ")}`, errors);
 			}
 			const manifest = await this.#createManifest(finalDir, {
 				name,
@@ -714,6 +722,21 @@ var BrowserSkillManager = class {
 			throw asInstallFailed(e);
 		}
 	}
+	/** 技能的真实根：先 managed，再只读根。都没有则 undefined */
+	async #resolveSkillRoot(name) {
+		const managed = `${this.#managedRoot}/${name}`;
+		if (await this.#fs.exists(managed)) return {
+			root: managed,
+			managed: true
+		};
+		for (const base of this.#skillRoots) {
+			const candidate = `${base}/${name}`;
+			if (await this.#fs.exists(candidate)) return {
+				root: candidate,
+				managed: false
+			};
+		}
+	}
 	/**
 	* 浏览器导出（单技能与包集同构：始终产出含 webskill.skill-pack.json 的 zip 字节，
 	* 统一安装路径；保存/下载由应用层处理）。
@@ -721,11 +744,13 @@ var BrowserSkillManager = class {
 	async exportArchive(names) {
 		const list = Array.isArray(names) ? names : [names];
 		if (list.length === 0) throw new WebSkillError("EXPORT_FAILED", "exportArchive requires at least one skill name");
-		const roots = list.map((name) => {
+		const roots = [];
+		for (const name of list) {
 			if (!isValidSkillName(name)) throw new WebSkillError("EXPORT_FAILED", `Invalid skill name (path traversal rejected): ${JSON.stringify(name)}`);
-			return `${this.#managedRoot}/${name}`;
-		});
-		for (const [index, root] of roots.entries()) if (!await this.#fs.exists(root)) throw new WebSkillError("EXPORT_FAILED", `Skill "${list[index]}" is not installed`);
+			const resolved = await this.#resolveSkillRoot(name);
+			if (resolved === void 0) throw new WebSkillError("EXPORT_FAILED", `Skill "${name}" is not installed`);
+			roots.push(resolved.root);
+		}
 		return exportSkills(this.#fs, {
 			roots,
 			manifestBuilder: (root) => this.#readManifest(root)
@@ -733,8 +758,10 @@ var BrowserSkillManager = class {
 	}
 	async uninstall(name) {
 		if (!isValidSkillName(name)) throw new WebSkillError("UNINSTALL_FAILED", `Invalid skill name (path traversal rejected): ${JSON.stringify(name)}`);
-		const targetDir = `${this.#managedRoot}/${name}`;
-		if (!await this.#fs.exists(targetDir)) throw new WebSkillError("UNINSTALL_FAILED", `Skill "${name}" is not installed`);
+		const resolved = await this.#resolveSkillRoot(name);
+		if (resolved === void 0) throw new WebSkillError("UNINSTALL_FAILED", `Skill "${name}" is not installed`);
+		if (!resolved.managed) throw new WebSkillError("UNINSTALL_FAILED", `Skill "${name}" ships with the host application and is not managed by the skill manager; remove it from the host's skill root instead.`);
+		const targetDir = resolved.root;
 		try {
 			await this.#fs.remove(targetDir, { recursive: true });
 			await this.#removeLockEntry(name);
@@ -763,6 +790,22 @@ var BrowserSkillManager = class {
 			throw new WebSkillError("INTEGRITY_FAILED", `Skills lockfile at ${path} is corrupted: ${messageOf(e)}`, e);
 		}
 	}
+	/**
+	* 库里已有的技能名：managed 目录 + 宿主声明的只读根。读失败按「库为空」处理，不阻断安装。
+	* 与 `listInstalled()` 的区别是**含本地技能**（后者只看安装账本）。
+	* @experimental
+	*/
+	async listSkillNames() {
+		const names = [];
+		for (const root of [this.#managedRoot, ...this.#skillRoots]) {
+			if (!await this.#fs.exists(root).catch(() => false)) continue;
+			for (const stat of await this.#fs.list(root).catch(() => [])) {
+				const name = stat.path.split("/").pop() ?? "";
+				if (stat.type === "directory" && isValidSkillName(name)) names.push(name);
+			}
+		}
+		return names;
+	}
 	async #createManifest(skillRoot, input) {
 		const files = [];
 		for (const rel of (await listFiles(this.#fs, skillRoot)).sort()) {
@@ -787,7 +830,16 @@ var BrowserSkillManager = class {
 	}
 	async #readManifest(skillRoot) {
 		const path = `${skillRoot}/${SKILL_MANIFEST_FILE}`;
-		if (!await this.#fs.exists(path)) throw new WebSkillError("INTEGRITY_FAILED", `Skill manifest not found at ${path} (was the skill installed via BrowserSkillManager?)`);
+		if (!await this.#fs.exists(path)) {
+			const name = skillRoot.split("/").pop() ?? skillRoot;
+			return this.#createManifest(skillRoot, {
+				name,
+				source: {
+					type: "local",
+					path: skillRoot
+				}
+			});
+		}
 		try {
 			return JSON.parse(await this.#fs.readText(path));
 		} catch (e) {
@@ -1615,8 +1667,20 @@ function describeError(e) {
 	if (e instanceof TypeError) return "the request was blocked, most likely by CORS";
 	return e instanceof Error ? e.message : String(e);
 }
-/** 值可能是凭据的输入类型：即便宿主忘了写进 exclude 也不读值 */
+/** 值可能是凭据的输入类型：即便宿主忘了写进 exclude 也不读值。操作侧复用同一份，不另写 */
 const SECRET_INPUT_TYPES = /* @__PURE__ */ new Set(["password", "hidden"]);
+/** 可被操作的角色：只给这些节点发句柄，其余节点模型连提都提不出来 */
+const ACTIONABLE_ROLES = /* @__PURE__ */ new Set([
+	"button",
+	"checkbox",
+	"combobox",
+	"form",
+	"link",
+	"radio",
+	"searchbox",
+	"switch",
+	"textbox"
+]);
 /** tag → 可访问性角色的最小映射；命中不了就退到 generic，不猜 */
 const ROLE_BY_TAG = {
 	A: "link",
@@ -1654,7 +1718,7 @@ const clip = (text) => {
 	const normalized = text.replace(/\s+/g, " ").trim();
 	return normalized.length > MAX_TEXT ? `${normalized.slice(0, MAX_TEXT)}…` : normalized;
 };
-function roleOf(element) {
+function roleOf$1(element) {
 	const explicit = element.getAttribute("role");
 	if (explicit !== null && explicit.trim() !== "") return explicit.trim();
 	if (element.tagName === "INPUT") {
@@ -1700,7 +1764,7 @@ function valueOf(element) {
 * 隐藏节点不进结果：屏幕上看不见的东西，用户没有机会发现它被读走了。
 * jsdom 里 `getComputedStyle` 可用但布局是假的，因此只看显式声明，不看尺寸。
 */
-function hidden(element, view) {
+function hidden$1(element, view) {
 	if (element.hasAttribute("hidden")) return true;
 	if (element.getAttribute("aria-hidden") === "true") return true;
 	const inlineStyle = element.getAttribute("style") ?? "";
@@ -1718,18 +1782,18 @@ const SKIPPED_TAGS = /* @__PURE__ */ new Set([
 	"NOSCRIPT",
 	"TEMPLATE"
 ]);
-function describe(element, excluded, doc, view, targets) {
+function describe(element, excluded, doc, view, targets, handles) {
 	if (excluded.has(element)) return void 0;
 	if (SKIPPED_TAGS.has(element.tagName)) return void 0;
-	if (hidden(element, view)) return void 0;
+	if (hidden$1(element, view)) return void 0;
 	const children = [];
 	for (const child of element.children) {
-		const node = describe(child, excluded, doc, view, targets);
+		const node = describe(child, excluded, doc, view, targets, handles);
 		if (node !== void 0) children.push(node);
 	}
 	const name = nameOf(element, doc);
 	const value = valueOf(element);
-	const role = roleOf(element);
+	const role = roleOf$1(element);
 	if (role === "generic" && name === void 0 && value === void 0 && children.length === 0) return void 0;
 	const node = {
 		role,
@@ -1737,6 +1801,8 @@ function describe(element, excluded, doc, view, targets) {
 		...value !== void 0 ? { value } : {},
 		...children.length > 0 ? { children } : {}
 	};
+	const ref = handles?.issue(element, role);
+	if (ref !== void 0) node.ref = ref;
 	if (targets !== void 0 && isCapturableElement(element)) targets.push({
 		element,
 		node
@@ -1744,6 +1810,31 @@ function describe(element, excluded, doc, view, targets) {
 	return node;
 }
 /**
+* 句柄发放与解析。表在 reader 实例内、每次 `read()` 整体替换：
+* 全局表是第二套状态且会跨会话泄漏；不替换则页面变了还能用旧句柄点到别的东西。
+*/
+var HandleIssuer = class {
+	#table = /* @__PURE__ */ new Map();
+	#actionable;
+	#excluded;
+	constructor(actionable, excluded) {
+		this.#actionable = actionable;
+		this.#excluded = excluded;
+	}
+	issue(element, role) {
+		if (!this.#actionable.has(element) || this.#excluded.has(element)) return void 0;
+		if (!ACTIONABLE_ROLES.has(role)) return void 0;
+		const bytes = /* @__PURE__ */ new Uint8Array(8);
+		crypto.getRandomValues(bytes);
+		const ref = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+		this.#table.set(ref, element);
+		return ref;
+	}
+	get table() {
+		return this.#table;
+	}
+};
+/**
 * DOM 遍历实现（设计 09 §2 的「实现层」）。产出只有角色 / 名称 / 值，
 * **不含任何 HTML 标记、class、data 属性或注释**（FR-10.4）。
 *
@@ -1752,17 +1843,43 @@ function describe(element, excluded, doc, view, targets) {
 * @experimental
 */
 function createDomPerceptionReader(options = {}) {
+	let handles;
+	const resolveDocument = () => options.document ?? globalThis.document;
+	/** 按当前 DOM 重算一次可操作集合；发句柄与执行前各算一次 */
+	const actionSets = (doc) => {
+		const actionable = /* @__PURE__ */ new Set();
+		const excluded = /* @__PURE__ */ new Set();
+		const scope = options.actionScope;
+		if (scope === void 0 || scope.include.length === 0) return {
+			actionable,
+			excluded
+		};
+		for (const selector of scope.include) for (const root of doc.querySelectorAll(selector)) {
+			actionable.add(root);
+			for (const descendant of root.querySelectorAll("*")) actionable.add(descendant);
+		}
+		for (const selector of scope.exclude ?? []) for (const root of doc.querySelectorAll(selector)) {
+			excluded.add(root);
+			for (const descendant of root.querySelectorAll("*")) excluded.add(descendant);
+		}
+		return {
+			actionable,
+			excluded
+		};
+	};
 	function collect(scope, targets) {
-		const doc = options.document ?? globalThis.document;
+		const doc = resolveDocument();
 		if (doc === void 0 || scope.include.length === 0) return [];
 		const view = doc.defaultView;
+		const sets = actionSets(doc);
+		handles = new HandleIssuer(sets.actionable, sets.excluded);
 		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, targets);
+			const node = describe(root, excluded, doc, view, targets, handles);
 			if (node !== void 0) nodes.push(node);
 		}
 		return nodes;
@@ -1804,7 +1921,126 @@ function createDomPerceptionReader(options = {}) {
 		if (!capture.images || capture.maxImages <= 0) return Promise.resolve({ nodes: collect(scope, void 0) });
 		return readWithImages(scope, capture);
 	}
-	return { read };
+	return {
+		read,
+		resolve: (ref) => handles?.table.get(ref),
+		inActionScope: (element) => {
+			const doc = resolveDocument();
+			if (doc === void 0) return false;
+			const sets = actionSets(doc);
+			return sets.actionable.has(element) && !sets.excluded.has(element);
+		}
+	};
+}
+const FILLABLE_TAGS = /* @__PURE__ */ new Set(["INPUT", "TEXTAREA"]);
+/** 只看显式声明，不看尺寸：jsdom 有 getComputedStyle 但没有布局 */
+function hidden(element) {
+	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;
+	const view = element.ownerDocument.defaultView;
+	if (view !== null) {
+		const computed = view.getComputedStyle(element);
+		if (computed.display === "none" || computed.visibility === "hidden") return true;
+	}
+	return false;
+}
+const inputType = (element) => (element.getAttribute("type") ?? "text").toLowerCase();
+const isSecret = (element) => element.tagName === "INPUT" && SECRET_INPUT_TYPES.has(inputType(element));
+function accessibleName(element) {
+	const label = element.getAttribute("aria-label");
+	if (label !== null && label.trim() !== "") return label.trim();
+	const text = element.textContent?.replace(/\s+/g, " ").trim() ?? "";
+	if (text !== "") return text;
+	const placeholder = element.getAttribute("placeholder");
+	return placeholder !== null && placeholder.trim() !== "" ? placeholder.trim() : void 0;
+}
+function roleOf(element) {
+	const explicit = element.getAttribute("role");
+	if (explicit !== null && explicit.trim() !== "") return explicit.trim();
+	if (element.tagName === "INPUT") {
+		const type = inputType(element);
+		return type === "checkbox" || type === "radio" ? type : type === "button" || type === "submit" ? "button" : "textbox";
+	}
+	if (element.tagName === "BUTTON") return "button";
+	if (element.tagName === "A") return "link";
+	if (element.tagName === "TEXTAREA") return "textbox";
+	if (element.tagName === "SELECT") return "combobox";
+	if (element.tagName === "FORM") return "form";
+	return "generic";
+}
+const describeElement = (element) => {
+	const name = accessibleName(element);
+	return {
+		role: roleOf(element),
+		...name !== void 0 ? { name } : {},
+		...isSecret(element) ? { secret: true } : {}
+	};
+};
+/**
+* 受控组件必须收到 `input` / `change`：直接写 `.value` 在 React 上会被下一次渲染覆盖，
+* 表现为「填了又没了」。原生 setter 是绕过 React value 劫持的唯一办法。
+*/
+function fillValue(element, value) {
+	const prototype = element.tagName === "INPUT" ? HTMLInputElement.prototype : HTMLTextAreaElement.prototype;
+	const setter = Object.getOwnPropertyDescriptor(prototype, "value")?.set;
+	if (setter) setter.call(element, value);
+	else element.value = value;
+	element.dispatchEvent(new Event("input", { bubbles: true }));
+	element.dispatchEvent(new Event("change", { bubbles: true }));
+}
+/** @experimental */
+function createDomPageActionExecutor(options) {
+	const { reader } = options;
+	const describe = (ref) => {
+		const element = reader.resolve(ref);
+		return element === void 0 ? void 0 : describeElement(element);
+	};
+	const execute = (request) => {
+		const element = reader.resolve(request.ref);
+		if (element === void 0) return {
+			ok: false,
+			target: { role: "generic" },
+			reason: "The element reference is unknown or expired."
+		};
+		const target = describeElement(element);
+		const fail = (reason) => ({
+			ok: false,
+			target,
+			reason
+		});
+		if (!reader.inActionScope(element)) return fail("The element is no longer inside the actionable scope.");
+		if (hidden(element)) return fail("The element is not visible.");
+		if (element.hasAttribute("disabled")) return fail("The element is disabled.");
+		if (request.action === "click") {
+			element.click();
+			return {
+				ok: true,
+				target
+			};
+		}
+		if (request.action === "fill") {
+			if (!FILLABLE_TAGS.has(element.tagName)) return fail("The element is not a text control.");
+			if (element.hasAttribute("readonly")) return fail("The element is read-only.");
+			fillValue(element, request.value ?? "");
+			return {
+				ok: true,
+				target
+			};
+		}
+		const form = element.tagName === "FORM" ? element : element.form;
+		if (!form) return fail("The element does not belong to a form.");
+		form.requestSubmit();
+		return {
+			ok: true,
+			target
+		};
+	};
+	return {
+		execute,
+		describe
+	};
 }
 const isRecord = (v) => typeof v === "object" && v !== null;
 const isNonEmptyString = (v) => typeof v === "string" && v !== "";
@@ -2486,6 +2722,179 @@ async function deleteMemoryEncryptionKey(name = "user-profile") {
 		db.close();
 	}
 }
+/**
+* 端口 × 宿主类型的**唯一定义**（AC-17.4）。
+* About 页与装配工厂都读这一份；护栏 `port-matrix-single-source` 盯着不许再抄。
+*/
+const HOST_PORT_MATRIX = [
+	{
+		id: "install / uninstall",
+		surface: "console-backend",
+		key: "install",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.install to let the console install and remove skills."
+	},
+	{
+		id: "export (zip)",
+		surface: "console-backend",
+		key: "exportSkill",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.exportSkill to enable zip export."
+	},
+	{
+		id: "export (tar)",
+		surface: "console-backend",
+		key: "exportSkillTar",
+		applicability: {
+			browser: "not-applicable",
+			node: "expected"
+		},
+		note: "Browsers have no tar toolchain in the platform; zip export covers the same need."
+	},
+	{
+		id: "integrity",
+		surface: "console-backend",
+		key: "verifyIntegrity",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.verifyIntegrity to enable the integrity report."
+	},
+	{
+		id: "editing",
+		surface: "console-backend",
+		key: "writeSkillFile",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.writeSkillFile to enable in-place skill editing."
+	},
+	{
+		id: "versions",
+		surface: "console-backend",
+		key: "listVersions",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.listVersions to show version history and rollback."
+	},
+	{
+		id: "runs",
+		surface: "console-backend",
+		key: "runs",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.runs to read run history; without it the runs pages have no source."
+	},
+	{
+		id: "sessions",
+		surface: "console-backend",
+		key: "sessions",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.sessions to list chat sessions."
+	},
+	{
+		id: "page perception",
+		surface: "chatbot-adapter",
+		key: "pagePerception",
+		applicability: {
+			browser: "expected",
+			node: "not-applicable"
+		},
+		note: "Page perception reads the live DOM; there is no page outside a browser."
+	},
+	{
+		id: "skill candidates",
+		surface: "chatbot-config",
+		key: "skillCandidates",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire skillCandidates so skill-miss suggestions can be reviewed in the console."
+	},
+	{
+		id: "remote endpoints",
+		surface: "connect-facade",
+		key: "listEndpoints",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConnectFacade.listEndpoints to manage remote MCP endpoints."
+	},
+	{
+		id: "page-declared skills",
+		surface: "connect-facade",
+		key: "temporarySkills",
+		applicability: {
+			browser: "expected",
+			node: "not-applicable"
+		},
+		note: "Page-declared temporary skills come from the document; Node hosts have none."
+	}
+];
+function inspectHostWiring(input) {
+	const kind = input.kind ?? "browser";
+	return HOST_PORT_MATRIX.map((spec) => {
+		if (!(spec.surface in input.surfaces)) return {
+			...spec,
+			status: "unknown"
+		};
+		if (spec.applicability[kind] === "not-applicable") return {
+			...spec,
+			status: "not-applicable"
+		};
+		const surface = input.surfaces[spec.surface];
+		const wired = surface !== void 0 && surface[spec.key] !== void 0;
+		return {
+			...spec,
+			status: wired ? "wired" : "missing"
+		};
+	});
+}
+/** 缺口 = 该接却没接的项；`unknown` 不算缺口，没看到不等于没接 */
+function missingPorts(reports) {
+	return reports.filter((report) => report.status === "missing");
+}
+function createBrowserChatbotHost(options) {
+	const { fs, managedRoot, skillRoots, navigation, overrides } = options;
+	const chatbotAdapter = {
+		storage: fs,
+		skillRoots,
+		navigation,
+		skillManager: new BrowserSkillManager({
+			fs,
+			managedRoot,
+			skillRoots
+		}),
+		...options.pagePerception !== void 0 ? { pagePerception: options.pagePerception } : {}
+	};
+	const consoleBackend = options.consoleBackend ?? { catalog: async () => ({ entries: [] }) };
+	const connectFacade = options.connectFacade ?? {
+		listEndpoints: async () => [],
+		listTools: async () => []
+	};
+	return {
+		chatbotAdapter: overrides?.chatbotAdapter ?? chatbotAdapter,
+		consoleBackend: overrides?.consoleBackend ?? consoleBackend,
+		connectFacade: overrides?.connectFacade ?? connectFacade
+	};
+}
 
 //#endregion
-export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, IframeWorkerLike, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };
+export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, HOST_PORT_MATRIX, IframeWorkerLike, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };