@huyooo/ai-chat-core 0.2.45 → 0.3.2

package/src/protocols/deepseek.ts

@@ -0,0 +1,192 @@
+/**
+ * DeepSeek Protocol（原生 Chat Completions API）
+ *
+ * 基于 OpenAI 兼容格式：
+ * - 端点：https://api.deepseek.com/chat/completions
+ * - thinking：{ type: "enabled" }
+ * - SSE delta：reasoning_content（思考）+ content（正文）
+ * - 工具调用循环内需回传 reasoning_content
+ * - finish_reason 额外值：content_filter / insufficient_system_resource
+ *
+ * 文档：https://api-docs.deepseek.com/zh-cn/api/create-chat-completion
+ */
+
+import type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  RawEvent,
+} from './types';
+import { createModuleLogger } from '../logger';
+import { friendlyHttpError } from './error-utils';
+import { readSSEJsonStream } from './sse-reader';
+import { mapOpenAIStream } from './openai-sse';
+import type { OpenAIStreamConfig } from './openai-sse';
+
+const logger = createModuleLogger('DeepSeekProtocol');
+
+const DEFAULT_DEEPSEEK_URL = 'https://api.deepseek.com';
+
+const DEEPSEEK_SSE_CONFIG: OpenAIStreamConfig = {
+  thinkingField: (delta) => delta.reasoning_content as string | undefined,
+  errorFinishReasons: ['content_filter', 'insufficient_system_resource'],
+  protocolName: 'DeepSeek',
+  parseUsage: (usage) => ({
+    promptTokens: (usage.prompt_tokens as number) ?? 0,
+    completionTokens: (usage.completion_tokens as number) ?? 0,
+    totalTokens: (usage.total_tokens as number) ?? 0,
+    reasoningTokens: (usage.completion_tokens_details as Record<string, number> | undefined)?.reasoning_tokens ?? 0,
+    cachedTokens: (usage.prompt_cache_hit_tokens as number) ?? 0,
+  }),
+};
+
+export class DeepSeekProtocol implements Protocol {
+  readonly name = 'deepseek';
+
+  private apiKey: string;
+  private apiUrl: string;
+
+  constructor(config: ProtocolConfig) {
+    this.apiKey = config.apiKey;
+    this.apiUrl = config.apiUrl ?? DEFAULT_DEEPSEEK_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({
+      url,
+      model: options.model,
+      enableThinking: options.enableThinking,
+      toolsCount: tools.length,
+    }, '发送 DeepSeek 请求');
+
+    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({ status: response.status, body: errorText.slice(0, 500) }, 'DeepSeek API 错误');
+      yield { type: 'error', error: friendlyHttpError(response.status, errorText, 'DeepSeek') };
+      return;
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: 'error', error: '无法获取响应流' };
+      return;
+    }
+
+    yield* mapOpenAIStream(readSSEJsonStream(reader), DEEPSEEK_SSE_CONFIG);
+  }
+
+  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,
+      stream_options: { include_usage: true },
+      max_tokens: options.maxOutputTokens,
+    };
+
+    // DeepSeek thinking 参数格式与 GLM 一致
+    if (options.enableThinking) {
+      body.thinking = { type: 'enabled' };
+    }
+
+    if (tools.length > 0) {
+      body.tools = tools.map(t => ({
+        type: 'function',
+        function: {
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters,
+        },
+      }));
+    }
+
+    return body;
+  }
+
+  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) {
+            // 工具调用循环内需回传 reasoning_content 给 API
+            result.push({
+              role: 'assistant',
+              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: msg.content });
+          }
+          break;
+
+        case 'tool':
+          result.push({
+            role: 'tool',
+            tool_call_id: msg.toolCallId,
+            content: msg.content,
+          });
+          break;
+      }
+    }
+
+    return result;
+  }
+
+}
+
+export function createDeepSeekProtocol(config: ProtocolConfig): DeepSeekProtocol {
+  return new DeepSeekProtocol(config);
+}

package/src/{providers/protocols → protocols}/error-utils.ts

