109 lines
4.5 KiB
Markdown
109 lines
4.5 KiB
Markdown
## ADDED Requirements
|
||
|
||
### Requirement: 同协议请求 URL 使用 Adapter 映射
|
||
|
||
ConversionEngine SHALL 在同协议透传和 Smart Passthrough 场景下使用 providerAdapter.BuildUrl 构建上游 URL 路径。
|
||
|
||
#### Scenario: 同协议 Chat URL 映射
|
||
|
||
- **WHEN** clientProtocol == providerProtocol 且 interfaceType 为 CHAT
|
||
- **THEN** ConversionEngine SHALL 调用 providerAdapter.BuildUrl(nativePath, interfaceType)
|
||
- **THEN** 上游 URL SHALL 为 provider.BaseURL 与 BuildUrl 返回路径的组合
|
||
- **THEN** ConversionEngine SHALL NOT 直接将 provider.BaseURL 与 nativePath 拼接为上游 URL
|
||
|
||
#### Scenario: 未知接口 URL 映射
|
||
|
||
- **WHEN** interfaceType 为 PASSTHROUGH
|
||
- **THEN** providerAdapter.BuildUrl SHALL 返回适合目标协议的路径或原 nativePath
|
||
- **THEN** ConversionEngine SHALL 使用该路径构建上游 URL
|
||
|
||
### Requirement: SSE Frame 级 Smart Passthrough
|
||
|
||
系统 SHALL 支持同协议流式 Smart Passthrough 对 SSE frame 中的 model 字段进行最小化改写。
|
||
|
||
#### Scenario: 改写 SSE data JSON
|
||
|
||
- **WHEN** 同协议流式响应需要将上游模型名改写为统一模型 ID
|
||
- **THEN** 系统 SHALL 按 SSE frame 解析上游字节流
|
||
- **THEN** 对包含 JSON payload 的 `data` 行 SHALL 调用 adapter.RewriteResponseModelName 改写 model 字段
|
||
- **THEN** SHALL 重建合法 SSE frame 输出
|
||
|
||
#### Scenario: 保留 DONE 事件
|
||
|
||
- **WHEN** SSE frame 的 data payload 为 `[DONE]`
|
||
- **THEN** 系统 SHALL 原样输出 `[DONE]`
|
||
- **THEN** SHALL NOT 尝试按 JSON 解析
|
||
|
||
#### Scenario: 改写失败宽容降级
|
||
|
||
- **WHEN** SSE frame 解析或 model 改写失败
|
||
- **THEN** 系统 SHALL 记录 warn 日志
|
||
- **THEN** SHALL 输出原始 SSE frame
|
||
- **THEN** SHALL 继续处理后续 frame
|
||
|
||
### Requirement: Adapter 模型提取边界
|
||
|
||
ProtocolAdapter SHALL 只对明确适配的接口提供 model 提取和 model 改写能力。
|
||
|
||
#### Scenario: 已适配接口提取 model
|
||
|
||
- **WHEN** ifaceType 为 adapter 明确支持提取 model 的接口
|
||
- **THEN** ExtractModelName SHALL 按该协议和接口的请求格式提取 model 字段
|
||
|
||
#### Scenario: 未适配接口不提取 model
|
||
|
||
- **WHEN** ifaceType 为 PASSTHROUGH 或 adapter 未明确支持提取 model 的接口
|
||
- **THEN** ExtractModelName SHALL 返回错误或空结果
|
||
- **THEN** 调用方 SHALL 按无 model 请求处理
|
||
|
||
### Requirement: 跨协议多模态暂不支持
|
||
|
||
ConversionEngine SHALL 在跨协议完整转换中对当前暂不支持的多模态内容返回明确错误。
|
||
|
||
#### Scenario: 跨协议请求包含多模态内容块
|
||
|
||
- **WHEN** clientProtocol != providerProtocol 且 CanonicalRequest 中包含 image、audio、video 或 file 内容块
|
||
- **THEN** ConversionEngine SHALL 中断转换
|
||
- **THEN** SHALL 返回网关层 `UNSUPPORTED_MULTIMODAL` 错误
|
||
- **THEN** SHALL NOT 静默丢弃多模态内容
|
||
|
||
#### Scenario: 同协议多模态请求
|
||
|
||
- **WHEN** clientProtocol == providerProtocol 且请求通过 Smart Passthrough 或 raw passthrough 处理
|
||
- **THEN** 系统 SHALL 保留原始请求体中未改写字段
|
||
- **THEN** SHALL NOT 因多模态字段存在而执行跨协议多模态校验
|
||
|
||
### Requirement: 上游非 2xx 响应不进入转换
|
||
|
||
ConversionEngine SHALL 只转换调用方传入的成功响应，ProxyHandler SHALL 在调用转换前过滤上游非 2xx 响应。
|
||
|
||
#### Scenario: 非 2xx 响应绕过响应转换
|
||
|
||
- **WHEN** 上游响应状态码不是 2xx
|
||
- **THEN** ProxyHandler SHALL NOT 调用 ConversionEngine.ConvertHttpResponse
|
||
- **THEN** ProxyHandler SHALL 直接透传该响应
|
||
|
||
#### Scenario: 流式非 2xx 响应绕过流式转换
|
||
|
||
- **WHEN** 流式请求收到上游非 2xx 响应
|
||
- **THEN** ProxyHandler SHALL NOT 调用 ConversionEngine.CreateStreamConverter
|
||
- **THEN** ProxyHandler SHALL 直接透传该响应
|
||
|
||
### Requirement: 协议路径来源
|
||
|
||
ProtocolAdapter SHALL 以对应协议的本地 API reference 文档作为 URL 识别和 URL 映射的事实来源。
|
||
|
||
#### Scenario: OpenAI 路径来源
|
||
|
||
- **WHEN** 实现或测试 OpenAI adapter 的 DetectInterfaceType 或 BuildUrl
|
||
- **THEN** SHALL 参考 `docs/api_reference/openai` 中的接口路径
|
||
- **THEN** SHALL 忽略 `docs/api_reference/openai/responses` 目录
|
||
- **THEN** SHALL NOT 因其他协议包含 `/v1` 而给 OpenAI nativePath 添加 `/v1`
|
||
|
||
#### Scenario: Anthropic 路径来源
|
||
|
||
- **WHEN** 实现或测试 Anthropic adapter 的 DetectInterfaceType 或 BuildUrl
|
||
- **THEN** SHALL 参考 `docs/api_reference/anthropic` 中的接口路径
|
||
- **THEN** SHALL 保留文档中接口路径自带的 `/v1` 前缀
|
||
- **THEN** SHALL NOT 因 OpenAI nativePath 不含 `/v1` 而移除 Anthropic nativePath 中的 `/v1`
|