nex/openspec/specs/conversion-engine/spec.md

Conversion Engine

Purpose

定义协议无关的 Canonical Model 和 ConversionEngine 转换引擎，作为所有协议间请求/响应转换的统一枢纽。

Requirement: 定义 CanonicalRequest 规范模型

系统 SHALL 定义协议无关的 CanonicalRequest 结构体，作为所有协议间请求转换的统一枢纽。

CanonicalRequest SHALL 包含以下字段：

• model: 字符串，模型名称
• system: 可选，字符串或 SystemBlock 数组
• messages: CanonicalMessage 数组
• tools: 可选，CanonicalTool 数组
• tool_choice: 可选，ToolChoice 联合体
• parameters: RequestParameters
• thinking: 可选，ThinkingConfig
• stream: 布尔值
• user_id: 可选字符串
• output_format: 可选，OutputFormat
• parallel_tool_use: 可选布尔值

Scenario: CanonicalRequest 包含所有公共字段

• WHEN 从任意协议解码请求为 CanonicalRequest
• THEN CanonicalRequest SHALL 包含协议间可映射的所有公共语义字段
• THEN 协议特有字段 SHALL NOT 出现在 CanonicalRequest 中

Scenario: System 消息独立存储

• WHEN 协议使用顶层 system 字段（如 Anthropic）
• THEN SHALL 提取为 canonical.system
• WHEN 协议使用 messages 数组中的 system 角色（如 OpenAI）
• THEN SHALL 从 messages 中提取为 canonical.system

Requirement: 定义 CanonicalMessage 和 ContentBlock

系统 SHALL 定义 CanonicalMessage 结构体和 ContentBlock 联合体。

CanonicalMessage SHALL 包含 role（枚举：system/user/assistant/tool）和 content（ContentBlock 数组）。

ContentBlock SHALL 支持以下类型：

• text: 文本内容块
• tool_use: 工具调用块（id, name, input）
• tool_result: 工具结果块（tool_use_id, content, is_error）
• thinking: 思考内容块（thinking）

Scenario: ContentBlock 类型化表示

• WHEN 编码 ContentBlock
• THEN SHALL 使用 type 字段标识块类型
• THEN 不同类型 SHALL 携带各自特有的字段

Scenario: Tool 输入保留原始 JSON

• WHEN 解码工具调用的 input 字段
• THEN SHALL 使用 json.RawMessage 保留原始 JSON 数据
• THEN SHALL NOT 强制解析为 map 或 struct

Requirement: 定义 CanonicalTool 和 ToolChoice

系统 SHALL 定义 CanonicalTool（name, description, input_schema）和 ToolChoice 联合体（auto/none/any/tool+name）。

Scenario: ToolChoice 覆盖所有语义

• WHEN 协议使用 "required" 表示必须调用工具（如 OpenAI）
• THEN SHALL 映射为 {type: "any"}
• WHEN 协议使用 {type: "tool", name} 指定工具
• THEN SHALL 保持 {type: "tool", name} 映射

Requirement: 定义 CanonicalResponse 规范模型

系统 SHALL 定义 CanonicalResponse 结构体，包含 id、model、content（ContentBlock 数组）、stop_reason（可选枚举）、usage（CanonicalUsage）。

CanonicalUsage SHALL 包含 input_tokens、output_tokens、可选的 cache_read_tokens、cache_creation_tokens、reasoning_tokens。

stop_reason 枚举 SHALL 包含：end_turn、max_tokens、tool_use、stop_sequence、content_filter、refusal、pause_turn。

Scenario: 响应内容块与请求共用类型

• WHEN 编码响应中的 content
• THEN SHALL 使用与请求相同的 ContentBlock 类型系统
• THEN TextBlock 和 ToolUseBlock SHALL 在请求和响应中通用

Requirement: 定义 CanonicalStreamEvent 联合体

系统 SHALL 定义类型化的 CanonicalStreamEvent 联合体，包含显式的 start/stop 生命周期。

事件类型 SHALL 包含：

• message_start: 包含 message（id, model, usage）
• content_block_start: 包含 index 和 content_block
• content_block_delta: 包含 index 和 delta（text_delta/input_json_delta/thinking_delta）
• content_block_stop: 包含 index
• message_delta: 包含 delta（stop_reason）和 usage
• message_stop: 无额外数据
• error: 包含 error（type, message）
• ping: 无额外数据

Scenario: 流式事件具有完整生命周期