@@ -26,36 +26,30 @@ const STATUS_MESSAGES: Record<number, string> = {
  * @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 消息
+  // API 返回了具体错误信息：始终附加，截断过长内容防止 UI 溢出
   if (apiMessage) {
-    const msg = apiMessage.length > 200 ? apiMessage.slice(0, 200) + '...' : apiMessage;
-    return `${providerName} 错误 (${status}): ${msg}`;
+    const trimmed = apiMessage.length > 300 ? apiMessage.slice(0, 300) + '...' : apiMessage;
+    const prefix = statusMessage ?? `${providerName} 错误 (${status})`;
+    return `${prefix}（${trimmed}）`;
   }
 
-  // 4. 纯兜底
-  return `${providerName} 错误 (${status})`;
+  // 无 API 消息：已知 status 用友好文案，未知 status 兜底
+  return statusMessage ?? `${providerName} 错误 (${status})`;
 }
 
 /**
- * 尝试从 JSON 响应体中提取 error.message
- * 兼容格式：
- *   { "error": { "message": "..." } }          — OpenAI / Gemini / Vercel
- *   { "error_msg": "..." }                      — ARK
- *   { "message": "..." }                        — 通用
+ * 尝试从 JSON 响应体中提取错误消息
+ *
+ * 各供应商实测错误格式（2026-03 验证）：
+ *   { "error": { "message": "..." } }    — OpenAI / DeepSeek / Gemini / Claude / GLM / ARK / Moonshot
+ *   { "error": "字符串" }                  — Grok（error 直接是字符串，code 在顶层）
+ *   { "error_msg": "..." }                — ARK 部分旧接口
+ *   { "message": "..." }                  — Qwen / DashScope（顶层 message + code）
+ *   HTML / 非 JSON                        — MiniMax 某些错误，返回 null 用 status 兜底
  */
 function tryParseErrorBody(body: string): { message?: string; type?: string } | null {
   try {
@@ -63,6 +57,9 @@ function tryParseErrorBody(body: string): { message?: string; type?: string } |
     if (json?.error?.message) {
       return { message: json.error.message, type: json.error.type };
     }
+    if (typeof json?.error === 'string') {
+      return { message: json.error, type: json.code };
+    }
     if (typeof json?.error_msg === 'string') {
       return { message: json.error_msg };
     }

package/src/protocols/gemini.ts

@@ -0,0 +1,352 @@
+/**
+ * Gemini Protocol（Google 原生 API）
+ *
+ * 支持两种部署模式：
+ * - 直连 Google API：apiUrl 含 googleapis.com，Key 通过 URL 参数传递
+ * - CF Worker 代理：apiUrl 指向代理地址（如 https://proxy/google-ai-studio/v1beta），
+ *   Key 通过 Authorization 头传递，代理负责注入厂商 Key
+ */
+
+import type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  RawEvent,
+  RawOutputPart,
+  RawToolCall,
+} from './types';
+import { createModuleLogger } from '../logger';
+import { friendlyHttpError } from './error-utils';
+import { readSSEJsonStream } from './sse-reader';
+import { parseProtocolToolArguments } from './tool-arguments';
+
+const logger = createModuleLogger('GeminiProtocol');
+
+const DEFAULT_GEMINI_URL = 'https://generativelanguage.googleapis.com/v1beta';
+
+/**
+ * 历史中无 thoughtSignature 时使用的占位值（跳过 Gemini 校验）。
+ * 见 https://ai.google.dev/gemini-api/docs/thought-signatures
+ */
+const THOUGHT_SIGNATURE_DUMMY = 'skip_thought_signature_validator';
+
+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 = buildRequestBody(messages, tools, options);
+
+    // 直连 Google：Key 走 URL 参数；代理模式：Key 走 Authorization 头
+    const isDirect = this.apiUrl.includes('googleapis.com');
+    const url = isDirect
+      ? `${this.apiUrl}/models/${options.model}:streamGenerateContent?key=${this.apiKey}&alt=sse`
+      : `${this.apiUrl}/models/${options.model}:streamGenerateContent?alt=sse`;
+
+    logger.debug({
+      url: url.replace(this.apiKey, '***'),
+      model: options.model,
+      enableThinking: options.enableThinking,
+      toolsCount: tools.length,
+    }, 'Gemini 请求');
+
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (!isDirect) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      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) }, 'Gemini API 错误');
+      yield { type: 'error', error: friendlyHttpError(response.status, errorText, 'Gemini') };
+      return;
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: 'error', error: '无法获取响应流' };
+      return;
+    }
+
+    yield* parseGeminiSSE(reader);
+  }
+}
+
+// ==================== 请求体构建 ====================
+
+function buildRequestBody(
+  messages: ProtocolMessage[],
+  tools: ProtocolToolDefinition[],
+  options: ProtocolRequestOptions,
+): Record<string, unknown> {
+  const { systemInstruction, contents } = convertMessages(messages);
+
+  const body: Record<string, unknown> = {
+    contents,
+    generationConfig: {
+      maxOutputTokens: options.maxOutputTokens,
+    },
+  };
+
+  if (systemInstruction) {
+    body.systemInstruction = systemInstruction;
+  }
+
+  if (options.enableThinking) {
+    (body.generationConfig as Record<string, unknown>).thinkingConfig = {
+      thinkingBudget: 24576,
+      includeThoughts: true,
+    };
+  }
+
+  if (tools.length > 0) {
+    const byName = new Map<string, unknown>();
+    for (const t of tools) {
+      if (!byName.has(t.name)) {
+        byName.set(t.name, {
+          name: t.name,
+          description: t.description,
+          // 使用 parametersJsonSchema 而非 parameters：
+          // parameters 走 protobuf Schema 校验，字段受限（不支持 additionalProperties 等）；
+          // parametersJsonSchema 直接接受原始 JSON Schema，绕过 proto 限制。
+          // 二者互斥，见 https://ai.google.dev/api/caching#FunctionDeclaration
+          parametersJsonSchema: stripUnsupportedRefs(t.parameters),
+        });
+      }
+    }
+    body.tools = [{ functionDeclarations: Array.from(byName.values()) }];
+  }
+
+  return body;
+}
+
+// ==================== Schema 兼容 ====================
+//
+// 使用 parametersJsonSchema 而非 parameters 传递工具参数 schema。
+//
+// FunctionDeclaration 有两种互斥方式传参数 schema：
+// 1. parameters — 走 protobuf Schema 对象，字段严格受限
+//    （不支持 additionalProperties、prefixItems、$ref/$defs 等）
+// 2. parametersJsonSchema — 直接接受原始 JSON Schema（google.protobuf.Value）
+//    绕过 proto 限制，支持 additionalProperties、oneOf、allOf、const 等标准特性
+//
+// 我们选方案 2，TypeBox 输出的标准 JSON Schema 几乎可以直接透传。
+//
+// 唯一已知限制：$ref 不被支持（googleapis/python-genai#1122）
+// 副作用：$ref/$defs 被递归剥离 → Type.Ref() / Type.Recursive() 的引用丢失，
+// 被引用的位置变为无约束的空 schema，AI 靠 description 补偿。
+
+/**
+ * 递归剥离 $ref/$defs——Gemini parametersJsonSchema 唯一不支持的 JSON Schema 特性。
+ * 其它所有标准 JSON Schema 关键字（const、oneOf、allOf、additionalProperties、
+ * prefixItems 等）均直接透传，无需转换。
+ */
+export function stripUnsupportedRefs(schema: unknown): unknown {
+  if (schema == null || typeof schema !== 'object') return schema;
+  if (Array.isArray(schema)) return schema.map(stripUnsupportedRefs);
+
+  const obj = schema as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === '$ref' || key === '$defs') continue;
+    result[key] = stripUnsupportedRefs(value);
+  }
+
+  return result;
+}
+
+// ==================== 消息转换 ====================
+
+function 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 hasMedia = Boolean(msg.images?.length || msg.attachments?.length);
+        const textContent = msg.content || (hasMedia ? '请分析这个媒体文件' : '');
+        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 } });
+            }
+          }
+        }
+        if (msg.attachments?.length) {
+          for (const attachment of msg.attachments) {
+            parts.push({ fileData: { mimeType: attachment.mimeType, fileUri: attachment.fileUri } });
+          }
+        }
+        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: parseProtocolToolArguments(tc.arguments, {
+                  protocol: 'gemini',
+                  toolCallId: tc.id,
+                  toolName: tc.name,
+                }),
+              },
+            };
+            // Gemini 3：每个 functionCall part 必须带 thoughtSignature，否则 400
+            funcPart.thoughtSignature = tc.thoughtSignature ?? 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 流解析 ====================
+
+/**
+ * 解析 Gemini SSE 流
+ *
+ * Layer 1 负责 bytes → JSON，此处做 Gemini 原生格式的语义映射。
+ */
+async function* parseGeminiSSE(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+): AsyncGenerator<RawEvent> {
+  const pendingToolCalls = new Map<string, RawToolCall>();
+  const outputParts: RawOutputPart[] = [];
+  let textStarted = false;
+  let toolCallIndex = 0;
+
+  for await (const json of readSSEJsonStream(reader)) {
+    const candidates = json.candidates as Array<Record<string, unknown>> | undefined;
+    const candidate = candidates?.[0];
+    const content = candidate?.content as Record<string, unknown> | undefined;
+    const parts = content?.parts as Array<Record<string, unknown>> | undefined;
+    if (!parts) continue;
+
+    for (const part of parts) {
+      if (part.text && part.thought === true) {
+        yield { type: 'thinking_delta', delta: part.text as string };
+        continue;
+      }
+
+      if (part.text) {
+        outputParts.push({ type: 'text', text: part.text as string });
+        if (!textStarted) {
+          textStarted = true;
+          yield { type: 'thinking_done' };
+        }
+        yield { type: 'text_delta', delta: part.text as string };
+      }
+
+      if (part.inlineData) {
+        const inlineData = part.inlineData as Record<string, unknown>;
+        const mimeType = inlineData.mimeType;
+        const data = inlineData.data;
+        if (typeof mimeType === 'string' && typeof data === 'string') {
+          outputParts.push({ type: 'inline_data', mimeType, data });
+        }
+      }
+
+      if (part.functionCall) {
+        const fc = part.functionCall as Record<string, unknown>;
+        const callId = `gemini-${toolCallIndex++}`;
+        const toolCall: RawToolCall = {
+          id: callId,
+          name: fc.name as string,
+          arguments: JSON.stringify(fc.args || {}),
+        };
+        if (part.thoughtSignature) {
+          toolCall.thoughtSignature = part.thoughtSignature as string;
+        }
+        pendingToolCalls.set(callId, toolCall);
+        yield { type: 'tool_call_start', toolCall: { id: callId, name: toolCall.name } };
+        yield { type: 'tool_call_done', toolCall };
+      }
+    }
+
+    if (candidate?.finishReason) {
+      const meta = json.usageMetadata as Record<string, number> | undefined;
+      const usage = meta ? {
+        promptTokens: meta.promptTokenCount ?? 0,
+        completionTokens: meta.candidatesTokenCount ?? 0,
+        totalTokens: meta.totalTokenCount ?? 0,
+        reasoningTokens: meta.thoughtsTokenCount ?? 0,
+        cachedTokens: meta.cachedContentTokenCount ?? 0,
+      } : undefined;
+
+      yield {
+        type: 'done',
+        finishReason: pendingToolCalls.size > 0 ? 'tool_calls' : 'stop',
+        usage,
+        outputParts,
+      };
+      return;
+    }
+  }
+
+  yield {
+    type: 'done',
+    finishReason: pendingToolCalls.size > 0 ? 'tool_calls' : 'stop',
+    outputParts,
+  };
+}
+
+export function createGeminiProtocol(config: ProtocolConfig): GeminiProtocol {
+  return new GeminiProtocol(config);
+}