my-ai-chat-framework 2.7.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [3.0.0] - 2026-08-?
+
+### Added
+- **公开管道 API**：`chat.pipe({ name, phase?, run(ctx) })` / `chat.unpipe(name)` / `chat.pipelineStages`
+  - phase `beforeSend`（默认）：内部 beforeRequest 之后、构建请求体之前
+  - phase `afterSend`：发送完成、结果落位之后（可改 ctx.result）
+  - 不注册任何车间 = 行为与 2.8.x 完全一致
+- **协议固化**：`assertAdapter` 校验 buildRequest/send/stream/parseResponse，缺方法抛 ConfigurationError 并列出方法名；JSDoc @typedef ChatAdapter / PipelineContext / PipeStage
+- **插件车间化**：tool-calling 经 afterSend 车间、model-registry 经 beforeSend 车间，不再占用 `_processResponse` 单座槽位
+- 新增测试 `tests/pipeline.test.js`（8 例：pipe 顺序/冲突/unpipe/改ctx/SSE 冒烟/工具循环端到端）
+
+### Changed
+- `ChatService._request` 固定线拆为内部管道：prepareInput → beforeSend → autoContinue → buildRequest → send（行为等价）
+- `_hooks` beforeRequest 保留为兼容桥；`_processResponse` 保留为旧通道（新代码请用 afterSend 车间）
+- 版本号 2.8.0 → 3.0.0（新增公共 API 面）
+
+### Known delta（流式 tool-calling 时序）
+- 流式工具调用时，初始回复的 `message` 事件在工具循环前发出（旧版循环后发）。非流式时序与旧版一致。
+
+## [2.8.0] - 2026-08-08
+
+### Added
+- **配置归属系统**：配置按层归属（运输/请求/会话/插件），谁消费谁声明
+- **工厂函数**：`createOpenAIAdapter(opts)` / `createToolCallingPlugin(opts)` / `createModelRegistryPlugin(opts)`——每个实例自持状态，规避模块级单例互踩陷阱
+- **请求级参数覆盖**：`chat.send(input, params)` / `chat.stream(input, params, onProgress, onDone)` / `sendExisting(params)` / `sendExistingStream(params, ...)`，合并链 = 适配器默认 ← 会话配置 ← 本次覆盖（近者优先）
+- **capabilities 按生效 model 解析**：model-registry 在 beforeRequest 钩子里按"本次请求的 model"（含请求级覆盖）查表
+- `chat.use(plugin, options)`：options 透传 `plugin.install(chat, options)`
+- `new ChatService({ adapter })`：构造时直接注入适配器
+- 工具定义移入插件实例（不再写 `chat.config.tools`），工具超时改走 `createToolCallingPlugin({ timeout })`
+
+### Changed
+- `updateConfig` 收窄为会话层字段（model/temperature/maxTokens/modelParams/system/retry/ephemeralContinue），非白名单或非法值抛 `ConfigurationError`（修复绕过校验问题）
+- openaiAdapter 的 transport（apiKey/baseUrl/headers）从实例自持，单例 `openaiAdapter` 保留为平铺兼容路径
+- `buildRequest(messages, config, systemPrompts)` 的 config 现为合并后的请求参数
+
+### Fixed
+- TODO.md 高危 #1：插件共享可变状态——工厂化后实例隔离（单例保留为兼容路径）
+- TODO.md 高危 #3：updateConfig 绕过校验——现在白名单 + 校验
+
+## [2.7.0] - 2026-05-25
+
+### Added
+- **Ephemeral 临时消息**：_ephemeral: true 标记，仅底部连续时参与请求，其余自动过滤
+- **续写转正**：continueLast / continueLastStream 续写 ephemeral 消息后自动转正（delete _ephemeral）
+- **EventEmitter.emitAsync**：异步触发事件，支持 beforeRequest 等钩子
+- **beforeRequest 钩子**：chat._hooks.on('beforeRequest', ...) 在 buildRequest 前修改 messages
+- **_processResponse 钩子**：tool-calling 改为注册此钩子，不再覆盖 send/stream
+
+### Changed
+- MessageFormatter 过滤 ephemeral：识别底部连续段，中间 ephemeral 自动跳过
+- ChatService._request 拆为 4 个私有方法（_addUserMessage / _withRetry / _stream / _handleResult）
+- 	ool-calling.js 改为注册 _processResponse，不再替换 send/stream
+- dapter.stream 不再接收/操作 streamEntry，_complete 由 ChatService 管理
+- openaiAdapter.stream 约减 20 行（删除所有 entry 相关代码）
+
+### Fixed
+- retry 循环重复 push 占位消息（已修复：提到循环外）
+- continueLastStream 被续写消息丢失（已修复：独立占位，ChatService 管理）
+- prefix 续写空 content 被过滤（已修复：MessageFormatter 保留 prefix）
+
+## [2.6.0] - 2026-05-23

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 My Name
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2024 My Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -16,6 +16,7 @@ A lightweight, modular AI chat framework with plugin system, unified message for
 - **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.
