my-ai-chat-framework 1.1.0 → 2.7.0

package/src/adapters/openai.js

@@ -0,0 +1,280 @@
+/**
+ * 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';
+
+export const openaiAdapter = {
+  name: 'openai',
+
+  install(chatService) {
+    chatService.setAdapter(this);
+  },
+
+  /**
+   * 构建 OpenAI 格式的请求体
+   * @param {Array} messages - 内部消息列表
+   * @param {Object} config - 完整配置对象
+   * @param {Array} [systemPrompts=[]] - 启用的 system prompt 列表
+   * @returns {Object} 请求体
+   */
+  buildRequest(messages, config, systemPrompts = []) {
+    const model = config.model || config.modelParams?.model;
+    if (!model) {
+      throw new Error('Missing required config: model (either at top level or in modelParams)');
+    }
+
+    const temperature = config.modelParams?.temperature ?? config.temperature ?? 0.7;
+    const maxTokens = config.modelParams?.maxTokens ?? config.maxTokens ?? 2000;
+    const reasoningEffort = config.modelParams?.reasoningEffort ?? config.reasoningEffort;
+
+    // 用 MessageFormatter 统一处理：system 置顶、消息过滤、字段映射、图片解析
+    // format 由 config.messageFormat 指定（默认 'openai'）
+    const apiMessages = MessageFormatter.format({
+      messages,
+      systemPrompts,
+      capabilities: config.capabilities || {},
+      resolveImage: config.resolveImage,
+      format: config.messageFormat
+    });
+
+    const requestBody = {
+      model,
+      messages: apiMessages,
+      temperature,
+      max_tokens: maxTokens,
+      stream: false
+    };
+
+    if (config.tools && Array.isArray(config.tools) && config.tools.length > 0) {
+      requestBody.tools = config.tools;
+      requestBody.tool_choice = 'auto';
+    }
+
+    if (reasoningEffort && model === 'deepseek-reasoner') {
+      requestBody.reasoning_effort = reasoningEffort;
+    }
+
+    return requestBody;
+  },
+
+  /**
+ * 处理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 {
+      const url = this._getUrl(config);
+
+      const headers = {
+        'Content-Type': 'application/json',
+        '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;
+    }
+  },
+
+  /**
+   * 解析 API 响应为内部消息格式
+   */
+  parseResponse(apiResponse) {
+    // 检查响应结构是否有效
+    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;
+    return internal;
+  },
+
+  /**
+   * 流式发送
+   * @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 = {}) {
+    const streamBody = { ...requestBody, stream: true };
+    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) {
+      await this.handleErrorResponse(response);
+    }
+
+    // 解析流式响应
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    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 });
+      const lines = buffer.split(/\n\n/);
+      buffer = lines.pop();
+
+      for (const line of lines) {
+        const dataLine = line.replace(/^data: /, '').trim();
+        if (!dataLine) continue;
+        if (dataLine === '[DONE]') { reachedDone = true; break; }
+        try {
+          const chunk = JSON.parse(dataLine);
+          const delta = chunk.choices?.[0]?.delta;
+          if (!delta) continue;
+
+          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('stream parsing failed :', e, dataLine);
+        }
+      }
+    }
+
+    const finalMessage = {
+      role: 'assistant',
+      content: accumulated.content,
+      toolCalls: accumulated.toolCalls,
+      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);
+  }
+
+};

package/src/core/ChatService.js

@@ -0,0 +1,298 @@
+import { EventEmitter } from './EventEmitter.js';
+import { MessageStore } from './MessageStore.js';
+import { SystemPromptStore } from './SystemPromptStore.js';
+import { ConfigurationError, NetworkError } from './Errors.js';
+
+export class ChatService extends EventEmitter {
+  constructor(config = {}) {
+    super();
+    this.config = { ...config };
+    this.messages = new MessageStore();
+    this.systemPrompts = new SystemPromptStore();
+    this._adapter = null;
+    this._abortController = null;
+    this._isGenerating = false;
+    this._hooks = new EventEmitter();
+    this._processResponse = null;
+
+    const model = this.config.model || this.config.modelParams?.model;
+    if (!model || typeof model !== 'string' || !model.trim()) {
+      throw new ConfigurationError('缺少 model 配置');
+    }
+
+    const temperature = this.config.modelParams?.temperature ?? this.config.temperature;
+    if (temperature !== undefined && (typeof temperature !== 'number' || temperature < 0 || temperature > 2)) {
+      throw new ConfigurationError(`temperature 必须在 0-2 之间，当前值: ${temperature}`);
+    }
+
+    const maxTokens = this.config.modelParams?.maxTokens ?? this.config.maxTokens;
+    if (maxTokens !== undefined && (typeof maxTokens !== 'number' || maxTokens < 1 || !Number.isInteger(maxTokens))) {
+      throw new ConfigurationError(`maxTokens 必须为正整数，当前值: ${maxTokens}`);
+    }
+
+    if (typeof config.system === 'string' && config.system.trim()) {
+      this.systemPrompts.set(config.system);
+    }
+  }
+
+  use(plugin) {
+    plugin.install(this);
+    return this;
+  }
+
+  setAdapter(adapter) {
+    this._adapter = adapter;
+  }
+
+  abort() {
+    if (this._abortController) this._abortController.abort();
+  }
+
+  get isGenerating() { return this._isGenerating; }
+
+  async continueLast() {
+    const target = this._prepareContinue();
+    this.messages.update(target.id, { prefix: true });
+    try {
+      await this._request({ addUser: false, isStream: false, mergeToEntry: target.id });
+      this.messages.update(target.id, {
+        _complete: true, prefix: undefined, _ephemeral: undefined
+      });
+      return target;
+    } catch (err) {
+      this.messages.update(target.id, { prefix: undefined });
+      throw err;
+    }
+  }
+
+  async continueLastStream(onProgress, onDone) {
+    const target = this._prepareContinue();
+    console.log('[DEBUG] continueLastStream target.id:', target.id);
+    this.messages.update(target.id, { prefix: true });
+    const baseLen = (target.content || '').length;
+
+    try {
+      await this._request({
+        addUser: false, isStream: true, mergeToEntry: target.id,
+        onProgress: (chunk) => {
+          if (onProgress) {
+            onProgress({ ...chunk, content: (chunk.content || '').slice(baseLen) });
+          }
+        },
+        onDone: (final) => { if (onDone) onDone(final); }
+      });
+      this.messages.update(target.id, {
+        _complete: true, prefix: undefined, _ephemeral: undefined
+      });
+      return target;
+    } catch (err) {
+      this.messages.update(target.id, { prefix: undefined });
+      throw err;
+    }
+  }
+
+  _prepareContinue() {
+    const msgs = this.messages.getAll();
+    const last = msgs[msgs.length - 1];
+    if (last && (last.role === 'assistant' || last._ephemeral)) return last;
+    throw new Error('最后一条消息不是 assistant，无法续写');
+  }
+
+  updateConfig(partial) {
+    Object.assign(this.config, partial);
+    if (typeof partial.system === 'string') this.systemPrompts.set(partial.system);
+    this.emit('config-updated', { changes: partial, timestamp: Date.now() });
+  }
+
+  // ========== 编排角色 ==========
+  async _request(options) {
+    let { userInput, addUser = true, isStream = false, onProgress, onDone, mergeToEntry } = options;
+
+    this.emit('sending', { addUser, userInput, timestamp: Date.now() });
+    this._addUserMessage(userInput, addUser);
+
+    // 发送前钩子：在 adapter 转换 messages 之前执行，可修改 messages/config
+    await this._hooks.emitAsync('beforeRequest', {
+      messages: this.messages,
+      config: this.config,
+      options
+    });
+
+    // 自动续写：启用 autoContinue 时，检测底部是否有 prefix 标记的消息，自动设为续写目标
+    // 用于 ephemeral 注入场景：注入一条带 prefix 的引导消息后，自动合并结果回原消息
+    // 不启用时 prefix 仅透传给 API，结果仍作为新消息追加
+    if (this.config.ephemeralContinue && !mergeToEntry) {
+      const msgs = this.messages.getAll();
+      const last = msgs[msgs.length - 1];
+      if (last && last.prefix && (last.role === 'assistant' || last._ephemeral)) {
+        mergeToEntry = last.id;
+      }
+    }
+
+    const body = this._adapter.buildRequest(
+      this.messages.getAll(), this.config, this.systemPrompts.getEnabled()
+    );
+
+    const retryCfg = this.config.retry || {};
+    try {
+      return await this._withRetry(body, {
+        isStream, onProgress, onDone, mergeToEntry,
+        maxRetries: retryCfg.maxRetries ?? 0,
+        retryDelay: retryCfg.retryDelay ?? 1000
+      });
+    } catch (error) {
+      this.emit('error', { error, timestamp: Date.now() });
+      throw error;
+    }
+  }
+
+  _addUserMessage(userInput, addUser) {
+    if (addUser && userInput !== undefined) {
+      const msg = typeof userInput === 'string'
+        ? { role: 'user', content: userInput }
+        : { role: 'user', ...userInput };
+      this.messages.add(msg);
+    }
+  }
+
+  /** retry 循环，占位消息只 push 一次 */
+  async _withRetry(body, { isStream, onProgress, onDone, mergeToEntry, maxRetries, retryDelay }) {
+    let lastError = null;
+    const adapterOptions = { signal: this._abortController?.signal };
+
+    let placeholder = null;
+    let base = null;
+    if (isStream) {
+      if (mergeToEntry) {
+        placeholder = this.messages.getAll().find(m => m.id === mergeToEntry);
+        if (placeholder) base = { content: placeholder.content || '', reasoning: placeholder.reasoningContent || '' };
+      }
+      if (!placeholder) {
+        placeholder = this.messages.add({ role: 'assistant', content: '', _complete: false });
+      }
+    }
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      if (attempt > 0) {
+        this.emit('retry', { attempt, maxRetries, lastError, timestamp: Date.now() });
+        await new Promise(r => setTimeout(r, retryDelay));
+      }
+      try {
+        this._isGenerating = true;
+        if (isStream) {
+          return await this._stream(body, adapterOptions, { placeholder, base, mergeToEntry, onProgress, onDone });
+        } else {
+          const resp = await this._adapter.send(body, this.config, adapterOptions);
+          let result = this._handleResult(this._adapter.parseResponse(resp), mergeToEntry);
+          // 响应后处理钩子（tool-calling 用），仅非续写时
+          if (this._processResponse && !mergeToEntry) {
+            result = await this._processResponse(result, { isStream: false });
+          }
+          return result;
+        }
+      } catch (error) {
+        lastError = error;
+        if (error.name === 'AbortError' || this._abortController?.signal.aborted) {
+          this._isGenerating = false; throw error;
+        }
+        if (error instanceof NetworkError && attempt < maxRetries) continue;
+        this._isGenerating = false; throw error;
+      }
+    }
+    this._isGenerating = false;
+    throw lastError;
+  }
+
+  /** 流式：ChatService 维护占位，adapter 只管解析 */
+  async _stream(body, adapterOptions, { placeholder, base, mergeToEntry, onProgress, onDone }) {
+    let finalMsg = null;
+
+    await this._adapter.stream(body, this.config,
+      (snap) => {
+        placeholder.content = snap.content || '';
+        if (snap.reasoningContent) placeholder.reasoningContent = snap.reasoningContent;
+        if (snap.toolCalls) placeholder.toolCalls = [...snap.toolCalls];
+        this.emit('stream-progress', snap);
+        if (onProgress) onProgress(snap);
+      },
+      async (final) => {
+        finalMsg = final;
+
+        if (this._processResponse && !mergeToEntry) {
+          finalMsg = await this._processResponse(finalMsg, {
+            isStream: true, onProgress, onDone
+          });
+        }
+
+        if (mergeToEntry && base) {
+          const newContent = base.content + (final.content || '');
+          const changes = { content: newContent, _complete: true };
+          if (final.reasoningContent) changes.reasoningContent = base.reasoning + final.reasoningContent;
+          if (final.toolCalls) changes.toolCalls = final.toolCalls;
+          this.messages.update(mergeToEntry, changes);
+          const updated = this.messages.getAll().find(m => m.id === mergeToEntry);
+          this.emit('message', updated);
+          if (onDone) onDone(updated);
+        } else {
+          placeholder._complete = true;
+          this.emit('message', finalMsg);
+          if (onDone) onDone(finalMsg);
+        }
+      },
+      adapterOptions
+    );
+    return mergeToEntry || finalMsg;
+  }
+
+  /** 非流式结果落位 */
+  _handleResult(assistantMsg, mergeToEntry) {
+    if (mergeToEntry) {
+      const entry = this.messages.getAll().find(m => m.id === mergeToEntry);
+      if (!entry) {
+        this.messages.add(assistantMsg);
+        this.emit('message', assistantMsg);
+        return assistantMsg;
+      }
+      const changes = {
+        content: (entry.content || '') + (assistantMsg.content || ''),
+        _complete: true
+      };
+      if (assistantMsg.reasoningContent) {
+        changes.reasoningContent = (entry.reasoningContent || '') + assistantMsg.reasoningContent;
+      }
+      if (assistantMsg.toolCalls) changes.toolCalls = assistantMsg.toolCalls;
+      this.messages.update(mergeToEntry, changes);
+      const updated = this.messages.getAll().find(m => m.id === mergeToEntry);
+      this.emit('message', updated);
+      return updated;
+    }
+    this.messages.add(assistantMsg);
+    this.emit('message', assistantMsg);
+    return assistantMsg;
+  }
+
+  // ========== 公共 API ==========
+  async send(userInput) {
+    this._abortController = new AbortController();
+    try { return await this._request({ userInput, addUser: true, isStream: false }); }
+    finally { this._abortController = null; this._isGenerating = false; }
+  }
+
+  async stream(userInput, onProgress, onDone) {
+    this._abortController = new AbortController();
+    try { return await this._request({ userInput, addUser: true, isStream: true, onProgress, onDone }); }
+    finally { this._abortController = null; this._isGenerating = false; }
+  }
+
+  async sendExisting() {
+    this._abortController = new AbortController();
+    try { return await this._request({ addUser: false, isStream: false }); }
+    finally { this._abortController = null; this._isGenerating = false; }
+  }
+
+  async sendExistingStream(onProgress, onDone) {
+    this._abortController = new AbortController();
+    try { return await this._request({ addUser: false, isStream: true, onProgress, onDone }); }
+    finally { this._abortController = null; this._isGenerating = false; }
+  }
+}

