my-ai-chat-framework 1.1.0 → 2.7.0

package/README.md

@@ -1,492 +1,304 @@
-# 🤖 My AI Chat Framework / 我的AI聊天框架
 
-## 🎯 概述 / Overview
-这是一个现代化的AI聊天框架，支持工具调用、流式传输和事件驱动架构。旨在帮助开发者构建功能丰富的AI聊天应用。
+# 🤖 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**: 清晰的关注点分离，易于扩展和维护
+> **⚠️ 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.
 
-## ✅ 核心功能 / Core Features
-- **消息管理** / **Message Management**: 包含一个`Messages`类，用于处理聊天消息的存储和操作
-- **请求构建** / **Request Building**: `RequestBuilder`类构建发送到聊天API的请求体
-- **API交互** / **API Interaction**: `ApiClient`类管理与聊天API的HTTP请求，支持标准和流式请求
-- **工具管理** / **Tool Management**: `ToolManager`类负责工具的注册、管理和执行
-- **事件系统** / **Event System**: `EventEmitter`类提供完整的事件驱动架构
-- **格式转换** / **Format Conversion**: `MessageFormatter`类负责消息格式转换
+## ✨ Features
 
-## 📁 项目结构 / 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
-```
-
-## 🎯 统一数据格式 / Unified Data Format
-
-从v1.1.0开始，框架使用统一的数据格式在所有组件之间传递消息，简化了使用体验。
+- **Lightweight Core** – ~300 lines, easy to understand and extend.
+- **Plugin System** – Add features (tool calling, reasoning, custom adapters) without touching the core.
+- **Unified Message Format** – Consistent data structure across all components.
+- **Multi‑Environment** – Builds ES module, UMD, and CommonJS for browser & 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.
+- **Flexible Configuration** – Supports both flat and nested `modelParams` structure.
+- **Event‑Driven** – Built‑in EventEmitter for `message`, `sending`, `error`, `stream-progress` events.
+- **Custom Error Classes** – `APIError`, `NetworkError`, `ConfigurationError`, `ParsingError` for fine‑grained error handling.
 
-### 核心消息格式
+---
 
-所有消息都遵循以下格式：
+## 🧱 Architecture
 
-```javascript
-{
-  // 必需字段 / Required fields
-  role: 'user' | 'assistant' | 'system' | 'tool',
-  content: string, // 允许空字符串 / Empty string allowed
-  
-  // 标准扩展字段 / Standard extension fields
-  timestamp: string, // ISO格式时间戳，自动生成 / ISO timestamp, auto-generated
-  metadata?: object, // 自定义元数据 / Custom metadata
-  
-  // 角色特定字段 / Role-specific fields
-  reasoning_content?: string, // 助手消息的推理内容 / Reasoning content for assistant messages
-  tool_calls?: array, // 助手消息的工具调用 / Tool calls for assistant messages
-  tool_call_id?: string, // 工具消息的调用ID / Call ID for tool messages
-  name?: string, // 工具消息的工具名称 / Tool name for tool messages
-  
-  // 自定义字段（任意）/ Custom fields (any)
-  [key: string]: any // 所有自定义字段都会被保留 / All custom fields are preserved
-}
 ```
-
-### 关键特性
-
-1. **字段保留** / **Field Preservation**: 所有自定义字段都被保留，不再丢失
-2. **空内容处理** / **Empty Content Handling**: 允许空字符串内容，仅在API请求时过滤
-3. **工具消息特殊处理** / **Tool Message Special Handling**: tool消息可以没有content
-4. **事件数据统一** / **Event Data Unification**: 所有事件使用相同的数据结构
-5. **向后兼容** / **Backward Compatibility**: 现有API保持不变
-
-### 使用示例
-
-```javascript
-// 添加带自定义字段的消息 / Add message with custom fields
-const msgIndex = chatService.messages.addUserMessage('Hello', {
-  metadata: { userId: '123', priority: 'high' },
-  customData: { session: 'test' }
-});
-
-// 获取完整消息 / Get complete message
-const fullMessage = chatService.messages.getMessages()[msgIndex];
-// 包含所有字段 / Contains all fields
-
-// 监听事件获取统一格式数据 / Listen to events for unified data format
-chatService.on('response', (data) => {
-  console.log('收到响应 / Response received:', data.message);
-  // data.message包含所有字段 / data.message contains all fields
-});
+src/
+├── index.js                  # Public entry point (re-exports)
+├── core/
+│   ├── ChatService.js        # Main service: config, send/stream, plugin hosting
+│   ├── MessageStore.js       # In-memory message list with CRUD helpers
+│   ├── EventEmitter.js       # Minimal pub/sub (on/off/emit)
+│   └── Errors.js             # Custom error classes
+├── adapters/
+│   └── openai.js             # OpenAI‑compatible API adapter (plugin pattern)
+├── plugins/
+│   └── tool-calling.js       # Tool calling plugin (auto‑detect & loop)
+└── utils/
+    ├── typeCheck.js          # Type checking helpers
+    └── url.js                # URL joining utility
 ```
 
-## 📦 安装和使用 / Installation and Usage
+**Data flow**:
 
-### 浏览器中使用 / 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>
+User calls chat.send(input)
+  → ChatService._request()
+    → emits 'sending'
+    → MessageStore.add(userMsg)
+    → adapter.buildRequest(messages, config)   ← formats request body
+    → adapter.send(requestBody, config)         ← HTTP call (fetch)
+    → adapter.parseResponse(response)           ← normalize response
+    → MessageStore.add(assistantMsg)
+    → emits 'message'
+    → returns assistantMsg
 ```
 
