my-ai-chat-framework 1.0.2 → 2.0.0

package/src/plugins/tool-calling.js

@@ -0,0 +1,119 @@
+/**
+ * 工具调用插件
+ * 拦截消息中的 tool_calls，执行注册的工具，并将结果插入对话，然后继续请求
+ */
+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 });
+          }
+        }
+
+        // 添加工具结果消息
+        for (const tr of toolResults) {
+          chat.messages.addTool(tr.content || tr.error, tr.tool_call_id);
+        }
+
+        // 再次请求
+        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();
+            });
+          });
+        } 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);
+        }
+      }
+      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;
+    }
+  }
+};

package/test.js

@@ -0,0 +1,107 @@
+// test.js - 测试新框架核心功能
+import 'dotenv/config'; // 如果已安装 dotenv，否则手动读取 .env
+import { ChatService, openaiAdapter, toolCallingPlugin } from './src/index.js';
+
+// 从环境变量读取配置（确保 .env 文件存在）
+const apiKey = process.env.DEEPSEEK_API_KEY;
+const apiUrl = process.env.DEEPSEEK_API_URL || 'https://api.deepseek.com/v1/chat/completions';
+const model = process.env.TEST_MODEL || 'deepseek-chat';
+
+if (!apiKey) {
+  console.error('❌ 未找到 API Key，请设置 DEEPSEEK_API_KEY 环境变量或创建 .env 文件');
+  process.exit(1);
+}
+
+console.log('🚀 开始测试新框架...\n');
+
+// 创建聊天服务实例
+const chat = new ChatService({
+  apiKey,
+  model,
+  apiUrl,
+  temperature: 0.7,
+  maxTokens: 2000
+});
+
+// 加载适配器和插件
+chat.use(openaiAdapter);
+chat.use(toolCallingPlugin);
+
+// 监听事件（便于观察）
+chat.on('sending', msg => {
+  console.log('📤 发送消息:', msg.content?.substring(0, 50) || msg);
+});
+chat.on('message', msg => {
+  console.log('📥 收到回复:', msg.content?.substring(0, 100) || msg);
+});
+chat.on('stream-progress', chunk => {
+  console.log('🌊 流式数据块:', chunk.content?.substring(0, 30) || '');
+});
+chat.on('error', err => {
+  console.error('❌ 错误:', err.message);
+});
+
+// 注册一个简单测试工具（不实际调用，只验证注册和工具调用流程）
+chat.registerTool('greet', '打招呼工具', async (args) => {
+  console.log('🔧 工具被调用:', args);
+  return `你好，${args.name || '朋友'}！`;
+});
+
+// 辅助函数：等待指定毫秒
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+// 测试 1：基础发送消息（非流式）
+console.log('===== 测试1：基础发送消息 =====');
+const response = await chat.send('请简单说一句：你好，世界！');
+console.log('最终回复:', response.content);
+console.log();
+
+// 等待一下，避免请求过快
+await sleep(1000);
+
+// 测试 2：流式发送消息
+console.log('===== 测试2：流式发送消息 =====');
+let streamContent = '';
+await chat.stream('请用流式方式回答：告诉我一个好消息。',
+  (chunk) => {
+    streamContent += chunk.content;
+    // 实时打印已接收内容（可选）
+    // process.stdout.write(chunk.content);
+  },
+  (final) => {
+    console.log('流式完成，完整内容:', final.content);
+  }
+);
+console.log();
+
+await sleep(1000);
+
+// 测试 3：工具调用
+console.log('===== 测试3：工具调用 =====');
+// 注意：需要让 AI 主动调用 greet 工具。由于 deepseek-chat 支持函数调用，我们可以在系统提示或用户消息中引导。
+// 我们在用户消息中明确要求调用工具，但 AI 是否调用取决于模型。这里做一个简单引导。
+const toolResponse = await chat.send('请使用 greet 工具，向 "小明" 打招呼。');
+console.log('工具调用后的回复:', toolResponse.content);
+console.log();
+
+await sleep(1000);
+
+// 测试 4：验证消息存储
+console.log('===== 测试4：消息存储验证 =====');
+const allMessages = chat.messages.getAll();
+console.log(`当前消息总数: ${allMessages.length}`);
+allMessages.forEach((msg, i) => {
+  console.log(`[${i}] ${msg.role}: ${msg.content?.substring(0, 40)}${msg.content?.length > 40 ? '...' : ''}`);
+  if (msg.toolCalls) console.log('  工具调用:', msg.toolCalls);
+  if (msg.toolCallId) console.log('  工具调用ID:', msg.toolCallId);
+});
+console.log();
+
+// 测试 5：撤回功能（可选）
+console.log('===== 测试5：撤回最后一条助手消息 =====');
+const removed = chat.messages.undoToLastAssistant();
+console.log(`撤回了 ${removed.length} 条消息`);
+const afterUndo = chat.messages.getAll();
+console.log(`剩余消息数: ${afterUndo.length}`);
+
+console.log('\n✅ 所有测试完成！');

