@huyooo/ai-chat-core 0.2.44 → 0.3.2

package/src/protocols/qwen.ts

@@ -0,0 +1,358 @@
+/**
+ * Qwen Protocol（DashScope 原生 API）
+ * 
+ * 使用 DashScope 原生端点，不依赖 OpenAI 兼容模式。
+ * - text-only 模型: /api/v1/services/aigc/text-generation/generation
+ * - multimodal 模型: /api/v1/services/aigc/multimodal-generation/generation
+ * 
+ * qwen3.5-* 和 *-vl-* 系列归为 multimodal，其余走 text-only 端点。
+ */
+
+import type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  RawEvent,
+  RawToolCall,
+} from './types';
+import { createModuleLogger } from '../logger';
+import { friendlyHttpError } from './error-utils';
+import { readSSEJsonStream } from './sse-reader';
+
+const logger = createModuleLogger('QwenProtocol');
+
+const DEFAULT_QWEN_NATIVE_URL = 'https://dashscope.aliyuncs.com/api/v1';
+
+const TEXT_GENERATION_PATH = '/services/aigc/text-generation/generation';
+const MULTIMODAL_GENERATION_PATH = '/services/aigc/multimodal-generation/generation';
+
+/**
+ * qwen3.5-* 和 *-vl-* 系列需要使用 multimodal 端点
+ */
+function isMultimodalModel(model: string): boolean {
+  return model.startsWith('qwen3.5-') || model.includes('-vl-');
+}
+
+/**
+ * 从 DashScope 原生 content 中提取文本
+ * text-only 端点返回 string，multimodal 端点返回 [{text: "..."}]
+ */
+function extractText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    for (const item of content) {
+      if (typeof item === 'object' && item !== null && 'text' in item) {
+        return (item as { text: string }).text || '';
+      }
+    }
+  }
+  return '';
+}
+
+export function extractIncrementalText(nextText: string, previousText: string): string {
+  if (!nextText) return '';
+  if (!previousText) return nextText;
+  if (nextText === previousText) return '';
+  if (nextText.startsWith(previousText)) {
+    return nextText.slice(previousText.length);
+  }
+  return nextText;
+}
+
+/**
+ * Qwen Protocol 实现（DashScope 原生 API）
+ */
+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_NATIVE_URL;
+  }
+  
+  async *stream(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): AsyncGenerator<RawEvent> {
+    const multimodal = isMultimodalModel(options.model);
+    const path = multimodal ? MULTIMODAL_GENERATION_PATH : TEXT_GENERATION_PATH;
+    const url = `${this.apiUrl.replace(/\/$/, '')}${path}`;
+    const requestBody = buildRequestBody(messages, tools, options, multimodal);
+    
+    logger.debug({
+      url,
+      model: options.model,
+      multimodal,
+      enableThinking: options.enableThinking,
+      toolsCount: tools.length,
+    }, '发送 Qwen 请求（DashScope 原生）');
+    
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+        'X-DashScope-SSE': 'enable',
+      },
+      body: JSON.stringify(requestBody),
+      signal: options.signal,
+    });
+    
+    if (!response.ok) {
+      const errorText = await response.text();
+      logger.error({ status: response.status, body: errorText.slice(0, 500) }, 'Qwen API 错误');
+      yield { type: 'error', error: friendlyHttpError(response.status, errorText, 'Qwen') };
+      return;
+    }
+    
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: 'error', error: '无法获取响应流' };
+      return;
+    }
+    
+    yield* parseSSE(reader, multimodal);
+  }
+}
+
+/**
+ * 构建 DashScope 原生请求体
+ * 
+ * 结构: { model, input: { messages }, parameters: { ... } }
+ */
+function buildRequestBody(
+  messages: ProtocolMessage[],
+  tools: ProtocolToolDefinition[],
+  options: ProtocolRequestOptions,
+  multimodal: boolean,
+): Record<string, unknown> {
+  const convertedMessages = convertMessages(messages, multimodal);
+  
+  const parameters: Record<string, unknown> = {
+    result_format: 'message',
+    incremental_output: true,
+  };
+  
+  if (options.enableThinking) {
+    parameters.enable_thinking = true;
+    parameters.thinking_budget = 38400;
+  }
+  
+  if (tools.length > 0) {
+    parameters.tools = tools.map(t => ({
+      type: 'function',
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      },
+    }));
+  }
+  
+  return {
+    model: options.model,
+    input: { messages: convertedMessages },
+    parameters,
+  };
+}
+
+/**
+ * 转换消息格式
+ * 
+ * text-only: content 是 string
+ * multimodal: content 是 [{text: "..."}, {image: "url"}] 数组
+ */
+function convertMessages(messages: ProtocolMessage[], multimodal: boolean): unknown[] {
+  const result: unknown[] = [];
+  
+  for (const msg of messages) {
+    switch (msg.role) {
+      case 'system':
+        result.push({
+          role: 'system',
+          content: multimodal ? [{ text: msg.content }] : msg.content,
+        });
+        break;
+        
+      case 'user': {
+        const textContent = msg.content || (msg.images?.length ? '请分析这张图片' : '');
+        
+        if (multimodal) {
+          const content: unknown[] = [{ text: textContent }];
+          if (msg.images?.length) {
+            for (const img of msg.images) {
+              content.push({
+                image: 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: multimodal ? (msg.content ? [{ text: msg.content }] : []) : (msg.content || null),
+            ...(msg.thinkingContent ? { reasoning_content: msg.thinkingContent } : {}),
+            tool_calls: msg.toolCalls.map(tc => ({
+              id: tc.id,
+              type: 'function',
+              function: { name: tc.name, arguments: tc.arguments },
+            })),
+          });
+        } else {
+          result.push({
+            role: 'assistant',
+            content: multimodal ? (msg.content ? [{ text: msg.content }] : []) : msg.content,
+          });
+        }
+        break;
+        
+      case 'tool':
+        result.push({
+          role: 'tool',
+          tool_call_id: msg.toolCallId,
+          content: msg.content,
+        });
+        break;
+    }
+  }
+  
+  return result;
+}
+
+/**
+ * 解析 DashScope 原生 SSE 流
+ *
+ * Layer 1（readSSEJsonStream）负责 bytes → JSON，此处仅做语义映射。
+ * 无 [DONE] 信号，通过 finish_reason !== "null" 判断结束。
+ */
+async function* parseSSE(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  multimodal: boolean,
+): AsyncGenerator<RawEvent> {
+  const toolCallsMap = new Map<number, RawToolCall>();
+  let textStarted = false;
+  let thinkingDone = false;
+  let lastUsage: RawEvent['usage'];
+  let lastReasoningText = '';
+  let lastText = '';
+
+  for await (const json of readSSEJsonStream(reader)) {
+    if (json.code) {
+      yield { type: 'error', error: `${json.code}: ${json.message}` };
+      return;
+    }
+
+    if (json.usage) {
+      const usage = json.usage as Record<string, unknown>;
+      lastUsage = {
+        promptTokens: (usage.input_tokens as number) ?? 0,
+        completionTokens: (usage.output_tokens as number) ?? 0,
+        totalTokens: (usage.total_tokens as number) ?? 0,
+        reasoningTokens: (usage.output_tokens_details as Record<string, number> | undefined)?.reasoning_tokens ?? 0,
+        cachedTokens: (usage.prompt_tokens_details as Record<string, number> | undefined)?.cached_tokens ?? 0,
+      };
+    }
+
+    const output = json.output as Record<string, unknown> | undefined;
+    const choices = output?.choices as Array<Record<string, unknown>> | undefined;
+    const choice = choices?.[0];
+    if (!choice) continue;
+
+    const message = choice.message as Record<string, unknown> | undefined;
+    if (!message) continue;
+
+    const reasoningText = typeof message.reasoning_content === 'string' ? message.reasoning_content : '';
+    if (reasoningText && !thinkingDone) {
+      const reasoningDelta = extractIncrementalText(reasoningText, lastReasoningText);
+      lastReasoningText = reasoningText;
+      if (reasoningDelta) {
+        yield { type: 'thinking_delta', delta: reasoningDelta };
+      }
+    }
+
+    const textSnapshot = multimodal ? extractText(message.content) : ((message.content as string) || '');
+    const textDelta = extractIncrementalText(textSnapshot, lastText);
+    if (textDelta) {
+      lastText = textSnapshot;
+      if (!textStarted && !thinkingDone) {
+        thinkingDone = true;
+        yield { type: 'thinking_done' };
+      }
+      textStarted = true;
+      yield { type: 'text_delta', delta: textDelta };
+    } else if (textSnapshot) {
+      lastText = textSnapshot;
+    }
+
+    const msgToolCalls = message.tool_calls as Array<Record<string, unknown>> | undefined;
+    if (msgToolCalls?.length) {
+      for (const tc of msgToolCalls) {
+        const index = (tc.index as number) ?? 0;
+        const fn = tc.function as Record<string, string> | undefined;
+        const existing = toolCallsMap.get(index);
+
+        if (existing) {
+          if (fn?.arguments) {
+            existing.arguments += fn.arguments;
+          }
+        } else {
+          if (!tc.id) logger.warn({ index }, 'SSE tool_call 首块缺少 id');
+          if (!fn?.name) logger.warn({ index, id: tc.id }, 'SSE tool_call 首块缺少 name');
+          const id = (tc.id as string) || `call_${index}`;
+          const name = fn?.name || '';
+          toolCallsMap.set(index, { id, name, arguments: fn?.arguments || '' });
+          yield { type: 'tool_call_start', toolCall: { id, name } };
+        }
+      }
+    }
+
+    // DashScope 用字符串 "null" 表示未完成
+    const finishReason = choice.finish_reason as string | undefined;
+    if (finishReason && finishReason !== 'null') {
+      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 {
+        const reason: RawEvent['finishReason'] = (finishReason === 'tool_calls' || finishReason === 'length' || finishReason === 'error')
+          ? finishReason
+          : 'stop';
+        yield { type: 'done', finishReason: reason, usage: lastUsage };
+      }
+      return;
+    }
+  }
+
+  // 流异常中断兜底
+  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/protocols/responses-sse.ts

@@ -0,0 +1,224 @@
+/**
+ * Responses API 共享逻辑
+ *
+ * OpenAI 和 xAI (Grok) 均使用相同的 Responses API 格式，
+ * 此模块提取共享的消息转换和 SSE 事件解析逻辑。
+ *
+ * 使用方：openai.ts, grok.ts
+ */
+
+import type {
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  RawEvent,
+  RawToolCall,
+  RawTokenUsage,
+} from './types';
+import { readSSEJsonStream } from './sse-reader';
+
+// ==================== 消息转换 ====================
+
+/** 将 ProtocolMessage[] 转换为 Responses API 的 input 格式 */
+export function convertToResponsesInput(messages: ProtocolMessage[]): unknown[] {
+  const input: unknown[] = [];
+
+  for (const msg of messages) {
+    switch (msg.role) {
+      case 'system':
+        input.push({ role: 'system', content: msg.content });
+        break;
+
+      case 'user': {
+        const textContent = msg.content || (msg.images?.length ? '请分析这张图片' : '');
+        const content: unknown[] = [{ type: 'input_text', text: textContent }];
+        if (msg.images?.length) {
+          for (const img of msg.images) {
+            content.push({
+              type: 'input_image',
+              image_url: img.startsWith('data:') ? img : `data:image/jpeg;base64,${img}`,
+            });
+          }
+        }
+        input.push({ role: 'user', content });
+        break;
+      }
+
+      case 'assistant':
+        if (msg.toolCalls?.length) {
+          if (msg.content) {
+            input.push({
+              type: 'message',
+              role: 'assistant',
+              content: [{ type: 'output_text', text: msg.content }],
+            });
+          }
+          for (const tc of msg.toolCalls) {
+            input.push({
+              type: 'function_call',
+              call_id: tc.id,
+              name: tc.name,
+              arguments: tc.arguments,
+            });
+          }
+        } else {
+          input.push({ role: 'assistant', content: msg.content });
+        }
+        break;
+
+      case 'tool':
+        input.push({
+          type: 'function_call_output',
+          call_id: msg.toolCallId,
+          output: msg.content,
+        });
+        break;
+    }
+  }
+
+  return input;
+}
+
+// ==================== 工具定义转换 ====================
+
+/** 将 ProtocolToolDefinition[] 转换为 Responses API 的 tools 格式 */
+export function convertToResponsesTools(tools: ProtocolToolDefinition[]): unknown[] {
+  return tools.map(t => ({
+    type: 'function',
+    name: t.name,
+    description: t.description,
+    parameters: t.parameters,
+  }));
+}
+
+// ==================== SSE 事件解析 ====================
+
+export interface ResponsesStreamConfig {
+  /** 协议名（用于错误消息，如 "OpenAI"、"Grok"） */
+  protocolName: string;
+}
+
+/**
+ * 解析 Responses API 的 SSE 事件流，映射为 RawEvent
+ *
+ * 处理的事件：
+ * - response.output_item.added (message / function_call / reasoning)
+ * - response.output_text.delta → text_delta
+ * - response.function_call_arguments.delta → tool_call_delta
+ * - response.reasoning_summary_text.delta → thinking_delta
+ * - response.completed → usage
+ * - response.failed → error
+ */
+export async function* mapResponsesStream(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  config: ResponsesStreamConfig,
+): AsyncGenerator<RawEvent> {
+  const pendingToolCalls = new Map<string, RawToolCall>();
+  let currentFunctionCallId: string | null = null;
+  let thinkingActive = false;
+  let thinkingDone = false;
+  let textStarted = false;
+  let lastUsage: RawTokenUsage | undefined;
+
+  for await (const event of readSSEJsonStream(reader)) {
+    const eventUsage = (event.response as Record<string, unknown>)?.usage ?? event.usage;
+    if (eventUsage) {
+      const u = eventUsage as Record<string, unknown>;
+      const inputTokens = (u.input_tokens as number) ?? 0;
+      const outputTokens = (u.output_tokens as number) ?? 0;
+      const outputDetails = u.output_tokens_details as Record<string, number> | undefined;
+      const inputDetails = u.input_tokens_details as Record<string, number> | undefined;
+      lastUsage = {
+        promptTokens: inputTokens,
+        completionTokens: outputTokens,
+        totalTokens: (u.total_tokens as number) ?? inputTokens + outputTokens,
+        reasoningTokens: outputDetails?.reasoning_tokens ?? 0,
+        cachedTokens: inputDetails?.cached_tokens ?? 0,
+      };
+    }
+
+    switch (event.type) {
+      case 'response.output_item.added': {
+        const item = event.item as Record<string, unknown> | undefined;
+        if (!item) break;
+
+        if (item.type === 'function_call' && item.call_id) {
+          currentFunctionCallId = item.call_id as string;
+          const name = (item.name as string) || '';
+          pendingToolCalls.set(currentFunctionCallId, {
+            id: currentFunctionCallId,
+            name,
+            arguments: (item.arguments as string) || '',
+          });
+          yield { type: 'tool_call_start', toolCall: { id: currentFunctionCallId, name } };
+        }
+
+        if (item.type === 'reasoning') {
+          thinkingActive = true;
+        }
+        break;
+      }
+
+      case 'response.function_call_arguments.delta': {
+        if (currentFunctionCallId) {
+          const call = pendingToolCalls.get(currentFunctionCallId);
+          if (call) {
+            call.arguments += (event.delta as string) || '';
+            yield { type: 'tool_call_delta', toolCall: { id: currentFunctionCallId, arguments: (event.delta as string) || '' } };
+          }
+        }
+        break;
+      }
+
+      case 'response.function_call_arguments.done':
+      case 'response.output_item.done': {
+        const item = event.item as Record<string, unknown> | undefined;
+        if (item?.type === 'function_call' && item.call_id) {
+          const callId = item.call_id as string;
+          const existing = pendingToolCalls.get(callId);
+          pendingToolCalls.set(callId, {
+            id: callId,
+            name: (item.name as string) || existing?.name || '',
+            arguments: (item.arguments as string) || existing?.arguments || '{}',
+          });
+        }
+        break;
+      }
+
+      case 'response.output_text.delta':
+        if (event.delta) {
+          if (!textStarted) {
+            textStarted = true;
+            if (thinkingActive && !thinkingDone) {
+              thinkingDone = true;
+              yield { type: 'thinking_done' };
+            }
+          }
+          yield { type: 'text_delta', delta: event.delta as string };
+        }
+        break;
+
+      case 'response.reasoning_summary_text.delta':
+        if (event.delta && !thinkingDone) {
+          yield { type: 'thinking_delta', delta: event.delta as string };
+        }
+        break;
+
+      case 'response.failed': {
+        const resp = event.response as Record<string, unknown> | undefined;
+        const errObj = resp?.error as Record<string, unknown> | undefined;
+        const errMsg = (errObj?.message as string) || `${config.protocolName} Responses API 失败`;
+        yield { type: 'error', error: errMsg };
+        break;
+      }
+    }
+  }
+
+  if (pendingToolCalls.size > 0) {
+    for (const tc of pendingToolCalls.values()) {
+      yield { type: 'tool_call_done', toolCall: tc };
+    }
+    yield { type: 'done', finishReason: 'tool_calls', usage: lastUsage };
+  } else {
+    yield { type: 'done', finishReason: 'stop', usage: lastUsage };
+  }
+}

package/src/protocols/sse-reader.ts

@@ -0,0 +1,54 @@
+/**
+ * Layer 1: 通用 SSE 字节流读取器
+ *
+ * 纯机械逻辑：bytes → lines → JSON objects
+ * 不含任何协议语义，所有协议通用。
+ *
+ * 处理：
+ * - 字节解码 + 缓冲区拼接
+ * - 行分割
+ * - data: 前缀提取
+ * - [DONE] 信号跳过
+ * - JSON.parse
+ *
+ * 忽略：event:、id:、:HTTP_STATUS 等非 data 行
+ */
+
+import { createModuleLogger } from '../logger';
+
+const logger = createModuleLogger('SSEReader');
+
+/**
+ * 将 ReadableStream 转换为 JSON 对象流
+ *
+ * 所有协议共用此函数，消除重复的 buffer/decode/split/parse 逻辑。
+ * 消费方根据 JSON 结构自行做语义映射。
+ */
+export async function* readSSEJsonStream(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+): AsyncGenerator<Record<string, unknown>> {
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  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]') continue;
+
+      try {
+        yield JSON.parse(data) as Record<string, unknown>;
+      } catch (e) {
+        logger.warn({ line: line.slice(0, 100), error: String(e) }, 'SSE JSON 解析失败');
+      }
+    }
+  }
+}

package/src/protocols/tool-arguments.ts

@@ -0,0 +1,32 @@
+interface ParseProtocolToolArgumentsOptions {
+  protocol: string;
+  toolCallId: string;
+  toolName: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function parseProtocolToolArguments(
+  argumentsJson: string,
+  options: ParseProtocolToolArgumentsOptions,
+): Record<string, unknown> {
+  const source = argumentsJson?.trim() ? argumentsJson : '{}';
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source);
+  } catch (error) {
+    throw new Error(
+      `[${options.protocol}] tool call arguments must be valid JSON: ${options.toolName}(${options.toolCallId}): ${String(error)}`,
+    );
+  }
+
+  if (!isRecord(parsed)) {
+    throw new Error(
+      `[${options.protocol}] tool call arguments must be a JSON object: ${options.toolName}(${options.toolCallId})`,
+    );
+  }
+
+  return parsed;
+}