-### Node.js中使用 / For Node.js Usage
+With `toolCallingPlugin`, the flow loops: response → detect tool_calls → execute tools → add tool results → sendExisting → repeat (max 5 iterations).
 
-#### 安装
-```bash
-npm install my-ai-chat-framework axios
-# 或
-yarn add my-ai-chat-framework axios
-# 或
-pnpm add my-ai-chat-framework axios
-```
-
-#### 使用
-```javascript
-// CommonJS
-const { ChatService, Messages } = require('my-ai-chat-framework');
+---
 
-// ES模块
-import { ChatService, Messages } from 'my-ai-chat-framework';
+## 📦 Installation
 
-// 创建聊天服务
-const chat = new ChatService('your-api-key');
+```bash
+npm install my-ai-chat-framework
 ```
 
-### 本地开发 / Local Development
+---
 
-#### 安装依赖
-```bash
-npm install
-```
+## 🚀 Quick Start
 
-### 构建项目 / Build Project
-```bash
-npm run build
-```
+### Basic Usage (Flat Configuration)
+
+```javascript
+import { ChatService, openaiAdapter, toolCallingPlugin } from 'my-ai-chat-framework';
 
-### 输出文件 / 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依赖）
+const chat = new ChatService({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.deepseek.com',    // optional, defaults to OpenAI
+  model: 'deepseek-chat',
+  temperature: 0.7,
+  maxTokens: 2000
+});
 
-**注意**: axios已被打包进所有输出文件中，用户无需额外安装axios依赖。
+chat.use(openaiAdapter);
+chat.use(toolCallingPlugin);
 
-### 预览构建结果 / Preview Build
-```bash
-npm run preview
+chat.on('message', msg => console.log(msg.content));
+await chat.send('Hello!');
 ```
 
-### 在浏览器中使用 / Usage in Browser
+### Using `modelParams` (Recommended for Many Parameters)
 
-#### 传统浏览器（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>
+```javascript
+const chat = new ChatService({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.deepseek.com',
+  model: 'deepseek-chat',               // still at top level for convenience
+  modelParams: {                         // optional parameters grouped
+    temperature: 0.8,
+    maxTokens: 1500,
+    reasoningEffort: 'medium'           // for deepseek-reasoner
+  }
+});
 ```
 
