标准化设计

设计目标

OpenTrans 的目标不是写一堆“协议 A -> 协议 B”的点对点桥接，而是建立一层稳定的中间抽象，让协议适配和业务逻辑解耦。

设计上主要追求三件事：

1. 把常见 provider 收敛到统一模型
2. 让开发者能在中间层插入自己的业务逻辑
3. 让新增协议或新增能力时不必重写所有 pairwise conversion

三段式转换链路

OpenTrans 的主链路是：

1. 解析源协议请求体、响应体或流式事件
2. 映射到标准化中间结构
3. 按目标协议重新编码输出

也就是：

source protocol -> canonical model -> target protocol

这带来的直接收益是：

• 协议适配点更清晰
• 业务中间层更稳定
• 新增协议时扩展成本更可控

为什么不用“协议对协议硬编码”

如果系统里有 N 个协议，直接 pairwise 实现通常会带来 N * (N - 1) 级别的桥接成本。

而标准化中间层只要求：

• 每个协议实现一次 protocol -> canonical
• 每个协议实现一次 canonical -> protocol

这会让维护和扩展都更可控。

三类核心模型

对外统一暴露三套核心模型：

• Request
• Response
• StreamEvent

作用分别是：

• Request：统一输入消息、采样参数、工具定义和扩展字段
• Response：统一非流式输出、停止原因、usage 和元信息
• StreamEvent：统一流式事件和增量内容

详细字段见：标准化模型

统一内容单元 ContentPart

ContentPart 是整个中间层设计里最关键的公共部件之一。

它被同时用于：

• Request.Messages[].Content
• Response.Output
• StreamEvent.Delta

当前常见 Type 包括：

• text
• image_url
• image_base64
• tool_call
• tool_result

这意味着图片输入、工具调用、工具结果都能复用同一套工程抽象，而不是在每个 provider 外层重新拼一遍对象结构。

为什么同时保留 Metadata 和 Extra

不同 provider 的协议字段并不总能完全纳入统一模型，所以 OpenTrans 明确保留两类“缓冲区”：

• Metadata：更适合业务层附加信息
• Extra：更适合协议层暂存未标准化字段

这样做的目的不是模糊边界，而是避免在统一层过早丢失有价值的信息。

流式设计原则

流式能力当前优先覆盖最稳定、最常见的公共语义：

• 响应开始
• 文本增量
• 响应结束
• usage

这也是为什么 StreamEvent 当前内置事件类型主要是：

• response_start
• content_delta
• response_stop
• usage

对于更复杂的 provider 私有流语义，OpenTrans 目前采取“尽量保留、逐步标准化”的策略。

对开发者意味着什么

如果你在做这些事情，这套设计会特别有价值：

• 在不同模型供应商之间切换
• 为多个客户暴露不同兼容协议
• 在统一中间层插入审计、日志、缓存、路由逻辑
• 为 Web 服务和 SDK 同时提供稳定转换能力

当前边界

当前设计优先保证：

• 文本输入输出
• 多轮消息
• 基础工具调用
• 图片输入
• 非流式响应
• 常见 SSE 文本流

仍在逐步演进的部分包括：

• 多模态输出统一抽象
• 更完整的 provider 高级字段标准化
• 更复杂的代理级流式语义