my-ai-chat-framework 2.0.0 → 3.0.0

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

@@ -1,13 +1,11 @@
 (function(global, factory) {
 	typeof exports === "object" && typeof module !== "undefined" ? factory(exports) : typeof define === "function" && define.amd ? define(["exports"], factory) : (global = typeof globalThis !== "undefined" ? globalThis : global || self, factory(global.AIChatFramework = {}));
 })(this, function(exports) {
-	Object.defineProperties(exports, {
-		__esModule: { value: true },
-		[Symbol.toStringTag]: { value: "Module" }
-	});
+	Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 	//#region src/core/EventEmitter.js
 	/**
 	* 极简事件发射器
+	* 支持同步/异步事件，handler 返回 Promise 时自动 await
 	*/
 	var EventEmitter = class {
 		constructor() {
@@ -24,6 +22,9 @@
 			if (handlers.length) this._events.set(event, handlers);
 			else this._events.delete(event);
 		}
+		/**
+		* 同步触发事件
+		*/
 		emit(event, data) {
 			if (!this._events.has(event)) return;
 			for (const handler of this._events.get(event)) try {
@@ -32,6 +33,18 @@
 				console.error(`事件 ${event} 处理出错:`, err);
 			}
 		}
+		/**
+		* 异步触发事件，逐个 await handler
+		* handler 返回 Promise 时自动等待
+		*/
+		async emitAsync(event, data) {
+			if (!this._events.has(event)) return;
+			for (const handler of this._events.get(event)) try {
+				await handler(data);
+			} catch (err) {
+				console.error(`事件 ${event} 处理出错:`, err);
+			}
+		}
 	};
 	//#endregion
 	//#region src/core/MessageStore.js
@@ -42,6 +55,10 @@
 	*   id?: string,
 	*   role: 'user'|'assistant'|'system'|'tool',
 	*   content: string,
+	*   images?: Array<string>,   // 图片引用（URL / id），框架不存储图片数据
+	*   _ephemeral?: boolean,     // 临时消息：仅底部连续时参与请求，续写后转正
+	*   _complete?: boolean,      // 流式是否完成（false=未完成/中断）
+	*   prefix?: boolean,         // 前缀续写标记
 	*   toolCalls?: Array,
 	*   toolCallId?: string,
 	*   timestamp?: number,
@@ -91,6 +108,22 @@
 				metadata
 			});
 		}
+		/**
+		* 快速添加一次性的、带续写标记的 assistant 消息
+		* 适用于思维链引导、临时注入等场景
+		* @param {string} content  — 引导内容
+		* @param {Object} [options] — { reasoningContent, prefix }
+		* @returns {Object} 添加的消息
+		*/
+		addOnceAssistant(content, options = {}) {
+			return this.add({
+				role: "assistant",
+				content,
+				reasoningContent: options.reasoningContent,
+				prefix: options.prefix !== false,
+				_ephemeral: true
+			});
+		}
 		getLast() {
 			return this._messages[this._messages.length - 1] || null;
 		}
@@ -109,151 +142,1172 @@
 			if (lastAssistantIndex >= 0) return this._messages.splice(lastAssistantIndex + 1);
 			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 — 要合并的字段
