@huyooo/ai-chat-core 0.2.45 → 0.3.2

package/src/protocols/glm.ts

@@ -0,0 +1,212 @@
+/**
+ * GLM Protocol（GLM OpenAI 兼容模式 API）
+ *
+ * API 格式与 Qwen 几乎一致（OpenAI Chat Completions），
+ * 主要区别：
+ * - thinking 参数：`"thinking": {"type": "enabled"}` （Qwen 用 `"enable_thinking": true`）
+ * - 默认 URL：https://open.bigmodel.cn/api/paas/v4
+ */
+
+import type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  RawEvent,
+} from './types';
+import { createModuleLogger } from '../logger';
+import { friendlyHttpError } from './error-utils';
+import { readSSEJsonStream } from './sse-reader';
+import { mapOpenAIStream } from './openai-sse';
+import type { OpenAIStreamConfig } from './openai-sse';
+
+const logger = createModuleLogger('GlmProtocol');
+
+const DEFAULT_GLM_URL = 'https://open.bigmodel.cn/api/paas/v4';
+
+const GLM_SSE_CONFIG: OpenAIStreamConfig = {
+  thinkingField: (delta) => delta.reasoning_content as string | undefined,
+  errorFinishReasons: ['sensitive', 'network_error'],
+  protocolName: 'GLM',
+  parseUsage: (usage) => ({
+    promptTokens: (usage.prompt_tokens as number) ?? 0,
+    completionTokens: (usage.completion_tokens as number) ?? 0,
+    totalTokens: (usage.total_tokens as number) ?? 0,
+    cachedTokens: (usage.prompt_tokens_details as Record<string, number> | undefined)?.cached_tokens ?? 0,
+  }),
+};
+
+export class GlmProtocol implements Protocol {
+  readonly name = 'glm';
+
+  private apiKey: string;
+  private apiUrl: string;
+
+  constructor(config: ProtocolConfig) {
+    this.apiKey = config.apiKey;
+    this.apiUrl = config.apiUrl || DEFAULT_GLM_URL;
+  }
+
+  async *stream(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): AsyncGenerator<RawEvent> {
+    const requestBody = this.buildRequestBody(messages, tools, options);
+    const url = `${this.apiUrl}/chat/completions`;
+
+    logger.debug({
+      url,
+      model: options.model,
+      enableThinking: options.enableThinking,
+      toolsCount: tools.length,
+    }, '发送 GLM 请求');
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(requestBody),
+      signal: options.signal,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      logger.error({ status: response.status, body: errorText.slice(0, 500) }, 'GLM API 错误');
+      yield { type: 'error', error: friendlyHttpError(response.status, errorText, 'GLM') };
+      return;
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: 'error', error: '无法获取响应流' };
+      return;
+    }
+
+    let hadThinkingDelta = false;
+    let hadTextDelta = false;
+    let hadToolCall = false;
+    for await (const ev of mapOpenAIStream(readSSEJsonStream(reader), GLM_SSE_CONFIG)) {
+      if (ev.type === 'thinking_delta') hadThinkingDelta = true;
+      if (ev.type === 'text_delta') hadTextDelta = true;
+      if (ev.type === 'tool_call_start' || ev.type === 'tool_call_done') hadToolCall = true;
+      yield ev;
+    }
+    const payload = {
+      model: options.model,
+      toolsCount: tools.length,
+      hadThinkingDelta,
+      hadTextDelta,
+      hadToolCall,
+    };
+    if (!hadThinkingDelta && !hadTextDelta && !hadToolCall) {
+      // 与 Orchestrator「空响应」合并：此处仅 debug，避免与编排层重复 WARN
+      logger.debug(payload, 'GLM 流结束：未产出思考/正文/工具调用（常见于工具或上下文过大）');
+    } else {
+      logger.debug(payload, 'GLM 流结束');
+    }
+  }
+
+  private buildRequestBody(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): Record<string, unknown> {
+    const convertedMessages = this.convertMessages(messages);
+
+    const maxTokens = options.maxOutputTokens;
+
+    const body: Record<string, unknown> = {
+      model: options.model,
+      messages: convertedMessages,
+      stream: true,
+      stream_options: { include_usage: true },
+      max_tokens: maxTokens,
+    };
+
+    // GLM thinking 默认 enabled（文档默认值），必须显式发送 disabled 才能关闭
+    if (options.enableThinking) {
+      body.thinking = { type: 'enabled' };
+      body.temperature = 1.0;
+    } else {
+      body.thinking = { type: 'disabled' };
+    }
+
+    if (tools.length > 0) {
+      body.tools = tools.map(t => ({
+        type: 'function',
+        function: {
+          name: t.name,
+          description: t.description,
+          parameters: t.parameters,
+        },
+      }));
+    }
+
+    return body;
+  }
+
+  private convertMessages(messages: ProtocolMessage[]): unknown[] {
+    const result: unknown[] = [];
+
+    for (const msg of messages) {
+      switch (msg.role) {
+        case 'system':
+          result.push({ role: 'system', content: msg.content });
+          break;
+
+        case 'user': {
+          const textContent = msg.content || (msg.images?.length ? '请分析这张图片' : '');
+          if (msg.images?.length) {
+            const content: unknown[] = [{ type: 'text', text: textContent }];
+            for (const img of msg.images) {
+              content.push({
+                type: 'image_url',
+                image_url: { url: img.startsWith('data:') ? img : `data:image/jpeg;base64,${img}` },
+              });
+            }
+            result.push({ role: 'user', content });
+          } else {
+            result.push({ role: 'user', content: textContent });
+          }
+          break;
+        }
+
+        case 'assistant':
+          if (msg.toolCalls?.length) {
+            result.push({
+              role: 'assistant',
+              content: msg.content || null,
+              ...(msg.thinkingContent ? { reasoning_content: msg.thinkingContent } : {}),
+              tool_calls: msg.toolCalls.map(tc => ({
+                id: tc.id,
+                type: 'function',
+                function: { name: tc.name, arguments: tc.arguments },
+              })),
+            });
+          } else {
+            result.push({ role: 'assistant', content: msg.content });
+          }
+          break;
+
+        case 'tool':
+          result.push({
+            role: 'tool',
+            tool_call_id: msg.toolCallId,
+            content: msg.content,
+          });
+          break;
+      }
+    }
+
+    return result;
+  }
+
+}
+
+export function createGlmProtocol(config: ProtocolConfig): GlmProtocol {
+  return new GlmProtocol(config);
+}

