@dp-bohrium/widget-cli 0.3.0 → 0.5.0

package/AGENTS.md

@@ -1,13 +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/contracts 与构建器。
+生成工程精确依赖 SDK 与构建器，类型、Schema 和工程命令均由 SDK 提供。
+教程与参考见文档站。
 
 先看全局帮助，再按命令查看参数、默认值、示例和必要提示：
 
@@ -23,13 +23,15 @@ 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-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。
 
 ## 入口
 
 ```bash
-bohr-widget create <目录> --template panel|file-preview --ui vanilla|react [--panel-id <id>] [--json]
+bohr-widget create <目录> --template panel|file-preview --ui vanilla|react [--panel-id <id>] [--extensions txt,csv] [--tool <名称>] [--json]
 bohr-widget check|validate <目录|manifest.json|all> [--json]
 bohr-widget build <目录> [--json]
 bohr-widget dev <目录> [--watch] [--open] [--no-build] [--json]
@@ -38,6 +40,8 @@ bohr-widget doctor [目录] [--json]
 bohr-widget integration [--project <目录>] [--host-compat <声明文件>] [--json]
 bohr-widget adopt <目录> [--host-compat <声明文件>] [--json]
 bohr-widget schema
+bohr-widget migrate project plan <source> [--candidate <prepared-current-project-dir>] --json
+bohr-widget migrate project apply <source> --plan <plan.json> --out <新目录> [--host-compat <声明文件>] [--json]
 bohr-widget migrate dsh audit <plugin-dir> [--json]
 bohr-widget migrate dsh scaffold <plugin-dir> --out <widget-dir> [--json]
 bohr-widget version | -v | --version [--json]
@@ -46,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)。
@@ -60,7 +64,9 @@ bohr-widget help [<命令路径>]
    `panelId`；工作区文件面板固定使用 `--panel-id workspace-files`，CLI 会补齐三项只读文件能力。
    `warnings` 说明目录名不是合法标识符时 `manifest.name` 已回退为 `widget-<hash>`。
    将 `widget-toolchain.json` 与包管理器 lockfile 一起提交；不手改 profile 绕过版本检查。
-2. 安装工程依赖（`pnpm install` 或 `npm install`）。生成工程已精确依赖本 CLI，后续使用
+   `--extensions` 只用于 file-preview，填写不带前导点的小写扩展名；`--tool` 将默认激活信号替换为
+   `tool-call-result:<名称>`，只筛选激活时机，不注册 `tool-result` 槽位，也不授予能力。
+2. 安装工程依赖（`pnpm install` 或 `npm install`）。生成工程已精确依赖自带命令的 SDK，后续使用
    `pnpm exec bohr-widget` / `npx --no-install bohr-widget`，不要假定存在全局命令。
    工程检查可用 `npm run check`，Widget ZIP 打包使用 `pnpm run widget:pack` 或
    `npm run widget:pack`；`pnpm pack` 是制作 npm `.tgz` 包的内置命令，生成工程使用独立的 `widget:pack` 脚本名。
@@ -72,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。
 
@@ -162,8 +168,13 @@ profile。`ready` 在此基础上还要求
 `warnings` 里。
 
 旧工程缺少 `widget-toolchain.json` 时，先检查 `doctor` 输出，恢复当前 profile 的精确依赖并安装，
-再运行 `adopt <目录>`。`adopt` 会校验实际安装的 SDK/contracts、Manifest 和 samples 后写锁定文件，
-不自动迁移字段或升级依赖。工程命令会检查声明版本与实际安装版本，不从父目录或 CLI 自身借用 SDK。
+再运行 `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 或控制面可使用 `@dp-bohrium/widget-contracts`，也可使用 SDK 的协议、Schema 和 conformance
+入口；固定与目标 SDK 配套的精确版本，不混用不同版本的协议资产。
 
 ## 宿主兼容声明
 
@@ -172,8 +183,8 @@ profile。`ready` 在此基础上还要求
 或过期声明；只有本次在线取得、仍有效且接受当前 profile 时才是 `confirmed`。后者是调用方报告
 的兼容证据，不是发布许可。格式错误、时间无效或 profile 不被接受时按错误处理。
 
-本次只交付 A、B 阶段的本地能力，平台在线发现接口与 Bohr 在线取声明尚需后续接入。不要把
-本地 profile、SDK package.json 或 `unknown` 解释为线上平台已兼容。
+CLI 不自动获取线上声明。调用方需提供目标 Host 的兼容证据，不要把本地 profile、
+SDK package.json 或 `unknown` 解释为线上平台已兼容。
 
 ## 错误处理
 
@@ -195,11 +206,11 @@ profile。`ready` 在此基础上还要求
 - `WIDGET_CLI_BUILD_UNRESOLVED_IMPORT`：构建器虽然退出 0，但输出仍包含未解析依赖；修正依赖和
   bundler 配置后再构建，不能继续打包外置全局变量产物。
 - `WIDGET_CLI_PROJECT_TOOLCHAIN_REQUIRED`：缺少工程锁定，先 doctor，再显式 adopt。
