@webskill/sdk 0.2.6 → 0.2.8

package/dist/node.js

@@ -1,6 +1,2066 @@
-import { i as SKILL_MANIFEST_FILE, r as SKILLS_LOCKFILE } from "./dist-BQzncxXg.js";
-import { T as createScriptContext } from "./dist-BXpDDZpR.js";
+import { A as resolveArchiveLimits, C as messageOf, D as readResponseWithLimit, E as parseSkillPackManifest, M as unzipWithLimits, N as validateSkills, P as verifyManifest, T as parseSkillMarkdown, b as exportSkills, d as assertRemoteUrlAllowed, f as assertSafePathSegment, h as buildManifest, i as SKILL_MANIFEST_FILE, j as resolveInsideRoot, p as atomicWriteText, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, x as isValidSkillName } from "./dist-BQzncxXg.js";
+import { C as bridgeError, I as normalizeToolContent, L as normalizeToolError, N as networkPolicyLibSource, R as parseBridgeRequest, S as WebSkillRuntime, T as createScriptContext, c as FsArtifactStore, l as FsMemoryStore, o as CapabilityApproval } from "./dist-B9VLwOME.js";
 import { i as probeLlmCapabilities } from "./env--jJB-TSX-04klhTYi.js";
-import { a as NodeScriptExecutor, c as SandboxedScriptExecutor, d as readArchiveManifest, i as NodeFS, l as SkillManager, n as FileArtifactStore, o as OxcSchemaInferer, r as FileMemoryStore, s as ProcessSandboxExecutor, t as CliUiBridge, u as exportArchive } from "./dist-DWFDb1Ww.js";
+import { createRequire } from "node:module";
+import { unzipSync, zipSync } from "fflate";
+import { existsSync, promises, realpathSync } from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { format, promisify } from "node:util";
+import { Worker } from "node:worker_threads";
+import { mkdtemp, rm } from "node:fs/promises";
+import { execFile, fork } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { createHash } from "node:crypto";
 
