lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
3fa5827de394b7af34a4975ae5f9890be87e1235
nex/openspec/specs/openai-protocol-proxy/spec.md
lanyuanxiaoyao bc1ee612d9 refactor: 实现 ConversionEngine 协议转换引擎，替代旧 protocol 包 
- 新增 ConversionEngine 核心引擎，支持 OpenAI 和 Anthropic 协议转换
- 添加 stream decoder/encoder 实现
- 更新 provider client 支持新引擎
- 补充单元测试和集成测试
- 更新 specs 文档
2026-04-20 13:02:28 +08:00

4.2 KiB
Raw Blame History

OpenAI Protocol Proxy

MODIFIED Requirements

Requirement: 支持 OpenAI Chat Completions API 端点

网关 SHALL 提供 OpenAI Chat Completions API 端点供外部应用调用。

Scenario: 成功的非流式请求

  • WHEN 应用发送 POST 请求到 /openai/v1/chat/completions，携带有效的 OpenAI 请求格式（非流式）
  • THEN 网关 SHALL 通过 ConversionEngine 转换请求
  • THEN 网关 SHALL 将转换后的请求转发到配置的供应商
  • THEN 网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 OpenAI 格式返回给应用

Scenario: 成功的流式请求

  • WHEN 应用发送 POST 请求到 /openai/v1/chat/completions，携带 stream: true
  • THEN 网关 SHALL 通过 ConversionEngine 创建 StreamConverter
  • THEN 网关 SHALL 使用 SSE 格式将转换后的响应流式返回给应用
  • THEN 网关 SHALL 在流完成时发送 data: [DONE]

Scenario: 同协议透传（OpenAI → OpenAI Provider）

  • WHEN 客户端使用 OpenAI 协议且目标供应商也是 OpenAI 协议
  • THEN 网关 SHALL 跳过 Canonical 转换，仅重建认证 Header 后原样转发
  • THEN 请求和响应 Body SHALL 保持原样

Requirement: 根据模型名称路由请求

网关 SHALL 根据请求中的 model 字段将请求路由到相应的供应商。

Scenario: 有效模型路由

  • WHEN 请求包含存在于配置模型中的 model 字段
  • AND 该模型已启用
  • THEN 网关 SHALL 将请求路由到该模型关联的供应商
  • THEN 网关 SHALL 从供应商的 protocol 字段获取 providerProtocol

Scenario: 模型未找到

  • WHEN 请求包含不存在于配置模型中的 model 字段
  • THEN 网关 SHALL 使用 OpenAI 格式返回错误响应

Scenario: 模型已禁用

  • WHEN 请求包含已禁用模型的 model 字段
  • THEN 网关 SHALL 使用 OpenAI 格式返回错误响应

Requirement: 对 OpenAI 兼容供应商透明代理

网关 SHALL 对 OpenAI 兼容供应商的请求和响应通过 ConversionEngine 进行转换处理。

Scenario: 跨协议请求转发

  • WHEN 网关收到 OpenAI 协议请求且目标供应商使用不同协议
  • THEN 网关 SHALL 通过 ConversionEngine 将请求转换为目标协议格式
  • THEN 网关 SHALL 使用目标协议的 Adapter 构建 URL 和 Header

Scenario: 扩展层接口代理

  • WHEN 网关收到 /openai/v1/models 等 GET 请求
  • THEN 网关 SHALL 通过 ConversionEngine 转换扩展层接口的响应格式

ADDED Requirements

Requirement: 使用 service 层处理请求

Handler SHALL 通过 service 层处理业务逻辑。

Scenario: 调用 routing service

  • WHEN handler 收到请求
  • THEN SHALL 调用 RoutingService.Route() 获取路由结果
  • THEN SHALL 使用路由结果中的供应商信息

Scenario: 调用 stats service

  • WHEN 请求成功完成
  • THEN SHALL 调用 StatsService.Record() 记录统计
  • THEN SHALL 异步记录统计（不阻塞响应）

Requirement: 使用 service 层处理请求

Handler SHALL 通过 service 层处理业务逻辑。

Scenario: 调用 routing service

  • WHEN ProxyHandler 收到请求
  • THEN SHALL 调用 RoutingService.Route() 获取路由结果
  • THEN SHALL 从路由结果获取 Provider（含 protocol 字段）

Scenario: 调用 stats service

  • WHEN 请求成功完成
  • THEN SHALL 调用 StatsService.Record() 记录统计
  • THEN SHALL 异步记录统计（不阻塞响应）

Requirement: 使用结构化错误处理

ProxyHandler SHALL 使用 ConversionError 和协议对应的 encodeError 处理错误。

Scenario: 转换错误

  • WHEN ConversionEngine 返回 ConversionError
  • THEN SHALL 使用 clientProtocol 的 Adapter.encodeError 编码错误响应
  • THEN SHALL 使用 OpenAI 错误格式（{error: {message, type, code}}）

Scenario: 路由错误处理

  • WHEN RoutingService 返回错误
  • THEN SHALL 转换为 ConversionError
  • THEN SHALL 使用 OpenAI 错误格式返回

Scenario: 供应商错误处理

  • WHEN ProviderClient 返回错误
  • THEN SHALL 包装为 ConversionError
  • THEN SHALL 使用 OpenAI 错误格式返回
View Git Blame Copy Permalink