@webskill/sdk 0.0.1

package/dist/governance.js

@@ -0,0 +1,844 @@
+import { H as isValidSkillName, J as resolveInsideRoot, R as WebSkillError, Y as validateSkills } from "./dist-B_ldNWwT.js";
+import { i as NodeFS } from "./dist-9fczg9Pa.js";
+import path from "node:path";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+
+//#region ../governance/dist/index.js
+const invalid = (message, details) => {
+	throw new WebSkillError("CANDIDATE_INVALID", message, details);
+};
+/** 剥 markdown fence 与 <think> 块、截取首尾 {}；非对象 → CANDIDATE_INVALID */
+function parseJsonObject(raw) {
+	const fenced = raw.replace(/<think>[\s\S]*?<\/think>/gi, "").replace(/```(?:json)?/gi, "");
+	const start = fenced.indexOf("{");
+	const end = fenced.lastIndexOf("}");
+	if (start < 0 || end <= start) invalid("LLM output does not contain a JSON object");
+	let parsed;
+	try {
+		parsed = JSON.parse(fenced.slice(start, end + 1));
+	} catch (e) {
+		invalid("LLM output is not valid JSON", e);
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) invalid("LLM output JSON is not an object");
+	return parsed;
+}
+/** 小写连字符化、≤64、过 isValidSkillName */
+function sanitizeCandidateName(raw) {
+	const name = raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-").slice(0, 64);
+	if (!isValidSkillName(name)) invalid(`Candidate name ${JSON.stringify(raw)} cannot be normalized to a valid skill name`);
+	return name;
+}
+const kindOf = (path) => {
+	if (path === "SKILL.md") return "skill-md";
+	if (path.startsWith("scripts/")) return "script";
+	if (path.startsWith("references/")) return "reference";
+	return "asset";
+};
+/**
+* 文件归一：补 SKILL.md；路径含 `..` / 以 `/` 开头 / 含 `\` → CANDIDATE_INVALID；
+* scripts/ 下必须是 .ts/.js。
+*/
+function normalizeCandidateFiles(files, name, description) {
+	const out = [];
+	for (const file of files) {
+		const p = file.path;
+		if (typeof p !== "string" || p === "" || p.includes("..") || p.startsWith("/") || p.includes("\\")) invalid(`Candidate file path is not allowed: ${JSON.stringify(p)}`);
+		const kind = kindOf(p);
+		if (kind === "script" && !/\.(ts|js)$/.test(p)) invalid(`Candidate script must be .ts or .js: ${p}`);
+		out.push({
+			path: p,
+			kind,
+			content: String(file.content ?? "")
+		});
+	}
+	if (!out.some((f) => f.kind === "skill-md")) out.unshift({
+		path: "SKILL.md",
+		kind: "skill-md",
+		content: `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n`
+	});
+	return out;
+}
+/** 含脚本且 LLM 自报 low → 强制 medium 并追加"必须人工审批"原因 */
+function normalizeRisk(declared, files, reasons) {
+	const hasScript = files.some((f) => f.kind === "script");
+	const risk = declared === "low" || declared === "medium" || declared === "high" ? hasScript && declared === "low" ? "medium" : declared : hasScript ? "medium" : "low";
+	const out = [...reasons];
+	if (hasScript && declared === "low") out.push("Candidate contains scripts: risk forced to medium, human approval is required");
+	else if (hasScript && declared !== "low") out.push("Candidate contains executable scripts");
+	return {
+		risk,
+		reasons: out
+	};
+}
+/** 不信任归一化管线全链路；状态恒为 draft */
+function normalizeCandidate(input) {
+	const { raw } = input;
+	const description = typeof raw["description"] === "string" ? raw["description"] : "";
+	if (description.trim() === "") invalid("Candidate is missing a description");
+	const name = sanitizeCandidateName(typeof raw["name"] === "string" ? raw["name"] : invalid("Candidate is missing a name"));
+	const files = normalizeCandidateFiles((Array.isArray(raw["files"]) ? raw["files"] : []).map((f) => ({
+		path: String(f?.["path"] ?? ""),
+		content: String(f?.["content"] ?? "")
+	})), name, description);
+	const declaredReasons = Array.isArray(raw["riskReasons"]) ? raw["riskReasons"].map(String) : [];
+	const { risk, reasons } = normalizeRisk(raw["risk"], files, declaredReasons);
+	const now = input.now?.() ?? (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		id: input.createId?.() ?? `cand-${Math.random().toString(36).slice(2, 10)}`,
+		name,
+		description,
+		status: "draft",
+		source: input.source,
+		risk,
+		riskReasons: reasons,
+		files,
+		...Array.isArray(raw["suggestedTests"]) ? { suggestedTests: raw["suggestedTests"].map(String) } : {},
+		createdAt: now,
+		updatedAt: now
+	};
+}
+/** 候选校验：缺 SKILL.md / 非法扩展名 → CANDIDATE_INVALID */
+function validateCandidate(candidate) {
+	if (!candidate.files.some((f) => f.kind === "skill-md")) throw new WebSkillError("CANDIDATE_INVALID", `Candidate "${candidate.name}" is missing SKILL.md`);
+	for (const file of candidate.files) if (file.kind === "script" && !/\.(ts|js)$/.test(file.path)) throw new WebSkillError("CANDIDATE_INVALID", `Candidate "${candidate.name}" has an unsupported script file: ${file.path}`);
+}
+const dirOf$1 = (root) => `${root}/.webskill/candidates`;
+/** 逐文件持久化的候选存储：<managedRoot>/.webskill/candidates/<id>.json */
+var CandidateStore = class {
+	#root;
+	#fs;
+	constructor(deps) {
+		this.#root = deps.root.replace(/\/+$/, "");
+		this.#fs = deps.fs;
+	}
+	async save(candidate) {
+		validateCandidate(candidate);
+		await this.#fs.writeText(`${dirOf$1(this.#root)}/${candidate.id}.json`, JSON.stringify(candidate, null, 2));
+	}
+	async get(id) {
+		const path = `${dirOf$1(this.#root)}/${id}.json`;
+		if (!await this.#fs.exists(path)) throw new WebSkillError("GOVERNANCE_FAILED", `Candidate not found: ${id}`);
+		return JSON.parse(await this.#fs.readText(path));
+	}
+	async list() {
+		const dir = dirOf$1(this.#root);
+		if (!await this.#fs.exists(dir)) return [];
+		const out = [];
+		for (const entry of await this.#fs.list(dir)) {
+			if (entry.type !== "file" || !entry.path.endsWith(".json")) continue;
+			out.push(JSON.parse(await this.#fs.readText(entry.path)));
+		}
+		return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+	}
+	async updateStatus(id, status, now) {
+		const candidate = await this.get(id);
+		candidate.status = status;
+		candidate.updatedAt = now ?? (/* @__PURE__ */ new Date()).toISOString();
+		await this.save(candidate);
+		return candidate;
+	}
+};
+/** 硬门禁：仅 published 可转换为 Catalog 条目，否则 APPROVAL_REQUIRED */
+function candidateToCatalogEntry(candidate) {
+	if (candidate.status !== "published") throw new WebSkillError("APPROVAL_REQUIRED", `Candidate "${candidate.name}" is not published (status: ${candidate.status})`);
+	return {
+		name: candidate.name,
+		description: candidate.description,
+		root: `candidate://${candidate.id}`,
+		source: "generated",
+		hasScripts: candidate.files.some((f) => f.kind === "script"),
+		hasReferences: candidate.files.some((f) => f.kind === "reference"),
+		hasAssets: candidate.files.some((f) => f.kind === "asset")
+	};
+}
+/**
+* 文本补全：优先走流式（慢速本地模型下非流式整响应缓冲会触发 fetch 头超时，
+* SSE 首包秒到不受此限）；无 stream 的客户端回退 complete。
+*/
+async function completeText(llm, messages) {
+	if (llm.stream) {
+		let content = "";
+		let doneContent;
+		for await (const event of llm.stream({ messages })) if (event.type === "text-delta") content += event.delta;
+		else if (event.type === "done") doneContent = event.content;
+		return doneContent ?? content;
+	}
+	return (await llm.complete({ messages })).content ?? "";
+}
+const GENERATION_PROMPT = (task, context) => [
+	"You generate a skill candidate as STRICT JSON only (no markdown, no explanation).",
+	"Schema: {\"name\": string, \"description\": string, \"risk\": \"low\"|\"medium\"|\"high\",",
+	" \"riskReasons\": string[], \"files\": [{\"path\": string, \"content\": string}], \"suggestedTests\": string[]}",
+	"Rules:",
+	"- The candidate is ALWAYS a draft. Do NOT claim approved or published status.",
+	"- \"name\" must be lowercase letters/digits/hyphens.",
+	"- Include a SKILL.md file with YAML frontmatter (name, description) and a Markdown body.",
+	"- Script files must live under scripts/ and end with .ts or .js.",
+	"- Keep the candidate MINIMAL: at most 2 files, each under 60 lines. Short contents only.",
+	context ? `- Context: ${context}` : "",
+	`Task: ${task}`
+].filter(Boolean).join("\n");
+/** LLM 候选生成器：prompt 强制约束 + 不信任归一化管线 + candidate.created 审计 */
+var LlmCandidateGenerator = class {
+	#llm;
+	#audit;
+	#now;
+	#createId;
+	constructor(deps) {
+		this.#llm = deps.llm;
+		this.#audit = deps.audit;
+		this.#now = deps.now;
+		this.#createId = deps.createId;
+	}
+	async generate(input) {
+		const candidate = normalizeCandidate({
+			raw: parseJsonObject(await completeText(this.#llm, [{
+				role: "user",
+				content: GENERATION_PROMPT(input.prompt, input.context)
+			}])),
+			source: input.source,
+			...this.#now ? { now: this.#now } : {},
+			...this.#createId ? { createId: this.#createId } : {}
+		});
+		await this.#audit?.append({
+			type: "candidate.created",
+			target: candidate.id,
+			data: {
+				name: candidate.name,
+				source: candidate.source,
+				risk: candidate.risk
+			}
+		});
+		return candidate;
+	}
+};
+/** 默认策略：任何候选都必须人工审批 */
+var AlwaysHumanApprovalPolicy = class {
+	evaluate(candidate) {
+		return {
+			needsHuman: true,
+			reason: `Candidate "${candidate.name}" requires human approval (risk: ${candidate.risk})`
+		};
+	}
+};
+/** 规则组合策略：首个命中的规则胜出，全部未命中走 fallback（默认 AlwaysHuman） */
+var CompositeApprovalPolicy = class {
+	#rules;
+	#fallback;
+	constructor(rules, fallback) {
+		this.#rules = rules;
+		this.#fallback = fallback ?? new AlwaysHumanApprovalPolicy();
+	}
+	evaluate(candidate) {
+		for (const rule of this.#rules) {
+			const decision = rule(candidate);
+			if (decision) return decision;
+		}
+		return this.#fallback.evaluate(candidate);
+	}
+};
+const messageOf$1 = (e) => e instanceof Error ? e.message : String(e);
+/** 审批工作流：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
+			});
+			await this.#versions.add(candidate.name, {
+				reason: `Publish candidate ${candidateId}`,
+				manifest
+			});
+			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$1(e)}`, e);
+		}
+	}
+};
+const fileOf$1 = (root) => `${root}/.webskill/audit.jsonl`;
+/** JSONL 追加的审计日志：<managedRoot>/.webskill/audit.jsonl；跨实例可恢复查询 */
+var FsAuditLog = class {
+	#root;
+	#fs;
+	#now;
+	#createId;
+	constructor(deps) {
+		this.#root = deps.root.replace(/\/+$/, "");
+		this.#fs = deps.fs;
+		this.#now = deps.now;
+		this.#createId = deps.createId;
+	}
+	async append(event) {
+		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 } : {}
+		};
+		const path = fileOf$1(this.#root);
+		const existing = await this.#fs.exists(path) ? await this.#fs.readText(path) : "";
+		const prefix = existing === "" || existing.endsWith("\n") ? existing : `${existing}\n`;
+		await this.#fs.writeText(path, `${prefix}${JSON.stringify(full)}\n`);
+		return full;
+	}
+	async query(filter) {
+		const path = fileOf$1(this.#root);
+		if (!await this.#fs.exists(path)) return [];
+		const raw = await this.#fs.readText(path);
+		const events = [];
+		for (const line of raw.split("\n")) {
+			if (line.trim() === "") continue;
+			const event = JSON.parse(line);
+			if (filter.target !== void 0 && event.target !== filter.target) continue;
+			if (filter.type !== void 0 && event.type !== filter.type) continue;
+			if (filter.since !== void 0 && event.ts < filter.since) continue;
+			events.push(event);
+		}
+		return events;
+	}
+};
+const dirOf = (root, skillName) => `${root}/.webskill/versions/${skillName}`;
+/** 版本存储：manifest 快照 + parentVersionId 链；回滚 = 追加新版本（谱系不断） */
+var SkillVersionStore = class {
+	#root;
+	#fs;
+	#now;
+	#createId;
+	#audit;
+	constructor(deps) {
+		this.#root = deps.root.replace(/\/+$/, "");
+		this.#fs = deps.fs;
+		this.#now = deps.now;
+		this.#createId = deps.createId;
+		this.#audit = deps.audit;
+	}
+	async add(skillName, input) {
+		const existing = await this.list(skillName);
+		const version = {
+			versionId: this.#createId?.() ?? `v-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+			parentVersionId: input.parentVersionId ?? existing.at(-1)?.versionId,
+			createdAt: this.#now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
+			reason: input.reason,
+			manifest: input.manifest
+		};
+		await this.#fs.writeText(`${dirOf(this.#root, skillName)}/${version.versionId}.json`, JSON.stringify(version, null, 2));
+		return version;
+	}
+	async list(skillName) {
+		const dir = dirOf(this.#root, skillName);
+		if (!await this.#fs.exists(dir)) return [];
+		const out = [];
+		for (const entry of await this.#fs.list(dir)) {
+			if (entry.type !== "file" || !entry.path.endsWith(".json")) continue;
+			out.push(JSON.parse(await this.#fs.readText(entry.path)));
+		}
+		return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+	}
+	async get(skillName, versionId) {
+		const path = `${dirOf(this.#root, skillName)}/${versionId}.json`;
+		if (!await this.#fs.exists(path)) throw new WebSkillError("GOVERNANCE_FAILED", `Version "${versionId}" of skill "${skillName}" not found`);
+		return JSON.parse(await this.#fs.readText(path));
+	}
+	/** 回滚：基于旧 manifest 追加新版本 + skill.rolled_back 审计 */
+	async rollback(skillName, targetVersionId, input) {
+		const target = await this.get(skillName, targetVersionId);
+		const auditEvent = await this.#audit?.append({
+			type: "skill.rolled_back",
+			target: skillName,
+			...input.actor !== void 0 ? { actor: input.actor } : {},
+			data: { targetVersionId }
+		});
+		return this.add(skillName, {
+			reason: input.reason ?? `Rollback to ${targetVersionId}`,
+			manifest: target.manifest,
+			...auditEvent ? { auditEventId: auditEvent.id } : {}
+		});
+	}
+};
+const ERROR_CAUSES = {
+	TOOL_NOT_FOUND: "The skill script or tool is missing",
+	TOOL_EXECUTION_FAILED: "The script failed at runtime",
+	TOOL_UNSUPPORTED: "A required capability or format is unsupported",
+	RUN_TIMEOUT: "The script or loop timed out",
+	FS_NOT_FOUND: "A required file is missing",
+	FS_PATH_OUTSIDE_ROOT: "The script attempted an out-of-root path access",
+	LLM_REQUEST_FAILED: "The LLM endpoint failed",
+	SKILL_INVALID_METADATA: "The skill metadata is invalid"
+};
+/** 失败诊断：trace 摘要 → LLM 诊断（JSON）；无 LLM 时规则版（错误码归类） */
+var FailureAnalyzer = class {
+	#llm;
+	constructor(deps) {
+		this.#llm = deps?.llm;
+	}
+	async analyze(input) {
+		const { run } = input;
+		const failed = run.trace.filter((e) => e.type === "tool.failed" || e.type === "run.failed");
+		const firstCode = failed.map((e) => e.data?.["code"]).find((c) => typeof c === "string");
+		if (this.#llm) {
+			const summary = failed.slice(0, 10).map((e) => `${e.type}: ${e.message ?? ""} ${JSON.stringify(e.data ?? {})}`).join("\n");
+			const response = await this.#llm.complete({ messages: [{
+				role: "user",
+				content: [
+					"Diagnose this failed agent run as STRICT JSON only:",
+					"{\"cause\": string, \"suggestedFix\": string, \"errorCode\"?: string}",
+					`Run termination: ${run.terminationReason ?? "unknown"}`,
+					`Failures:\n${summary || "(none recorded)"}`
+				].join("\n")
+			}] });
+			try {
+				const parsed = parseJsonObject(response.content ?? "");
+				return {
+					cause: String(parsed["cause"] ?? "Unknown cause"),
+					suggestedFix: String(parsed["suggestedFix"] ?? "Manual inspection required"),
+					...typeof parsed["errorCode"] === "string" ? { errorCode: parsed["errorCode"] } : firstCode ? { errorCode: firstCode } : {}
+				};
+			} catch {}
+		}
+		return {
+			cause: firstCode ? ERROR_CAUSES[firstCode] ?? `Failure with code ${firstCode}` : "Unknown failure (no error code in trace)",
+			suggestedFix: firstCode ? `Inspect the component responsible for ${firstCode}` : "Inspect the run trace manually",
+			...firstCode ? { errorCode: firstCode } : {}
+		};
+	}
+};
+/**
+* 修订选项规划：patch（按诊断给具体文件变更）/ rollback（有旧版本时）/ quarantine。
+* 注意：任何 option 的 apply 都必须经 ApprovalWorkflow 审批后执行。
+*/
+var RepairPlanner = class {
+	plan(input) {
+		const { diagnosis, skillName, versions } = input;
+		const options = [{
+			kind: "patch",
+			description: `Patch "${skillName}": ${diagnosis.suggestedFix}`,
+			patch: [{
+				path: "SKILL.md",
+				content: `<!-- repair patch for: ${diagnosis.cause} -->\n<!-- ${diagnosis.suggestedFix} -->\n`
+			}]
+		}];
+		const previous = versions.at(-2) ?? versions.at(-1);
+		if (previous) options.push({
+			kind: "rollback",
+			description: `Rollback "${skillName}" to version ${previous.versionId}`,
+			targetVersionId: previous.versionId
+		});
+		options.push({
+			kind: "quarantine",
+			description: `Quarantine "${skillName}" until it is repaired (cause: ${diagnosis.cause})`
+		});
+		return options;
+	}
+};
+const fileOf = (root) => `${root}/.webskill/states.json`;
+/**
+* 降级治理：states.json 持久化；失败达阈值 → quarantined；
+* canRoute 仅 active；canExecute active|deprecated；disabled 执行抛 SKILL_DISABLED；
+* 卸载/状态变更经 UiBridge confirm 审批。
+*/
+var SkillStatePolicy = class {
+	#root;
+	#fs;
+	#audit;
+	#failureThreshold;
+	#loaded;
+	constructor(deps) {
+		this.#root = deps.root.replace(/\/+$/, "");
+		this.#fs = deps.fs;
+		this.#audit = deps.audit;
+		this.#failureThreshold = deps.failureThreshold ?? 3;
+	}
+	async #load() {
+		if (this.#loaded) return this.#loaded;
+		const path = fileOf(this.#root);
+		this.#loaded = await this.#fs.exists(path) ? JSON.parse(await this.#fs.readText(path)) : {
+			states: {},
+			failures: {}
+		};
+		return this.#loaded;
+	}
+	async #persist() {
+		const data = await this.#load();
+		await this.#fs.writeText(fileOf(this.#root), JSON.stringify(data, null, 2));
+	}
+	async getState(skillName) {
+		return (await this.#load()).states[skillName] ?? "active";
+	}
+	async listStates() {
+		return { ...(await this.#load()).states };
+	}
+	async setState(skillName, state, input) {
+		const data = await this.#load();
+		data.states[skillName] = state;
+		if (state === "active") delete data.failures[skillName];
+		await this.#persist();
+		await this.#audit?.append({
+			type: `skill.${state === "active" ? "reactivated" : state === "quarantined" ? "quarantined" : state === "deprecated" ? "deprecated" : "disabled"}`,
+			target: skillName,
+			...input.actor !== void 0 ? { actor: input.actor } : {},
+			...input.reason !== void 0 ? { data: { reason: input.reason } } : {}
+		});
+	}
+	/** 失败计数；达阈值（默认 3）→ quarantined + 审计 */
+	async recordFailure(skillName, input = {}) {
+		const data = await this.#load();
+		const count = (data.failures[skillName] ?? 0) + 1;
+		data.failures[skillName] = count;
+		let state = data.states[skillName] ?? "active";
+		if (count >= this.#failureThreshold && state === "active") {
+			state = "quarantined";
+			data.states[skillName] = "quarantined";
+			await this.#audit?.append({
+				type: "skill.quarantined",
+				target: skillName,
+				...input.actor !== void 0 ? { actor: input.actor } : {},
+				data: {
+					failures: count,
+					threshold: this.#failureThreshold
+				}
+			});
+		}
+		await this.#persist();
+		return state;
+	}
+	canRoute(state) {
+		return state === "active";
+	}
+	canExecute(state) {
+		return state === "active" || state === "deprecated";
+	}
+	/** disabled → SKILL_DISABLED；quarantined → SKILL_QUARANTINED */
+	async assertExecutable(skillName) {
+		const state = await this.getState(skillName);
+		if (state === "disabled") throw new WebSkillError("SKILL_DISABLED", `Skill "${skillName}" is disabled`);
+		if (state === "quarantined") throw new WebSkillError("SKILL_QUARANTINED", `Skill "${skillName}" is quarantined`);
+	}
+	/** runtime catalogFilter 实现：quarantined/deprecated/disabled 技能被路由过滤 */
+	catalogFilter() {
+		return async (entries) => {
+			const out = [];
+			for (const entry of entries) if (this.canRoute(await this.getState(entry.name))) out.push(entry);
+			return out;
+		};
+	}
+	/** 卸载需显式审批（UiBridge confirm 真实接线）；拒绝 → APPROVAL_REQUIRED */
+	async uninstall(skillName, input) {
+		const response = await input.uiBridge.request({
+			type: "confirm",
+			id: `uninstall-${skillName}`,
+			message: `Uninstall skill "${skillName}"? This removes it from the managed root.`,
+			defaultValue: false
+		});
+		if (response.cancelled === true || response.value !== true) throw new WebSkillError("APPROVAL_REQUIRED", `Uninstall of skill "${skillName}" was rejected by ${input.actor}`);
+		await input.skillManager.uninstall(skillName);
+		const data = await this.#load();
+		delete data.states[skillName];
+		delete data.failures[skillName];
+		await this.#persist();
+		await this.#audit?.append({
+			type: "skill.uninstalled",
+			target: skillName,
+			actor: input.actor
+		});
+	}
+};
+const messageOf = (e) => e instanceof Error ? e.message : String(e);
+function matchExpected(expected, output, run) {
+	if (expected === void 0) return run.status === "completed";
+	if (typeof expected === "string") return output.includes(expected);
+	return expected(output, run);
+}
+/** 批量评估：顺序执行（单任务异常不中断批）；expected 参与判定；结构化报告 */
+var EvaluationRunner = class {
+	#runtime;
+	#now;
+	#createId;
+	constructor(deps) {
+		this.#runtime = deps.runtime;
+		this.#now = deps.now;
+		this.#createId = deps.createId;
+	}
+	async run(tasks) {
+		const results = [];
+		for (const task of tasks) try {
+			const { output, run } = await this.#runtime.run(task.prompt);
+			const ok = matchExpected(task.expected, output, run);
+			results.push({
+				taskId: task.id,
+				ok,
+				score: ok ? 1 : 0,
+				output
+			});
+		} catch (e) {
+			results.push({
+				taskId: task.id,
+				ok: false,
+				score: 0,
+				error: messageOf(e)
+			});
+		}
+		const passed = results.filter((r) => r.ok).length;
+		const scores = results.map((r) => r.score);
+		return {
+			id: this.#createId?.() ?? `eval-${Math.random().toString(36).slice(2, 10)}`,
+			generatedAt: this.#now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
+			results,
+			summary: {
+				total: results.length,
+				passed,
+				failed: results.length - passed,
+				averageScore: scores.length ? scores.reduce((a, b) => a + b, 0) / scores.length : void 0
+			}
+		};
+	}
+};
+/** 失败 trace → 回归评估任务建议（prompt 复现 + expected 错误模式） */
+function suggestFromFailedRun(run) {
+	const errorPatterns = run.trace.filter((e) => e.type === "tool.failed" || e.type === "run.failed").map((e) => String(e.data?.["code"] ?? e.message ?? "")).filter(Boolean);
+	return {
+		id: `regression-${run.id}`,
+		prompt: run.userPrompt,
+		expected: (output, rerun) => rerun.status === "completed" && !rerun.trace.some((e) => (e.type === "tool.failed" || e.type === "run.failed") && errorPatterns.includes(String(e.data?.["code"] ?? ""))),
+		metadata: {
+			source: "test-suggestion",
+			failureReason: run.terminationReason ?? "unknown",
+			errorPatterns
+		}
+	};
+}
+const SCORING_WEIGHTS = {
+	success: .5,
+	usage: .2,
+	eval: .2,
+	risk: .1
+};
+const RISK_SCORE = {
+	low: 0,
+	medium: .5,
+	high: 1
+};
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+/**
+* 综合评分：successRate*W_SUCCESS + usageNorm*W_USAGE + evalScore*W_EVAL − risk*W_RISK
+* （clamp [0,1]）；低于阈值给 improve 建议。usage 数据来自 skill:{name} memory scope。
+*/
+var SkillScorer = class {
+	#weights;
+	#improveThreshold;
+	constructor(weights = SCORING_WEIGHTS, improveThreshold = .5) {
+		this.#weights = weights;
+		this.#improveThreshold = improveThreshold;
+	}
+	score(input) {
+		const usageNorm = clamp01(input.usageCount / (input.usageBaseline ?? 100));
+		const value = clamp01(input.successRate * this.#weights.success + usageNorm * this.#weights.usage + (input.evalScore ?? 0) * this.#weights.eval - RISK_SCORE[input.risk] * this.#weights.risk);
+		return {
+			value,
+			...value < this.#improveThreshold ? { suggestion: `Score ${value.toFixed(2)} is below ${this.#improveThreshold}: consider improving reliability (success rate ${(input.successRate * 100).toFixed(0)}%) or reducing risk` } : {}
+		};
+	}
+};
+const tokenize = (text) => new Set(text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1));
+function jaccardSimilarity(a, b) {
+	const sa = tokenize(a);
+	const sb = tokenize(b);
+	if (sa.size === 0 && sb.size === 0) return 1;
+	let intersection = 0;
+	for (const t of sa) if (sb.has(t)) intersection++;
+	return intersection / (sa.size + sb.size - intersection || 1);
+}
+/** 描述词集 Jaccard 查重 */
+var SimilarityDetector = class {
+	#threshold;
+	constructor(threshold = .8) {
+		this.#threshold = threshold;
+	}
+	/** 返回首个超过阈值的已有技能名；无重复返回 undefined */
+	findDuplicate(description, existing) {
+		for (const skill of existing) if (jaccardSimilarity(description, skill.description) >= this.#threshold) return skill.name;
+	}
+};
+/** 技能引用依赖图（references/ 中引用其他技能的声明关系） */
+var DependencyGraph = class {
+	#edges = /* @__PURE__ */ new Map();
+	addDependency(from, to) {
+		if (from === to) return;
+		const set = this.#edges.get(from) ?? /* @__PURE__ */ new Set();
+		set.add(to);
+		this.#edges.set(from, set);
+	}
+	dependenciesOf(name) {
+		return [...this.#edges.get(name) ?? []].sort();
+	}
+	dependentsOf(name) {
+		const out = [];
+		for (const [from, targets] of this.#edges) if (targets.has(name)) out.push(from);
+		return out.sort();
+	}
+};
+/** 读文档 + sha256 hash（变更检测用） */
+async function readDocument(fs, path) {
+	const content = await fs.readText(path);
+	return {
+		path,
+		content,
+		hash: createHash("sha256").update(content).digest("hex")
+	};
+}
+const EXTRACT_PROMPT = (doc, nameHint) => [
+	"Extract an executable skill from the following document as STRICT JSON only.",
+	"Schema: {\"name\": string, \"description\": string, \"risk\": \"low\"|\"medium\"|\"high\",",
+	" \"riskReasons\": string[], \"files\": [{\"path\": string, \"content\": string}]}",
+	"The candidate is ALWAYS a draft. Do NOT claim approved or published status.",
+	"Include a SKILL.md (frontmatter name/description + procedure steps as Markdown body).",
+	"Scripts (if any) go under scripts/ and must end with .ts or .js.",
+	nameHint ? `Prefer the name "${nameHint}" if appropriate.` : "",
+	"--- DOCUMENT ---",
+	doc.content.slice(0, 12e3)
+].filter(Boolean).join("\n");
+/** 文档 → LLM 抽取 → 完整防御管线 → draft 候选（source: document） */
+var DocumentSkillExtractor = class {
+	#llm;
+	#audit;
+	#now;
+	#createId;
+	constructor(deps) {
+		this.#llm = deps.llm;
+		this.#audit = deps.audit;
+		this.#now = deps.now;
+		this.#createId = deps.createId;
+	}
+	async extract(input) {
+		const candidate = normalizeCandidate({
+			raw: parseJsonObject(await completeText(this.#llm, [{
+				role: "user",
+				content: EXTRACT_PROMPT(input.document, input.nameHint)
+			}])),
+			source: "document",
+			...this.#now ? { now: this.#now } : {},
+			...this.#createId ? { createId: this.#createId } : {}
+		});
+		candidate.metadata = {
+			...candidate.metadata ?? {},
+			documentPath: input.document.path,
+			documentHash: input.document.hash
+		};
+		await this.#audit?.append({
+			type: "candidate.created",
+			target: candidate.id,
+			data: {
+				name: candidate.name,
+				source: "document",
+				documentPath: input.document.path,
+				documentHash: input.document.hash
+			}
+		});
+		return candidate;
+	}
+	/** hash 变化 → 生成新候选（关联原技能名，不覆盖已发布技能）；无变化返回 changed:false */
+	async checkUpdate(input) {
+		if (input.document.hash === input.previousHash) return { changed: false };
+		const candidate = await this.extract({
+			document: input.document,
+			...input.previousSkillName ? { nameHint: input.previousSkillName } : {}
+		});
+		candidate.metadata = {
+			...candidate.metadata ?? {},
+			updatesSkill: input.previousSkillName,
+			previousHash: input.previousHash
+		};
+		return {
+			changed: true,
+			candidate
+		};
+	}
+};
+/**
+* runtime-miss 现成适配（opt-in）：run 未激活技能时生成 draft 候选入库待审。
+* 返回的 hook 失败会向上抛（由 runtime 降级为 warning）。
+*/
+function createMissHook(deps) {
+	return async ({ prompt }) => {
+		const candidate = await deps.generator.generate({
+			prompt,
+			source: "runtime-miss"
+		});
+		await deps.store.save(candidate);
+	};
+}
+
+//#endregion
+export { AlwaysHumanApprovalPolicy, ApprovalWorkflow, CandidateStore, CompositeApprovalPolicy, DependencyGraph, DocumentSkillExtractor, EvaluationRunner, FailureAnalyzer, FsAuditLog, LlmCandidateGenerator, RepairPlanner, SCORING_WEIGHTS, SimilarityDetector, SkillScorer, SkillStatePolicy, SkillVersionStore, candidateToCatalogEntry, completeText, createMissHook, jaccardSimilarity, normalizeCandidate, normalizeCandidateFiles, normalizeRisk, parseJsonObject, readDocument, sanitizeCandidateName, suggestFromFailedRun, validateCandidate };