package/README_ZH.md

@@ -1,401 +0,0 @@
-# 🚀 我的AI聊天框架 - 中文文档
-
-一个现代化的AI聊天框架，支持工具调用、流式传输和事件驱动架构。
-
-## ✨ 核心特性
-
-### ✅ 已完成功能
-1. **完整的工具调用系统**
-   - 工具注册和管理
-   - 工具执行和错误处理
-   - 支持批量工具调用
-   - 流式传输中的工具调用支持
-
-2. **流式传输支持**
-   - 实时数据流处理
-   - 进度回调支持
-   - 工具调用与流式传输的完美集成
-
-3. **事件驱动架构**
-   - 基于EventEmitter的事件系统
-   - 丰富的生命周期事件
-   - 可扩展的事件监听
-
-4. **模块化设计**
-   - 分离关注点：状态管理、格式转换、请求构建
-   - 易于扩展和维护
-   - 支持多种使用方式（ES模块、UMD、CommonJS）
-
-### 🎯 设计理念
-- **简单易用**: 提供直观的API接口
-- **功能强大**: 支持复杂的AI交互场景
-- **可扩展**: 易于添加新功能和工具
-- **稳定可靠**: 完善的错误处理和类型检查
-
-## 📦 快速开始
-
-### 安装
-```bash
-cd my-ai-chat-framework
-npm install
-```
-
-### 构建项目
-```bash
-npm run build
-```
-
-### 输出文件
-构建后会在 `dist/` 目录生成以下文件：
-- `my-ai-chat-framework.es.js` - ES模块格式（包含axios依赖）
-- `my-ai-chat-framework.umd.js` - UMD格式（包含axios依赖）
-- `my-ai-chat-framework.cjs.js` - CommonJS格式（包含axios依赖）
-
-**重要**: axios已被打包进所有输出文件中，用户无需额外安装axios依赖。
-
-## 🔧 核心组件
-
-### 1. ChatService (主服务类)
-```javascript
-import { ChatService } from './src/index.js';
-
-// 创建聊天服务
-const chat = new ChatService('your-api-key', 'deepseek-chat');
-
-// 注册工具
-chat.registerTool(
-  'get_weather',
-  {
-    type: 'function',
-    function: {
-      name: 'get_weather',
-      description: '获取天气信息',
-      parameters: {
-        type: 'object',
-        properties: {
-          city: { type: 'string' }
-        },
-        required: ['city']
-      }
-    }
-  },
-  async (args) => {
-    // 工具执行逻辑
-    return { temperature: '25°C', condition: '晴朗' };
-  }
-);
-
-// 发送消息（支持工具调用）
-const response = await chat.send('北京的天气怎么样？');
-console.log('AI回复:', response);
-
-// 流式传输
-await chat.stream(
-  '请用流式方式告诉我一个故事',
-  (chunk) => console.log('收到数据:', chunk.content),
-  (final) => console.log('完成:', final.content)
-);
-```
-
-### 2. 事件系统
-```javascript
-// 监听各种事件
-chat.on('sending', (data) => {
-  console.log('发送消息:', data.content);
-});
-
-chat.on('message', (data) => {
-  console.log('收到回复:', data.content);
-});
-
-chat.on('tool-call-requested', (data) => {
-  console.log('AI请求工具调用:', data.tool_calls);
-});
-
-chat.on('tool-execute-success', (data) => {
-  console.log('工具执行成功:', data.name, data.result);
-});
-
-chat.on('stream-progress', (chunk) => {
-  console.log('流式进度:', chunk.content);
-});
-```
-
-### 3. 消息管理
-```javascript
-import { Messages } from './src/index.js';
-
-const messages = new Messages();
-
-// 添加各种消息
-messages.addUserMessage('你好');
-messages.addAssistantMessage('你好！有什么可以帮助您的吗？');
-messages.addSystemMessage('你是一个有帮助的AI助手');
-
-// 工具调用消息
-messages.addAssistantMessage('我来查询天气', {
-  tool_calls: [{
-    id: 'call_123',
-    type: 'function',
-    function: {
-      name: 'get_weather',
-      arguments: JSON.stringify({ city: '北京' })
-    }
-  }]
-});
-
-// 工具结果消息
-messages.addToolMessage(JSON.stringify({ temp: '25°C' }), 'call_123');
-```
-
-## 🛠️ 工具调用详解
-
-### 工具注册
-```javascript
-chat.registerTool(
-  'tool_name',           // 工具名称
-  toolDefinition,        // 工具定义（符合OpenAI格式）
-  async executor         // 工具执行函数
-);
-```
-
-### 工具定义格式
-```javascript
-const toolDefinition = {
-  type: 'function',
-  function: {
-    name: 'get_weather',
-    description: '获取天气信息',
-    parameters: {
-      type: 'object',
-      properties: {
-        city: {
-          type: 'string',
-          description: '城市名称'
-        }
-      },
-      required: ['city']
-    }
-  }
-};
-```
-
-### 工具执行流程
-1. **用户发送消息** → AI识别需要调用工具
-2. **AI返回工具调用请求** → 包含 `tool_calls` 数组
-3. **框架执行工具** → 调用注册的工具函数
-4. **添加工具结果** → 将结果作为工具消息添加到对话
-5. **再次请求AI** → 将工具结果发送给AI生成最终回复
-
-## 🌊 流式传输
-
-### 基本使用
-```javascript
-await chat.stream(
-  '用户消息',
-  (chunk) => {
-    // 实时处理流式数据
-    console.log('实时内容:', chunk.content);
-  },
-  (finalMessage) => {
-    // 流式传输完成
-    console.log('最终结果:', finalMessage);
-  }
-);
-```
-
-### 流式传输中的工具调用
-框架自动处理流式传输中的工具调用：
-1. 流式传输过程中AI请求工具调用
-2. 框架收集完整的工具调用信息
-3. 执行工具并获取结果
-4. 继续流式传输最终回复
-
-## 📁 项目结构
-
-```
-my-ai-chat-framework/
-├── src/
-│   ├── core/
-│   │   ├── EventEmitter.js      # 事件系统
-│   │   ├── Messages.js          # 消息状态管理
-│   │   ├── MessageFormatter.js  # 消息格式转换
-│   │   ├── RequestBuilder.js    # 请求构建器
-│   │   ├── ApiClient.js         # API客户端（使用axios）
-│   │   └── ToolManager.js       # 工具管理器
-│   ├── utils/
-│   │   └── index.js             # 工具函数
-│   └── index.js                 # 主入口文件
-├── dist/                        # 打包输出
-├── test-*.html                  # 各种测试页面
-├── vite.config.js              # 构建配置
-└── package.json                # 项目配置
-```
-
-## 🧪 测试页面
-
-### 1. 完整功能测试
-打开 `test-complete-tool-call.html` 进行完整的功能测试：
-- 工具调用流程测试
-- 流式传输测试
-- 错误处理测试
-
-### 2. 工具调用ID测试
-打开 `test-tool-call-id.html` 验证 `tool_call_id` 的正确传递。
-
-### 3. 事件系统测试
-打开 `test-eventemitter.html` 测试事件系统功能。
-
-## 🔍 调试技巧
-
-### 启用详细日志
-```javascript
-// 在ChatService中启用详细日志
-chat.on('sending', (data) => console.log('发送:', data));
-chat.on('message', (data) => console.log('接收:', data));
-chat.on('tool-call-requested', (data) => console.log('工具调用:', data));
-```
-
-### 检查消息状态
-```javascript
-// 查看当前所有消息
-const allMessages = chat.messages.getMessages();
-console.log('当前消息:', allMessages);
-
-// 查看格式化后的消息
-const formatted = chat.requestBuilder.toObject();
-console.log('API请求体:', formatted);
-```
-
-## ⚠️ 注意事项
-
-### 1. API Key 安全
-- 不要在客户端代码中硬编码API Key
-- 使用环境变量或后端代理
-- 测试时可以使用临时Key
-
-### 2. 工具调用限制
-- 工具名称必须唯一
-- 工具参数必须符合JSON Schema
-- 工具执行函数应该是异步的
-
-### 3. 流式传输
-- 流式传输需要显式设置 `stream: true`
-- 工具调用在流式传输中会自动处理
-- 注意网络连接稳定性
-
-### 4. 错误处理
-- 所有工具调用都有错误处理
-- 网络错误会自动重试（可配置）
-- 详细的错误日志
-
-## 🚀 高级用法
-
-### 自定义事件处理器
-```javascript
-class MyChatService extends ChatService {
-  constructor(apiKey, model, config) {
-    super(apiKey, model, config);
-    this._setupCustomListeners();
-  }
-  
-  _setupCustomListeners() {
-    this.on('tool-execute-start', this._onToolStart.bind(this));
-    this.on('tool-execute-success', this._onToolSuccess.bind(this));
-  }
-  
-  _onToolStart(data) {
-    console.log(`工具 ${data.name} 开始执行`);
-  }
-  
-  _onToolSuccess(data) {
-    console.log(`工具 ${data.name} 执行成功:`, data.result);
-  }
-}
-```
-
-### 批量工具注册
-```javascript
-const tools = [
-  {
-    name: 'get_weather',
-    definition: { /* ... */ },
-    executor: async (args) => { /* ... */ }
-  },
-  {
-    name: 'get_time',
-    definition: { /* ... */ },
-    executor: async (args) => { /* ... */ }
-  }
-];
-
-tools.forEach(tool => {
-  chat.registerTool(tool.name, tool.definition, tool.executor);
-});
-```
-
-### 消息持久化
-```javascript
-// 导出对话
-const exportData = chat.export();
-localStorage.setItem('chat_history', JSON.stringify(exportData));
-
-// 导入对话
-const savedData = JSON.parse(localStorage.getItem('chat_history'));
-chat.import(savedData);
-```
-
-## 📚 学习资源
-
-### 框架设计理念
-1. **观察者模式**: EventEmitter实现事件系统
-2. **工厂模式**: 消息对象创建
-3. **策略模式**: 不同的API适配器
-4. **外观模式**: ChatService作为统一接口
-
-### 最佳实践
-1. **单一职责**: 每个类只负责一个功能
-2. **开放封闭**: 易于扩展，无需修改现有代码
-3. **依赖倒置**: 高层模块不依赖低层模块
-4. **接口隔离**: 客户端不应该依赖它不需要的接口
-
-## 🤝 贡献指南
-
-### 开发流程
-1. Fork项目
-2. 创建功能分支
-3. 编写代码和测试
-4. 提交Pull Request
-
-### 代码规范
-- 使用ES6+语法
-- 添加JSDoc注释
-- 编写单元测试
-- 保持向后兼容性
-
-### 测试要求
-- 所有新功能都需要测试
-- 保持测试覆盖率
-- 测试应该独立且可重复
-
-## 📄 许可证
-
-MIT License - 详见LICENSE文件
-
-## 🙏 致谢
-
-感谢以下开源项目：
-- [axios](https://github.com/axios/axios) - HTTP客户端
-- [Vite](https://vitejs.dev/) - 构建工具
-- [DeepSeek API](https://platform.deepseek.com/) - AI服务
-
----
-
-**版本**: 1.0.0  
-**最后更新**: 2026年3月9日  
-**状态**: ✅ 生产就绪  
-**工具调用**: ✅ 完全支持  
-**流式传输**: ✅ 完全支持  
-**事件系统**: ✅ 完全支持  
-
-**提示**: 这是一个学习项目，旨在帮助理解AI聊天框架的设计和实现。欢迎反馈和建议！