ServiceReference 声明、绑定与运行时交付

声明 Interface 属性，通过模块属性配置绑定目标服务，并由 Runtime 管理访问关系，插件按新协议解析当前引用的访问信息凭据。

Interface 的字段、方法数组和签名规则统一见类型系统：接口与方法；本页说明绑定值与运行时交付。

ServiceReference 用于把调用模块的一个 Interface 属性绑定到同一 Runtime 内的目标服务。这里的“绑定”就是设置模块属性值，不存在需要开发者额外调用的服务授权接口。属性写入成功后，Runtime 会校验来源资源身份、属性值形状、引用归属和授权。绑定记录用户选择，不比对提供方的实际方法、事件、签名或接口实现身份；目标是否满足业务要求由用户或其 AI 保证。插件生命周期只接收无凭据的引用描述，生命周期中领取并持久化凭据，业务调用复用已生效的本地配置，完整方式见生命周期与引用协议。

模块属性是唯一的绑定源事实

把 Interface 属性设置为 {"@type":"ServiceReference","serviceId":"完整 businessId"} 是在显式配置对应引用。绑定生效时校验引用身份、值形状、归属和权限，不检查目标服务是否实现声明的方法；安装 Bundle 只交付定义，不自动安装提供方或授予跨资源调用权限。详见安装与资源绑定。

需要用稳定业务键绑定多个同接口服务时，使用 InterfaceMap 属性和 ServiceReferenceMap 值；不要把多个目标塞进单值 ServiceReference。完整声明、更新和引用描述示例见 InterfaceMap 与 ServiceReferenceMap。

声明 Interface 属性

调用方模块在 module.json 的 propertyDefinition 中声明 Interface 类型属性。接口中的方法定义是调用方编译期的期望契约。用户或其 AI 可通过目标 Runtime 服务目录核对当前方法和 paramDefinitions；平台不将这项比对作为绑定生效或单包升级的前置检查。

{
  "propertyDefinition": [
    {
      "name": "xiaoxiangService",
      "type": {
        "@type": "Interface",
        "name": "XiaoxiangService",
        "methods": [
          {
            "name": "listManagedShops",
            "async": false,
            "returnType": {
              "@type": "JsonSchema",
              "schema": {
                "type": "object"
              }
            },
            "paramDefinitions": [
              {
                "name": "params",
                "type": {
                  "@type": "JsonSchema",
                  "schema": {
                    "type": "object"
                  }
                }
              }
            ]
          }
        ],
        "events": []
      },
      "required": true
    }
  ]
}

引用属性只声明接口契约，必须省略 defaultValue。Interface、InterfaceMap、InterfaceList 和接口 RefType 都不允许默认值，包括 null、空对象、空数组或编码后的 JSON 字符串。未配置时保持未绑定；required: true 不要求安装前已经绑定，也不会选择目标或自动授权。移除默认值只表示目标必须由配置者显式选择，不能推导成“安装时必须提供引用”。安装后使用下面的正式属性配置命令绑定目标。普通 JsonSchema 数据属性仍可声明符合其 Schema 的默认值。

credentialProperties 只声明插件获准访问的引用属性名，不表示这些属性已有值或必须全部绑定。空引用和部分绑定的生命周期处理遵循未绑定引用与失败策略。

逻辑属性值固定使用：

{
  "@type": "ServiceReference",
  "serviceId": "<targetBusinessId>"
}

serviceId 必须是目标服务完整的 businessId，不是模块名、Bundle 名、方法名、Hosted Backend 地址或调用方自行拼接的 URL。

安装后手动绑定或修改

CLI 0.96.0 起，正式模块属性命令支持指定 Application Runtime；省略目标时仍使用工作区默认 Runtime。先把需要部分更新的属性保存为 properties.json；文件只包含属性对象，不包含工作区、调用服务或接口 URL：

{
  "xiaoxiangService": {
    "@type": "ServiceReference",
    "serviceId": "<targetBusinessId>"
  }
}

执行正式命令：

baijimu runtime app properties update \
  <callerBusinessId> \
  --workspace-id <workspaceId> \
  --application-runtime-id <applicationRuntimeId> \
  --properties @properties.json

<workspaceId> 决定目标工作区，<applicationRuntimeId> 指定该工作区内的目标 Runtime，<callerBusinessId> 是调用模块安装后的完整服务标识。
省略 --application-runtime-id 才选择默认 Runtime。指定目标后出现权限、参数或服务错误会直接失败，不转向默认 Runtime。
--properties 接受内联 JSON 对象或 @文件；这是部分更新，未出现的模块属性保持不变。
属性名必须已经存在于当前不可变模块版本的 propertyDefinition 中。该命令只改属性值，不修改属性定义。
目标 serviceId 必须在同一 Runtime 中可解析；解析或访问关系生成失败时，本次配置更新失败。
CLI 负责平台接口路径、工作区凭据和请求结构。开发者不得改用 baijimu api 拼接内部路径。

