my-ai-chat-framework 3.0.0 → 4.0.0

package/dist/my-ai-chat-framework.browser.umd.js

@@ -177,6 +177,69 @@
 		}
 	};
 	//#endregion
+	//#region src/core/Errors.js
+	/**
+	* 自定义错误类
+	* 用于区分不同类型的错误，方便用户通过 `error.name` 或 `instanceof` 处理
+	*/
+	var APIError = class extends Error {
+		/**
+		* @param {string} message - 错误消息(通常来自 API 响应)
+		* @param {number} statusCode - HTTP 状态码
+		* @param {any} originalError - 原始错误对象或相关信息
+		* @param {string} responseText - 原始响应文本（如果有）
+		*/
+		constructor(message, statusCode, originalError, responseText) {
+			super(message);
+			this.name = "APIError";
+			this.statusCode = statusCode;
+			this.originalError = originalError;
+			this.responseText = responseText;
+		}
+	};
+	var NetworkError = class extends Error {
+		/**
+		* @param {string} message - 错误消息
+		* @param {any} originalError - 原始错误对象或相关信息
+		*/
+		constructor(message, originalError) {
+			super(message);
+			this.name = "NetworkError";
+			this.originalError = originalError;
+		}
+	};
+	var ConfigurationError = class extends Error {
+		/**
+		* @param {string} message - 错误消息
+		*/
+		constructor(message) {
+			super(message);
+			this.name = "ConfigurationError";
+		}
+	};
+	var ValidationError = class extends ConfigurationError {
+		/**
+		* @param {string} message - 错误消息
+		*/
+		constructor(message) {
+			super(message);
+			this.name = "ValidationError";
+		}
+	};
+	var ParsingError = class extends Error {
+		/**
+		* @param {string} message - 错误消息
+		* @param {any} originalError - 原始错误对象或相关信息  
+		* @param {string} responseText - 原始响应文本（如果有）
+		**/
+		constructor(message, originalError, responseText) {
+			super(message);
+			this.name = "ParsingError";
+			this.originalError = originalError;
+			this.responseText = responseText;
+		}
+	};
+	//#endregion
 	//#region src/core/SystemPromptStore.js
 	/**
 	* SystemPromptStore — 系统提示词存储
@@ -204,7 +267,7 @@
 		* @returns {Object} 添加的记录
 		*/
 		add(content, enabled = true) {
-			if (!content || typeof content !== "string" || !content.trim()) throw new Error("[SystemPromptStore] content 必须是非空字符串");
+			if (!content || typeof content !== "string" || !content.trim()) throw new ValidationError("[SystemPromptStore] content 必须是非空字符串");
 			const record = {
 				id: `sys_${Date.now()}_${++this._idCounter}`,
 				content: content.trim(),
@@ -220,7 +283,7 @@
 		* @returns {Object} 被删除的记录
 		*/
 		remove(index) {
-			if (index < 0 || index >= this._prompts.length) throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
+			if (index < 0 || index >= this._prompts.length) throw new ValidationError(`[SystemPromptStore] 索引越界: ${index}`);
 			return this._prompts.splice(index, 1)[0];
 		}
 		/**
@@ -229,7 +292,7 @@
 		* @returns {boolean} 切换后的状态
 		*/
 		toggle(index) {
-			if (index < 0 || index >= this._prompts.length) throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
+			if (index < 0 || index >= this._prompts.length) throw new ValidationError(`[SystemPromptStore] 索引越界: ${index}`);
 			this._prompts[index].enabled = !this._prompts[index].enabled;
 			return this._prompts[index].enabled;
 		}
@@ -239,8 +302,8 @@
 		* @param {string} content
 		*/
 		update(index, content) {
-			if (index < 0 || index >= this._prompts.length) throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
-			if (!content || typeof content !== "string" || !content.trim()) throw new Error("[SystemPromptStore] content 必须是非空字符串");
+			if (index < 0 || index >= this._prompts.length) throw new ValidationError(`[SystemPromptStore] 索引越界: ${index}`);
+			if (!content || typeof content !== "string" || !content.trim()) throw new ValidationError("[SystemPromptStore] content 必须是非空字符串");
 			this._prompts[index].content = content.trim();
 			this._prompts[index].timestamp = Date.now();
 		}
@@ -277,60 +340,6 @@
 		}
 	};
 	//#endregion
