@huyooo/ai-chat-core 0.2.19 → 0.2.21

package/src/providers/protocols/error-utils.ts

@@ -0,0 +1,74 @@
+/**
+ * Protocol 错误处理工具
+ *
+ * 将各种 API 错误（HTTP status + JSON body / SDK 异常）转换为用户友好的消息。
+ */
+
+/** HTTP 状态码 → 友好消息 */
+const STATUS_MESSAGES: Record<number, string> = {
+  400: '请求参数错误',
+  401: 'API 认证失败，请检查 API Key 配置',
+  402: '账户余额不足，请充值后重试',
+  403: '没有权限访问此模型',
+  404: '请求的模型或接口不存在',
+  429: '请求过于频繁，请稍后重试',
+  500: 'API 服务器内部错误，请稍后重试',
+  502: 'API 网关错误，请稍后重试',
+  503: 'API 服务暂时不可用，请稍后重试',
+  504: 'API 请求超时，请稍后重试',
+};
+
+/**
+ * 从 HTTP 响应中提取用户友好的错误消息
+ *
+ * @param status HTTP 状态码
+ * @param body 原始响应体字符串
+ * @param providerName 供应商名称（如 "Gemini"、"OpenAI"）
+ */
+export function friendlyHttpError(status: number, body: string, providerName: string): string {
+  // 1. 尝试从 JSON body 提取 message
+  const parsed = tryParseErrorBody(body);
+  const apiMessage = parsed?.message;
+
+  // 2. 已知 status → 友好中文
+  const statusMessage = STATUS_MESSAGES[status];
+  if (statusMessage) {
+    // 如果有 API 返回的具体消息且不太长，附在后面
+    if (apiMessage && apiMessage.length <= 100) {
+      return `${statusMessage}（${apiMessage}）`;
+    }
+    return statusMessage;
+  }
+
+  // 3. 未知 status，但有 API 消息
+  if (apiMessage) {
+    const msg = apiMessage.length > 200 ? apiMessage.slice(0, 200) + '...' : apiMessage;
+    return `${providerName} 错误 (${status}): ${msg}`;
+  }
+
+  // 4. 纯兜底
+  return `${providerName} 错误 (${status})`;
+}
+
+/**
+ * 尝试从 JSON 响应体中提取 error.message
+ * 兼容格式：
+ *   { "error": { "message": "..." } }          — OpenAI / Gemini / Vercel
+ *   { "error_msg": "..." }                      — ARK
+ *   { "message": "..." }                        — 通用
+ */
+function tryParseErrorBody(body: string): { message?: string; type?: string } | null {
+  try {
+    const json = JSON.parse(body);
+    if (json?.error?.message) {
+      return { message: json.error.message, type: json.error.type };
+    }
+    if (typeof json?.error_msg === 'string') {
+      return { message: json.error_msg };
+    }
+    if (typeof json?.message === 'string') {
+      return { message: json.message };
+    }
+  } catch { /* not JSON */ }
+  return null;
+}

package/src/providers/protocols/gemini.ts

