模块服务间调用协议

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

模块 A 的独立后端需要调用同一 Runtime 中模块 B 的公开方法时，在模块 A 声明 Interface 属性， 把该属性设置为指向 B 的 ServiceReference。Runtime 校验来源资源身份与属性绑定，并交付来源资源 token。 插件按生命周期与引用协议取得当前授权引用， 后端通过 Runtime 网关调用 B。

完整调用链

分别安装调用方与提供方的资源定义（安装顺序不限）
  -> 模块 A 声明 Interface 属性
  -> 模块 A 的属性设置为 ServiceReference(B)
  -> Runtime 校验绑定并收敛访问关系
  -> 插件在生命周期中按授权 propertyKey 解析引用
  -> 校验并保存安装定位、目标选择关系、URL 与 Token
  -> 后端正常调用及重试读取本地配置，通过 Runtime 网关调用 B
  -> Runtime 校验来源服务、目标服务和允许的方法
  -> 模块 B 执行方法并返回统一响应

资源引用不构成 Bundle 安装依赖。设置属性时校验目标 Owner 的当前资源、接口和授权； 未绑定、目标缺失或授权失败会明确报错。显式设置属性就是绑定，没有另一套需要开发者调用的授权接口。 声明与 CLI 示例见ServiceReference 声明、绑定与运行时交付。

本次解析的访问信息

响应的 data.reference 保留当前目标选择；data.access 按该属性下的相对选择器路径索引。单值引用使用空字符串键：

{
  "reference": {"@type": "ServiceReference", "serviceId": "<targetBusinessId>"},
  "access": {
    "": {
      "url": "https://runtime.example/service/<sourceBusinessId>/xiaoxiangService",
      "token": "<sourceResourceToken>"
    }
  }
}

url 是来源模块属性在 Runtime 网关中的访问地址，形态为 {apiGatewayUrl}/{sourceBusinessId}/{propertyKey}/{selectors...}。 平台沿属性定义与有效绑定解析目标服务，目标 serviceId 仅表达绑定选择，不作为 access 的索引或 URL 首段。 token 认证来源资源；属性定义、有效绑定、方法合同和当前用户权限决定实际允许的调用范围。

access 键采用相对 JSON Pointer：每个选择器先把 ~ 转为 ~0、/ 转为 ~1，再以 / 连接。 Map 按完整键选择，List 下标从零开始，非零下标不含前导零。同一目标出现在多个属性路径时保留各路径，不能按目标去重； 同一来源资源的各叶子共用来源 token。URL 使用平台返回的完整值，不把 access 键直接当成 URL 编码结果。 reference 中不含地址或 token。机器可读示例见属性访问响应数据。

HTTP 模块不能通过 position: "property" 接收引用。后端把生命周期解析的凭据保存到受保护的运行配置， 后续生命周期负责更新或清理；不得写入日志、源码、Bundle、普通业务载荷或前端状态。

调用具体方法

例如代码中的逻辑调用是：

xiaoxiangService.listManagedShops(params)

外部后端使用生命周期准备并保存的引用访问配置，把接口方法转换为以下 HTTP 请求：

POST {access.url}/listManagedShops
Authorization: Bearer {access.token}
X-Runtime-Actor-Assertion: {currentRequest.actorAssertion}
Content-Type: application/json

X-Runtime-Actor-Assertion 只在当前入站 Runtime 调用已经建立用户身份时存在。调用方必须把它作为不透明、 请求级值转发；不得从生命周期 userId、业务参数或环境默认用户生成替代值。不需要用户身份的调用可以不带 该 Header。完整的单跳、链式轮换、异步边界和日志要求见 Runtime 用户委托。

请求体顶层字段与目标方法当前 paramDefinitions 一一对应。目标方法声明一个名为 params 的参数时：

{
  "params": {
    "status": "ACTIVE"
  }
}

