my-ai-chat-framework 2.0.0 → 3.0.0

package/src/adapters/openai.js

@@ -2,93 +2,263 @@
  * OpenAI 兼容 API 适配器
  * 支持 DeepSeek 等完全兼容 OpenAI 接口的服务
  */
+
+import { joinUrl } from "../utils/url.js";
+import { isString } from "../utils/typeCheck.js";
+import { APIError, NetworkError, ParsingError } from '../core/Errors.js';
+import { MessageFormatter } from '../utils/MessageFormatter.js';
+
+// 属于"运输层"的配置键：工厂实例持有，请求时覆盖 config 中同名项
+const TRANSPORT_KEYS = ['apiKey', 'baseUrl', 'apiUrl', 'path', 'headers'];
+
 export const openaiAdapter = {
   name: 'openai',
 
-  install(chatService) {
-    // 将自身设置为适配器
+  /**
+   * 安装适配器。
+   * - 单例（openaiAdapter）：options 无意义，配置从 chat.config 读取（平铺兼容路径）
+   * - 工厂实例（createOpenAIAdapter）：options 并入实例自持的运输配置
+   */
+  install(chatService, options = {}) {
+    if (this._transport) this._transport = { ...this._transport, ...options };
     chatService.setAdapter(this);
   },
 
-  buildRequest(messages, config) {
-    // 将内部消息格式转为 OpenAI 格式
-    const apiMessages = messages.map(msg => {
-      const base = { role: msg.role, content: msg.content };
-      if (msg.role === 'assistant' && msg.toolCalls) {
-        base.tool_calls = msg.toolCalls;
-      }
-      if (msg.role === 'tool' && msg.toolCallId) {
-        base.tool_call_id = msg.toolCallId;
-      }
-      return base;
+  /**
+   * 实例自持配置（运输层）覆盖调用方传入的 config 同名项。
+   * modelParams 特殊处理：深度合并（config 优先，transport 兜底）——
+   * 避免工厂实例的默认参数覆盖掉会话/请求级覆盖。
+   */
+  _resolveConfig(config) {
+    const transport = this._transport || {};
+    const resolved = { ...config, ...transport };
+    if (transport.modelParams) {
+      resolved.modelParams = { ...transport.modelParams, ...(config.modelParams || {}) };
+    }
+    return resolved;
+  },
+
+  /** 工厂实例可提供给会话层的"请求默认参数"（非运输键的部分） */
+  getRequestDefaults() {
+    if (!this._transport) return {};
+    const defaults = {};
+    for (const [key, value] of Object.entries(this._transport)) {
+      if (!TRANSPORT_KEYS.includes(key) && value !== undefined) defaults[key] = value;
+    }
+    return defaults;
+  },
+
+  /**
+   * 构建 OpenAI 格式的请求体
+   * @param {Array} messages - 内部消息列表
+   * @param {Object} config - 合并后的请求参数（含 model/temperature 等）
+   * @param {Array} [systemPrompts=[]] - 启用的 system prompt 列表
+   * @returns {Object} 请求体
+   */
+  buildRequest(messages, config, systemPrompts = []) {
+    config = this._resolveConfig(config);
+    const model = config.model || config.modelParams?.model;
+    if (!model) {
+      throw new Error('Missing required config: model (either at top level or in modelParams)');
+    }
+
+    const mp = config.modelParams || {};
+    const temperature = mp.temperature ?? config.temperature ?? 0.7;
+    const maxTokens = mp.maxTokens ?? config.maxTokens ?? 2000;
+    const reasoningEffort = mp.reasoningEffort ?? config.reasoningEffort;
+
+    // 用 MessageFormatter 统一处理：system 置顶、消息过滤、字段映射、图片解析
+    // format 由 config.messageFormat 指定（默认 'openai'）
+    const apiMessages = MessageFormatter.format({
+      messages,
+      systemPrompts,
+      capabilities: config.capabilities || {},
+      resolveImage: config.resolveImage,
+      format: config.messageFormat
     });
 
-    return {
-      model: config.model,
+    const requestBody = {
+      model,
       messages: apiMessages,
-      temperature: config.temperature ?? 0.7,
-      max_tokens: config.maxTokens ?? 2000,
-      stream: false  // 流式请求会在 stream 方法中单独处理
+      temperature,
+      max_tokens: maxTokens,
+      stream: false
     };
+
+    // 硬编码常用参数：驼峰命名，适配器负责转 API 格式
+    if (mp.topP !== undefined) requestBody.top_p = mp.topP;
+    if (mp.frequencyPenalty !== undefined) requestBody.frequency_penalty = mp.frequencyPenalty;
+    if (mp.presencePenalty !== undefined) requestBody.presence_penalty = mp.presencePenalty;
+    if (mp.stop !== undefined) requestBody.stop = mp.stop;
+    if (mp.responseFormat !== undefined) requestBody.response_format = mp.responseFormat;
+    if (mp.seed !== undefined) requestBody.seed = mp.seed;
+
+    if (config.tools && Array.isArray(config.tools) && config.tools.length > 0) {
+      requestBody.tools = config.tools;
+      requestBody.tool_choice = 'auto';
+    }
+
+    if (reasoningEffort !== undefined) {
+      requestBody.reasoning_effort = reasoningEffort;
+    }
+
+    // modelParams 中未被硬编码处理的字段，透传到请求体
+    const consumedKeys = new Set([
+      'model', 'temperature', 'maxTokens', 'reasoningEffort',
+      'topP', 'frequencyPenalty', 'presencePenalty',
+      'stop', 'responseFormat', 'seed'
+    ]);
+    for (const [key, value] of Object.entries(mp)) {
+      if (!consumedKeys.has(key) && value !== undefined) {
+        requestBody[key] = value;
+      }
+    }
+
+    return requestBody;
   },
 
-  async send(requestBody, config) {
-    const response = await fetch(config.apiUrl || 'https://api.openai.com/v1/chat/completions', {
-      method: 'POST',
-      headers: {
+  /**
+ * 处理URL相关配置，将其转换为完整请求URL
+ * @param {Object} config - 配置参数
+ * @returns {String} 实际请求地址
+ */
+  _getUrl(config) {
+    config = config || {};
+    const { apiUrl, baseUrl, path } = config;
+    // 默认 path 没有 v1 因为 baseUrl 一般包括版本号
+    const defaultPath = '/chat/completions';
+
+    if (apiUrl && isString(apiUrl)) {
+      return apiUrl;
+    }
+
+    if (baseUrl && isString(baseUrl)) {
+      const finalPath = (path && isString(path)) ? path : defaultPath;
+      return joinUrl(baseUrl, finalPath);
+    }
+
+    return 'https://api.openai.com/v1/chat/completions';
+  },
+
+  /**
+   * 非流式发送
+   * @param {Object} requestBody
+   * @param {Object} config
+   * @param {Object} [options] — { signal, headers: {...} }
+   */
+  async send(requestBody, config, options = {}) {
+    try {
+      config = this._resolveConfig(config);
+      const url = this._getUrl(config);
+
+      const headers = {
         'Content-Type': 'application/json',
-        'Authorization': `Bearer ${config.apiKey}`
-      },
-      body: JSON.stringify(requestBody)
-    });
-    if (!response.ok) {
-      const error = await response.text();
-      throw new Error(`API 请求失败: ${response.status} ${error}`);
+        'Authorization': `Bearer ${config.apiKey}`,
+        ...(config.headers || {}),
+        ...(options.headers || {})
+      };
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(requestBody),
+        signal: options.signal
+      });
+
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+
+      const data = await response.json();
+      return data;
+
+    } catch (error) {
+      if (error instanceof APIError) throw error;
+      if (error.name === 'AbortError') throw error;
+
+      if (error.name === 'TypeError' && error.message.includes('fetch')) {
+        throw new NetworkError(`Request failed: ${error.message}`, error);
+      }
+
+      throw error;
     }
-    const data = await response.json();
-    return data;
   },
 
+  /**
+   * 解析 API 响应为内部消息格式
+   */
   parseResponse(apiResponse) {
-    const choice = apiResponse.choices[0];
-    const msg = choice.message;
-    // 转换为内部格式
+    // 检查响应结构是否有效
+    if (!apiResponse || !apiResponse.choices || !apiResponse.choices[0] || !apiResponse.choices[0].message) {
+      throw new ParsingError('Invalid API response: missing choices or message', apiResponse, JSON.stringify(apiResponse));
+    }
+    // 将 API 响应转换为内部消息格式
+    const msg = apiResponse.choices[0].message;
     const internal = {
       role: msg.role,
       content: msg.content || '',
     };
-    if (msg.tool_calls) {
-      internal.toolCalls = msg.tool_calls;
-    }
-    if (msg.reasoning_content) {
-      internal.reasoningContent = msg.reasoning_content;
-    }
+    if (msg.tool_calls) internal.toolCalls = msg.tool_calls;
+    if (msg.reasoning_content) internal.reasoningContent = msg.reasoning_content;
     return internal;
   },
 
-  async stream(requestBody, config, onProgress, onDone) {
-    // 流式请求需要设置 stream: true
+  /**
+   * 流式发送
+   * @param {Object} requestBody
+   * @param {Object} config
+   * @param {Function} onProgress — 接收累积快照 { content, reasoningContent, toolCalls }
+   * @param {Function} onDone — 接收最终消息对象
+   * @param {Object} [options] — { signal, headers: {...} }
+   */
+  async stream(requestBody, config, onProgress, onDone, options = {}) {
+    config = this._resolveConfig(config);
     const streamBody = { ...requestBody, stream: true };
-    const response = await fetch(config.apiUrl || 'https://api.openai.com/v1/chat/completions', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${config.apiKey}`,
-        'Accept': 'text/event-stream'
-      },
-      body: JSON.stringify(streamBody)
-    });
+    const url = this._getUrl(config);
+    let response;
+
+    const headers = {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${config.apiKey}`,
+      'Accept': 'text/event-stream',
+      ...(config.headers || {}),
+      ...(options.headers || {})
+    };
+
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(streamBody),
+        signal: options.signal
+      });
+
+    } catch (error) {
+      if (error.name === 'AbortError') throw error;
+
+      if (error.name === 'TypeError' && error.message.includes('fetch')) {
+        throw new NetworkError(`Stream request failed: ${error.message}`, error);
+      }
+
+      throw error;
+    }
+
+    // 处理非 2xx 响应
     if (!response.ok) {
-      const error = await response.text();
-      throw new Error(`流式请求失败: ${response.status} ${error}`);
+      await this.handleErrorResponse(response);
     }
 
+    // 解析流式响应
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
-    let accumulated = { role: 'assistant', content: '' };
+    let accumulated = { role: 'assistant', content: '', reasoningContent: '' };
+    let reachedDone = false;  // 是否收到 [DONE]
 
     while (true) {
+      // 用户调用 abort() 后 signal.aborted 为 true，跳出循环
+      if (options.signal?.aborted) break;
+
       const { done, value } = await reader.read();
       if (done) break;
       buffer += decoder.decode(value, { stream: true });
@@ -97,28 +267,45 @@ export const openaiAdapter = {
 
       for (const line of lines) {
         const dataLine = line.replace(/^data: /, '').trim();
-        if (!dataLine || dataLine === '[DONE]') continue;
+        if (!dataLine) continue;
+        if (dataLine === '[DONE]') { reachedDone = true; break; }
         try {
           const chunk = JSON.parse(dataLine);
           const delta = chunk.choices?.[0]?.delta;
           if (!delta) continue;
 
-          const update = { role: delta.role || 'assistant', content: delta.content || '' };
-          if (delta.tool_calls) update.toolCalls = delta.tool_calls;
-          if (delta.reasoning_content) update.reasoningContent = delta.reasoning_content;
-
-          if (update.content) accumulated.content += update.content;
-          if (update.toolCalls) accumulated.toolCalls = update.toolCalls;
-          if (update.reasoningContent) accumulated.reasoningContent = update.reasoningContent;
+          if (delta.content) accumulated.content += delta.content;
+          if (delta.tool_calls) {
+            if (!accumulated.toolCalls) accumulated.toolCalls = [];
+            for (const toolCallDelta of delta.tool_calls) {
+              const index = toolCallDelta.index;
+              if (!accumulated.toolCalls[index]) {
+                accumulated.toolCalls[index] = {
+                  id: '',
+                  type: 'function',
+                  function: { name: '', arguments: '' }
+                };
+              }
+              if (toolCallDelta.id) accumulated.toolCalls[index].id = toolCallDelta.id;
+              if (toolCallDelta.type) accumulated.toolCalls[index].type = toolCallDelta.type;
+              if (toolCallDelta.function?.name) {
+                accumulated.toolCalls[index].function.name += toolCallDelta.function.name;
+              }
+              if (toolCallDelta.function?.arguments) {
+                accumulated.toolCalls[index].function.arguments += toolCallDelta.function.arguments;
+              }
+            }
+          }
+          if (delta.reasoning_content) accumulated.reasoningContent += delta.reasoning_content;
 
+          // 传出累积快照，ChatService 自行处理占位消息更新
           onProgress({ ...accumulated });
         } catch (e) {
-          console.warn('解析流式数据块失败:', e, dataLine);
+          console.warn('stream parsing failed :', e, dataLine);
         }
       }
     }
 
-    // 流结束，最终消息
     const finalMessage = {
       role: 'assistant',
       content: accumulated.content,
@@ -126,5 +313,43 @@ export const openaiAdapter = {
       reasoningContent: accumulated.reasoningContent
     };
     onDone(finalMessage);
+  },
+
+  /**
+   * 处理对话请求的非 2xx 响应，抛出 APIError，包含状态码、错误消息和原始响应文本
+   * @param {Response} response - fetch API 的 Response 对象
+   * @returns {Promise<never>} 抛出错误  
+   */
+  async handleErrorResponse(response) {
+    let errorText = await response.text();
+    let errorMessage = `HTTP ${response.status}`;
+    // 尝试从响应体中解析 JSON 格式的错误信息
+    try {
+      const errorJson = JSON.parse(errorText);
+      errorMessage = errorJson.error?.message || errorJson.message || errorText.slice(0, 200);
+    } catch (e) {
+      // 如果解析失败，使用原始文本（已截断）
+      errorMessage = errorText.length > 200 ? errorText.slice(0, 200) + '...' : errorText;
+    }
+    throw new APIError(errorMessage, response.status, null, errorText);
   }
+
 };
+
+/**
+ * 创建 OpenAI 兼容适配器实例（工厂）。
+ *
+ * 与单例 openaiAdapter 的区别：每个实例自持一份运输配置（apiKey/baseUrl/apiUrl/path/headers），
+ * 互不干扰——解决"同一适配器装到多个 ChatService 互相覆盖"的单例陷阱。
+ *
+ * 用法：
+ *   const adapter = createOpenAIAdapter({ apiKey, baseUrl, modelParams: { temperature: 0.8 } });
+ *   const chat = new ChatService({ adapter, model: 'deepseek-chat' });
+ *   chat.use(adapter);  // 或直接 new ChatService({ adapter })
+ *
+ * 非运输键（model/modelParams/messageFormat/resolveImage/capabilities 等）会作为
+ * "请求默认参数"供会话层合并，单次请求仍可覆盖。
+ */
+export function createOpenAIAdapter(options = {}) {
+  return { ...openaiAdapter, _transport: { ...options } };
+}