@leevan/module-builder

将已经构建完成的 JT 桌面子系统封装为主系统可下载、校验和安装的 JTM1 模块包。 这是一个发布期 Node.js 工具，不参与子系统页面运行。

安装

当前为实验版本，项目应固定具体版本：

pnpm add -D @leevan/[email protected]

要求 Node.js 20.19 或更高版本。

项目约定

默认从当前目录读取：

module.json
dist/
  index.html
  assets/

推荐的模块清单：

{
  "id": "inventory-center",
  "name": "库存中心",
  "version": "1.0.0",
  "entry": "index.html",
  "hostApiRange": "^1.1.0",
  "minShellVersion": "1.0.0",
  "router": "hash",
  "routes": ["/records"],
  "allowedOrigins": []
}

permissions、capabilities 和其他未登记字段会被拒绝。模块必须使用 Hash Router， 入口、路由、来源地址和所有文件路径都会在打包前校验。

打包

Builder 不调用 Vite，也不绑定 pnpm。由子系统先完成页面构建，再执行打包：

{
  "scripts": {
    "build": "vite build",
    "module:pack": "jt-module pack",
    "release": "pnpm build && pnpm module:pack"
  }
}

pnpm release

默认输出：

release/
  modules/
    inventory-center/
      1.0.0/
        module.jtm
        module.json

包内还会写入一份规范化的运行时 module.json。外部同名文件是 release descriptor， 其中包含模块信息、JTM 地址、文件大小和整个模块包的 SHA-256。

可用选项：

--root <path>          项目根目录
--manifest <path>      manifest 路径，默认 module.json
--dist <path>          Vite 产物目录，默认 dist
--out <path>           发布产物根目录，默认 release
--version <x.y.z>      覆盖本次模块版本
--package-url <path>   模块仓库中的相对 JTM 地址
--json                 输出供流水线读取的 JSON

例如：

jt-module pack --root . --version 1.1.0 --json

JSON 结果包含可交给中央 registry 流水线的 catalogEntry。Builder 不负责上传文件， 也不会直接覆盖 stable.json 等公共 catalog。

同一个模块版本不可覆盖：重复打包得到完全相同的内容时会直接复用已有产物；内容发生 变化时必须先提升 module.json 版本。程序化 limits 只允许收紧 JTM1 的固定上限， 不能生成超出当前宿主能力的模块包。

如果打包进程被强制中止，版本目录旁可能留下 .版本号.lock。确认没有其他 jt-module pack 进程正在处理该版本后，删除错误信息中给出的锁文件并重试。

格式能力

@leevan/module-builder/jtm 导出 JTM1 的创建、读取和安全解包 API，Electron 宿主应采用这个入口，与构建端共享同一份格式实现：

import { readJtmPackage, extractJtmPackage } from '@leevan/module-builder/jtm'

默认限制为：模块包 50 MiB、展开后 100 MiB、单文件 20 MiB、最多 5,000 个文件。 打包会拒绝符号链接、路径穿越、大小写冲突、Windows 保留路径及打包过程中发生变化的文件。

SHA-256 用于检测传输或存储损坏，不用于证明发布者身份。模块上传、catalog 原子更新和 发布账号控制应由独立的 registry 发布流程负责。