• WHEN 解码协议的 SSE 流为 CanonicalStreamEvent
• THEN SHALL 包含 message_start → content_block_start/delta/stop → message_delta → message_stop 的完整生命周期
• THEN 每个事件 SHALL 包含足够的信息用于编码为任意目标协议的 SSE 格式

Requirement: 定义 ProtocolAdapter 接口

系统 SHALL 定义 ProtocolAdapter 接口，每种协议实现完整适配。

ProtocolAdapter SHALL 包含以下方法：

• protocolName(): 返回协议唯一标识
• protocolVersion(): 返回协议版本
• supportsPassthrough(): 返回是否支持同协议透传
• detectInterfaceType(nativePath): 根据协议的 URL 路径识别接口类型
• buildUrl(nativePath, interfaceType): 映射 URL 路径
• buildHeaders(provider): 构建认证和必要 Header
• supportsInterface(interfaceType): 判断是否支持某接口类型
• decodeRequest(raw): 协议格式 → CanonicalRequest
• encodeRequest(canonical, provider): CanonicalRequest → 协议格式
• decodeResponse(raw): 协议格式 → CanonicalResponse
• encodeResponse(canonical): CanonicalResponse → 协议格式
• createStreamDecoder(): 创建 StreamDecoder 实例
• createStreamEncoder(): 创建 StreamEncoder 实例
• encodeError(error): ConversionError → 协议错误格式
• 扩展层编解码方法（Models/Embeddings/Rerank）

Scenario: Adapter 注册到 Registry

• WHEN 应用启动
• THEN SHALL 将所有 Adapter 注册到 AdapterRegistry
• THEN 可通过 registry.get(protocolName) 获取 Adapter

Scenario: Adapter 自描述接口能力

• WHEN 调用 supportsInterface(interfaceType)
• THEN SHALL 返回布尔值表示是否支持该接口类型
• THEN 不支持的接口 SHALL 由引擎走透传逻辑

Scenario: Adapter 识别接口类型

• WHEN 调用 detectInterfaceType(nativePath)
• THEN SHALL 根据协议的 URL 路径模式识别接口类型
• THEN SHALL 返回对应的 InterfaceType（CHAT/MODELS/MODEL_INFO/EMBEDDINGS/RERANK）
• THEN 无法识别的路径 SHALL 返回 PASSTHROUGH 类型

Requirement: 实现 AdapterRegistry

系统 SHALL 实现 AdapterRegistry，支持 Adapter 的注册和查询。

Scenario: 注册 Adapter

• WHEN 调用 registry.register(adapter)
• THEN SHALL 以 adapter 的 protocolName 为 key 存储
• THEN 重复注册同名协议 SHALL 返回错误

Scenario: 查询 Adapter

• WHEN 调用 registry.get(protocolName)
• THEN SHALL 返回已注册的 ProtocolAdapter
• THEN 未注册的协议 SHALL 返回错误

Requirement: 实现 ConversionEngine 门面

系统 SHALL 实现 ConversionEngine 作为无状态的转换引擎门面，线程安全、可复用。

ConversionEngine SHALL 提供：

• registerAdapter(adapter): 注册协议适配器
• use(middleware): 注册转换中间件
• isPassthrough(clientProtocol, providerProtocol): 判断是否同协议透传
• convertHttpRequest(request, clientProtocol, providerProtocol, provider): 请求转换
• convertHttpResponse(response, clientProtocol, providerProtocol, interfaceType): 响应转换
• createStreamConverter(clientProtocol, providerProtocol, provider): 创建流式转换器

Scenario: 跨协议 Chat 请求转换

• WHEN clientProtocol != providerProtocol 且 interfaceType == CHAT
• THEN SHALL 使用 clientAdapter.detectInterfaceType 识别接口类型
• THEN SHALL 使用 clientAdapter.decodeRequest 解码为 CanonicalRequest
• THEN SHALL 经 middlewareChain 处理
• THEN SHALL 使用 providerAdapter.encodeRequest 编码为目标协议格式
• THEN SHALL 使用 providerAdapter.buildUrl 映射目标 URL
• THEN SHALL 使用 providerAdapter.buildHeaders 构建目标 Header
• THEN SHALL 返回 HTTPRequestSpec{URL, Method, Headers, Body}

Scenario: 同协议透传

