---
docStatus: current
---

# Bundle 安装与资源绑定

区分资源定义安装、运行时绑定生效和业务调用，独立管理资源引用。

Bundle 是资源的版本化交付单元。安装把所选 Bundle 的资源定义及精确版本交付到 Runtime；资源之间的协作通过各自定义中的引用或运行时绑定配置表达。

## 三个阶段

| 阶段   | 做什么                                       | 成功表示什么                      |
| ---- | ----------------------------------------- | --------------------------- |
| 安装   | 交付已验证的精确版本，保留请求权限、协议解码、归属与并发保护            | 资源定义已经交付；不表示外部引用已绑定或业务已经可运行 |
| 绑定生效 | 提交资源配置，校验引用身份、值形状、归属和权限，完成执行交付；不比较提供方实际方法 | 所选配置已经交付；接口兼容性由用户或其 AI 保证   |
| 调用   | 使用已生效的配置或执行快照，并进行权限与撤销检查                  | 本次具体业务操作成功                  |

Bundle 不声明其他 Bundle 的安装依赖。外部提供方尚未安装，不阻止本 Bundle 的定义安装；两个 Bundle 相互引用也不要求安装顺序。缺失的目标会在绑定或调用对应功能时返回明确错误。

## 未绑定引用是合法安装状态

Interface 引用没有 `defaultValue`、声明 `required: true`，或被插件列入 `credentialProperties`，
均不要求安装前已经选择提供方。定义可以先安装，之后再配置引用；部分引用已绑定时，其他未绑定引用也不能阻塞安装。
普通业务数据仍按各自属性合同校验，这条规则不免除身份、权限、格式和实际资源归属校验。

生命周期插件同样遵守这一边界。`failurePolicy: "FAIL_FAST"` 表示真实插件错误阻止操作继续，
不把合法未绑定状态变成错误。插件应初始化自己的业务实例、接受当前获准引用配置，并在实际业务调用
需要某个未绑定引用时明确拒绝该功能。完整处理规则见[未绑定引用与失败策略](/development/lifecycle-plugin-development/reference-protocol/#未绑定引用与失败策略)。

从独立安装到绑定、换绑、清空和再绑定的正式 CLI 操作见
[服务引用完整操作示例](/development/bundle-development/module-development/reference-binding-walkthrough/)。

## 如何表达引用

### 自包含与三类依赖边界

| 关系                          | 所有者与验证时机                                      | 对独立安装的影响                         |
| --------------------------- | --------------------------------------------- | -------------------------------- |
| 同包引用（internal reference）    | 作者选择本包资源的精确版本；资源 Owner 在创建版本时校验归属、方法与合同       | 必须随本包闭合，不要求安装其他 Bundle           |
| 运行期绑定（optional binding）     | 本包 Module 声明 Interface；配置者选择提供方，绑定和调用时校验目标及权限 | 提供方缺失或尚未绑定不阻止定义安装，使用相关功能时明确失败    |
| 平台能力要求（platform dependency） | 目标平台登记资源 Owner、内容 Schema 和执行协议，由平台消费合同并执行     | 不支持的类型或协议明确失败，不能跳过资源或改装其他 Bundle |

这里的 optional 表示相对于定义安装可延后配置，不保证该集成功能在未绑定时仍可用。
Type Definition 的精确导入另外属于编译期依赖：Module 创建版本时展开和校验，不参与 Bundle 安装。
Workflow 的直接 Module 引用与属性来源只能来自本包，跨包能力通过本包 Module 的 Interface 属性选择。

例如，飞书 Bundle 可以独立安装；调用飞书 API 仍需合法的飞书应用配置和用户授权。第三方平台的必要配置
应写明为功能前置条件，不能改写成必须先安装另一个业务 Bundle，也不能用默认管理员或隐式补授权代替配置。

发布验收须明确核心业务场景和集成扩展场景，在没有其他业务 Bundle 的 Runtime 中验证独立安装及声明的
核心能力。通用 Schema 校验不能证明业务场景成功；相关交付证据见[交付完整性与验收证据](/development/bundle-development/delivery-verification/)。

引用具体资源时，使用平台返回的完整资源身份；需要冻结版本的定义使用资源的精确版本。由使用方选择提供服务时，通过 Interface 或 InterfaceMap 属性配置 ServiceReference。

资源引用始终保留来源身份。不要用 Bundle 名称、显示名或内部版本记录 ID 猜测资源，也不要通过 Bundle 的安装版本推断某个资源当前存在。当前版本、启用配置和实际归属以资源 Owner 的返回结果为准。

具体字段和命令见[ServiceReference 声明与绑定](/development/bundle-development/module-development/service-reference/)。类型定义的编译期导入见[Type Definition](/development/bundle-development/type-definition-development/)，它与运行时服务绑定分别管理。

## 不同资源何时生效

- Module：先安装方法和属性定义；显式设置引用属性后校验值形状、引用身份与访问权限，不检查目标实际方法、事件、签名或接口实现身份。
- Workflow：直接模块引用及表达式的属性来源必须在 Workflow 所属 Bundle 内，开发和创建版本时拒绝直接引用外部模块或外部模块属性，并完成方法、Interface、表达式与类型检查。安装直接消费已验证的版本，不重复这些语义检查；外部服务通过内部模块属性绑定，未绑定不阻塞定义安装，但相关调用会明确失败。Workflow、Timer、普通事件订阅和设备事件动作均发送原属性路径，由 Gateway 解析当前绑定、鉴权并执行。属性换绑后，消费者无需重新解析外部模块。未绑定、目标缺失或权限拒绝均明确失败，不自动补授权、换凭据或回退 Backend。不需要为此另设 Workflow 启用步骤，业务执行保留既定快照和执行主体。
- Platform Application：先交付应用定义和前端；通过工作区应用的“绑定 / 更新授权”或 CLI `platform-app workspace binding-preview`、`bind` 生效后使用。绑定会确认精确应用版本和方法列表，不在 Bundle 安装时申请授权。
- Timer：安装交付定义、表达式及自身凭据，不要求外部目标存在或属性已配置。沿用现有启停与调度设置，不新增独立绑定步骤。属性配置更新 Timer 自身调用授权，清空属性撤权但不删除自身身份，也不重置调度。执行主体必须保存，首次安装默认安装人，升级、重放和属性配置保留原主体；未绑定时触发明确失败。
- Event Trigger：先安装定义；来源与动作绑定生效后才建立有效订阅。
- Role 与 Permission：定义中的引用不等于已授予权限；实际分配和使用权限时必须满足授权条件。

## 升级、卸载与失败处理

每次 Bundle 操作只应用本次明确选择的资源配置，不触发整个 Runtime 的配置应用或引用校验。同包未选资源和其他 Bundle 的配置保持不变。提供方升级不会自动重绑消费者或扩大授权；提供方卸载后，相关调用按现有撤销规则失败。重新安装同名资源不会自动获得旧凭据的权限。

配置失败时检查对应资源、引用目标、接口和权限，再提交修正后的配置。不要通过重装无关 Bundle、清空安装账或重复执行旧操作来伪造生效。失败后重新读取 Owner 当前资源并创建新计划，详见[失败重试与回滚](/development/bundle-development/recovery/)。

如果安装仅因接口引用未绑定而失败，应定位拒绝它的 Runtime Owner 或生命周期插件并修正阶段校验，
保留原 `FAIL_FAST`。不能据此推断安装必须预绑定，也不应通过预置业务目标、放宽失败策略或反复更换安装参数绕过。