+- **Pipeline Stages (v3.0)** – `chat.pipe()` to hook custom logic at `beforeSend` / `afterSend` without touching the core.
 - **Custom Error Classes** – `APIError`, `NetworkError`, `ConfigurationError`, `ParsingError` for fine‑grained error handling.
 
 ---
@@ -26,32 +27,35 @@ A lightweight, modular AI chat framework with plugin system, unified message for
 src/
 ├── index.js                  # Public entry point (re-exports)
 ├── core/
-│   ├── ChatService.js        # Main service: config, send/stream, plugin hosting
+│   ├── ChatService.js        # Main service: config, pipeline, send/stream, plugin hosting
+│   ├── Pipeline.js           # Sequential pipeline (v3.0: ctx flows through stages)
 │   ├── MessageStore.js       # In-memory message list with CRUD helpers
+│   ├── SystemPromptStore.js  # Toggleable system prompts
 │   ├── EventEmitter.js       # Minimal pub/sub (on/off/emit)
 │   └── Errors.js             # Custom error classes
 ├── adapters/
-│   └── openai.js             # OpenAI‑compatible API adapter (plugin pattern)
+│   └── openai.js             # OpenAI‑compatible API adapter (protocol via assertAdapter)
 ├── plugins/
-│   └── tool-calling.js       # Tool calling plugin (auto‑detect & loop)
+│   ├── tool-calling.js       # Tool calling plugin (afterSend stage, auto‑detect & loop)
+│   └── model-registry.js     # Model capability table (beforeSend stage)
 └── utils/
+    ├── MessageFormatter.js   # Message format conversion (registrable)
     ├── typeCheck.js          # Type checking helpers
     └── url.js                # URL joining utility
+tests/                        # node:test suites (core / pipeline / integration)
 ```
 
 **Data flow**:
 
 ```
 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
+  → ChatService._request() → ctx flows through stages:
+    → prepareInput (add user msg, merge config, emit 'sending')
+    → beforeSend (internal hook + user beforeSend stages)
+    → autoContinue / buildRequest (→ request body)
+    → send (adapter.send / stream + retry + placeholder)
+    → afterSend (user stages + tool-calling loop)
+    → returns result, emitting 'message' along the way
 ```
 
 With `toolCallingPlugin`, the flow loops: response → detect tool_calls → execute tools → add tool results → sendExisting → repeat (max 5 iterations).
@@ -88,6 +92,32 @@ chat.on('message', msg => console.log(msg.content));
 await chat.send('Hello!');
 ```
 