@@ -0,0 +1,350 @@
+/**
+ * Gemini Protocol（Google Gemini API）
+ * 
+ * 只负责：
+ * - HTTP 请求发送
+ * - SSE 流解析
+ * - 原始事件产出
+ */
+
+import type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  RawEvent,
+  RawToolCall,
+  RawSearchResult,
+} from './types';
+import { DebugLogger } from '../../utils';
+import { friendlyHttpError } from './error-utils';
+
+const logger = DebugLogger.module('GeminiProtocol');
+
+const DEFAULT_GEMINI_URL = 'https://generativelanguage.googleapis.com/v1beta';
+
+/**
+ * 历史中无 thoughtSignature 时使用的占位值（跳过 Gemini 校验）。
+ * 见 https://ai.google.dev/gemini-api/docs/thought-signatures
+ */
+const GEMINI_THOUGHT_SIGNATURE_DUMMY = 'skip_thought_signature_validator';
+
+/**
+ * Gemini Protocol 实现
+ */
+export class GeminiProtocol implements Protocol {
+  readonly name = 'gemini';
+
+  private apiKey: string;
+  private apiUrl: string;
+
+  constructor(config: ProtocolConfig) {
+    this.apiKey = config.apiKey;
+    this.apiUrl = config.apiUrl ?? DEFAULT_GEMINI_URL;
+  }
+
+  /**
+   * 发送请求并返回原始事件流
+   */
+  async *stream(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): AsyncGenerator<RawEvent> {
+    const requestBody = this.buildRequestBody(messages, tools, options);
+    const url = `${this.apiUrl}/models/${options.model}:streamGenerateContent?key=${this.apiKey}&alt=sse`;
+
+    logger.debug('发送 Gemini 请求', {
+      url: url.replace(this.apiKey, '***'),
+      model: options.model,
+      enableSearch: options.enableSearch,
+      enableThinking: options.enableThinking,
+      toolsCount: tools.length,
+    });
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(requestBody),
+      signal: options.signal,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      logger.error('Gemini API 错误', { status: response.status, body: errorText.slice(0, 500) });
+      yield { type: 'error', error: friendlyHttpError(response.status, errorText, 'Gemini') };
+      return;
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: 'error', error: '无法获取响应流' };
+      return;
+    }
+
+    yield* this.parseSSE(reader);
+  }
+
+  /**
+   * 构建请求体
+   */
+  private buildRequestBody(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): Record<string, unknown> {
+    const { systemInstruction, contents } = this.convertMessages(messages);
+
+    const body: Record<string, unknown> = {
+      contents,
+      generationConfig: {
+        maxOutputTokens: options.familyConfig.defaultMaxTokens ?? 65536,
+      },
+    };
+
+    if (systemInstruction) {
+      body.systemInstruction = systemInstruction;
+    }
+
+    // 启用 thinking（需要 includeThoughts 才能输出思考内容）
+    if (options.enableThinking) {
+      (body.generationConfig as Record<string, unknown>).thinkingConfig = {
+        thinkingBudget: 24576,
+        includeThoughts: true,
+      };
+    }
+
+    // 构建工具
+    // 注意：Gemini 的 googleSearch 工具不能与其他函数调用工具同时使用
+    // 因此：如果有其他工具，则通过 web_search 工具（Tavily）进行搜索
+    // 如果没有其他工具，可以使用原生 googleSearch
+    const geminiTools: unknown[] = [];
+
+    // 添加函数调用工具：按名称去重（混合模式可能传入重复）
+    if (tools.length > 0) {
+      const decls = tools.map(t => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      }));
+      const byName = new Map<string, { name: string; description: string; parameters: object }>();
+      for (const d of decls) {
+        if (!byName.has(d.name)) byName.set(d.name, d);
+      }
+      geminiTools.push({
+        functionDeclarations: Array.from(byName.values()),
+      });
+    }
+    // 仅在没有其他工具时使用原生 Google Search
+    else if (options.enableSearch) {
+      geminiTools.push({ googleSearch: {} });
+    }
+
+    if (geminiTools.length > 0) {
+      body.tools = geminiTools;
+    }
+
+    return body;
+  }
+
+  /**
+   * 转换消息格式
+   */
+  private convertMessages(messages: ProtocolMessage[]): {
+    systemInstruction?: { parts: { text: string }[] };
+    contents: unknown[];
+  } {
+    let systemInstruction: { parts: { text: string }[] } | undefined;
+    const contents: unknown[] = [];
+
+    for (const msg of messages) {
+      switch (msg.role) {
+        case 'system':
+          systemInstruction = { parts: [{ text: msg.content }] };
+          break;
+
+        case 'user': {
+          // 当只有图片没有文字时提供默认提示
+          const textContent = msg.content || (msg.images?.length ? '请分析这张图片' : '');
+          const parts: unknown[] = [{ text: textContent }];
+          if (msg.images?.length) {
+            for (const img of msg.images) {
+              if (img.startsWith('data:')) {
+                const match = img.match(/^data:([^;]+);base64,(.+)$/);
+                if (match) {
+                  parts.push({
+                    inlineData: { mimeType: match[1], data: match[2] },
+                  });
+                }
+              } else {
+                parts.push({
+                  inlineData: { mimeType: 'image/jpeg', data: img },
+                });
+              }
+            }
+          }
+          contents.push({ role: 'user', parts });
+          break;
+        }
+
+        case 'assistant':
+          if (msg.toolCalls?.length) {
+            const parts: unknown[] = [];
+            for (const tc of msg.toolCalls) {
+              const funcPart: Record<string, unknown> = {
+                functionCall: {
+                  name: tc.name,
+                  args: JSON.parse(tc.arguments || '{}'),
+                },
+              };
+              // Gemini 3：每个 functionCall part 必须带 thoughtSignature，否则 400。
+              // 历史/跨模型回放可能没有，用官方 dummy 跳过校验。见 thought-signatures 文档。
+              funcPart.thoughtSignature = tc.thoughtSignature ?? GEMINI_THOUGHT_SIGNATURE_DUMMY;
+              parts.push(funcPart);
+            }
+            contents.push({ role: 'model', parts });
+          } else {
+            contents.push({ role: 'model', parts: [{ text: msg.content }] });
+          }
+          break;
+
+        case 'tool':
+          contents.push({
+            role: 'user',
+            parts: [{
+              functionResponse: {
+                name: msg.toolName || 'unknown',
+                response: { result: msg.content },
+              },
+            }],
+          });
+          break;
+      }
+    }
+
+    return { systemInstruction, contents };
+  }
+
+  /**
+   * 解析 SSE 流
+   */
+  private async *parseSSE(reader: ReadableStreamDefaultReader<Uint8Array>): AsyncGenerator<RawEvent> {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const pendingToolCalls = new Map<string, RawToolCall>();
+    let textStarted = false;
+    let toolCallIndex = 0;
+
+    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) continue;
+
+        try {
+          const json = JSON.parse(data);
+          const candidate = json.candidates?.[0];
+          if (!candidate?.content?.parts) continue;
+
+          for (const part of candidate.content.parts) {
+            // 处理文本（根据 thought 标志区分思考和回复）
+            if (part.text) {
+              if (part.thought === true) {
+                // 思考内容
+                yield { type: 'thinking_delta', delta: part.text };
+              } else {
+                // 正常回复
+                if (!textStarted) {
+                  textStarted = true;
+                  yield { type: 'thinking_done' };
+                }
+                yield { type: 'text_delta', delta: part.text };
+              }
+            }
+
+            // 处理函数调用
+            if (part.functionCall) {
+              const callId = `gemini-${toolCallIndex++}`;
+              const toolCall: RawToolCall = {
+                id: callId,
+                name: part.functionCall.name,
+                arguments: JSON.stringify(part.functionCall.args || {}),
+              };
+              // 捕获 thoughtSignature
+              if (part.thoughtSignature) {
+                toolCall.thoughtSignature = part.thoughtSignature;
+              }
+              pendingToolCalls.set(callId, toolCall);
+              yield { type: 'tool_call_start', toolCall: { id: callId, name: toolCall.name } };
+              yield { type: 'tool_call_done', toolCall };
+            }
+          }
+
+          // 处理 grounding metadata（搜索结果）
+          const groundingMeta = candidate.groundingMetadata;
+          if (groundingMeta?.groundingChunks?.length) {
+            const searchResults: RawSearchResult[] = [];
+            for (const chunk of groundingMeta.groundingChunks) {
+              if (chunk.web?.uri) {
+                searchResults.push({
+                  title: chunk.web.title || '',
+                  url: chunk.web.uri,
+                  snippet: '',
+                });
+              }
+            }
+            if (searchResults.length > 0) {
+              yield { type: 'search_result', searchResults };
+            }
+          }
+
+          // 检查是否结束
+          if (candidate.finishReason) {
+            // 提取 Token 使用统计（Gemini usageMetadata）
+            const meta = json.usageMetadata;
+            const usage = meta ? {
+              promptTokens: meta.promptTokenCount || 0,
+              completionTokens: meta.candidatesTokenCount || 0,
+              totalTokens: meta.totalTokenCount || 0,
+              reasoningTokens: meta.thoughtsTokenCount || 0,
+              cachedTokens: meta.cachedContentTokenCount || 0,
+            } : undefined;
+
+            if (pendingToolCalls.size > 0) {
+              yield { type: 'done', finishReason: 'tool_calls', usage };
+            } else {
+              yield { type: 'done', finishReason: 'stop', usage };
+            }
+            return;
+          }
+        } catch {
+          // 忽略解析错误
+        }
+      }
+    }
+
+    // 兜底
+    if (pendingToolCalls.size > 0) {
+      yield { type: 'done', finishReason: 'tool_calls' };
+    } else {
+      yield { type: 'done', finishReason: 'stop' };
+    }
+  }
+}
+
+/**
+ * 创建 Gemini Protocol
+ */
+export function createGeminiProtocol(config: ProtocolConfig): GeminiProtocol {
+  return new GeminiProtocol(config);
+}
+

