my-ai-chat-framework 3.0.0 → 4.0.0

package/docs/DEVELOPER.md

@@ -111,13 +111,13 @@ chat.use(openaiAdapter);      // 无状态单例，配置从 chat.config 读取
 | `chat.stream(input, params?, onProgress, onDone)` | 流式发送。兼容旧签名 `stream(input, onProgress, onDone)`。AbortError 内部捕获 |
 | `chat.sendExisting(params?)` | 重发当前消息（不加用户消息）。AbortError 内部捕获 |
 | `chat.sendExistingStream(params?, onProgress, onDone)` | 流式重发。兼容旧签名。AbortError 内部捕获 |
-| `chat.continueLast()` | 前缀续写：从最后一条 assistant/ephemeral 续写并拼回原消息，续写后自动转正。AbortError 内部捕获，返回 target |
-| `chat.continueLastStream(onProgress, onDone)` | 流式前缀续写。AbortError 内部捕获，返回 target |
+| `chat.plugins['continuation'].continueLast()` | 前缀续写：从最后一条 assistant/ephemeral 续写并拼回原消息，续写后自动转正。AbortError 内部捕获，返回 target |
+| `chat.plugins['continuation'].continueLastStream(onProgress, onDone)` | 流式前缀续写。AbortError 内部捕获，返回 target |
 | `chat.abort()` | 中断当前请求，触发 `aborted` 事件 |
 | `chat.use(plugin, options?)` | 安装插件，options 透传给 `plugin.install(chat, options)` |
 | `chat.updateConfig(partial)` | 更新会话层配置（白名单+校验），触发 `config-updated` |
-| `chat.registerTool(name, desc, fn, params?)` | 注册工具（需 toolCallingPlugin） |
-| `chat.registerModel(name, caps)` | 注册/覆盖模型能力（需 modelRegistryPlugin） |
+| `chat.plugins['tool-calling'].registerTool(name, desc, fn, params?)` | 注册工具（需 toolCallingPlugin） |
+| `chat.plugins['model-registry'].registerModel(name, caps)` | 注册/覆盖模型能力（需 modelRegistryPlugin） |
 
 ### 属性
 
@@ -263,7 +263,7 @@ chat._hooks.on('beforeRequest', async ({ messages }) => {
 });
 
 // 续写后自动转正
-await chat.continueLast();
+await chat.plugins['continuation'].continueLast();
 // 该消息的 _ephemeral 已被清除，成为永久 assistant
 ```
 
@@ -322,7 +322,7 @@ console.log(MessageFormatter.listFormats()); // ['openai', 'anthropic']
 
 ## 前缀续写
 
-调用 `chat.continueLast()` 从最后一条 assistant 消息续写——
+调用 `chat.plugins['continuation'].continueLast()` 从最后一条 assistant 消息续写——
 模型直接从原内容末尾接续，结果拼回原消息（不新增消息）。
 
 > 部分服务商需 baseUrl 加 `/beta` 开启该功能（如 DeepSeek）。
@@ -330,11 +330,11 @@ console.log(MessageFormatter.listFormats()); // ['openai', 'anthropic']
 ```javascript
 // 中断后直接续写（流式标记 _complete 为 false）
 chat.abort();
-const msg = await chat.continueLast();
+const msg = await chat.plugins['continuation'].continueLast();
 // msg.content 已是原始 + 续写拼接，_complete 变为 true
 
 // 已完成的对话也可以续写（但通常没必要）
-await chat.continueLast();
+await chat.plugins['continuation'].continueLast();
 ```
 
 ---
@@ -423,7 +423,7 @@ chat.use(openaiAdapter);
 chat.use(modelRegistryPlugin);
 chat.use(toolCallingPlugin);
 
-chat.registerTool('get_weather', '查询天气', async (args) => {
+chat.plugins['tool-calling'].registerTool('get_weather', '查询天气', async (args) => {
   return `${args.city}: 22°C, 晴`;
 }, { city: { type: 'string', description: '城市', required: true } });
 
@@ -441,7 +441,7 @@ setTimeout(() => chat.abort(), 3000);
 await chat.stream('讲个长故事', ...);
 
 // 前缀续写（从最后一条 assistant 续写）
-await chat.continueLast();
+await chat.plugins['continuation'].continueLast();
 // 结果拼回原消息，不新增消息
 ```
 
