my-ai-chat-framework 1.0.2 → 2.0.0

package/.env

@@ -0,0 +1,15 @@
+# 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

package/README.md

@@ -1,305 +1,107 @@
-# 🤖 My AI Chat Framework / 我的AI聊天框架
 
-## 🎯 概述 / Overview
-这是一个现代化的AI聊天框架，支持工具调用、流式传输和事件驱动架构。旨在帮助开发者构建功能丰富的AI聊天应用。
+ **⚠️ Note**: This project is created for **learning purposes** and is **AI‑generated**. It is not intended for production use. No backward compatibility is guaranteed. Use at your own risk.
+ 
+# 🤖 My AI Chat Framework
 
-This is a modern AI chat framework with tool calling, streaming, and event-driven architecture. Designed to help developers build feature-rich AI chat applications.
+A lightweight, modular AI chat framework with plugin system, unified message format, and tool calling support.
 
-## ✨ 新功能特性 / New Features
-- **🔧 工具调用系统** / **Tool Calling System**: 完整的OpenAI兼容工具调用支持，包括工具注册、执行和错误处理
-- **🌊 流式传输** / **Streaming**: 实时流式传输，支持工具调用和进度回调
-- **⚡ 事件驱动架构** / **Event-Driven Architecture**: 基于EventEmitter的丰富事件系统
-- **📦 模块化设计** / **Modular Design**: 清晰的关注点分离，易于扩展和维护
+## ✨ Features
 
-## ✅ 核心功能 / Core Features
-- **消息管理** / **Message Management**: 包含一个`Messages`类，用于处理聊天消息的存储和操作
-- **请求构建** / **Request Building**: `RequestBuilder`类构建发送到聊天API的请求体
-- **API交互** / **API Interaction**: `ApiClient`类管理与聊天API的HTTP请求，支持标准和流式请求
-- **工具管理** / **Tool Management**: `ToolManager`类负责工具的注册、管理和执行
-- **事件系统** / **Event System**: `EventEmitter`类提供完整的事件驱动架构
-- **格式转换** / **Format Conversion**: `MessageFormatter`类负责消息格式转换
+- **Lightweight Core** – Only ~300 lines, easy to understand and extend.
+- **Plugin System** – Add features like tool calling, reasoning, or custom adapters without touching the core.
+- **Unified Message Format** – Consistent data structure across all components.
+- **Multi‑Environment** – Builds ES module, UMD, and CommonJS formats for browser and Node.js.
+- **No External Dependencies** – Uses native `fetch` (Node 18+ & modern browsers).
+- **Tool Calling** – Built‑in plugin to handle function calls from AI models.
+- **Streaming** – Full support for real‑time responses.
 
-## 📁 项目结构 / Project Structure
-```
-my-ai-chat-framework/
-├── dist/                          # 打包输出目录 / Build output
-│   ├── my-ai-chat-framework.es.js    # ES模块 / ES Module
-│   ├── my-ai-chat-framework.umd.js   # UMD模块（注册到window.AIChatFramework）/ UMD Module
-│   └── my-ai-chat-framework.cjs.js   # CommonJS模块 / CommonJS Module
-├── src/                           # 源代码 / Source code
-│   ├── core/                      # 核心类 / Core classes
-│   │   ├── EventEmitter.js        # 事件系统 / Event System
-│   │   ├── Messages.js            # 消息状态管理 / Message State Management
-│   │   ├── MessageFormatter.js    # 消息格式转换 / Message Format Conversion
-│   │   ├── RequestBuilder.js      # 请求构建器 / Request Builder
-│   │   ├── ApiClient.js           # API客户端（使用axios）/ API Client (axios)
-│   │   └── ToolManager.js         # 工具管理器 / Tool Manager
-│   ├── utils/                     # 工具函数 / Utility functions
-│   └── index.js                   # 主入口文件 / Main entry point
-├── test-*.html                    # 各种测试页面 / Various test pages
-├── README_ZH.md                   # 详细中文文档 / Detailed Chinese documentation
-├── FIX_SUMMARY.md                 # 修复总结 / Fix summary
-├── vite.config.js                 # Vite配置 / Vite configuration
-└── package.json                   # 项目配置 / Project configuration
-```
-
-## 📦 安装和使用 / Installation and Usage
-
-### 浏览器中使用 / For Browser Usage
-
-#### 方式1：直接引入UMD版本（推荐）
-```html
-<script src="https://unpkg.com/my-ai-chat-framework@latest/dist/my-ai-chat-framework.browser.umd.js"></script>
-<script>
-  // 全局变量 AIChatFramework 可用
-  const { ChatService, Messages } = AIChatFramework;
-  
-  // 创建聊天服务
-  const chat = new ChatService('your-api-key');
-</script>
-```
-
-#### 方式2：使用ES模块
-```html
-<script type="module">
-  import { ChatService, Messages } from 'https://unpkg.com/my-ai-chat-framework@latest/dist/my-ai-chat-framework.browser.es.js';
-  
-  const chat = new ChatService('your-api-key');
-</script>
-```
+## 📦 Installation
 
