my-ai-chat-framework 2.0.0 → 2.7.0

package/src/core/ChatService.js

@@ -1,110 +1,298 @@
-import { EventEmitter } from './EventEmitter.js';
-import { MessageStore } from './MessageStore.js';
-
-/**
- * 核心聊天服务
- * 极简设计：只负责消息存储、事件发射、插件管理、请求委托
- */
-export class ChatService extends EventEmitter {
-  constructor(config = {}) {
-    super();
-    this.config = {
-      apiKey: config.apiKey || '',
-      model: config.model || 'gpt-3.5-turbo',
-      ...config
-    };
-    this.messages = new MessageStore();
-    this._plugins = [];
-    this._adapter = null;      // 当前使用的 API 适配器
-    this._pendingRequest = null;
-  }
-
-  /**
-   * 加载插件
-   * @param {object} plugin - 必须包含 install 方法
-   */
-  use(plugin) {
-    if (typeof plugin.install === 'function') {
-      plugin.install(this);
-      this._plugins.push(plugin);
-    } else {
-      throw new Error('插件必须提供 install 方法');
-    }
-    return this;
-  }
-
-  /**
-   * 设置 API 适配器
-   */
-  setAdapter(adapter) {
-    this._adapter = adapter;
-    return this;
-  }
-
-  /**
-   * 发送消息（非流式）
-   * @param {string|object} input - 字符串或消息对象
-   */
-  async send(input) {
-    const userMsg = typeof input === 'string'
-      ? { role: 'user', content: input }
-      : { role: 'user', ...input };
-
-    this.messages.add(userMsg);
-    this.emit('sending', userMsg);
-
-    // 构建请求
-    const requestBody = this._adapter.buildRequest(this.messages.getAll(), this.config);
-    const response = await this._adapter.send(requestBody, this.config);
-    const assistantMsg = this._adapter.parseResponse(response);
-
-    this.messages.add(assistantMsg);
-    this.emit('message', assistantMsg);
-    return assistantMsg;
-  }
-
-  /**
-   * 流式发送消息
-   * @param {string|object} input
-   * @param {function} onProgress - 每次收到数据块时调用，参数为累积的当前消息对象
-   * @param {function} onDone - 完成时调用，参数为最终消息对象
-   */
-  async stream(input, onProgress, onDone) {
-    const userMsg = typeof input === 'string'
-      ? { role: 'user', content: input }
-      : { role: 'user', ...input };
-
-    this.messages.add(userMsg);
-    this.emit('sending', userMsg);
-
-    const requestBody = this._adapter.buildRequest(this.messages.getAll(), this.config);
-
-    let accumulated = { role: 'assistant', content: '' };
-    await this._adapter.stream(
-      requestBody,
-      this.config,
-      (chunk) => {
-        // 累积消息
-        if (chunk.content) accumulated.content += chunk.content;
-        if (chunk.toolCalls) accumulated.toolCalls = chunk.toolCalls;
-        if (chunk.reasoningContent) accumulated.reasoningContent = chunk.reasoningContent;
-        // 触发进度事件
-        this.emit('stream-progress', { ...accumulated });
-        if (onProgress) onProgress({ ...accumulated });
-      },
-      (finalMessage) => {
-        this.messages.add(finalMessage);
-        this.emit('message', finalMessage);
-        if (onDone) onDone(finalMessage);
-      }
-    );
-  }
-
-  /**
-   * 注册工具（由工具调用插件实现）
-   * 这里只留一个空方法，插件会覆盖它
-   */
-  registerTool(name, description, executor) {
-    throw new Error('工具调用插件未加载，请先使用 use(toolCallingPlugin)');
-  }
-}
+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
+  }
+}

package/src/core/EventEmitter.js

@@ -1,5 +1,6 @@
 /**
  * 极简事件发射器
+ * 支持同步/异步事件，handler 返回 Promise 时自动 await
  */
 export class EventEmitter {
   constructor() {
@@ -19,6 +20,9 @@ export class EventEmitter {
     else this._events.delete(event);
   }
 
+  /**
+   * 同步触发事件
+   */
   emit(event, data) {
     if (!this._events.has(event)) return;
     for (const handler of this._events.get(event)) {
@@ -29,4 +33,19 @@ export class EventEmitter {
       }
     }
   }
+
+  /**
+   * 异步触发事件，逐个 await handler
+   * handler 返回 Promise 时自动等待
+   */
+  async emitAsync(event, data) {
+    if (!this._events.has(event)) return;
+    for (const handler of this._events.get(event)) {
+      try {
+        await handler(data);
+      } catch (err) {
+        console.error(`事件 ${event} 处理出错:`, err);
+      }
+    }
+  }
 }

package/src/core/MessageStore.js

@@ -5,6 +5,10 @@
  *   id?: string,
  *   role: 'user'|'assistant'|'system'|'tool',
  *   content: string,
+ *   images?: Array<string>,   // 图片引用（URL / id），框架不存储图片数据
+ *   _ephemeral?: boolean,     // 临时消息：仅底部连续时参与请求，续写后转正
+ *   _complete?: boolean,      // 流式是否完成（false=未完成/中断）
+ *   prefix?: boolean,         // 前缀续写标记
  *   toolCalls?: Array,
  *   toolCallId?: string,
  *   timestamp?: number,
@@ -43,6 +47,23 @@ export class MessageStore {
     return this.add({ role: 'tool', content, toolCallId, metadata });
   }
 
+  /**
+   * 快速添加一次性的、带续写标记的 assistant 消息
+   * 适用于思维链引导、临时注入等场景
+   * @param {string} content  — 引导内容
+   * @param {Object} [options] — { reasoningContent, prefix }
+   * @returns {Object} 添加的消息
+   */
+  addOnceAssistant(content, options = {}) {
+    return this.add({
+      role: 'assistant',
+      content,
+      reasoningContent: options.reasoningContent,
+      prefix: options.prefix !== false,  // 默认开启续写
+      _ephemeral: true
+    });
+  }
+
   getLast() {
     return this._messages[this._messages.length - 1] || null;
   }
@@ -70,4 +91,22 @@ export class MessageStore {
     }
     return [];
   }