+		* @returns {Object|null} 更新后的消息，未找到返回 null
+		*/
+		update(id, changes) {
+			for (const msg of this._messages) if (msg.id === id) {
+				Object.assign(msg, changes);
+				msg.timestamp = changes.timestamp || Date.now();
+				return msg;
+			}
+			return null;
+		}
+	};
+	//#endregion
+	//#region src/core/SystemPromptStore.js
+	/**
+	* SystemPromptStore — 系统提示词存储
+	* 
+	* 职责：管理多条 system prompt 的增删改查与开关
+	* 与 MessageStore 分离，因为 system prompt 是"AI 行为准则"，不是对话事件
+	* 
+	* 每条记录格式：
+	* {
+	*   id: string,
+	*   content: string,
+	*   enabled: boolean,
+	*   timestamp: number
+	* }
+	*/
+	var SystemPromptStore = class {
+		constructor() {
+			this._prompts = [];
+			this._idCounter = 0;
+		}
+		/**
+		* 添加一条 system prompt
+		* @param {string} content — 提示词内容
+		* @param {boolean} [enabled=true] — 是否启用
+		* @returns {Object} 添加的记录
+		*/
+		add(content, enabled = true) {
+			if (!content || typeof content !== "string" || !content.trim()) throw new Error("[SystemPromptStore] content 必须是非空字符串");
+			const record = {
+				id: `sys_${Date.now()}_${++this._idCounter}`,
+				content: content.trim(),
+				enabled: Boolean(enabled),
+				timestamp: Date.now()
+			};
+			this._prompts.push(record);
+			return record;
+		}
+		/**
+		* 删除指定索引的 system prompt
+		* @param {number} index
+		* @returns {Object} 被删除的记录
+		*/
+		remove(index) {
+			if (index < 0 || index >= this._prompts.length) throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
+			return this._prompts.splice(index, 1)[0];
+		}
+		/**
+		* 切换指定索引的启用/禁用状态
+		* @param {number} index
+		* @returns {boolean} 切换后的状态
+		*/
+		toggle(index) {
+			if (index < 0 || index >= this._prompts.length) throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
+			this._prompts[index].enabled = !this._prompts[index].enabled;
+			return this._prompts[index].enabled;
+		}
+		/**
+		* 更新指定索引的 content
+		* @param {number} index
+		* @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 必须是非空字符串");
+			this._prompts[index].content = content.trim();
+			this._prompts[index].timestamp = Date.now();
+		}
+		/**
+		* 清空并用一条 content 替换（便捷方法，常用于 config.system = '...'）
+		* @param {string} content
+		*/
+		set(content) {
+			this._prompts = [];
+			if (content && typeof content === "string" && content.trim()) this.add(content, true);
+		}
+		/**
+		* 按 enabled 筛选后，转为适配器可用的格式
+		* @returns {Array<{role:'system', content:string}>}
+		*/
+		getEnabled() {
+			return this._prompts.filter((p) => p.enabled).map((p) => ({
+				role: "system",
+				content: p.content
+			}));
+		}
+		/**
+		* 返回所有记录（含 enabled 状态，用于 UI 展示）
+		* @returns {Array}
+		*/
+		getAll() {
+			return [...this._prompts];
+		}
+		/**
+		* 清空所有 system prompt
+		*/
+		clear() {
+			this._prompts = [];
+		}
+	};
+	//#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）
+	*
+	* 三个概念（对照 pipeline-demo.html）：
+	* - 小车 ctx   —— 本次请求的全部"状态"，车间之间只通过它交接
+	* - 车间 stage —— { name, run(ctx) }，只干一件事，不认别的车间
+	* - 调度 run()  —— for + await，顺序执行（线性，无"回程"；洋葱能力留给阶段 2 的 after 车间）
+	*/
+	var Pipeline = class {
+		constructor() {
+			this._stages = [];
+		}
+		/**
+		* 注册一个车间（追加到末尾）。
+		* @param {{name: string, run: (ctx: object) => void | Promise<void>}} stage
+		* @returns {Pipeline} this，支持链式
+		*/
+		register(stage) {
+			if (!stage || typeof stage.run !== "function") throw new TypeError("Pipeline.register: stage 需要 { name, run(ctx) }，运行 run 必须是函数");
+			this._stages.push(stage);
+			return this;
+		}
+		/** 按名字移除车间（移除不存在的名字是安全的） */
+		unregister(name) {
+			this._stages = this._stages.filter((s) => s.name !== name);
+			return this;
+		}
+		/** 列出当前车间名（调试用） */
+		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",
+		"ephemeralContinue"
+	];
 	var ChatService = class extends EventEmitter {
 		constructor(config = {}) {
 			super();
-			this.config = {
-				apiKey: config.apiKey || "",
-				model: config.model || "gpt-3.5-turbo",
-				...config
-			};
+			this.config = { ...config };
 			this.messages = new MessageStore();
-			this._plugins = [];
+			this.systemPrompts = new SystemPromptStore();
 			this._adapter = null;
-			this._pendingRequest = null;
+			this._abortController = null;
+			this._isGenerating = false;
+			this._hooks = new EventEmitter();
+			this._processResponse = null;
+			const model = this.config.model || this.config.modelParams?.model;
+			if (!model || typeof model !== "string" || !model.trim()) throw new ConfigurationError("缺少 model 配置");
+			this._assertValidConfig(this.config);
+			if (typeof config.system === "string" && config.system.trim()) this.systemPrompts.set(config.system);
+			if (config.adapter) this.setAdapter(config.adapter);
+			this._userStages = [];
+			this._pipeline = this._buildPipeline();
 		}
 		/**
-		* 加载插件
-		* @param {object} plugin - 必须包含 install 方法
+		* 校验配置中的可校验字段（model 必填由构造器负责，这里只校验存在性）
+		* @throws {ConfigurationError}
 		*/
-		use(plugin) {
-			if (typeof plugin.install === "function") {
-				plugin.install(this);
-				this._plugins.push(plugin);
-			} else throw new Error("插件必须提供 install 方法");
+		_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 = cfg.modelParams?.maxTokens ?? cfg.maxTokens;
+			if (maxTokens !== void 0 && (typeof maxTokens !== "number" || maxTokens < 1 || !Number.isInteger(maxTokens))) throw new ConfigurationError(`maxTokens 必须为正整数，当前值: ${maxTokens}`);
+			const model = cfg.model ?? cfg.modelParams?.model;
+			if (model !== void 0 && (typeof model !== "string" || !model.trim())) throw new ConfigurationError("model 必须是非空字符串");
+		}
+		use(plugin, options = {}) {
+			plugin.install(this, options);
 			return this;
 		}
 		/**
-		* 设置 API 适配器
+		* 往请求管道里挂一个"车间"。
+		* - 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 ([
+				"prepareInput",
+				"beforeSend",
+				"autoContinue",
+				"buildRequest",
+				"send"
+			].includes(stage.name)) throw new ConfigurationError(`pipe: "${stage.name}" 是内部车间名，请换一个名字`);
+			if (this._userStages.some((s) => s.name === stage.name)) throw new ConfigurationError(`pipe: 车间 "${stage.name}" 已存在，请先 chat.unpipe("${stage.name}")`);
+			const phase = stage.phase === "afterSend" ? "afterSend" : "beforeSend";
+			this._userStages.push({
+				name: stage.name,
+				phase,
+				run: stage.run
+			});
+			this._rebuildPipeline();
+			return this;
+		}
+		/** 移除一个用户车间（移除不存在的名字是安全的）。@returns {ChatService} this */
+		unpipe(name) {
+			const before = this._userStages.length;
+			this._userStages = this._userStages.filter((s) => s.name !== name);
+			if (this._userStages.length !== before) this._rebuildPipeline();
+			return this;
+		}
+		/** 查看当前管道里所有车间名（调试/说明用，含内部车间） */
+		get pipelineStages() {
+			return this._pipeline.names();
+		}
+		/** 重建内部管道：内部 5 车间 + 用户车间按 phase 插入 */
+		_buildPipeline() {
+			const p = new Pipeline();
+			p.register({
+				name: "prepareInput",
+				run: (ctx) => this._stagePrepareInput(ctx)
+			});
+			p.register({
+				name: "beforeSend",
+				run: (ctx) => this._stageBeforeSend(ctx)
+			});
+			for (const s of this._userStages) if (s.phase === "beforeSend") p.register({
+				name: s.name,
+				run: (ctx) => s.run(ctx)
+			});
+			p.register({
+				name: "autoContinue",
+				run: (ctx) => this._stageAutoContinue(ctx)
+			});
+			p.register({
+				name: "buildRequest",
+				run: (ctx) => this._stageBuildRequest(ctx)
+			});
+			p.register({
+				name: "send",
+				run: (ctx) => this._stageSend(ctx)
+			});
+			for (const s of this._userStages) if (s.phase === "afterSend") p.register({
+				name: s.name,
+				run: (ctx) => s.run(ctx)
+			});
+			return p;
+		}
+		_rebuildPipeline() {
+			this._pipeline = this._buildPipeline();
+		}
 		setAdapter(adapter) {
+			assertAdapter(adapter);
 			this._adapter = adapter;
-			return this;
+		}
+		abort() {
+			if (this._abortController) this._abortController.abort();
+		}
+		get isGenerating() {
+			return this._isGenerating;
+		}
+		async continueLast() {
+			const target = this._prepareContinue();
+			this.messages.update(target.id, { prefix: true });
+			try {
+				await this._request({
+					addUser: false,
+					isStream: false,
+					mergeToEntry: target.id
+				});
+				this.messages.update(target.id, {
+					_complete: true,
+					prefix: 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;
+			}
+		}
+		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;
+			}
+		}
+		_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，无法续写");
 		}
 		/**
-		* 发送消息（非流式）
-		* @param {string|object} input - 字符串或消息对象
+		* 运行时修改配置（仅会话层字段）。
+		*
+		* 白名单：model / temperature / maxTokens / modelParams / system / retry / ephemeralContinue。
+		* - 运输层（apiKey/baseUrl/headers）：归适配器，要改就换适配器实例
+		* - 请求参数默认值：走适配器工厂 options 或请求级覆盖（chat.send(x, params)）
+		* - 能力表：归 modelRegistry 插件
+		*
+		* 与构造器一样经过校验，不能注入非法值。
+		* @throws {ConfigurationError} 非白名单字段或非法值
 		*/