-### Node.js中使用 / For Node.js Usage
-
-#### 安装
 ```bash
-npm install my-ai-chat-framework axios
-# 或
-yarn add my-ai-chat-framework axios
-# 或
-pnpm add my-ai-chat-framework axios
+npm install my-ai-chat-framework
 ```
 
-#### 使用
+## 🚀 Quick Start
+
 ```javascript
-// CommonJS
-const { ChatService, Messages } = require('my-ai-chat-framework');
+import { ChatService, openaiAdapter, toolCallingPlugin } from 'my-ai-chat-framework';
 
-// ES模块
-import { ChatService, Messages } from 'my-ai-chat-framework';
+const chat = new ChatService({
+  apiKey: 'your-api-key',
+  model: 'deepseek-chat',
+  apiUrl: 'https://api.deepseek.com/v1/chat/completions'
+});
 
-// 创建聊天服务
-const chat = new ChatService('your-api-key');
-```
+chat.use(openaiAdapter);
+chat.use(toolCallingPlugin);
 
-### 本地开发 / Local Development
+chat.registerTool('greet', 'Say hello', async (args) => {
+  return `Hello, ${args.name}!`;
+});
 
-#### 安装依赖
-```bash
-npm install
-```
+chat.on('message', msg => console.log(msg.content));
 
-### 构建项目 / Build Project
-```bash
-npm run build
+await chat.send('Please greet Alice.');
 ```
 
-### 输出文件 / Output Files
-构建后会在 `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依赖。
+## 🔌 Plugins & Adapters
 
-### 预览构建结果 / Preview Build
-```bash
-npm run preview
-```
+- **openaiAdapter** – Converts internal messages to OpenAI-compatible format.
+- **toolCallingPlugin** – Detects `tool_calls` in responses, executes tools, and continues the conversation.
 
-### 在浏览器中使用 / Usage in Browser
+You can easily create your own adapter for other APIs (Anthropic, Cohere, etc.) or plugins for logging, caching, etc.
 
-#### 传统浏览器（UMD模块）/ Traditional Browser (UMD Module)
-```html
-<script src="./dist/my-ai-chat-framework.umd.js"></script>
-<script>
-// 使用全局变量 / Use global variable
-const { Messages, ApiClient, ChatRequestBuilder, ChatService } = window.AIChatFramework;
-const chat = new ChatService('your-api-key');
-</script>
-```
+## 📚 API
 
-#### 现代浏览器（ES模块）/ Modern Browser (ES Module)
-```html
-<script type="module">
-import { Messages, ChatService } from './dist/my-ai-chat-framework.es.js';
-const chat = new ChatService('your-api-key');
-</script>
-```
+### ChatService
 
-### 在Node.js中使用 / Usage in Node.js
-```javascript
-const { Messages, ChatService } = require('./dist/my-ai-chat-framework.cjs.js');
-const chat = new ChatService('your-api-key');
+```typescript
+new ChatService(config: {
+  apiKey: string;
+  model?: string;
+  apiUrl?: string;
+  temperature?: number;
+  maxTokens?: number;
+})
 ```
 
-## 核心类说明 / Core Classes Description
-
-### Messages 类
-管理对话消息的核心类，支持：
-- 消息的推送、修改、撤回
-- 系统提示词管理
-- 工具定义管理
-- 数据导入/导出
+- `use(plugin)` – Load a plugin.
+- `send(message)` – Send a message and wait for the complete response.
+- `stream(message, onProgress, onDone)` – Stream the response.
+- `registerTool(name, description, executor)` – Register a tool (only available after loading `toolCallingPlugin`).
 
-### ChatRequestBuilder 类
-构建符合API规范的请求体，支持：
-- 自动格式化消息
-- 配置模型参数
-- 生成JSON请求体
+### MessageStore
 
-### ApiClient 类
-HTTP客户端，支持：
-- 普通请求和流式请求
-- 请求中断
-- 错误处理
-- 前后端通用（使用axios）
+- `add(message)` – Add a message (unified format).
+- `addUser(content, metadata)` – Convenience method.
+- `addAssistant(content, metadata)`
+- `addSystem(content, metadata)`
+- `addTool(content, toolCallId, metadata)`
+- `getAll()` – Get all messages.
+- `undoToLastAssistant()` – Rollback to the last assistant message.
 
-### ChatService 类
-高级封装类，简化使用：
-- 集成所有核心功能
-- 提供简单API接口
-- 自动管理消息状态
+### EventEmitter
 
