my-ai-chat-framework 3.0.0 → 4.0.0

package/src/core/SystemPromptStore.js

@@ -13,6 +13,8 @@
  * }
  */
 
+import { ValidationError } from './Errors.js';
+
 export class SystemPromptStore {
   constructor() {
     this._prompts = [];
@@ -27,7 +29,7 @@ export class SystemPromptStore {
    */
   add(content, enabled = true) {
     if (!content || typeof content !== 'string' || !content.trim()) {
-      throw new Error('[SystemPromptStore] content 必须是非空字符串');
+      throw new ValidationError('[SystemPromptStore] content 必须是非空字符串');
     }
     const record = {
       id: `sys_${Date.now()}_${++this._idCounter}`,
@@ -46,7 +48,7 @@ export class SystemPromptStore {
    */
   remove(index) {
     if (index < 0 || index >= this._prompts.length) {
-      throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
+      throw new ValidationError(`[SystemPromptStore] 索引越界: ${index}`);
     }
     return this._prompts.splice(index, 1)[0];
   }
@@ -58,7 +60,7 @@ export class SystemPromptStore {
    */
   toggle(index) {
     if (index < 0 || index >= this._prompts.length) {
-      throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
+      throw new ValidationError(`[SystemPromptStore] 索引越界: ${index}`);
     }
     this._prompts[index].enabled = !this._prompts[index].enabled;
     return this._prompts[index].enabled;
@@ -71,10 +73,10 @@ export class SystemPromptStore {
    */
   update(index, content) {
     if (index < 0 || index >= this._prompts.length) {
-      throw new Error(`[SystemPromptStore] 索引越界: ${index}`);
+      throw new ValidationError(`[SystemPromptStore] 索引越界: ${index}`);
     }
     if (!content || typeof content !== 'string' || !content.trim()) {
-      throw new Error('[SystemPromptStore] content 必须是非空字符串');
+      throw new ValidationError('[SystemPromptStore] content 必须是非空字符串');
     }
     this._prompts[index].content = content.trim();
     this._prompts[index].timestamp = Date.now();

package/src/index.js

@@ -5,9 +5,10 @@ export { EventEmitter } from './core/EventEmitter.js';
 export { openaiAdapter, createOpenAIAdapter } from './adapters/openai.js';
 export { toolCallingPlugin, createToolCallingPlugin } from './plugins/tool-calling.js';
 export { modelRegistryPlugin, createModelRegistryPlugin } from './plugins/model-registry.js';
+export { continuationPlugin, createContinuationPlugin } from './plugins/continuation.js';
 export { MessageFormatter } from './utils/MessageFormatter.js';
 export { assembleMessages } from './utils/MessageFormatter.js';
 
-export { APIError, NetworkError, ConfigurationError, ParsingError } from './core/Errors.js';
+export { APIError, NetworkError, ConfigurationError, ValidationError, ParsingError } from './core/Errors.js';
 export { assertAdapter } from './core/ChatService.js';
 export { Pipeline } from './core/Pipeline.js';

package/src/plugins/continuation.js

@@ -0,0 +1,156 @@
+/**
+ * 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('在吗');
+ */
+
+import { MessageFormatter } from '../utils/MessageFormatter.js';
+import { ValidationError } from '../core/Errors.js';
+
+/**
+ * ephemeral 规则：只有底部连续的临时消息保留，其余丢弃（与 v3.x 核心内置行为一致）。
+ * 导出以便使用者直接注册到 MessageFormatter（不使用插件时也能用这条规则）。
+ */
+export 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 实例
+ */
+export 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: undefined, _ephemeral: false });
+}
+
+/**
+ * 创建续写插件实例（工厂）
+ * @param {Object} [options] — { autoContinue?: boolean }  是否自动识别底部 prefix 消息并合并（默认 false）
+ */
+export function createContinuationPlugin(options = {}) {
+  return {
+    name: 'continuation',
+    _options: { autoContinue: false, ...options },
+    _prevEphemeralFilter: undefined,
+    _installedOn: null,
+
+    /**
+     * 安装：替换续写步骤 + 接管 ephemeral 过滤 + 挂续写 API
+     * @param {import('../core/ChatService.js').ChatService} chat
+     */
+    install(chat) {
+      this._installedOn = chat;
+
+      // 0) 登记可运行时修改的配置字段（v4.0：插件自带配置，不用改核心白名单）
+      if (typeof chat.registerConfigKeys === 'function') {
+        chat.registerConfigKeys({ autoContinue: (v) => typeof v === 'boolean' });
+      }
+
+      // 1) 续写检测（用 v3.1 的出口替换核心的 autoContinue 步骤）
+      chat.replaceStage('autoContinue', (ctx) => {
+        // 运行时 `chat.updateConfig({ autoContinue })` 优先，其次取安装时的工厂 options
+        const enabled = chat.config.autoContinue ?? this._options.autoContinue;
+        if (!enabled) return;                             // 默认关：不替用户做选择
+        if (ctx.mergeToEntry) return;
+        const last = ctx.messages.getLast();
+        if (last && last.prefix && (last.role === 'assistant' || last._ephemeral)) {
+          ctx.mergeToEntry = last.id;
+        }
+      });
+
+      // 2) 接管 ephemeral 过滤（同名覆盖；保存旧函数，卸载时还原）
+      this._prevEphemeralFilter = MessageFormatter.registerFilter('ephemeral', ephemeralFilterRule, { priority: 100 });
+
+      // 3) 续写 API（通过 chat.plugins.continuation 暴露，v4.0 命名空间）
+      const continueLast = async () => {
+        const target = prepareContinue(chat);
+        chat.messages.update(target.id, { prefix: true });
+        try {
+          await chat.sendExisting(undefined, { 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(
+            undefined,
+            { 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;
+        }
+      };
+
+      // 交给 use() 挂到 chat.plugins['continuation']
+      return { continueLast, continueLastStream, uninstall: () => this.uninstall(chat) };
+    },
+
+    /**
+     * 卸载：恢复被替换的步骤、还原过滤器、移除挂载的方法
+     * @param {import('../core/ChatService.js').ChatService} [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;
+    }
+  };
+}
+
+/** 兼容用单例（多实例场景请用工厂） */
+export const continuationPlugin = createContinuationPlugin();

package/src/plugins/model-registry.js

@@ -23,6 +23,8 @@
  *   chat.registerModel('my-custom-model', { toolCalling: true });
  */
 
+import { ValidationError } from '../core/Errors.js';
+
 // ====== 内置模型能力表 ======
 // 数据来源：各厂商官方文档（2026-05 快照），用户可通过 registerModel() 覆盖
 const BUILTIN_MODELS = {
@@ -149,9 +151,9 @@ export function createModelRegistryPlugin(options = {}) {
        * @param {Object} capabilities — 能力标签对象（部分字段即可，未提供的取默认值）
        * @returns {ChatService}
        */
-      chatService.registerModel = (name, capabilities = {}) => {
+      const registerModel = (name, capabilities = {}) => {
         if (!name || typeof name !== 'string' || !name.trim()) {
-          throw new Error('[model-registry] 模型名称必须是非空字符串');
+          throw new ValidationError('[model-registry] 模型名称必须是非空字符串');
         }
         const merged = { ...DEFAULT_CAPABILITIES, ...capabilities };
         this._registry.set(name.trim(), merged);
@@ -166,7 +168,7 @@ export function createModelRegistryPlugin(options = {}) {
        * 列出所有已注册的模型名称
        * @returns {Array<string>}
        */
-      chatService.listModels = () => {
+      const listModels = () => {
         return [...this._registry.keys()];
       };
 
@@ -198,6 +200,17 @@ export function createModelRegistryPlugin(options = {}) {
           }
         }
       });
+
+      // 交给 use() 挂到 chat.plugins['model-registry']（v4.0 命名空间）
+      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;
     },
 
     // ---- 内部方法 ----

package/src/plugins/tool-calling.js

@@ -18,12 +18,15 @@ export const toolCallingPlugin = createToolCallingPlugin();
 
 /**
  * 创建工具调用插件实例（工厂）。
- * @param {Object} [options] — { timeout, maxIterations }
+ * @param {Object} [options] — { timeout?, maxIterations? }
+ *   - 两者**默认都不限制**：不传就是"循环到没有工具调用为止 / 不超时"
+ *   - 想限制才传（这是使用者的选择，不是框架替你做的决定）
  */
 export function createToolCallingPlugin(options = {}) {
   return {
     name: 'tool-calling',
-    maxIterations: options.maxIterations || 5, // 最大工具调用循环次数，防止无限循环
+    // 默认不限制循环轮数（旧版硬编码 5 轮，属于"框架替用户做决定"，v4.0 移除）
+    maxIterations: options.maxIterations ?? Infinity,
     _options: { ...options },
     _tools: new Map(),    // 工具名 -> { executor, description }
     _toolDefs: [],        // OpenAI 格式的工具定义（按注册顺序）
@@ -55,21 +58,26 @@ export function createToolCallingPlugin(options = {}) {
        * @param {Object} parameters - JSON Schema 参数定义（可选，默认为空对象）
        * @returns {ChatService} 返回 chatService 实例，支持链式调用
        */
-      chatService.registerTool = (name, description, executor, parameters = {}) => {
+      const registerTool = (name, description, executor, parameters = {}) => {
         // 保存执行器
         this._tools.set(name, { executor, description });
 
         // 构建 OpenAI 兼容的工具定义
+        // 参数写法：{ 参数名: { type, description, required? } }
+        // → 必填项收集到顶层 required 数组；properties 里不残留 required 字段（标准 JSON Schema 要求）
+        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: parameters,
-              required: Object.keys(parameters).filter(key => parameters[key]?.required)
-            }
+            parameters: { type: 'object', properties, required: requiredKeys }
           }
         };
         // 避免重复添加相同工具
@@ -93,6 +101,18 @@ export function createToolCallingPlugin(options = {}) {
           );
         }
       });
+
+      // 交给 use() 挂到 chat.plugins['tool-calling']（v4.0 命名空间）
+      return { registerTool, tools: this._tools, uninstall: (c) => this.uninstall(c) };
+    },
+
+    /** 卸载：移除注入车间（工具定义注入 + 工具循环） */
+    uninstall(chat) {
+      if (!chat) return chat;
+      chat.unpipe?.('tool-calling-inject');
+      chat.unpipe?.('tool-calling-loop');
+      if (chat.plugins && chat.plugins['tool-calling']) delete chat.plugins['tool-calling'];
+      return chat;
     },
 
     /**
@@ -162,19 +182,27 @@ export function createToolCallingPlugin(options = {}) {
               }
 
               try {
-                // 工具执行超时控制（工厂 options.timeout 优先，兼容旧 config.toolTimeout）
-                const toolTimeout = self._options.timeout ?? chat.config.toolTimeout;
-                let execPromise = tool.executor(args);
-                if (toolTimeout && typeof toolTimeout === 'number' && toolTimeout > 0) {
+                // 工具执行超时：只在工厂 options.timeout 显式传入时生效（不传 = 不限制）
+                const toolTimeout = self._options.timeout;
+                let result;
+                if (typeof toolTimeout === 'number' && toolTimeout > 0) {
+                  const controller = new AbortController();          // 通知支持 signal 的工具去清理
                   const timeoutErr = new Error(`工具 ${toolName} 执行超时 (${toolTimeout}ms)`);
                   timeoutErr.name = 'ToolTimeoutError';
-                  const timeoutPromise = new Promise((_, reject) =>
-                    setTimeout(() => reject(timeoutErr), toolTimeout)
-                  );
-                  execPromise = Promise.race([execPromise, timeoutPromise]);
+                  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(() => {});                        // 超时后工具的后续结果不再冒泡为 unhandled
+                  try {
+                    result = await Promise.race([execPromise, timeoutPromise]);
+                  } finally {
+                    clearTimeout(timer);                              // 工具先完成时不留悬挂的 timer（旧版泄漏点）
+                  }
+                } else {
+                  result = await tool.executor(args);
                 }
-
-                const result = await execPromise;
                 chat.emit('tool-success', {
                   toolName,
                   result,

package/src/utils/MessageFormatter.js

@@ -1,29 +1,27 @@
 /**
- * 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);
  */
 
 import { isString } from './typeCheck.js';
+import { ValidationError } from '../core/Errors.js';
 
-// ====== 内置格式 ======
+// ====== 内置工具 ======
 
 const IS_URL = /^https?:\/\//i;
 
@@ -47,38 +45,59 @@ function buildMultimodalContent(textContent, images, resolveImage) {
   return content;
 }
 
-/** OpenAI 兼容格式 */
+// ====== 内置过滤器（通用清理规则，无业务含义）======
+
+/**
+ * ephemeral 规则：临时消息只有"位于底部连续段"时才保留，其余丢弃。
+ * （v3.x 时硬编码在 toOpenAI 里；v4.0 起是过滤器，插件可同名覆盖）
+ */
+function filterEphemeral(msg, { index, messages }) {
+  if (!msg._ephemeral) return msg;
+  let ephemStart = messages.length;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]._ephemeral) ephemStart = i;
+    else break;
+  }
+  return index >= ephemStart ? msg : null;
+}
+
+/** 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;
+}
+
+// ====== 内置格式：OpenAI 兼容 ======
+
 function toOpenAI({ messages, systemPrompts, capabilities, resolveImage }) {
   const rImg = typeof resolveImage === 'function' ? resolveImage : defaultResolveImage;
   const result = [];
 
-  // 1) system 置顶
+  // 1) system 置顶（来自 SystemPromptStore）
   for (const sp of systemPrompts) {
     if (sp?.content && isString(sp.content) && sp.content.trim()) {
       result.push({ role: 'system', content: sp.content.trim() });
     }
   }
 
-  // 2) 识别底部连续 ephemeral（只保留这些临时消息，其他 ephemeral 忽略）
-  let ephemEnd = messages.length;
-  for (let i = messages.length - 1; i >= 0; i--) {
-    if (messages[i]._ephemeral) ephemEnd = i;
-    else break;
-  }
-
-  // 3) 过滤 + 字段映射
-  for (let i = 0; i < messages.length; i++) {
-    const msg = messages[i];
-
-    // ephemeral 消息：仅底部连续的保留，其余跳过
-    if (msg._ephemeral) {
-      if (i < ephemEnd) continue;
-      // 底部 ephemeral 按原始 role 处理，不加 _ephemeral 标记
-    }
-
-    // 非底部 ephemeral 的正常消息仍保留原有过滤
-    if (msg.role === 'system' && !msg._ephemeral) continue;
+  // 2) 跑过滤器链 → 决定"哪些消息进入请求"（规则可插拔）
+  const kept = MessageFormatter._runFilters(messages, capabilities || {});
 
+  // 3) 字段映射（过滤后的消息 → API 格式）
+  for (const msg of kept) {
     if (msg.role === 'tool') {
       result.push({ role: 'tool', content: msg.content || '', tool_call_id: msg.toolCallId });
       continue;
@@ -87,22 +106,19 @@ function toOpenAI({ messages, systemPrompts, capabilities, resolveImage }) {
     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;
-      }
+      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;
+
+    // 走到这里说明是被过滤器"特意保留"的空消息（prefix 续写占位）
     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;
-        }
+        if (capabilities?.reasoning && msg.reasoningContent) prefixEntry.reasoning_content = msg.reasoningContent;
         result.push(prefixEntry);
       }
       continue;
@@ -112,7 +128,7 @@ function toOpenAI({ messages, systemPrompts, capabilities, resolveImage }) {
 
     if (hasImages) {
       if (!capabilities?.vision) {
-        throw new Error(
+        throw new ValidationError(
           '[MessageFormatter] 消息包含图片但模型不支持视觉（capabilities.vision=false）。' +
           '请切换模型或移除图片。'
         );
@@ -123,7 +139,6 @@ function toOpenAI({ messages, systemPrompts, capabilities, resolveImage }) {
     }
 
     if (msg.prefix) entry.prefix = true;
-    // 常规 assistant 不回传 reasoningContent——API 自己会重新推理
     result.push(entry);
   }
 
@@ -137,6 +152,10 @@ export const MessageFormatter = {
     ['openai', toOpenAI]
   ]),
 
+  /** 过滤器表：name → { name, fn, priority, order } */
+  _filters: new Map(),
+  _filterOrder: 0,
+
   /**
    * 注册自定义格式
    * @param {string} name — 格式名称（如 'anthropic', 'gemini'）
@@ -144,10 +163,10 @@ export const MessageFormatter = {
    */
   register(name, fn) {
     if (!name || typeof name !== 'string' || !name.trim()) {
-      throw new Error('[MessageFormatter] 格式名称必须是非空字符串');
+      throw new ValidationError('[MessageFormatter] 格式名称必须是非空字符串');
     }
     if (typeof fn !== 'function') {
-      throw new Error('[MessageFormatter] 转换函数必须是 function');
+      throw new ValidationError('[MessageFormatter] 转换函数必须是 function');
     }
     this._formats.set(name.trim(), fn);
   },
@@ -158,7 +177,7 @@ export const MessageFormatter = {
    */
   unregister(name) {
     if (name === 'openai') {
-      throw new Error('[MessageFormatter] 内置格式 "openai" 不可移除');
+      throw new ValidationError('[MessageFormatter] 内置格式 "openai" 不可移除');
     }
     this._formats.delete(name);
   },
@@ -171,6 +190,73 @@ export const MessageFormatter = {
     return [...this._formats.keys()];
   },
 
+  // ===== 过滤器 API（v4.0）=====
+
+  /**
+   * 注册一个消息过滤器（决定消息是否进入请求、允许改写字段）。
+   * 同名会**覆盖**（返回被覆盖的旧函数），因此插件可以接管内置规则。
+   * @param {string} name
+   * @param {(msg: Object, ctx: {index:number,total:number,messages:Array,capabilities:Object}) => Object|null} fn
+   *        返回消息 = 保留（可改字段 / 返回新对象）；返回 null = 丢弃
+   * @param {{priority?: number}} [options] 数字越小越先执行，默认 100
+   * @returns {Function|undefined} 被覆盖的旧过滤器（没有则 undefined）
+   */
+  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 : undefined;
+  },
+
+  /**
+   * 移除过滤器
+   * @param {string} name
+   * @returns {boolean} 是否移除成功
+   */
+  unregisterFilter(name) {
+    return this._filters.delete(name);
+  },
+
+  /**
+   * 列出过滤器（按执行顺序）
+   * @returns {Array<{name: string, priority: number}>}
+   */
+  listFilters() {
+    return [...this._filters.values()]
+      .sort((a, b) => a.priority - b.priority || a.order - b.order)
+      .map(f => ({ name: f.name, priority: f.priority }));
+  },
+
+  /**
+   * 跑过滤器链（内部使用）
+   * @param {Array} messages
+   * @param {Object} capabilities
+   * @returns {Array} 保留的消息
+   */
+  _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 === undefined) { dropped = true; break; }
+      }
+      if (!dropped) out.push(msg);
+    }
+    return out;
+  },
+
   /**
    * 按指定格式转换消息
    * @param {Object} options
@@ -185,7 +271,7 @@ export const MessageFormatter = {
     const formatName = options.format || 'openai';
     const fn = this._formats.get(formatName);
     if (!fn) {
-      throw new Error(
+      throw new ValidationError(
         `[MessageFormatter] 未知格式 "${formatName}"。可用格式: ${[...this._formats.keys()].join(', ')}`
       );
     }
@@ -198,6 +284,12 @@ export const MessageFormatter = {
   }
 };
 
+// ====== 内置过滤器注册 ======
+// v4.0：核心只保留「通用清理」规则（system 置顶分流、空内容清理）。
+// ephemeral（临时消息）属于玩法规则，由 continuation 插件注册 —— 见 src/plugins/continuation.js。
+MessageFormatter.registerFilter('system-drop', filterSystemDrop, { priority: 900 });
+MessageFormatter.registerFilter('empty-drop', filterEmptyDrop, { priority: 910 });
+
 // 向后兼容：保留 assembleMessages 函数
 export function assembleMessages(options = {}) {
   return MessageFormatter.format({ ...options, format: 'openai' });