@webskill/sdk 0.0.5 → 0.1.0

package/README.md

@@ -9,22 +9,25 @@ governance.
 ## Features
 
 - **Skill protocol** — Agent Skills compatible discovery, validation, cataloging
-  (JSON / XML), and safe per-skill file access.
+  (JSON / XML), declarative `dependencies` and `allowed-tools`, skill packs
+  (multi-skill zip export/import with integrity digests).
 - **Agent loop** — multi-turn tool calling with structured errors fed back to
-  the LLM, guardrails, lifecycle events, memory, and human interaction
-  (missing-parameter forms, confirmations, ask-user).
-- **Script sandbox** — in-process Node executor plus a `worker_threads` sandbox;
-  Web Worker sandbox for the browser. Timeouts kill runaway scripts.
-- **Streaming** — OpenAI-compatible SSE streaming end to end, with incremental
-  UI updates.
+  the LLM, guardrails, lifecycle events, memory, human interaction
+  (missing-parameter forms, confirmations, authorization prompts), and
+  resumable interrupted runs.
+- **Script sandbox** — `worker_threads` sandbox for Node, Web Worker sandbox for
+  the browser. Deny-by-default network policy, per-capability forced approval,
+  timeouts kill runaway scripts.
+- **`navigator.webskill`** — a browser facade (`discover` / `read` / `validate` /
+  `run` / `install` / `uninstall`) assembled explicitly in one call.
 - **MCP** — call page-provided tools and consume page-declared dynamic skills
   over standard MCP transports (MessageChannel).
 - **Governance** — LLM-generated skill candidates with mandatory review,
   approval workflows, audit log, versioning/rollback, quarantine, evaluation,
   and scoring.
-- **UI** — framework-agnostic web forms, result rendering, generative UI
-  adapters (Vercel AI SDK, OpenUI, A2UI), plus React and Vue component
-  primitives.
+- **UI** — framework-agnostic forms, result rendering (markdown, tables, SVG
+  charts), generative UI adapters (Vercel AI SDK, OpenUI, A2UI), plus React and
+  Vue component primitives.
 
 ## Installation
 
@@ -35,53 +38,184 @@ npm install @webskill/sdk
 React/Vue integrations require their respective peer dependencies
 (`react` + `react-dom`, or `vue`), which are optional.
 
+## Requirements
+
+- Node.js >= 22.18 (native type stripping for `.ts` skill scripts)
+- Modern browsers for the browser host (OPFS, Web Workers, ES modules)
+
 ## Quick start (Node)
 
-```ts
-import { OpenAiCompatibleClient, WebSkillRuntime } from '@webskill/sdk';
-import { NodeFS, NodeScriptExecutor, FileArtifactStore } from '@webskill/sdk/node';
-
-const runtime = new WebSkillRuntime({
-  fs: new NodeFS(),
-  roots: ['./skills'],
-  llm: new OpenAiCompatibleClient({
-    baseUrl: 'https://your-llm-endpoint/v1',
-    apiKey: process.env.LLM_API_KEY!,
-    model: 'your-model'
-  }),
-  executor: new NodeScriptExecutor(new NodeFS()),
-  artifactStore: new FileArtifactStore({ root: './.webskill/artifacts' })
-});
+Runs as-is with the bundled mock LLM — see
+[`examples/quickstart-node`](../examples/quickstart-node) for the full project.
+
+```js
+import { WebSkillRuntime } from '@webskill/sdk';
+import { NodeFS, SandboxedScriptExecutor } from '@webskill/sdk/node';
+import { MockLlmClient } from '@webskill/sdk/testing';
+
+const fs = new NodeFS();
+const llm = new MockLlmClient([
+  { toolCalls: [{ id: 'c1', name: 'read_skill_file', arguments: { skillName: 'greeter' } }] },
+  { toolCalls: [{ id: 'c2', name: 'greeter__greet', arguments: { text: 'world' } }] },
+  { content: 'Greeted the world.' }
+]);
 
-// Discover skills and render the catalog
-const { entries, issues } = await runtime.discover();
-console.log(
-  entries.map((e) => e.name),
-  issues
-);
+const runtime = new WebSkillRuntime({ fs, roots: ['./skills'], llm, executor: new SandboxedScriptExecutor(fs) });
 
