my-ai-chat-framework 2.7.0 → 4.0.0

package/src/core/Errors.js

@@ -1,60 +1,73 @@
-/**
- * 自定义错误类
- * 用于区分不同类型的错误，方便用户通过 `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
-  }
+/**
+ * 自定义错误类
+ * 用于区分不同类型的错误，方便用户通过 `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'
+  }
+}
+
+// 校验错误 （传参非法、索引越界、调用前提不满足等 —— 使用者传错了东西）
+// 继承 ConfigurationError：老的 `catch (e) { if (e instanceof ConfigurationError) }` 仍然命中，
+// 需要精细区分时用 `instanceof ValidationError`。
+export class ValidationError extends ConfigurationError {
+  /**
+   * @param {string} message - 错误消息
+   */
+  constructor(message) {
+    super(message)
+    this.name = 'ValidationError'
+  }
+}
+
+// 解析错误 （解析 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/MessageStore.js

@@ -91,6 +91,32 @@ export class MessageStore {
     }
     return [];
   }
+  /**
+   * 撤回到指定消息 id 的上一个用户消息，删除两者之间的所有消息
+   * 适用于重发
+   * @param {string} id — 目标消息 id
+   * @returns {Array} 被删除的消息列表
+   */
+  undoToPreviousUser(id) {
+    // 从后往前找到指定消息及其上一个用户消息，删除两者之间的所有消息
+    let targetIndex = -1;
+    let previousUserIndex = -1;
+    for (let i = this._messages.length - 1; i >= 0; i--) {
+      if (this._messages[i].id === id) {
+        targetIndex = i;
+      }
+      if (targetIndex >= 0 && this._messages[i].role === 'user') {
+        previousUserIndex = i;
+        break;
+      }
+    }
+    if (targetIndex >= 0 && previousUserIndex >= 0) {
+      const removed = this._messages.splice(previousUserIndex + 1, targetIndex - previousUserIndex);
+      return removed;
+    }
+    return [];
+  }
+
 
   /**
    * 更新消息：按 id 查找并合并 changes，不新增消息
@@ -109,4 +135,5 @@ export class MessageStore {
     }
     return null;
   }
+
 }

package/src/core/Pipeline.js

@@ -0,0 +1,48 @@
+/**
+ * Pipeline —— 极简顺序管道（v3.0 提案 · 阶段 1）
+ *
+ * 三个概念（对照 pipeline-demo.html）：
+ * - 小车 ctx   —— 本次请求的全部"状态"，车间之间只通过它交接
+ * - 车间 stage —— { name, run(ctx) }，只干一件事，不认别的车间
+ * - 调度 run()  —— for + await，顺序执行（线性，无"回程"；洋葱能力留给阶段 2 的 after 车间）
+ */
+
+export class Pipeline {
+  constructor() {
+    this._stages = [];
+  }
+
+  /**
+   * 注册一个车间（追加到末尾）。
+   * @param {{name: string, run: (ctx: object) => void | Promise<void>}} stage
+   * @returns {Pipeline} this，支持链式
+   */
+  register(stage) {
+    if (!stage || typeof stage.run !== 'function') {
+      throw new TypeError('Pipeline.register: stage 需要 { name, run(ctx) }，运行 run 必须是函数');
+    }
+    this._stages.push(stage);
+    return this;
+  }
+
+  /** 按名字移除车间（移除不存在的名字是安全的） */
+  unregister(name) {
+    this._stages = this._stages.filter(s => s.name !== name);
+    return this;
+  }
+
+  /** 列出当前车间名（调试用） */
+  names() {
+    return this._stages.map(s => s.name);
+  }
+
+  /** 把小车开过所有车间；返回 ctx（车间可改 ctx 上的字段） */
+  async run(ctx) {
+    for (const stage of this._stages) {
+      await stage.run(ctx);
+    }
+    return ctx;
+  }
+}
+
+export default Pipeline;

package/src/core/SystemPromptStore.js

