@webskill/chatbot 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AgentLoopConfig, ApprovalScope, BridgeCapabilities, DataSourceInfo, DocxTextExtractor, ExternalSkillProvider, ExternalToolSource, FileSystemProvider, HookRunner, InteractionRequest, InteractionResponse, LifecycleEventInit, LinkedDocumentReader, LlmClient, NetworkPolicy, Page, PageQuery, PdfTextExtractor, RenderBlock, RenderResultRequest, RunSnapshot, RunSnapshotListEntry, RuntimePhase, RuntimeRun, ScriptExecutor, SessionStore, SkillCandidateMarker, SkillCatalogEntry, SkillIntegrityGuard, SkillOutcomeReporter, SkillStateGuard, UiBridge, UiSpecDrafts, UiSpecEvent, UiSpecSnapshot, UiSurfaceActionRequest, UiSurfaceActionResponse, UserProfile, UserProfileExport, WebSkillErrorCode, XlsxTextExtractor, diffUserProfile } from "@webskill/sdk";
+import { AgentLoopConfig, ApprovalScope, BridgeCapabilities, DataSourceInfo, DocumentSurfaceHost, DocxTextExtractor, ExternalSkillProvider, ExternalToolSource, FileSystemProvider, HookRunner, InteractionRequest, InteractionResponse, LifecycleEventInit, LinkedDocumentReader, LlmClient, NetworkPolicy, Page, PageQuery, PdfTextExtractor, RenderBlock, RenderResultRequest, RunSnapshot, RunSnapshotListEntry, RuntimePhase, RuntimeRun, ScriptExecutor, SessionStore, SkillCandidateMarker, SkillCatalogEntry, SkillIntegrityGuard, SkillOutcomeReporter, SkillStateGuard, UiBridge, UiSpecDrafts, UiSpecEvent, UiSpecSnapshot, UiSurfaceActionRequest, UiSurfaceActionResponse, UserProfile, UserProfileExport, WebSkillErrorCode, XlsxTextExtractor, diffUserProfile } from "@webskill/sdk";
 import { SandboxMode, TypeScriptSupportOptions } from "@webskill/sdk/browser";
 import { CustomSurfaceActionEvent, ReactBridgeState, SpecInteractionChannel, SurfaceRegistry, UiSurfaceActionEvent } from "@webskill/sdk/ui-react";
 import { DownloadedFileConsent, DownloadedFileReader, PageActionPolicy, PagePerceptionPolicy, PerceptionPagingBudget, PerceptionRecord, SkillCandidateSink, TodoItem } from "@webskill/sdk/agent";
@@ -57,6 +57,23 @@ interface DataSourceInfo$1 {
   provenance?: 'page-declared' | 'tool-projection';
 }
 //#endregion
+//#region ../runtime/src/interaction/documentSurface.d.ts
+/**
+ * 渲染侧端口；由 chatbot 装配，`undefined` 表示本宿主没有文档面（按钮整个不渲染）。
+ *
+ * 收的是**产物文件名**，不是路径：路径由引擎按 run 拼出并做包含校验，
+ * 让声明树给完整路径等于凭空开一个读取面。
+ * @experimental
+ */
+interface DocumentSurfacePort {
+  open(request: {
+    runId: string;
+    artifact: string;
+    style?: string;
+    dataSource: string;
+  }): Promise<void>;
+}
+//#endregion
 //#region ../runtime/src/sandbox/bridgeProtocol.d.ts
 /**
  * 能力模式：true 直通 / false 关闭（TOOL_UNSUPPORTED）/ 'require-approval' 调用前强制授权
@@ -201,6 +218,18 @@ interface RuntimeSandboxConfig {
    * 而本能力的「需批准」是恒定的，放进去会凭空多出一个「开且不批准」的非法组合。
    */
   downloadedFiles: boolean;