@@ -477,3 +477,93 @@ chat.unpipe('角色卡注入');
 ```
 
 车间即"同级功能"：tool-calling / model-registry 本身现在就是车间（见 src/plugins/）。ctx 的全部字段见 ChatService.js 顶部 @typedef PipelineContext。
+
+---
+
+## 出口：替换 / 关闭内部步骤（v3.1）
+
+框架的 5 个内部步骤都能被替换、关闭、包装——"加功能只能改源码"成为历史。
+
+```js
+chat.internalStages   // ['prepareInput','beforeSend','autoContinue','buildRequest','send']
+
+// 1) 完全接管"发送"这一步（框架不再插手）
+chat.replaceStage('send', async (ctx) => {
+  ctx.result = await 我自己的发送逻辑(ctx.body);
+});
+
+// 2) 包一层：先做自己的事，再交回默认实现
+const 默认发送 = chat.getStage('send');
+chat.replaceStage('send', async (ctx) => { 记录日志(ctx); await 默认发送(ctx); });
+
+// 3) 彻底关掉某一步
+chat.unstage('autoContinue');
+
+// 4) 反悔
+chat.restoreStage('send');      // 恢复默认实现
+chat.restage('autoContinue');   // 重新启用
+```
+
+---
+
+## 临时消息：用业务规则实现（v4.0）
+
+> v4.0 起，**核心不认识 ephemeral（临时消息）与续写** —— 它们是玩法，住在 `src/plugins/continuation.js`。
+> 两条路，按需选。
+
+### 场景 A：不装插件 —— 一次性注入（最轻）
+
+```js
+// 让一段内容"只影响本次请求、不进历史"
+chat.pipe({
+  name: '临时引导',
+  phase: 'beforeSend',
+  run(ctx) { ctx.config.guideText = '接下来用三句话总结'; }
+});
+
+// 在你自己写的 adapter.buildRequest 里，把 config.guideText 变成请求里的一条消息
+```
+
+### 场景 B：装插件 —— 模拟思维链 / 前缀续写
+
+```js
+import { createContinuationPlugin } from 'my-ai-chat-framework';
+
+chat.use(createContinuationPlugin({ autoContinue: true }));
+
+// 1) 模拟思维链：注入临时引导，结果并回上一条 assistant，不留痕
+chat.messages.addOnceAssistant('（内心：他肯定又要熬夜）');
+await chat.stream('在吗');
+
+// 2) 前缀续写：让 AI 接着最后一条 assistant 往下写
+await chat.plugins['continuation'].continueLast();
+```
+
+### 插件到底装了什么（可整体卸载）
+
+| 装的东西 | 用到的机制 |
+|---|---|
+| 续写检测（`autoContinue` 步骤） | `chat.replaceStage('autoContinue', …)`（v3.1 出口） |
+| ephemeral 过滤规则 | `MessageFormatter.registerFilter('ephemeral', …)`（v4.0 过滤器注册点） |
+| `chat.plugins['continuation'].continueLast` / `chat.plugins['continuation'].continueLastStream` | 挂到实例上 |
+| `plugin.uninstall(chat)` | 全部还原（步骤 / 过滤器 / 方法） |
+
+### 只要规则、不要插件
+
+```js
+import { ephemeralFilterRule } from 'my-ai-chat-framework';
+MessageFormatter.registerFilter('ephemeral', ephemeralFilterRule, { priority: 100 });
+```
+
+### 自定义消息过滤（决定哪些消息进入请求）
+
+```js
+MessageFormatter.registerFilter('我的规则', (msg, { index, messages, capabilities }) => {
+  if (msg.metadata?.hidden) return null;      // 丢弃
+  return msg;                                  // 保留（也可返回改写后的新对象）
+}, { priority: 100 });                         // 数字越小越先执行
+
+MessageFormatter.listFilters();                // 查看当前过滤器链
+MessageFormatter.unregisterFilter('我的规则');  // 移除
+```
+

package/docs/README.md

@@ -0,0 +1,33 @@
+# 文档索引
+
+> 按"你现在想干什么"挑一份看。
+
+| 我想…… | 看这份 |
+|---|---|
+| **快速用起来**（抄代码） | [COOKBOOK.md](./COOKBOOK.md) —— 16 个常见任务配方 |
+| **查某个方法/事件/错误** | [API-REFERENCE.md](./API-REFERENCE.md) —— 完整 API 参考 |
+| **搞懂它为什么这么设计** | [ARCHITECTURE.md](./ARCHITECTURE.md) —— 架构、数据流、五种扩展方式 |
+| **确认哪些能改、哪些不能改** | [API-STABILITY.md](./API-STABILITY.md) —— 稳定性契约（Stable/Experimental/Internal） |
+| **理解"框架 vs 库"、责任边界** | [DESIGN-boundaries.md](./DESIGN-boundaries.md) —— 责任边界与出口缺口 |
+| **上手时的注意点 / 试用结论** | [FRAMEWORK-REVIEW.md](./FRAMEWORK-REVIEW.md) —— 试用报告（5 个易踩点） |
+| **发布到 npm** | [PUBLISHING.md](./PUBLISHING.md) —— 发布流程（含 2027 变化） |
+| **看还有什么没做** | [TODO.md](./TODO.md) —— 路线图与已知问题 |
+| **开发这个框架本身** | [DEVELOPER.md](./DEVELOPER.md) —— 扩展教程（写车间/出口/临时消息） |
+| **让 AI 帮你改这个仓库** | [../AGENTS.md](../AGENTS.md) · [../CLAUDE.md](../CLAUDE.md) —— 给 AI 的说明书 |
+
+## 推荐阅读顺序（第一次接触）
+
+1. 仓库根目录 [README_ZH.md](../README_ZH.md) —— 5 分钟了解是什么
+2. [COOKBOOK.md](./COOKBOOK.md) 的配方 1、3、4 —— 能跑起来、能流式、能注入角色卡
+3. [ARCHITECTURE.md](./ARCHITECTURE.md) 的第三节（生命周期）+ 第四节（五种扩展方式）
+4. [API-STABILITY.md](./API-STABILITY.md) —— 记住"只加不改"，然后放心写业务
+5. 剩下按需查
+
+## 可运行的示例
+
+| 文件 | 用途 |
+|---|---|
+| [../examples/selfcheck.js](../examples/selfcheck.js) | 无网络自检 21 项：`node examples/selfcheck.js` |
+| [../examples/demo.html](../examples/demo.html) | 浏览器真实对话（含车间开关、插件开关） |
+| [../tests/pipeline.test.js](../tests/pipeline.test.js) | **测试即文档**：36 个用例，每个演示一种用法 |
+| [../tests/core.test.js](../tests/core.test.js) | 48 个基础用例（存储/配置/适配器/过滤器） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-ai-chat-framework",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "A lightweight AI chat framework with plugin system, unified message format, and tool calling support.",
   "type": "module",
   "main": "dist/my-ai-chat-framework.node.cjs.js",

package/src/adapters/openai.js

@@ -5,7 +5,7 @@
 
 import { joinUrl } from "../utils/url.js";
 import { isString } from "../utils/typeCheck.js";
-import { APIError, NetworkError, ParsingError } from '../core/Errors.js';
+import { APIError, NetworkError, ParsingError, ConfigurationError } from '../core/Errors.js';
 import { MessageFormatter } from '../utils/MessageFormatter.js';
 
 // 属于"运输层"的配置键：工厂实例持有，请求时覆盖 config 中同名项
@@ -59,12 +59,13 @@ export const openaiAdapter = {
     config = this._resolveConfig(config);
     const model = config.model || config.modelParams?.model;
     if (!model) {
-      throw new Error('Missing required config: model (either at top level or in modelParams)');
+      throw new ConfigurationError('Missing required config: model (either at top level or in modelParams)');
     }
 
     const mp = config.modelParams || {};
-    const temperature = mp.temperature ?? config.temperature ?? 0.7;
-    const maxTokens = mp.maxTokens ?? config.maxTokens ?? 2000;
+    // v4.0：**不再提供默认值** —— 没传就不放进请求体，由 API 用自己的默认
+    const temperature = mp.temperature ?? config.temperature;
+    const maxTokens = mp.maxTokens ?? config.maxTokens;
     const reasoningEffort = mp.reasoningEffort ?? config.reasoningEffort;
 
     // 用 MessageFormatter 统一处理：system 置顶、消息过滤、字段映射、图片解析
@@ -80,11 +81,13 @@ export const openaiAdapter = {
     const requestBody = {
       model,
       messages: apiMessages,
-      temperature,
-      max_tokens: maxTokens,
       stream: false
     };
 
+    // v4.0：可选参数只在"显式传了"时才放进请求体（不替使用者决定要什么默认值）
+    if (temperature !== undefined) requestBody.temperature = temperature;
+    if (maxTokens !== undefined) requestBody.max_tokens = maxTokens;
+
     // 硬编码常用参数：驼峰命名，适配器负责转 API 格式
     if (mp.topP !== undefined) requestBody.top_p = mp.topP;
     if (mp.frequencyPenalty !== undefined) requestBody.frequency_penalty = mp.frequencyPenalty;
@@ -262,20 +265,37 @@ export const openaiAdapter = {
       const { done, value } = await reader.read();
       if (done) break;
       buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split(/\n\n/);
-      buffer = lines.pop();
 
-      for (const line of lines) {
-        const dataLine = line.replace(/^data: /, '').trim();
-        if (!dataLine) continue;
-        if (dataLine === '[DONE]') { reachedDone = true; break; }
+      // ===== v4.0：稳健的 SSE 事件解析 =====
+      // 支持：\r\n 换行、`data:`（无空格）、多行 data（按 SSE 规范用 \n 连接）、注释行
+      let sepMatch;
+      const EVENT_SEP = /\r?\n\r?\n/;
+      while ((sepMatch = EVENT_SEP.exec(buffer)) !== null) {
+        const rawEvent = buffer.slice(0, sepMatch.index);
+        buffer = buffer.slice(sepMatch.index + sepMatch[0].length);
+
+        const dataPayload = rawEvent
+          .split(/\r?\n/)
+          .filter(l => l.startsWith('data:'))
+          .map(l => l.slice(5).replace(/^ /, ''))
+          .join('\n');
+        if (!dataPayload) continue;
+        if (dataPayload.trim() === '[DONE]') { reachedDone = true; break; }
+
         try {
-          const chunk = JSON.parse(dataLine);
+          const chunk = JSON.parse(dataPayload);
           const delta = chunk.choices?.[0]?.delta;
           if (!delta) continue;
 
-          if (delta.content) accumulated.content += delta.content;
+          // v4.0：本次 chunk 的"增量"（onProgress 第二个参数）
+          const deltaInfo = { content: '', reasoningContent: '', toolCalls: null };
+
+          if (delta.content) {
+            accumulated.content += delta.content;
+            deltaInfo.content = delta.content;
+          }
           if (delta.tool_calls) {
+            const newCalls = [];
             if (!accumulated.toolCalls) accumulated.toolCalls = [];
             for (const toolCallDelta of delta.tool_calls) {
               const index = toolCallDelta.index;
@@ -294,16 +314,22 @@ export const openaiAdapter = {
               if (toolCallDelta.function?.arguments) {
                 accumulated.toolCalls[index].function.arguments += toolCallDelta.function.arguments;
               }
+              newCalls.push({ index, delta: toolCallDelta });
             }
+            deltaInfo.toolCalls = newCalls;
+          }
+          if (delta.reasoning_content) {
+            accumulated.reasoningContent += delta.reasoning_content;
+            deltaInfo.reasoningContent = delta.reasoning_content;
           }
-          if (delta.reasoning_content) accumulated.reasoningContent += delta.reasoning_content;
 
-          // 传出累积快照，ChatService 自行处理占位消息更新
-          onProgress({ ...accumulated });
+          // onProgress(snap, delta)：snap = 全量累积快照；delta = 本次新增片段
+          onProgress({ ...accumulated }, deltaInfo);
         } catch (e) {
-          console.warn('stream parsing failed :', e, dataLine);
+          console.warn('stream parsing failed :', e, dataPayload);
         }
       }
+      if (reachedDone) break;
     }
 
     const finalMessage = {