my-ai-chat-framework 2.7.0 → 4.0.0

package/src/plugins/tool-calling.js

@@ -2,212 +2,270 @@
  * 工具调用插件
  * 功能：拦截助手消息中的 tool_calls，执行对应的工具，将结果作为 tool 消息加入对话，
  *       然后自动继续对话（通过 sendExisting / sendExistingStream），直到没有新的工具调用。
- * 
+ *
  * 设计要点：
  * - 支持普通请求和流式请求（通过 isStream 标志区分）
  * - 支持多次工具调用循环（maxIterations 防止无限循环）
- * - 串行执行工具（可后续升级为并行）
+ * - 并行执行工具
  * - 工具执行失败时，仍然返回错误信息给 AI，而不是中断整个流程
  * - 触发 tool-error 事件，方便用户监听工具执行异常
+ *
+ * 注意：请使用 createToolCallingPlugin() 工厂创建实例。
+ * 默认导出的 toolCallingPlugin 是兼容用的模块级单例，装到多个 ChatService
+ * 实例会互相覆盖（executor 表、工具定义、配置），新代码不要直接用单例。
  */
-export const toolCallingPlugin = {
-  name: 'tool-calling',
-  maxIterations: 5,                // 最大工具调用循环次数，防止无限循环（例如 AI 反复请求同一工具）
-
-  /**
-   * 安装插件，覆盖 ChatService 的 registerTool、send、stream 方法
-   * @param {ChatService} chatService - ChatService 实例
-   */
-  install(chatService) {
-    this.chatService = chatService;
-    this._tools = new Map();        // 存储工具名 -> { executor, description }
-
-    // 初始化 config.tools 数组（用于存放 OpenAI 格式的工具定义）
-    if (!chatService.config.tools) {
-      chatService.config.tools = [];
-    }
+export const toolCallingPlugin = createToolCallingPlugin();
+
+/**
+ * 创建工具调用插件实例（工厂）。
+ * @param {Object} [options] — { timeout?, maxIterations? }
+ *   - 两者**默认都不限制**：不传就是"循环到没有工具调用为止 / 不超时"
+ *   - 想限制才传（这是使用者的选择，不是框架替你做的决定）
+ */
+export function createToolCallingPlugin(options = {}) {
+  return {
+    name: 'tool-calling',
+    // 默认不限制循环轮数（旧版硬编码 5 轮，属于"框架替用户做决定"，v4.0 移除）
+    maxIterations: options.maxIterations ?? Infinity,
+    _options: { ...options },
+    _tools: new Map(),    // 工具名 -> { executor, description }
+    _toolDefs: [],        // OpenAI 格式的工具定义（按注册顺序）
+    chatService: null,
 
     /**
-     * 注册工具
-     * @param {string} name - 工具名称（唯一标识）
-     * @param {string} description - 工具描述（告诉 AI 何时调用）
-     * @param {Function} executor - 异步执行函数，接收参数对象，返回结果（字符串或对象）
-     * @param {Object} parameters - JSON Schema 参数定义（可选，默认为空对象）
-     * @returns {ChatService} 返回 chatService 实例，支持链式调用
+     * 安装插件：挂 registerTool、注册 beforeRequest 钩子注入工具定义、注册响应处理钩子
+     * @param {ChatService} chatService - ChatService 实例
+     * @param {Object} [options] - 安装时配置（合并进 _options）
      */
-    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)
+    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 实例，支持链式调用
+       */
+      const registerTool = (name, description, executor, parameters = {}) => {
+        // 保存执行器
+        this._tools.set(name, { executor, description });
+
+        // 构建 OpenAI 兼容的工具定义
+        // 参数写法：{ 参数名: { type, description, required? } }
+        // → 必填项收集到顶层 required 数组；properties 里不残留 required 字段（标准 JSON Schema 要求）
+        const properties = {};
+        const requiredKeys = [];
+        for (const [key, def] of Object.entries(parameters || {})) {
+          const { required: isRequired, ...schema } = def || {};
+          properties[key] = schema;
+          if (isRequired) requiredKeys.push(key);
+        }
+        const toolDefinition = {
+          type: 'function',
+          function: {
+            name,
+            description,
+            parameters: { type: 'object', properties, required: requiredKeys }
           }
+        };
+        // 避免重复添加相同工具
+        const existing = this._toolDefs.find(t => t.function.name === name);
+        if (!existing) {
+          this._toolDefs.push(toolDefinition);
         }
+        return chatService;
       };
-      // 避免重复添加相同工具
-      const existing = chatService.config.tools.find(t => t.function.name === name);
-      if (!existing) {
-        chatService.config.tools.push(toolDefinition);
-      }
-      return chatService;
-    };
-
-    // 注册响应后处理钩子，不再覆盖 send/stream
-    chatService._processResponse = async (response, { isStream, onProgress, onDone }) => {
-      return this._handleWithTools(response, 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;
+
+      // 响应后处理（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
+          );
+        }
+      });
+
+      // 交给 use() 挂到 chat.plugins['tool-calling']（v4.0 命名空间）
+      return { registerTool, tools: this._tools, uninstall: (c) => this.uninstall(c) };
+    },
+
+    /** 卸载：移除注入车间（工具定义注入 + 工具循环） */
+    uninstall(chat) {
+      if (!chat) return chat;
+      chat.unpipe?.('tool-calling-inject');
+      chat.unpipe?.('tool-calling-loop');
+      if (chat.plugins && chat.plugins['tool-calling']) delete chat.plugins['tool-calling'];
+      return chat;
+    },
 
     /**
-     * 递归处理工具调用
-     * @param {Object} initialResponse - 初始 AI 响应（可能是第一次请求的响应）
-     * @returns {Promise<Object>} 最终 AI 响应（不含 tool_calls）
+     * 核心处理逻辑：检查响应 → 执行工具 → 继续请求 → 循环
+     * @param {Object} initialResponse - 初始 AI 响应
+     * @param {boolean} isStream - 是否流式
+     * @param {Function} onProgress - 流式进度回调
+     * @param {Function} onDone - 流式完成回调
+     * @returns {Promise<Object>} 最终 AI 响应
      */