package/src/core/Errors.js

@@ -0,0 +1,60 @@
+/**
+ * 自定义错误类
+ * 用于区分不同类型的错误，方便用户通过 `error.name` 或 `instanceof` 处理
+ */
+
+// API 错误 （如 401 认证失败、400 参数错误、429 限流等）
+export class APIError extends Error {
+  /**
+   * @param {string} message - 错误消息(通常来自 API 响应)
+   * @param {number} statusCode - HTTP 状态码
+   * @param {any} originalError - 原始错误对象或相关信息
+   * @param {string} responseText - 原始响应文本（如果有）
+   */
+  constructor(message, statusCode, originalError, responseText) {
+    super(message)
+    this.name = 'APIError'
+    this.statusCode = statusCode
+    this.originalError = originalError
+    this.responseText = responseText
+  }
+}
+
+// 网络错误 （fetch 失败、连接超时等）
+export class NetworkError extends Error {
+  /**
+   * @param {string} message - 错误消息
+   * @param {any} originalError - 原始错误对象或相关信息
+   */
+  constructor(message, originalError) {
+    super(message)
+    this.name = 'NetworkError'
+    this.originalError = originalError
+  }
+}
+
+// 配置错误 （缺少必要配置项、配置项类型错误等）
+export class ConfigurationError extends Error {
+  /**
+   * @param {string} message - 错误消息
+   */
+  constructor(message) {
+    super(message)
+    this.name = 'ConfigurationError'
+  }
+}
+
+// 解析错误 （解析 API 响应失败、响应格式不正确，不符合预期等）
+export class ParsingError extends Error {
+  /**
+   * @param {string} message - 错误消息
+   * @param {any} originalError - 原始错误对象或相关信息  
+   * @param {string} responseText - 原始响应文本（如果有）
+   **/
+  constructor(message, originalError, responseText) {
+    super(message)
+    this.name = 'ParsingError'
+    this.originalError = originalError
+    this.responseText = responseText
+  }
+}