@dp-bohrium/widget-sdk 0.0.7 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# `@dp-bohrium/widget-sdk` 变更记录
+
+本文件只记录影响使用者的变更：运行时 API、事件订阅、Manifest 要求。
+
+## 0.1.0
+
+### 新增
+
+**1. 暴露受控文件下载、长任务观察和 UI 状态 API**
+
+- 新增 `context.files.download`、`context.tasks.watch` 和 `context.ui.state.read/write`，均受 Host grant、预算和作用域约束。
+
+**2. 暴露结构化 Tool Result envelope 类型**
+
+- SDK 类型和运行时辅助函数支持带状态、指标、产物引用、provenance、warning 与 missing 的结构化 Tool Result。
+
+说明：0.0.9 曾在 Git 中准备，但未创建发布 Tag 或进入 npm；本节变更作为新的兼容性边界随 0.1.0 发布。
+
+## 0.0.8
+
+### 修复
+
+- 与 `@dp-bohrium/widget-contracts` 0.0.8 保持版本一致。运行时 API、事件订阅与 Manifest 要求均无变化，从 0.0.7 升级无需改代码。
+
+说明：0.0.8 未单独发布；本节变更最终随 0.1.0 一并发布。
+
+## 0.0.7
+
+### 破坏性变更
+
+**1. onEvent 的事件载荷从 PublicWidgetEvent 变为 WidgetLiveEvent**
+
+新载荷只有 `type` 和 `payload` 两个字段。`schemaVersion`、`id`、`occurredAt`、`sessionId`、`workflowId`、`topic` 都不再下发，读这些字段的代码会失效。
+
+```ts
+// 0.0.6 及以前
+client.onEvent((event) => {
+  if (event.topic === "tools.lifecycle" && event.type === "tool-call") {
+    render(event.payload);
+  }
+});
+
+// 0.0.7 —— 按 type 分派，不再有 topic
+client.onEvent((event) => {
+  if (event.type === "tool-call") {
+    render(event.payload);
+  }
+});
+```
+
+需要 `sessionId` / `workflowId` 的，从 `init` 阶段拿到的上下文取，不要再从事件对象上读。
+
+**2. Manifest 的 widgetConfig.behaviors 移除，改为 widgetConfig.activationEvents**
+
+从对象数组改成字符串数组，保留旧字段的 Manifest 上传会被拒。完整迁移写法见 `@dp-bohrium/widget-contracts` 的变更记录。原先靠 `behaviors` 自动执行 `panel.open` 等 Host 动作的能力没有等价替代。
+
+### 新增
+
+- onEvent 新增按事件名订阅的重载，回调直接收到该类型的事件，不必再判断 event.type。
+
+  ```ts
+  client.onEvent("tool-call", (event) => render(event.payload));
+  ```
+
+  无参数形式仍然接收全部事件，行为不变。
+
+## 0.0.6
+
+### 新增
+
+- 支持接收 Host 通过 MessageChannel 主动推送的实时事件（`onEvent`），无需 HTTP 轮询。
+
+## 0.0.5
+
+### 新增
+
+- 支持消费事件驱动的 Widget 行为。
+
+## 0.0.4
+
+### 新增
+
+- Manifest 支持声明式地在 Session 启动时打开 Panel。
+
+## 0.0.3
+
+- 仅发布流程调整，无对外变更。
+
+## 0.0.2
+
+### 破坏性变更
+
+- 包迁移至 `@dp-bohrium` scope，旧 scope 不再发布新版本。
+
+## 0.0.1
+
+首个公开版本。
+
+- MessagePort Transport、Widget 生命周期、Host Bridge 能力。
+- Host 代理的网络请求能力。

package/README.md

@@ -1,8 +1,11 @@
 # @dp-bohrium/widget-sdk
 
-Widget 开发者 SDK。在生产 Widget Bundle 内使用 `createWidgetClient`：向 Host
-宣告 Bundle、接收转移过来的 `MessagePort`，并暴露共享的生命周期与能力协议，
-无需直接处理 `window.postMessage`。
+Widget 开发者 SDK。普通作者只实现 `activate(context)` 和可选的 `deactivate()`；CLI
+会生成 Widget Host 入口，负责向 Host 宣告 Bundle、接收转移过来的 `MessagePort`，并暴露共享的
+生命周期与能力协议。作者无需直接处理 `window.postMessage`，也无需手动启动插件。
+
+激活事件目录、`context.events` 与低层 `topic` 的边界见
+[Widget 激活事件与事件查询](../../docs/design/widget-activation-events-zh.md)。
 
 ## 环境要求
 
@@ -25,74 +28,128 @@ pnpm add @dp-bohrium/widget-sdk
 yarn add @dp-bohrium/widget-sdk
 ```
 
-在自己的 `package.json` 里钉死精确 SemVer，不要用 `^` 或裸 `latest`。
+需要在 TypeScript 中直接声明或在编辑器中解析 Manifest Schema 时，再把
+`@dp-bohrium/widget-contracts` 作为开发依赖安装；它是独立的类型/Schema 包，不需要通过
+`defineManifest()` 工厂获得提示。
+
+在自己的 `package.json` 里钉死精确 SemVer，不要用 `^` 或裸 `latest`。SDK 运行时会从已安装
+包自身读取版本，插件源码和 Manifest 不需要再次填写 SDK 版本。
 
 ## 快速开始
 
 ```ts
