my-ai-chat-framework 2.0.0 → 2.7.0

package/src/index.js

@@ -1,15 +1,11 @@
-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 } from './adapters/openai.js';
+export { toolCallingPlugin } from './plugins/tool-calling.js';
+export { modelRegistryPlugin } 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';

package/src/plugins/model-registry.js

@@ -0,0 +1,187 @@
+/**
+ * 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
+};
+
+export const modelRegistryPlugin = {
+  name: 'model-registry',
+
+  install(chatService) {
+    this.chat = chatService;
+    // 合并内置表 + 用户通过 registerModel 追加的
+    this._registry = new Map(Object.entries(BUILTIN_MODELS));
+
+    /**
+     * 注册/覆盖一个模型的能力标签
+     * @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 变了就重新同步
+    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，保留用户手动设的值
+  }
+};

package/src/plugins/tool-calling.js

@@ -1,119 +1,213 @@
 /**
  * 工具调用插件
- * 拦截消息中的 tool_calls，执行注册的工具，并将结果插入对话，然后继续请求
+ * 功能：拦截助手消息中的 tool_calls，执行对应的工具，将结果作为 tool 消息加入对话，
+ *       然后自动继续对话（通过 sendExisting / sendExistingStream），直到没有新的工具调用。
+ * 
+ * 设计要点：
+ * - 支持普通请求和流式请求（通过 isStream 标志区分）
+ * - 支持多次工具调用循环（maxIterations 防止无限循环）
+ * - 串行执行工具（可后续升级为并行）
+ * - 工具执行失败时，仍然返回错误信息给 AI，而不是中断整个流程
+ * - 触发 tool-error 事件，方便用户监听工具执行异常
  */
 export const toolCallingPlugin = {
   name: 'tool-calling',
-  maxIterations: 5,  // 防止无限循环
+  maxIterations: 5,                // 最大工具调用循环次数，防止无限循环（例如 AI 反复请求同一工具）
 
+  /**
+   * 安装插件，覆盖 ChatService 的 registerTool、send、stream 方法
+   * @param {ChatService} chatService - ChatService 实例
+   */
   install(chatService) {
     this.chatService = chatService;
-    this._tools = new Map();   // 工具名 -> { executor, definition }
+    this._tools = new Map();        // 存储工具名 -> { executor, description }
 
-    // 覆盖 registerTool 方法
-    chatService.registerTool = (name, description, executor) => {
+    // 初始化 config.tools 数组（用于存放 OpenAI 格式的工具定义）
+    if (!chatService.config.tools) {
+      chatService.config.tools = [];
+    }
+
+    /**
+     * 注册工具
+     * @param {string} name - 工具名称（唯一标识）
+     * @param {string} description - 工具描述（告诉 AI 何时调用）
+     * @param {Function} executor - 异步执行函数，接收参数对象，返回结果（字符串或对象）
+     * @param {Object} parameters - JSON Schema 参数定义（可选，默认为空对象）
+     * @returns {ChatService} 返回 chatService 实例，支持链式调用
+     */
+    chatService.registerTool = (name, description, executor, parameters = {}) => {
+      // 保存执行器
       this._tools.set(name, { executor, description });
-      // 可选：同时生成工具定义，以便在请求中告知 AI
-      // 这里简化，依赖适配器在请求中自动包含工具定义（如果需要）
-      return chatService;
-    };
 
-    // 拦截发送流程：在发送前注入工具定义（如果需要）
-    // 在流式和非流式响应后检测 tool_calls
-    const originalSend = chatService.send;
-    chatService.send = async (input) => {
-      return this._handleWithTools(originalSend, input, false);
+      // 构建 OpenAI 兼容的工具定义
+      const toolDefinition = {
+        type: 'function',
+        function: {
+          name,
+          description,
+          parameters: {
+            type: 'object',
+            properties: parameters,
+            required: Object.keys(parameters).filter(key => parameters[key]?.required)
+          }
+        }
+      };
+      // 避免重复添加相同工具
+      const existing = chatService.config.tools.find(t => t.function.name === name);
+      if (!existing) {
+        chatService.config.tools.push(toolDefinition);
+      }
+      return chatService;
     };
 
-    const originalStream = chatService.stream;
-    chatService.stream = async (input, onProgress, onDone) => {
-      return this._handleWithTools(originalStream, input, true, onProgress, onDone);
+    // 注册响应后处理钩子，不再覆盖 send/stream
+    chatService._processResponse = async (response, { isStream, onProgress, onDone }) => {
+      return this._handleWithTools(response, isStream, onProgress, onDone);
     };
   },
 
-  async _handleWithTools(originalMethod, input, isStream, onProgress, onDone) {
+  /**
+   * 核心处理逻辑：检查响应 → 执行工具 → 继续请求 → 循环
+   * @param {Object} initialResponse - 初始 AI 响应
+   * @param {boolean} isStream - 是否流式
+   * @param {Function} onProgress - 流式进度回调
+   * @param {Function} onDone - 流式完成回调
+   * @returns {Promise<Object>} 最终 AI 响应
+   */
+  async _handleWithTools(initialResponse, isStream, onProgress, onDone) {
     const self = this;
     const chat = this.chatService;
     let iteration = 0;
 
-    // 包装回调，用于递归处理
+    /**
+     * 递归处理工具调用
+     * @param {Object} initialResponse - 初始 AI 响应（可能是第一次请求的响应）
+     * @returns {Promise<Object>} 最终 AI 响应（不含 tool_calls）
+     */
     async function processResponse(initialResponse) {
       let lastResponse = initialResponse;
       while (iteration < self.maxIterations) {
-        // 检查是否有工具调用
+        // 检查 AI 返回的消息中是否包含工具调用请求
         const toolCalls = lastResponse?.toolCalls;
         if (!toolCalls || toolCalls.length === 0) break;
 
         iteration++;
-        // 执行所有工具
-        const toolResults = [];
-        for (const call of toolCalls) {
-          const toolName = call.function?.name;
-          const args = JSON.parse(call.function?.arguments || '{}');
-          const tool = self._tools.get(toolName);
-          if (!tool) {
-            console.warn(`未找到工具: ${toolName}`);
-            toolResults.push({ tool_call_id: call.id, error: `工具 ${toolName} 未注册`, success: false });
-            continue;
-          }
-          try {
-            const result = await tool.executor(args);
-            toolResults.push({
-              tool_call_id: call.id,
-              content: typeof result === 'string' ? result : JSON.stringify(result),
-              success: true
-            });
-          } catch (err) {
-            console.error(`工具 ${toolName} 执行失败:`, err);
-            toolResults.push({ tool_call_id: call.id, error: err.message, success: false });
-          }
-        }
+        // 并行执行所有工具调用（彼此独立，不会因一个失败而阻塞其他）
+        const toolResults = await Promise.all(
+          toolCalls.map(async (call) => {
+            const toolName = call.function?.name;
+
+            // 解析参数（JSON.parse 可能失败，需单独 try/catch）
+            let args;
+            try {
+              args = JSON.parse(call.function?.arguments || '{}');
+            } catch (parseErr) {
+              chat.emit('tool-error', {
+                toolName: toolName || 'unknown',
+                error: parseErr,
+                toolCallId: call.id,
+                stage: 'parse',
+                timestamp: Date.now()
+              });
+              return {
+                tool_call_id: call.id,
+                error: `参数解析失败: ${parseErr.message}`,
+                success: false
+              };
+            }
+
+            const tool = self._tools.get(toolName);
+            if (!tool) {
+              chat.emit('tool-error', {
+                toolName,
+                error: new Error(`Tool not registered: ${toolName}`),
+                toolCallId: call.id,
+                stage: 'lookup',
+                timestamp: Date.now()
+              });
+              return {
+                tool_call_id: call.id,
+                error: `工具 ${toolName} 未注册`,
+                success: false
+              };
+            }
 
-        // 添加工具结果消息
+            try {
+              // 工具执行超时控制
+              const toolTimeout = chat.config.toolTimeout;
+              let execPromise = tool.executor(args);
+              if (toolTimeout && typeof toolTimeout === 'number' && toolTimeout > 0) {
+                const timeoutErr = new Error(`工具 ${toolName} 执行超时 (${toolTimeout}ms)`);
+                timeoutErr.name = 'ToolTimeoutError';
+                const timeoutPromise = new Promise((_, reject) =>
+                  setTimeout(() => reject(timeoutErr), toolTimeout)
+                );
+                execPromise = Promise.race([execPromise, timeoutPromise]);
+              }
+
+              const result = await execPromise;
+              chat.emit('tool-success', {
+                toolName,
+                result,
+                toolCallId: call.id,
+                timestamp: Date.now()
+              });
+              return {
+                tool_call_id: call.id,
+                content: typeof result === 'string' ? result : JSON.stringify(result),
+                success: true
+              };
+            } catch (err) {
+              const stage = err.name === 'ToolTimeoutError' ? 'timeout' : 'execute';
+              chat.emit('tool-error', {
+                toolName,
+                error: err,
+                toolCallId: call.id,
+                stage,
+                timestamp: Date.now()
+              });
+              return {
+                tool_call_id: call.id,
+                error: err.message,
+                success: false
+              };
+            }
+          })
+        );
+
+        // 将工具执行结果作为 tool 消息添加到对话历史
         for (const tr of toolResults) {
-          chat.messages.addTool(tr.content || tr.error, tr.tool_call_id);
+          // 注意：addTool 的第二个参数是 tool_call_id
+          // 如果工具执行失败且没有内容，则传递错误信息作为 content
+          const content = tr.success ? tr.content : (tr.error || '工具执行失败');
+          chat.messages.addTool(content, tr.tool_call_id);
         }
 
-        // 再次请求
+        // 再次请求 AI，获取基于工具结果的回复
         if (isStream) {
-          // 流式重新请求：需要重新构建请求体
-          const userMsg = chat.messages.getLast(); // 实际上应该重新生成请求
-          // 这里简化：直接调用原 stream 方法，但需要避免循环
-          // 实际实现需更细致，我们这里仅示意
+          // 流式继续：使用 sendExistingStream
           await new Promise((resolve) => {
-            originalStream.call(chat, null, (chunk) => {
-              if (onProgress) onProgress(chunk);
-              lastResponse = chunk;
-            }, (final) => {
-              lastResponse = final;
-              resolve();
-            });
+            chat.sendExistingStream(
+              (chunk) => {
+                if (onProgress) onProgress(chunk);
+                lastResponse = chunk;
+              },
+              (final) => {
+                lastResponse = final;
+                resolve();
+              }
+            );
           });
         } else {
-          const reqBody = chat._adapter.buildRequest(chat.messages.getAll(), chat.config);
-          const apiResp = await chat._adapter.send(reqBody, chat.config);
-          lastResponse = chat._adapter.parseResponse(apiResp);
+          // 非流式继续：使用 sendExisting
+          lastResponse = await chat.sendExisting();
         }
       }
       return lastResponse;
     }
 
-    if (isStream) {
-      // 流式模式
-      let finalMessage;
-      await originalMethod.call(chat, input,
-        (chunk) => {
-          if (onProgress) onProgress(chunk);
-        },
-        async (final) => {
-          finalMessage = await processResponse(final);
-          if (onDone) onDone(finalMessage);
-        }
-      );
-    } else {
-      const resp = await originalMethod.call(chat, input);
-      const final = await processResponse(resp);
-      return final;
-    }
+    // 初始响应已由 ChatService 发出，直接进入工具调用循环
+    const final = await processResponse(initialResponse);
+    return final;
   }
-};
+};