package/src/protocols/grok.ts

@@ -0,0 +1,98 @@
+/**
+ * Grok Protocol（xAI Responses API）
+ *
+ * xAI 与 OpenAI 使用相同的 Responses API 格式（/v1/responses），
+ * 共享消息转换和 SSE 解析逻辑，仅保留 Grok 特有的入口和参数差异。
+ *
+ * 支持直连 api.x.ai 或代理（如 llm.huyooo.com/grok）。
+ *
+ * 文档：https://docs.x.ai/developers/rest-api-reference/inference/chat
+ */
+
+import type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  RawEvent,
+} from './types';
+import { createModuleLogger } from '../logger';
+import { friendlyHttpError } from './error-utils';
+import { convertToResponsesInput, convertToResponsesTools, mapResponsesStream } from './responses-sse';
+
+const logger = createModuleLogger('GrokProtocol');
+
+const DEFAULT_GROK_URL = 'https://api.x.ai/v1';
+
+export class GrokProtocol implements Protocol {
+  readonly name = 'grok';
+
+  private apiKey: string;
+  private apiUrl: string;
+
+  constructor(config: ProtocolConfig) {
+    this.apiKey = config.apiKey;
+    this.apiUrl = config.apiUrl ?? DEFAULT_GROK_URL;
+  }
+
+  async *stream(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions,
+  ): AsyncGenerator<RawEvent> {
+    const body: Record<string, unknown> = {
+      model: options.model,
+      input: convertToResponsesInput(messages),
+      stream: true,
+      max_output_tokens: options.maxOutputTokens,
+      store: false,
+    };
+
+    if (options.enableThinking) {
+      body.reasoning = { effort: 'high' };
+    }
+
+    if (tools.length > 0) {
+      body.tools = convertToResponsesTools(tools);
+    }
+
+    const url = `${this.apiUrl}/responses`;
+
+    logger.debug({
+      url,
+      model: options.model,
+      enableThinking: options.enableThinking,
+      toolsCount: tools.length,
+    }, 'Grok Responses 请求');
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal: options.signal,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      logger.error({ status: response.status, body: errorText.slice(0, 500) }, 'Grok API 错误');
+      yield { type: 'error', error: friendlyHttpError(response.status, errorText, 'Grok') };
+      return;
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: 'error', error: '无法获取响应流' };
+      return;
+    }
+
+    yield* mapResponsesStream(reader, { protocolName: 'Grok' });
+  }
+}
+
+export function createGrokProtocol(config: ProtocolConfig): GrokProtocol {
+  return new GrokProtocol(config);
+}