-	//#region src/core/Errors.js
-	/**
-	* 自定义错误类
-	* 用于区分不同类型的错误，方便用户通过 `error.name` 或 `instanceof` 处理
-	*/
-	var APIError = class extends Error {
-		/**
-		* @param {string} message - 错误消息(通常来自 API 响应)
-		* @param {number} statusCode - HTTP 状态码
-		* @param {any} originalError - 原始错误对象或相关信息
-		* @param {string} responseText - 原始响应文本（如果有）
-		*/
-		constructor(message, statusCode, originalError, responseText) {
-			super(message);
-			this.name = "APIError";
-			this.statusCode = statusCode;
-			this.originalError = originalError;
-			this.responseText = responseText;
-		}
-	};
-	var NetworkError = class extends Error {
-		/**
-		* @param {string} message - 错误消息
-		* @param {any} originalError - 原始错误对象或相关信息
-		*/
-		constructor(message, originalError) {
-			super(message);
-			this.name = "NetworkError";
-			this.originalError = originalError;
-		}
-	};
-	var ConfigurationError = class extends Error {
-		/**
-		* @param {string} message - 错误消息
-		*/
-		constructor(message) {
-			super(message);
-			this.name = "ConfigurationError";
-		}
-	};
-	var ParsingError = class extends Error {
-		/**
-		* @param {string} message - 错误消息
-		* @param {any} originalError - 原始错误对象或相关信息  
-		* @param {string} responseText - 原始响应文本（如果有）
-		**/
-		constructor(message, originalError, responseText) {
-			super(message);
-			this.name = "ParsingError";
-			this.originalError = originalError;
-			this.responseText = responseText;
-		}
-	};
-	//#endregion
 	//#region src/core/Pipeline.js
 	/**
 	* Pipeline —— 极简顺序管道（v3.0 提案 · 阶段 1）
@@ -407,26 +416,37 @@
 		"maxTokens",
 		"modelParams",
 		"system",
-		"retry",
-		"ephemeralContinue"
+		"retry"
+	];
+	var INTERNAL_STAGES = [
+		"prepareInput",
+		"beforeSend",
+		"autoContinue",
+		"buildRequest",
+		"send"
 	];
 	var ChatService = class extends EventEmitter {
 		constructor(config = {}) {
 			super();
 			this.config = { ...config };
-			this.messages = new MessageStore();
+			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;
+			this._activeRequests = /* @__PURE__ */ new Map();
+			this._requestSeq = 0;
 			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);
 			this._userStages = [];
+			this._stageOverrides = /* @__PURE__ */ new Map();
+			this._disabledStages = /* @__PURE__ */ new Set();
+			this._extraConfigKeys = /* @__PURE__ */ new Map();
+			this.plugins = {};
 			this._pipeline = this._buildPipeline();
 		}
 		/**
@@ -441,8 +461,16 @@
 			const model = cfg.model ?? cfg.modelParams?.model;
 			if (model !== void 0 && (typeof model !== "string" || !model.trim())) throw new ConfigurationError("model 必须是非空字符串");
 		}
+		/**
+		* 安装插件。
+		* - 插件实现 `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;
 		}
 		/**
@@ -457,13 +485,7 @@
 		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（车间名，非空字符串）");
-			if ([
-				"prepareInput",
-				"beforeSend",
-				"autoContinue",
-				"buildRequest",
-				"send"
-			].includes(stage.name)) throw new ConfigurationError(`pipe: "${stage.name}" 是内部车间名，请换一个名字`);
+			if (INTERNAL_STAGES.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({
@@ -485,37 +507,86 @@
 		get pipelineStages() {
 			return this._pipeline.names();
 		}
-		/** 重建内部管道：内部 5 车间 + 用户车间按 phase 插入 */
+		/** 内部步骤名（顺序即执行顺序）：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;
 		}
 		_rebuildPipeline() {
@@ -525,98 +596,81 @@
 			assertAdapter(adapter);
 			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;
+			return this._activeRequests.size > 0;
+		}
+		/** 当前活跃请求的 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 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: void 0,
-					_ephemeral: false
-				});
-				return target;
-			} catch (err) {
-				this.messages.update(target.id, {
-					_complete: true,
-					prefix: void 0,
-					_ephemeral: false
-				});
-				if (err.name === "AbortError") {
-					this.emit("aborted", { timestamp: Date.now() });
-					return target;
-				}
-				throw err;
-			}
+		/** 内部：注销一个请求 */
+		_endRequest(id) {
+			this._activeRequests.delete(id);
 		}
