fix: 完善转换代理行为

openspec/specs/openai-protocol-proxy/spec.md

@@ -2,33 +2,66 @@
 
 ## Purpose
 
-定义 OpenAI Chat Completions API 端点的协议代理行为，包括请求处理流程、模型路由、同协议透传和跨协议转换。
+定义 OpenAI Chat Completions API 端点及扩展层端点的协议代理行为，包括请求处理流程、模型路由、同协议透传和跨协议转换。
 
 ## Requirements
 
+### Requirement: 支持 OpenAI 扩展层 v1 端点
+
+网关 SHALL 提供带 `/v1` 层级的 OpenAI 扩展层端点供外部应用调用。
+
+#### Scenario: Models 列表端点
+
+- **WHEN** 应用发送 GET 请求到 `/openai/v1/models`
+- **THEN** 网关 SHALL 将剥离 `/openai` 后的 `/v1/models` 作为 OpenAI nativePath
+- **THEN** 网关 SHALL 返回 OpenAI Models 格式响应
+
+#### Scenario: ModelInfo 详情端点
+
+- **WHEN** 应用发送 GET 请求到 `/openai/v1/models/{provider_id}/{model_name}`
+- **THEN** 网关 SHALL 将剥离 `/openai` 后的 `/v1/models/{provider_id}/{model_name}` 作为 OpenAI nativePath
+- **THEN** 网关 SHALL 返回 OpenAI ModelInfo 格式响应
+
+#### Scenario: Embeddings 端点
+
+- **WHEN** 应用发送 POST 请求到 `/openai/v1/embeddings`
+- **THEN** 网关 SHALL 将剥离 `/openai` 后的 `/v1/embeddings` 作为 OpenAI nativePath
+- **THEN** 网关 SHALL 使用 OpenAI adapter 识别并处理 Embeddings 请求
+
+#### Scenario: Rerank 端点
+
+- **WHEN** 应用发送 POST 请求到 `/openai/v1/rerank`
+- **THEN** 网关 SHALL 将剥离 `/openai` 后的 `/v1/rerank` 作为 OpenAI nativePath
+- **THEN** 网关 SHALL 使用 OpenAI adapter 识别并处理 Rerank 请求
+
 ### Requirement: 支持 OpenAI Chat Completions API 端点
 
-网关 SHALL 提供 OpenAI Chat Completions API 端点供外部应用调用。
+网关 SHALL 提供带 `/v1` 层级的 OpenAI Chat Completions API 端点供外部应用调用。
 
 #### Scenario: 成功的非流式请求
 
-- **WHEN** 应用发送 POST 请求到 `/openai/chat/completions`，携带有效的 OpenAI 请求格式（非流式）
+- **WHEN** 应用发送 POST 请求到 `/openai/v1/chat/completions`，携带有效的 OpenAI 请求格式（非流式）
+- **THEN** 网关 SHALL 剥离 `/openai` 前缀并将 `/v1/chat/completions` 作为 OpenAI nativePath
 - **THEN** 网关 SHALL 通过 ConversionEngine 转换请求
 - **THEN** 网关 SHALL 将转换后的请求转发到配置的供应商
-- **THEN** 网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 OpenAI 格式返回给应用
+- **THEN** 若上游返回 2xx，网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 OpenAI 格式返回给应用
 
 #### Scenario: 成功的流式请求
 
-- **WHEN** 应用发送 POST 请求到 `/openai/chat/completions`，携带 `stream: true`
-- **THEN** 网关 SHALL 通过 ConversionEngine 创建 StreamConverter
+- **WHEN** 应用发送 POST 请求到 `/openai/v1/chat/completions`，携带 `stream: true`
+- **THEN** 网关 SHALL 剥离 `/openai` 前缀并将 `/v1/chat/completions` 作为 OpenAI nativePath
+- **THEN** 网关 SHALL 通过 ConversionEngine 创建 StreamConverter 或使用同协议流式透传路径
 - **THEN** 网关 SHALL 使用 SSE 格式将转换后的响应流式返回给应用