-// Run the agent loop
-const { output, run } = await runtime.run('Use the calculator skill to compute 2+3.');
+const catalog = await runtime.discover();
+console.log(catalog.entries.map((e) => e.name));
+
+const { output, run } = await runtime.run('Greet the world.');
 console.log(output, run.status, run.trace.length);
 ```
 
+For a real LLM, replace the mock with `OpenAiCompatibleClient`:
+
+```js
+import { OpenAiCompatibleClient } from '@webskill/sdk';
+
+const llm = new OpenAiCompatibleClient({
+  baseUrl: 'https://your-llm-endpoint/v1',
+  apiKey: process.env.LLM_API_KEY,
+  model: 'your-model'
+});
+```
+
 ## Subpath exports
 
-| Subpath                    | Contents                                                                                                             |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `@webskill/sdk`            | Core protocol + runtime engine (discovery, agent loop, LLM clients, routing, interaction, memory, artifacts, trace)  |
-| `@webskill/sdk/node`       | Node host: NodeFS, script executors (in-process + sandboxed), file stores, skill manager, CLI UI bridge, env helpers |
-| `@webskill/sdk/browser`    | Browser host: OPFS provider, Web Worker script sandbox, worker runtime host/client                                   |
-| `@webskill/sdk/mcp`        | MCP transports, endpoint registry, tool resolver, temporary skills, WebMCP adapter, runtime plugin                   |
-| `@webskill/sdk/ui`         | Framework-agnostic forms, result rendering, mini markdown, Vercel/OpenUI/A2UI adapters, A2UI Lit runtime             |
-| `@webskill/sdk/ui-react`   | React bridge state + InteractionForm/ResultBlocks/StreamingText components                                           |
-| `@webskill/sdk/ui-vue`     | Vue bridge state + equivalent components                                                                             |
-| `@webskill/sdk/governance` | Candidates, approval, audit, versioning, state policy, evaluation, scoring, documents                                |
+### `@webskill/sdk` (main entry)
 
-## Requirements
+Core protocol + runtime engine: discovery, catalog, validation, agent loop, LLM
+clients, routing, interaction types, memory, artifacts, tracing, network policy,
+capability approval, and the environment-agnostic `createWebSkillApi` facade.
 
-- Node.js >= 22.18 (native type stripping for `.ts` skill scripts)
-- Modern browsers for the browser host (OPFS, Web Workers, ES modules)
+```js
+import { SkillDiscovery, validateSkills, createWebSkillApi } from '@webskill/sdk';
+
+const api = createWebSkillApi({ fs, roots: ['./skills'], llm, skillManager });
+const report = await api.validate('./skills');
+const run = await api.run('Summarize the references of skill greeter.');
+```
+
+### `@webskill/sdk/node`
+
+Node host: `NodeFS`, script executors (in-process + `worker_threads` sandbox),
+file-backed stores, `SkillManager` (install/export incl. multi-skill packs),
+CLI UI bridge, schema inference.
+
+```js
+import { NodeFS, SkillManager } from '@webskill/sdk/node';
+
+const manager = new SkillManager({ managedRoot: './.webskill/skills' });
+await manager.install({ type: 'http', url: 'https://example.com/greeter.zip' });
+await manager.exportPack(['greeter', 'calculator'], { outPath: './pack.zip' });
+console.log((await manager.verifyIntegrity('greeter')).ok);
+```
+
+### `@webskill/sdk/browser`
+
+Browser host: OPFS provider, Web Worker script sandbox (deny-by-default network
+policy), worker runtime host/client, `BrowserSkillManager`, and the
+`navigator.webskill` assembler. See
+[`examples/quickstart-browser`](../examples/quickstart-browser).
+
+```js
+import { installWebSkillNavigator } from '@webskill/browser';
+
+const api = installWebSkillNavigator({ roots: ['/skills'], llm });
+const catalog = await navigator.webskill.discover('/skills');
+const run = await navigator.webskill.run('Greet the world.');
+```
+
+### `@webskill/sdk/mcp`
+
+MCP integration: MessageChannel transport, endpoint registry, tool resolver,
+temporary (page-declared) skills, WebMCP adapter, runtime plugin.
+
+```js
+import { MessageChannelTransport, serveSkillAsMcp } from '@webskill/sdk/mcp';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+const server = new McpServer({ name: 'page', version: '0.1.0' });
+serveSkillAsMcp(server, { name: 'greeter', description: 'Greet someone', body: '# Greeter' });
+await server.connect(new MessageChannelTransport(port));
+```
+
+### `@webskill/sdk/ui`
+
+Framework-agnostic UI: form models + `WebFormBridge`, result rendering
+(markdown / table / mini-chart SVG), mini markdown, generative UI adapters
+(Vercel AI SDK, OpenUI, A2UI).
+
+```js
+import { WebFormBridge } from '@webskill/sdk/ui';
+
+const bridge = new WebFormBridge({ mount: document.querySelector('#ui') });
+// pass as uiBridge to the runtime: forms, confirmations, and authorization
+// prompts render as real DOM, results (incl. charts) render on completion.
+```
+
+### `@webskill/sdk/ui-react`
+
+React bridge state + `InteractionForm` / `ResultBlocks` / `StreamingText`
+components (requires `react` + `react-dom`).
+
+```jsx
+import { ReactBridgeState, InteractionForm, ResultBlocks } from '@webskill/sdk/ui-react';
+
+const bridge = new ReactBridgeState();
+// <InteractionForm bridge={bridge} /> <ResultBlocks bridge={bridge} />
+```
+
+### `@webskill/sdk/ui-vue`
+
+Vue bridge state + equivalent components (requires `vue`).
+
+```js
+import { VueBridgeState, InteractionForm, ResultBlocks } from '@webskill/sdk/ui-vue';
+
+const bridge = new VueBridgeState();
+// <InteractionForm :bridge="bridge" /> <ResultBlocks :bridge="bridge" />
+```
+
+### `@webskill/sdk/governance`
+
+Governance: skill candidates with mandatory review, approval workflows, audit
+log, versioning/rollback, quarantine, evaluation, scoring, dependency graph.
+
+```js
+import { DependencyGraph } from '@webskill/sdk/governance';
+
+const graph = DependencyGraph.buildFromCatalog(catalog.entries, documents);
+console.log(graph.dependenciesOf('greeter'));
+```
+
+### `@webskill/sdk/testing`
+
+Test facilities (moved out of the main entry in 0.1.0): `MockLlmClient`,
+`MockUiBridge`, `InMemoryStore`, `MemoryArtifactStore`.
+
+```js
+import { MockLlmClient, MockUiBridge, InMemoryStore, MemoryArtifactStore } from '@webskill/sdk/testing';
+
+const llm = new MockLlmClient([{ content: 'deterministic answer' }]);
+```
+
+## Stability
+
+This package follows semver starting at 0.1.0. Public symbols carry JSDoc
+stability tags:
+
+- **`@stable`** — covered by the semver contract: bug fixes ship in patch,
+  backwards-compatible capabilities in minor, breaking changes only in major
+  (with release notes).
+- **`@experimental`** — may change in minor/patch releases. Currently:
+  `ExperimentalWebMcpAdapter`, `resumeRun` and the `RunSnapshot` format,
+  the A2UI/OpenUI adapters, and the `authorize` interaction type.
+
+The public API surface of every subpath is pinned by checked-in `.d.ts`
+snapshots (`api-snapshots/`); any intentional change requires
+`pnpm api:update` and is reviewable in the diff.
 
 ## License
 

package/dist/browser.d.ts

@@ -1,4 +1,5 @@
-import { A as InteractionResponse, F as LlmClient, Gt as FileSystemProvider, Lt as parseBridgeRequest, O as InteractionPolicy, Ot as bridgeError, R as LlmResponse, Wt as FileStat, Y as NetworkPolicy, _t as ToolDefinition, an as SkillManifest, c as ApprovalScope, d as BridgeCapabilities, dn as VerifyResult, ht as ScriptExecutor, it as RenderResultRequest, k as InteractionRequest, ln as SkillsLockfile, m as BridgeResponse, mt as ScriptExecutionContext, nn as SkillInstallSource, p as BridgeRequest, v as ExternalSkillProvider, wt as UiBridge, y as ExternalToolSource, yt as ToolResult, z as LlmStreamEvent } from "./index-BQDc-U1x.js";
+import { H as SkillsLockfile, L as SkillManifest, P as SkillInstallSource, S as FileSystemProvider, W as VerifyResult, _ as RenderResultRequest, a as InteractionPolicy, c as LlmClient, d as LlmResponse, f as LlmStreamEvent, o as InteractionRequest, s as InteractionResponse, v as UiBridge, x as FileStat } from "./types-CgNC-oQu-DCklnS0h.js";
+import { K as ScriptExecutionContext, Y as ToolDefinition, Z as ToolResult, _ as ExternalToolSource, _t as parseBridgeRequest, c as ApprovalScope, d as BridgeRequest, f as BridgeResponse, g as ExternalSkillProvider, k as NetworkPolicy, l as BridgeCapabilities, ot as bridgeError, q as ScriptExecutor, rt as WebSkillApi } from "./index-S8uza3ld.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -74,6 +75,7 @@ declare class TsTranspiler {
  * D5：浏览器技能安装（http(s) zip / ArrayBuffer；tar/git/npm → TOOL_UNSUPPORTED）。
  * 流程与 Node 对齐：staging → 解析 name → validateSkills（失败零残留）→ managed root →
  * manifest（WebCrypto sha256）→ skills.lock.json；zip-slip 防护；manifest/lockfile 与 Node 同格式。
+ * @stable
  */
 declare class BrowserSkillManager {
   #private;
@@ -85,6 +87,11 @@ declare class BrowserSkillManager {
   install(source: SkillInstallSource, options?: {
     expectedSha256?: string;
   }): Promise<SkillManifest>;
+  /**
+   * 浏览器导出（单技能与包集同构：始终产出含 webskill.skill-pack.json 的 zip 字节，
+   * 统一安装路径；保存/下载由应用层处理）。
+   */
+  exportArchive(names: string | string[]): Promise<Uint8Array>;
   uninstall(name: string): Promise<void>;
   verifyIntegrity(name: string): Promise<VerifyResult>;
   listInstalled(): Promise<SkillsLockfile>;
@@ -114,6 +121,7 @@ type WorkerFactory = () => WorkerLike;
 /**
  * Web Worker 脚本沙箱执行器：loadDefinition 与 execute 都在 Worker 内完成，
  * 主线程从不 import 技能脚本；每次执行独立 Worker；超时 terminate 强杀。
+ * @stable
  */
 declare class BrowserWorkerScriptExecutor implements ScriptExecutor {
   #private;
@@ -140,6 +148,33 @@ declare class BrowserWorkerScriptExecutor implements ScriptExecutor {
   }): Promise<ToolResult>;
 }
 //#endregion
+//#region src/navigator.d.ts
+declare global {
+  /** 0.0.6：installWebSkillNavigator 显式装配后可用（不自动挂全局） */
+  interface Navigator {
+    webskill?: WebSkillApi;
+  }
+}
+/**
+ * navigator.webskill 显式装配：OPFS 默认存储 + BrowserWorkerScriptExecutor +
+ * BrowserSkillManager → createWebSkillApi；target 提供时挂 target.navigator
+ * （缺失则补空对象），否则挂真实 navigator.webskill。
+ * target 可注入（测试）；返回值即门面本体（挂载只是副作用）。
+ * @stable
+ */
+declare function installWebSkillNavigator(config: {
+  roots?: string[];
+  llm: LlmClient;
+  typescript?: TypeScriptSupportOptions;
+  /** 测试注入：替换 OPFS 默认 fs（jsdom 无 OPFS） */
+  fs?: FileSystemProvider;
+  /** 安装目标根（默认与 roots[0] 一致） */
+  managedRoot?: string;
+  target?: {
+    navigator?: Record<string, unknown>;
+  };
+}): WebSkillApi;
+//#endregion
 //#region src/host/protocol.d.ts
 /** 主线程 → Worker 的 LLM 配置；mockResponses 供 E2E/测试注入确定性 Mock */
 interface LlmClientConfig {
@@ -303,4 +338,4 @@ declare class WorkerUiBridge implements UiBridge {
   onTextDelta(runId: string, delta: string): Promise<void>;
 }
 //#endregion
-export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, BrowserSkillManager, BrowserWorkerScriptExecutor, type LlmClientConfig, type MainToWorkerMessage, OpfsProvider, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, WORKER_BOOTSTRAP_SOURCE, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, bridgeError, extractZipWeb, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, startWorkerRuntimeHost };
+export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, BrowserSkillManager, BrowserWorkerScriptExecutor, type LlmClientConfig, type MainToWorkerMessage, OpfsProvider, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, WORKER_BOOTSTRAP_SOURCE, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, bridgeError, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, startWorkerRuntimeHost };

package/dist/browser.js

@@ -1,4 +1,6 @@
-import { A as mergeCatalogEntries, B as SKILL_MANIFEST_FILE, G as WebSkillError, K as buildCatalog, M as normalizeToolContent, N as parseBridgeRequest, U as SkillDiscovery, Z as isValidSkillName, _ as ProgressiveRouter, a as CapabilityApproval, at as verifyManifest, c as FsMemoryStore, et as parseSkillMarkdown, g as OpenAiCompatibleClient, i as AgentLoop, it as validateSkills, j as networkUrlHost, k as isNetworkAllowed, l as FsRunSnapshotStore, m as MockLlmClient, q as buildManifest, rt as resolveInsideRoot, s as FsArtifactStore, w as bridgeError, x as RUN_SNAPSHOT_SCHEMA_VERSION, z as SKILLS_LOCKFILE } from "./dist-D405AlPD.js";
+import { D as verifyManifest, E as validateSkills, S as parseSkillPackManifest, T as resolveInsideRoot, _ as exportSkills, c as SkillDiscovery, d as buildCatalog, f as buildManifest, i as SKILL_MANIFEST_FILE, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, v as isValidSkillName, x as parseSkillMarkdown } from "./memoryArtifactStore-C9lFVqPF-U8nXvqL9.js";
+import { A as normalizeToolContent, C as createWebSkillApi, D as isNetworkAllowed, O as mergeCatalogEntries, _ as RUN_SNAPSHOT_SCHEMA_VERSION, a as CapabilityApproval, b as bridgeError, c as FsMemoryStore, f as OpenAiCompatibleClient, i as AgentLoop, j as parseBridgeRequest, k as networkUrlHost, l as FsRunSnapshotStore, p as ProgressiveRouter, s as FsArtifactStore } from "./dist-CiYRkm71.js";
+import { n as MockLlmClient } from "./testing-pn3NhXSV.js";
 import { unzipSync } from "fflate";
 
 //#region ../browser/dist/index.js
@@ -442,6 +444,7 @@ const lockfilePath = (root) => `${root}/${SKILLS_LOCKFILE}`;
 * D5：浏览器技能安装（http(s) zip / ArrayBuffer；tar/git/npm → TOOL_UNSUPPORTED）。
 * 流程与 Node 对齐：staging → 解析 name → validateSkills（失败零残留）→ managed root →
 * manifest（WebCrypto sha256）→ skills.lock.json；zip-slip 防护；manifest/lockfile 与 Node 同格式。
+* @stable
 */
 var BrowserSkillManager = class {
 	#fs;
@@ -476,6 +479,11 @@ var BrowserSkillManager = class {
 			const contentDir = `${stagingRoot}/content`;
 			await fs.mkdir(contentDir);
 			await extractZipWeb(fs, data, contentDir);
+			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");
@@ -521,6 +529,77 @@ var BrowserSkillManager = class {
 			await removeDirQuiet(fs, stagingRoot);
 		}
 	}
+	/**
+	* 包集安装：逐技能走单技能管线（归一 → 汇总校验 → 落 managed root → manifest → digest 比对）。
+	* 任一失败整体回滚（删除本次已落目录；lockfile 在全部成功后才写入，天然零残留）。
+	*/
+	async #installPack(pack, source, stagingRoot) {
+		const fs = this.#fs;
+		const finalRoot = `${stagingRoot}/final`;
+		const installed = [];
+		try {
+			const versions = /* @__PURE__ */ new Map();
+			for (const entry of pack.manifest.skills) {
+				const skillDir = `${pack.contentDir}/${entry.name}`;
+				if (!await fs.exists(`${skillDir}/SKILL.md`)) throw new WebSkillError("INSTALL_FAILED", `Skill pack is missing a directory for skill "${entry.name}"`);
+				let name;
+				try {
+					const { metadata } = parseSkillMarkdown(await fs.readText(`${skillDir}/SKILL.md`));
+					name = metadata.name;
+					versions.set(name, typeof metadata["version"] === "string" ? metadata["version"] : void 0);
+				} catch (e) {
+					throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md of pack entry "${entry.name}": ${messageOf$1(e)}`, e);
+				}
+				if (name !== entry.name) throw new WebSkillError("INSTALL_FAILED", `Skill pack entry "${entry.name}" does not match the SKILL.md name "${name}"`);
+				await copyDir(fs, skillDir, `${finalRoot}/${name}`);
+			}
+			const report = await validateSkills(fs, [finalRoot]);
+			if (!report.ok) {
+				const errors = report.issues.filter((i) => i.severity === "error");
+				throw new WebSkillError("INSTALL_FAILED", `Skill pack failed validation: ${errors.map((i) => i.message).join("; ")}`, errors);
+			}
+			const manifests = [];
+			for (const entry of pack.manifest.skills) {
+				const targetDir = `${this.#managedRoot}/${entry.name}`;
+				if (await fs.exists(targetDir)) await fs.remove(targetDir, { recursive: true });
+				await copyDir(fs, `${finalRoot}/${entry.name}`, targetDir);
+				installed.push(targetDir);
+				const manifest = await this.#createManifest(targetDir, {
+					name: entry.name,
+					...versions.get(entry.name) ? { version: versions.get(entry.name) } : {},
+					source
+				});
+				if (manifest.integrity.digest !== entry.digest) throw new WebSkillError("INSTALL_FAILED", `Skill "${entry.name}" digest mismatch: expected ${entry.digest}, got ${manifest.integrity.digest}`);
+				manifests.push(manifest);
+			}
+			for (const manifest of manifests) await this.#upsertLockEntry(manifest.name, {
+				digest: manifest.integrity.digest,
+				installedAt: manifest.installedAt,
+				source
+			});
+			return manifests;
+		} catch (e) {
+			for (const targetDir of installed) await removeDirQuiet(fs, targetDir);
+			throw asInstallFailed(e);
+		}
+	}
+	/**
+	* 浏览器导出（单技能与包集同构：始终产出含 webskill.skill-pack.json 的 zip 字节，
+	* 统一安装路径；保存/下载由应用层处理）。
+	*/
+	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) => {
+			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`);
+		return exportSkills(this.#fs, {
+			roots,
+			manifestBuilder: (root) => this.#readManifest(root)
+		});
+	}
 	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}`;
@@ -609,6 +688,7 @@ const messageOf = (e) => e instanceof Error ? e.message : String(e);
 /**
 * Web Worker 脚本沙箱执行器：loadDefinition 与 execute 都在 Worker 内完成，
 * 主线程从不 import 技能脚本；每次执行独立 Worker；超时 terminate 强杀。
+* @stable
 */
 var BrowserWorkerScriptExecutor = class {
 	#fs;
@@ -829,6 +909,35 @@ var BrowserWorkerScriptExecutor = class {
 		}
 	}
 };
