my-ai-chat-framework 1.0.2 → 1.1.0

package/README.md

@@ -43,6 +43,63 @@ my-ai-chat-framework/
 └── package.json                   # 项目配置 / Project configuration
 ```
 
+## 🎯 统一数据格式 / Unified Data Format
+
+从v1.1.0开始，框架使用统一的数据格式在所有组件之间传递消息，简化了使用体验。
+
+### 核心消息格式
+
+所有消息都遵循以下格式：
+
+```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
+});
+```
+
 ## 📦 安装和使用 / Installation and Usage
 
 ### 浏览器中使用 / For Browser Usage
@@ -198,7 +255,7 @@ chat.undo();
 // 导出对话 / Export conversation
 const exportData = chat.export();
 
-## 📤 npm发布 / npm Publishing
+## 🤤 npm发布 / npm Publishing
 
 ### 发布准备
 1. 确保已登录npm账号：
@@ -302,4 +359,134 @@ This project is licensed under the MIT License. See the LICENSE file for more de
 ---
 
 *此文档由AI辅助生成，内容可能不完整或存在错误，请以实际代码为准。*
-*This document is AI-assisted and may be incomplete or contain errors. Please refer to the actual code for accurate information.*
+*This document is AI-assisted and may be incomplete or contain errors. Please refer to the actual code for accurate information.*
+
+### 配置系统章节
+需要在两个 README 中都添加：
+
+```markdown
+## 🔧 配置系统 / Configuration System
+
+### 配置结构
+```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
+
+### 配置结构 / 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
+}
+```
+
+### 使用方式 / Usage
+
+#### 方式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
+  }
+});
+```
+
+#### 方式2：动态配置更新 / Dynamic Configuration Updates
+```javascript
+// 创建服务后更新配置 / Update configuration after creating service
+const chat = new ChatService({ api: { key: 'initial-key' } });
+
+// 方法1：直接修改配置（自动同步）/ Method 1: Direct modification (auto-sync)
+chat.configManager.config.api.key = 'new-key';
+chat.configManager.config.model.temperature = 0.9;
+
+// 方法2：批量更新 / Method 2: Batch update
+chat.configManager.update({
+  api: { url: 'https://custom-api.com/v1/chat/completions' },
+  model: { name: 'custom-model' }
+});
+
+// 方法3：便捷方法 / Method 3: Convenience methods
+chat.setApi('new-key', 'https://api.openai.com/v1/chat/completions');
+chat.setModel('gpt-4', 0.8);
+```
+
+#### 方式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);
+});
+```
+
+### 配置验证 / 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
+````

package/README_ZH.md

@@ -45,6 +45,49 @@ npm install
 npm run build
 ```
 
+### 基本使用
+```javascript
+import { ChatService } from './src/index.js';
+
+// 创建聊天服务（新版配置方式）
+const chat = new ChatService({
+  api: { key: 'your-api-key' },
+  model: { name: 'deepseek-chat' }
+});
+
+// 发送消息
+const response = await chat.send('你好！');
+console.log('AI回复:', response);
+```
+
+### 完整示例
+```javascript
+import { ChatService } from './src/index.js';
+
+// 创建带完整配置的聊天服务
+const chat = new ChatService({
+  api: {
+    key: 'your-api-key',
+    url: 'https://api.deepseek.com/v1/chat/completions'
+  },
+  model: {
+    name: 'deepseek-chat',
+    temperature: 0.8,
+    stream: false
+  },
+  debug: true
+});
+
+// 注册工具
+chat.registerTool('get_weather', { /* 工具定义 */ }, async (args) => {
+  return { temperature: '25°C', condition: '晴朗' };
+});
+
+// 发送消息并处理工具调用
+const response = await chat.send('北京的天气怎么样？');
+console.log('最终回复:', response);
+```
+
 ### 输出文件
 构建后会在 `dist/` 目录生成以下文件：
 - `my-ai-chat-framework.es.js` - ES模块格式（包含axios依赖）
@@ -398,4 +441,105 @@ MIT License - 详见LICENSE文件
 **流式传输**: ✅ 完全支持  
 **事件系统**: ✅ 完全支持  
 
-**提示**: 这是一个学习项目，旨在帮助理解AI聊天框架的设计和实现。欢迎反馈和建议！
+**提示**: 这是一个学习项目，旨在帮助理解AI聊天框架的设计和实现。欢迎反馈和建议！
+
+## 🔧 配置系统 / Configuration System
+
+### 配置结构 / 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
+}
+```
+
+### 使用方式 / Usage
+
+#### 方式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
+  }
+});
+```
+
+#### 方式2：动态配置更新 / Dynamic Configuration Updates
+```javascript
+// 创建服务后更新配置 / Update configuration after creating service
+const chat = new ChatService({ api: { key: 'initial-key' } });
+
+// 方法1：直接修改配置（自动同步）/ Method 1: Direct modification (auto-sync)
+chat.configManager.config.api.key = 'new-key';
+chat.configManager.config.model.temperature = 0.9;
+
+// 方法2：批量更新 / Method 2: Batch update
+chat.configManager.update({
+  api: { url: 'https://custom-api.com/v1/chat/completions' },
+  model: { name: 'custom-model' }
+});
+
+// 方法3：便捷方法 / Method 3: Convenience methods
+chat.setApi('new-key', 'https://api.openai.com/v1/chat/completions');
+chat.setModel('gpt-4', 0.8);
+```
+
+#### 方式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);
+});
+```
+
+### 配置验证 / 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