-		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: void 0,
-					_ephemeral: false
-				});
-				return target;
-			} catch (err) {
-				this.messages.update(target.id, {
-					_complete: true,
-					prefix: void 0,
-					_ephemeral: false
-				});
-				if (err.name === "AbortError") {
-					this.emit("aborted", { timestamp: Date.now() });
-					return target;
-				}
-				throw err;
+		/**
+		* 注册"运行时可改的配置字段"（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: 字段名必须是非空字符串");
+				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) {
-			for (const key of Object.keys(partial)) if (!SESSION_CONFIG_KEYS.includes(key)) throw new ConfigurationError(`updateConfig 不支持修改 "${key}"。允许的会话层字段: ${SESSION_CONFIG_KEYS.join(", ")}`);
+			const allowed = this.configKeys;
+			for (const key of Object.keys(partial)) if (!allowed.includes(key)) throw new ConfigurationError(`updateConfig 不支持修改 "${key}"。允许的字段: ${allowed.join(", ")}`);
 			this._assertValidConfig(partial);
+			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", {
@@ -682,6 +736,7 @@
 				onProgress: options.onProgress || null,
 				onDone: options.onDone || null,
 				mergeToEntry: options.mergeToEntry || null,
+				signal: options.signal || null,
 				body: null,
 				result: null
 			};
@@ -707,22 +762,19 @@
 				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;
-			}
-		}
+		/**
+		* 车间 2：发送前 —— **v4.0 起默认什么都不做**。
+		* 需要在这里做事的（注入、改写消息/配置）：`chat.replaceStage('beforeSend', fn)`
+		* 或挂一个 `chat.pipe({ phase: 'beforeSend' })` 车间（在它之后执行）。
+		* 旧的 `_hooks.on('beforeRequest')` 兼容桥已于 v4.0 移除。
+		*/
+		async _stageBeforeSend(ctx) {}
+		/**
+		* 车间 3：自动续写检测 —— **v4.0 起默认什么都不做**。
+		* 续写是玩法：需要它的装上 continuation 插件，由插件 replaceStage('autoContinue', ...) 接管。
+		* 步骤名与位置保留，方便插件替换、也方便使用者 `unstage('autoContinue')` 明确移除。
+		*/
+		async _stageAutoContinue(ctx) {}
 		/** 车间 4：构建请求体 */
 		async _stageBuildRequest(ctx) {
 			ctx.body = this._adapter.buildRequest(ctx.messages.getAll(), ctx.config, ctx.systemPrompts.getEnabled());
@@ -737,7 +789,8 @@
 				mergeToEntry: ctx.mergeToEntry,
 				config: ctx.config,
 				maxRetries: retryCfg.maxRetries ?? 0,
-				retryDelay: retryCfg.retryDelay ?? 1e3
+				retryDelay: retryCfg.retryDelay ?? 1e3,
+				signal: ctx.signal
 			});
 		}
 		_addUserMessage(userInput, addUser) {
@@ -753,9 +806,9 @@
 			}
 		}
 		/** 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 };
+			const adapterOptions = { signal };
 			let placeholder = null;
 			let base = null;
 			if (isStream) {
@@ -783,7 +836,6 @@
 					await new Promise((r) => setTimeout(r, retryDelay));
 				}
 				try {
-					this._isGenerating = true;
 					if (isStream) return await this._stream(body, adapterOptions, {
 						placeholder,
 						base,
@@ -794,22 +846,15 @@
 					});
 					else {
 						const resp = await this._adapter.send(body, config, adapterOptions);
-						let result = this._handleResult(this._adapter.parseResponse(resp), mergeToEntry);
-						if (this._processResponse && !mergeToEntry) result = await this._processResponse(result, { isStream: false });
-						return result;
+						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;
 				}
 			}
-			this._isGenerating = false;
 			throw lastError;
 		}
 		/**
@@ -824,19 +869,14 @@
 		*/
 		async _stream(body, adapterOptions, { placeholder, base, mergeToEntry, onProgress, onDone, config }) {
 			let finalMsg = null;
-			await this._adapter.stream(body, config, (snap) => {
+			await this._adapter.stream(body, config, (snap, delta) => {
 				placeholder.content = mergeToEntry && base ? base.content + (snap.content || "") : snap.content || "";
 				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);
+				if (onProgress) onProgress(snap, delta);
 			}, async (final) => {
 				finalMsg = final;
-				if (this._processResponse && !mergeToEntry) finalMsg = await this._processResponse(finalMsg, {
-					isStream: true,
-					onProgress,
-					onDone
-				});
 				if (mergeToEntry && base) {
 					const changes = {
 						content: base.content + (final.content || ""),
@@ -890,13 +930,14 @@
 		* @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
+					params,
+					signal
 				});
 			} catch (err) {
 				if (err.name === "AbortError") {
@@ -905,8 +946,7 @@
 				}
 				throw err;
 			} finally {
-				this._abortController = null;
-				this._isGenerating = false;
+				this._endRequest(id);
 			}
 		}
 		/**
@@ -922,7 +962,7 @@
 				onProgress = params;
 				params = void 0;
 			}
-			this._abortController = new AbortController();
+			const { id, signal } = this._beginRequest();
 			try {
 				return await this._request({
 					userInput,
@@ -930,7 +970,8 @@
 					isStream: true,
 					onProgress,
 					onDone,
-					params
+					params,
+					signal
 				});
 			} catch (err) {
 				if (err.name === "AbortError") {
@@ -939,21 +980,24 @@
 				}
 				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
+					params,
+					mergeToEntry,
+					signal
 				});
 			} catch (err) {
 				if (err.name === "AbortError") {
@@ -962,30 +1006,38 @@
 				}
 				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) {
+		async sendExistingStream(params, options, onProgress, onDone) {
 			if (typeof params === "function") {
-				onDone = onProgress;
+				onDone = options;
 				onProgress = params;
+				options = {};
 				params = void 0;
+			} else if (typeof options === "function") {
+				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
+					params,
+					mergeToEntry,
+					signal
 				});
 			} catch (err) {
 				if (err.name === "AbortError") {
@@ -994,8 +1046,7 @@
 				}
 				throw err;
 			} finally {
-				this._abortController = null;
-				this._isGenerating = false;
+				this._endRequest(id);
 			}
 		}
 	};
@@ -1046,26 +1097,23 @@
 	//#endregion
 	//#region src/utils/MessageFormatter.js
 	/**
-	* MessageFormatter — 可注册的消息格式转换器
+	* MessageFormatter — 可注册的消息格式转换器 + 可注册的过滤器链（v4.0）
 	*
 	* 职责：
-	* 1. 内置 OpenA I兼容格式的转换逻辑
+	* 1. 内置 OpenAI 兼容格式的转换逻辑
 	* 2. 支持 register(name, fn) 注册自定义格式（如 Anthropic、Gemini 等）
-	* 3. 统一处理 capabilities 过滤（reasoning、vision 等）
-	* 4. 所有适配器通过此工具获取 API 消息数组，消除重复代码
+	* 3. v4.0：消息"保留 / 丢弃"规则改为可注册的过滤器链（registerFilter）
+	*    —— 原来硬编码在格式里的 ephemeral / system / 空内容规则，现在都是过滤器；
+	*       业务插件（如 continuation）可以同名覆盖内置过滤器，接管规则。
 	*
 	* 用法：
 	*   import { MessageFormatter } from 'my-ai-chat-framework';
 	*
 	*   // 使用内置格式
-	*   const msgs = MessageFormatter.format({
-	*     messages, systemPrompts, capabilities, resolveImage
-	*   });  // 默认 'openai'
+	*   const msgs = MessageFormatter.format({ messages, systemPrompts, capabilities, resolveImage });
 	*
-	*   // 注册自定义格式
-	*   MessageFormatter.register('anthropic', ({ messages, systemPrompts, capabilities }) => {
-	*     // 返回 Anthropic 格式的消息数组
-	*   });
+	*   // 注册自己的过滤器（决定哪些消息进入请求）
+	*   MessageFormatter.registerFilter('my-rule', (msg, ctx) => msg.role === 'system' ? null : msg);
 	*/
 	var IS_URL = /^https?:\/\//i;
 	function defaultResolveImage(imageId) {
@@ -1094,7 +1142,23 @@
 		}
 		return content;
 	}
-	/** OpenAI 兼容格式 */
+	/** system 角色消息不进对话数组（system 由 systemPrompts 统一置顶） */
+	function filterSystemDrop(msg) {
+		if (msg.role === "system" && !msg._ephemeral) return null;
+		return msg;
+	}
+	/** 空内容清理：无文本、无图片的消息丢弃（tool、带 toolCalls 的 assistant、prefix 空消息例外） */
+	function filterEmptyDrop(msg) {
+		if (msg.role === "system" || msg.role === "tool") return msg;
+		if (msg.role === "assistant" && msg.toolCalls?.length) return msg;
+		const hasText = msg.content && isString(msg.content) && msg.content.trim();
+		const hasImages = Array.isArray(msg.images) && msg.images.length > 0;
+		if (!hasText && !hasImages) {
+			if (msg.role === "assistant" && msg.prefix) return msg;
+			return null;
+		}
+		return msg;
+	}
 	function toOpenAI({ messages, systemPrompts, capabilities, resolveImage }) {
 		const rImg = typeof resolveImage === "function" ? resolveImage : defaultResolveImage;
 		const result = [];
@@ -1102,15 +1166,8 @@
 			role: "system",
 			content: sp.content.trim()
 		});
