TrueGrowth/openspec/changes/add-provider-protocol-routing/design.md

Context

当前代码已经具备以下基础能力：

• settings-manager 可以管理 ProviderProfile / ProviderCatalog / ModelRef / InvocationPreset
• runtime-model-discovery 可以按 profileId 隔离发现和选择模型
• 图片和视频侧已经存在若干专用 adapter，分别处理 Flux、MJ、Kling、Seedance 等协议变体

但当前结构仍存在三个核心缺口：

1. resolveInvocationRoute 只解析凭证和模型，不解析协议与请求体策略
2. runtime-model-discovery 仍以统一 /models + Bearer 的假设执行发现
3. model-adapters 仍然按模型 / 厂商 / 标签进行猜测式匹配，无法表达“同名模型在不同 profile 下走不同协议”的事实

这会导致下列问题：

• 同名模型在不同上游中发生协议冲突
• 同协议不同请求体的差异只能堆在 adapter 内的条件分支中，难以扩展
• 文本链路继续绕过统一路由层，无法和图片 / 视频共享同一套供应商协议规划

Goals / Non-Goals

• Goals:
  • 让运行时调用基于 profileId + modelId + operation 选择协议绑定
  • 支持同一模型 ID 在不同供应商下走不同协议
  • 支持同一协议下的不同请求体 schema
  • 统一文本、图片、视频三类调用的运行时规划流程
  • 尽量降低用户配置成本，优先自动推断协议绑定，仅在歧义时暴露高级覆盖项
• Non-Goals:
  • 本次不实现跨供应商自动故障切换
  • 本次不实现按价格 / 延迟 / 健康度自动择优调度
  • 本次不为所有第三方平台实现完全自动化、零误差的协议识别

Decisions

• Decision: 区分“模型标识”和“可执行绑定”

  • modelId 表示用户看到的模型
  • ProviderModelBinding 表示该模型在特定供应商下针对特定操作的调用方式
  • 绑定的主键必须至少包含 profileId + modelId + operation

• Decision: 引入 InvocationPlanner

  • 输入：routeType + ModelRef + optional override
  • 输出：InvocationPlan
  • Planner 负责在多个绑定中选择当前最合适的协议，而不是让 UI 或 service 直接拼 URL

• Decision: 将适配器从“按模型注册”迁移为“按协议注册”

  • 现有 Flux / MJ / Kling / Seedance 等实现可以保留，但角色改为 ProtocolAdapter
  • ProtocolAdapter 负责请求体构建、响应解析、可选轮询策略

• Decision: 将鉴权和基础 URL 处理下沉到 ProviderTransport

  • 统一处理 bearer / header / query / custom 等认证方式
  • 统一处理额外 Header、查询参数和供应商级发现接口
  • 避免每个 adapter 再重复拼装认证信息

• Decision: discovery 必须保留原始元数据和绑定推断结果

  • 不能只把远端模型压成扁平 ModelConfig
  • 必须保留 raw、capabilityHints、bindingCandidates
  • 否则后续运行时无法稳定判断同名模型的协议归属

• Decision: 同名模型不得按裸 modelId 全局去重

  • 选择器和运行时缓存应使用 selectionKey = profileId::modelId
  • 运行时绑定必须保留 profileId

Proposed Data Model

interface ResolvedProviderContext {
  profileId: string;
  profileName: string;
  providerType: string;
  baseUrl: string;
  apiKey: string;
  authType: 'bearer' | 'header' | 'query' | 'custom';
  extraHeaders?: Record<string, string>;
}

interface ProviderModelBinding {
  id: string;
  profileId: string;
  modelId: string;
  operation: 'text' | 'image' | 'video';
  protocol:
    | 'openai.chat.completions'
    | 'openai.images.generations'
    | 'openai.async.video'
    | 'google.generateContent'
    | 'mj.imagine'
    | 'flux.task'
    | 'kling.video'
    | 'seedance.task';
  requestSchema: string;
  responseSchema: string;
  submitPath: string;
  pollPathTemplate?: string;
  priority: number;
  confidence: 'high' | 'medium' | 'low';
  source: 'discovered' | 'template' | 'manual';
}

interface DiscoveredProviderModel {
  profileId: string;
  modelId: string;
  selectionKey: string;
  raw: unknown;
  capabilityHints: {
    supportsText: boolean;
    supportsImage: boolean;
    supportsVideo: boolean;
  };
  bindings: ProviderModelBinding[];
}

interface InvocationPlan {
  provider: ResolvedProviderContext;
  modelRef: { profileId: string; modelId: string };
  binding: ProviderModelBinding;
}

Execution Flow

1. 用户在设置中保存 ProviderProfile
2. ProviderTransport 根据 providerType/baseUrl 选择供应商模板或探测策略
3. discovery 同步远端模型，并推断出每个模型的 bindings[]
4. 用户在运行时选择 ModelRef(profileId + modelId)
5. InvocationPlanner 根据 operation 找到最高优先级的可执行 binding
6. ProtocolAdapterRegistry 按 binding.protocol 取得协议适配器
7. 适配器根据 requestSchema 构建请求，并通过 ProviderTransport 发送
8. 如为异步任务，则由对应 PollingStrategy 轮询并标准化结果

Binding Inference Strategy

• OpenAI 兼容供应商：
  • 优先使用 /v1/models 返回的字段、模型 ID 和供应商模板推断绑定
  • 默认优先生成 openai.chat.completions / openai.images.generations / openai.async.video
• Gemini 官方供应商：
  • 不再强依赖 /models
  • 允许由 provider template 直接提供 google.generateContent 绑定
• 自定义供应商：
  • 若 discovery 无法高置信度推断协议，则保留低置信度绑定
  • 仅在需要时暴露高级覆盖入口

Request Schema Strategy

同一协议下的请求体差异不再通过大量 if modelId.includes(...) 解决，而是显式建模：

• openai.image.basic-json
• openai.video.form.input-reference
• google.gemini.generate-content.image
• kling.video.text2video
• kling.video.image2video
• seedance.video.first-last-frame

这样新增模型时，优先复用已有协议，仅为其指派合适的 requestSchema。

Migration Plan

1. 新增 provider protocol routing 类型与 planner，不改 UI
2. 将现有图片 / 视频 adapter 包装为 ProtocolAdapter
3. 将文本链路迁移到同一 planner 和 protocol registry
4. 扩展 discovery 存储，保留 bindings[]
5. 最后再清理旧的“按模型猜 adapter”逻辑

Risks / Trade-offs

• 风险: 架构抽象增加初始复杂度

  • Mitigation: 分阶段迁移，先保留现有 adapter 实现，只调整其注册方式

• 风险: 自动推断协议可能存在误判

  • Mitigation: 为 binding 引入 confidence 与 source，仅在低置信度场景允许高级覆盖

• 风险: 文本 / 图片 / 视频同时迁移会影响面较大

  • Mitigation: 先完成 planner 和 image/video 迁移，再迁移 text

Open Questions

• 是否需要将用户手动覆盖的 binding 保存在 ProviderCatalog，还是单独存为 ProviderBindingOverrides
• authType 是否需要从当前的 bearer/header 扩展为更通用的 query/custom
• 官方 Gemini 等不提供 OpenAI 风格 /models 时，设置页是否需要显式展示“供应商模板已接管模型能力”