直接实现插件协议

协议状态（2026-10-21）：资源凭据领取与生命周期通知是已确认、尚未实现和定版的目标设计。插件在 AFTER_RESOURCES 按安装与资源主动领取自己的入口和凭据，回调不携带秘密；配置变化仍走生命周期通知，业务请求不解析引用。Backend 保留插件身份关联，轮换只撤销自己的旧凭据；ACS 不改，不做多插件协调。下文版本化示例保留用于现有协议维护，不能把新 API 字段发送给旧接收端。

本页介绍由独立插件服务直接实现完整协议的方式。也可采用 独立 Adapter Hosted Service 分担公共协议；业务后端仍负责实例归属、事务、幂等和执行顺序。采用 Adapter 时，以下协议职责由 Adapter 实现，业务后端遵循其业务处理合同；不能仅删除协议代码而不建立已验证的替代入口。

插件拥有外部业务操作逻辑；平台负责认证、安装编排、授权投影与输出校验。 Rust 插件使用 crates.io 的公开协议库：

[dependencies]
baijimu-bundle-plugin = "=12.0.0"

从 baijimu_bundle_plugin::bundle_plugin 导入 BundlePluginLifecycleRequest、 BundlePluginLifecycleResponse、BundlePluginReferenceRequest 和 BundlePluginReferenceResponse。 协议版本与选择规则只在权威规范维护。 受管插件握手使用 baijimu_bundle_plugin::enrollment 的交换、确认及 caller 授权类型；按已登记协议解码，不在业务载荷中补入旧版本字段。

按首次接入流程与验收实现启动流程： 连接数据库、启动 listener、执行后台握手、持久化双向凭据并调度轮换。受保护调用验证当前有效凭据。 协议库提供类型和校验，插件程序负责 HTTP 调用、持久化及轮换调度。

执行与认证

插件运行在 Hosted Service 时，先按 业务、管理与插件生命周期入口 声明执行 Endpoint，读取平台注入的命名端口变量并实现 listener。推荐使用独立的 lifecycle 入口； 部署启动时从正式端点元数据读取真实 HTTPS baseUrl，与已实现的 POST 路径组成握手执行地址； 部署配置交付一次性授权，插件在握手时提交执行地址。 服务端监听端口、人工管理入口和 bundleExecution.executeUrl 不能互相代用；多 Endpoint 不会自动完成插件登记。

提供 JSON POST Endpoint，在 bundleExecution 中登记 HTTPS 地址和支持的资源阶段。 按首次握手与凭据轮换 完成受管接入。验证平台访问插件的独立凭据，再按协议反序列化请求并调用 SDK 校验。字段开放与拒绝策略遵循权威规范，已知字段和授权校验不能省略。 按 operation.operationType 与 stage 执行业务逻辑；不能把仅识别阶段当成支持全部操作。 resources 中的业务属性和逻辑引用只包含当前授权范围，不能依赖额外注入的字段。 完整示例见生命周期与引用协议。

外部状态与恢复

保存外部实例与完整 installation、资源 Locator、插件身份的关联，校验已传入实例的归属。 Runtime 拥有 operation.operationId 及阶段执行记录；插件根据业务系统真实结果处理同一次操作重试。 这不要求每个平台业务组件建立一套插件安装表。

生命周期调用执行必要变更；网络中断后，平台以相同 operationId + stage 重试，插件返回对应业务结果和属性。请求与响应不再包含 intent。 超时不代表没有执行；无法证明结果时返回 UNKNOWN，不得伪造成功或直接重建实例。 DETACH 解除本次安装的关联，业务资源清理受所有权约束。 卸载清理使用生命周期身份校验归属，不能通过放宽引用访问授权来取得已撤销的凭据。

生命周期更新与业务调用

在安装、升级或配置的生命周期中解析引用，按生命周期更新访问凭据校验、持久化并切换受保护运行配置。 普通业务调用、业务重试与进程重启读取已经生效的本地配置；重绑、轮换、撤销和过期的责任及失败语义统一遵循该规范。 不得跟随 HTTP 重定向转发凭据。Actor assertion 属于Runtime 用户委托，不能持久化。

处理空引用与部分绑定

