my-ai-chat-framework 2.0.0 → 3.0.0

package/src/core/ChatService.js

@@ -1,110 +1,652 @@
-import { EventEmitter } from './EventEmitter.js';
-import { MessageStore } from './MessageStore.js';
-
-/**
- * 核心聊天服务
- * 极简设计：只负责消息存储、事件发射、插件管理、请求委托
- */
-export class ChatService extends EventEmitter {
-  constructor(config = {}) {
-    super();
-    this.config = {
-      apiKey: config.apiKey || '',
-      model: config.model || 'gpt-3.5-turbo',
-      ...config
-    };
-    this.messages = new MessageStore();
-    this._plugins = [];
-    this._adapter = null;      // 当前使用的 API 适配器
-    this._pendingRequest = null;
-  }
-
-  /**
-   * 加载插件
-   * @param {object} plugin - 必须包含 install 方法
-   */
-  use(plugin) {
-    if (typeof plugin.install === 'function') {
-      plugin.install(this);
-      this._plugins.push(plugin);
-    } else {
-      throw new Error('插件必须提供 install 方法');
-    }
-    return this;
-  }
-
-  /**
-   * 设置 API 适配器
-   */
-  setAdapter(adapter) {
-    this._adapter = adapter;
-    return this;
-  }
-
-  /**
-   * 发送消息（非流式）
-   * @param {string|object} input - 字符串或消息对象
-   */
-  async send(input) {
-    const userMsg = typeof input === 'string'
-      ? { role: 'user', content: input }
-      : { role: 'user', ...input };
-
-    this.messages.add(userMsg);
-    this.emit('sending', userMsg);
-
-    // 构建请求
-    const requestBody = this._adapter.buildRequest(this.messages.getAll(), this.config);
-    const response = await this._adapter.send(requestBody, this.config);
-    const assistantMsg = this._adapter.parseResponse(response);
-
-    this.messages.add(assistantMsg);
-    this.emit('message', assistantMsg);
-    return assistantMsg;
-  }
-
-  /**
-   * 流式发送消息
-   * @param {string|object} input
-   * @param {function} onProgress - 每次收到数据块时调用，参数为累积的当前消息对象
-   * @param {function} onDone - 完成时调用，参数为最终消息对象
-   */
-  async stream(input, onProgress, onDone) {
-    const userMsg = typeof input === 'string'
-      ? { role: 'user', content: input }
-      : { role: 'user', ...input };
-
-    this.messages.add(userMsg);
-    this.emit('sending', userMsg);
-
-    const requestBody = this._adapter.buildRequest(this.messages.getAll(), this.config);
-
-    let accumulated = { role: 'assistant', content: '' };
-    await this._adapter.stream(
-      requestBody,
-      this.config,
-      (chunk) => {
-        // 累积消息
-        if (chunk.content) accumulated.content += chunk.content;
-        if (chunk.toolCalls) accumulated.toolCalls = chunk.toolCalls;
-        if (chunk.reasoningContent) accumulated.reasoningContent = chunk.reasoningContent;
-        // 触发进度事件
-        this.emit('stream-progress', { ...accumulated });
-        if (onProgress) onProgress({ ...accumulated });
-      },
-      (finalMessage) => {
-        this.messages.add(finalMessage);
-        this.emit('message', finalMessage);
-        if (onDone) onDone(finalMessage);
-      }
-    );
-  }
-
-  /**
-   * 注册工具（由工具调用插件实现）
-   * 这里只留一个空方法，插件会覆盖它
-   */
-  registerTool(name, description, executor) {
-    throw new Error('工具调用插件未加载，请先使用 use(toolCallingPlugin)');
-  }
-}
+import { EventEmitter } from './EventEmitter.js';
+import { MessageStore } from './MessageStore.js';
+import { SystemPromptStore } from './SystemPromptStore.js';
+import { ConfigurationError, NetworkError } from './Errors.js';
+import { Pipeline } from './Pipeline.js';
+
+/**
+ * @typedef {Object} ChatAdapter 适配器协议（v3.0：写同级适配器只需实现这 4+1 个方法）
+ * @property {Function} buildRequest  (messages, config, systemPrompts) => requestBody
+ * @property {Function} send          (body, config, opts) => Promise<apiResponse>
+ * @property {Function} stream        (body, config, onProgress, onDone, opts) => Promise<void>
+ * @property {Function} parseResponse (apiResponse) => assistantMessage
+ * @property {Function} [getRequestDefaults] () => 默认请求参数（可选）
+ * @property {Function} [install]     (chatService, options) 插件式安装（可选）
+ */
+
+/**
+ * @typedef {Object} PipelineContext 管道小车 ctx（public pipe 车间可见/可改的全部字段）
+ * @property {Object}   options       原始请求选项
+ * @property {*}        userInput     用户输入（可为 undefined）
+ * @property {boolean}  addUser       是否已新增/将新增用户消息
+ * @property {MessageStore} messages  消息列表（可读可改：push / unshift / update）
+ * @property {SystemPromptStore} systemPrompts 系统提示词（可读可改）
+ * @property {Object}   config        合并后的请求级配置（prepareInput 后生效）
+ * @property {boolean}  isStream      本次是否流式
+ * @property {Function|null} onProgress 流式进度回调
+ * @property {Function|null} onDone     流式完成回调
+ * @property {string|null} mergeToEntry 续写目标 id（null = 普通发送）
+ * @property {*}        body          请求体（buildRequest 后产出）
+ * @property {*}        result        最终结果（send 后产出）
+ */
+
+/**
+ * @typedef {Object} PipeStage 车间（v3.0 公开扩展单元）
+ * @property {string}   name      车间名（唯一，不能与内部车间重名）
+ * @property {string}   [phase]   'beforeSend'（默认）| 'afterSend'
+ * @property {Function} run       (ctx: PipelineContext) => void | Promise<void>
+ */
+
+// updateConfig 白名单：会话层字段（运输层/请求默认参数归适配器，能力表归插件）
+const SESSION_CONFIG_KEYS = ['model', 'temperature', 'maxTokens', 'modelParams', 'system', 'retry', 'ephemeralContinue'];
+
+export class ChatService extends EventEmitter {
+  constructor(config = {}) {
+    super();
+    this.config = { ...config };
+    this.messages = new MessageStore();
+    this.systemPrompts = new SystemPromptStore();
+    this._adapter = null;
+    this._abortController = null;
+    this._isGenerating = false;
+    this._hooks = new EventEmitter();
+    this._processResponse = null;
+
+    const model = this.config.model || this.config.modelParams?.model;
+    if (!model || typeof model !== 'string' || !model.trim()) {
+      throw new ConfigurationError('缺少 model 配置');
+    }
+
+    this._assertValidConfig(this.config);
+
+    if (typeof config.system === 'string' && config.system.trim()) {
+      this.systemPrompts.set(config.system);
+    }
+    if (config.adapter) {
+      this.setAdapter(config.adapter);
+    }
+
+    // ===== 内部管道（v3.0）：内部车间 + 用户车间（pipe 注册）按 phase 插入 =====
+    this._userStages = [];
+    this._pipeline = this._buildPipeline();
+  }
+
+  /**
+   * 校验配置中的可校验字段（model 必填由构造器负责，这里只校验存在性）
+   * @throws {ConfigurationError}
+   */
+  _assertValidConfig(cfg) {
+    const temperature = cfg.modelParams?.temperature ?? cfg.temperature;
+    if (temperature !== undefined && (typeof temperature !== 'number' || temperature < 0 || temperature > 2)) {
+      throw new ConfigurationError(`temperature 必须在 0-2 之间，当前值: ${temperature}`);
+    }
+
+    const maxTokens = cfg.modelParams?.maxTokens ?? cfg.maxTokens;
+    if (maxTokens !== undefined && (typeof maxTokens !== 'number' || maxTokens < 1 || !Number.isInteger(maxTokens))) {
+      throw new ConfigurationError(`maxTokens 必须为正整数，当前值: ${maxTokens}`);
+    }
+
+    const model = cfg.model ?? cfg.modelParams?.model;
+    if (model !== undefined && (typeof model !== 'string' || !model.trim())) {
+      throw new ConfigurationError('model 必须是非空字符串');
+    }
+  }
+
+  use(plugin, options = {}) {
+    plugin.install(this, options);
+    return this;
+  }
+
+  // ========== 公开管道 API（v3.0 · 阶段 2）==========
+
+  /**
+   * 往请求管道里挂一个"车间"。
+   * - phase 'beforeSend'（默认）：在内部 beforeRequest 钩子之后、构建请求体之前执行
+   * - phase 'afterSend'  ：在内部发送（流式/非流式）完成、结果落位之后执行（可改 ctx.result）
+   * 不注册任何车间 = 行为与版本 2.8.x 完全一致。
+   * @param {PipeStage} stage
+   * @returns {ChatService} this
+   * @throws {ConfigurationError} 参数非法 / 名字被占用 / 与内部车间重名
+   */
+  pipe(stage) {
+    if (!stage || typeof stage !== 'object' || typeof stage.run !== 'function') {
+      throw new ConfigurationError('pipe: 需要 { name, phase?, run(ctx) }，run 必须是函数');
+    }
+    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)) {
+      throw new ConfigurationError(`pipe: "${stage.name}" 是内部车间名，请换一个名字`);
+    }
+    if (this._userStages.some(s => s.name === stage.name)) {
+      throw new ConfigurationError(`pipe: 车间 "${stage.name}" 已存在，请先 chat.unpipe("${stage.name}")`);
+    }
+    const phase = stage.phase === 'afterSend' ? 'afterSend' : 'beforeSend';
+    this._userStages.push({ name: stage.name, phase, run: stage.run });
+    this._rebuildPipeline();
+    return this;
+  }
+
+  /** 移除一个用户车间（移除不存在的名字是安全的）。@returns {ChatService} this */
+  unpipe(name) {
+    const before = this._userStages.length;
+    this._userStages = this._userStages.filter(s => s.name !== name);
+    if (this._userStages.length !== before) this._rebuildPipeline();
+    return this;
+  }
+
+  /** 查看当前管道里所有车间名（调试/说明用，含内部车间） */
+  get pipelineStages() {
+    return this._pipeline.names();
+  }
+
+  /** 重建内部管道：内部 5 车间 + 用户车间按 phase 插入 */
+  _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) });
+    }
+    return p;
+  }
+
+  _rebuildPipeline() {
+    this._pipeline = this._buildPipeline();
+  }
+
+  setAdapter(adapter) {
+    assertAdapter(adapter);
+    this._adapter = adapter;
+  }
+
+  abort() {
+    if (this._abortController) {
+      this._abortController.abort();
+    }
+  }
+
+  get isGenerating() { return this._isGenerating; }
+
+  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;
+    }
+  }
+
+  async continueLastStream(onProgress, onDone) {
+    const target = this._prepareContinue();
+    this.messages.update(target.id, { prefix: true });
+    const baseLen = (target.content || '').length;
+
+    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;
+      }
+      throw err;
+    }
+  }
+
+  _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，无法续写');
+  }
+
+  /**
+   * 运行时修改配置（仅会话层字段）。
+   *
+   * 白名单：model / temperature / maxTokens / modelParams / system / retry / ephemeralContinue。
+   * - 运输层（apiKey/baseUrl/headers）：归适配器，要改就换适配器实例
+   * - 请求参数默认值：走适配器工厂 options 或请求级覆盖（chat.send(x, params)）
+   * - 能力表：归 modelRegistry 插件
+   *
+   * 与构造器一样经过校验，不能注入非法值。
+   * @throws {ConfigurationError} 非白名单字段或非法值
+   */
+  updateConfig(partial) {
+    for (const key of Object.keys(partial)) {
+      if (!SESSION_CONFIG_KEYS.includes(key)) {
+        throw new ConfigurationError(
+          `updateConfig 不支持修改 "${key}"。允许的会话层字段: ${SESSION_CONFIG_KEYS.join(', ')}`
+        );
+      }
+    }
+    this._assertValidConfig(partial);
+    Object.assign(this.config, partial);
+    if (typeof partial.system === 'string') this.systemPrompts.set(partial.system);
+    this.emit('config-updated', { changes: partial, timestamp: Date.now() });
+  }
+
+  // ========== 编排角色 ==========
+
+  /**
+   * 合并请求参数（近者优先）：
+   *   适配器默认(getRequestDefaults) ← 会话配置(this.config) ← 本次覆盖(params)
+   * modelParams 深层合并；平铺便捷键（temperature/maxTokens/reasoningEffort）自动折叠进 modelParams
+   */
+  _mergeRequestConfig(params = {}) {
+    const adapterDefaults = this._adapter?.getRequestDefaults?.() || {};
+    const requestConfig = { ...adapterDefaults, ...this.config, ...params };
+    const modelParams = {
+      ...(adapterDefaults.modelParams || {}),
+      ...(this.config.modelParams || {}),
+      ...(params.modelParams || {})
+    };
+    for (const key of ['temperature', 'maxTokens', 'reasoningEffort']) {
+      const value = params[key] ?? this.config[key] ?? adapterDefaults[key];
+      if (value !== undefined) modelParams[key] = value;
+    }
+    requestConfig.modelParams = modelParams;
+    return requestConfig;
+  }
+
+  /**
+   * 内部调度（v3.0 提案 · 阶段 1）：造一辆小车 ctx，开过内部管道，返回结果。
+   * 行为与旧版 _request 完全一致，只是把固定线拆成了车间（见 _stage* 方法）。
+   *
+   * ctx 字段（车间可见）：
+   *   options       —— 原始请求选项
+   *   userInput     —— 用户输入
+   *   addUser       —— 是否新增用户消息
+   *   messages      —— MessageStore（可读可改）
+   *   systemPrompts —— SystemPromptStore
+   *   config        —— 合并后的请求级配置（prepareInput 车间产出）
+   *   isStream      —— 本次是否流式
+   *   onProgress    —— 流式进度回调（可为 null）
+   *   onDone        —— 流式完成回调（可为 null）
+   *   mergeToEntry  —— 续写目标 id（空 = 普通发送）
+   *   body          —— adapter 构建出的请求体（buildRequest 车间产出）
+   *   result        —— 最终结果（send 车间产出）
+   */
+  async _request(options = {}) {
+    const ctx = {
+      options,
+      userInput: options.userInput,
+      addUser: options.addUser !== false,
+      messages: this.messages,
+      systemPrompts: this.systemPrompts,
+      config: null,
+      isStream: !!options.isStream,
+      onProgress: options.onProgress || null,
+      onDone: options.onDone || null,
+      mergeToEntry: options.mergeToEntry || null,
+      body: null,
+      result: null,
+    };
+    try {
+      await this._pipeline.run(ctx);
+      return ctx.result;
+    } catch (error) {
+      // AbortError 不是异常，是用户主动行为，由公共 API 层处理
+      if (error.name === 'AbortError') throw error;
+      this.emit('error', { error, timestamp: Date.now() });
+      throw error;
+    }
+  }
+
+  // ===== 内部车间（阶段 1）：与原 _request 的固定线 1:1 对应 =====
+
+  /** 车间 1：加用户消息 → 合并请求参数 → 广播 sending */
+  async _stagePrepareInput(ctx) {
+    this._addUserMessage(ctx.userInput, ctx.addUser);
+    // 合并请求参数：先于 beforeRequest 钩子，钩子拿到的是本次生效的配置
+    ctx.config = this._mergeRequestConfig(ctx.options.params);
+    this.emit('sending', { addUser: ctx.addUser, userInput: ctx.userInput, timestamp: Date.now() });
+  }
+
+  /** 车间 2：发送前钩子（兼容桥：事件钩子照发；阶段 4 会迁到 beforeSend 公开位置） */
+  async _stageBeforeSend(ctx) {
+    await this._hooks.emitAsync('beforeRequest', {
+      messages: ctx.messages,
+      config: ctx.config,
+      options: ctx.options
+    });
+  }
+
+  /** 车间 3：自动续写检测（ephemeralContinue 时，底部若有 prefix 消息则续写） */
+  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;
+      }
+    }
+  }
+
+  /** 车间 4：构建请求体 */
+  async _stageBuildRequest(ctx) {
+    ctx.body = this._adapter.buildRequest(
+      ctx.messages.getAll(), ctx.config, ctx.systemPrompts.getEnabled()
+    );
+  }
+
+  /** 车间 5：发送（流式/非流式 + 重试 + 占位消息 + _processResponse 工具钩子） */
+  async _stageSend(ctx) {
+    const retryCfg = this.config.retry || {};
+    ctx.result = await this._withRetry(ctx.body, {
+      isStream: ctx.isStream,
+      onProgress: ctx.onProgress,
+      onDone: ctx.onDone,
+      mergeToEntry: ctx.mergeToEntry,
+      config: ctx.config,
+      maxRetries: retryCfg.maxRetries ?? 0,
+      retryDelay: retryCfg.retryDelay ?? 1000
+    });
+  }
+
+  _addUserMessage(userInput, addUser) {
+    if (addUser && userInput !== undefined) {
+      const msg = typeof userInput === 'string'
+        ? { role: 'user', content: userInput }
+        : { role: 'user', ...userInput };
+      this.messages.add(msg);
+    }
+  }
+
+  /** retry 循环，占位消息只 push 一次 */
+  async _withRetry(body, { isStream, onProgress, onDone, mergeToEntry, config, maxRetries, retryDelay }) {
+    let lastError = null;
+    const adapterOptions = { signal: this._abortController?.signal };
+
+    let placeholder = null;
+    let base = null;
+    if (isStream) {
+      if (mergeToEntry) {
+        placeholder = this.messages.getAll().find(m => m.id === mergeToEntry);
+        if (placeholder) base = { content: placeholder.content || '', reasoning: placeholder.reasoningContent || '' };
+      }
+      if (!placeholder) {
+        placeholder = this.messages.add({ role: 'assistant', content: '', _complete: false });
+      }
+    }
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      if (attempt > 0) {
+        this.emit('retry', { attempt, maxRetries, lastError, timestamp: Date.now() });
+        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;
+        }
+      } catch (error) {
+        lastError = error;
+        if (error.name === 'AbortError' || this._abortController?.signal.aborted) {
+          this._isGenerating = false; throw error;
+        }
+        if (error instanceof NetworkError && attempt < maxRetries) continue;
+        this._isGenerating = false; throw error;
+      }
+    }
+    this._isGenerating = false;
+    throw lastError;
+  }
+
+  /**
+   * 流式处理：ChatService 维护占位消息，adapter 只负责解析 SSE
+   *
+   * 参数说明：
+   * - placeholder：流式期间实时更新的目标消息（续写时 = target 本身，普通发送时 = 新建的空消息）
+   * - base：续写时保存的旧内容快照，用于和 API 新内容拼接
+   * - mergeToEntry：续写目标的 id，有值时走续写逻辑
+   * - onProgress：外部回调，每收到一个 chunk 触发
+   * - onDone：流结束回调
+   */
+  async _stream(body, adapterOptions, { placeholder, base, mergeToEntry, onProgress, onDone, config }) {
+    let finalMsg = null;
+
+    await this._adapter.stream(body, config,
+      // === onProgress：每收到一个 SSE chunk 触发 ===
+      (snap) => {
+        // snap.content 是 adapter 累积的全部 API 新内容（不是增量）
+        // 续写时：base.content（旧内容）+ snap.content（API 新内容）= 完整内容
+        // 普通发送时：直接用 snap.content
+        placeholder.content = mergeToEntry && base
+          ? base.content + (snap.content || '')
+          : (snap.content || '');
+        // 思维链同样拼接：续写时 base 旧思维 + 新思维
+        if (snap.reasoningContent) {
+          placeholder.reasoningContent = mergeToEntry && base
+            ? base.reasoning + snap.reasoningContent
+            : snap.reasoningContent;
+        }
+        if (snap.toolCalls) placeholder.toolCalls = [...snap.toolCalls];
+        this.emit('stream-progress', snap);
+        if (onProgress) onProgress(snap);
+      },
+      // === 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 || '');
+          const changes = { content: newContent, _complete: true, _ephemeral: false, prefix: undefined };
+          if (final.reasoningContent) changes.reasoningContent = base.reasoning + final.reasoningContent;
+          if (final.toolCalls) changes.toolCalls = final.toolCalls;
+          this.messages.update(mergeToEntry, changes);
+          const updated = this.messages.getAll().find(m => m.id === mergeToEntry);
+          this.emit('message', updated);
+          if (onDone) onDone(updated);
+        } else {
+          // 普通发送：标记占位消息完成
+          placeholder._complete = true;
+          this.emit('message', finalMsg);
+          if (onDone) onDone(finalMsg);
+        }
+      },
+      adapterOptions
+    );
+    // 返回续写目标 id 或最终消息（供 _withRetry 返回给调用方）
+    return mergeToEntry || finalMsg;
+  }
+
+  /** 非流式结果落位 */
+  _handleResult(assistantMsg, mergeToEntry) {
+    if (mergeToEntry) {
+      const entry = this.messages.getAll().find(m => m.id === mergeToEntry);
+      if (!entry) {
+        this.messages.add(assistantMsg);
+        this.emit('message', assistantMsg);
+        return assistantMsg;
+      }
+      const changes = {
+        content: (entry.content || '') + (assistantMsg.content || ''),
+        _complete: true,
+        _ephemeral: false,
+        prefix: undefined
+      };
+      if (assistantMsg.reasoningContent) {
+        changes.reasoningContent = (entry.reasoningContent || '') + assistantMsg.reasoningContent;
+      }
+      if (assistantMsg.toolCalls) changes.toolCalls = assistantMsg.toolCalls;
+      this.messages.update(mergeToEntry, changes);
+      const updated = this.messages.getAll().find(m => m.id === mergeToEntry);
+      this.emit('message', updated);
+      return updated;
+    }
+    this.messages.add(assistantMsg);
+    this.emit('message', assistantMsg);
+    return assistantMsg;
+  }
+
+  // ========== 公共 API ==========
+
+  /**
+   * 发送消息。
+   * @param {string|Object} userInput - 用户输入
+   * @param {Object} [params] - 请求级参数覆盖（model/temperature/modelParams 等，仅本次生效）
+   */
+  async send(userInput, params) {
+    this._abortController = new AbortController();
+    try {
+      return await this._request({ userInput, addUser: true, isStream: false, params });
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        this.emit('aborted', { timestamp: Date.now() });
+        return;
+      }
+      throw err;
+    } finally {
+      this._abortController = null;
+      this._isGenerating = false;
+    }
+  }
+
+  /**
+   * 流式发送。
+   * @param {string|Object} userInput - 用户输入
+   * @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+   * @param {Function} [onProgress] - 流式进度回调
+   * @param {Function} [onDone] - 流式完成回调
+   */
+  async stream(userInput, params, onProgress, onDone) {
+    // 兼容旧签名 stream(input, onProgress, onDone)
+    if (typeof params === 'function') {
+      onDone = onProgress;
+      onProgress = params;
+      params = undefined;
+    }
+    this._abortController = new AbortController();
+    try {
+      return await this._request({ userInput, addUser: true, isStream: true, onProgress, onDone, params });
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        this.emit('aborted', { timestamp: Date.now() });
+        return;
+      }
+      throw err;
+    } finally {
+      this._abortController = null;
+      this._isGenerating = false;
+    }
+  }
+
+  /**
+   * 重发当前消息（不加用户消息）。
+   * @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+   */
+  async sendExisting(params) {
+    this._abortController = new AbortController();
+    try {
+      return await this._request({ addUser: false, isStream: false, params });
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        this.emit('aborted', { timestamp: Date.now() });
+        return;
+      }
+      throw err;
+    } finally {
+      this._abortController = null;
+      this._isGenerating = false;
+    }
+  }
+
+  /**
+   * 流式重发（不加用户消息）。
+   * @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+   * @param {Function} [onProgress] - 流式进度回调
+   * @param {Function} [onDone] - 流式完成回调
+   */
+  async sendExistingStream(params, onProgress, onDone) {
+    // 兼容旧签名 sendExistingStream(onProgress, onDone)
+    if (typeof params === 'function') {
+      onDone = onProgress;
+      onProgress = params;
+      params = undefined;
+    }
+    this._abortController = new AbortController();
+    try {
+      return await this._request({ addUser: false, isStream: true, onProgress, onDone, params });
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        this.emit('aborted', { timestamp: Date.now() });
+        return;
+      }
+      throw err;
+    } finally {
+      this._abortController = null;
+      this._isGenerating = false;
+    }
+  }
+}
+
+/**
+ * 校验 adapter 是否满足协议（v3.0 · 阶段 3）。
+ * 缺少必要方法时抛 ConfigurationError，并列出缺少的方法名——写"同级适配器"不再靠猜。
+ * @param {*} adapter
+ * @throws {ConfigurationError}
+ */
+export function assertAdapter(adapter) {
+  if (!adapter || typeof adapter !== 'object') {
+    throw new ConfigurationError('setAdapter: adapter 必须是对象（如 openaiAdapter / createOpenAIAdapter() 实例）');
+  }
+  const required = ['buildRequest', 'send', 'stream', 'parseResponse'];
+  const missing = required.filter(k => typeof adapter[k] !== 'function');
+  if (missing.length) {
+    throw new ConfigurationError(
+      `setAdapter: adapter 缺少必要方法: ${missing.join(', ')}（协议见 ChatService.js 顶部的 @typedef ChatAdapter）`
+    );
+  }
+}