3.3 KiB
3.3 KiB
Why
当前 conversion/proxy 层的错误处理和流式透传行为与最新产品决策不一致；路径文档也需要明确职责边界：网关只剥离 /{protocol} 前缀，不对剩余路径做版本号归一化，是否包含 /v1 由具体协议 adapter 处理。
这次调整在应用上线前完成，可以避免错误的路径抽象固化，并为后续新增接口和多模态转换打好边界。
What Changes
- 明确网关路径职责：只剥离协议前缀
/{protocol}，剩余 path 原样作为客户端协议 nativePath 交给 adapter。 - 明确不同协议的对外路径由协议自身决定，不做跨协议统一：OpenAI 使用
/openai/chat/completions、/openai/models、/openai/embeddings、/openai/rerank；Anthropic 使用/anthropic/v1/messages、/anthropic/v1/models、/anthropic/v1/models/{provider_id}/{model_name}。 - 明确
base_url约定不变：OpenAI 配置到版本路径一级（如http://xxx.com/v1），Anthropic 配置到域名级（如http://xxx.com）。 - adapter 负责识别剥离协议前缀后的协议原生 nativePath，并通过 BuildUrl 产出真实上游路径。
- 同协议流式无 model 改写时直接透传上游 SSE 字节；需要 model 改写时按 SSE frame 解析和重建，只改写 data JSON 内的 model 字段。
- 网关层错误使用应用统一错误格式
{error, code}；上游已经返回 HTTP 响应时，非 2xx 状态码、headers、body 直接透传，不进入协议转换。 - 只有 adapter 明确适配的接口才提取 model 并参与统一模型 ID 路由；未知接口不做通用 model 猜测，按无 model 透传处理。
- 多模态占位保留；本次不实现多模态转换，跨协议检测到 image/audio/video/file 时返回网关层不支持错误。
- 本次不调整统计口径。
Capabilities
New Capabilities
- 无
Modified Capabilities
unified-proxy-handler: 修改 nativePath 语义、同协议流式透传、上游错误透传和未知接口路由规则。openai-protocol-proxy: 明确 OpenAI 对外路径和 adapter 接收的 nativePath 形态，并约束流式完成标记和上游错误透传行为。anthropic-protocol-proxy: 明确 Anthropic 对外路径保持/v1层级、adapter 接收/v1/...nativePath、上游 URL 由base_url + nativePath/BuildUrl 组合得到。error-responses: 增加网关层统一错误码设计，并明确代理接口中上游错误透传、不做协议错误包装。conversion-engine: 约束同协议 Smart Passthrough 的 URL 构建、SSE frame 级 model 改写、adapter 模型提取边界和跨协议多模态暂不支持行为。
Impact
- 后端代理入口：
backend/internal/handler/proxy_handler.go - 供应商客户端流式接口：
backend/internal/provider/client.go - 转换引擎和流式转换器：
backend/internal/conversion/engine.go、backend/internal/conversion/stream.go - OpenAI/Anthropic adapter：
backend/internal/conversion/openai/*、backend/internal/conversion/anthropic/* - 错误处理公共逻辑：
backend/pkg/errors、handler 错误响应逻辑 - 测试：conversion 单测、adapter 单测、代理集成测试、E2E conversion 测试
- 文档：
README.md、backend/README.md、docs/conversion_design.md - 不引入新依赖，不调整数据库 schema，不调整统计模块