@dp-bohrium/widget-sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 本文件只记录影响使用者的变更：运行时 API、事件订阅、Manifest 要求。
 
+## 0.4.0
+
+### 新增
+
+**1. 增加文件读取与条件保存接口**
+
+- 新增 context.files.read 与 context.files.write。保存使用 expectedRevision 和稳定 mutationId，由 Host 执行权限、预算、原子替换与去重。
+- 旧 Host 只返回 content 与 encoding 时，读取仍然成功。游标、截断标记和版本是可选扩展，SDK 不补造这些字段。
+- 发出保存后若超时、中止、断线或回执无法确认，返回 write-outcome-unknown，不自动重试。
+
 ## 0.3.0
 
 ### 破坏性变更

package/README.md

@@ -174,7 +174,9 @@ SDK 发布包会生成 `dist/index.d.ts` 与对应的 declaration map，并通
 
 | grant 名 | Manifest 申请键 | SDK 调用 |
 | --- | --- | --- |
-| `files.list` / `files.metadata` / `files.read` | `files` | `context.capabilities.request({ operation, input })` |
+| `files.list` / `files.metadata` | `files` | `context.capabilities.request({ operation, input })` |
+| `files.read` | `files.read` | `context.files.read({ file, offset, length, encoding, expectedRevision? })` |
+| `files.write` | `files.write` | `context.files.write({ file, content, encoding, expectedRevision, mutationId })` |
 | `files.download` | `files.download` | `context.files.download({ file, suggestedName })` |
 | `events.read` | `events`（需列出 `topics`） | 低层分页订阅；`context.events.on(…)` 是 Host 主动推送，不需要该 grant |
 | `tasks.watch` | `tasks.watch` | `context.tasks.watch({ taskId, cursor, limit })` |
