nex/openspec/changes/refactor-conversion-engine/design.md

## Context

### 现有架构

当前后端协议转换以 OpenAI 类型为内部枢纽，整体结构：

```
Anthropic Handler ──▶ anthropic.ConvertRequest() ──▶ openai.ChatCompletionRequest
                                                 │
OpenAI Handler ──────────────────────────────────▶ openai.ChatCompletionRequest
                                                 │
                                                 ▼
                                          ProviderClient
                                          (硬编码 OpenAI Adapter)
                                                 │
                                                 ▼
                                          上游 OpenAI 兼容 API
```

关键文件：
- `internal/protocol/openai/types.go` — OpenAI 线路格式类型，兼作内部枢纽格式
- `internal/protocol/anthropic/converter.go` — Anthropic→OpenAI 单向转换
- `internal/protocol/anthropic/stream_converter.go` — OpenAI chunk→Anthropic SSE 单向流式转换
- `internal/handler/openai_handler.go` — OpenAI 请求处理
- `internal/handler/anthropic_handler.go` — Anthropic 请求处理，内含协议转换编排
- `internal/provider/client.go` — HTTP 客户端，硬编码 `openai.Adapter` 做序列化/反序列化

### 核心限制

1. **单向转换**：只有 Anthropic→OpenAI，无反向能力
2. **OpenAI 绑定**：上游通信只能走 OpenAI 协议
3. **无透传**：即使 client==provider（同协议），仍走完整序列化/反序列化
4. **无扩展性**：新增协议需修改多处代码，无统一接入点
5. **仅 Chat**：只支持 `/v1/chat/completions` 和 `/v1/messages` 两个固定端点，无 Models/Embeddings/Rerank

### 设计参考

三份设计文档已完整定义目标架构和两个协议的适配细节：
- `docs/conversion_design.md` — 整体架构（Hub-and-Spoke、Canonical Model、ProtocolAdapter 接口、ConversionEngine、流式管道、错误处理）
- `docs/conversion_openai.md` — OpenAI 协议适配清单（字段映射、流式状态机、角色合并等）
- `docs/conversion_anthropic.md` — Anthropic 协议适配清单（角色约束、thinking、流式命名事件等）

## Goals / Non-Goals

**Goals:**

- 实现完整的 Hub-and-Spoke 协议转换架构，以 Canonical Model 为枢纽
- 支持任意协议对的请求/响应双向转换（当前：OpenAI ↔ Anthropic）
- 支持同协议透传（零语义损失、零序列化开销）
- 支持流式 SSE 双向转换（含 Tool Calling、Thinking）
- 支持 Chat 核心层 + Models/Embeddings/Rerank 扩展层 + 未知接口透传
- ProviderClient 支持多协议上游通信
- 统一代理入口，URL 路由支持协议前缀

**Non-Goals:**

- 本阶段不实现多模态（Image/Audio/Video），Canonical Model 仅预留扩展点
- 不实现 Middleware 的具体业务逻辑（仅定义接口和 Chain）
- 不实现新的协议 Adapter（除 OpenAI 和 Anthropic 外）
- 不实现有状态特性（架构预留 StatefulMiddleware 接口）
- 不实现前端管理界面的协议选择功能
- 不修改前端代码（前端使用管理 API，代理 API 路由变更对前端透明）

## Decisions

### D1: Canonical Model 用独立 Go 结构体实现，不使用 `interface{}` 或 `map[string]any`

**选择**：为 CanonicalRequest、CanonicalResponse、CanonicalStreamEvent 等定义强类型 Go struct，ContentBlock 使用 discriminated union 模式（type 字段 + 各类型嵌入）

**理由**：
- 编译期类型安全，IDE 自动补全和重构友好
- 性能优于 `map[string]any`（无反射开销）
- 与 Go 生态的习惯一致

**替代方案**：
- `map[string]any` — 灵活但无类型安全，重构时容易遗漏字段
- 代码生成（如 protobuf）— 引入新依赖和构建步骤，过度工程化

