update

Author: lrbmike

backend/README.md

@@ -267,4 +267,103 @@ DATABASE_URL=postgres://user:password@localhost:5432/dbname?sslmode=disable
 
 Add PostgreSQL build support in Dockerfile, similar to existing MySQL and SQLite builds.
 
-This extension approach maintains the integrity of the existing architecture while providing flexible database support.
+This extension approach maintains the integrity of the existing architecture while providing flexible database support.
+
+### Adding New LLM Adapters (Adapters)
+
+Adapters are responsible for handling direct communication with upstream LLM APIs, including request building, authentication, and key rotation. Core code is located in `backend/internal/adapters`.
+
+#### 1. Define Adapter Structure
+Implement the `LLMAdapter` interface:
+
+```go
+type LLMAdapter interface {
+    ProcessRequest() (*services.TargetRequest, error)
+}
+```
+
+#### 2. Implement Core Logic
+Embed `BaseLLMAdapter` to reuse common logic (like key rotation):
+
+```go
+type XAIAdapter struct {
+    *BaseLLMAdapter
+}
+
+func (a *XAIAdapter) ProcessRequest() (*services.TargetRequest, error) {
+    // 1. Verify Proxy Key
+    // 2. Rotate Upstream Key
+    upstreamKey, err := a.RotateUpstreamKey()
+    
+    // 3. Build Request (Filtering headers, removing gzip, etc.)
+    headers := utils.FilterRequestHeaders(a.c.Request.Header, []string{"authorization", "accept-encoding"})
+    headers["Authorization"] = "Bearer " + upstreamKey
+    
+    // 4. Return TargetRequest object
+    return &services.TargetRequest{...}, nil
+}
+```
+
+### Extending New API Formats (Converters)
+
+Converters are responsible for handling transformations between client-side formats and backend API expected formats. Core code is located in `backend/internal/converters`.
+
+#### 1. Register New Format
+Register the new format identifier in `backend/internal/converters/formats/registry.go`:
+
+```go
+// Example: Adding a new format identifier
+const (
+    FormatClaudeNative = "claude_native"
+)
+```
+
+#### 2. Implement Format Handler
+Implement the `FormatHandler` interface in `backend/internal/converters/formats/claude_native/`:
+
+```go
+type ClaudeNativeHandler struct{}
+
+// Build Request: Convert universal request format to Claude native format
+func (h *ClaudeNativeHandler) BuildRequest(req *types.UniversalRequest) ([]byte, error) {
+    // Implement conversion logic...
+}
+
+// Parse Response: Convert Claude native response to universal response format
+func (h *ClaudeNativeHandler) ParseResponse(body []byte) (*types.UniversalResponse, error) {
+    // Implement parsing logic...
+}
+```
+
+#### 3. Handle Streaming Responses (Optional)
+If streaming support is required, implement the `StreamHandler` interface to handle SSE (Server-Sent Events) transformations. This is critical for chat interaction experiences.
+
+```go
+type StreamHandler interface {
+    // Parse stream chunk: Parse format-specific SSE data line into universal stream chunk
+    ParseStreamChunk(chunk []byte) (*UniversalStreamChunk, error)
+    
+    // Build stream chunk: Build format-specific SSE data line from universal stream chunk
+    BuildStreamChunk(chunk *UniversalStreamChunk) ([]byte, error)
+    
+    // Build start event (e.g., OpenAI's role delta)
+    BuildStartEvent(model string, id string) [][]byte
+    
+    // Build end event (e.g., [DONE])
+    BuildEndEvent() [][]byte
+}
+```
+
+Implementation Example:
+
+```go
+func (h *ClaudeStreamHandler) ParseStreamChunk(chunk []byte) (*UniversalStreamChunk, error) {
+    // 1. Parse SSE line (e.g., "data: {...}")
+    // 2. Extract content delta
+    // 3. Construct UniversalStreamChunk
+    return &UniversalStreamChunk{
+        Content: deltaContent,
+        FinishReason: finishReason,
+    }, nil
+}
+```

backend/README_CN.md

@@ -269,4 +269,103 @@ DATABASE_URL=postgres://user:password@localhost:5432/dbname?sslmode=disable
 
 在Dockerfile中添加PostgreSQL构建支持，类似于现有的MySQL和SQLite构建。
 
