@webskill/sdk 0.5.0 → 0.6.0

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
-import { I as JsonSchema, Q as SkillCatalogEntry, et as SkillDocument, g as LlmToolSpec } from "./types-D_hoCri8-BnNPiZCi.js";
-import { Nt as ToolResult, b as ExternalSkillProvider, rn as mergeCatalogEntries, x as ExternalToolSource } from "./index-vBz_FC9w.js";
+import { I as JsonSchema, Q as SkillCatalogEntry, et as SkillDocument, g as LlmToolSpec } from "./types-4pg-qp_I-Gq63X8Oa.js";
+import { D as ExternalSkillProvider, O as ExternalToolSource, Tn as mergeCatalogEntries, Ut as ToolResult } from "./index-C-KFAZoF.js";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -192,15 +192,46 @@ declare function serveSkillAsMcp(server: McpServer, skill: ServedSkill): Promise
 declare const catalogMerge: typeof mergeCatalogEntries;
 //#endregion
 //#region src/webmcp/experimentalWebMcpAdapter.d.ts
-/** navigator.modelContext 鸭子类型（对齐浏览器 WebMCP API 草案） */
+/**
+ * WebMCP 命令式 API 的工具形状（Chrome 150+）。
+ * `getTools()` 返回的工具含 `inputSchema`（JSON 字符串）、`origin`、`window`、`annotations`。
+ * 参考 https://developer.chrome.com/docs/ai/webmcp/imperative-api
+ */
+interface WebMcpToolLike {
+  name: string;
+  description?: string;
+  /** getTools() 返回的 inputSchema 是 JSON 字符串（非对象） */
+  inputSchema?: string;
+  origin?: string;
+  window?: unknown;
+  annotations?: {
+    readOnlyHint?: boolean;
+    untrustedContentHint?: boolean;
+  };
+}
+/**
+ * document.modelContext 鸭子类型（对齐 Chrome 150+ 的 WebMCP 命令式 API）。
+ * - 旧版（Chrome <150）：navigator.modelContext.listTools() / executeTool(name, argsJson)
+ * - 新版（Chrome 150+）：document.modelContext.getTools() / executeTool(tool, argsJson, { signal? })
+ * executeTool 的第一参在两种版本都能接受：新版传 tool 对象，旧版传 name 字符串。
+ */
 interface BrowserModelContextLike {
-  listTools?: () => Promise<unknown>;
-  executeTool?: (name: string, argsJson: string) => Promise<unknown>;
+  getTools?: () => Promise<unknown>;
+  executeTool?: (tool: WebMcpToolLike | string, argsJson: string, options?: {
+    signal?: AbortSignal;
+  }) => Promise<unknown>;
 }
 interface WebMcpToolDescriptor {
   name: string;
   description?: string;
   inputSchema?: unknown;
+  origin?: string;
+  annotations?: {
+    readOnlyHint?: boolean;
+    untrustedContentHint?: boolean;
+  };
+  /** getTools() 返回的原始 tool 对象：executeTool 第一参须透传原对象（含 inputSchema JSON 字符串、window 等） */
+  raw?: unknown;
 }
 /**
  * Experimental WebMCP Adapter（mcp# 分支）：默认关闭显式启用；
@@ -214,9 +245,9 @@ declare class ExperimentalWebMcpAdapter {
     enabled?: boolean;
   });
   isAvailable(): boolean;
-  /** 工具清单（listTools 缺失时返回 undefined；调用失败时告警后返回 undefined） */
+  /** 工具清单（getTools 缺失时返回 undefined；调用失败时告警后返回 undefined） */
   listTools(): Promise<WebMcpToolDescriptor[] | undefined>;
-  /** 工具名清单（listTools 缺失/失败时返回 undefined） */
+  /** 工具名清单（getTools 缺失/失败时返回 undefined） */
   listToolNames(): Promise<string[] | undefined>;
   call(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
 }
@@ -269,4 +300,4 @@ declare function connectRemoteEndpoint(registry: EndpointRegistry<McpClientLike>
   close(): Promise<void>;
 }>;
 //#endregion
-export { type BrowserModelContextLike, EndpointRegistry, ExperimentalWebMcpAdapter, type McpClientLike, McpRuntimePlugin, McpToolResolver, MessageChannelTransport, type MessageChannelTransportOptions, type MessagePortLike, type RemoteEndpointConfig, type ServedSkill, TemporarySkillProvider, type TransportState, type WebMcpToolDescriptor, catalogMerge, connectRemoteEndpoint, endpointToolLlmName, parseEndpointToolLlmName, parseWebMcpToolLlmName, serveSkillAsMcp, validateJsonRpcMessage, webMcpToolLlmName };
+export { type BrowserModelContextLike, EndpointRegistry, ExperimentalWebMcpAdapter, type McpClientLike, McpRuntimePlugin, McpToolResolver, MessageChannelTransport, type MessageChannelTransportOptions, type MessagePortLike, type RemoteEndpointConfig, type ServedSkill, TemporarySkillProvider, type TransportState, type WebMcpToolDescriptor, type WebMcpToolLike, catalogMerge, connectRemoteEndpoint, endpointToolLlmName, parseEndpointToolLlmName, parseWebMcpToolLlmName, serveSkillAsMcp, validateJsonRpcMessage, webMcpToolLlmName };

package/dist/mcp.js

@@ -1,5 +1,5 @@
 import { O as messageOf, h as assertRemoteUrlAllowed, m as WebSkillError } from "./dist-8oQRa8Xz.js";
