@dp-bohrium/widget-cli 0.1.0 → 0.2.0

package/AGENTS.md

@@ -4,6 +4,28 @@
 `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
@@ -13,27 +35,102 @@ 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 [--json]
-bohr-widget help | -h | --help
+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`、`name` 和可选
+1. `create` 创建工程后检查返回的 `projectRoot`、`manifestPath`、`packagePath`、`profile`、`name` 和可选
    `panelId`；工作区文件面板固定使用 `--panel-id workspace-files`，CLI 会补齐三项只读文件能力。
    `warnings` 说明目录名不是合法标识符时 `manifest.name` 已回退为 `widget-<hash>`。
-2. 安装工程依赖（`pnpm install` 或 `npm install`）。
-3. 执行工程 `build`（或 `bohr-widget build .`）。失败时先读取 JSON 里的 `error.message`（已带构建器
-   stderr 摘要）、`stdout` 和 `stderr`，不要直接重复执行。
+   将 `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` 和当前目录的
@@ -45,10 +142,26 @@ bohr-widget help | -h | --help
 ## doctor
 
 `doctor --json` 的 `ok` 要求 Node 版本受支持、`package.json` 存在且
-`manifest.json` 是有效 JSON；`ready` 在此基础上还要求 `node_modules` 与构建入口存在。
+`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` 处理。至少记录：
@@ -64,10 +177,16 @@ bohr-widget help | -h | --help
 - `WIDGET_CLI_MANIFEST_INVALID`：作者清单本身有错（`version` 缺失或不是 semver、`displayName`
   不是字符串、顶层有未知字段）。这类错误不再回落到宿主 schema，直接按 `errors` 里的字段名修。
 - `WIDGET_CLI_NO_WIDGET_PROJECT`：`check all` 没有匹配到工程。
-- `WIDGET_CLI_BUILD_FAILED`：工程 `build` 脚本失败；`error.message` 带构建器 stderr 首行，
+- `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 中
@@ -79,6 +198,10 @@ bohr-widget help | -h | --help
 里带 `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

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 本文件记录使用者可感知的命令、工程模板、校验与打包能力变化。
 
+## 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
 
 ### 新增

package/README.md

@@ -1,123 +1,81 @@
 # @dp-bohrium/widget-cli
 
-Agent 使用入口：先读 [`llms.txt`](./llms.txt) 获取文档索引，再读
-[`AGENTS.md`](./AGENTS.md) 获取命令、参数、错误和恢复规则。
+创建、开发和打包 Bohrium 自定义 Widget 的命令行工具。
 
-Bohrium Widget 插件工程工具。它把创建、校验、开发预览和打包收敛为一个开发者入口，
-不参与 Widget 运行时，也不暴露 Host 的 Bridge、iframe 或内部面板实现。
+[文档站](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)
 
-```bash
-pnpm dlx @dp-bohrium/widget-cli create my-widget --template panel --ui react \
-  --panel-id workspace-files
-cd my-widget
-pnpm install
-bohr-widget build .
-bohr-widget check .
-bohr-widget pack .
-```
+## 环境
 