-- `WIDGET_CLI_PROJECT_PROFILE_MISMATCH`：CLI 未携带工程的 profile；使用匹配的 CLI 或安排迁移。
+- `WIDGET_CLI_PROJECT_PROFILE_MISMATCH`：工程不符合当前 Bohr 支持的目标；显式迁移工程，不回选旧 CLI。
 - `WIDGET_CLI_PROJECT_SDK_MISMATCH`：工程锁、依赖声明或实际安装版本不一致；恢复精确依赖并安装。
 - `WIDGET_CLI_BUILD_RECEIPT_MISMATCH`：构建记录缺失或内容变化；重新 build 或去掉 `pack --no-build`。
 - `WIDGET_CLI_HOST_PROFILE_UNSUPPORTED` / `WIDGET_CLI_HOST_COMPAT_INVALID`：宿主未接受当前 profile，
-  或声明无效；取得正确目标声明或使用经目标平台验收的 CLI。
+  或声明无效；取得正确目标声明，目标 Host 不支持当前 profile 时升级 Host，不回选旧 CLI。
 - 其他命令失败是 `WIDGET_CLI_<COMMAND>_FAILED`，命令名已净化成大写标识符片段。
 
 `check` 失败通常先修 Manifest、entry、sample 或 fixture；`workspace-files` 还要求目录 fixture 中
@@ -211,12 +222,13 @@ profile。`ready` 在此基础上还要求
 里带 `profileUrl`、`statusUrl`、`hostUrl`、digest 和 assets，不得把整个 stdout 当作单个 JSON
 文档解析。watch 重建失败时从 `statusUrl` 读取 `lastBuildError`，修复工程后重新保存源码或重新
 执行 build。`statusUrl` 是本地诊断接口，不是生产 Host API。
-每轮重建都会重新核对工具链与实际 SDK/contracts，失败时继续保留上一轮可用 generation。
+每轮重建都会重新核对工具链与实际 SDK 与内置协议摘要，失败时继续保留上一轮可用 generation。
 
 `/core` 是模板、compiler、校验和打包的底层 API；直接调用它时，调用方负责工程锁定、实际依赖
 和宿主兼容策略。完整预检由上述命令提供。`sdkVersion` 不能用来伪造另一代 compiler 的版本。
 
 `--open` 优先协商 Widget Development Host v1，旧宿主才回落 legacy profile 并告警。
+legacy profile 已废弃，目标 Host 应升级到当前协议。
 descriptor、status、events、control、一次性 claim 和 session token 都通过命令返回的 URL
 与类型声明表达；不要依赖源码仓库中的内部设计文档来猜测协议。
 

package/CHANGELOG.md

@@ -1,6 +1,48 @@
 # `@dp-bohrium/widget-cli` 变更记录
 
-本文件记录使用者可感知的命令、工程模板、校验与打包能力变化。
+## 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
+
+- 61ddcea: 新增 Agent 引导的 `migrate project plan/apply`：没有候选时给出准备步骤，Agent 按当前 SDK
+  模板、示例与文档审阅候选后，计划绑定来源、候选和执行摘要，apply 将候选原样写入新目录。
+  不自动转换作者逻辑、声明或依赖锁，不执行来源或候选代码，也不提供 Bundle 升级。
+  完成后显式安装、构建、校验、打包与真实 Host 验收；当前没有必须兼容的真实旧 Widget，
+  不维护 0.x 专用配方或旧执行器。
+- 31e930e: 新建与 DSH 迁移工程只直接声明 SDK 和 CLI，类型与编辑器 Schema 改从 SDK 获取，并新增
+  `create --extensions` 与 `--tool`。工程校验继续核对 SDK 实际解析的 contracts；旧工程直接声明
+  contracts 时返回稳定的废弃诊断，版本漂移仍然失败。
+- 7c21acf: SDK 发布包新增 `bohr-widget` 可执行入口并内置固定工具链资产，使新工程只需精确安装 SDK 即可完成
+  创建、构建、校验、开发和打包。现有 widget-cli 暂按现行发布治理复用同一份命令实现与原有分发身份，
+  作为过渡兼容分发；两种入口创建或迁移的新工程都只依赖 SDK，SDK bin 不根据旧工程依赖回选历史执行器。
+  两包同时安装时不保证同名命令保留旧 CLI 身份；旧工程须移除 CLI、重新安装，并由 SDK 重新构建 receipt
+  后再校验与打包，receipt 严格校验不变。
+  复用的命令源码与构建输入纳入 SDK 版本门禁；本次不改变 integration v2、工程锁或发布 Tag 协议。
+  Widget 作者 skill 同步改用 SDK 创建入口，避免 Agent 为新工程重新引入独立 CLI 依赖。
 
 ## 0.3.0
 

package/README.md

@@ -2,6 +2,9 @@
 
 创建、开发和打包 Bohrium 自定义 Widget 的命令行工具。
 