access 选择完成后，把该条目的 url 和 token 交给调用代码。平台当前不生成语言级代理对象；xiaoxiangService.listManagedShops(params) 表示上面的标准 HTTP 调用， 不是另一个未发布的 SDK。调用方应从 Runtime 回读目标方法定义，不能自行复制一份可能漂移的方法签名。 响应按 CModel 错误模型 处理。

调用方不得自行把逻辑 ServiceReference 转换成地址或凭据，不直接请求目标 Hosted Backend 的 Controller 或部署地址。

上下文、权限和重试

引用 token 认证来源资源，不自动代表最终用户，也不单独授予任意目标方法的访问权。需要用户权限时， 调用方还必须转发当前请求由 Runtime 注入的 Actor assertion：

• Runtime、工作区和来源资源身份由引用调用链确定，不从普通业务参数中接受同名字段。
• 生命周期请求中的操作 userId 不能保存后用于业务调用。
• 普通请求体或自定义头中的用户编号不是平台已验证的用户上下文。
• 目标方法需要最终用户权限而可信用户上下文缺失时，必须拒绝，不能回退到安装用户或固定管理员。
• Actor assertion 不能持久化或用于请求结束后的重试；服务链跨到新目标后，由 Runtime 为该目标后端自动 轮换下一跳 assertion，外部服务不签名。

调用方对 HTTP 200 响应检查 CModel errorCode；非 200、连接中断或超时时属于传输失败，执行结果可能未知。只有目标方法 本身声明幂等，或目标实现了该方法规定的幂等键去重语义且请求满足要求时，才可按声明的策略重试。 声明位置、未知结果查询和默认处理见方法行为与重试契约。旧 token 返回未授权时不循环重试， 本次操作应失败，并检查本地配置及授权状态；由生命周期处理所需更新，不能在业务请求中刷新 Token 或复用已撤销凭据。

可执行的端到端步骤

1. 安装双方资源定义，再显式绑定目标；核对 Owner 当前资源、接口和授权结果。
2. 在模块 A 当前版本中声明 xiaoxiangService 的 Interface 属性，创建该模块的不可变版本，纳入本包 Bundle 后发布并安装或升级到明确的目标 Runtime。
3. 回读模块 B 的完整 businessId、listManagedShops 方法及 paramDefinitions。
4. 使用正式的 baijimu runtime app properties update 命令，把模块 A 的 xiaoxiangService 设置为 指向模块 B 的 ServiceReference；完整参数见 ServiceReference 页面，不要自行拼接平台接口路径。
5. 插件按新协议接收并校验安装定位，在生命周期中按授权属性解析、校验并持久化地址和调用凭据，不要输出 token。
6. 由模块 A 后端按上述 JSON POST 请求调用 listManagedShops；当前请求存在 Actor Header 时同时原样 转发，确认 HTTP 200 并检查 CModel errorCode。
7. 修改或清除属性后，确认配置生命周期更新或停用本地调用配置，撤销后的引用不能继续调用。

如果第 5 步领取失败，应检查安装环境、活动安装、插件身份、绑定协议、授权属性和当前目标关系； 不能用硬编码地址或非公开凭据绕过引用授权。

业务设备选择与执行授权

应用保存“成员选择哪些设备”时，应把业务选择与设备服务的方法级授权分开。选择页读取权限 Owner 的实时设备和授权目录，在当前成员权限范围内展示设备；组件安装或在线状态不能代替设备权限，也不能作为保存业务关联的必要条件。

业务选择只保存成员与设备的稳定标识，不复制权限、设备名称、在线或安装状态，不因关联设备而创建或扩大方法授权。管理他人的选择仍需要管理权限，后端通过只读 ServiceReference 转发本次 Runtime Actor 委托，由权限 Owner 验证当前调用者。

真正执行本地方法时，直接调用设备 Owner 的标准执行入口，由它检查当前用户的方法权限、设备连接和组件安装，并返回实际错误。业务选择不能跳过这个安全边界；没有安装组件的设备可以关联，调用不会因此获得不存在的能力。