@huyooo/ai-chat-core 0.2.19 → 0.2.21

package/src/providers/protocols/qwen.ts

@@ -0,0 +1,326 @@
+/**
+ * Qwen Protocol（通义千问 OpenAI 兼容模式 API）
+ * 
+ * 使用 OpenAI 兼容端点以支持工具调用：
+ * https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
+ */
+
+import type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  RawEvent,
+  RawToolCall,
+} from './types';
+import { DebugLogger } from '../../utils';
+import { friendlyHttpError } from './error-utils';
+
+const logger = DebugLogger.module('QwenProtocol');
+
+// OpenAI 兼容模式端点
+const DEFAULT_QWEN_COMPATIBLE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
+
+/**
+ * Qwen Protocol 实现（OpenAI 兼容模式）
+ */
+export class QwenProtocol implements Protocol {
+  readonly name = 'qwen';
+  
+  private apiKey: string;
+  private apiUrl: string;
+  
+  constructor(config: ProtocolConfig) {
+    this.apiKey = config.apiKey;
+    // 使用兼容模式端点
+    this.apiUrl = config.apiUrl ?? DEFAULT_QWEN_COMPATIBLE_URL;
+  }
+  
+  /**
+   * 发送请求并返回原始事件流
+   */
+  async *stream(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): AsyncGenerator<RawEvent> {
+    const requestBody = this.buildRequestBody(messages, tools, options);
+    const url = `${this.apiUrl}/chat/completions`;
+    
+    logger.debug('发送 Qwen 请求（兼容模式）', {
+      url,
+      model: options.model,
+      enableThinking: options.enableThinking,
+      toolsCount: tools.length,
+    });
+    
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(requestBody),
+      signal: options.signal,
+    });
+    
+    if (!response.ok) {
+      const errorText = await response.text();
+      logger.error('Qwen API 错误', { status: response.status, body: errorText.slice(0, 500) });
+      yield { type: 'error', error: friendlyHttpError(response.status, errorText, 'Qwen') };
+      return;
+    }
+    
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: 'error', error: '无法获取响应流' };
+      return;
+    }
+    
+    yield* this.parseSSE(reader, options.enableThinking);
+  }
+  
+  /**
+   * 构建请求体（OpenAI 格式）
+   */
+  private buildRequestBody(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): Record<string, unknown> {
+    const convertedMessages = this.convertMessages(messages);
+    
+    const body: Record<string, unknown> = {
+      model: options.model,
+      messages: convertedMessages,
+      stream: true,
+      // 请求返回 Token 使用统计（Chat Completions 格式）
+      stream_options: { include_usage: true },
+    };
+    
+    // 启用 thinking（Qwen 直接在请求体中设置）
+    if (options.enableThinking) {
+      body.enable_thinking = true;
+      body.thinking_budget = 38400;
+    }
+    
+    // 注意：Qwen 搜索通过 Tavily web_search 工具实现（searchStrategy: tavily）
+    // 不使用原生 enable_search 参数，保持与其他 Provider 一致
+    
+    // 添加工具
+    if (tools.length > 0) {
+      body.tools = tools.map(t => ({
+        type: 'function',
+        function: {
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters,
+        },
+      }));
+    }
+    
+    return body;
+  }
+  
+  /**
+   * 转换消息格式（OpenAI 标准格式）
+   */
+  private convertMessages(messages: ProtocolMessage[]): unknown[] {
+    const result: unknown[] = [];
+    
+    for (const msg of messages) {
+      switch (msg.role) {
+        case 'system':
+          result.push({ role: 'system', content: msg.content });
+          break;
+          
+        case 'user': {
+          // 当只有图片没有文字时提供默认提示
+          const textContent = msg.content || (msg.images?.length ? '请分析这张图片' : '');
+          if (msg.images?.length) {
+            const content: unknown[] = [{ type: 'text', text: textContent }];
+            for (const img of msg.images) {
+              content.push({
+                type: 'image_url',
+                image_url: { url: img.startsWith('data:') ? img : `data:image/jpeg;base64,${img}` },
+              });
+            }
+            result.push({ role: 'user', content });
+          } else {
+            result.push({ role: 'user', content: textContent });
+          }
+          break;
+        }
+        
+        case 'assistant':
+          if (msg.toolCalls?.length) {
+            result.push({
+              role: 'assistant',
+              content: msg.content || null,
+              tool_calls: msg.toolCalls.map(tc => ({
+                id: tc.id,
+                type: 'function',
+                function: { name: tc.name, arguments: tc.arguments },
+              })),
+            });
+          } else {
+            result.push({ role: 'assistant', content: msg.content });
+          }
+          break;
+          
+        case 'tool':
+          result.push({
+            role: 'tool',
+            tool_call_id: msg.toolCallId,
+            content: msg.content,
+          });
+          break;
+      }
+    }
+    
+    return result;
+  }
+  
+  /**
+   * 解析 SSE 流（OpenAI 格式）
+   */
+  private async *parseSSE(
+    reader: ReadableStreamDefaultReader<Uint8Array>,
+    enableThinking: boolean
+  ): AsyncGenerator<RawEvent> {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const toolCallsMap = new Map<number, RawToolCall>();
+    let textStarted = false;
+    let thinkingDone = false;
+    // Token 使用统计
+    let lastUsage: { promptTokens: number; completionTokens: number; totalTokens: number } | undefined;
+    
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+      
+      for (const line of lines) {
+        if (!line.startsWith('data:')) continue;
+        
+        const data = line.slice(5).trim();
+        if (!data || data === '[DONE]') {
+          if (data === '[DONE]') {
+            // 输出工具调用
+            const toolCalls = Array.from(toolCallsMap.values());
+            if (toolCalls.length > 0) {
+              for (const tc of toolCalls) {
+                yield { type: 'tool_call_done', toolCall: tc };
+              }
+              yield { type: 'done', finishReason: 'tool_calls', usage: lastUsage };
+            } else {
+              yield { type: 'done', finishReason: 'stop', usage: lastUsage };
+            }
+            return;
+          }
+          continue;
+        }
+        
+        try {
+          const json = JSON.parse(data);
+          
+          // 提取 Token 使用统计（Chat Completions 格式）
+          if (json.usage) {
+            lastUsage = {
+              promptTokens: json.usage.prompt_tokens || 0,
+              completionTokens: json.usage.completion_tokens || 0,
+              totalTokens: json.usage.total_tokens || (json.usage.prompt_tokens || 0) + (json.usage.completion_tokens || 0),
+            };
+          }
+          
+          const choice = json.choices?.[0];
+          if (!choice) continue;
+          
+          const delta = choice.delta;
+          if (!delta) continue;
+          
+          // 处理 reasoning_content（Qwen 的思考输出）
+          if (enableThinking && delta.reasoning_content && !thinkingDone) {
+            yield { type: 'thinking_delta', delta: delta.reasoning_content };
+          }
+          
+          // 处理文本
+          if (delta.content) {
+            // 第一次收到 content 时，结束 thinking
+            if (enableThinking && !textStarted && !thinkingDone) {
+              thinkingDone = true;
+              yield { type: 'thinking_done' };
+            }
+            textStarted = true;
+            yield { type: 'text_delta', delta: delta.content };
+          }
+          
+          // 处理工具调用
+          if (delta.tool_calls?.length) {
+            for (const tc of delta.tool_calls) {
+              const index = tc.index ?? 0;
+              const existing = toolCallsMap.get(index);
+              
+              if (existing) {
+                // 累积 arguments
+                if (tc.function?.arguments) {
+                  existing.arguments += tc.function.arguments;
+                }
+              } else {
+                // 新工具调用
+                toolCallsMap.set(index, {
+                  id: tc.id || `call_${index}`,
+                  name: tc.function?.name || '',
+                  arguments: tc.function?.arguments || '',
+                });
+                yield { 
+                  type: 'tool_call_start', 
+                  toolCall: { id: tc.id || `call_${index}`, name: tc.function?.name || '' } 
+                };
+              }
+            }
+          }
+          
+          // 检查 finish_reason
+          if (choice.finish_reason) {
+            const toolCalls = Array.from(toolCallsMap.values());
+            if (toolCalls.length > 0) {
+              for (const tc of toolCalls) {
+                yield { type: 'tool_call_done', toolCall: tc };
+              }
+              yield { type: 'done', finishReason: 'tool_calls', usage: lastUsage };
+            } else {
+              yield { type: 'done', finishReason: choice.finish_reason, usage: lastUsage };
+            }
+            return;
+          }
+        } catch {
+          // 忽略解析错误
+        }
+      }
+    }
+    
+    // 兜底
+    const toolCalls = Array.from(toolCallsMap.values());
+    if (toolCalls.length > 0) {
+      for (const tc of toolCalls) {
+        yield { type: 'tool_call_done', toolCall: tc };
+      }
+      yield { type: 'done', finishReason: 'tool_calls', usage: lastUsage };
+    } else {
+      yield { type: 'done', finishReason: 'stop', usage: lastUsage };
+    }
+  }
+}
+
+/**
+ * 创建 Qwen Protocol
+ */
+export function createQwenProtocol(config: ProtocolConfig): QwenProtocol {
+  return new QwenProtocol(config);
+}