-#### 现代浏览器（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>
-```
+### Registering a Tool
 
-### 在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');
-```
+chat.registerTool('get_weather', 'Get current weather for a city',
+  async (args) => {
+    // args = { city: 'Beijing' }
+    return `Weather in ${args.city}: 22°C, sunny`;
+  },
+  {  // parameter schema (optional but recommended)
+    city: { type: 'string', description: 'City name', required: true }
+  }
+);
 
-## 核心类说明 / Core Classes Description
+await chat.send('What\'s the weather in Beijing?');
+// → AI calls get_weather, framework executes it, AI responds with weather info
+```
 
-### Messages 类
-管理对话消息的核心类，支持：
-- 消息的推送、修改、撤回
-- 系统提示词管理
-- 工具定义管理
-- 数据导入/导出
+---
 
-### ChatRequestBuilder 类
-构建符合API规范的请求体，支持：
-- 自动格式化消息
-- 配置模型参数
-- 生成JSON请求体
+## 🔌 Plugins & Adapters
 
-### ApiClient 类
-HTTP客户端，支持：
-- 普通请求和流式请求
-- 请求中断
-- 错误处理
-- 前后端通用（使用axios）
+### openaiAdapter
 
-### ChatService 类
-高级封装类，简化使用：
-- 集成所有核心功能
-- 提供简单API接口
-- 自动管理消息状态
+Converts internal messages to OpenAI‑compatible format. Supports:
+- `apiUrl` – full URL (highest priority)
+- `baseUrl` + `path` – base domain + API path
+- Defaults to `https://api.openai.com/v1/chat/completions`
 
-## 示例代码 / Example Code
+| Config field | Type | Default | Description |
+|-------------|------|---------|-------------|
+| `apiKey` | string | **required** | Bearer token for Authorization header |
+| `apiUrl` | string | – | Full request URL (overrides baseUrl+path) |
+| `baseUrl` | string | `https://api.openai.com` | API base domain |
+| `path` | string | `/v1/chat/completions` | API endpoint path |
 
-```javascript
-// 创建聊天服务 / Create chat service
-const chat = new ChatService('your-api-key', 'deepseek-chat');
+### toolCallingPlugin
 
-// 发送消息 / Send message
-const response = await chat.send('你好，世界！');
-console.log('AI回复:', response);
+Detects `tool_calls` in assistant responses, executes registered tools, feeds results back, and continues the conversation (up to `maxIterations` = 5).
 
-// 流式消息 / Stream message
-await chat.stream('告诉我一个故事', 
-  (chunk) => console.log('收到数据:', chunk),
-  () => console.log('流式传输完成')
-);
+- `chat.registerTool(name, description, executor, parameters?)` – register a tool
+- Automatically injects `tool` role messages into the conversation
+- Recovers from tool execution errors gracefully (logs error, returns error message to model)
 
-// 流式传输中的工具调用 / Tool calling in streaming
-await chat.stream('查询北京天气', 
-  (chunk) => console.log('实时数据:', chunk.content),
-  (final) => console.log('最终结果:', final.content)
-);
+---
 
-// 撤回消息 / Undo message
-chat.undo();
+## 📡 Events (EventEmitter)
 
-// 导出对话 / Export conversation
-const exportData = chat.export();
+`ChatService` extends `EventEmitter`. Subscribe with `chat.on(event, handler)`:
 
-## 🤤 npm发布 / npm Publishing
+| Event | Payload | When |
+|-------|---------|------|
+| `sending` | `{ addUser, userInput, timestamp }` | Before each request |
+| `message` | `{ role, content, ... }` | Full assistant message received |
+| `stream-progress` | chunk object | Each streaming chunk arrives |
+| `error` | `{ error, timestamp }` | Any error during request |
 
-### 发布准备
-1. 确保已登录npm账号：
-```bash
-npm login
-```
+```javascript
+chat.on('sending', ({ userInput }) => console.log('Sending:', userInput));
+chat.on('message', msg => console.log('Got:', msg.content));
+chat.on('error', ({ error }) => console.error('Error:', error.message));
 
