my-ai-chat-framework 3.0.0 → 4.0.0

package/src/core/ChatService.js

@@ -1,7 +1,7 @@
 import { EventEmitter } from './EventEmitter.js';
 import { MessageStore } from './MessageStore.js';
 import { SystemPromptStore } from './SystemPromptStore.js';
-import { ConfigurationError, NetworkError } from './Errors.js';
+import { ConfigurationError, NetworkError, ValidationError } from './Errors.js';
 import { Pipeline } from './Pipeline.js';
 
 /**
@@ -38,19 +38,29 @@ import { Pipeline } from './Pipeline.js';
  */
 
 // updateConfig 白名单：会话层字段（运输层/请求默认参数归适配器，能力表归插件）
-const SESSION_CONFIG_KEYS = ['model', 'temperature', 'maxTokens', 'modelParams', 'system', 'retry', 'ephemeralContinue'];
+const SESSION_CONFIG_KEYS = ['model', 'temperature', 'maxTokens', 'modelParams', 'system', 'retry'];
+
+// 内部车间四步 + 发送（顺序即执行顺序）；v3.1 起每一步都可以被 replaceStage 顶替、被 unstage 关闭
+const INTERNAL_STAGES = ['prepareInput', 'beforeSend', 'autoContinue', 'buildRequest', 'send'];
 
 export class ChatService extends EventEmitter {
   constructor(config = {}) {
     super();
     this.config = { ...config };
-    this.messages = new MessageStore();
+    // v4.0（B3）：消息存储可注入 —— 想换成自定义 store（如将来支持对话树）不用改核心
+    if (config.store) {
+      if (typeof config.store.getAll !== 'function' || typeof config.store.add !== 'function') {
+        throw new ValidationError('store 必须实现 MessageStore 的接口（至少 getAll / add / update）');
+      }
+      this.messages = config.store;
+    } else {
+      this.messages = new MessageStore();
+    }
     this.systemPrompts = new SystemPromptStore();
     this._adapter = null;
-    this._abortController = null;
-    this._isGenerating = false;
-    this._hooks = new EventEmitter();
-    this._processResponse = null;
+    // v4.0（B1）：每个请求各自持有 AbortController —— 多请求互不干扰（工具循环里再发请求也安全）
+    this._activeRequests = new Map();   // requestId → AbortController
+    this._requestSeq = 0;
 
     const model = this.config.model || this.config.modelParams?.model;
     if (!model || typeof model !== 'string' || !model.trim()) {
@@ -68,6 +78,10 @@ export class ChatService extends EventEmitter {
 
     // ===== 内部管道（v3.0）：内部车间 + 用户车间（pipe 注册）按 phase 插入 =====
     this._userStages = [];
+    this._stageOverrides = new Map();   // v3.1 出口：内部步骤名 → 用户实现
+    this._disabledStages = new Set();   // v3.1 出口：被 unstage 关闭的内部步骤
+    this._extraConfigKeys = new Map();  // v4.0：插件注册的运行时可改字段 → 校验器（可空）
+    this.plugins = {};                  // v4.0（B4）：插件命名空间 —— 插件 API 挂在 chat.plugins.<插件名> 下，互不撞名
     this._pipeline = this._buildPipeline();
   }
 
@@ -92,8 +106,18 @@ export class ChatService extends EventEmitter {
     }
   }
 
+  /**
+   * 安装插件。
+   * - 插件实现 `install(chat, options)`
+   * - 若 install 返回一个对象，会挂到 **`chat.plugins[plugin.name]`**（v4.0 命名空间，插件之间不会撞名）
+   * - 插件要提供卸载时，自己在返回值里带 `uninstall()`（或调用 `plugin.uninstall(chat)`）
+   * @returns {ChatService} this
+   */
   use(plugin, options = {}) {
-    plugin.install(this, options);
+    const api = plugin.install(this, options);
+    if (plugin.name && api && typeof api === 'object') {
+      this.plugins[plugin.name] = api;
+    }
     return this;
   }
 
@@ -115,8 +139,7 @@ export class ChatService extends EventEmitter {
     if (typeof stage.name !== 'string' || !stage.name.trim()) {
       throw new ConfigurationError('pipe: 需要 name（车间名，非空字符串）');
     }
-    const INTERNAL = ['prepareInput', 'beforeSend', 'autoContinue', 'buildRequest', 'send'];
-    if (INTERNAL.includes(stage.name)) {
+    if (INTERNAL_STAGES.includes(stage.name)) {
       throw new ConfigurationError(`pipe: "${stage.name}" 是内部车间名，请换一个名字`);
     }
     if (this._userStages.some(s => s.name === stage.name)) {
@@ -141,19 +164,104 @@ export class ChatService extends EventEmitter {
     return this._pipeline.names();
   }
 
-  /** 重建内部管道：内部 5 车间 + 用户车间按 phase 插入 */
+  // ========== 出口 API（v3.1）：替换 / 关闭 内部步骤 ==========
+
+  /** 内部步骤名（顺序即执行顺序）：prepareInput / beforeSend / autoContinue / buildRequest / send */
+  get internalStages() {
+    return [...INTERNAL_STAGES];
+  }
+
+  /** 内部步骤的默认实现表 */
+  _defaultStageRuns() {
+    return {
+      prepareInput: (ctx) => this._stagePrepareInput(ctx),
+      beforeSend: (ctx) => this._stageBeforeSend(ctx),
+      autoContinue: (ctx) => this._stageAutoContinue(ctx),
+      buildRequest: (ctx) => this._stageBuildRequest(ctx),
+      send: (ctx) => this._stageSend(ctx),
+    };
+  }
+
+  /**
+   * 用你自己的实现**顶替**某个内部步骤。框架不再执行该步的默认行为。
+   * 例：`chat.replaceStage('send', async (ctx) => { ctx.result = await 我的发送(ctx.body) })`
+   * 想"包一层"默认实现：先 `const base = chat.getStage('send')`，再在自己的函数里调用它。
+   * @param {string} name 步骤名（见 internalStages）
+   * @param {Function} run (ctx) => void | Promise<void>
+   * @throws {ConfigurationError} 步骤名未知 / run 不是函数
+   */
+  replaceStage(name, run) {
+    if (!INTERNAL_STAGES.includes(name)) {
+      throw new ConfigurationError(`replaceStage: 未知的内部步骤 "${name}"。可选: ${INTERNAL_STAGES.join(', ')}`);
+    }
+    if (typeof run !== 'function') {
+      throw new ConfigurationError('replaceStage: 第二个参数必须是函数 (ctx) => void | Promise<void>');
+    }
+    this._stageOverrides.set(name, run);
+    this._rebuildPipeline();
+    return this;
+  }
+
+  /** 撤销替换，恢复该步骤的默认实现（不影响 unstage 的关闭状态） */
+  restoreStage(name) {
+    if (!INTERNAL_STAGES.includes(name)) {
+      throw new ConfigurationError(`restoreStage: 未知的内部步骤 "${name}"。可选: ${INTERNAL_STAGES.join(', ')}`);
+    }
+    this._stageOverrides.delete(name);
+    this._rebuildPipeline();
+    return this;
+  }
+
+  /**
+   * **关闭**某个内部步骤（从管道里移除，不再执行）。
+   * 例：`chat.unstage('autoContinue')` —— 彻底不要"自动续写检测"这一步。
+   * 警告：关闭 prepareInput / buildRequest / send 会让流程失去必要产物（如 ctx.body）。
+   */
+  unstage(name) {
+    if (!INTERNAL_STAGES.includes(name)) {
+      throw new ConfigurationError(`unstage: 未知的内部步骤 "${name}"。可选: ${INTERNAL_STAGES.join(', ')}`);
+    }
+    this._disabledStages.add(name);
+    this._rebuildPipeline();
+    return this;
+  }
+
+  /** 重新启用被 unstage 关闭的步骤 */
+  restage(name) {
+    if (!INTERNAL_STAGES.includes(name)) {
+      throw new ConfigurationError(`restage: 未知的内部步骤 "${name}"。可选: ${INTERNAL_STAGES.join(', ')}`);
+    }
+    this._disabledStages.delete(name);
+    this._rebuildPipeline();
+    return this;
+  }
+
+  /** 取得某个内部步骤的默认实现（用于"包一层"：做自己的事，再调用它） */
+  getStage(name) {
+    if (!INTERNAL_STAGES.includes(name)) {
+      throw new ConfigurationError(`getStage: 未知的内部步骤 "${name}"。可选: ${INTERNAL_STAGES.join(', ')}`);
+    }
+    return this._defaultStageRuns()[name];
+  }
+
+  /**
+   * 重建内部管道：内部步骤（可被 replaceStage 顶替 / 被 unstage 关闭）+ 用户车间按 phase 插入
+   * 顺序：prepareInput → beforeSend → [用户 beforeSend 车间] → autoContinue → buildRequest → send → [用户 afterSend 车间]
+   */
   _buildPipeline() {
     const p = new Pipeline();
-    p.register({ name: 'prepareInput', run: (ctx) => this._stagePrepareInput(ctx) });
-    p.register({ name: 'beforeSend', run: (ctx) => this._stageBeforeSend(ctx) });
-    for (const s of this._userStages) {
-      if (s.phase === 'beforeSend') p.register({ name: s.name, run: (ctx) => s.run(ctx) });
-    }
-    p.register({ name: 'autoContinue', run: (ctx) => this._stageAutoContinue(ctx) });
-    p.register({ name: 'buildRequest', run: (ctx) => this._stageBuildRequest(ctx) });
-    p.register({ name: 'send', run: (ctx) => this._stageSend(ctx) });
-    for (const s of this._userStages) {
-      if (s.phase === 'afterSend') p.register({ name: s.name, run: (ctx) => s.run(ctx) });
+    const defaults = this._defaultStageRuns();
+    const insertUsers = (phase) => {
+      for (const s of this._userStages) {
+        if (s.phase === phase) p.register({ name: s.name, run: (ctx) => s.run(ctx) });
+      }
+    };
+    for (const name of INTERNAL_STAGES) {
+      if (!this._disabledStages.has(name)) {
+        p.register({ name, run: this._stageOverrides.get(name) || defaults[name] });
+      }
+      if (name === 'beforeSend') insertUsers('beforeSend');
+      if (name === 'send') insertUsers('afterSend');
     }
     return p;
   }
@@ -167,95 +275,100 @@ export class ChatService extends EventEmitter {
     this._adapter = adapter;
   }
 
-  abort() {
-    if (this._abortController) {
-      this._abortController.abort();
+  /**
+   * 中断请求（v4.0：按请求隔离）。
+   * - 不传参数：中断**所有**活跃请求（旧版只会中断"最后一个"，多请求时会中断错的那个）
+   * - 传 requestId：只中断那一个（id 见 `chat.activeRequests`）
+   */
+  abort(requestId) {
+    if (requestId) {
+      const controller = this._activeRequests.get(requestId);
+      if (controller) controller.abort();
+      return;
     }
+    for (const controller of this._activeRequests.values()) controller.abort();
   }
 
-  get isGenerating() { return this._isGenerating; }
+  /** 是否有请求正在生成中 */
+  get isGenerating() { return this._activeRequests.size > 0; }
 
-  async continueLast() {
-    const target = this._prepareContinue();
-    this.messages.update(target.id, { prefix: true });
-    try {
-      await this._request({ addUser: false, isStream: false, mergeToEntry: target.id });
-      this.messages.update(target.id, {
-        _complete: true, prefix: undefined, _ephemeral: false
-      });
-      return target;
-    } catch (err) {
-      this.messages.update(target.id, {
-        _complete: true, prefix: undefined, _ephemeral: false
-      });
-      if (err.name === 'AbortError') {
-        this.emit('aborted', { timestamp: Date.now() });
-        return target;
-      }
-      throw err;
-    }
+  /** 当前活跃请求的 id 列表（调试 / 精确中断用） */
+  get activeRequests() { return [...this._activeRequests.keys()]; }
+
+  /** 内部：登记一个请求，返回 { id, signal } */
+  _beginRequest() {
+    const id = 'req_' + (++this._requestSeq);
+    const controller = new AbortController();
+    this._activeRequests.set(id, controller);
+    return { id, signal: controller.signal };
   }
 
-  async continueLastStream(onProgress, onDone) {
-    const target = this._prepareContinue();
-    this.messages.update(target.id, { prefix: true });
-    const baseLen = (target.content || '').length;
+  /** 内部：注销一个请求 */
+  _endRequest(id) {
+    this._activeRequests.delete(id);
+  }
 
-    try {
-      await this._request({
-        addUser: false, isStream: true, mergeToEntry: target.id,
-        onProgress: (chunk) => {
-          if (onProgress) {
-            onProgress({ ...chunk, content: (chunk.content || '').slice(baseLen) });
-          }
-        },
-        onDone: (final) => { if (onDone) onDone(final); }
-      });
-      this.messages.update(target.id, {
-        _complete: true, prefix: undefined, _ephemeral: false
-      });
-      return target;
-    } catch (err) {
-      // 保留已累积的内容，标记完成
-      this.messages.update(target.id, {
-        _complete: true, prefix: undefined, _ephemeral: false
-      });
-      // abort 是用户主动行为，静默处理，通知外部
-      if (err.name === 'AbortError') {
-        this.emit('aborted', { timestamp: Date.now() });
-        return target;
+  // 注（v4.0）：continueLast / continueLastStream / _prepareContinue 已迁出核心。
+  // 续写是「玩法」，由 src/plugins/continuation.js 提供 —— chat.use(createContinuationPlugin())。
+
+  /**
+   * 注册"运行时可改的配置字段"（v4.0）。
+   * 让插件自带配置（如 continuation 的 autoContinue）不必回头改核心白名单。
+   * @param {string[]|Object<string, Function>} keys 字段名数组，或 { 字段名: 校验器(value)=>boolean }
+   * @returns {ChatService} this
+   * @throws {ConfigurationError} 字段名非法 / 校验器不是函数
+   */
+  registerConfigKeys(keys) {
+    const entries = Array.isArray(keys) ? keys.map(k => [k, null]) : Object.entries(keys || {});
+    for (const [key, validator] of entries) {
+      if (typeof key !== 'string' || !key.trim()) {
+        throw new ConfigurationError('registerConfigKeys: 字段名必须是非空字符串');
       }
-      throw err;
+      if (validator != null && typeof validator !== 'function') {
+        throw new ConfigurationError(`registerConfigKeys: "${key}" 的校验器必须是函数`);
+      }
+      this._extraConfigKeys.set(key.trim(), validator || null);
     }
+    return this;
   }
 
-  _prepareContinue() {
-    const msgs = this.messages.getAll();
-    const last = msgs[msgs.length - 1];
-    if (last && (last.role === 'assistant' || last._ephemeral)) return last;
-    throw new Error('最后一条消息不是 assistant，无法续写');
+  /** 注销运行时可改字段（插件卸载时调用）@returns {ChatService} this */
+  unregisterConfigKeys(keys) {
+    for (const k of (Array.isArray(keys) ? keys : [keys])) this._extraConfigKeys.delete(k);
+    return this;
+  }
+
+  /** 当前允许在运行时修改的配置字段（内置基础字段 + 插件注册） */
+  get configKeys() {
+    return [...SESSION_CONFIG_KEYS, ...this._extraConfigKeys.keys()];
   }
 
   /**
-   * 运行时修改配置（仅会话层字段）。
+   * 运行时修改配置（仅"可改字段"：内置基础字段 + 插件注册字段）。
    *
-   * 白名单：model / temperature / maxTokens / modelParams / system / retry / ephemeralContinue。
    * - 运输层（apiKey/baseUrl/headers）：归适配器，要改就换适配器实例
    * - 请求参数默认值：走适配器工厂 options 或请求级覆盖（chat.send(x, params)）
-   * - 能力表：归 modelRegistry 插件
+   * - 插件自有配置：插件用 `registerConfigKeys` 登记后才可改（工厂 options 仍是首选）
    *
    * 与构造器一样经过校验，不能注入非法值。
-   * @throws {ConfigurationError} 非白名单字段或非法值
+   * @throws {ConfigurationError} 非白名单字段、非法值、或插件校验器拒绝
    */
   updateConfig(partial) {
+    const allowed = this.configKeys;
     for (const key of Object.keys(partial)) {
-      if (!SESSION_CONFIG_KEYS.includes(key)) {
+      if (!allowed.includes(key)) {
         throw new ConfigurationError(
-          `updateConfig 不支持修改 "${key}"。允许的会话层字段: ${SESSION_CONFIG_KEYS.join(', ')}`
+          `updateConfig 不支持修改 "${key}"。允许的字段: ${allowed.join(', ')}`
         );
       }
     }
     this._assertValidConfig(partial);
+    // 插件注册字段的校验（校验器返回 false 即拒绝）
+    for (const [key, validator] of this._extraConfigKeys) {
+      if (validator && key in partial && validator(partial[key]) === false) {
+        throw new ConfigurationError(`updateConfig: 字段 "${key}" 的值不合法: ${JSON.stringify(partial[key])}`);
+      }
+    }
     Object.assign(this.config, partial);
     if (typeof partial.system === 'string') this.systemPrompts.set(partial.system);
     this.emit('config-updated', { changes: partial, timestamp: Date.now() });
@@ -314,6 +427,7 @@ export class ChatService extends EventEmitter {
       onProgress: options.onProgress || null,
       onDone: options.onDone || null,
       mergeToEntry: options.mergeToEntry || null,
+      signal: options.signal || null,     // v4.0（B1）：本请求自己的中断信号
       body: null,
       result: null,
     };
@@ -333,29 +447,28 @@ export class ChatService extends EventEmitter {
   /** 车间 1：加用户消息 → 合并请求参数 → 广播 sending */
   async _stagePrepareInput(ctx) {
     this._addUserMessage(ctx.userInput, ctx.addUser);
-    // 合并请求参数：先于 beforeRequest 钩子，钩子拿到的是本次生效的配置
+    // 合并请求参数（合并后的 ctx.config 供后续车间使用）
     ctx.config = this._mergeRequestConfig(ctx.options.params);
     this.emit('sending', { addUser: ctx.addUser, userInput: ctx.userInput, timestamp: Date.now() });
   }
 
-  /** 车间 2：发送前钩子（兼容桥：事件钩子照发；阶段 4 会迁到 beforeSend 公开位置） */
+  /**
+   * 车间 2：发送前 —— **v4.0 起默认什么都不做**。
+   * 需要在这里做事的（注入、改写消息/配置）：`chat.replaceStage('beforeSend', fn)`
+   * 或挂一个 `chat.pipe({ phase: 'beforeSend' })` 车间（在它之后执行）。
+   * 旧的 `_hooks.on('beforeRequest')` 兼容桥已于 v4.0 移除。
+   */
   async _stageBeforeSend(ctx) {
-    await this._hooks.emitAsync('beforeRequest', {
-      messages: ctx.messages,
-      config: ctx.config,
-      options: ctx.options
-    });
+    // 默认空实现（no-op）
   }
 
-  /** 车间 3：自动续写检测（ephemeralContinue 时，底部若有 prefix 消息则续写） */
+  /**
+   * 车间 3：自动续写检测 —— **v4.0 起默认什么都不做**。
+   * 续写是玩法：需要它的装上 continuation 插件，由插件 replaceStage('autoContinue', ...) 接管。
+   * 步骤名与位置保留，方便插件替换、也方便使用者 `unstage('autoContinue')` 明确移除。
+   */
   async _stageAutoContinue(ctx) {
-    if (this.config.ephemeralContinue && !ctx.mergeToEntry) {
-      const msgs = ctx.messages.getAll();
-      const last = msgs[msgs.length - 1];
-      if (last && last.prefix && (last.role === 'assistant' || last._ephemeral)) {
-        ctx.mergeToEntry = last.id;
-      }
-    }
+    // 默认空实现（no-op）
   }
 
   /** 车间 4：构建请求体 */
@@ -375,7 +488,8 @@ export class ChatService extends EventEmitter {
       mergeToEntry: ctx.mergeToEntry,
       config: ctx.config,
       maxRetries: retryCfg.maxRetries ?? 0,
-      retryDelay: retryCfg.retryDelay ?? 1000
+      retryDelay: retryCfg.retryDelay ?? 1000,
+      signal: ctx.signal
     });
   }
 
@@ -389,9 +503,10 @@ export class ChatService extends EventEmitter {
   }
 
   /** retry 循环，占位消息只 push 一次 */
-  async _withRetry(body, { isStream, onProgress, onDone, mergeToEntry, config, maxRetries, retryDelay }) {
+  async _withRetry(body, { isStream, onProgress, onDone, mergeToEntry, config, maxRetries, retryDelay, signal }) {
     let lastError = null;
-    const adapterOptions = { signal: this._abortController?.signal };
+    // v4.0（B1）：使用"本请求自己的"信号（不再读写共享的 this._abortController）
+    const adapterOptions = { signal };
 
     let placeholder = null;
     let base = null;
@@ -411,28 +526,22 @@ export class ChatService extends EventEmitter {
         await new Promise(r => setTimeout(r, retryDelay));
       }
       try {
-        this._isGenerating = true;
         if (isStream) {
           return await this._stream(body, adapterOptions, { placeholder, base, mergeToEntry, onProgress, onDone, config });
         } else {
           const resp = await this._adapter.send(body, config, adapterOptions);
-          let result = this._handleResult(this._adapter.parseResponse(resp), mergeToEntry);
-          // 响应后处理钩子（tool-calling 用），仅非续写时
-          if (this._processResponse && !mergeToEntry) {
-            result = await this._processResponse(result, { isStream: false });
-          }
-          return result;
+          // 响应落位后交给管道：afterSend 车间接管后续处理（如工具调用循环）
+          return this._handleResult(this._adapter.parseResponse(resp), mergeToEntry);
         }
       } catch (error) {
         lastError = error;
-        if (error.name === 'AbortError' || this._abortController?.signal.aborted) {
-          this._isGenerating = false; throw error;
+        if (error.name === 'AbortError' || signal?.aborted) {
+          throw error;
         }
         if (error instanceof NetworkError && attempt < maxRetries) continue;
-        this._isGenerating = false; throw error;
+        throw error;
       }
     }
-    this._isGenerating = false;
     throw lastError;
   }
 
@@ -451,7 +560,8 @@ export class ChatService extends EventEmitter {
 
     await this._adapter.stream(body, config,
       // === onProgress：每收到一个 SSE chunk 触发 ===
-      (snap) => {
+      // snap = 全量累积快照；delta = 本次新增片段（v4.0 起两个都给你）
+      (snap, delta) => {
         // snap.content 是 adapter 累积的全部 API 新内容（不是增量）
         // 续写时：base.content（旧内容）+ snap.content（API 新内容）= 完整内容
         // 普通发送时：直接用 snap.content
@@ -466,19 +576,12 @@ export class ChatService extends EventEmitter {
         }
         if (snap.toolCalls) placeholder.toolCalls = [...snap.toolCalls];
         this.emit('stream-progress', snap);
-        if (onProgress) onProgress(snap);
+        if (onProgress) onProgress(snap, delta);   // v4.0：第二个参数是本次增量
       },
       // === onDone：流结束，做最终落位 ===
       async (final) => {
         finalMsg = final;
 
-        // 工具调用钩子（仅普通发送时，续写不走 tool-calling 循环）
-        if (this._processResponse && !mergeToEntry) {
-          finalMsg = await this._processResponse(finalMsg, {
-            isStream: true, onProgress, onDone
-          });
-        }
-
         if (mergeToEntry && base) {
           // 续写：把 base + 最终内容写回 target，标记完成
           const newContent = base.content + (final.content || '');
@@ -539,9 +642,9 @@ export class ChatService extends EventEmitter {
    * @param {Object} [params] - 请求级参数覆盖（model/temperature/modelParams 等，仅本次生效）
    */
   async send(userInput, params) {
-    this._abortController = new AbortController();
+    const { id, signal } = this._beginRequest();
     try {
-      return await this._request({ userInput, addUser: true, isStream: false, params });
+      return await this._request({ userInput, addUser: true, isStream: false, params, signal });
     } catch (err) {
       if (err.name === 'AbortError') {
         this.emit('aborted', { timestamp: Date.now() });
@@ -549,8 +652,7 @@ export class ChatService extends EventEmitter {
       }
       throw err;
     } finally {
-      this._abortController = null;
-      this._isGenerating = false;
+      this._endRequest(id);
     }
   }
 
@@ -568,9 +670,9 @@ export class ChatService extends EventEmitter {
       onProgress = params;
       params = undefined;
     }
-    this._abortController = new AbortController();
+    const { id, signal } = this._beginRequest();
     try {
-      return await this._request({ userInput, addUser: true, isStream: true, onProgress, onDone, params });
+      return await this._request({ userInput, addUser: true, isStream: true, onProgress, onDone, params, signal });
     } catch (err) {
       if (err.name === 'AbortError') {
         this.emit('aborted', { timestamp: Date.now() });
@@ -578,19 +680,20 @@ export class ChatService extends EventEmitter {
       }
       throw err;
     } finally {
-      this._abortController = null;
-      this._isGenerating = false;
+      this._endRequest(id);
     }
   }
 
   /**
    * 重发当前消息（不加用户消息）。
    * @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+   * @param {Object} [options] - { mergeToEntry } 可选：把结果合并进指定的已有消息（续写等场景）
    */
-  async sendExisting(params) {
-    this._abortController = new AbortController();
+  async sendExisting(params, options = {}) {
+    const mergeToEntry = options?.mergeToEntry || null;
+    const { id, signal } = this._beginRequest();
     try {
-      return await this._request({ addUser: false, isStream: false, params });
+      return await this._request({ addUser: false, isStream: false, params, mergeToEntry, signal });
     } catch (err) {
       if (err.name === 'AbortError') {
         this.emit('aborted', { timestamp: Date.now() });
@@ -598,27 +701,34 @@ export class ChatService extends EventEmitter {
       }
       throw err;
     } finally {
-      this._abortController = null;
-      this._isGenerating = false;
+      this._endRequest(id);
     }
   }
 
   /**
    * 流式重发（不加用户消息）。
    * @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+   * @param {Object} [options] - { mergeToEntry } 可选：把结果合并进指定的已有消息
    * @param {Function} [onProgress] - 流式进度回调
    * @param {Function} [onDone] - 流式完成回调
    */
-  async sendExistingStream(params, onProgress, onDone) {
-    // 兼容旧签名 sendExistingStream(onProgress, onDone)
+  async sendExistingStream(params, options, onProgress, onDone) {
+    // 兼容签名1：sendExistingStream(onProgress, onDone)
     if (typeof params === 'function') {
-      onDone = onProgress;
+      onDone = options;
       onProgress = params;
+      options = {};
       params = undefined;
+    } else if (typeof options === 'function') {
+      // 兼容签名2：sendExistingStream(params, onProgress, onDone)
+      onDone = onProgress;
+      onProgress = options;
+      options = {};
     }
-    this._abortController = new AbortController();
+    const mergeToEntry = options?.mergeToEntry || null;
+    const { id, signal } = this._beginRequest();
     try {
-      return await this._request({ addUser: false, isStream: true, onProgress, onDone, params });
+      return await this._request({ addUser: false, isStream: true, onProgress, onDone, params, mergeToEntry, signal });
     } catch (err) {
       if (err.name === 'AbortError') {
         this.emit('aborted', { timestamp: Date.now() });
@@ -626,8 +736,7 @@ export class ChatService extends EventEmitter {
       }
       throw err;
     } finally {
-      this._abortController = null;
-      this._isGenerating = false;
+      this._endRequest(id);
     }
   }
 }

package/src/core/Errors.js

@@ -44,6 +44,19 @@ export class ConfigurationError extends Error {
   }
 }
 
+// 校验错误 （传参非法、索引越界、调用前提不满足等 —— 使用者传错了东西）
+// 继承 ConfigurationError：老的 `catch (e) { if (e instanceof ConfigurationError) }` 仍然命中，
+// 需要精细区分时用 `instanceof ValidationError`。
+export class ValidationError extends ConfigurationError {
+  /**
+   * @param {string} message - 错误消息
+   */
+  constructor(message) {
+    super(message)
+    this.name = 'ValidationError'
+  }
+}
+
 // 解析错误 （解析 API 响应失败、响应格式不正确，不符合预期等）
 export class ParsingError extends Error {
   /**