创建版本并纳入 Bundle

平台应用定义、不可变版本和 Bundle 版本是不同对象。平台应用先创建自己的不可变版本，再由 Bundle 锁定并组合交付。

创建版本与安装链路

本文完整流程面向 ENVIRONMENT_HOSTED_APP。普通外链不进入前端构建和平台授权链路。

Platform Application
  -> Platform Application Version
  -> Bundle Manifest
  -> Immutable Bundle Version
  -> Workspace Bundle Install
  -> Platform-managed Hosting + Same-origin Configuration
  -> Bundle Installation Authorization

使用 CLI

先确认本机 CLI 的版本和当前命令：

baijimu --version
baijimu platform-app --help
baijimu platform-app version create --help
baijimu bundle create --help
baijimu bundle version create --help

先创建专属项目。项目类型必须使用稳定键 PLATFORM_APPLICATION，不能依赖某个环境里的数字类型 ID：

baijimu project create \
  --workspace-id <workspaceId> \
  --project-type-key PLATFORM_APPLICATION \
  --name <projectName>

平台应用项目的模板归档和 baijimu.platform-application.json 初始内容属于 PLATFORM_APPLICATION 项目类型目录，不由创建命令指定。

项目初始化后会包含 baijimu.platform-application.json。入口、方法、配置 Schema、Manifest、卡片和工作流声明都在这个文件中维护；字段是原生 JSON 对象或数组，不是再次编码的 JSON 字符串。

环境托管前端使用 ENVIRONMENT_HOSTED_APP，入口为版本内相对根路径，例如 /index.html。项目根目录 package.json 的 version 必须等于创建的版本，源文件须先提交到项目主线。首次创建项目制品版本时平台读取主线、校验版本并固定源码，再构建不可变制品。重试同一版本沿用已经固定的源码，主线变化不会换源；修改源码必须使用新版本。

配置环境托管前端

新开发的 React/Vite 平台应用使用以下清单。/index.html 是版本构建产物内的入口，不是外部 URL，也不是 Manager 内置路由：

{
  "schemaVersion": "3.0.0",
  "entry": {
    "urlTemplate": "/index.html",
    "type": "ENVIRONMENT_HOSTED_APP",
    "openMode": "WORKSPACE_TAB"
  },
  "methodDefinitions": [
    {
      "target": {
        "type": "module",
        "bundleId": "workspace-core",
        "moduleId": "2108"
      },
      "methods": [
        "listWorkspaceMembers"
      ]
    }
  ],
  "configSchema": {
    "type": "object"
  },
  "manifest": {},
  "cardDefinitions": [],
  "workflowDefinitions": []
}

入口不能包含外部域名、查询串、hash 或 {installId}；平台负责生成实际 accessUrl 并追加安装标识。

前端使用标准 SDK 的 createPlatformApplicationClientFromHostedConfiguration(applicationDefinition.id) 初始化， 从同源 /.well-known/baijimu-platform-application.json 读取当前环境配置。应用归档不能覆盖该文件， 也不能把授权地址、API 域名或发布目录固化进源码。见 Web 接入与运行态调用。

构建资源与路由

新创建的应用版本使用 SDK 7，在每个精确应用版本独立的 HTTPS origin 根路径运行。Vite 使用默认根路径，或在 vite.config.ts 中显式设置：

export default defineConfig({
  base: "/",
  // 其他 Vite 配置
});

标准构建动作使用 pnpm run build。JavaScript、CSS 和公共资源可以引用根路径 /assets/...，无需拼接发布目录。平台仍保存不可变应用版本，并通过 Bundle 安装或升级交付；根路径托管没有取消版本、安装和回滚。

新建 SPA 模板默认使用 BrowserRouter，无需配置版本目录 basename；平台站点为前端路由提供根 index.html 回退。 开发者可以改用 HashRouter，对外页面链接随之使用 /#/...。安装后应通过实际 accessUrl 验证首页，并直接刷新一个深层路由，确认业务页面正常。 还应验证 普通 href 页面直达，包括未登录时授权后返回同一页面。只检查 index.html 和静态资源返回 200 不足以完成验证。

已有部署继续使用原配置和入口。历史 SDK 6 归档首次安装到新环境前，必须升级 SDK、重新构建并创建新应用版本；不能把旧归档直接搬到根路径，也不增加应用实体的托管模式字段。

当前入口与历史类型迁移的完整规则见 入口类型与应用清单。

把专属项目与 Bundle 内的平台应用一对一绑定：

baijimu platform-app create \
  --workspace-id <workspaceId> \
  --bundle-id <bundleId> \
  --project-id <projectId> \
  --platform-app-id <platformAppId> \
  --name <name>

提交项目文件后，环境托管应用按项目与版本创建：

baijimu platform-app version create <platformAppId> \
  --workspace-id <workspaceId> \
  --project-id <projectId> \
  --bundle-id <bundleId> \
  --version <semanticVersion>

CLI 等待构建完成后才创建不可变应用版本。版本与 package.json 不一致、已有版本指向不同提交或构建失败都会终止版本创建，不会生成可安装的平台应用版本。普通外链等非环境托管配置在该命令上另加 --git-commit-id <40-character-commit-id>；这不意味着历史可信外部应用仍可启动或取得平台 token。

