@dp-bohrium/widget-sdk 0.4.1 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +10 -4
- package/CHANGELOG.md +34 -1
- package/README.md +61 -19
- package/assets/licenses/ajv@8.20.0/LICENSE +22 -0
- package/assets/licenses/fast-deep-equal@3.1.3/LICENSE +21 -0
- package/assets/licenses/fast-uri@3.1.6/LICENSE +30 -0
- package/assets/licenses/json-schema-traverse@1.0.0/LICENSE +21 -0
- package/assets/licenses/require-from-string@2.0.2/license +21 -0
- package/assets/licenses/widget-contracts.LICENSE +21 -0
- package/assets/licenses/widget-sdk.LICENSE +21 -0
- package/assets/schemas/host-runtime-config.schema.json +305 -0
- package/assets/schemas/widget-manifest.schema.json +361 -0
- package/assets/schemas/widget-plugin-manifest.schema.json +162 -0
- package/assets/schemas/widget-runtime-contracts.schema.json +2870 -0
- package/assets/toolchain.json +24 -0
- package/conformance/bridge/capability-request.json +23 -0
- package/conformance/bridge/files-download-request.json +23 -0
- package/conformance/bridge/files-read-versioned-request.json +25 -0
- package/conformance/bridge/files-write-request.json +25 -0
- package/conformance/bridge/files-write-success.json +25 -0
- package/conformance/bridge/network-fetch-denied.json +16 -0
- package/conformance/bridge/network-fetch-request.json +19 -0
- package/conformance/bridge/network-fetch-success.json +22 -0
- package/conformance/bridge/presentation-change-surface-request.json +14 -0
- package/conformance/bridge/presentation-close-request.json +14 -0
- package/conformance/bridge/presentation-close-success.json +11 -0
- package/conformance/bridge/presentation-downgrade-success.json +14 -0
- package/conformance/bridge/presentation-focus-backward-request.json +14 -0
- package/conformance/bridge/presentation-focus-boundary-success.json +14 -0
- package/conformance/bridge/presentation-focus-forward-request.json +14 -0
- package/conformance/bridge/presentation-init.json +70 -0
- package/conformance/bridge/presentation-policy-denied.json +16 -0
- package/conformance/bridge/presentation-present-request.json +14 -0
- package/conformance/bridge/presentation-user-denied.json +16 -0
- package/conformance/bridge/ready.json +11 -0
- package/conformance/bridge/region-acquire-request.json +14 -0
- package/conformance/bridge/tasks-list-request.json +17 -0
- package/conformance/bridge/tasks-watch-request.json +18 -0
- package/conformance/bridge/ui-state-write-request.json +18 -0
- package/conformance/bundles/minimal-file-preview/entry.js +1 -0
- package/conformance/bundles/minimal-file-preview/manifest.json +12 -0
- package/conformance/bundles/minimal-file-preview/samples/file-preview.json +1 -0
- package/conformance/bundles/minimal-panel/entry.js +1 -0
- package/conformance/bundles/minimal-panel/manifest.json +11 -0
- package/conformance/bundles/minimal-panel/samples/panel.json +1 -0
- package/conformance/bundles/minimal-tool-result/entry.js +1 -0
- package/conformance/bundles/minimal-tool-result/manifest.json +11 -0
- package/conformance/bundles/minimal-tool-result/samples/tool-result.json +1 -0
- package/conformance/file-grants/write.json +8 -0
- package/conformance/file-responses/list.json +1 -0
- package/conformance/file-responses/metadata.json +11 -0
- package/conformance/file-responses/mutation-conflict.json +6 -0
- package/conformance/file-responses/permission-denied.json +6 -0
- package/conformance/file-responses/read-revision-only.json +8 -0
- package/conformance/file-responses/read-unversioned-range.json +12 -0
- package/conformance/file-responses/read-versioned.json +12 -0
- package/conformance/file-responses/resource-limit.json +1 -0
- package/conformance/file-responses/revision-conflict.json +6 -0
- package/conformance/file-responses/text-content.json +7 -0
- package/conformance/file-responses/write-outcome-unknown.json +6 -0
- package/conformance/file-responses/write-success.json +15 -0
- package/conformance/host-runtime-config/invalid-host-service-expiry.json +85 -0
- package/conformance/host-runtime-config/invalid-host-service-identity.json +85 -0
- package/conformance/host-runtime-config/invalid-host-service-permission.json +85 -0
- package/conformance/host-runtime-config/invalid-host-service-status.json +65 -0
- package/conformance/host-runtime-config/invalid-missing-manifest-fields.json +55 -0
- package/conformance/host-runtime-config/invalid-static-origins.json +60 -0
- package/conformance/host-runtime-config/valid-host-service-authorization-required.json +65 -0
- package/conformance/host-runtime-config/valid-host-service-authorization.json +85 -0
- package/conformance/host-runtime-config/valid-no-requested-permissions.json +52 -0
- package/conformance/host-runtime-config/valid.json +85 -0
- package/conformance/invalid-bridge-messages/network-fetch-mixed-case-forbidden-header.json +21 -0
- package/conformance/invalid-file-grants/extra-file-scope.json +9 -0
- package/conformance/invalid-file-grants/missing-write-limits.json +4 -0
- package/conformance/invalid-file-requests/arbitrary-path.json +16 -0
- package/conformance/invalid-file-requests/missing-expected-revision.json +14 -0
- package/conformance/invalid-file-requests/missing-mutation-id.json +14 -0
- package/conformance/invalid-file-requests/path-in-reference.json +16 -0
- package/conformance/invalid-file-results/read-empty-revision.json +5 -0
- package/conformance/invalid-file-results/read-null-revision.json +5 -0
- package/conformance/invalid-file-results/write-missing-mutation-id.json +11 -0
- package/conformance/invalid-manifests/missing-target.json +11 -0
- package/conformance/invalid-manifests/presentation-duplicate-surfaces.json +16 -0
- package/conformance/invalid-manifests/presentation-empty-surfaces.json +14 -0
- package/conformance/invalid-manifests/presentation-unknown-surface.json +16 -0
- package/conformance/invalid-manifests/unknown-field.json +12 -0
- package/conformance/invalid-network-requests/mixed-case-forbidden-header.json +11 -0
- package/conformance/invalid-presentation-grants/duplicate-surfaces.json +5 -0
- package/conformance/invalid-presentation-grants/empty-surfaces.json +5 -0
- package/conformance/invalid-presentation-grants/false-confirmation.json +5 -0
- package/conformance/invalid-presentation-grants/missing-confirmation.json +4 -0
- package/conformance/invalid-presentation-grants/unknown-surface.json +5 -0
- package/conformance/invalid-presentation-requests/change-surface-missing-surface.json +4 -0
- package/conformance/invalid-presentation-requests/close-with-surface.json +4 -0
- package/conformance/invalid-presentation-requests/focus-boundary-missing-direction.json +4 -0
- package/conformance/invalid-presentation-requests/focus-boundary-unknown-direction.json +4 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-coordinates.json +9 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-event-provenance.json +8 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-generation.json +8 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-identity.json +12 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-key.json +8 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-modifiers.json +11 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-selector.json +8 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-surface.json +8 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-target.json +8 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-timestamp.json +8 -0
- package/conformance/invalid-presentation-requests/focus-boundary-with-z-index.json +8 -0
- package/conformance/invalid-presentation-requests/present-missing-surface.json +4 -0
- package/conformance/invalid-presentation-requests/unknown-surface.json +4 -0
- package/conformance/invalid-presentation-requests/widget-controls-coordinates.json +9 -0
- package/conformance/invalid-presentation-requests/widget-controls-geometry.json +8 -0
- package/conformance/invalid-presentation-requests/widget-controls-instance-id.json +8 -0
- package/conformance/invalid-presentation-requests/widget-controls-principal.json +8 -0
- package/conformance/invalid-presentation-requests/widget-controls-run-id.json +4 -0
- package/conformance/invalid-presentation-requests/widget-controls-widget-id.json +8 -0
- package/conformance/invalid-presentation-requests/widget-controls-widget-version-id.json +8 -0
- package/conformance/invalid-presentation-requests/widget-controls-z-index.json +4 -0
- package/conformance/invalid-render-inputs/malformed.json +17 -0
- package/conformance/manifests/valid-file-preview.json +12 -0
- package/conformance/manifests/valid-file-write-preview.json +30 -0
- package/conformance/manifests/valid-network.json +15 -0
- package/conformance/manifests/valid-panel.json +11 -0
- package/conformance/manifests/valid-presentation-panel.json +21 -0
- package/conformance/manifests/valid-region-panel.json +18 -0
- package/conformance/manifests/valid-tool-result.json +14 -0
- package/conformance/render-inputs/compatibility/literature-search-paper-results.json +75 -0
- package/conformance/render-inputs/compatibility/scientific-bibliography-bibtex.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-dataset-csv.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-manuscript-latex.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-manuscript-markdown.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-molecule-mol.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-molecule-mol2.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-notebook-ipynb.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-paper-pdf.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-protein-pdb.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-source-python.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-structure-cif.json +47 -0
- package/conformance/render-inputs/compatibility/scientific-structure-poscar.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-structure-stru.json +10 -0
- package/conformance/render-inputs/compatibility/scientific-trajectory-xyz.json +10 -0
- package/conformance/render-inputs/compatibility/thinking-process-paper-search.json +25 -0
- package/conformance/render-inputs/compatibility/thinking-process-scholar-search.json +25 -0
- package/conformance/render-inputs/compatibility/thinking-process-web-search.json +25 -0
- package/conformance/render-inputs/compatibility/workspace-file-search.json +24 -0
- package/conformance/render-inputs/compatibility/workspace-file-tree.json +24 -0
- package/conformance/render-inputs/empty.json +10 -0
- package/conformance/render-inputs/file-preview.json +10 -0
- package/conformance/render-inputs/incremental-update.json +10 -0
- package/conformance/render-inputs/large.json +10 -0
- package/conformance/render-inputs/malformed.json +1 -0
- package/conformance/render-inputs/panel.json +10 -0
- package/conformance/render-inputs/partial-state-full-snapshot.json +40 -0
- package/conformance/render-inputs/tool-result.json +10 -0
- package/conformance/resource-budgets/corpus.json +431 -0
- package/dist/cli.mjs +15577 -0
- package/dist/contracts.d.ts +2 -0
- package/dist/contracts.js +1 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +42 -8
- package/dist/runtime/index.js +1 -1
- package/dist/{runtime-RyAEhkyn.js → runtime-D7KxTtdu.js} +1 -1
- package/dist/widget.d.ts +20 -1
- package/llms.txt +11 -1
- package/package.json +17 -3
- package/schemas/host-runtime-config.schema.json +305 -0
- package/schemas/widget-manifest.schema.json +361 -0
- package/schemas/widget-plugin-manifest.schema.json +162 -0
- package/schemas/widget-runtime-contracts.schema.json +2870 -0
package/AGENTS.md
CHANGED
|
@@ -1,20 +1,25 @@
|
|
|
1
1
|
# Widget SDK Agent 使用说明
|
|
2
2
|
|
|
3
|
-
`@dp-bohrium/widget-sdk` 是
|
|
3
|
+
`@dp-bohrium/widget-sdk` 是 Widget 作者的统一代码、类型与 Schema 入口。Agent 先读取 `llms.txt`,再
|
|
4
4
|
根据任务选择高层 Widget API、低层 Runtime API 或测试入口;不要自行实现 Bridge 握手。
|
|
5
5
|
|
|
6
6
|
## 常用动作
|
|
7
7
|
|
|
8
8
|
```bash
|
|
9
9
|
pnpm add @dp-bohrium/widget-sdk
|
|
10
|
+
pnpm dlx @dp-bohrium/widget-sdk create my-widget --template panel
|
|
10
11
|
```
|
|
11
12
|
|
|
12
|
-
1. 用 `activate(context)` 实现 Widget
|
|
13
|
+
1. 用 SDK 自带的 `bohr-widget` 创建工程,再用 `activate(context)` 实现 Widget;生成工程只直接依赖 SDK。
|
|
13
14
|
2. 在 Manifest 中声明所需 capability,再使用 `context.capabilities`、`context.files`、
|
|
14
15
|
`context.tasks`、`context.ui` 或 `context.network`。
|
|
15
16
|
3. 在测试中使用 `@dp-bohrium/widget-sdk/testing` 的 `MockWidgetHost`;生产 Bundle 使用
|
|
16
17
|
根入口,不把 testing 入口打进产物。
|
|
17
|
-
4.
|
|
18
|
+
4. 常用作者类型从根入口获取;完整协议用 `/contracts`,编辑器 Schema 用 `/schemas/*.json`。
|
|
19
|
+
SDK 与开发工具负责核对配套协议版本,作者无需直接安装 contracts;直接依赖的旧用法已废弃,
|
|
20
|
+
统一入口切换发布 R1 前迁移并移除,不恢复旧版本执行器。
|
|
21
|
+
5. 低层协议客户端从 `@dp-bohrium/widget-sdk/runtime` 导入。根入口的 `WidgetRenderContext`
|
|
22
|
+
表示渲染回调的 phase/signal,协议同名类型从 `/contracts` 导入。
|
|
18
23
|
|
|
19
24
|
## 错误恢复
|
|
20
25
|
|
|
@@ -30,4 +35,5 @@ pnpm add @dp-bohrium/widget-sdk
|
|
|
30
35
|
|
|
31
36
|
SDK 不授予权限、不上传或发布 Bundle、不决定 iframe/CSP 策略,也不保证脱离 Host 可以运行。
|
|
32
37
|
`ok=true` 只表示当前调用被 Runtime/Host 接受;真实授权、渲染和生产绑定由 Host 与平台负责。
|
|
33
|
-
发布包使用精确 SemVer;升级 SDK
|
|
38
|
+
发布包使用精确 SemVer;升级 SDK 时让开发工具核对配套协议和生成 Bundle 的 digest。
|
|
39
|
+
SDK 的 Node 命令与浏览器 Runtime 使用独立构建入口;不要从根入口或 `/runtime` 导入 CLI 模块。
|
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,39 @@
|
|
|
1
1
|
# `@dp-bohrium/widget-sdk` 变更记录
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## 0.6.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 7c21acf: SDK 发布包新增 `bohr-widget` 可执行入口并内置固定工具链资产,使新工程只需精确安装 SDK 即可完成
|
|
8
|
+
创建、构建、校验、开发和打包。现有 widget-cli 暂按现行发布治理复用同一份命令实现与原有分发身份,
|
|
9
|
+
作为过渡兼容分发;两种入口创建或迁移的新工程都只依赖 SDK,SDK bin 不根据旧工程依赖回选历史执行器。
|
|
10
|
+
两包同时安装时不保证同名命令保留旧 CLI 身份;旧工程须移除 CLI、重新安装,并由 SDK 重新构建 receipt
|
|
11
|
+
后再校验与打包,receipt 严格校验不变。
|
|
12
|
+
复用的命令源码与构建输入纳入 SDK 版本门禁;本次不改变 integration v2、工程锁或发布 Tag 协议。
|
|
13
|
+
Widget 作者 skill 同步改用 SDK 创建入口,避免 Agent 为新工程重新引入独立 CLI 依赖。
|
|
14
|
+
- 31e930e: 统一 Widget 作者入口:SDK 根入口导出常用作者类型,并新增 `/contracts`、`/schemas/*.json` 和
|
|
15
|
+
`/conformance/*` 子入口,使作者与 Host 无需直接安装 contracts。直接声明或导入 contracts 的旧用法
|
|
16
|
+
进入迁移期,统一入口切换发布 R1 前应迁移到 SDK;规范协议类型仍由 contracts 唯一维护。
|
|
17
|
+
|
|
18
|
+
### Patch Changes
|
|
19
|
+
|
|
20
|
+
- @dp-bohrium/widget-contracts@0.6.0
|
|
21
|
+
|
|
22
|
+
## 0.5.0
|
|
23
|
+
|
|
24
|
+
### 新增
|
|
25
|
+
|
|
26
|
+
**1. 增加任务发现 API**
|
|
27
|
+
|
|
28
|
+
- 新增 `context.tasks.list({ cursor, limit }, options)`,一次读取 Host 授权的任务摘要页;返回的 `taskId` 可继续传给既有 `context.tasks.watch`。
|
|
29
|
+
- SDK 不自行轮询或缓存列表,Widget 应遵守 `tasks.list` grant 的 `minPollMs`;该 API 不创建、调度或取消任务。
|
|
30
|
+
|
|
31
|
+
### 修复
|
|
32
|
+
|
|
33
|
+
- `context.render` 的同步异常与异步拒绝不再静默丢失:Guest console 保留原始异常,既有
|
|
34
|
+
`onError` / `events.onError` 收到本地 `RENDER_FAILED` 或 `UPDATE_FAILED` 诊断。
|
|
35
|
+
- 渲染失败不自动终止 Bridge 或重试,其他处理器和后续快照可继续;观察者错误被隔离,停用后
|
|
36
|
+
迟到的拒绝不再产生诊断。公开类型与协议不变,Host 侧非终态诊断仍需单独设计兼容。
|
|
4
37
|
|
|
5
38
|
## 0.4.1
|
|
6
39
|
|
package/README.md
CHANGED
|
@@ -3,27 +3,27 @@
|
|
|
3
3
|
Agent 使用入口:先读 [`llms.txt`](./llms.txt) 获取文档索引,再读 [`AGENTS.md`](./AGENTS.md)
|
|
4
4
|
获取安装、运行时调用和错误恢复规则。
|
|
5
5
|
|
|
6
|
-
Widget 开发者 SDK
|
|
7
|
-
|
|
6
|
+
Widget 开发者 SDK,也是创建、构建、校验、开发和打包 Widget 的统一安装入口。普通作者只实现
|
|
7
|
+
`activate(context)` 和可选的 `deactivate()`;SDK 自带的 `bohr-widget` 会生成 Widget Host 入口,
|
|
8
|
+
负责向 Host 宣告 Bundle、接收转移过来的 `MessagePort`,并暴露共享的
|
|
8
9
|
生命周期与能力协议。作者无需直接处理 `window.postMessage`,也无需手动启动插件。
|
|
9
10
|
|
|
10
11
|
激活事件目录、`context.events` 与低层 `topic` 的边界以本包的 `AGENTS.md`、本 README
|
|
11
|
-
|
|
12
|
+
和本包公开的类型与 Schema 为准;协议实现保持同一份事实源。
|
|
12
13
|
|
|
13
14
|
## 环境要求
|
|
14
15
|
|
|
15
16
|
| 项 | 要求 |
|
|
16
17
|
| --- | --- |
|
|
17
|
-
| Node.js | ≥ 20
|
|
18
|
+
| Node.js | ≥ 20(执行 `bohr-widget` 与构建时;Widget 产物运行在浏览器 iframe 内) |
|
|
18
19
|
| 源码格式 | 纯 ESM,必须经打包器处理后交付 |
|
|
19
20
|
| 运行环境 | 必须由 Bohrium Host 加载,脱离 Host 无法完成握手 |
|
|
20
21
|
| 产物格式 | Host iframe 为 `sandbox="allow-scripts"` 且无 `allow-same-origin` 时,打成 classic script / IIFE(隔离源下 `type="module"` 需要 CORS) |
|
|
21
22
|
|
|
22
23
|
## 安装
|
|
23
24
|
|
|
24
|
-
写 Widget
|
|
25
|
-
|
|
26
|
-
即可。
|
|
25
|
+
写 Widget、调用本地工具、消费 Host 协议都安装本包;contracts 作为 SDK 的精确传递依赖维护,
|
|
26
|
+
不再要求使用者单独选择版本。
|
|
27
27
|
|
|
28
28
|
```bash
|
|
29
29
|
npm install @dp-bohrium/widget-sdk
|
|
@@ -31,9 +31,27 @@ pnpm add @dp-bohrium/widget-sdk
|
|
|
31
31
|
yarn add @dp-bohrium/widget-sdk
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
34
|
+
新建工程只需调用 SDK 自带的命令,生成结果也只直接声明精确 SDK 版本:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pnpm dlx @dp-bohrium/widget-sdk create my-widget --template panel
|
|
38
|
+
cd my-widget
|
|
39
|
+
pnpm install
|
|
40
|
+
pnpm exec bohr-widget build .
|
|
41
|
+
pnpm exec bohr-widget check .
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`@dp-bohrium/widget-cli` 的现有直接安装方式暂按现行发布治理保留,只作为过渡分发、
|
|
45
|
+
历史审计和废弃诊断。作者工程统一只直接安装 SDK;两包提供同名 `bohr-widget`,同时安装时
|
|
46
|
+
不保证保留旧 CLI 身份。旧工程须移除 CLI、重新安装,并由 SDK `build` 重建 receipt 后再打包,
|
|
47
|
+
见[单 SDK 迁移步骤](https://dev.dp.tech/bohrium-widget-sdk/reference/versioning)。SDK 不回选旧执行器,
|
|
48
|
+
receipt 校验保持严格。
|
|
49
|
+
|
|
50
|
+
常用作者类型从本包根入口导入;完整协议从 `@dp-bohrium/widget-sdk/contracts` 导入,
|
|
51
|
+
编辑器 Schema 使用 `@dp-bohrium/widget-sdk/schemas/*.json`。作者无需直接安装 contracts,
|
|
52
|
+
配套协议版本由 SDK 和开发工具核对。Host/控制面也通过本包 `/contracts`、`/schemas/*.json`、
|
|
53
|
+
`/conformance/*` 消费协议,不加载作者 Runtime。直接依赖 contracts 的旧用法已废弃,
|
|
54
|
+
本轮统一入口切换发布 R1 前移除,见[迁移计划](https://dev.dp.tech/bohrium-widget-sdk/reference/versioning)。
|
|
37
55
|
|
|
38
56
|
在自己的 `package.json` 里钉死精确 SemVer,不要用 `^` 或裸 `latest`。SDK 运行时会从已安装
|
|
39
57
|
包自身读取版本,插件源码和 Manifest 不需要再次填写 SDK 版本。
|
|
@@ -78,13 +96,30 @@ Binding 级 Runtime Loader 尚未开放。插件可以按 Runtime/Surface 分层
|
|
|
78
96
|
最多调用一次 `deactivate()`,已完成激活的异步清理可通过 `whenDisposed` 等待;
|
|
79
97
|
- `context.render` 首帧和更新都会收到完整快照,通过 `renderContext.phase` 区分。
|
|
80
98
|
|
|
99
|
+
### 渲染失败与本地诊断
|
|
100
|
+
|
|
101
|
+
`runWidgetHost` 会隔离 `context.render` 处理器的同步异常和异步拒绝,并在 Guest console
|
|
102
|
+
记录原始异常。已有 `onError` 和 `events.onError` 也会收到本地结构化诊断:首帧使用
|
|
103
|
+
`RENDER_FAILED/render`,更新使用 `UPDATE_FAILED/update`,`correlationId` 对应失败快照的
|
|
104
|
+
`requestId`,`retryable` 为 `false`。结构化消息不包含渲染负载或原始异常。
|
|
105
|
+
|
|
106
|
+
这类通知本身不会让 SDK 终止 Bridge、销毁界面或自动重试;其他处理器和后续快照仍可继续,
|
|
107
|
+
插件应保留草稿并提供可恢复的提示。观察者显式调用 `dispose()` 时,SDK 仍尊重停用意图。
|
|
108
|
+
SDK 不回滚处理器失败前已执行的 DOM 修改;界面和草稿的恢复仍由插件拥有。
|
|
109
|
+
观察者自身的同步异常、异步拒绝和 console 失败不会阻断渲染,也不会递归触发 `onError`;
|
|
110
|
+
停用后迟到的渲染拒绝会被消费,但不再产生本地诊断。
|
|
111
|
+
|
|
112
|
+
这些是 Guest 本地出口,SDK 不通过 Bridge 把它们发送给 Host。
|
|
113
|
+
旧 Host 会把 Widget 的协议 `error` 当作致命失败,
|
|
114
|
+
不能用它承载可恢复的渲染诊断;Host 的 `ready` 或 `render-sent` 也不能证明 Guest DOM 渲染成功。
|
|
115
|
+
|
|
81
116
|
## 从 Manifest 到插件运行
|
|
82
117
|
|
|
83
118
|
Manifest 是插件的静态声明,SDK 代码是隔离 iframe 内的运行时实现,Host 负责二者之间的生命周期编排。一个插件可以这样声明:
|
|
84
119
|
|
|
85
120
|
```json
|
|
86
121
|
{
|
|
87
|
-
"$schema": "@dp-bohrium/widget-
|
|
122
|
+
"$schema": "@dp-bohrium/widget-sdk/schemas/widget-plugin-manifest.schema.json",
|
|
88
123
|
"name": "research",
|
|
89
124
|
"version": "1.0.0",
|
|
90
125
|
"entry": "src/widget.ts",
|
|
@@ -133,8 +168,8 @@ Manifest 的 `contributes.widget` 决定;运行时代码只认识统一的 `co
|
|
|
133
168
|
`context.render`、`context.capabilities` 和 `context.ui`。首帧和后续快照通过
|
|
134
169
|
`renderContext.phase` 区分,不需要维护两套回调。
|
|
135
170
|
|
|
136
|
-
Manifest
|
|
137
|
-
|
|
171
|
+
Manifest 的编辑器提示来自本包 `/schemas` 的 JSON Schema 和公开 TypeScript 类型,
|
|
172
|
+
不依赖某个 `defineManifest` 工厂。构建工具调用
|
|
138
173
|
`compileWidgetPluginManifest`,自动补齐 `schemaVersion`、`hostApiVersion`、SDK 版本和
|
|
139
174
|
宿主加载字段;它会直接读取 Manifest 内的 `samples`,只有构建器从别处生成样例时
|
|
140
175
|
才需要传入第二个参数。`createWidgetClient` 是协议级基础实现,不属于 Widget 作者 API;当前根入口只提供统一 Widget API,协议级代码应从
|
|
@@ -142,19 +177,23 @@ TypeScript 类型,不依赖某个 `defineManifest` 工厂。构建工具调用
|
|
|
142
177
|
|
|
143
178
|
受信任的内部 Host/协议测试仍可直接构造低层 Tool Result RenderRequest,但该能力不属于外部作者清单或公共示例。
|
|
144
179
|
|
|
145
|
-
SDK 发布包会生成 `dist/index.d.ts`
|
|
180
|
+
SDK 发布包会生成 `dist/index.d.ts` 与各子入口声明,并通过 `package.json` 的
|
|
146
181
|
`types`/`exports` 暴露。插件安装 `@dp-bohrium/widget-sdk` 后,编辑器会直接获得
|
|
147
182
|
`WidgetContext`、事件名、能力请求、渲染请求和生命周期返回值的类型提示;Manifest
|
|
148
|
-
|
|
183
|
+
编辑器提示由本包的 `/schemas` 和声明文件提供,Schema 在构建时从协议唯一源生成。
|
|
149
184
|
|
|
150
185
|
## 包入口
|
|
151
186
|
|
|
152
187
|
| 入口 | 内容 | 用途 |
|
|
153
188
|
| --- | --- | --- |
|
|
154
|
-
| `.` | `runWidgetHost`、`compileWidgetPluginManifest`
|
|
189
|
+
| `.` | `runWidgetHost`、`compileWidgetPluginManifest` 和常用作者类型 | 生成的生产 Bundle |
|
|
190
|
+
| `./contracts` | 完整协议类型、事件目录与判定函数 | 高级协议集成;同名协议类型显式从此处获取 |
|
|
191
|
+
| `./conformance/*` | 同源协议校验语料 | Host/控制面验证 |
|
|
192
|
+
| `./schemas/*.json` | 作者清单、宿主清单、运行配置与消息 Schema | 编辑器提示和工具校验 |
|
|
155
193
|
| `./testing` | `MemoryTransport`、`MockWidgetHost` | 单元测试 |
|
|
156
194
|
| `./runtime` | 低层 `WidgetClient`、transport 与 bootstrap 常量 | 协议级集成 |
|
|
157
195
|
| `./package.json` | 已安装包的元数据 | SDK 和构建工具自动读取版本,作者无需复制版本字符串 |
|
|
196
|
+
| `bohr-widget` | Node.js 命令入口 | 创建、构建、校验、开发和打包工程;不进入浏览器 Bundle |
|
|
158
197
|
|
|
159
198
|
根入口只导出插件运行时和 Manifest 编译所需的少量值,其余均为类型。低层
|
|
160
199
|
`MessagePortTransport` 与 bootstrap 消息不属于普通 Widget API。
|
|
@@ -179,6 +218,7 @@ SDK 发布包会生成 `dist/index.d.ts` 与对应的 declaration map,并通
|
|
|
179
218
|
| `files.write` | `files.write` | `context.files.write({ file, content, encoding, expectedRevision, mutationId })` |
|
|
180
219
|
| `files.download` | `files.download` | `context.files.download({ file, suggestedName })` |
|
|
181
220
|
| `events.read` | `events`(需列出 `topics`) | 低层分页订阅;`context.events.on(…)` 是 Host 主动推送,不需要该 grant |
|
|
221
|
+
| `tasks.list` | `tasks.list` | `context.tasks.list({ cursor, limit })` |
|
|
182
222
|
| `tasks.watch` | `tasks.watch` | `context.tasks.watch({ taskId, cursor, limit })` |
|
|
183
223
|
| `ui.state` | `state`(`read` / `write`) | `context.ui.state.read(key)` / `write(key, value)` |
|
|
184
224
|
| `actions.invoke` | `actions` | `context.capabilities.request({ operation: "actions.invoke", input })` |
|
|
@@ -217,8 +257,10 @@ if (result.ok) {
|
|
|
217
257
|
业务 payload,不会把 Cookie、Bearer Token 或其他凭据放入 iframe。
|
|
218
258
|
- `context.files.download` 只提交文件引用和建议文件名;Host 在用户确认后经宿主
|
|
219
259
|
Download Adapter 惰性打开内容源。Widget 不会收到源 URL、保存路径或凭据。
|
|
260
|
+
- `context.tasks.list` 只读取一次受限任务摘要页;返回的 `taskId` 是可继续传给
|
|
261
|
+
`context.tasks.watch` 的不透明引用。SDK 不会自行轮询,调用方应遵守 grant 的 `minPollMs`。
|
|
220
262
|
- `context.tasks.watch` 只读取一次受限任务快照和事件页;调用方用返回的 cursor 继续轮询。
|
|
221
|
-
|
|
263
|
+
两个任务 API 都不创建、调度或取消任务,服务端负责任务授权、脱敏和终态保留。
|
|
222
264
|
- `context.ui.state` 只保存按 Widget + Session 隔离的 JSON UI 状态;Host 按 key、单值大小、总字节数和调用
|
|
223
265
|
频率限流。它不能保存任务执行、凭据、文件内容或 Workspace 权限状态。
|
|
224
266
|
- 外部插件的工具结果场景通过 `tool-call-result` 事件作为可选运行时信号;内部 Host/协议测试仍可使用低层 Tool Result RenderRequest
|
|
@@ -312,14 +354,14 @@ import { MockWidgetHost } from "@dp-bohrium/widget-sdk/testing";
|
|
|
312
354
|
## 限制
|
|
313
355
|
|
|
314
356
|
- SDK 不做授权决策,能力是否可用最终由 Host 判定。
|
|
315
|
-
- `tasks.watch`
|
|
357
|
+
- `tasks.list` / `tasks.watch` 是有界发现与观察协议,不是调度器、执行器或取消 API;任务摘要、状态和事件由服务端投影。
|
|
316
358
|
- `invokeAction` 不自动重试,回调完成也不代表工具执行完成。
|
|
317
359
|
- `subscribeEvents` 的 `events.read` 是有界分页读取,不是 websocket;实时推送走
|
|
318
360
|
`onEvent`。当前版本没有单请求取消的独立协议消息:`unsubscribe` 会停止后续轮询并取消
|
|
319
361
|
本地等待,已发出的服务端读取可能完成,但结果被忽略。
|
|
320
362
|
- Host 发来畸形 Bridge 信封或载荷时,transport 报结构化 `MESSAGE_INVALID` 并关闭
|
|
321
363
|
连接,不会让 Widget 悬等。
|
|
322
|
-
- Schema
|
|
364
|
+
- contracts 维护 Schema 与类型的内部唯一事实源;使用者从 SDK 的 `/contracts` 与 `/schemas/*` 公开出口读取。
|
|
323
365
|
|
|
324
366
|
## 许可证
|
|
325
367
|
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2015-2021 Evgeny Poberezkin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2017 Evgeny Poberezkin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
Copyright (c) 2011-2021, Gary Court until https://github.com/garycourt/uri-js/commit/a1acf730b4bba3f1097c9f52e7d9d3aba8cdcaae
|
|
2
|
+
Copyright (c) 2021-present The Fastify team <https://github.com/fastify/fastify#team>
|
|
3
|
+
All rights reserved.
|
|
4
|
+
|
|
5
|
+
Redistribution and use in source and binary forms, with or without
|
|
6
|
+
modification, are permitted provided that the following conditions are met:
|
|
7
|
+
* Redistributions of source code must retain the above copyright
|
|
8
|
+
notice, this list of conditions and the following disclaimer.
|
|
9
|
+
* Redistributions in binary form must reproduce the above copyright
|
|
10
|
+
notice, this list of conditions and the following disclaimer in the
|
|
11
|
+
documentation and/or other materials provided with the distribution.
|
|
12
|
+
* The names of any contributors may not be used to endorse or promote
|
|
13
|
+
products derived from this software without specific prior written
|
|
14
|
+
permission.
|
|
15
|
+
|
|
16
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
17
|
+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
18
|
+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
19
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY
|
|
20
|
+
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
21
|
+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
22
|
+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
23
|
+
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
24
|
+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
25
|
+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
26
|
+
|
|
27
|
+
* * *
|
|
28
|
+
|
|
29
|
+
The complete list of contributors can be found at:
|
|
30
|
+
- https://github.com/garycourt/uri-js/graphs/contributors
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2017 Evgeny Poberezkin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) Vsevolod Strukchinsky <floatdrop@gmail.com> (github.com/floatdrop)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
|
13
|
+
all copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
21
|
+
THE SOFTWARE.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 DP Technology
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 DP Technology
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|