@@ -204,8 +206,9 @@ if (result.ok) {
 
 跨能力约定：
 
-- 失败以 `{ ok: false, reason, message, retryable }` 正常兑现；只有客户端超时、中止、
-  dispose 和畸形响应才 reject。
+- Host 拒绝以 `{ ok: false, reason, message, retryable }` 正常兑现；本地状态、输入、客户端超时、
+  中止、dispose 和畸形响应可 reject。`files.write` 发出后的结果不确定时兑现为
+  `write-outcome-unknown`，处理方式见下文。
 - 中止与超时统一用 `{ signal, timeoutMs }`，复用既有 MessageChannel 能力生命周期。
 - Widget 永远拿不到 Host 凭据，也不应直接调用浏览器 `fetch`：是否弹窗、记住 Origin
   授权、跟随重定向还是拒绝，全部由 Host 决定。
@@ -230,6 +233,67 @@ if (result.ok) {
   提交，重新订阅需显式传回 `events.cursor`。工具 Hook 观察的是**已经发生的**服务端
   事实，不是执行前拦截器。
 
+### 读取和保存当前文件
+
+作者 Manifest 申请 `"capabilities": { "files": { "read": true, "write": true } }`，Host 仍需独立
+授权两个能力。`files.write` 对当前 `file-preview` 绑定的已有文件作整文件条件替换；引用来自
+`request.content.file`，不能传路径、URL、别的文件 id 或指定另存位置。Host 校验引用、作用域、
+写权限和实际字节预算，成功回执表示执行端已确认持久化。SDK 不负责 ASE、晶格或文件格式转换，
+插件应使用自己的序列化器生成最终字节。
+
+`FileReadInput` / `FileReadResult`、`FileWriteInput` / `FileWriteResult`、`FileRevision`、
+`FileMutationId` 与两个 `*CapabilityResult` 类型均可从 SDK 根入口导入。`revision` 是文件内容的
+不透明版本，与渲染快照的 `RenderRequest.revision` 无关。下面的 `file` 来自当前文件预览：
+
+```ts
+const loaded = await context.files.read({
+  file, offset: 0, length: 64_000, encoding: "utf8",
+  ...(file.revision ? { expectedRevision: file.revision } : {}),
+});
+if (!loaded.ok) return showReadFailure(loaded.reason);
+if (!loaded.data.revision) return showReadOnlyFile(loaded.data.content);
+if (loaded.data.eof === false || loaded.data.truncated === true) {
+  return showFileNeedsChunkedReading();
+}
+
+const expectedRevision = loaded.data.revision;
+const content = serializeEditedModel(loaded.data.content);
+// 一次逻辑保存只生成一次；核对或重试同一内容时复用。
+const mutationId = crypto.randomUUID();
+const saved = await context.files.write({
+  file, content, encoding: "utf8", expectedRevision, mutationId,
+}, { signal: saveController.signal, timeoutMs: 15_000 });
+if (saved.ok) {
+  markSaved(saved.data.file, saved.data.revision);
+} else {
+  keepUnsavedChanges(saved.reason, mutationId);
+}
+```
+
+`read` 兼容旧 Host 的 `{ content, encoding }` 结果；`offset`、`bytesRead`、`nextOffset`、`eof`、
+`truncated` 和 `revision` 均为可选扩展。SDK 原样返回结果，只验证已提供字段，不补造游标或版本。
+没有 `revision` 时内容可展示，但不能据此保存；带 `expectedRevision` 的读取必须返回有效且匹配的
+版本，不能降级为无版本读取。Host 必须从同次读取的内容快照签发版本，不能另用 metadata/stat 补取。
+
+有游标的 `read` 按原始字节计数：使用 `nextOffset` 继续；若首块带版本，后续块携带对应
+`expectedRevision`，防止混合版本。`utf8` 字节区间可能切断多字节字符，不能用重新编码后的文本长度推断 `bytesRead`。
+二进制文件或需完整解码的分块文本使用 `base64`，先将每块解码为字节并拼接，再解码文本。
+`base64` 使用标准、带正确 padding 的编码；空文件和空字符串替换均合法。
+上面的整文件保存示例以 Host 返回完整内容为前提；缺少完整性标记时，插件需依据 Host 的读取约定
+确认内容完整，不能把一个未完成的分块直接替换为整个文件。
+
+`write` 必填读取时的 `expectedRevision` 和一次逻辑保存的 `mutationId`（1–128 个字符，只含
+字母、数字、`_ . : -` 且以字母或数字开头）。`revision-conflict` 表示当前文件已变化，应重新读取
+并由用户合并；相同 mutationId 携带不同内容会返回 `mutation-conflict`。保存成功后更新本地文件引用
+和基础版本；未修改内容的保存可以返回相同版本。
+游标元信息不是保存的前提；只有读取内容所绑定的有效版本才能用作 `expectedRevision`。
+
+SDK 不自动重试保存。调用前已中止、客户端未就绪或输入非法会 reject，且不发送请求；缺少 grant
+返回 `permission-denied`。发出后超时、中止、断线或畸形回执都不能证明未写入，返回
+`{ ok: false, reason: "write-outcome-unknown", retryable: false }`。此时保留未保存内容、原基础版本
+和 mutationId，通过 Host 核对文件版本或用**同一 mutationId、同一内容**确认结果；不要直接生成新 id
+重试，也不要提前标记已保存。新的编辑内容属于新的逻辑保存，应使用新的 mutationId。
+
 ## 测试
 
 ```ts

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export type { WidgetActivationEvent, WidgetActivationEvents, WidgetContribution, WidgetEventName, WidgetFilePreviewContribution, WidgetPanelContribution, WidgetPluginContributions, WidgetPluginManifest, WidgetToolPhase, } from "@dp-bohrium/widget-contracts";
+export type { FileMutationId, FileReadInput, FileReadResult, FileRevision, FileWriteInput, FileWriteResult, WidgetActivationEvent, WidgetActivationEvents, WidgetContribution, WidgetEventName, WidgetFilePreviewContribution, WidgetPanelContribution, WidgetPluginContributions, WidgetPluginManifest, WidgetToolPhase, } from "@dp-bohrium/widget-contracts";
 export { isWidgetActivationEvent, isWidgetEventName, WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, } from "@dp-bohrium/widget-contracts";
 export type { CompileWidgetPluginManifestOptions } from "./manifest.js";
 export { compileWidgetPluginManifest } from "./manifest.js";
 export type { HostUserEmail, HostUserEmailResult, HostUserProfile, HostUserProfileResult, WidgetHostUserClient, } from "./runtime/service.js";
-export type { FileDownloadCapabilityResult, TaskWatchCapabilityResult, UiStateReadCapabilityResult, UiStateWriteCapabilityResult, WidgetActivation, WidgetCapabilityApi, WidgetContext, WidgetDisposable, WidgetEventApi, WidgetFileApi, WidgetHandle, WidgetHostOptions, WidgetModule, WidgetRenderContext, WidgetRenderHandler, WidgetTaskApi, WidgetUiApi, WidgetUiStateApi, } from "./widget.js";
+export type { FileDownloadCapabilityResult, FileReadCapabilityResult, FileWriteCapabilityResult, TaskWatchCapabilityResult, UiStateReadCapabilityResult, UiStateWriteCapabilityResult, WidgetActivation, WidgetCapabilityApi, WidgetContext, WidgetDisposable, WidgetEventApi, WidgetFileApi, WidgetHandle, WidgetHostOptions, WidgetModule, WidgetRenderContext, WidgetRenderHandler, WidgetTaskApi, WidgetUiApi, WidgetUiStateApi, } from "./widget.js";
 export { runWidgetHost } from "./widget.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-import { i as createWidgetClient, l as WIDGET_SDK_VERSION } from "./runtime-Drr96Awx.js";
+import { i as createWidgetClient, l as WIDGET_SDK_VERSION } from "./runtime-8ppcE14g.js";
 import { WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, isWidgetActivationEvent, isWidgetEventName } from "@dp-bohrium/widget-contracts";
 //#region src/manifest.ts
 function compiledContribution(contribution) {
@@ -87,6 +87,177 @@ function createWidgetLifetime(onError) {
 	};
 }
 //#endregion
+//#region src/runtime/files.ts
+const failureReasons = /* @__PURE__ */ new Set([
+	"unsupported",
+	"permission-denied",
+	"resource-limit",
+	"invalid-reference",
+	"timeout",
+	"internal-error",
+	"revision-conflict",
+	"mutation-conflict",
+	"write-outcome-unknown",
+	"network-consent-denied",
+	"network-policy-denied",
+	"network-transport-unavailable",
+	"network-request-too-large",
+	"network-response-too-large",
+	"network-rate-limited",
+	"network-redirect-denied",
+	"network-credential-unavailable",
+	"network-scope-invalid",
+	"network-dns-denied",
+	"network-error"
+]);
+/** 文件字节协议检查；权限和持久化仍由 Host 执行。 */
+function createWidgetFileClient(dependencies) {
+	function preflight(operation, options) {
+		if (options?.signal?.aborted) throw new Error("file request aborted before dispatch");
+		const state = dependencies.state();
+		if (state === "disposed") throw new Error("client is disposed");
+		if (state !== "ready") throw new Error("Widget files are not ready");
+		if (!dependencies.granted(operation)) return {
+			ok: false,
+			reason: "permission-denied",
+			message: `${operation} is not granted`,
+			retryable: false
+		};
+	}
+	return Object.freeze({
+		async read(input, options) {
+			const denied = preflight("files.read", options);
+			if (denied) return denied;
+			if (!validReadInput(input)) invalid("read input");
+			const snapshot = {
+				...input,
+				file: { ...input.file }
+			};
+			const result = await dependencies.request({
+				operation: "files.read",
+				input: snapshot
+			}, options);
+			if (isFailure(result)) return result;
+			if (!exactKeys(result, ["ok", "data"]) || result["ok"] !== true || !validReadResult(result["data"], snapshot)) invalid("read result");
+			return {
+				ok: true,
+				data: result["data"]
+			};
+		},
+		async write(input, options) {
+			const denied = preflight("files.write", options);
+			if (denied) return denied;
+			if (!validWriteInput(input)) invalid("write input");
+			const snapshot = {
+				...input,
+				file: { ...input.file }
+			};
+			const bytes = snapshot.encoding === "utf8" ? new TextEncoder().encode(snapshot.content).byteLength : base64Bytes(snapshot.content);
+			if (bytes === null) invalid("write input encoding");
+			try {
+				const result = await dependencies.request({
+					operation: "files.write",
+					input: snapshot
+				}, options);
+				if (isFailure(result)) return result;
+				if (!exactKeys(result, ["ok", "data"]) || result["ok"] !== true || !validWriteResult(result["data"], snapshot, bytes)) invalid("write result");
+				return {
+					ok: true,
+					data: result["data"]
+				};
+			} catch {
+				return {
+					ok: false,
+					reason: "write-outcome-unknown",
+					message: "File write outcome is unknown; reconcile the file revision before retrying with the same mutationId",
+					retryable: false
+				};
+			}
+		}
+	});
+}
+function validReadInput(value) {
+	return exactKeys(value, [
+		"file",
+		"offset",
+		"length",
+		"encoding"
+	], ["expectedRevision"]) && isFile(value["file"]) && nonnegative(value["offset"]) && nonnegative(value["length"]) && value["length"] > 0 && encoding(value["encoding"]) && (!Object.hasOwn(value, "expectedRevision") || revision(value["expectedRevision"]));
+}
+function validWriteInput(value) {
+	return exactKeys(value, [
+		"file",
+		"content",
+		"encoding",
+		"expectedRevision",
+		"mutationId"
+	]) && isFile(value["file"]) && typeof value["content"] === "string" && encoding(value["encoding"]) && (value["encoding"] !== "utf8" || !/[\uD800-\uDFFF]/u.test(value["content"])) && revision(value["expectedRevision"]) && typeof value["mutationId"] === "string" && value["mutationId"].length <= 128 && /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/u.test(value["mutationId"]);
+}
+function validReadResult(value, input) {
+	if (!exactKeys(value, ["content", "encoding"], [
+		"offset",
+		"bytesRead",
+		"nextOffset",
+		"eof",
+		"truncated",
+		"revision"
+	]) || typeof value["content"] !== "string" || value["encoding"] !== input.encoding || Object.hasOwn(value, "offset") && value["offset"] !== input.offset || Object.hasOwn(value, "bytesRead") && (!nonnegative(value["bytesRead"]) || value["bytesRead"] > input.length || value["bytesRead"] === 0 && value["content"] !== "") || Object.hasOwn(value, "nextOffset") && (!nonnegative(value["nextOffset"]) || value["nextOffset"] < input.offset || value["nextOffset"] - input.offset > input.length || Object.hasOwn(value, "bytesRead") && value["nextOffset"] !== input.offset + value["bytesRead"]) || Object.hasOwn(value, "eof") && typeof value["eof"] !== "boolean" || Object.hasOwn(value, "truncated") && typeof value["truncated"] !== "boolean" || value["eof"] === false && value["bytesRead"] === 0 || Object.hasOwn(value, "revision") && !revision(value["revision"]) || input.expectedRevision !== void 0 && value["revision"] !== input.expectedRevision) return false;
+	if (input.encoding !== "base64") return true;
+	const bytes = base64Bytes(value["content"]);
+	return bytes !== null && bytes <= input.length && (!Object.hasOwn(value, "bytesRead") || value["bytesRead"] === bytes) && (!Object.hasOwn(value, "nextOffset") || value["nextOffset"] === input.offset + bytes);
+}
+function validWriteResult(value, input, bytes) {
+	return exactKeys(value, [
+		"file",
+		"revision",
+		"bytesWritten",
+		"mutationId"
+	]) && isFile(value["file"]) && value["file"].id === input.file.id && revision(value["revision"]) && (value["file"].revision === void 0 || value["file"].revision === value["revision"]) && (value["file"].size === void 0 || value["file"].size === bytes) && nonnegative(value["bytesWritten"]) && value["bytesWritten"] === bytes && value["mutationId"] === input.mutationId;
+}
+function isFailure(value) {
+	return exactKeys(value, [
+		"ok",
+		"reason",
+		"message",
+		"retryable"
+	]) && value["ok"] === false && typeof value["reason"] === "string" && failureReasons.has(value["reason"]) && typeof value["message"] === "string" && value["message"].length > 0 && typeof value["retryable"] === "boolean";
+}
+function isFile(value) {
+	return exactKeys(value, [
+		"id",
+		"kind",
+		"name"
+	], [
+		"extension",
+		"mimeType",
+		"size",
+		"revision"
+	]) && typeof value["id"] === "string" && value["id"].length > 0 && value["kind"] === "file" && typeof value["name"] === "string" && value["name"].length > 0 && (!Object.hasOwn(value, "extension") || typeof value["extension"] === "string" && value["extension"].length <= 32 && /^[a-z0-9][a-z0-9.-]*$/u.test(value["extension"])) && (!Object.hasOwn(value, "mimeType") || typeof value["mimeType"] === "string" && value["mimeType"].length > 0 && Array.from(value["mimeType"]).length <= 255) && (!Object.hasOwn(value, "size") || nonnegative(value["size"])) && (!Object.hasOwn(value, "revision") || revision(value["revision"]));
+}
+function revision(value) {
+	return typeof value === "string" && value.length > 0 && Array.from(value).length <= 256;
+}
+function nonnegative(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function encoding(value) {
+	return value === "utf8" || value === "base64";
+}
+function base64Bytes(value) {
+	try {
+		const binary = atob(value);
+		return btoa(binary) === value ? binary.length : null;
+	} catch {
+		return null;
+	}
+}
+function exactKeys(value, required, optional = []) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
+}
+function invalid(part) {
+	throw new Error(`file protocol error: invalid ${part}`);
+}
+//#endregion
 //#region src/widget.ts
 /**
 * Generated Widget Host 的唯一运行入口。Widget 作者只导出 activate/deactivate，
@@ -111,6 +282,13 @@ function runWidgetHost(widget, options = {}) {
 	};
 }
 function createContext(client, payload, renderHandlers, lifetime) {
+	const subscriptions = { add(registration) {
+		lifetime.add(registration);
+	} };
+	const events = { on(handlerOrName, maybeHandler) {
+		const unsubscribe = typeof handlerOrName === "string" ? client.onEvent(handlerOrName, maybeHandler) : client.onEvent(handlerOrName);
+		return lifetime.add(unsubscribe);
+	} };
 	return {
 		instanceId: payload.instanceId,
 		locale: payload.locale,
@@ -120,10 +298,17 @@ function createContext(client, payload, renderHandlers, lifetime) {
 			granted: payload.capabilities,
 			request: (request, options) => client.requestCapability(request, options)
 		},
-		files: { download: (input, options) => client.requestCapability({
-			operation: "files.download",
-			input
-		}, options) },
+		files: {
+			...createWidgetFileClient({
+				state: () => client.currentState,
+				granted: (operation) => payload.capabilities.some((grant) => grant.name === operation),
+				request: (request, requestOptions) => client.requestCapability(request, requestOptions)
+			}),
+			download: (input, options) => client.requestCapability({
+				operation: "files.download",
+				input
+			}, options)
+		},
 		tasks: { watch: (input, options) => client.requestCapability({
 			operation: "tasks.watch",
 			input
@@ -157,13 +342,8 @@ function createContext(client, payload, renderHandlers, lifetime) {
 			close: (options) => client.closePresentation(options),
 			changeSurface: (surface, options) => client.changePresentationSurface(surface, options)
 		},
-		events: { on(handlerOrName, maybeHandler) {
-			const unsubscribe = typeof handlerOrName === "string" ? client.onEvent(handlerOrName, maybeHandler) : client.onEvent(handlerOrName);
-			return lifetime.add(unsubscribe);
-		} },
-		subscriptions: { add(registration) {
-			lifetime.add(registration);
-		} },
+		events,
+		subscriptions,
 		render(handler) {
 			renderHandlers.add(handler);
 			return lifetime.add({ dispose: () => {

package/dist/runtime/files.d.ts

@@ -0,0 +1,24 @@
+import type { CapabilityRequest, CapabilityResult, FileReadInput, FileReadResult, FileWriteInput, FileWriteResult } from "@dp-bohrium/widget-contracts";
+import type { WidgetCapabilityRequestOptions, WidgetClientState } from "./client.js";
+type Failure = Extract<CapabilityResult, {
+    ok: false;
+}>;
+export type FileReadCapabilityResult = {
+    readonly ok: true;
+    readonly data: FileReadResult;
+} | Failure;
+export type FileWriteCapabilityResult = {
+    readonly ok: true;
+    readonly data: FileWriteResult;
+} | Failure;
+interface Dependencies {
+    readonly state: () => WidgetClientState;
+    readonly granted: (operation: "files.read" | "files.write") => boolean;
+    readonly request: (request: CapabilityRequest, options?: WidgetCapabilityRequestOptions) => Promise<CapabilityResult>;
+}
+/** 文件字节协议检查；权限和持久化仍由 Host 执行。 */
+export declare function createWidgetFileClient(dependencies: Dependencies): Readonly<{
+    read(input: FileReadInput, options?: WidgetCapabilityRequestOptions): Promise<FileReadCapabilityResult>;
+    write(input: FileWriteInput, options?: WidgetCapabilityRequestOptions): Promise<FileWriteCapabilityResult>;
+}>;
+export {};

package/dist/runtime/index.js

@@ -1,3 +1,3 @@
-import { a as isWidgetHostConnectMessage, c as WidgetClient, i as createWidgetClient, l as WIDGET_SDK_VERSION, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as REGION_CONFIRMATION_TIMEOUT_MS, t as WIDGET_BOOTSTRAP_READY } from "../runtime-Drr96Awx.js";
+import { a as isWidgetHostConnectMessage, c as WidgetClient, i as createWidgetClient, l as WIDGET_SDK_VERSION, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as REGION_CONFIRMATION_TIMEOUT_MS, t as WIDGET_BOOTSTRAP_READY } from "../runtime-8ppcE14g.js";
 import { i as isWidgetProtocolMessage, r as MessagePortTransport } from "../protocol-endpoint-CDz-YDGT.js";
 export { MessagePortTransport, PRESENTATION_CONFIRMATION_TIMEOUT_MS, REGION_CONFIRMATION_TIMEOUT_MS, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WIDGET_SDK_VERSION, WidgetClient, WidgetRuntimeClient, createWidgetClient, isWidgetHostConnectMessage, isWidgetProtocolMessage };

package/dist/{runtime-Drr96Awx.js → runtime-8ppcE14g.js}

@@ -2,7 +2,7 @@ import { r as MessagePortTransport, t as ProtocolEndpoint } from "./protocol-end
 //#endregion
 //#region src/runtime/version.ts
 /** 从当前安装的 SDK package.json 读取版本，插件作者不需要重复填写。 */
-const WIDGET_SDK_VERSION = "0.3.0";
+const WIDGET_SDK_VERSION = "0.4.0";
 //#endregion
 //#region src/runtime/network.ts
 const failureReasons = /* @__PURE__ */ new Set([
@@ -95,6 +95,9 @@ const capabilityFailureReasons = {
 	"invalid-reference": true,
 	timeout: true,
 	"internal-error": true,
+	"revision-conflict": true,
+	"mutation-conflict": true,
+	"write-outcome-unknown": true,
 	"network-consent-denied": true,
 	"network-policy-denied": true,
 	"network-transport-unavailable": true,

package/dist/widget.d.ts

@@ -1,7 +1,9 @@
-import type { CapabilityRequest, CapabilityResult, FileDownloadResult, FileReference, GrantedCapability, RegionCapabilityResult, RenderRequest, TaskObservationBatch, Theme, UiStateResult, UiStateWriteResult, WidgetEventName, WidgetLiveEvent } from "@dp-bohrium/widget-contracts";
+import type { CapabilityRequest, CapabilityResult, FileDownloadResult, FileReadInput, FileReference, FileWriteInput, GrantedCapability, RegionCapabilityResult, RenderRequest, TaskObservationBatch, Theme, UiStateResult, UiStateWriteResult, WidgetEventName, WidgetLiveEvent } from "@dp-bohrium/widget-contracts";
+import { type FileReadCapabilityResult, type FileWriteCapabilityResult } from "./runtime/files.js";
 import { type CreateWidgetClientOptions, type RegionName, type WidgetClientFactoryOptions, type WidgetClientState, type WidgetLiveEventContext, type WidgetLiveEventHandler } from "./runtime/index.js";
 import type { WidgetNetworkClient } from "./runtime/network.js";
 import type { WidgetHostUserClient, WidgetServiceClient } from "./runtime/service.js";
+export type { FileReadCapabilityResult, FileWriteCapabilityResult, } from "./runtime/files.js";
 export interface WidgetDisposable {
     dispose(): void | Promise<void>;
 }
@@ -25,6 +27,16 @@ export interface WidgetCapabilityApi {
     }): Promise<CapabilityResult>;
 }
 export interface WidgetFileApi {
+    /** 读取指定版本的一个字节区间；二进制文件使用 base64。 */
+    read(input: FileReadInput, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<FileReadCapabilityResult>;
+    /** 原子替换当前文件；未知结果须核对版本并保留 mutationId，不自动重试。 */
+    write(input: FileWriteInput, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<FileWriteCapabilityResult>;
     /** 请求 Host 在用户确认后通过宿主 Download Adapter 保存文件。 */
     download(input: {
         readonly file: FileReference;

package/llms.txt

@@ -21,4 +21,15 @@
 - 先在 Manifest 声明 capability，再等待 Host grant。
 - 用 `WidgetError` 的 `code/phase/retryable/correlationId` 诊断启动、渲染和能力失败。
 - `ok=false` 的能力结果是可处理状态，不要直接重试或绕过 Host。
+- 当前文件读写使用 `context.files.read(input, options)` / `write(input, options)`；Manifest
+  分别申请 `files.read` / `files.write`，文件引用来自当前 file-preview。SDK 只传字节，不负责 ASE
+  或其他格式序列化。完整保存示例见 README「读取和保存当前文件」。
+- read 兼容仅含 content/encoding 的旧响应，可选 offset/bytesRead/nextOffset/eof/truncated/revision
+  只验证已提供值并原样返回，不补造版本或游标。无 revision 仍可展示，但不能保存。
+- 请求 expectedRevision 必须返回有效且匹配的 revision；版本必须绑定同次读取的内容，不能另调
+  metadata/stat 补取。分块若有首块 revision，后续携带对应 expectedRevision；base64 解码后拼接
+  原始字节，避免 utf8 区间切断多字节字符。文件 revision 不是 RenderRequest.revision。
+- 保存必填 expectedRevision 和稳定 mutationId。发出后超时/中止/断线返回
+  write-outcome-unknown，不自动重试；保留内容和同一 mutationId 核对结果，成功回执后才标记已保存。
+- revision-conflict 需重读并合并；mutation-conflict 表示同一 mutationId 被用于不同内容。
 - SDK 本地通过不等于 iframe 已真实渲染、Bundle 已发布或 Agent 已绑定。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-bohrium/widget-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Bohrium Widget 开发者 SDK：在 Widget Bundle 内与 Host 建立 Bridge，并暴露生命周期与能力协议。",
   "license": "MIT",
   "type": "module",
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dp-bohrium/widget-contracts": "0.3.0"
+    "@dp-bohrium/widget-contracts": "0.4.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.2.0",