package/src/protocols/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Protocol Layer 导出
+ * 
+ * Protocol 只负责 HTTP/SSE 通信，不处理业务逻辑
+ * 
+ * 每个 Protocol 对应一种 API 协议：
+ * - ArkProtocol: 火山引擎 Responses API（Doubao）
+ * - DeepSeekProtocol: DeepSeek 原生 Chat Completions API
+ * - QwenProtocol: Qwen DashScope API
+ * - GlmProtocol: GLM API
+ * - MoonshotProtocol: Kimi API
+ * - MiniMaxProtocol: MiniMax Anthropic 兼容 API
+ * - VercelGateway: GPT + Gemini + Claude（通过 Vercel AI Gateway V3 协议）
+ * - GeminiProtocol: Google Gemini 原生 API（直连 / 代理透传）
+ * - OpenAIProtocol: OpenAI Responses API（直连 / 代理透传，统一支持 GPT / Codex / o-series）
+ * - GrokProtocol: xAI Grok（独立实现，reasoning_content 思考格式）
+ */
+
+// 类型 + 协议标识
+export type {
+  ProtocolId,
+  RawEventType,
+  RawEvent,
+  RawOutputPart,
+  RawToolCall,
+  RawTokenUsage,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  Protocol,
+  ProtocolConfig,
+  ProtocolAttachment,
+  ProtocolFactory,
+} from './types';
+export { getBaseProtocol } from './types';
+
+// 各 Protocol 实现
+export { ArkProtocol, createArkProtocol } from './ark';
+export { DeepSeekProtocol, createDeepSeekProtocol } from './deepseek';
+export { QwenProtocol, createQwenProtocol } from './qwen';
+export { GlmProtocol, createGlmProtocol } from './glm';
+export { MoonshotProtocol, createMoonshotProtocol } from './moonshot';
+export { MiniMaxProtocol, createMiniMaxProtocol } from './minimax';
+export { createVercelGatewayProtocol } from './vercel-gateway';
+export { AnthropicProtocol, createAnthropicProtocol } from './anthropic';
+export { GeminiProtocol, createGeminiProtocol } from './gemini';
+export { OpenAIProtocol, createOpenAIProtocol } from './openai';
+export { GrokProtocol, createGrokProtocol } from './grok';

package/src/protocols/minimax.ts

