my-ai-chat-framework 2.0.0 → 3.0.0

package/src/plugins/tool-calling.js

@@ -1,119 +1,243 @@
 /**
  * 工具调用插件
- * 拦截消息中的 tool_calls，执行注册的工具，并将结果插入对话，然后继续请求
+ * 功能：拦截助手消息中的 tool_calls，执行对应的工具，将结果作为 tool 消息加入对话，
+ *       然后自动继续对话（通过 sendExisting / sendExistingStream），直到没有新的工具调用。
+ *
+ * 设计要点：
+ * - 支持普通请求和流式请求（通过 isStream 标志区分）
+ * - 支持多次工具调用循环（maxIterations 防止无限循环）
+ * - 并行执行工具
+ * - 工具执行失败时，仍然返回错误信息给 AI，而不是中断整个流程
+ * - 触发 tool-error 事件，方便用户监听工具执行异常
+ *
+ * 注意：请使用 createToolCallingPlugin() 工厂创建实例。
+ * 默认导出的 toolCallingPlugin 是兼容用的模块级单例，装到多个 ChatService
+ * 实例会互相覆盖（executor 表、工具定义、配置），新代码不要直接用单例。
  */
-export const toolCallingPlugin = {
-  name: 'tool-calling',
-  maxIterations: 5,  // 防止无限循环
-
-  install(chatService) {
-    this.chatService = chatService;
-    this._tools = new Map();   // 工具名 -> { executor, definition }
-
-    // 覆盖 registerTool 方法
-    chatService.registerTool = (name, description, executor) => {
-      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);
-    };
-
-    const originalStream = chatService.stream;
-    chatService.stream = async (input, onProgress, onDone) => {
-      return this._handleWithTools(originalStream, input, true, onProgress, onDone);
-    };
-  },
-
-  async _handleWithTools(originalMethod, input, isStream, onProgress, onDone) {
-    const self = this;
-    const chat = this.chatService;
-    let iteration = 0;
-
-    // 包装回调，用于递归处理
-    async function processResponse(initialResponse) {
-      let lastResponse = initialResponse;
-      while (iteration < self.maxIterations) {
-        // 检查是否有工具调用
-        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 });
+export const toolCallingPlugin = createToolCallingPlugin();
+
+/**
+ * 创建工具调用插件实例（工厂）。
+ * @param {Object} [options] — { timeout, maxIterations }
+ */
+export function createToolCallingPlugin(options = {}) {
+  return {
+    name: 'tool-calling',
+    maxIterations: options.maxIterations || 5, // 最大工具调用循环次数，防止无限循环
+    _options: { ...options },
+    _tools: new Map(),    // 工具名 -> { executor, description }
+    _toolDefs: [],        // OpenAI 格式的工具定义（按注册顺序）
+    chatService: null,
+
+    /**
+     * 安装插件：挂 registerTool、注册 beforeRequest 钩子注入工具定义、注册响应处理钩子
+     * @param {ChatService} chatService - ChatService 实例
+     * @param {Object} [options] - 安装时配置（合并进 _options）
+     */
+    install(chatService, options = {}) {
+      this._options = { ...this._options, ...options };
+      this.chatService = chatService;
+
+      // 每次请求前把工具定义注入到请求配置（v3.0：beforeSend 车间，不再用 _hooks 钩子）
+      chatService.pipe({
+        name: 'tool-calling-inject',
+        phase: 'beforeSend',
+        run: ({ config }) => {
+          if (this._toolDefs.length) config.tools = this._toolDefs;
+        }
+      });
+
+      /**
+       * 注册工具
+       * @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 });
+
+        // 构建 OpenAI 兼容的工具定义
+        const toolDefinition = {
+          type: 'function',
+          function: {
+            name,
+            description,
+            parameters: {
+              type: 'object',
+              properties: parameters,
+              required: Object.keys(parameters).filter(key => parameters[key]?.required)
+            }
           }
+        };
+        // 避免重复添加相同工具
+        const existing = this._toolDefs.find(t => t.function.name === name);
+        if (!existing) {
+          this._toolDefs.push(toolDefinition);
         }
+        return chatService;
+      };
 
-        // 添加工具结果消息
-        for (const tr of toolResults) {
-          chat.messages.addTool(tr.content || tr.error, tr.tool_call_id);
+      // 响应后处理（v3.0：afterSend 车间，不再占用 ChatService._processResponse 单座槽位）
+      chatService.pipe({
+        name: 'tool-calling-loop',
+        phase: 'afterSend',
+        run: async (ctx) => {
+          ctx.result = await this._handleWithTools(
+            ctx.result,
+            ctx.isStream,
+            ctx.onProgress || undefined,
+            ctx.onDone || undefined
+          );
         }
+      });
+    },
+
+    /**
+     * 核心处理逻辑：检查响应 → 执行工具 → 继续请求 → 循环
+     * @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;
 
-        // 再次请求
-        if (isStream) {
-          // 流式重新请求：需要重新构建请求体
-          const userMsg = chat.messages.getLast(); // 实际上应该重新生成请求
-          // 这里简化：直接调用原 stream 方法，但需要避免循环
-          // 实际实现需更细致，我们这里仅示意
-          await new Promise((resolve) => {
-            originalStream.call(chat, null, (chunk) => {
-              if (onProgress) onProgress(chunk);
-              lastResponse = chunk;
-            }, (final) => {
-              lastResponse = final;
-              resolve();
+      /**
+       * 递归处理工具调用
+       * @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 = 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 {
+                // 工具执行超时控制（工厂 options.timeout 优先，兼容旧 config.toolTimeout）
+                const toolTimeout = self._options.timeout ?? 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) {
+            // 注意：addTool 的第二个参数是 tool_call_id
+            // 如果工具执行失败且没有内容，则传递错误信息作为 content
+            const content = tr.success ? tr.content : (tr.error || '工具执行失败');
+            chat.messages.addTool(content, tr.tool_call_id);
+          }
+
+          // 再次请求 AI，获取基于工具结果的回复
+          if (isStream) {
+            // 流式继续：使用 sendExistingStream
+            await new Promise((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);
+          } else {
+            // 非流式继续：使用 sendExisting
+            lastResponse = await chat.sendExisting();
+          }
         }
+        return lastResponse;
       }
-      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);
+      // 初始响应已由 ChatService 发出，直接进入工具调用循环
+      const final = await processResponse(initialResponse);
       return final;
     }
-  }
-};
+  };
+}

package/src/utils/MessageFormatter.js

@@ -0,0 +1,204 @@
+/**
+ * MessageFormatter — 可注册的消息格式转换器
+ *
+ * 职责：
+ * 1. 内置 OpenA I兼容格式的转换逻辑
+ * 2. 支持 register(name, fn) 注册自定义格式（如 Anthropic、Gemini 等）
+ * 3. 统一处理 capabilities 过滤（reasoning、vision 等）
+ * 4. 所有适配器通过此工具获取 API 消息数组，消除重复代码
+ *
+ * 用法：
+ *   import { MessageFormatter } from 'my-ai-chat-framework';
+ *
+ *   // 使用内置格式
+ *   const msgs = MessageFormatter.format({
+ *     messages, systemPrompts, capabilities, resolveImage
+ *   });  // 默认 'openai'
+ *
+ *   // 注册自定义格式
+ *   MessageFormatter.register('anthropic', ({ messages, systemPrompts, capabilities }) => {
+ *     // 返回 Anthropic 格式的消息数组
+ *   });
+ */
+
+import { isString } from './typeCheck.js';
+
+// ====== 内置格式 ======
+
+const IS_URL = /^https?:\/\//i;
+
+function defaultResolveImage(imageId) {
+  if (IS_URL.test(imageId)) return { url: imageId };
+  return null;
+}
+
+function buildMultimodalContent(textContent, images, resolveImage) {
+  const content = [{ type: 'text', text: textContent }];
+  for (const ref of images) {
+    const resolved = resolveImage(ref);
+    if (!resolved) continue;
+    if (resolved.url) {
+      content.push({ type: 'image_url', image_url: { url: resolved.url } });
+    } else if (resolved.data) {
+      const mime = resolved.mimeType || 'image/png';
+      content.push({ type: 'image_url', image_url: { url: `data:${mime};base64,${resolved.data}` } });
+    }
+  }
+  return content;
+}
+
+/** OpenAI 兼容格式 */
+function toOpenAI({ messages, systemPrompts, capabilities, resolveImage }) {
+  const rImg = typeof resolveImage === 'function' ? resolveImage : defaultResolveImage;
+  const result = [];
+
+  // 1) system 置顶
+  for (const sp of systemPrompts) {
+    if (sp?.content && isString(sp.content) && sp.content.trim()) {
+      result.push({ role: 'system', content: sp.content.trim() });
+    }
+  }
+
+  // 2) 识别底部连续 ephemeral（只保留这些临时消息，其他 ephemeral 忽略）
+  let ephemEnd = messages.length;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]._ephemeral) ephemEnd = i;
+    else break;
+  }
+
+  // 3) 过滤 + 字段映射
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+
+    // ephemeral 消息：仅底部连续的保留，其余跳过
+    if (msg._ephemeral) {
+      if (i < ephemEnd) continue;
+      // 底部 ephemeral 按原始 role 处理，不加 _ephemeral 标记
+    }
+
+    // 非底部 ephemeral 的正常消息仍保留原有过滤
+    if (msg.role === 'system' && !msg._ephemeral) continue;
+
+    if (msg.role === 'tool') {
+      result.push({ role: 'tool', content: msg.content || '', tool_call_id: msg.toolCallId });
+      continue;
+    }
+
+    if (msg.role === 'assistant' && msg.toolCalls?.length) {
+      const entry = { role: 'assistant', content: msg.content || '', tool_calls: msg.toolCalls };
+      if (msg.prefix) entry.prefix = true;
+      if (capabilities?.reasoning && msg.reasoningContent) {
+        entry.reasoning_content = msg.reasoningContent;
+      }
+      result.push(entry);
+      continue;
+    }
+
+    // 常规消息
+    const hasText = msg.content && isString(msg.content) && msg.content.trim();
+    const hasImages = msg.images && Array.isArray(msg.images) && msg.images.length > 0;
+    if (!hasText && !hasImages) {
+      if (msg.role === 'assistant' && msg.prefix) {
+        const prefixEntry = { role: 'assistant', content: '', prefix: true };
+        if (capabilities?.reasoning && msg.reasoningContent) {
+          prefixEntry.reasoning_content = msg.reasoningContent;
+        }
+        result.push(prefixEntry);
+      }
+      continue;
+    }
+
+    const entry = { role: msg.role };
+
+    if (hasImages) {
+      if (!capabilities?.vision) {
+        throw new Error(
+          '[MessageFormatter] 消息包含图片但模型不支持视觉（capabilities.vision=false）。' +
+          '请切换模型或移除图片。'
+        );
+      }
+      entry.content = buildMultimodalContent(msg.content || '', msg.images, rImg);
+    } else {
+      entry.content = msg.content;
+    }
+
+    if (msg.prefix) entry.prefix = true;
+    // 常规 assistant 不回传 reasoningContent——API 自己会重新推理
+    result.push(entry);
+  }
+
+  return result;
+}
+
+// ====== 格式化器 ======
+
+export const MessageFormatter = {
+  _formats: new Map([
+    ['openai', toOpenAI]
+  ]),
+
+  /**
+   * 注册自定义格式
+   * @param {string} name — 格式名称（如 'anthropic', 'gemini'）
+   * @param {Function} fn — 转换函数，接收 { messages, systemPrompts, capabilities, resolveImage }，返回消息数组
+   */
+  register(name, fn) {
+    if (!name || typeof name !== 'string' || !name.trim()) {
+      throw new Error('[MessageFormatter] 格式名称必须是非空字符串');
+    }
+    if (typeof fn !== 'function') {
+      throw new Error('[MessageFormatter] 转换函数必须是 function');
+    }
+    this._formats.set(name.trim(), fn);
+  },
+
+  /**
+   * 移除自定义格式（内置格式不可移除）
+   * @param {string} name
+   */
+  unregister(name) {
+    if (name === 'openai') {
+      throw new Error('[MessageFormatter] 内置格式 "openai" 不可移除');
+    }
+    this._formats.delete(name);
+  },
+
+  /**
+   * 列出所有已注册的格式名称
+   * @returns {Array<string>}
+   */
+  listFormats() {
+    return [...this._formats.keys()];
+  },
+
+  /**
+   * 按指定格式转换消息
+   * @param {Object} options
+   * @param {Array}  options.messages        — 内部消息列表
+   * @param {Array}  [options.systemPrompts=[]] — 启用的 system prompt
+   * @param {Object} [options.capabilities={}]  — 模型能力标签
+   * @param {Function} [options.resolveImage]   — 图片解析钩子
+   * @param {string} [options.format='openai']  — 目标格式名称
+   * @returns {Array<Object>}
+   */
+  format(options = {}) {
+    const formatName = options.format || 'openai';
+    const fn = this._formats.get(formatName);
+    if (!fn) {
+      throw new Error(
+        `[MessageFormatter] 未知格式 "${formatName}"。可用格式: ${[...this._formats.keys()].join(', ')}`
+      );
+    }
+    return fn({
+      messages: options.messages || [],
+      systemPrompts: options.systemPrompts || [],
+      capabilities: options.capabilities || {},
+      resolveImage: options.resolveImage
+    });
+  }
+};
+
+// 向后兼容：保留 assembleMessages 函数
+export function assembleMessages(options = {}) {
+  return MessageFormatter.format({ ...options, format: 'openai' });
+}