-`bohr-widget pack` 默认先执行工程自己的 `build` 脚本，再把作者维护的插件清单编译为宿主可加载的
-插件清单，并自动生成宿主入口、读取当前安装的 SDK 版本。开发者不需要填写构建后的 `dist`
-路径、`widgetSdkVersion`、`contribution` 或 Bridge 字段；需要复用已有构建产物时可使用 `--no-build`。
-`pack --out ./artifacts/release/widget.zip` 会自动创建父目录；`--json` 结果里的
-`fixtures.requested` / `fixtures.included` 说明 `preview/fixtures.json` 是否真的打进了 ZIP，
-被跳过时会出现在 `warnings` 中，不再静默忽略。
-
-`--ui vanilla` 生成原生 DOM 模板，`--ui react` 生成 React + TypeScript + `createRoot` 模板。
-两种模板都只导出 `activate(context)`；CLI 另外生成 `src/widget-host.ts`，由独立的
-Widget Host 启动边界调用 SDK。React 只是可替换的开发层，不会改变插件生命周期。
-
-创建工作区文件面板时使用 `--panel-id workspace-files`。CLI 会自动补齐
-`files.list`、`files.metadata`、`files.read` 和目录根 sample；其他 Panel id 只有在 Host
-已经注册并绑定对应路由时才能显示。
-
-生成的工程自带 `tsconfig.json`（含 `allowImportingTsExtensions`，React 模板附带 `jsx: react-jsx`）、
-`.gitignore` 和 `README.md`，`tsdown` 配置默认开启 `minify`（React 产物约 258 KB，未压缩约 1.06 MB）。
-工程 `build` 会先运行 `tsc --noEmit`；即便 bundler 返回退出码 0，CLI 也会拒绝包含未解析依赖
-诊断的构建结果。
-`create` 会把目录名规范化为 `manifest.name` 和 `contributes.widget.id`；目录名不是合法标识符
-（例如中文目录名）时回退为 `widget-<hash>` 并通过 `warnings` 说明。
-
-如果需要封装自己的 CLI，可以使用稳定的核心出口，不需要导入内部实现：
-
-```ts
-import {
-  createWidgetTemplateRegistry,
-  defineWidgetTemplate,
-  checkWidgetProject,
-  buildWidgetPackage,
-} from "@dp-bohrium/widget-cli/core";
-```
-
-`core` 提供模板注册、清单编译、工程校验和插件包打包；官方 `bohr-widget` 负责默认模板和命令行
-参数，社区工具可以自行选择 Vite、Webpack、esbuild 或其他 bundler。
+推荐使用 Node.js 24（>=24.11.0）。CLI 本身支持 Node.js >=20，默认模板的构建器要求
+`^22.18.0 || >=24.11.0`。安装 pnpm 或 npm 后即可开始。
 
-`@dp-bohrium/widget-cli/development-host` 只导出开发宿主的**类型**（`exports` 里只有 `types`
-条件），运行时 `import` 会抛 `ERR_PACKAGE_PATH_NOT_EXPORTED`；它是给类型检查用的，不是可执行入口。
+SDK/contracts 的配套版本由 CLI 固定管理，创建工程后安装其依赖即可。
 
-`bohr-widget dev` 提供本地开发服务器，`--watch` 可在源码变化后重新构建，`--open` 可连接
-Widget Development Host v1。SciX bridge 优先使用
-`POST /widget-host/desktop/v1/development-sessions`，不支持 v1 时回落 legacy profile 并告警。
-`bohr-widget dev --json` 输出 `bohrium.widget-development-cli` v1 的逐行 NDJSON envelope
-（`session-ready` 里带 `profileUrl`/`statusUrl`/`hostUrl`/`digest`/`assets`），不是单个 JSON
-文档；`--watch` 会在重建后继续追加 envelope。协议、安全 token、descriptor/status/events/control
-和不可变 generation 约束会通过 `session-ready`、状态接口与错误 envelope 返回；Agent 可按
-[`AGENTS.md`](./AGENTS.md) 的错误处理规则读取并恢复，不需要依赖仓库内部文档。
+## 创建并打包
 
-`bohr-widget doctor --json` 适合接入 CI 和问题诊断：`ok` 表示 Node 版本、`package.json` 和
-有效的 `manifest.json` 都存在，`ready` 在此基础上还要求 `node_modules` 与构建入口存在，原因
-写在 `warnings` 里。尚未安装依赖或尚未构建时 `ok=true` / `ready=false`。
+下面创建一个 React 面板，构建、检查后生成 ZIP：
 
-## Bohr CLI 桥接契约
+```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
+```
 
-Bohr CLI 可以把 Widget CLI 作为本地工程执行器调用。`widget-cli` 只负责工程创建、校验、
-构建、开发预览和 Bundle 打包；上传、preview、commit、版本发布和 Agent 绑定由 Bohr CLI
-及平台服务负责。
+编辑 `src/widget.tsx` 实现界面。原生 DOM 使用 `--ui vanilla`；文件预览使用
+`--template file-preview`。生成工程已包含本地 CLI 依赖，不需要全局安装。
 
-需要机器消费结果时使用 `--json`：
+使用 npm 时，创建命令改为 `npx --yes @dp-bohrium/widget-cli create my-widget --template panel --ui react`，
+进入工程后执行：
 
 ```bash
-bohr-widget create ./my-widget --template panel --json
-bohr-widget validate ./my-widget --json
-bohr-widget version --json
-bohr-widget pack ./my-widget --out ./artifacts/widget.zip --json
+npm install
+npx --no-install bohr-widget build .
+npm run check
+npm run widget:pack -- --out artifacts/my-widget.zip
 ```
 
