@dp-bohrium/widget-sdk 0.6.0 → 0.8.0

package/AGENTS.md

@@ -16,8 +16,8 @@ pnpm dlx @dp-bohrium/widget-sdk create my-widget --template panel
 3. 在测试中使用 `@dp-bohrium/widget-sdk/testing` 的 `MockWidgetHost`；生产 Bundle 使用
    根入口，不把 testing 入口打进产物。
 4. 常用作者类型从根入口获取；完整协议用 `/contracts`，编辑器 Schema 用 `/schemas/*.json`。
-   SDK 与开发工具负责核对配套协议版本，作者无需直接安装 contracts；直接依赖的旧用法已废弃，
-   统一入口切换发布 R1 前迁移并移除，不恢复旧版本执行器。
+   SDK 与开发工具负责核对内置协议资产与摘要，生成的作者工程不需要重复安装 Contracts 或 CLI。
+   升级旧作者工程时，在新目录准备迁移候选并重新构建，不复用不匹配的执行器。
 5. 低层协议客户端从 `@dp-bohrium/widget-sdk/runtime` 导入。根入口的 `WidgetRenderContext`
    表示渲染回调的 phase/signal，协议同名类型从 `/contracts` 导入。
 
@@ -35,5 +35,36 @@ pnpm dlx @dp-bohrium/widget-sdk create my-widget --template panel
 
 SDK 不授予权限、不上传或发布 Bundle、不决定 iframe/CSP 策略，也不保证脱离 Host 可以运行。
 `ok=true` 只表示当前调用被 Runtime/Host 接受；真实授权、渲染和生产绑定由 Host 与平台负责。
-发布包使用精确 SemVer；升级 SDK 时让开发工具核对配套协议和生成 Bundle 的 digest。
+工程依赖使用精确 SemVer；升级 SDK 时让开发工具核对配套协议和生成 Bundle 的 digest。
 SDK 的 Node 命令与浏览器 Runtime 使用独立构建入口；不要从根入口或 `/runtime` 导入 CLI 模块。
+
+当前执行器采用 integration v3、toolchain v3、工程锁 v2 和 receipt v2。SDK 自包含协议与声明，
+`protocol` 记录固定协议字段版本及 Schema 内容摘要；旧锁或 receipt 必须显式迁移或重新构建。
+
+## 协议事实源
+
+`schemas/` 是协议的唯一事实源，`src/protocol/generated-*.ts` 由根目录
+`pnpm generate:types` 生成；`src/validation/generated-*-schema.ts` 中的嵌入 Schema 同步由该命令生成，不手工维护副本。
+完整协议通过 `/contracts` 导出，conformance 正反语料在 `conformance/`，协议测试在
+`test/protocol/`。协议模块不得依赖 Runtime 初始化、CLI、Node 文件系统或 Host 实现。
+
+包 SemVer、`schemaVersion` / `hostApiVersion` 和能力 domain 版本各自表达不同约束；
+合包不改变协议字段版本，不为类型名添加版本后缀，也不放宽非法输入的拒绝条件。
+
+纯 Manifest 编译实现位于 `src/manifest.ts`，根入口的 `compileWidgetPluginManifest`
+绑定当前 SDK 版本；CLI 工程模块直接复用该实现，不另存一份编译算法。
+
+## 内部校验与测试支持
+
+Widget 作者通过 `bohr-widget check/build/pack` 校验工程，CLI 复用内部 `src/validation`
+模块中的同源 Schema 校验实现。校验器与 AJV 内嵌在 Node 命令中，不提供公开校验子入口，
+普通 SDK 根、`/runtime`、`/contracts`、`/testing` 不加载这些实现。内部独立编译产物
+只供仓库构建与测试使用，不进入 SDK tarball。校验通过不代表 Host 已授予权限或网络安全策略已通过。
+
+仓库维护构建由中央准备器分为运行库、Node 工具与分发组装；私有编译器和校验器生成到
+`.build/tooling`，最终 `dist` 只存分发产物。SDK 组装复用同一份 Node 命令及其 chunks，
+不会调用 CLI 完整构建；开发者运行包的 `build` 可准备完整 SDK。
+
+`/testing` 保留 MockWidgetHost、MemoryTransport。仓库专用 fixture 名称、Node 文件加载器、
+兼容场景目录与 conformance runner 位于 `test/support/`，不公开导出或打包；公开协议语料仍在
+`conformance/`，测试支持直接引用该事实源，不复制语料。

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # `@dp-bohrium/widget-sdk` 变更记录
 
