@dp-bohrium/widget-cli 0.3.0 → 0.4.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 +25 -7
- package/CHANGELOG.md +19 -1
- package/README.md +29 -7
- package/assets/toolchain.json +6 -6
- package/dist/cli.mjs +658 -67
- package/dist/core.mjs +1 -1
- package/dist/{dsh-DbOeoKFJ.mjs → dsh-BvnlfCRX.mjs} +9 -10
- package/llms.txt +6 -2
- package/package.json +3 -3
package/AGENTS.md
CHANGED
|
@@ -7,7 +7,8 @@
|
|
|
7
7
|
CLI 本身要求 Node.js >=20，默认生成工程构建器要求 `^22.18.0 || >=24.11.0`。
|
|
8
8
|
`integration.requirements.node` 和 `generatedProjectNode` 分别表达这两项要求。
|
|
9
9
|
本包自包含固定 SDK/contracts、Schema、compiler、校验器和模板，
|
|
10
|
-
|
|
10
|
+
通过文档站提供教程与参考。生成工程只直接安装锁定的 SDK 与构建器；
|
|
11
|
+
公开类型和 Schema 从 SDK 导入，contracts 由 SDK 的传递依赖提供。
|
|
11
12
|
|
|
12
13
|
先看全局帮助，再按命令查看参数、默认值、示例和必要提示：
|
|
13
14
|
|
|
@@ -24,12 +25,13 @@ pnpm exec bohr-widget --version --json
|
|
|
24
25
|
`migrate dsh --help`。`-v` / `--version` 等价于 `version`，`--version --json` 等价于 `version --json`。
|
|
25
26
|
帮助仅输出本地文本，不执行所选命令或联网获取文档。npm 的全局帮助用
|
|
26
27
|
`npx --no-install bohr-widget --help`，其他命令同样替换前缀；未安装时可用
|
|
27
|
-
`pnpm dlx @dp-bohrium/widget-
|
|
28
|
+
新工程用 `pnpm dlx @dp-bohrium/widget-sdk --help` 查看 SDK 自带入口；
|
|
29
|
+
`pnpm dlx @dp-bohrium/widget-cli --help` 在兼容期保持原行为。
|
|
28
30
|
|
|
29
31
|
## 入口
|
|
30
32
|
|
|
31
33
|
```bash
|
|
32
|
-
bohr-widget create <目录> --template panel|file-preview --ui vanilla|react [--panel-id <id>] [--json]
|
|
34
|
+
bohr-widget create <目录> --template panel|file-preview --ui vanilla|react [--panel-id <id>] [--extensions txt,csv] [--tool <名称>] [--json]
|
|
33
35
|
bohr-widget check|validate <目录|manifest.json|all> [--json]
|
|
34
36
|
bohr-widget build <目录> [--json]
|
|
35
37
|
bohr-widget dev <目录> [--watch] [--open] [--no-build] [--json]
|
|
@@ -38,6 +40,8 @@ bohr-widget doctor [目录] [--json]
|
|
|
38
40
|
bohr-widget integration [--project <目录>] [--host-compat <声明文件>] [--json]
|
|
39
41
|
bohr-widget adopt <目录> [--host-compat <声明文件>] [--json]
|
|
40
42
|
bohr-widget schema
|
|
43
|
+
bohr-widget migrate project plan <source> [--candidate <prepared-current-project-dir>] --json
|
|
44
|
+
bohr-widget migrate project apply <source> --plan <plan.json> --out <新目录> [--host-compat <声明文件>] [--json]
|
|
41
45
|
bohr-widget migrate dsh audit <plugin-dir> [--json]
|
|
42
46
|
bohr-widget migrate dsh scaffold <plugin-dir> --out <widget-dir> [--json]
|
|
43
47
|
bohr-widget version | -v | --version [--json]
|
|
@@ -60,7 +64,9 @@ bohr-widget help [<命令路径>]
|
|
|
60
64
|
`panelId`；工作区文件面板固定使用 `--panel-id workspace-files`，CLI 会补齐三项只读文件能力。
|
|
61
65
|
`warnings` 说明目录名不是合法标识符时 `manifest.name` 已回退为 `widget-<hash>`。
|
|
62
66
|
将 `widget-toolchain.json` 与包管理器 lockfile 一起提交；不手改 profile 绕过版本检查。
|
|
63
|
-
|
|
67
|
+
`--extensions` 只用于 file-preview，填写不带前导点的小写扩展名；`--tool` 将默认激活信号替换为
|
|
68
|
+
`tool-call-result:<名称>`，只筛选激活时机，不注册 `tool-result` 槽位，也不授予能力。
|
|
69
|
+
2. 安装工程依赖（`pnpm install` 或 `npm install`）。生成工程已精确依赖自带命令的 SDK，后续使用
|
|
64
70
|
`pnpm exec bohr-widget` / `npx --no-install bohr-widget`，不要假定存在全局命令。
|
|
65
71
|
工程检查可用 `npm run check`，Widget ZIP 打包使用 `pnpm run widget:pack` 或
|
|
66
72
|
`npm run widget:pack`；`pnpm pack` 是制作 npm `.tgz` 包的内置命令，生成工程使用独立的 `widget:pack` 脚本名。
|
|
@@ -163,7 +169,18 @@ profile。`ready` 在此基础上还要求
|
|
|
163
169
|
|
|
164
170
|
旧工程缺少 `widget-toolchain.json` 时，先检查 `doctor` 输出，恢复当前 profile 的精确依赖并安装，
|
|
165
171
|
再运行 `adopt <目录>`。`adopt` 会校验实际安装的 SDK/contracts、Manifest 和 samples 后写锁定文件，
|
|
166
|
-
|
|
172
|
+
不自动迁移字段或升级依赖。工程命令会检查精确 SDK 声明与直接安装版本，再从该 SDK 的真实依赖
|
|
173
|
+
核对 contracts 与固定 profile；源码工作区支持 `workspace:*`，发布包必须转换为精确版本。
|
|
174
|
+
已有工程若仍直接声明 contracts，也会继续核对其精确声明与实际版本；缺少依赖时不能向工程祖先
|
|
175
|
+
或 CLI 借用。该作者用法已废弃，机器诊断为 `WIDGET_CLI_DIRECT_CONTRACTS_DEPRECATED`；
|
|
176
|
+
读取 `deprecations` 中的替代出口、`migration.status` 与 `removal`，不要将暂时通过解释为长期支持。
|
|
177
|
+
R0 只做本地改造；统一入口切换发布 R1 前必须移除。实际内部消费者迁移、旧实现删除与
|
|
178
|
+
Host 验收未完成时阻止 R1；不存在的旧 Widget 不要求专用转换规则。版本号由发布计划决定。根计划为
|
|
179
|
+
`docs/plans/2026-10-29-widget-sdk-forge-unified-entry.md`。
|
|
180
|
+
SDK 出口准备批只为消费者迁移提供可安装版本，不代表 Bohr 与内部宿主联合切换 R1 已完成。
|
|
181
|
+
保留已有作者源码、跨 profile 升级或准备候选工程时，先读[准备迁移候选](https://dev.dp.tech/bohrium-widget-sdk/guides/migration)，按指南完成候选审阅、plan/apply 和后续验收。
|
|
182
|
+
Host / 控制面在 R0 保留现有公开 contracts，R1 转 SDK 的协议/Schema/conformance 出口；
|
|
183
|
+
协议类型仍由 contracts 同源维护，不给 canonical 类型标记 `@deprecated`。
|
|
167
184
|
|
|
168
185
|
## 宿主兼容声明
|
|
169
186
|
|
|
@@ -195,11 +212,11 @@ profile。`ready` 在此基础上还要求
|
|
|
195
212
|
- `WIDGET_CLI_BUILD_UNRESOLVED_IMPORT`：构建器虽然退出 0，但输出仍包含未解析依赖；修正依赖和
|
|
196
213
|
bundler 配置后再构建，不能继续打包外置全局变量产物。
|
|
197
214
|
- `WIDGET_CLI_PROJECT_TOOLCHAIN_REQUIRED`：缺少工程锁定，先 doctor，再显式 adopt。
|
|
198
|
-
- `WIDGET_CLI_PROJECT_PROFILE_MISMATCH
|
|
215
|
+
- `WIDGET_CLI_PROJECT_PROFILE_MISMATCH`：工程不符合当前 Bohr 支持的目标；显式迁移工程，不回选旧 CLI。
|
|
199
216
|
- `WIDGET_CLI_PROJECT_SDK_MISMATCH`：工程锁、依赖声明或实际安装版本不一致；恢复精确依赖并安装。
|
|
200
217
|
- `WIDGET_CLI_BUILD_RECEIPT_MISMATCH`：构建记录缺失或内容变化；重新 build 或去掉 `pack --no-build`。
|
|
201
218
|
- `WIDGET_CLI_HOST_PROFILE_UNSUPPORTED` / `WIDGET_CLI_HOST_COMPAT_INVALID`：宿主未接受当前 profile，
|
|
202
|
-
|
|
219
|
+
或声明无效；取得正确目标声明，目标 Host 不支持当前 profile 时升级 Host，不回选旧 CLI。
|
|
203
220
|
- 其他命令失败是 `WIDGET_CLI_<COMMAND>_FAILED`，命令名已净化成大写标识符片段。
|
|
204
221
|
|
|
205
222
|
`check` 失败通常先修 Manifest、entry、sample 或 fixture；`workspace-files` 还要求目录 fixture 中
|
|
@@ -217,6 +234,7 @@ profile。`ready` 在此基础上还要求
|
|
|
217
234
|
和宿主兼容策略。完整预检由上述命令提供。`sdkVersion` 不能用来伪造另一代 compiler 的版本。
|
|
218
235
|
|
|
219
236
|
`--open` 优先协商 Widget Development Host v1，旧宿主才回落 legacy profile 并告警。
|
|
237
|
+
该降级仅在 R0 保留且已废弃，R1 前随旧开发桥接迁移删除；目标 Host 应升级到当前协议。
|
|
220
238
|
descriptor、status、events、control、一次性 claim 和 session token 都通过命令返回的 URL
|
|
221
239
|
与类型声明表达；不要依赖源码仓库中的内部设计文档来猜测协议。
|
|
222
240
|
|
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,24 @@
|
|
|
1
1
|
# `@dp-bohrium/widget-cli` 变更记录
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## 0.4.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 61ddcea: 新增 Agent 引导的 `migrate project plan/apply`：没有候选时给出准备步骤，Agent 按当前 SDK
|
|
8
|
+
模板、示例与文档审阅候选后，计划绑定来源、候选和执行摘要，apply 将候选原样写入新目录。
|
|
9
|
+
不自动转换作者逻辑、声明或依赖锁，不执行来源或候选代码，也不提供 Bundle 升级。
|
|
10
|
+
完成后显式安装、构建、校验、打包与真实 Host 验收；当前没有必须兼容的真实旧 Widget，
|
|
11
|
+
不维护 0.x 专用配方或旧执行器。
|
|
12
|
+
- 31e930e: 新建与 DSH 迁移工程只直接声明 SDK 和 CLI，类型与编辑器 Schema 改从 SDK 获取，并新增
|
|
13
|
+
`create --extensions` 与 `--tool`。工程校验继续核对 SDK 实际解析的 contracts；旧工程直接声明
|
|
14
|
+
contracts 时返回稳定的废弃诊断，版本漂移仍然失败。
|
|
15
|
+
- 7c21acf: SDK 发布包新增 `bohr-widget` 可执行入口并内置固定工具链资产，使新工程只需精确安装 SDK 即可完成
|
|
16
|
+
创建、构建、校验、开发和打包。现有 widget-cli 暂按现行发布治理复用同一份命令实现与原有分发身份，
|
|
17
|
+
作为过渡兼容分发；两种入口创建或迁移的新工程都只依赖 SDK，SDK bin 不根据旧工程依赖回选历史执行器。
|
|
18
|
+
两包同时安装时不保证同名命令保留旧 CLI 身份；旧工程须移除 CLI、重新安装，并由 SDK 重新构建 receipt
|
|
19
|
+
后再校验与打包，receipt 严格校验不变。
|
|
20
|
+
复用的命令源码与构建输入纳入 SDK 版本门禁；本次不改变 integration v2、工程锁或发布 Tag 协议。
|
|
21
|
+
Widget 作者 skill 同步改用 SDK 创建入口，避免 Agent 为新工程重新引入独立 CLI 依赖。
|
|
4
22
|
|
|
5
23
|
## 0.3.0
|
|
6
24
|
|
package/README.md
CHANGED
|
@@ -2,6 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
创建、开发和打包 Bohrium 自定义 Widget 的命令行工具。
|
|
4
4
|
|
|
5
|
+
`bohr-widget` 现已随 `@dp-bohrium/widget-sdk` 一起交付，作者工程统一只直接安装 SDK。
|
|
6
|
+
本包在迁移期继续保留原有直接安装与命令行为，但创建和迁移出的新工程同样只依赖 SDK；
|
|
7
|
+
它只按现行发布治理保留过渡分发、历史审计和废弃诊断，按阶段 3 退出新作者安装和发布流程。
|
|
8
|
+
两包的同名命令不保证在 npm/pnpm 下保留旧 CLI 身份。旧工程按[单 SDK 迁移步骤](https://dev.dp.tech/bohrium-widget-sdk/reference/versioning)
|
|
9
|
+
移除本包、重新安装并由 SDK `build` 重建 receipt，再校验和打包；不复用旧 CLI 的 receipt。
|
|
10
|
+
|
|
5
11
|
[文档站](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)
|
|
6
12
|
|
|
7
13
|
## 环境
|
|
@@ -9,14 +15,27 @@
|
|
|
9
15
|
推荐使用 Node.js 24（>=24.11.0）。CLI 本身支持 Node.js >=20，默认模板的构建器要求
|
|
10
16
|
`^22.18.0 || >=24.11.0`。安装 pnpm 或 npm 后即可开始。
|
|
11
17
|
|
|
12
|
-
SDK
|
|
18
|
+
SDK 与内部 contracts 的配套版本由 CLI 固定管理，创建工程后安装其依赖即可。
|
|
19
|
+
Widget 作者从 SDK 导入公开类型与 Schema，无需单独选择或安装 contracts。
|
|
20
|
+
|
|
21
|
+
独立消费者直接依赖 contracts 的旧入口已废弃。`doctor --json` 与工程命令的
|
|
22
|
+
`deprecations` 返回 `WIDGET_CLI_DIRECT_CONTRACTS_DEPRECATED`，包含替代出口、迁移状态和
|
|
23
|
+
移除阶段“统一入口切换发布 R1”。R0 是本地改造，R1 前必须移除旧分支；实际内部消费者
|
|
24
|
+
迁移、SDK 出口交付或 Host 验收未完成时阻止 R1，不能据此延长兼容。版本号以正式发布计划为准，
|
|
25
|
+
不从当前源码推算。当前仍严格核对旧声明和实际依赖，版本漂移继续失败。
|
|
26
|
+
SDK 出口准备批只提供消费者迁移所需的可安装版本，不代表 Bohr 与内部宿主联合切换 R1 已完成。
|
|
27
|
+
|
|
28
|
+
`migrate project plan/apply` 核对 Agent 准备的候选并写入新目录，具体边界见下方。
|
|
29
|
+
`adopt` 仅为已符合当前 profile 的工程补锁，不升级代码、依赖或旧 Bundle。Host / 控制面在 R0 暂时使用现有已公开 contracts，
|
|
30
|
+
R1 改经 SDK `/contracts`、`/schemas`、`/conformance` 消费；canonical 协议类型本身没有废弃。
|
|
31
|
+
仓库移除计划见 `docs/plans/2026-10-29-widget-sdk-forge-unified-entry.md`。
|
|
13
32
|
|
|
14
33
|
## 创建并打包
|
|
15
34
|
|
|
16
35
|
下面创建一个 React 面板，构建、检查后生成 ZIP：
|
|
17
36
|
|
|
18
37
|
```bash
|
|
19
|
-
pnpm dlx @dp-bohrium/widget-
|
|
38
|
+
pnpm dlx @dp-bohrium/widget-sdk create my-widget --template panel --ui react
|
|
20
39
|
cd my-widget
|
|
21
40
|
pnpm install
|
|
22
41
|
pnpm exec bohr-widget build .
|
|
@@ -25,9 +44,9 @@ pnpm run widget:pack --out artifacts/my-widget.zip
|
|
|
25
44
|
```
|
|
26
45
|
|
|
27
46
|
编辑 `src/widget.tsx` 实现界面。原生 DOM 使用 `--ui vanilla`；文件预览使用
|
|
28
|
-
`--template file-preview
|
|
47
|
+
`--template file-preview`。生成工程已包含自带命令的本地 SDK 依赖，不需要全局安装。
|
|
29
48
|
|
|
30
|
-
使用 npm 时，创建命令改为 `npx --yes @dp-bohrium/widget-
|
|
49
|
+
使用 npm 时，创建命令改为 `npx --yes @dp-bohrium/widget-sdk create my-widget --template panel --ui react`，
|
|
31
50
|
进入工程后执行：
|
|
32
51
|
|
|
33
52
|
```bash
|
|
@@ -45,6 +64,10 @@ npm run widget:pack -- --out artifacts/my-widget.zip
|
|
|
45
64
|
`{ list: true, watch: true }`。Widget 只能在 Host 签发对应 grant 后调用能力，列表刷新频率须遵守
|
|
46
65
|
`tasks.list` grant 的 `minPollMs`。
|
|
47
66
|
|
|
67
|
+
## 准备迁移候选
|
|
68
|
+
|
|
69
|
+
保留已有源码、升级 SDK 或跨 profile 时，先读[准备迁移候选](https://dev.dp.tech/bohrium-widget-sdk/guides/migration)，按指南准备并审阅独立候选，再安排后续验收。
|
|
70
|
+
|
|
48
71
|
## 开发预览
|
|
49
72
|
|
|
50
73
|
在工程目录监听修改并重新构建：
|
|
@@ -66,7 +89,7 @@ pnpm exec bohr-widget --version
|
|
|
66
89
|
```
|
|
67
90
|
|
|
68
91
|
无参数、`-h`、`help` 也可查看帮助。npm 使用 `npx --no-install bohr-widget --help`；
|
|
69
|
-
|
|
92
|
+
尚未安装时推荐运行 `pnpm dlx @dp-bohrium/widget-sdk --help`；本包原入口仍可使用。
|
|
70
93
|
|
|
71
94
|
以下命令通过 `pnpm exec bohr-widget` 或 `npx --no-install bohr-widget` 执行：
|
|
72
95
|
|
|
@@ -80,7 +103,6 @@ pnpm exec bohr-widget --version
|
|
|
80
103
|
|
|
81
104
|
## 继续阅读
|
|
82
105
|
|
|
83
|
-
- [SDK](https://www.npmjs.com/package/@dp-bohrium/widget-sdk)：Widget
|
|
84
|
-
- [Contracts](https://www.npmjs.com/package/@dp-bohrium/widget-contracts)：公开类型与 JSON Schema。
|
|
106
|
+
- [SDK](https://www.npmjs.com/package/@dp-bohrium/widget-sdk)：Widget 生命周期、能力调用、公开类型与 JSON Schema。
|
|
85
107
|
- [Design Tokens](https://www.npmjs.com/package/@dp-bohrium/widget-design-token)：可选的配色与主题。
|
|
86
108
|
- [更新记录](https://dev.dp.tech/bohrium-widget-sdk/changelog/cli) · [故障排查](https://dev.dp.tech/bohrium-widget-sdk/guides/debugging)。
|
package/assets/toolchain.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"formatVersion": 2,
|
|
3
3
|
"packageName": "@dp-bohrium/widget-cli",
|
|
4
|
-
"cli": "0.
|
|
4
|
+
"cli": "0.4.0",
|
|
5
5
|
"profile": {
|
|
6
|
-
"id": "widget-sdk-0.
|
|
7
|
-
"sdk": "0.
|
|
8
|
-
"contracts": "0.
|
|
6
|
+
"id": "widget-sdk-0.6.0-contracts-0.6.0",
|
|
7
|
+
"sdk": "0.6.0",
|
|
8
|
+
"contracts": "0.6.0"
|
|
9
9
|
},
|
|
10
10
|
"hostAcceptance": "unknown",
|
|
11
11
|
"documentation": {
|
|
@@ -16,9 +16,9 @@
|
|
|
16
16
|
"llms": "https://dev.dp.tech/bohrium-widget-sdk/llms.txt"
|
|
17
17
|
},
|
|
18
18
|
"digests": {
|
|
19
|
-
"compiler": "sha256:
|
|
19
|
+
"compiler": "sha256:d541f305c8cccdfc8e122ab84d57103da68c734325df2ead3729cc3a21b7d222",
|
|
20
20
|
"validators": "sha256:e3e411c6ea3c09f07554222141ccb92124cdf8921ab39dbaeb8f79f4ad8d12aa",
|
|
21
21
|
"schemas": "sha256:2286156c619d6482471966fb97a2a4adbb9c86ef9ec17225eb1b070d8489dd9c",
|
|
22
|
-
"templates": "sha256:
|
|
22
|
+
"templates": "sha256:34f08fb56072c2722a1e02cee09b3130d075853129c333aa8916e0411cee5618"
|
|
23
23
|
}
|
|
24
24
|
}
|