**实现细节**：

```go
type ContentBlock struct {
    Type string `json:"type"`
    // Text
    Text string `json:"text,omitempty"`
    // ToolUse
    ID   string          `json:"id,omitempty"`
    Name string          `json:"name,omitempty"`
    Input json.RawMessage `json:"input,omitempty"`
    // ToolResult
    ToolUseID string `json:"tool_use_id,omitempty"`
    IsError   *bool  `json:"is_error,omitempty"`
    // Thinking
    Thinking string `json:"thinking,omitempty"`
}
```

使用 `json.RawMessage` 保留 Tool Input 的原始 JSON，避免不必要的 `map` 解析。

### D2: ProtocolAdapter 接口集中定义所有方法，不用接口组合

**选择**：一个大的 `ProtocolAdapter` 接口包含所有方法（Chat、流式、扩展层、错误编码），不拆分为小接口

**理由**：
- 对照 `docs/conversion_design.md` §5.2 的定义，接口集中便于明确所有应实现的内容
- Adapter 实现者可一目了然看到所有方法
- 不支持的功能直接返回 false（`supportsInterface`）或空实现
- `detectInterfaceType` 由各协议 Adapter 实现，因为不同协议有不同的 URL 路径约定

**替代方案**：
- 接口组合（ChatAdapter + StreamAdapter + ExtendedAdapter）——增加类型复杂度，Adapter 注册和管理更繁琐
- 用空接口 + 类型断言——丢失编译期检查
- `detectInterfaceType` 放在 ConversionEngine 中——违反开闭原则，新增协议需要修改 Engine

### D3: StreamDecoder 直接解析原始 SSE 字节流

**选择**：`ProviderClient.SendStream()` 返回 `<-chan []byte`（原始 SSE 字节流），`StreamDecoder.processChunk()` 负责拆分 SSE event 并解析 JSON

**理由**：
- SSE 解析与协议语义紧密相关（不同协议的 SSE 格式不同：OpenAI 用 `data:` 无名事件，Anthropic 用命名事件 `event: xxx\ndata: xxx`）
- 减少中间层，降低内存拷贝
- ProviderClient 保持最简——只做 HTTP 请求和字节流读取

**替代方案**：
- ProviderClient 内做 SSE 解析——强制所有上游使用同一 SSE 格式，不符合多协议目标
- 独立 SSE Parser 层——增加不必要的抽象，SSE 格式本身就是 Adapter 职责的一部分

### D4: ProviderClient 接受 `HTTPRequestSpec`，返回 `*HTTPResponseSpec`

**选择**：ConversionEngine 输出 `HTTPRequestSpec{URL, Method, Headers, Body []byte}`，ProviderClient 接收后发送 HTTP 请求；响应返回 `HTTPResponseSpec{StatusCode, Headers, Body []byte}`

**理由**：
- ProviderClient 完全不感知协议，只做 HTTP 通信
- ConversionEngine 统一负责 URL 构建、Header 构建、Body 序列化
- 同协议透传时，Engine 直接透传 body bytes，Client 不做任何序列化/反序列化

**接口定义**：

```go
type HTTPRequestSpec struct {
    URL     string
    Method  string
    Headers map[string]string
    Body    []byte
}

type HTTPResponseSpec struct {
    StatusCode int
    Headers    map[string]string
    Body       []byte
}

type ProviderClient interface {
    Send(ctx context.Context, spec HTTPRequestSpec) (*HTTPResponseSpec, error)
    SendStream(ctx context.Context, spec HTTPRequestSpec) (<-chan StreamEvent, error)
}
```

### D5: 统一代理入口使用 `/{protocol}/v1/...` URL 前缀

**选择**：新路由格式 `/{protocol}/v1/{path}`，handler 从 URL 提取 protocol 前缀作为 clientProtocol

**理由**：
- 符合 `docs/conversion_design.md` §2.2 的设计
- 调用方通过 URL 前缀明确指定协议，无需额外配置
- 统一入口简化 handler 数量