-export { CliUiBridge, FileArtifactStore, FileMemoryStore, NodeFS, NodeScriptExecutor, OxcSchemaInferer, ProcessSandboxExecutor, SKILLS_LOCKFILE, SKILL_MANIFEST_FILE, SandboxedScriptExecutor, SkillManager, createScriptContext, exportArchive, probeLlmCapabilities, readArchiveManifest };
+//#region ../node/dist/index.js
+const toPlatform$4 = (p) => p.split("/").join(path.sep);
+const toPosix = (p) => p.split(path.sep).join("/");
+const isEnoent = (e) => typeof e === "object" && e !== null && e.code === "ENOENT";
+/** realpath 最近现存祖先并拼回剩余段（写入目标尚不存在时的等价判定） */
+async function realpathNearest(platformPath) {
+	let current = platformPath;
+	const rest = [];
+	for (;;) try {
+		const real = await promises.realpath(current);
+		return rest.length === 0 ? real : [real, ...rest].join(path.sep);
+	} catch (e) {
+		if (!isEnoent(e)) throw e;
+		rest.unshift(path.basename(current));
+		const parent = path.dirname(current);
+		if (parent === current) return platformPath;
+		current = parent;
+	}
+}
+/**
+* 基于 node:fs/promises 的 FileSystemProvider；接受 `/` 风格路径，写入自动创建父目录。
+* 可选 root 模式：构造传入 root 后，read/write 操作先做 realpath 包含校验
+* （root 与目标都 realpath 后前缀比对），经符号链接逃逸 root → FS_PATH_OUTSIDE_ROOT。
+*/
+var NodeFS = class NodeFS {
+	kind = "node";
+	#root;
+	constructor(deps = {}) {
+		this.#root = deps.root;
+	}
+	/** root 模式：全部方法（read/write/exists/stat/list/mkdir/remove/rename）目标 realpath 必须落在 root realpath 前缀内 */
+	withRoot(root) {
+		return new NodeFS({ root });
+	}
+	async #assertContained(p) {
+		if (!this.#root) return;
+		const rootReal = await promises.realpath(toPlatform$4(this.#root));
+		const targetReal = await realpathNearest(toPlatform$4(p));
+		if (targetReal !== rootReal && !targetReal.startsWith(rootReal + path.sep)) throw new WebSkillError("FS_PATH_OUTSIDE_ROOT", `Path escapes root via symbolic link: ${p} (resolves outside ${this.#root})`);
+	}
+	async readText(p) {
+		await this.#assertContained(p);
+		try {
+			return await promises.readFile(toPlatform$4(p), "utf8");
+		} catch (e) {
+			throw this.#mapError(e, p);
+		}
+	}
+	async writeText(p, content) {
+		await this.#assertContained(p);
+		const target = toPlatform$4(p);
+		await promises.mkdir(path.dirname(target), { recursive: true });
+		await promises.writeFile(target, content, "utf8");
+	}
+	async appendText(p, content) {
+		await this.#assertContained(p);
+		const target = toPlatform$4(p);
+		await promises.mkdir(path.dirname(target), { recursive: true });
+		await promises.appendFile(target, content, "utf8");
+	}
+	async readBinary(p) {
+		await this.#assertContained(p);
+		try {
+			return await promises.readFile(toPlatform$4(p));
+		} catch (e) {
+			throw this.#mapError(e, p);
+		}
+	}
+	async writeBinary(p, content) {
+		await this.#assertContained(p);
+		const target = toPlatform$4(p);
+		await promises.mkdir(path.dirname(target), { recursive: true });
+		await promises.writeFile(target, content);
+	}
+	async exists(p) {
+		await this.#assertContained(p);
+		try {
+			await promises.access(toPlatform$4(p));
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async stat(p) {
+		await this.#assertContained(p);
+		try {
+			const s = await promises.stat(toPlatform$4(p));
+			return {
+				path: toPosix(p),
+				type: s.isDirectory() ? "directory" : "file",
+				size: s.isFile() ? s.size : void 0,
+				mtimeMs: s.mtimeMs
+			};
+		} catch (e) {
+			throw this.#mapError(e, p);
+		}
+	}
+	async list(p) {
+		await this.#assertContained(p);
+		let dirents;
+		try {
+			dirents = await promises.readdir(toPlatform$4(p), { withFileTypes: true });
+		} catch (e) {
+			throw this.#mapError(e, p);
+		}
+		return dirents.map((d) => ({
+			path: toPosix(path.join(toPlatform$4(p), d.name)),
+			type: d.isDirectory() ? "directory" : "file"
+		}));
+	}
+	async mkdir(p) {
+		await this.#assertContained(p);
+		await promises.mkdir(toPlatform$4(p), { recursive: true });
+	}
+	async remove(p, options) {
+		await this.#assertContained(p);
+		try {
+			await promises.rm(toPlatform$4(p), { recursive: options?.recursive ?? false });
+		} catch (e) {
+			throw this.#mapError(e, p);
+		}
+	}
+	async rename(from, to) {
+		await this.#assertContained(from);
+		await this.#assertContained(to);
+		await promises.mkdir(path.dirname(toPlatform$4(to)), { recursive: true });
+		try {
+			await promises.rename(toPlatform$4(from), toPlatform$4(to));
+		} catch (e) {
+			throw this.#mapError(e, from);
+		}
+	}
+	#mapError(e, p) {
+		if (isEnoent(e)) return new WebSkillError("FS_NOT_FOUND", `Path not found: ${p}`);
+		return e;
+	}
+};
+const baseName$2 = (p) => p.split("/").pop() ?? p;
+/**
+* 进程内脚本执行器。接口按沙箱语义设计（context 无隐式宿主访问），
+* worker_threads 沙箱见 deferred-items D1。
+*/
+var NodeScriptExecutor = class {
+	#fs;
+	constructor(fs) {
+		this.#fs = fs;
+	}
+	/** 定位 scripts/<name>.ts|js；冲突/缺失抛结构化错误 */
+	async #locateScript(skillRoot, scriptName) {
+		const tsPath = `${skillRoot}/scripts/${scriptName}.ts`;
+		const jsPath = `${skillRoot}/scripts/${scriptName}.js`;
+		const [hasTs, hasJs] = await Promise.all([this.#fs.exists(tsPath), this.#fs.exists(jsPath)]);
+		if (hasTs && hasJs) throw new WebSkillError("TOOL_EXECUTION_FAILED", `Script "${scriptName}" is ambiguous: both .ts and .js exist under ${skillRoot}/scripts`);
+		if (!hasTs && !hasJs) throw new WebSkillError("TOOL_NOT_FOUND", `Script "${scriptName}" not found under ${skillRoot}/scripts`);
+		return hasTs ? tsPath : jsPath;
+	}
+	async #loadModule(scriptPath) {
+		if (scriptPath.endsWith(".ts")) {
+			const source = await this.#fs.readText(scriptPath);
+			const dir = await promises.mkdtemp(path.join(tmpdir(), "webskill-ts-"));
+			try {
+				const file = path.join(dir, "script.ts");
+				await promises.writeFile(file, source);
+				return await import(`${pathToFileURL(file).href}?t=${Date.now()}`);
+			} finally {
+				await promises.rm(dir, {
+					recursive: true,
+					force: true
+				});
+			}
+		}
+		const source = await this.#fs.readText(scriptPath);
+		return await import(`data:text/javascript;charset=utf-8,${encodeURIComponent(`${source}\n//# ${Date.now()}`)}`);
+	}
+	async loadDefinition(skillRoot, scriptName) {
+		const scriptPath = await this.#locateScript(skillRoot, scriptName);
+		const skillName = baseName$2(skillRoot);
+		let module;
+		try {
+			module = await this.#loadModule(scriptPath);
+		} catch (e) {
+			throw new WebSkillError("TOOL_EXECUTION_FAILED", `Failed to load script "${scriptName}": ${e instanceof Error ? e.message : String(e)}`, e);
+		}
+		return {
+			name: `${skillName}__${scriptName}`,
+			description: typeof module.description === "string" ? module.description : void 0,
+			inputSchema: typeof module.inputSchema === "object" && module.inputSchema !== null ? module.inputSchema : void 0,
+			source: "script",
+			skillName
+		};
+	}
+	async execute(input) {
+		const { skillRoot, scriptName, args, context, timeoutMs } = input;
+		let scriptPath;
+		try {
+			scriptPath = await this.#locateScript(skillRoot, scriptName);
+		} catch (e) {
+			return this.#failure(e);
+		}
+		let module;
+		try {
+			module = await this.#loadModule(scriptPath);
+		} catch (e) {
+			return this.#failure(e);
+		}
+		if (typeof module.run !== "function") return {
+			ok: false,
+			content: [],
+			error: {
+				code: "TOOL_EXECUTION_FAILED",
+				message: `Script "${scriptName}" does not export a run function`
+			}
+		};
+		const missing = this.#missingRequiredArgs(module.inputSchema, args);
+		if (missing.length > 0) return {
+			ok: false,
+			content: [],
+			error: {
+				code: "TOOL_EXECUTION_FAILED",
+				message: `Missing required argument(s): ${missing.join(", ")}`
+			}
+		};
+		const stdout = [];
+		const stderr = [];
+		const originals = {
+			log: console.log,
+			info: console.info,
+			debug: console.debug,
+			warn: console.warn,
+			error: console.error
+		};
+		console.log = console.info = console.debug = (...a) => stdout.push(format(...a));
+		console.warn = console.error = (...a) => stderr.push(format(...a));
+		let timer;
+		try {
+			const runFn = module.run;
+			const timeout = new Promise((_, reject) => {
+				timer = setTimeout(() => reject(new WebSkillError("RUN_TIMEOUT", `Script "${scriptName}" timed out after ${timeoutMs}ms`)), timeoutMs);
+			});
+			const content = normalizeToolContent(await Promise.race([Promise.resolve().then(() => runFn(args, context)), timeout]));
+			if (stdout.length > 0) content.push({
+				type: "text",
+				text: stdout.join("\n")
+			});
+			return {
+				ok: true,
+				content
+			};
+		} catch (e) {
+			return this.#failure(e, stderr);
+		} finally {
+			if (timer) clearTimeout(timer);
+			console.log = originals.log;
+			console.info = originals.info;
+			console.debug = originals.debug;
+			console.warn = originals.warn;
+			console.error = originals.error;
+		}
+	}
+	#missingRequiredArgs(schema, args) {
+		if (typeof schema !== "object" || schema === null) return [];
+		const required = schema.required;
+		if (!Array.isArray(required)) return [];
+		return required.filter((key) => typeof key === "string" && args[key] === void 0);
+	}
+	#failure(e, stderr = []) {
+		const isTimeout = e instanceof WebSkillError && e.code === "RUN_TIMEOUT";
+		const code = e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED";
+		const base = e instanceof Error ? e.message : String(e);
+		const stderrSummary = stderr.length > 0 ? ` | stderr: ${stderr.join(" | ").slice(0, 500)}` : "";
+		return {
+			ok: false,
+			content: [],
+			error: {
+				code: isTimeout ? "RUN_TIMEOUT" : code,
+				message: `${base}${stderrSummary}`
+			}
+		};
+	}
+};
+const baseName$1 = (p) => p.split("/").pop() ?? p;
+const toPlatform$3 = (p) => p.split("/").join(path.sep);
+/**
+* 网络策略判定函数源码（注入 Worker；匹配逻辑单一来源在
+* runtime/sandbox/networkPolicy.ts，Worker 线程不走 vitest 别名故注入而非 import）
+*/
+const NETWORK_POLICY_LIB$1 = networkPolicyLibSource();
+/** Worker 入口文件：src 为同目录 .ts；node dist 为 dist/executor/；sdk dist 为平铺 dist/ */
+function workerEntryPath() {
+	const dir = path.dirname(fileURLToPath(import.meta.url));
+	const candidates = [
+		path.join(dir, "sandboxWorkerEntry.js"),
+		path.join(dir, "sandboxWorkerEntry.ts"),
+		path.join(dir, "executor", "sandboxWorkerEntry.js")
+	];
+	for (const candidate of candidates) if (existsSync(candidate)) return candidate;
+	throw new WebSkillError("TOOL_EXECUTION_FAILED", `Sandbox worker entry not found (tried: ${candidates.join(", ")})`);
+}
+/**
+* D1：worker_threads 沙箱脚本执行器。
+* 每次执行独立 Worker（resourceLimits + env 白名单），loadDefinition 同样在
+* Worker 内完成（禁止主进程 import 不可信脚本）；超时 terminate（可杀同步死循环）。
+* 能力桥协议与浏览器同一来源（runtime/sandbox/bridgeProtocol）。
+*
+* 诚实标注：本执行器做的是**能力面收敛**（网络策略、模块 allowlist、资源限额、
+* 超时强杀），**不是安全边界**——Worker 内脚本与宿主共享进程；
+* 已知主动逃逸面（process.binding/_linkedBinding/dlopen/openStdin/reallyExit/abort）
+* 已在入口删除（0.2.3），常规 import 拦截之外不承诺防御其它宿主共享面；
+* 禁止假定其可隔离不可信脚本（隔离级需求用 ProcessSandboxExecutor）。
+*/
+var SandboxedScriptExecutor = class {
+	#fs;
+	#options;
+	#capabilities;
+	#networkPolicy;
+	#approval;
+	constructor(fs, options = {}) {
+		this.#fs = fs;
+		this.#options = options;
+		this.#capabilities = {
+			readReference: options.capabilities?.readReference ?? true,
+			writeArtifact: options.capabilities?.writeArtifact ?? true,
+			confirm: options.capabilities?.confirm ?? true
+		};
+		this.#networkPolicy = options.networkPolicy ?? "deny-all";
+		this.#approval = new CapabilityApproval({
+			...options.uiBridge ? { uiBridge: options.uiBridge } : {},
+			...options.approvalScope ? { scope: options.approvalScope } : {}
+		});
+	}
+	async #locateScript(skillRoot, scriptName) {
+		const tsPath = `${skillRoot}/scripts/${scriptName}.ts`;
+		const jsPath = `${skillRoot}/scripts/${scriptName}.js`;
+		const [hasTs, hasJs] = await Promise.all([this.#fs.exists(tsPath), this.#fs.exists(jsPath)]);
+		if (hasTs && hasJs) throw new WebSkillError("TOOL_EXECUTION_FAILED", `Script "${scriptName}" is ambiguous: both .ts and .js exist under ${skillRoot}/scripts`);
+		if (!hasTs && !hasJs) throw new WebSkillError("TOOL_NOT_FOUND", `Script "${scriptName}" not found under ${skillRoot}/scripts`);
+		return hasTs ? tsPath : jsPath;
+	}
+	async loadDefinition(skillRoot, scriptName) {
+		const scriptPath = await this.#locateScript(skillRoot, scriptName);
+		const skillName = baseName$1(skillRoot);
+		const result = await this.#runWorker({
+			mode: "load",
+			scriptPath: toPlatform$3(scriptPath),
+			scriptName,
+			scriptSource: await this.#fs.readText(scriptPath)
+		});
+		if (!result.ok) throw new WebSkillError("TOOL_EXECUTION_FAILED", `Failed to load script "${scriptName}": ${result.error?.message ?? "unknown error"}`);
+		return {
+			name: `${skillName}__${scriptName}`,
+			description: result.definition?.description,
+			inputSchema: result.definition?.inputSchema,
+			source: "script",
+			skillName
+		};
+	}
+	async execute(input) {
+		const { skillRoot, scriptName, args, context, timeoutMs } = input;
+		let scriptPath;
+		try {
+			scriptPath = await this.#locateScript(skillRoot, scriptName);
+		} catch (e) {
+			return {
+				ok: false,
+				content: [],
+				error: {
+					code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
+					message: messageOf(e)
+				}
+			};
+		}
+		try {
+			const result = await this.#runWorker({
+				mode: "execute",
+				scriptPath: toPlatform$3(scriptPath),
+				scriptName,
+				skillName: context.skillName,
+				runId: context.runId,
+				args,
+				scriptSource: await this.#fs.readText(scriptPath)
+			}, timeoutMs, (request) => this.#handleBridge(request, context), (host) => context.onWarning?.(`Network request blocked by sandbox network policy: ${host}`));
+			if (!result.ok) {
+				const stderrSummary = result.stderr?.length ? ` | stderr: ${result.stderr.join(" | ").slice(0, 500)}` : "";
+				const normalized = normalizeToolError(result.error?.code, result.error?.message ?? "script execution failed");
+				return {
+					ok: false,
+					content: [],
+					error: {
+						code: normalized.code,
+						message: `${normalized.message}${stderrSummary}`
+					}
+				};
+			}
+			const content = normalizeToolContent(result.value);
+			if (result.stdout?.length) content.push({
+				type: "text",
+				text: result.stdout.join("\n")
+			});
+			return {
+				ok: true,
+				content
+			};
+		} catch (e) {
+			return {
+				ok: false,
+				content: [],
+				error: {
+					code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
+					message: messageOf(e)
+				}
+			};
+		}
+	}
+	/** 起独立 Worker 执行任务；超时 terminate（同步死循环可杀）；非零退出码 → TOOL_EXECUTION_FAILED */
+	#runWorker(workerData, timeoutMs = 3e4, onBridge, onNetworkBlocked) {
+		const envWhitelist = this.#options.envWhitelist ?? [];
+		const env = Object.fromEntries(envWhitelist.filter((key) => process.env[key] !== void 0).map((key) => [key, process.env[key]]));
+		return new Promise((resolve, reject) => {
+			const worker = new Worker(workerEntryPath(), {
+				workerData: {
+					...workerData,
+					networkPolicy: this.#networkPolicy,
+					networkPolicyLib: NETWORK_POLICY_LIB$1,
+					allowedModules: this.#options.allowedModules ?? []
+				},
+				env,
+				resourceLimits: this.#options.resourceLimits ?? {
+					maxOldGenerationSizeMb: 64,
+					maxYoungGenerationSizeMb: 16
+				}
+			});
+			let settled = false;
+			const timer = setTimeout(() => {
+				if (settled) return;
+				settled = true;
+				worker.terminate();
+				reject(new WebSkillError("RUN_TIMEOUT", `Sandboxed script timed out after ${timeoutMs}ms (worker terminated)`));
+			}, timeoutMs);
+			const done = (fn) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				fn();
+			};
+			worker.on("message", (msg) => {
+				if (msg?.type === "network-blocked") {
+					if (typeof msg.host === "string") onNetworkBlocked?.(msg.host);
+					return;
+				}
+				if (msg?.type === "bridge" && onBridge) {
+					const request = parseBridgeRequest(msg.request);
+					const respond = (response) => worker.postMessage({
+						type: "bridge-response",
+						response
+					});
+					if (!request) {
+						respond(bridgeError("unknown", "TOOL_EXECUTION_FAILED", "invalid bridge request"));
+						return;
+					}
+					onBridge(request).then(respond, (e) => respond(bridgeError(request.id, "TOOL_EXECUTION_FAILED", messageOf(e))));
+					return;
+				}
+				if (msg?.type === "load-result" || msg?.type === "execute-result") done(() => resolve(msg));
+			});
+			worker.on("error", (e) => done(() => reject(e)));
+			worker.on("exit", (code) => {
+				if (!settled) done(() => reject(new WebSkillError("TOOL_EXECUTION_FAILED", `Sandbox worker exited ${code === null ? "by signal" : `with code ${code}`} without producing a result`)));
+			});
+		});
+	}
+	/** 能力桥宿主侧处理：能力关闭/授权拒绝即 TOOL_UNSUPPORTED；判定逻辑共用 runtime/sandbox/approval */
+	async #handleBridge(request, context) {
+		const gate = async (capability, message, details) => {
+			const decision = await this.#approval.authorize({
+				runId: context.runId,
+				capability,
+				mode: this.#capabilities[capability],
+				message,
+				...details !== void 0 ? { details } : {}
+			});
+			if (decision === "allowed") return void 0;
+			return bridgeError(request.id, "TOOL_UNSUPPORTED", decision === "disabled" ? `Capability "${capability}" is disabled` : `Capability "${capability}" was denied by the user`);
+		};
+		try {
+			switch (request.kind) {
+				case "readReference": {
+					const denied = await gate("readReference", `Script "${context.skillName}" wants to read reference "${request.path}"`, { path: request.path });
+					if (denied) return denied;
+					return {
+						id: request.id,
+						ok: true,
+						value: await context.readReference(request.path)
+					};
+				}
+				case "writeArtifact": {
+					const denied = await gate("writeArtifact", `Script "${context.skillName}" wants to write artifact "${request.path}"`, {
+						path: request.path,
+						mimeType: request.mimeType
+					});
+					if (denied) return denied;
+					const content = typeof request.content === "string" ? request.content : new Uint8Array(request.content);
+					const artifact = await context.writeArtifact(request.path, content, { ...request.mimeType ? { mimeType: request.mimeType } : {} });
+					return {
+						id: request.id,
+						ok: true,
+						value: artifact
+					};
+				}
+				case "confirm": {
+					if (!context.confirm) return bridgeError(request.id, "TOOL_UNSUPPORTED", "Capability \"confirm\" is disabled");
+					const denied = await gate("confirm", `Script "${context.skillName}" asks for confirmation: ${request.message}`);
+					if (denied) return denied;
+					return {
+						id: request.id,
+						ok: true,
+						value: await context.confirm(request.message)
+					};
+				}
+			}
+		} catch (e) {
+			return bridgeError(request.id, e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", messageOf(e));
+		}
+	}
+};
+const baseName = (p) => p.split("/").pop() ?? p;
+const toPlatform$2 = (p) => p.split("/").join(path.sep);
+const NETWORK_POLICY_LIB = networkPolicyLibSource();
+const readAllow = (p) => [`--allow-fs-read=${p}`, `--allow-fs-read=${realpathSync(p)}`];
+const writeAllow = (p) => [`--allow-fs-write=${p}`, `--allow-fs-write=${realpathSync(p)}`];
+/** 子进程入口文件：src 为同目录 .ts；node dist 为 dist/executor/；sdk dist 为平铺 dist/ */
+function processEntryPath() {
+	const dir = path.dirname(fileURLToPath(import.meta.url));
+	const candidates = [
+		path.join(dir, "processSandboxEntry.js"),
+		path.join(dir, "processSandboxEntry.ts"),
+		path.join(dir, "executor", "processSandboxEntry.js")
+	];
+	for (const candidate of candidates) if (existsSync(candidate)) return candidate;
+	throw new WebSkillError("TOOL_EXECUTION_FAILED", `Process sandbox entry not found (tried: ${candidates.join(", ")})`);
+}
+/**
+* child_process.fork + --permission 进程沙箱（真实进程隔离）。
+* 每个子进程以 `--permission --allow-fs-read=<入口目录> --allow-fs-read=<skillRoot>
+* --allow-fs-write=<artifactDir>` 启动：fs 维度由权限模型管控（experimental），
+* 子进程/Worker/addons 默认禁；网络无权限维度仍靠 fetch/WebSocket patch。
+* 能力桥协议与 worker_threads 沙箱同一形态（readReference/writeArtifact/confirm + 授权）。
+* 温池（默认 2）：同 skillRoot 复用子进程；执行后 kill 并补位重生；并发上限即池大小。
+* 超时 kill（同步死循环可杀）；非零退出码 → TOOL_EXECUTION_FAILED。
+*/
+var ProcessSandboxExecutor = class {
+	#fs;
+	#options;
+	#capabilities;
+	#networkPolicy;
+	#approval;
+	#slots = [];
+	#waiters = [];
+	#disposed = false;
+	constructor(fs, options = {}) {
+		this.#fs = fs;
+		this.#options = options;
+		this.#capabilities = {
+			readReference: options.capabilities?.readReference ?? true,
+			writeArtifact: options.capabilities?.writeArtifact ?? true,
+			confirm: options.capabilities?.confirm ?? true
+		};
+		this.#networkPolicy = options.networkPolicy ?? "deny-all";
+		this.#approval = new CapabilityApproval({
+			...options.uiBridge ? { uiBridge: options.uiBridge } : {},
+			...options.approvalScope ? { scope: options.approvalScope } : {}
+		});
+	}
+	get poolSize() {
+		return this.#options.poolSize ?? 2;
+	}
+	/** 池全部子进程销毁（测试收尾/进程退出前调用）；排队中的 acquire 一律 reject（不悬挂） */
+	async dispose() {
+		this.#disposed = true;
+		for (const slot of this.#slots) {
+			slot.child.kill();
+			await rm(slot.artifactDir, {
+				recursive: true,
+				force: true
+			}).catch(() => void 0);
+		}
+		this.#slots = [];
+		const waiters = this.#waiters.splice(0);
+		for (const waiter of waiters) waiter.reject(new WebSkillError("TOOL_EXECUTION_FAILED", "Process sandbox executor disposed while a caller was waiting for a pool slot"));
+	}
+	async #locateScript(skillRoot, scriptName) {
+		const tsPath = `${skillRoot}/scripts/${scriptName}.ts`;
+		const jsPath = `${skillRoot}/scripts/${scriptName}.js`;
+		const [hasTs, hasJs] = await Promise.all([this.#fs.exists(tsPath), this.#fs.exists(jsPath)]);
+		if (hasTs && hasJs) throw new WebSkillError("TOOL_EXECUTION_FAILED", `Script "${scriptName}" is ambiguous: both .ts and .js exist under ${skillRoot}/scripts`);
+		if (!hasTs && !hasJs) throw new WebSkillError("TOOL_NOT_FOUND", `Script "${scriptName}" not found under ${skillRoot}/scripts`);
+		return hasTs ? tsPath : jsPath;
+	}
+	/** 取一个可用子进程（同 key 复用 / 淘汰 idle 重生 / 扩容 / 排队） */
+	async #acquire(key) {
+		for (;;) {
+			if (this.#disposed) throw new WebSkillError("TOOL_EXECUTION_FAILED", "Process sandbox executor is disposed");
+			const idle = this.#slots.filter((s) => !s.busy);
+			const match = idle.find((s) => s.key === key);
+			if (match) {
+				match.busy = true;
+				return match;
+			}
+			if (idle.length > 0) {
+				const victim = idle[0];
+				victim.child.kill();
+				await rm(victim.artifactDir, {
+					recursive: true,
+					force: true
+				}).catch(() => void 0);
+				this.#slots.splice(this.#slots.indexOf(victim), 1);
+			}
+			if (this.#slots.length < this.poolSize) {
+				const slot = await this.#spawnSlot(key);
+				slot.busy = true;
+				this.#slots.push(slot);
+				return slot;
+			}
+			await new Promise((resolve, reject) => this.#waiters.push({
+				resolve,
+				reject
+			}));
+		}
+	}
+	/** 执行后回收：kill 旧子进程，补位重生同 key 新子进程（温池保持），唤醒排队 */
+	#recycle(slot) {
+		slot.child.kill();
+		const index = this.#slots.indexOf(slot);
+		if (index >= 0) this.#slots.splice(index, 1);
+		rm(slot.artifactDir, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+		this.#spawnSlot(slot.key).then(async (fresh) => {
+			if (this.#disposed) {
+				fresh.child.kill();
+				await rm(fresh.artifactDir, {
+					recursive: true,
+					force: true
+				}).catch(() => void 0);
+				return;
+			}
+			this.#slots.push(fresh);
+		}).catch((e) => {
+			this.#warn(`Failed to respawn sandbox child for pool maintenance: ${messageOf(e)}`);
+		}).finally(() => {
+			const waiter = this.#waiters.shift();
+			if (waiter) waiter.resolve();
+		});
+	}
+	#warn(message) {
+		if (this.#options.onWarning) this.#options.onWarning(message);
+		else console.warn(message);
+	}
+	async #spawnSlot(key) {
+		const artifactDir = await mkdtemp(path.join(tmpdir(), "webskill-psbx-out-")).then((d) => d.split(path.sep).join("/"));
+		const entry = processEntryPath();
+		const child = fork(entry, [], {
+			execArgv: [
+				"--permission",
+				...readAllow(path.dirname(entry)),
+				...readAllow(toPlatform$2(key)),
+				...readAllow(artifactDir),
+				...writeAllow(artifactDir)
+			],
+			env: Object.fromEntries((this.#options.envWhitelist ?? []).filter((key) => process.env[key] !== void 0).map((key) => [key, process.env[key]])),
+			silent: true
+		});
+		child.stdout?.resume();
+		child.stderr?.resume();
+		child.unref();
+		child.channel?.unref();
+		return {
+			key,
+			child,
+			busy: false,
+			artifactDir
+		};
+	}
+	async loadDefinition(skillRoot, scriptName) {
+		const scriptPath = await this.#locateScript(skillRoot, scriptName);
+		const skillName = baseName(skillRoot);
+		const slot = await this.#acquire(toPlatform$2(skillRoot));
+		try {
+			const response = await this.#runTask(slot, {
+				mode: "load",
+				scriptPath: toPlatform$2(scriptPath),
+				scriptName,
+				scriptSource: await this.#fs.readText(scriptPath),
+				scratchDir: slot.artifactDir
+			}, 3e4);
+			if (!response.ok) throw new WebSkillError("TOOL_EXECUTION_FAILED", `Failed to load script "${scriptName}": ${response.error?.message ?? "unknown error"}`);
+			return {
+				name: `${skillName}__${scriptName}`,
+				description: response.definition?.description,
+				inputSchema: response.definition?.inputSchema,
+				source: "script",
+				skillName
+			};
+		} finally {
+			this.#recycle(slot);
+		}
+	}
+	async execute(input) {
+		const { skillRoot, scriptName, args, context, timeoutMs } = input;
+		let scriptPath;
+		try {
+			scriptPath = await this.#locateScript(skillRoot, scriptName);
+		} catch (e) {
+			return {
+				ok: false,
+				content: [],
+				error: {
+					code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
+					message: messageOf(e)
+				}
+			};
+		}
+		const slot = await this.#acquire(toPlatform$2(skillRoot));
+		try {
+			const result = await this.#runTask(slot, {
+				mode: "execute",
+				scriptPath: toPlatform$2(scriptPath),
+				scriptName,
+				skillName: context.skillName,
+				runId: context.runId,
+				args,
+				scriptSource: await this.#fs.readText(scriptPath),
+				scratchDir: slot.artifactDir
+			}, timeoutMs, (request) => this.#handleBridge(request, context), (host) => context.onWarning?.(`Network request blocked by sandbox network policy: ${host}`));
+			if (!result.ok) {
+				const stderrSummary = result.stderr?.length ? ` | stderr: ${result.stderr.join(" | ").slice(0, 500)}` : "";
+				const normalized = normalizeToolError(result.error?.code, result.error?.message ?? "script execution failed");
+				return {
+					ok: false,
+					content: [],
+					error: {
+						code: normalized.code,
+						message: `${normalized.message}${stderrSummary}`
+					}
+				};
+			}
+			const content = normalizeToolContent(result.value);
+			if (result.stdout?.length) content.push({
+				type: "text",
+				text: result.stdout.join("\n")
+			});
+			return {
+				ok: true,
+				content
+			};
+		} catch (e) {
+			return {
+				ok: false,
+				content: [],
+				error: {
+					code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
+					message: messageOf(e)
+				}
+			};
+		} finally {
+			this.#recycle(slot);
+		}
+	}
+	/** 在子进程上跑一个任务；超时 kill；非零退出码 → TOOL_EXECUTION_FAILED */
+	#runTask(slot, task, timeoutMs, onBridge, onNetworkBlocked) {
+		const { child } = slot;
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			const timer = setTimeout(() => {
+				if (settled) return;
+				settled = true;
+				child.kill();
+				reject(new WebSkillError("RUN_TIMEOUT", `Process sandbox task timed out after ${timeoutMs}ms (child killed)`));
+			}, timeoutMs);
+			const done = (fn) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				fn();
+			};
+			child.on("message", (msg) => {
+				if (msg?.type === "network-blocked") {
+					if (typeof msg.host === "string") onNetworkBlocked?.(msg.host);
+					return;
+				}
+				if (msg?.type === "bridge" && onBridge) {
+					const request = parseBridgeRequest(msg.request);
+					const respond = (response) => child.send({
+						type: "bridge-response",
+						response
+					});
+					if (!request) {
+						respond(bridgeError("unknown", "TOOL_EXECUTION_FAILED", "invalid bridge request"));
+						return;
+					}
+					onBridge(request).then(respond, (e) => respond(bridgeError(request.id, "TOOL_EXECUTION_FAILED", messageOf(e))));
+					return;
+				}
+				if (msg?.type === "load-result" || msg?.type === "execute-result") done(() => resolve(msg));
+			});
+			child.on("error", (e) => done(() => reject(e)));
+			child.on("exit", (code) => {
+				if (!settled) done(() => reject(new WebSkillError("TOOL_EXECUTION_FAILED", `Sandbox child exited ${code === null ? "by signal" : `with code ${code}`} without producing a result`)));
+			});
+			child.send({
+				type: "task",
+				task: {
+					...task,
+					networkPolicy: this.#networkPolicy,
+					networkPolicyLib: NETWORK_POLICY_LIB
+				}
+			});
+		});
+	}
+	/** 能力桥宿主侧处理：与 worker_threads 沙箱同一判定（runtime/sandbox/approval 单一来源） */
+	async #handleBridge(request, context) {
+		const gate = async (capability, message, details) => {
+			const decision = await this.#approval.authorize({
+				runId: context.runId,
+				capability,
+				mode: this.#capabilities[capability],
+				message,
+				...details !== void 0 ? { details } : {}
+			});
+			if (decision === "allowed") return void 0;
+			return bridgeError(request.id, "TOOL_UNSUPPORTED", decision === "disabled" ? `Capability "${capability}" is disabled` : `Capability "${capability}" was denied by the user`);
+		};
+		try {
+			switch (request.kind) {
+				case "readReference": {
+					const denied = await gate("readReference", `Script "${context.skillName}" wants to read reference "${request.path}"`, { path: request.path });
+					if (denied) return denied;
+					return {
+						id: request.id,
+						ok: true,
+						value: await context.readReference(request.path)
+					};
+				}
+				case "writeArtifact": {
+					const denied = await gate("writeArtifact", `Script "${context.skillName}" wants to write artifact "${request.path}"`, {
+						path: request.path,
+						mimeType: request.mimeType
+					});
+					if (denied) return denied;
+					const content = typeof request.content === "string" ? request.content : new Uint8Array(request.content);
+					const artifact = await context.writeArtifact(request.path, content, { ...request.mimeType ? { mimeType: request.mimeType } : {} });
+					return {
+						id: request.id,
+						ok: true,
+						value: artifact
+					};
+				}
+				case "confirm": {
+					if (!context.confirm) return bridgeError(request.id, "TOOL_UNSUPPORTED", "Capability \"confirm\" is disabled");
+					const denied = await gate("confirm", `Script "${context.skillName}" asks for confirmation: ${request.message}`);
+					if (denied) return denied;
+					return {
+						id: request.id,
+						ok: true,
+						value: await context.confirm(request.message)
+					};
+				}
+			}
+		} catch (e) {
+			return bridgeError(request.id, e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", messageOf(e));
+		}
+	}
+};
+const require_ = createRequire(import.meta.url);
+let parseSyncCache;
+function loadParseSync() {
+	if (!parseSyncCache) try {
+		parseSyncCache = require_("oxc-parser").parseSync;
+	} catch (e) {
+		throw new WebSkillError("TOOL_UNSUPPORTED", "The \"oxc-parser\" package is required for schema inference; install it first (npm i oxc-parser)", e);
+	}
+	return parseSyncCache;
+}
+const PLACEHOLDER_PREFIX = "Inferred placeholder (unsupported type: ";
+const placeholder = (text) => ({
+	type: "string",
+	description: `${PLACEHOLDER_PREFIX}${text})`,
+	"x-inferred": true
+});
+/** 主路径映射：基础类型/数组/嵌套对象/可选/字面量 union；其余降级 placeholder */
+var TypeMapper = class {
+	#decls = /* @__PURE__ */ new Map();
+	#source;
+	constructor(body, source) {
+		this.#source = source;
+		for (const node of body) {
+			if (node.type === "TSInterfaceDeclaration" || node.type === "TSTypeAliasDeclaration") this.#decls.set(node.id?.name, node);
+			if (node.type === "ExportNamedDeclaration" && (node.declaration?.type === "TSInterfaceDeclaration" || node.declaration?.type === "TSTypeAliasDeclaration")) this.#decls.set(node.declaration.id?.name, node.declaration);
+		}
+	}
+	objectSchema(t, seen) {
+		const mapped = this.map(t, seen);
+		return mapped?.type === "object" ? mapped : void 0;
+	}
+	map(t, seen) {
+		if (!t) return void 0;
+		switch (t.type) {
+			case "TSStringKeyword": return { type: "string" };
+			case "TSNumberKeyword": return { type: "number" };
+			case "TSBooleanKeyword": return { type: "boolean" };
+			case "TSAnyKeyword":
+			case "TSUnknownKeyword": return {};
+			case "TSArrayType": return {
+				type: "array",
+				items: this.map(t.elementType, seen) ?? {}
+			};
+			case "TSTypeLiteral": return this.#literalObject(t, seen);
+			case "TSLiteralType": return this.#literal(t);
+			case "TSUnionType": return this.#union(t, seen);
+			case "TSTypeReference": return this.#reference(t, seen);
+			case "TSParenthesizedType": return this.map(t.typeAnnotation, seen);
+			default: return placeholder(this.#text(t));
+		}
+	}
+	#literal(t) {
+		const value = t.literal?.value ?? t.value;
+		if (typeof value === "string") return {
+			type: "string",
+			enum: [value]
+		};
+		return placeholder(this.#text(t));
+	}
+	#union(t, _seen) {
+		const values = [];
+		for (const member of t.types ?? []) {
+			const value = member.literal?.value ?? member.value;
+			if (member.type === "TSLiteralType" && typeof value === "string") values.push(value);
+			else return placeholder(this.#text(t));
+		}
+		return {
+			type: "string",
+			enum: values
+		};
+	}
+	#literalObject(t, seen) {
+		const properties = {};
+		const required = [];
+		for (const member of t.members ?? []) {
+			if (member.type !== "TSPropertySignature") continue;
+			const name = member.key?.name ?? member.key?.value;
+			if (typeof name !== "string") continue;
+			const annotation = member.typeAnnotation?.typeAnnotation;
+			properties[name] = annotation ? this.map(annotation, seen) ?? {} : { type: "string" };
+			if (!member.optional) required.push(name);
+		}
+		return {
+			type: "object",
+			properties,
+			...required.length ? { required } : {}
+		};
+	}
+	#reference(t, seen) {
+		const name = t.typeName?.name ?? t.typeName?.left?.name;
+		const params = t.typeArguments?.params ?? t.typeParameters?.params ?? [];
+		if (name === "Array" && params.length === 1) return {
+			type: "array",
+			items: this.map(params[0], seen) ?? {}
+		};
+		if (name === "string" || name === "number" || name === "boolean") return { type: name };
+		if (!name || params.length > 0) return placeholder(this.#text(t));
+		if (seen.has(name)) return placeholder(`recursive reference ${name}`);
+		const decl = this.#decls.get(name);
+		if (!decl) return placeholder(this.#text(t));
+		const nextSeen = new Set(seen).add(name);
+		if (decl.type === "TSInterfaceDeclaration") return this.#literalObject({ members: decl.body?.body ?? [] }, nextSeen);
+		return this.map(decl.typeAnnotation, nextSeen) ?? placeholder(this.#text(t));
+	}
+	#text(t) {
+		if (typeof t.start === "number" && typeof t.end === "number") return this.#source.slice(t.start, t.end);
+		return String(t.type);
+	}
+};
+const findRunFunction = (body) => {
+	for (const node of body) {
+		if (node.type !== "ExportNamedDeclaration") continue;
+		const decl = node.declaration;
+		if (!decl) continue;
+		if (decl.type === "FunctionDeclaration" && decl.id?.name === "run") return decl;
+		if (decl.type === "VariableDeclaration") {
+			for (const d of decl.declarations ?? []) if (d.id?.name === "run" && (d.init?.type === "ArrowFunctionExpression" || d.init?.type === "FunctionExpression")) return d.init;
+		}
+	}
+};
+/** JSDoc 辅路径：@param {type} input.name - desc（点形式）与 @param {{...}} input（对象形式） */
+function inferFromJsDoc(jsdoc, mapper, reparse) {
+	const properties = {};
+	const required = [];
+	const objectForm = /@param\s+\{\{([\s\S]+?)\}\}\s+input(?:\s+-\s+(.*))?/.exec(jsdoc);
+	if (objectForm) {
+		const alias = reparse(`{${objectForm[1]}}`);
+		if (!alias) return void 0;
+		const schema = mapper.map(alias, /* @__PURE__ */ new Set());
+		return schema?.type === "object" ? schema : void 0;
+	}
+	const dotForm = /@param\s+\{([^}]+)\}\s+input\.(\w+)(?:\s+-\s+([^\n*]+))?/g;
+	let matched = false;
+	for (const m of jsdoc.matchAll(dotForm)) {
+		const [, typeText, name, desc] = m;
+		if (!typeText || !name) continue;
+		matched = true;
+		const alias = reparse(typeText.trim());
+		const schema = alias ? mapper.map(alias, /* @__PURE__ */ new Set()) ?? {} : { type: "string" };
+		if (desc?.trim()) schema.description = desc.trim();
+		properties[name] = schema;
+		required.push(name);
+	}
+	if (!matched) return void 0;
+	return {
+		type: "object",
+		properties,
+		required
+	};
+}
+/**
+* D2 Schema 推导（OXC 静态文本分析，宿主侧执行，不进沙箱）。
+* TS 类型标注为主路径，JSDoc @param 为辅路径；不支持类型降级 string 并标 'x-inferred'。
+*/
+var OxcSchemaInferer = class {
+	inferSchemaFromSource(source, options) {
+		let program;
+		let comments;
+		try {
+			const result = loadParseSync()(options?.fileName ?? "script.ts", source);
+			if (result.errors?.length > 0) return void 0;
+			program = result.program;
+			comments = result.comments ?? [];
+		} catch {
+			return;
+		}
+		const runFn = findRunFunction(program.body ?? []);
+		if (!runFn) return void 0;
+		const annotation = (runFn.params?.[0] ?? runFn.params?.items?.[0])?.typeAnnotation?.typeAnnotation;
+		const mapper = new TypeMapper(program.body ?? [], source);
+		if (annotation) return mapper.objectSchema(annotation, /* @__PURE__ */ new Set());
+		const runStart = runFn.start ?? Number.MAX_SAFE_INTEGER;
+		const jsdoc = comments.filter((c) => c.type === "Block" && typeof c.value === "string" && c.value.includes("@param") && typeof c.end === "number" && c.end <= runStart).sort((a, b) => b.end - a.end)[0];
+		if (!jsdoc) return void 0;
+		const reparse = (typeText) => {
+			const r = loadParseSync()("__t.ts", `type __T = ${typeText};`);
+			if (r.errors?.length > 0) return void 0;
+			return r.program.body.find((n) => n.type === "TSTypeAliasDeclaration")?.typeAnnotation;
+		};
+		return inferFromJsDoc(jsdoc.value, mapper, reparse);
+	}
+};
+/**
+* FileArtifactStore：兼容别名，语义同阶段 2-4。
+* 实现已上移到 runtime 的 FsArtifactStore；node 侧保留 NodeFS 默认值。
+*/
+var FileArtifactStore = class extends FsArtifactStore {
+	constructor(deps) {
+		super({
+			root: deps.root,
+			fs: deps.fs ?? new NodeFS()
+		});
+	}
+};
+/**
+* FileMemoryStore：兼容别名，语义同阶段 3。
+* 实现已上移到 runtime 的 FsMemoryStore；node 侧保留 NodeFS 默认值。
+*/
+var FileMemoryStore = class extends FsMemoryStore {
+	constructor(deps) {
+		super({
+			root: deps.root,
+			fs: deps.fs ?? new NodeFS()
+		});
+	}
+};
+/**
+* 命令行 UiBridge：ask→问答，confirm→y/n（带默认值），
+* form→逐字段提示（显示默认值与必填标记），select→编号列表，
+* authorize→授权询问（默认拒绝，仅显式 y/yes 批准）。
+* 输入/输出流可注入（测试用 PassThrough）。
+*/
+var CliUiBridge = class {
+	#input;
+	#output;
+	constructor(deps = {}) {
+		this.#input = deps.input ?? process.stdin;
+		this.#output = deps.output ?? process.stdout;
+	}
+	async request(input) {
+		switch (input.type) {
+			case "ask": return {
+				id: input.id,
+				value: await this.#question(`${input.message}\n> `)
+			};
+			case "confirm": {
+				const hint = input.defaultValue === false ? "y/N" : "Y/n";
+				const answer = (await this.#question(`${input.message} [${hint}] `)).trim().toLowerCase();
+				const value = answer === "" ? input.defaultValue ?? true : answer === "y" || answer === "yes";
+				return {
+					id: input.id,
+					value
+				};
+			}
+			case "form": {
+				const value = {};
+				if (input.title) this.#write(`${input.title}\n`);
+				for (const field of input.fields) value[field.name] = await this.#askField(field);
+				return {
+					id: input.id,
+					value
+				};
+			}
+			case "select": {
+				const lines = input.options.map((o, i) => `  ${i + 1}) ${o.label}`).join("\n");
+				const answer = (await this.#question(`${input.message}\n${lines}\n> `)).trim();
+				const index = Number.parseInt(answer, 10) - 1;
+				const option = input.options[index];
+				return {
+					id: input.id,
+					value: option ? option.value : void 0
+				};
+			}
+			case "authorize": {
+				this.#write(`[authorization required: ${input.capability}]\n`);
+				const answer = (await this.#question(`${input.message} [y/N] `)).trim().toLowerCase();
+				return {
+					id: input.id,
+					value: answer === "y" || answer === "yes"
+				};
+			}
+		}
+	}
+	async progress(input) {
+		const pct = input.value !== void 0 ? ` (${Math.round(input.value * 100)}%)` : "";
+		this.#write(`[progress] ${input.message}${pct}\n`);
+	}
+	async renderResult(input) {
+		const lines = [`\n[result] ${input.summary ?? ""}`];
+		for (const block of input.blocks) if (block.type === "markdown") lines.push(block.text);
+		else if (block.type === "json") lines.push(JSON.stringify(block.data, null, 2));
+		else if (block.type === "file") lines.push(`[file] ${block.path}`);
+		this.#write(`${lines.join("\n")}\n`);
+	}
+	#write(text) {
+		this.#output.write(text);
+	}
+	async #askField(field) {
+		const requiredMark = field.required ? " (required)" : "";
+		const defaultMark = field.defaultValue !== void 0 ? ` [${JSON.stringify(field.defaultValue)}]` : "";
+		if (field.type === "select" && field.options) {
+			const lines = field.options.map((o, i) => `  ${i + 1}) ${o.label}`).join("\n");
+			const answer = (await this.#question(`${field.label}${requiredMark}${defaultMark}:\n${lines}\n> `)).trim();
+			if (answer === "") return field.defaultValue;
+			const option = field.options[Number.parseInt(answer, 10) - 1];
+			return option ? option.value : field.defaultValue;
+		}
+		const answer = (await this.#question(`${field.label}${requiredMark}${defaultMark}: `)).trim();
+		if (answer === "") return field.defaultValue;
+		switch (field.type) {
+			case "number": {
+				const n = Number(answer);
+				return Number.isNaN(n) ? field.defaultValue : n;
+			}
+			case "boolean": return answer === "y" || answer === "yes" || answer === "true";
+			case "textarea": try {
+				return JSON.parse(answer);
+			} catch {
+				return answer;
+			}
+			default: return answer;
+		}
+	}
+	#rl;
+	#lines = [];
+	#waiters = [];
+	/** 常驻 line 监听进入内部队列：预写入的多行输入不会在两次提问之间丢失 */
+	#ensureInterface() {
+		if (this.#rl) return;
+		this.#rl = createInterface({
+			input: this.#input,
+			output: this.#output,
+			terminal: false
+		});
+		this.#rl.on("line", (line) => {
+			const waiter = this.#waiters.shift();
+			if (waiter) waiter(line);
+			else this.#lines.push(line);
+		});
+	}
+	async #question(prompt) {
+		this.#ensureInterface();
+		this.#output.write(prompt);
+		const queued = this.#lines.shift();
+		if (queued !== void 0) return queued;
+		return new Promise((resolve) => this.#waiters.push(resolve));
+	}
+};
+const toPlatform$1 = (p) => p.split("/").join(path.sep);
+const isZipArchive = (data) => data.length > 1 && data[0] === 80 && data[1] === 75;
+let tarModule$1;
+async function loadTar$1() {
+	tarModule$1 ??= await import("tar").catch((e) => {
+		throw new WebSkillError("TOOL_UNSUPPORTED", "The \"tar\" package is required for tar/tar.gz archives; install it first (npm i tar)", e);
+	});
+	return tarModule$1;
+}
+/**
+* zip 解包（fflate 流式，单条目/总解压体积上限）。每个条目路径过 resolveInsideRoot：
+* 拒绝 `..` 段、绝对路径、反斜杠穿越（zip-slip 防护）。
+*/
+async function extractZipData(fs, data, destRoot, limits) {
+	for (const [entryPath, content] of await unzipWithLimits(data, limits)) {
+		const target = resolveInsideRoot(destRoot, entryPath);
+		if (entryPath.endsWith("/")) await fs.mkdir(target);
+		else await fs.writeBinary(target, content);
+	}
+}
+/**
+* tar/tar.gz 解包（tar 包）。先列条目逐一过 resolveInsideRoot 校验并累计
+* 单条目/总体积上限（声明 size 预检），再解包；符号链接/硬链接条目不跟随（跳过）。
+*/
+async function extractTarFile(archivePath, destRoot, limits) {
+	const { maxEntryBytes, maxTotalBytes } = resolveArchiveLimits(limits);
+	try {
+		const entryPaths = [];
+		let total = 0;
+		const tarMod = await loadTar$1();
+		await tarMod.t({
+			file: toPlatform$1(archivePath),
+			onentry: (entry) => {
+				entryPaths.push(entry.path);
+				const size = typeof entry.size === "number" ? entry.size : 0;
+				if (size > maxEntryBytes) throw new WebSkillError("INSTALL_FAILED", `Archive entry exceeds the ${maxEntryBytes}-byte limit: ${entry.path}`);
+				total += size;
+				if (total > maxTotalBytes) throw new WebSkillError("INSTALL_FAILED", `Archive contents exceed the ${maxTotalBytes}-byte total limit`);
+			}
+		});
+		for (const p of entryPaths) if (!p.replace(/\\/g, "/").split("/").every((s) => s === "" || s === ".")) resolveInsideRoot(destRoot, p);
+		await tarMod.x({
+			file: toPlatform$1(archivePath),
+			cwd: toPlatform$1(destRoot),
+			filter: (_p, entry) => !("type" in entry) || entry.type !== "SymbolicLink" && entry.type !== "Link"
+		});
+	} catch (e) {
+		if (e instanceof WebSkillError) throw e;
+		throw new WebSkillError("INSTALL_FAILED", `Failed to extract tar archive: ${messageOf(e)}`, e);
+	}
+}
+/** 递归列出目录内全部文件（相对路径，posix 分隔，不含目录条目） */
+async function listFiles(fs, root, prefix = "") {
+	const out = [];
+	for (const entry of await fs.list(root)) {
+		const name = entry.path.split("/").pop() ?? "";
+		const rel = prefix === "" ? name : `${prefix}/${name}`;
+		if (entry.type === "directory") out.push(...await listFiles(fs, entry.path, rel));
+		else out.push(rel);
+	}
+	return out;
+}
+const toPlatform = (p) => p.split("/").join(path.sep);
+/** lstat 扫描拒绝符号链接条目（与 tar 解包 filter 策略一致；虚拟 fs 路径不存在于真实 fs 时跳过） */
+async function assertNoSymlinks(platformRoot) {
+	let entries;
+	try {
+		entries = await promises.readdir(platformRoot, { withFileTypes: true });
+	} catch (error) {
+		const code = error.code;
+		if (code === "ENOENT") return;
+		throw new WebSkillError("INSTALL_FAILED", `Cannot verify symbolic links under ${platformRoot} (${code ?? "unknown error"}); refusing to copy`, { cause: error });
+	}
+	for (const entry of entries) {
+		if (entry.isSymbolicLink()) throw new WebSkillError("INSTALL_FAILED", `Refusing to copy symbolic link entry: ${platformRoot}${path.sep}${entry.name}`);
+		if (entry.isDirectory()) await assertNoSymlinks(`${platformRoot}${path.sep}${entry.name}`);
+	}
+}
+/** 递归拷贝目录（含子目录与二进制文件）；真实 fs 上先做符号链接扫描 */
+async function copyDir(fs, from, to) {
+	await assertNoSymlinks(toPlatform(from));
+	await fs.mkdir(to);
+	for (const entry of await fs.list(from)) {
+		const name = entry.path.split("/").pop() ?? "";
+		if (entry.type === "directory") await copyDir(fs, entry.path, `${to}/${name}`);
+		else await fs.writeBinary(`${to}/${name}`, await fs.readBinary(entry.path));
+	}
+}
+/** 删除目录（不存在时静默） */
+async function removeDirQuiet(fs, dir) {
+	try {
+		if (await fs.exists(dir)) await fs.remove(dir, { recursive: true });
+	} catch {}
+}
+let tarModule;
+async function loadTar() {
+	tarModule ??= await import("tar").catch((e) => {
+		throw new WebSkillError("TOOL_UNSUPPORTED", "The \"tar\" package is required for tar/tar.gz archives; install it first (npm i tar)", e);
+	});
+	return tarModule;
+}
+/** 导出技能目录全部文件（含 manifest）为 zip/tar 归档，返回 outPath */
+async function exportArchive(fs, skillRoot, options) {
+	try {
+		if (options.format === "zip") {
+			const files = {};
+			for (const rel of await listFiles(fs, skillRoot)) files[rel] = await fs.readBinary(`${skillRoot}/${rel}`);
+			await fs.writeBinary(options.outPath, zipSync(files, { level: 6 }));
+		} else await (await loadTar()).c({
+			file: toPlatform$1(options.outPath),
+			cwd: toPlatform$1(skillRoot)
+		}, ["."]);
+		return options.outPath;
+	} catch (e) {
+		if (e instanceof WebSkillError) throw e;
+		throw new WebSkillError("EXPORT_FAILED", `Failed to export ${options.format} archive: ${messageOf(e)}`, e);
+	}
+}
+/** 只解出归档中的 webskill.skill-manifest.json 条目（安装前预览） */
+async function readArchiveManifest(fs, archivePath) {
+	const notFound = () => new WebSkillError("EXPORT_FAILED", `Archive ${archivePath} does not contain ${SKILL_MANIFEST_FILE}`);
+	const data = await fs.readBinary(archivePath);
+	if (isZipArchive(data)) {
+		const entries = unzipSync(data);
+		const key = Object.keys(entries).find((k) => k === "webskill.skill-manifest.json" || k.endsWith(`/${"webskill.skill-manifest.json"}`));
+		if (!key) throw notFound();
+		return JSON.parse(new TextDecoder().decode(entries[key]));
+	}
+	let manifestText;
+	try {
+		await (await loadTar()).t({
+			file: toPlatform$1(archivePath),
+			onentry: (entry) => {
+				if (entry.path === "webskill.skill-manifest.json" || entry.path.endsWith(`/${"webskill.skill-manifest.json"}`)) {
+					const chunks = [];
+					entry.on("data", (chunk) => chunks.push(chunk));
+					entry.on("end", () => {
+						manifestText = Buffer.concat(chunks).toString("utf8");
+					});
+				}
+			}
+		});
+	} catch (e) {
+		throw new WebSkillError("EXPORT_FAILED", `Failed to read tar archive: ${messageOf(e)}`, e);
+	}
+	if (manifestText === void 0) throw notFound();
+	return JSON.parse(manifestText);
+}
+const _execFileP = promisify(execFile);
+/**
+* 跨平台执行命令：Windows 下对 npm 等 cmd 包装的命令通过 cmd.exe 代理执行，
+* git 等原生 exe 不受影响。默认 120s 超时（防挂死安装管线）。
+*/
+async function execFileP(command, args, options = {}) {
+	const timeoutMs = options.timeoutMs ?? 12e4;
+	if (process.platform === "win32" && command === "npm") return _execFileP("cmd", [
+		"/c",
+		command,
+		...args
+	], { timeout: timeoutMs });
+	return _execFileP(command, args, { timeout: timeoutMs });
+}
+/** 命令缺失/失败 → INSTALL_FAILED 结构化诊断 */
+function commandFailed(command, e) {
+	return new WebSkillError("INSTALL_FAILED", `Failed to run ${command}: ${e?.code === "ENOENT" ? `command "${command}" not found on this system` : messageOf(e)}`, e);
+}
+/** git url 协议白名单：https:// 与 git@ SCP 形式；无 scheme 的本地路径放行（dev 工作流）；
+* 其余显式协议（ext::/file:// 等）一律拒绝 */
+function assertGitUrlSafe(url) {
+	if (url.startsWith("--")) throw new WebSkillError("INSTALL_FAILED", `Git url must not start with "--": ${JSON.stringify(url)}`);
+	if (url.startsWith("https://") || url.startsWith("git@")) return;
+	if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url)) throw new WebSkillError("INSTALL_FAILED", `Git url protocol is not allowed (only https://, git@ SCP form, or plain local paths): ${JSON.stringify(url)}`);
+}
+/** git 源：clone --depth 1 + rev-parse HEAD 记录 commit；url/ref 前插 `--` 防选项注入 */
+async function stageGit(source, ctx) {
+	assertGitUrlSafe(source.url);
+	if (source.ref?.startsWith("--")) throw new WebSkillError("INSTALL_FAILED", `Git ref must not start with "--": ${JSON.stringify(source.ref)}`);
+	const skillDir = `${ctx.stagingRoot}/repo`;
+	const args = [
+		"clone",
+		"--depth",
+		"1",
+		...source.ref ? ["--branch", source.ref] : [],
+		"--",
+		source.url,
+		skillDir
+	];
+	try {
+		await execFileP("git", args);
+	} catch (e) {
+		throw commandFailed("git", e);
+	}
+	let commit;
+	try {
+		const { stdout } = await execFileP("git", [
+			"-C",
+			skillDir,
+			"rev-parse",
+			"HEAD"
+		]);
+		commit = stdout.trim() || void 0;
+	} catch (e) {
+		console.warn(`[webskill] git rev-parse failed for ${source.url}; install provenance will omit the commit: ${e instanceof Error ? e.message : String(e)}`);
+	}
+	return {
+		skillDir,
+		source: {
+			...source,
+			...commit ? { commit } : {}
+		}
+	};
+}
+function sha256Hex(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+/** 重定向跳数上限（SSRF 防护：逐跳重新校验目标 URL） */
+const MAX_REDIRECT_HOPS = 3;
+/**
+* 带 SSRF 防护的下载：手动跟随重定向（默认 ≤3 跳），初始 URL 与每一跳目标
+* 都过 assertRemoteUrlAllowed（https 默认；私有/环回/链路本地默认拒绝）。
+*/
+async function fetchWithSsrfGuard(source, fetchImpl) {
+	const policy = {
+		allowHttp: source.allowHttp ?? false,
+		allowPrivateHosts: source.allowPrivateHosts ?? false
+	};
+	let url = assertRemoteUrlAllowed(source.url, policy);
+	for (let hop = 0;; hop++) {
+		const res = await fetchImpl(url.href, { redirect: "manual" });
+		const location = res.headers.get("location");
+		if (res.status >= 300 && res.status < 400 && location) {
+			if (hop >= MAX_REDIRECT_HOPS) throw new WebSkillError("INSTALL_FAILED", `Download exceeded the redirect limit of ${MAX_REDIRECT_HOPS} hops`);
+			url = assertRemoteUrlAllowed(new URL(location, url).href, policy);
+			continue;
+		}
+		return res;
+	}
+}
+/** http 源：下载归档（SSRF 防护 + Content-Length/流式上限；可选 expectedSha256 校验包体）→ 解包 → 定位技能根/包集 */
+async function stageHttp(source, ctx, expectedSha256) {
+	const fetchImpl = ctx.fetchImpl ?? fetch;
+	let res;
+	try {
+		res = await fetchWithSsrfGuard(source, fetchImpl);
+	} catch (e) {
+		if (e instanceof WebSkillError) throw e;
+		throw new WebSkillError("INSTALL_FAILED", `Download failed: ${messageOf(e)}`, e);
+	}
+	if (!res.ok) throw new WebSkillError("INSTALL_FAILED", `Download failed with HTTP ${res.status}`);
+	const data = await readResponseWithLimit(res, ctx.archiveLimits);
+	if (expectedSha256 !== void 0) {
+		const actual = sha256Hex(data);
+		if (actual !== expectedSha256) throw new WebSkillError("INSTALL_FAILED", `Archive checksum mismatch: expected ${expectedSha256}, got ${actual}`);
+	}
+	const contentDir = `${ctx.stagingRoot}/content`;
+	await ctx.fs.mkdir(contentDir);
+	if (isZipArchive(data)) await extractZipData(ctx.fs, data, contentDir, ctx.archiveLimits);
+	else {
+		const archivePath = `${ctx.stagingRoot}/archive.tar`;
+		await ctx.fs.writeBinary(archivePath, data);
+		await extractTarFile(toPlatform$1(archivePath), toPlatform$1(contentDir), ctx.archiveLimits);
+	}
+	const packFilePath = `${contentDir}/${SKILL_PACK_FILE}`;
+	if (await ctx.fs.exists(packFilePath)) return {
+		skillDir: "",
+		source,
+		pack: {
+			contentDir,
+			manifest: parseSkillPackManifest(await ctx.fs.readText(packFilePath))
+		}
+	};
+	if (await ctx.fs.exists(`${contentDir}/SKILL.md`)) return {
+		skillDir: contentDir,
+		source
+	};
+	const dirs = (await ctx.fs.list(contentDir)).filter((e) => e.type === "directory");
+	if (dirs.length === 1 && await ctx.fs.exists(`${dirs[0]?.path}/SKILL.md`)) return {
+		skillDir: dirs[0].path,
+		source
+	};
+	throw new WebSkillError("INSTALL_FAILED", "Archive does not contain a SKILL.md at its root or in a single top-level directory");
+}
+/** local 源：校验源目录存在，拷贝到 staging */
+async function stageLocal(source, ctx) {
+	if (!await ctx.fs.exists(source.path)) throw new WebSkillError("INSTALL_FAILED", `Local skill directory not found: ${source.path}`);
+	const skillDir = `${ctx.stagingRoot}/skill`;
+	await copyDir(ctx.fs, source.path, skillDir);
+	return {
+		skillDir,
+		source
+	};
+}
+/** npm 包名（@scope/name 或 name，小写字母数字 . _ - /）与版本（semver 或 dist-tag）正则 */
+const PACKAGE_NAME_RE = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/;
+const VERSION_RE = /^[a-z0-9._~^>=<x*+-]+$/i;
+/**
+* 本地路径字符白名单（Windows 下 npm 经 cmd /c 代理二次解析，
+* `& | < > ^ " ' % ! ;` 与空格一律拒绝；允许 Windows 盘符 `C:\` 与正/反斜杠）
+*/
+const LOCAL_PATH_RE = /^[A-Za-z0-9._~+@/\\:-]+$/;
+function assertNpmSpecSafe(source) {
+	const name = source.packageName;
+	const isLocalPath = name.startsWith("/") || name.startsWith("./") || name.startsWith("../");
+	if (name.startsWith("--") || !PACKAGE_NAME_RE.test(name) && !isLocalPath) throw new WebSkillError("INSTALL_FAILED", `Invalid npm package name: ${JSON.stringify(name)}`);
+	if (isLocalPath && !LOCAL_PATH_RE.test(name)) throw new WebSkillError("INSTALL_FAILED", `Local npm path contains characters outside the safe whitelist: ${JSON.stringify(name)}`);
+	if (source.version !== void 0 && (!VERSION_RE.test(source.version) || source.version.startsWith("--"))) throw new WebSkillError("INSTALL_FAILED", `Invalid npm package version: ${JSON.stringify(source.version)}`);
+}
+/** npm 源：npm pack --ignore-scripts → 解 tar.gz；技能根取包的 skill/ 子目录（存在时）否则包根；spec 前插 `--` 防选项注入 */
+async function stageNpm(source, ctx) {
+	assertNpmSpecSafe(source);
+	const spec = source.version ? `${source.packageName}@${source.version}` : source.packageName;
+	let stdout;
+	try {
+		({stdout} = await execFileP("npm", [
+			"pack",
+			"--ignore-scripts",
+			"--pack-destination",
+			ctx.stagingRoot,
+			"--",
+			spec
+		]));
+	} catch (e) {
+		throw commandFailed("npm", e);
+	}
+	const tarball = stdout.trim().split("\n").filter(Boolean).pop();
+	const tgzPath = tarball ? `${ctx.stagingRoot}/${tarball}` : "";
+	if (!tarball || !await ctx.fs.exists(tgzPath)) throw new WebSkillError("INSTALL_FAILED", `npm pack output not found in staging directory: ${tarball ?? "(empty output)"}`);
+	const pkgDir = `${ctx.stagingRoot}/pkg`;
+	await ctx.fs.mkdir(pkgDir);
+	await extractTarFile(toPlatform$1(tgzPath), toPlatform$1(pkgDir));
+	const pkgRoot = `${pkgDir}/package`;
+	const skillDir = await ctx.fs.exists(`${pkgRoot}/skill/SKILL.md`) ? `${pkgRoot}/skill` : pkgRoot;
+	let packageName = source.packageName;
+	let version = source.version;
+	try {
+		const pkg = JSON.parse(await ctx.fs.readText(`${pkgRoot}/package.json`));
+		packageName = pkg.name ?? packageName;
+		version = pkg.version ?? version;
+	} catch (e) {
+		console.warn(`[webskill] Cannot read package.json of npm skill "${source.packageName}"; recorded version may not match the installed artifact: ${e instanceof Error ? e.message : String(e)}`);
+	}
+	return {
+		skillDir,
+		source: {
+			type: "npm",
+			packageName,
+			...version ? { version } : {}
+		}
+	};
+}
+const emptyLockfile = () => ({
+	schemaVersion: 1,
+	skills: {}
+});
+/** 读取 lockfile；不存在返回空结构；损坏 JSON → INTEGRITY_FAILED */
+async function readLockfile(fs, managedRoot) {
+	const path = `${managedRoot}/${SKILLS_LOCKFILE}`;
+	if (!await fs.exists(path)) return emptyLockfile();
+	try {
+		const parsed = JSON.parse(await fs.readText(path));
+		if (typeof parsed !== "object" || parsed === null || typeof parsed.skills !== "object") throw new Error("unexpected lockfile shape");
+		return parsed;
+	} catch (e) {
+		throw new WebSkillError("INTEGRITY_FAILED", `Skills lockfile at ${path} is corrupted: ${e instanceof Error ? e.message : String(e)}`, e);
+	}
+}
+async function upsertLockEntry(fs, managedRoot, name, entry) {
+	const lockfile = await readLockfile(fs, managedRoot);
+	lockfile.skills[name] = entry;
+	await writeLockfileAtomic(fs, managedRoot, lockfile);
+	return lockfile;
+}
+async function removeLockEntry(fs, managedRoot, name) {
+	const lockfile = await readLockfile(fs, managedRoot);
+	delete lockfile.skills[name];
+	await writeLockfileAtomic(fs, managedRoot, lockfile);
+	return lockfile;
+}
+/** 原子写：先写临时文件再 rename（进程崩溃不留下半写 lockfile） */
+async function writeLockfileAtomic(fs, managedRoot, lockfile) {
+	await atomicWriteText(fs, `${managedRoot}/${SKILLS_LOCKFILE}`, JSON.stringify(lockfile, null, 2));
+}
+const EXCLUDED_FILES = /* @__PURE__ */ new Set([SKILL_MANIFEST_FILE, SKILLS_LOCKFILE]);
+/** 递归收集技能目录内的文件（相对路径，posix 分隔） */
+async function walkFiles(fs, root, prefix = "") {
+	const out = [];
+	for (const entry of await fs.list(root)) {
+		const name = entry.path.split("/").pop() ?? "";
+		const rel = prefix === "" ? name : `${prefix}/${name}`;
+		if (entry.type === "directory") out.push(...await walkFiles(fs, entry.path, rel));
+		else if (!EXCLUDED_FILES.has(name)) out.push(rel);
+	}
+	return out;
+}
+/** 生成并写入 webskill.skill-manifest.json */
+async function createManifest(fs, skillRoot, input) {
+	const files = [];
+	for (const rel of (await walkFiles(fs, skillRoot)).sort()) {
+		const content = await fs.readBinary(`${skillRoot}/${rel}`);
+		files.push({
+			path: rel,
+			size: content.length,
+			sha256: sha256Hex(content)
+		});
+	}
+	const manifest = await buildManifest({
+		name: input.name,
+		...input.version !== void 0 ? { version: input.version } : {},
+		source: input.source,
+		installedAt: input.installedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		files,
+		sha256: sha256Hex
+	});
+	await fs.writeText(`${skillRoot}/${SKILL_MANIFEST_FILE}`, JSON.stringify(manifest, null, 2));
+	return manifest;
+}
+/** 读取技能目录内的 manifest；缺失/损坏 → INTEGRITY_FAILED */
+async function readManifest(fs, skillRoot) {
+	const path = `${skillRoot}/${SKILL_MANIFEST_FILE}`;
+	if (!await fs.exists(path)) throw new WebSkillError("INTEGRITY_FAILED", `Skill manifest not found at ${path} (was the skill installed via SkillManager?)`);
+	try {
+		return JSON.parse(await fs.readText(path));
+	} catch (e) {
+		throw new WebSkillError("INTEGRITY_FAILED", `Skill manifest at ${path} is corrupted: ${e instanceof Error ? e.message : String(e)}`, e);
+	}
+}
+/** walk 实际目录与 manifest 比对：hash 不一致 / 清单外新增 / 清单内缺失三类全空才 ok */
+async function verifyIntegrity(fs, skillRoot) {
+	const manifest = await readManifest(fs, skillRoot);
+	const actualHashes = /* @__PURE__ */ new Map();
+	const actualFiles = await walkFiles(fs, skillRoot);
+	for (const rel of actualFiles) actualHashes.set(rel, sha256Hex(await fs.readBinary(`${skillRoot}/${rel}`)));
+	return verifyManifest(manifest, actualHashes, actualFiles);
+}
+const asInstallFailed = (e) => e instanceof WebSkillError && e.code === "INSTALL_FAILED" ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf(e)}`, e);
+/**
+* 技能管理门面：统一安装管线（staging → 解析 name → 校验 → 拷贝 → manifest → lockfile），
+* 任何失败清理现场抛 INSTALL_FAILED。
+* @stable
+*/
+var SkillManager = class {
+	#managedRoot;
+	#fs;
+	#fetchImpl;
+	#schemaInference;
+	#archiveLimits;
+	#onChanged;
+	#schemaInferer = new OxcSchemaInferer();
+	constructor(deps) {
+		this.#managedRoot = deps.managedRoot.replace(/\/+$/, "");
+		this.#fs = deps.fs ?? new NodeFS();
+		this.#fetchImpl = deps.fetchImpl;
+		this.#schemaInference = deps.schemaInference ?? true;
+		this.#archiveLimits = deps.archiveLimits;
+		this.#onChanged = deps.onChanged;
+	}
+	/** 托管根目录（治理发布归档捕获等只读场景） */
+	get managedRoot() {
+		return this.#managedRoot;
+	}
+	async install(source, options) {
+		const fs = this.#fs;
+		const stagingRoot = (await mkdtemp(path.join(tmpdir(), "webskill-install-"))).split(path.sep).join("/");
+		/** 已写入目标目录时用于回滚 */
+		let targetDir;
+		try {
+			const ctx = {
+				fs,
+				stagingRoot,
+				...this.#fetchImpl ? { fetchImpl: this.#fetchImpl } : {},
+				...this.#archiveLimits ? { archiveLimits: this.#archiveLimits } : {}
+			};
+			let staged;
+			switch (source.type) {
+				case "local":
+					staged = await stageLocal(source, ctx);
+					break;
+				case "http":
+					staged = await stageHttp(source, ctx, options?.expectedSha256);
+					break;
+				case "git":
+					staged = await stageGit(source, ctx);
+					break;
+				case "npm":
+					staged = await stageNpm(source, ctx);
+					break;
+				case "archive": throw new WebSkillError("TOOL_UNSUPPORTED", "The \"archive\" install source is only supported by the browser skill manager");
+			}
+			if (staged.pack) return (await this.#installPack(staged.pack, staged.source, stagingRoot))[0];
+			let name;
+			let version;
+			try {
+				const { metadata } = parseSkillMarkdown(await fs.readText(`${staged.skillDir}/SKILL.md`));
+				name = metadata.name;
+				version = typeof metadata["version"] === "string" ? metadata["version"] : void 0;
+			} catch (e) {
+				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)}`);
+			const finalRoot = `${stagingRoot}/final`;
+			const finalDir = `${finalRoot}/${name}`;
+			await copyDir(fs, staged.skillDir, finalDir);
+			const report = await validateSkills(fs, [finalRoot]);
+			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);
+			}
+			await this.#inferSkillSchemas(finalDir);
+			const manifest = await createManifest(fs, finalDir, {
+				name,
+				...version ? { version } : {},
+				source: staged.source
+			});
+			targetDir = `${this.#managedRoot}/${name}`;
+			const backupDir = `${stagingRoot}/backup`;
+			const hadPrevious = await fs.exists(targetDir);
+			if (hadPrevious) await copyDir(fs, targetDir, backupDir);
+			let committed = false;
+			try {
+				if (hadPrevious) await fs.remove(targetDir, { recursive: true });
+				await copyDir(fs, finalDir, targetDir);
+				committed = true;
+				await upsertLockEntry(fs, this.#managedRoot, name, {
+					digest: manifest.integrity.digest,
+					installedAt: manifest.installedAt,
+					source: staged.source
+				});
+			} catch (e) {
+				if (committed) await removeDirQuiet(fs, targetDir);
+				if (hadPrevious) await copyDir(fs, backupDir, targetDir);
+				targetDir = void 0;
+				throw e;
+			}
+			targetDir = void 0;
+			this.#onChanged?.();
+			return manifest;
+		} catch (e) {
+			if (targetDir) await removeDirQuiet(fs, targetDir);
+			throw asInstallFailed(e);
+		} finally {
+			await removeDirQuiet(fs, stagingRoot);
+		}
+	}
+	/**
+	* 包集安装：逐技能走单技能管线（归一 → 汇总校验 → 落 managed root → manifest → digest 比对）。
+	* 任一失败整体回滚（删除本次已落目录；lockfile 在全部成功后才写入，天然零残留）。
+	* 包是封闭产物：跳过安装期 schema 推导（sidecar 已随包携带，保证 digest 逐字节一致）。
+	*/
+	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) {
+				if (!isValidSkillName(entry.name)) throw new WebSkillError("INSTALL_FAILED", `Invalid skill name in skill pack manifest (path traversal rejected): ${JSON.stringify(entry.name)}`);
+				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(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 manifest = await createManifest(fs, `${finalRoot}/${entry.name}`, {
+					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);
+			}
+			const swapped = [];
+			try {
+				for (const manifest of manifests) {
+					const targetDir = `${this.#managedRoot}/${manifest.name}`;
+					const backupDir = `${stagingRoot}/backup/${manifest.name}`;
+					if (await fs.exists(targetDir)) {
+						await copyDir(fs, targetDir, backupDir);
+						await fs.remove(targetDir, { recursive: true });
+					}
+					await copyDir(fs, `${finalRoot}/${manifest.name}`, targetDir);
+					installed.push(targetDir);
+					swapped.push({
+						targetDir,
+						backupDir
+					});
+				}
+				for (const manifest of manifests) await upsertLockEntry(fs, this.#managedRoot, manifest.name, {
+					digest: manifest.integrity.digest,
+					installedAt: manifest.installedAt,
+					source
+				});
+			} catch (e) {
+				for (const { targetDir, backupDir } of swapped) {
+					await removeDirQuiet(fs, targetDir);
+					if (await fs.exists(backupDir)) await copyDir(fs, backupDir, targetDir);
+				}
+				installed.length = 0;
+				throw e;
+			}
+			this.#onChanged?.();
+			return manifests;
+		} catch (e) {
+			for (const targetDir of installed) await removeDirQuiet(fs, targetDir);
+			throw asInstallFailed(e);
+		}
+	}
+	/**
+	* D2 安装期预推导：scripts/ 下无显式 inputSchema 导出且无 sidecar 的脚本，
+	* 经 OXC 推导写 sidecar（计入 manifest.files；重装重新生成）
+	*/
+	async #inferSkillSchemas(skillRoot) {
+		if (!this.#schemaInference) return;
+		const fs = this.#fs;
+		const scriptsDir = `${skillRoot}/scripts`;
+		if (!await fs.exists(scriptsDir)) return;
+		for (const entry of await fs.list(scriptsDir)) {
+			if (entry.type !== "file") continue;
+			const match = /^(.*)\.(ts|js)$/.exec(entry.path.split("/").pop() ?? "");
+			if (!match?.[1]) continue;
+			const scriptName = match[1];
+			const sidecar = `${scriptsDir}/${scriptName}.schema.json`;
+			if (await fs.exists(sidecar)) continue;
+			const source = await fs.readText(entry.path);
+			if (/export\s+(?:const|let|var)\s+inputSchema/.test(source)) continue;
+			const inferred = this.#schemaInferer.inferSchemaFromSource(source, { fileName: `${scriptName}.${match[2]}` });
+			if (inferred) await fs.writeText(sidecar, JSON.stringify(inferred, null, 2));
+		}
+	}
+	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`);
+		try {
+			await this.#fs.remove(targetDir, { recursive: true });
+			await removeLockEntry(this.#fs, this.#managedRoot, name);
+			this.#onChanged?.();
+		} catch (e) {
+			throw new WebSkillError("UNINSTALL_FAILED", `Failed to uninstall "${name}": ${messageOf(e)}`, e);
+		}
+	}
+	async verifyIntegrity(name) {
+		if (!isValidSkillName(name)) throw new WebSkillError("INTEGRITY_FAILED", `Invalid skill name (path traversal rejected): ${JSON.stringify(name)}`);
+		return verifyIntegrity(this.#fs, `${this.#managedRoot}/${name}`);
+	}
+	async listInstalled() {
+		return readLockfile(this.#fs, this.#managedRoot);
+	}
+	async exportArchive(name, options) {
+		if (!isValidSkillName(name)) throw new WebSkillError("EXPORT_FAILED", `Invalid skill name (path traversal rejected): ${JSON.stringify(name)}`);
+		const skillRoot = `${this.#managedRoot}/${name}`;
+		if (!await this.#fs.exists(skillRoot)) throw new WebSkillError("EXPORT_FAILED", `Skill "${name}" is not installed`);
+		return exportArchive(this.#fs, skillRoot, options);
+	}
+	/** 多技能包集导出（webskill.skill-pack.json + 各技能目录含 manifest），写 outPath 并返回 */
+	async exportPack(names, options) {
+		if (names.length === 0) throw new WebSkillError("EXPORT_FAILED", "exportPack requires at least one skill name");
+		const roots = names.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 "${names[index]}" is not installed`);
+		const bytes = await exportSkills(this.#fs, {
+			roots,
+			manifestBuilder: (root) => readManifest(this.#fs, root)
+		});
+		await this.#fs.writeBinary(options.outPath, bytes);
+		return options.outPath;
+	}
+};
+
+//#endregion
+//#region ../governance/dist/node.js
+/** 审批工作流：review（UiBridge confirm 真实接线）/ publish（校验→安装→版本→审计） */
+var ApprovalWorkflow = class {
+	#policy;
+	#audit;
+	#store;
+	#skillManager;
+	#versions;
+	#fs;
+	constructor(deps) {
+		this.#policy = deps.policy;
+		this.#audit = deps.audit;
+		this.#store = deps.store;
+		this.#skillManager = deps.skillManager;
+		this.#versions = deps.versions;
+		this.#fs = deps.fs ?? new NodeFS();
+	}
+	/** 策略评估；needs-human 时经 UiBridge confirm 真实询问，按应答迁移状态 */
+	async review(candidateId, input) {
+		const candidate = await this.#store.get(candidateId);
+		if (candidate.status !== "draft" && candidate.status !== "pending-review") throw new WebSkillError("GOVERNANCE_FAILED", `Candidate "${candidateId}" cannot be reviewed from status "${candidate.status}"`);
+		const decision = this.#policy.evaluate(candidate);
+		let approved;
+		if (decision.needsHuman) {
+			if (!input.uiBridge) {
+				await this.#store.updateStatus(candidateId, "pending-review");
+				throw new WebSkillError("APPROVAL_REQUIRED", `Candidate "${candidate.name}" requires human approval: ${decision.reason}`);
+			}
+			await this.#store.updateStatus(candidateId, "pending-review");
+			const response = await input.uiBridge.request({
+				type: "confirm",
+				id: `approval-${candidateId}`,
+				message: `Approve candidate "${candidate.name}" (risk: ${candidate.risk})? ${decision.reason}`,
+				defaultValue: false
+			});
+			approved = response.cancelled !== true && response.value === true;
+		} else approved = true;
+		const updated = await this.#store.updateStatus(candidateId, approved ? "approved" : "rejected");
+		await this.#audit.append({
+			type: "candidate.reviewed",
+			target: candidateId,
+			actor: input.actor,
+			data: {
+				approved,
+				reason: decision.reason
+			}
+		});
+		return updated;
+	}
+	/** publish 全链路：approved 前置 → 写出 staging → validateSkills → install → 版本 → 审计 */
+	async publish(candidateId, input) {
+		const candidate = await this.#store.get(candidateId);
+		if (candidate.status !== "approved") throw new WebSkillError("APPROVAL_REQUIRED", `Candidate "${candidate.name}" must be approved before publishing (status: ${candidate.status})`);
+		const stagingRoot = (await mkdtemp(path.join(tmpdir(), "webskill-candidate-"))).split(path.sep).join("/");
+		try {
+			const skillDir = `${stagingRoot}/${candidate.name}`;
+			for (const file of candidate.files) await this.#fs.writeText(resolveInsideRoot(skillDir, file.path), file.content);
+			const report = await validateSkills(this.#fs, [stagingRoot]);
+			if (!report.ok) {
+				const errors = report.issues.filter((i) => i.severity === "error");
+				throw new WebSkillError("GOVERNANCE_FAILED", `Candidate "${candidate.name}" failed validation: ${errors.map((i) => i.message).join("; ")}`, errors);
+			}
+			const manifest = await this.#skillManager.install({
+				type: "local",
+				path: skillDir
+			});
+			const archiveOut = `${stagingRoot}/version-archive.zip`;
+			await exportArchive(this.#fs, `${this.#skillManager.managedRoot}/${candidate.name}`, {
+				format: "zip",
+				outPath: archiveOut
+			});
+			await this.#versions.add(candidate.name, {
+				reason: `Publish candidate ${candidateId}`,
+				manifest,
+				archive: await this.#fs.readBinary(archiveOut)
+			});
+			await this.#store.updateStatus(candidateId, "published");
+			await this.#audit.append({
+				type: "skill.published",
+				target: candidate.name,
+				actor: input.actor,
+				data: {
+					candidateId,
+					digest: manifest.integrity.digest
+				}
+			});
+			return manifest;
+		} catch (e) {
+			if (e instanceof WebSkillError) throw e;
+			throw new WebSkillError("GOVERNANCE_FAILED", `Failed to publish candidate "${candidateId}": ${messageOf(e)}`, e);
+		} finally {
+			try {
+				await this.#fs.remove(stagingRoot, { recursive: true });
+			} catch {}
+		}
+	}
+	/**
+	* 真实回滚（受审批保护：仅经显式 actor 调用并全程审计）：
+	* 版本归档解包 → staging 校验 → 原子安装（复用安装管线 swap）→ 追加新版本 + 审计。
+	* RepairPlanner 的 rollback 选项（targetVersionId）经本方法执行。
+	*/
+	async applyRollback(skillName, versionId, input) {
+		assertSafePathSegment(skillName, "skill name");
+		assertSafePathSegment(versionId, "version id");
+		const version = await this.#versions.get(skillName, versionId);
+		const archive = await this.#versions.readArchive(skillName, versionId);
+		const stagingRoot = (await mkdtemp(path.join(tmpdir(), "webskill-rollback-"))).split(path.sep).join("/");
+		try {
+			const skillDir = `${stagingRoot}/${skillName}`;
+			for (const [rel, content] of await unzipWithLimits(archive)) {
+				if (rel.endsWith("/")) continue;
+				await this.#fs.writeBinary(resolveInsideRoot(skillDir, rel), content);
+			}
+			const report = await validateSkills(this.#fs, [stagingRoot]);
+			if (!report.ok) {
+				const errors = report.issues.filter((i) => i.severity === "error");
+				throw new WebSkillError("GOVERNANCE_FAILED", `Rollback archive of "${skillName}" failed validation: ${errors.map((i) => i.message).join("; ")}`, errors);
+			}
+			const manifest = await this.#skillManager.install({
+				type: "local",
+				path: skillDir
+			});
+			if (manifest.integrity.digest !== version.manifest.integrity.digest) throw new WebSkillError("GOVERNANCE_FAILED", `Rollback of "${skillName}" to version "${versionId}" produced a digest mismatch: expected ${version.manifest.integrity.digest}, got ${manifest.integrity.digest}`);
+			await this.#versions.add(skillName, {
+				reason: input.reason ?? `Rollback to version ${versionId}`,
+				manifest,
+				archive
+			});
+			await this.#audit.append({
+				type: "skill.rolled_back",
+				target: skillName,
+				actor: input.actor,
+				data: {
+					targetVersionId: versionId,
+					reason: input.reason
+				}
+			});
+			return manifest;
+		} catch (e) {
+			if (e instanceof WebSkillError) throw e;
+			throw new WebSkillError("GOVERNANCE_FAILED", `Failed to roll back "${skillName}" to version "${versionId}": ${messageOf(e)}`, e);
+		} finally {
+			try {
+				await this.#fs.remove(stagingRoot, { recursive: true });
+			} catch {}
+		}
+	}
+};
+/**
+* 治理评估专用 runtime 装配（不可信技能试用路径）：
+* 默认注入 ProcessSandboxExecutor（fork + --permission 真实进程隔离；子进程
+* env 默认清空防密钥泄露，需透传时经 ProcessSandboxOptions.envWhitelist 显式放行）。
+* 可配置 executor 切回 SandboxedScriptExecutor（worker_threads 能力面收敛形态，
+* 非安全边界；envWhitelist 同样适用于该执行器）。
+*/
+function createEvaluationRuntime(deps) {
+	return new WebSkillRuntime({
+		...deps,
+		executor: deps.executor ?? new ProcessSandboxExecutor(deps.fs)
+	});
+}
+
+//#endregion
+export { ApprovalWorkflow, CliUiBridge, FileArtifactStore, FileMemoryStore, NodeFS, NodeScriptExecutor, OxcSchemaInferer, ProcessSandboxExecutor, SKILLS_LOCKFILE, SKILL_MANIFEST_FILE, SandboxedScriptExecutor, SkillManager, createEvaluationRuntime, createScriptContext, exportArchive, probeLlmCapabilities, readArchiveManifest };