nex/openspec/changes/refactor-conversion-engine/proposal.md at 1dac347d3b95f7d75706768e5c037451c1c16a45

Files

lanyuanxiaoyao 1dac347d3b refactor: 实现 ConversionEngine 协议转换引擎，替代旧 protocol 包

引入 Canonical Model 和 ProtocolAdapter 架构，支持 OpenAI/Anthropic 协议间
无缝转换，统一 ProxyHandler 替代分散的 OpenAI/Anthropic Handler，简化
ProviderClient 为协议无关的 HTTP 发送器，Provider 新增 protocol 字段。

2026-04-20 00:36:27 +08:00

5.5 KiB

Raw Blame History

Why

当前后端协议转换层以 OpenAI 类型作为内部枢纽，Anthropic 请求单向转换为 OpenAI 格式后再发往上游。这种设计导致：无法支持 OpenAI→Anthropic 的反向转换、无法对接 Anthropic 协议的上游供应商、无法实现同协议透传的零开销转发、无法横向扩展新协议。重构为基于协议中立 Canonical Model 的 Hub-and-Spoke 架构（参考 docs/conversion_design.md），从根本上解决这些问题。

What Changes

引入 Canonical Model：定义协议无关的 CanonicalRequest、CanonicalResponse、CanonicalStreamEvent 等规范模型，作为所有协议间转换的统一枢纽
引入 ConversionEngine：无状态的转换引擎门面，协调 Adapter 注册、接口识别、透传判断、请求/响应转换、流式转换
引入 ProtocolAdapter 接口：统一适配器契约，每种协议实现完整的编解码（Chat 请求/响应、流式、扩展层接口、错误编码）
实现 OpenAI Adapter：对照 docs/conversion_openai.md 全新实现 OpenAI 协议的完整 Adapter（含状态机流式解码器/编码器），不沿用旧 internal/protocol/openai/ 代码
实现 Anthropic Adapter：对照 docs/conversion_anthropic.md 全新实现 Anthropic 协议的完整 Adapter（含命名事件流式解码器/编码器），不沿用旧 internal/protocol/anthropic/ 代码
统一代理 Handler：合并 OpenAIHandler 和 AnthropicHandler 为统一的 ProxyHandler，支持 /{protocol}/v1/... URL 前缀路由
同协议透传：client == provider 时跳过 Canonical 转换，仅重建 Header 后原样转发
接口分层：核心层（Chat）走 Canonical 深度转换，扩展层（Models/Embeddings/Rerank）走轻量映射，未知接口走透传
ProviderClient 简化：移除 OpenAI Adapter 硬编码，变为协议无关的 HTTP 发送器
Provider 新增 Protocol 字段：BREAKING — Provider 模型新增 protocol 字段标识上游协议类型
删除旧 protocol 包：移除 internal/protocol/openai/ 和 internal/protocol/anthropic/，在 internal/conversion/ 中全新实现
URL 路由变更：BREAKING — 代理端点从 /v1/chat/completions + /v1/messages 变更为 /{protocol}/v1/...，不保留旧路由

Capabilities

New Capabilities

conversion-engine: 协议转换引擎核心能力——Canonical Model 定义、ProtocolAdapter 接口与注册表、ConversionEngine 门面（请求/响应转换、流式转换、接口识别、透传判断）、StreamDecoder/Encoder 接口、Middleware 拦截链、ConversionError 错误体系
protocol-adapter-openai: OpenAI 协议适配器——完整的 ProtocolAdapter 实现（对照 conversion_openai.md），涵盖 Chat 请求/响应编解码、流式状态机解码器（OpenAI delta chunk → CanonicalStreamEvent）和编码器（反向）、扩展层接口编解码（Models/Embeddings/Rerank）、错误编码、同协议透传
protocol-adapter-anthropic: Anthropic 协议适配器——完整的 ProtocolAdapter 实现（对照 conversion_anthropic.md），涵盖 Chat 请求/响应编解码（含角色约束处理：tool→user 合并、user/assistant 交替保证）、流式解码器（命名 SSE 事件 → CanonicalStreamEvent）和编码器（反向）、扩展层接口编解码（Models）、错误编码、同协议透传
unified-proxy-handler: 统一代理入口——合并 OpenAI/Anthropic 双 Handler 为统一 ProxyHandler，支持 /{protocol}/v1/... URL 前缀路由、协议识别

Modified Capabilities

openai-protocol-proxy: URL 路由从硬编码 /v1/chat/completions 变更为 /{protocol}/v1/... 统一入口；请求处理从直接调用 ProviderClient 变更为经 ConversionEngine 转换；新增同协议透传能力；新增扩展层接口（Models/Embeddings/Rerank）代理
anthropic-protocol-proxy: 从单向 Anthropic→OpenAI 转换变更为双向任意协议互转；从 Handler 内直接调用 converter 变更为经 ConversionEngine；新增 Anthropic 作为上游供应商的能力；新增同协议透传能力；新增扩展层接口代理
provider-management: Provider 模型新增 protocol 字段（标识上游协议类型，默认 "openai"）；数据库迁移新增 protocol 列
layered-architecture: 新增 conversion 层（internal/conversion/）位于 handler 和 provider 之间；ProviderClient 接口简化为协议无关的 HTTP 发送器
error-handling: 新增 ConversionError 错误类型和 ErrorCode 枚举；转换失败时使用客户端协议格式编码错误响应
request-validation: 请求验证从 handler 层前移到 ProtocolAdapter 的 decodeRequest 中；验证规则按各协议规范独立定义

Impact

代码结构：新增 internal/conversion/ 包（约 20+ 文件，全新编写），删除 internal/protocol/ 包（不迁移，直接删除后重写），改造 internal/handler/ 和 internal/provider/
API 兼容性：BREAKING — 代理端点 URL 变更（/v1/chat/completions → /openai/v1/chat/completions，/v1/messages → /anthropic/v1/messages），不保留旧路由
数据库：Provider 表新增 protocol 列，需数据库迁移
依赖：无新增外部依赖，复用现有 Go 标准库和已引入的包
测试：需为 conversion 包编写全面单元测试，覆盖每个 Adapter 的编解码、流式转换、错误处理、同协议透传
文档：需更新 README.md 中的项目结构、API 接口说明

5.5 KiB Raw Blame History Unescape Escape

Why