nex/openspec/specs/anthropic-protocol-proxy/spec.md

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 剥离 /anthropic 前缀并将 /v1/messages 作为 Anthropic nativePath
• THEN 网关 SHALL 通过 ConversionEngine 将 Anthropic 请求解码为 Canonical 格式
• THEN 网关 SHALL 将 Canonical 请求编码为目标供应商协议格式
• THEN 若上游返回 2xx，网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 Anthropic 格式返回给应用

Scenario: 成功的流式请求

• WHEN 应用发送 POST 请求到 /anthropic/v1/messages，携带 stream: true
• THEN 网关 SHALL 通过 ConversionEngine 创建 StreamConverter 或使用同协议流式透传路径
• THEN 网关 SHALL 将上游协议的 SSE 流转换为 Anthropic 命名事件格式，或在同协议 raw passthrough 下透传 Anthropic SSE
• THEN 网关 SHALL 使用 event: <type>\ndata: <json>\n\n 格式流式返回给应用

Scenario: 同协议透传（Anthropic → Anthropic Provider）

• WHEN 客户端使用 Anthropic 协议且目标供应商也是 Anthropic 协议
• THEN 网关 SHALL 跳过 Canonical 转换
• THEN 网关 SHALL 使用 Anthropic adapter 重建上游 URL 和认证 Header
• THEN 若请求使用统一模型 ID，网关 SHALL 仅通过 Smart Passthrough 改写 model 字段

Requirement: 双向协议转换

网关 SHALL 支持 Anthropic 协议与任意已注册协议间的双向转换。

Scenario: Anthropic 客户端 → OpenAI 供应商

• WHEN 客户端使用 Anthropic 协议且供应商使用 OpenAI 协议
• THEN SHALL 将 Anthropic MessagesRequest 解码为 CanonicalRequest
• THEN SHALL 将 CanonicalRequest 编码为 OpenAI ChatCompletionRequest
• THEN 若上游返回 2xx，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 若上游返回 2xx，SHALL 将 Anthropic MessagesResponse 解码为 CanonicalResponse
• THEN SHALL 将 CanonicalResponse 编码为 OpenAI ChatCompletionResponse

Scenario: 上游错误透传

• WHEN Anthropic 代理请求收到上游非 2xx HTTP 响应
• THEN 网关 SHALL 直接透传上游 status code、过滤后的 headers 和 body
• THEN 网关 SHALL NOT 将上游错误转换为 Anthropic 错误格式

Requirement: Anthropic 端点保持 v1 层级

Anthropic 协议的对外端点 SHALL 保持 /v1 层级以匹配 Anthropic 原生路径约定。

Scenario: Claude Code 调用 Anthropic 端点

• WHEN Claude Code 发送请求到 /anthropic/v1/messages
• THEN 网关 SHALL 正确处理请求
• THEN nativePath SHALL 为 /v1/messages
• THEN 最终上游 URL SHALL 为 base_url + /v1/messages

Requirement: Anthropic 上游路径映射

Anthropic adapter SHALL 将剥离协议前缀后的 Anthropic nativePath 映射为 Anthropic 上游路径。

Scenario: Messages 上游路径

• WHEN nativePath 为 /v1/messages
• THEN Anthropic adapter BuildUrl SHALL 返回 /v1/messages

Scenario: Models 上游路径

• WHEN nativePath 为 /v1/models
• THEN Anthropic adapter BuildUrl SHALL 返回 /v1/models