my-ai-chat-framework 2.0.0 → 3.0.0

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,49 @@ 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，不新增消息
+   * @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/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

@@ -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 = [];
+  }
+}

package/src/index.js

@@ -1,15 +1,13 @@
-import { ChatService } from './core/ChatService.js';
-import { MessageStore } from './core/MessageStore.js';
-import { EventEmitter } from './core/EventEmitter.js';
-import { openaiAdapter } from './adapters/openai.js';
-import { toolCallingPlugin } from './plugins/tool-calling.js';
+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, createOpenAIAdapter } from './adapters/openai.js';
+export { toolCallingPlugin, createToolCallingPlugin } from './plugins/tool-calling.js';
+export { modelRegistryPlugin, createModelRegistryPlugin } from './plugins/model-registry.js';
+export { MessageFormatter } from './utils/MessageFormatter.js';
+export { assembleMessages } from './utils/MessageFormatter.js';
 
-export { ChatService, MessageStore, EventEmitter, openaiAdapter, toolCallingPlugin };
-
-export default {
-  ChatService,
-  MessageStore,
-  EventEmitter,
-  openaiAdapter,
-  toolCallingPlugin
-};
+export { APIError, NetworkError, ConfigurationError, ParsingError } from './core/Errors.js';
+export { assertAdapter } from './core/ChatService.js';
+export { Pipeline } from './core/Pipeline.js';

package/src/plugins/model-registry.js