**兼容路由**：不保留旧路由，客户端需迁移到新路由格式。

**替代方案**：
- 保持两个独立 handler——违背统一架构目标
- 请求体嗅探协议——不可靠，且设计文档明确"协议识别是调用方职责"

### D6: Provider 新增 `Protocol` 字段，存储在数据库

**选择**：Provider 表新增 `protocol TEXT DEFAULT 'openai'` 列，用于标识上游供应商使用的协议

**理由**：
- 上游供应商可能是 OpenAI 兼容（大多数）或 Anthropic 原生
- 路由时需要知道 providerProtocol 以选择正确的 Adapter
- 默认值 `'openai'` 确保现有数据兼容

### D7: 删除旧 `internal/protocol/` 包，在 `internal/conversion/` 中全新实现

**选择**：直接删除 `internal/protocol/openai/` 和 `internal/protocol/anthropic/`，在 `internal/conversion/` 下对照设计文档全新编写所有代码

**理由**：
- 旧代码的设计模式（OpenAI 类型为枢纽）与新架构根本不同，无法复用
- 保留旧代码容易导致混用两种模式，引入隐蔽 bug
- 旧代码中的类型定义不迁移，直接根据设计文档重新定义，确保与新架构一致

### D8: 目标包结构

```
internal/conversion/
  canonical/
    types.go                     # CanonicalRequest/Response/Message/ContentBlock/Tool/ToolChoice/ThinkingConfig/OutputFormat
    stream.go                    # CanonicalStreamEvent 联合体 + 所有事件类型
    extended.go                  # CanonicalModelList/ModelInfo/Embedding/Rerank
  errors.go                      # ConversionError + ErrorCode 枚举
  interface.go                   # InterfaceType 枚举
  provider.go                    # TargetProvider struct
  adapter.go                     # ProtocolAdapter 接口 + AdapterRegistry 接口和实现
  stream.go                      # StreamDecoder/StreamEncoder/StreamConverter 接口 + Passthrough/Canonical 实现
  middleware.go                   # ConversionMiddleware 接口 + MiddlewareChain
  engine.go                      # ConversionEngine 门面 + HTTPRequestSpec/HTTPResponseSpec

  openai/
    types.go                     # OpenAI 线路格式类型（对照 conversion_openai.md 全新定义）
    adapter.go                   # ProtocolAdapter 实现（detectInterfaceType/buildUrl/buildHeaders/supportsInterface/encodeError）
    decoder.go                   # decodeRequest/decodeResponse/扩展层 decode 方法
    encoder.go                   # encodeRequest/encodeResponse/扩展层 encode 方法
    stream_decoder.go            # OpenAIStreamDecoder（delta chunk 状态机）
    stream_encoder.go            # OpenAIStreamEncoder（缓冲策略）

  anthropic/
    types.go                     # Anthropic 线路格式类型（对照 conversion_anthropic.md 全新定义）
    adapter.go                   # ProtocolAdapter 实现（detectInterfaceType/buildUrl/buildHeaders/supportsInterface/encodeError）
    decoder.go                   # decodeRequest/decodeResponse/扩展层 decode 方法
    encoder.go                   # encodeRequest/encodeResponse/扩展层 encode 方法
    stream_decoder.go            # AnthropicStreamDecoder（命名事件 1:1 映射）
    stream_encoder.go            # AnthropicStreamEncoder（直接映射，无缓冲）
```

## Risks / Trade-offs

### R1: Anthropic 角色约束处理复杂度高
**风险**：Anthropic 要求 user/assistant 严格交替、首消息必须为 user、tool_result 必须嵌入 user 消息。从 Canonical 编码为 Anthropic 时需要合并/拆分/注入消息，逻辑容易出错。
**缓解**：
- 编写详尽的测试用例覆盖所有边界情况（连续 tool 消息、首条 assistant 消息、空 user 消息注入等）
- 将角色约束处理封装为独立函数，与内容编码逻辑分离

