@webskill/sdk 0.1.4 → 0.2.0

package/dist/env--jJB-TSX-04klhTYi.js

@@ -0,0 +1,143 @@
+import { readFileSync } from "node:fs";
+
+//#region ../node/dist/env--jJB-TSX.js
+/** 解析 .env（简单 KEY=VALUE 行解析，不引依赖）；文件缺失返回 undefined */
+function readEnvVars(dotenvPath) {
+	let raw;
+	try {
+		raw = readFileSync(dotenvPath, "utf8");
+	} catch {
+		return;
+	}
+	const vars = /* @__PURE__ */ new Map();
+	for (const line of raw.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		const eq = trimmed.indexOf("=");
+		if (eq <= 0) continue;
+		const key = trimmed.slice(0, eq).trim();
+		let value = trimmed.slice(eq + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+		vars.set(key, value);
+	}
+	return vars;
+}
+/**
+* 读取 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL（优先），
+* 向后兼容 VITE_BASE_URL / VITE_API_KEY / VITE_MODEL_NAME；缺项返回 undefined 供测试 skip 判断。
+*/
+function loadLlmConfigFromEnv(dotenvPath = ".env") {
+	const vars = readEnvVars(dotenvPath);
+	if (!vars) return void 0;
+	const baseUrl = vars.get("LLM_BASE_URL") ?? vars.get("VITE_BASE_URL");
+	const apiKey = vars.get("LLM_API_KEY") ?? vars.get("VITE_API_KEY");
+	const model = vars.get("LLM_MODEL") ?? vars.get("VITE_MODEL_NAME");
+	if (!baseUrl || !apiKey || !model) return void 0;
+	return {
+		baseUrl,
+		apiKey,
+		model
+	};
+}
+/** ANTHROPIC_API_KEY / ANTHROPIC_MODEL（可选 ANTHROPIC_BASE_URL）；缺项返回 undefined */
+function loadAnthropicConfigFromEnv(dotenvPath = ".env") {
+	const vars = readEnvVars(dotenvPath);
+	if (!vars) return void 0;
+	const apiKey = vars.get("ANTHROPIC_API_KEY");
+	const model = vars.get("ANTHROPIC_MODEL");
+	if (!apiKey || !model) return void 0;
+	const baseUrl = vars.get("ANTHROPIC_BASE_URL");
+	return {
+		apiKey,
+		model,
+		...baseUrl ? { baseUrl } : {}
+	};
+}
+/** GOOGLE_API_KEY / GOOGLE_MODEL（可选 GOOGLE_BASE_URL）；缺项返回 undefined */
+function loadGoogleConfigFromEnv(dotenvPath = ".env") {
+	const vars = readEnvVars(dotenvPath);
+	if (!vars) return void 0;
+	const apiKey = vars.get("GOOGLE_API_KEY");
+	const model = vars.get("GOOGLE_MODEL");
+	if (!apiKey || !model) return void 0;
+	const baseUrl = vars.get("GOOGLE_BASE_URL");
+	return {
+		apiKey,
+		model,
+		...baseUrl ? { baseUrl } : {}
+	};
+}
+let capabilitiesCache;
+/**
+* 探测 LLM 能力（结果模块级缓存）：
+* - available：GET /models 可达（与 checkAvailability 同语义）
+* - nonStreaming：最小非流式 chat completion（max_tokens=1，短超时）；
+*   HTTP 400/404 或明确不支持非流式的错误 → false
+* - streaming 能力由 available 推断（SSE 解析在 SDK 侧实现）
+* 环境变量 VITE_LLM_NON_STREAMING=0 可显式强制 nonStreaming=false（模拟流式-only 回归）。
+*/
+function probeLlmCapabilities(config) {
+	capabilitiesCache ??= doProbeLlmCapabilities(config);
+	return capabilitiesCache;
+}
+async function doProbeLlmCapabilities(config) {
+	const baseUrl = config.baseUrl.replace(/\/+$/, "");
+	const headers = { authorization: `Bearer ${config.apiKey}` };
+	let available;
+	try {
+		available = (await fetch(`${baseUrl}/models`, {
+			headers,
+			signal: AbortSignal.timeout(1e4)
+		})).ok;
+	} catch {
+		available = false;
+	}
+	if (!available) return {
+		available: false,
+		nonStreaming: false,
+		reason: "endpoint unreachable or unauthorized"
+	};
+	if (process.env["VITE_LLM_NON_STREAMING"] === "0") return {
+		available: true,
+		nonStreaming: false,
+		reason: "non-streaming disabled via VITE_LLM_NON_STREAMING=0 (simulated)"
+	};
+	try {
+		const res = await fetch(`${baseUrl}/chat/completions`, {
+			method: "POST",
+			headers: {
+				...headers,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify({
+				model: config.model,
+				messages: [{
+					role: "user",
+					content: "OK"
+				}],
+				max_tokens: 1
+			}),
+			signal: AbortSignal.timeout(15e3)
+		});
+		const contentType = res.headers.get("content-type") ?? "";
+		if (res.ok && !contentType.includes("text/event-stream")) return {
+			available: true,
+			nonStreaming: true
+		};
+		const detail = (await res.text().catch(() => "")).slice(0, 200);
+		return {
+			available: true,
+			nonStreaming: false,
+			reason: `endpoint rejects non-streaming chat completions (HTTP ${res.status})${detail ? `: ${detail}` : ""}`
+		};
+	} catch (e) {
+		return {
+			available: true,
+			nonStreaming: false,
+			reason: `non-streaming probe failed: ${e instanceof Error ? e.message : String(e)}`
+		};
+	}
+}
+
+//#endregion
+export { probeLlmCapabilities as i, loadGoogleConfigFromEnv as n, loadLlmConfigFromEnv as r, loadAnthropicConfigFromEnv as t };

package/dist/env-BPUBZCwJ-4jat_SVG.d.ts

@@ -0,0 +1,38 @@
+//#region ../node/dist/env-BPUBZCwJ.d.ts
+//#region src/env.d.ts
+interface LlmEnvConfig {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+}
+/** per-provider env 配置（baseUrl 可选，客户端自带默认） */
+interface ProviderEnvConfig {
+  apiKey: string;
+  model: string;
+  baseUrl?: string;
+}
+/**
+ * 读取 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL（优先），
+ * 向后兼容 VITE_BASE_URL / VITE_API_KEY / VITE_MODEL_NAME；缺项返回 undefined 供测试 skip 判断。
+ */
+declare function loadLlmConfigFromEnv(dotenvPath?: string): LlmEnvConfig | undefined;
+/** ANTHROPIC_API_KEY / ANTHROPIC_MODEL（可选 ANTHROPIC_BASE_URL）；缺项返回 undefined */
+declare function loadAnthropicConfigFromEnv(dotenvPath?: string): ProviderEnvConfig | undefined;
+/** GOOGLE_API_KEY / GOOGLE_MODEL（可选 GOOGLE_BASE_URL）；缺项返回 undefined */
+declare function loadGoogleConfigFromEnv(dotenvPath?: string): ProviderEnvConfig | undefined;
+interface LlmCapabilities {
+  available: boolean;
+  nonStreaming: boolean;
+  reason?: string;
+}
+/**
+ * 探测 LLM 能力（结果模块级缓存）：
+ * - available：GET /models 可达（与 checkAvailability 同语义）
+ * - nonStreaming：最小非流式 chat completion（max_tokens=1，短超时）；
+ *   HTTP 400/404 或明确不支持非流式的错误 → false
+ * - streaming 能力由 available 推断（SSE 解析在 SDK 侧实现）
+ * 环境变量 VITE_LLM_NON_STREAMING=0 可显式强制 nonStreaming=false（模拟流式-only 回归）。
+ */
+declare function probeLlmCapabilities(config: LlmEnvConfig): Promise<LlmCapabilities>;
+//#endregion
+export { loadGoogleConfigFromEnv as a, loadAnthropicConfigFromEnv as i, LlmEnvConfig as n, loadLlmConfigFromEnv as o, ProviderEnvConfig as r, probeLlmCapabilities as s, LlmCapabilities as t };

package/dist/governance.d.ts

@@ -1,6 +1,6 @@
-import { L as SkillManifest, N as SkillDocument, S as FileSystemProvider, c as LlmClient, j as SkillCatalogEntry, u as LlmMessage, v as UiBridge } from "./types-CgNC-oQu-DYrxhD3z.js";
-import { ct as WebSkillRuntime, q as RuntimeRun } from "./index-BSS3EWY-.js";
-import { f as SkillManager } from "./index-npFMt2Zw.js";
+import { F as SkillDocument, N as SkillCatalogEntry, c as LlmClient, u as LlmMessage, v as UiBridge, w as FileSystemProvider, z as SkillManifest } from "./types-CKm5G_eQ-8W8FnP4u.js";
+import { dt as WebSkillRuntime, q as RuntimeRun, tt as SkillStateGuard } from "./index-CySxIvRz.js";
+import { l as SkillManager } from "./index-Vn63HJRO.js";
 //#region ../governance/dist/index.d.ts
 //#region src/types.d.ts
 type CandidateStatus = 'draft' | 'pending-review' | 'approved' | 'published' | 'rejected';
@@ -32,6 +32,10 @@ interface AuditEvent {
   actor?: string;
   ts: string;
   data?: Record<string, unknown>;
+  /** hash 链：上一条事件的 hash（首条为 GENESIS） */
+  prevHash?: string;
+  /** 本事件规范化载荷 + prevHash 的 sha256 */
+  hash?: string;
 }
 interface AuditLog {
   append(event: Omit<AuditEvent, 'id' | 'ts'> & {
@@ -51,6 +55,8 @@ interface SkillVersion {
   reason: string;
   manifest: SkillManifest;
   auditEventId?: string;
+  /** 发布时捕获的技能归档（zip 相对路径，applyRollback 恢复用；0.2.0 起记录） */
+  archivePath?: string;
 }
 type SkillState = 'active' | 'quarantined' | 'deprecated' | 'disabled';
 //#endregion
@@ -151,7 +157,10 @@ declare class SkillVersionStore {
     reason: string;
     manifest: SkillManifest;
     parentVersionId?: string;
+    archive?: Uint8Array;
   }): Promise<SkillVersion>;
+  /** 读取版本归档字节（applyRollback 用；未捕获归档的旧版本 → GOVERNANCE_FAILED） */
+  readArchive(skillName: string, versionId: string): Promise<Uint8Array>;
   list(skillName: string): Promise<SkillVersion[]>;
   get(skillName: string, versionId: string): Promise<SkillVersion>;
   /** 回滚：基于旧 manifest 追加新版本 + skill.rolled_back 审计 */
@@ -182,10 +191,25 @@ declare class ApprovalWorkflow {
   publish(candidateId: string, input: {
     actor: string;
   }): Promise<SkillManifest>;
+  /**
+   * 真实回滚（受审批保护：仅经显式 actor 调用并全程审计）：
+   * 版本归档解包 → staging 校验 → 原子安装（复用安装管线 swap）→ 追加新版本 + 审计。
+   * RepairPlanner 的 rollback 选项（targetVersionId）经本方法执行。
+   */
+  applyRollback(skillName: string, versionId: string, input: {
+    actor: string;
+    reason?: string;
+  }): Promise<SkillManifest>;
 }
 //#endregion
 //#region src/audit/fsAuditLog.d.ts
-/** JSONL 追加的审计日志：<managedRoot>/.webskill/audit.jsonl；跨实例可恢复查询 */
+interface AuditChainVerification {
+  ok: boolean;
+  /** 首个断链位置（行号，0 起；ok 时 undefined） */
+  brokenAt?: number;
+  reason?: string;
+}
+/** JSONL 追加的审计日志：<managedRoot>/.webskill/audit.jsonl；跨实例可恢复查询；prevHash 链可校验完整性 */
 declare class FsAuditLog implements AuditLog {
   #private;
   constructor(deps: {
@@ -194,7 +218,7 @@ declare class FsAuditLog implements AuditLog {
     now?: () => string;
     createId?: () => string;
   });
-  append(event: Omit<AuditEvent, 'id' | 'ts'> & {
+  append(event: Omit<AuditEvent, 'id' | 'ts' | 'prevHash' | 'hash'> & {
     id?: string;
     ts?: string;
   }): Promise<AuditEvent>;
@@ -203,6 +227,8 @@ declare class FsAuditLog implements AuditLog {
     type?: string;
     since?: string;
   }): Promise<AuditEvent[]>;
+  /** hash 链完整性校验：逐行重算 hash 并核对 prevHash 链接 */
+  verifyChain(): Promise<AuditChainVerification>;
 }
 //#endregion
 //#region src/repair/failureAnalyzer.d.ts
@@ -234,7 +260,7 @@ interface RepairOption {
 }
 /**
  * 修订选项规划：patch（按诊断给具体文件变更）/ rollback（有旧版本时）/ quarantine。
- * 注意：任何 option 的 apply 都必须经 ApprovalWorkflow 审批后执行。
+ * 注意：任何 option 的 apply 都必须经 ApprovalWorkflow 审批后执行；rollback 选项（targetVersionId）经 ApprovalWorkflow.applyRollback 真实恢复文件。
  */
 declare class RepairPlanner {
   plan(input: {
@@ -270,6 +296,12 @@ declare class SkillStatePolicy {
   }): Promise<SkillState>;
   canRoute(state: SkillState): boolean;
   canExecute(state: SkillState): boolean;
+  /**
+   * runtime SkillStateGuard 适配（0.1.5 一致拦截）：
+   * canRead：active/deprecated 放行；canActivate/canExecute 与 canRoute/canExecute 语义对齐；
+   * quarantined/disabled 三入口全拦截。
+   */
+  toSkillStateGuard(): SkillStateGuard;
   /** disabled → SKILL_DISABLED；quarantined → SKILL_QUARANTINED */
   assertExecutable(skillName: string): Promise<void>;
   /** runtime catalogFilter 实现：quarantined/deprecated/disabled 技能被路由过滤 */

package/dist/governance.js

@@ -1,8 +1,8 @@
-import { E as validateSkills, T as resolveInsideRoot, l as WebSkillError, u as assertSafePathSegment, v as isValidSkillName } from "./dist-DvoBsChX.js";
-import { i as NodeFS } from "./dist-BVXZF7H_.js";
+import { A as unzipWithLimits, b as isValidSkillName, d as assertSafePathSegment, j as validateSkills, k as resolveInsideRoot, u as WebSkillError } from "./dist-D0saNPi_.js";
+import { i as NodeFS, l as exportArchive } from "./dist-Dj6QjHBn.js";
 import path from "node:path";
-import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
+import { mkdtemp } from "node:fs/promises";
 import { createHash } from "node:crypto";
 
 //#region ../governance/dist/index.js
@@ -307,9 +307,15 @@ var ApprovalWorkflow = class {
 				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
+				manifest,
+				archive: await this.#fs.readBinary(archiveOut)
 			});
 			await this.#store.updateStatus(candidateId, "published");
 			await this.#audit.append({
@@ -325,11 +331,79 @@ var ApprovalWorkflow = class {
 		} catch (e) {
 			if (e instanceof WebSkillError) throw e;
 			throw new WebSkillError("GOVERNANCE_FAILED", `Failed to publish candidate "${candidateId}": ${messageOf$1(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$1(e)}`, e);
+		} finally {
+			try {
+				await this.#fs.remove(stagingRoot, { recursive: true });
+			} catch {}
 		}
 	}
 };
 const fileOf$1 = (root) => `${root}/.webskill/audit.jsonl`;
-/** JSONL 追加的审计日志：<managedRoot>/.webskill/audit.jsonl；跨实例可恢复查询 */
+const sha256Hex = (text) => createHash("sha256").update(text, "utf8").digest("hex");
+/** 链字段之外的规范化事件载荷（hash 计算输入） */
+function canonical(event) {
+	return JSON.stringify({
+		id: event.id,
+		ts: event.ts,
+		type: event.type,
+		target: event.target,
+		actor: event.actor,
+		data: event.data,
+		prevHash: event.prevHash
+	});
+}
+/** JSONL 追加的审计日志：<managedRoot>/.webskill/audit.jsonl；跨实例可恢复查询；prevHash 链可校验完整性 */
 var FsAuditLog = class {
 	#root;
 	#fs;
@@ -342,16 +416,26 @@ var FsAuditLog = class {
 		this.#createId = deps.createId;
 	}
 	async append(event) {
+		const path = fileOf$1(this.#root);
+		const existing = await this.#fs.exists(path) ? await this.#fs.readText(path) : "";
+		const lines = existing.split("\n").filter((l) => l.trim() !== "");
+		let prevHash = "GENESIS";
+		if (lines.length > 0) try {
+			const last = JSON.parse(lines.at(-1));
+			prevHash = last.hash ?? sha256Hex(canonical(last));
+		} catch {
+			prevHash = "GENESIS";
+		}
 		const full = {
 			id: event.id ?? this.#createId?.() ?? `audit-${Math.random().toString(36).slice(2, 10)}`,
 			ts: event.ts ?? this.#now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
 			type: event.type,
 			target: event.target,
 			...event.actor !== void 0 ? { actor: event.actor } : {},
-			...event.data !== void 0 ? { data: event.data } : {}
+			...event.data !== void 0 ? { data: event.data } : {},
+			prevHash
 		};
-		const path = fileOf$1(this.#root);
-		const existing = await this.#fs.exists(path) ? await this.#fs.readText(path) : "";
+		full.hash = sha256Hex(canonical(full));
 		const prefix = existing === "" || existing.endsWith("\n") ? existing : `${existing}\n`;
 		await this.#fs.writeText(path, `${prefix}${JSON.stringify(full)}\n`);
 		return full;
@@ -371,6 +455,38 @@ var FsAuditLog = class {
 		}
 		return events;
 	}
+	/** hash 链完整性校验：逐行重算 hash 并核对 prevHash 链接 */
+	async verifyChain() {
+		const path = fileOf$1(this.#root);
+		if (!await this.#fs.exists(path)) return { ok: true };
+		const lines = (await this.#fs.readText(path)).split("\n").filter((l) => l.trim() !== "");
+		let expectedPrev = "GENESIS";
+		for (let i = 0; i < lines.length; i++) {
+			let event;
+			try {
+				event = JSON.parse(lines[i]);
+			} catch {
+				return {
+					ok: false,
+					brokenAt: i,
+					reason: "line is not valid JSON"
+				};
+			}
+			if (event.prevHash !== expectedPrev) return {
+				ok: false,
+				brokenAt: i,
+				reason: "prevHash link mismatch (events may have been removed or reordered)"
+			};
+			const expectedHash = sha256Hex(canonical(event));
+			if (event.hash !== expectedHash) return {
+				ok: false,
+				brokenAt: i,
+				reason: "event hash mismatch (event content was tampered)"
+			};
+			expectedPrev = event.hash;
+		}
+		return { ok: true };
+	}
 };
 const dirOf = (root, skillName) => {
 	assertSafePathSegment(skillName, "skill name");
@@ -400,9 +516,20 @@ var SkillVersionStore = class {
 			manifest: input.manifest
 		};
 		assertSafePathSegment(version.versionId, "version id");
+		if (input.archive) {
+			const archivePath = `${dirOf(this.#root, skillName)}/${version.versionId}.zip`;
+			await this.#fs.writeBinary(archivePath, input.archive);
+			version.archivePath = archivePath;
+		}
 		await this.#fs.writeText(`${dirOf(this.#root, skillName)}/${version.versionId}.json`, JSON.stringify(version, null, 2));
 		return version;
 	}
+	/** 读取版本归档字节（applyRollback 用；未捕获归档的旧版本 → GOVERNANCE_FAILED） */
+	async readArchive(skillName, versionId) {
+		const version = await this.get(skillName, versionId);
+		if (!version.archivePath || !await this.#fs.exists(version.archivePath)) throw new WebSkillError("GOVERNANCE_FAILED", `Version "${versionId}" of skill "${skillName}" has no captured archive (recorded before archive capture existed)`);
+		return this.#fs.readBinary(version.archivePath);
+	}
 	async list(skillName) {
 		const dir = dirOf(this.#root, skillName);
 		if (!await this.#fs.exists(dir)) return [];
@@ -484,7 +611,7 @@ var FailureAnalyzer = class {
 };
 /**
 * 修订选项规划：patch（按诊断给具体文件变更）/ rollback（有旧版本时）/ quarantine。
-* 注意：任何 option 的 apply 都必须经 ApprovalWorkflow 审批后执行。
+* 注意：任何 option 的 apply 都必须经 ApprovalWorkflow 审批后执行；rollback 选项（targetVersionId）经 ApprovalWorkflow.applyRollback 真实恢复文件。
 */
 var RepairPlanner = class {
 	plan(input) {
@@ -522,6 +649,8 @@ var SkillStatePolicy = class {
 	#audit;
 	#failureThreshold;
 	#loaded;
+	/** 缓存文件 mtime（states.json 外部变更时按 mtime 重载） */
+	#loadedMtimeMs;
 	constructor(deps) {
 		this.#root = deps.root.replace(/\/+$/, "");
 		this.#fs = deps.fs;
@@ -529,17 +658,33 @@ var SkillStatePolicy = class {
 		this.#failureThreshold = deps.failureThreshold ?? 3;
 	}
 	async #load() {
-		if (this.#loaded) return this.#loaded;
 		const path = fileOf(this.#root);
+		if (this.#loaded) try {
+			const stat = await this.#fs.stat(path);
+			if (stat.mtimeMs !== void 0 && stat.mtimeMs === this.#loadedMtimeMs) return this.#loaded;
+		} catch {
+			return this.#loaded;
+		}
 		this.#loaded = await this.#fs.exists(path) ? JSON.parse(await this.#fs.readText(path)) : {
 			states: {},
 			failures: {}
 		};
+		try {
+			this.#loadedMtimeMs = (await this.#fs.stat(path)).mtimeMs;
+		} catch {
+			this.#loadedMtimeMs = void 0;
+		}
 		return this.#loaded;
 	}
 	async #persist() {
 		const data = await this.#load();
-		await this.#fs.writeText(fileOf(this.#root), JSON.stringify(data, null, 2));
+		const path = fileOf(this.#root);
+		await this.#fs.writeText(path, JSON.stringify(data, null, 2));
+		try {
+			this.#loadedMtimeMs = (await this.#fs.stat(path)).mtimeMs;
+		} catch {
+			this.#loadedMtimeMs = void 0;
+		}
 	}
 	async getState(skillName) {
 		assertSafePathSegment(skillName, "skill name");
@@ -590,6 +735,21 @@ var SkillStatePolicy = class {
 	canExecute(state) {
 		return state === "active" || state === "deprecated";
 	}
+	/**
+	* runtime SkillStateGuard 适配（0.1.5 一致拦截）：
+	* canRead：active/deprecated 放行；canActivate/canExecute 与 canRoute/canExecute 语义对齐；
+	* quarantined/disabled 三入口全拦截。
+	*/
+	toSkillStateGuard() {
+		return {
+			canRead: async (skillName) => {
+				const state = await this.getState(skillName);
+				return state === "active" || state === "deprecated";
+			},
+			canActivate: async (skillName) => this.canRoute(await this.getState(skillName)),
+			canExecute: async (skillName) => this.canExecute(await this.getState(skillName))
+		};
+	}
 	/** disabled → SKILL_DISABLED；quarantined → SKILL_QUARANTINED */
 	async assertExecutable(skillName) {
 		const state = await this.getState(skillName);