lanyuanxiaoyao
b7e205f4b6
## 主要变更 **核心修改**： - 路由定义：/:protocol/v1/*path → /:protocol/*path - proxy_handler：nativePath 直接使用 path 参数，不添加 /v1 前缀 - OpenAI 适配器：DetectInterfaceType 和 BuildUrl 去掉 /v1 前缀 - Anthropic 适配器：保持 /v1 前缀（Claude Code 兼容） **URL 格式变化**： - OpenAI: /openai/v1/chat/completions → /openai/chat/completions - Anthropic: /anthropic/v1/messages (保持不变) **base_url 配置**： - OpenAI: 配置到版本路径，如 https://api.openai.com/v1 - Anthropic: 不配置版本路径，如 https://api.anthropic.com ## 测试验证 - 所有单元测试通过 - 所有集成测试通过 - 真实 API 测试验证成功 - 跨协议转换正常工作 ## 文档更新 - 更新 backend/README.md URL 格式说明 - 同步 OpenSpec 规范文件
63 lines
2.8 KiB
Markdown
63 lines
2.8 KiB
Markdown
# Anthropic Protocol Proxy
|
||
|
||
## Purpose
|
||
|
||
定义 Anthropic Messages API 端点的协议代理行为，包括请求处理流程、同协议透传和双向协议转换。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 支持 Anthropic Messages API 端点
|
||
|
||
网关 SHALL 提供 Anthropic Messages API 端点供外部应用调用。
|
||
|
||
#### Scenario: 成功的非流式请求
|
||
|
||
- **WHEN** 应用发送 POST 请求到 `/anthropic/v1/messages`，携带有效的 Anthropic 请求格式（非流式）
|
||
- **THEN** 网关 SHALL 通过 ConversionEngine 将 Anthropic 请求解码为 Canonical 格式
|
||
- **THEN** 网关 SHALL 将 Canonical 请求编码为目标供应商协议格式
|
||
- **THEN** 网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 Anthropic 格式返回给应用
|
||
|
||
#### Scenario: 成功的流式请求
|
||
|
||
- **WHEN** 应用发送 POST 请求到 `/anthropic/v1/messages`，携带 `stream: true`
|
||
- **THEN** 网关 SHALL 通过 ConversionEngine 创建 StreamConverter
|
||
- **THEN** 网关 SHALL 将上游协议的 SSE 流转换为 Anthropic 命名事件格式
|
||
- **THEN** 网关 SHALL 使用 `event: <type>\ndata: <json>\n\n` 格式流式返回给应用
|
||
|
||
#### Scenario: 同协议透传（Anthropic → Anthropic Provider）
|
||
|
||
- **WHEN** 客户端使用 Anthropic 协议且目标供应商也是 Anthropic 协议
|
||
- **THEN** 网关 SHALL 跳过 Canonical 转换，仅重建认证 Header 后原样转发
|
||
- **THEN** 请求和响应 Body SHALL 保持原样
|
||
|
||
### Requirement: 双向协议转换
|
||
|
||
网关 SHALL 支持 Anthropic 协议与任意已注册协议间的双向转换。
|
||
|
||
#### Scenario: Anthropic 客户端 → OpenAI 供应商
|
||
|
||
- **WHEN** 客户端使用 Anthropic 协议且供应商使用 OpenAI 协议
|
||
- **THEN** SHALL 将 Anthropic MessagesRequest 解码为 CanonicalRequest
|
||
- **THEN** SHALL 将 CanonicalRequest 编码为 OpenAI ChatCompletionRequest
|
||
- **THEN** SHALL 将 OpenAI ChatCompletionResponse 解码为 CanonicalResponse
|
||
- **THEN** SHALL 将 CanonicalResponse 编码为 Anthropic MessagesResponse
|
||
|
||
#### Scenario: OpenAI 客户端 → Anthropic 供应商
|
||
|
||
- **WHEN** 客户端使用 OpenAI 协议且供应商使用 Anthropic 协议
|
||
- **THEN** SHALL 将 OpenAI ChatCompletionRequest 解码为 CanonicalRequest
|
||
- **THEN** SHALL 将 CanonicalRequest 编码为 Anthropic MessagesRequest
|
||
- **THEN** SHALL 将 Anthropic MessagesResponse 解码为 CanonicalResponse
|
||
- **THEN** SHALL 将 CanonicalResponse 编码为 OpenAI ChatCompletionResponse
|
||
|
||
### Requirement: Anthropic 端点保持 v1 层级
|
||
|
||
Anthropic 协议的对外端点 SHALL 保持 `/v1` 层级以兼容 Claude Code。
|
||
|
||
#### Scenario: Claude Code 调用 Anthropic 端点
|
||
|
||
- **WHEN** Claude Code 发送请求到 `/anthropic/v1/messages`
|
||
- **THEN** 网关 SHALL 正确处理请求
|
||
- **THEN** nativePath SHALL 为 `/v1/messages`
|
||
- **THEN** 最终上游 URL SHALL 为 `base_url + /v1/messages`
|