开发指南Bundle 开发平台应用开发
入口类型与应用清单
正确选择平台内路由、普通外链或可信外部应用，并定义可由 Bundle 引用的版本清单。
入口类型决定应用在哪里运行、是否携带安装态，以及是否需要平台应用授权。不要仅根据 URL 是否为外部地址选择类型。
三种入口类型
entryType | 适用场景 | 入口要求 | 授权方式 |
|---|---|---|---|
PLATFORM_ROUTE | 平台管理端已经内置的页面 | 以 / 开头的平台相对路径 | 继承平台管理端登录态，不跳转外部应用 PKCE 授权页 |
EXTERNAL_URL | 不调用平台能力的普通链接 | http:// 或 https:// 地址，不含安装态或运行态占位符 | 不签发平台应用 token |
TRUSTED_EXTERNAL_APP | 独立部署、需要平台安装态或平台 API 权限的 Web 应用 | http:// 或 https:// 地址，并包含 {installId} | 跳转平台网页授权页，使用 PKCE 兑换 token |
如果一个普通外链后来需要调用平台 API，应把入口改为 TRUSTED_EXTERNAL_APP 并补齐能力声明，不能在 EXTERNAL_URL 上私自传递平台登录 token。
如果还不能确定平台应用入口是否需要接入 App Gateway，先阅读 App Gateway 接入与配置。
入口模板
可信外部应用的入口只传递安装标识：
https://app.example.com/?installId={installId}不要在入口模板中传递：
appClientToken- 平台用户 token
workspaceId或userId- 内部服务地址
- 数据库或第三方系统密钥
平台安装后会把 {installId} 替换成真实安装记录。应用使用该标识启动授权，而不是根据 URL 中的其他字段自行信任用户身份。
打开方式
openMode 用于声明入口的展示位置：
CURRENT：在当前页面打开。NEW_TAB：在浏览器新标签页打开。WORKSPACE_TAB：在工作区标签中承载。
跨域应用在 WORKSPACE_TAB 中通常由 iframe 承载。应用需要同时验证自身的 frame、安全头、Cookie SameSite 和跨域策略是否允许这种运行方式。
版本清单
平台应用版本至少要把以下内容作为同一个不可变契约发布：
entryUrlTemplateentryTypeopenModemethodDefinitionsJsonconfigSchemaJsonmanifestJson- 可选的卡片、后端模块和工作流定义
安装记录引用具体版本。修改入口、权限或配置结构后，应发布新版本并升级安装，不能只修改已经发布版本的预期行为。