-`validate` 是 `check` 的桥接别名。`check all` 以**当前工作目录**为根，依次查找
-`examples/sdk`、`examples/integration` 和当前目录的 `manifest.json`；找不到任何工程时返回
-`error.code=WIDGET_CLI_NO_WIDGET_PROJECT` 并以退出码 1 结束，不会静默通过。`check all --json`
-输出单个汇总文档（`checked` / `passed` / `failed` / `results[]`）；传入单个目录或
-`manifest.json` 时仍输出该工程的校验结果，与既有桥接契约一致。
+`widget:pack` 生成 Widget ZIP；`pnpm pack` 是制作 npm `.tgz` 的内置命令。
+`check` 检查声明和样例，不执行界面；实际运行验收见[交付指南](https://dev.dp.tech/bohrium-widget-sdk/guides/delivery-checklist)。
 
-`check` / `validate` 会先补一遍作者清单检查：`version` 必填且为 semver、`displayName` 必须是
-字符串、顶层不允许未知字段、`entry` 指向的源文件必须存在（缺失只告警）。这些字段不会进入宿主
-清单，写错过去不会报错；现在直接返回 `error.code=WIDGET_CLI_MANIFEST_INVALID` 和具体字段名，
-而不是套用宿主 schema 后产生一串 `must NOT have additional properties`。
-对于 `workspace-files`，还会要求三项只读文件能力完整；存在 preview fixture 时，目录清单中的
-每个文件必须有 `files.read` 内容，声明的大小也必须与实际字节数一致。
+## 开发预览
 
-`pack --json` 返回产物路径、字节数、`sha256:<hex>`、
-CLI/SDK/Contracts `toolchain` 版本、Manifest 摘要和校验结果；Bohr CLI 应继续使用同一份 ZIP 和 digest，不要重新构建或替换
-产物字节。CLI 返回 `ok=true` 只证明本地校验或打包成功，不代表 平台 浏览器已经渲染，
-也不代表 Widget 已发布或绑定 Agent。
+在工程目录监听修改并重新构建：
 
-## DeepSeek Harness 迁移
+```bash
+pnpm exec bohr-widget dev . --watch
+```
 
-迁移命令只读取 DSH 源目录，不执行 Cordis patch 或源插件安装脚本：
+追加 `--open` 可连接已安装且支持开发接入的目标 Host；`dev` 不会独立打开普通浏览器预览页。
+真实面板的注册、文件授权和 Agent 绑定由目标平台提供，详见[本地开发](https://dev.dp.tech/bohrium-widget-sdk/guides/cli#本地开发)。
+
+## 帮助与常用命令
 
 ```bash
-bohr-widget migrate dsh audit /path/to/dsh-plugin --json
-bohr-widget migrate dsh scaffold /path/to/dsh-plugin --out ./my-dsh-widget
+pnpm exec bohr-widget --help
+pnpm exec bohr-widget create --help
+pnpm exec bohr-widget help pack
+pnpm exec bohr-widget --version
 ```
 
-审计结果包含 `rulesetVersion`、DSH profile、来源指纹、peer 版本范围和能力分级。只有已审查
-的精确来源指纹才允许 scaffold；指纹变化会进入 `source-changed`/`requires-review`，避免 DSH
-破坏式更新静默生成错误 Widget。工具执行、Skill、system prompt、文件、网络和 DSH client UI
-不会被嵌入 Widget，须由平台宿主适配器承接。`migration-report.json` 仅作旁车资料。
+无参数、`-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 .` | 检查环境与工程状态 |
 
-`dsh-better-sidebar` 的已审查配方会生成声明 `capabilities.region` 的 `session.rightRail` Widget
-shell，并把文件树、编辑器、任务和侧聊继续标为 Host adapter 工作；审计状态仍是
-`requires-host-work`，因为生成 shell 不等于这些后端服务已经迁移。
+## 继续阅读
 
-生成工程仍走普通 `check → build → pack`；上传、preview、commit、版本发布和 Agent binding
-由 Bohr CLI/平台执行，必须继续使用同一份 ZIP 与 digest。
+- [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.