my-ai-chat-framework 3.0.0 → 4.0.0

package/dist/my-ai-chat-framework.node.cjs.js

@@ -174,6 +174,69 @@ var MessageStore = class {
 	}
 };
 //#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 — 系统提示词存储
@@ -201,7 +264,7 @@ var SystemPromptStore = class {
 	* @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(),
@@ -217,7 +280,7 @@ var SystemPromptStore = class {
 	* @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];
 	}
 	/**
@@ -226,7 +289,7 @@ var SystemPromptStore = class {
 	* @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;
 	}
@@ -236,8 +299,8 @@ var SystemPromptStore = class {
 	* @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();
 	}
@@ -274,60 +337,6 @@ var SystemPromptStore = class {
 	}
 };
 //#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）
@@ -404,26 +413,37 @@ var SESSION_CONFIG_KEYS = [
 	"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();
 	}
 	/**
@@ -438,8 +458,16 @@ var ChatService = class extends EventEmitter {
 		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;
 	}
 	/**
@@ -454,13 +482,7 @@ var ChatService = class extends EventEmitter {
 	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({
@@ -482,37 +504,86 @@ var ChatService = class extends EventEmitter {
 	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() {
@@ -522,98 +593,81 @@ var ChatService = class extends EventEmitter {
 		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", {
@@ -679,6 +733,7 @@ var ChatService = class extends EventEmitter {
 			onProgress: options.onProgress || null,
 			onDone: options.onDone || null,
 			mergeToEntry: options.mergeToEntry || null,
+			signal: options.signal || null,
 			body: null,
 			result: null
 		};
@@ -704,22 +759,19 @@ var ChatService = class extends EventEmitter {
 			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());
@@ -734,7 +786,8 @@ var ChatService = class extends EventEmitter {
 			mergeToEntry: ctx.mergeToEntry,
 			config: ctx.config,
 			maxRetries: retryCfg.maxRetries ?? 0,
-			retryDelay: retryCfg.retryDelay ?? 1e3
+			retryDelay: retryCfg.retryDelay ?? 1e3,
+			signal: ctx.signal
 		});
 	}
 	_addUserMessage(userInput, addUser) {
@@ -750,9 +803,9 @@ var ChatService = class 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 };
+		const adapterOptions = { signal };
 		let placeholder = null;
 		let base = null;
 		if (isStream) {
@@ -780,7 +833,6 @@ var ChatService = class extends EventEmitter {
 				await new Promise((r) => setTimeout(r, retryDelay));
 			}
 			try {
-				this._isGenerating = true;
 				if (isStream) return await this._stream(body, adapterOptions, {
 					placeholder,
 					base,
@@ -791,22 +843,15 @@ var ChatService = class extends EventEmitter {
 				});
 				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;
 	}
 	/**
@@ -821,19 +866,14 @@ var ChatService = class extends EventEmitter {
 	*/
 	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 || ""),
@@ -887,13 +927,14 @@ var ChatService = class 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
+				params,
+				signal
 			});
 		} catch (err) {
 			if (err.name === "AbortError") {
@@ -902,8 +943,7 @@ var ChatService = class extends EventEmitter {
 			}
 			throw err;
 		} finally {
-			this._abortController = null;
-			this._isGenerating = false;
+			this._endRequest(id);
 		}
 	}
 	/**
@@ -919,7 +959,7 @@ var ChatService = class extends EventEmitter {
 			onProgress = params;
 			params = void 0;
 		}
-		this._abortController = new AbortController();
+		const { id, signal } = this._beginRequest();
 		try {
 			return await this._request({
 				userInput,
@@ -927,7 +967,8 @@ var ChatService = class extends EventEmitter {
 				isStream: true,
 				onProgress,
 				onDone,
-				params
+				params,
+				signal
 			});
 		} catch (err) {
 			if (err.name === "AbortError") {
@@ -936,21 +977,24 @@ var ChatService = class 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
+				params,
+				mergeToEntry,
+				signal
 			});
 		} catch (err) {
 			if (err.name === "AbortError") {
@@ -959,30 +1003,38 @@ var ChatService = class 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) {
+	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") {
@@ -991,8 +1043,7 @@ var ChatService = class extends EventEmitter {
 			}
 			throw err;
 		} finally {
-			this._abortController = null;
-			this._isGenerating = false;
+			this._endRequest(id);
 		}
 	}
 };
@@ -1043,26 +1094,23 @@ function isString(value) {
 //#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) {
@@ -1091,7 +1139,23 @@ function buildMultimodalContent(textContent, images, resolveImage) {
 	}
 	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 = [];
@@ -1099,15 +1163,8 @@ function toOpenAI({ messages, systemPrompts, capabilities, resolveImage }) {
 		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",
@@ -1143,7 +1200,7 @@ function toOpenAI({ messages, systemPrompts, capabilities, resolveImage }) {
 		}
 		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;
@@ -1153,22 +1210,71 @@ function toOpenAI({ messages, systemPrompts, capabilities, resolveImage }) {
 }
 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 || [],
@@ -1177,6 +1283,8 @@ var MessageFormatter = {
 		});
 	}
 };
+MessageFormatter.registerFilter("system-drop", filterSystemDrop, { priority: 900 });
+MessageFormatter.registerFilter("empty-drop", filterEmptyDrop, { priority: 910 });
 function assembleMessages(options = {}) {
 	return MessageFormatter.format({
 		...options,
@@ -1226,10 +1334,10 @@ var openaiAdapter = {
 	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,
@@ -1240,10 +1348,10 @@ var openaiAdapter = {
 				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;
@@ -1350,22 +1458,37 @@ var openaiAdapter = {
 			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;
@@ -1381,14 +1504,23 @@ var openaiAdapter = {
 							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",
@@ -1450,12 +1582,14 @@ function createOpenAIAdapter(options = {}) {
 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: [],
@@ -1481,11 +1615,18 @@ function createToolCallingPlugin(options = {}) {
 			* @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: {
@@ -1493,8 +1634,8 @@ function createToolCallingPlugin(options = {}) {
 						description,
 						parameters: {
 							type: "object",
-							properties: parameters,
-							required: Object.keys(parameters).filter((key) => parameters[key]?.required)
+							properties,
+							required: requiredKeys
 						}
 					}
 				};
@@ -1508,6 +1649,18 @@ function createToolCallingPlugin(options = {}) {
 					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;
@@ -1559,15 +1712,27 @@ function createToolCallingPlugin(options = {}) {
 							};
 						}
 						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,
@@ -1750,8 +1915,8 @@ function createModelRegistryPlugin(options = {}) {
 			* @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
@@ -1764,7 +1929,7 @@ function createModelRegistryPlugin(options = {}) {
 			* 列出所有已注册的模型名称
 			* @returns {Array<string>}
 			*/
-			chatService.listModels = () => {
+			const listModels = () => {
 				return [...this._registry.keys()];
 			};
 			this._syncCapabilities();
@@ -1787,6 +1952,17 @@ function createModelRegistryPlugin(options = {}) {
 					};
 				}
 			});
+			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;
@@ -1800,6 +1976,137 @@ function createModelRegistryPlugin(options = {}) {
 	};
 }
 //#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;
@@ -1810,8 +2117,11 @@ exports.NetworkError = NetworkError;
 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;