+### Factory Mode (Owned Configuration, Recommended)
+
+```javascript
+import { ChatService, createOpenAIAdapter, createToolCallingPlugin } from 'my-ai-chat-framework';
+
+// transport + request defaults belong to the adapter
+const adapter = createOpenAIAdapter({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.deepseek.com',
+  modelParams: { temperature: 0.8, maxTokens: 2000 }
+});
+
+const chat = new ChatService({
+  adapter,                    // injected at construction (same as chat.use(adapter))
+  model: 'deepseek-chat',
+  system: 'You are a helpful assistant'
+});
+
+chat.use(createToolCallingPlugin({ timeout: 30000 }));  // plugin options
+
+// per-request override (this request only)
+await chat.send('Hello', { temperature: 0.2 });
+```
+
+> ⚠️ The default exports `openaiAdapter` / `toolCallingPlugin` / `modelRegistryPlugin` are module-level singletons — installing one on multiple `ChatService` instances will clobber shared state. Use the factories (`createXxx`) for multiple instances.
+
 ### Using `modelParams` (Recommended for Many Parameters)
 
 ```javascript
@@ -148,6 +178,25 @@ Detects `tool_calls` in assistant responses, executes registered tools, feeds re
 
 ---
 
+## 🔧 Extending with Pipeline (v3.0)
+
+```javascript
+// Inject a role card before every request
+chat.pipe({ name: 'role-card', phase: 'beforeSend', async run(ctx) {
+  ctx.messages.add({ role: 'system', content: 'You are a tsundere CEO.' });
+}});
+
+// Post-process the reply
+chat.pipe({ name: 'stamp', phase: 'afterSend', run(ctx) {
+  if (ctx.result?.content) ctx.result.content += ' — ' + Date.now();
+}});
+
+chat.unpipe('role-card');   // remove
+console.log(chat.pipelineStages);  // inspect stage order
+```
+
+See `docs/DEVELOPER.md` \u201cWrite a Stage\u201d for the full guide.
+
 ## 📡 Events (EventEmitter)
 
 `ChatService` extends `EventEmitter`. Subscribe with `chat.on(event, handler)`:
@@ -196,10 +245,12 @@ unsubscribe(); // stop listening
 | `addAssistant(content, meta?)` | Add an assistant message |
 | `addSystem(content, meta?)` | Add a system message |
 | `addTool(content, toolCallId, meta?)` | Add a tool result message |
+| `addOnceAssistant(content, options?)` | Add a one-shot assistant guide message (defaults to `_ephemeral: true` + `prefix: true`; options: `{ reasoningContent, prefix }`) |
 | `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 |
+| `undoToPreviousUser(id)` | Remove messages from the message with `id` (inclusive) back to, but excluding, the previous user message — useful before resending |
 
 **Message format**:
 
@@ -263,6 +314,42 @@ try {
 
 > Both flat and `modelParams` styles work. `modelParams` takes precedence over top‑level values.
 
+### modelParams
+
+`modelParams` groups all model-related parameters. Supported fields:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | – | Model name (overrides top-level `model`) |
+| `temperature` | number | `0.7` | Sampling temperature (0–2) |
+| `maxTokens` | number | `2000` | Max tokens to generate |
+| `reasoningEffort` | string | – | For `deepseek-reasoner`: `'low'`, `'medium'`, `'high'` |
+| `topP` | number | – | Nucleus sampling (0–1) |
+| `frequencyPenalty` | number | – | Penalize frequent tokens (-2.0–2.0) |
+| `presencePenalty` | number | – | Penalize repeated tokens (-2.0–2.0) |
+| `stop` | string \| string[] | – | Stop sequences |
+| `responseFormat` | object | – | e.g., `{ type: 'json_object' }` |
+| `seed` | number | – | For reproducible results |
+
+**Naming convention**: CamelCase fields (`maxTokens`, `topP`) are managed by the adapter (converted to API format). Any unknown field is passed through as‑is—use the provider's native naming (e.g., `snake_case` for OpenAI).
+
+```javascript
+const chat = new ChatService({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.deepseek.com',
+  model: 'deepseek-chat',
+  modelParams: {
+    temperature: 0.8,
+    maxTokens: 1500,
+    topP: 0.9,
+    frequencyPenalty: 0.5,
+    // unknown fields pass through directly (use API's native names):
+    logprobs: true,
+    top_logprobs: 5
+  }
+});
+```
+
 ---
 
 ## 🧪 Testing
@@ -275,7 +362,7 @@ echo "DEEPSEEK_API_KEY=sk-xxxxx" > .env
 npm test
 ```
 
-The test script (`test.js`) sends a simple message and logs the response.
+Unit tests: `npm test` (`tests/core.test.js` + `tests/pipeline.test.js`, no API key needed). Integration test: `npm run test:integration` (`tests/integration.test.js`, requires `DEEPSEEK_API_KEY` in `.env`).
 
 ---
 

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