my-ai-chat-framework 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 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

package/README.md

@@ -136,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`;
@@ -172,7 +172,7 @@ 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)
 
@@ -231,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 |
 
 ---

package/README_ZH.md

@@ -17,6 +17,8 @@
 - **灵活配置** – 支持平铺和嵌套 `modelParams` 两种配置风格。
 - **事件驱动** – 内置 EventEmitter，支持 `message`、`sending`、`error`、`stream-progress` 事件。
 - **管道车间（v3.0）** – `chat.pipe()` 在任何阶段挂自定义功能（beforeSend/afterSend），核心代码不用改。
+- **出口 API（v4.0）** – `chat.replaceStage()` / `chat.unstage()`：内部 5 个步骤可替换、可关闭、可包装。
+- **玩法插件化（v4.0）** – 续写 / 临时消息住在 `continuation` 插件里（核心不含业务玩法）；`MessageFormatter.registerFilter()` 可自定义"哪些消息进请求"。
 - **类型化错误** – `APIError`、`NetworkError`、`ConfigurationError`、`ParsingError`，方便分类处理。
 
 ---
@@ -37,9 +39,10 @@ src/
 │   └── openai.js             # OpenAI 兼容 API 适配器（协议见 assertAdapter）
 ├── plugins/
 │   ├── tool-calling.js       # 工具调用插件（afterSend 车间，自动检测&循环执行）
-│   └── model-registry.js     # 模型能力表（beforeSend 车间）
+│   ├── model-registry.js     # 模型能力表（beforeSend 车间）
+│   └── continuation.js       # 续写 / 临时消息玩法（v4.0 从核心迁出，可整体卸载）
 └── utils/
-    ├── MessageFormatter.js   # 消息格式转换（可注册）
+    ├── MessageFormatter.js   # 消息格式转换 + 消息过滤器链（可注册）
     ├── typeCheck.js          # 类型判断工具
     └── url.js                # URL 拼接工具
 tests/                        # node:test 单元测试（core / pipeline / integration）
@@ -134,7 +137,7 @@ const chat = new ChatService({
 ### 注册工具
 
 ```javascript
-chat.registerTool('get_weather', '获取指定城市的天气',
+chat.plugins['tool-calling'].registerTool('get_weather', '获取指定城市的天气',
   async (args) => {
     // args = { city: '北京' }
     return `${args.city}天气：22°C，晴`;
@@ -170,7 +173,7 @@ await chat.send('北京今天天气怎么样？');
 
 检测助手响应中的 `tool_calls`，执行已注册的工具，将结果回传并继续对话（最多 `maxIterations` = 5 轮）。
 
-- `chat.registerTool(name, description, executor, parameters?)` – 注册工具
+- `chat.plugins['tool-calling'].registerTool(name, description, executor, parameters?)` – 注册工具
 - 自动向对话中插入 `role: 'tool'` 消息
 - 工具执行出错时优雅降级（记录日志，将错误信息返回给模型）
 - 配置：`createToolCallingPlugin({ timeout: 30000, maxIterations: 5 })`
@@ -213,7 +216,7 @@ unsubscribe(); // 停止监听
 | `chat.use(plugin)` | `this` | 安装插件/适配器 |
 | `chat.setAdapter(adapter)` | `void` | 手动设置适配器 |
 | `chat.on(event, handler)` | `取消订阅函数` | 订阅事件 |
-| `chat.registerTool(name, desc, fn, params?)` | `this` | 注册工具（需安装 toolCallingPlugin） |
+| `chat.plugins['tool-calling'].registerTool(name, desc, fn, params?)` | `this` | 注册工具（需安装 toolCallingPlugin） |
 | `chat.messages` | `MessageStore` | 直接访问消息存储 |
 
 ---
@@ -322,6 +325,20 @@ npm install
 # 开发模式（监听文件变化）
 npm run dev
 
+## 📚 文档
+
+| 我想…… | 看这份 |
+|---|---|
+| 快速抄代码上手 | [docs/COOKBOOK.md](./docs/COOKBOOK.md) —— 16 个常见任务配方 |
+| 查方法 / 事件 / 错误 | [docs/API-REFERENCE.md](./docs/API-REFERENCE.md) |
+| 搞懂设计 | [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) |
+| 确认哪些能改 | [docs/API-STABILITY.md](./docs/API-STABILITY.md)（**v4.0 起"只加不改"**） |
+| 全部文档索引 | [docs/README.md](./docs/README.md) |
+
+可运行示例：`node examples/selfcheck.js`（无网络自检 21 项）· 打开 `examples/demo.html`（浏览器真实对话）
+
+---
+
 ## 🧩 扩展：管道车间（v3.0）
 
 核心流程是一辆小车（ctx）依次开过车间；加新功能 = 注册一个车间，核心代码不用改。