1
0

refactor: 实现 ConversionEngine 协议转换引擎,替代旧 protocol 包

- 新增 ConversionEngine 核心引擎,支持 OpenAI 和 Anthropic 协议转换
- 添加 stream decoder/encoder 实现
- 更新 provider client 支持新引擎
- 补充单元测试和集成测试
- 更新 specs 文档
This commit is contained in:
2026-04-20 13:01:05 +08:00
parent 1dac347d3b
commit bc1ee612d9
39 changed files with 11177 additions and 995 deletions

View File

@@ -0,0 +1,104 @@
# Unified Proxy Handler
## ADDED Requirements
### Requirement: 实现统一代理 Handler
系统 SHALL 实现统一的 ProxyHandler替代现有的 OpenAIHandler 和 AnthropicHandler。
ProxyHandler SHALL 依赖 ConversionEngine、ProviderClient、RoutingService、StatsService。
#### Scenario: 从 URL 提取客户端协议
- **WHEN** 收到 `/{protocol}/v1/{path}` 格式的请求
- **THEN** SHALL 从 URL 第一段提取 protocol 作为 clientProtocol
- **THEN** SHALL 剥离前缀得到 nativePath
#### Scenario: 协议前缀必须是已注册协议
- **WHEN** 收到的 URL 前缀不是已注册的协议名称
- **THEN** SHALL 返回 404 错误
#### Scenario: 接口类型识别
- **WHEN** 提取 nativePath 后
- **THEN** SHALL 通过 ConversionEngine.convertHttpRequest 内部调用 clientAdapter.detectInterfaceType(nativePath) 识别接口类型
- **THEN** 未知路径 SHALL 使用透传模式
### Requirement: 非流式请求处理流程
ProxyHandler SHALL 按以下流程处理非流式请求。
#### Scenario: 完整转换流程
- **WHEN** 收到非流式请求
- **THEN** SHALL 解析请求体为 JSON
- **THEN** SHALL 调用 RoutingService.Route(modelName) 获取路由结果
- **THEN** SHALL 从路由结果的 Provider.Protocol 获取 providerProtocol
- **THEN** SHALL 构建 TargetProviderbase_url, api_key, model_name, adapter_config
- **THEN** SHALL 调用 engine.convertHttpRequest(body, clientProtocol, providerProtocol, provider)
- **THEN** SHALL 调用 providerClient.Send(ctx, requestSpec)
- **THEN** SHALL 调用 engine.convertHttpResponse(response, clientProtocol, providerProtocol, interfaceType)
- **THEN** SHALL 将转换后的响应返回给客户端
#### Scenario: 路由失败处理
- **WHEN** RoutingService.Route 返回错误
- **THEN** SHALL 使用 clientProtocol 对应的 Adapter.encodeError 编码错误响应
- **THEN** SHALL 返回适当的 HTTP 状态码
#### Scenario: 上游请求失败处理
- **WHEN** ProviderClient.Send 返回错误
- **THEN** SHALL 使用 clientProtocol 对应的 Adapter.encodeError 编码错误响应
- **THEN** SHALL 包装原始错误信息
### Requirement: 流式请求处理流程
ProxyHandler SHALL 按以下流程处理流式请求。
#### Scenario: 流式转换流程
- **WHEN** 请求中 stream=true 或接口类型为 CHAT 且请求体含 stream:true
- **THEN** SHALL 执行与非流式相同的前置处理(路由、构建 TargetProvider
- **THEN** SHALL 调用 engine.convertHttpRequest 获取 HTTPRequestSpec
- **THEN** SHALL 调用 providerClient.SendStream(ctx, requestSpec) 获取流
- **THEN** SHALL 调用 engine.createStreamConverter(clientProtocol, providerProtocol, provider)
- **THEN** SHALL 设置响应 Header `Content-Type: text/event-stream`
- **THEN** SHALL 对每个流 chunk 调用 converter.processChunk 并写入响应
- **THEN** SHALL 在流结束时调用 converter.flush() 刷新缓冲
#### Scenario: 同协议透传流式
- **WHEN** clientProtocol == providerProtocol
- **THEN** SHALL 直接将上游 SSE 字节流写入响应
- **THEN** SHALL NOT 做任何解析或转换
#### Scenario: 流式错误处理
- **WHEN** 流过程中发生错误
- **THEN** SHALL 记录错误日志
- **THEN** SHALL 关闭响应流
### Requirement: 统计记录
ProxyHandler SHALL 记录请求统计。
#### Scenario: 异步记录统计
- **WHEN** 请求处理完成(成功或失败)
- **THEN** SHALL 异步调用 StatsService.Record
- **THEN** SHALL NOT 阻塞响应返回
### Requirement: GET 请求透传
ProxyHandler SHALL 支持 GET 请求的扩展层接口代理。
#### Scenario: Models 接口<E68EA5><E58FA3>
- **WHEN** 收到 GET /{protocol}/v1/models 请求
- **THEN** SHALL 执行路由和协议识别
- **THEN** SHALL 调用 engine.convertHttpRequestGET 请求 body 为空)
- **THEN** SHALL 调用 providerClient.Send 发送请求
- **THEN** SHALL 调用 engine.convertHttpResponse 转换响应格式
- **THEN** SHALL 返回转换后的响应