当前生命周期插件协议 v1

当前生产可用的 Hook、请求字段、CModel 响应契约、配置合并和能力限制。

协议 v1 由平台组装 Runtime 和服务上下文，插件管理服务根据注册的 pluginId 解析 executeUrl，校验 Hook，合并配置后调用插件 Endpoint。插件不直接推进 Runtime 或 Bundle 状态。

标准 Hook

Hook	调用时机	典型职责
`BEFORE_DEPLOY`	服务部署到 Runtime 前	创建或查询外部实例，返回需要写入的属性
`AFTER_DEPLOY`	Runtime 部署成功后	把最新运行属性同步到外部系统
`BEFORE_STOP`	Runtime 停止前	停止或暂停外部实例
`BEFORE_DETACH`	服务从当前 Runtime 卸载前	解除当前 Runtime 绑定，不等于删除外部实例
`BEFORE_DELETE`	外部实例删除前	回收或删除外部实例
`ON_CONFIG_UPDATE`	Runtime 服务配置变更时	同步由插件管理的外部配置

hook 是当前字段。stage 只是历史兼容别名；调用一方可以只传其中一个，插件管理服务会对齐两者并以大写 Hook 调用插件。新插件不要为 hook 和 stage 实现两套语义。

插件收到的请求

{
  "pluginId": "tenant-provisioner",
  "hook": "BEFORE_DEPLOY",
  "stage": "BEFORE_DEPLOY",
  "applicationRuntimeId": "runtime-identity",
  "workspaceId": 100,
  "serviceId": "crm-service",
  "userId": 200,
  "properties": {},
  "propertyDefinitions": {},
  "pluginConfig": {}
}

字段	类型	必需	语义
`pluginId`	string	是	当前注册插件的稳定逻辑标识
`hook`	string	与 `stage` 二选一	当前 Hook，新实现优先读取此字段
`stage`	string	与 `hook` 二选一	历史兼容别名，管理服务调用时会与 `hook` 保持一致
`applicationRuntimeId`	string	是	本次调用所属 Runtime 的平台身份
`workspaceId`	integer	否	当前工作区上下文；缺失时不得由插件猜测
`serviceId`	string	是	Runtime 中的服务逻辑标识
`userId`	integer	否	经平台确定的操作用户上下文
`properties`	object	否	当前服务属性，缺省为空对象
`propertyDefinitions`	object	否	当前服务属性定义，缺省为空对象
`pluginConfig`	object	否	注册默认配置与当前绑定配置合并后的结果，缺省为空对象

applicationRuntimeId、workspaceId 和 userId 是业务上下文，不是 Endpoint 访问凭据。插件必须使用自己的服务身份和资源所有权规则保护 Endpoint，不能因为请求体带有这些字段就信任任意公网请求。

配置合并

管理服务对 defaultConfig 和当前调用的 pluginConfig 做顶层对象合并：

先加载注册记录的 defaultConfig。
再用当前 pluginConfig 的同名顶层字段覆盖默认值。
不递归合并嵌套对象。
最终结果必须是 JSON 对象。

因为管理查询会返回 defaultConfig，两处配置都不得保存访问 token、密码、数据库凭据或其他长期敏感值。敏感配置必须由插件服务自己的密钥与配置所有者管理。

固定 CModel 响应

插件 Endpoint 必须返回完整 CModel envelope，不得只返回裸 data：

{
  "errorCode": "0",
  "value": "success",
  "systemCurrentTime": 1786665600000,
  "data": {
    "status": "RUNNING",
    "properties": {
      "tenantId": {
        "@type": "Data",
        "value": "tenant-123"
      }
    }
  }
}

字段	必需	语义
`errorCode`	是	`"0"` 表示成功；其他值表示插件执行失败
`value`	是	成功摘要或可供诊断的失败信息
`systemCurrentTime`	是	插件生成响应时的 Unix epoch 毫秒整数
`data`	成功时是	标准执行结果
`data.status`	是	当前 Hook 执行结果字符串
`data.properties`	是	希望由平台校验并写回的属性对象，没有输出时返回空对象

当前实现会解析插件返回的 externalId，但不会继续把它返回给上游。不要把 externalId 作为 v1 的可见输出契约；需要保留的外部实例引用应通过明确允许写回的 properties 表达。

当前能力限制

协议 v1 当前没有提供：

独立的 operationId 和 idempotencyKey。
按调用持久化的 checkpoint、异步状态查询和执行账。
受约束的警告、结构化错误、建议重试时间和补偿输出。
插件 revision 锁定。
执行时对 protocolVersion 和 requiredInterfaces 的强制校验。

因此，v1 插件必须将每个 Hook 实现为“查询当前状态并收敛到目标”的可重试操作，不能假设平台会保证恰好调用一次。需要长时任务、检查点、回滚或补偿的新产品不应自行扩展 v1 私有字段，应等待或共同完成 Bundle 顶层协议。