• WHEN clientProtocol == providerProtocol 且 supportsPassthrough == true
• THEN SHALL 使用 providerAdapter.buildHeaders 重建 Header
• THEN SHALL 原样传递请求 Body
• THEN SHALL NOT 执行 decode/encode 转换

Scenario: 未知接口透传

• WHEN clientAdapter.detectInterfaceType 返回 PASSTHROUGH 类型
• THEN SHALL 使用 providerAdapter.buildUrl 和 buildHeaders 适配 URL 和 Header
• THEN SHALL 原样传递请求 Body

Requirement: 定义 StreamDecoder/StreamEncoder/StreamConverter 接口

系统 SHALL 定义流式转换的三层接口。

StreamDecoder SHALL 接口：

• processChunk(rawChunk): 原始字节 → CanonicalStreamEvent 数组
• flush(): 刷新缓冲区 → CanonicalStreamEvent 数组

StreamEncoder SHALL 接口：

• encodeEvent(event): CanonicalStreamEvent → SSE 字节数组
• flush(): 刷新缓冲区 → SSE 字节数组

StreamConverter SHALL 接口：

• processChunk(rawChunk): 原始字节 → SSE 字节数组
• flush(): 刷新 → SSE 字节数组

Scenario: PassthroughStreamConverter

• WHEN 同协议透传时
• THEN SHALL 直接传递原始 SSE 字节，不做任何解析或转换

Scenario: CanonicalStreamConverter

• WHEN 跨协议转换时
• THEN SHALL 使用 providerAdapter 的 StreamDecoder 解码原始 SSE
• THEN SHALL 经 middlewareChain 处理事件
• THEN SHALL 使用 clientAdapter 的 StreamEncoder 编码为目标 SSE 格式

Requirement: 定义 ConversionMiddleware 接口

系统 SHALL 定义 ConversionMiddleware 接口，用于在 decode→encode 之间拦截转换。

• intercept(canonical, clientProtocol, providerProtocol, context): 修改或拒绝 Canonical
• interceptStreamEvent(event, clientProtocol, providerProtocol, context): 修改或拒绝流式事件

Scenario: Middleware 链式执行

• WHEN 注册多个 Middleware
• THEN SHALL 按注册顺序链式执行
• THEN 任一 Middleware 返回错误 SHALL 中断后续执行

Scenario: Middleware 中断转换

• WHEN Middleware 返回 ConversionError
• THEN SHALL 停止转换流程
• THEN SHALL 使用 clientAdapter.encodeError 编码错误响应

Requirement: 定义 ConversionError 错误体系

系统 SHALL 定义 ConversionError 和 ErrorCode 枚举。

ErrorCode SHALL 包含：INVALID_INPUT、MISSING_REQUIRED_FIELD、INCOMPATIBLE_FEATURE、FIELD_MAPPING_FAILURE、TOOL_CALL_PARSE_ERROR、JSON_PARSE_ERROR、STREAM_STATE_ERROR、UTF8_DECODE_ERROR、PROTOCOL_CONSTRAINT_VIOLATION、ENCODING_FAILURE、INTERFACE_NOT_SUPPORTED。

Scenario: 转换错误包含上下文

• WHEN 转换过程中发生错误
• THEN ConversionError SHALL 包含 code、message、clientProtocol、providerProtocol、interfaceType 等上下文
• THEN SHALL 支持包装原始错误（cause）

Requirement: 定义 InterfaceType 枚举和接口分层

系统 SHALL 定义 InterfaceType 枚举（CHAT、MODELS、MODEL_INFO、EMBEDDINGS、RERANK）和接口分层策略。

• 核心层（CHAT）：使用 Canonical Model 深度转换
• 扩展层（MODELS、MODEL_INFO、EMBEDDINGS、RERANK）：使用轻量 Canonical Models 做字段映射
• 透传层（未知接口）：URL+Header 适配后 Body 原样转发

Scenario: 扩展层接口转换

• WHEN interfaceType 为 MODELS/MODEL_INFO/EMBEDDINGS/RERANK
• THEN SHALL 使用对应扩展层 Canonical Model 做轻量字段映射
• THEN 双方都不支持时 SHALL 走透传逻辑

Requirement: <20><>义 TargetProvider 结构体

系统 SHALL 定义 TargetProvider 结构体，包含 base_url、api_key、model_name、adapter_config。

Scenario: Adapter 从 TargetProvider 获取配置

