my-ai-chat-framework 1.0.2

package/README_ZH.md

@@ -0,0 +1,401 @@
+# 🚀 我的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聊天框架的设计和实现。欢迎反馈和建议！