-这样的扩展方式保持了现有架构的完整性，同时提供了灵活的数据库支持。
+这样的扩展方式保持了现有架构的完整性，同时提供了灵活的数据库支持。
+
+### 接入新的LLM适配器 (Adapters)
+
+适配器负责处理与上游 LLM API 的直接通信，包括请求构建、认证和密钥轮询。核心代码位于 `backend/internal/adapters`。
+
+#### 1. 定义适配器结构
+实现 `LLMAdapter` 接口：
+
+```go
+type LLMAdapter interface {
+    ProcessRequest() (*services.TargetRequest, error)
+}
+```
+
+#### 2. 实现核心逻辑
+继承 `BaseLLMAdapter` 以复用通用逻辑（如密钥轮询）：
+
+```go
+type XAIAdapter struct {
+    *BaseLLMAdapter
+}
+
+func (a *XAIAdapter) ProcessRequest() (*services.TargetRequest, error) {
+    // 1. 验证代理密钥 (Proxy Key)
+    // 2. 轮询上游密钥 (Upstream Key)
+    upstreamKey, err := a.RotateUpstreamKey()
+    
+    // 3. 构建请求 (Header处理，移除 Gzip 等)
+    headers := utils.FilterRequestHeaders(a.c.Request.Header, []string{"authorization", "accept-encoding"})
+    headers["Authorization"] = "Bearer " + upstreamKey
+    
+    // 4. 返回目标请求对象
+    return &services.TargetRequest{...}, nil
+}
+```
+
+### 扩展新的API格式 (Converters)
+
+转换器负责处理客户端格式与后端 API 期望格式之间的相互转换。核心代码位于 `backend/internal/converters`。
+
+#### 1. 注册新格式
+在 `backend/internal/converters/formats/registry.go` 中注册新的格式标识：
+
+```go
+// 示例：添加新的格式标识
+const (
+    FormatClaudeNative = "claude_native"
+)
+```
+
+#### 2. 实现格式处理器
+在 `backend/internal/converters/formats/claude_native/` 下实现 `FormatHandler` 接口：
+
+```go
+type ClaudeNativeHandler struct{}
+
+// 转换请求：将通用请求格式转换为 Claude 原生格式
+func (h *ClaudeNativeHandler) BuildRequest(req *types.UniversalRequest) ([]byte, error) {
+    // 实现转换逻辑...
+}
+
+// 转换响应：将 Claude 原生响应转换为通用响应格式
+func (h *ClaudeNativeHandler) ParseResponse(body []byte) (*types.UniversalResponse, error) {
+    // 实现解析逻辑...
+}
+```
+
+#### 3. 处理流式响应 (可选)
+如果需要支持流式传输，还需实现 `StreamHandler` 接口以处理 SSE (Server-Sent Events) 转换。这对于聊天交互体验至关重要。
+
+```go
+type StreamHandler interface {
+    // 解析流分块：将特定格式的 SSE 数据行解析为通用流分块
+    ParseStreamChunk(chunk []byte) (*UniversalStreamChunk, error)
+    
+    // 构建流分块：将通用流分块构建为特定格式的 SSE 数据行
+    BuildStreamChunk(chunk *UniversalStreamChunk) ([]byte, error)
+    
+    // 构建起始事件 (如 OpenAI 的 role delta)
+    BuildStartEvent(model string, id string) [][]byte
+    
+    // 构建结束事件 (如 [DONE])
+    BuildEndEvent() [][]byte
+}
+```
+
+实现示例：
+
+```go
+func (h *ClaudeStreamHandler) ParseStreamChunk(chunk []byte) (*UniversalStreamChunk, error) {
+    // 1. 解析 SSE 行 (e.g., "data: {...}")
+    // 2. 提取 content delta
+    // 3. 构造 UniversalStreamChunk
+    return &UniversalStreamChunk{
+        Content: deltaContent,
+        FinishReason: finishReason,
+    }, nil
+}
+```

backend/internal/handlers/llm_proxy.go

@@ -97,7 +97,6 @@ func (h *LLMProxyHandler) prepareLLMRequest(c *gin.Context, slug, action string)
 	convertedAction := action
 	if needConversion {
 		logger.Infof("Request format conversion enabled: %s -> %s", clientFormat, apiFormat)
-		logger.Infof("Original request body: %s", string(bodyBytes))
 
 		converter, err := converters.NewConverter(clientFormat, apiFormat)
 		if err != nil {
@@ -111,7 +110,6 @@ func (h *LLMProxyHandler) prepareLLMRequest(c *gin.Context, slug, action string)
 			return nil, nil, fmt.Errorf("failed to convert request format: %w", err)
 		}
 		bodyBytes = convertedBody
-		logger.Infof("Converted request body: %s", string(bodyBytes))
 
 		// 转换请求路径
 		convertedAction = converter.GetTargetPath(action)
@@ -266,9 +264,6 @@ func (h *LLMProxyHandler) forwardLLMRequest(c *gin.Context, target *services.Tar
 		}
 
 		if needConversion && converter != nil {
-			// 调试日志：打印原始响应内容
-			logger.Infof("Original response body (first 500 chars): %s", truncateString(string(body), 500))
-
 			// 转换响应格式
 			convertedBody, err := converter.ConvertResponse(body)
 			if err != nil {
@@ -378,11 +373,3 @@ func extractModelFromBody(body []byte) string {
 
 	return ""
 }
-
-// truncateString truncates a string to the specified max length
-func truncateString(s string, maxLen int) string {
-	if len(s) <= maxLen {
-		return s
-	}
-	return s[:maxLen] + "..."
-}