sub2api-cn-relay-manager/docs/SHADOW_PROVIDER_VALIDATION.md

Shadow Provider Validation

本文件记录插件前置路由架构下，shadow provider 的最小正确验证路径。

目标

验证以下结论是否成立：

1. 插件层可以继续维护 logical_group/public_model
2. 宿主层的 shadow group 只承载 canonical upstream model
3. 真实 managed key 能通过宿主 /v1/models 与 /v1/chat/completions
4. 旧的 alias/public model 不再下沉到 stock host 的 channel_mapped + restrict_models 组合

设计结论

旧的 route-lab 已证明两件事：

1. 当前宿主不支持“多个 channel 复用同一个 group”
2. 在 weishaw/sub2api:0.1.129 上，把 alias 继续下沉到宿主 shadow group，会触发 channel pricing restriction

因此新的 shadow provider 约束是：

plugin logical group
  -> route
    -> shadow group (host)
      -> canonical models only

当前实验 pack

• pack 目录：packs/openai-cn-pack-shadow-asxs
• provider：gpt-asxs-shadow-lab

实验建模

Shadow Group: GPT ASXS Shadow 实验
  Channel: GPT ASXS Shadow
    Models:
      - gpt-5.4
      - gpt-5.4-mini

关键点：

• shadow group 不再暴露 gpt-5.4-asxs
• 插件 route 层如果需要 alias，必须在 logical_group_route_models.shadow_model 之外处理
• stock host 只看到 canonical 模型

建议验证顺序

1. 导入 gpt-asxs-shadow-lab
2. 记录 group_id / channel_id / account_id
3. 用宿主订阅 key 直接验证：
   • GET /v1/models
   • POST /v1/chat/completions
4. 再用插件管理面创建临时 logical_group / route
5. 调 POST /api/routing/proxy/chat/completions
6. 核对：
   • effective_gateway_key_source=managed_subscription
   • forward.upstream_status=200
   • route_decision_logs 已写回同一 request_id

成功标准

• managed key /v1/models 返回 canonical model
• managed key /v1/chat/completions 返回 200
• 插件 route proxy 走真实 shadow group 时返回 200
• 不再出现 channel pricing restriction