my-ai-chat-framework 2.0.0 → 3.0.0

package/README_ZH.md

@@ -0,0 +1,375 @@
+
+# 🤖 我的AI聊天框架
+
+一个轻量级、模块化的AI聊天框架，内置插件系统、统一消息格式和工具调用支持。
+
+> **⚠️ 注意**：本项目用于**学习目的**，由 **AI 生成**，不适用于生产环境。不保证向后兼容性，请谨慎使用。
+
+## ✨ 特性
+
+- **轻量核心** – 仅约300行代码，易于理解和扩展。
+- **插件系统** – 添加功能（工具调用、思维链、自定义适配器）无需修改核心。
+- **统一消息格式** – 所有组件使用一致的数据结构。
+- **多环境支持** – 构建为 ES 模块、UMD 和 CommonJS 格式，可用于浏览器和 Node.js。
+- **无外部依赖** – 使用原生 `fetch`（Node 18+ 及现代浏览器）。
+- **工具调用** – 内置插件处理 AI 的函数调用（自动多轮循环）。
+- **流式传输** – 完整支持实时响应。
+- **灵活配置** – 支持平铺和嵌套 `modelParams` 两种配置风格。
+- **事件驱动** – 内置 EventEmitter，支持 `message`、`sending`、`error`、`stream-progress` 事件。
+- **管道车间（v3.0）** – `chat.pipe()` 在任何阶段挂自定义功能（beforeSend/afterSend），核心代码不用改。
+- **类型化错误** – `APIError`、`NetworkError`、`ConfigurationError`、`ParsingError`，方便分类处理。
+
+---
+
+## 🧱 架构概览
+
+```
+src/
+├── index.js                  # 公共入口（统一导出）
+├── core/
+│   ├── ChatService.js        # 核心：配置、管道调度、发送/流式、插件托管
+│   ├── Pipeline.js           # 顺序管道（v3.0：小车 ctx 依次过车间）
+│   ├── MessageStore.js       # 内存消息列表（增删改查）
+│   ├── SystemPromptStore.js  # 可开关的 system 提示词
+│   ├── EventEmitter.js       # 极简发布/订阅（on/off/emit）
+│   └── Errors.js             # 自定义错误类
+├── adapters/
+│   └── openai.js             # OpenAI 兼容 API 适配器（协议见 assertAdapter）
+├── plugins/
+│   ├── tool-calling.js       # 工具调用插件（afterSend 车间，自动检测&循环执行）
+│   └── model-registry.js     # 模型能力表（beforeSend 车间）
+└── utils/
+    ├── MessageFormatter.js   # 消息格式转换（可注册）
+    ├── typeCheck.js          # 类型判断工具
+    └── url.js                # URL 拼接工具
+tests/                        # node:test 单元测试（core / pipeline / integration）
+```
+
+**数据流**：
+
+```
+用户调用 chat.send(input)
+  → ChatService._request() → 小车 ctx 依次开过车间：
+    → prepareInput（加用户消息、合并配置、发出 'sending'）
+    → beforeSend（内部钩子 + 用户 beforeSend 车间）
+    → autoContinue / buildRequest（→ 请求体）
+    → send（adapter.send / stream + 重试 + 占位消息）
+    → afterSend（用户车间 + tool-calling 循环）
+    → 返回结果，过程中发出 'message' 事件
+```
+
+使用 `toolCallingPlugin` 时，流程会循环：响应 → 检测 tool_calls → 执行工具 → 添加工具结果 → sendExisting → 重复（最多 5 轮）。
+
+---
+
+## 📦 安装
+
+```bash
+npm install my-ai-chat-framework
+```
+
+---
+
+## 🚀 快速开始
+
+### 基础用法（平铺配置）
+
+```javascript
+import { ChatService, openaiAdapter, toolCallingPlugin } from 'my-ai-chat-framework';
+
+const chat = new ChatService({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.deepseek.com',    // 可选，默认 OpenAI
+  model: 'deepseek-chat',
+  temperature: 0.7,
+  maxTokens: 2000
+});
+
+chat.use(openaiAdapter);
+chat.use(toolCallingPlugin);
+
+chat.on('message', msg => console.log(msg.content));
+await chat.send('你好！');
+```
+
+### 工厂模式（配置归属更清晰，推荐）
+
+```javascript
+import { ChatService, createOpenAIAdapter, createToolCallingPlugin } from 'my-ai-chat-framework';
+
+// 运输层 + 请求默认参数归适配器
+const adapter = createOpenAIAdapter({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.deepseek.com',
+  modelParams: { temperature: 0.8, maxTokens: 2000 }
+});
+
+const chat = new ChatService({
+  adapter,                    // 构造时注入（等价于 chat.use(adapter)）
+  model: 'deepseek-chat',
+  system: '你是乐于助人的AI助手'
+});
+
+chat.use(createToolCallingPlugin({ timeout: 30000 }));  // 插件自带配置
+
+// 请求级覆盖：只对本次请求生效
+await chat.send('你好', { temperature: 0.2 });
+```
+
+### 使用 `modelParams`（参数较多时推荐）
+
+```javascript
+const chat = new ChatService({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.deepseek.com',
+  model: 'deepseek-chat',               // 顶层仍保留 model 方便
+  modelParams: {                         // 可选参数分组
+    temperature: 0.8,
+    maxTokens: 1500,
+    reasoningEffort: 'medium'           // 用于 deepseek-reasoner
+  }
+});
+```
+
+### 注册工具
+
+```javascript
+chat.registerTool('get_weather', '获取指定城市的天气',
+  async (args) => {
+    // args = { city: '北京' }
+    return `${args.city}天气：22°C，晴`;
+  },
+  {  // 参数 schema（可选但推荐）
+    city: { type: 'string', description: '城市名称', required: true }
+  }
+);
+
+await chat.send('北京今天天气怎么样？');
+// → AI 调用 get_weather，框架执行，AI 返回天气信息
+```
+
+---
+
+## 🔌 插件与适配器
+
+### openaiAdapter
+
+将内部消息转换为 OpenAI 兼容格式。支持：
+- `apiUrl` – 完整 URL（最高优先级）
+- `baseUrl` + `path` – 基础域名 + API 路径
+- 默认：`https://api.openai.com/v1/chat/completions`
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `apiKey` | string | **必填** | Authorization 请求头中的 Bearer token |
+| `apiUrl` | string | – | 完整请求 URL（优先级高于 baseUrl+path） |
+| `baseUrl` | string | `https://api.openai.com` | API 基础域名 |
+| `path` | string | `/v1/chat/completions` | API 端点路径 |
+
+### toolCallingPlugin
+
+检测助手响应中的 `tool_calls`，执行已注册的工具，将结果回传并继续对话（最多 `maxIterations` = 5 轮）。
+
+- `chat.registerTool(name, description, executor, parameters?)` – 注册工具
+- 自动向对话中插入 `role: 'tool'` 消息
+- 工具执行出错时优雅降级（记录日志，将错误信息返回给模型）
+- 配置：`createToolCallingPlugin({ timeout: 30000, maxIterations: 5 })`
+
+> ⚠️ **多实例注意**：`openaiAdapter` / `toolCallingPlugin` / `modelRegistryPlugin` 默认导出是模块级单例，装到多个 ChatService 实例会互相覆盖。多实例场景请用工厂：`createOpenAIAdapter(opts)` / `createToolCallingPlugin(opts)` / `createModelRegistryPlugin(opts)`。
+
+---
+
+## 📡 事件系统（EventEmitter）
+
+`ChatService` 继承自 `EventEmitter`。通过 `chat.on(event, handler)` 订阅：
+
+| 事件 | 数据 | 触发时机 |
+|------|------|----------|
+| `sending` | `{ addUser, userInput, timestamp }` | 每次请求发送前 |
+| `message` | `{ role, content, ... }` | 收到完整助手消息 |
+| `stream-progress` | chunk 对象 | 每个流式块到达时 |
+| `error` | `{ error, timestamp }` | 请求过程中发生错误 |
+
+```javascript
+chat.on('sending', ({ userInput }) => console.log('发送中:', userInput));
+chat.on('message', msg => console.log('收到:', msg.content));
+chat.on('error', ({ error }) => console.error('错误:', error.message));
+
+// on() 返回取消订阅函数
+const unsubscribe = chat.on('message', handler);
+unsubscribe(); // 停止监听
+```
+
+---
+
+## 🧩 ChatService API
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| `chat.send(userInput)` | `Promise<Message>` | 发送消息，获取回复（非流式） |
+| `chat.stream(userInput, onProgress, onDone)` | `Promise<Message>` | 发送消息，获取流式回复 |
+| `chat.sendExisting()` | `Promise<Message>` | 用现有消息重新请求（不添加用户消息） |
+| `chat.sendExistingStream(onProgress, onDone)` | `Promise<Message>` | 同上，流式 |
+| `chat.use(plugin)` | `this` | 安装插件/适配器 |
+| `chat.setAdapter(adapter)` | `void` | 手动设置适配器 |
+| `chat.on(event, handler)` | `取消订阅函数` | 订阅事件 |
+| `chat.registerTool(name, desc, fn, params?)` | `this` | 注册工具（需安装 toolCallingPlugin） |
+| `chat.messages` | `MessageStore` | 直接访问消息存储 |
+
+---
+
+## 🗄️ MessageStore API
+
+| 方法 | 描述 |
+|------|------|
+| `add(message)` | 添加原始消息对象 |
+| `addUser(content, meta?)` | 添加用户消息 |
+| `addAssistant(content, meta?)` | 添加助手消息 |
+| `addSystem(content, meta?)` | 添加系统消息 |
+| `addTool(content, toolCallId, meta?)` | 添加工具结果消息 |
+| `addOnceAssistant(content, options?)` | 添加一次性引导消息（默认 `_ephemeral: true` + `prefix: true`；options: `{ reasoningContent, prefix }`） |
+| `getAll()` | 返回所有消息的浅拷贝 |
+| `getLast()` | 返回最后一条消息（或 null） |
+| `clear()` | 清空所有消息 |
+| `undoToLastAssistant()` | 移除最后一条助手消息之后的所有消息 |
+| `undoToPreviousUser(id)` | 撤回到指定消息之前的最近 user，删除该 user 之后到该消息（含）之间的消息（适用于重发） |
+
+**消息格式**：
+
+```javascript
+{
+  id: string,           // 未提供时自动生成
+  role: 'user' | 'assistant' | 'system' | 'tool',
+  content: string,
+  toolCalls?: Array,    // 助手消息中的工具调用
+  toolCallId?: string,  // 工具消息
+  reasoningContent?: string,  // deepseek-reasoner 思维链
+  timestamp?: number,
+  metadata?: any
+}
+```
+
+---
+
+## ❌ 错误处理
+
+框架针对不同失败场景抛出类型化错误：
+
+| 错误类 | `.name` | 触发场景 |
+|--------|---------|----------|
+| `APIError` | `'APIError'` | 非 2xx HTTP 响应（401, 429, 500 等） |
+| `NetworkError` | `'NetworkError'` | `fetch` 失败、连接超时等 |
+| `ConfigurationError` | `'ConfigurationError'` | 缺少必要配置项 |
+| `ParsingError` | `'ParsingError'` | API 响应格式异常 |
+
+```javascript
+import { APIError, NetworkError, ConfigurationError, ParsingError } from 'my-ai-chat-framework';
+
+try {
+  await chat.send('你好');
+} catch (error) {
+  if (error instanceof APIError) {
+    console.error(`API 错误 ${error.statusCode}: ${error.message}`);
+  } else if (error instanceof NetworkError) {
+    console.error('网络问题:', error.message);
+  }
+}
+```
+
+---
+
+## 📚 配置参考
+
+`new ChatService(config)` 可接受以下选项：
+
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `apiKey` | string | **必填** | API 密钥 |
+| `baseUrl` | string | `'https://api.openai.com'` | API 基础域名（与 `path` 配合） |
+| `path` | string | `'/v1/chat/completions'` | API 路径（与 `baseUrl` 配合） |
+| `apiUrl` | string | – | 完整 API URL（优先级高于 `baseUrl`+`path`） |
+| `model` | string | **必填** | 模型名称（如 `deepseek-chat`） |
+| `modelParams` | object | `{}` | 分组模型参数（见下） |
+| `temperature` | number | `0.7` | 温度（0–2） |
+| `maxTokens` | number | `2000` | 最大生成 token 数 |
+| `reasoningEffort` | string | – | 仅 `deepseek-reasoner`：`'low'`、`'medium'`、`'high'` |
+
+> 平铺和 `modelParams` 两种风格都支持。`modelParams` 中的值优先级高于顶层同名属性。
+
+---
+
+## 🧪 测试
+
+```bash
+# 1. 创建 .env 文件，写入 API key
+echo "DEEPSEEK_API_KEY=sk-xxxxx" > .env
+
+# 2. 运行测试
+npm test
+```
+
+单元测试：`npm test`（`tests/core.test.js` + `tests/pipeline.test.js`，无需 API Key）。集成测试：`npm run test:integration`（`tests/integration.test.js`，需要 .env 中的 `DEEPSEEK_API_KEY`）。
+
+---
+
+## 🛠️ 开发
+
+```bash
+git clone https://github.com/your-username/my-ai-chat-framework.git
+cd my-ai-chat-framework
+npm install
+
+# 开发模式（监听文件变化）
+npm run dev
+
+## 🧩 扩展：管道车间（v3.0）
+
+核心流程是一辆小车（ctx）依次开过车间；加新功能 = 注册一个车间，核心代码不用改。
+
+```javascript
+// 发送前注入角色卡
+chat.pipe({
+  name: '角色卡注入',
+  phase: 'beforeSend',                       // 默认
+  async run(ctx) {
+    ctx.messages.add({ role: 'system', content: '你是傲娇霸总' });
+  }
+});
+
+// 发送后改写回复
+chat.pipe({
+  name: '加时间戳',
+  phase: 'afterSend',
+  run(ctx) { if (ctx.result?.content) ctx.result.content += ' — ' + Date.now(); }
+});
+
+chat.unpipe('角色卡注入');                    // 移除
+console.log(chat.pipelineStages);            // 查看车间顺序
+```
+
+**写一个 adapter（同级服务商）**：实现 4 个方法即可，`assertAdapter` 会帮你在装错时点名哪个方法缺失：
+
+```javascript
+const myAdapter = {
+  buildRequest(messages, config) { /* 内部消息 → 请求体 */ },
+  async send(body, config, opts) { /* 非流式 → 原始响应 */ },
+  async stream(body, config, onProgress, onDone, opts) { /* 流式 */ },
+  parseResponse(resp) { /* 原始响应 → 内部消息格式 */ },
+};
+chat.setAdapter(myAdapter);
+```
+
+---
+
+# 构建库（ES + UMD + CJS）
+npm run build
+
+# 运行测试
+npm test
+```
+
+---
+
+## 📄 许可证
+
+MIT