minimal-agent 0.10.0 → 0.12.0

package/src/llm/providers/openaiFormat.ts

@@ -0,0 +1,428 @@
+/**
+ * ============================================================
+ *  src/llm/providers/openaiFormat.ts —— OpenAI Chat Completions 协议
+ * ------------------------------------------------------------
+ *  从 client.ts 拆出来的格式相关部分：请求体构造 + SSE chunk → LlmStreamEvent。
+ *  重试/退避/空闲看门狗等协议无关的骨架留在 client.ts，两个格式模块共用。
+ * ============================================================
+ */
+
+import type {
+  LlmStreamEvent,
+  Message,
+  PromptCacheContext,
+  PromptCacheUsage,
+  Provider,
+  Tool,
+} from '../../types.js';
+
+/** LLM 收到的 tool 描述格式（OpenAI function-calling 协议）。 */
+interface OpenAIToolSpec {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    /** JSON Schema 描述参数；模型会按它生成 arguments */
+    parameters: object;
+  };
+}
+
+/**
+ * 判断一个 400 是否在抱怨 response_format（json_schema）不被支持。
+ * 各 provider 文案不一（火山 GLM：`json_schema is not supported by this model`），
+ * 故宽松匹配："提到 response_format" 且 "出现 not support / unsupported / not valid / invalid"。
+ */
+export function isResponseFormatUnsupported(status: number, errText: string): boolean {
+  if (status !== 400) return false;
+  const t = errText.toLowerCase();
+  if (!t.includes('response_format')) return false;
+  return (
+    t.includes('not support') ||
+    t.includes('unsupported') ||
+    t.includes('not valid') ||
+    t.includes('invalid')
+  );
+}
+
+/**
+ * 判断一个 400 是否在抱怨 max_tokens（不支持 / 超模型上限 / 取值非法）。
+ * 文案各家不一，故宽松匹配："提到 max_tokens" 且 "出现 not support / invalid /
+ * exceed / too large / out of range / maximum"。命中后去掉 max_tokens 重发即可。
+ */
+export function isMaxTokensRejected(status: number, errText: string): boolean {
+  if (status !== 400) return false;
+  const t = errText.toLowerCase();
+  if (!t.includes('max_tokens') && !t.includes('max tokens')) return false;
+  return (
+    t.includes('not support') ||
+    t.includes('unsupported') ||
+    t.includes('not valid') ||
+    t.includes('invalid') ||
+    t.includes('exceed') ||
+    t.includes('too large') ||
+    t.includes('out of range') ||
+    t.includes('maximum')
+  );
+}
+
+/**
+ * 判断一个 4xx 是否在抱怨图片/image_url/多模态输入不被支持。
+ * 匹配关键词：image_url、image、vision、multimodal + not support/unsupported/invalid 等。
+ * 排除图片尺寸/大小/格式等临时性错误，以及参数值错误（如 detail 取值非法），这些不是模型不支持图片。
+ */
+export function isImageInputRejected(status: number, errText: string): boolean {
+  if (status !== 400 && status !== 404) return false;
+  const t = errText.toLowerCase();
+
+  // 先排除临时性图片错误（尺寸太小/太大、格式问题、参数值非法等）：这些重试或调整参数后可能成功，不是模型不支持
+  if (t.includes('dimension') || t.includes('too small') || t.includes('too large')
+    || t.includes('maximum') || t.includes('exceed') || t.includes('out of range')
+    || t.includes('invalid format') || t.includes('decode') || t.includes('corrupt')
+    || (t.includes('image_url') && t.includes('supported values'))) { // detail 等参数取值非法
+    return false;
+  }
+
+  const hasImageKw = t.includes('image_url') || t.includes('image') || t.includes('vision') || t.includes('multimodal') || t.includes('不支持图片') || t.includes('图片输入');
+  if (!hasImageKw) return false;
+  return (
+    t.includes('not support') ||
+    t.includes('unsupported') ||
+    t.includes('not valid') ||
+    t.includes('not allowed') ||
+    t.includes('does not support') ||
+    t.includes('cannot accept') ||
+    t.includes('no access') ||
+    t.includes('not found') ||
+    t.includes('不存在') ||
+    t.includes('不支持')
+  );
+}
+
+export function isPromptCacheKeyRejected(status: number, errText: string): boolean {
+  if (status < 400 || status >= 500) return false;
+  const text = errText.toLowerCase();
+  return (
+    (text.includes('prompt_cache_key') || text.includes('prompt cache key')) &&
+    (text.includes('unsupported') ||
+      text.includes('not support') ||
+      text.includes('unknown') ||
+      text.includes('invalid') ||
+      text.includes('extra'))
+  );
+}
+
+export interface OpenAIRequestArgs {
+  provider: Provider;
+  cleanedMessages: unknown[];
+  tools: Tool[];
+  withResponseFormat: boolean;
+  withMaxTokens: boolean;
+  includeUsage: boolean;
+  promptCache?: PromptCacheContext;
+  withPromptCacheKey?: boolean;
+  responseFormat?: {
+    type: 'json_schema';
+    json_schema: { name: string; schema: Record<string, unknown>; strict?: boolean };
+  };
+}
+
+/**
+ * 递归遍历消息，把 image_url.detail: 'default' 转换成 'auto'。
+ * OpenAI 兼容 API（豆包/火山引擎等）不接受 'default'，标准默认值是 'auto'。
+ */
+function normalizeImageDetailForOpenAI(messages: unknown[]): unknown[] {
+  return messages.map((msg) => {
+    if (!msg || typeof msg !== 'object') return msg;
+    const m = msg as Record<string, unknown>;
+    if (Array.isArray(m.content)) {
+      m.content = m.content.map((part: unknown) => {
+        if (!part || typeof part !== 'object') return part;
+        const p = part as Record<string, unknown>;
+        if (p.type === 'image_url' && p.image_url && typeof p.image_url === 'object') {
+          const imgUrl = p.image_url as Record<string, unknown>;
+          if (imgUrl.detail === 'default') {
+            imgUrl.detail = 'auto';
+          }
+        }
+        return p;
+      });
+    }
+    return m;
+  });
+}
+
+/**
+ * 图像滑动窗口限制（对齐UI-TARS）：
+ * 最多保留最近N张图片，超出时从最旧的消息开始删除图片。
+ * 防止LLM对话历史中图像过多导致token爆炸。
+ */
+const MAX_IMAGES_IN_CONTEXT = 10;
+
+/**
+ * 限制消息历史中的图片数量（滑动窗口）。
+ * 从最旧的消息开始，如果图片数量超过MAX_IMAGES_IN_CONTEXT，删除最旧的图片。
+ */
+function limitImageCount(messages: unknown[]): unknown[] {
+  // 统计所有图片数量
+  let imageCount = 0;
+  const messagesWithImages: Array<{ msgIdx: number; contentIdx: number }> = [];
+  
+  messages.forEach((msg, msgIdx) => {
+    if (!msg || typeof msg !== 'object') return;
+    const m = msg as Record<string, unknown>;
+    if (Array.isArray(m.content)) {
+      m.content.forEach((part: unknown, contentIdx: number) => {
+        if (!part || typeof part !== 'object') return;
+        const p = part as Record<string, unknown>;
+        if (p.type === 'image_url') {
+          imageCount++;
+          messagesWithImages.push({ msgIdx, contentIdx });
+        }
+      });
+    }
+  });
+  
+  // 如果图片数量超过限制，从最旧的开始删除
+  if (imageCount > MAX_IMAGES_IN_CONTEXT) {
+    const toDelete = messagesWithImages.slice(0, imageCount - MAX_IMAGES_IN_CONTEXT);
+    // 从后往前删除，避免索引偏移
+    for (let i = toDelete.length - 1; i >= 0; i--) {
+      const { msgIdx, contentIdx } = toDelete[i];
+      const msg = messages[msgIdx] as Record<string, unknown>;
+      if (Array.isArray(msg.content)) {
+        msg.content.splice(contentIdx, 1);
+      }
+    }
+  }
+  
+  return messages;
+}
+
+function looksLikeVersionedBase(url: string): boolean {
+  try {
+    const u = new URL(url);
+    const path = u.pathname.replace(/\/+$/, '');
+    if (path === '' || path === '/') return true;
+    const segments = path.split('/');
+    const last = segments[segments.length - 1];
+    return /^v\d+/.test(last);
+  } catch {
+    return false;
+  }
+}
+
+export function buildOpenAIUrl(provider: Provider): string {
+  // baseURL 是完整端点 URL（以 /chat/completions 结尾）。
+  // 向后兼容：旧格式 baseURL（版本化基础路径，如 /v1）自动补全后缀，并打 warning。
+  const url = provider.baseURL.trim().replace(/\/+$/, '');
+  if (url.endsWith('/chat/completions') || url.endsWith('/v1/messages')) return url;
+  if (url.length === 0) return url;
+  if (looksLikeVersionedBase(url)) {
+    console.warn(
+      `[minimal-agent] 旧格式 baseURL 检测："${provider.baseURL}" 未包含端点后缀，` +
+      `已自动补全为 "${url}/chat/completions"。请在设置页更新为完整端点地址。`,
+    );
+    return `${url}/chat/completions`;
+  }
+  return url;
+}
+
+export function buildOpenAIRequest(args: OpenAIRequestArgs): { url: string; headers: Record<string, string>; body: string } {
+  const {
+    provider,
+    cleanedMessages,
+    tools,
+    withResponseFormat,
+    withMaxTokens,
+    includeUsage,
+    responseFormat,
+    promptCache,
+    withPromptCacheKey,
+  } = args;
+  // 转换 image_url.detail: 'default' → 'auto'，兼容所有 OpenAI 兼容 provider
+  let messages = normalizeImageDetailForOpenAI(cleanedMessages);
+  // 限制图片数量（滑动窗口），防止token爆炸
+  messages = limitImageCount(messages);
+  const openaiTools: OpenAIToolSpec[] = tools.map((t) => ({
+    type: 'function',
+    function: {
+      name: t.name,
+      description: typeof t.description === 'function' ? t.description() : t.description,
+      parameters: t.parameters,
+    },
+  }));
+  return {
+    url: buildOpenAIUrl(provider),
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${provider.apiKey}`,
+    },
+    body: JSON.stringify({
+      model: provider.model,
+      messages,
+      tools: openaiTools.length > 0 ? openaiTools : undefined,
+      stream: true,
+      // 显式输出上限：兜住默认上限偏小的 provider（豆包默认 4096）。缺省 undefined 不出现在 body。
+      max_tokens: withMaxTokens ? provider.maxTokens : undefined,
+      // stream_options.include_usage：让 provider 在流末附带真实 prompt_tokens，
+      // 供上层自动压缩判断用；provider 不支持时 usagePromptTokens 保持 undefined，上层 fallback 本地估算。
+      ...(includeUsage ? { stream_options: { include_usage: true } } : {}),
+      // tool_choice: 'auto' 是默认值，可不写；某些 provider 必须显式
+      tool_choice: openaiTools.length > 0 ? 'auto' : undefined,
+      // ADR-05: structured output；缺省 undefined 不出现在 body（JSON.stringify 自动剥离）
+      response_format: withResponseFormat ? responseFormat : undefined,
+      ...(withPromptCacheKey && promptCache?.scopeKey
+        ? { prompt_cache_key: promptCache.scopeKey }
+        : {}),
+    }),
+  };
+}
+
+/**
+ * 从 usage 帧里抽出「命中缓存的 prompt token 数」。
+ *
+ * 各家 OpenAI 兼容 provider 的字段形状不统一，且都属于自动前缀缓存（不需要我们在请求里
+ * 发任何标记），只在 usage 里回报命中量。已知三种形状，按优先级依次探测：
+ *   1. `prompt_tokens_details.cached_tokens` —— OpenAI 官方形状，Kimi/智谱等跟随
+ *   2. `prompt_cache_hit_tokens`             —— DeepSeek 形状（配对 prompt_cache_miss_tokens）
+ *   3. `cached_tokens`                       —— 少数 provider 直接平铺在 usage 上
+ * 全都拿不到就返回 undefined（≠ 0）——「没报告」和「报告了 0 命中」必须可区分，
+ * 否则观测层会把不支持缓存的 provider 显示成「命中率 0%」，误导排障。
+ *
+ * ⚠️ OpenAI 协议里 prompt_tokens **已包含**缓存命中部分，cached_tokens 只是其子集明细，
+ * 所以这里不需要对 promptTokens 做任何加法（Anthropic 相反，见 anthropicFormat.ts）。
+ */
+export function extractPromptCacheUsage(usage: unknown): PromptCacheUsage {
+  if (!usage || typeof usage !== 'object') return { reported: false };
+  const u = usage as Record<string, unknown>;
+  let cacheReadTokens: number | undefined;
+  const details = u.prompt_tokens_details;
+  if (details && typeof details === 'object') {
+    const cached = (details as Record<string, unknown>).cached_tokens;
+    if (typeof cached === 'number' && Number.isFinite(cached)) cacheReadTokens = cached;
+  }
+  if (cacheReadTokens === undefined && typeof u.prompt_cache_hit_tokens === 'number' && Number.isFinite(u.prompt_cache_hit_tokens)) {
+    cacheReadTokens = u.prompt_cache_hit_tokens;
+  }
+  if (cacheReadTokens === undefined && typeof u.cached_tokens === 'number' && Number.isFinite(u.cached_tokens)) {
+    cacheReadTokens = u.cached_tokens;
+  }
+  const cacheMissTokens =
+    typeof u.prompt_cache_miss_tokens === 'number' && Number.isFinite(u.prompt_cache_miss_tokens)
+      ? u.prompt_cache_miss_tokens
+      : undefined;
+  const directPrompt =
+    typeof u.prompt_tokens === 'number' && Number.isFinite(u.prompt_tokens)
+      ? u.prompt_tokens
+      : undefined;
+  const promptTokens =
+    directPrompt ??
+    (cacheReadTokens !== undefined && cacheMissTokens !== undefined
+      ? cacheReadTokens + cacheMissTokens
+      : undefined);
+  const reported =
+    cacheReadTokens !== undefined ||
+    cacheMissTokens !== undefined;
+  return {
+    reported,
+    ...(promptTokens !== undefined ? { promptTokens } : {}),
+    ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}),
+    ...(cacheMissTokens !== undefined ? { cacheMissTokens } : {}),
+  };
+}
+
+/** Compatibility helper retained for existing callers/tests. */
+export function extractCachedPromptTokens(usage: unknown): number | undefined {
+  return extractPromptCacheUsage(usage).cacheReadTokens;
+}
+
+/** 每个请求一个新实例；把逐条 SSE `data:` 行的内容转换成 LlmStreamEvent（0..N 个）。 */
+export function createOpenAISSEParser(): {
+  handleData(dataStr: string): LlmStreamEvent[];
+  /** 流意外中断（没收到显式 [DONE]）时，用累积状态兜底发一个 done。 */
+  buildFallbackDone(): LlmStreamEvent;
+} {
+  let stopReason: 'stop' | 'tool_calls' | 'length' | 'unknown' = 'unknown';
+  let usagePromptTokens: number | undefined;
+  let usageCachedTokens: number | undefined;
+  let usageCacheMissTokens: number | undefined;
+  let promptCacheUsage: PromptCacheUsage = { reported: false };
+  return {
+    buildFallbackDone(): LlmStreamEvent {
+      return {
+        type: 'done',
+        stopReason,
+        promptTokens: usagePromptTokens,
+        cachedPromptTokens: usageCachedTokens,
+        cacheMissTokens: usageCacheMissTokens,
+        promptCacheUsage,
+      };
+    },
+    handleData(dataStr: string): LlmStreamEvent[] {
+      if (dataStr === '[DONE]') {
+        return [{
+          type: 'done',
+          stopReason,
+          promptTokens: usagePromptTokens,
+          cachedPromptTokens: usageCachedTokens,
+          cacheMissTokens: usageCacheMissTokens,
+          promptCacheUsage,
+        }];
+      }
+      let chunk: any;
+      try {
+        chunk = JSON.parse(dataStr);
+      } catch {
+        // 罕见：某些 provider 会发空行或心跳，忽略
+        return [];
+      }
+      const events: LlmStreamEvent[] = [];
+      // usage chunk：include_usage 开启时，provider 通常在流末单独发一帧，
+      // 此帧 choices 为空（没有 delta），必须在 `if (!delta) return` 之前读取，
+      // 否则会被跳过，永远拿不到真实 prompt_tokens。
+      if (chunk.usage) {
+        const cacheUsage = extractPromptCacheUsage(chunk.usage);
+        promptCacheUsage = cacheUsage;
+        if (cacheUsage.promptTokens !== undefined) usagePromptTokens = cacheUsage.promptTokens;
+        if (cacheUsage.cacheReadTokens !== undefined) usageCachedTokens = cacheUsage.cacheReadTokens;
+        if (cacheUsage.cacheMissTokens !== undefined) usageCacheMissTokens = cacheUsage.cacheMissTokens;
+      }
+      const delta = chunk.choices?.[0]?.delta;
+      const finish = chunk.choices?.[0]?.finish_reason;
+      if (finish) {
+        stopReason = finish === 'stop' || finish === 'tool_calls' || finish === 'length' ? finish : 'unknown';
+      }
+      if (!delta) return events;
+
+      // 文本增量。注意：MiniMax 等模型默认会把 <think>...</think> 标签直接放在
+      // content 字段里——我们原样累积，不剥离，确保下一轮工具调用时思维链完整回传。
+      if (typeof delta.content === 'string' && delta.content.length > 0) {
+        events.push({ type: 'text_delta', delta: delta.content });
+      }
+      // tool_calls 增量（OpenAI 协议下 tool_calls 也是分片返回的）
+      if (Array.isArray(delta.tool_calls)) {
+        for (const tc of delta.tool_calls) {
+          events.push({
+            type: 'tool_call_delta',
+            index: tc.index ?? 0,
+            id: tc.id,
+            name: tc.function?.name,
+            argumentsDelta: tc.function?.arguments,
+          });
+        }
+      }
+      // 思维链增量（DeepSeek-R1 / MiniMax reasoning_split / OpenRouter）
+      // 三种字段名都见过：reasoning_content / reasoning / reasoning_details
+      if (typeof delta.reasoning_content === 'string' && delta.reasoning_content.length > 0) {
+        events.push({ type: 'reasoning_delta', field: 'reasoning_content', delta: delta.reasoning_content });
+      }
+      if (typeof delta.reasoning === 'string' && delta.reasoning.length > 0) {
+        events.push({ type: 'reasoning_delta', field: 'reasoning', delta: delta.reasoning });
+      }
+      if (Array.isArray(delta.reasoning_details) && delta.reasoning_details.length > 0) {
+        events.push({ type: 'reasoning_delta', field: 'reasoning_details', items: delta.reasoning_details });
+      }
+      return events;
+    },
+  };
+}