### R2: OpenAI 流式状态机复杂
**风险**：OpenAI 的 delta chunk 没有显式生命周期（无 start/stop），StreamDecoder 需要状态机推断 block 边界，管理工具调用索引映射和参数累积。
**缓解**：
- 严格对照 `docs/conversion_openai.md` §6.2-§6.3 的伪代码实现
- 为每种 delta 类型编写独立测试（text、tool_calls、reasoning_content、refusal、usage chunk）
- UTF-8 跨 chunk 截断使用 `utf8Remainder` 缓冲

### R3: 全量重构影响范围大
**风险**：同时删除旧代码、新建包、改造 handler/provider/domain，可能导致系统长时间不可用。
**缓解**：
- 旧代码在删除前确认新代码所有测试通过
- Git 分支隔离开发，完成后再合并
- 新路由 `/{protocol}/v1/...` 确保协议明确指定

### R4: Canonical Model 字段演进
**风险**：Canonical Model 的字段集反映当前已适配协议的公共语义，未来新增协议时可能需要频繁修改。
**缓解**：
- 字段晋升规范已在 `docs/conversion_design.md` 附录 C 中定义
- `json:"-"` 标签控制序列化输出，新增可选字段不影响已有编解码
- 协议特有字段不纳入 Canonical，通过同协议透传保留

### R5: 性能——双重序列化开销
**风险**：跨协议转换时经过 decode→canonical→encode 两次序列化/反序列化，相比直接转换多一次拷贝。
**权衡**：接受此开销以换取架构清晰和可扩展性。同协议透传路径零开销补偿。实际 LLM API 延迟（数百毫秒到数秒）远大于 JSON 序列化开销（微秒级）。

## Migration Plan

### 步骤

1. **创建 `internal/conversion/` 包**：实现 Layer 1-3（Canonical Model、接口定义、Engine），不改动现有代码
2. **全新实现 OpenAI Adapter 和 Anthropic Adapter**：Layer 4-5，对照设计文档在 conversion 包内全新编写，不沿用旧 protocol 包代码
3. **编写全面测试**：覆盖编解码、流式转换、错误处理、同协议透传
4. **改造 `domain.Provider`**：新增 `Protocol` 字段
5. **创建数据库迁移**：`ALTER TABLE providers ADD COLUMN protocol TEXT DEFAULT 'openai'`
6. **改造 `ProviderClient`**：简化为接受 `HTTPRequestSpec` 的 HTTP 发送器
7. **创建 `ProxyHandler`**：统一代理入口，集成 ConversionEngine
8. **更新 `cmd/server/main.go`**：注册 Adapter、创建 Engine、配置新路由
9. **删除旧 `internal/protocol/` 包**：直接删除，不迁移代码，确认新架构完全替代
10. **更新 README.md**：项目结构、API 接口、路由说明

### 兼容策略

- 旧路由 `/v1/chat/completions` 和 `/v1/messages` 不再保留，客户端需迁移
- 现有 Provider 数据通过 `DEFAULT 'openai'` 自动获得协议标识
- 前端管理 API 不受影响

### 回滚策略

- Git 分支隔离：在新分支开发，合并前充分测试
- 旧 `internal/protocol/` 包在删除前确认新架构所有测试通过，删除后不可恢复旧代码（从 git 历史仍可找回）
- 数据库迁移向下兼容（仅 ADD COLUMN）

## Open Questions

- ~~是否需要为兼容路由 `/v1/chat/completions` 和 `/v1/messages` 设置 deprecation 期限？~~ → **决定**：不保留旧路由，客户端直接迁移到 `/{protocol}/v1/...`
- ~~扩展层接口（Models/Embeddings/Rerank）在本阶段是否全部实现，还是先做 Models，其余后续迭代？~~ → **决定**：本阶段全部实现（对照三份文档的字段映射已在 spec 中完整定义），因为扩展层接口编解码逻辑量不大（轻量字段映射），且实现后能完整验证引擎的接口分层分发逻辑