-import { createWidgetClient } from "@dp-bohrium/widget-sdk";
-
-const widget = createWidgetClient({
-  // 填已安装的精确版本，并与 manifest.json 的 widgetSdkVersion 写成同一个值。
-  widgetSdkVersion: "REPLACE_WITH_INSTALLED_SDK_VERSION",
-  async onInit(payload) {
-    // Host 下发 locale、theme 与已授予的 capabilities。
-    await applyHostContext(payload.locale, payload.theme, payload.capabilities);
-  },
-  onRender(request) {
-    // 按 Slot 渲染完整快照。
-    renderSlot(request.slot, request.content);
-  },
-  onDispose({ reason, deadlineMs }) {
-    // 释放定时器、订阅与 worker。
-    releaseLocalResources(reason, deadlineMs);
-  },
-});
+import type { WidgetContext } from "@dp-bohrium/widget-sdk";
 
-await widget.ready();
-widget.resize({ width: 600, height: 400 });
+export function activate(context: WidgetContext) {
+  context.render((request, renderContext) => {
+    renderSlot(request.slot, request.content, renderContext.phase);
+  });
+  context.events.on("tool-call-result", (event) => showToolResult(event.payload));
+}
 ```
 
+CLI 生成的 `src/widget-host.ts` 会调用平台入口 `runWidgetHost(widget)`。
+这与 VS Code 的激活入口一致：开发者实现 `activate(context)`，可选实现 `deactivate()`；
+Widget Host/SDK 负责加载、等待初始化、报告启动失败和执行清理。普通插件代码不需要调用
+`ready()`，也不应该写 `plugin.ready().catch(() => {})`。`whenReady` 只保留给测试和高级宿主编排。
+
+`context.signal` 会在 Host 停用插件或 Bridge 断开时 `abort`。`context.render` 和 `context.events`
+会自动登记到当前插件生命周期；`subscriptions` 只用于
+第三方计时器、观察器或其它需要在停用时释放的资源。
+
 三条时序约定：
 
-- `ready()` 只在 `onInit` 返回（含其 Promise settle）之后才发给 Host，
+- `ready()` 只在 `activate(context)` 返回（含其 Promise settle）之后才发给 Host，
   `handshakeTimeoutMs` 同时约束这一步；
-- 初始化失败时，SDK 先报结构化 `onError`，再调 `onDispose`;
-- 若只提供 `onUpdate`，首帧完整 `render` 快照也会投递给 `onUpdate`。
+- 初始化失败时，SDK 先报结构化错误，再调用插件资源清理；
+- `context.render` 首帧和更新都会收到完整快照，通过 `renderContext.phase` 区分。
+
+## 从 Manifest 到插件运行
+
+Manifest 是插件的静态声明，SDK 代码是隔离 iframe 内的运行时实现，Host 负责二者之间的生命周期编排。一个插件可以这样声明：
+
+```json
+{
+  "$schema": "@dp-bohrium/widget-contracts/schemas/widget-plugin-manifest.schema.json",
+  "name": "research",
+  "version": "1.0.0",
+  "entry": "src/widget.ts",
+  "displayName": "研究面板",
+  "description": "展示研究工具的结构化结果",
+  "activationEvents": ["session.start", "tool-call-result:ScholarSearch", "ui-tool-opened"],
+  "contributes": {
+    "widget": { "type": "panel", "id": "research", "surfaces": ["workspace", "floating"] }
+  },
+  "capabilities": {
+    "files": { "read": true },
+    "events": { "topics": ["tool-call-result", "workspace-file-opened"] }
+  }
+}
+```
+
+`activationEvents` 只决定 Host 何时创建插件运行时；它不授予事件读取权限，也不负责打开思考过程或某个面板。插件激活后通过 `context.events` 和 `context.render` 注册监听与渲染器。Host 会对每个事件和能力请求做白名单投影与授权，插件收到的事件可能是有限回放，也可能是实时事件。
+
+实现建议：事件处理器保持幂等，按 `toolCallId` 或 `requestId` 去重；不要从 iframe URL、DOM 或宿主绝对路径推断内部数据；当能力未授予时显示结构化空态并继续保留可渲染的主界面。声明但没有实际使用的能力会被 Host 记录为诊断信息，未声明能力的调用会被拒绝并结束当前 Bridge 会话。
+
+### 统一插件入口
+
+所有插件类型都使用同一个 `activate(context)` 约定。面板、工具结果和文件预览由
+Manifest 的 `contributes.widget` 决定；运行时代码只认识统一的 `context.events`、
+`context.render`、`context.capabilities` 和 `context.ui`。首帧和后续快照通过
+`renderContext.phase` 区分，不需要维护两套回调。
+
+Manifest 的编辑器提示来自 `@dp-bohrium/widget-contracts` 发布的 JSON Schema 和
+TypeScript 类型，不依赖某个 `defineManifest` 工厂。构建工具调用
+`compileWidgetPluginManifest`，自动补齐 `schemaVersion`、`hostApiVersion`、SDK 版本和
+宿主加载字段；它会直接读取 Manifest 内的 `samples`，只有构建器从别处生成样例时
+才需要传入第二个参数。`createWidgetClient` 是协议级基础实现，不属于 Widget 作者 API；当前根入口只提供统一 Widget API，协议级代码应从
+`./runtime` 显式引入。
+
+SDK 发布包会生成 `dist/index.d.ts` 与对应的 declaration map，并通过 `package.json` 的
+`types`/`exports` 暴露。插件安装 `@dp-bohrium/widget-sdk` 后，编辑器会直接获得
+`WidgetContext`、事件名、能力请求、渲染请求和生命周期返回值的类型提示；Manifest
+编辑器提示由 `@dp-bohrium/widget-contracts` 的 JSON Schema 和声明文件提供。
 
 ## 包入口
 
 | 入口 | 内容 | 用途 |
 | --- | --- | --- |
-| `.` | `createWidgetClient`、`PRESENTATION_CONFIRMATION_TIMEOUT_MS`，以及全部公开类型 | 生产 Widget |
+| `.` | `runWidgetHost`、`compileWidgetPluginManifest` 和全部公开类型 | 生成的生产 Bundle |
 | `./testing` | `MemoryTransport`、`MockWidgetHost` | 单元测试 |
 | `./runtime` | 低层 `WidgetClient`、transport 与 bootstrap 常量 | 协议级集成 |
-| `./package.json` | 已安装包的元数据 | 工具读取版本。源码与 Manifest 的 `widgetSdkVersion` 写成同一个精确版本字符串 |
+| `./package.json` | 已安装包的元数据 | SDK 和构建工具自动读取版本，作者无需复制版本字符串 |
+
+根入口只导出插件运行时和 Manifest 编译所需的少量值，其余均为类型。低层
+`MessagePortTransport` 与 bootstrap 消息不属于普通 Widget API。
 
-根入口只导出两个运行时值，其余均为类型。`MessagePortTransport` 与 bootstrap 消息
-不属于普通 Widget API。
+`runWidgetHost` 是生成的 `widget-host.ts` 使用的 Widget Host 启动边界；
+插件作者只维护 `widget.ts` 中的 `activate/deactivate`。
 
 ## 能力
 
-每项能力都要在 Manifest 的 `requestedCapabilities` 里声明，并由 Host 实际 grant；
+每项能力都要在 Manifest 的 `capabilities` 里声明，并由 Host 实际 grant；
 缺任一侧，调用在 Widget 本地即被拒绝。所有能力调用都必须在 `ready()` 之后。
 
-下面五项是当前的全部能力。grant 名与 Manifest 申请键不一定同名 —— `ui.presentation`
-对应的申请键是 `requestedCapabilities.presentation`。
+下面七项是当前的全部能力。grant 名与 Manifest 申请键不一定同名 —— `ui.presentation`
+对应的作者侧申请键是 `capabilities.presentation`（编译后的 宿主格式字段才叫
+`requestedCapabilities.presentation`）。
 
 | grant 名 | Manifest 申请键 | SDK 调用 |
 | --- | --- | --- |
-| `files.list` / `files.metadata` / `files.read` | `files` | `widget.requestCapability({ operation, input })` |
-| `events.read` | `events`（需列出 `topics`） | 拉取 `widget.subscribeEvents(…)` / `widget.onTool(…)` |
-| `actions.invoke` | `actions` | `widget.invokeAction(…)` |
-| `network.fetch` | `network` | `widget.network.fetch(…)` |
-| `ui.presentation` | `presentation` | `widget.present(…)` / `changePresentationSurface` / `focusPresentationBoundary` / `closePresentation` |
+| `files.list` / `files.metadata` / `files.read` | `files` | `context.capabilities.request({ operation, input })` |
+| `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 })` |
+| `ui.state` | `state`（`read` / `write`） | `context.ui.state.read(key)` / `write(key, value)` |
+| `actions.invoke` | `actions` | `context.capabilities.request({ operation: "actions.invoke", input })` |
+| `network.fetch` | `network` | `context.network.fetch(…)` |
+| `ui.presentation` | `presentation` | `context.ui.present(…)` / `changeSurface` / `close` |
 
-五项共用同一套调用范式，掌握下面这一个就会调其余四个：
+除 Host 主动推送事件外，其余能力共用同一套调用范式，掌握下面这一个就会调其余能力：
 
 ```ts
 const controller = new AbortController();
