Initial commit

src/api/handlers/claude_cli/__init__.py

@@ -0,0 +1,11 @@
+"""
+Claude CLI 透传处理器
+"""
+
+from src.api.handlers.claude_cli.adapter import ClaudeCliAdapter
+from src.api.handlers.claude_cli.handler import ClaudeCliMessageHandler
+
+__all__ = [
+    "ClaudeCliAdapter",
+    "ClaudeCliMessageHandler",
+]

src/api/handlers/claude_cli/adapter.py

@@ -0,0 +1,103 @@
+"""
+Claude CLI Adapter - 基于通用 CLI Adapter 基类的简化实现
+
+继承 CliAdapterBase，只需配置 FORMAT_ID 和 HANDLER_CLASS。
+"""
+
+from typing import Any, Dict, Optional, Type
+
+from fastapi import Request
+
+from src.api.handlers.base.cli_adapter_base import CliAdapterBase, register_cli_adapter
+from src.api.handlers.base.cli_handler_base import CliMessageHandlerBase
+from src.api.handlers.claude.adapter import ClaudeCapabilityDetector
+
+
+@register_cli_adapter
+class ClaudeCliAdapter(CliAdapterBase):
+    """
+    Claude CLI API 适配器
+
+    处理 Claude CLI 格式的请求（/v1/messages 端点，使用 Bearer 认证）。
+    """
+
+    FORMAT_ID = "CLAUDE_CLI"
+    name = "claude.cli"
+
+    @property
+    def HANDLER_CLASS(self) -> Type[CliMessageHandlerBase]:
+        """延迟导入 Handler 类避免循环依赖"""
+        from src.api.handlers.claude_cli.handler import ClaudeCliMessageHandler
+
+        return ClaudeCliMessageHandler
+
+    def __init__(self, allowed_api_formats: Optional[list[str]] = None):
+        super().__init__(allowed_api_formats or ["CLAUDE_CLI"])
+
+    def extract_api_key(self, request: Request) -> Optional[str]:
+        """从请求中提取 API 密钥 (Authorization: Bearer)"""
+        authorization = request.headers.get("authorization")
+        if authorization and authorization.startswith("Bearer "):
+            return authorization.replace("Bearer ", "")
+        return None
+
+    def detect_capability_requirements(
+        self,
+        headers: Dict[str, str],
+        request_body: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, bool]:
+        """检测 Claude CLI 请求中隐含的能力需求"""
+        return ClaudeCapabilityDetector.detect_from_headers(headers)
+
+    # =========================================================================
+    # Claude CLI 特定的计费逻辑
+    # =========================================================================
+
+    def compute_total_input_context(
+        self,
+        input_tokens: int,
+        cache_read_input_tokens: int,
+        cache_creation_input_tokens: int = 0,
+    ) -> int:
+        """
+        计算 Claude CLI 的总输入上下文（用于阶梯计费判定）
+
+        Claude 的总输入 = input_tokens + cache_creation_input_tokens + cache_read_input_tokens
+        """
+        return input_tokens + cache_creation_input_tokens + cache_read_input_tokens
+
+    def _extract_message_count(self, payload: Dict[str, Any]) -> int:
+        """Claude CLI 使用 messages 字段"""
+        messages = payload.get("messages", [])
+        return len(messages) if isinstance(messages, list) else 0
+
+    def _build_audit_metadata(
+        self,
+        payload: Dict[str, Any],
+        path_params: Optional[Dict[str, Any]] = None,  # noqa: ARG002
+    ) -> Dict[str, Any]:
+        """Claude CLI 特定的审计元数据"""
+        model = payload.get("model", "unknown")
+        stream = payload.get("stream", False)
+        messages = payload.get("messages", [])
+
+        role_counts = {}
+        for msg in messages:
+            role = msg.get("role", "unknown")
+            role_counts[role] = role_counts.get(role, 0) + 1
+
+        return {
+            "action": "claude_cli_request",
+            "model": model,
+            "stream": bool(stream),
+            "max_tokens": payload.get("max_tokens"),
+            "messages_count": len(messages),
+            "message_roles": role_counts,
+            "temperature": payload.get("temperature"),
+            "top_p": payload.get("top_p"),
+            "tool_count": len(payload.get("tools") or []),
+            "system_present": bool(payload.get("system")),
+        }
+
+
+__all__ = ["ClaudeCliAdapter"]

src/api/handlers/claude_cli/handler.py

