@huyooo/ai-chat-core 0.2.19 → 0.2.21

package/src/providers/protocols/ark.ts

@@ -0,0 +1,362 @@
+/**
+ * ARK Protocol（火山引擎 Responses API）
+ * 
+ * 只负责：
+ * - HTTP 请求发送
+ * - SSE 流解析
+ * - 原始事件产出
+ */
+
+import type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  RawEvent,
+  RawToolCall,
+  RawSearchResult,
+} from './types';
+import { DEFAULT_ARK_URL } from '../../constants';
+import { DebugLogger } from '../../utils';
+import { friendlyHttpError } from './error-utils';
+import { WEB_SEARCH_TOOL_NAME } from '../../internal/web-search';
+
+const logger = DebugLogger.module('ArkProtocol');
+
+/**
+ * ARK Protocol 实现
+ */
+export class ArkProtocol implements Protocol {
+  readonly name = 'ark';
+
+  private apiKey: string;
+  private apiUrl: string;
+
+  constructor(config: ProtocolConfig) {
+    this.apiKey = config.apiKey;
+    this.apiUrl = config.apiUrl ?? DEFAULT_ARK_URL;
+  }
+
+  /**
+   * 发送请求并返回原始事件流
+   */
+  async *stream(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): AsyncGenerator<RawEvent> {
+    // 构建请求体
+    const requestBody = this.buildRequestBody(messages, tools, options);
+
+    logger.debug('发送 ARK 请求', {
+      url: `${this.apiUrl}/responses`,
+      model: options.model,
+      enableSearch: options.enableSearch,
+      enableThinking: options.enableThinking,
+      toolsCount: tools.length,
+    });
+
+    // 发送请求
+    const response = await fetch(`${this.apiUrl}/responses`, {
+      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('ARK API 错误', { status: response.status, body: errorText.slice(0, 500) });
+      yield { type: 'error', error: friendlyHttpError(response.status, errorText, 'ARK') };
+      return;
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: 'error', error: '无法获取响应流' };
+      return;
+    }
+
+    // 解析 SSE 流
+    yield* this.parseSSE(reader);
+  }
+
+  /**
+   * 构建请求体
+   */
+  private buildRequestBody(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): Record<string, unknown> {
+    const input = this.convertMessages(messages);
+
+    const body: Record<string, unknown> = {
+      model: options.model,
+      stream: true,
+      max_output_tokens: options.familyConfig.defaultMaxTokens ?? 32768,
+      input,
+      // ARK 不支持 include: ['usage']，通过 response.completed 事件的 usage 字段获取
+    };
+
+    // 构建工具列表（若已包含 web_search_ai 则不再加原生 web_search，统一走 Tavily）
+    const apiTools: unknown[] = [];
+    const hasWebSearchTool = tools.some(t => t.name === WEB_SEARCH_TOOL_NAME);
+
+    if (options.enableSearch && !hasWebSearchTool) {
+      apiTools.push({ type: 'web_search', max_keyword: 5, limit: 20 });
+    }
+
+    for (const t of tools) {
+      apiTools.push({
+        type: 'function',
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      });
+    }
+
+    if (apiTools.length > 0) {
+      body.tools = apiTools;
+    }
+
+    // 启用 thinking
+    if (options.enableThinking) {
+      body.thinking = { type: 'enabled' };
+    }
+
+    return body;
+  }
+
+  /**
+   * 转换消息格式
+   */
+  private convertMessages(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': {
+          // ARK API 要求 input_text 必须有内容，当只有图片时提供默认提示
+          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) {
+            // 如果 assistant 同时有文本和工具调用，先保留文本内容
+            // 避免模型丢失推理上下文导致重复调用工具
+            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: 'developer',
+              content: `[上一轮AI回复]: ${msg.content}`,
+            });
+          }
+          break;
+
+        case 'tool':
+          input.push({
+            type: 'function_call_output',
+            call_id: msg.toolCallId,
+            output: msg.content,
+          });
+          break;
+      }
+    }
+
+    return input;
+  }
+
+  /**
+   * 解析 SSE 流
+   */
+  private async *parseSSE(reader: ReadableStreamDefaultReader<Uint8Array>): AsyncGenerator<RawEvent> {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const pendingToolCalls = new Map<string, RawToolCall>();
+    let currentFunctionCallId: string | null = null;
+    const searchResults: RawSearchResult[] = [];
+    let streamDone = false;
+    let thinkingDone = false;
+    let textStarted = false;
+    let lastUsage: import('./types').RawTokenUsage | 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 (streamDone) continue;
+        if (!line.startsWith('data:')) continue;
+
+        const data = line.slice(5).trim();
+        if (data === '[DONE]') {
+          streamDone = true;
+
+          // 输出工具调用
+          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 };
+          }
+          return;
+        }
+
+        try {
+          const event = JSON.parse(data);
+
+          // 提取 Token 使用统计（response.completed 或任意事件的 usage）
+          const eventUsage = event.response?.usage || event.usage;
+          if (eventUsage) {
+            lastUsage = {
+              promptTokens: eventUsage.input_tokens || eventUsage.prompt_tokens || 0,
+              completionTokens: eventUsage.output_tokens || eventUsage.completion_tokens || 0,
+              totalTokens: (eventUsage.input_tokens || eventUsage.prompt_tokens || 0) + (eventUsage.output_tokens || eventUsage.completion_tokens || 0),
+              reasoningTokens: eventUsage.output_tokens_details?.reasoning_tokens || 0,
+              cachedTokens: eventUsage.input_tokens_details?.cached_tokens || 0,
+            };
+          }
+
+          switch (event.type) {
+            case 'response.output_item.added': {
+              const item = event.item;
+              if (item?.type === 'function_call' && item.call_id) {
+                currentFunctionCallId = item.call_id;
+                pendingToolCalls.set(item.call_id, {
+                  id: item.call_id,
+                  name: item.name || '',
+                  arguments: item.arguments || '',
+                });
+                yield { type: 'tool_call_start', toolCall: { id: item.call_id, name: item.name || '' } };
+              }
+              break;
+            }
+
+            case 'response.function_call_arguments.delta': {
+              if (currentFunctionCallId) {
+                const call = pendingToolCalls.get(currentFunctionCallId);
+                if (call) {
+                  call.arguments += event.delta || '';
+                  yield { type: 'tool_call_delta', toolCall: { id: currentFunctionCallId, arguments: event.delta || '' } };
+                }
+              }
+              break;
+            }
+
+            case 'response.function_call_arguments.done':
+            case 'response.output_item.done': {
+              const item = event.item;
+              if (item?.type === 'function_call' && item.call_id) {
+                const existing = pendingToolCalls.get(item.call_id);
+                pendingToolCalls.set(item.call_id, {
+                  id: item.call_id,
+                  name: item.name || existing?.name || '',
+                  arguments: item.arguments || existing?.arguments || '{}',
+                });
+              }
+              break;
+            }
+
+            case 'response.output_text.annotation.added': {
+              const annotation = event.annotation;
+              if (annotation?.url) {
+                const exists = searchResults.some(r => r.url === annotation.url);
+                if (!exists) {
+                  searchResults.push({
+                    title: annotation.title || annotation.text || '',
+                    url: annotation.url,
+                    snippet: annotation.summary || annotation.snippet || '',
+                  });
+                  yield { type: 'search_result', searchResults: [...searchResults] };
+                }
+              }
+              break;
+            }
+
+            case 'response.output_text.delta':
+              if (event.delta) {
+                // 首次收到 text 时，结束 thinking
+                if (!textStarted) {
+                  textStarted = true;
+                  if (!thinkingDone) {
+                    thinkingDone = true;
+                    yield { type: 'thinking_done' };
+                  }
+                }
+                yield { type: 'text_delta', delta: event.delta };
+              }
+              break;
+
+            case 'response.reasoning_summary_text.delta':
+              if (event.delta && !thinkingDone) {
+                yield { type: 'thinking_delta', delta: event.delta };
+              }
+              break;
+          }
+        } catch {
+          // 忽略解析错误
+        }
+      }
+    }
+
+    // 兜底处理
+    if (!streamDone) {
+      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 };
+      }
+    }
+  }
+}
+
+/**
+ * 创建 ARK Protocol
+ */
+export function createArkProtocol(config: ProtocolConfig): ArkProtocol {
+  return new ArkProtocol(config);
+}
+

