minimal-agent 0.10.0 → 0.12.0

package/src/llm/promptCache.ts

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+
+import type { PromptCacheContext, PromptCacheMode } from '../types.js';
+
+const SCOPE_VERSION = 'minimal-agent:prompt-cache:v1';
+
+/** Build a provider-safe cache routing key without exposing local identity. */
+export function createPromptCacheContext(
+  conversationKey: string,
+  namespace = 'main',
+): PromptCacheContext {
+  const scopeKey = createHash('sha256')
+    .update(SCOPE_VERSION)
+    .update('\0')
+    .update(namespace)
+    .update('\0')
+    .update(conversationKey)
+    .digest('hex');
+  return { scopeKey, conversationKey };
+}
+
+export function derivePromptCacheContext(
+  parent: PromptCacheContext | undefined,
+  namespace: string,
+): PromptCacheContext | undefined {
+  return parent ? createPromptCacheContext(parent.conversationKey, namespace) : undefined;
+}
+
+export function normalizePromptCacheMode(value: unknown): PromptCacheMode {
+  return value === 'session-key' || value === 'disabled' ? value : 'auto';
+}
+
+export function shortCacheScope(scopeKey: string | undefined): string | undefined {
+  return scopeKey?.slice(0, 12);
+}
+
+/** Diagnostic fingerprint only; callers must never log the source material. */
+export function promptMaterialHash(value: unknown): string {
+  const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+  return createHash('sha256').update(serialized ?? '').digest('hex').slice(0, 12);
+}

package/src/llm/providers/anthropicFormat.js

