my-ai-chat-framework 2.7.0 → 4.0.0

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

@@ -140,6 +140,25 @@ var MessageStore = class {
 		return [];
 	}
 	/**
+	* 撤回到指定消息 id 的上一个用户消息，删除两者之间的所有消息
+	* 适用于重发
+	* @param {string} id — 目标消息 id
+	* @returns {Array} 被删除的消息列表
+	*/
+	undoToPreviousUser(id) {
+		let targetIndex = -1;
+		let previousUserIndex = -1;
+		for (let i = this._messages.length - 1; i >= 0; i--) {
+			if (this._messages[i].id === id) targetIndex = i;
+			if (targetIndex >= 0 && this._messages[i].role === "user") {
+				previousUserIndex = i;
+				break;
+			}
+		}
+		if (targetIndex >= 0 && previousUserIndex >= 0) return this._messages.splice(previousUserIndex + 1, targetIndex - previousUserIndex);
+		return [];
+	}
+	/**
 	* 更新消息：按 id 查找并合并 changes，不新增消息
 	* @param {string} id — 消息 id
 	* @param {Object} changes — 要合并的字段
@@ -155,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 — 系统提示词存储
@@ -182,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(),
@@ -198,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];
 	}
 	/**
@@ -207,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;
 	}
@@ -217,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();
 	}
@@ -255,151 +337,337 @@ var SystemPromptStore = class {
 	}
 };
 //#endregion
-//#region src/core/Errors.js
+//#region src/core/Pipeline.js
 /**
-* 自定义错误类
-* 用于区分不同类型的错误，方便用户通过 `error.name` 或 `instanceof` 处理
+* Pipeline —— 极简顺序管道（v3.0 提案 · 阶段 1）
+*
+* 三个概念（对照 pipeline-demo.html）：
+* - 小车 ctx   —— 本次请求的全部"状态"，车间之间只通过它交接
+* - 车间 stage —— { name, run(ctx) }，只干一件事，不认别的车间
+* - 调度 run()  —— for + await，顺序执行（线性，无"回程"；洋葱能力留给阶段 2 的 after 车间）
 */
-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 Pipeline = class {
+	constructor() {
+		this._stages = [];
 	}
-};
-var NetworkError = class extends Error {
 	/**
-	* @param {string} message - 错误消息
-	* @param {any} originalError - 原始错误对象或相关信息
+	* 注册一个车间（追加到末尾）。
+	* @param {{name: string, run: (ctx: object) => void | Promise<void>}} stage
+	* @returns {Pipeline} this，支持链式
 	*/
-	constructor(message, originalError) {
-		super(message);
-		this.name = "NetworkError";
-		this.originalError = originalError;
+	register(stage) {
+		if (!stage || typeof stage.run !== "function") throw new TypeError("Pipeline.register: stage 需要 { name, run(ctx) }，运行 run 必须是函数");
+		this._stages.push(stage);
+		return this;
 	}
-};
-var ConfigurationError = class extends Error {
-	/**
-	* @param {string} message - 错误消息
-	*/
-	constructor(message) {
-		super(message);
-		this.name = "ConfigurationError";
+	/** 按名字移除车间（移除不存在的名字是安全的） */
+	unregister(name) {
+		this._stages = this._stages.filter((s) => s.name !== name);
+		return this;
 	}
-};
-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;
+	/** 列出当前车间名（调试用） */
+	names() {
+		return this._stages.map((s) => s.name);
+	}
+	/** 把小车开过所有车间；返回 ctx（车间可改 ctx 上的字段） */
+	async run(ctx) {
+		for (const stage of this._stages) await stage.run(ctx);
+		return ctx;
 	}
 };
 //#endregion
 //#region src/core/ChatService.js
+/**
+* @typedef {Object} ChatAdapter 适配器协议（v3.0：写同级适配器只需实现这 4+1 个方法）
+* @property {Function} buildRequest  (messages, config, systemPrompts) => requestBody
+* @property {Function} send          (body, config, opts) => Promise<apiResponse>
+* @property {Function} stream        (body, config, onProgress, onDone, opts) => Promise<void>
+* @property {Function} parseResponse (apiResponse) => assistantMessage
+* @property {Function} [getRequestDefaults] () => 默认请求参数（可选）
+* @property {Function} [install]     (chatService, options) 插件式安装（可选）
+*/
+/**
+* @typedef {Object} PipelineContext 管道小车 ctx（public pipe 车间可见/可改的全部字段）
+* @property {Object}   options       原始请求选项
+* @property {*}        userInput     用户输入（可为 undefined）
+* @property {boolean}  addUser       是否已新增/将新增用户消息
+* @property {MessageStore} messages  消息列表（可读可改：push / unshift / update）
+* @property {SystemPromptStore} systemPrompts 系统提示词（可读可改）
+* @property {Object}   config        合并后的请求级配置（prepareInput 后生效）
+* @property {boolean}  isStream      本次是否流式
+* @property {Function|null} onProgress 流式进度回调
+* @property {Function|null} onDone     流式完成回调
+* @property {string|null} mergeToEntry 续写目标 id（null = 普通发送）
+* @property {*}        body          请求体（buildRequest 后产出）
+* @property {*}        result        最终结果（send 后产出）
+*/
+/**
+* @typedef {Object} PipeStage 车间（v3.0 公开扩展单元）
+* @property {string}   name      车间名（唯一，不能与内部车间重名）
+* @property {string}   [phase]   'beforeSend'（默认）| 'afterSend'
+* @property {Function} run       (ctx: PipelineContext) => void | Promise<void>
+*/
+var SESSION_CONFIG_KEYS = [
+	"model",
+	"temperature",
+	"maxTokens",
+	"modelParams",
+	"system",
+	"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 配置");
-		const temperature = this.config.modelParams?.temperature ?? this.config.temperature;
+		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();
+	}
+	/**
+	* 校验配置中的可校验字段（model 必填由构造器负责，这里只校验存在性）
+	* @throws {ConfigurationError}
+	*/
+	_assertValidConfig(cfg) {
+		const temperature = cfg.modelParams?.temperature ?? cfg.temperature;
 		if (temperature !== void 0 && (typeof temperature !== "number" || temperature < 0 || temperature > 2)) throw new ConfigurationError(`temperature 必须在 0-2 之间，当前值: ${temperature}`);
-		const maxTokens = this.config.modelParams?.maxTokens ?? this.config.maxTokens;
+		const maxTokens = cfg.modelParams?.maxTokens ?? cfg.maxTokens;
 		if (maxTokens !== void 0 && (typeof maxTokens !== "number" || maxTokens < 1 || !Number.isInteger(maxTokens))) throw new ConfigurationError(`maxTokens 必须为正整数，当前值: ${maxTokens}`);
-		if (typeof config.system === "string" && config.system.trim()) this.systemPrompts.set(config.system);
+		const model = cfg.model ?? cfg.modelParams?.model;
+		if (model !== void 0 && (typeof model !== "string" || !model.trim())) throw new ConfigurationError("model 必须是非空字符串");
 	}