package/src/providers/protocols/deepseek.ts

@@ -0,0 +1,344 @@
+/**
+ * DeepSeek Protocol（通过火山引擎 ARK API 访问）
+ * 
+ * 特点：
+ * - 支持 reasoning（深度思考）
+ * - 支持 web_search 原生搜索
+ * - 与豆包共用 ARK API，但行为可能有差异
+ */
+
+import type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  RawEvent,
+  RawToolCall,
+  RawSearchResult,
+} from './types';
+import { DEFAULT_ARK_URL } from '../../constants';
+import { DebugLogger } from '../../utils';
+import { friendlyHttpError } from './error-utils';
+import { WEB_SEARCH_TOOL_NAME } from '../../internal/web-search';
+
+const logger = DebugLogger.module('DeepSeekProtocol');
+
+/**
+ * DeepSeek Protocol 实现
+ */
+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_ARK_URL;
+  }
+
+  async *stream(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): AsyncGenerator<RawEvent> {
+    const requestBody = this.buildRequestBody(messages, tools, options);
+    const url = `${this.apiUrl}/responses`;
+
+    logger.debug('发送 DeepSeek 请求', {
+      url,
+      model: options.model,
+      enableSearch: options.enableSearch,
+      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('DeepSeek API 错误', { status: response.status, body: errorText.slice(0, 500) });
+      yield { type: 'error', error: friendlyHttpError(response.status, errorText, 'DeepSeek') };
+      return;
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: 'error', error: '无法获取响应流' };
+      return;
+    }
+
+    yield* this.parseSSE(reader, options.enableThinking);
+  }
+
+  /**
+   * 构建请求体（DeepSeek 专用）
+   */
+  private buildRequestBody(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): Record<string, unknown> {
+    const input = this.convertMessages(messages);
+
+    const body: Record<string, unknown> = {
+      model: options.model,
+      stream: true,
+      max_output_tokens: options.familyConfig.defaultMaxTokens ?? 32768,
+      input,
+      // 火山引擎 DeepSeek 端点不支持 include: ['usage']，通过 response.completed 等事件的 usage 字段获取
+    };
+
+    // 构建工具列表（若已包含 web_search_ai 则不再加原生 web_search，统一走 Tavily）
+    const apiTools: unknown[] = [];
+    const hasWebSearchTool = tools.some(t => t.name === WEB_SEARCH_TOOL_NAME);
+
+    if (options.enableSearch && !hasWebSearchTool) {
+      apiTools.push({ type: 'web_search', max_keyword: 5, limit: 20 });
+    }
+
+    for (const t of tools) {
+      apiTools.push({
+        type: 'function',
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      });
+    }
+
+    if (apiTools.length > 0) {
+      body.tools = apiTools;
+    }
+
+    // DeepSeek 启用 thinking（深度思考模式）
+    if (options.enableThinking) {
+      body.thinking = { type: 'enabled' };
+    }
+
+    return body;
+  }
+
+  private convertMessages(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) {
+            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: 'developer',
+              content: `[上一轮AI回复]: ${msg.content}`,
+            });
+          }
+          break;
+
+        case 'tool':
+          input.push({
+            type: 'function_call_output',
+            call_id: msg.toolCallId,
+            output: msg.content,
+          });
+          break;
+      }
+    }
+
+    return input;
+  }
+
+  /**
+   * 解析 SSE 流（DeepSeek 专用）
+   */
+  private async *parseSSE(
+    reader: ReadableStreamDefaultReader<Uint8Array>,
+    enableThinking: boolean
+  ): AsyncGenerator<RawEvent> {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const pendingToolCalls = new Map<string, RawToolCall>();
+    let currentFunctionCallId: string | null = null;
+    const searchResults: RawSearchResult[] = [];
+    let streamDone = false;
+    let thinkingDone = false;
+    let textStarted = false;
+    // Token 使用统计（保存最后一次的 usage）
+    let lastUsage: { promptTokens: number; completionTokens: number; totalTokens: number; reasoningTokens: 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 (streamDone) continue;
+        if (!line.startsWith('data:')) continue;
+
+        const data = line.slice(5).trim();
+        if (data === '[DONE]') {
+          streamDone = true;
+
+          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 };
+          }
+          return;
+        }
+
+        try {
+          const event = JSON.parse(data);
+
+          // 提取 Token 使用统计（response.usage 或 Chat Completions usage）
+          const eventUsage = event.response?.usage || event.usage;
+          if (eventUsage) {
+            lastUsage = {
+              promptTokens: eventUsage.input_tokens || eventUsage.prompt_tokens || 0,
+              completionTokens: eventUsage.output_tokens || eventUsage.completion_tokens || 0,
+              totalTokens: (eventUsage.input_tokens || eventUsage.prompt_tokens || 0) + (eventUsage.output_tokens || eventUsage.completion_tokens || 0),
+              reasoningTokens: eventUsage.output_tokens_details?.reasoning_tokens || eventUsage.completion_tokens_details?.reasoning_tokens || 0,
+            };
+          }
+
+          switch (event.type) {
+            case 'response.output_item.added': {
+              const item = event.item;
+              if (item?.type === 'function_call' && item.call_id) {
+                currentFunctionCallId = item.call_id;
+                pendingToolCalls.set(item.call_id, {
+                  id: item.call_id,
+                  name: item.name || '',
+                  arguments: item.arguments || '',
+                });
+                yield { type: 'tool_call_start', toolCall: { id: item.call_id, name: item.name || '' } };
+              }
+              break;
+            }
+
+            case 'response.function_call_arguments.delta': {
+              if (currentFunctionCallId) {
+                const call = pendingToolCalls.get(currentFunctionCallId);
+                if (call) {
+                  call.arguments += event.delta || '';
+                  yield { type: 'tool_call_delta', toolCall: { id: currentFunctionCallId, arguments: event.delta || '' } };
+                }
+              }
+              break;
+            }
+
+            case 'response.function_call_arguments.done':
+            case 'response.output_item.done': {
+              const item = event.item;
+              if (item?.type === 'function_call' && item.call_id) {
+                const existing = pendingToolCalls.get(item.call_id);
+                pendingToolCalls.set(item.call_id, {
+                  id: item.call_id,
+                  name: item.name || existing?.name || '',
+                  arguments: item.arguments || existing?.arguments || '{}',
+                });
+              }
+              break;
+            }
+
+            case 'response.output_text.annotation.added': {
+              const annotation = event.annotation;
+              if (annotation?.url) {
+                const exists = searchResults.some(r => r.url === annotation.url);
+                if (!exists) {
+                  searchResults.push({
+                    title: annotation.title || annotation.text || '',
+                    url: annotation.url,
+                    snippet: annotation.summary || annotation.snippet || '',
+                  });
+                  yield { type: 'search_result', searchResults: [...searchResults] };
+                }
+              }
+              break;
+            }
+
+            case 'response.output_text.delta':
+              if (event.delta) {
+                if (!textStarted) {
+                  textStarted = true;
+                  if (enableThinking && !thinkingDone) {
+                    thinkingDone = true;
+                    yield { type: 'thinking_done' };
+                  }
+                }
+                yield { type: 'text_delta', delta: event.delta };
+              }
+              break;
+
+            // DeepSeek 支持 reasoning（深度思考）
+            case 'response.reasoning_summary_text.delta':
+              if (enableThinking && event.delta && !thinkingDone) {
+                yield { type: 'thinking_delta', delta: event.delta };
+              }
+              break;
+          }
+        } catch {
+          // 忽略解析错误
+        }
+      }
+    }
+
+    // 兜底
+    if (!streamDone) {
+      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 };
+      }
+    }
+  }
+}
+
+export function createDeepSeekProtocol(config: ProtocolConfig): DeepSeekProtocol {
+  return new DeepSeekProtocol(config);
+}
+