@dp-bohrium/widget-cli 0.4.0 → 0.5.1

package/AGENTS.md

@@ -1,14 +1,13 @@
 # Widget CLI Agent 使用说明
 
-`@dp-bohrium/widget-cli` 是 Widget 工程的本地执行器。Agent 应先读取本文件和
-`llms.txt`，再根据任务选择一个命令；不要猜测参数，也不要把 CLI 的成功输出解释为
-平台 已渲染或已发布。
+`bohr-widget` 用于创建、迁移、校验、开发、构建和打包 Widget 工程。Agent 先读取
+`llms.txt` 和本文件，再按任务选择命令；不要猜测参数，也不要把 CLI 的成功输出解释为
+平台已渲染或已发布。
 
 CLI 本身要求 Node.js >=20，默认生成工程构建器要求 `^22.18.0 || >=24.11.0`。
 `integration.requirements.node` 和 `generatedProjectNode` 分别表达这两项要求。
-本包自包含固定 SDK/contracts、Schema、compiler、校验器和模板，
-通过文档站提供教程与参考。生成工程只直接安装锁定的 SDK 与构建器；
-公开类型和 Schema 从 SDK 导入，contracts 由 SDK 的传递依赖提供。
+生成工程精确依赖 SDK 与构建器，类型、Schema 和工程命令均由 SDK 提供。
+教程与参考见文档站。
 
 先看全局帮助，再按命令查看参数、默认值、示例和必要提示：
 
@@ -24,9 +23,10 @@ pnpm exec bohr-widget --version --json
 `<命令路径> --help` 与 `help <命令路径>` 查看对应层级；例如 `dev -h`、`pack --help` 或
 `migrate dsh --help`。`-v` / `--version` 等价于 `version`，`--version --json` 等价于 `version --json`。
 帮助仅输出本地文本，不执行所选命令或联网获取文档。npm 的全局帮助用
-`npx --no-install bohr-widget --help`，其他命令同样替换前缀；未安装时可用
-新工程用 `pnpm dlx @dp-bohrium/widget-sdk --help` 查看 SDK 自带入口；
-`pnpm dlx @dp-bohrium/widget-cli --help` 在兼容期保持原行为。
+`npx --no-install bohr-widget --help`，其他命令同样替换前缀。
+创建新工程可用 `pnpm dlx @dp-bohrium/widget-sdk --help` 查看 SDK 自带命令；
+工具集成可用 `pnpm dlx @dp-bohrium/widget-cli --help`，并核对执行包版本与 SDK profile。
+升级时迁移并重建工程，不复用不匹配的执行器或 receipt。
 
 ## 入口
 