-- **THEN** 网关 SHALL 在流完成时发送 `data: [DONE]`
+- **THEN** 网关 SHALL 在 OpenAI 协议流完成时发送或透传 `data: [DONE]`
 
 #### Scenario: 同协议透传（OpenAI → OpenAI Provider）
 
 - **WHEN** 客户端使用 OpenAI 协议且目标供应商也是 OpenAI 协议
-- **THEN** 网关 SHALL 跳过 Canonical 转换，仅重建认证 Header 后原样转发
-- **THEN** 请求和响应 Body SHALL 保持原样
+- **THEN** 网关 SHALL 跳过 Canonical 转换
+- **THEN** 网关 SHALL 使用 OpenAI adapter 重建上游 URL 和认证 Header
+- **THEN** 若请求使用统一模型 ID，网关 SHALL 仅通过 Smart Passthrough 改写 model 字段
+- **THEN** OpenAI adapter SHALL 将 `/v1/chat/completions` 映射为上游路径 `/chat/completions`
+- **THEN** OpenAI 供应商 `base_url` 配置到版本路径一级时，最终上游 URL SHALL 不重复 `/v1`
 
 ### Requirement: 根据模型名称路由请求
 
@@ -36,20 +69,25 @@
 
 #### Scenario: 有效模型路由
 
-- **WHEN** 请求包含存在于配置模型中的 `model` 字段
-- **AND** 该模型已启用
+- **WHEN** 请求包含有效统一模型 ID 格式的 `model` 字段
+- **AND** 该模型存在且已启用
 - **THEN** 网关 SHALL 将请求路由到该模型关联的供应商
 - **THEN** 网关 SHALL 从供应商的 `protocol` 字段获取 providerProtocol
 
 #### Scenario: 模型未找到
 
-- **WHEN** 请求包含不存在于配置模型中的 `model` 字段
-- **THEN** 网关 SHALL 使用 OpenAI 格式返回错误响应
+- **WHEN** 请求包含有效统一模型 ID 格式的 `model` 字段但模型不存在
+- **THEN** 网关 SHALL 使用应用统一错误格式返回 404 错误
 
 #### Scenario: 模型已禁用
 
-- **WHEN** 请求包含已禁用模型的 `model` 字段
-- **THEN** 网关 SHALL 使用 OpenAI 格式返回错误响应
+- **WHEN** 请求包含已禁用模型的有效统一模型 ID
+- **THEN** 网关 SHALL 使用应用统一错误格式返回 404 错误
+
+#### Scenario: 原始模型名兼容透传
+
+- **WHEN** 请求中的 `model` 字段不是有效统一模型 ID 格式
+- **THEN** 网关 SHALL 按无可路由 model 请求走 forwardPassthrough
 
 ### Requirement: 跨协议请求转换
 
@@ -60,8 +98,16 @@
 - **WHEN** 网关收到 OpenAI 协议请求且目标供应商使用不同协议
 - **THEN** 网关 SHALL 通过 ConversionEngine 将请求转换为目标协议格式
 - **THEN** 网关 SHALL 使用目标协议的 Adapter 构建 URL 和 Header
+- **THEN** 目标协议 Adapter SHALL 基于接口类型构建目标协议路径，不直接复用 OpenAI nativePath 中的 `/v1` 版本段
 
 #### Scenario: 扩展层接口代理
 
 - **WHEN** 网关收到 `/openai/v1/models` 等 GET 请求
-- **THEN** 网关 SHALL 通过 ConversionEngine 转换扩展层接口的响应格式
+- **THEN** 网关 SHALL 将 `/v1/models` 作为 OpenAI nativePath 识别扩展层接口
+- **THEN** 网关 SHALL 通过本地聚合或 ConversionEngine 转换扩展层接口响应格式
+
+#### Scenario: 上游错误透传
+
+- **WHEN** OpenAI 代理请求收到上游非 2xx HTTP 响应
+- **THEN** 网关 SHALL 直接透传上游 status code、过滤后的 headers 和 body
+- **THEN** 网关 SHALL NOT 将上游错误转换为 OpenAI 错误格式