+## 0.8.0
+
+### Minor Changes
+
+- 0578f90: 破坏性变更：将独立 Contracts 包合入 SDK，统一通过 SDK 的 `/contracts`、`/schemas/*.json` 和
+  `/conformance/*` 入口提供协议类型、Schema 与校验语料，不再独立发行 Contracts。
+
+### Patch Changes
+
+- 75c4148: 创建 Panel 时不再将自定义 ID 作为警告，成功输出明确说明 ID 可自定义。同步帮助和 Agent 指引，将 `workspace-files` 说明为可选的文件浏览面板预设。
+- 75c4148: 创建 Widget 工程时生成简短的 AGENTS.md，并在 README 与命令输出中直接提供固定 SDK 版本、公开文档、Agent 阅读入口和后续命令。开发前先确认目标工作台能力，安装依赖后使用工程内命令构建、校验和打包，再完成真实 Host 验收。
+
+## 0.7.0
+
+### Minor Changes
+
+- af5aee4: 破坏性变更：取消 `files.read` 的累计字节额度，让文件预览和 Panel 可以持续读取已授权文件。
+  `resourceBudget.files.readBytesPerRun` 与读取 grant 的 `bytesPerRun` 改为已废弃的可选历史字段；
+  新宿主不再下发或执行这两项额度。单次大小、调用频率、并发、授权以及写入、下载和状态预算不变。
+
+  消费者须先升级协议与宿主校验器，再省略旧字段；仍要求历史字段的旧宿主不能消费新配置。
+- 破坏性变更：SDK 自包含协议类型、Schema、测试语料和 `bohr-widget` 命令，Widget 工程只需安装 SDK。
+  Host 或控制面可使用 SDK 的协议子入口，也可独立安装同版 `@dp-bohrium/widget-contracts@0.7.0`。
+
+  integration/toolchain 升为 v3，工程锁和构建回执（receipt）升为 v2。旧工程须保留原源码，
+  在新目录按当前模板迁移并重新构建；旧格式的锁和回执不能直接复用。
+
+### Patch Changes
+
+- 86773d8: 修复开发 Host 面板投影使用 `snapshot.id` 而被正式 Host 拒绝的问题，统一输出既有契约要求的
+  `snapshot.panelType`，并同步开发会话类型声明。Manifest 的 `contribution.id` 和
+  RenderRequest 的 `content.id` 保持原义。
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -1,13 +1,13 @@
 # @dp-bohrium/widget-sdk
 
-Agent 使用入口：先读 [`llms.txt`](./llms.txt) 获取文档索引，再读 [`AGENTS.md`](./AGENTS.md)
-获取安装、运行时调用和错误恢复规则。
-
 Widget 开发者 SDK，也是创建、构建、校验、开发和打包 Widget 的统一安装入口。普通作者只实现
 `activate(context)` 和可选的 `deactivate()`；SDK 自带的 `bohr-widget` 会生成 Widget Host 入口，
 负责向 Host 宣告 Bundle、接收转移过来的 `MessagePort`，并暴露共享的
 生命周期与能力协议。作者无需直接处理 `window.postMessage`，也无需手动启动插件。
 
+使用 Agent 开发时，先读 [`llms.txt`](./llms.txt) 获取文档索引，再读 [`AGENTS.md`](./AGENTS.md)
+了解安装、运行时调用和错误恢复规则。
+
 激活事件目录、`context.events` 与低层 `topic` 的边界以本包的 `AGENTS.md`、本 README
 和本包公开的类型与 Schema 为准；协议实现保持同一份事实源。
 
@@ -22,8 +22,7 @@ Widget 开发者 SDK，也是创建、构建、校验、开发和打包 Widget
 
 ## 安装
 
-写 Widget、调用本地工具、消费 Host 协议都安装本包；contracts 作为 SDK 的精确传递依赖维护，
-不再要求使用者单独选择版本。
+安装 SDK 即可获得 Widget API、协议类型、JSON Schema、测试工具和 `bohr-widget` 命令。
 
 ```bash
 npm install @dp-bohrium/widget-sdk
@@ -41,21 +40,28 @@ pnpm exec bohr-widget build .
 pnpm exec bohr-widget check .
 ```
 