@@ -0,0 +1,195 @@
+"""
+Claude CLI Message Handler - 基于通用 CLI Handler 基类的简化实现
+
+继承 CliMessageHandlerBase，只需覆盖格式特定的配置和事件处理逻辑。
+验证新架构的有效性：代码量从数百行减少到 ~80 行。
+"""
+
+from typing import Any, Dict, Optional
+
+from src.api.handlers.base.cli_handler_base import (
+    CliMessageHandlerBase,
+    StreamContext,
+)
+
+
+class ClaudeCliMessageHandler(CliMessageHandlerBase):
+    """
+    Claude CLI Message Handler - 处理 Claude CLI API 格式
+
+    使用新三层架构 (Provider -> ProviderEndpoint -> ProviderAPIKey)
+    通过 FallbackOrchestrator 实现自动故障转移、健康监控和并发控制
+
+    响应格式特点：
+    - 使用 content[] 数组
+    - 使用 text 类型
+    - 流式事件：message_start, content_block_delta, message_delta, message_stop
+    - 支持 cache_creation_input_tokens 和 cache_read_input_tokens
+
+    模型字段：请求体顶级 model 字段
+    """
+
+    FORMAT_ID = "CLAUDE_CLI"
+
+    def extract_model_from_request(
+        self,
+        request_body: Dict[str, Any],
+        path_params: Optional[Dict[str, Any]] = None,  # noqa: ARG002
+    ) -> str:
+        """
+        从请求中提取模型名 - Claude 格式实现
+
+        Claude API 的 model 在请求体顶级字段。
+
+        Args:
+            request_body: 请求体
+            path_params: URL 路径参数（Claude 不使用）
+
+        Returns:
+            模型名
+        """
+        model = request_body.get("model")
+        return str(model) if model else "unknown"
+
+    def apply_mapped_model(
+        self,
+        request_body: Dict[str, Any],
+        mapped_model: str,
+    ) -> Dict[str, Any]:
+        """
+        Claude API 的 model 在请求体顶级
+
+        Args:
+            request_body: 原始请求体
+            mapped_model: 映射后的模型名
+
+        Returns:
+            更新了 model 字段的请求体
+        """
+        result = dict(request_body)
+        result["model"] = mapped_model
+        return result
+
+    def _process_event_data(
+        self,
+        ctx: StreamContext,
+        event_type: str,
+        data: Dict[str, Any],
+    ) -> None:
+        """
+        处理 Claude CLI 格式的 SSE 事件
+
+        事件类型：
+        - message_start: 消息开始，包含初始 usage（含缓存 tokens）
+        - content_block_delta: 文本增量
+        - message_delta: 消息增量，包含最终 usage
+        - message_stop: 消息结束
+        """
+        # 处理 message_start 事件
+        if event_type == "message_start":
+            message = data.get("message", {})
+            if message.get("id"):
+                ctx.response_id = message["id"]
+
+            # 提取初始 usage（包含缓存 tokens）
+            usage = message.get("usage", {})
+            if usage:
+                ctx.input_tokens = usage.get("input_tokens", 0)
+                # Claude 的缓存 tokens 使用不同的字段名
+                cache_read = usage.get("cache_read_input_tokens", 0)
+                if cache_read:
+                    ctx.cached_tokens = cache_read
+                cache_creation = usage.get("cache_creation_input_tokens", 0)
+                if cache_creation:
+                    ctx.cache_creation_tokens = cache_creation
+
+        # 处理文本增量
+        elif event_type == "content_block_delta":
+            delta = data.get("delta", {})
+            if delta.get("type") == "text_delta":
+                text = delta.get("text", "")
+                if text:
+                    ctx.collected_text += text
+
+        # 处理消息增量（包含最终 usage）
+        elif event_type == "message_delta":
+            usage = data.get("usage", {})
+            if usage:
+                if "input_tokens" in usage:
+                    ctx.input_tokens = usage["input_tokens"]
+                if "output_tokens" in usage:
+                    ctx.output_tokens = usage["output_tokens"]
+                # 更新缓存 tokens
+                if "cache_read_input_tokens" in usage:
+                    ctx.cached_tokens = usage["cache_read_input_tokens"]
+                if "cache_creation_input_tokens" in usage:
+                    ctx.cache_creation_tokens = usage["cache_creation_input_tokens"]
+
+            # 检查是否结束
+            delta = data.get("delta", {})
+            if delta.get("stop_reason"):
+                ctx.has_completion = True
+                ctx.final_response = data
+
+        # 处理消息结束
+        elif event_type == "message_stop":
+            ctx.has_completion = True
+
+    def _extract_response_metadata(
+        self,
+        response: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """
+        从 Claude 响应中提取元数据
+
+        提取 model、stop_reason 等字段作为元数据。
+
+        Args:
+            response: Claude API 响应
+
+        Returns:
+            提取的元数据字典
+        """
+        metadata: Dict[str, Any] = {}
+
+        # 提取模型名称（实际使用的模型）
+        if "model" in response:
+            metadata["model"] = response["model"]
+
+        # 提取停止原因
+        if "stop_reason" in response:
+            metadata["stop_reason"] = response["stop_reason"]
+
+        # 提取消息 ID
+        if "id" in response:
+            metadata["message_id"] = response["id"]
+
+        # 提取消息类型
+        if "type" in response:
+            metadata["type"] = response["type"]
+
+        return metadata
+
+    def _finalize_stream_metadata(self, ctx: StreamContext) -> None:
+        """
+        从流上下文中提取最终元数据
+
+        在流传输完成后调用，从收集的事件中提取元数据。
+
+        Args:
+            ctx: 流上下文
+        """
+        # 从 response_id 提取消息 ID
+        if ctx.response_id:
+            ctx.response_metadata["message_id"] = ctx.response_id
+
+        # 从 final_response 提取停止原因（message_delta 事件中的 delta.stop_reason）
+        if ctx.final_response:
+            delta = ctx.final_response.get("delta", {})
+            if "stop_reason" in delta:
+                ctx.response_metadata["stop_reason"] = delta["stop_reason"]
+
+        # 记录模型名称
+        if ctx.model:
+            ctx.response_metadata["model"] = ctx.model
+