-		async send(input) {
-			const userMsg = typeof input === "string" ? {
-				role: "user",
-				content: input
-			} : {
-				role: "user",
-				...input
+		updateConfig(partial) {
+			for (const key of Object.keys(partial)) if (!SESSION_CONFIG_KEYS.includes(key)) throw new ConfigurationError(`updateConfig 不支持修改 "${key}"。允许的会话层字段: ${SESSION_CONFIG_KEYS.join(", ")}`);
+			this._assertValidConfig(partial);
+			Object.assign(this.config, partial);
+			if (typeof partial.system === "string") this.systemPrompts.set(partial.system);
+			this.emit("config-updated", {
+				changes: partial,
+				timestamp: Date.now()
+			});
+		}
+		/**
+		* 合并请求参数（近者优先）：
+		*   适配器默认(getRequestDefaults) ← 会话配置(this.config) ← 本次覆盖(params)
+		* modelParams 深层合并；平铺便捷键（temperature/maxTokens/reasoningEffort）自动折叠进 modelParams
+		*/
+		_mergeRequestConfig(params = {}) {
+			const adapterDefaults = this._adapter?.getRequestDefaults?.() || {};
+			const requestConfig = {
+				...adapterDefaults,
+				...this.config,
+				...params
 			};
-			this.messages.add(userMsg);
-			this.emit("sending", userMsg);
-			const requestBody = this._adapter.buildRequest(this.messages.getAll(), this.config);
-			const response = await this._adapter.send(requestBody, this.config);
-			const assistantMsg = this._adapter.parseResponse(response);
+			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;
+			}
+			requestConfig.modelParams = modelParams;
+			return requestConfig;
+		}
+		/**
+		* 内部调度（v3.0 提案 · 阶段 1）：造一辆小车 ctx，开过内部管道，返回结果。
+		* 行为与旧版 _request 完全一致，只是把固定线拆成了车间（见 _stage* 方法）。
+		*
+		* ctx 字段（车间可见）：
+		*   options       —— 原始请求选项
+		*   userInput     —— 用户输入
+		*   addUser       —— 是否新增用户消息
+		*   messages      —— MessageStore（可读可改）
+		*   systemPrompts —— SystemPromptStore
+		*   config        —— 合并后的请求级配置（prepareInput 车间产出）
+		*   isStream      —— 本次是否流式
+		*   onProgress    —— 流式进度回调（可为 null）
+		*   onDone        —— 流式完成回调（可为 null）
+		*   mergeToEntry  —— 续写目标 id（空 = 普通发送）
+		*   body          —— adapter 构建出的请求体（buildRequest 车间产出）
+		*   result        —— 最终结果（send 车间产出）
+		*/
+		async _request(options = {}) {
+			const ctx = {
+				options,
+				userInput: options.userInput,
+				addUser: options.addUser !== false,
+				messages: this.messages,
+				systemPrompts: this.systemPrompts,
+				config: null,
+				isStream: !!options.isStream,
+				onProgress: options.onProgress || null,
+				onDone: options.onDone || null,
+				mergeToEntry: options.mergeToEntry || null,
+				body: null,
+				result: null
+			};
+			try {
+				await this._pipeline.run(ctx);
+				return ctx.result;
+			} catch (error) {
+				if (error.name === "AbortError") throw error;
+				this.emit("error", {
+					error,
+					timestamp: Date.now()
+				});
+				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：发送前钩子（兼容桥：事件钩子照发；阶段 4 会迁到 beforeSend 公开位置） */
+		async _stageBeforeSend(ctx) {
+			await this._hooks.emitAsync("beforeRequest", {
+				messages: ctx.messages,
+				config: ctx.config,
+				options: ctx.options
+			});
+		}
+		/** 车间 3：自动续写检测（ephemeralContinue 时，底部若有 prefix 消息则续写） */
+		async _stageAutoContinue(ctx) {
+			if (this.config.ephemeralContinue && !ctx.mergeToEntry) {
+				const msgs = ctx.messages.getAll();
+				const last = msgs[msgs.length - 1];
+				if (last && last.prefix && (last.role === "assistant" || last._ephemeral)) ctx.mergeToEntry = last.id;
+			}
+		}
+		/** 车间 4：构建请求体 */
+		async _stageBuildRequest(ctx) {
+			ctx.body = this._adapter.buildRequest(ctx.messages.getAll(), ctx.config, ctx.systemPrompts.getEnabled());
+		}
+		/** 车间 5：发送（流式/非流式 + 重试 + 占位消息 + _processResponse 工具钩子） */
+		async _stageSend(ctx) {
+			const retryCfg = this.config.retry || {};
+			ctx.result = await this._withRetry(ctx.body, {
+				isStream: ctx.isStream,
+				onProgress: ctx.onProgress,
+				onDone: ctx.onDone,
+				mergeToEntry: ctx.mergeToEntry,
+				config: ctx.config,
+				maxRetries: retryCfg.maxRetries ?? 0,
+				retryDelay: retryCfg.retryDelay ?? 1e3
+			});
+		}
+		_addUserMessage(userInput, addUser) {
+			if (addUser && userInput !== void 0) {
+				const msg = typeof userInput === "string" ? {
+					role: "user",
+					content: userInput
+				} : {
+					role: "user",
+					...userInput
+				};
+				this.messages.add(msg);
+			}
+		}
+		/** retry 循环，占位消息只 push 一次 */
+		async _withRetry(body, { isStream, onProgress, onDone, mergeToEntry, config, maxRetries, retryDelay }) {
+			let lastError = null;
+			const adapterOptions = { signal: this._abortController?.signal };
+			let placeholder = null;
+			let base = null;
+			if (isStream) {
+				if (mergeToEntry) {
+					placeholder = this.messages.getAll().find((m) => m.id === mergeToEntry);
+					if (placeholder) base = {
+						content: placeholder.content || "",
+						reasoning: placeholder.reasoningContent || ""
+					};
+				}
+				if (!placeholder) placeholder = this.messages.add({
+					role: "assistant",
+					content: "",
+					_complete: false
+				});
+			}
+			for (let attempt = 0; attempt <= maxRetries; attempt++) {
+				if (attempt > 0) {
+					this.emit("retry", {
+						attempt,
+						maxRetries,
+						lastError,
+						timestamp: Date.now()
+					});
+					await new Promise((r) => setTimeout(r, retryDelay));
+				}
+				try {
+					this._isGenerating = true;
+					if (isStream) return await this._stream(body, adapterOptions, {
+						placeholder,
+						base,
+						mergeToEntry,
+						onProgress,
+						onDone,
+						config
+					});
+					else {
+						const resp = await this._adapter.send(body, config, adapterOptions);
+						let result = this._handleResult(this._adapter.parseResponse(resp), mergeToEntry);
+						if (this._processResponse && !mergeToEntry) result = await this._processResponse(result, { isStream: false });
+						return result;
+					}
+				} catch (error) {
+					lastError = error;
+					if (error.name === "AbortError" || this._abortController?.signal.aborted) {
+						this._isGenerating = false;
+						throw error;
+					}
+					if (error instanceof NetworkError && attempt < maxRetries) continue;
+					this._isGenerating = false;
+					throw error;
+				}
+			}
+			this._isGenerating = false;
+			throw lastError;
+		}
+		/**
+		* 流式处理：ChatService 维护占位消息，adapter 只负责解析 SSE
+		*
+		* 参数说明：
+		* - placeholder：流式期间实时更新的目标消息（续写时 = target 本身，普通发送时 = 新建的空消息）
+		* - base：续写时保存的旧内容快照，用于和 API 新内容拼接
+		* - mergeToEntry：续写目标的 id，有值时走续写逻辑
+		* - onProgress：外部回调，每收到一个 chunk 触发
+		* - onDone：流结束回调
+		*/
+		async _stream(body, adapterOptions, { placeholder, base, mergeToEntry, onProgress, onDone, config }) {
+			let finalMsg = null;
+			await this._adapter.stream(body, config, (snap) => {
+				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);
+			}, 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,
+						_ephemeral: false,
+						prefix: void 0
+					};
+					if (final.reasoningContent) changes.reasoningContent = base.reasoning + final.reasoningContent;
+					if (final.toolCalls) changes.toolCalls = final.toolCalls;
+					this.messages.update(mergeToEntry, changes);
+					const updated = this.messages.getAll().find((m) => m.id === mergeToEntry);
+					this.emit("message", updated);
+					if (onDone) onDone(updated);
+				} else {
+					placeholder._complete = true;
+					this.emit("message", finalMsg);
+					if (onDone) onDone(finalMsg);
+				}
+			}, adapterOptions);
+			return mergeToEntry || finalMsg;
+		}
+		/** 非流式结果落位 */
+		_handleResult(assistantMsg, mergeToEntry) {
+			if (mergeToEntry) {
+				const entry = this.messages.getAll().find((m) => m.id === mergeToEntry);
+				if (!entry) {
+					this.messages.add(assistantMsg);
+					this.emit("message", assistantMsg);
+					return assistantMsg;
+				}
+				const changes = {
+					content: (entry.content || "") + (assistantMsg.content || ""),
+					_complete: true,
+					_ephemeral: false,
+					prefix: void 0
+				};
+				if (assistantMsg.reasoningContent) changes.reasoningContent = (entry.reasoningContent || "") + assistantMsg.reasoningContent;
+				if (assistantMsg.toolCalls) changes.toolCalls = assistantMsg.toolCalls;
+				this.messages.update(mergeToEntry, changes);
+				const updated = this.messages.getAll().find((m) => m.id === mergeToEntry);
+				this.emit("message", updated);
+				return updated;
+			}
 			this.messages.add(assistantMsg);
 			this.emit("message", assistantMsg);
 			return assistantMsg;
 		}
 		/**
-		* 流式发送消息
-		* @param {string|object} input
-		* @param {function} onProgress - 每次收到数据块时调用，参数为累积的当前消息对象
-		* @param {function} onDone - 完成时调用，参数为最终消息对象
+		* 发送消息。
+		* @param {string|Object} userInput - 用户输入
+		* @param {Object} [params] - 请求级参数覆盖（model/temperature/modelParams 等，仅本次生效）
 		*/