平台应用服务校验显式传入的项目 ID 必须属于同一工作区且类型为 PLATFORM_APPLICATION，并要求它与平台应用主记录中的 sourceProjectId 一致，再从项目版本绑定的不可变提交读取配置文件（非环境托管配置使用显式提交）。每个平台应用使用一对一绑定的专属项目；平台应用不能在创建或首次采用来源项目后改绑。CLI 0.15.0 起不再接收 methodDefinitionsJson，也不需要 @file 把 JSON 作为命令参数传输。@file 仍可用于其他明确声明接受“JSON 或 @文件”的命令，但不是平台应用版本内容协议。创建成功只会生成新的不可变版本，不会修改已有版本。

迁移历史外部应用

当前 App Gateway 拒绝 TRUSTED_EXTERNAL_APP 启动和平台授权。即使定义或版本创建成功，也不能据此判断应用可用。 历史 STATIC_SPA 站点没有同源配置入口，并不表示平台缺少环境托管能力。迁移目标是让平台托管新应用版本， 不需要为旧站点补配置入口；旧站点地址也不会自动成为新版本的入口。 迁移必须完成整个交付链：

1. 将前端源码放入该应用专属的 PLATFORM_APPLICATION 项目；尚未绑定项目的历史应用先按当前 CLI 的 platform-app 帮助完成项目绑定。
2. 把入口改为 ENVIRONMENT_HOSTED_APP 和 /index.html，移除外部地址与 {installId} 模板；保留业务需要的方法、配置及 Bundle 依赖声明。
3. 升级标准 SDK，改为同源配置初始化；删除自实现的 PKCE、token 存储和手工部署地址，保证相对资源路径和 SPA 路由可迁移。
4. 设置新的项目版本并提交主线，执行上述版本创建命令；创建时等待平台构建成功，不传 artifactId 或 --git-commit-id。
5. 用新的 Bundle 版本锁定平台应用版本，升级目标安装，并从实际入口验证授权和业务能力。

只创建前端版本、只改入口类型或只升级 SDK 都不能替代完整迁移。原外部站点若继续独立运营，应使用自己的后台授权； 工作区中不需要平台能力的普通链接可以使用 EXTERNAL_URL。

纳入 Bundle 并安装

应用版本创建后，在 Bundle 项目的本地 Git 工作树选择目录中的应用和精确版本：

baijimu bundle manifest catalog <bundle> platform-application --workspace-id <workspaceId>
baijimu bundle manifest include <bundle> platform-application --workspace-id <workspaceId> \
  --file baijimu.bundle.json --name <exactApplicationName> --version <applicationVersion>

CLI 自动取得 Owner 返回的 platformAppId，写入作者清单的 definition.platformApplications 并在线预检。 重名时使用目录返回的 --object-id。审查并提交 Git 后再创建 Bundle 版本，不能根据应用名称手工构造另一种资源身份。

创建 Bundle 版本后，通过 Bundle 安装或升级操作物化平台应用。不要绕过 Bundle 另造一条安装记录来模拟产品交付。

安装或升级前必须先预览。核对依赖计划与工作区当前安装版本；历史依赖范围可能排除已升级的基础套件，导致计划选择旧版。 遇到这种情况，先验证业务能力与当前依赖的兼容性，再创建修正依赖声明的新 Bundle 版本，不要直接接受非预期降级。

预览还会汇总平台应用调用的、由其他依赖 Bundle 提供的精确 Module 方法；清单非空时，Manager 显示确认窗口，CLI 要求显式传入 --confirm-runtime-method-access。客户端回传的是预览得到的结构化清单，后端会重新解析并 精确比较，不接受布尔值代替授权，也不接受客户端追加 service、方法或通配符。同一 Bundle 内部方法不重复提示，但安装器仍会为所有声明方法维护安装态调用身份。

验证清单

安装或升级后至少确认：

1. 平台应用版本已经创建且内容不可变。
2. 版本记录的 sourceProjectId 和 sourceGitCommitId 与该项目制品版本的提交一致。
3. Bundle 版本内容引用的是同一个平台应用版本。
4. 工作区 Bundle 资源台账记录了平台应用安装。
5. 平台应用安装记录的 installId 保持稳定，版本已经更新。
6. accessUrl 指向当前环境托管的实际版本入口，已追加真实 installId，且不包含 token。
7. 根路径中的 HTML、JavaScript、CSS 和公共资源都返回 200；直接刷新 SPA 深层路由仍显示正确页面。
8. 同源环境配置可读取，配置 contractVersion 为 2.0.0，applicationOrigin 与当前页面一致且不含 releasePath；打开入口会校验工作区成员和已启用的精确 Bundle 安装，再进入 PKCE 授权链路。
9. 回跳只携带一次性 code，并能成功兑换 token。
10. 已声明能力可调用，未声明能力被拒绝。
11. 分享 Manager 的 /bundle-app/{bundleId}/{platformAppId} 入口时，未安装工作区会提示安装整个 Bundle，安装后返回并打开应用。
12. 跨 Bundle 方法清单与预览一致并已确认；取消确认或篡改清单时安装被拒绝。