模块开发与 Bundle 自动安装

当前平台没有独立的“模块市场”交付概念。模块是 Bundle 的内部资源，面向用户发布和安装 的是 Bundle：

• module-service 保存模块定义、不可变版本和安装 Artifact。
• Bundle Manifest 引用精确的 moduleId + semanticVersion。
• Bundle Version 冻结后保存精确资源锁。
• 用户把 Bundle 安装到 Runtime，Bundle Service 自动物化其中的模块。

同一个模块在同一个 Runtime 中只能安装一次。Bundle 升级引用模块的新版本时，更新现有 模块安装，不会创建第二条同模块安装记录。

完整交付链

模块项目 Git
  -> 在所属 Bundle 内冻结不可变模块版本
  -> Bundle Manifest 引用精确模块版本
  -> 冻结 Bundle Version 和 resolvedLock
  -> 发布 Bundle
  -> 用户把 Bundle 安装到 Runtime
  -> Bundle Service 自动物化模块

模块自动安装由 Bundle Service 完成，不需要为每个模块配一个插件服务。

第一步：开发模块

模块首先是一个可安装的运行时能力契约。模块项目至少要确定：

• module.json 中的名称、属性、用户域和依赖。
• methods/*.json 中的方法名称、参数、返回值、错误语义和实现。
• 哪些属性由用户填写，哪些来自 Runtime 或 Bundle 安装输出。
• 模块方法由页面、智能体、工作流还是后端服务调用。
• 模块状态和业务数据保存在哪里。

模块版本不是市场商品。冻结模块版本的目的，是生成可被 Bundle 精确引用和安装的不可变 资源。

第二步：选择运行与存储模式

外部服务不是模块获得存储能力的前置条件。是否使用外部服务，取决于业务逻辑和数据边界； 是否使用生命周期插件，则取决于整个 Bundle 是否需要自动管理平台外部资源。

用户已经拥有第三方业务租户时，可以在安装配置中填写 vendorTenantId 和凭据。这是连接 已有账号，不需要为了自动安装模块增加生命周期插件。

第三步：在 Bundle 内冻结模块版本

从模块项目 Git 提交发布不可变模块版本：

baijimu bundle module freeze <workspace> <bundle> <projectId> \
  --module-id <moduleId> \
  --version <semanticVersion> \
  --commit-id <commitId>

这里生成的是 Bundle 可引用资源，不是把模块提交到独立市场。单独冻结模块新版本不会 改变 Bundle，也不会升级任何已安装 Runtime。

第四步：纳入 Bundle

在 Bundle Manifest 中引用精确模块版本：

{
  "backendModules": [
    {
      "moduleId": 2200,
      "semanticVersion": "1.3.0"
    }
  ]
}

Bundle 冻结时解析模块安装 Artifact 并写入 resolvedLock。Bundle 安装、升级和卸载 过程中，Bundle Service 负责模块资源编排和台账记录。

第五步：验证自动安装

至少使用两个不同 Runtime 验证：

1. Bundle resolvedLock 引用了预期模块版本。
2. Bundle 安装后模块方法、属性和用户域正确。
3. 同一模块在同一 Runtime 不能重复安装。
4. 安装重试不会生成重复模块记录。
5. 同一 Bundle 安装到不同 Runtime 时，配置和业务数据相互隔离。
6. Bundle 升级更新现有模块，同时保持安装身份和用户配置。
7. 卸载不会影响其他 Runtime 中的安装。
8. 失败资源在 Bundle 台账中保留明确错误，不能静默跳过。

什么时候进入高级开发

完成普通 Bundle 后，如果安装过程还必须执行以下动作，再进入 高级 Bundle 开发：

• 自动创建外部租户、数据库、许可证、存储空间或第三方账号。
• 多个模块和平台应用共享同一个外部安装实例。
• Bundle 升级需要迁移外部配置或数据。
• Bundle 卸载需要停用、保留或回收外部资源。
• 外部操作需要验证、重试、回滚或补偿。

生命周期插件属于整个 Bundle 的安装编排。模块只是插件可以读取安装结果或接收属性输出 的一类资源，不拥有插件注册和执行流程。