Bundle 安装与资源绑定

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

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

三个阶段

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

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

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

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

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

从独立安装到绑定、换绑、清空和再绑定的正式 CLI 操作见服务引用完整操作示例。

如何表达引用

自包含与三类依赖边界

关系	所有者与验证时机	对独立安装的影响
同包引用（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 校验不能证明业务场景成功；相关交付证据见交付完整性与验收证据。

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

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

具体字段和命令见ServiceReference 声明与绑定。类型定义的编译期导入见Type Definition，它与运行时服务绑定分别管理。

不同资源何时生效

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 当前资源并创建新计划，详见失败重试与回滚。

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