@@ -1,118 +1,120 @@
-/**
- * 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 = [];
-  }
-}
+/**
+ * SystemPromptStore — 系统提示词存储
+ * 
+ * 职责：管理多条 system prompt 的增删改查与开关
+ * 与 MessageStore 分离，因为 system prompt 是"AI 行为准则"，不是对话事件
+ * 
+ * 每条记录格式：
+ * {
+ *   id: string,
+ *   content: string,
+ *   enabled: boolean,
+ *   timestamp: number
+ * }
+ */
+
+import { ValidationError } from './Errors.js';
+
+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 ValidationError('[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 ValidationError(`[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 ValidationError(`[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 ValidationError(`[SystemPromptStore] 索引越界: ${index}`);
+    }
+    if (!content || typeof content !== 'string' || !content.trim()) {
+      throw new ValidationError('[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 = [];
+  }
+}

package/src/index.js

@@ -2,10 +2,13 @@ export { ChatService } from './core/ChatService.js';
 export { MessageStore } from './core/MessageStore.js';
 export { SystemPromptStore } from './core/SystemPromptStore.js';
 export { EventEmitter } from './core/EventEmitter.js';
-export { openaiAdapter } from './adapters/openai.js';
-export { toolCallingPlugin } from './plugins/tool-calling.js';
-export { modelRegistryPlugin } from './plugins/model-registry.js';
+export { openaiAdapter, createOpenAIAdapter } from './adapters/openai.js';
+export { toolCallingPlugin, createToolCallingPlugin } from './plugins/tool-calling.js';
+export { modelRegistryPlugin, createModelRegistryPlugin } from './plugins/model-registry.js';
+export { continuationPlugin, createContinuationPlugin } from './plugins/continuation.js';
 export { MessageFormatter } from './utils/MessageFormatter.js';
 export { assembleMessages } from './utils/MessageFormatter.js';
 
-export { APIError, NetworkError, ConfigurationError, ParsingError } from './core/Errors.js';
+export { APIError, NetworkError, ConfigurationError, ValidationError, ParsingError } from './core/Errors.js';
+export { assertAdapter } from './core/ChatService.js';
+export { Pipeline } from './core/Pipeline.js';

package/src/plugins/continuation.js

