## 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,不调整统计模块