@webskill/sdk 0.21.0 → 0.23.0

package/dist/governance.d.ts

@@ -1,6 +1,6 @@
-import { S as UiBridge, U as FileSystemProvider, X as Page, Z as PageQuery, _t as SkillManagerPort, dt as SkillCatalogEntry, f as LlmMessage, l as LlmClient, pt as SkillDocument } from "./types-BvTV_05--BW8zDuEk.js";
-import { $ as IntegrityVerdict, ar as WebSkillRuntime, dn as SkillStateGuard, on as SkillIntegrityGuard, sn as SkillOutcomeReporter, zt as RuntimeRun } from "./index-DHopiH_m.js";
-import { _ as SkillState, a as AuditLog, b as SkillVersionStore, c as CandidateFile, d as CandidateSkill, f as CandidateSource, g as SKILL_VERSION_PAGE_SIZE, h as CompositeApprovalPolicy, i as AuditEvent, l as CandidatePage, m as CandidateStore, n as ApprovalDecision, o as AuditQueryFilter, p as CandidateStatus, r as ApprovalPolicy, s as CANDIDATE_PAGE_SIZE, t as AlwaysHumanApprovalPolicy, u as CandidateRisk, v as SkillVersion, x as candidateToCatalogEntry, y as SkillVersionPage } from "./skillVersionStore-B24Jjjry-BkOk9wI_.js";
+import { K as FileSystemProvider, S as UiBridge, _t as SkillDocument, et as Page, f as LlmMessage, ht as SkillCatalogEntry, l as LlmClient, tt as PageQuery, xt as SkillManagerPort } from "./types-CpDRZ0rA-BiZBXGm4.js";
+import { Wt as RuntimeRun, dn as SkillIntegrityGuard, fn as SkillOutcomeReporter, gn as SkillStateGuard, hr as WebSkillRuntime, tt as IntegrityVerdict } from "./index-7No55dRb.js";
+import { S as candidateToCatalogEntry, _ as SKILL_VERSION_PAGE_SIZE, a as AuditLog, b as SkillVersionPage, c as CandidateBinaryRef, d as CandidateRisk, f as CandidateSkill, g as CompositeApprovalPolicy, h as CandidateStore, i as AuditEvent, l as CandidateFile, m as CandidateStatus, n as ApprovalDecision, o as AuditQueryFilter, p as CandidateSource, r as ApprovalPolicy, s as CANDIDATE_PAGE_SIZE, t as AlwaysHumanApprovalPolicy, u as CandidatePage, v as SkillState, x as SkillVersionStore, y as SkillVersion } from "./skillVersionStore-S4_HJ_Fl-Cvy9LqVu.js";
 //#region ../governance/dist/index.d.ts
 //#region src/candidate/candidateNormalizer.d.ts
 /** 剥 markdown fence 与 <think> 块、截取首尾 {}；非对象 → CANDIDATE_INVALID */