-const result = await widget.network.fetch(
+const result = await context.network.fetch(
   { url: "https://api.example.org/papers", method: "GET", auth: "optional" },
   { signal: controller.signal, timeoutMs: 15_000 },
 );
@@ -105,19 +162,27 @@ if (result.ok) {
 }
 ```
 
-跨能力的六条约定：
+跨能力约定：
 
 - 失败以 `{ ok: false, reason, message, retryable }` 正常兑现；只有客户端超时、中止、
   dispose 和畸形响应才 reject。
 - 中止与超时统一用 `{ signal, timeoutMs }`，复用既有 MessageChannel 能力生命周期。
 - Widget 永远拿不到 Host 凭据，也不应直接调用浏览器 `fetch`：是否弹窗、记住 Origin
   授权、跟随重定向还是拒绝，全部由 Host 决定。
+- `context.files.download` 只提交文件引用和建议文件名；Host 在用户确认后经宿主
+  Download Adapter 惰性打开内容源。Widget 不会收到源 URL、保存路径或凭据。
+- `context.tasks.watch` 只读取一次受限任务快照和事件页；调用方用返回的 cursor 继续轮询。
+  它不创建、调度或取消任务，服务端负责任务授权、脱敏和终态保留。
+- `context.ui.state` 只保存按 Widget + Session 隔离的 JSON UI 状态；Host 按 key、单值大小、总字节数和调用
+  频率限流。它不能保存任务执行、凭据、文件内容或 Workspace 权限状态。
+- Tool Result 的 `content.envelope` 是可选的结构化投影，包含受约束的状态、数据、指标、产物引用、
+  provenance、warning 和 missing；产物只携带 opaque id 与展示元数据，不携带下载 URL 或本机路径。
 - 呈现只是**请求**。Host 可能降级到别的表面，成功结果里的 `surface` 才是真实表面；
   Widget 不能指定目标 Panel、身份、运行时 generation、坐标或层级。
-- 事件有两条路径，按需要选一条：`onEvent(handler)` 接收 Host 从当前 Runtime **主动
-  推送**的聚合事件，只按 `type` 分发，不依赖 Manifest Topic 或 `events.read` grant；
-  `subscribeEvents` / `onTool` 走兼容的**有界分页拉取**，带游标、可续读。
-- `subscribeEvents` / `onTool` 的所有订阅共享同一实例的 events 读预算，并各自遵守
+- 高层插件 API 使用 `context.events.on(handler)` 接收 Host 从当前 Runtime **主动推送**的
+  聚合事件，只按 `type` 分发，不依赖 Manifest Topic 或 `events.read` grant。需要直接使用有界
+  分页读取时，从 `@dp-bohrium/widget-sdk/runtime` 使用 `subscribeEvents` / `onTool`。
+- 低层 `subscribeEvents` / `onTool` 的所有订阅共享同一实例的 events 读预算，并各自遵守
   topic 最小轮询间隔 —— 订阅越多，单个 topic 刷新越慢。游标只在 `onBatch` 成功后
   提交，重新订阅需显式传回 `events.cursor`。工具 Hook 观察的是**已经发生的**服务端
   事实，不是执行前拦截器。
@@ -139,9 +204,10 @@ import { MockWidgetHost } from "@dp-bohrium/widget-sdk/testing";
 ## 限制
 
 - SDK 不做授权决策，能力是否可用最终由 Host 判定。
+- `tasks.watch` 是有界观察协议，不是调度器、执行器或取消 API；任务状态和事件由服务端投影。
 - `invokeAction` 不自动重试，回调完成也不代表工具执行完成。
 - `subscribeEvents` 的 `events.read` 是有界分页读取，不是 websocket；实时推送走
-  `onEvent`。当前版本没有单请求取消的 wire 消息：`unsubscribe` 会停止后续轮询并取消
+  `onEvent`。当前版本没有单请求取消的独立协议消息：`unsubscribe` 会停止后续轮询并取消
   本地等待，已发出的服务端读取可能完成，但结果被忽略。
 - Host 发来畸形 Bridge 信封或载荷时，transport 报结构化 `MESSAGE_INVALID` 并关闭
   连接，不会让 Widget 悬等。

package/dist/index.d.ts

@@ -1,2 +1,6 @@
-export type { CreateWidgetClientOptions, PresentationFocusDirection, PresentationSurface, SubscribeWidgetEventsOptions, WidgetCapabilityRequestOptions, WidgetClientEvents, WidgetClientFactoryOptions, WidgetClientOptions, WidgetClientState, WidgetDisposeEvent, WidgetEventBatchContext, WidgetEventSubscription, WidgetHostConnectMessage, WidgetLiveEventContext, WidgetLiveEventHandler, WidgetMessagePort, WidgetNetworkClient, WidgetNetworkFetchResult, WidgetRuntimeWindow, WidgetSize, WidgetToolHooks, WidgetTransport, } from "./runtime/index.js";
-export { createWidgetClient, PRESENTATION_CONFIRMATION_TIMEOUT_MS, } from "./runtime/index.js";
+export type { WidgetActivationEvent, WidgetActivationEvents, WidgetContribution, WidgetEventName, WidgetFilePreviewContribution, WidgetPanelContribution, WidgetPluginContributions, WidgetPluginManifest, WidgetToolPhase, WidgetToolResultContribution, } 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 { FileDownloadCapabilityResult, 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,2 +1,182 @@
-import { i as createWidgetClient, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS } from "./runtime-h-oTCwcs.js";
-export { PRESENTATION_CONFIRMATION_TIMEOUT_MS, createWidgetClient };
+import { c as WIDGET_SDK_VERSION, i as createWidgetClient } from "./runtime-B5kilTcQ.js";
+import { WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, isWidgetActivationEvent, isWidgetEventName } from "@dp-bohrium/widget-contracts";
+//#region src/manifest.ts
+function compiledSlot(contribution) {
+	switch (contribution.type) {
+		case "panel": return {
+			type: "panel",
+			panelType: contribution.id
+		};
+		case "tool-result": return {
+			type: "tool-result",
+			toolName: contribution.toolName
+		};
+		case "file-preview": return {
+			type: "file-preview",
+			extensions: [...contribution.extensions]
+		};
+	}
+}
+/**
+* 将开发者维护的插件清单编译为宿主可加载的宿主清单。
+*
+* 这是构建工具的边界函数，不是类型提示入口：作者直接编辑带 `$schema` 的 JSON，
+* SDK 版本从当前安装包读取，宿主入口默认落到 dist/widget.js，内部 slot 标识只在这里生成。
+*/
+function compileWidgetPluginManifest(manifest, options = {}) {
+	const samples = options.samples ?? manifest.samples;
+	if (!samples || samples.length === 0) throw new Error("Widget Plugin Manifest must provide at least one sample before packaging");
+	const activationEvents = manifest.activationEvents ? [...manifest.activationEvents] : void 0;
+	return {
+		name: manifest.name,
+		...manifest.description === void 0 ? {} : { description: manifest.description },
+		widgetConfig: {
+			schemaVersion: 1,
+			hostApiVersion: 1,
+			widgetSdkVersion: WIDGET_SDK_VERSION,
+			entry: options.hostEntry ?? "dist/widget.js",
+			slot: compiledSlot(manifest.contributes.widget),
+			...activationEvents === void 0 ? {} : { activationEvents },
+			...manifest.capabilities === void 0 ? {} : { requestedCapabilities: manifest.capabilities },
+			...manifest.runtime === void 0 ? {} : { runtime: manifest.runtime },
+			samples
+		}
+	};
+}
+//#endregion
+//#region src/widget.ts
+/**
+* Generated Widget Host 的唯一运行入口。Widget 作者只导出 activate/deactivate，
+* 不直接调用此函数；CLI 生成的 widget-host.ts 负责调用它。
+*/
+function runWidgetHost(widget, options = {}) {
+	const client = createWidgetRuntime((typeof widget === "function" ? { activate: widget } : widget).activate, options);
+	const whenReady = client.ready();
+	whenReady.catch((reason) => {
+		const error = toStartupError(reason);
+		if (options.onStartupError) {
+			options.onStartupError(error);
+			return;
+		}
+		console.error(`[Widget 启动失败] ${error.message}`, error);
+	});
+	return {
+		whenReady,
+		state: client.state,
+		dispose: client.dispose
+	};
+}
+function disposable(registration) {
+	return typeof registration === "function" ? { dispose: registration } : registration;
+}
+function createContext(client, payload, renderHandlers, registrations, signal) {
+	return {
+		instanceId: payload.instanceId,
+		locale: payload.locale,
+		theme: payload.theme,
+		signal,
+		capabilities: {
+			granted: payload.capabilities,
+			request: (request, options) => client.requestCapability(request, options)
+		},
+		files: { download: (input, options) => client.requestCapability({
+			operation: "files.download",
+			input
+		}, options) },
+		tasks: { watch: (input, options) => client.requestCapability({
+			operation: "tasks.watch",
+			input
+		}, options) },
+		network: client.network,
+		ui: {
+			state: {
+				read: (key, options) => client.requestCapability({
+					operation: "ui.state",
+					input: {
+						action: "read",
+						key
+					}
+				}, options),
+				write: (key, value, options) => client.requestCapability({
+					operation: "ui.state",
+					input: {
+						action: "write",
+						key,
+						value
+					}
+				}, options)
+			},
+			present: (surface, options) => client.present(surface, options),
+			close: (options) => client.closePresentation(options),
+			changeSurface: (surface, options) => client.changePresentationSurface(surface, options)
+		},
+		events: { on(handlerOrName, maybeHandler) {
+			const result = { dispose: typeof handlerOrName === "string" ? client.onEvent(handlerOrName, maybeHandler) : client.onEvent(handlerOrName) };
+			registrations.add(result);
+			return result;
+		} },
+		subscriptions: { add(registration) {
+			registrations.add(disposable(registration));
+		} },
+		render(handler) {
+			renderHandlers.add(handler);
+			const result = { dispose: () => {
+				renderHandlers.delete(handler);
+			} };
+			registrations.add(result);
+			return result;
+		},
+		resize: (width, height) => client.resize(width, height)
+	};
+}
+function createWidgetRuntime(activate, options = {}) {
+	let client;
+	let widgetDispose;
+	let context;
+	const renderHandlers = /* @__PURE__ */ new Set();
+	const registrations = /* @__PURE__ */ new Set();
+	const lifetime = new AbortController();
+	client = createWidgetClient({
+		...options,
+		events: {
+			...options.events,
+			async onInit(payload) {
+				context = createContext(client, payload, renderHandlers, registrations, lifetime.signal);
+				const registration = await activate(context);
+				if (registration !== void 0) {
+					widgetDispose = disposable(registration);
+					context.subscriptions.add(widgetDispose);
+				}
+			},
+			onRender(request, update) {
+				const renderContext = {
+					phase: update ? "update" : "initial",
+					signal: lifetime.signal
+				};
+				for (const handler of [...renderHandlers]) try {
+					Promise.resolve(handler(request, renderContext)).catch(() => {});
+				} catch {}
+			},
+			onDispose() {
+				lifetime.abort();
+				for (const registration of [...registrations]) try {
+					Promise.resolve(registration.dispose()).catch(() => {});
+				} catch {}
+				registrations.clear();
+				renderHandlers.clear();
+				context = void 0;
+				widgetDispose = void 0;
+			}
+		}
+	});
+	return {
+		ready: () => client.ready(),
+		state: () => client.currentState,
+		dispose: () => client.dispose()
+	};
+}
+function toStartupError(reason) {
+	return reason instanceof Error ? reason : new Error("Widget 启动失败", { cause: reason });
+}
+//#endregion
+export { WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, compileWidgetPluginManifest, isWidgetActivationEvent, isWidgetEventName, runWidgetHost };

package/dist/manifest.d.ts

@@ -0,0 +1,13 @@
+import type { WidgetManifest, WidgetPluginManifest } from "@dp-bohrium/widget-contracts";
+export interface CompileWidgetPluginManifestOptions {
+    readonly samples?: NonNullable<WidgetPluginManifest["samples"]>;
+    /** Host bundle entry. CLI supplies this after the project is built. */
+    readonly hostEntry?: string;
+}
+/**
+ * 将开发者维护的插件清单编译为宿主可加载的宿主清单。
+ *
+ * 这是构建工具的边界函数，不是类型提示入口：作者直接编辑带 `$schema` 的 JSON，
+ * SDK 版本从当前安装包读取，宿主入口默认落到 dist/widget.js，内部 slot 标识只在这里生成。
+ */
+export declare function compileWidgetPluginManifest(manifest: WidgetPluginManifest, options?: CompileWidgetPluginManifestOptions): WidgetManifest;

package/dist/runtime/bootstrap.d.ts

@@ -2,8 +2,10 @@ import type { CapabilityRequest, CapabilityResult, InitPayload, PresentationCapa
 import { type PresentationFocusDirection, type PresentationSurface, type WidgetCapabilityRequestOptions, type WidgetClientEvents, type WidgetClientState } from "./client.js";
 import { type SubscribeWidgetEventsOptions, type WidgetEventSubscription, type WidgetToolHooks } from "./events.js";
 import type { WidgetNetworkClient } from "./network.js";
+import { WIDGET_SDK_VERSION } from "./version.js";
 export declare const WIDGET_BOOTSTRAP_READY: "widget-bootstrap-ready";
 export declare const WIDGET_HOST_CONNECT: "widget-host-connect";
+export { WIDGET_SDK_VERSION };
 export interface WidgetHostConnectMessage {
     type: typeof WIDGET_HOST_CONNECT;
     protocolVersion: 1;
@@ -27,8 +29,10 @@ export interface WidgetLiveEventContext {
 }
 /** 由 Host 通过当前 MessageChannel 推送的实时 Workflow 事件处理器。 */
 export type WidgetLiveEventHandler = (event: WidgetLiveEvent, context: WidgetLiveEventContext) => void | Promise<void>;
+export type WidgetLiveEventName = WidgetLiveEvent["type"];
 export interface CreateWidgetClientOptions {
-    widgetSdkVersion: string;
+    /** 低层协议字段；Widget Host 会从已安装 SDK 自动读取 SDK 版本。 */
+    widgetSdkVersion?: string;
     hostApiVersion?: 1;
     handshakeTimeoutMs?: number;
     capabilityTimeoutMs?: number;
@@ -90,7 +94,7 @@ export declare class WidgetRuntimeClient {
     /** 订阅 Host 从当前 Workflow 流实时推送的全部聚合事件。 */
     onEvent(handler: WidgetLiveEventHandler): () => void;
     /** 订阅 Host 从当前 Workflow 流实时推送的指定聚合事件。 */
-    onEvent(eventName: string, handler: WidgetLiveEventHandler): () => void;
+    onEvent(eventName: WidgetLiveEventName, handler: WidgetLiveEventHandler): () => void;
     onTool(hooks: WidgetToolHooks, options: Pick<SubscribeWidgetEventsOptions, "cursor" | "onError">): WidgetEventSubscription;
     invokeAction(input: Extract<CapabilityRequest, {
         operation: "actions.invoke";

package/dist/runtime/index.d.ts

@@ -1,5 +1,5 @@
-export type { CreateWidgetClientOptions, WidgetClientFactoryOptions, WidgetDisposeEvent, WidgetHostConnectMessage, WidgetLiveEventContext, WidgetLiveEventHandler, WidgetRuntimeWindow, WidgetSize, } from "./bootstrap.js";
-export { createWidgetClient, isWidgetHostConnectMessage, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WidgetRuntimeClient, } from "./bootstrap.js";
+export type { CreateWidgetClientOptions, WidgetClientFactoryOptions, WidgetDisposeEvent, WidgetHostConnectMessage, WidgetLiveEventContext, WidgetLiveEventHandler, WidgetLiveEventName, WidgetRuntimeWindow, WidgetSize, } from "./bootstrap.js";
+export { createWidgetClient, isWidgetHostConnectMessage, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WIDGET_SDK_VERSION, WidgetRuntimeClient, } from "./bootstrap.js";
 export type { PresentationFocusDirection, PresentationSurface, WidgetCapabilityRequestOptions, WidgetClientEvents, WidgetClientOptions, WidgetClientState, } from "./client.js";
 export { PRESENTATION_CONFIRMATION_TIMEOUT_MS, WidgetClient, } from "./client.js";
 export type { SubscribeWidgetEventsOptions, WidgetEventBatchContext, WidgetEventSubscription, WidgetToolHooks, } from "./events.js";

package/dist/runtime/index.js

@@ -1,3 +1,3 @@
-import { a as isWidgetHostConnectMessage, i as createWidgetClient, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as WidgetClient, t as WIDGET_BOOTSTRAP_READY } from "../runtime-h-oTCwcs.js";
+import { a as isWidgetHostConnectMessage, c as WIDGET_SDK_VERSION, i as createWidgetClient, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as WidgetClient, t as WIDGET_BOOTSTRAP_READY } from "../runtime-B5kilTcQ.js";
 import { i as isWidgetProtocolMessage, r as MessagePortTransport } from "../protocol-endpoint-I78q3jVT.js";
-export { MessagePortTransport, PRESENTATION_CONFIRMATION_TIMEOUT_MS, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WidgetClient, WidgetRuntimeClient, createWidgetClient, isWidgetHostConnectMessage, isWidgetProtocolMessage };
+export { MessagePortTransport, PRESENTATION_CONFIRMATION_TIMEOUT_MS, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WIDGET_SDK_VERSION, WidgetClient, WidgetRuntimeClient, createWidgetClient, isWidgetHostConnectMessage, isWidgetProtocolMessage };

package/dist/runtime/version.d.ts

@@ -0,0 +1,2 @@
+/** 从当前安装的 SDK package.json 读取版本，插件作者不需要重复填写。 */
+export declare const WIDGET_SDK_VERSION: string;

package/dist/{runtime-h-oTCwcs.js → runtime-B5kilTcQ.js}

@@ -1,4 +1,9 @@
 import { r as MessagePortTransport, t as ProtocolEndpoint } from "./protocol-endpoint-I78q3jVT.js";
+//#endregion
+//#region src/runtime/version.ts
+/** 从当前安装的 SDK package.json 读取版本，插件作者不需要重复填写。 */
+const WIDGET_SDK_VERSION = "0.1.0";
+//#endregion
 //#region src/runtime/network.ts
 const failureReasons = /* @__PURE__ */ new Set([
 	"unsupported",
@@ -1101,7 +1106,7 @@ var WidgetRuntimeClient = class {
 			const clientOptions = {
 				transport: new MessagePortTransport(port),
 				channelId: event.data.channelId,
-				widgetSdkVersion: this.options.widgetSdkVersion,
+				widgetSdkVersion: this.options.widgetSdkVersion ?? WIDGET_SDK_VERSION,
 				initialPayload: event.data.initPayload,
 				...this.options.hostApiVersion === void 0 ? {} : { hostApiVersion: this.options.hostApiVersion },
 				...this.options.capabilityTimeoutMs === void 0 ? {} : { capabilityTimeoutMs: this.options.capabilityTimeoutMs },
@@ -1157,4 +1162,4 @@ function createWidgetClient(options) {
 	return new WidgetRuntimeClient(options);
 }
 //#endregion
-export { isWidgetHostConnectMessage as a, createWidgetClient as i, WIDGET_HOST_CONNECT as n, PRESENTATION_CONFIRMATION_TIMEOUT_MS as o, WidgetRuntimeClient as r, WidgetClient as s, WIDGET_BOOTSTRAP_READY as t };
+export { isWidgetHostConnectMessage as a, WIDGET_SDK_VERSION as c, createWidgetClient as i, WIDGET_HOST_CONNECT as n, PRESENTATION_CONFIRMATION_TIMEOUT_MS as o, WidgetRuntimeClient as r, WidgetClient as s, WIDGET_BOOTSTRAP_READY as t };

package/dist/widget.d.ts

@@ -0,0 +1,137 @@
+import type { CapabilityRequest, CapabilityResult, FileDownloadResult, FileReference, GrantedCapability, RenderRequest, TaskObservationBatch, Theme, UiStateResult, UiStateWriteResult, WidgetEventName, WidgetLiveEvent } from "@dp-bohrium/widget-contracts";
+import { type CreateWidgetClientOptions, type WidgetClientFactoryOptions, type WidgetClientState, type WidgetLiveEventContext, type WidgetLiveEventHandler } from "./runtime/index.js";
+import type { WidgetNetworkClient } from "./runtime/network.js";
+export interface WidgetDisposable {
+    dispose(): void | Promise<void>;
+}
+export type WidgetDisposeRegistration = WidgetDisposable | (() => void | Promise<void>);
+export interface WidgetRenderContext {
+    readonly phase: "initial" | "update";
+    readonly signal: AbortSignal;
+}
+export type WidgetRenderHandler = (request: RenderRequest, context: WidgetRenderContext) => void | PromiseLike<void>;
+export interface WidgetEventApi {
+    on(handler: WidgetLiveEventHandler): WidgetDisposable;
+    on<T extends WidgetEventName>(eventName: T, handler: (event: WidgetLiveEvent & {
+        readonly type: T;
+    }, context: WidgetLiveEventContext) => void | Promise<void>): WidgetDisposable;
+}
+export interface WidgetCapabilityApi {
+    readonly granted: readonly GrantedCapability[];
+    request(request: CapabilityRequest, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CapabilityResult>;
+}
+export interface WidgetFileApi {
+    /** 请求 Host 在用户确认后通过宿主 Download Adapter 保存文件。 */
+    download(input: {
+        readonly file: FileReference;
+        readonly suggestedName: string;
+    }, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<FileDownloadCapabilityResult>;
+}
+export type FileDownloadCapabilityResult = {
+    readonly ok: true;
+    readonly data: FileDownloadResult;
+} | Extract<CapabilityResult, {
+    readonly ok: false;
+}>;
+export interface WidgetTaskApi {
+    /**
+     * 读取一次受 Host 限制的任务快照和事件页。调用方使用返回的 cursor
+     * 继续轮询；此 API 不创建、调度或取消任务。
+     */
+    watch(input: {
+        readonly taskId: string;
+        readonly cursor?: string;
+        readonly limit?: number;
+    }, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<TaskWatchCapabilityResult>;
+}
+export type TaskWatchCapabilityResult = {
+    readonly ok: true;
+    readonly data: TaskObservationBatch;
+} | Extract<CapabilityResult, {
+    readonly ok: false;
+}>;
+export interface WidgetUiStateApi {
+    read(key: string, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<UiStateReadCapabilityResult>;
+    write(key: string, value: import("@dp-bohrium/widget-contracts").JsonValue, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<UiStateWriteCapabilityResult>;
+}
+export type UiStateReadCapabilityResult = {
+    readonly ok: true;
+    readonly data: UiStateResult;
+} | Extract<CapabilityResult, {
+    readonly ok: false;
+}>;
+export type UiStateWriteCapabilityResult = {
+    readonly ok: true;
+    readonly data: UiStateWriteResult;
+} | Extract<CapabilityResult, {
+    readonly ok: false;
+}>;
+export interface WidgetUiApi {
+    readonly state: WidgetUiStateApi;
+    present(surface: "workspace" | "floating" | "overlay", options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CapabilityResult>;
+    close(options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CapabilityResult>;
+    changeSurface(surface: "workspace" | "floating" | "overlay", options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CapabilityResult>;
+}
+export interface WidgetContext {
+    readonly instanceId: string;
+    readonly locale: string;
+    readonly theme: Theme;
+    /** Widget Host 的生命周期信号；Host 停用或 Bridge 断开时会 abort。 */
+    readonly signal: AbortSignal;
+    readonly capabilities: WidgetCapabilityApi;
+    readonly files: WidgetFileApi;
+    readonly tasks: WidgetTaskApi;
+    readonly network: WidgetNetworkClient;
+    readonly ui: WidgetUiApi;
+    readonly events: WidgetEventApi;
+    readonly subscriptions: {
+        add(registration: WidgetDisposeRegistration): void;
+    };
+    render(handler: WidgetRenderHandler): WidgetDisposable;
+    resize(width: number, height: number): void;
+}
+export type WidgetActivation = (context: WidgetContext) => void | WidgetDisposeRegistration | PromiseLike<WidgetDisposeRegistration | void>;
+export interface WidgetHostOptions extends Omit<CreateWidgetClientOptions, "widgetSdkVersion" | "events" | "onInit" | "onRender" | "onUpdate" | "onEvent" | "onDispose"> {
+    readonly events?: Pick<NonNullable<WidgetClientFactoryOptions["events"]>, "onError">;
+    /** Widget Host 启动失败时的统一处理入口。 */
+    readonly onStartupError?: (error: Error) => void;
+}
+export interface WidgetModule {
+    activate: WidgetActivation;
+    deactivate?: () => void | PromiseLike<void>;
+}
+export interface WidgetHandle {
+    /** 供测试、开发工具和 Host 编排等待激活完成。 */
+    readonly whenReady: Promise<void>;
+    readonly state: () => WidgetClientState;
+    dispose(): void;
+}
+/**
+ * Generated Widget Host 的唯一运行入口。Widget 作者只导出 activate/deactivate，
+ * 不直接调用此函数；CLI 生成的 widget-host.ts 负责调用它。
+ */
+export declare function runWidgetHost(widget: WidgetModule | WidgetActivation, options?: WidgetHostOptions): WidgetHandle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-bohrium/widget-sdk",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "description": "Bohrium Widget 开发者 SDK：在 Widget Bundle 内与 Host 建立 Bridge，并暴露生命周期与能力协议。",
   "license": "MIT",
   "type": "module",
@@ -38,6 +38,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": false,
@@ -45,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dp-bohrium/widget-contracts": "0.0.7"
+    "@dp-bohrium/widget-contracts": "0.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.2.0",