百川自定义页面插件 CLI

此仓库包含用于构建百川 OS 自定义页面低代码业务组件插件的 MVP 阶段 CLI 工具。

该 CLI 工具可以将插件开发者的 React 组件和 plugin.json 编译转化为可供数字造机低代码平台以及百川 OS 自定义页面运行态消费的共享产物：

• dist/editor.iife.js
• dist/runtime.iife.js
• dist/style.css
• dist/plugin.json
• release/*.manifest.json
• release/*.checksums.json
• release/*.zip
• release/*.deb （当需要 Debian 打包且系统存在 dpkg-deb 工具时生成）

常用命令

pnpm install
pnpm build
node dist/cli.js doctor

本地开发调试命令默认启动在 127.0.0.1:3004：

pnpm dev

创建一个电池插件示例工程。react-battery 是默认模板，因此也可以省略 --template：

node dist/cli.js create battery-plugin \
  --plugin-id com.baichuan.custom-page.battery \
  --template react-battery \
  --device-type MCR

在生成的插件项目中进行开发与构建：

cd battery-plugin
pnpm install
pnpm validate
pnpm build
pnpm pack:zip
pnpm pack:deb

向已有插件项目添加新的业务组件（Widget）：

pnpm exec baichuan-plugin add-widget AlarmList \
  --type alarm-list.panel \
  --category alarm

npm 使用方式

发布到 npm 后，可以通过以下方式直接命令行使用：

pnpm dlx @baichuan-os/plugin-cli create battery-plugin \
  --plugin-id com.baichuan.custom-page.battery \
  --template react-battery \
  --device-type MCR

也可以全局安装后使用主命令：

pnpm add -g @baichuan-os/plugin-cli

baichuan-plugin create battery-plugin \
  --plugin-id com.baichuan.custom-page.battery \
  --template react-battery \
  --device-type MCR

生成插件后进入插件目录：

cd battery-plugin
pnpm install
pnpm dev

pnpm dev 默认监听 http://127.0.0.1:3004/。如需临时切换端口，可执行：

pnpm exec baichuan-plugin dev --port 3005

如果希望支持更短的 pnpm create baichuan-plugin battery-plugin，需要在 npm 上额外发布一个名为 create-baichuan-plugin 的 create 入口包，或将该名称作为正式包名发布。

MVP 阶段实现范围

已实现的 CLI 命令：

• create：创建插件工程模板，默认生成基于发布包示例的 react-battery 电池组件。
• add-widget：增量添加业务组件骨架代码。
• dev：启动本地开发服务器，提供动态 manifest 调试接口。
• validate：对项目配置、规范及代码契约执行严格校验。
• build：打包编译双端 IIFE bundle 并提取 CSS 样式。
• pack-zip：将打包产物以 zip 格式进行打包。
• pack-deb：将打包产物以 deb 格式进行打包。
• doctor：对当前运行环境（Node.js, pnpm 等）进行诊断。
• inspect：查看解析并格式化后的 manifest 以及产物详情。

权限声明与初始化

新模板会默认初始化 plugin.json.permissions，并生成 src/shared/permissions.ts 作为代码侧权限检查示例：

• sdkScopes、mapiScopes、streamScopes 声明插件要调用的宿主能力。
• controlPoints 声明插件内部按钮、面板或服务端动作，编码必须以 plugin.<pluginId>. 开头。
• 插件页的“查看/控制”权限由百川 OS 在导入时自动生成，不要在 controlPoints 中重复声明，也不要手工追加 .view / .control 子项。
• plugin.json.permissions 是权限声明的唯一来源；src/shared/permissions.ts 只复用稳定权限码，不复制整份声明。
• 模板里的刷新按钮使用 context.permissions.can(...) 判断当前用户是否有权操作。

数据请求（MAPI HTTP）

百川 OS 插件沙箱禁止直接使用 fetch、axios 和 XMLHttpRequest。新模板会生成 src/shared/http.ts，基于宿主注入的 context.sdk.mapi.request 提供 get、post、put、patch 和 delete 方法，统一处理 query、response.data 解包、非 2xx 状态和传输错误。

plugin.json.permissions.mapiScopes 默认带有一个当前 SDK 校验允许的读权限示例。开发者必须根据后端接口替换为实际 scope；本地调试则通过 src/shared/mock-sdk.ts 中的 mapi.request 路由返回分页、列表和状态样例数据。

构建输出中的 dist/plugin.json、release/*.manifest.json 和组件 zip 根目录 plugin.json 都会保留归一化后的完整权限声明。dist/build-meta.json 会额外记录权限摘要，方便排查导入或授权问题。

需要注意：CLI 只负责初始化、合并和校验声明；插件页入口的 myAuth 动态目录仍由百川 OS 在导入页面包后注册，运行时最终授权由宿主注入的 context.permissions 和服务端强制校验共同决定。

国际化与依赖策略

为了对齐百川 OS 的国际化规范，并避免引入类似 i18next 等运行时多余的第三方依赖，CLI 制定了以下规则：

• 声明文件支持的多语言固定为 zh（简体中文）、zh-TW（繁体中文）、en（英文）、vi（越南文）和 ms-MY（马来文）。
• plugin.json.i18n.defaultLocale 和 plugin.json.i18n.fallbackLocale 必须全部设置为 zh。
• plugin.json 中的 name、description 以及组件层级的 widgets[].title 和 widgets[].description 必须完整提供上述五种语言。
• 生成的组件会优先读取宿主注入的 data-baichuan-locale，并用本地自动生成的 src/shared/i18n.ts 处理 zh-CN、zh-HK、zh-Hant、en-US、vi-VN、ms 等别名映射。
• 运行态业务文案由插件自己的五语字典提供；宿主只负责注入当前语言环境，不再依赖 SDK 翻译入口。
• 主题色和明暗模式由宿主通过 data-baichuan-theme、data-baichuan-color-scheme、data-baichuan-primary-color 以及 --bc-* / --personal-theme-color CSS 变量注入，插件监听 baichuan-plugin-environment-change 后刷新视图，不再调用 SDK 主题入口。

依赖项规则（由 validate 命令严格执行校验）：

• React、ReactDOM、Ant Design、组件图标库、ECharts 以及 Three.js 都被锁定为宿主系统内置共享的版本，并且在构建时作为 external 排除，不打进最终 bundle。
• 这六类共享依赖必须同时声明在 devDependencies 和 peerDependencies 中，禁止出现在 dependencies 中。
• 依赖声明的版本号必须为精确的 npm 版本（例如 19.0.0），禁止使用 ^、~、latest、workspace:* 或 file: 等模糊说明符。
• 插件自己特有的前端依赖仍可以放进 dependencies，并会被正常打包融合进 bundle 中。

组件属性契约校验 (Prop Contract Validation)

validate 校验工具将低代码配置清单中的 Schema 视为唯一的真理来源（Source of Truth），并在编译构建前强制执行这些规则契约：

• propsSchema.type 必须为 object，且 propsSchema.properties 不能为空。
• defaultProps 中的所有 key 必须存在于 propsSchema.properties 中。
• propsSchema.required 中声明的必填 key 必须存在于 propsSchema.properties 中，且必须在 defaultProps 中提供相应的默认值。
• uiSchema 中的所有配置项必须在 propsSchema.properties 中存在定义。
• 当 propsSchema.properties.*.default 与 defaultProps 中的同名属性同时存在时，它们的值必须完全一致。
• 当工程内的 props.ts 类型定义文件可以被成功解析时，propsSchema.properties 中声明的所有属性必须在对应的 *Props TS 接口中定义。

注：源代码对属性的消费引用分析目前仅输出为 Warning。如果某个属性未在 editor.tsx 或 runtime.tsx 中直接解构使用，CLI 会发出警告，但这并不影响打包（因为该属性可能通过参数透传给子组件，或通过对象展开运算符解包使用）。

注意事项

• 生成模板项目时，CLI 会自动解析 npm 上的 @baichuan-os/plugin-support@latest，并把解析到的精确版本写入 package.json 和 plugin.json.sdkVersion；如果网络或 registry 不可用，会使用当前已安装的 @baichuan-os/plugin-support 版本。
• 模板项目会生成 .npmrc，将 @baichuan-os scope 指向 public npm，避免本机私有 registry 配置导致 @baichuan-os/plugin-support 安装失败。
• 构建时会自动将这些共享包排除在 editor 和 runtime 包之外。
• 考虑到公共的 @baichuan-os/plugin-support/sdk 仅提供了 SDK 接口定义和连接桥，并未提供组件本身相关的桥接 API，因此 MVP 模板内部使用了一个局部的 src/shared/plugin-api.ts 文件来作为临时过渡。
• 默认 react-battery 模板申请 robot.read 和 plugin.<pluginId>.action.refresh，运行态通过公开的 context.sdk.robot.getBatteryStatus() 读取电池状态。本地调试宿主提供同名 mock，导入百川 OS 后使用宿主注入的真实 SDK。
• pack-zip 生成的压缩包在根目录下呈扁平结构，即直接包含 plugin.json、dist/、checksums.json 和 signature.json，这是最有利于平台解析的格式。
• 对于不支持 dpkg-deb 工具的操作系统（例如 macOS 或未装对应依赖的 Linux），pack-deb 会在 release/*.deb-root 中生成完整的待打包暂存树以及校验和，并输出警告。

示例验证

可以使用 create 命令生成一个测试验证项目，例如：

node dist/cli.js create battery-plugin \
  --plugin-id com.baichuan.custom-page.battery \
  --template react-battery \
  --device-type MCR

生成的 battery-plugin 默认包含以下示例组件：

• battery.status-card（电池状态卡片）：包含 title、showTitle、accentColor、refreshInterval 和 showBatteryList 五个可配置 props。
• 编辑态使用 src/widgets/BatteryStatus/props.ts 中的样例数据稳定预览。
• 运行态在 src/widgets/BatteryStatus/runtime.tsx 中调用 context.sdk.robot.getBatteryStatus()，并通过 src/widgets/BatteryStatus/view.tsx 的 normalizeBatteries() 适配 SDK 返回数据。

可在生成的示例项目中执行以下命令进行完整校验：

pnpm validate
pnpm build
pnpm pack:zip
pnpm pack:deb