package/src/providers/protocols/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Protocol Layer 导出
+ * 
+ * Protocol 只负责 HTTP/SSE 通信，不处理业务逻辑
+ * 
+ * 每个 Protocol 对应一种 API 协议：
+ * - ArkProtocol: 火山引擎 Responses API（豆包/DeepSeek）
+ * - QwenProtocol: 通义千问 DashScope API
+ * - GeminiProtocol: Google Gemini API
+ * - OpenAIProtocol: OpenAI API（通过 OpenRouter）
+ * - AnthropicProtocol: Anthropic API（通过 OpenRouter）
+ */
+
+// 类型
+export type {
+  RawEventType,
+  RawEvent,
+  RawToolCall,
+  RawSearchResult,
+  ProtocolToolCall,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  Protocol,
+  ProtocolConfig,
+  ProtocolFactory,
+} from './types';
+
+// 各 Protocol 实现
+export { ArkProtocol, createArkProtocol } from './ark';
+export { DeepSeekProtocol, createDeepSeekProtocol } from './deepseek';
+export { QwenProtocol, createQwenProtocol } from './qwen';
+export { GeminiProtocol, createGeminiProtocol } from './gemini';
+export { OpenAIProtocol, createOpenAIProtocol } from './openai';
+export { AnthropicProtocol, createAnthropicProtocol } from './anthropic';
+