设置属性就是绑定；这也是手动修改绑定的正式操作，不需要另一套“ServiceReference 授权”命令或接口。

换绑与清空

换绑时，向同一属性提交新目标的完整 ServiceReference，命令和参数结构与首次绑定相同。 CLI 的属性更新是部分更新：省略一个属性表示保持原值，不表示清空。

清空单值引用时，提交显式 null：

{
  "xiaoxiangService": null
}

将上述对象保存为 clear-reference.json，执行：

baijimu runtime app properties update \
  <callerBusinessId> \
  --workspace-id <workspaceId> \
  --application-runtime-id <applicationRuntimeId> \
  --properties @clear-reference.json

CLI 将这里的 null 编码为属性更新的 Data(null)，表示清空当前绑定；它不是给属性定义增加默认值，也不是把空字符串当作目标 serviceId。这对 required: true 的单值引用同样适用。 Map 的显式空集合使用 {"@type":"ServiceReferenceMap","valueMap":{}}，完整规则见 InterfaceMap。

成功清空后，调用方资源和插件业务实例仍存在。生命周期配置必须去掉该属性的旧目标及本地访问配置，后续依赖它的业务调用明确返回未绑定，不得继续使用旧绑定；再次绑定通过同一正式属性命令完成。命令失败、配置提交后通知失败与成功清空必须分别记录，不能把失败响应当成清空成功。逐步操作和预期结果见服务引用完整操作示例。

Runtime 自动执行的步骤

显式属性更新按当前资源和授权源事实收敛：

调用方与目标资源定义已安装，顺序不限
  -> 写入调用模块的 ServiceReference 属性
  -> Runtime 校验引用身份、属性值形状、归属和配置权限
  -> Runtime 自动生成或更新引用访问关系
  -> 新插件生命周期接收无 token 的 references 描述
  -> 插件在生命周期中按授权属性解析并保存调用地址与凭据
  -> 正常业务调用和重试读取本地配置，经 Runtime 网关调用目标服务

配置更新中的校验失败会让本次配置操作失败；生命周期中的真实引用解析错误必须明确失败，不报告交付成功。配置源提交与后续通知结果分别核对；失败候选不能覆盖插件此前有效的配置，显式清空成功则必须去掉旧绑定。设置属性就是绑定并提交授权意图；不需要另行调用内部授权接口。定义安装不会自动交付外部引用凭据。

运行时交付边界

生命周期回调的 references 保留逻辑 ServiceReference 及其 Map/List 结构，不含地址或密钥。插件在生命周期中按授权属性解析当前引用，保存安装定位和运行配置。响应中的 reference 给出目标关系， access[相对选择器路径] 给出来源模块属性的 Runtime 网关 url 和来源资源 token，单值引用使用 access[""]，校验后持久化并供业务调用复用；变化由后续生命周期更新。HTTP 方法的 position: "property" 映射不参与这条链路。完整请求格式和 xiaoxiangService.listManagedShops(params) 的调用方式见模块服务间调用协议。

引用 token 认证来源资源，不携带最终用户；属性定义、有效绑定和方法合同决定属性调用范围。需要代表当前用户调用时，外部后端另外转发 Runtime 在本次业务请求中注入的短期 Actor assertion；该值不是逻辑引用字段，也不通过生命周期保存。见 Runtime 用户委托。

调用模块不得：

在独立后端自行把逻辑 ServiceReference 转换为地址、推导凭据或自行拼接 Runtime 网关地址。
绕过 Runtime 网关，直接调用目标 Hosted Backend 的 Controller 或部署地址。
把生命周期请求中的操作 userId 保存成后续业务调用的固定最终用户身份。
把请求级 Actor assertion 保存到引用配置、数据库、缓存、队列或后台任务。
输出、记录或依赖 token 的内部格式。

作者输入与安装依赖

当前模块创建命令不接收 --module-dependencies 或 --dependency-definition。模块属性与接口通过项目源码维护，运行时目标通过属性设置接口配置；不要把历史依赖输入迁回 Bundle 清单。

验证清单

同一 Runtime 的资源 Owner 返回调用方与目标资源；安装记录不代替当前资源事实。
调用模块当前版本声明了目标 Interface 属性。
使用目标服务完整 businessId；由用户或其 AI 确认目标方法满足业务需要。
使用 baijimu runtime app properties update 写入逻辑 ServiceReference，确认命令成功。
检查插件收到当前无凭据引用描述；在生命周期中解析该属性的当前引用，验证授权与返回结构并保存运行配置，不输出 token。
调用模块后端使用生命周期保存的引用访问配置，通过 Runtime 网关调用目标方法。
换绑后使用新配置；清空后对应调用明确失败，再绑定后恢复。生命周期按当前配置更新本地访问材料，业务调用不临时解析或领取凭据。

不得为了验证而拼接内部网关地址、复用非公开凭据或直连目标 Hosted Backend。