@dp-bohrium/widget-sdk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 本文件只记录影响使用者的变更：运行时 API、事件订阅、Manifest 要求。
 
+## 0.5.0
+
+### 新增
+
+**1. 增加任务发现 API**
+
+- 新增 `context.tasks.list({ cursor, limit }, options)`，一次读取 Host 授权的任务摘要页；返回的 `taskId` 可继续传给既有 `context.tasks.watch`。
+- SDK 不自行轮询或缓存列表，Widget 应遵守 `tasks.list` grant 的 `minPollMs`；该 API 不创建、调度或取消任务。
+
+### 修复
+
+- `context.render` 的同步异常与异步拒绝不再静默丢失：Guest console 保留原始异常，既有
+  `onError` / `events.onError` 收到本地 `RENDER_FAILED` 或 `UPDATE_FAILED` 诊断。
+- 渲染失败不自动终止 Bridge 或重试，其他处理器和后续快照可继续；观察者错误被隔离，停用后
+  迟到的拒绝不再产生诊断。公开类型与协议不变，Host 侧非终态诊断仍需单独设计兼容。
+
+## 0.4.1
+
+### 修复
+
+**1. 解除已释放监听与资源的强引用**
+
+- 手动释放 render、event 或第三方资源登记后，生命周期不再持续强引用原资源及其闭包；调用方继续持有释放句柄时，也不会因此保留已释放资源，避免长期运行的 Widget 反复切换监听器后累积内存。
+- 重复登记和重复释放继续保持幂等，活动资源仍在 Widget 停用时清理；公开 API、回调与释放语义不变。
+
+**2. 对齐 Panel 文件保存指南与授权边界**
+
+- npm 包首页指向官方文档站，便于从包元数据发现教程与 API 参考。
+- README 与 Agent 索引明确：file-preview 使用当前文件引用，获独立 `files.write` grant 的 Panel 使用 Host 签发的工作区文件引用；SDK 仍通过既有 `context.files.read/write` 接口传递字节，不新增文件操作。
+- [文件能力指南](https://dev.dp.tech/bohrium-widget-sdk/guides/capabilities/files) 补充 Panel 编辑示例，覆盖同文件 render 保留草稿、Session 切换、保存快照与冲突／未知结果；缺少授权、完整内容或读取版本时保持只读。
+- SDK 与 contracts 同步为 `0.4.1`，保持文件请求、回执与公开类型兼容。
+
 ## 0.4.0
 
 ### 新增

package/README.md

@@ -78,6 +78,23 @@ Binding 级 Runtime Loader 尚未开放。插件可以按 Runtime/Surface 分层
   最多调用一次 `deactivate()`，已完成激活的异步清理可通过 `whenDisposed` 等待；
 - `context.render` 首帧和更新都会收到完整快照，通过 `renderContext.phase` 区分。
 
+### 渲染失败与本地诊断
+
+`runWidgetHost` 会隔离 `context.render` 处理器的同步异常和异步拒绝，并在 Guest console
+记录原始异常。已有 `onError` 和 `events.onError` 也会收到本地结构化诊断：首帧使用
+`RENDER_FAILED/render`，更新使用 `UPDATE_FAILED/update`，`correlationId` 对应失败快照的
+`requestId`，`retryable` 为 `false`。结构化消息不包含渲染负载或原始异常。
+
+这类通知本身不会让 SDK 终止 Bridge、销毁界面或自动重试；其他处理器和后续快照仍可继续，
+插件应保留草稿并提供可恢复的提示。观察者显式调用 `dispose()` 时，SDK 仍尊重停用意图。
+SDK 不回滚处理器失败前已执行的 DOM 修改；界面和草稿的恢复仍由插件拥有。
+观察者自身的同步异常、异步拒绝和 console 失败不会阻断渲染，也不会递归触发 `onError`；
+停用后迟到的渲染拒绝会被消费，但不再产生本地诊断。
+
+这些是 Guest 本地出口，SDK 不通过 Bridge 把它们发送给 Host。
+旧 Host 会把 Widget 的协议 `error` 当作致命失败，
+不能用它承载可恢复的渲染诊断；Host 的 `ready` 或 `render-sent` 也不能证明 Guest DOM 渲染成功。
+
 ## 从 Manifest 到插件运行
 
 Manifest 是插件的静态声明，SDK 代码是隔离 iframe 内的运行时实现，Host 负责二者之间的生命周期编排。一个插件可以这样声明：
@@ -179,6 +196,7 @@ SDK 发布包会生成 `dist/index.d.ts` 与对应的 declaration map，并通
 | `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.list` | `tasks.list` | `context.tasks.list({ cursor, limit })` |
 | `tasks.watch` | `tasks.watch` | `context.tasks.watch({ taskId, cursor, limit })` |
 | `ui.state` | `state`（`read` / `write`） | `context.ui.state.read(key)` / `write(key, value)` |
 | `actions.invoke` | `actions` | `context.capabilities.request({ operation: "actions.invoke", input })` |
@@ -217,8 +235,10 @@ if (result.ok) {
   业务 payload，不会把 Cookie、Bearer Token 或其他凭据放入 iframe。
 - `context.files.download` 只提交文件引用和建议文件名；Host 在用户确认后经宿主
   Download Adapter 惰性打开内容源。Widget 不会收到源 URL、保存路径或凭据。
+- `context.tasks.list` 只读取一次受限任务摘要页；返回的 `taskId` 是可继续传给
+  `context.tasks.watch` 的不透明引用。SDK 不会自行轮询，调用方应遵守 grant 的 `minPollMs`。
 - `context.tasks.watch` 只读取一次受限任务快照和事件页；调用方用返回的 cursor 继续轮询。
-  它不创建、调度或取消任务，服务端负责任务授权、脱敏和终态保留。
+  两个任务 API 都不创建、调度或取消任务，服务端负责任务授权、脱敏和终态保留。
 - `context.ui.state` 只保存按 Widget + Session 隔离的 JSON UI 状态；Host 按 key、单值大小、总字节数和调用
   频率限流。它不能保存任务执行、凭据、文件内容或 Workspace 权限状态。
 - 外部插件的工具结果场景通过 `tool-call-result` 事件作为可选运行时信号；内部 Host/协议测试仍可使用低层 Tool Result RenderRequest
@@ -236,8 +256,9 @@ if (result.ok) {
 ### 读取和保存当前文件
 
 作者 Manifest 申请 `"capabilities": { "files": { "read": true, "write": true } }`，Host 仍需独立
-授权两个能力。`files.write` 对当前 `file-preview` 绑定的已有文件作整文件条件替换；引用来自
-`request.content.file`，不能传路径、URL、别的文件 id 或指定另存位置。Host 校验引用、作用域、
+授权两个能力。`files.write` 对 Host 签发引用指向的已有文件作整文件条件替换：在 `file-preview`
+中引用来自 `request.content.file`；在获得写 grant 的 Panel 中引用来自 `data.root` 或 `files.list`
+的结果。不能传路径、URL、自造的文件 id 或指定另存位置。Host 校验引用、作用域、
 写权限和实际字节预算，成功回执表示执行端已确认持久化。SDK 不负责 ASE、晶格或文件格式转换，
 插件应使用自己的序列化器生成最终字节。
 
@@ -311,7 +332,7 @@ import { MockWidgetHost } from "@dp-bohrium/widget-sdk/testing";
 ## 限制
 
 - SDK 不做授权决策，能力是否可用最终由 Host 判定。
-- `tasks.watch` 是有界观察协议，不是调度器、执行器或取消 API；任务状态和事件由服务端投影。
+- `tasks.list` / `tasks.watch` 是有界发现与观察协议，不是调度器、执行器或取消 API；任务摘要、状态和事件由服务端投影。
 - `invokeAction` 不自动重试，回调完成也不代表工具执行完成。
 - `subscribeEvents` 的 `events.read` 是有界分页读取，不是 websocket；实时推送走
   `onEvent`。当前版本没有单请求取消的独立协议消息：`unsubscribe` 会停止后续轮询并取消

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export { isWidgetActivationEvent, isWidgetEventName, WIDGET_ACTIVATION_EVENTS, W
 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, FileReadCapabilityResult, FileWriteCapabilityResult, 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, TaskListCapabilityResult, 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-8ppcE14g.js";
+import { i as createWidgetClient, l as WIDGET_SDK_VERSION } from "./runtime-DVFTv55x.js";
 import { WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, isWidgetActivationEvent, isWidgetEventName } from "@dp-bohrium/widget-contracts";
 //#region src/manifest.ts
 function compiledContribution(contribution) {
@@ -46,7 +46,8 @@ function compileWidgetPluginManifest(manifest, options = {}) {
 //#region src/lifetime.ts
 function createWidgetLifetime(onError) {
 	const controller = new AbortController();
-	const resources = /* @__PURE__ */ new Map();
+	const registrations = /* @__PURE__ */ new WeakMap();
+	const resources = /* @__PURE__ */ new Set();
 	const pending = /* @__PURE__ */ new Set();
 	let closePromise;
 	function run(callback) {
@@ -60,15 +61,20 @@ function createWidgetLifetime(onError) {
 		return task;
 	}
 	function add(resource) {
-		const existing = resources.get(resource);
+		const existing = registrations.get(resource);
 		if (existing) return existing;
+		let retained = resource;
 		let disposed;
 		const handle = { dispose() {
 			if (disposed) return disposed;
-			disposed = run(() => typeof resource === "function" ? resource() : resource.dispose());
+			const current = retained;
+			retained = void 0;
+			resources.delete(handle);
+			disposed = run(() => typeof current === "function" ? current() : current?.dispose());
 			return disposed;
 		} };
-		resources.set(resource, handle);
+		registrations.set(resource, handle);
+		resources.add(handle);
 		if (controller.signal.aborted) handle.dispose();
 		return handle;
 	}
@@ -309,10 +315,16 @@ function createContext(client, payload, renderHandlers, lifetime) {
 				input
 			}, options)
 		},
-		tasks: { watch: (input, options) => client.requestCapability({
-			operation: "tasks.watch",
-			input
-		}, options) },
+		tasks: {
+			list: (input = {}, options) => client.requestCapability({
+				operation: "tasks.list",
+				input
+			}, options),
+			watch: (input, options) => client.requestCapability({
+				operation: "tasks.watch",
+				input
+			}, options)
+		},
 		network: client.network,
 		services: client.services,
 		hostUser: client.hostUser,
@@ -367,6 +379,29 @@ function createWidgetRuntime(module, options = {}) {
 	const disposedPromise = new Promise((resolve) => {
 		resolveDisposed = resolve;
 	});
+	function writeLocalDiagnostic(...details) {
+		try {
+			console.error(...details);
+		} catch {}
+	}
+	function reportRenderFailure(error, request, update) {
+		if (lifetime.signal.aborted) return;
+		const failure = {
+			code: update ? "UPDATE_FAILED" : "RENDER_FAILED",
+			phase: update ? "update" : "render",
+			message: "Widget render handler failed",
+			retryable: false,
+			correlationId: request.requestId
+		};
+		writeLocalDiagnostic("[Widget 渲染失败]", failure, error);
+		for (const observer of [options.events?.onError, options.onError]) try {
+			Promise.resolve(observer?.(failure)).catch((observerError) => {
+				writeLocalDiagnostic("[Widget 诊断回调失败]", observerError);
+			});
+		} catch (observerError) {
+			writeLocalDiagnostic("[Widget 诊断回调失败]", observerError);
+		}
+	}
 	function runDeactivation() {
 		if (deactivation) return deactivation;
 		deactivation = Promise.resolve().then(() => module.deactivate?.()).catch((error) => {
@@ -407,9 +442,14 @@ function createWidgetRuntime(module, options = {}) {
 					phase: update ? "update" : "initial",
 					signal: lifetime.signal
 				};
-				for (const handler of [...renderHandlers]) try {
-					Promise.resolve(handler(request, renderContext)).catch(() => {});
-				} catch {}
+				for (const handler of [...renderHandlers]) {
+					if (lifetime.signal.aborted) break;
+					try {
+						Promise.resolve(handler(request, renderContext)).catch((error) => reportRenderFailure(error, request, update));
+					} catch (error) {
+						reportRenderFailure(error, request, update);
+					}
+				}
 			},
 			onDispose: dispose
 		}

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-8ppcE14g.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-DVFTv55x.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-8ppcE14g.js → runtime-DVFTv55x.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.4.0";
+const WIDGET_SDK_VERSION = "0.5.0";
 //#endregion
 //#region src/runtime/network.ts
 const failureReasons = /* @__PURE__ */ new Set([

package/dist/widget.d.ts

@@ -1,4 +1,4 @@
-import type { CapabilityRequest, CapabilityResult, FileDownloadResult, FileReadInput, FileReference, FileWriteInput, 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, TaskListPage, 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";
@@ -53,6 +53,17 @@ export type FileDownloadCapabilityResult = {
     readonly ok: false;
 }>;
 export interface WidgetTaskApi {
+    /**
+     * 读取一次受 Host 限制的任务摘要页。返回的 taskId 可继续用于 tasks.watch；
+     * 此 API 只发现任务，不创建、调度或取消任务。
+     */
+    list(input?: {
+        readonly cursor?: string;
+        readonly limit?: number;
+    }, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<TaskListCapabilityResult>;
     /**
      * 读取一次受 Host 限制的任务快照和事件页。调用方使用返回的 cursor
      * 继续轮询；此 API 不创建、调度或取消任务。
@@ -66,6 +77,14 @@ export interface WidgetTaskApi {
         readonly signal?: AbortSignal;
     }): Promise<TaskWatchCapabilityResult>;
 }
+/** tasks.list 的类型化能力结果。 */
+export type TaskListCapabilityResult = {
+    readonly ok: true;
+    readonly data: TaskListPage;
+} | Extract<CapabilityResult, {
+    readonly ok: false;
+}>;
+/** tasks.watch 的类型化能力结果。 */
 export type TaskWatchCapabilityResult = {
     readonly ok: true;
     readonly data: TaskObservationBatch;

package/llms.txt

@@ -20,9 +20,12 @@
 
 - 先在 Manifest 声明 capability，再等待 Host grant。
 - 用 `WidgetError` 的 `code/phase/retryable/correlationId` 诊断启动、渲染和能力失败。
+- `context.render` 异常通过 `runWidgetHost` 的既有 `onError` / `events.onError` 和 Guest console
+  本地报告，不自动终止或重试；不要改成向旧 Host 发送致命协议 `error`。
 - `ok=false` 的能力结果是可处理状态，不要直接重试或绕过 Host。
-- 当前文件读写使用 `context.files.read(input, options)` / `write(input, options)`；Manifest
-  分别申请 `files.read` / `files.write`，文件引用来自当前 file-preview。SDK 只传字节，不负责 ASE
+- 文件读写使用 `context.files.read(input, options)` / `write(input, options)`；Manifest
+  分别申请 `files.read` / `files.write`。file-preview 的引用来自当前文件；Panel 只有获得
+  `files.write` grant 时才能保存 `data.root` / `files.list` 取得的已有文件。SDK 只传字节，不负责 ASE
   或其他格式序列化。完整保存示例见 README「读取和保存当前文件」。
 - read 兼容仅含 content/encoding 的旧响应，可选 offset/bytesRead/nextOffset/eof/truncated/revision
   只验证已提供值并原样返回，不补造版本或游标。无 revision 仍可展示，但不能保存。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-bohrium/widget-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Bohrium Widget 开发者 SDK：在 Widget Bundle 内与 Host 建立 Bridge，并暴露生命周期与能力协议。",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,7 @@
     "runtime"
   ],
   "author": "Bohrium",
-  "homepage": "https://www.npmjs.com/package/@dp-bohrium/widget-sdk",
+  "homepage": "https://dev.dp.tech/bohrium-widget-sdk/",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dp-bohrium/widget-contracts": "0.4.0"
+    "@dp-bohrium/widget-contracts": "0.5.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.2.0",