-2. 更新版本号（如果需要）：
-```bash
-npm version patch  # 小版本更新
-npm version minor  # 中版本更新  
-npm version major  # 大版本更新
+// on() returns an unsubscribe function
+const unsubscribe = chat.on('message', handler);
+unsubscribe(); // stop listening
 ```
 
-3. 构建项目：
-```bash
-npm run build
-```
+---
 
-### 发布到npm
-```bash
-npm publish
-```
+## 🧩 ChatService API
 
-### 发布后验证
-1. 检查包是否发布成功：
-```bash
-npm view my-ai-chat-framework
-```
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `chat.send(userInput)` | `Promise<Message>` | Send a message, get reply (non‑streaming) |
+| `chat.stream(userInput, onProgress, onDone)` | `Promise<Message>` | Send a message, get streaming reply |
+| `chat.sendExisting()` | `Promise<Message>` | Re‑send current messages without adding user input |
+| `chat.sendExistingStream(onProgress, onDone)` | `Promise<Message>` | Same as above, streaming |
+| `chat.use(plugin)` | `this` | Install a plugin/adapter |
+| `chat.setAdapter(adapter)` | `void` | Manually set the adapter |
+| `chat.on(event, handler)` | `unsubscribe function` | Subscribe to events |
+| `chat.registerTool(name, desc, fn, params?)` | `this` | Register a tool (requires toolCallingPlugin) |
+| `chat.messages` | `MessageStore` | Access the message store directly |
 
-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
+## 🗄️ MessageStore API
 
-## 📄 许可证 / License
-MIT License - 详见 [LICENSE](LICENSE) 文件
+| Method | Description |
+|--------|-------------|
+| `add(message)` | Add a raw message object |
+| `addUser(content, meta?)` | Add a user message |
+| `addAssistant(content, meta?)` | Add an assistant message |
+| `addSystem(content, meta?)` | Add a system message |
+| `addTool(content, toolCallId, meta?)` | Add a tool result message |
+| `getAll()` | Return a shallow copy of all messages |
+| `getLast()` | Return the last message (or null) |
+| `clear()` | Remove all messages |
+| `undoToLastAssistant()` | Remove messages after the last assistant message |
 
-## 🤝 贡献 / Contributing
-欢迎提交Issue和Pull Request！
+**Message format**:
 
-## 📞 支持 / Support
-如有问题，请提交Issue或联系作者。
+```javascript
+{
+  id: string,           // auto‑generated if not provided
+  role: 'user' | 'assistant' | 'system' | 'tool',
+  content: string,
+  toolCalls?: Array,    // assistant messages with tool calls
+  toolCallId?: string,  // tool messages
+  reasoningContent?: string,  // deepseek-reasoner
+  timestamp?: number,
+  metadata?: any
+}
+```
 
 ---
 
