46 lines
5.3 KiB
Markdown
46 lines
5.3 KiB
Markdown
## 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（含状态机流式解码器/编码器）
|
||
- **实现 Anthropic Adapter**：对照 `docs/conversion_anthropic.md` 实现 Anthropic 协议的完整 Adapter（含命名事件流式解码器/编码器）
|
||
- **统一代理 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 接口说明
|