+
+  /**
+   * 更新消息：按 id 查找并合并 changes，不新增消息
+   * @param {string} id — 消息 id
+   * @param {Object} changes — 要合并的字段
+   * @returns {Object|null} 更新后的消息，未找到返回 null
+   */
+  update(id, changes) {
+    for (const msg of this._messages) {
+      if (msg.id === id) {
+        Object.assign(msg, changes);
+        // 更新 timestamp 便于排查
+        msg.timestamp = changes.timestamp || Date.now();
+        return msg;
+      }
+    }
+    return null;
+  }
 }

package/src/core/SystemPromptStore.js

@@ -0,0 +1,118 @@
+/**
+ * SystemPromptStore — 系统提示词存储
+ * 
+ * 职责：管理多条 system prompt 的增删改查与开关
+ * 与 MessageStore 分离，因为 system prompt 是"AI 行为准则"，不是对话事件
+ * 
+ * 每条记录格式：
+ * {
+ *   id: string,
+ *   content: string,
+ *   enabled: boolean,
+ *   timestamp: number
+ * }
+ */
+
+export class SystemPromptStore {
+  constructor() {
+    this._prompts = [];
+    this._idCounter = 0;
+  }
+
+  /**
+   * 添加一条 system prompt
+   * @param {string} content — 提示词内容
+   * @param {boolean} [enabled=true] — 是否启用
+   * @returns {Object} 添加的记录
+   */
+  add(content, enabled = true) {
+    if (!content || typeof content !== 'string' || !content.trim()) {
+      throw new Error('[SystemPromptStore] content 必须是非空字符串');
+    }
+    const record = {
+      id: `sys_${Date.now()}_${++this._idCounter}`,
+      content: content.trim(),
+      enabled: Boolean(enabled),
+      timestamp: Date.now()
+    };
+    this._prompts.push(record);
+    return record;
+  }
+
+  /**
+   * 删除指定索引的 system prompt
+   * @param {number} index
+   * @returns {Object} 被删除的记录
+   */
+  remove(index) {
+    if (index < 0 || index >= this._prompts.length) {
+      throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
+    }
+    return this._prompts.splice(index, 1)[0];
+  }
+
+  /**
+   * 切换指定索引的启用/禁用状态
+   * @param {number} index
+   * @returns {boolean} 切换后的状态
+   */
+  toggle(index) {
+    if (index < 0 || index >= this._prompts.length) {
+      throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
+    }
+    this._prompts[index].enabled = !this._prompts[index].enabled;
+    return this._prompts[index].enabled;
+  }
+
+  /**
+   * 更新指定索引的 content
+   * @param {number} index
+   * @param {string} content
+   */
+  update(index, content) {
+    if (index < 0 || index >= this._prompts.length) {
+      throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
+    }
+    if (!content || typeof content !== 'string' || !content.trim()) {
+      throw new Error('[SystemPromptStore] content 必须是非空字符串');
+    }
+    this._prompts[index].content = content.trim();
+    this._prompts[index].timestamp = Date.now();
+  }
+
+  /**
+   * 清空并用一条 content 替换（便捷方法，常用于 config.system = '...'）
+   * @param {string} content
+   */
+  set(content) {
+    this._prompts = [];
+    if (content && typeof content === 'string' && content.trim()) {
+      this.add(content, true);
+    }
+  }
+
+  /**
+   * 按 enabled 筛选后，转为适配器可用的格式
+   * @returns {Array<{role:'system', content:string}>}
+   */
+  getEnabled() {
+    return this._prompts
+      .filter(p => p.enabled)
+      .map(p => ({ role: 'system', content: p.content }));
+  }
+
+  /**
+   * 返回所有记录（含 enabled 状态，用于 UI 展示）
+   * @returns {Array}
+   */
+  getAll() {
+    return [...this._prompts];
+  }
+
+  /**
+   * 清空所有 system prompt
+   */
+  clear() {
+    this._prompts = [];
+  }
+}