百川自定义页面插件 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 以及产物详情。

国际化与依赖策略

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

• 声明文件支持的多语言固定为 zh（中文）、en（英文）和 vi（越南文）。
• plugin.json.i18n.defaultLocale 和 plugin.json.i18n.fallbackLocale 必须全部设置为 zh。
• plugin.json 中的 name、description 以及组件层级的 widgets[].title 和 widgets[].description 必须完整提供上述三种语言。
• 生成的组件会接收 context.locale 属性，并使用本地自动生成的 src/shared/i18n.ts 辅助函数自动处理 zh-CN、en-US、vi-VN 等别名映射。
• 运行态业务文案应优先使用宿主系统注入的 context.i18n 或 context.sdk.i18n；模版中的 i18n 辅助函数仅用作无依赖的兜底方案。

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

• React、ReactDOM、Ant Design 以及组件图标库都被锁定为宿主系统内置共享的版本，并且在构建时作为 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 会发出警告，但这并不影响打包（因为该属性可能通过参数透传给子组件，或通过对象展开运算符解包使用）。

注意事项

• 生成的模板项目默认锁定的依赖版本为：React 19.0.0、ReactDOM 19.0.0、Ant Design 6.1.3、@ant-design/icons 6.1.0、Vite 7.0.0、TypeScript 5.9.3、@baichuan-os/plugin-sdk 0.1.0。
• 构建时会自动将这些共享包排除在 editor 和 runtime 包之外。
• 考虑到公共的 @baichuan-os/[email protected] 仅提供了 SDK 接口定义和连接桥，并未提供组件本身相关的桥接 API，因此 MVP 模板内部使用了一个局部的 src/shared/plugin-api.ts 文件来作为临时过渡。
• 默认 react-battery 模板会申请 robot:battery:read 权限，并在运行态调用 context.sdk.robot.getBatteryStatus()。如果宿主 SDK 权限名有变化，需要同步调整 plugin.json.permissions.sdkScopes 和 CLI 校验白名单。
• 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