@webskill/sdk 0.2.8 → 0.4.0

package/dist/mcp.js

@@ -1,5 +1,5 @@
-import { C as messageOf, d as assertRemoteUrlAllowed, u as WebSkillError } from "./dist-BQzncxXg.js";
-import { I as normalizeToolContent, M as mergeCatalogEntries } from "./dist-B9VLwOME.js";
+import { O as messageOf, h as assertRemoteUrlAllowed, m as WebSkillError } from "./dist-8oQRa8Xz.js";
+import { H as normalizeToolContent, R as mergeCatalogEntries } from "./dist-C-Sh0MDU.js";
 
 //#region ../mcp/dist/index.js
 /**

package/dist/memoryArtifactStore-BtOeB_hm-tj3fC5ip.js

@@ -0,0 +1,78 @@
+import { m as WebSkillError } from "./dist-8oQRa8Xz.js";
+
+//#region ../runtime/dist/memoryArtifactStore-BtOeB_hm.js
+/** 纯文本消息内容的构造快捷方式（引擎内部绝大多数消息仍是纯文本） */
+const textParts = (text) => [{
+	type: "text",
+	text
+}];
+/** 取出 parts 中的文本（非文本分片在纯文本语境下无法表达，此处按丢弃处理——调用方须先校验） */
+const partsToText = (parts) => (parts ?? []).reduce((acc, part) => part.type === "text" ? acc + part.text : acc, "");
+const isContentPart = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const part = value;
+	if (part["type"] === "text") return typeof part["text"] === "string";
+	if (part["type"] === "image" || part["type"] === "file") return typeof part["mimeType"] === "string" && typeof part["data"] === "string";
+	return false;
+};
+/**
+* 0.4.0 起 `content` 是 parts 数组。旧的 `string` content 一律拒绝，不做静默转换：
+* 转换会让「模型看到的输入」与「历史记录的输入」悄悄分叉。
+*/
+function validateLlmMessages(messages) {
+	messages.forEach((message, index) => {
+		if (typeof message.content === "string") throw new WebSkillError("VALIDATION_FAILED", `messages[${index}].content is a string; since schema version 2 it must be an array of content parts. Legacy data is not converted automatically.`);
+		if (!Array.isArray(message.content) || !message.content.every(isContentPart)) throw new WebSkillError("VALIDATION_FAILED", `messages[${index}].content is not a valid array of content parts`);
+	});
+}
+/** provider 不支持某类分片时的统一拒绝：静默丢弃会让模型回答一个它没看见的附件 */
+function rejectUnsupportedPart(part, provider, where) {
+	throw new WebSkillError("VALIDATION_FAILED", `${provider} does not support ${part.type} content in ${where} messages`);
+}
+/** 内存 ArtifactStore：测试与浏览器降级用；索引随进程生命周期存在 */
+var MemoryArtifactStore = class {
+	#byRun = /* @__PURE__ */ new Map();
+	#seq = 0;
+	async createTextArtifact(input) {
+		return this.#record({
+			runId: input.runId,
+			path: input.path,
+			type: "text",
+			size: new TextEncoder().encode(input.content).length,
+			mimeType: input.mimeType,
+			metadata: input.metadata
+		});
+	}
+	async createBinaryArtifact(input) {
+		return this.#record({
+			runId: input.runId,
+			path: input.path,
+			type: "binary",
+			size: input.content.length,
+			mimeType: input.mimeType,
+			metadata: input.metadata
+		});
+	}
+	async listArtifacts(runId) {
+		return [...this.#byRun.get(runId) ?? []];
+	}
+	#record(input) {
+		const artifact = {
+			id: `art-${++this.#seq}`,
+			runId: input.runId,
+			path: input.path,
+			type: input.type,
+			mimeType: input.mimeType,
+			size: input.size,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			metadata: input.metadata
+		};
+		const list = this.#byRun.get(input.runId) ?? [];
+		list.push(artifact);
+		this.#byRun.set(input.runId, list);
+		return artifact;
+	}
+};
+
+//#endregion
+export { validateLlmMessages as a, textParts as i, partsToText as n, rejectUnsupportedPart as r, MemoryArtifactStore as t };