@@ -50,7 +50,7 @@ bohr-widget help [<命令路径>]
 ```
 
 工程命令均可通过 `--host-compat <声明文件>` 检查目标宿主。接入方先调用
-`integration --json`：`interfaceVersion=2`，`toolchain.formatVersion=2`；返回固定 profile、
+`integration --json`：`interfaceVersion=3`，`toolchain.formatVersion=3`；返回固定 profile、
 执行器与 `documentation`，不返回 `skills`。文档字段为 `url`、`quickStart`、`cli`、`llms`、
 `llmsFull`。先读[文档索引](https://dev.dp.tech/bohrium-widget-sdk/llms.txt)，再选取相关页面；
 需要完整材料时读[完整文档](https://dev.dp.tech/bohrium-widget-sdk/llms-full.txt)。
@@ -61,7 +61,7 @@ bohr-widget help [<命令路径>]
 ## 执行顺序
 
 1. `create` 创建工程后检查返回的 `projectRoot`、`manifestPath`、`packagePath`、`profile`、`name` 和可选
-   `panelId`；工作区文件面板固定使用 `--panel-id workspace-files`，CLI 会补齐三项只读文件能力。
+   `panelId`。Panel ID 可自定义；如需文件浏览面板预设，可使用 `--panel-id workspace-files`，CLI 会补齐三项只读文件能力。
    `warnings` 说明目录名不是合法标识符时 `manifest.name` 已回退为 `widget-<hash>`。
    将 `widget-toolchain.json` 与包管理器 lockfile 一起提交；不手改 profile 绕过版本检查。
    `--extensions` 只用于 file-preview，填写不带前导点的小写扩展名；`--tool` 将默认激活信号替换为
@@ -78,7 +78,7 @@ bohr-widget help [<命令路径>]
    `pack --no-build` 要求上次 `bohr-widget build` 生成的 `.widget-build-receipt.json` 与当前工具链、
    实际依赖、源文件和 `dist` 内容一致；缺失或变化时重新 build，不补写或篡改 receipt。
    receipt 的执行摘要只有 `compiler`、`validators`、`schemas`、`templates` 四项；
-   文档站更新不改变这些摘要、不使 receipt 失效，也不要求 CLI 发版。
+   文档站更新不改变这些摘要，也不使 receipt 失效。
 6. Bohr CLI 或平台侧必须继续使用同一份 ZIP 和 digest；Widget CLI 不负责 upload、preview、
    commit、版本发布或 Agent binding。
 
@@ -140,8 +140,8 @@ bohr-widget help [<命令路径>]
 
 ## 在 Panel 中编辑工作区文件
 
-用户要在文件树面板里直接保存时，用 `create --template panel --panel-id workspace-files` 创建工程，
-再在作者 Manifest 的 `capabilities.files` 中加上 `write: true`（模板默认只有 list/metadata/read）。
+开发文件树面板时，可用 `create --template panel --panel-id workspace-files` 选择文件浏览预设。
+需要保存文件时，在作者 Manifest 的 `capabilities.files` 中加上 `write: true`（模板默认只有 list/metadata/read），并确认目标工作台支持写入。
 
 - 文件引用只取自 `content.data.root` 和 `files.list` 结果中 `kind: "file"` 的项；不拼路径，不自造 id。
 - 运行时没有 `files.write` grant 时保持只读并说明原因；较早的 Host 只向 file-preview 签发写权限。
@@ -168,19 +168,13 @@ profile。`ready` 在此基础上还要求
 `warnings` 里。
 
 旧工程缺少 `widget-toolchain.json` 时，先检查 `doctor` 输出，恢复当前 profile 的精确依赖并安装，
-再运行 `adopt <目录>`。`adopt` 会校验实际安装的 SDK/contracts、Manifest 和 samples 后写锁定文件，
-不自动迁移字段或升级依赖。工程命令会检查精确 SDK 声明与直接安装版本，再从该 SDK 的真实依赖
-核对 contracts 与固定 profile；源码工作区支持 `workspace:*`，发布包必须转换为精确版本。
-已有工程若仍直接声明 contracts，也会继续核对其精确声明与实际版本；缺少依赖时不能向工程祖先
-或 CLI 借用。该作者用法已废弃，机器诊断为 `WIDGET_CLI_DIRECT_CONTRACTS_DEPRECATED`；
-读取 `deprecations` 中的替代出口、`migration.status` 与 `removal`，不要将暂时通过解释为长期支持。
-R0 只做本地改造；统一入口切换发布 R1 前必须移除。实际内部消费者迁移、旧实现删除与
-Host 验收未完成时阻止 R1；不存在的旧 Widget 不要求专用转换规则。版本号由发布计划决定。根计划为
-`docs/plans/2026-10-29-widget-sdk-forge-unified-entry.md`。
-SDK 出口准备批只为消费者迁移提供可安装版本，不代表 Bohr 与内部宿主联合切换 R1 已完成。
+再运行 `adopt <目录>`。`adopt` 会校验实际安装的 SDK 与内置协议资产、Manifest 和 samples 后写锁定文件，
+不自动迁移字段或升级依赖。工程命令会检查精确 SDK 声明与直接安装版本，再核对该 SDK 自身的协议元数据、公开 Schema 与执行摘要；不能通过祖先目录或旧包补齐资产。
+旧工程直接声明 contracts 或 CLI 时会失败；先在独立候选中改用 SDK 出口并移除旧包，
+重新安装、构建和验收。锁和 receipt 为 v2，integration 与 toolchain 为 v3；不自动回选旧执行器。
 保留已有作者源码、跨 profile 升级或准备候选工程时，先读[准备迁移候选](https://dev.dp.tech/bohrium-widget-sdk/guides/migration)，按指南完成候选审阅、plan/apply 和后续验收。
-Host / 控制面在 R0 保留现有公开 contracts，R1 转 SDK 的协议/Schema/conformance 出口；
-协议类型仍由 contracts 同源维护，不给 canonical 类型标记 `@deprecated`。
+Host 或控制面统一使用 SDK 的 `/contracts`、Schema 和 conformance 入口；固定与目标 SDK 配套的
+精确版本，不混用不同版本的协议资产。
 
 ## 宿主兼容声明
 
@@ -189,8 +183,8 @@ Host / 控制面在 R0 保留现有公开 contracts，R1 转 SDK 的协议/Schem
 或过期声明；只有本次在线取得、仍有效且接受当前 profile 时才是 `confirmed`。后者是调用方报告
 的兼容证据，不是发布许可。格式错误、时间无效或 profile 不被接受时按错误处理。
 
-本次只交付 A、B 阶段的本地能力，平台在线发现接口与 Bohr 在线取声明尚需后续接入。不要把
-本地 profile、SDK package.json 或 `unknown` 解释为线上平台已兼容。
+CLI 不自动获取线上声明。调用方需提供目标 Host 的兼容证据，不要把本地 profile、
+SDK package.json 或 `unknown` 解释为线上平台已兼容。
 
 ## 错误处理
 
@@ -228,13 +222,21 @@ Host / 控制面在 R0 保留现有公开 contracts，R1 转 SDK 的协议/Schem
 里带 `profileUrl`、`statusUrl`、`hostUrl`、digest 和 assets，不得把整个 stdout 当作单个 JSON
 文档解析。watch 重建失败时从 `statusUrl` 读取 `lastBuildError`，修复工程后重新保存源码或重新
 执行 build。`statusUrl` 是本地诊断接口，不是生产 Host API。
-每轮重建都会重新核对工具链与实际 SDK/contracts，失败时继续保留上一轮可用 generation。
+每轮重建都会重新核对工具链与实际 SDK 与内置协议摘要，失败时继续保留上一轮可用 generation。
 
 `/core` 是模板、compiler、校验和打包的底层 API；直接调用它时，调用方负责工程锁定、实际依赖
 和宿主兼容策略。完整预检由上述命令提供。`sdkVersion` 不能用来伪造另一代 compiler 的版本。
 
+仓库内部的工程发现、检查、资源收集、ZIP 与摘要实现在 `src/project/`，供命令、维护脚本和
+Demo 服务端复用；纯 Manifest 编译由 SDK 维护。Gallery 路由、展示状态和 Render 投影归 Demo，
+不进入通用工程模块；Demo 浏览器通过服务端导出 ZIP，不导入 Node 工程实现。
+
+仓库构建由中央准备器生成私有 SDK 工具输入和共享 Node 产物，再组装 CLI 的 `dist/assets`。
+CLI 完整构建不调用 SDK 完整构建，也不要求 SDK 最终 `dist` 已存在。SDK 内嵌命令与 CLI
+共用 Node 实现，但各自读取安装位置的工具链身份；私有 `.build` 不进入发布物。
+
 `--open` 优先协商 Widget Development Host v1，旧宿主才回落 legacy profile 并告警。
-该降级仅在 R0 保留且已废弃，R1 前随旧开发桥接迁移删除；目标 Host 应升级到当前协议。
+legacy profile 已废弃，目标 Host 应升级到当前协议。
 descriptor、status、events、control、一次性 claim 和 session token 都通过命令返回的 URL
 与类型声明表达；不要依赖源码仓库中的内部设计文档来猜测协议。
 

package/CHANGELOG.md

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

package/README.md

@@ -2,11 +2,8 @@
 
 创建、开发和打包 Bohrium 自定义 Widget 的命令行工具。
 
-`bohr-widget` 现已随 `@dp-bohrium/widget-sdk` 一起交付，作者工程统一只直接安装 SDK。
-本包在迁移期继续保留原有直接安装与命令行为，但创建和迁移出的新工程同样只依赖 SDK；
-它只按现行发布治理保留过渡分发、历史审计和废弃诊断，按阶段 3 退出新作者安装和发布流程。
-两包的同名命令不保证在 npm/pnpm 下保留旧 CLI 身份。旧工程按[单 SDK 迁移步骤](https://dev.dp.tech/bohrium-widget-sdk/reference/versioning)
-移除本包、重新安装并由 SDK `build` 重建 receipt，再校验和打包；不复用旧 CLI 的 receipt。
+提供 `bohr-widget` 命令，支持工程创建、构建、校验、开发联调与 ZIP 打包。
+SDK 已包含此命令，开发 Widget 推荐从 SDK 开始；脚本或工具集成也可直接调用本包。
 
 [文档站](https://dev.dp.tech/bohrium-widget-sdk/) · [快速开始](https://dev.dp.tech/bohrium-widget-sdk/guides/quick-start) · [命令行指南](https://dev.dp.tech/bohrium-widget-sdk/guides/cli)
 
@@ -15,21 +12,6 @@
 推荐使用 Node.js 24（>=24.11.0）。CLI 本身支持 Node.js >=20，默认模板的构建器要求
 `^22.18.0 || >=24.11.0`。安装 pnpm 或 npm 后即可开始。
 
-SDK 与内部 contracts 的配套版本由 CLI 固定管理，创建工程后安装其依赖即可。
-Widget 作者从 SDK 导入公开类型与 Schema，无需单独选择或安装 contracts。
-
-独立消费者直接依赖 contracts 的旧入口已废弃。`doctor --json` 与工程命令的
-`deprecations` 返回 `WIDGET_CLI_DIRECT_CONTRACTS_DEPRECATED`，包含替代出口、迁移状态和
-移除阶段“统一入口切换发布 R1”。R0 是本地改造，R1 前必须移除旧分支；实际内部消费者
-迁移、SDK 出口交付或 Host 验收未完成时阻止 R1，不能据此延长兼容。版本号以正式发布计划为准，
-不从当前源码推算。当前仍严格核对旧声明和实际依赖，版本漂移继续失败。
-SDK 出口准备批只提供消费者迁移所需的可安装版本，不代表 Bohr 与内部宿主联合切换 R1 已完成。
-
-`migrate project plan/apply` 核对 Agent 准备的候选并写入新目录，具体边界见下方。
-`adopt` 仅为已符合当前 profile 的工程补锁，不升级代码、依赖或旧 Bundle。Host / 控制面在 R0 暂时使用现有已公开 contracts，
-R1 改经 SDK `/contracts`、`/schemas`、`/conformance` 消费；canonical 协议类型本身没有废弃。
-仓库移除计划见 `docs/plans/2026-10-29-widget-sdk-forge-unified-entry.md`。
-
 ## 创建并打包
 
 下面创建一个 React 面板，构建、检查后生成 ZIP：
@@ -89,7 +71,8 @@ pnpm exec bohr-widget --version
 ```
 
 无参数、`-h`、`help` 也可查看帮助。npm 使用 `npx --no-install bohr-widget --help`；
-尚未安装时推荐运行 `pnpm dlx @dp-bohrium/widget-sdk --help`；本包原入口仍可使用。
+尚未安装时可运行 `pnpm dlx @dp-bohrium/widget-sdk --help`，
+也可通过 `pnpm dlx @dp-bohrium/widget-cli --help` 调用本包。
 
 以下命令通过 `pnpm exec bohr-widget` 或 `npx --no-install bohr-widget` 执行：
 

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-cli",
-  "cli": "0.4.0",
+  "cli": "0.5.1",
   "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"
   }
 }