@dp-bohrium/widget-cli 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,217 @@
+# Widget CLI Agent 使用说明
+
+`@dp-bohrium/widget-cli` 是 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 与构建器。
+
+先看全局帮助，再按命令查看参数、默认值、示例和必要提示：
+
+```bash
+pnpm exec bohr-widget --help
+pnpm exec bohr-widget create --help
+pnpm exec bohr-widget help migrate dsh scaffold
+pnpm exec bohr-widget --version --json
+```
+
+无参数、`-h`、`--help`、`help` 显示全局帮助，包含版本、命令、选项、开发流程，
+以及文档站、快速开始、命令行指南和 `llms.txt` 链接。
+`<命令路径> --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` 查看入口。
+
+## 入口
+
+```bash
+bohr-widget create <目录> --template panel|file-preview --ui vanilla|react [--panel-id <id>] [--json]
+bohr-widget check|validate <目录|manifest.json|all> [--json]
+bohr-widget build <目录> [--json]
+bohr-widget dev <目录> [--watch] [--open] [--no-build] [--json]
+bohr-widget pack <目录> [--out <zip>] [--include-preview-fixtures] [--no-build] [--json]
+bohr-widget doctor [目录] [--json]
+bohr-widget integration [--project <目录>] [--host-compat <声明文件>] [--json]
+bohr-widget adopt <目录> [--host-compat <声明文件>] [--json]
+bohr-widget schema
+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]
+bohr-widget [<命令路径>] --help | -h
+bohr-widget help [<命令路径>]
+```
+
+工程命令均可通过 `--host-compat <声明文件>` 检查目标宿主。接入方先调用
+`integration --json`：`interfaceVersion=2`，`toolchain.formatVersion=2`；返回固定 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)。
+已有工程用 `--project <目录>` 核对 profile，再按返回的 `execution.executable` 和
+`[execution.entry, ...参数]` 启动同一份 CLI。Bohr 的命令转发和文档获取由其自身接入实现决定。
+文档正文变化独立于执行工具链，不自动升级工程依赖或证明宿主接受当前 profile。
+
+## 执行顺序
+
+1. `create` 创建工程后检查返回的 `projectRoot`、`manifestPath`、`packagePath`、`profile`、`name` 和可选
+   `panelId`；工作区文件面板固定使用 `--panel-id workspace-files`，CLI 会补齐三项只读文件能力。
+   `warnings` 说明目录名不是合法标识符时 `manifest.name` 已回退为 `widget-<hash>`。
+   将 `widget-toolchain.json` 与包管理器 lockfile 一起提交；不手改 profile 绕过版本检查。
+2. 安装工程依赖（`pnpm install` 或 `npm install`）。生成工程已精确依赖本 CLI，后续使用
+   `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` 脚本名。
+3. 执行工程 `build`（或 `pnpm exec bohr-widget build .`）。失败时先读取 JSON 里的 `error.message`
+   （优先从 stderr/stdout 提取实际诊断）、`stdout` 和 `stderr`，不要直接重复执行。
+4. 执行 `check` 或 `validate`。`check` 要求入口已构建，未构建会报
+   `entry file is missing: dist/widget.js`，回到第 3 步。
+5. `pack --json` 成功后保存 `path`、`bytes`、`sha256`、`toolchain` 版本和 `manifest` 摘要。
+   `pack --no-build` 要求上次 `bohr-widget build` 生成的 `.widget-build-receipt.json` 与当前工具链、
+   实际依赖、源文件和 `dist` 内容一致；缺失或变化时重新 build，不补写或篡改 receipt。
+   receipt 的执行摘要只有 `compiler`、`validators`、`schemas`、`templates` 四项；
+   文档站更新不改变这些摘要、不使 receipt 失效，也不要求 CLI 发版。
+6. Bohr CLI 或平台侧必须继续使用同一份 ZIP 和 digest；Widget CLI 不负责 upload、preview、
+   commit、版本发布或 Agent binding。
+
+`pack` 保留入口顶层构建目录（通常是 `dist/`）中的 chunk、CSS、WASM 等资源；这个目录只放
+可部署产物，不放源码或凭据。历史根目录入口不遍历工程根。ZIP 拒绝符号链接，sample 引用同一
+文件时只写一个条目。完整包结构通过仍不等于 Bundle 已执行。
+
+## 开发与交付
+
+- 模板的高度链、布局和滚动样式放在作者源码 `src/widget.ts` / `src/widget.tsx` 中，
+  `activate` 安装后通过 `context.subscriptions` 清理。修改界面时直接维护这份源码；
+  `src/widget-host.ts` 只保留 SDK 启动与诊断。JSON 换行只作用于独立的 `<pre>`，
+  不给 React 组件整树设置 `white-space: pre-wrap`；React 使用 `<div>` 挂载并保留一个 `<main>`。
+- `context.render` 的首个参数是完整 `RenderRequest`，不是待调用的函数；事件与 render
+  的先后可能不同。不要在每次 render 时清空已回放的事件或当前文件的未保存编辑。
+- `FileReference` 只保留公开契约字段；展开、选中、loading 等 UI 状态放在独立结构中。
+- 文件目录处理 `nextCursor`；文本预览明确显示范围、截断和错误。零结果保留筛选控件。
+- 没有 `files.open` 等公开能力时不能用提示文案代替真实宿主联动；按实际 grant 决定可用动作。
+- 交付前执行首帧、事件后 render、空数据、缺授权、主题/尺寸更新和实际可见布局检查。
+  文件编辑还需验证切换文件、保存中的草稿、冲突和未知结果，保持未修改内容原样。
+
+完整步骤见[交付验收指南](https://dev.dp.tech/bohrium-widget-sdk/guides/delivery-checklist)。
+
+## file-preview 当前文件读写（SDK 0.4.0）
+
+按原来的 `create --template file-preview --ui vanilla|react` 创建工程。用户需要编辑文件时，
+由 Agent 在作者 Manifest 中声明 `capabilities.files: { read: true, write: true }`，并实现
+`context.files.read/write` 调用。
+完整用法参照文档站的[文件能力](https://dev.dp.tech/bohrium-widget-sdk/guides/capabilities/files)。
+
+- `file` 取自当前 `request.content.file`；保存基础版本取自同次读取回执的 `revision`，
+  不是 `RenderRequest.revision`，也不能另查 metadata/stat 来补版本。
+- 先确认内容完整且具有内容版本，再开放保存；无授权或缺少版本/完整性证据时只读。
+  对单次读取预算外的文件实现有版本约束的分块读取，格式序列化由作者实现。
+- 读取使用 `base64` 原始字节，经 `TextDecoder("utf-8", { fatal: true, ignoreBOM: true })`
+  拒绝非法 UTF-8 并保留 BOM；不能把 Host 有损解码产生的替换字符作为整文件保存基础。
+- 保存需独立的 Host `files.write` grant；Manifest/sample 声明不等于授权。
+- 一次逻辑保存只生成一个 `mutationId`，冻结当次文件引用、完整内容、基础版本和对应草稿。
+  保存进行中不继续修改该草稿；只在匹配的成功回执后更新引用、基础版本并标为已保存。
+- 预览切换到另一文件或 Session 后，停用旧草稿的编辑和保存，保留草稿供核对。
+  迟到的读取或保存回执不能重开旧文件保存，也不能把新文件的草稿标记为已保存。
+- `revision-conflict` 保留草稿，重新读取后由用户合并；`write-outcome-unknown` 保留原内容、基础版本
+  和 mutationId，先通过 Host 核对。同一保存的确认使用同一 id 和内容，不能自动生成新 id 重试。
+- 当前开发宿主仍是只读文件能力；`dev` 只能验证这一降级路径，真实写入需 Host 持久化适配。
+  本地构建、校验与 sample 中的 grant 都不能证明真实宿主已支持保存。
+
+## 在 Panel 中编辑工作区文件
+
+用户要在文件树面板里直接保存时，用 `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 签发写权限。
+- 保存规则与上一节相同，另按 `file.id` 分别保存每个文件的草稿、基础版本和 mutationId；
+  切换选中文件不丢弃其他草稿，迟到回执只更新所属文件。
+- 宿主编辑器或 file-preview 可能同时打开同一文件；`revision-conflict` 时保留草稿并重读合并。
+- 完整说明见[在 Panel 中编辑工作区文件](https://dev.dp.tech/bohrium-widget-sdk/guides/capabilities/files#在-panel-中编辑工作区文件)。
+
+## check all
+
+`check all` 以当前工作目录为根，查找 `examples/sdk`、`examples/integration` 和当前目录的
+`manifest.json`；一个工程都没找到时返回 `error.code=WIDGET_CLI_NO_WIDGET_PROJECT`（退出码 1），
+不得把"没校验任何工程"当成通过。`--json` 输出单个汇总文档（`checked` / `passed` / `failed` /
+`results[]`）；传入单个目录或 `manifest.json` 时输出该工程的校验结果。`label` 是相对当前工作
+目录的路径，只在仓库外退化成绝对路径。
+
+## doctor
+
+`doctor --json` 的 `ok` 要求 Node 版本受支持、`package.json` 存在且
+`manifest.json` 是有效 JSON，并始终核对候选 profile 的精确依赖；已有锁定信息时再核对锁定的
+profile。`ready` 在此基础上还要求
+`widget-toolchain.json`、`node_modules` 与构建入口存在。
+未安装依赖或未构建时 `ok=true` / `ready=false`，manifest 语法错误时 `ok=false`，原因在
+`warnings` 里。
+
+旧工程缺少 `widget-toolchain.json` 时，先检查 `doctor` 输出，恢复当前 profile 的精确依赖并安装，
+再运行 `adopt <目录>`。`adopt` 会校验实际安装的 SDK/contracts、Manifest 和 samples 后写锁定文件，
+不自动迁移字段或升级依赖。工程命令会检查声明版本与实际安装版本，不从父目录或 CLI 自身借用 SDK。
+
+## 宿主兼容声明
+
+`--host-compat` 文件包含平台 `statement` 和调用方 `observation`，后者记录 `source` 与
+`fetchedAt`。`hostCompatibility.status=unknown` 表示未提供声明；`snapshot` 表示匹配的快照
+或过期声明；只有本次在线取得、仍有效且接受当前 profile 时才是 `confirmed`。后者是调用方报告
+的兼容证据，不是发布许可。格式错误、时间无效或 profile 不被接受时按错误处理。
+
+本次只交付 A、B 阶段的本地能力，平台在线发现接口与 Bohr 在线取声明尚需后续接入。不要把
+本地 profile、SDK package.json 或 `unknown` 解释为线上平台已兼容。
+
+## 错误处理
+
+使用 `--json` 时，失败结果必须按 `ok=false` 处理。至少记录：
+
+- `command`：失败的命令；
+- `error.code`：机器分类；
+- `error.message`：给人的具体原因；
+- `error.context`：目录、Manifest、入口或构建阶段等上下文；
+- `error.recovery`：下一步可执行动作。
+
+常见 `error.code`：
+
+- `WIDGET_CLI_MANIFEST_INVALID`：作者清单本身有错（`version` 缺失或不是 semver、`displayName`
+  不是字符串、顶层有未知字段）。这类错误不再回落到宿主 schema，直接按 `errors` 里的字段名修。
+- `WIDGET_CLI_NO_WIDGET_PROJECT`：`check all` 没有匹配到工程。
+- `WIDGET_CLI_BUILD_FAILED`：工程 `build` 脚本失败；`error.message` 优先显示 stderr/stdout 的实际诊断，
+  `code=127` 通常意味着依赖没装。
+- `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_SDK_MISMATCH`：工程锁、依赖声明或实际安装版本不一致；恢复精确依赖并安装。
+- `WIDGET_CLI_BUILD_RECEIPT_MISMATCH`：构建记录缺失或内容变化；重新 build 或去掉 `pack --no-build`。
+- `WIDGET_CLI_HOST_PROFILE_UNSUPPORTED` / `WIDGET_CLI_HOST_COMPAT_INVALID`：宿主未接受当前 profile，
+  或声明无效；取得正确目标声明或使用经目标平台验收的 CLI。
+- 其他命令失败是 `WIDGET_CLI_<COMMAND>_FAILED`，命令名已净化成大写标识符片段。
+
+`check` 失败通常先修 Manifest、entry、sample 或 fixture；`workspace-files` 还要求目录 fixture 中
+每个文件都有 `files.read` 内容，且 list/metadata 的 size 与实际字节数一致。`build` 失败先读取构建器输出；
+`pack` 失败先保留原工程和校验结果，不要上传不完整 ZIP。CLI 本地 `ok=true` 只说明本地
+检查或打包成功，不代表浏览器 iframe 已渲染、Widget 已发布或已绑定 Agent。
+
+`dev --json` 输出 `bohrium.widget-development-cli` v1 的逐行 NDJSON envelope；`session-ready`
+里带 `profileUrl`、`statusUrl`、`hostUrl`、digest 和 assets，不得把整个 stdout 当作单个 JSON
+文档解析。watch 重建失败时从 `statusUrl` 读取 `lastBuildError`，修复工程后重新保存源码或重新
+执行 build。`statusUrl` 是本地诊断接口，不是生产 Host API。
+每轮重建都会重新核对工具链与实际 SDK/contracts，失败时继续保留上一轮可用 generation。
+
+`/core` 是模板、compiler、校验和打包的底层 API；直接调用它时，调用方负责工程锁定、实际依赖
+和宿主兼容策略。完整预检由上述命令提供。`sdkVersion` 不能用来伪造另一代 compiler 的版本。
+
+`--open` 优先协商 Widget Development Host v1，旧宿主才回落 legacy profile 并告警。
+descriptor、status、events、control、一次性 claim 和 session token 都通过命令返回的 URL
+与类型声明表达；不要依赖源码仓库中的内部设计文档来猜测协议。
+
+DSH 迁移命令只读取源目录，不执行 Cordis patch 或源插件安装脚本；它不会把 Cordis runtime、
+tool、Skill、system prompt、文件系统、网络或 DSH client UI 嵌入 Widget。`source.fingerprint`
+变化、未知 profile 和阻断能力必须回到 `audit`，不得自动 scaffold。
+
+## 安全边界
+
+不要把 AccessKey、签名 URL、主机内部绝对路径或 Agent 凭据写入 Manifest、sample、ZIP、
+日志或错误上下文。上传、preview、commit、发布和绑定必须由 Bohr CLI 与平台服务执行。

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# `@dp-bohrium/widget-cli` 变更记录
+
+本文件记录使用者可感知的命令、工程模板、校验与打包能力变化。
+
+## 0.2.0
+
+### 新增
+
+**1. 提供分层命令帮助与版本快捷参数**
+
+- 无参数、`--help`、`-h`、`help` 显示全局版本、命令、选项、开发流程，以及文档站、快速开始、命令行指南和 llms 索引入口。
+- `<命令路径> --help` 与 `help <命令路径>` 展示对应层级的参数、默认值、示例和必要提示，覆盖 `migrate`、`migrate dsh`、`audit` 与 `scaffold`。帮助仅输出本地文本，不执行所选命令或联网获取文档。
+- 新增 `-v` / `--version`，等价于 `version`；`--version --json` 等价于 `version --json`。
+
+**2. 固定执行工具链，通过公开文档发现开发指引**
+
+- CLI 自包含固定的 SDK/compiler、contracts/Schema、校验器和模板；本版配套 SDK/contracts `0.4.1`。`integration --json` 使用接口版本 2，返回 profile、执行器和 `documentation`，不再打包 skills 快照。
+- 工具链格式升级为 2，执行摘要只绑定 `compiler`、`validators`、`schemas`、`templates` 四项；文档正文独立更新，不改变执行摘要或使构建 receipt 失效。
+- 移除技能源码版本与 Git 来源对 CLI 构建的限制；发布包检查拒绝遗留技能快照和元数据，教程通过文档站索引与全文读取。
+
+**3. 锁定工程依赖并核对目标宿主兼容声明**
+
+- `create` 写入 `widget-toolchain.json`；新增 `adopt`，为依赖、Manifest 和 samples 已通过校验的旧工程显式建立锁定，不自动升级依赖或迁移字段。
+- 工程命令同时核对精确依赖声明、实际安装的 SDK/contracts 与固定 profile，CLI 升级不再静默更换协议组合。
+- `--host-compat` 检查目标声明，区分 `unknown`、`snapshot`、`confirmed`；无效或不接受当前 profile 的声明会提前失败。当前不包含平台在线发现或 Bohr 在线接入，真实授权仍由目标 Host 决定。
+
+**4. 以构建记录约束产物复用**
+
+- 标准 `build` 写入 `.widget-build-receipt.json`；`pack --no-build` 只有在工具链、实际依赖、工程输入和 `dist` 摘要全部匹配时才复用产物。
+- 旧工程须先完成 `doctor` / `adopt`，旧摘要格式或源码、依赖、产物变化时重新执行标准 build；单独运行工程构建脚本不替代 receipt。
+
+### 修复
+
+**5. 完整归档部署资源并统一 ZIP 边界**
+
+- ZIP 保留入口顶层构建目录中 chunk、CSS、WASM 等部署资源及目录关系；多个 sample 共用文件时去重，中文和空格路径可以正常打包。
+- 拒绝符号链接与同路径内容冲突；历史根目录入口只归档入口和显式 samples，不递归整个工程。共享 ZIP 写入逻辑与资源闭包检查，避免生成能通过结构校验却缺少运行资源的包。
+
+**6. 让生成工程可独立安装、布局与交付**
+
+- 生成工程精确依赖创建它的 CLI，安装后可用本地命令检查和打包；分别说明 CLI 的 Node 20 最低要求与默认构建器的 `^22.18.0 || >=24.11.0` 要求。
+- Widget ZIP 脚本统一为 `pnpm run widget:pack` / `npm run widget:pack`，与制作 npm `.tgz` 的 `pnpm pack` 分开，避免同名命令混淆。
+- 高度链、布局和滚动样式放入作者源码，由 `activate` 安装并随生命周期清理；JSON 换行只作用于展示元素，React 使用 `<div>` 挂载并保留一个 `<main>`，Host 入口只负责 SDK 启动与诊断。
+- 模板在 render 中应用宿主主题，启动失败显示具体原因，协议错误输出到浏览器控制台；交付仍需验证真实首帧、事件和可见布局。
+
+**7. 保留构建失败的实际诊断**
+
+- 构建失败摘要同时搜索 stderr 与 stdout，跳过包管理器警告和脚本标题，优先显示实际编译诊断；两个流都没有诊断时才回退原始输出。
+- JSON 结果保留完整 stdout、stderr 和恢复上下文，避免 npm 配置警告盖住 TypeScript 错误。
+
+**8. 对齐清单编译与 watch 重建检查**
+
+- 清单编译统一调用 SDK canonical compiler，保留 region placement 并核对对应 capability；`sdkVersion` 不能把另一代编译器输出重标为旧版本。
+- `dev --watch` 每轮重新核对工程锁、实际依赖与契约；失败时保留上一轮可用 generation，继续使用既有 NDJSON envelope 和明确的工具链错误码。
+- 工具链回归检查以实际包版本为准，不再把旧 SDK/contracts 版本硬编码为固定预期。
+
+**9. 完善公开教程与运行验收指引**
+
+- npm 包首页指向官方文档站，README 聚焦安装、开发与交付入口；通过包元数据或 `--help` 可发现完整教程。
+- [交付验收指南](https://dev.dp.tech/bohrium-widget-sdk/guides/delivery-checklist) 补充槽位与 grant 边界、事件回放后 render、终态与参数保留、可信耗时、UI 状态与文件引用分离、目录分页、读取截断和权限拒绝。
+- [文件能力指南](https://dev.dp.tech/bohrium-widget-sdk/guides/capabilities/files) 补充获授权 Panel 的已有文件编辑、完整内容与版本条件、编码保真、草稿与保存快照，以及稳定 `mutationId`、冲突及未知结果处理；这些指引不新增 SDK 运行时能力。
+- 文档站更新日志同步各包版本记录，并移除私有 GitLab 链接。
+
+CLI 运行仍要求 Node.js >=20；`/core` 保持底层编译、校验与打包 API，直接调用方负责工程锁定和目标宿主策略。
+
+## 0.1.0
+
+### 新增
+
+**1. 创建可直接开发的 Widget 工程**
+
+- `create` 提供 Vanilla 与 React 模板，并生成 Manifest、构建配置、Host 入口和示例数据。
+- 生成项目只需要实现 `activate(context)`，无需手写 Bridge 或宿主加载字段。
+
+**2. 覆盖校验、开发、构建和打包闭环**
+
+- `check`、`build`、`dev`、`pack` 与 `doctor` 提供一致的命令行体验和结构化 JSON 输出。
+- `pack` 输出可追踪的 ZIP、SHA-256 摘要、工具链版本和 Manifest 摘要，便于 Agent 与自动化流程安全接续。
+
+**3. 提供明确的诊断与恢复信息**
+
+- 校验和构建失败会返回稳定的错误代码、具体原因、上下文与下一步恢复动作。
+- `doctor` 区分工程骨架是否有效与依赖、构建产物是否就绪，减少重复尝试。
+
+**4. 支持生成可直接绑定的工作区文件面板**
+
+- `create --panel-id workspace-files` 会生成稳定的 Panel id、完整的只读文件能力声明和对应 sample。
+- 生成工程统一执行 TypeScript 类型检查，避免错误源码被 bundler 当作可发布产物。
+
+### 修复
+
+**5. 阻止未解析依赖和不可点击的文件 fixture 混入产物**
+
+- `build` 会识别构建器退出码为 0 时仍存在的未解析依赖，并返回稳定错误码。
+- `check` 会校验 `workspace-files` 所需能力，以及目录 fixture 中每个文件的读取内容和字节大小。
+- `check` 与 `pack` 会在 Manifest 编译失败时保留原始契约错误，不再被二次异常覆盖。
+- DSH scaffold 会生成完整 TypeScript 配置；未解析依赖报错会指向实际命中的诊断行。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DP Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @dp-bohrium/widget-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+创建、开发和打包 Bohrium 自定义 Widget 的命令行工具。
+
+[文档站](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)
+
+## 环境
+
+推荐使用 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
+cd my-widget
+pnpm install
+pnpm exec bohr-widget build .
+pnpm exec bohr-widget check .
+pnpm run widget:pack --out artifacts/my-widget.zip
+```
+
+编辑 `src/widget.tsx` 实现界面。原生 DOM 使用 `--ui vanilla`；文件预览使用
+`--template file-preview`。生成工程已包含本地 CLI 依赖，不需要全局安装。
+
+使用 npm 时，创建命令改为 `npx --yes @dp-bohrium/widget-cli create my-widget --template panel --ui react`，
+进入工程后执行：
+
+```bash
+npm install
+npx --no-install bohr-widget build .
+npm run check
+npm run widget:pack -- --out artifacts/my-widget.zip
+```
+
+`widget:pack` 生成 Widget ZIP；`pnpm pack` 是制作 npm `.tgz` 的内置命令。
+`check` 检查声明和样例，不执行界面；实际运行验收见[交付指南](https://dev.dp.tech/bohrium-widget-sdk/guides/delivery-checklist)。
+
+## 开发预览
+
+在工程目录监听修改并重新构建：
+
+```bash
+pnpm exec bohr-widget dev . --watch
+```
+
+追加 `--open` 可连接已安装且支持开发接入的目标 Host；`dev` 不会独立打开普通浏览器预览页。
+真实面板的注册、文件授权和 Agent 绑定由目标平台提供，详见[本地开发](https://dev.dp.tech/bohrium-widget-sdk/guides/cli#本地开发)。
+
+## 帮助与常用命令
+
+```bash
+pnpm exec bohr-widget --help
+pnpm exec bohr-widget create --help
+pnpm exec bohr-widget help pack
+pnpm exec bohr-widget --version
+```
+
+无参数、`-h`、`help` 也可查看帮助。npm 使用 `npx --no-install bohr-widget --help`；
+尚未安装时可运行 `pnpm dlx @dp-bohrium/widget-cli --help`。
+
+以下命令通过 `pnpm exec bohr-widget` 或 `npx --no-install bohr-widget` 执行：
+
+| 命令 | 用途 |
+| --- | --- |
+| `build .` | 构建当前工程 |
+| `check .` | 校验 Manifest、入口与样例 |
+| `pack . --out artifacts/widget.zip` | 构建、校验并生成 ZIP |
+| `dev . --watch` | 监听源码变化，供目标 Host 联调 |
+| `doctor .` | 检查环境与工程状态 |
+
+## 继续阅读
+
+- [SDK](https://www.npmjs.com/package/@dp-bohrium/widget-sdk)：Widget 生命周期与能力调用。
+- [Contracts](https://www.npmjs.com/package/@dp-bohrium/widget-contracts)：公开类型与 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/licenses/ajv@8.20.0/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2021 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/assets/licenses/fast-deep-equal@3.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/licenses/fast-uri@3.1.6/LICENSE

@@ -0,0 +1,30 @@
+Copyright (c) 2011-2021, Gary Court until https://github.com/garycourt/uri-js/commit/a1acf730b4bba3f1097c9f52e7d9d3aba8cdcaae
+Copyright (c) 2021-present The Fastify team <https://github.com/fastify/fastify#team>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * The names of any contributors may not be used to endorse or promote
+      products derived from this software without specific prior written
+      permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+                                  *   *   *
+
+The complete list of contributors can be found at:
+- https://github.com/garycourt/uri-js/graphs/contributors

package/assets/licenses/json-schema-traverse@1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Evgeny Poberezkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/licenses/require-from-string@2.0.2/license

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Vsevolod Strukchinsky <floatdrop@gmail.com> (github.com/floatdrop)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/assets/licenses/widget-contracts.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DP Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/licenses/widget-sdk.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DP Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.