-		async stream(input, onProgress, onDone) {
-			const userMsg = typeof input === "string" ? {
-				role: "user",
-				content: input
-			} : {
-				role: "user",
-				...input
-			};
-			this.messages.add(userMsg);
-			this.emit("sending", userMsg);
-			const requestBody = this._adapter.buildRequest(this.messages.getAll(), this.config);
-			let accumulated = {
-				role: "assistant",
-				content: ""
-			};
-			await this._adapter.stream(requestBody, this.config, (chunk) => {
-				if (chunk.content) accumulated.content += chunk.content;
-				if (chunk.toolCalls) accumulated.toolCalls = chunk.toolCalls;
-				if (chunk.reasoningContent) accumulated.reasoningContent = chunk.reasoningContent;
-				this.emit("stream-progress", { ...accumulated });
-				if (onProgress) onProgress({ ...accumulated });
-			}, (finalMessage) => {
-				this.messages.add(finalMessage);
-				this.emit("message", finalMessage);
-				if (onDone) onDone(finalMessage);
-			});
+		async send(userInput, params) {
+			this._abortController = new AbortController();
+			try {
+				return await this._request({
+					userInput,
+					addUser: true,
+					isStream: false,
+					params
+				});
+			} catch (err) {
+				if (err.name === "AbortError") {
+					this.emit("aborted", { timestamp: Date.now() });
+					return;
+				}
+				throw err;
+			} finally {
+				this._abortController = null;
+				this._isGenerating = false;
+			}
 		}
 		/**
-		* 注册工具（由工具调用插件实现）
-		* 这里只留一个空方法，插件会覆盖它
+		* 流式发送。
+		* @param {string|Object} userInput - 用户输入
+		* @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+		* @param {Function} [onProgress] - 流式进度回调
+		* @param {Function} [onDone] - 流式完成回调
 		*/
-		registerTool(name, description, executor) {
-			throw new Error("工具调用插件未加载，请先使用 use(toolCallingPlugin)");
+		async stream(userInput, params, onProgress, onDone) {
+			if (typeof params === "function") {
+				onDone = onProgress;
+				onProgress = params;
+				params = void 0;
+			}
+			this._abortController = new AbortController();
+			try {
+				return await this._request({
+					userInput,
+					addUser: true,
+					isStream: true,
+					onProgress,
+					onDone,
+					params
+				});
+			} catch (err) {
+				if (err.name === "AbortError") {
+					this.emit("aborted", { timestamp: Date.now() });
+					return;
+				}
+				throw err;
+			} finally {
+				this._abortController = null;
+				this._isGenerating = false;
+			}
+		}
+		/**
+		* 重发当前消息（不加用户消息）。
+		* @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+		*/
+		async sendExisting(params) {
+			this._abortController = new AbortController();
+			try {
+				return await this._request({
+					addUser: false,
+					isStream: false,
+					params
+				});
+			} catch (err) {
+				if (err.name === "AbortError") {
+					this.emit("aborted", { timestamp: Date.now() });
+					return;
+				}
+				throw err;
+			} finally {
+				this._abortController = null;
+				this._isGenerating = false;
+			}
+		}
+		/**
+		* 流式重发（不加用户消息）。
+		* @param {Object} [params] - 请求级参数覆盖（仅本次生效）
+		* @param {Function} [onProgress] - 流式进度回调
+		* @param {Function} [onDone] - 流式完成回调
+		*/
+		async sendExistingStream(params, onProgress, onDone) {
+			if (typeof params === "function") {
+				onDone = onProgress;
+				onProgress = params;
+				params = void 0;
+			}
+			this._abortController = new AbortController();
+			try {
+				return await this._request({
+					addUser: false,
+					isStream: true,
+					onProgress,
+					onDone,
+					params
+				});
+			} catch (err) {
+				if (err.name === "AbortError") {
+					this.emit("aborted", { timestamp: Date.now() });
+					return;
+				}
+				throw err;
+			} finally {
+				this._abortController = null;
+				this._isGenerating = false;
+			}
 		}
 	};
+	/**
+	* 校验 adapter 是否满足协议（v3.0 · 阶段 3）。
+	* 缺少必要方法时抛 ConfigurationError，并列出缺少的方法名——写"同级适配器"不再靠猜。
+	* @param {*} adapter
+	* @throws {ConfigurationError}
+	*/
+	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
+	/**
+	* URL 工具函数
+	*/
+	/**
+	* 拼接 baseUrl 和 path
+	* 注意：path 应以 '/' 开头，否则会替换 baseUrl 的最后一段
+	* @param {string} baseUrl - 基础 URL（如 https://api.deepseek.com）
+	* @param {string} path - 路径（如 /v1/chat/completions）
+	* @returns {string} 完整的 URL
+	*/
+	function joinUrl(baseUrl, path) {
+		return baseUrl.replace(/\/$/, "") + (path.startsWith("/") ? path : "/" + path);
+	}
+	//#endregion
+	//#region src/utils/typeCheck.js
+	/**
+	* 类型判断工具
+	*/
+	/**
+	* 判断一个值是否为字符串
+	* @param {any} value - 要检查的值
+	* @returns {boolean} 如果是字符串则返回 true
+	*/
+	function isString(value) {
+		return typeof value === "string";
+	}
+	//#endregion
+	//#region src/utils/MessageFormatter.js
+	/**
+	* MessageFormatter — 可注册的消息格式转换器
+	*
+	* 职责：
+	* 1. 内置 OpenA I兼容格式的转换逻辑
+	* 2. 支持 register(name, fn) 注册自定义格式（如 Anthropic、Gemini 等）
+	* 3. 统一处理 capabilities 过滤（reasoning、vision 等）
+	* 4. 所有适配器通过此工具获取 API 消息数组，消除重复代码
+	*
+	* 用法：
+	*   import { MessageFormatter } from 'my-ai-chat-framework';
+	*
+	*   // 使用内置格式
+	*   const msgs = MessageFormatter.format({
+	*     messages, systemPrompts, capabilities, resolveImage
+	*   });  // 默认 'openai'
+	*
+	*   // 注册自定义格式
+	*   MessageFormatter.register('anthropic', ({ messages, systemPrompts, capabilities }) => {
+	*     // 返回 Anthropic 格式的消息数组
+	*   });
+	*/
+	var IS_URL = /^https?:\/\//i;
+	function defaultResolveImage(imageId) {
+		if (IS_URL.test(imageId)) return { url: imageId };
+		return null;
+	}
+	function buildMultimodalContent(textContent, images, resolveImage) {
+		const content = [{
+			type: "text",
+			text: textContent
+		}];
+		for (const ref of images) {
+			const resolved = resolveImage(ref);
+			if (!resolved) continue;
+			if (resolved.url) content.push({
+				type: "image_url",
+				image_url: { url: resolved.url }
+			});
+			else if (resolved.data) {
+				const mime = resolved.mimeType || "image/png";
+				content.push({
+					type: "image_url",
+					image_url: { url: `data:${mime};base64,${resolved.data}` }
+				});
+			}
+		}
+		return content;
+	}
+	/** OpenAI 兼容格式 */
+	function toOpenAI({ messages, systemPrompts, capabilities, resolveImage }) {
+		const rImg = typeof resolveImage === "function" ? resolveImage : defaultResolveImage;
+		const result = [];
+		for (const sp of systemPrompts) if (sp?.content && isString(sp.content) && sp.content.trim()) result.push({
+			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;
+			if (msg.role === "tool") {
+				result.push({
+					role: "tool",
+					content: msg.content || "",
+					tool_call_id: msg.toolCallId
+				});
+				continue;
+			}
+			if (msg.role === "assistant" && msg.toolCalls?.length) {
+				const entry = {
+					role: "assistant",
+					content: msg.content || "",
+					tool_calls: msg.toolCalls
+				};
+				if (msg.prefix) entry.prefix = true;
+				if (capabilities?.reasoning && msg.reasoningContent) entry.reasoning_content = msg.reasoningContent;
+				result.push(entry);
+				continue;
+			}
+			const hasText = msg.content && isString(msg.content) && msg.content.trim();
+			const hasImages = msg.images && Array.isArray(msg.images) && msg.images.length > 0;
+			if (!hasText && !hasImages) {
+				if (msg.role === "assistant" && msg.prefix) {
+					const prefixEntry = {
+						role: "assistant",
+						content: "",
+						prefix: true
+					};
+					if (capabilities?.reasoning && msg.reasoningContent) prefixEntry.reasoning_content = msg.reasoningContent;
+					result.push(prefixEntry);
+				}
+				continue;
+			}
+			const entry = { role: msg.role };
+			if (hasImages) {
+				if (!capabilities?.vision) throw new Error("[MessageFormatter] 消息包含图片但模型不支持视觉（capabilities.vision=false）。请切换模型或移除图片。");
+				entry.content = buildMultimodalContent(msg.content || "", msg.images, rImg);
+			} else entry.content = msg.content;
+			if (msg.prefix) entry.prefix = true;
+			result.push(entry);
+		}
+		return result;
+	}
+	var MessageFormatter = {
+		_formats: new Map([["openai", toOpenAI]]),
+		register(name, fn) {
+			if (!name || typeof name !== "string" || !name.trim()) throw new Error("[MessageFormatter] 格式名称必须是非空字符串");
+			if (typeof fn !== "function") throw new Error("[MessageFormatter] 转换函数必须是 function");
+			this._formats.set(name.trim(), fn);
+		},
+		unregister(name) {
+			if (name === "openai") throw new Error("[MessageFormatter] 内置格式 \"openai\" 不可移除");
+			this._formats.delete(name);
+		},
+		listFormats() {
+			return [...this._formats.keys()];
+		},
+		format(options = {}) {
+			const formatName = options.format || "openai";
+			const fn = this._formats.get(formatName);
+			if (!fn) throw new Error(`[MessageFormatter] 未知格式 "${formatName}"。可用格式: ${[...this._formats.keys()].join(", ")}`);
+			return fn({
+				messages: options.messages || [],
+				systemPrompts: options.systemPrompts || [],
+				capabilities: options.capabilities || {},
+				resolveImage: options.resolveImage
+			});
+		}
+	};
+	function assembleMessages(options = {}) {
+		return MessageFormatter.format({
+			...options,
+			format: "openai"
+		});
+	}
 	//#endregion
 	//#region src/adapters/openai.js
 	/**
 	* 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);
 		},
-		buildRequest(messages, config) {
-			const apiMessages = messages.map((msg) => {
-				const base = {
-					role: msg.role,
-					content: msg.content
-				};
-				if (msg.role === "assistant" && msg.toolCalls) base.tool_calls = msg.toolCalls;
-				if (msg.role === "tool" && msg.toolCallId) base.tool_call_id = msg.toolCallId;
-				return base;
-			});
-			return {
-				model: config.model,
-				messages: apiMessages,
-				temperature: config.temperature ?? .7,
-				max_tokens: config.maxTokens ?? 2e3,
+		_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 mp = config.modelParams || {};
+			const temperature = mp.temperature ?? config.temperature ?? .7;
+			const maxTokens = mp.maxTokens ?? config.maxTokens ?? 2e3;
+			const reasoningEffort = mp.reasoningEffort ?? config.reasoningEffort;
+			const requestBody = {
+				model,
+				messages: MessageFormatter.format({
+					messages,
+					systemPrompts,
+					capabilities: config.capabilities || {},
+					resolveImage: config.resolveImage,
+					format: config.messageFormat
+				}),
+				temperature,
+				max_tokens: maxTokens,
 				stream: false
 			};
+			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 !== 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;
 		},
-		async send(requestBody, config) {
-			const response = await fetch(config.apiUrl || "https://api.openai.com/v1/chat/completions", {
-				method: "POST",
-				headers: {
+		_getUrl(config) {
+			config = config || {};
+			const { apiUrl, baseUrl, path } = config;
+			const defaultPath = "/chat/completions";
+			if (apiUrl && isString(apiUrl)) return apiUrl;
+			if (baseUrl && isString(baseUrl)) return joinUrl(baseUrl, path && isString(path) ? path : defaultPath);
+			return "https://api.openai.com/v1/chat/completions";
+		},
+		async send(requestBody, config, options = {}) {
+			try {
+				config = this._resolveConfig(config);
+				const url = this._getUrl(config);
+				const headers = {
 					"Content-Type": "application/json",
-					"Authorization": `Bearer ${config.apiKey}`
-				},
-				body: JSON.stringify(requestBody)
-			});
-			if (!response.ok) {
-				const error = await response.text();
-				throw new Error(`API 请求失败: ${response.status} ${error}`);
+					"Authorization": `Bearer ${config.apiKey}`,
+					...config.headers || {},
+					...options.headers || {}
+				};
+				const response = await fetch(url, {
+					method: "POST",
+					headers,
+					body: JSON.stringify(requestBody),
+					signal: options.signal
+				});
+				if (!response.ok) await this.handleErrorResponse(response);
+				return await response.json();
+			} catch (error) {
+				if (error instanceof APIError) throw error;
+				if (error.name === "AbortError") throw error;
+				if (error.name === "TypeError" && error.message.includes("fetch")) throw new NetworkError(`Request failed: ${error.message}`, error);
+				throw error;
 			}
-			return await response.json();
 		},
 		parseResponse(apiResponse) {
+			if (!apiResponse || !apiResponse.choices || !apiResponse.choices[0] || !apiResponse.choices[0].message) throw new ParsingError("Invalid API response: missing choices or message", apiResponse, JSON.stringify(apiResponse));
 			const msg = apiResponse.choices[0].message;
 			const internal = {
 				role: msg.role,
@@ -263,32 +1317,44 @@
 			if (msg.reasoning_content) internal.reasoningContent = msg.reasoning_content;
 			return internal;
 		},
-		async stream(requestBody, config, onProgress, onDone) {
+		async stream(requestBody, config, onProgress, onDone, options = {}) {
+			config = this._resolveConfig(config);
 			const streamBody = {
 				...requestBody,
 				stream: true
 			};
-			const response = await fetch(config.apiUrl || "https://api.openai.com/v1/chat/completions", {
-				method: "POST",
-				headers: {
-					"Content-Type": "application/json",
-					"Authorization": `Bearer ${config.apiKey}`,
-					"Accept": "text/event-stream"
-				},
-				body: JSON.stringify(streamBody)
-			});
-			if (!response.ok) {
-				const error = await response.text();
-				throw new Error(`流式请求失败: ${response.status} ${error}`);
+			const url = this._getUrl(config);
+			let response;
+			const headers = {
+				"Content-Type": "application/json",
+				"Authorization": `Bearer ${config.apiKey}`,
+				"Accept": "text/event-stream",
+				...config.headers || {},
+				...options.headers || {}
+			};
+			try {
+				response = await fetch(url, {
+					method: "POST",
+					headers,
+					body: JSON.stringify(streamBody),
+					signal: options.signal
+				});
+			} catch (error) {
+				if (error.name === "AbortError") throw error;
+				if (error.name === "TypeError" && error.message.includes("fetch")) throw new NetworkError(`Stream request failed: ${error.message}`, error);
+				throw error;
 			}
+			if (!response.ok) await this.handleErrorResponse(response);
 			const reader = response.body.getReader();
 			const decoder = new TextDecoder();
 			let buffer = "";
 			let accumulated = {
 				role: "assistant",
-				content: ""
+				content: "",
+				reasoningContent: ""
 			};
 			while (true) {
+				if (options.signal?.aborted) break;
 				const { done, value } = await reader.read();
 				if (done) break;
 				buffer += decoder.decode(value, { stream: true });
@@ -296,22 +1362,34 @@
 				buffer = lines.pop();
 				for (const line of lines) {
 					const dataLine = line.replace(/^data: /, "").trim();
-					if (!dataLine || dataLine === "[DONE]") continue;
+					if (!dataLine) continue;
+					if (dataLine === "[DONE]") break;
 					try {
 						const delta = JSON.parse(dataLine).choices?.[0]?.delta;
 						if (!delta) continue;
-						const update = {
-							role: delta.role || "assistant",
-							content: delta.content || ""
-						};
-						if (delta.tool_calls) update.toolCalls = delta.tool_calls;
-						if (delta.reasoning_content) update.reasoningContent = delta.reasoning_content;
-						if (update.content) accumulated.content += update.content;
-						if (update.toolCalls) accumulated.toolCalls = update.toolCalls;
-						if (update.reasoningContent) accumulated.reasoningContent = update.reasoningContent;
+						if (delta.content) accumulated.content += delta.content;
+						if (delta.tool_calls) {
+							if (!accumulated.toolCalls) accumulated.toolCalls = [];
+							for (const toolCallDelta of delta.tool_calls) {
+								const index = toolCallDelta.index;
+								if (!accumulated.toolCalls[index]) accumulated.toolCalls[index] = {
+									id: "",
+									type: "function",
+									function: {
+										name: "",
+										arguments: ""
+									}
+								};
+								if (toolCallDelta.id) accumulated.toolCalls[index].id = toolCallDelta.id;
+								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;
+							}
+						}
+						if (delta.reasoning_content) accumulated.reasoningContent += delta.reasoning_content;
 						onProgress({ ...accumulated });
 					} catch (e) {
-						console.warn("解析流式数据块失败:", e, dataLine);
+						console.warn("stream parsing failed :", e, dataLine);
 					}
 				}
 			}
@@ -321,81 +1399,211 @@
 				toolCalls: accumulated.toolCalls,
 				reasoningContent: accumulated.reasoningContent
 			});
+		},
+		async handleErrorResponse(response) {
+			let errorText = await response.text();
+			let errorMessage = `HTTP ${response.status}`;
+			try {
+				const errorJson = JSON.parse(errorText);
+				errorMessage = errorJson.error?.message || errorJson.message || errorText.slice(0, 200);
+			} catch (e) {
+				errorMessage = errorText.length > 200 ? errorText.slice(0, 200) + "..." : errorText;
+			}
+			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_calls，执行对应的工具，将结果作为 tool 消息加入对话，
+	*       然后自动继续对话（通过 sendExisting / sendExistingStream），直到没有新的工具调用。
+	*
+	* 设计要点：
+	* - 支持普通请求和流式请求（通过 isStream 标志区分）
+	* - 支持多次工具调用循环（maxIterations 防止无限循环）
+	* - 并行执行工具
+	* - 工具执行失败时，仍然返回错误信息给 AI，而不是中断整个流程
+	* - 触发 tool-error 事件，方便用户监听工具执行异常
+	*
+	* 注意：请使用 createToolCallingPlugin() 工厂创建实例。
+	* 默认导出的 toolCallingPlugin 是兼容用的模块级单例，装到多个 ChatService
+	* 实例会互相覆盖（executor 表、工具定义、配置），新代码不要直接用单例。
 	*/
-	var toolCallingPlugin = {
-		name: "tool-calling",
-		maxIterations: 5,
-		install(chatService) {
-			this.chatService = chatService;
-			this._tools = /* @__PURE__ */ new Map();
-			chatService.registerTool = (name, description, executor) => {
-				this._tools.set(name, {
-					executor,
-					description
+	var toolCallingPlugin = createToolCallingPlugin();
+	/**
+	* 创建工具调用插件实例（工厂）。
+	* @param {Object} [options] — { timeout, maxIterations }
+	*/
+	function createToolCallingPlugin(options = {}) {
+		return {
+			name: "tool-calling",
+			maxIterations: options.maxIterations || 5,
+			_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;
+					}
 				});
-				return chatService;
-			};
-			const originalSend = chatService.send;
-			chatService.send = async (input) => {
-				return this._handleWithTools(originalSend, input, false);
-			};
-			const originalStream = chatService.stream;
-			chatService.stream = async (input, onProgress, onDone) => {
-				return this._handleWithTools(originalStream, input, true, onProgress, onDone);
-			};
-		},
-		async _handleWithTools(originalMethod, input, isStream, onProgress, onDone) {
-			const self = this;
-			const chat = this.chatService;
-			let iteration = 0;
-			async function processResponse(initialResponse) {
-				let lastResponse = initialResponse;
-				while (iteration < self.maxIterations) {
-					const toolCalls = lastResponse?.toolCalls;
-					if (!toolCalls || toolCalls.length === 0) break;
-					iteration++;
-					const toolResults = [];
-					for (const call of toolCalls) {
-						const toolName = call.function?.name;
-						const args = JSON.parse(call.function?.arguments || "{}");
-						const tool = self._tools.get(toolName);
-						if (!tool) {
-							console.warn(`未找到工具: ${toolName}`);
-							toolResults.push({
-								tool_call_id: call.id,
-								error: `工具 ${toolName} 未注册`,
-								success: false
-							});
-							continue;
-						}
-						try {
-							const result = await tool.executor(args);
-							toolResults.push({
-								tool_call_id: call.id,
-								content: typeof result === "string" ? result : JSON.stringify(result),
-								success: true
-							});
-						} catch (err) {
-							console.error(`工具 ${toolName} 执行失败:`, err);
-							toolResults.push({
-								tool_call_id: call.id,
-								error: err.message,
-								success: false
-							});
+				/**
+				* 注册工具
+				* @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
+					});
+					const toolDefinition = {
+						type: "function",
+						function: {
+							name,
+							description,
+							parameters: {
+								type: "object",
+								properties: parameters,
+								required: Object.keys(parameters).filter((key) => parameters[key]?.required)
+							}
 						}
+					};
+					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);
 					}
-					for (const tr of toolResults) chat.messages.addTool(tr.content || tr.error, tr.tool_call_id);
-					if (isStream) {
-						chat.messages.getLast();
-						await new Promise((resolve) => {
-							originalStream.call(chat, null, (chunk) => {
+				});
+			},
+			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 = self._options.timeout ?? 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]);
+								}
+								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
+								};
+							}
+						}));
+						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) => {
@@ -403,39 +1611,214 @@
 								resolve();
 							});
 						});
-					} else {
-						const reqBody = chat._adapter.buildRequest(chat.messages.getAll(), chat.config);
-						const apiResp = await chat._adapter.send(reqBody, chat.config);
-						lastResponse = chat._adapter.parseResponse(apiResp);
+						else lastResponse = await chat.sendExisting();
 					}
+					return lastResponse;
 				}
-				return lastResponse;
+				return await processResponse(initialResponse);
 			}
-			if (isStream) {
-				let finalMessage;
-				await originalMethod.call(chat, input, (chunk) => {
-					if (onProgress) onProgress(chunk);
-				}, async (final) => {
-					finalMessage = await processResponse(final);
-					if (onDone) onDone(finalMessage);
-				});
-			} else return await processResponse(await originalMethod.call(chat, input));
+		};
+	}
+	//#endregion
+	//#region src/plugins/model-registry.js
+	/**
+	* model-registry 插件
+	* 
+	* 职责：
+	* 1. 内置常用模型的能力标签表（model → capabilities 映射）
+	* 2. 安装时自动根据 config.model 查表，写入 config.capabilities
+	* 3. 监听 config-updated 事件，切换模型时自动同步能力
+	* 4. 提供 chat.registerModel()，允许用户追加/覆盖自定义模型
+	* 
+	* 能力标签字段（全部可选，缺失视为 false / 未知）：
+	* {
+	*   reasoning:    boolean — 是否返回 reasoning_content（思维链）
+	*   vision:       boolean — 是否支持图片输入
+	*   toolCalling:  boolean — 是否支持 function calling
+	*   streaming:    boolean — 是否支持流式传输
+	*   maxInputTokens:  number — 最大输入 token 数
+	*   maxOutputTokens: number — 最大输出 token 数
+	* }
+	* 
+	* 使用：
+	*   chat.use(modelRegistryPlugin);
+	*   // config.capabilities 现在已自动填充
+	*   chat.registerModel('my-custom-model', { toolCalling: true });
+	*/
+	var BUILTIN_MODELS = {
+		"deepseek-chat": {
+			reasoning: false,
+			vision: false,
+			toolCalling: true,
+			streaming: true,
+			maxInputTokens: 128e3,
+			maxOutputTokens: 8192
+		},
+		"deepseek-reasoner": {
+			reasoning: true,
+			vision: false,
+			toolCalling: true,
+			streaming: true,
+			maxInputTokens: 128e3,
+			maxOutputTokens: 8192
+		},
+		"gpt-4o": {
+			reasoning: false,
+			vision: true,
+			toolCalling: true,
+			streaming: true,
+			maxInputTokens: 128e3,
+			maxOutputTokens: 16384
+		},
+		"gpt-4o-mini": {
+			reasoning: false,
+			vision: true,
+			toolCalling: true,
+			streaming: true,
+			maxInputTokens: 128e3,
+			maxOutputTokens: 16384
+		},
+		"gpt-3.5-turbo": {
+			reasoning: false,
+			vision: false,
+			toolCalling: true,
+			streaming: true,
+			maxInputTokens: 16385,
+			maxOutputTokens: 4096
+		},
+		"o1": {
+			reasoning: true,
+			vision: false,
+			toolCalling: false,
+			streaming: false,
+			maxInputTokens: 2e5,
+			maxOutputTokens: 1e5
+		},
+		"o3-mini": {
+			reasoning: true,
+			vision: false,
+			toolCalling: true,
+			streaming: true,
+			maxInputTokens: 2e5,
+			maxOutputTokens: 1e5
+		},
+		"claude-3.5-sonnet": {
+			reasoning: false,
+			vision: true,
+			toolCalling: true,
+			streaming: true,
+			maxInputTokens: 2e5,
+			maxOutputTokens: 8192
+		},
+		"claude-3.5-haiku": {
+			reasoning: false,
+			vision: true,
+			toolCalling: true,
+			streaming: true,
+			maxInputTokens: 2e5,
+			maxOutputTokens: 8192
 		}
 	};
-	//#endregion
-	//#region src/index.js
-	var src_default = {
-		ChatService,
-		MessageStore,
-		EventEmitter,
-		openaiAdapter,
-		toolCallingPlugin
+	var DEFAULT_CAPABILITIES = {
+		streaming: true,
+		toolCalling: false,
+		reasoning: false,
+		vision: false
 	};
+	/**
+	* 注意：请使用 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.chat = chatService;
+				/**
+				* 注册/覆盖一个模型的能力标签
+				* @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
+					};
+					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.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
+						};
+					}
+				});
+			},
+			_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
+	exports.APIError = APIError;
 	exports.ChatService = ChatService;
+	exports.ConfigurationError = ConfigurationError;
 	exports.EventEmitter = EventEmitter;
+	exports.MessageFormatter = MessageFormatter;
 	exports.MessageStore = MessageStore;
-	exports.default = src_default;
+	exports.NetworkError = NetworkError;
+	exports.ParsingError = ParsingError;
+	exports.Pipeline = Pipeline;
+	exports.SystemPromptStore = SystemPromptStore;
+	exports.assembleMessages = assembleMessages;
+	exports.assertAdapter = assertAdapter;
+	exports.createModelRegistryPlugin = createModelRegistryPlugin;
+	exports.createOpenAIAdapter = createOpenAIAdapter;
+	exports.createToolCallingPlugin = createToolCallingPlugin;
+	exports.modelRegistryPlugin = modelRegistryPlugin;
 	exports.openaiAdapter = openaiAdapter;
 	exports.toolCallingPlugin = toolCallingPlugin;
 });