@@ -0,0 +1,223 @@
+/**
+ * model-registry 插件
+ * 
+ * 职责：
+ * 1. 内置常用模型的能力标签表（model → capabilities 映射）
+ * 2. 安装时自动根据 config.model 查表，写入 config.capabilities
+ * 3. 监听 config-updated 事件，切换模型时自动同步能力
+ * 4. 提供 chat.registerModel()，允许用户追加/覆盖自定义模型
+ * 
+ * 能力标签字段（全部可选，缺失视为 false / 未知）：
+ * {
+ *   reasoning:    boolean — 是否返回 reasoning_content（思维链）
+ *   vision:       boolean — 是否支持图片输入
+ *   toolCalling:  boolean — 是否支持 function calling
+ *   streaming:    boolean — 是否支持流式传输
+ *   maxInputTokens:  number — 最大输入 token 数
+ *   maxOutputTokens: number — 最大输出 token 数
+ * }
+ * 
+ * 使用：
+ *   chat.use(modelRegistryPlugin);
+ *   // config.capabilities 现在已自动填充
+ *   chat.registerModel('my-custom-model', { toolCalling: true });
+ */
+
+// ====== 内置模型能力表 ======
+// 数据来源：各厂商官方文档（2026-05 快照），用户可通过 registerModel() 覆盖
+const BUILTIN_MODELS = {
+  // ---- DeepSeek ----
+  'deepseek-chat': {
+    reasoning: false,
+    vision: false,
+    toolCalling: true,
+    streaming: true,
+    maxInputTokens: 128000,
+    maxOutputTokens: 8192
+  },
+  'deepseek-reasoner': {
+    reasoning: true,
+    vision: false,
+    toolCalling: true,
+    streaming: true,
+    maxInputTokens: 128000,
+    maxOutputTokens: 8192
+  },
+
+  // ---- OpenAI ----
+  'gpt-4o': {
+    reasoning: false,
+    vision: true,
+    toolCalling: true,
+    streaming: true,
+    maxInputTokens: 128000,
+    maxOutputTokens: 16384
+  },
+  'gpt-4o-mini': {
+    reasoning: false,
+    vision: true,
+    toolCalling: true,
+    streaming: true,
+    maxInputTokens: 128000,
+    maxOutputTokens: 16384
+  },
+  'gpt-3.5-turbo': {
+    reasoning: false,
+    vision: false,
+    toolCalling: true,
+    streaming: true,
+    maxInputTokens: 16385,
+    maxOutputTokens: 4096
+  },
+  'o1': {
+    reasoning: true,
+    vision: false,
+    toolCalling: false,
+    streaming: false,
+    maxInputTokens: 200000,
+    maxOutputTokens: 100000
+  },
+  'o3-mini': {
+    reasoning: true,
+    vision: false,
+    toolCalling: true,
+    streaming: true,
+    maxInputTokens: 200000,
+    maxOutputTokens: 100000
+  },
+
+  // ---- Anthropic ----
+  'claude-3.5-sonnet': {
+    reasoning: false,
+    vision: true,
+    toolCalling: true,
+    streaming: true,
+    maxInputTokens: 200000,
+    maxOutputTokens: 8192
+  },
+  'claude-3.5-haiku': {
+    reasoning: false,
+    vision: true,
+    toolCalling: true,
+    streaming: true,
+    maxInputTokens: 200000,
+    maxOutputTokens: 8192
+  }
+};
+
+const DEFAULT_CAPABILITIES = {
+  streaming: true,
+  toolCalling: false,
+  reasoning: false,
+  vision: false
+};
+
+/**
+ * 注意：请使用 createModelRegistryPlugin() 工厂创建实例。
+ * 默认导出的 modelRegistryPlugin 是兼容用的模块级单例，装到多个 ChatService
+ * 实例会互相覆盖（注册表、实例引用），新代码不要直接用单例。
+ */
+export const modelRegistryPlugin = createModelRegistryPlugin();
+
+/**
+ * 创建模型能力注册表插件实例（工厂）。
+ * @param {Object} [options] — { models: { '模型名': capabilities } }（合并进内置表）
+ */
+export function createModelRegistryPlugin(options = {}) {
+  return {
+    name: 'model-registry',
+
+    _options: { ...options },
+    _registry: new Map([
+      ...Object.entries(BUILTIN_MODELS),
+      ...Object.entries(options.models || {})
+    ]),
+    chat: null,
+
+    /**
+     * 安装插件
+     * @param {ChatService} chatService - ChatService 实例
+     * @param {Object} [options] - 安装时配置（合并进 _options）
+     */
+    install(chatService, options = {}) {
+      this._options = { ...this._options, ...options };
+      this.chat = chatService;
+
+      /**
+       * 注册/覆盖一个模型的能力标签
+       * @param {string} name — 模型名称
+       * @param {Object} capabilities — 能力标签对象（部分字段即可，未提供的取默认值）
+       * @returns {ChatService}
+       */
+      chatService.registerModel = (name, capabilities = {}) => {
+        if (!name || typeof name !== 'string' || !name.trim()) {
+          throw new Error('[model-registry] 模型名称必须是非空字符串');
+        }
+        const merged = { ...DEFAULT_CAPABILITIES, ...capabilities };
+        this._registry.set(name.trim(), merged);
+        // 如果注册的模型与当前使用的模型同名，立即同步
+        if (chatService.config.model === name.trim()) {
+          this._syncCapabilities();
+        }
+        return chatService;
+      };
+
+      /**
+       * 列出所有已注册的模型名称
+       * @returns {Array<string>}
+       */
+      chatService.listModels = () => {
+        return [...this._registry.keys()];
+      };
+
+      // 安装时立即同步一次
+      this._syncCapabilities();
+
+      // 每次请求时按"本次生效的 model"（含请求级覆盖）解析 capabilities
+      // v3.0：beforeSend 车间，不再用 _hooks 钩子（时机与之前一致）
+      chatService.pipe({
+        name: 'model-registry-caps',
+        phase: 'beforeSend',
+        run: ({ config }) => {
+          if (!config.model) return;
+          const caps = this._registry.get(config.model);
+          if (caps) config.capabilities = { ...caps };
+        }
+      });
+
+      // 监听配置变更：model 变了就重新同步（兼容路径；请求时按生效 model 实时查表）
+      chatService.on('config-updated', ({ changes }) => {
+        if ('model' in changes) {
+          this._syncCapabilities();
+        }
+        // 如果用户手动改了 capabilities，用 merge 保留未指定的字段
+        if ('capabilities' in changes && !('model' in changes)) {
+          const current = this._lookupCapabilities();
+          if (current) {
+            chatService.config.capabilities = { ...current, ...changes.capabilities };
+          }
+        }
+      });
+    },
+
+    // ---- 内部方法 ----
+
+    /** 查表获取模型能力，未注册返回 null */
+    _lookupCapabilities() {
+      const model = this.chat.config.model;
+      if (!model) return null;
+      return this._registry.get(model) || null;
+    },
+
+    /** 将查到的能力写入 config.capabilities */
+    _syncCapabilities() {
+      const caps = this._lookupCapabilities();
+      if (caps) {
+        // 若用户已手动设了 capabilities，用模型的合并（用户值优先？还是模型优先？）
+        // 策略：模型优先，因为换了模型能力应该重置
+        this.chat.config.capabilities = { ...caps };
+      }
+      // 未注册的模型：不清除已有 capabilities，保留用户手动设的值
+    }
+  };
+}