-		let ephemEnd = messages.length;
-		for (let i = messages.length - 1; i >= 0; i--) if (messages[i]._ephemeral) ephemEnd = i;
-		else break;
-		for (let i = 0; i < messages.length; i++) {
-			const msg = messages[i];
-			if (msg._ephemeral) {
-				if (i < ephemEnd) continue;
-			}
-			if (msg.role === "system" && !msg._ephemeral) continue;
+		const kept = MessageFormatter._runFilters(messages, capabilities || {});
+		for (const msg of kept) {
 			if (msg.role === "tool") {
 				result.push({
 					role: "tool",
@@ -1146,7 +1203,7 @@
 			}
 			const entry = { role: msg.role };
 			if (hasImages) {
-				if (!capabilities?.vision) throw new Error("[MessageFormatter] 消息包含图片但模型不支持视觉（capabilities.vision=false）。请切换模型或移除图片。");
+				if (!capabilities?.vision) throw new ValidationError("[MessageFormatter] 消息包含图片但模型不支持视觉（capabilities.vision=false）。请切换模型或移除图片。");
 				entry.content = buildMultimodalContent(msg.content || "", msg.images, rImg);
 			} else entry.content = msg.content;
 			if (msg.prefix) entry.prefix = true;
@@ -1156,22 +1213,71 @@
 	}
 	var MessageFormatter = {
 		_formats: new Map([["openai", toOpenAI]]),
+		_filters: /* @__PURE__ */ new Map(),
+		_filterOrder: 0,
 		register(name, fn) {
-			if (!name || typeof name !== "string" || !name.trim()) throw new Error("[MessageFormatter] 格式名称必须是非空字符串");
-			if (typeof fn !== "function") throw new Error("[MessageFormatter] 转换函数必须是 function");
+			if (!name || typeof name !== "string" || !name.trim()) throw new ValidationError("[MessageFormatter] 格式名称必须是非空字符串");
+			if (typeof fn !== "function") throw new ValidationError("[MessageFormatter] 转换函数必须是 function");
 			this._formats.set(name.trim(), fn);
 		},
 		unregister(name) {
-			if (name === "openai") throw new Error("[MessageFormatter] 内置格式 \"openai\" 不可移除");
+			if (name === "openai") throw new ValidationError("[MessageFormatter] 内置格式 \"openai\" 不可移除");
 			this._formats.delete(name);
 		},
 		listFormats() {
 			return [...this._formats.keys()];
 		},
+		registerFilter(name, fn, options = {}) {
+			if (!name || typeof name !== "string" || !name.trim()) throw new ValidationError("[MessageFormatter] 过滤器名称必须是非空字符串");
+			if (typeof fn !== "function") throw new ValidationError("[MessageFormatter] 过滤器必须是 function");
+			const key = name.trim();
+			const priority = typeof options.priority === "number" ? options.priority : 100;
+			const prev = this._filters.get(key);
+			this._filters.set(key, {
+				name: key,
+				fn,
+				priority,
+				order: ++this._filterOrder
+			});
+			return prev ? prev.fn : void 0;
+		},
+		unregisterFilter(name) {
+			return this._filters.delete(name);
+		},
+		listFilters() {
+			return [...this._filters.values()].sort((a, b) => a.priority - b.priority || a.order - b.order).map((f) => ({
+				name: f.name,
+				priority: f.priority
+			}));
+		},
+		_runFilters(messages, capabilities = {}) {
+			if (this._filters.size === 0) return [...messages];
+			const list = [...this._filters.values()].sort((a, b) => a.priority - b.priority || a.order - b.order);
+			const out = [];
+			for (let i = 0; i < messages.length; i++) {
+				let msg = messages[i];
+				const ctx = {
+					index: i,
+					total: messages.length,
+					messages,
+					capabilities
+				};
+				let dropped = false;
+				for (const f of list) {
+					msg = f.fn(msg, ctx);
+					if (msg === null || msg === void 0) {
+						dropped = true;
+						break;
+					}
+				}
+				if (!dropped) out.push(msg);
+			}
+			return out;
+		},
 		format(options = {}) {
 			const formatName = options.format || "openai";
 			const fn = this._formats.get(formatName);
-			if (!fn) throw new Error(`[MessageFormatter] 未知格式 "${formatName}"。可用格式: ${[...this._formats.keys()].join(", ")}`);
+			if (!fn) throw new ValidationError(`[MessageFormatter] 未知格式 "${formatName}"。可用格式: ${[...this._formats.keys()].join(", ")}`);
 			return fn({
 				messages: options.messages || [],
 				systemPrompts: options.systemPrompts || [],
@@ -1180,6 +1286,8 @@
 			});
 		}
 	};
+	MessageFormatter.registerFilter("system-drop", filterSystemDrop, { priority: 900 });
+	MessageFormatter.registerFilter("empty-drop", filterEmptyDrop, { priority: 910 });
 	function assembleMessages(options = {}) {
 		return MessageFormatter.format({
 			...options,
@@ -1229,10 +1337,10 @@
 		buildRequest(messages, config, systemPrompts = []) {
 			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)");
+			if (!model) throw new ConfigurationError("Missing required config: model (either at top level or in modelParams)");
 			const mp = config.modelParams || {};
-			const temperature = mp.temperature ?? config.temperature ?? .7;
-			const maxTokens = mp.maxTokens ?? config.maxTokens ?? 2e3;
+			const temperature = mp.temperature ?? config.temperature;
+			const maxTokens = mp.maxTokens ?? config.maxTokens;
 			const reasoningEffort = mp.reasoningEffort ?? config.reasoningEffort;
 			const requestBody = {
 				model,
@@ -1243,10 +1351,10 @@
 					resolveImage: config.resolveImage,
 					format: config.messageFormat
 				}),
-				temperature,
-				max_tokens: maxTokens,
 				stream: false
 			};
+			if (temperature !== void 0) requestBody.temperature = temperature;
+			if (maxTokens !== void 0) requestBody.max_tokens = maxTokens;
 			if (mp.topP !== void 0) requestBody.top_p = mp.topP;
 			if (mp.frequencyPenalty !== void 0) requestBody.frequency_penalty = mp.frequencyPenalty;
 			if (mp.presencePenalty !== void 0) requestBody.presence_penalty = mp.presencePenalty;
@@ -1353,22 +1461,37 @@
 				content: "",
 				reasoningContent: ""
 			};
+			let reachedDone = false;
 			while (true) {
 				if (options.signal?.aborted) break;
 				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]") break;
+				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 delta = JSON.parse(dataLine).choices?.[0]?.delta;
+						const delta = JSON.parse(dataPayload).choices?.[0]?.delta;
 						if (!delta) continue;
-						if (delta.content) accumulated.content += delta.content;
+						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;
@@ -1384,14 +1507,23 @@
 								if (toolCallDelta.type) accumulated.toolCalls[index].type = toolCallDelta.type;
 								if (toolCallDelta.function?.name) accumulated.toolCalls[index].function.name += toolCallDelta.function.name;
 								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;
-						onProgress({ ...accumulated });
+						onProgress({ ...accumulated }, deltaInfo);
 					} catch (e) {
-						console.warn("stream parsing failed :", e, dataLine);
+						console.warn("stream parsing failed :", e, dataPayload);
 					}
 				}
+				if (reachedDone) break;
 			}
 			onDone({
 				role: "assistant",
@@ -1453,12 +1585,14 @@
 	var toolCallingPlugin = createToolCallingPlugin();
 	/**
 	* 创建工具调用插件实例（工厂）。
-	* @param {Object} [options] — { timeout, maxIterations }
+	* @param {Object} [options] — { timeout?, maxIterations? }
+	*   - 两者**默认都不限制**：不传就是"循环到没有工具调用为止 / 不超时"
+	*   - 想限制才传（这是使用者的选择，不是框架替你做的决定）
 	*/
 	function createToolCallingPlugin(options = {}) {
 		return {
 			name: "tool-calling",
-			maxIterations: options.maxIterations || 5,
+			maxIterations: options.maxIterations ?? Infinity,
 			_options: { ...options },
 			_tools: /* @__PURE__ */ new Map(),
 			_toolDefs: [],
@@ -1484,11 +1618,18 @@
 				* @param {Object} parameters - JSON Schema 参数定义（可选，默认为空对象）
 				* @returns {ChatService} 返回 chatService 实例，支持链式调用
 				*/
-				chatService.registerTool = (name, description, executor, parameters = {}) => {
+				const registerTool = (name, description, executor, parameters = {}) => {
 					this._tools.set(name, {
 						executor,
 						description
 					});
+					const properties = {};
+					const requiredKeys = [];
+					for (const [key, def] of Object.entries(parameters || {})) {
+						const { required: isRequired, ...schema } = def || {};
+						properties[key] = schema;
+						if (isRequired) requiredKeys.push(key);
+					}
 					const toolDefinition = {
 						type: "function",
 						function: {
@@ -1496,8 +1637,8 @@
 							description,
 							parameters: {
 								type: "object",
-								properties: parameters,
-								required: Object.keys(parameters).filter((key) => parameters[key]?.required)
+								properties,
+								required: requiredKeys
 							}
 						}
 					};
@@ -1511,6 +1652,18 @@
 						ctx.result = await this._handleWithTools(ctx.result, ctx.isStream, ctx.onProgress || void 0, ctx.onDone || void 0);
 					}
 				});
+				return {
+					registerTool,
+					tools: this._tools,
+					uninstall: (c) => this.uninstall(c)
+				};
+			},
+			uninstall(chat) {
+				if (!chat) return chat;
+				chat.unpipe?.("tool-calling-inject");
+				chat.unpipe?.("tool-calling-loop");
+				if (chat.plugins && chat.plugins["tool-calling"]) delete chat.plugins["tool-calling"];
+				return chat;
 			},
 			async _handleWithTools(initialResponse, isStream, onProgress, onDone) {
 				const self = this;
@@ -1562,15 +1715,27 @@
 								};
 							}
 							try {
-								const toolTimeout = self._options.timeout ?? chat.config.toolTimeout;
-								let execPromise = tool.executor(args);
-								if (toolTimeout && typeof toolTimeout === "number" && toolTimeout > 0) {
+								const toolTimeout = self._options.timeout;
+								let result;
+								if (typeof toolTimeout === "number" && toolTimeout > 0) {
+									const controller = new AbortController();
 									const timeoutErr = /* @__PURE__ */ new Error(`工具 ${toolName} 执行超时 (${toolTimeout}ms)`);
 									timeoutErr.name = "ToolTimeoutError";
-									const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(timeoutErr), toolTimeout));
-									execPromise = Promise.race([execPromise, timeoutPromise]);
-								}
-								const result = await execPromise;
+									let timer;
+									const timeoutPromise = new Promise((_, reject) => {
+										timer = setTimeout(() => {
+											controller.abort();
+											reject(timeoutErr);
+										}, toolTimeout);
+									});
+									const execPromise = Promise.resolve().then(() => tool.executor(args, { signal: controller.signal }));
+									execPromise.catch(() => {});
+									try {
+										result = await Promise.race([execPromise, timeoutPromise]);
+									} finally {
+										clearTimeout(timer);
+									}
+								} else result = await tool.executor(args);
 								chat.emit("tool-success", {
 									toolName,
 									result,
@@ -1753,8 +1918,8 @@
 				* @param {Object} capabilities — 能力标签对象（部分字段即可，未提供的取默认值）
 				* @returns {ChatService}
 				*/
-				chatService.registerModel = (name, capabilities = {}) => {
-					if (!name || typeof name !== "string" || !name.trim()) throw new Error("[model-registry] 模型名称必须是非空字符串");
+				const registerModel = (name, capabilities = {}) => {
+					if (!name || typeof name !== "string" || !name.trim()) throw new ValidationError("[model-registry] 模型名称必须是非空字符串");
 					const merged = {
 						...DEFAULT_CAPABILITIES,
 						...capabilities
@@ -1767,7 +1932,7 @@
 				* 列出所有已注册的模型名称
 				* @returns {Array<string>}
 				*/
-				chatService.listModels = () => {
+				const listModels = () => {
 					return [...this._registry.keys()];
 				};
 				this._syncCapabilities();
@@ -1790,6 +1955,17 @@
 						};
 					}
 				});
+				return {
+					registerModel,
+					listModels,
+					uninstall: (c) => this.uninstall(c)
+				};
+			},
+			uninstall(chat = this.chat) {
+				if (!chat) return chat;
+				chat.unpipe?.("model-registry-caps");
+				if (chat.plugins && chat.plugins["model-registry"]) delete chat.plugins["model-registry"];
+				return chat;
 			},
 			_lookupCapabilities() {
 				const model = this.chat.config.model;
@@ -1803,6 +1979,137 @@
 		};
 	}
 	//#endregion