+提供 `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)
 
 ## 环境
@@ -9,14 +12,12 @@
 推荐使用 Node.js 24（>=24.11.0）。CLI 本身支持 Node.js >=20，默认模板的构建器要求
 `^22.18.0 || >=24.11.0`。安装 pnpm 或 npm 后即可开始。
 
-SDK/contracts 的配套版本由 CLI 固定管理，创建工程后安装其依赖即可。
-
 ## 创建并打包
 
 下面创建一个 React 面板，构建、检查后生成 ZIP：
 
 ```bash
-pnpm dlx @dp-bohrium/widget-cli create my-widget --template panel --ui react
+pnpm dlx @dp-bohrium/widget-sdk create my-widget --template panel --ui react
 cd my-widget
 pnpm install
 pnpm exec bohr-widget build .
@@ -25,9 +26,9 @@ pnpm run widget:pack --out artifacts/my-widget.zip
 ```
 
 编辑 `src/widget.tsx` 实现界面。原生 DOM 使用 `--ui vanilla`；文件预览使用
-`--template file-preview`。生成工程已包含本地 CLI 依赖，不需要全局安装。
+`--template file-preview`。生成工程已包含自带命令的本地 SDK 依赖，不需要全局安装。
 
-使用 npm 时，创建命令改为 `npx --yes @dp-bohrium/widget-cli create my-widget --template panel --ui react`，
+使用 npm 时，创建命令改为 `npx --yes @dp-bohrium/widget-sdk create my-widget --template panel --ui react`，
 进入工程后执行：
 
 ```bash
@@ -45,6 +46,10 @@ npm run widget:pack -- --out artifacts/my-widget.zip
 `{ list: true, watch: true }`。Widget 只能在 Host 签发对应 grant 后调用能力，列表刷新频率须遵守
 `tasks.list` grant 的 `minPollMs`。
 
+## 准备迁移候选
+
+保留已有源码、升级 SDK 或跨 profile 时，先读[准备迁移候选](https://dev.dp.tech/bohrium-widget-sdk/guides/migration)，按指南准备并审阅独立候选，再安排后续验收。
+
 ## 开发预览
 
 在工程目录监听修改并重新构建：
@@ -66,7 +71,8 @@ pnpm exec bohr-widget --version
 ```
 
 无参数、`-h`、`help` 也可查看帮助。npm 使用 `npx --no-install bohr-widget --help`；
-尚未安装时可运行 `pnpm dlx @dp-bohrium/widget-cli --help`。
+尚未安装时可运行 `pnpm dlx @dp-bohrium/widget-sdk --help`，
+也可通过 `pnpm dlx @dp-bohrium/widget-cli --help` 调用本包。
 
 以下命令通过 `pnpm exec bohr-widget` 或 `npx --no-install bohr-widget` 执行：
 
@@ -80,7 +86,6 @@ pnpm exec bohr-widget --version
 
 ## 继续阅读
 
-- [SDK](https://www.npmjs.com/package/@dp-bohrium/widget-sdk)：Widget 生命周期与能力调用。
-- [Contracts](https://www.npmjs.com/package/@dp-bohrium/widget-contracts)：公开类型与 JSON Schema。
+- [SDK](https://www.npmjs.com/package/@dp-bohrium/widget-sdk)：Widget 生命周期、能力调用、公开类型与 JSON Schema。
 - [Design Tokens](https://www.npmjs.com/package/@dp-bohrium/widget-design-token)：可选的配色与主题。
 - [更新记录](https://dev.dp.tech/bohrium-widget-sdk/changelog/cli) · [故障排查](https://dev.dp.tech/bohrium-widget-sdk/guides/debugging)。

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.3.0",
+  "cli": "0.5.0",
   "profile": {
-    "id": "widget-sdk-0.5.0-contracts-0.5.0",
-    "sdk": "0.5.0",
-    "contracts": "0.5.0"
+    "id": "widget-sdk-0.7.0",
+    "sdk": "0.7.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:e5944e59c8070a239b803945a5c15abb0398736a0f1622c1543242acf7d4c533",
-    "validators": "sha256:e3e411c6ea3c09f07554222141ccb92124cdf8921ab39dbaeb8f79f4ad8d12aa",
-    "schemas": "sha256:2286156c619d6482471966fb97a2a4adbb9c86ef9ec17225eb1b070d8489dd9c",
-    "templates": "sha256:c495eb5a7faf3123acf871ddd54fa745e17efd5f45c7c037908475610ff13c77"
+    "compiler": "sha256:6b6ac1585a3f2bc0f8b2717b2475584a502a9026045b840337547528b7a063b0",
+    "validators": "sha256:8712fb004d9decf1eeae56c1e7057092a8abc0eeae1093c29546bb56e3261922",
+    "schemas": "sha256:ee3023e337559bbf83c096365fe1eb49ce6809a880a5e5d65e2a2f6fd53a7ddb",
+    "templates": "sha256:60f555788f33fb38d707525f571d13b6fa78875be7d2d87cb864db6926a52ccb"
   }
 }