-**✨ 感谢使用 My AI Chat Framework! ✨**
-
-// 导入对话 / Import conversation
-chat.import(exportData);
-```
+## ❌ Error Handling
 
-## 🌊 流式传输下的工具调用 / Tool Calling in Streaming
+The framework throws typed errors for different failure modes:
 
-### 工作原理 / How It Works
-框架自动处理流式传输中的工具调用：
-1. **流式收集** / **Stream Collection**: 在流式传输过程中收集完整的工具调用信息
-2. **工具执行** / **Tool Execution**: 执行所有请求的工具
-3. **继续流式** / **Continue Streaming**: 将工具结果发送给AI并继续流式传输
+| Error Class | `.name` | When |
+|------------|---------|------|
+| `APIError` | `'APIError'` | Non‑2xx HTTP responses (401, 429, 500, etc.) |
+| `NetworkError` | `'NetworkError'` | `fetch` failures, connection timeouts |
+| `ConfigurationError` | `'ConfigurationError'` | Missing required config |
+| `ParsingError` | `'ParsingError'` | Malformed API response |
 
-### 代码示例 / 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);
+import { APIError, NetworkError, ConfigurationError, ParsingError } from 'my-ai-chat-framework';
+
+try {
+  await chat.send('Hello');
+} catch (error) {
+  if (error instanceof APIError) {
+    console.error(`API ${error.statusCode}: ${error.message}`);
+  } else if (error instanceof NetworkError) {
+    console.error('Network issue:', error.message);
   }
-);
+}
 ```
 
-## 📚 更多文档 / 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.
+## 📚 Configuration Reference
 