+	//#region src/plugins/continuation.js
+	/**
+	* continuation 插件（v4.0）
+	*
+	* 「续写 / 临时消息」这套玩法住在这里 —— 核心不认识它，装上才有：
+	* 1. 续写检测（替换核心的 autoContinue 步骤）：底部若有带 prefix 标记的消息，就把结果合并回它
+	* 2. ephemeral 过滤器：临时消息只有"位于底部连续段"时才发给 API
+	* 3. continueLast / continueLastStream 两个 API
+	* 4. uninstall()：把自己装的东西全部还原（步骤、过滤器、方法）
+	*
+	* 用法：
+	*   import { createContinuationPlugin } from 'my-ai-chat-framework';
+	*   chat.use(createContinuationPlugin({ autoContinue: true }));
+	*
+	*   // 模拟思维链：注入一条临时引导，结果合并回上一条 assistant，不留痕
+	*   chat.messages.addOnceAssistant('（内心：他肯定又要熬夜）');
+	*   await chat.stream('在吗');
+	*/
+	/**
+	* ephemeral 规则：只有底部连续的临时消息保留，其余丢弃（与 v3.x 核心内置行为一致）。
+	* 导出以便使用者直接注册到 MessageFormatter（不使用插件时也能用这条规则）。
+	*/
+	function ephemeralFilterRule(msg, { index, messages }) {
+		if (!msg._ephemeral) return msg;
+		let start = messages.length;
+		for (let i = messages.length - 1; i >= 0; i--) if (messages[i]._ephemeral) start = i;
+		else break;
+		return index >= start ? msg : null;
+	}
+	/**
+	* 找续写目标：最后一条必须是 assistant 或临时消息（否则抛错）。
+	* @param {object} chat ChatService 实例
+	*/
+	function prepareContinue(chat) {
+		const msgs = chat.messages.getAll();
+		const last = msgs[msgs.length - 1];
+		if (last && (last.role === "assistant" || last._ephemeral)) return last;
+		throw new ValidationError("最后一条消息不是 assistant，无法续写");
+	}
+	/** 续写结束后的"转正" */
+	function finalize(chat, targetId) {
+		chat.messages.update(targetId, {
+			_complete: true,
+			prefix: void 0,
+			_ephemeral: false
+		});
+	}
+	/**
+	* 创建续写插件实例（工厂）
+	* @param {Object} [options] — { autoContinue?: boolean }  是否自动识别底部 prefix 消息并合并（默认 false）
+	*/
+	function createContinuationPlugin(options = {}) {
+		return {
+			name: "continuation",
+			_options: {
+				autoContinue: false,
+				...options
+			},
+			_prevEphemeralFilter: void 0,
+			_installedOn: null,
+			install(chat) {
+				this._installedOn = chat;
+				if (typeof chat.registerConfigKeys === "function") chat.registerConfigKeys({ autoContinue: (v) => typeof v === "boolean" });
+				chat.replaceStage("autoContinue", (ctx) => {
+					if (!(chat.config.autoContinue ?? this._options.autoContinue)) return;
+					if (ctx.mergeToEntry) return;
+					const last = ctx.messages.getLast();
+					if (last && last.prefix && (last.role === "assistant" || last._ephemeral)) ctx.mergeToEntry = last.id;
+				});
+				this._prevEphemeralFilter = MessageFormatter.registerFilter("ephemeral", ephemeralFilterRule, { priority: 100 });
+				const continueLast = async () => {
+					const target = prepareContinue(chat);
+					chat.messages.update(target.id, { prefix: true });
+					try {
+						await chat.sendExisting(void 0, { mergeToEntry: target.id });
+						finalize(chat, target.id);
+						return target;
+					} catch (err) {
+						finalize(chat, target.id);
+						if (err.name === "AbortError") {
+							chat.emit("aborted", { timestamp: Date.now() });
+							return target;
+						}
+						throw err;
+					}
+				};
+				const continueLastStream = async (onProgress, onDone) => {
+					const target = prepareContinue(chat);
+					chat.messages.update(target.id, { prefix: true });
+					const baseLen = (target.content || "").length;
+					try {
+						await chat.sendExistingStream(void 0, { mergeToEntry: target.id }, (chunk) => {
+							if (onProgress) onProgress({
+								...chunk,
+								content: (chunk.content || "").slice(baseLen)
+							});
+						}, (final) => {
+							if (onDone) onDone(final);
+						});
+						finalize(chat, target.id);
+						return target;
+					} catch (err) {
+						finalize(chat, target.id);
+						if (err.name === "AbortError") {
+							chat.emit("aborted", { timestamp: Date.now() });
+							return target;
+						}
+						throw err;
+					}
+				};
+				return {
+					continueLast,
+					continueLastStream,
+					uninstall: () => this.uninstall(chat)
+				};
+			},
+			uninstall(chat = this._installedOn) {
+				if (!chat) return chat;
+				if (typeof chat.restoreStage === "function") chat.restoreStage("autoContinue");
+				if (this._prevEphemeralFilter) MessageFormatter.registerFilter("ephemeral", this._prevEphemeralFilter, { priority: 100 });
+				else MessageFormatter.unregisterFilter("ephemeral");
+				if (chat.plugins && chat.plugins["continuation"]) delete chat.plugins["continuation"];
+				if (typeof chat.unregisterConfigKeys === "function") chat.unregisterConfigKeys(["autoContinue"]);
+				this._installedOn = null;
+				return chat;
+			}
+		};
+	}
+	/** 兼容用单例（多实例场景请用工厂） */
+	var continuationPlugin = createContinuationPlugin();
+	//#endregion
 	exports.APIError = APIError;
 	exports.ChatService = ChatService;
 	exports.ConfigurationError = ConfigurationError;
@@ -1813,8 +2120,11 @@
 	exports.ParsingError = ParsingError;
 	exports.Pipeline = Pipeline;
 	exports.SystemPromptStore = SystemPromptStore;
+	exports.ValidationError = ValidationError;
 	exports.assembleMessages = assembleMessages;
 	exports.assertAdapter = assertAdapter;
+	exports.continuationPlugin = continuationPlugin;
+	exports.createContinuationPlugin = createContinuationPlugin;
 	exports.createModelRegistryPlugin = createModelRegistryPlugin;
 	exports.createOpenAIAdapter = createOpenAIAdapter;
 	exports.createToolCallingPlugin = createToolCallingPlugin;