@@ -0,0 +1,308 @@
+/**
+ * MiniMax Protocol（Anthropic Messages API 兼容）
+ *
+ * 官方推荐使用 Anthropic 格式接入 MiniMax-M2.5。
+ * 主要区别于 OpenAI 兼容协议：
+ * - SSE 使用 Anthropic 命名事件（content_block_start/delta/stop）
+ * - Thinking 始终开启，通过 thinking_delta 事件输出
+ * - 工具调用使用 tool_use/tool_result 格式
+ * - system 是顶层参数（不在 messages 内）
+ *
+ * @see https://platform.minimaxi.com/docs/api-reference/text-anthropic-api
+ */
+
+import type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolRequestOptions,
+  RawEvent,
+  RawToolCall,
+} from './types';
+import { createModuleLogger } from '../logger';
+import { friendlyHttpError } from './error-utils';
+import { readSSEJsonStream } from './sse-reader';
+import { parseProtocolToolArguments } from './tool-arguments';
+
+const logger = createModuleLogger('MiniMaxProtocol');
+
+const DEFAULT_MINIMAX_URL = 'https://api.minimaxi.com/anthropic';
+
+export class MiniMaxProtocol implements Protocol {
+  readonly name = 'minimax';
+
+  private apiKey: string;
+  private apiUrl: string;
+
+  constructor(config: ProtocolConfig) {
+    this.apiKey = config.apiKey;
+    this.apiUrl = config.apiUrl || DEFAULT_MINIMAX_URL;
+  }
+
+  async *stream(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): AsyncGenerator<RawEvent> {
+    const requestBody = this.buildRequestBody(messages, tools, options);
+    const url = `${this.apiUrl}/v1/messages`;
+
+    logger.debug({
+      url,
+      model: options.model,
+      enableThinking: options.enableThinking,
+      toolsCount: tools.length,
+    }, '发送 MiniMax 请求（Anthropic 格式）');
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'x-api-key': this.apiKey,
+        'anthropic-version': '2023-06-01',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(requestBody),
+      signal: options.signal,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      logger.error({ status: response.status, body: errorText.slice(0, 500) }, 'MiniMax API 错误');
+      yield { type: 'error', error: friendlyHttpError(response.status, errorText, 'MiniMax') };
+      return;
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: 'error', error: '无法获取响应流' };
+      return;
+    }
+
+    yield* this.parseAnthropicSSE(reader);
+  }
+
+  private buildRequestBody(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: ProtocolRequestOptions
+  ): Record<string, unknown> {
+    const { systemPrompt, convertedMessages } = this.convertMessages(messages);
+
+    const body: Record<string, unknown> = {
+      model: options.model,
+      messages: convertedMessages,
+      max_tokens: options.maxOutputTokens,
+      stream: true,
+    };
+
+    if (systemPrompt) {
+      body.system = systemPrompt;
+    }
+
+    if (tools.length > 0) {
+      body.tools = tools.map(t => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.parameters,
+      }));
+    }
+
+    return body;
+  }
+
+  /**
+   * 转换消息格式（ProtocolMessage → Anthropic Messages 格式）
+   *
+   * Anthropic 格式要求：
+   * - system 是顶层参数，不在 messages 里
+   * - messages 必须 user/assistant 交替
+   * - 工具结果用 tool_result 块放在 user 消息里
+   */
+  private convertMessages(messages: ProtocolMessage[]): {
+    systemPrompt: string;
+    convertedMessages: unknown[];
+  } {
+    let systemPrompt = '';
+    const result: unknown[] = [];
+
+    for (const msg of messages) {
+      switch (msg.role) {
+        case 'system':
+          systemPrompt += (systemPrompt ? '\n\n' : '') + msg.content;
+          break;
+
+        case 'user':
+          result.push({
+            role: 'user',
+            content: [{ type: 'text', text: msg.content || '' }],
+          });
+          break;
+
+        case 'assistant':
+          if (msg.toolCalls?.length) {
+            // assistant 带工具调用：先文本再 tool_use 块
+            const content: unknown[] = [];
+            if (msg.content) {
+              content.push({ type: 'text', text: msg.content });
+            }
+            for (const tc of msg.toolCalls) {
+              content.push({
+                type: 'tool_use',
+                id: tc.id,
+                name: tc.name,
+                input: parseProtocolToolArguments(tc.arguments, {
+                  protocol: this.name,
+                  toolCallId: tc.id,
+                  toolName: tc.name,
+                }),
+              });
+            }
+            result.push({ role: 'assistant', content });
+          } else {
+            result.push({
+              role: 'assistant',
+              content: [{ type: 'text', text: msg.content || '' }],
+            });
+          }
+          break;
+
+        case 'tool':
+          // Anthropic 格式：tool_result 放在 user 消息中
+          result.push({
+            role: 'user',
+            content: [{
+              type: 'tool_result',
+              tool_use_id: msg.toolCallId,
+              content: msg.content,
+            }],
+          });
+          break;
+      }
+    }
+
+    return { systemPrompt, convertedMessages: result };
+  }
+
+  /**
+   * Anthropic SSE 解析（MiniMax 兼容）
+   *
+   * Layer 1 负责 bytes → JSON，此处通过 json.type 做语义映射。
+   */
+  private async *parseAnthropicSSE(
+    reader: ReadableStreamDefaultReader<Uint8Array>,
+  ): AsyncGenerator<RawEvent> {
+    let thinkingStarted = false;
+    let thinkingDone = false;
+    const toolCalls = new Map<number, RawToolCall & { jsonBuffer: string }>();
+    let inputTokens = 0;
+    let outputTokens = 0;
+
+    for await (const json of readSSEJsonStream(reader)) {
+      switch (json.type) {
+        case 'message_start': {
+          const msg = json.message as Record<string, unknown> | undefined;
+          const msgUsage = msg?.usage as Record<string, number> | undefined;
+          if (msgUsage?.input_tokens) {
+            inputTokens = msgUsage.input_tokens;
+          }
+          break;
+        }
+
+        case 'content_block_start': {
+          const block = json.content_block as Record<string, unknown> | undefined;
+          if (block?.type === 'tool_use') {
+            if (!block.id) logger.warn({ index: json.index }, 'content_block_start tool_use 缺少 id');
+            if (!block.name) logger.warn({ index: json.index, id: block.id }, 'content_block_start tool_use 缺少 name');
+            const index = (json.index as number) ?? toolCalls.size;
+            const id = (block.id as string) || `call_${index}`;
+            const name = (block.name as string) || '';
+            toolCalls.set(index, { id, name, arguments: '', jsonBuffer: '' });
+            yield { type: 'tool_call_start', toolCall: { id, name } };
+          }
+          break;
+        }
+
+        case 'content_block_delta': {
+          const delta = json.delta as Record<string, unknown> | undefined;
+          if (!delta) break;
+
+          if (delta.type === 'thinking_delta' && delta.thinking) {
+            if (!thinkingDone) {
+              thinkingStarted = true;
+              yield { type: 'thinking_delta', delta: delta.thinking as string };
+            }
+          } else if (delta.type === 'text_delta' && delta.text) {
+            if (thinkingStarted && !thinkingDone) {
+              thinkingDone = true;
+              yield { type: 'thinking_done' };
+            }
+            yield { type: 'text_delta', delta: delta.text as string };
+          } else if (delta.type === 'input_json_delta' && delta.partial_json !== undefined) {
+            const index = json.index as number;
+            const tc = toolCalls.get(index);
+            if (tc) {
+              tc.jsonBuffer += delta.partial_json;
+            }
+          }
+          break;
+        }
+
+        case 'content_block_stop': {
+          const index = json.index as number;
+          const tc = toolCalls.get(index);
+          if (tc) {
+            tc.arguments = tc.jsonBuffer;
+            yield {
+              type: 'tool_call_done',
+              toolCall: { id: tc.id, name: tc.name, arguments: tc.arguments },
+            };
+          }
+          break;
+        }
+
+        case 'message_delta': {
+          const deltaUsage = json.usage as Record<string, number> | undefined;
+          if (deltaUsage?.output_tokens) {
+            outputTokens = deltaUsage.output_tokens;
+          }
+          break;
+        }
+
+        case 'message_stop': {
+          const hasToolCalls = toolCalls.size > 0;
+          const usage = {
+            promptTokens: inputTokens,
+            completionTokens: outputTokens,
+            totalTokens: inputTokens + outputTokens,
+          };
+          if (thinkingStarted && !thinkingDone) {
+            thinkingDone = true;
+            yield { type: 'thinking_done' };
+          }
+          yield {
+            type: 'done',
+            finishReason: hasToolCalls ? 'tool_calls' : 'stop',
+            usage,
+          };
+          return;
+        }
+      }
+    }
+
+    // 流异常中断兜底
+    if (thinkingStarted && !thinkingDone) {
+      yield { type: 'thinking_done' };
+    }
+    const hasToolCalls = toolCalls.size > 0;
+    yield {
+      type: 'done',
+      finishReason: hasToolCalls ? 'tool_calls' : 'stop',
+      usage: { promptTokens: inputTokens, completionTokens: outputTokens, totalTokens: inputTokens + outputTokens },
+    };
+  }
+}
+
+export function createMiniMaxProtocol(config: ProtocolConfig): MiniMaxProtocol {
+  return new MiniMaxProtocol(config);
+}