@@ -0,0 +1,156 @@
+/**
+ * continuation 插件（v4.0）
+ *
+ * 「续写 / 临时消息」这套玩法住在这里 —— 核心不认识它，装上才有：
+ * 1. 续写检测（替换核心的 autoContinue 步骤）：底部若有带 prefix 标记的消息，就把结果合并回它
+ * 2. ephemeral 过滤器：临时消息只有"位于底部连续段"时才发给 API
+ * 3. continueLast / continueLastStream 两个 API
+ * 4. uninstall()：把自己装的东西全部还原（步骤、过滤器、方法）
+ *
+ * 用法：
+ *   import { createContinuationPlugin } from 'my-ai-chat-framework';
+ *   chat.use(createContinuationPlugin({ autoContinue: true }));
+ *
+ *   // 模拟思维链：注入一条临时引导，结果合并回上一条 assistant，不留痕
+ *   chat.messages.addOnceAssistant('（内心：他肯定又要熬夜）');
+ *   await chat.stream('在吗');
+ */
+
+import { MessageFormatter } from '../utils/MessageFormatter.js';
+import { ValidationError } from '../core/Errors.js';
+
+/**
+ * ephemeral 规则：只有底部连续的临时消息保留，其余丢弃（与 v3.x 核心内置行为一致）。
+ * 导出以便使用者直接注册到 MessageFormatter（不使用插件时也能用这条规则）。
+ */
+export function ephemeralFilterRule(msg, { index, messages }) {
+  if (!msg._ephemeral) return msg;
+  let start = messages.length;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]._ephemeral) start = i;
+    else break;
+  }
+  return index >= start ? msg : null;
+}
+
+/**
+ * 找续写目标：最后一条必须是 assistant 或临时消息（否则抛错）。
+ * @param {object} chat ChatService 实例
+ */
+export function prepareContinue(chat) {
+  const msgs = chat.messages.getAll();
+  const last = msgs[msgs.length - 1];
+  if (last && (last.role === 'assistant' || last._ephemeral)) return last;
+  throw new ValidationError('最后一条消息不是 assistant，无法续写');
+}
+
+/** 续写结束后的"转正" */
+function finalize(chat, targetId) {
+  chat.messages.update(targetId, { _complete: true, prefix: undefined, _ephemeral: false });
+}
+
+/**
+ * 创建续写插件实例（工厂）
+ * @param {Object} [options] — { autoContinue?: boolean }  是否自动识别底部 prefix 消息并合并（默认 false）
+ */
+export function createContinuationPlugin(options = {}) {
+  return {
+    name: 'continuation',
+    _options: { autoContinue: false, ...options },
+    _prevEphemeralFilter: undefined,
+    _installedOn: null,
+
+    /**
+     * 安装：替换续写步骤 + 接管 ephemeral 过滤 + 挂续写 API
+     * @param {import('../core/ChatService.js').ChatService} chat
+     */
+    install(chat) {
+      this._installedOn = chat;
+
+      // 0) 登记可运行时修改的配置字段（v4.0：插件自带配置，不用改核心白名单）
+      if (typeof chat.registerConfigKeys === 'function') {
+        chat.registerConfigKeys({ autoContinue: (v) => typeof v === 'boolean' });
+      }
+
+      // 1) 续写检测（用 v3.1 的出口替换核心的 autoContinue 步骤）
+      chat.replaceStage('autoContinue', (ctx) => {
+        // 运行时 `chat.updateConfig({ autoContinue })` 优先，其次取安装时的工厂 options
+        const enabled = chat.config.autoContinue ?? this._options.autoContinue;
+        if (!enabled) return;                             // 默认关：不替用户做选择
+        if (ctx.mergeToEntry) return;
+        const last = ctx.messages.getLast();
+        if (last && last.prefix && (last.role === 'assistant' || last._ephemeral)) {
+          ctx.mergeToEntry = last.id;
+        }
+      });
+
+      // 2) 接管 ephemeral 过滤（同名覆盖；保存旧函数，卸载时还原）
+      this._prevEphemeralFilter = MessageFormatter.registerFilter('ephemeral', ephemeralFilterRule, { priority: 100 });
+
+      // 3) 续写 API（通过 chat.plugins.continuation 暴露，v4.0 命名空间）
+      const continueLast = async () => {
+        const target = prepareContinue(chat);
+        chat.messages.update(target.id, { prefix: true });
+        try {
+          await chat.sendExisting(undefined, { mergeToEntry: target.id });
+          finalize(chat, target.id);
+          return target;
+        } catch (err) {
+          finalize(chat, target.id);
+          if (err.name === 'AbortError') {
+            chat.emit('aborted', { timestamp: Date.now() });
+            return target;
+          }
+          throw err;
+        }
+      };
+
+      const continueLastStream = async (onProgress, onDone) => {
+        const target = prepareContinue(chat);
+        chat.messages.update(target.id, { prefix: true });
+        const baseLen = (target.content || '').length;
+        try {
+          await chat.sendExistingStream(
+            undefined,
+            { mergeToEntry: target.id },
+            (chunk) => { if (onProgress) onProgress({ ...chunk, content: (chunk.content || '').slice(baseLen) }); },
+            (final) => { if (onDone) onDone(final); }
+          );
+          finalize(chat, target.id);
+          return target;
+        } catch (err) {
+          finalize(chat, target.id);
+          if (err.name === 'AbortError') {
+            chat.emit('aborted', { timestamp: Date.now() });
+            return target;
+          }
+          throw err;
+        }
+      };
+
+      // 交给 use() 挂到 chat.plugins['continuation']
+      return { continueLast, continueLastStream, uninstall: () => this.uninstall(chat) };
+    },
+
+    /**
+     * 卸载：恢复被替换的步骤、还原过滤器、移除挂载的方法
+     * @param {import('../core/ChatService.js').ChatService} [chat]
+     */
+    uninstall(chat = this._installedOn) {
+      if (!chat) return chat;
+      if (typeof chat.restoreStage === 'function') chat.restoreStage('autoContinue');
+      if (this._prevEphemeralFilter) {
+        MessageFormatter.registerFilter('ephemeral', this._prevEphemeralFilter, { priority: 100 });
+      } else {
+        MessageFormatter.unregisterFilter('ephemeral');
+      }
+      if (chat.plugins && chat.plugins['continuation']) delete chat.plugins['continuation'];
+      if (typeof chat.unregisterConfigKeys === 'function') chat.unregisterConfigKeys(['autoContinue']);
+      this._installedOn = null;
+      return chat;
+    }
+  };
+}
+
+/** 兼容用单例（多实例场景请用工厂） */
+export const continuationPlugin = createContinuationPlugin();