package/src/utils/typeCheck.js

@@ -0,0 +1,12 @@
+/**
+ * 类型判断工具
+ */
+
+/**
+ * 判断一个值是否为字符串
+ * @param {any} value - 要检查的值
+ * @returns {boolean} 如果是字符串则返回 true
+ */
+export function isString(value) {
+  return typeof value === 'string';
+}

package/src/utils/url.js

@@ -0,0 +1,18 @@
+/**
+ * URL 工具函数
+ */
+
+/**
+ * 拼接 baseUrl 和 path
+ * 注意：path 应以 '/' 开头，否则会替换 baseUrl 的最后一段
+ * @param {string} baseUrl - 基础 URL（如 https://api.deepseek.com）
+ * @param {string} path - 路径（如 /v1/chat/completions）
+ * @returns {string} 完整的 URL
+ */
+export function joinUrl(baseUrl, path) {
+  // 移除 baseUrl 末尾的斜杠（如果有）
+  const base = baseUrl.replace(/\/$/, '');
+  // 确保 path 以斜杠开头
+  const p = path.startsWith('/') ? path : '/' + path;
+  return base + p;
+}

package/.env

@@ -1,15 +0,0 @@
-# AI Chat Framework 环境变量配置
-
-# DeepSeek API 配置
-DEEPSEEK_API_KEY=sk-3b396e7fd64b463390d4ff033c6e7e0b
-DEEPSEEK_API_URL=https://api.deepseek.com/v1/chat/completions
-
-# 测试配置
-TEST_API_KEY=sk-3b396e7fd64b463390d4ff033c6e7e0b
-TEST_MODEL=deepseek-chat
-TEST_TEMPERATURE=0.7
-TEST_MAX_TOKENS=2000
-
-# 调试配置
-DEBUG=false
-LOG_LEVEL=info