package/dist/node.d.ts

@@ -1,7 +1,300 @@
-import { K as SkillInstallSource, L as SKILLS_LOCKFILE, N as FileSystemProvider, R as SKILL_MANIFEST_FILE, Y as SkillManifest, et as SkillsLockfile, nt as VerifyResult, v as UiBridge } from "./types-AmKCKJn_-BogJPQHU.js";
-import { Q as ScriptExecutor, dt as WebSkillRuntime, ft as WebSkillRuntimeDeps, ht as createScriptContext } from "./index-QrHtAudz.js";
+import { D as ArchiveLimits, F as JsonSchema, H as SKILLS_LOCKFILE, J as SignatureAuditSink, M as FileStat, N as FileSystemProvider, U as SKILL_MANIFEST_FILE, et as SkillInstallSource, ft as TrustedKeyStore, gt as VerifyResult, it as SkillManifest, mt as UnsignedPolicy, o as InteractionRequest, rt as SkillManagerPort, s as InteractionResponse, ut as SkillsLockfile, v as RenderResultRequest, y as UiBridge } from "./types-7Wcg--Vh-1YlQ4jF9.js";
+import { C as FsArtifactStore, Dt as ToolDefinition, Lt as WebSkillRuntime, Rt as WebSkillRuntimeDeps, V as NetworkPolicy, Vt as createScriptContext, d as ApprovalScope, f as BridgeCapabilities, gt as ScriptExecutor, ht as ScriptExecutionContext, kt as ToolResult, mt as SchemaInferer, w as FsMemoryStore } from "./index-DLfR2Y6I.js";
+import { a as AuditLog, p as CandidateStore, r as ApprovalPolicy, u as CandidateSkill, v as SkillVersionStore } from "./skillVersionStore-uyefLPR1-DXOzbksv.js";
 import { n as LlmEnvConfig, s as probeLlmCapabilities, t as LlmCapabilities } from "./env-BPUBZCwJ-4jat_SVG.js";
