my-ai-chat-framework 2.7.0 → 3.0.0

package/src/utils/MessageFormatter.js

@@ -1,204 +1,204 @@
-/**
- * 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 格式的消息数组
- *   });
- */
-
-import { isString } from './typeCheck.js';
-
-// ====== 内置格式 ======
-
-const 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 = [];
-
-  // 1) system 置顶
-  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;
-
-    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;
-    // 常规 assistant 不回传 reasoningContent——API 自己会重新推理
-    result.push(entry);
-  }
-
-  return result;
-}
-
-// ====== 格式化器 ======
-
-export const MessageFormatter = {
-  _formats: new Map([
-    ['openai', toOpenAI]
-  ]),
-
-  /**
-   * 注册自定义格式
-   * @param {string} name — 格式名称（如 'anthropic', 'gemini'）
-   * @param {Function} fn — 转换函数，接收 { messages, systemPrompts, capabilities, resolveImage }，返回消息数组
-   */
-  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);
-  },
-
-  /**
-   * 移除自定义格式（内置格式不可移除）
-   * @param {string} name
-   */
-  unregister(name) {
-    if (name === 'openai') {
-      throw new Error('[MessageFormatter] 内置格式 "openai" 不可移除');
-    }
-    this._formats.delete(name);
-  },
-
-  /**
-   * 列出所有已注册的格式名称
-   * @returns {Array<string>}
-   */
-  listFormats() {
-    return [...this._formats.keys()];
-  },
-
-  /**
-   * 按指定格式转换消息
-   * @param {Object} options
-   * @param {Array}  options.messages        — 内部消息列表
-   * @param {Array}  [options.systemPrompts=[]] — 启用的 system prompt
-   * @param {Object} [options.capabilities={}]  — 模型能力标签
-   * @param {Function} [options.resolveImage]   — 图片解析钩子
-   * @param {string} [options.format='openai']  — 目标格式名称
-   * @returns {Array<Object>}
-   */
-  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
-    });
-  }
-};
-
-// 向后兼容：保留 assembleMessages 函数
-export function assembleMessages(options = {}) {
-  return MessageFormatter.format({ ...options, format: 'openai' });
-}
+/**
+ * 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 格式的消息数组
+ *   });
+ */
+
+import { isString } from './typeCheck.js';
+
+// ====== 内置格式 ======
+
+const 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 = [];
+
+  // 1) system 置顶
+  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;
+
+    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;
+    // 常规 assistant 不回传 reasoningContent——API 自己会重新推理
+    result.push(entry);
+  }
+
+  return result;
+}
+
+// ====== 格式化器 ======
+
+export const MessageFormatter = {
+  _formats: new Map([
+    ['openai', toOpenAI]
+  ]),
+
+  /**
+   * 注册自定义格式
+   * @param {string} name — 格式名称（如 'anthropic', 'gemini'）
+   * @param {Function} fn — 转换函数，接收 { messages, systemPrompts, capabilities, resolveImage }，返回消息数组
+   */
+  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);
+  },
+
+  /**
+   * 移除自定义格式（内置格式不可移除）
+   * @param {string} name
+   */
+  unregister(name) {
+    if (name === 'openai') {
+      throw new Error('[MessageFormatter] 内置格式 "openai" 不可移除');
+    }
+    this._formats.delete(name);
+  },
+
+  /**
+   * 列出所有已注册的格式名称
+   * @returns {Array<string>}
+   */
+  listFormats() {
+    return [...this._formats.keys()];
+  },
+
+  /**
+   * 按指定格式转换消息
+   * @param {Object} options
+   * @param {Array}  options.messages        — 内部消息列表
+   * @param {Array}  [options.systemPrompts=[]] — 启用的 system prompt
+   * @param {Object} [options.capabilities={}]  — 模型能力标签
+   * @param {Function} [options.resolveImage]   — 图片解析钩子
+   * @param {string} [options.format='openai']  — 目标格式名称
+   * @returns {Array<Object>}
+   */
+  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
+    });
+  }
+};
+
+// 向后兼容：保留 assembleMessages 函数
+export function assembleMessages(options = {}) {
+  return MessageFormatter.format({ ...options, format: 'openai' });
+}

package/src/utils/typeCheck.js

@@ -1,12 +1,12 @@
-/**
- * 类型判断工具
- */
-
-/**
- * 判断一个值是否为字符串
- * @param {any} value - 要检查的值
- * @returns {boolean} 如果是字符串则返回 true
- */
-export function isString(value) {
-  return typeof value === 'string';
+/**
+ * 类型判断工具
+ */
+
+/**
+ * 判断一个值是否为字符串
+ * @param {any} value - 要检查的值
+ * @returns {boolean} 如果是字符串则返回 true
+ */
+export function isString(value) {
+  return typeof value === 'string';
 }

package/src/utils/url.js

@@ -1,18 +1,18 @@
-/**
- * URL 工具函数
- */
-
-/**
- * 拼接 baseUrl 和 path
- * 注意：path 应以 '/' 开头，否则会替换 baseUrl 的最后一段
- * @param {string} baseUrl - 基础 URL（如 https://api.deepseek.com）
- * @param {string} path - 路径（如 /v1/chat/completions）
- * @returns {string} 完整的 URL
- */
-export function joinUrl(baseUrl, path) {
-  // 移除 baseUrl 末尾的斜杠（如果有）
-  const base = baseUrl.replace(/\/$/, '');
-  // 确保 path 以斜杠开头
-  const p = path.startsWith('/') ? path : '/' + path;
-  return base + p;
+/**
+ * URL 工具函数
+ */
+
+/**
+ * 拼接 baseUrl 和 path
+ * 注意：path 应以 '/' 开头，否则会替换 baseUrl 的最后一段
+ * @param {string} baseUrl - 基础 URL（如 https://api.deepseek.com）
+ * @param {string} path - 路径（如 /v1/chat/completions）
+ * @returns {string} 完整的 URL
+ */
+export function joinUrl(baseUrl, path) {
+  // 移除 baseUrl 末尾的斜杠（如果有）
+  const base = baseUrl.replace(/\/$/, '');
+  // 确保 path 以斜杠开头
+  const p = path.startsWith('/') ? path : '/' + path;
+  return base + p;
 }