my-ai-chat-framework 2.0.0 → 2.7.0

package/src/utils/MessageFormatter.js

@@ -0,0 +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' });
+}

package/src/utils/typeCheck.js

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

package/src/utils/url.js

@@ -0,0 +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;
+}

package/.env

@@ -1,15 +0,0 @@
-# AI Chat Framework 环境变量配置
-
-# DeepSeek API 配置
-DEEPSEEK_API_KEY=sk-3b396e7fd64b463390d4ff033c6e7e0b
-DEEPSEEK_API_URL=https://api.deepseek.com/v1/chat/completions
-
-# 测试配置
-TEST_API_KEY=sk-3b396e7fd64b463390d4ff033c6e7e0b
-TEST_MODEL=deepseek-chat
-TEST_TEMPERATURE=0.7
-TEST_MAX_TOKENS=2000
-
-# 调试配置
-DEBUG=false
-LOG_LEVEL=info

package/test.js

@@ -1,107 +0,0 @@
-// test.js - 测试新框架核心功能
-import 'dotenv/config'; // 如果已安装 dotenv，否则手动读取 .env
-import { ChatService, openaiAdapter, toolCallingPlugin } from './src/index.js';
-
-// 从环境变量读取配置（确保 .env 文件存在）
-const apiKey = process.env.DEEPSEEK_API_KEY;
-const apiUrl = process.env.DEEPSEEK_API_URL || 'https://api.deepseek.com/v1/chat/completions';
-const model = process.env.TEST_MODEL || 'deepseek-chat';
-
-if (!apiKey) {
-  console.error('❌ 未找到 API Key，请设置 DEEPSEEK_API_KEY 环境变量或创建 .env 文件');
-  process.exit(1);
-}
-
-console.log('🚀 开始测试新框架...\n');
-
-// 创建聊天服务实例
-const chat = new ChatService({
-  apiKey,
-  model,
-  apiUrl,
-  temperature: 0.7,
-  maxTokens: 2000
-});
-
-// 加载适配器和插件
-chat.use(openaiAdapter);
-chat.use(toolCallingPlugin);
-
-// 监听事件（便于观察）
-chat.on('sending', msg => {
-  console.log('📤 发送消息:', msg.content?.substring(0, 50) || msg);
-});
-chat.on('message', msg => {
-  console.log('📥 收到回复:', msg.content?.substring(0, 100) || msg);
-});
-chat.on('stream-progress', chunk => {
-  console.log('🌊 流式数据块:', chunk.content?.substring(0, 30) || '');
-});
-chat.on('error', err => {
-  console.error('❌ 错误:', err.message);
-});
-
-// 注册一个简单测试工具（不实际调用，只验证注册和工具调用流程）
-chat.registerTool('greet', '打招呼工具', async (args) => {
-  console.log('🔧 工具被调用:', args);
-  return `你好，${args.name || '朋友'}！`;
-});
-
-// 辅助函数：等待指定毫秒
-const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
-
-// 测试 1：基础发送消息（非流式）
-console.log('===== 测试1：基础发送消息 =====');
-const response = await chat.send('请简单说一句：你好，世界！');
-console.log('最终回复:', response.content);
-console.log();
-
-// 等待一下，避免请求过快
-await sleep(1000);
-
-// 测试 2：流式发送消息
-console.log('===== 测试2：流式发送消息 =====');
-let streamContent = '';
-await chat.stream('请用流式方式回答：告诉我一个好消息。',
-  (chunk) => {
-    streamContent += chunk.content;
-    // 实时打印已接收内容（可选）
-    // process.stdout.write(chunk.content);
-  },
-  (final) => {
-    console.log('流式完成，完整内容:', final.content);
-  }
-);
-console.log();
-
-await sleep(1000);
-
-// 测试 3：工具调用
-console.log('===== 测试3：工具调用 =====');
-// 注意：需要让 AI 主动调用 greet 工具。由于 deepseek-chat 支持函数调用，我们可以在系统提示或用户消息中引导。
-// 我们在用户消息中明确要求调用工具，但 AI 是否调用取决于模型。这里做一个简单引导。
-const toolResponse = await chat.send('请使用 greet 工具，向 "小明" 打招呼。');
-console.log('工具调用后的回复:', toolResponse.content);
-console.log();
-
-await sleep(1000);
-
-// 测试 4：验证消息存储
-console.log('===== 测试4：消息存储验证 =====');
-const allMessages = chat.messages.getAll();
-console.log(`当前消息总数: ${allMessages.length}`);
-allMessages.forEach((msg, i) => {
-  console.log(`[${i}] ${msg.role}: ${msg.content?.substring(0, 40)}${msg.content?.length > 40 ? '...' : ''}`);
-  if (msg.toolCalls) console.log('  工具调用:', msg.toolCalls);
-  if (msg.toolCallId) console.log('  工具调用ID:', msg.toolCallId);
-});
-console.log();
-
-// 测试 5：撤回功能（可选）
-console.log('===== 测试5：撤回最后一条助手消息 =====');
-const removed = chat.messages.undoToLastAssistant();
-console.log(`撤回了 ${removed.length} 条消息`);
-const afterUndo = chat.messages.getAll();
-console.log(`剩余消息数: ${afterUndo.length}`);
-
-console.log('\n✅ 所有测试完成！');