-    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 {
-              // 工具执行超时控制
-              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]);
+    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 = 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 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);
-        }
+              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
+                };
+              }
 
-        // 再次请求 AI，获取基于工具结果的回复
-        if (isStream) {
-          // 流式继续：使用 sendExistingStream
-          await new Promise((resolve) => {
-            chat.sendExistingStream(
-              (chunk) => {
-                if (onProgress) onProgress(chunk);
-                lastResponse = chunk;
-              },
-              (final) => {
-                lastResponse = final;
-                resolve();
+              try {
+                // 工具执行超时：只在工厂 options.timeout 显式传入时生效（不传 = 不限制）
+                const toolTimeout = self._options.timeout;
+                let result;
+                if (typeof toolTimeout === 'number' && toolTimeout > 0) {
+                  const controller = new AbortController();          // 通知支持 signal 的工具去清理
+                  const timeoutErr = new Error(`工具 ${toolName} 执行超时 (${toolTimeout}ms)`);
+                  timeoutErr.name = 'ToolTimeoutError';
+                  let timer;
+                  const timeoutPromise = new Promise((_, reject) => {
+                    timer = setTimeout(() => { controller.abort(); reject(timeoutErr); }, toolTimeout);
+                  });
+                  const execPromise = Promise.resolve().then(() => tool.executor(args, { signal: controller.signal }));
+                  execPromise.catch(() => {});                        // 超时后工具的后续结果不再冒泡为 unhandled
+                  try {
+                    result = await Promise.race([execPromise, timeoutPromise]);
+                  } finally {
+                    clearTimeout(timer);                              // 工具先完成时不留悬挂的 timer（旧版泄漏点）
+                  }
+                } else {
+                  result = await tool.executor(args);
+                }
+                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
+                };
               }
-            );
-          });
-        } else {
-          // 非流式继续：使用 sendExisting
-          lastResponse = await chat.sendExisting();
+            })
+          );
+
+          // 将工具执行结果作为 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 {
+            // 非流式继续：使用 sendExisting
+            lastResponse = await chat.sendExisting();
+          }
         }
+        return lastResponse;
       }
-      return lastResponse;
-    }
 
-    // 初始响应已由 ChatService 发出，直接进入工具调用循环
-    const final = await processResponse(initialResponse);
-    return final;
-  }
-};
+      // 初始响应已由 ChatService 发出，直接进入工具调用循环
+      const final = await processResponse(initialResponse);
+      return final;
+    }
+  };
+}