package/src/providers/protocols/types.ts

@@ -0,0 +1,189 @@
+/**
+ * Protocol Layer 类型定义
+ * 
+ * Protocol 只负责：
+ * 1. HTTP 请求发送
+ * 2. SSE 流解析
+ * 3. 认证处理
+ * 
+ * 不负责：
+ * - thinking 格式转换（由 Family 处理）
+ * - 搜索行为差异（由 Family 处理）
+ * - 工具调用格式差异（由 Family 处理）
+ */
+
+import type { ModelFamilyConfig } from '../model-registry';
+
+// ==================== 原始事件类型 ====================
+
+/**
+ * Protocol 原始事件类型
+ * 
+ * 这是 Protocol 层产出的"原始"事件，
+ * 后续由 FamilyBehavior 转换为标准 StreamChunk
+ */
+export type RawEventType =
+  | 'text_delta'           // 文本增量
+  | 'thinking_delta'       // 思考内容增量
+  | 'thinking_done'        // 思考完成
+  | 'tool_call_start'      // 工具调用开始
+  | 'tool_call_delta'      // 工具调用参数增量
+  | 'tool_call_done'       // 工具调用完成
+  | 'search_query'         // 搜索查询
+  | 'search_result'        // 搜索结果
+  | 'done'                 // 流结束
+  | 'error';               // 错误
+
+/**
+ * 原始工具调用
+ */
+export interface RawToolCall {
+  id: string;
+  name: string;
+  arguments: string;
+  /** Gemini 需要的 thoughtSignature（用于工具调用循环） */
+  thoughtSignature?: string;
+}
+
+/**
+ * Protocol 消息中的工具调用
+ */
+export interface ProtocolToolCall {
+  id: string;
+  name: string;
+  arguments: string;
+  /** Gemini 需要的 thoughtSignature */
+  thoughtSignature?: string;
+}
+
+/**
+ * 原始搜索结果
+ */
+export interface RawSearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+/**
+ * Protocol 原始事件
+ */
+/** Token 使用统计（Protocol 层） */
+export interface RawTokenUsage {
+  promptTokens?: number;
+  completionTokens?: number;
+  totalTokens?: number;
+  reasoningTokens?: number;
+  cachedTokens?: number;
+}
+
+export interface RawEvent {
+  type: RawEventType;
+  
+  // text_delta / thinking_delta
+  delta?: string;
+  
+  // tool_call_*
+  toolCall?: Partial<RawToolCall>;
+  
+  // search_*
+  searchQuery?: string;
+  searchResults?: RawSearchResult[];
+  
+  // done
+  finishReason?: 'stop' | 'tool_calls' | 'length' | 'error';
+  /** Token 使用统计（done 事件携带） */
+  usage?: RawTokenUsage;
+  
+  // error
+  error?: string;
+}
+
+// ==================== Protocol 请求类型 ====================
+
+/**
+ * Protocol 请求消息（标准化格式）
+ */
+export interface ProtocolMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  
+  /** 图片列表（base64 或 URL） */
+  images?: string[];
+  
+  /** 工具调用（assistant 消息） */
+  toolCalls?: ProtocolToolCall[];
+  
+  /** 工具调用 ID（tool 消息） */
+  toolCallId?: string;
+  
+  /** 工具名称（tool 消息，Gemini 需要） */
+  toolName?: string;
+}
+
+/**
+ * Protocol 工具定义（简化格式）
+ */
+import type { JsonSchemaObject } from '../../types';
+
+export interface ProtocolToolDefinition {
+  name: string;
+  description: string;
+  parameters: JsonSchemaObject;
+}
+
+/**
+ * Protocol 请求选项
+ */
+export interface ProtocolRequestOptions {
+  /** 模型 ID */
+  model: string;
+  /** 模型家族配置 */
+  familyConfig: ModelFamilyConfig;
+  /** 是否启用 thinking */
+  enableThinking: boolean;
+  /** 是否启用搜索 */
+  enableSearch: boolean;
+  /** 中断信号 */
+  signal: AbortSignal;
+}
+
+// ==================== Protocol 接口 ====================
+
+/**
+ * Protocol 配置
+ */
+export interface ProtocolConfig {
+  apiKey: string;
+  apiUrl?: string;
+}
+
+/**
+ * Protocol 接口
+ * 
+ * 只负责 HTTP/SSE 通信，不处理任何业务逻辑
+ */
+export interface Protocol {
+  /** 协议名称 */
+  readonly name: string;
+  
+  /**
+   * 发送请求并返回原始事件流
+   * 
+   * @param messages 消息列表
+   * @param tools 工具定义
+   * @param options 请求选项
+   * @returns 原始事件流
+   */
+  stream(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): AsyncGenerator<RawEvent>;
+}
+
+/**
+ * Protocol 工厂函数类型
+ */
+export type ProtocolFactory = (config: ProtocolConfig) => Protocol;
+