-## 示例代码 / Example Code
+- `on(event, handler)` – Subscribe to events.
+- `off(event, handler)` – Unsubscribe.
+- `emit(event, data)` – Emit an event.
 
-```javascript
-// 创建聊天服务 / Create chat service
-const chat = new ChatService('your-api-key', 'deepseek-chat');
-
-// 发送消息 / Send message
-const response = await chat.send('你好，世界！');
-console.log('AI回复:', response);
-
-// 流式消息 / Stream message
-await chat.stream('告诉我一个故事', 
-  (chunk) => console.log('收到数据:', chunk),
-  () => console.log('流式传输完成')
-);
-
-// 流式传输中的工具调用 / Tool calling in streaming
-await chat.stream('查询北京天气', 
-  (chunk) => console.log('实时数据:', chunk.content),
-  (final) => console.log('最终结果:', final.content)
-);
+Events: `sending`, `message`, `stream-progress`, `error`, etc.
 
-// 撤回消息 / Undo message
-chat.undo();
+## 🛠️ Development
 
-// 导出对话 / Export conversation
-const exportData = chat.export();
-
-## 📤 npm发布 / npm Publishing
-
-### 发布准备
-1. 确保已登录npm账号：
 ```bash
-npm login
-```
-
-2. 更新版本号（如果需要）：
-```bash
-npm version patch  # 小版本更新
-npm version minor  # 中版本更新  
-npm version major  # 大版本更新
-```
-
-3. 构建项目：
-```bash
-npm run build
-```
-
-### 发布到npm
-```bash
-npm publish
-```
-
-### 发布后验证
-1. 检查包是否发布成功：
-```bash
-npm view my-ai-chat-framework
-```
-
-2. 测试安装：
-```bash
-npm install my-ai-chat-framework@latest
-```
-
-### 包信息
-- **包名**: `my-ai-chat-framework`
-- **当前版本**: 1.0.2
-- **许可证**: MIT
-- **关键词**: AI, chat, framework, messages, API, deepseek, openai, tool-calling
-
-## 📄 许可证 / License
-MIT License - 详见 [LICENSE](LICENSE) 文件
-
-## 🤝 贡献 / Contributing
-欢迎提交Issue和Pull Request！
-
-## 📞 支持 / Support
-如有问题，请提交Issue或联系作者。
-
----
-
-**✨ 感谢使用 My AI Chat Framework! ✨**
-
-// 导入对话 / Import conversation
-chat.import(exportData);
-```
-
-## 🌊 流式传输下的工具调用 / Tool Calling in Streaming
-
-### 工作原理 / How It Works
-框架自动处理流式传输中的工具调用：
-1. **流式收集** / **Stream Collection**: 在流式传输过程中收集完整的工具调用信息
-2. **工具执行** / **Tool Execution**: 执行所有请求的工具
-3. **继续流式** / **Continue Streaming**: 将工具结果发送给AI并继续流式传输
-
-### 代码示例 / Code Example
-```javascript
-// 注册工具 / Register tool
-chat.registerTool('get_weather', toolDefinition, async (args) => {
-  return { temperature: '25°C', condition: 'Sunny' };
-});
-
-// 流式传输会自动处理工具调用 / Streaming automatically handles tool calls
-await chat.stream('What is the weather in Beijing?',
-  (chunk) => {
-    // 实时接收流式数据 / Receive streaming data in real-time
-    if (chunk.content) console.log('Content:', chunk.content);
-    if (chunk.tool_calls) console.log('Tool calls:', chunk.tool_calls);
-  },
-  (final) => {
-    // 流式传输完成 / Streaming completed
-    console.log('Final result:', final.content);
-  }
-);
+git clone https://github.com/your-username/my-ai-chat-framework.git
+cd my-ai-chat-framework
+npm install
+npm run build   # build the library
+npm test        # run the test script
 ```
 
-## 📚 更多文档 / More Documentation
-- **[详细中文文档](README_ZH.md)** - 完整的功能说明和使用示例
-- **[修复总结](FIX_SUMMARY.md)** - 技术修复细节和架构改进
-
-## 许可证 / License
-本项目采用MIT许可证。详见LICENSE文件。
-
-This project is licensed under the MIT License. See the LICENSE file for more details.
+## 📄 License
 
-## 依赖库 / Dependencies
-- [axios](https://github.com/axios/axios) - MIT License
-- [vite](https://vitejs.dev/) - MIT License
+MIT
 
----
+## 🤝 Contributing
 
-*此文档由AI辅助生成，内容可能不完整或存在错误，请以实际代码为准。*
-*This document is AI-assisted and may be incomplete or contain errors. Please refer to the actual code for accurate information.*
+Contributions are welcome! Please open an issue or submit a pull request.