-import { C as ProcessSandboxExecutor, D as SkillManager, E as SandboxedScriptExecutor, O as exportArchive, S as OxcSchemaInferer, T as SandboxOptions, _ as CliUiBridge, a as AuditLog, b as NodeFS, c as CandidateSkill, d as CandidateStore, h as SkillVersionStore, k as readArchiveManifest, r as ApprovalPolicy, v as FileArtifactStore, w as ProcessSandboxOptions, x as NodeScriptExecutor, y as FileMemoryStore } from "./skillVersionStore-B7rGjtMi-BgnQho9v.js";
+import { Readable, Writable } from "node:stream";
+//#region ../node/dist/index.d.ts
+//#region src/fs/nodeFs.d.ts
+/**
+ * 基于 node:fs/promises 的 FileSystemProvider；接受 `/` 风格路径，写入自动创建父目录。
+ * 可选 root 模式：构造传入 root 后，read/write 操作先做 realpath 包含校验
+ * （root 与目标都 realpath 后前缀比对），经符号链接逃逸 root → FS_PATH_OUTSIDE_ROOT。
+ */
+declare class NodeFS implements FileSystemProvider {
+  #private;
+  readonly kind = "node";
+  constructor(deps?: {
+    root?: string;
+  });
+  /** root 模式：全部方法（read/write/exists/stat/list/mkdir/remove/rename）目标 realpath 必须落在 root realpath 前缀内 */
+  withRoot(root: string): NodeFS;
+  readText(p: string): Promise<string>;
+  writeText(p: string, content: string): Promise<void>;
+  appendText(p: string, content: string): Promise<void>;
+  readBinary(p: string): Promise<Uint8Array>;
+  writeBinary(p: string, content: Uint8Array): Promise<void>;
+  exists(p: string): Promise<boolean>;
+  stat(p: string): Promise<FileStat>;
+  list(p: string): Promise<FileStat[]>;
+  mkdir(p: string): Promise<void>;
+  remove(p: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  rename(from: string, to: string): Promise<void>;
+}
+//#endregion
+//#region src/executor/nodeScriptExecutor.d.ts
+/**
+ * 进程内脚本执行器。接口按沙箱语义设计（context 无隐式宿主访问），
+ * worker_threads 沙箱见 deferred-items D1。
+ */
+declare class NodeScriptExecutor implements ScriptExecutor {
+  #private;
+  constructor(fs: FileSystemProvider);
+  loadDefinition(skillRoot: string, scriptName: string): Promise<ToolDefinition>;
+  execute(input: {
+    skillRoot: string;
+    scriptName: string;
+    args: Record<string, unknown>;
+    context: Parameters<ScriptExecutor['execute']>[0]['context'];
+    timeoutMs: number;
+  }): Promise<ToolResult>;
+}
+//#endregion
+//#region src/executor/sandboxedScriptExecutor.d.ts
+interface SandboxOptions {
+  /** 默认 { maxOldGenerationSizeMb: 64, maxYoungGenerationSizeMb: 16 } */
+  resourceLimits?: {
+    maxOldGenerationSizeMb?: number;
+    maxYoungGenerationSizeMb?: number;
+  };
+  /** env 白名单（仅这些变量传入 Worker；默认空） */
+  envWhitelist?: string[];
+  capabilities?: BridgeCapabilities;
+  /** 网络策略：默认 'deny-all'（白名单见 runtime/sandbox/networkPolicy） */
+  networkPolicy?: NetworkPolicy;
+  /** 裸模块 allowlist（默认 []：一切 node: 内置模块全禁；按需放行如 ['node:path']） */
+  allowedModules?: string[];
+  /** require-approval 模式的授权询问出口（缺失时 require-approval 一律拒绝） */
+  uiBridge?: UiBridge;
+  /** 授权粒度：默认 'once-per-run' */
+  approvalScope?: ApprovalScope;
+}
+/**
+ * D1：worker_threads 沙箱脚本执行器。
+ * 每次执行独立 Worker（resourceLimits + env 白名单），loadDefinition 同样在
+ * Worker 内完成（禁止主进程 import 不可信脚本）；超时 terminate（可杀同步死循环）。
+ * 能力桥协议与浏览器同一来源（runtime/sandbox/bridgeProtocol）。
+ *
+ * 诚实标注：本执行器做的是**能力面收敛**（网络策略、模块 allowlist、资源限额、
+ * 超时强杀），**不是安全边界**——Worker 内脚本与宿主共享进程；
+ * 已知主动逃逸面（process.binding/_linkedBinding/dlopen/openStdin/reallyExit/abort）
+ * 已在入口删除（0.2.3），常规 import 拦截之外不承诺防御其它宿主共享面；
+ * 禁止假定其可隔离不可信脚本（隔离级需求用 ProcessSandboxExecutor）。
+ */
+declare class SandboxedScriptExecutor implements ScriptExecutor {
+  #private;
+  constructor(fs: FileSystemProvider, options?: SandboxOptions);
+  loadDefinition(skillRoot: string, scriptName: string): Promise<ToolDefinition>;
+  execute(input: {
+    skillRoot: string;
+    scriptName: string;
+    args: Record<string, unknown>;
+    context: ScriptExecutionContext;
+    timeoutMs: number;
+  }): Promise<ToolResult>;
+}
+//#endregion
+//#region src/executor/processSandboxExecutor.d.ts
+interface ProcessSandboxOptions {
+  /** 温池大小（并发上限；执行后 kill 并补位重生），默认 2 */
+  poolSize?: number;
+  /** 透传给子进程的环境变量白名单（默认 []：子进程 env 为空，防密钥泄露） */
+  envWhitelist?: string[];
+  capabilities?: BridgeCapabilities;
+  /** 网络策略：默认 'deny-all'（权限模型无网络维度，补丁兜底；node:net 裸模块为已知残余面） */
+  networkPolicy?: NetworkPolicy;
+  /** require-approval 模式的授权询问出口 */
+  uiBridge?: UiBridge;
+  /** 授权粒度：默认 'once-per-run' */
+  approvalScope?: ApprovalScope;
+  /** 池维护告警出口（recycle 重生失败等；默认 console.warn） */
+  onWarning?: (message: string) => void;
+}
+/**
+ * child_process.fork + --permission 进程沙箱（真实进程隔离）。
+ * 每个子进程以 `--permission --allow-fs-read=<入口目录> --allow-fs-read=<skillRoot>
+ * --allow-fs-write=<artifactDir>` 启动：fs 维度由权限模型管控（experimental），
+ * 子进程/Worker/addons 默认禁；网络无权限维度仍靠 fetch/WebSocket patch。
+ * 能力桥协议与 worker_threads 沙箱同一形态（readReference/writeArtifact/confirm + 授权）。
+ * 温池（默认 2）：同 skillRoot 复用子进程；执行后 kill 并补位重生；并发上限即池大小。
+ * 超时 kill（同步死循环可杀）；非零退出码 → TOOL_EXECUTION_FAILED。
+ */
+declare class ProcessSandboxExecutor implements ScriptExecutor {
+  #private;
+  constructor(fs: FileSystemProvider, options?: ProcessSandboxOptions);
+  get poolSize(): number;
+  /** 池全部子进程销毁（测试收尾/进程退出前调用）；排队中的 acquire 一律 reject（不悬挂） */
+  dispose(): Promise<void>;
+  loadDefinition(skillRoot: string, scriptName: string): Promise<ToolDefinition>;
+  execute(input: {
+    skillRoot: string;
+    scriptName: string;
+    args: Record<string, unknown>;
+    context: ScriptExecutionContext;
+    timeoutMs: number;
+  }): Promise<ToolResult>;
+}
+//#endregion
+//#region src/schema/oxcSchemaInferer.d.ts
+/**
+ * D2 Schema 推导（OXC 静态文本分析，宿主侧执行，不进沙箱）。
+ * TS 类型标注为主路径，JSDoc @param 为辅路径；不支持类型降级 string 并标 'x-inferred'。
+ */
+declare class OxcSchemaInferer implements SchemaInferer {
+  inferSchemaFromSource(source: string, options?: {
+    fileName?: string;
+  }): JsonSchema | undefined;
+}
+//#endregion
+//#region src/artifacts/fileArtifactStore.d.ts
+/**
+ * FileArtifactStore：兼容别名，语义同阶段 2-4。
+ * 实现已上移到 runtime 的 FsArtifactStore；node 侧保留 NodeFS 默认值。
+ */
+declare class FileArtifactStore extends FsArtifactStore {
+  constructor(deps: {
+    root: string;
+    fs?: FileSystemProvider;
+  });
+}
+//#endregion
+//#region src/memory/fileMemoryStore.d.ts
+/**
+ * FileMemoryStore：兼容别名，语义同阶段 3。
+ * 实现已上移到 runtime 的 FsMemoryStore；node 侧保留 NodeFS 默认值。
+ */
+declare class FileMemoryStore extends FsMemoryStore {
+  constructor(deps: {
+    root: string;
+    fs?: FileSystemProvider;
+  });
+}
+//#endregion
+//#region src/ui/cliUiBridge.d.ts
+/**
+ * 命令行 UiBridge：ask→问答，confirm→y/n（带默认值），
+ * form→逐字段提示（显示默认值与必填标记），select→编号列表，
+ * authorize→授权询问（默认拒绝，仅显式 y/yes 批准）。
+ * 输入/输出流可注入（测试用 PassThrough）。
+ */
+declare class CliUiBridge implements UiBridge {
+  #private;
+  constructor(deps?: {
+    input?: Readable;
+    output?: Writable;
+  });
+  request(input: InteractionRequest): Promise<InteractionResponse>;
+  progress(input: {
+    runId: string;
+    message: string;
+    value?: number;
+  }): Promise<void>;
+  renderResult(input: RenderResultRequest): Promise<void>;
+}
+//#endregion
+//#region src/skillManagement/skillManager.d.ts
+/**
+ * 技能管理门面：统一安装管线（staging → 解析 name → 校验 → 拷贝 → manifest → lockfile），
+ * 任何失败清理现场抛 INSTALL_FAILED。
+ * @stable
+ */
+declare class SkillManager implements SkillManagerPort {
+  #private;
+  constructor(deps: {
+    managedRoot: string;
+    fs?: FileSystemProvider;
+    fetchImpl?: typeof fetch;
+    /** D2 安装期 schema 预推导（默认 true，可关） */
+    schemaInference?: boolean;
+    /** 归档体积三重上限（缺省 DEFAULT_ARCHIVE_LIMITS） */
+    archiveLimits?: ArchiveLimits;
+    /** install/uninstall 成功后的变更回调（宿主接线缓存失效，如 WebSkillRuntime.invalidate） */
+    onChanged?: () => void;
+    /**
+     * 供应链信任（design 03 §5.1）。未注入时仍会验签，只是信任库为空——
+     * 未签名的包不受影响（默认策略 warn），带着不受信公钥的包则装不上。
+     */
+    signature?: {
+      trustedKeys?: TrustedKeyStore;
+      /**
+       * 未签名包的处置，默认 `warn`（0.4.0 D2 复核后维持）。
+       * 收成 `deny` 必须同时注入 `trustedKeys`：空信任库 + deny 的接受集为空，
+       * 任何包都装不上。
+       */
+      unsigned?: UnsignedPolicy;
+      /** 验签结论落审计（governance 的 FsAuditLog 结构上兼容） */
+      audit?: SignatureAuditSink;
+    };
+    /** 安装期告警（当前仅未签名放行）；宿主接线日志/UI */
+    onWarning?: (warning: {
+      skill: string;
+      message: string;
+    }) => void;
+  });
+  /** 托管根目录（治理发布归档捕获等只读场景） */
+  get managedRoot(): string;
+  install(source: SkillInstallSource, options?: {
+    expectedSha256?: string;
+  }): Promise<SkillManifest>;
+  uninstall(name: string): Promise<void>;
+  verifyIntegrity(name: string): Promise<VerifyResult>;
+  listInstalled(): Promise<SkillsLockfile>;
+  exportArchive(name: string, options: {
+    format: 'zip' | 'tar';
+    outPath: string;
+  }): Promise<string>;
+  /** 多技能包集导出（webskill.skill-pack.json + 各技能目录含 manifest），写 outPath 并返回 */
+  exportPack(names: string[], options: {
+    outPath: string;
+  }): Promise<string>;
+}
+//#endregion
+//#region src/mcp/connectStdioEndpoint.d.ts
+interface StdioEndpointConfig {
+  /** registry 中的名字（endpoint:tool 引用） */
+  endpoint: string;
+  /**
+   * 可执行文件。**只能来自宿主配置**：从技能 frontmatter / manifest 到这里没有任何代码路径。
+   * 因为 env 不继承父进程，PATH 默认为空——请传绝对路径，或在 env 里显式给出 PATH。
+   */
+  command: string;
+  args?: readonly string[];
+  cwd?: string;
+  /** 子进程环境变量。**不默认继承 process.env**：MCP server 是宿主机上的任意程序 */
+  env?: Record<string, string>;
+  /** 连接与调用超时；0/缺省 = 不超时 */
+  timeoutMs?: number;
+  /** 子进程 stderr 观测（默认丢弃，仅保留尾部用于错误消息） */
+  onStderr?: (chunk: string) => void;
+}
+/**
+ * stdio MCP endpoint 装配：spawn 宿主配置的可执行程序，经 stdin/stdout 说 MCP，
+ * 注册进 EndpointRegistry——endpoint:tool 解析、TTL+版本缓存、临时技能消费自动生效。
+ * 返回 close 句柄：断开后 unregister 并确保子进程真的退出（不留僵尸）。
+ *
+ * registry 参数写成结构型而非 `EndpointRegistry<McpClientLike>`：只要从 `@webskill/mcp`
+ * `import type`，tsdown 就会把整个 mcp 的 d.ts chunk 拖进 `@webskill/sdk/node`，
+ * 把 optional peer `@modelcontextprotocol/sdk` 变成 node 子路径的类型硬依赖
+ * （install-smoke 的消费方 typecheck 探针会因此变红）。结构类型保证真实的
+ * `EndpointRegistry<McpClientLike>` 仍可直接传入。
+ */
+declare function connectStdioEndpoint<TClient>(registry: {
+  register(endpoint: string, client: TClient): void;
+  unregister(endpoint: string): void;
+}, config: StdioEndpointConfig): Promise<{
+  close(): Promise<void>;
+}>;
+//#endregion
+//#region src/skillManagement/export/archiveExporter.d.ts
+/** 导出技能目录全部文件（含 manifest）为 zip/tar 归档，返回 outPath */
+declare function exportArchive(fs: FileSystemProvider, skillRoot: string, options: {
+  format: 'zip' | 'tar';
+  outPath: string;
+}): Promise<string>;
+/** 只解出归档中的 webskill.skill-manifest.json 条目（安装前预览） */
+declare function readArchiveManifest(fs: FileSystemProvider, archivePath: string): Promise<SkillManifest>;
+//#endregion
 //#region ../governance/dist/node.d.ts
 //#region src/approval/approvalWorkflow.d.ts
 /** 审批工作流：review（UiBridge confirm 真实接线）/ publish（校验→安装→版本→审计） */
@@ -47,4 +340,4 @@ declare function createEvaluationRuntime(deps: WebSkillRuntimeDeps & {
   executor?: ScriptExecutor;
 }): WebSkillRuntime;
 //#endregion
-export { ApprovalWorkflow, CliUiBridge, FileArtifactStore, FileMemoryStore, type LlmCapabilities, type LlmEnvConfig, NodeFS, NodeScriptExecutor, OxcSchemaInferer, ProcessSandboxExecutor, type ProcessSandboxOptions, SKILLS_LOCKFILE, SKILL_MANIFEST_FILE, type SandboxOptions, SandboxedScriptExecutor, type SkillInstallSource, SkillManager, type SkillManifest, type SkillsLockfile, type VerifyResult, createEvaluationRuntime, createScriptContext, exportArchive, probeLlmCapabilities, readArchiveManifest };
+export { ApprovalWorkflow, CliUiBridge, FileArtifactStore, FileMemoryStore, type LlmCapabilities, type LlmEnvConfig, NodeFS, NodeScriptExecutor, OxcSchemaInferer, ProcessSandboxExecutor, type ProcessSandboxOptions, SKILLS_LOCKFILE, SKILL_MANIFEST_FILE, type SandboxOptions, SandboxedScriptExecutor, type SkillInstallSource, SkillManager, type SkillManifest, type SkillsLockfile, type StdioEndpointConfig, type VerifyResult, connectStdioEndpoint, createEvaluationRuntime, createScriptContext, exportArchive, probeLlmCapabilities, readArchiveManifest };