先调用 SDK 的 request.validate_authorization(&binding) 校验身份、字段和资源授权， 再处理业务数据。遍历每个获准资源本次实际收到的 references，不要遍历 credentialProperties 并要求每个属性都有值。合法的 references: {} 允许安装初始化和配置确认正常完成。

处理顺序如下；事务、业务实例和输出的具体实现由插件自己的业务合同决定：

认证并校验完整生命周期请求与资源授权
  -> BEFORE_RESOURCES：按完整安装身份幂等初始化或更新自己的业务实例
  -> Runtime 提交资源及获准业务属性
  -> AFTER_RESOURCES：取得本次每个投影资源的完整获准 references
  -> 已绑定项按登记协议取得调用材料；真实错误明确失败
  -> 原子保存该资源的新配置，删除本次已清空的旧目标与本地访问配置
  -> 回显安装、操作、阶段和执行顺序，确认本阶段实际结果

空配置同样需要保存和确认。它不是卸载，也不能用“没有新引用所以直接返回”保留此前的目标。 部分绑定只启用具备所需配置的功能；业务入口检查自身需要的属性，未绑定时明确失败。 业务调用和重试只读已生效的本地配置，不临时解析引用或恢复已清空的绑定。

可下载生命周期引用状态样例，与 权威请求示例一起验证安装、升级、 绑定、换绑、清空、再绑定和重复通知。文档仓库的公开 SDK 测试消费同一份状态样例，验证请求和响应授权； 真实 HTTP、数据库事务、凭据处理及业务效果仍须执行引用生命周期验收。

返回结果

使用完整 CModel envelope。成功 data 回显请求的协议、插件、安装、操作、阶段和执行顺序，并返回 outcome 与 按资源 Locator 组织的 resources。仅 APPLIED 或 VERIFIED 可以返回获授权业务属性；其他结果不回写资源。 不得覆盖引用属性、用户自有配置或 Runtime 安装状态。空输出使用空对象。

请求非法、鉴权失败或执行错误使用标准非零 errorCode，公开错误详情不带 Token、上游原文或完整配置。 日志只记录必要关联身份与结果。没有实现的阶段不登记；已经登记的操作不能静默成功。

插件自有业务凭据

插件可以为自己拥有的业务实例签发服务 Token，并通过生命周期 resources 输出交给 Runtime。 例如 serviceAccessToken 可以是声明了 isSensitive: true 的字符串 Data 属性，由插件的 writeProperties 明确授权；需要在后续生命周期请求读取时，再显式授权 readProperties。 它不应加入 credentialProperties，后者只授权平台引用解析。

这类 Token 由业务后端负责签发、校验、轮换和撤销，按完整安装身份与业务实例隔离。 它不能复用 Hosted Service 共享管理 Token、平台调用插件的凭据、插件调用平台的凭据，或引用解析返回的 Token。 Runtime 校验当前资源、属性定义、写入授权和响应关联，只接受 APPLIED 或 VERIFIED 的获准输出； 移除中的资源不接受属性回写。现有生命周期输出合同已支持这一用途，无需另造业务 Token 交付接口。

业务后端应验证重复生命周期调用能恢复同一业务实例及其返回属性。消息插件从同一操作的业务回执返回原租户凭据。系统插件需要模块 Token 时自行调用 ACS，Runtime 不参与签发或凭据清理。 按业务需要安全保存校验材料或用于重试交付的秘密，禁止记录明文 Token、完整请求或响应； 撤销必须以真实业务效果为依据，不能借用 ACS 的平台令牌身份或把平台安装账复制到业务库。

系统插件初始化模块 Token

模块是否需要 Token 由其属性和插件能力决定。system-manage 只有在获准写入 Authorization 或 moduleToken 且当前值缺失时才申请 Token；只配置 workspaceId、serviceBaseUrl 的模块不调用 ACS。

Token 属性需要同时声明 readProperties 和 writeProperties，使插件能够保留已有配置。已有 Token 不因升级或卸载自动替换、撤销；这不是安装账的一部分。ACS 的请求只包含工作区、Module、服务主体及签发审计信息，不包含 Runtime、安装单或阶段。

顺序与恢复

Runtime 提供正整数 executionSequence；同一操作的阶段和重试保持该值。 插件必须把顺序校验与实际业务写入放进同一事务，保留 DETACH 的顺序记录，拒绝迟到的旧操作。 完整规则见失败与重试。