• WHEN Adapter 调用 buildHeaders(provider)
• THEN SHALL 从 provider.api_key 提取认证信息
• THEN SHALL 从 provider.adapter_config 提取协议专属配置
• THEN SHALL 使用 provider.model_name 覆盖请求中的 model 字段

Requirement: 跨协议响应转换支持 model 覆写

ConversionEngine SHALL 在跨协议响应转换时支持 model 字段覆写。

Scenario: ConvertHttpResponse 接收 modelOverride 参数

• WHEN 调用 ConvertHttpResponse 时传入 modelOverride 参数（跨协议场景，非空字符串）
• THEN SHALL 在解码上游响应到 canonical 后，将 Model 字段设为 modelOverride
• THEN SHALL 使用覆写后的 canonical 编码为客户端协议格式

Scenario: modelOverride 为空

• WHEN 调用 ConvertHttpResponse 时 modelOverride 为空字符串
• THEN SHALL NOT 覆写 canonical 的 Model 字段，保持上游原始值

Scenario: Chat 响应 model 覆写

• WHEN 跨协议转换 Chat 类型响应且 modelOverride 非空
• THEN CanonicalResponse.Model SHALL 被设为 modelOverride

Scenario: Embedding 响应 model 覆写

• WHEN 跨协议转换 Embedding 类型响应且 modelOverride 非空
• THEN CanonicalEmbeddingResponse.Model SHALL 被设为 modelOverride

Scenario: Rerank 响应 model 覆写

• WHEN 跨协议转换 Rerank 类型响应且 modelOverride 非空
• THEN CanonicalRerankResponse.Model SHALL 被设为 modelOverride

Requirement: 跨协议流式转换支持 model 覆写

ConversionEngine SHALL 在跨协议流式转换时支持 model 字段覆写。

Scenario: CreateStreamConverter 接收 modelOverride 参数

• WHEN 调用 CreateStreamConverter 时传入 modelOverride 参数（跨协议场景）
• THEN SHALL 在流式 canonical 事件中将 Model 字段设为 modelOverride

Requirement: TargetProvider 字段语义

TargetProvider 的 ModelName 字段 SHALL 存储上游供应商的模型名称（即 model_name 字段值），语义保持不变。

Scenario: encoder 使用 TargetProvider.ModelName

• WHEN 协议适配器编码请求时
• THEN SHALL 使用 TargetProvider.ModelName 作为发给上游的 model 字段值（值为路由结果中的 model_name）

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: 上游 URL 构建使用目标协议 Adapter

ConversionEngine SHALL 始终使用目标供应商协议的 adapter 构建上游 URL 路径，避免客户端协议 nativePath 中的版本段泄露到目标协议上游 URL。

Scenario: OpenAI 客户端到 OpenAI 供应商

• WHEN clientProtocol 为 openai，providerProtocol 为 openai，nativePath 为 /v1/chat/completions
• THEN ConversionEngine SHALL 调用 OpenAI adapter 的 BuildUrl(nativePath, InterfaceTypeChat)
• THEN 上游 path SHALL 为 /chat/completions
• THEN 当 provider.base_url 为 https://api.openai.com/v1 时，最终上游 URL SHALL 为 https://api.openai.com/v1/chat/completions

Scenario: OpenAI 客户端到 Anthropic 供应商

• WHEN clientProtocol 为 openai，providerProtocol 为 anthropic，nativePath 为 /v1/chat/completions
• THEN ConversionEngine SHALL 使用 OpenAI adapter 识别接口类型为 InterfaceTypeChat
• THEN ConversionEngine SHALL 调用 Anthropic adapter 的 BuildUrl(nativePath, InterfaceTypeChat)
• THEN 上游 path SHALL 为 /v1/messages
• THEN OpenAI nativePath 中的 /v1/chat/completions SHALL NOT 被直接拼接到 Anthropic 上游 URL

Scenario: Anthropic 客户端到 OpenAI 供应商

• WHEN clientProtocol 为 anthropic，providerProtocol 为 openai，nativePath 为 /v1/messages
• THEN ConversionEngine SHALL 使用 Anthropic adapter 识别接口类型为 InterfaceTypeChat
• THEN ConversionEngine SHALL 调用 OpenAI adapter 的 BuildUrl(nativePath, InterfaceTypeChat)
• THEN 上游 path SHALL 为 /chat/completions
• THEN 当 provider.base_url 为 https://api.openai.com/v1 时，最终上游 URL SHALL 为 https://api.openai.com/v1/chat/completions

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