+  /**
+   * 让技能脚本读用户本轮上传的文件（0.15.0 分册 17）。缺省 `false`。
+   *
+   * **不放进 `capabilities`**，理由同 `downloadedFiles`：本能力的「需批准」是恒定的。
+   * 关闭时脚本上下文里连那两个成员都不存在，而不是存在但总失败。
+   */
+  uploadFiles: boolean;
+  /**
+   * 单个上传文件交给脚本的字节上限（分册 17）。超出即拒，**不截断**
+   * ——截一半的 xlsx / 图片解不开，而脚本看不出它残缺。
+   */
+  maxUploadFileBytes: number;
 }
 /**
  * 只做类型擦除，不做类型检查。`esbuildUrl` 为绝对 http(s) 地址时按 `remoteUrl` 判定；
@@ -492,7 +521,7 @@ interface ChatbotHostAdapter {
    * PDF 仍然默认直传，能读的端点拿到的还是原件；不注入即没有回退能力。
    */
   pdfExtractor?: PdfTextExtractor;
-  /** 文档读取留痕出口（FR-22.6） */
+  /** 文档读取留痕出口（FR-22.6）；分册 17 的 `upload.file.read` 也走这条 */
   documentAudit?: {
     append(event: {
       type: string;
@@ -513,6 +542,15 @@ interface ChatbotHostAdapter {
     /** 「不再询问」的记忆端口；不注入即每次都问 */
     consent?: DownloadedFileConsent;
   };
+  /**
+   * 文档投放面（0.15.0 分册 13）。宿主交出 viewer 页地址、投放前确认与审计出口，
+   * 三件都在 `createDocumentSurfaceHost` 的选项里。
+   *
+   * **不注入即 `OpenDocument` 按钮整个不渲染**——与 `pagePerception` 同一条装配规矩，
+   * 设置抽屉里没有也不会有开关。技能可经 `context.documentSurface` 提前探测。
+   * @experimental
+   */
+  documentSurface?: DocumentSurfaceHost;
 }
 //#endregion
 //#region src/core/chatEngine.d.ts
@@ -646,6 +684,16 @@ declare class ChatEngine {
   setRenderer(renderer: RendererKind): void;
   /** 非 native 三档共用的交互通道（Chatbot 的 SpecInteraction 订阅/attach；core 只产出 catalog 节点树） */
   get interactionChannel(): SpecInteractionChannel;
+  /**
+   * 文档投放端口（0.15.0 分册 13）。宿主没注入 `adapter.documentSurface` 时为 `undefined`，
+   * 渲染侧据此整个不渲染按钮。
+   *
+   * 端口实现落在引擎里而不是宿主里，是因为「产物在哪、技能叫什么」这两件事只有引擎知道：
+   * 交给宿主就等于把产物目录布局变成宿主必须复刻的知识，两个宿主各抄一份必然分叉，
+   * 而那正是本册要消灭的东西。
+   * @experimental
+   */
+  get documentSurface(): DocumentSurfacePort | undefined;
   /** 探测 @a2ui/lit 是否安装（Appearance/设置区 A2UI 档置灰判定） */
   probeA2uiAvailability(): Promise<boolean>;
   onEvent(listener: (event: ChatEvent) => void): () => void;
@@ -1467,6 +1515,7 @@ declare const chatbotDictionary: {
     'surface.readOnlySnapshot': string;
     'surface.suggested': string;
     'surface.useSuggestion': string;
+    'surface.openDocument': string;
     'surface.control.previousPage': string;
     'surface.control.previous': string;
     'surface.control.nextPage': string;
@@ -1828,6 +1877,7 @@ declare const chatbotDictionary: {
     'surface.readOnlySnapshot': string;
     'surface.suggested': string;
     'surface.useSuggestion': string;
+    'surface.openDocument': string;
     'surface.control.previousPage': string;
     'surface.control.previous': string;
     'surface.control.nextPage': string;
@@ -2192,6 +2242,7 @@ declare const useT: () => TranslateFn<{
     'surface.readOnlySnapshot': string;
     'surface.suggested': string;
     'surface.useSuggestion': string;
+    'surface.openDocument': string;
     'surface.control.previousPage': string;
     'surface.control.previous': string;
     'surface.control.nextPage': string;
@@ -2553,6 +2604,7 @@ declare const useT: () => TranslateFn<{
     'surface.readOnlySnapshot': string;
     'surface.suggested': string;
     'surface.useSuggestion': string;
+    'surface.openDocument': string;
     'surface.control.previousPage': string;
     'surface.control.previous': string;
     'surface.control.nextPage': string;
@@ -3019,6 +3071,6 @@ declare function ErrorCard({ code, message, loopLimits, onOpenSettings, onDismis
  * Version of the published `@webskill/chatbot` package, injected at build time.
  * @stable
  */
-declare const CHATBOT_VERSION = "0.11.0";
+declare const CHATBOT_VERSION = "0.12.0";
 //#endregion
 export { A2uiSurfaceHost, type A2uiSurfaceHostProps, A2uiSurfaceSnapshotHost, type A2uiSurfaceSnapshotHostProps, type AppearanceChange, CHATBOT_VERSION, type ChatAttachmentInput, type ChatAttachmentMeta, type ChatContentPart, ChatEngine, type ChatEngineOptions, type ChatEvent, type ChatInteractionRecord, type ChatLayout, type ChatMessage, type ChatRunPhase, type ChatSessionListResult, type ChatSessionMeta, type ChatTheme, type ChatThinking, type ChatTokenUsage, type ChatToolCall, Chatbot, type ChatbotConfig, type ChatbotGovernancePorts, type ChatbotHostAdapter, type ChatbotProps, CompositeUiBridge, type CompositeUiBridgeDeps, DEFAULT_RENDERER_CAPABILITIES, DEFAULT_RUNTIME_CONFIG_STORAGE_KEY, type DownloadableFile, ErrorCard, type ErrorCardProps, InteractionCard, type InteractionCardProps, InterruptedBanner, type InterruptedBannerProps, type Locale, type LocalizedText, OpenUiSurfaceHost, type OpenUiSurfaceHostProps, OpenUiSurfaceSnapshotHost, type OpenUiSurfaceSnapshotHostProps, type QuickPrompt, type QuickPromptIconName, type RendererCapability, type RendererKind, type ResolvedChatLayout, ResultBlockList, type ResultBlockListProps, ResultBlocksPro, type ResultBlocksProProps, type RunSnapshot, type RuntimeAppearanceConfig, type RuntimeConfig, type RuntimeConfigStore, type RuntimeQuickPrompt, type RuntimeRendererId, type SandboxExecutorDeps, type SettingsSectionId, SkillBadges, SpecInteraction, type SpecInteractionProps, VercelPayloadPreview, type VercelPayloadPreviewProps, VercelSurfaceHost, type VercelSurfaceHostProps, VercelSurfaceSnapshotHost, type VercelSurfaceSnapshotHostProps, chatbotDictionary, configureA2uiMarkdown, createLocalStorageRuntimeConfigStore, createMemoryRuntimeConfigStore, isLlmEntryUsable, pickUsableLlmEntry, probeA2uiAvailability, probeOpenUiAvailability, sandboxExecutorDeps, useT };

package/dist/index.js

@@ -6,7 +6,7 @@ import { t as yaml } from "./yaml-C888tCbJ.js";
 import { t as json } from "./json-BOcU6nei.js";
 import { t as typescript } from "./typescript-DAau_Qyl.js";
 import { t as jsx$1 } from "./jsx-D2Jv0wvt.js";
-import { BEHAVIOR_RECORDS_KEY, DEFAULT_LOOP_LIMITS, DEFAULT_USER_PROFILE_LIMITS, EventBus, FsArtifactStore, FsMemoryStore, FsRunSnapshotStore, FsRunTraceStore, FsSessionStore, FsToolStepStore, FullDisclosureRouter, SUPPORTED_DOCUMENT_MIME, SerializingMemoryStore, SkillDiscovery, USER_PROFILE_KEY, WebSkillError, WebSkillRuntime, applyUserProfileImport, assertRemoteUrlAllowed, atomicWriteText, diffUserProfile, exportUserProfile, formatAttachmentText, isUnsupportedRunSnapshot, messageOf, readBehaviorRecords, readUserProfile, refineUserProfile, summarizeRunUsage, summarizeToolCalls, textParts } from "@webskill/sdk";
+import { BEHAVIOR_RECORDS_KEY, DEFAULT_LOOP_LIMITS, DEFAULT_USER_PROFILE_LIMITS, EventBus, FsArtifactStore, FsMemoryStore, FsRunSnapshotStore, FsRunTraceStore, FsSessionStore, FsToolStepStore, FullDisclosureRouter, SUPPORTED_DOCUMENT_MIME, SerializingMemoryStore, SkillDiscovery, USER_PROFILE_KEY, WebSkillError, WebSkillRuntime, applyUserProfileImport, assertRemoteUrlAllowed, assertSafePathSegment, atomicWriteText, diffUserProfile, exportUserProfile, formatAttachmentText, isUnsupportedRunSnapshot, messageOf, readBehaviorRecords, readUserProfile, refineUserProfile, resolveInsideRoot, sanitizeUntrustedLine, summarizeRunUsage, summarizeToolCalls, textParts } from "@webskill/sdk";
 import { BrowserWorkerScriptExecutor, checkDictationAvailability, compressImageToBudget, createEncryptedMemoryStore, createLlmClient, deleteMemoryEncryptionKey, openMemoryEncryptionKey, probeChromeBuiltinAvailability, startDictation } from "@webskill/sdk/browser";
 import { JsonRenderSpecSurface, NativeSpecSurface, OpenUiSpecSurface, ReactBridgeState, SpecInteractionChannel, SurfaceFormTextsProvider, UiSurfaceSnapshotList, probeJsonRenderAvailability } from "@webskill/sdk/ui-react";
 import { A2UI_SPEC_FORM_PATH, collectFormScopes, createUiCatalogToolSource, fromA2uiSpecAction, fromA2uiSurfaceAction, interactionToFormModel, interactionToUiSpec, loadOpenUiPeers, loadWebSkillLitCatalog, renderMiniChart, shapeInteractionValue, toA2uiSpecMessages, toA2uiSurfaceAction, toVercelToolInvocation, uiCatalog } from "@webskill/sdk/ui";
@@ -30416,6 +30416,11 @@ const DEFAULT_MAX_DOCUMENT_TEXT_BYTES = 512e3;
 * 结构化数据不是文档，量级差一个数量级；超出**只拒不截**——截断的 JSON 解不出来。
 */
 const DEFAULT_MAX_DATA_SOURCE_BYTES = 1024e3;
+/**
+* 单个上传文件交给脚本的字节上限（0.15.0 分册 17，FR-17.5）：20 MB。
+* 取得比模型图片预算宽：字节不进模型上下文，只进脚本，护的是内存不是 token。
+*/
+const DEFAULT_MAX_UPLOAD_FILE_BYTES = 20 * 1024 * 1024;
 
 //#endregion
 //#region ../runtime/src/engine/limits.ts
@@ -30589,7 +30594,9 @@ function defaultRuntimeConfig() {
 				allowPrivateHosts: false
 			},
 			typescript: { enabled: false },
-			downloadedFiles: false
+			downloadedFiles: false,
+			uploadFiles: false,
+			maxUploadFileBytes: DEFAULT_MAX_UPLOAD_FILE_BYTES
 		},
 		llm: { entries: [] },
 		agentCapabilities: {
@@ -31708,6 +31715,7 @@ const chatbotDictionary = defineDictionary({
 		"surface.readOnlySnapshot": "This is a saved record — its actions are no longer available.",
 		"surface.suggested": "Suggested:",
 		"surface.useSuggestion": "Use",
+		"surface.openDocument": "Open document",
 		"surface.control.previousPage": "Previous page",
 		"surface.control.previous": "Previous",
 		"surface.control.nextPage": "Next page",
@@ -32069,6 +32077,7 @@ const chatbotDictionary = defineDictionary({
 		"surface.readOnlySnapshot": "这是已保存的记录，其中的操作已不可用。",
 		"surface.suggested": "建议：",
 		"surface.useSuggestion": "使用",
+		"surface.openDocument": "打开文档",
 		"surface.control.previousPage": "上一页",
 		"surface.control.previous": "上一页",
 		"surface.control.nextPage": "下一页",
@@ -32597,11 +32606,18 @@ var ChatEngine = class {
 	#ready;
 	/** 已装配的 runtime（cancel 等同步委托用；未装配时为 undefined） */
 	#runtime;
+	/**
+	* 每轮 `send()` 开头刷新的运行时配置快照（0.15.0 分册 15 · FR-15.6）。
+	* 只给那些必须同步回答、又不能等到重建运行时的开关用。
+	*/
+	#liveConfig;
 	#handles = /* @__PURE__ */ new Map();
 	#currentSessionId;
 	#listeners = /* @__PURE__ */ new Set();
 	/** runId → 已激活技能累积（skill-activated 事件用；终态清理） */
 	#runSkills = /* @__PURE__ */ new Map();
+	/** 文档投放端口只构造一次：渲染侧把它放进 memo 依赖，每次取新对象会触发无谓重渲染 */
+	#documentSurfacePort;
 	/** 当前渲染框架档（复合 uiBridge 分发；setRenderer 热切换） */
 	#renderer;
 	/** 非 native 三档共用的交互通道（Chatbot 的 SpecInteraction attach 后生效） */
@@ -32810,6 +32826,52 @@ var ChatEngine = class {
 	get interactionChannel() {
 		return this.#interactionChannel;
 	}
+	/**
+	* 文档投放端口（0.15.0 分册 13）。宿主没注入 `adapter.documentSurface` 时为 `undefined`，
+	* 渲染侧据此整个不渲染按钮。
+	*
+	* 端口实现落在引擎里而不是宿主里，是因为「产物在哪、技能叫什么」这两件事只有引擎知道：
+	* 交给宿主就等于把产物目录布局变成宿主必须复刻的知识，两个宿主各抄一份必然分叉，
+	* 而那正是本册要消灭的东西。
+	* @experimental
+	*/
+	get documentSurface() {
+		const host = this.#adapter.documentSurface;
+		if (!host) return void 0;
+		return this.#documentSurfacePort ??= { open: async ({ runId, artifact, style, dataSource }) => {
+			const dir = `${this.#chatRoot}/artifacts/${runId}`;
+			const html = await this.#adapter.storage.readText(this.#artifactPath(dir, artifact));
+			const css = style === void 0 ? void 0 : await this.#adapter.storage.readText(this.#artifactPath(dir, style));
+			await host.open({
+				skillName: await this.#skillNamesOfRun(runId),
+				dataSource: sanitizeUntrustedLine(dataSource),
+				document: {
+					html,
+					...css === void 0 ? {} : { css }
+				}
+			});
+		} };
+	}
+	/**
+	* 产物名 → 绝对路径。`assertSafePathSegment` + `resolveInsideRoot` 两道都不是可选写法：
+	* 少了它们，「组件只收产物名」就退化成「组件收完整路径」，凭空开出一个读取面。
+	*/
+	#artifactPath(dir, artifact) {
+		assertSafePathSegment(artifact, "artifact");
+		return resolveInsideRoot(dir, artifact);
+	}
+	/**
+	* 这次 run 激活过的技能名。它是授权告知的主语，因此**不能**由发出 surface 的技能自报——
+	* 那等于让被授权方自己写授权提示。
+	*
+	* 进行中的 run 读内存累积；已结束的（历史消息里的按钮就是这种）读 trace，
+	* 只读内存会在 run 收尾清表后得到空串。
+	*/
+	async #skillNamesOfRun(runId) {
+		const live = this.#runSkills.get(runId);
+		if (live && live.size > 0) return [...live].sort().join(", ");
+		return [...(await this.#traceStore.get(runId).catch(() => void 0))?.activeSkills ?? []].sort().join(", ");
+	}
 	/** 探测 @a2ui/lit 是否安装（Appearance/设置区 A2UI 档置灰判定） */
 	probeA2uiAvailability() {
 		return probeA2uiAvailability();
@@ -33007,6 +33069,7 @@ var ChatEngine = class {
 	async send(text, attachments = []) {
 		if (this.#disposed) throw new WebSkillError("RUN_FAILED", "This ChatEngine was disposed; create a new one to keep chatting.");
 		if (text.trim() === "" && attachments.length === 0) return;
+		this.#liveConfig = await this.#runtimeConfigStore()?.load();
 		const admitted = await this.#admitAttachments(attachments);
 		const runtime = await this.#ensureReady();
 		const sessionId = this.#currentSessionId ?? (await this.createSession({ title: truncateTitle(text) })).id;
@@ -33034,12 +33097,36 @@ var ChatEngine = class {
 		});
 		const handle = this.#sessionHandle(runtime, sessionId);
 		try {
-			const result = await handle.run(prompt);
+			const uploadFiles = this.#uploadFilesFor(admitted.accepted);
+			const result = await handle.run(prompt, uploadFiles ? { uploadFiles } : {});
 			await this.#finishRun(sessionId, result);
 		} catch (e) {
 			this.#emitError(e);
 		}
 	}
+	/**
+	* 本轮触发消息里的附件，包成只对这一次 run 生效的读取端口（0.15.0 分册 17）。
+	* 开关关着就返回 undefined → 脚本上下文里那两个成员整个不存在，
+	* 与「本轮没传附件」（空数组）分得开。
+	*/
+	#uploadFilesFor(attachments) {
+		if (!(this.#liveConfig?.sandbox.uploadFiles ?? false)) return void 0;
+		const files = attachments.map((a) => ({ ...a }));
+		const infos = files.map((a) => ({
+			id: a.id,
+			name: a.name,
+			contentType: a.contentType,
+			size: a.size
+		}));
+		return {
+			list: async () => infos,
+			read: async (id) => {
+				const attachment = files.find((a) => a.id === id);
+				if (!attachment) throw new WebSkillError("UPLOAD_FILE_NOT_FOUND", `Upload file "${id}" is not part of the message that started this run`);
+				return this.#adapter.storage.readBinary(`${this.attachmentsRoot}/${attachment.path}`);
+			}
+		};
+	}
 	/** 附件落盘根目录（composer 附件适配器写入，send 时读回） */
 	get attachmentsRoot() {
 		return `${this.#chatRoot}/attachments`;
@@ -33185,6 +33272,13 @@ var ChatEngine = class {
 		return this.#ready;
 	}
 	/**
+	* `sandbox.downloadedFiles` 的实时取值（分册 15 · FR-15.6）。
+	* 优先读每轮 `send()` 刷新的快照；还没发过消息时回落到装配期的那一份。
+	*/
+	#sandboxDownloadedFiles(assembled) {
+		return (this.#liveConfig ?? assembled)?.sandbox.downloadedFiles === true;
+	}
+	/**
 	* LLM 选择链：options.llm（demo/测试）→ `RuntimeConfig.llm` 里选中/默认的条目
 	* → 内置演示。streaming=false 时包装掉 stream（AgentLoop 走 complete）。
 	*/
@@ -33450,7 +33544,7 @@ var ChatEngine = class {
 			...this.#adapter.downloads ? [createDownloadedFileToolSource({ policy: new DownloadedFilePolicy({
 				reader: this.#adapter.downloads.reader,
 				ui: this.#uiBridge,
-				capabilityEnabled: () => rc?.sandbox.downloadedFiles === true,
+				capabilityEnabled: () => this.#sandboxDownloadedFiles(rc),
 				imageCapable: async () => {
 					return entryCapabilities(pickLlmEntry(await this.#runtimeConfigStore()?.load(), this.#selectedModelId)).image;
 				},
@@ -33499,6 +33593,9 @@ var ChatEngine = class {
 			...this.#adapter.xlsxExtractor ? { xlsxExtractor: this.#adapter.xlsxExtractor } : {},
 			...this.#adapter.pdfExtractor ? { pdfExtractor: this.#adapter.pdfExtractor } : {},
 			...this.#adapter.documentAudit ? { documentAudit: this.#adapter.documentAudit } : {},
+			...this.#adapter.documentAudit ? { uploadFileAudit: this.#adapter.documentAudit } : {},
+			maxUploadFileBytes: rc?.sandbox.maxUploadFileBytes ?? defaultRuntimeConfig().sandbox.maxUploadFileBytes,
+			...this.#adapter.documentSurface ? { documentSurface: true } : {},
 			...toolStepStore ? { toolSteps: toolStepStore } : {}
 		};
 		const runtime = new WebSkillRuntime({
@@ -33801,7 +33898,8 @@ function ChatbotSurfaceTexts({ children }) {
 			arrayFirstItemOnly: t("surface.arrayFirstItemOnly"),
 			readOnlySnapshot: t("surface.readOnlySnapshot"),
 			suggested: t("surface.suggested"),
-			useSuggestion: t("surface.useSuggestion")
+			useSuggestion: t("surface.useSuggestion"),
+			openDocument: t("surface.openDocument")
 		}), [t]),
 		hostControlTexts: useMemo(() => ({
 			previousPage: t("surface.control.previousPage"),
@@ -45665,7 +45763,7 @@ function resolveByNonce(bridge, snapshots, event) {
 * 一组 surface 快照 → 当前渲染档的宿主（分册 17）。
 * 四档与原 `HistoricalSurfaces` 一一对应；差别只在 `bridge` 存在时补上动作/草稿回接。
 */
-function SurfaceByRenderer({ snapshots, renderer, registry, bridge }) {
+function SurfaceByRenderer({ snapshots, renderer, registry, bridge, documentSurface }) {
 	const drafts = bridge && snapshots[0]?.runId ? bridge.surfaceDrafts(snapshots[0].runId) : void 0;
 	const onDraftChange = bridge ? (event) => bridge.setSurfaceDraft(event.runId, event.surfaceId, event.value) : void 0;
 	if (renderer === "a2ui") {
@@ -45704,6 +45802,7 @@ function SurfaceByRenderer({ snapshots, renderer, registry, bridge }) {
 	return /* @__PURE__ */ jsx(UiSurfaceSnapshotList, {
 		snapshots,
 		...registry ? { registry } : {},
+		...documentSurface ? { documentSurface } : {},
 		...bridge ? { onAction: (event) => resolveByNonce(bridge, snapshots, event) } : {},
 		...drafts ? { drafts } : {},
 		...onDraftChange ? { onDraftChange } : {}
@@ -45738,6 +45837,7 @@ function InlineSurface({ surfaceId }) {
 			snapshots: [snapshot],
 			...ctx.renderer ? { renderer: ctx.renderer } : {},
 			...ctx.registry ? { registry: ctx.registry } : {},
+			...ctx.documentSurface ? { documentSurface: ctx.documentSurface } : {},
 			...!persisted && bridge ? { bridge } : {}
 		})
 	});
@@ -46571,7 +46671,7 @@ function SkillBadges({ skills }) {
 //#endregion
 //#region src/react/WebSkillMessageExtensions.tsx
 /** WebSkill domain content rendered beneath a Base message without choosing its chat layout. */
-function WebSkillMessageExtensions({ message, onDownload, surfaceRegistry, renderer }) {
+function WebSkillMessageExtensions({ message, onDownload, surfaceRegistry, documentSurface, renderer }) {
 	const t = useT();
 	if (message.role === "user") return null;
 	const contentParts = message.contentParts ?? [];
@@ -46592,7 +46692,8 @@ function WebSkillMessageExtensions({ message, onDownload, surfaceRegistry, rende
 				children: /* @__PURE__ */ jsx(SurfaceByRenderer, {
 					snapshots: renderable,
 					...renderer ? { renderer } : {},
-					...surfaceRegistry ? { registry: surfaceRegistry } : {}
+					...surfaceRegistry ? { registry: surfaceRegistry } : {},
+					...documentSurface ? { documentSurface } : {}
 				})
 			}) : null,
 			renderable.length < surfaces.filter((snapshot) => !inlineIds.has(snapshot.id)).length ? /* @__PURE__ */ jsx("p", {
@@ -46719,6 +46820,7 @@ function AssistantUiMessage(props) {
 		...props.bridge ? { bridge: props.bridge } : {},
 		...props.renderer ? { renderer: props.renderer } : {},
 		...props.surfaceRegistry ? { registry: props.surfaceRegistry } : {},
+		...props.documentSurface ? { documentSurface: props.documentSurface } : {},
 		...props.onDownload ? { onDownload: props.onDownload } : {}
 	}), [
 		message?.surfaces,
@@ -46727,6 +46829,7 @@ function AssistantUiMessage(props) {
 		props.bridge,
 		props.renderer,
 		props.surfaceRegistry,
+		props.documentSurface,
 		props.onDownload
 	]);
 	if (role === "user") return /* @__PURE__ */ jsxs("div", {
@@ -46782,6 +46885,7 @@ function AssistantUiMessage(props) {
 				message,
 				...props.onDownload ? { onDownload: props.onDownload } : {},
 				...props.surfaceRegistry ? { surfaceRegistry: props.surfaceRegistry } : {},
+				...props.documentSurface ? { documentSurface: props.documentSurface } : {},
 				...props.renderer ? { renderer: props.renderer } : {}
 			}) : null,
 			/* @__PURE__ */ jsx(AssistantUiMessageActions, { ...props })
@@ -48621,6 +48725,7 @@ function Chatbot({ adapter, config, locale: localeProp, theme: themeProp, render
 														modelLabels,
 														resolveAttachmentUrl,
 														...surfaceRegistry ? { surfaceRegistry } : {},
+														...engine.documentSurface ? { documentSurface: engine.documentSurface } : {},
 														renderer,
 														bridge: engine.bridge,
 														...adapter.navigation.openConsoleTrace ? { onViewTrace: adapter.navigation.openConsoleTrace } : {},
@@ -48756,7 +48861,7 @@ function VercelPayloadPreview({ bridge }) {
 * Version of the published `@webskill/chatbot` package, injected at build time.
 * @stable
 */
-const CHATBOT_VERSION = "0.11.0";
+const CHATBOT_VERSION = "0.12.0";
 
 //#endregion
 export { A2uiSurfaceHost, A2uiSurfaceSnapshotHost, CHATBOT_VERSION, ChatEngine, Chatbot, CompositeUiBridge, DEFAULT_RENDERER_CAPABILITIES, DEFAULT_RUNTIME_CONFIG_STORAGE_KEY, ErrorCard, InteractionCard, InterruptedBanner, OpenUiSurfaceHost, OpenUiSurfaceSnapshotHost, ResultBlockList, ResultBlocksPro, SkillBadges, SpecInteraction, VercelPayloadPreview, VercelSurfaceHost, VercelSurfaceSnapshotHost, chatbotDictionary, configureA2uiMarkdown, createLocalStorageRuntimeConfigStore, createMemoryRuntimeConfigStore, isLlmEntryUsable, pickUsableLlmEntry, probeA2uiAvailability, probeOpenUiAvailability, sandboxExecutorDeps, useT };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webskill/chatbot",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -26,7 +26,7 @@
     "@a2ui/web_core": "^0.10.5",
     "@lit/context": "^1.1.0",
     "@openuidev/react-lang": "0.2.8",
-    "@webskill/sdk": "^0.14.0",
+    "@webskill/sdk": "^0.15.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "zod": "^3.25.0 || ^4.0.0"