@webskill/sdk 0.1.3 → 0.1.4

package/README.md

@@ -16,8 +16,11 @@ governance.
   (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.
+  the browser. Deny-by-default network policy, deny-by-default builtin-module
+  allowlist, per-capability forced approval, timeouts kill runaway scripts.
+  **Honest note:** these executors reduce the capability surface — they are NOT
+  a security boundary. Scripts share the host process/origin and bypasses
+  exist; never rely on them to isolate untrusted 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

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-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-Dq_A1yA-.js";
-import { $ as ToolDefinition, N as NetworkPolicy, X as ScriptExecutionContext, Z as ScriptExecutor, d as BridgeCapabilities, m as BridgeResponse, p as BridgeRequest, st as WebSkillApi, tt as ToolResult, u as ApprovalScope, ut as bridgeError, v as ExternalSkillProvider, xt as parseBridgeRequest, y as ExternalToolSource } from "./index-CqMuvcb2.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-DYrxhD3z.js";
+import { $ as ToolDefinition, N as NetworkPolicy, X as ScriptExecutionContext, Z as ScriptExecutor, d as BridgeCapabilities, m as BridgeResponse, p as BridgeRequest, st as WebSkillApi, tt as ToolResult, u as ApprovalScope, ut as bridgeError, v as ExternalSkillProvider, xt as parseBridgeRequest, y as ExternalToolSource } from "./index-BSS3EWY-.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */

package/dist/browser.js

@@ -1,6 +1,6 @@
-import { E as verifyManifest, T as validateSkills, _ as isValidSkillName, b as parseSkillMarkdown, d as buildManifest, g as exportSkills, l as WebSkillError, n as SKILLS_LOCKFILE, o as SKILL_PACK_FILE, r as SKILL_MANIFEST_FILE, s as SkillDiscovery, u as buildCatalog, w as resolveInsideRoot, x as parseSkillPackManifest } from "./dist-DS1sfgHa.js";
-import { A as mergeCatalogEntries, M as normalizeToolContent, N as parseBridgeRequest, S as bridgeError, T as createWebSkillApi, c as FsArtifactStore, h as ProgressiveRouter, i as AgentLoop, j as networkUrlHost, k as isNetworkAllowed, l as FsMemoryStore, m as OpenAiCompatibleClient, o as CapabilityApproval, u as FsRunSnapshotStore, y as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-DZobLFh6.js";
-import { n as MockLlmClient } from "./testing-CbM6rJ-E.js";
+import { D as verifyManifest, E as validateSkills, S as parseSkillPackManifest, T as resolveInsideRoot, _ as exportSkills, d as buildCatalog, f as buildManifest, l as WebSkillError, n as SKILLS_LOCKFILE, o as SKILL_PACK_FILE, r as SKILL_MANIFEST_FILE, s as SkillDiscovery, v as isValidSkillName, x as parseSkillMarkdown } from "./dist-DvoBsChX.js";
+import { A as mergeCatalogEntries, M as normalizeToolContent, N as parseBridgeRequest, S as bridgeError, T as createWebSkillApi, c as FsArtifactStore, h as ProgressiveRouter, i as AgentLoop, j as networkUrlHost, k as isNetworkAllowed, l as FsMemoryStore, m as OpenAiCompatibleClient, o as CapabilityApproval, u as FsRunSnapshotStore, y as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-DAn07zHu.js";
+import { n as MockLlmClient } from "./testing-S8SN9Lc6.js";
 import { unzipSync } from "fflate";
 
 //#region ../browser/dist/index.js
@@ -508,19 +508,31 @@ var BrowserSkillManager = class {
 				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);
 			}
-			targetDir = `${this.#managedRoot}/${name}`;
-			if (await fs.exists(targetDir)) await fs.remove(targetDir, { recursive: true });
-			await copyDir(fs, finalDir, targetDir);
-			const manifest = await this.#createManifest(targetDir, {
+			const manifest = await this.#createManifest(finalDir, {
 				name,
 				...version ? { version } : {},
 				source
 			});