-## 依赖库 / Dependencies
-- [axios](https://github.com/axios/axios) - MIT License
-- [vite](https://vitejs.dev/) - MIT License
+`new ChatService(config)` accepts:
 
----
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | **required** | Your API key |
+| `baseUrl` | string | `'https://api.openai.com'` | API base URL (used with `path`) |
+| `path` | string | `'/v1/chat/completions'` | API path (used with `baseUrl`) |
+| `apiUrl` | string | – | Full API URL (overrides `baseUrl`+`path`) |
+| `model` | string | **required** | Model name (e.g., `deepseek-chat`) |
+| `modelParams` | object | `{}` | Grouped model parameters (see below) |
+| `temperature` | number | `0.7` | Sampling temperature (0–2) |
+| `maxTokens` | number | `2000` | Max tokens to generate |
+| `reasoningEffort` | string | – | For `deepseek-reasoner`: `'low'`, `'medium'`, `'high'` |
 
-*此文档由AI辅助生成，内容可能不完整或存在错误，请以实际代码为准。*
-*This document is AI-assisted and may be incomplete or contain errors. Please refer to the actual code for accurate information.*
+> Both flat and `modelParams` styles work. `modelParams` takes precedence over top‑level values.
 
-### 配置系统章节
-需要在两个 README 中都添加：
+---
 
-```markdown
-## 🔧 配置系统 / Configuration System
+## 🧪 Testing
 
-### 配置结构
-```javascript
-{
-  api: {
-    key: '',                    // API密钥
-    url: 'https://api.deepseek.com/v1/chat/completions',
-    timeout: 30000
-  },
-  model: {
-    name: 'deepseek-chat',
-    temperature: 0.7,
-    maxTokens: 2000,
-    stream: false,
-    reasoningEffort: 'medium'
-  }
-  // ...
-}
-```
-```
-````
-This is the code block that represents the suggested code change:
-````markdown
-## 🔧 配置系统 / Configuration System
+```bash
+# 1. Create a .env file with your API key
+echo "DEEPSEEK_API_KEY=sk-xxxxx" > .env
 
-### 配置结构 / Configuration Structure
-```javascript
-// 完整配置结构 / Complete configuration structure
-{
-  api: {
-    key: '',                    // API密钥（必填）/ API Key (required)
-    url: 'https://api.deepseek.com/v1/chat/completions',
-    timeout: 30000              // 请求超时（毫秒）/ Request timeout (ms)
-  },
-  model: {
-    name: 'deepseek-chat',      // 模型名称 / Model name
-    temperature: 0.7,           // 温度（0-2）/ Temperature (0-2)
-    maxTokens: 2000,            // 最大token数 / Max tokens
-    stream: false,              // 是否流式传输 / Whether to use streaming
-    reasoningEffort: 'medium'   // 推理强度（仅DeepSeek）/ Reasoning effort (DeepSeek only)
-  },
-  conversation: {
-    baseRounds: 10,             // 基础对话轮次 / Base conversation rounds
-    cycleRounds: 5              // 循环对话轮次 / Cycle conversation rounds
-  },
-  debug: false                  // 调试模式 / Debug mode
-}
+# 2. Run the test
+npm test
 ```
 
-### 使用方式 / Usage
+The test script (`test.js`) sends a simple message and logs the response.
 
-#### 方式1：基本使用 / Basic Usage
-```javascript
-import { ChatService } from './src/index.js';
-
-// 最小配置 / Minimal configuration
-const chat = new ChatService({
-  api: { key: 'your-api-key' }
-});
+---
 
-// 完整配置 / Complete configuration
-const chat = new ChatService({
-  api: {
-    key: 'your-api-key',
-    url: 'https://api.openai.com/v1/chat/completions'
-  },
-  model: {
-    name: 'gpt-4',
-    temperature: 0.8,
-    stream: true
-  }
-});
-```
+## 🛠️ Development
 
-#### 方式2：动态配置更新 / Dynamic Configuration Updates
-```javascript
-// 创建服务后更新配置 / Update configuration after creating service
-const chat = new ChatService({ api: { key: 'initial-key' } });
+```bash
+git clone https://github.com/your-username/my-ai-chat-framework.git
+cd my-ai-chat-framework
+npm install
 
-// 方法1：直接修改配置（自动同步）/ Method 1: Direct modification (auto-sync)
-chat.configManager.config.api.key = 'new-key';
-chat.configManager.config.model.temperature = 0.9;
+# Dev mode (watching)
+npm run dev
 
-// 方法2：批量更新 / Method 2: Batch update
-chat.configManager.update({
-  api: { url: 'https://custom-api.com/v1/chat/completions' },
-  model: { name: 'custom-model' }
-});
+# Build the library (ES + UMD + CJS)
+npm run build
 
-// 方法3：便捷方法 / Method 3: Convenience methods
-chat.setApi('new-key', 'https://api.openai.com/v1/chat/completions');
-chat.setModel('gpt-4', 0.8);
+# Run tests
+npm test
 ```
 
-#### 方式3：配置事件监听 / Configuration Event Listening
-```javascript
-// 监听配置变更 / Listen to configuration changes
-chat.configManager.on('config-changed', (data) => {
-  console.log(`配置 ${data.path} 已更新:`, data.oldValue, '→', data.newValue);
-  console.log(`Configuration ${data.path} updated:`, data.oldValue, '→', data.newValue);
-});
+---
 
-// 监听特定配置变更 / Listen to specific configuration changes
-chat.configManager.on('config-changed:model.temperature', (data) => {
-  console.log('温度已更新:', data.newValue);
-  console.log('Temperature updated:', data.newValue);
-});
-```
+## 📄 License
+
+MIT
 
-### 配置验证 / Configuration Validation
-框架会自动验证配置 / The framework automatically validates configuration:
-- ✅ API Key 格式检查 / API Key format check
-- ✅ URL 格式验证 / URL format validation
-- ✅ 数值范围检查（temperature: 0-2）/ Value range check (temperature: 0-2)
-- ✅ 枚举值验证（reasoningEffort: 'low'/'medium'/'high'）/ Enum value validation
-
-发现无效配置时会发出警告，但不会阻止执行 / Warnings are issued for invalid configurations, but execution is not blocked.
-
-### 最佳实践 / Best Practices
-1. **环境变量** / **Environment Variables**: 在生产环境中使用环境变量存储API Key / Use environment variables to store API keys in production
-2. **配置分离** / **Configuration Separation**: 将配置提取到单独的文件中 / Extract configuration to separate files
-3. **类型检查** / **Type Checking**: 使用TypeScript获得更好的类型安全 / Use TypeScript for better type safety
-4. **版本控制** / **Version Control**: 不要将敏感配置提交到版本控制系统 / Do not commit sensitive configurations to version control
-````