@@ -171,9 +171,24 @@ export function buildAnthropicRequest(args) {
 export function createAnthropicSSEParser() {
     let stopReason = 'unknown';
     let usagePromptTokens;
+    let usageCachedTokens;
+    let usageCacheWriteTokens;
+    let promptCacheUsage = { reported: false };
+    const buildDoneEvent = () => ({
+        type: 'done',
+        stopReason,
+        promptTokens: usagePromptTokens,
+        ...(promptCacheUsage.reported
+            ? {
+                ...(usageCachedTokens !== undefined ? { cachedPromptTokens: usageCachedTokens } : {}),
+                ...(usageCacheWriteTokens !== undefined ? { cacheWriteTokens: usageCacheWriteTokens } : {}),
+                promptCacheUsage,
+            }
+            : {}),
+    });
     return {
         buildFallbackDone() {
-            return { type: 'done', stopReason, promptTokens: usagePromptTokens };
+            return buildDoneEvent();
         },
         handleData(dataStr) {
             let data;
@@ -185,9 +200,30 @@ export function createAnthropicSSEParser() {
             }
             switch (data.type) {
                 case 'message_start': {
-                    const inputTokens = data.message?.usage?.input_tokens;
-                    if (typeof inputTokens === 'number')
-                        usagePromptTokens = inputTokens;
+                    // ⚠️ Anthropic 的 input_tokens **不含**缓存部分（与 OpenAI 相反）：
+                    //   总 prompt = input_tokens + cache_read_input_tokens + cache_creation_input_tokens
+                    // 旧 Anthropic 配置或兼容代理可能返回缓存字段。当前客户端不主动发送
+                    // cache_control；这里仅兼容解析真实返回，不能据此宣称已开启显式缓存。
+                    const usage = data.message?.usage;
+                    const inputTokens = usage?.input_tokens;
+                    const cacheRead = usage?.cache_read_input_tokens;
+                    const cacheWrite = usage?.cache_creation_input_tokens;
+                    if (typeof cacheRead === 'number')
+                        usageCachedTokens = cacheRead;
+                    if (typeof cacheWrite === 'number')
+                        usageCacheWriteTokens = cacheWrite;
+                    if (typeof inputTokens === 'number') {
+                        usagePromptTokens =
+                            inputTokens +
+                                (typeof cacheRead === 'number' ? cacheRead : 0) +
+                                (typeof cacheWrite === 'number' ? cacheWrite : 0);
+                    }
+                    promptCacheUsage = {
+                        reported: typeof cacheRead === 'number' || typeof cacheWrite === 'number',
+                        ...(usagePromptTokens !== undefined ? { promptTokens: usagePromptTokens } : {}),
+                        ...(usageCachedTokens !== undefined ? { cacheReadTokens: usageCachedTokens } : {}),
+                        ...(usageCacheWriteTokens !== undefined ? { cacheWriteTokens: usageCacheWriteTokens } : {}),
+                    };
                     return [];
                 }
                 case 'content_block_start': {
@@ -227,7 +263,7 @@ export function createAnthropicSSEParser() {
                     return [];
                 }
                 case 'message_stop':
-                    return [{ type: 'done', stopReason, promptTokens: usagePromptTokens }];
+                    return [buildDoneEvent()];
                 case 'error':
                     // 中途错误事件（如 overloaded_error/529）：不能静默结束流，必须让调用方看到失败——
                     // 抛出后由 client.ts 共享读取循环的 try/finally 传播给上层（与其它流中断失败同一路径）。

package/src/llm/providers/anthropicFormat.ts

@@ -0,0 +1,290 @@
+/**
+ * ============================================================
+ *  src/llm/providers/anthropicFormat.ts —— Anthropic Messages API 协议
+ * ------------------------------------------------------------
+ *  ⚠️ 未经真实端点验证：本机没有任何 Anthropic 兼容的 key/代理，这里的请求体形状
+ *  和 SSE 事件字段完全照 Anthropic 官方文档（Messages API，2023-06-01）实现，配了
+ *  手写的 SSE 录像单测，但没有做过一次真实 round-trip。拿到真实 key 后务必先跑一次
+ *  真实对话冒烟测试，见 test/llm.anthropicFormat.test.ts 头注。
+ *
+ *  与 openaiFormat.ts 的分工一致：这里只做「内部 Message[]/Tool[] ⇄ Anthropic 协议
+ *  形状」的翻译 + SSE 逐行解析；重试/退避/空闲看门狗等协议无关骨架留在 client.ts。
+ *
+ *  v1 明确不支持（写清楚，不装作支持）：
+ *   - output_schema 结构化输出（Anthropic 的强制工具输出模式跟 OpenAI 的
+ *     response_format.json_schema 形状不同）——client.ts 在请求前直接抛错。
+ *   - OpenAI 特有的「400 文本嗅探退化」（不支持 response_format/max_tokens 时自动
+ *     摘字段重发）无 Anthropic 对应逻辑；Anthropic 的 400 直接暴露。
+ *   - 视频输入（ChatContentPart 的 video_url）：Anthropic 无对应协议，退化成文本占位。
+ * ============================================================
+ */
+
+import type { ChatContentPart, LlmStreamEvent, Message, PromptCacheUsage, Provider, Tool } from '../../types.js';
+
+const ANTHROPIC_VERSION = '2023-06-01';
+
+interface AnthropicContentBlock {
+  type: string;
+  [key: string]: unknown;
+}
+
+interface AnthropicMessage {
+  role: 'user' | 'assistant';
+  content: AnthropicContentBlock[];
+}
+
+function toAnthropicUserContent(content: string | ChatContentPart[]): AnthropicContentBlock[] {
+  if (typeof content === 'string') return [{ type: 'text', text: content }];
+  return content.map((part): AnthropicContentBlock => {
+    if (part.type === 'text') return { type: 'text', text: part.text };
+    if (part.type === 'image_url') {
+      const url = part.image_url.url;
+      if (url.startsWith('data:')) {
+        const match = /^data:([^;]+);base64,([\s\S]+)$/.exec(url);
+        if (match) return { type: 'image', source: { type: 'base64', media_type: match[1], data: match[2] } };
+      }
+      return { type: 'image', source: { type: 'url', url } };
+    }
+    // video_url：Anthropic 无对应协议，退化成文本占位（v1 范围限制）。
+    return { type: 'text', text: '[视频内容未发送：Anthropic 格式的 provider 暂不支持视频输入]' };
+  });
+}
+
+/**
+ * 内部 Message[]（OpenAI 形状：role 含 tool、assistant.tool_calls、tool.tool_call_id）
+ * → Anthropic 形状：{system, messages}。
+ *
+ * 关键翻译规则：
+ *  - 所有 system 角色内容拼成顶层 system 字符串，从 messages 数组里摘除。
+ *  - tool 角色 → {role:'user', content:[{type:'tool_result', tool_use_id, content}]}。
+ *  - assistant 的 tool_calls[i] → {type:'tool_use', id, name, input}（arguments 是内部的
+ *    JSON 字符串，Anthropic 的 input 要解析后的对象；parse 失败兜底空对象）。
+ *  - **必须合并连续同角色消息**：Anthropic 强制 user/assistant 严格交替，1:1 硬映射会因
+ *    「assistant 调工具 → tool 结果(→user) → 下一条也是 user 的正常对话」之类的连续同角色
+ *    序列而 400。
+ */
+export function toAnthropicMessages(messages: readonly Message[]): { system: string; messages: AnthropicMessage[] } {
+  const systemParts: string[] = [];
+  const pieces: AnthropicMessage[] = [];
+
+  for (const m of messages) {
+    if (m.role === 'system') {
+      systemParts.push(m.content);
+      continue;
+    }
+    if (m.role === 'user') {
+      pieces.push({ role: 'user', content: toAnthropicUserContent(m.content) });
+      continue;
+    }
+    if (m.role === 'assistant') {
+      const content: AnthropicContentBlock[] = [];
+      if (m.content) content.push({ type: 'text', text: m.content });
+      for (const call of m.tool_calls ?? []) {
+        let input: unknown = {};
+        try {
+          input = JSON.parse(call.function.arguments || '{}');
+        } catch {
+          input = {};
+        }
+        content.push({ type: 'tool_use', id: call.id, name: call.function.name, input });
+      }
+      // 退化 assistant 消息（content 为 null/空字符串且没有 tool_calls——如模型只吐了
+      // reasoning 就被中断）整条跳过，而不是塞一个空文本块：Anthropic 拒绝空 text block
+      // （"text content blocks must be non-empty"），塞了会让下一轮请求直接 400。
+      if (content.length > 0) pieces.push({ role: 'assistant', content });
+      continue;
+    }
+    // role === 'tool'
+    pieces.push({ role: 'user', content: [{ type: 'tool_result', tool_use_id: m.tool_call_id, content: m.content }] });
+  }
+
+  const merged: AnthropicMessage[] = [];
+  for (const piece of pieces) {
+    const last = merged[merged.length - 1];
+    if (last && last.role === piece.role) last.content.push(...piece.content);
+    else merged.push({ role: piece.role, content: [...piece.content] });
+  }
+  return { system: systemParts.join('\n\n'), messages: merged };
+}
+
+function toAnthropicTools(tools: Tool[]): Array<{ name: string; description: string; input_schema: object }> {
+  return tools.map((t) => ({
+    name: t.name,
+    description: typeof t.description === 'function' ? t.description() : t.description,
+    input_schema: t.parameters,
+  }));
+}
+
+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 buildAnthropicUrl(provider: Provider): string {
+  // baseURL 是完整端点 URL（以 /v1/messages 结尾）。
+  // 向后兼容：旧格式 baseURL（根域名或版本化基础路径）自动补全 /v1/messages 后缀。
+  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}/v1/messages"。请在设置页更新为完整端点地址。`,
+    );
+    return `${url}/v1/messages`;
+  }
+  return url;
+}
+
+export interface AnthropicRequestArgs {
+  provider: Provider;
+  cleanedMessages: readonly Message[];
+  tools: Tool[];
+}
+
+export function buildAnthropicRequest(args: AnthropicRequestArgs): { url: string; headers: Record<string, string>; body: string } {
+  const { provider, cleanedMessages, tools } = args;
+  const { system, messages } = toAnthropicMessages(cleanedMessages);
+  const anthropicTools = toAnthropicTools(tools);
+  const body: Record<string, unknown> = {
+    model: provider.model,
+    ...(system ? { system } : {}),
+    messages,
+    // Anthropic 的 max_tokens 是必填字段；解析层（configService.ts::resolveProvider）已保证
+    // provider.maxTokens 一定有值（defaultMaxTokens() 兜底），这里直接透传不做协商退化——
+    // OpenAI 那套「不支持就摘掉重发」的 400 文本嗅探对 Anthropic 无对应逻辑，见文件头注。
+    max_tokens: provider.maxTokens,
+    stream: true,
+  };
+  // tools: [] 会被部分 provider 拒绝或产生意外行为——空数组直接不发这个字段。
+  if (anthropicTools.length > 0) body.tools = anthropicTools;
+  return {
+    url: buildAnthropicUrl(provider),
+    headers: {
+      'content-type': 'application/json',
+      'x-api-key': provider.apiKey,
+      'anthropic-version': ANTHROPIC_VERSION,
+    },
+    body: JSON.stringify(body),
+  };
+}
+
+/**
+ * 每个请求一个新实例；把逐条 SSE `data:` 行的内容转换成 LlmStreamEvent（0..N 个）。
+ *
+ * Anthropic 的 SSE 每帧是 `event: <type>` + `data: <json>` 两行，但 data 的 JSON payload
+ * 自身也带 `type` 字段（与 event 行的值相同）——client.ts 的共享读取骨架只识别 `data:`
+ * 开头的行（继承自 OpenAI 分支的既有约定），所以这里直接从 JSON payload 的 `.type` 分支，
+ * 不需要读 `event:` 行，共享骨架的行拆分逻辑不用为 Anthropic 特殊改动。
+ */
+export function createAnthropicSSEParser(): {
+  handleData(dataStr: string): LlmStreamEvent[];
+  /** 流意外中断（没收到显式 message_stop）时，用累积状态兜底发一个 done。 */
+  buildFallbackDone(): LlmStreamEvent;
+} {
+  let stopReason: 'stop' | 'tool_calls' | 'length' | 'unknown' = 'unknown';
+  let usagePromptTokens: number | undefined;
+  let usageCachedTokens: number | undefined;
+  let usageCacheWriteTokens: number | undefined;
+  let promptCacheUsage: PromptCacheUsage = { reported: false };
+  const buildDoneEvent = (): LlmStreamEvent => ({
+    type: 'done',
+    stopReason,
+    promptTokens: usagePromptTokens,
+    ...(promptCacheUsage.reported
+      ? {
+          ...(usageCachedTokens !== undefined ? { cachedPromptTokens: usageCachedTokens } : {}),
+          ...(usageCacheWriteTokens !== undefined ? { cacheWriteTokens: usageCacheWriteTokens } : {}),
+          promptCacheUsage,
+        }
+      : {}),
+  });
+  return {
+    buildFallbackDone(): LlmStreamEvent {
+      return buildDoneEvent();
+    },
+    handleData(dataStr: string): LlmStreamEvent[] {
+      let data: any;
+      try {
+        data = JSON.parse(dataStr);
+      } catch {
+        return [];
+      }
+      switch (data.type) {
+        case 'message_start': {
+          // ⚠️ Anthropic 的 input_tokens **不含**缓存部分（与 OpenAI 相反）：
+          //   总 prompt = input_tokens + cache_read_input_tokens + cache_creation_input_tokens
+          // 旧 Anthropic 配置或兼容代理可能返回缓存字段。当前客户端不主动发送
+          // cache_control；这里仅兼容解析真实返回，不能据此宣称已开启显式缓存。
+          const usage = data.message?.usage;
+          const inputTokens = usage?.input_tokens;
+          const cacheRead = usage?.cache_read_input_tokens;
+          const cacheWrite = usage?.cache_creation_input_tokens;
+          if (typeof cacheRead === 'number') usageCachedTokens = cacheRead;
+          if (typeof cacheWrite === 'number') usageCacheWriteTokens = cacheWrite;
+          if (typeof inputTokens === 'number') {
+            usagePromptTokens =
+              inputTokens +
+              (typeof cacheRead === 'number' ? cacheRead : 0) +
+              (typeof cacheWrite === 'number' ? cacheWrite : 0);
+          }
+          promptCacheUsage = {
+            reported: typeof cacheRead === 'number' || typeof cacheWrite === 'number',
+            ...(usagePromptTokens !== undefined ? { promptTokens: usagePromptTokens } : {}),
+            ...(usageCachedTokens !== undefined ? { cacheReadTokens: usageCachedTokens } : {}),
+            ...(usageCacheWriteTokens !== undefined ? { cacheWriteTokens: usageCacheWriteTokens } : {}),
+          };
+          return [];
+        }
+        case 'content_block_start': {
+          // tool_use 块的 id/name 在 start 事件里一次性给出（不像 OpenAI 分片在 delta 里），
+          // 这里补发一条只带 id/name、不带 argumentsDelta 的 tool_call_delta 把它们「种」进
+          // loop.ts::mergeToolCallDelta 的累积槽；后续同 index 的 input_json_delta 只带参数增量。
+          const block = data.content_block;
+          if (block?.type === 'tool_use') {
+            return [{ type: 'tool_call_delta', index: data.index, id: block.id, name: block.name }];
+          }
+          return [];
+        }
+        case 'content_block_delta': {
+          const delta = data.delta;
+          if (delta?.type === 'text_delta') return [{ type: 'text_delta', delta: delta.text }];
+          if (delta?.type === 'input_json_delta') {
+            return [{ type: 'tool_call_delta', index: data.index, argumentsDelta: delta.partial_json }];
+          }
+          if (delta?.type === 'thinking_delta') {
+            return [{ type: 'reasoning_delta', field: 'reasoning', delta: delta.thinking }];
+          }
+          // signature_delta（扩展思维签名）等其它 delta 类型：v1 不处理，安全忽略。
+          return [];
+        }
+        case 'message_delta': {
+          // ⚠️ stop_reason 嵌套在 delta.stop_reason 下，不是 message_delta 顶层。
+          const sr = data.delta?.stop_reason;
+          if (sr === 'end_turn' || sr === 'stop_sequence') stopReason = 'stop';
+          else if (sr === 'tool_use') stopReason = 'tool_calls';
+          else if (sr === 'max_tokens') stopReason = 'length';
+          else if (sr) stopReason = 'unknown';
+          return [];
+        }
+        case 'message_stop':
+          return [buildDoneEvent()];
+        case 'error':
+          // 中途错误事件（如 overloaded_error/529）：不能静默结束流，必须让调用方看到失败——
+          // 抛出后由 client.ts 共享读取循环的 try/finally 传播给上层（与其它流中断失败同一路径）。
+          throw new Error(`Anthropic 流式响应报错：${JSON.stringify(data.error ?? data)}`);
+        default:
+          // 含 ping、content_block_stop 及未来可能新增的事件类型——已知安全的 no-op，不抛错。
+          return [];
+      }
+    },
+  };
+}

package/src/llm/providers/openaiFormat.js

@@ -45,22 +45,114 @@ export function isMaxTokensRejected(status, errText) {
 /**
  * 判断一个 4xx 是否在抱怨图片/image_url/多模态输入不被支持。
  * 匹配关键词：image_url、image、vision、multimodal + not support/unsupported/invalid 等。
+ * 排除图片尺寸/大小/格式等临时性错误，以及参数值错误（如 detail 取值非法），这些不是模型不支持图片。
  */
 export function isImageInputRejected(status, errText) {
     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('invalid') ||
         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, errText) {
+    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')));
+}
+/**
+ * 递归遍历消息，把 image_url.detail: 'default' 转换成 'auto'。
+ * OpenAI 兼容 API（豆包/火山引擎等）不接受 'default'，标准默认值是 'auto'。
+ */
+function normalizeImageDetailForOpenAI(messages) {
+    return messages.map((msg) => {
+        if (!msg || typeof msg !== 'object')
+            return msg;
+        const m = msg;
+        if (Array.isArray(m.content)) {
+            m.content = m.content.map((part) => {
+                if (!part || typeof part !== 'object')
+                    return part;
+                const p = part;
+                if (p.type === 'image_url' && p.image_url && typeof p.image_url === 'object') {
+                    const imgUrl = p.image_url;
+                    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) {
+    // 统计所有图片数量
+    let imageCount = 0;
+    const messagesWithImages = [];
+    messages.forEach((msg, msgIdx) => {
+        if (!msg || typeof msg !== 'object')
+            return;
+        const m = msg;
+        if (Array.isArray(m.content)) {
+            m.content.forEach((part, contentIdx) => {
+                if (!part || typeof part !== 'object')
+                    return;
+                const p = part;
+                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];
+            if (Array.isArray(msg.content)) {
+                msg.content.splice(contentIdx, 1);
+            }
+        }
+    }
+    return messages;
+}
 function looksLikeVersionedBase(url) {
     try {
         const u = new URL(url);
@@ -91,7 +183,11 @@ export function buildOpenAIUrl(provider) {
     return url;
 }
 export function buildOpenAIRequest(args) {
-    const { provider, cleanedMessages, tools, withResponseFormat, withMaxTokens, includeUsage, responseFormat } = args;
+    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 = tools.map((t) => ({
         type: 'function',
         function: {
@@ -108,7 +204,7 @@ export function buildOpenAIRequest(args) {
         },
         body: JSON.stringify({
             model: provider.model,
-            messages: cleanedMessages,
+            messages,
             tools: openaiTools.length > 0 ? openaiTools : undefined,
             stream: true,
             // 显式输出上限：兜住默认上限偏小的 provider（豆包默认 4096）。缺省 undefined 不出现在 body。
@@ -120,20 +216,95 @@ export function buildOpenAIRequest(args) {
             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) {
+    if (!usage || typeof usage !== 'object')
+        return { reported: false };
+    const u = usage;
+    let cacheReadTokens;
+    const details = u.prompt_tokens_details;
+    if (details && typeof details === 'object') {
+        const cached = details.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) {
+    return extractPromptCacheUsage(usage).cacheReadTokens;
+}
 /** 每个请求一个新实例；把逐条 SSE `data:` 行的内容转换成 LlmStreamEvent（0..N 个）。 */
 export function createOpenAISSEParser() {
     let stopReason = 'unknown';
     let usagePromptTokens;
+    let usageCachedTokens;
+    let usageCacheMissTokens;
+    let promptCacheUsage = { reported: false };
     return {
         buildFallbackDone() {
-            return { type: 'done', stopReason, promptTokens: usagePromptTokens };
+            return {
+                type: 'done',
+                stopReason,
+                promptTokens: usagePromptTokens,
+                cachedPromptTokens: usageCachedTokens,
+                cacheMissTokens: usageCacheMissTokens,
+                promptCacheUsage,
+            };
         },
         handleData(dataStr) {
-            if (dataStr === '[DONE]')
-                return [{ type: 'done', stopReason, promptTokens: usagePromptTokens }];
+            if (dataStr === '[DONE]') {
+                return [{
+                        type: 'done',
+                        stopReason,
+                        promptTokens: usagePromptTokens,
+                        cachedPromptTokens: usageCachedTokens,
+                        cacheMissTokens: usageCacheMissTokens,
+                        promptCacheUsage,
+                    }];
+            }
             let chunk;
             try {
                 chunk = JSON.parse(dataStr);
@@ -146,8 +317,15 @@ export function createOpenAISSEParser() {
             // usage chunk：include_usage 开启时，provider 通常在流末单独发一帧，
             // 此帧 choices 为空（没有 delta），必须在 `if (!delta) return` 之前读取，
             // 否则会被跳过，永远拿不到真实 prompt_tokens。
-            if (chunk.usage && typeof chunk.usage.prompt_tokens === 'number') {
-                usagePromptTokens = chunk.usage.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;