my-ai-chat-framework 2.7.0 → 4.0.0

package/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [4.0.0] - 2026-09
+
+> 主题：**把"玩法"从核心搬出去，并给核心补上"出口"**。
+> 一句话：核心只保留"怎么合并、怎么发、怎么映射字段"；"续写 / 临时消息"变成可选的 continuation 插件。
+
+### Added（清债 · A 组）
+- **A1 删旧通道**：`_hooks` / `beforeRequest` 钩子 / `_processResponse` 全部移除（改用 `pipe` 车间 / `replaceStage`）；`beforeSend` 步骤改空实现
+- **A2 可扩展配置白名单**：`registerConfigKeys(keys)` / `unregisterConfigKeys` / `configKeys`
+  —— 插件自带配置（如 continuation 的 `autoContinue`）可运行时修改，**不必回头改核心**
+- **A3 错误类型统一**：新增 `ValidationError extends ConfigurationError`，15 处裸 `Error` 全部类型化
+- **A5 流式增量**：`onProgress(snap, delta)` —— `snap` 全量、`delta` 本次新增
+- **A6 SSE 健壮化**：支持 `\r\n`、`data:`（无空格）、多行 `data` 拼接
+
+### Changed（架构 · B 组）
+- **B1 每请求独立中断**：`abort()` 中断全部 / `abort(id)` 精确中断 / `activeRequests`；多请求互不干扰（旧版共享单个 controller，会中断错的那个）
+- **B3 消息存储可注入**：`new ChatService({ store })`（为将来的对话树/自定义存储留口）
+- **B4 插件命名空间**：插件 API 挂到 `chat.plugins.<插件名>`，不再直接挂 `chat`（撞名从根上消失）；三个插件都提供 `uninstall`
+- **A4 工具去限制 / 参数不默认**（BREAKING）：
+  - 工具循环**默认不限轮数**（旧版硬编码 5 轮）；`timeout` 只在显式传入时生效，并修掉超时泄漏（clearTimeout + AbortController 通知工具）
+  - `registerTool` 生成标准 JSON Schema（必填项进顶层 `required`，properties 不再残留）
+  - `temperature` / `maxTokens` **不再有默认值** —— 不传就不放进请求体（由 API 用自己的默认）
+
+### Docs
+- **docs/API-STABILITY.md**：稳定性契约（Stable 清单 / 四个协议 / 事件 payload 形状 / 兼容纪律 / v3→v4 迁移记录）
+
+### Added
+- **出口 API**：`chat.replaceStage(name, fn)` / `restoreStage` / `unstage` / `restage` / `getStage` / `internalStages`
+  —— 5 个内部步骤（prepareInput / beforeSend / autoContinue / buildRequest / send）可替换、可关闭、可包装
+- **消息过滤器注册点**：`MessageFormatter.registerFilter(name, fn, { priority })` / `unregisterFilter` / `listFilters`
+  —— 决定"哪些消息进入请求"的规则变成可插拔链（同名覆盖，返回旧函数）
+- **continuation 插件**（`src/plugins/continuation.js`，随框架发布，非独立包）：
+  - 续写检测（`replaceStage('autoContinue', …)`）、ephemeral 过滤规则、`chat.continueLast` / `continueLastStream`
+  - `createContinuationPlugin({ autoContinue = false })` + `plugin.uninstall(chat)` 完整还原
+  - 导出 `ephemeralFilterRule` / `prepareContinue`（只要规则不要插件时可用）
+- `sendExisting(params, { mergeToEntry })` / `sendExistingStream(params, { mergeToEntry }, onProgress, onDone)`
+  —— "把结果并回指定消息"成为公开能力（兼容旧签名）
+
+### Changed（BREAKING）
+- **`new ChatService()` 不再自带续写与临时消息**：核心删除了 `continueLast` / `continueLastStream` / `_prepareContinue`，
+  `autoContinue` 步骤改为空实现，`MessageFormatter` 不再内置 ephemeral 过滤规则
+  → 需要这些能力的：`chat.use(createContinuationPlugin({ autoContinue: true }))`
+- `config.ephemeralContinue` 移除（`updateConfig` 白名单同步收窄）；改用插件选项 `autoContinue`
+- 消息"保留/丢弃"规则改为过滤器实现（行为与 v3.x 一致：ephemeral 底部连续、system 分流、空内容清理）
+
+### 迁移（从 3.x 升到 4.0）
+```js
+// 旧：什么都不用做，续写开箱可用
+// 新：一行装配
+import { createContinuationPlugin } from 'my-ai-chat-framework';
+chat.use(createContinuationPlugin({ autoContinue: true }));
+```
+
+## [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
@@ -106,7 +136,7 @@ const chat = new ChatService({
 ### Registering a Tool
 
 ```javascript
-chat.registerTool('get_weather', 'Get current weather for a city',
+chat.plugins['tool-calling'].registerTool('get_weather', 'Get current weather for a city',
   async (args) => {
     // args = { city: 'Beijing' }
     return `Weather in ${args.city}: 22°C, sunny`;
@@ -142,12 +172,31 @@ Converts internal messages to OpenAI‑compatible format. Supports:
 
 Detects `tool_calls` in assistant responses, executes registered tools, feeds results back, and continues the conversation (up to `maxIterations` = 5).
 
-- `chat.registerTool(name, description, executor, parameters?)` – register a tool
+- `chat.plugins['tool-calling'].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)
 
 ---
 
+## 🔧 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)`:
@@ -182,7 +231,7 @@ unsubscribe(); // stop listening
 | `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.plugins['tool-calling'].registerTool(name, desc, fn, params?)` | `this` | Register a tool (requires toolCallingPlugin) |
 | `chat.messages` | `MessageStore` | Access the message store directly |
 
 ---
@@ -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`).
 
 ---