@@ -10,10 +10,14 @@ declare function sanitizeCandidateName(raw: string): string;
 /**
  * 文件归一：补 SKILL.md；路径含 `..` / 以 `/` 开头 / 含 `\` → CANDIDATE_INVALID；
  * scripts/ 下必须是 .ts/.js。
+ *
+ * 路径校验对两种形态**一视同仁**（0.23.0 分册 20 FR-20.3）：这套校验本来就与内容无关，
+ * 二进制条目走另一套校验等于给越界路径开第二道门。
  */
 declare function normalizeCandidateFiles(files: Array<{
   path: string;
   content: string;
+  binary?: CandidateBinaryRef;
 }>, name: string, description: string): CandidateFile[];
 /** 含脚本且 LLM 自报 low → 强制 medium 并追加"必须人工审批"原因 */
 declare function normalizeRisk(declared: unknown, files: CandidateFile[], reasons: string[]): {
@@ -53,6 +57,20 @@ interface GeneratedSkillSubmission {
   sessionId?: string;
   /** 用户确认的时刻（FR-9.7 的「用户确认事实」） */
   confirmedAt: string;
+  /**
+   * 已物化的二进制，键是 `draft.files[].path`（0.23.0 分册 20）。
+   * 字节由 agent 侧在用户确认之前取好——候选一旦生成就必须能脱离会话附件独立存活（FR-20.6）。
+   */
+  binaries?: ReadonlyMap<string, SubmittedBinary>;
+}
+/** 一份随候选提交的字节及其校验信息（0.23.0 分册 20） */
+interface SubmittedBinary {
+  bytes: Uint8Array;
+  size: number;
+  /** 十六进制小写 */
+  sha256: string;
+  /** 上传时的原始文件名 */
+  sourceName: string;
 }
 interface CandidateSinkOptions {
   store: CandidateStore;
@@ -561,4 +579,4 @@ declare function createMissHook(deps: {
  */
 declare function completeText(llm: LlmClient, messages: LlmMessage[]): Promise<string>;
 //#endregion
-export { AUDIT_EVENT_TYPES, AUDIT_EVENT_TYPE_LIST, AUDIT_PAGE_SIZE, AlwaysHumanApprovalPolicy, type ApprovalDecision, type ApprovalPolicy, type AuditChainVerification, type AuditEvent, type AuditEventType, type AuditLog, type AuditPage, type AuditQueryFilter, CANDIDATE_PAGE_SIZE, type CandidateFile, type CandidatePage, type CandidateRisk, type CandidateSink, type CandidateSinkOptions, type CandidateSkill, type CandidateSource, type CandidateStatus, CandidateStore, CompositeApprovalPolicy, DependencyGraph, DocumentSkillExtractor, type EvaluationReport, type EvaluationResult, EvaluationRunner, type EvaluationTask, FailureAnalyzer, type FailureDiagnosis, FsAuditLog, type GeneratedSkillSubmission, LlmCandidateGenerator, POLICY_DENIAL_CODES, QUARANTINE_REASONS, type RepairOption, RepairPlanner, SCORING_WEIGHTS, SKILL_VERSION_PAGE_SIZE, type ScoreInput, SimilarityDetector, SkillScorer, type SkillState, SkillStatePolicy, type SkillVersion, type SkillVersionPage, SkillVersionStore, type SourceDocument, USER_CAUSED_CODES, candidateToCatalogEntry, completeText, createCandidateSink, createMissHook, jaccardSimilarity, normalizeCandidate, normalizeCandidateFiles, normalizeRisk, parseJsonObject, readDocument, sanitizeCandidateName, suggestFromFailedRun, validateCandidate };
+export { AUDIT_EVENT_TYPES, AUDIT_EVENT_TYPE_LIST, AUDIT_PAGE_SIZE, AlwaysHumanApprovalPolicy, type ApprovalDecision, type ApprovalPolicy, type AuditChainVerification, type AuditEvent, type AuditEventType, type AuditLog, type AuditPage, type AuditQueryFilter, CANDIDATE_PAGE_SIZE, type CandidateBinaryRef, type CandidateFile, type CandidatePage, type CandidateRisk, type CandidateSink, type CandidateSinkOptions, type CandidateSkill, type CandidateSource, type CandidateStatus, CandidateStore, CompositeApprovalPolicy, DependencyGraph, DocumentSkillExtractor, type EvaluationReport, type EvaluationResult, EvaluationRunner, type EvaluationTask, FailureAnalyzer, type FailureDiagnosis, FsAuditLog, type GeneratedSkillSubmission, LlmCandidateGenerator, POLICY_DENIAL_CODES, QUARANTINE_REASONS, type RepairOption, RepairPlanner, SCORING_WEIGHTS, SKILL_VERSION_PAGE_SIZE, type ScoreInput, SimilarityDetector, SkillScorer, type SkillState, SkillStatePolicy, type SkillVersion, type SkillVersionPage, SkillVersionStore, type SourceDocument, type SubmittedBinary, USER_CAUSED_CODES, candidateToCatalogEntry, completeText, createCandidateSink, createMissHook, jaccardSimilarity, normalizeCandidate, normalizeCandidateFiles, normalizeRisk, parseJsonObject, readDocument, sanitizeCandidateName, suggestFromFailedRun, validateCandidate };

package/dist/governance.js

@@ -1,6 +1,6 @@
 import { n as messageOf, t as WebSkillError } from "./errors-BDZNpC13.js";
-import { y as isValidSkillName } from "./skill-CAJMsLod.js";
-import { a as atomicWriteText, t as assertSafePathSegment } from "./pathSecurity-B1owvJAF.js";
+import { y as isValidSkillName } from "./skill-WSUDp6A1.js";
+import { a as atomicWriteBinary, o as atomicWriteText, t as assertSafePathSegment } from "./pathSecurity-CirkQwWP.js";
 import { d as partsToText, p as textParts } from "./llm-eIQNO9tr.js";
 import { n as AUDIT_EVENT_TYPE_LIST, t as AUDIT_EVENT_TYPES } from "./eventTypes-DcTQXSV1.js";
 
@@ -36,8 +36,32 @@ const kindOf = (path) => {
 	return "asset";
 };
 /**
+* 二进制引用的形状校验（0.23.0 分册 20）。
+*
+* 这条管线的既定前提是「不信任全链路」，所以引用也要逐字段查过才收下：
+* 一条字段缺失的引用会一路活到安装那一步，届时才表现为读不到字节的技能包。
+* `file` 必须是单个文件名——带路径分隔符的值等于一条越出候选旁路目录的通路。
+*/
+function readBinaryRef(raw) {
+	if (raw === void 0 || raw === null) return void 0;
+	if (typeof raw !== "object" || Array.isArray(raw)) return invalid("Candidate file \"binary\" must be an object");
+	const { file, size, sha256, sourceName } = raw;
+	if (typeof file !== "string" || file === "" || file.includes("/") || file.includes("\\") || file.includes("..")) return invalid(`Candidate binary file name is not allowed: ${JSON.stringify(file)}`);
+	if (typeof size !== "number" || !Number.isFinite(size) || size < 0) return invalid(`Candidate binary "${file}" has an invalid size`);
+	if (typeof sha256 !== "string" || !/^[0-9a-f]{64}$/.test(sha256)) return invalid(`Candidate binary "${file}" has an invalid sha256`);
+	return {
+		file,
+		size,
+		sha256,
+		sourceName: typeof sourceName === "string" ? sourceName : file
+	};
+}
+/**
 * 文件归一：补 SKILL.md；路径含 `..` / 以 `/` 开头 / 含 `\` → CANDIDATE_INVALID；
 * scripts/ 下必须是 .ts/.js。
+*
+* 路径校验对两种形态**一视同仁**（0.23.0 分册 20 FR-20.3）：这套校验本来就与内容无关，
+* 二进制条目走另一套校验等于给越界路径开第二道门。
 */
 function normalizeCandidateFiles(files, name, description) {
 	const out = [];
@@ -49,7 +73,8 @@ function normalizeCandidateFiles(files, name, description) {
 		out.push({
 			path: p,
 			kind,
-			content: String(file.content ?? "")
+			content: String(file.content ?? ""),
+			...file.binary !== void 0 ? { binary: file.binary } : {}
 		});
 	}
 	if (!out.some((f) => f.kind === "skill-md")) out.unshift({
@@ -77,10 +102,15 @@ function normalizeCandidate(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 files = normalizeCandidateFiles((Array.isArray(raw["files"]) ? raw["files"] : []).map((f) => {
+		const record = f ?? {};
+		const binary = readBinaryRef(record["binary"]);
+		return {
+			path: String(record["path"] ?? ""),
+			content: String(record["content"] ?? ""),
+			...binary !== void 0 ? { binary } : {}
+		};
+	}), 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();
@@ -137,6 +167,8 @@ function takeTailPage(all, options, defaultLimit, what) {
 //#endregion
 //#region ../governance/src/candidate/candidateStore.ts
 const dirOf$1 = (root) => `${root}/.webskill/candidates`;
+/** 候选的二进制旁路目录（0.23.0 分册 20 §3）：与元数据 JSON 同级，整目录随候选一起删 */
+const candidateBinaryDir = (root, id) => `${dirOf$1(root)}/${id}.files`;
 /** 候选列表的缺省页长。缺省属于实现，不属于调用方 */
 const CANDIDATE_PAGE_SIZE = 50;
 /** 逐文件持久化的候选存储：<managedRoot>/.webskill/candidates/<id>.json */
@@ -149,11 +181,37 @@ var CandidateStore = class {
 		this.#fs = deps.fs;
 		this.#isSkillInstalled = deps.isSkillInstalled;
 	}
-	async save(candidate) {
+	/**
+	* 存候选。`binaries` 的键是 `CandidateFile.binary.file`，缺省即本候选全是文本。
+	*
+	* 落盘顺序是**先字节、后 JSON**（0.23.0 分册 20 §3.2）：反过来的话，
+	* 崩溃会留下一条指向不存在字节的元数据，而那种候选要到审批安装那一步才暴露——
+	* 正是 FR-20.6 要避免的那类「延迟到审批才失败」。
+	*/
+	async save(candidate, binaries) {
 		validateCandidate(candidate);
 		assertSafePathSegment(candidate.id, "candidate id");
+		for (const file of candidate.files) {
+			if (file.binary === void 0) continue;
+			const bytes = binaries?.get(file.binary.file);
+			if (bytes === void 0) {
+				if (await this.#fs.exists(this.#binaryPath(candidate.id, file.binary.file))) continue;
+				throw new WebSkillError("CANDIDATE_INVALID", `Candidate "${candidate.name}" declares binary "${file.path}" but its bytes were not provided`);
+			}
+			assertSafePathSegment(file.binary.file, "candidate binary file");
+			await atomicWriteBinary(this.#fs, this.#binaryPath(candidate.id, file.binary.file), bytes);
+		}
 		await atomicWriteText(this.#fs, `${dirOf$1(this.#root)}/${candidate.id}.json`, JSON.stringify(candidate, null, 2));
 	}
+	/** 读回候选旁路里的一份字节（安装时按原样写进技能目录，0.23.0 分册 20 FR-20.8） */
+	readCandidateBinary(id, file) {
+		assertSafePathSegment(id, "candidate id");
+		assertSafePathSegment(file, "candidate binary file");
+		return this.#fs.readBinary(this.#binaryPath(id, file));
+	}
+	#binaryPath(id, file) {
+		return `${candidateBinaryDir(this.#root, id)}/${file}`;
+	}
 	async get(id) {
 		assertSafePathSegment(id, "candidate id");
 		const path = `${dirOf$1(this.#root)}/${id}.json`;
@@ -202,6 +260,8 @@ var CandidateStore = class {
 		if (candidate.status === "approved") throw new WebSkillError("GOVERNANCE_FAILED", `Candidate "${candidate.name}" cannot be removed from status "${candidate.status}"`);
 		if (candidate.status === "published" && await this.#skillStillInstalled(candidate.name)) throw new WebSkillError("GOVERNANCE_FAILED", `Candidate "${candidate.name}" is the provenance record of an installed skill and cannot be removed; uninstall the skill first`);
 		await this.#fs.remove(`${dirOf$1(this.#root)}/${id}.json`);
+		const binaryDir = candidateBinaryDir(this.#root, id);
+		if (await this.#fs.exists(binaryDir)) await this.#fs.remove(binaryDir, { recursive: true });
 	}
 	async #skillStillInstalled(name) {
 		return this.#isSkillInstalled === void 0 ? true : await this.#isSkillInstalled(name);
@@ -224,6 +284,16 @@ function candidateToCatalogEntry(candidate) {
 //#endregion
 //#region ../governance/src/candidate/candidateSink.ts
 /**
+* 旁路文件名：序号在前保证唯一，原名跟在后面是为了让人在文件管理器里也认得出
+* 哪个是哪个（0.23.0 分册 20 §3）。直接拿技能内路径当文件名不行——
+* 那是一个平铺目录，`references/a/t.xlsx` 与 `references/b/t.xlsx` 会撞在一起。
+* 权威的原名记在 `sourceName` 里，这里只保留能安全落盘的那部分。
+*/
+const binaryFileNameOf = (index, path) => {
+	const safe = (path.split("/").pop() ?? "").replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "");
+	return `${index}-${safe === "" ? "file" : safe}`;
+};
+/**
 * 把 agent 生成的技能草稿接进既有的候选管线（设计 02 §5）。
 *
 * 走的是与文档抽取、runtime-miss 完全相同的 `normalizeCandidate` → `CandidateStore.save`，
@@ -232,6 +302,26 @@ function candidateToCatalogEntry(candidate) {
 function createCandidateSink(options) {
 	return { async submit(input) {
 		const { draft } = input;
+		const bytes = /* @__PURE__ */ new Map();
+		const files = (draft.files ?? []).map((file, index) => {
+			const payload = input.binaries?.get(file.path);
+			if (payload === void 0) return {
+				path: file.path,
+				content: file.content
+			};
+			const name = binaryFileNameOf(index, file.path);
+			bytes.set(name, payload.bytes);
+			return {
+				path: file.path,
+				content: "",
+				binary: {
+					file: name,
+					size: payload.size,
+					sha256: payload.sha256,
+					sourceName: payload.sourceName
+				}
+			};
+		});
 		const candidate = normalizeCandidate({
 			raw: {
 				name: draft.name,
@@ -239,7 +329,7 @@ function createCandidateSink(options) {
 				files: [{
 					path: "SKILL.md",
 					content: draft.content
-				}, ...draft.files ?? []]
+				}, ...files]
 			},
 			source: "generated",
 			...options.now ? { now: options.now } : {},
@@ -250,7 +340,7 @@ function createCandidateSink(options) {
 			confirmedAt: input.confirmedAt,
 			...input.sessionId !== void 0 ? { sessionId: input.sessionId } : {}
 		};
-		await options.store.save(candidate);
+		await options.store.save(candidate, bytes);
 		await options.audit?.append({
 			type: AUDIT_EVENT_TYPES.candidateCreated,
 			target: candidate.id,