-import { U as mergeCatalogEntries, q as normalizeToolContent } from "./dist-6C03DShK.js";
+import { at as normalizeToolContent, et as mergeCatalogEntries } from "./dist-DusANsrn.js";
 
 //#region ../mcp/dist/index.js
 /**
@@ -392,15 +392,39 @@ const failure = (code, message) => ({
 		message
 	}
 });
-/** 从 listTools 返回值提取工具描述（容忍数组或 {tools:[]} 两种形状） */
+/** getTools() 返回的工具 → 描述符：inputSchema 为 JSON 字符串时解析为对象，并保留原始对象 */
+function toDescriptor(raw) {
+	if (typeof raw !== "object" || raw === null) return void 0;
+	const t = raw;
+	const name = String(t["name"] ?? "");
+	if (name === "") return void 0;
+	const descriptor = {
+		name,
+		raw
+	};
+	if (typeof t["description"] === "string") descriptor.description = t["description"];
+	if (typeof t["origin"] === "string") descriptor.origin = t["origin"];
+	if (typeof t["annotations"] === "object" && t["annotations"] !== null) {
+		const annotations = t["annotations"];
+		descriptor.annotations = {
+			...typeof annotations["readOnlyHint"] === "boolean" ? { readOnlyHint: annotations["readOnlyHint"] } : {},
+			...typeof annotations["untrustedContentHint"] === "boolean" ? { untrustedContentHint: annotations["untrustedContentHint"] } : {}
+		};
+	}
+	const schema = t["inputSchema"];
+	if (typeof schema === "string" && schema.trim() !== "") try {
+		descriptor.inputSchema = JSON.parse(schema);
+	} catch {
+		descriptor.inputSchema = schema;
+	}
+	else if (typeof schema === "object" && schema !== null) descriptor.inputSchema = schema;
+	return descriptor;
+}
+/** 从 getTools 返回值提取工具描述（容忍数组或 {tools:[]} 两种形状） */
 function extractToolDescriptors(raw) {
 	const list = Array.isArray(raw) ? raw : typeof raw === "object" && raw !== null && Array.isArray(raw.tools) ? raw.tools : void 0;
 	if (!list) return void 0;
-	return list.filter((t) => typeof t === "object" && t !== null).map((t) => ({
-		name: String(t["name"] ?? ""),
-		...typeof t["description"] === "string" ? { description: t["description"] } : {},
-		...typeof t["inputSchema"] === "object" && t["inputSchema"] !== null ? { inputSchema: t["inputSchema"] } : {}
-	})).filter((t) => t.name !== "");
+	return list.map(toDescriptor).filter((d) => d !== void 0);
 }
 /**
 * Experimental WebMCP Adapter（mcp# 分支）：默认关闭显式启用；
@@ -416,35 +440,45 @@ var ExperimentalWebMcpAdapter = class {
 		this.#enabled = options?.enabled ?? false;
 	}
 	isAvailable() {
-		return this.#enabled && typeof this.#resolveApi()?.executeTool === "function";
+		const api = this.#resolveApi();
+		return this.#enabled && typeof api?.executeTool === "function";
 	}
-	/** 工具清单（listTools 缺失时返回 undefined；调用失败时告警后返回 undefined） */
+	/** 工具清单（getTools 缺失时返回 undefined；调用失败时告警后返回 undefined） */
 	async listTools() {
 		const api = this.#resolveApi();
-		if (typeof api?.listTools !== "function") return void 0;
+		if (typeof api?.getTools !== "function") return void 0;
 		try {
-			return extractToolDescriptors(await api.listTools());
+			return extractToolDescriptors(await api.getTools());
 		} catch (e) {
-			console.warn(`[webskill] navigator.modelContext.listTools() failed: ${e instanceof Error ? e.message : String(e)}`);
+			console.warn(`[webskill] document.modelContext.getTools() failed: ${e instanceof Error ? e.message : String(e)}`);
 			return;
 		}
 	}