-`@dp-bohrium/widget-cli` 的现有直接安装方式暂按现行发布治理保留，只作为过渡分发、
-历史审计和废弃诊断。作者工程统一只直接安装 SDK；两包提供同名 `bohr-widget`，同时安装时
-不保证保留旧 CLI 身份。旧工程须移除 CLI、重新安装，并由 SDK `build` 重建 receipt 后再打包，
-见[单 SDK 迁移步骤](https://dev.dp.tech/bohrium-widget-sdk/reference/versioning)。SDK 不回选旧执行器，
-receipt 校验保持严格。
-
 常用作者类型从本包根入口导入；完整协议从 `@dp-bohrium/widget-sdk/contracts` 导入，
-编辑器 Schema 使用 `@dp-bohrium/widget-sdk/schemas/*.json`。作者无需直接安装 contracts，
-配套协议版本由 SDK 和开发工具核对。Host/控制面也通过本包 `/contracts`、`/schemas/*.json`、
-`/conformance/*` 消费协议，不加载作者 Runtime。直接依赖 contracts 的旧用法已废弃，
-本轮统一入口切换发布 R1 前移除，见[迁移计划](https://dev.dp.tech/bohrium-widget-sdk/reference/versioning)。
+编辑器 Schema 使用 `@dp-bohrium/widget-sdk/schemas/*.json`，协议测试语料使用
+`@dp-bohrium/widget-sdk/conformance/*`。升级已有工程时，参照
+[版本兼容](https://dev.dp.tech/bohrium-widget-sdk/reference/versioning)。
 
 在自己的 `package.json` 里钉死精确 SemVer，不要用 `^` 或裸 `latest`。SDK 运行时会从已安装
 包自身读取版本，插件源码和 Manifest 不需要再次填写 SDK 版本。
 
+## 校验工程
+
+使用 SDK 自带的命令检查 Widget 工程：
+
+```bash
+pnpm exec bohr-widget build .
+pnpm exec bohr-widget check .
+pnpm exec bohr-widget pack . --out widget.zip
+```
+
+命令复用同一份协议 Schema 校验 Manifest 与样例，并检查入口、资源和打包要求。
+校验实现供内部工具使用，不提供独立公开子入口，普通 SDK 导入不加载校验器或 AJV。
+校验通过只表示本地工程符合检查要求，Host 仍负责实际权限、网络策略与运行隔离。
+
 ## 快速开始
 
 ```ts
@@ -361,7 +367,6 @@ import { MockWidgetHost } from "@dp-bohrium/widget-sdk/testing";
   本地等待，已发出的服务端读取可能完成，但结果被忽略。
 - Host 发来畸形 Bridge 信封或载荷时，transport 报结构化 `MESSAGE_INVALID` 并关闭
   连接，不会让 Widget 悬等。
-- contracts 维护 Schema 与类型的内部唯一事实源；使用者从 SDK 的 `/contracts` 与 `/schemas/*` 公开出口读取。
 
 ## 许可证
 

package/assets/schemas/widget-runtime-contracts.schema.json

@@ -821,7 +821,6 @@
               "additionalProperties": false,
               "required": [
                 "bytesPerRequest",
-                "bytesPerRun",
                 "callsPerMinute"
               ],
               "properties": {
@@ -830,6 +829,8 @@
                   "minimum": 1
                 },
                 "bytesPerRun": {
+                  "description": "历史读取累计额度字段，仅为兼容旧配置保留；当前 files.read 不累计或执行此额度，新宿主不再下发。",
+                  "deprecated": true,
                   "type": "integer",
                   "minimum": 1
                 },
@@ -1998,13 +1999,16 @@
           "additionalProperties": false,
           "required": [
             "readBytesPerRequest",
-            "readBytesPerRun",
             "callsPerMinute",
             "listPageSize"
           ],
           "properties": {
             "readBytesPerRequest": { "type": "integer", "minimum": 1 },
-            "readBytesPerRun": { "type": "integer", "minimum": 1 },
+            "readBytesPerRun": {
+              "description": "历史读取累计额度字段，仅为兼容旧配置保留；当前 files.read 不累计或执行此额度，新宿主不再下发。",
+              "deprecated": true,
+              "type": "integer", "minimum": 1
+            },
             "callsPerMinute": { "type": "integer", "minimum": 1 },
             "listPageSize": { "type": "integer", "minimum": 1 },
             "writeBytesPerRequest": {

package/assets/toolchain.json

@@ -1,11 +1,15 @@
 {
-  "formatVersion": 2,
+  "formatVersion": 3,
   "packageName": "@dp-bohrium/widget-sdk",
-  "cli": "0.6.0",
+  "cli": "0.8.0",
   "profile": {
-    "id": "widget-sdk-0.6.0-contracts-0.6.0",
-    "sdk": "0.6.0",
-    "contracts": "0.6.0"
+    "id": "widget-sdk-0.8.0",
+    "sdk": "0.8.0"
+  },
+  "protocol": {
+    "schemaVersion": 1,
+    "hostApiVersion": 1,
+    "digest": "sha256:ee3023e337559bbf83c096365fe1eb49ce6809a880a5e5d65e2a2f6fd53a7ddb"
   },
   "hostAcceptance": "unknown",
   "documentation": {
@@ -16,9 +20,9 @@
     "llms": "https://dev.dp.tech/bohrium-widget-sdk/llms.txt"
   },
   "digests": {
-    "compiler": "sha256:d541f305c8cccdfc8e122ab84d57103da68c734325df2ead3729cc3a21b7d222",
-    "validators": "sha256:e3e411c6ea3c09f07554222141ccb92124cdf8921ab39dbaeb8f79f4ad8d12aa",
-    "schemas": "sha256:2286156c619d6482471966fb97a2a4adbb9c86ef9ec17225eb1b070d8489dd9c",
-    "templates": "sha256:34f08fb56072c2722a1e02cee09b3130d075853129c333aa8916e0411cee5618"
+    "compiler": "sha256:92822832e958aa5448312194de3d1d4e8515721be2862d978abaefe2143c9c71",
+    "validators": "sha256:47f6793e099e0b4c56da28f42e6ea0c79aecd9cc8915e1746fbd24f999bf05d9",
+    "schemas": "sha256:ee3023e337559bbf83c096365fe1eb49ce6809a880a5e5d65e2a2f6fd53a7ddb",
+    "templates": "sha256:87cf4085fb2769b1b874e9f331258c024f5826c31d0937a6e046b5511b5567c9"
   }
 }