主用例说明：宿主调用插件

背景概述

PowerX 宿主为企业提供统一的业务编排与智能体运行平台，插件则承载各类垂直能力。若宿主缺乏对插件调用的标准化治理，常出现路由混乱、鉴权不一致、可观测性不足和故障恢复滞后等问题。本主用例聚焦“宿主调用插件”，梳理从调用路径管理、请求编排、重试熔断到多租户隔离的全链路，确保宿主能够安全、高可用地消费插件服务。

目标与价值

• 统一调用编排：提供标准的调用入口、协议转换与请求路由，降低插件接入成本。
• 租户级安全隔离：根据租户策略精准路由并执行访问控制，避免数据越界。
• 可观测与可恢复：构建调用指标、日志、链路追踪与自动化重试，提升韧性。
• 弹性扩缩容：依据调用压力调度插件实例，实现资源利用最大化。

参与角色

• 宿主编排服务（Core Services）：发起插件调用、负责协议转换与安全校验。
• 租户策略引擎 / IAM 服务：根据租户与用户策略判断授权范围与限流规则。
• 插件网关 / Sidecar：管理插件实例路由、连接池与传输协议。
• 插件实例（Runtime）：接收请求并返回业务处理结果或事件。
• 运维与 SRE 团队：监控调用链路、处理异常并制定恢复策略。

主场景 User Story

作为 PowerX 宿主编排服务，我希望 能够按照租户策略稳定地调用插件实例，从而 向终端用户提供一致、可靠的业务能力体验。

子场景详解

子场景 A：调用入口统一与协议编排

• 角色与触发：宿主接收到来自前端、Agent 或工作流的任务，需要调用插件能力。
• 主要流程：
  1. 宿主根据任务上下文选择目标插件能力并生成调用请求。
  2. 调用请求在 API Gateway / Orchestrator 中统一落地，完成鉴权、限流与参数校验。
  3. 编排服务根据插件声明的协议（gRPC、HTTP、MCP 等）适配序列化与头部信息。
  4. 将请求转交插件网关或 Service Mesh Sidecar，准备路由到具体实例。
• 成功标准：统一入口响应时间 <50ms；协议转换后保持幂等；调用上下文（Trace ID、租户 ID）完整传递。
• 异常与风控：参数校验失败直接阻断；鉴权失败返回 401/403；请求体过大触发拒绝并记录审计。
• 指标建议：入口 QPS、鉴权失败率、协议转换耗时。

子场景 B：多租户策略路由与隔离

• 角色与触发：宿主需根据租户策略决定调用目标实例与资源配额。
• 主要流程：
  1. 调用上下文携带租户 ID、用户角色、业务标签。
  2. 策略引擎校验租户是否授权该插件能力，并获取限流、地域、数据域等策略。
  3. 路由层根据策略匹配相应的插件实例池（同城/跨区、生产/测试）。
  4. 调用过程中注入租户隔离 Header / Token，并记录租户级调用指标。
• 成功标准：未授权租户调用被阻断；租户切换时路由正确；限流策略实时生效。
• 异常与风控：策略缓存失效时回退至权威配置；当租户实例不可用时触发降级（备用实例、Mock 响应）。
• 指标建议：租户授权命中率、限流触发次数、降级率。

子场景 C：调用链路可观测与重试熔断

• 角色与触发：宿主需要在调用失败或性能下降时自动恢复并告警。
• 主要流程：
  1. 调用请求通过分布式追踪记录 Trace/Span，并附带关键指标（延迟、状态码、payload 大小）。
  2. 若返回超时或 5xx，宿主根据策略执行重试（指数退避、最大次数控制）。
  3. 重试失败时触发熔断，将请求导向降级逻辑或返回友好提示。
  4. 异常事件同步到监控与告警系统，SRE 可快速定位问题实例。
• 成功标准：追踪日志完整；重试命中率可观测；熔断后自动恢复需要健康探针验证。
• 异常与风控：防止雪崩—重试策略需设置抖动；熔断与降级需避免影响其他租户；监控系统需隔离敏感数据。
• 指标建议：平均响应时间、重试成功率、熔断次数、MTTR。

子场景 D：异步任务与批量调用编排

• 角色与触发：宿主需要批量处理或异步执行插件任务。
• 主要流程：
  1. 宿主将批量任务拆分为消息或事件，投递至任务队列 / EventBus。
  2. 插件订阅任务并异步返回处理结果或回调。
  3. 宿主聚合结果并更新业务状态（如工作流节点完成、生成报表）。
  4. 对长耗时任务提供状态查询与取消接口。
• 成功标准：任务投递可靠（至少一次或恰好一次）；结果聚合成功；长任务状态可追踪。
• 异常与风控：消息积压时触发扩容；回调失败时支持补偿；防止重复消费造成副作用。
• 指标建议：任务吞吐量、积压深度、回调成功率。