-	/** 工具名清单（listTools 缺失/失败时返回 undefined） */
+	/** 工具名清单（getTools 缺失/失败时返回 undefined） */
 	async listToolNames() {
 		return (await this.listTools())?.map((t) => t.name);
 	}
 	async call(toolName, args) {
 		if (!this.#enabled) return failure("TOOL_UNSUPPORTED", "WebMCP adapter is disabled (enable it explicitly to use mcp# tools)");
 		const api = this.#resolveApi();
-		if (typeof api?.executeTool !== "function") return failure("TOOL_UNSUPPORTED", "navigator.modelContext is not available");
-		if (typeof api.listTools === "function") try {
-			const names = extractToolDescriptors(await api.listTools())?.map((t) => t.name);
-			if (names && !names.includes(toolName)) return failure("MCP_TOOL_NOT_FOUND", `WebMCP tool "${toolName}" not found`);
-		} catch {}
+		if (typeof api?.executeTool !== "function") return failure("TOOL_UNSUPPORTED", "document.modelContext is not available");
+		const argsJson = JSON.stringify(args);
+		if (typeof api.getTools === "function") try {
+			const descriptors = extractToolDescriptors(await api.getTools());
+			const match = descriptors?.find((t) => t.name === toolName);
+			if (descriptors !== void 0 && match === void 0) return failure("MCP_TOOL_NOT_FOUND", `WebMCP tool "${toolName}" not found`);
+			const tool = match?.raw ?? { name: toolName };
+			return {
+				ok: true,
+				content: normalizeToolContent(await api.executeTool(tool, argsJson))
+			};
+		} catch (e) {
+			return failure("TOOL_EXECUTION_FAILED", `WebMCP tool "${toolName}" failed: ${messageOf(e)}`);
+		}
 		try {
 			return {
 				ok: true,
-				content: normalizeToolContent(await api.executeTool(toolName, JSON.stringify(args)))
+				content: normalizeToolContent(await api.executeTool(toolName, argsJson))
 			};
 		} catch (e) {
 			return failure("TOOL_EXECUTION_FAILED", `WebMCP tool "${toolName}" failed: ${messageOf(e)}`);

package/dist/{memoryArtifactStore-BtOeB_hm-tj3fC5ip.js → memoryArtifactStore-52Zn9npI-BMPYwvoy.js}

@@ -1,6 +1,6 @@
 import { m as WebSkillError } from "./dist-8oQRa8Xz.js";
 
-//#region ../runtime/dist/memoryArtifactStore-BtOeB_hm.js
+//#region ../runtime/dist/memoryArtifactStore-52Zn9npI.js
 /** 纯文本消息内容的构造快捷方式（引擎内部绝大多数消息仍是纯文本） */
 const textParts = (text) => [{
 	type: "text",
@@ -8,6 +8,14 @@ const textParts = (text) => [{
 }];
 /** 取出 parts 中的文本（非文本分片在纯文本语境下无法表达，此处按丢弃处理——调用方须先校验） */
 const partsToText = (parts) => (parts ?? []).reduce((acc, part) => part.type === "text" ? acc + part.text : acc, "");
+/**
+* run 的提示词文本投影：`RuntimeRun.userPrompt` 与快照都是字符串字段，
+* 而多模态提示词里的图片/文件分片没有文本形态，用占位符标注，避免记录成空串。
+*/
+const promptText = (prompt) => {
+	if (typeof prompt === "string") return prompt;
+	return prompt.map((part) => part.type === "text" ? part.text : `[${part.type}: ${part.mimeType}]`).join("\n");
+};
 const isContentPart = (value) => {
 	if (typeof value !== "object" || value === null) return false;
 	const part = value;
@@ -75,4 +83,4 @@ var MemoryArtifactStore = class {
 };
 
 //#endregion
-export { validateLlmMessages as a, textParts as i, partsToText as n, rejectUnsupportedPart as r, MemoryArtifactStore as t };
+export { textParts as a, rejectUnsupportedPart as i, partsToText as n, validateLlmMessages as o, promptText as r, MemoryArtifactStore as t };

package/dist/node.d.ts

@@ -1,7 +1,7 @@
-import { I as JsonSchema, N as FileStat, O as ArchiveLimits, P as FileSystemProvider, U as SKILLS_LOCKFILE, W as SKILL_MANIFEST_FILE, Y as SignatureAuditSink, _t as VerifyResult, at as SkillManifest, b as UiBridge, c as InteractionResponse, dt as SkillsLockfile, ht as UnsignedPolicy, it as SkillManagerPort, pt as TrustedKeyStore, s as InteractionRequest, tt as SkillInstallSource, y as RenderResultRequest } from "./types-D_hoCri8-BnNPiZCi.js";
-import { D as FsMemoryStore, E as FsArtifactStore, Ht as WebSkillRuntimeDeps, Nt as ToolResult, Vt as WebSkillRuntime, W as NetworkPolicy, _t as SchemaInferer, d as ApprovalScope, f as BridgeCapabilities, jt as ToolDefinition, qt as createScriptContext, vt as ScriptExecutionContext, yt as ScriptExecutor } from "./index-vBz_FC9w.js";
-import { a as AuditLog, p as CandidateStore, r as ApprovalPolicy, u as CandidateSkill, v as SkillVersionStore } from "./skillVersionStore-BzLbzFOL-CxwIewHJ.js";
-import { n as LlmEnvConfig, s as probeLlmCapabilities, t as LlmCapabilities } from "./env-BPUBZCwJ-4jat_SVG.js";
+import { I as JsonSchema, N as FileStat, O as ArchiveLimits, P as FileSystemProvider, U as SKILLS_LOCKFILE, W as SKILL_MANIFEST_FILE, Y as SignatureAuditSink, _t as VerifyResult, at as SkillManifest, b as UiBridge, c as InteractionResponse, dt as SkillsLockfile, ht as UnsignedPolicy, it as SkillManagerPort, pt as TrustedKeyStore, s as InteractionRequest, tt as SkillInstallSource, y as RenderResultRequest } from "./types-4pg-qp_I-Gq63X8Oa.js";
+import { A as FsArtifactStore, Ct as ScriptExecutionContext, J as NetworkPolicy, St as SchemaInferer, Ut as ToolResult, Vt as ToolDefinition, _ as BridgeCapabilities, f as ApprovalScope, fn as createScriptContext, j as FsMemoryStore, on as WebSkillRuntime, sn as WebSkillRuntimeDeps, wt as ScriptExecutor } from "./index-C-KFAZoF.js";
+import { a as AuditLog, p as CandidateStore, r as ApprovalPolicy, u as CandidateSkill, v as SkillVersionStore } from "./skillVersionStore-BzLbzFOL-CxdAFWO2.js";
+import { n as LlmEnvConfig, s as probeLlmCapabilities, t as LlmCapabilities } from "./env-AK3cSMEA-Dli6QU5E.js";
 import { Readable, Writable } from "node:stream";
 //#region ../node/dist/index.d.ts
 //#region src/fs/nodeFs.d.ts

package/dist/node.js

@@ -1,6 +1,6 @@
 import { A as parseSkillMarkdown, B as unzipWithLimits, H as verifyManifest, I as resolveArchiveLimits, L as resolveInsideRoot, M as readResponseWithLimit, N as readSkillSignature, O as messageOf, T as isValidSkillName, U as verifySkillSignature, V as validateSkills, _ as atomicWriteText, g as assertSafePathSegment, h as assertRemoteUrlAllowed, j as parseSkillPackManifest, m as WebSkillError, o as SKILLS_LOCKFILE, r as MANIFEST_EXCLUDED_FILES, s as SKILL_MANIFEST_FILE, u as SKILL_PACK_FILE, w as exportSkills, y as buildManifest } from "./dist-8oQRa8Xz.js";
-import { J as normalizeToolError, N as createScriptContext, O as WebSkillRuntime, W as networkPolicyLibSource, Y as parseBridgeRequest, d as FsMemoryStore, k as bridgeError, o as CapabilityApproval, q as normalizeToolContent, u as FsArtifactStore } from "./dist-6C03DShK.js";
-import { i as probeLlmCapabilities } from "./env--jJB-TSX-04klhTYi.js";
+import { I as WebSkillRuntime, V as createScriptContext, at as normalizeToolContent, c as CapabilityApproval, m as FsMemoryStore, nt as networkPolicyLibSource, ot as normalizeToolError, p as FsArtifactStore, st as parseBridgeRequest, z as bridgeError } from "./dist-DusANsrn.js";
+import { i as probeLlmCapabilities } from "./env-8cY40DXB-CGnEVZby.js";
 import { createRequire } from "node:module";
 import { unzipSync, zipSync } from "fflate";
 import { existsSync, promises, realpathSync } from "node:fs";
@@ -1148,6 +1148,13 @@ var CliUiBridge = class {
 					value: answer === "y" || answer === "yes"
 				};
 			}
+			case "file-pick": {
+				const answer = (await this.#question(`${input.message}\nLocal file path (empty to decline): `)).trim();
+				return answer === "" ? { id: input.id } : {
+					id: input.id,
+					value: { path: answer }
+				};
+			}
 		}
 	}
 	async progress(input) {

package/dist/{openUiLibrary-W3Ce896k-ClFTRZFs.js → openUiLibrary-Bdrji9qK-DzAxRlTY.js}

@@ -1,5 +1,5 @@
-import { nt as uiCatalog } from "./dist-bewtXYlO.js";
-import { t as CatalogNode } from "./catalogComponents-DV7cPpUm-C77AEEx9.js";
+import { nt as uiCatalog } from "./dist-DnYG2-eY.js";
+import { t as CatalogNode } from "./catalogComponents-Dr5dFMAb-Dacibl1e.js";
 import { z } from "zod";
 import { Component, Fragment, createContext, useCallback, useContext, useEffect, useInsertionEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -3761,7 +3761,7 @@ function Renderer({ response, library, isStreaming = false, onAction, onStateUpd
 const FormValidationContext = createContext(null);
 
 //#endregion
-//#region ../ui-react/dist/openUiLibrary-W3Ce896k.js
+//#region ../ui-react/dist/openUiLibrary-Bdrji9qK.js
 const propsFor = (props, container) => container ? props.extend({ children: z.array(z.any()).optional() }) : props;
 /**
 * catalog 的 OpenUI 投影：`defineComponent` 复用同一份 zod schema 与描述，

package/dist/{skillVersionStore-BzLbzFOL-CxwIewHJ.d.ts → skillVersionStore-BzLbzFOL-CxdAFWO2.d.ts}

@@ -1,4 +1,4 @@
-import { B as PageQuery, P as FileSystemProvider, Q as SkillCatalogEntry, at as SkillManifest, z as Page } from "./types-D_hoCri8-BnNPiZCi.js";
+import { B as PageQuery, P as FileSystemProvider, Q as SkillCatalogEntry, at as SkillManifest, z as Page } from "./types-4pg-qp_I-Gq63X8Oa.js";
 //#region ../governance/dist/skillVersionStore-BzLbzFOL.d.ts
 //#region src/types.d.ts
 type CandidateStatus = 'draft' | 'pending-review' | 'approved' | 'published' | 'rejected';

package/dist/{testing-DDCJWvgA.js → testing-CYTFqkDm.js}

@@ -1,5 +1,5 @@
 import { m as WebSkillError } from "./dist-8oQRa8Xz.js";
-import { i as textParts, n as partsToText } from "./memoryArtifactStore-BtOeB_hm-tj3fC5ip.js";
+import { a as textParts, n as partsToText } from "./memoryArtifactStore-52Zn9npI-BMPYwvoy.js";
 
 //#region ../runtime/dist/testing.js
 /**

package/dist/testing.d.ts

@@ -1,5 +1,5 @@
-import { _ as MemoryStore, b as UiBridge, c as InteractionResponse, l as LlmClient, m as LlmStreamEvent, n as ArtifactStore, p as LlmResponse, s as InteractionRequest, t as Artifact, u as LlmCompleteInput } from "./types-D_hoCri8-BnNPiZCi.js";
-import { a as loadGoogleConfigFromEnv, i as loadAnthropicConfigFromEnv, n as LlmEnvConfig, o as loadLlmConfigFromEnv, r as ProviderEnvConfig } from "./env-BPUBZCwJ-4jat_SVG.js";
+import { _ as MemoryStore, b as UiBridge, c as InteractionResponse, l as LlmClient, m as LlmStreamEvent, n as ArtifactStore, p as LlmResponse, s as InteractionRequest, t as Artifact, u as LlmCompleteInput } from "./types-4pg-qp_I-Gq63X8Oa.js";
+import { a as loadGoogleConfigFromEnv, i as loadAnthropicConfigFromEnv, n as LlmEnvConfig, o as loadLlmConfigFromEnv, r as ProviderEnvConfig } from "./env-AK3cSMEA-Dli6QU5E.js";
 //#region ../runtime/dist/testing.d.ts
 //#region src/llm/mockLlmClient.d.ts
 type MockLlmHandler = (input: LlmCompleteInput) => LlmResponse | Promise<LlmResponse>;

package/dist/testing.js

@@ -1,5 +1,5 @@
-import { t as MemoryArtifactStore } from "./memoryArtifactStore-BtOeB_hm-tj3fC5ip.js";
-import { n as loadGoogleConfigFromEnv, r as loadLlmConfigFromEnv, t as loadAnthropicConfigFromEnv } from "./env--jJB-TSX-04klhTYi.js";
-import { n as MockLlmClient, r as MockUiBridge, t as InMemoryStore } from "./testing-DDCJWvgA.js";
+import { t as MemoryArtifactStore } from "./memoryArtifactStore-52Zn9npI-BMPYwvoy.js";
+import { n as loadGoogleConfigFromEnv, r as loadLlmConfigFromEnv, t as loadAnthropicConfigFromEnv } from "./env-8cY40DXB-CGnEVZby.js";
+import { n as MockLlmClient, r as MockUiBridge, t as InMemoryStore } from "./testing-CYTFqkDm.js";
 
 export { InMemoryStore, MemoryArtifactStore, MockLlmClient, MockUiBridge, loadAnthropicConfigFromEnv, loadGoogleConfigFromEnv, loadLlmConfigFromEnv };

package/dist/{types-D_hoCri8-BnNPiZCi.d.ts → types-4pg-qp_I-Gq63X8Oa.d.ts}

@@ -1,6 +1,6 @@
 //#region ../core/dist/index.d.ts
 //#region src/errors.d.ts
-type WebSkillErrorCode = 'FS_NOT_FOUND' | 'FS_PATH_OUTSIDE_ROOT' | 'SKILL_NOT_FOUND' | 'SKILL_INVALID_METADATA' | 'SKILL_INVALID_NAME' | 'SKILL_DUPLICATE_NAME' | 'SKILL_UNSUPPORTED_SCRIPT' | 'VALIDATION_FAILED' | 'TOOL_NOT_FOUND' | 'TOOL_EXECUTION_FAILED' | 'NETWORK_BLOCKED' | 'TOOL_UNSUPPORTED' | 'TOOL_NOT_ALLOWED' | 'TOOL_SCHEMA_UNAVAILABLE' | 'RUN_TIMEOUT' | 'RUN_MAX_TURNS_EXCEEDED' | 'RUN_FAILED' | 'RUN_CANCELLED' | 'RUN_INTERACTION_TIMEOUT' | 'UI_UNAVAILABLE' | 'LLM_UNAVAILABLE' | 'LLM_REQUEST_FAILED' | 'INSTALL_FAILED' | 'UNINSTALL_FAILED' | 'EXPORT_FAILED' | 'INTEGRITY_FAILED' | 'FS_PERMISSION_DENIED' | 'MCP_ENDPOINT_UNAVAILABLE' | 'MCP_TOOL_NOT_FOUND' | 'CANDIDATE_INVALID' | 'APPROVAL_REQUIRED' | 'SKILL_QUARANTINED' | 'SKILL_DISABLED' | 'SKILL_UNKNOWN_ALLOWED_TOOL' | 'SKILL_UNKNOWN_DEPENDENCY' | 'SKILL_CIRCULAR_DEPENDENCY' | 'GOVERNANCE_FAILED' | 'RUN_SNAPSHOT_NOT_FOUND' | 'RUN_SNAPSHOT_EXPIRED' | 'RUN_SNAPSHOT_INCOMPATIBLE' | 'RUN_SNAPSHOT_SCHEMA_UNSUPPORTED' | 'RUN_TRACE_INCOMPATIBLE' | 'SESSION_INCOMPATIBLE' | 'SIGNATURE_MISSING' | 'SIGNATURE_MALFORMED' | 'SIGNATURE_UNTRUSTED_KEY' | 'SIGNATURE_MISMATCH' | 'SIGNATURE_UNSUPPORTED' | 'MCP_STDIO_SPAWN_FAILED' | 'MCP_STDIO_EXITED' | 'MCP_STDIO_TIMEOUT' | 'TS_RESOURCE_URL_REJECTED' | 'TS_TRANSPILER_UNAVAILABLE' | 'TS_TRANSPILE_FAILED' | 'TODO_LIST_INVALID' | 'TODO_ITEM_NOT_FOUND' | 'SKILL_GENERATION_DISABLED' | 'SKILL_GENERATION_LIMIT_EXCEEDED' | 'SKILL_GENERATION_VALIDATION_FAILED' | 'DELEGATION_UNAVAILABLE' | 'DELEGATION_IN_PROGRESS' | 'DELEGATION_BUDGET_EXCEEDED' | 'PREFERENCE_IMPORT_INVALID' | 'PREFERENCE_IMPORT_VERSION_UNSUPPORTED' | 'PREFERENCE_IMPORT_CREDENTIAL_REJECTED' | 'DICTATION_UNAVAILABLE' | 'DICTATION_PERMISSION_DENIED' | 'DICTATION_FAILED' | 'PERCEPTION_NOT_ENABLED' | 'PERCEPTION_FAILED';
+type WebSkillErrorCode = 'FS_NOT_FOUND' | 'FS_PATH_OUTSIDE_ROOT' | 'SKILL_NOT_FOUND' | 'SKILL_INVALID_METADATA' | 'SKILL_INVALID_NAME' | 'SKILL_DUPLICATE_NAME' | 'SKILL_UNSUPPORTED_SCRIPT' | 'VALIDATION_FAILED' | 'TOOL_NOT_FOUND' | 'TOOL_EXECUTION_FAILED' | 'NETWORK_BLOCKED' | 'TOOL_UNSUPPORTED' | 'TOOL_NOT_ALLOWED' | 'TOOL_SCHEMA_UNAVAILABLE' | 'TOOL_RESOLUTION_EXHAUSTED' | 'RUN_TIMEOUT' | 'RUN_MAX_TURNS_EXCEEDED' | 'RUN_FAILED' | 'RUN_CANCELLED' | 'RUN_INTERACTION_TIMEOUT' | 'UI_UNAVAILABLE' | 'LLM_UNAVAILABLE' | 'LLM_REQUEST_FAILED' | 'INSTALL_FAILED' | 'UNINSTALL_FAILED' | 'EXPORT_FAILED' | 'INTEGRITY_FAILED' | 'FS_PERMISSION_DENIED' | 'MCP_ENDPOINT_UNAVAILABLE' | 'MCP_TOOL_NOT_FOUND' | 'CANDIDATE_INVALID' | 'APPROVAL_REQUIRED' | 'SKILL_QUARANTINED' | 'SKILL_DISABLED' | 'SKILL_UNKNOWN_ALLOWED_TOOL' | 'SKILL_UNKNOWN_DEPENDENCY' | 'SKILL_CIRCULAR_DEPENDENCY' | 'GOVERNANCE_FAILED' | 'RUN_SNAPSHOT_NOT_FOUND' | 'RUN_SNAPSHOT_EXPIRED' | 'RUN_SNAPSHOT_INCOMPATIBLE' | 'RUN_SNAPSHOT_SCHEMA_UNSUPPORTED' | 'RUN_TRACE_INCOMPATIBLE' | 'SESSION_INCOMPATIBLE' | 'SIGNATURE_MISSING' | 'SIGNATURE_MALFORMED' | 'SIGNATURE_UNTRUSTED_KEY' | 'SIGNATURE_MISMATCH' | 'SIGNATURE_UNSUPPORTED' | 'MCP_STDIO_SPAWN_FAILED' | 'MCP_STDIO_EXITED' | 'MCP_STDIO_TIMEOUT' | 'TS_RESOURCE_URL_REJECTED' | 'TS_TRANSPILER_UNAVAILABLE' | 'TS_TRANSPILE_FAILED' | 'TODO_LIST_INVALID' | 'TODO_ITEM_NOT_FOUND' | 'SKILL_GENERATION_DISABLED' | 'SKILL_GENERATION_LIMIT_EXCEEDED' | 'SKILL_GENERATION_VALIDATION_FAILED' | 'DELEGATION_UNAVAILABLE' | 'DELEGATION_IN_PROGRESS' | 'DELEGATION_BUDGET_EXCEEDED' | 'PROFILE_IMPORT_INVALID' | 'PROFILE_IMPORT_VERSION_UNSUPPORTED' | 'PROFILE_IMPORT_CREDENTIAL_REJECTED' | 'PROFILE_KEY_UNAVAILABLE' | 'DICTATION_UNAVAILABLE' | 'DICTATION_PERMISSION_DENIED' | 'DICTATION_FAILED' | 'PERCEPTION_NOT_ENABLED' | 'PERCEPTION_FAILED' | 'MODEL_IMAGE_UNSUPPORTED' | 'MODEL_TOOLS_UNSUPPORTED' | 'ATTACHMENT_TOO_LARGE' | 'ATTACHMENT_TYPE_REJECTED';
 /**
  * 所有公开 API 抛出的结构化错误，code 供上层可编程处理
  * @stable
@@ -582,7 +582,7 @@ declare function escapeXml(text: string): string;
 declare function renderAvailableSkillsXml(catalog: SkillCatalog): string;
 declare const xmlRenderer: CatalogRenderer;
 //#endregion
-//#region ../runtime/dist/types-D_hoCri8.d.ts
+//#region ../runtime/dist/types-4pg-qp_I.d.ts
 //#region src/llm/streamTypes.d.ts
 /** 流式 LLM 事件（OpenAI SSE / Vercel fullStream 统一映射） */
 type LlmStreamEvent = {
@@ -701,6 +701,7 @@ type InteractionRequest = {
   id: string;
   message: string;
   schema?: JsonSchema;
+  suggestion?: InteractionSuggestion;
 } | {
   type: 'confirm';
   id: string;
@@ -719,6 +720,22 @@ type InteractionRequest = {
     label: string;
     value: unknown;
   }>;
+  suggestion?: InteractionSuggestion;
+} | {
+  /**
+   * 打开本地文件选择（FR-11.1）。与 `confirm` 分开：浏览器要求
+   * `input[type=file].click()` 处于用户手势的调用栈内，渲染层必须能识别
+   * 出“这个确认按钮点下去要同步打开选择器”，光看文案分辨不出。
+   * @experimental
+   */
+  type: 'file-pick';
+  id: string;
+  message: string;
+  /** 传给 `input.accept` 的 MIME / 扩展名列表 */
+  accept?: readonly string[];
+  multiple?: boolean;
+  /** 该文件要填的表单字段名 */
+  field?: string;
 } | {
   /**
    * 能力强制授权（require-approval）：与脚本自发 confirm 区分，UI 渲染为授权样式
@@ -735,6 +752,16 @@ interface InteractionResponse {
   value?: unknown;
   cancelled?: boolean;
 }
+/**
+ * 依据用户画像给出的建议值（FR-19.4）。**不会预填进控件**：
+ * 渲染器只能展示它并提供「采纳」入口，用户确认后才算填写。
+ * @experimental
+ */
+interface InteractionSuggestion {
+  value: unknown;
+  /** 建议依据，展示给用户判断是否采纳 */
+  reason?: string;
+}
 /** 图表规格（$chart 约定的校验后形态；渲染单一来源在 ui/chart/miniChart） */
 interface ChartSpec {
   kind: 'bar' | 'line' | 'pie';
@@ -873,7 +900,7 @@ interface UiBridge {
 interface FormField {
   name: string;
   label: string;
-  type: 'text' | 'number' | 'boolean' | 'select' | 'textarea';
+  type: 'text' | 'number' | 'boolean' | 'select' | 'textarea' | 'file';
   required?: boolean;
   description?: string;
   defaultValue?: unknown;
@@ -881,16 +908,14 @@ interface FormField {
     label: string;
     value: unknown;
   }>;
-  /** 跨会话稳定的字段标识 `<skillName>#<fieldName>`（FR-5.6）；缺省表示该字段不参与召回 */
-  fieldKey?: string;
   /**
-   * 上次填写值（FR-5.9）。**刻意不叫 defaultValue**：渲染器会把 defaultValue 直接填进控件，
-   * 而历史值可能是手机号、地址甚至凭据，必须由用户看到后主动采纳。
+   * 建议值（FR-19.4）。**刻意不叫 defaultValue**：渲染器会把 defaultValue 直接填进控件，
+   * 而建议值来自对用户过往行为的推断，可能过时或不适用，必须由用户看到后主动采纳。
    * @experimental
    */
   suggestion?: {
     value: unknown;
-    ts: number;
+    reason?: string;
   };
 }
 interface InteractionPolicy {

package/dist/ui-react.d.ts

@@ -1,5 +1,5 @@
-import { C as UiSpecEvent, D as UiSurfaceActionResponse, E as UiSurfaceActionRequest, S as UiSpecDrafts, T as UiSpecSnapshot, b as UiBridge, c as InteractionResponse, mt as UiSpecNode, s as InteractionRequest, x as UiSpecActionCapability, y as RenderResultRequest } from "./types-D_hoCri8-BnNPiZCi.js";
-import { b as InteractionSpecLabels } from "./index-Bsqg4ftU.js";
+import { C as UiSpecEvent, D as UiSurfaceActionResponse, E as UiSurfaceActionRequest, S as UiSpecDrafts, T as UiSpecSnapshot, b as UiBridge, c as InteractionResponse, mt as UiSpecNode, s as InteractionRequest, x as UiSpecActionCapability, y as RenderResultRequest } from "./types-4pg-qp_I-Gq63X8Oa.js";
+import { b as InteractionSpecLabels } from "./index-BMocOEi0.js";
 import { z } from "zod";
 import { ComponentType, ReactNode } from "react";
 import "react/jsx-runtime";

package/dist/ui-react.js

@@ -1,8 +1,8 @@
 import { r as __exportAll$1 } from "./rolldown-runtime-BOF7iYI8.js";
 import { m as WebSkillError } from "./dist-8oQRa8Xz.js";
-import { it as validateUiSpecNode, rt as validateUiSpecEvent } from "./dist-6C03DShK.js";
-import { B as toOpenUiSpecLang, I as shapeInteractionValue, O as interactionToFormModel, P as renderMiniChart, Q as chartSpecFromProps, g as applySuggestion, k as interactionToUiSpec, nt as uiCatalog, tt as renderMiniMarkdown, x as collectValues, z as toJsonRenderSpec } from "./dist-bewtXYlO.js";
-import { C as Input, S as DropdownMenuTrigger, T as Separator, _ as Checkbox, a as SpecProgress, b as DropdownMenuCheckboxItem, c as SurfaceButton, d as catalogComponentImpls, f as str, g as Button, h as Badge, i as SpecGrid, l as SurfaceField, m as useSurfaceForm, n as CatalogSurfaceProvider, o as SpecTabs, p as useCatalogSurfaceForm, r as EChart, s as SpecTimeline, u as SurfaceFormButtons, v as DataTable, w as Markdown, x as DropdownMenuContent, y as DropdownMenu } from "./catalogComponents-DV7cPpUm-C77AEEx9.js";
+import { Ct as validateUiSpecEvent, wt as validateUiSpecNode } from "./dist-DusANsrn.js";
+import { B as toOpenUiSpecLang, I as shapeInteractionValue, O as interactionToFormModel, P as renderMiniChart, Q as chartSpecFromProps, g as applySuggestion, k as interactionToUiSpec, nt as uiCatalog, tt as renderMiniMarkdown, x as collectValues, z as toJsonRenderSpec } from "./dist-DnYG2-eY.js";
+import { C as Input, S as DropdownMenuTrigger, T as Separator, _ as Checkbox, a as SpecProgress, b as DropdownMenuCheckboxItem, c as SurfaceButton, d as catalogComponentImpls, f as str, g as Button, h as Badge, i as SpecGrid, l as SurfaceField, m as useSurfaceForm, n as CatalogSurfaceProvider, o as SpecTabs, p as useCatalogSurfaceForm, r as EChart, s as SpecTimeline, u as SurfaceFormButtons, v as DataTable, w as Markdown, x as DropdownMenuContent, y as DropdownMenu } from "./catalogComponents-Dr5dFMAb-Dacibl1e.js";
 import { z } from "zod";
 import * as React$1 from "react";
 import React, { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
@@ -6367,9 +6367,19 @@ function applyPatch(node, patch) {
 	}
 	return copy;
 }
+/** 键序无关的序列化：同一份内容不能因写入顺序不同而算两个 surface（FR-21.5） */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	if (isRecord(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+	return JSON.stringify(value) ?? "null";
+}
 /** Observable, revision-checked snapshot store for framework-neutral UI surfaces. @experimental */
 var UiSurfaceStore = class {
 	#entries = /* @__PURE__ */ new Map();
+	/** 内容指纹 → 首次开的 surface id；仅在同一 runId 内合并 */
+	#fingerprints = /* @__PURE__ */ new Map();
+	/** 后到的重复 id → 已存在的 surface id，让后续 patch/complete 仍然寻址得到 */
+	#aliases = /* @__PURE__ */ new Map();
 	#listeners = /* @__PURE__ */ new Set();
 	#snapshots = [];
 	#patchEmitTimer;
@@ -6383,23 +6393,36 @@ var UiSurfaceStore = class {
 	apply(event) {
 		event = validateUiSpecEvent(event);
 		switch (event.type) {
-			case "open":
-				this.#entries.set(event.id, {
+			case "open": {
+				const snapshot = {
 					id: event.id,
 					node: structuredClone(event.node),
 					...event.actions ? { actions: structuredClone(event.actions) } : {},
 					revision: 0,
 					status: "active",
 					...event.runId ? { runId: event.runId } : {}
-				});
+				};
+				const fingerprint = this.#fingerprint(event);
+				const merged = fingerprint === void 0 ? void 0 : this.#fingerprints.get(fingerprint);
+				if (merged !== void 0 && this.#entries.has(merged)) {
+					this.#aliases.set(event.id, merged);
+					this.#entries.set(merged, {
+						...snapshot,
+						id: merged
+					});
+				} else {
+					if (fingerprint !== void 0) this.#fingerprints.set(fingerprint, event.id);
+					this.#entries.set(event.id, snapshot);
+				}
 				break;
+			}
 			case "patch": {
 				const current = this.#entry(event.id);
 				this.#assertRunId(current, event.runId);
 				if (current.status !== "active" || event.revision !== current.revision + 1) throw new WebSkillError("VALIDATION_FAILED", `Surface patch revision is invalid for "${event.id}"`);
 				let node = current.node;
 				for (const operation of event.operations) node = applyPatch(node, operation);
-				this.#entries.set(event.id, {
+				this.#entries.set(current.id, {
 					...current,
 					node: validateUiSpecNode(node),
 					revision: event.revision
@@ -6410,7 +6433,7 @@ var UiSurfaceStore = class {
 				const current = this.#entry(event.id);
 				this.#assertRunId(current, event.runId);
 				if (event.revision !== current.revision) throw new WebSkillError("VALIDATION_FAILED", `Surface completion revision is invalid for "${event.id}"`);
-				this.#entries.set(event.id, {
+				this.#entries.set(current.id, {
 					...current,
 					status: "complete"
 				});
@@ -6419,7 +6442,7 @@ var UiSurfaceStore = class {
 			case "error": {
 				const current = this.#entry(event.id);
 				this.#assertRunId(current, event.runId);
-				this.#entries.set(event.id, {
+				this.#entries.set(current.id, {
 					...current,
 					status: "error",
 					error: {
@@ -6432,7 +6455,7 @@ var UiSurfaceStore = class {
 			case "cancel": {
 				const current = this.#entry(event.id);
 				this.#assertRunId(current, event.runId);
-				this.#entries.set(event.id, {
+				this.#entries.set(current.id, {
 					...current,
 					status: "cancelled"
 				});
@@ -6446,8 +6469,16 @@ var UiSurfaceStore = class {
 			this.#emit();
 		}
 	}
+	/** 跨 run 的相同界面是合法重复（用户又问了一次），所以无 runId 时不合并 */
+	#fingerprint(event) {
+		if (event.runId === void 0) return void 0;
+		return `${event.runId}\u0000${stableStringify({
+			node: event.node,
+			actions: event.actions ?? null
+		})}`;
+	}
 	#entry(id) {
-		const entry = this.#entries.get(id);
+		const entry = this.#entries.get(this.#aliases.get(id) ?? id);
 		if (!entry) throw new WebSkillError("VALIDATION_FAILED", `Unknown UI surface "${id}"`);
 		return entry;
 	}
@@ -6625,25 +6656,37 @@ var ReactBridgeState = class {
 	}
 };
 /**
-* 历史值以**建议**形态出现（FR-5.9）：控件初始值仍为空，
+* 建议值以**建议**形态出现（FR-19.4）：控件初始值仍为空，
 * 用户点「使用」才写入。切勿改成 defaultValue。
 */
 function Suggestion({ control, onUse }) {
 	if (control.suggestion === void 0) return null;
 	const preview = String(control.suggestion.value);
+	const reason = control.suggestion.reason;
 	return /* @__PURE__ */ jsxs("div", {
 		className: "webskill-form__suggestion",
 		"data-webskill-suggestion": control.name,
-		children: [/* @__PURE__ */ jsxs("span", {
-			className: "webskill-form__suggestion-value",
-			children: ["Last entered: ", preview]
-		}), /* @__PURE__ */ jsx("button", {
-			type: "button",
-			className: "webskill-form__suggestion-use",
-			"data-webskill-suggestion-use": control.name,
-			onClick: onUse,
-			children: "Use"
-		})]
+		children: [
+			/* @__PURE__ */ jsxs("span", {
+				className: "webskill-form__suggestion-value",
+				children: ["Suggested: ", preview]
+			}),
+			reason ? /* @__PURE__ */ jsxs("span", {
+				className: "webskill-form__suggestion-reason",
+				children: [
+					"(",
+					reason,
+					")"
+				]
+			}) : null,
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "webskill-form__suggestion-use",
+				"data-webskill-suggestion-use": control.name,
+				onClick: onUse,
+				children: "Use"
+			})
+		]
 	});
 }
 function Control({ control, invalid }) {
@@ -7493,7 +7536,7 @@ function OpenUiSpecSurface({ spec, surfaceId, actions, onAction }) {
 	const [unavailable, setUnavailable] = useState(false);
 	useEffect(() => {
 		let cancelled = false;
-		import("./openUiLibrary-W3Ce896k-ClFTRZFs.js").then((loaded) => {
+		import("./openUiLibrary-Bdrji9qK-DzAxRlTY.js").then((loaded) => {
 			if (!cancelled) setModule(loaded);
 		}).catch(() => {
 			if (!cancelled) setUnavailable(true);

package/dist/ui-vue.d.ts

@@ -1,4 +1,4 @@
-import { b as UiBridge, c as InteractionResponse, s as InteractionRequest, y as RenderResultRequest } from "./types-D_hoCri8-BnNPiZCi.js";
+import { b as UiBridge, c as InteractionResponse, s as InteractionRequest, y as RenderResultRequest } from "./types-4pg-qp_I-Gq63X8Oa.js";
 import { PropType } from "vue";
 //#region ../ui-vue/dist/index.d.ts
 //#region src/bridgeState.d.ts