-			await this.#upsertLockEntry(name, {
-				digest: manifest.integrity.digest,
-				installedAt: manifest.installedAt,
-				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 this.#upsertLockEntry(name, {
+					digest: manifest.integrity.digest,
+					installedAt: manifest.installedAt,
+					source
+				});
+			} catch (e) {
+				if (committed) await removeDirQuiet(fs, targetDir);
+				if (hadPrevious) await copyDir(fs, backupDir, targetDir);
+				targetDir = void 0;
+				throw e;
+			}
 			targetDir = void 0;
 			return manifest;
 		} catch (e) {
@@ -562,11 +574,7 @@ var BrowserSkillManager = class {
 			}
 			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, {
+				const manifest = await this.#createManifest(`${finalRoot}/${entry.name}`, {
 					name: entry.name,
 					...versions.get(entry.name) ? { version: versions.get(entry.name) } : {},
 					source
@@ -574,11 +582,35 @@ var BrowserSkillManager = class {
 				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
-			});
+			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 this.#upsertLockEntry(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;
+			}
 			return manifests;
 		} catch (e) {
 			for (const targetDir of installed) await removeDirQuiet(fs, targetDir);

package/dist/{dist-Cm_j6Jol.js → dist-BVXZF7H_.js}

@@ -1,5 +1,5 @@
-import { E as verifyManifest, T as validateSkills, _ as isValidSkillName, b as parseSkillMarkdown, d as buildManifest, g as exportSkills, l as WebSkillError, n as SKILLS_LOCKFILE, o as SKILL_PACK_FILE, r as SKILL_MANIFEST_FILE, w as resolveInsideRoot, x as parseSkillPackManifest } from "./dist-DS1sfgHa.js";
-import { M as normalizeToolContent, N as parseBridgeRequest, S as bridgeError, c as FsArtifactStore, j as networkUrlHost, k as isNetworkAllowed, l as FsMemoryStore, o as CapabilityApproval } from "./dist-DZobLFh6.js";
+import { D as verifyManifest, E as validateSkills, S as parseSkillPackManifest, T as resolveInsideRoot, _ as exportSkills, f as buildManifest, l as WebSkillError, n as SKILLS_LOCKFILE, o as SKILL_PACK_FILE, r as SKILL_MANIFEST_FILE, v as isValidSkillName, x as parseSkillMarkdown } from "./dist-DvoBsChX.js";
+import { M as normalizeToolContent, N as parseBridgeRequest, S as bridgeError, c as FsArtifactStore, j as networkUrlHost, k as isNetworkAllowed, l as FsMemoryStore, o as CapabilityApproval } from "./dist-DAn07zHu.js";
 import { unzipSync, zipSync } from "fflate";
 import { existsSync, promises, readFileSync } from "node:fs";
 import path from "node:path";
@@ -15,39 +15,73 @@ import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 
 //#region ../node/dist/index.js
-const toPlatform$3 = (p) => p.split("/").join(path.sep);
+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";
-/** 基于 node:fs/promises 的 FileSystemProvider；接受 `/` 风格路径，写入自动创建父目录 */
+/** 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 {
 	kind = "node";
+	#root;
+	constructor(deps = {}) {
+		this.#root = deps.root;
+	}
+	/** root 模式：目标 realpath 必须落在 root realpath 前缀内（符号链接逃逸防护） */
+	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$3(p), "utf8");
+			return await promises.readFile(toPlatform$4(p), "utf8");
 		} catch (e) {
 			throw this.#mapError(e, p);
 		}
 	}
 	async writeText(p, content) {
-		const target = toPlatform$3(p);
+		await this.#assertContained(p);
+		const target = toPlatform$4(p);
 		await promises.mkdir(path.dirname(target), { recursive: true });
 		await promises.writeFile(target, content, "utf8");
 	}
 	async readBinary(p) {
+		await this.#assertContained(p);
 		try {
-			return await promises.readFile(toPlatform$3(p));
+			return await promises.readFile(toPlatform$4(p));
 		} catch (e) {
 			throw this.#mapError(e, p);
 		}
 	}
 	async writeBinary(p, content) {
-		const target = toPlatform$3(p);
+		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) {
 		try {
-			await promises.access(toPlatform$3(p));
+			await promises.access(toPlatform$4(p));
 			return true;
 		} catch {
 			return false;
@@ -55,7 +89,7 @@ var NodeFS = class {
 	}
 	async stat(p) {
 		try {
-			const s = await promises.stat(toPlatform$3(p));
+			const s = await promises.stat(toPlatform$4(p));
 			return {
 				path: toPosix(p),
 				type: s.isDirectory() ? "directory" : "file",
@@ -69,21 +103,21 @@ var NodeFS = class {
 	async list(p) {
 		let dirents;
 		try {
-			dirents = await promises.readdir(toPlatform$3(p), { withFileTypes: true });
+			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$3(p), d.name)),
+			path: toPosix(path.join(toPlatform$4(p), d.name)),
 			type: d.isDirectory() ? "directory" : "file"
 		}));
 	}
 	async mkdir(p) {
-		await promises.mkdir(toPlatform$3(p), { recursive: true });
+		await promises.mkdir(toPlatform$4(p), { recursive: true });
 	}
 	async remove(p, options) {
 		try {
-			await promises.rm(toPlatform$3(p), { recursive: options?.recursive ?? false });
+			await promises.rm(toPlatform$4(p), { recursive: options?.recursive ?? false });
 		} catch (e) {
 			throw this.#mapError(e, p);
 		}
@@ -94,7 +128,7 @@ var NodeFS = class {
 	}
 };
 const baseName$1 = (p) => p.split("/").pop() ?? p;
-const toPlatform$2 = (p) => p.split("/").join(path.sep);
+const toPlatform$3 = (p) => p.split("/").join(path.sep);
 /**
 * 进程内脚本执行器。接口按沙箱语义设计（context 无隐式宿主访问），
 * worker_threads 沙箱见 deferred-items D1。
@@ -114,7 +148,7 @@ var NodeScriptExecutor = class {
 		return hasTs ? tsPath : jsPath;
 	}
 	async #loadModule(scriptPath) {
-		return await import(`${pathToFileURL(toPlatform$2(scriptPath)).href}?t=${Date.now()}`);
+		return await import(`${pathToFileURL(toPlatform$3(scriptPath)).href}?t=${Date.now()}`);
 	}
 	async loadDefinition(skillRoot, scriptName) {
 		const scriptPath = await this.#locateScript(skillRoot, scriptName);
@@ -223,14 +257,14 @@ var NodeScriptExecutor = class {
 	}
 };
 const baseName = (p) => p.split("/").pop() ?? p;
-const toPlatform$1 = (p) => p.split("/").join(path.sep);
+const toPlatform$2 = (p) => p.split("/").join(path.sep);
 const messageOf$5 = (e) => e instanceof Error ? e.message : String(e);
 /**
 * 网络策略判定函数源码（注入 Worker；匹配逻辑单一来源在
 * runtime/sandbox/networkPolicy.ts，Worker 线程不走 vitest 别名故注入而非 import）
 */
 const NETWORK_POLICY_LIB = `${isNetworkAllowed.toString()}\n${networkUrlHost.toString()}`;
-/** Worker 入口文件：src 为同目录 .ts；dist 为 dist/executor/ 下的 .js */
+/** Worker 入口文件：src 为同目录 .ts；node dist 为 dist/executor/；sdk dist 为平铺 dist/ */
 function workerEntryPath() {
 	const dir = path.dirname(fileURLToPath(import.meta.url));
 	const candidates = [
@@ -239,13 +273,17 @@ function workerEntryPath() {
 		path.join(dir, "executor", "sandboxWorkerEntry.js")
 	];
 	for (const candidate of candidates) if (existsSync(candidate)) return candidate;
-	return candidates[0];
+	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 内脚本与宿主共享进程，仍有绕过手段；
+* 禁止假定其可隔离不可信脚本。
 */
 var SandboxedScriptExecutor = class {
 	#fs;
@@ -280,7 +318,7 @@ var SandboxedScriptExecutor = class {
 		const skillName = baseName(skillRoot);
 		const result = await this.#runWorker({
 			mode: "load",
-			scriptPath: toPlatform$1(scriptPath),
+			scriptPath: toPlatform$2(scriptPath),
 			scriptName
 		});
 		if (!result.ok) throw new WebSkillError("TOOL_EXECUTION_FAILED", `Failed to load script "${scriptName}": ${result.error?.message ?? "unknown error"}`);
@@ -310,7 +348,7 @@ var SandboxedScriptExecutor = class {
 		try {
 			const result = await this.#runWorker({
 				mode: "execute",
-				scriptPath: toPlatform$1(scriptPath),
+				scriptPath: toPlatform$2(scriptPath),
 				scriptName,
 				skillName: context.skillName,
 				runId: context.runId,
@@ -356,7 +394,8 @@ var SandboxedScriptExecutor = class {
 				workerData: {
 					...workerData,
 					networkPolicy: this.#networkPolicy,
-					networkPolicyLib: NETWORK_POLICY_LIB
+					networkPolicyLib: NETWORK_POLICY_LIB,
+					allowedModules: this.#options.allowedModules ?? []
 				},
 				env,
 				resourceLimits: this.#options.resourceLimits ?? {
@@ -776,7 +815,7 @@ var CliUiBridge = class {
 	}
 };
 const messageOf$4 = (e) => e instanceof Error ? e.message : String(e);
-const toPlatform = (p) => p.split("/").join(path.sep);
+const toPlatform$1 = (p) => p.split("/").join(path.sep);
 const isZipArchive = (data) => data.length > 1 && data[0] === 80 && data[1] === 75;
 /**
 * zip 解包（fflate）。每个条目路径过 resolveInsideRoot：
@@ -803,15 +842,15 @@ async function extractTarFile(archivePath, destRoot) {
 	try {
 		const entryPaths = [];
 		await tar.t({
-			file: toPlatform(archivePath),
+			file: toPlatform$1(archivePath),
 			onentry: (entry) => {
 				entryPaths.push(entry.path);
 			}
 		});
 		for (const p of entryPaths) if (!p.replace(/\\/g, "/").split("/").every((s) => s === "" || s === ".")) resolveInsideRoot(destRoot, p);
 		await tar.x({
-			file: toPlatform(archivePath),
-			cwd: toPlatform(destRoot),
+			file: toPlatform$1(archivePath),
+			cwd: toPlatform$1(destRoot),
 			filter: (_p, entry) => !("type" in entry) || entry.type !== "SymbolicLink" && entry.type !== "Link"
 		});
 	} catch (e) {
@@ -830,8 +869,23 @@ async function listFiles(fs, root, prefix = "") {
 	}
 	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 {
+		return;
+	}
+	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() ?? "";
@@ -854,8 +908,8 @@ async function exportArchive(fs, skillRoot, options) {
 			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 tar.c({
-			file: toPlatform(options.outPath),
-			cwd: toPlatform(skillRoot)
+			file: toPlatform$1(options.outPath),
+			cwd: toPlatform$1(skillRoot)
 		}, ["."]);
 		return options.outPath;
 	} catch (e) {
@@ -876,7 +930,7 @@ async function readArchiveManifest(fs, archivePath) {
 	let manifestText;
 	try {
 		await tar.t({
-			file: toPlatform(archivePath),
+			file: toPlatform$1(archivePath),
 			onentry: (entry) => {
 				if (entry.path === "webskill.skill-manifest.json" || entry.path.endsWith(`/${"webskill.skill-manifest.json"}`)) {
 					const chunks = [];
@@ -970,7 +1024,7 @@ async function stageHttp(source, ctx, expectedSha256) {
 	else {
 		const archivePath = `${ctx.stagingRoot}/archive.tar`;
 		await ctx.fs.writeBinary(archivePath, data);
-		await extractTarFile(toPlatform(archivePath), toPlatform(contentDir));
+		await extractTarFile(toPlatform$1(archivePath), toPlatform$1(contentDir));
 	}
 	const packFilePath = `${contentDir}/${SKILL_PACK_FILE}`;
 	if (await ctx.fs.exists(packFilePath)) return {
@@ -1021,7 +1075,7 @@ async function stageNpm(source, ctx) {
 	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(tgzPath), toPlatform(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;
@@ -1187,20 +1241,32 @@ var SkillManager = class {
 				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);
 			}
-			targetDir = `${this.#managedRoot}/${name}`;
-			if (await fs.exists(targetDir)) await fs.remove(targetDir, { recursive: true });
-			await copyDir(fs, finalDir, targetDir);
-			await this.#inferSkillSchemas(targetDir);
-			const manifest = await createManifest(fs, targetDir, {
+			await this.#inferSkillSchemas(finalDir);
+			const manifest = await createManifest(fs, finalDir, {
 				name,
 				...version ? { version } : {},
 				source: staged.source
 			});
-			await upsertLockEntry(fs, this.#managedRoot, name, {
-				digest: manifest.integrity.digest,
-				installedAt: manifest.installedAt,
-				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;
 			return manifest;
 		} catch (e) {
@@ -1243,11 +1309,7 @@ var SkillManager = class {
 			}
 			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 createManifest(fs, targetDir, {
+				const manifest = await createManifest(fs, `${finalRoot}/${entry.name}`, {
 					name: entry.name,
 					...versions.get(entry.name) ? { version: versions.get(entry.name) } : {},
 					source
@@ -1255,11 +1317,35 @@ var SkillManager = class {
 				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 upsertLockEntry(fs, this.#managedRoot, manifest.name, {
-				digest: manifest.integrity.digest,
-				installedAt: manifest.installedAt,
-				source
-			});
+			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;
+			}
 			return manifests;
 		} catch (e) {
 			for (const targetDir of installed) await removeDirQuiet(fs, targetDir);

package/dist/{dist-DZobLFh6.js → dist-DAn07zHu.js}

@@ -1,4 +1,4 @@
-import { S as renderAvailableSkillsXml, T as validateSkills, b as parseSkillMarkdown, c as SkillReader, l as WebSkillError, s as SkillDiscovery, u as buildCatalog, w as resolveInsideRoot } from "./dist-DS1sfgHa.js";
+import { C as renderAvailableSkillsXml, E as validateSkills, T as resolveInsideRoot, c as SkillReader, d as buildCatalog, l as WebSkillError, s as SkillDiscovery, u as assertSafePathSegment, x as parseSkillMarkdown } from "./dist-DvoBsChX.js";
 import { t as MemoryArtifactStore } from "./memoryArtifactStore-C9lFVqPF-yFz6yJj0.js";
 
 //#region ../runtime/dist/index.js
@@ -1577,6 +1577,7 @@ var AgentLoop = class {
 	}
 	/** 经外部技能提供者读取技能文档/资源；skillKey 为技能名或 mcp:// URI */
 	async #handleReadExternalSkill(skillKey, pathArg, state) {
+		const failures = [];
 		for (const provider of this.#deps.skillProviders ?? []) try {
 			let name = skillKey;
 			if (skillKey.startsWith("mcp://")) {
@@ -1610,10 +1611,12 @@ var AgentLoop = class {
 					text: await provider.readFile(name, pathArg)
 				}]
 			};
-		} catch {
+		} catch (e) {
+			failures.push(messageOf$1(e));
 			continue;
 		}
-		return toolError("SKILL_NOT_FOUND", `Skill not found via external providers: ${skillKey}`);
+		const detail = failures.length > 0 ? ` (provider errors: ${failures.join("; ")})` : "";
+		return toolError("SKILL_NOT_FOUND", `Skill not found via external providers: ${skillKey}${detail}`);
 	}
 	/** 首次读到 SKILL.md 时激活技能：加载其 scripts 工具定义，供后续轮次使用；dependencies 级联激活（via 记录来源） */
 	async #activateSkill(skillName, state, via, skillMdText) {
@@ -1635,7 +1638,9 @@ var AgentLoop = class {
 			const rawAllowed = metadata["allowed-tools"];
 			if (rawAllowed !== void 0) if (Array.isArray(rawAllowed)) allowedTools = rawAllowed.filter((e) => typeof e === "string");
 			else state.trace.record("run.warning", { message: `Skill "${skillName}" has a non-array "allowed-tools" metadata entry; ignored` });
-		} catch {}
+		} catch (e) {
+			state.trace.record("run.warning", { message: `Failed to read or parse SKILL.md of skill "${skillName}": ${messageOf$1(e)}` });
+		}
 		const executor = this.#deps.executor;
 		const loaded = [];
 		if (executor) {
@@ -1654,7 +1659,9 @@ var AgentLoop = class {
 					await this.#enrichDefinition(root, match[1], def, state);
 					state.activatedTools.set(def.name, def);
 					loaded.push(def.name);
-				} catch {}
+				} catch (e) {
+					state.trace.record("run.warning", { message: `Failed to load definition of script "${match[1]}" for skill "${skillName}": ${messageOf$1(e)}` });
+				}
 			}
 		}
 		let note = loaded.length ? `\n\nActivated tools: ${loaded.join(", ")}` : "";
@@ -1924,10 +1931,12 @@ var WebSkillRuntime = class {
 		if (!this.#catalogCache) await this.discover();
 		const cache = this.#catalogCache;
 		if (!cache) throw new Error("discover() did not populate the catalog cache");
+		const providerFailures = [];
 		const providerEntries = (await Promise.all((this.#deps.skillProviders ?? []).map(async (p) => {
 			try {
 				return await p.listSkills();
-			} catch {
+			} catch (e) {
+				providerFailures.push(e instanceof Error ? e.message : String(e));
 				return [];
 			}
 		}))).flat();
@@ -1957,6 +1966,13 @@ var WebSkillRuntime = class {
 			userPrompt,
 			route
 		});
+		for (const failure of providerFailures) result.run.trace.push({
+			id: `evt-provider-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+			runId: result.run.id,
+			ts: (/* @__PURE__ */ new Date()).toISOString(),
+			type: "run.warning",
+			message: `Skill provider listSkills() failed: ${failure}`
+		});
 		if (this.#deps.onSkillMiss && result.run.activeSkillNames.length === 0) this.#deps.onSkillMiss({
 			prompt: userPrompt,
 			run: result.run
@@ -2279,6 +2295,7 @@ var FsArtifactStore = class {
 		});
 	}
 	async listArtifacts(runId) {
+		assertSafePathSegment(runId, "runId");
 		const indexPath = `${this.#root}/${runId}/${INDEX_FILE}`;
 		if (!await this.#fs.exists(indexPath)) return [];
 		const raw = await this.#fs.readText(indexPath);
@@ -2290,6 +2307,7 @@ var FsArtifactStore = class {
 		}
 	}
 	#artifactPath(runId, artifactPath) {
+		assertSafePathSegment(runId, "runId");
 		return resolveInsideRoot(`${this.#root}/${runId}`, artifactPath);
 	}
 	async #persist(input) {

package/dist/{dist-DS1sfgHa.js → dist-DvoBsChX.js}

@@ -174,8 +174,20 @@ function normalizePath(path) {
 	return path.replace(/\\/g, "/").split("/").filter((s) => s !== "" && s !== ".").join("/");
 }
 /**
+* 外部标识（runId、candidateId、skillName、versionId 等）作为单一路径段使用前的统一校验：
+* 拒绝空串、`.`、`..`、含 `/` 或 `\`、含 `:`（Windows 盘符/ADS）。
+* 违规抛 FS_PATH_OUTSIDE_ROOT（kind 用于错误消息定位，如 "runId"）。
+*/
+function assertSafePathSegment(segment, kind) {
+	if (segment === "" || segment === "." || segment === ".." || segment.includes("/") || segment.includes("\\") || segment.includes(":")) throw new WebSkillError("FS_PATH_OUTSIDE_ROOT", `Invalid ${kind} (must be a single safe path segment): ${JSON.stringify(segment)}`);
+}
+/**
 * 将相对路径安全地解析到 root 之内。
 * 拒绝空路径、绝对路径（`/`、`\\`、`C:\` 形式）与任何 `..` 段。
+*
+* 注意：本函数仅做**词法**校验，不解析符号链接——root 内经符号链接指向
+* 外部的目标无法被词法检查拦截（realpath 防护见 NodeFS root 模式与
+* 安装管线的 lstat 符号链接扫描）。
 */
 function resolveInsideRoot(root, relativePath) {
 	const fail = (reason) => {
@@ -587,4 +599,4 @@ const xmlRenderer = {
 };
 
 //#endregion
-export { renderCatalogJson as C, xmlRenderer as D, verifyManifest as E, renderAvailableSkillsXml as S, validateSkills as T, isValidSkillName as _, SKILL_NAME_PATTERN as a, parseSkillMarkdown as b, SkillReader as c, buildManifest as d, checkDependencyCycles as f, exportSkills as g, escapeXml as h, SKILL_NAME_MAX_LENGTH as i, WebSkillError as l, computeDigest as m, SKILLS_LOCKFILE as n, SKILL_PACK_FILE as o, checkSkillRules as p, SKILL_MANIFEST_FILE as r, SkillDiscovery as s, MemoryFS as t, buildCatalog as u, jsonRenderer as v, resolveInsideRoot as w, parseSkillPackManifest as x, normalizePath as y };
+export { renderAvailableSkillsXml as C, verifyManifest as D, validateSkills as E, xmlRenderer as O, parseSkillPackManifest as S, resolveInsideRoot as T, exportSkills as _, SKILL_NAME_PATTERN as a, normalizePath as b, SkillReader as c, buildCatalog as d, buildManifest as f, escapeXml as g, computeDigest as h, SKILL_NAME_MAX_LENGTH as i, WebSkillError as l, checkSkillRules as m, SKILLS_LOCKFILE as n, SKILL_PACK_FILE as o, checkDependencyCycles as p, SKILL_MANIFEST_FILE as r, SkillDiscovery as s, MemoryFS as t, assertSafePathSegment as u, isValidSkillName as v, renderCatalogJson as w, parseSkillMarkdown as x, jsonRenderer as y };