功能边界 & 非目标场景

• 不覆盖插件能力注册、授权审批流程，相关内容见“插件能力注册与暴露”主用例。
• 不讨论插件内部逻辑与调试流程，可参考“插件开发与调试”主用例。
• 宿主对外提供的公共 API 网关治理另属“系统监控与告警”，此处仅聚焦宿主到插件的调用闭环。
• 不包含插件主动调用宿主的回调场景，请参阅“插件调用宿主”主用例。

依赖与接口

• 宿主编排引擎 API：统一生成调用上下文、序列化与重试策略配置。
• 租户策略 / IAM 服务：校验授权、返回租户级限流与路由策略。
• Service Mesh / 插件网关：维护插件实例注册、健康检查、流量调度。
• 监控与日志平台：采集链路指标、触发告警、支持追踪查询。
• 任务队列 / EventBus（针对异步场景）：承担批量任务与回调消息分发。

验收要点

1. 宿主调用插件的统一入口具备鉴权、限流、协议转换能力，并支持至少 gRPC 与 HTTP。
2. 租户级策略生效可验证：未授权租户被拦截，限流与地域策略可配置并即时生效。
3. 调用链路具备可观测性：Trace、日志、指标三位一体，并能快速定位失败实例。
4. 自动化恢复能力完善：重试、熔断、降级策略可配置，异常后能通知运维并支持快速恢复。
5. 异步批量场景可执行：任务分发、状态回调与结果汇总流程完整，并支持超时/取消控制。

场景级测试用例示例

测试准备：在沙箱环境部署 host-core@1.4.0 与插件 insight-calculator@2.1.0，配置 Service Mesh（Istio）与租户策略服务。准备租户 tenant-pro（已授权）与 tenant-beta（未授权），并在监控平台开启调用追踪。

用例 A-1：gRPC 调用成功（正向）

• 前置条件：插件注册 gRPC 服务 CalcService.Compute，租户 tenant-pro 授权启用。
• 操作步骤：
  1. 宿主通过统一入口发起 gRPC 请求，携带 Trace ID 与租户 Header。
  2. Service Mesh 路由到就近插件实例。
• 预期结果：
  • 返回 200/OK，响应时间 <300ms。
  • Trace 平台可查看完整链路，租户调用计数 +1。

用例 A-2：协议转换失败（逆向）

• 前置条件：插件仅支持 gRPC，宿主误以 HTTP 方式调用。
• 操作步骤：
  1. 模拟错误协议请求。
• 预期结果：
  • 统一入口返回 415 Unsupported Media Type，并记录错误。
  • 不会触发下游插件实例。

用例 B-1：未授权租户调用阻断（逆向）

• 前置条件：tenant-beta 未在策略中授权该插件。
• 操作步骤：
  1. 使用 tenant-beta 的上下文调用同一能力。
• 预期结果：
  • 返回 403 Forbidden，日志记录租户信息与阻断原因。
  • 监控面板显示一次策略拒绝事件。

用例 B-2：限流策略生效（正向）

• 前置条件：为 tenant-pro 设置每分钟 100 次的限流阈值。
• 操作步骤：
  1. 通过压测脚本在 1 分钟内发起 150 次请求。
• 预期结果：
  • 前 100 次成功，后续请求返回 429 Too Many Requests。
  • 限流日志记录触发时间与租户 ID，指标面板可见限流曲线。

用例 C-1：自动重试成功（正向）

• 前置条件：插件实例首次调用模拟 500 错误，第二次恢复正常。
• 操作步骤：
  1. 发起调用并观察宿主重试策略。
• 预期结果：
  • 第一次响应 500，宿主在 200ms 后自动重试成功。
  • Trace 显示两次调用，监控记录一次重试事件。

用例 C-2：熔断与降级（逆向）

• 前置条件：插件连续返回 500；熔断阈值设置为 3 次失败/30s。
• 操作步骤：
  1. 连续触发失败调用 5 次。
• 预期结果：
  • 第 4 次后宿主触发熔断，返回降级结果并提示稍后重试。
  • 监控告警发送给 SRE，熔断状态 60s 后自动恢复。

用例 D-1：异步任务结果聚合（正向）

• 前置条件：启用任务队列模式，插件支持异步回调。
• 操作步骤：
  1. 宿主一次性提交 50 个批量任务到队列。
  2. 插件处理完成后回调宿主结果。
• 预期结果：
  • 队列无积压，所有任务状态在 5 分钟内更新为完成。
  • 宿主生成聚合报表，并在监控中记录吞吐指标。

用例 D-2：回调失败补偿（逆向）

• 前置条件：模拟回调接口超时。
• 操作步骤：
  1. 插件回调宿主时故意返回超时。
• 预期结果：
  • 宿主检测到失败后触发补偿任务重新拉取结果。
  • 日志保留补偿记录，并在 10 分钟内完成数据对账。