+/**
+* navigator.webskill 显式装配：OPFS 默认存储 + BrowserWorkerScriptExecutor +
+* BrowserSkillManager → createWebSkillApi；target 提供时挂 target.navigator
+* （缺失则补空对象），否则挂真实 navigator.webskill。
+* target 可注入（测试）；返回值即门面本体（挂载只是副作用）。
+* @stable
+*/
+function installWebSkillNavigator(config) {
+	const roots = config.roots ?? ["/skills"];
+	const fs = config.fs ?? new OpfsProvider();
+	const executor = new BrowserWorkerScriptExecutor({
+		fs,
+		...config.typescript ? { typescript: config.typescript } : {}
+	});
+	const skillManager = new BrowserSkillManager({
+		fs,
+		managedRoot: config.managedRoot ?? roots[0] ?? "/skills"
+	});
+	const api = createWebSkillApi({
+		fs,
+		roots,
+		llm: config.llm,
+		executor,
+		skillManager
+	});
+	const nav = config.target ? config.target.navigator ??= {} : navigator;
+	nav["webskill"] = api;
+	return api;
+}
 const isRecord = (v) => typeof v === "object" && v !== null;
 const isNonEmptyString = (v) => typeof v === "string" && v !== "";
 /** Worker 侧入站校验：非法消息返回 undefined（忽略） */
@@ -1028,7 +1137,7 @@ function startWorkerRuntimeHost(scope, overrides = {}) {
 					return [];
 				}
 			}))).flat();
-			const catalog = providerEntries.length > 0 ? { skills: mergeCatalogEntries(buildCatalog(entries).skills, providerEntries) } : buildCatalog(entries);
+			const catalog = providerEntries.length > 0 ? { entries: mergeCatalogEntries(buildCatalog(entries).entries, providerEntries) } : buildCatalog(entries);
 			const route = await new ProgressiveRouter().route(catalog);
 			const uiBridge = new WorkerUiBridge(scope);
 			activeUiBridge = uiBridge;
@@ -1337,4 +1446,4 @@ var WorkerRuntimeClient = class {
 };
 
 //#endregion
-export { BrowserSkillManager, BrowserWorkerScriptExecutor, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, extractZipWeb, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, startWorkerRuntimeHost };
+export { BrowserSkillManager, BrowserWorkerScriptExecutor, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, extractZipWeb, installWebSkillNavigator, isOpfsAvailable, parseBridgeRequest, parseMainMessage, parseWorkerEvent, sha256HexWeb, startWorkerRuntimeHost };