-	use(plugin) {
-		plugin.install(this);
+	/**
+	* 安装插件。
+	* - 插件实现 `install(chat, options)`
+	* - 若 install 返回一个对象，会挂到 **`chat.plugins[plugin.name]`**（v4.0 命名空间，插件之间不会撞名）
+	* - 插件要提供卸载时，自己在返回值里带 `uninstall()`（或调用 `plugin.uninstall(chat)`）
+	* @returns {ChatService} this
+	*/
+	use(plugin, options = {}) {
+		const api = plugin.install(this, options);
+		if (plugin.name && api && typeof api === "object") this.plugins[plugin.name] = api;
 		return this;
 	}
-	setAdapter(adapter) {
-		this._adapter = adapter;
+	/**
+	* 往请求管道里挂一个"车间"。
+	* - phase 'beforeSend'（默认）：在内部 beforeRequest 钩子之后、构建请求体之前执行
+	* - phase 'afterSend'  ：在内部发送（流式/非流式）完成、结果落位之后执行（可改 ctx.result）
+	* 不注册任何车间 = 行为与版本 2.8.x 完全一致。
+	* @param {PipeStage} stage
+	* @returns {ChatService} this
+	* @throws {ConfigurationError} 参数非法 / 名字被占用 / 与内部车间重名
+	*/
+	pipe(stage) {
+		if (!stage || typeof stage !== "object" || typeof stage.run !== "function") throw new ConfigurationError("pipe: 需要 { name, phase?, run(ctx) }，run 必须是函数");
+		if (typeof stage.name !== "string" || !stage.name.trim()) throw new ConfigurationError("pipe: 需要 name（车间名，非空字符串）");
+		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({
+			name: stage.name,
+			phase,
+			run: stage.run
+		});
+		this._rebuildPipeline();
+		return this;
 	}
-	abort() {
-		if (this._abortController) this._abortController.abort();
+	/** 移除一个用户车间（移除不存在的名字是安全的）。@returns {ChatService} this */
+	unpipe(name) {
+		const before = this._userStages.length;
+		this._userStages = this._userStages.filter((s) => s.name !== name);
+		if (this._userStages.length !== before) this._rebuildPipeline();
+		return this;
 	}
-	get isGenerating() {
-		return this._isGenerating;
+	/** 查看当前管道里所有车间名（调试/说明用，含内部车间） */
+	get pipelineStages() {
+		return this._pipeline.names();
 	}
-	async continueLast() {
-		const target = this._prepareContinue();
-		this.messages.update(target.id, { prefix: true });
-		try {
-			await this._request({
-				addUser: false,
-				isStream: false,
-				mergeToEntry: target.id
+	/** 内部步骤名（顺序即执行顺序）：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();
+		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)
 			});
-			this.messages.update(target.id, {
-				_complete: true,
-				prefix: void 0,
-				_ephemeral: void 0
+		};
+		for (const name of INTERNAL_STAGES) {
+			if (!this._disabledStages.has(name)) p.register({
+				name,
+				run: this._stageOverrides.get(name) || defaults[name]
 			});
-			return target;
-		} catch (err) {
-			this.messages.update(target.id, { prefix: void 0 });
-			throw err;
+			if (name === "beforeSend") insertUsers("beforeSend");
+			if (name === "send") insertUsers("afterSend");
 		}
+		return p;
 	}
-	async continueLastStream(onProgress, onDone) {
-		const target = this._prepareContinue();
-		console.log("[DEBUG] continueLastStream target.id:", target.id);
-		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: void 0
-			});
-			return target;
-		} catch (err) {
-			this.messages.update(target.id, { prefix: void 0 });
-			throw err;
+	_rebuildPipeline() {
+		this._pipeline = this._buildPipeline();
+	}
+	setAdapter(adapter) {
+		assertAdapter(adapter);
+		this._adapter = adapter;
+	}
+	/**
+	* 中断请求（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._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
+		};
+	}
+	/** 内部：注销一个请求 */
+	_endRequest(id) {
+		this._activeRequests.delete(id);
+	}
+	/**
+	* 注册"运行时可改的配置字段"（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;
+	}
+	/** 注销运行时可改字段（插件卸载时调用）@returns {ChatService} this */
+	unregisterConfigKeys(keys) {
+		for (const k of Array.isArray(keys) ? keys : [keys]) this._extraConfigKeys.delete(k);
+		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，无法续写");
+	/** 当前允许在运行时修改的配置字段（内置基础字段 + 插件注册） */
+	get configKeys() {
+		return [...SESSION_CONFIG_KEYS, ...this._extraConfigKeys.keys()];
 	}
+	/**
+	* 运行时修改配置（仅"可改字段"：内置基础字段 + 插件注册字段）。
+	*
+	* - 运输层（apiKey/baseUrl/headers）：归适配器，要改就换适配器实例
+	* - 请求参数默认值：走适配器工厂 options 或请求级覆盖（chat.send(x, params)）
+	* - 插件自有配置：插件用 `registerConfigKeys` 登记后才可改（工厂 options 仍是首选）
+	*
+	* 与构造器一样经过校验，不能注入非法值。
+	* @throws {ConfigurationError} 非白名单字段、非法值、或插件校验器拒绝
+	*/
 	updateConfig(partial) {
+		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", {
@@ -407,36 +675,73 @@ var ChatService = class extends EventEmitter {
 			timestamp: Date.now()
 		});
 	}
-	async _request(options) {
-		let { userInput, addUser = true, isStream = false, onProgress, onDone, mergeToEntry } = options;
-		this.emit("sending", {
-			addUser,
-			userInput,
-			timestamp: Date.now()
-		});
-		this._addUserMessage(userInput, addUser);
-		await this._hooks.emitAsync("beforeRequest", {
-			messages: this.messages,
-			config: this.config,
-			options
-		});
-		if (this.config.ephemeralContinue && !mergeToEntry) {
-			const msgs = this.messages.getAll();
-			const last = msgs[msgs.length - 1];
-			if (last && last.prefix && (last.role === "assistant" || last._ephemeral)) mergeToEntry = last.id;
+	/**
+	* 合并请求参数（近者优先）：
+	*   适配器默认(getRequestDefaults) ← 会话配置(this.config) ← 本次覆盖(params)
+	* modelParams 深层合并；平铺便捷键（temperature/maxTokens/reasoningEffort）自动折叠进 modelParams
+	*/
+	_mergeRequestConfig(params = {}) {
+		const adapterDefaults = this._adapter?.getRequestDefaults?.() || {};
+		const requestConfig = {
+			...adapterDefaults,
+			...this.config,
+			...params
+		};
+		const modelParams = {
+			...adapterDefaults.modelParams || {},
+			...this.config.modelParams || {},
+			...params.modelParams || {}
+		};
+		for (const key of [
+			"temperature",
+			"maxTokens",
+			"reasoningEffort"
+		]) {
+			const value = params[key] ?? this.config[key] ?? adapterDefaults[key];
+			if (value !== void 0) modelParams[key] = value;
 		}
-		const body = this._adapter.buildRequest(this.messages.getAll(), this.config, this.systemPrompts.getEnabled());
-		const retryCfg = this.config.retry || {};
+		requestConfig.modelParams = modelParams;
+		return requestConfig;
+	}
+	/**
+	* 内部调度（v3.0 提案 · 阶段 1）：造一辆小车 ctx，开过内部管道，返回结果。
+	* 行为与旧版 _request 完全一致，只是把固定线拆成了车间（见 _stage* 方法）。
+	*
+	* ctx 字段（车间可见）：
+	*   options       —— 原始请求选项
+	*   userInput     —— 用户输入
+	*   addUser       —— 是否新增用户消息
+	*   messages      —— MessageStore（可读可改）
+	*   systemPrompts —— SystemPromptStore
+	*   config        —— 合并后的请求级配置（prepareInput 车间产出）
+	*   isStream      —— 本次是否流式
+	*   onProgress    —— 流式进度回调（可为 null）
+	*   onDone        —— 流式完成回调（可为 null）
+	*   mergeToEntry  —— 续写目标 id（空 = 普通发送）
+	*   body          —— adapter 构建出的请求体（buildRequest 车间产出）
+	*   result        —— 最终结果（send 车间产出）
+	*/
+	async _request(options = {}) {
+		const ctx = {
+			options,
+			userInput: options.userInput,
+			addUser: options.addUser !== false,
+			messages: this.messages,
+			systemPrompts: this.systemPrompts,
+			config: null,
+			isStream: !!options.isStream,
+			onProgress: options.onProgress || null,
+			onDone: options.onDone || null,
+			mergeToEntry: options.mergeToEntry || null,
+			signal: options.signal || null,
+			body: null,
+			result: null
+		};
 		try {
-			return await this._withRetry(body, {
-				isStream,
-				onProgress,
-				onDone,
-				mergeToEntry,
-				maxRetries: retryCfg.maxRetries ?? 0,
-				retryDelay: retryCfg.retryDelay ?? 1e3
-			});
+			await this._pipeline.run(ctx);
+			return ctx.result;
 		} catch (error) {
+			if (error.name === "AbortError") throw error;
 			this.emit("error", {
 				error,
 				timestamp: Date.now()
@@ -444,6 +749,47 @@ var ChatService = class extends EventEmitter {
 			throw error;
 		}
 	}
+	/** 车间 1：加用户消息 → 合并请求参数 → 广播 sending */
+	async _stagePrepareInput(ctx) {
+		this._addUserMessage(ctx.userInput, ctx.addUser);
+		ctx.config = this._mergeRequestConfig(ctx.options.params);
+		this.emit("sending", {
+			addUser: ctx.addUser,
+			userInput: ctx.userInput,
+			timestamp: Date.now()
+		});
+	}
+	/**
+	* 车间 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());
+	}
+	/** 车间 5：发送（流式/非流式 + 重试 + 占位消息 + _processResponse 工具钩子） */
+	async _stageSend(ctx) {
+		const retryCfg = this.config.retry || {};
+		ctx.result = await this._withRetry(ctx.body, {
+			isStream: ctx.isStream,
+			onProgress: ctx.onProgress,
+			onDone: ctx.onDone,
+			mergeToEntry: ctx.mergeToEntry,
+			config: ctx.config,
+			maxRetries: retryCfg.maxRetries ?? 0,
+			retryDelay: retryCfg.retryDelay ?? 1e3,
+			signal: ctx.signal
+		});
+	}
 	_addUserMessage(userInput, addUser) {
 		if (addUser && userInput !== void 0) {
 			const msg = typeof userInput === "string" ? {
@@ -457,9 +803,9 @@ var ChatService = class extends EventEmitter {
 		}
 	}
 	/** retry 循环，占位消息只 push 一次 */
-	async _withRetry(body, { isStream, onProgress, onDone, mergeToEntry, 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) {
@@ -487,54 +833,53 @@ 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,
 					mergeToEntry,
 					onProgress,
-					onDone
+					onDone,
+					config
 				});
 				else {
-					const resp = await this._adapter.send(body, this.config, adapterOptions);
-					let result = this._handleResult(this._adapter.parseResponse(resp), mergeToEntry);
-					if (this._processResponse && !mergeToEntry) result = await this._processResponse(result, { isStream: false });
-					return result;
+					const resp = await this._adapter.send(body, config, adapterOptions);
+					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;
 	}
-	/** 流式：ChatService 维护占位，adapter 只管解析 */
-	async _stream(body, adapterOptions, { placeholder, base, mergeToEntry, onProgress, onDone }) {
+	/**
+	* 流式处理：ChatService 维护占位消息，adapter 只负责解析 SSE
+	*
+	* 参数说明：
+	* - placeholder：流式期间实时更新的目标消息（续写时 = target 本身，普通发送时 = 新建的空消息）
+	* - base：续写时保存的旧内容快照，用于和 API 新内容拼接
+	* - mergeToEntry：续写目标的 id，有值时走续写逻辑
+	* - onProgress：外部回调，每收到一个 chunk 触发
+	* - onDone：流结束回调
+	*/
+	async _stream(body, adapterOptions, { placeholder, base, mergeToEntry, onProgress, onDone, config }) {
 		let finalMsg = null;
-		await this._adapter.stream(body, this.config, (snap) => {
-			placeholder.content = snap.content || "";
-			if (snap.reasoningContent) placeholder.reasoningContent = snap.reasoningContent;
+		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 || ""),
-					_complete: true
+					_complete: true,
+					_ephemeral: false,
+					prefix: void 0
 				};
 				if (final.reasoningContent) changes.reasoningContent = base.reasoning + final.reasoningContent;
 				if (final.toolCalls) changes.toolCalls = final.toolCalls;
@@ -561,7 +906,9 @@ var ChatService = class extends EventEmitter {
 			}
 			const changes = {
 				content: (entry.content || "") + (assistantMsg.content || ""),
-				_complete: true
+				_complete: true,
+				_ephemeral: false,
+				prefix: void 0
 			};
 			if (assistantMsg.reasoningContent) changes.reasoningContent = (entry.reasoningContent || "") + assistantMsg.reasoningContent;
 			if (assistantMsg.toolCalls) changes.toolCalls = assistantMsg.toolCalls;
@@ -574,61 +921,148 @@ var ChatService = class extends EventEmitter {
 		this.emit("message", assistantMsg);
 		return assistantMsg;
 	}
-	async send(userInput) {
-		this._abortController = new AbortController();
+	/**
+	* 发送消息。
+	* @param {string|Object} userInput - 用户输入
+	* @param {Object} [params] - 请求级参数覆盖（model/temperature/modelParams 等，仅本次生效）
+	*/
+	async send(userInput, params) {
+		const { id, signal } = this._beginRequest();
 		try {
 			return await this._request({
 				userInput,
 				addUser: true,
-				isStream: false
+				isStream: false,
+				params,
+				signal
 			});
+		} catch (err) {
+			if (err.name === "AbortError") {
+				this.emit("aborted", { timestamp: Date.now() });
+				return;
+			}
+			throw err;
 		} finally {
-			this._abortController = null;
-			this._isGenerating = false;
+			this._endRequest(id);
 		}
 	}
-	async stream(userInput, onProgress, onDone) {
-		this._abortController = new AbortController();
+	/**
+	* 流式发送。
+	* @param {string|Object} userInput - 用户输入
+	* @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+	* @param {Function} [onProgress] - 流式进度回调
+	* @param {Function} [onDone] - 流式完成回调
+	*/
+	async stream(userInput, params, onProgress, onDone) {
+		if (typeof params === "function") {
+			onDone = onProgress;
+			onProgress = params;
+			params = void 0;
+		}
+		const { id, signal } = this._beginRequest();
 		try {
 			return await this._request({
 				userInput,
 				addUser: true,
 				isStream: true,
 				onProgress,
-				onDone
+				onDone,
+				params,
+				signal
 			});
+		} catch (err) {
+			if (err.name === "AbortError") {
+				this.emit("aborted", { timestamp: Date.now() });
+				return;
+			}
+			throw err;
 		} finally {
-			this._abortController = null;
-			this._isGenerating = false;
+			this._endRequest(id);
 		}
 	}
-	async sendExisting() {
-		this._abortController = new AbortController();
+	/**
+	* 重发当前消息（不加用户消息）。
+	* @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+	* @param {Object} [options] - { mergeToEntry } 可选：把结果合并进指定的已有消息（续写等场景）
+	*/
+	async sendExisting(params, options = {}) {
+		const mergeToEntry = options?.mergeToEntry || null;
+		const { id, signal } = this._beginRequest();
 		try {
 			return await this._request({
 				addUser: false,
-				isStream: false
+				isStream: false,
+				params,
+				mergeToEntry,
+				signal
 			});
+		} catch (err) {
+			if (err.name === "AbortError") {
+				this.emit("aborted", { timestamp: Date.now() });
+				return;
+			}
+			throw err;
 		} finally {
-			this._abortController = null;
-			this._isGenerating = false;
+			this._endRequest(id);
 		}
 	}
-	async sendExistingStream(onProgress, onDone) {
-		this._abortController = new AbortController();
+	/**
+	* 流式重发（不加用户消息）。
+	* @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+	* @param {Object} [options] - { mergeToEntry } 可选：把结果合并进指定的已有消息
+	* @param {Function} [onProgress] - 流式进度回调
+	* @param {Function} [onDone] - 流式完成回调
+	*/
+	async sendExistingStream(params, options, onProgress, onDone) {
+		if (typeof params === "function") {
+			onDone = options;
+			onProgress = params;
+			options = {};
+			params = void 0;
+		} else if (typeof options === "function") {
+			onDone = onProgress;
+			onProgress = options;
+			options = {};
+		}
+		const mergeToEntry = options?.mergeToEntry || null;
+		const { id, signal } = this._beginRequest();
 		try {
 			return await this._request({
 				addUser: false,
 				isStream: true,
 				onProgress,
-				onDone
+				onDone,
+				params,
+				mergeToEntry,
+				signal
 			});
+		} catch (err) {
+			if (err.name === "AbortError") {
+				this.emit("aborted", { timestamp: Date.now() });
+				return;
+			}
+			throw err;
 		} finally {
-			this._abortController = null;
-			this._isGenerating = false;
+			this._endRequest(id);
 		}
 	}
 };
+/**
+* 校验 adapter 是否满足协议（v3.0 · 阶段 3）。
+* 缺少必要方法时抛 ConfigurationError，并列出缺少的方法名——写"同级适配器"不再靠猜。
+* @param {*} adapter
+* @throws {ConfigurationError}
+*/
+function assertAdapter(adapter) {
+	if (!adapter || typeof adapter !== "object") throw new ConfigurationError("setAdapter: adapter 必须是对象（如 openaiAdapter / createOpenAIAdapter() 实例）");
+	const missing = [
+		"buildRequest",
+		"send",
+		"stream",
+		"parseResponse"
+	].filter((k) => typeof adapter[k] !== "function");
+	if (missing.length) throw new ConfigurationError(`setAdapter: adapter 缺少必要方法: ${missing.join(", ")}（协议见 ChatService.js 顶部的 @typedef ChatAdapter）`);
+}
 //#endregion
 //#region src/utils/url.js
 /**
@@ -660,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) {
@@ -708,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 = [];
@@ -716,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",
@@ -760,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;
@@ -770,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 || [],
@@ -794,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,
@@ -806,17 +1297,48 @@ function assembleMessages(options = {}) {
 * OpenAI 兼容 API 适配器
 * 支持 DeepSeek 等完全兼容 OpenAI 接口的服务
 */
+var TRANSPORT_KEYS = [
+	"apiKey",
+	"baseUrl",
+	"apiUrl",
+	"path",
+	"headers"
+];
 var openaiAdapter = {
 	name: "openai",
-	install(chatService) {
+	install(chatService, options = {}) {
+		if (this._transport) this._transport = {
+			...this._transport,
+			...options
+		};
 		chatService.setAdapter(this);
 	},
+	_resolveConfig(config) {
+		const transport = this._transport || {};
+		const resolved = {
+			...config,
+			...transport
+		};
+		if (transport.modelParams) resolved.modelParams = {
+			...transport.modelParams,
+			...config.modelParams || {}
+		};
+		return resolved;
+	},
+	getRequestDefaults() {
+		if (!this._transport) return {};
+		const defaults = {};
+		for (const [key, value] of Object.entries(this._transport)) if (!TRANSPORT_KEYS.includes(key) && value !== void 0) defaults[key] = value;
+		return defaults;
+	},
 	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)");
-		const temperature = config.modelParams?.temperature ?? config.temperature ?? .7;
-		const maxTokens = config.modelParams?.maxTokens ?? config.maxTokens ?? 2e3;
-		const reasoningEffort = config.modelParams?.reasoningEffort ?? config.reasoningEffort;
+		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;
+		const maxTokens = mp.maxTokens ?? config.maxTokens;
+		const reasoningEffort = mp.reasoningEffort ?? config.reasoningEffort;
 		const requestBody = {
 			model,
 			messages: MessageFormatter.format({
@@ -826,15 +1348,34 @@ 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;
+		if (mp.stop !== void 0) requestBody.stop = mp.stop;
+		if (mp.responseFormat !== void 0) requestBody.response_format = mp.responseFormat;
+		if (mp.seed !== void 0) requestBody.seed = mp.seed;
 		if (config.tools && Array.isArray(config.tools) && config.tools.length > 0) {
 			requestBody.tools = config.tools;
 			requestBody.tool_choice = "auto";
 		}
-		if (reasoningEffort && model === "deepseek-reasoner") requestBody.reasoning_effort = reasoningEffort;
+		if (reasoningEffort !== void 0) requestBody.reasoning_effort = reasoningEffort;
+		const consumedKeys = new Set([
+			"model",
+			"temperature",
+			"maxTokens",
+			"reasoningEffort",
+			"topP",
+			"frequencyPenalty",
+			"presencePenalty",
+			"stop",
+			"responseFormat",
+			"seed"
+		]);
+		for (const [key, value] of Object.entries(mp)) if (!consumedKeys.has(key) && value !== void 0) requestBody[key] = value;
 		return requestBody;
 	},
 	_getUrl(config) {
@@ -847,6 +1388,7 @@ var openaiAdapter = {
 	},
 	async send(requestBody, config, options = {}) {
 		try {
+			config = this._resolveConfig(config);
 			const url = this._getUrl(config);
 			const headers = {
 				"Content-Type": "application/json",
@@ -881,6 +1423,7 @@ var openaiAdapter = {
 		return internal;
 	},
 	async stream(requestBody, config, onProgress, onDone, options = {}) {
+		config = this._resolveConfig(config);
 		const streamBody = {
 			...requestBody,
 			stream: true
@@ -915,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;
@@ -946,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;
-					onProgress({ ...accumulated });
+					if (delta.reasoning_content) {
+						accumulated.reasoningContent += delta.reasoning_content;
+						deltaInfo.reasoningContent = delta.reasoning_content;
+					}
+					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",
@@ -974,165 +1541,246 @@ var openaiAdapter = {
 		throw new APIError(errorMessage, response.status, null, errorText);
 	}
 };
+/**
+* 创建 OpenAI 兼容适配器实例（工厂）。
+*
+* 与单例 openaiAdapter 的区别：每个实例自持一份运输配置（apiKey/baseUrl/apiUrl/path/headers），
+* 互不干扰——解决"同一适配器装到多个 ChatService 互相覆盖"的单例陷阱。
+*
+* 用法：
+*   const adapter = createOpenAIAdapter({ apiKey, baseUrl, modelParams: { temperature: 0.8 } });
+*   const chat = new ChatService({ adapter, model: 'deepseek-chat' });
+*   chat.use(adapter);  // 或直接 new ChatService({ adapter })
+*
+* 非运输键（model/modelParams/messageFormat/resolveImage/capabilities 等）会作为
+* "请求默认参数"供会话层合并，单次请求仍可覆盖。
+*/
+function createOpenAIAdapter(options = {}) {
+	return {
+		...openaiAdapter,
+		_transport: { ...options }
+	};
+}
 //#endregion
 //#region src/plugins/tool-calling.js
 /**
 * 工具调用插件
 * 功能：拦截助手消息中的 tool_calls，执行对应的工具，将结果作为 tool 消息加入对话，
 *       然后自动继续对话（通过 sendExisting / sendExistingStream），直到没有新的工具调用。
-* 
+*
 * 设计要点：
 * - 支持普通请求和流式请求（通过 isStream 标志区分）
 * - 支持多次工具调用循环（maxIterations 防止无限循环）
-* - 串行执行工具（可后续升级为并行）
+* - 并行执行工具
 * - 工具执行失败时，仍然返回错误信息给 AI，而不是中断整个流程
 * - 触发 tool-error 事件，方便用户监听工具执行异常
+*
+* 注意：请使用 createToolCallingPlugin() 工厂创建实例。
+* 默认导出的 toolCallingPlugin 是兼容用的模块级单例，装到多个 ChatService
+* 实例会互相覆盖（executor 表、工具定义、配置），新代码不要直接用单例。
+*/
+var toolCallingPlugin = createToolCallingPlugin();
+/**
+* 创建工具调用插件实例（工厂）。
+* @param {Object} [options] — { timeout?, maxIterations? }
+*   - 两者**默认都不限制**：不传就是"循环到没有工具调用为止 / 不超时"
+*   - 想限制才传（这是使用者的选择，不是框架替你做的决定）
 */
-var toolCallingPlugin = {
-	name: "tool-calling",
-	maxIterations: 5,
-	install(chatService) {
-		this.chatService = chatService;
-		this._tools = /* @__PURE__ */ new Map();
-		if (!chatService.config.tools) chatService.config.tools = [];
-		/**
-		* 注册工具
-		* @param {string} name - 工具名称（唯一标识）
-		* @param {string} description - 工具描述（告诉 AI 何时调用）
-		* @param {Function} executor - 异步执行函数，接收参数对象，返回结果（字符串或对象）
-		* @param {Object} parameters - JSON Schema 参数定义（可选，默认为空对象）
-		* @returns {ChatService} 返回 chatService 实例，支持链式调用
-		*/
-		chatService.registerTool = (name, description, executor, parameters = {}) => {
-			this._tools.set(name, {
-				executor,
-				description
+function createToolCallingPlugin(options = {}) {
+	return {
+		name: "tool-calling",
+		maxIterations: options.maxIterations ?? Infinity,
+		_options: { ...options },
+		_tools: /* @__PURE__ */ new Map(),
+		_toolDefs: [],
+		chatService: null,
+		install(chatService, options = {}) {
+			this._options = {
+				...this._options,
+				...options
+			};
+			this.chatService = chatService;
+			chatService.pipe({
+				name: "tool-calling-inject",
+				phase: "beforeSend",
+				run: ({ config }) => {
+					if (this._toolDefs.length) config.tools = this._toolDefs;
+				}
 			});
-			const toolDefinition = {
-				type: "function",
-				function: {
-					name,
-					description,
-					parameters: {
-						type: "object",
-						properties: parameters,
-						required: Object.keys(parameters).filter((key) => parameters[key]?.required)
+			/**
+			* 注册工具
+			* @param {string} name - 工具名称（唯一标识）
+			* @param {string} description - 工具描述（告诉 AI 何时调用）
+			* @param {Function} executor - 异步执行函数，接收参数对象，返回结果（字符串或对象）
+			* @param {Object} parameters - JSON Schema 参数定义（可选，默认为空对象）
+			* @returns {ChatService} 返回 chatService 实例，支持链式调用
+			*/
+			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: {
+						name,
+						description,
+						parameters: {
+							type: "object",
+							properties,
+							required: requiredKeys
+						}
 					}
+				};
+				if (!this._toolDefs.find((t) => t.function.name === name)) this._toolDefs.push(toolDefinition);
+				return chatService;
+			};
+			chatService.pipe({
+				name: "tool-calling-loop",
+				phase: "afterSend",
+				run: async (ctx) => {
+					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)
 			};
-			if (!chatService.config.tools.find((t) => t.function.name === name)) chatService.config.tools.push(toolDefinition);
-			return chatService;
-		};
-		chatService._processResponse = async (response, { isStream, onProgress, onDone }) => {
-			return this._handleWithTools(response, isStream, onProgress, onDone);
-		};
-	},
-	async _handleWithTools(initialResponse, isStream, onProgress, onDone) {
-		const self = this;
-		const chat = this.chatService;
-		let iteration = 0;
-		/**
-		* 递归处理工具调用
-		* @param {Object} initialResponse - 初始 AI 响应（可能是第一次请求的响应）
-		* @returns {Promise<Object>} 最终 AI 响应（不含 tool_calls）
-		*/
-		async function processResponse(initialResponse) {
-			let lastResponse = initialResponse;
-			while (iteration < self.maxIterations) {
-				const toolCalls = lastResponse?.toolCalls;
-				if (!toolCalls || toolCalls.length === 0) break;
-				iteration++;
-				const toolResults = await Promise.all(toolCalls.map(async (call) => {
-					const toolName = call.function?.name;
-					let args;
-					try {
-						args = JSON.parse(call.function?.arguments || "{}");
-					} catch (parseErr) {
-						chat.emit("tool-error", {
-							toolName: toolName || "unknown",
-							error: parseErr,
-							toolCallId: call.id,
-							stage: "parse",
-							timestamp: Date.now()
-						});
-						return {
-							tool_call_id: call.id,
-							error: `参数解析失败: ${parseErr.message}`,
-							success: false
-						};
-					}
-					const tool = self._tools.get(toolName);
-					if (!tool) {
-						chat.emit("tool-error", {
-							toolName,
-							error: /* @__PURE__ */ new Error(`Tool not registered: ${toolName}`),
-							toolCallId: call.id,
-							stage: "lookup",
-							timestamp: Date.now()
-						});
-						return {
-							tool_call_id: call.id,
-							error: `工具 ${toolName} 未注册`,
-							success: false
-						};
-					}
-					try {
-						const toolTimeout = chat.config.toolTimeout;
-						let execPromise = tool.executor(args);
-						if (toolTimeout && typeof toolTimeout === "number" && toolTimeout > 0) {
-							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]);
+		},
+		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;
+			const chat = this.chatService;
+			let iteration = 0;
+			/**
+			* 递归处理工具调用
+			* @param {Object} initialResponse - 初始 AI 响应（可能是第一次请求的响应）
+			* @returns {Promise<Object>} 最终 AI 响应（不含 tool_calls）
+			*/
+			async function processResponse(initialResponse) {
+				let lastResponse = initialResponse;
+				while (iteration < self.maxIterations) {
+					const toolCalls = lastResponse?.toolCalls;
+					if (!toolCalls || toolCalls.length === 0) break;
+					iteration++;
+					const toolResults = await Promise.all(toolCalls.map(async (call) => {
+						const toolName = call.function?.name;
+						let args;
+						try {
+							args = JSON.parse(call.function?.arguments || "{}");
+						} catch (parseErr) {
+							chat.emit("tool-error", {
+								toolName: toolName || "unknown",
+								error: parseErr,
+								toolCallId: call.id,
+								stage: "parse",
+								timestamp: Date.now()
+							});
+							return {
+								tool_call_id: call.id,
+								error: `参数解析失败: ${parseErr.message}`,
+								success: false
+							};
 						}
-						const result = await execPromise;
-						chat.emit("tool-success", {
-							toolName,
-							result,
-							toolCallId: call.id,
-							timestamp: Date.now()
-						});
-						return {
-							tool_call_id: call.id,
-							content: typeof result === "string" ? result : JSON.stringify(result),
-							success: true
-						};
-					} catch (err) {
-						const stage = err.name === "ToolTimeoutError" ? "timeout" : "execute";
-						chat.emit("tool-error", {
-							toolName,
-							error: err,
-							toolCallId: call.id,
-							stage,
-							timestamp: Date.now()
-						});
-						return {
-							tool_call_id: call.id,
-							error: err.message,
-							success: false
-						};
+						const tool = self._tools.get(toolName);
+						if (!tool) {
+							chat.emit("tool-error", {
+								toolName,
+								error: /* @__PURE__ */ new Error(`Tool not registered: ${toolName}`),
+								toolCallId: call.id,
+								stage: "lookup",
+								timestamp: Date.now()
+							});
+							return {
+								tool_call_id: call.id,
+								error: `工具 ${toolName} 未注册`,
+								success: false
+							};
+						}
+						try {
+							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";
+								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,
+								toolCallId: call.id,
+								timestamp: Date.now()
+							});
+							return {
+								tool_call_id: call.id,
+								content: typeof result === "string" ? result : JSON.stringify(result),
+								success: true
+							};
+						} catch (err) {
+							const stage = err.name === "ToolTimeoutError" ? "timeout" : "execute";
+							chat.emit("tool-error", {
+								toolName,
+								error: err,
+								toolCallId: call.id,
+								stage,
+								timestamp: Date.now()
+							});
+							return {
+								tool_call_id: call.id,
+								error: err.message,
+								success: false
+							};
+						}
+					}));
+					for (const tr of toolResults) {
+						const content = tr.success ? tr.content : tr.error || "工具执行失败";
+						chat.messages.addTool(content, tr.tool_call_id);
 					}
-				}));
-				for (const tr of toolResults) {
-					const content = tr.success ? tr.content : tr.error || "工具执行失败";
-					chat.messages.addTool(content, tr.tool_call_id);
-				}
-				if (isStream) await new Promise((resolve) => {
-					chat.sendExistingStream((chunk) => {
-						if (onProgress) onProgress(chunk);
-						lastResponse = chunk;
-					}, (final) => {
-						lastResponse = final;
-						resolve();
+					if (isStream) await new Promise((resolve) => {
+						chat.sendExistingStream((chunk) => {
+							if (onProgress) onProgress(chunk);
+							lastResponse = chunk;
+						}, (final) => {
+							lastResponse = final;
+							resolve();
+						});
 					});
-				});
-				else lastResponse = await chat.sendExisting();
+					else lastResponse = await chat.sendExisting();
+				}
+				return lastResponse;
 			}
-			return lastResponse;
+			return await processResponse(initialResponse);
 		}
-		return await processResponse(initialResponse);
-	}
-};
+	};
+}
 //#endregion
 //#region src/plugins/model-registry.js
 /**
@@ -1239,56 +1887,225 @@ var DEFAULT_CAPABILITIES = {
 	reasoning: false,
 	vision: false
 };
-var modelRegistryPlugin = {
-	name: "model-registry",
-	install(chatService) {
-		this.chat = chatService;
-		this._registry = new Map(Object.entries(BUILTIN_MODELS));
-		/**
-		* 注册/覆盖一个模型的能力标签
-		* @param {string} name — 模型名称
-		* @param {Object} capabilities — 能力标签对象（部分字段即可，未提供的取默认值）
-		* @returns {ChatService}
-		*/
-		chatService.registerModel = (name, capabilities = {}) => {
-			if (!name || typeof name !== "string" || !name.trim()) throw new Error("[model-registry] 模型名称必须是非空字符串");
-			const merged = {
-				...DEFAULT_CAPABILITIES,
-				...capabilities
+/**
+* 注意：请使用 createModelRegistryPlugin() 工厂创建实例。
+* 默认导出的 modelRegistryPlugin 是兼容用的模块级单例，装到多个 ChatService
+* 实例会互相覆盖（注册表、实例引用），新代码不要直接用单例。
+*/
+var modelRegistryPlugin = createModelRegistryPlugin();
+/**
+* 创建模型能力注册表插件实例（工厂）。
+* @param {Object} [options] — { models: { '模型名': capabilities } }（合并进内置表）
+*/
+function createModelRegistryPlugin(options = {}) {
+	return {
+		name: "model-registry",
+		_options: { ...options },
+		_registry: new Map([...Object.entries(BUILTIN_MODELS), ...Object.entries(options.models || {})]),
+		chat: null,
+		install(chatService, options = {}) {
+			this._options = {
+				...this._options,
+				...options
 			};
-			this._registry.set(name.trim(), merged);
-			if (chatService.config.model === name.trim()) this._syncCapabilities();
-			return chatService;
-		};
-		/**
-		* 列出所有已注册的模型名称
-		* @returns {Array<string>}
-		*/
-		chatService.listModels = () => {
-			return [...this._registry.keys()];
-		};
-		this._syncCapabilities();
-		chatService.on("config-updated", ({ changes }) => {
-			if ("model" in changes) this._syncCapabilities();
-			if ("capabilities" in changes && !("model" in changes)) {
-				const current = this._lookupCapabilities();
-				if (current) chatService.config.capabilities = {
-					...current,
-					...changes.capabilities
+			this.chat = chatService;
+			/**
+			* 注册/覆盖一个模型的能力标签
+			* @param {string} name — 模型名称
+			* @param {Object} capabilities — 能力标签对象（部分字段即可，未提供的取默认值）
+			* @returns {ChatService}
+			*/
+			const registerModel = (name, capabilities = {}) => {
+				if (!name || typeof name !== "string" || !name.trim()) throw new ValidationError("[model-registry] 模型名称必须是非空字符串");
+				const merged = {
+					...DEFAULT_CAPABILITIES,
+					...capabilities
 				};
-			}
-		});
-	},
-	_lookupCapabilities() {
-		const model = this.chat.config.model;
-		if (!model) return null;
-		return this._registry.get(model) || null;
-	},
-	_syncCapabilities() {
-		const caps = this._lookupCapabilities();
-		if (caps) this.chat.config.capabilities = { ...caps };
-	}
-};
+				this._registry.set(name.trim(), merged);
+				if (chatService.config.model === name.trim()) this._syncCapabilities();
+				return chatService;
+			};
+			/**
+			* 列出所有已注册的模型名称
+			* @returns {Array<string>}
+			*/
+			const listModels = () => {
+				return [...this._registry.keys()];
+			};
+			this._syncCapabilities();
+			chatService.pipe({
+				name: "model-registry-caps",
+				phase: "beforeSend",
+				run: ({ config }) => {
+					if (!config.model) return;
+					const caps = this._registry.get(config.model);
+					if (caps) config.capabilities = { ...caps };
+				}
+			});
+			chatService.on("config-updated", ({ changes }) => {
+				if ("model" in changes) this._syncCapabilities();
+				if ("capabilities" in changes && !("model" in changes)) {
+					const current = this._lookupCapabilities();
+					if (current) chatService.config.capabilities = {
+						...current,
+						...changes.capabilities
+					};
+				}
+			});
+			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;
+			if (!model) return null;
+			return this._registry.get(model) || null;
+		},
+		_syncCapabilities() {
+			const caps = this._lookupCapabilities();
+			if (caps) this.chat.config.capabilities = { ...caps };
+		}
+	};
+}
+//#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;
@@ -1298,8 +2115,16 @@ exports.MessageFormatter = MessageFormatter;
 exports.MessageStore = MessageStore;
 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;
 exports.modelRegistryPlugin = modelRegistryPlugin;
 exports.openaiAdapter = openaiAdapter;
 exports.toolCallingPlugin = toolCallingPlugin;