minimal-agent 0.10.0 → 0.12.0

package/src/llm/client.ts

@@ -0,0 +1,621 @@
+/**
+ * ============================================================
+ *  src/llm/client.ts —— LLM 客户端（流式，双协议）
+ * ------------------------------------------------------------
+ *  这个文件做一件事：把"消息历史 + 可用工具"发给 LLM，把"流式响应"逐 chunk
+ *  yield 回上层。它是整个 agent 系统里唯一会 fetch() 远端 API 的地方。
+ *
+ *  支持两种协议格式（`provider.apiFormat`，缺省 'openai'）：
+ *    - OpenAI Chat Completions —— DeepSeek、月之暗面、智谱、火山、OpenRouter 都按它兼容
+ *    - Anthropic Messages API —— ⚠️ 未经真实端点验证，见 providers/anthropicFormat.ts 头注
+ *
+ *  格式相关的请求体构造 + SSE chunk 解析拆到 `providers/openaiFormat.ts` /
+ *  `providers/anthropicFormat.ts`；本文件只保留协议无关的共享骨架：重试/自适应退避/
+ *  空闲看门狗/中断处理——这部分历史上踩过真实事故（P0-1），两种格式共用同一份，
+ *  不重复实现以免两份retry逻辑逐渐漂移出不一致的行为。
+ *
+ *  SSE（Server-Sent Events）是什么？
+ *    一种很简单的流式协议：服务器逐行返回 "data: <json>\n\n"，
+ *    OpenAI 用 "data: [DONE]\n\n" 表示结束；Anthropic 用一个 data payload 里
+ *    `type:"message_stop"` 的事件表示结束（两者的 data 载荷都自解释，行拆分逻辑
+ *    不需要为格式差异特殊处理，见 anthropicFormat.ts 头注）。
+ *
+ *  本文件不依赖任何 npm 包（fetch 是 Bun/Node 20+ 内置）。
+ * ============================================================
+ */
+
+import type { LlmStreamEvent, Message, Provider, Tool } from '../types.js';
+import { dlog } from '../utils/debugLog.js';
+import {
+  buildOpenAIRequest,
+  createOpenAISSEParser,
+  isImageInputRejected,
+  isMaxTokensRejected,
+  isPromptCacheKeyRejected,
+  isResponseFormatUnsupported,
+} from './providers/openaiFormat.js';
+import { promptMaterialHash, shortCacheScope } from './promptCache.js';
+import { buildAnthropicRequest, createAnthropicSSEParser } from './providers/anthropicFormat.js';
+
+/**
+ * 记住"这个 baseURL::model 不支持 response_format.json_schema"，避免每次都先撞 400。
+ * 单进程内有效；每个 -p 子进程是全新进程 → 首个结构化调用吃一次 400 再退化，可接受。
+ * 只对 openai 格式有意义（anthropic 无此就地退化概念，见下）。
+ */
+const rfUnsupported = new Set<string>();
+
+/**
+ * 记住"这个 baseURL::model 拒绝我们发的 max_tokens"，避免每次都先撞 400。
+ * 与 rfUnsupported 同理，单进程内有效。绝大多数 provider 接受 max_tokens（实测豆包到
+ * ≥131072 仍正常），这只是给个别挑剔 provider 的兜底，命中后该进程不再发 max_tokens。
+ */
+const maxTokensUnsupported = new Set<string>();
+const promptCacheKeyUnsupported = new Set<string>();
+
+/** 调试日志用的请求自增号（vote 并发多 voter 时靠它在日志里区分是哪一路）。 */
+let reqCounter = 0;
+
+// ============================================================
+//  重试 + 超时（无网络重试 → 整条 IM 链卡死；这是 P0-1 的根治）
+// ------------------------------------------------------------
+//  背景：之前 fetch 直接 await，没有 timeout 也没有重试。
+//  后果：① 断网 1 帧流式 60+ chunk 报废；② 429/5xx 直接抛错；
+//  ③ 401/403 错误文案不带"key 失效"提示；④ gateway 桥接 stream-json 后
+//  子进程挂起会整条 IM 通道 dir 锁卡死。
+//
+//  设计：
+//   - 自适应退避（拥塞控制式）：进程级档位 0.5→1→2→5→10→30→60s，失败逐级抬高、
+//     成功（拿到 200）立即回落到最小值；封顶 60s（超 1min 就不是拥塞、是真死，无谓再等）。
+//     跨请求记忆当前拥塞程度——连续失败不会从头傻试，刚成功又不会被旧拥塞拖慢。
+//   - 5xx / 408 / 425 / 429 / 网络错误全部重试
+//   - 401 / 403 / 404 等 4xx 不重试（重试无意义）+ 给清晰"key 失效"提示
+//   - 429 优先解析 Retry-After 头（秒），封顶 60s
+//   - 空闲 watchdog 兜底卡死（语义见 IDLE_TIMEOUT_MS 注释——是【空闲】不是【总时长】）
+//   - 用户 signal 触发的 abort 立即退出，不重试
+//   - 流式响应中途中断（reader.read reject）走同一个错误路径
+// ============================================================
+
+/**
+ * 流式空闲超时（毫秒）：自上一个字节到达起算，超过仍无任何新数据才判死。
+ * 可用 env `MINIMAL_AGENT_IDLE_TIMEOUT_MS` 覆盖。
+ *
+ * ⚠️ 语义是【空闲】而非【总时长】：重思考模型（MiniMax-M3/DeepSeek-R1 等）
+ * 带大上下文的流式响应总时长可以远超 2 分钟，但只要还在持续吐 chunk
+ * （reasoning_delta 也算）就不该掐。v0.9.x 之前用 AbortSignal.timeout 对
+ * 整个请求硬超时 120s——design 类长步骤被恰好 120s 掐死、重试必然同败，是 bug。
+ */
+const IDLE_TIMEOUT_MS = (() => {
+  const v = Number(process.env.MINIMAL_AGENT_IDLE_TIMEOUT_MS);
+  return Number.isFinite(v) && v > 0 ? v : 120_000;
+})();
+
+interface RetryConfig {
+  maxAttempts: number;
+}
+
+/**
+ * 网络/5xx/429 的重试预算（单次请求最多尝试几次）。配合下面的自适应档位，
+ * 默认 6 次足以「骑过一次网络拥塞波」：实测某些 provider 端点（如 api.minimax.chat）
+ * 经路存在分钟级拥塞波——TLS 握手在 0.15s 与 6.8s 间剧烈摆动，坏的时候连接直接 RST
+ * （Bun fetch 报 "Unable to connect"）。不稳网可用 env `MINIMAL_AGENT_LLM_MAX_RETRIES`
+ * 加码（如 10）。注意：现在「等多久」由自适应档位决定，本值只管「试几次」。
+ */
+const DEFAULT_RETRY: RetryConfig = {
+  maxAttempts: (() => {
+    const v = Number(process.env.MINIMAL_AGENT_LLM_MAX_RETRIES);
+    return Number.isFinite(v) && v >= 1 ? Math.floor(v) : 6;
+  })(),
+};
+
+// ------------------------------------------------------------
+//  自适应退避（拥塞控制式 AIMD 的简化版）
+// ------------------------------------------------------------
+//  动机：各家模型的 token plan 现在普遍会拥堵。固定指数退避有两个毛病：
+//    ① 每个新请求都从最小值重来 → 端点正堵时仍一上来就猛打、徒增失败；
+//    ② 退避封顶才 8s → 真遇上分钟级拥塞波，整段重试落在同一坏波里仍败。
+//  对策：一个【进程级档位】记忆「当前网络有多堵」：
+//    - 每次重试前取当前档位延时（带抖动）并抬高一档（失败 = 乘性增）；
+//    - 任一请求拿到 200 → 档位立即清零回最小值（成功 = 立即恢复，不永久拉长）；
+//    - 档位封顶 60s：超过 1 分钟就不是「拥塞波」而是端点真死，再等无意义，让其 honest 失败。
+//  跨请求共享：A 请求把档位顶到 30s，紧接着 B 请求重试就从 30s 起（别再傻试），
+//  直到某次成功才回落。-p 子进程各自全新 → 从最小档位起，互不影响。
+
+/** 退避档位（毫秒）：0.5→1→2→5→10→30→60s。近似 log 曲线的「几个档位」，封顶 60s。 */
+const BACKOFF_TIERS_MS = [500, 1000, 2000, 5000, 10_000, 30_000, 60_000];
+
+/** 进程级当前档位索引（跨请求记忆当前拥塞程度；成功清零，失败抬高）。 */
+let backoffTier = 0;
+
+/**
+ * 取「这次重试该等多久」：当前档位延时 + ±15% 抖动（防 vote/parallel 并发请求
+ * 同步重试踩同一波），随后把档位抬高一档（封顶最后一档）。
+ * retryAfterMs 有值（429 的 Retry-After 头）时听服务器的（仍封顶 60s、仍抬档）。
+ */
+function nextRetryDelayMs(retryAfterMs?: number): number {
+  const tierMs = BACKOFF_TIERS_MS[Math.min(backoffTier, BACKOFF_TIERS_MS.length - 1)];
+  backoffTier = Math.min(backoffTier + 1, BACKOFF_TIERS_MS.length - 1);
+  if (retryAfterMs !== undefined) return Math.min(retryAfterMs, 60_000);
+  const jittered = tierMs * (0.85 + Math.random() * 0.3);
+  return Math.min(Math.round(jittered), 60_000);
+}
+
+/** 任一请求成功（拿到 200）→ 拥塞已缓解，档位立即回落到最小值。 */
+function resetBackoff(): void {
+  backoffTier = 0;
+}
+
+/** 仅供测试：读取/重置进程级档位（生产代码勿调）。 */
+export function _getBackoffTier(): number {
+  return backoffTier;
+}
+export function _resetBackoffTier(): void {
+  backoffTier = 0;
+}
+/** 仅供测试：暴露纯退避计算，供单测验证档位曲线/封顶/Retry-After（不触网）。 */
+export function _nextRetryDelayMs(retryAfterMs?: number): number {
+  return nextRetryDelayMs(retryAfterMs);
+}
+
+/** 可重试的 HTTP 状态码。4xx 除 408/425/429 外不重试（重试无意义）。 */
+function isRetryableStatus(status: number): boolean {
+  return status === 408 || status === 425 || status === 429 || (status >= 500 && status < 600);
+}
+
+/** 鉴权类错误：明确告诉用户"key 失效/过期/无权访问"，避免重试无意义。 */
+function isClientAuthError(status: number): boolean {
+  return status === 401 || status === 403;
+}
+
+/** 解析 Retry-After 头（秒数字符串），封顶 60s。无效/缺省返回 undefined。 */
+function parseRetryAfter(resp: Response): number | undefined {
+  const h = resp.headers.get('retry-after');
+  if (!h) return undefined;
+  const sec = parseFloat(h);
+  if (!Number.isFinite(sec) || sec < 0) return undefined;
+  return Math.min(sec * 1000, 60_000);
+}
+
+/**
+ * 构造带正确 .name 的中断错误。
+ *
+ * 为什么需要这个而不是直接 `new Error('aborted')`：loop.ts 靠 `e.name === 'AbortError'`
+ * 判断"这是用户主动中断"，走优雅的 interrupted 收尾（不显示红色错误）。普通 `new Error(...)`
+ * 的 `.name` 是 `'Error'`，会让 loop.ts 把真实的用户中断误判成普通 LLM 报错
+ * （`code:'llm_error'`，红色错误）。本文件里所有"确认是用户 signal 触发的 abort"都必须
+ * 用这个构造，保持 `.name` 与真实 DOMException AbortError 一致。
+ */
+function makeAbortError(message = 'aborted'): Error {
+  const err = new Error(message);
+  err.name = 'AbortError';
+  return err;
+}
+
+/** 可中断的 sleep：用户 signal 触发 abort 立刻 reject，不阻塞退出。 */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(makeAbortError());
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(makeAbortError());
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/** 构造带诊断的 Error；401/403 走专属文案，避免"重试 5 次才发现是 key 失效"。 */
+function buildChatError(resp: Response, body: string): Error {
+  const status = resp.status;
+  const head = `[${status} ${resp.statusText}]`;
+  if (isClientAuthError(status)) {
+    return new Error(
+      `LLM 鉴权失败 ${head}：API key 可能失效、过期或无权访问 model "${resp.url.split('/').pop()}".\n` +
+        `请检查 .env / ~/.minimal-agent/config.json 的模型配置。\n` +
+        `原始错误：${body.slice(0, 500)}`,
+    );
+  }
+  return new Error(`LLM 请求失败 ${head}：${body.slice(0, 500)}`);
+}
+
+/**
+ * 空闲 watchdog：kick() 重置计时；IDLE_TIMEOUT_MS 内没有任何 kick 才 abort。
+ * 与用户 signal 组合（AbortSignal.any，Node 20.3+/Bun 内置），任一触发即中断。
+ * 调用方契约：fetch 等待期自动计时；流式期间每收到一个 chunk 调一次 kick()；
+ * 结束（无论成败）调 dispose() 清掉定时器。
+ */
+export function createIdleWatchdog(
+  userSignal: AbortSignal | undefined,
+  timeoutMs: number = IDLE_TIMEOUT_MS, // 测试注入用；生产走默认
+): {
+  signal: AbortSignal;
+  kick: () => void;
+  dispose: () => void;
+} {
+  const ctrl = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const arm = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      ctrl.abort(
+        new Error(
+          `LLM 流式响应空闲超时：${timeoutMs}ms 内未收到任何新数据（总时长不限，只判空闲；可用 MINIMAL_AGENT_IDLE_TIMEOUT_MS 调整）`,
+        ),
+      );
+    }, timeoutMs);
+    // 不阻止进程退出（Bun/Node 均支持 unref）
+    (timer as { unref?: () => void }).unref?.();
+  };
+  arm();
+  return {
+    signal: userSignal ? AbortSignal.any([userSignal, ctrl.signal]) : ctrl.signal,
+    kick: arm,
+    dispose: () => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+    },
+  };
+}
+
+/**
+ * 调用 LLM 并以流的形式 yield 事件。协议格式由 `provider.apiFormat` 决定
+ * （缺省 'openai'）；两种格式共用本函数的重试/退避/看门狗骨架，请求体构造和
+ * SSE 解析分别委托给 providers/openaiFormat.ts / providers/anthropicFormat.ts。
+ *
+ * @param provider 选好的 provider（含 baseURL / apiKey / model / apiFormat）
+ * @param messages 完整的对话历史
+ * @param tools    工具列表（每个工具需要带 jsonSchema 才能给 LLM）
+ * @param signal   AbortSignal，UI 按 Ctrl+C 时中断
+ *
+ * @yield LlmStreamEvent: text_delta / tool_call_delta / done
+ *
+ * 用法示例：
+ * ```
+ * for await (const ev of chat({ provider, messages, tools })) {
+ *   if (ev.type === 'text_delta') process.stdout.write(ev.delta);
+ * }
+ * ```
+ */
+export async function* chat(args: {
+  provider: Provider;
+  messages: Message[];
+  tools: Tool[];
+  signal?: AbortSignal;
+  /** ADR-05: provider-native structured output。OpenAI / MiniMax / DeepSeek 兼容。
+   *  传入后 LLM 输出保证符合 schema；不兼容 provider 会报 400，runner 透传。
+   *  Anthropic 格式的 provider 目前不支持（见 providers/anthropicFormat.ts 头注），
+   *  传了会在发请求前直接抛错，不浪费一次网络往返。*/
+  responseFormat?: {
+    type: 'json_schema';
+    json_schema: { name: string; schema: Record<string, unknown>; strict?: boolean };
+  };
+  promptCache?: import('../types.js').PromptCacheContext;
+}): AsyncGenerator<LlmStreamEvent, void, void> {
+  const { provider, messages, tools, signal, responseFormat, promptCache } = args;
+  const format: 'openai' | 'anthropic' = provider.apiFormat === 'anthropic' ? 'anthropic' : 'openai';
+
+  if (format === 'anthropic' && responseFormat) {
+    throw new Error(
+      'output_schema 结构化输出目前不支持 Anthropic Messages 格式的 provider' +
+        '（Anthropic 的强制工具输出模式与 OpenAI 的 response_format.json_schema 形状不同，尚未实现映射）。' +
+        '请改用 OpenAI 格式的 provider，或去掉这一步的 output_schema。',
+    );
+  }
+
+  // 过滤并清洁 messages 数组，剥离 timestamp, id, _ephemeral 等本地渲染元数据。
+  // 两种格式共用同一份清洗后的内部形状——Anthropic 分支的翻译（system 摘除/
+  // tool_calls→tool_use 等）在 buildAnthropicRequest 内部做，不在这里做。
+  let cleanedMessages: Message[] = messages
+    .filter((m) => !(m.role === 'system' && (m as { _ephemeral?: boolean })._ephemeral === true))
+    .map((m) => {
+      const { id, timestamp, attachments, browserReferences, display_metadata, ...rest } = m as any;
+      return rest;
+    });
+
+  const includeUsage = process.env.MINIMAL_AGENT_DISABLE_USAGE !== '1';
+  const rfKey = `${provider.baseURL}::${provider.model}`;
+
+  // OpenAI 分支专属的「就地退化」状态；Anthropic 无此概念，两个 flag 恒为 false，
+  // 下面的退化 if 分支天然不会进入（不需要额外的 format 判断散落各处）。
+  let wantResponseFormat =
+    format === 'openai' && responseFormat !== undefined && !rfUnsupported.has(rfKey);
+  let wantMaxTokens =
+    format === 'openai' &&
+    typeof provider.maxTokens === 'number' &&
+    provider.maxTokens > 0 &&
+    !maxTokensUnsupported.has(rfKey);
+  let imagesStripped = false;
+  let wantPromptCacheKey =
+    format === 'openai' &&
+    provider.promptCache?.mode === 'session-key' &&
+    !!promptCache?.scopeKey &&
+    !promptCacheKeyUnsupported.has(rfKey);
+
+  const stripImagesFromMessages = (msgs: Message[]): Message[] =>
+    msgs.map((m) => {
+      const c = (m as { content?: unknown }).content;
+      if (!Array.isArray(c)) return m;
+      const textOnly = c.filter((p: any) => p.type === 'text');
+      const newContent = textOnly.length > 0
+        ? textOnly.map((p: any) => ({ type: 'text' as const, text: p.text }))
+        : [{ type: 'text' as const, text: '[图片内容未发送：当前模型不支持图片输入]' }];
+      return { ...m, content: newContent } as Message;
+    });
+
+  // 空闲 watchdog：每个 attempt 一只（重试前换新）；fetch 等待期自动计时，
+  // 流式期间每个 chunk kick 一次。用户 signal 与 watchdog 任一触发即中断。
+  let watchdog = createIdleWatchdog(signal);
+
+  const postChat = (): Promise<Response> => {
+    const req =
+      format === 'anthropic'
+        ? buildAnthropicRequest({ provider, cleanedMessages, tools })
+        : buildOpenAIRequest({
+            provider,
+            cleanedMessages,
+            tools,
+            withResponseFormat: wantResponseFormat,
+            withMaxTokens: wantMaxTokens,
+            includeUsage,
+            promptCache,
+            withPromptCacheKey: wantPromptCacheKey,
+            responseFormat,
+          });
+    return fetch(req.url, { method: 'POST', headers: req.headers, body: req.body, signal: watchdog.signal });
+  };
+
+  const reqId = ++reqCounter;
+  dlog('llm', `req#${reqId} POST →`, {
+    model: provider.model,
+    format,
+    rf: wantResponseFormat,
+    maxTokens: wantMaxTokens ? provider.maxTokens : undefined,
+    msgs: cleanedMessages.length,
+    tools: tools.length,
+    promptCacheMode: provider.promptCache?.mode ?? 'auto',
+    promptCacheScope: shortCacheScope(promptCache?.scopeKey),
+    systemPromptHash: promptMaterialHash(
+      cleanedMessages
+        .filter((message) => message.role === 'system')
+        .map((message) => message.content),
+    ),
+    toolSchemaHash: promptMaterialHash(
+      tools.map((tool) => ({
+        name: tool.name,
+        description: typeof tool.description === 'function' ? tool.description() : tool.description,
+        parameters: tool.parameters,
+      })),
+    ),
+  });
+
+  // 重试循环：每个 attempt 内部可能触发"response_format 不支持 → 去掉"的本地退化
+  //     （本地退化不算重试，仍属同一 attempt 的"拿到 200"路径的一部分；只 openai 分支会真的
+  //     进入这两个退化 if）。只有"网络/超时/5xx/429"才跨 attempt 重试，4xx 业务错误直接抛
+  //     （401/403 走 buildChatError 的专属文案，不浪费 5 次重试）
+  let resp: Response | undefined;
+  let lastErr: Error | undefined;
+
+  // 网络错误统一收尾（主路径 + 两条退化路径共用，防退避策略三处漂移）：
+  // 用户 abort → 抛；置 lastErr + dlog；额度用尽 → 'break'；否则退避后 'retry'。
+  const handleNetworkError = async (
+    e: unknown,
+    attempt: number,
+    label: string,
+  ): Promise<'break' | 'retry'> => {
+    if (signal?.aborted) throw makeAbortError();
+    const err = e as Error;
+    lastErr = new Error(`LLM 网络错误 [${err.name ?? 'NetworkError'}]：${err.message}`);
+    dlog('llm', `req#${reqId} attempt ${attempt} ${label}:`, err.message);
+    if (attempt >= DEFAULT_RETRY.maxAttempts) return 'break';
+    const delay = nextRetryDelayMs();
+    dlog('llm', `req#${reqId} retry in ${delay}ms (attempt ${attempt + 1}/${DEFAULT_RETRY.maxAttempts}, tier=${backoffTier})`);
+    await sleep(delay, signal);
+    return 'retry';
+  };
+
+  for (let attempt = 1; attempt <= DEFAULT_RETRY.maxAttempts; attempt++) {
+    // 用户按 ESC/Ctrl+C 触发的 abort：立刻退出，不重试
+    if (signal?.aborted) {
+      throw makeAbortError();
+    }
+
+    // 每个 attempt 换一只新 watchdog（上一只可能已超时 abort，不能复用）
+    watchdog.dispose();
+    watchdog = createIdleWatchdog(signal);
+
+    try {
+      resp = await postChat();
+      watchdog.kick(); // 响应头到达 = 有进展
+    } catch (e) {
+      // 1) 用户主动 abort → handleNetworkError 里立刻抛
+      // 2) AbortSignal.timeout 触发的超时（Fetch 空闲超时还没回）
+      // 3) 其它网络错误（ECONNRESET / fetch failed / DNS 失败）→ 全部按"可重试"处理
+      if ((await handleNetworkError(e, attempt, 'failed (network)')) === 'break') break;
+      continue;
+    }
+
+    // resp.ok = true 直接跳出循环
+    if (resp.ok) break;
+
+    // resp !ok：本地退化路径（response_format / max_tokens 不被支持 → 去掉重发，不算重试；
+    // 仅 openai 分支——wantResponseFormat/wantMaxTokens 在 anthropic 分支恒为 false）
+    let errText = await resp.text().catch(() => '');
+
+    if (wantPromptCacheKey && isPromptCacheKeyRejected(resp.status, errText)) {
+      promptCacheKeyUnsupported.add(rfKey);
+      wantPromptCacheKey = false;
+      dlog('llm', `req#${reqId} prompt_cache_key unsupported; downgraded`, {
+        model: provider.model,
+      });
+      try {
+        resp = await postChat();
+        watchdog.kick();
+      } catch (e) {
+        if ((await handleNetworkError(e, attempt, 'cache-key fallback fetch failed')) === 'break') break;
+        continue;
+      }
+      if (resp.ok) break;
+      errText = await resp.text().catch(() => '');
+    }
+
+    // 退化①：response_format.json_schema 不支持
+    if (wantResponseFormat && isResponseFormatUnsupported(resp.status, errText)) {
+      // 记住该 model 不支持，单进程内后续结构化调用直接跳过 response_format（不再撞 400）。
+      rfUnsupported.add(rfKey);
+      console.warn(
+        `[minimal-agent] provider model "${provider.model}" 不支持 response_format.json_schema，` +
+          `已退化为 prompt 引导 + 容错解析（结构化输出的硬保证降级为尽力而为）。`,
+      );
+      wantResponseFormat = false; // 本 attempt 内继续，关闭 response_format
+      // 在同一 attempt 内再发一次（不计重试）
+      try {
+        resp = await postChat();
+        watchdog.kick();
+      } catch (e) {
+        // 退化二次 fetch 也网络错：把错误外提到外层重试循环
+        if ((await handleNetworkError(e, attempt, 'fallback fetch failed')) === 'break') break;
+        continue;
+      }
+      if (resp.ok) break;
+      // 仍 !ok：刷新 errText，让下面 max_tokens 退化看到最新报错（两种退化可叠加）
+      errText = await resp.text().catch(() => '');
+    }
+
+    // 退化②：max_tokens 不被该 provider 接受（极少数；豆包实测接受到 ≥131072）→ 去掉重发
+    if (wantMaxTokens && isMaxTokensRejected(resp.status, errText)) {
+      maxTokensUnsupported.add(rfKey);
+      console.warn(
+        `[minimal-agent] provider model "${provider.model}" 拒绝 max_tokens=${provider.maxTokens}，` +
+          `已去掉 max_tokens 重发（回落该 provider 默认输出上限，长输出可能被截断）。`,
+      );
+      wantMaxTokens = false; // 本 attempt 内继续，关闭 max_tokens
+      try {
+        resp = await postChat();
+        watchdog.kick();
+      } catch (e) {
+        if ((await handleNetworkError(e, attempt, 'fallback fetch failed')) === 'break') break;
+        continue;
+      }
+      if (resp.ok) break;
+      errText = await resp.text().catch(() => '');
+    }
+
+    // 退化③：模型不支持图片输入 → 剥离所有 image_url/video_url 重发（自动降级为纯文本）。
+    // 适用于新旧格式（openai/anthropic），仅触发一次，避免无限循环。
+    if (!imagesStripped && isImageInputRejected(resp.status, errText)) {
+      const hasImages = cleanedMessages.some((m) => {
+        const c = (m as { content?: unknown }).content;
+        return Array.isArray(c) && c.some((p: any) => p.type === 'image_url' || p.type === 'video_url');
+      });
+      if (hasImages) {
+        console.warn(
+          `[minimal-agent] provider model "${provider.model}" 不支持图片输入，` +
+            `已剥离图片重发（仅保留文本内容）。如该模型实际支持视觉，请在模型设置中确认。`,
+        );
+        cleanedMessages = stripImagesFromMessages(cleanedMessages);
+        imagesStripped = true;
+        try {
+          resp = await postChat();
+          watchdog.kick();
+        } catch (e) {
+          if ((await handleNetworkError(e, attempt, 'fallback fetch failed')) === 'break') break;
+          continue;
+        }
+        if (resp.ok) break;
+        errText = await resp.text().catch(() => '');
+      }
+    }
+
+    // 4xx 业务错误：不重试，直接抛（401/403 走 buildChatError 专属文案）
+    if (!isRetryableStatus(resp.status)) {
+      throw buildChatError(resp, errText);
+    }
+
+    // 5xx / 408 / 425 / 429：可重试
+    lastErr = buildChatError(resp, errText);
+    dlog('llm', `req#${reqId} attempt ${attempt} failed [${resp.status}]:`, errText.slice(0, 200));
+    if (attempt >= DEFAULT_RETRY.maxAttempts) break;
+
+    // 429 优先用 Retry-After 头，否则走自适应档位退避
+    const retryAfterMs = parseRetryAfter(resp);
+    const delay = nextRetryDelayMs(retryAfterMs);
+    dlog('llm', `req#${reqId} retry in ${delay}ms (attempt ${attempt + 1}/${DEFAULT_RETRY.maxAttempts}, tier=${backoffTier}, retryAfter=${retryAfterMs ?? 'tier'})`);
+    await sleep(delay, signal);
+  }
+
+  // 重试预算用尽仍没拿到 200：把最后一次的 Error 抛出去（注意不重置档位——还在堵）
+  if (!resp || !resp.ok) {
+    throw lastErr ?? new Error('LLM 请求失败：超过最大重试次数');
+  }
+  // 拿到 200 = 端点可达、拥塞已缓解 → 档位立即回落到最小值（成功就恢复，不永久拉长）。
+  resetBackoff();
+  if (!resp.body) {
+    throw new Error('LLM 响应没有 body（provider 可能不支持流式？）');
+  }
+  // fetch 已返回且 ok：若日志卡在这条之前 = fetch 阶段挂起（无超时）；卡在这条之后无 done = 流中途挂起。
+  dlog('llm', `req#${reqId} streaming begin (status ${resp.status})`);
+
+  // SSE 解析：把 ReadableStream 切成一行行 "data: ..." 交给 format 对应的 parser。
+  // 两种格式的 data 载荷都自解释（OpenAI 用字面量 "[DONE]"；Anthropic 的 JSON payload
+  // 自带 type 字段），行拆分逻辑本身不需要为格式差异分叉。
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  /** 临时缓冲：HTTP chunk 不一定按行切，要自己拼 */
+  let buffer = '';
+  const parser = format === 'anthropic' ? createAnthropicSSEParser() : createOpenAISSEParser();
+
+  try {
+    while (true) {
+      // 每次 read 前检查 abort：用户按 ESC/Ctrl+C 时 signal.aborted 为 true。
+      // 这样即使 fetch 还没完成，loop 也能及时退出而不是一直等到网络超时。
+      if (signal?.aborted) {
+        yield { type: 'done', stopReason: 'aborted' };
+        return;
+      }
+
+      const { value, done } = await reader.read();
+      watchdog.kick(); // 有新数据（reasoning/text/心跳都算进展）→ 重置空闲计时
+      if (done) break;
+
+      // 每个 chunk 处理完后也检查 abort，让快速连按能及时退出。
+      if (signal?.aborted) {
+        yield { type: 'done', stopReason: 'aborted' };
+        return;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // SSE 用 "\n\n" 分事件，按行拆 buffer
+      let lineEnd: number;
+      while ((lineEnd = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, lineEnd).trim();
+        buffer = buffer.slice(lineEnd + 1);
+        if (!line || !line.startsWith('data:')) continue;
+
+        const dataStr = line.slice(5).trim(); // 去掉 "data:" 前缀
+        const events = parser.handleData(dataStr);
+        for (const ev of events) {
+          yield ev;
+          if (ev.type === 'done') {
+            dlog('llm', `req#${reqId} done`, ev);
+            return;
+          }
+        }
+      }
+    }
+
+    // 流没有显式发终止事件（OpenAI [DONE] / Anthropic message_stop）就结束了——
+    // 用 parser 累积的兜底状态补一个 done。
+    const fallback = parser.buildFallbackDone();
+    dlog('llm', `req#${reqId} done (stream end, no terminal event)`, fallback);
+    yield fallback;
+  } finally {
+    watchdog.dispose();
+    reader.releaseLock?.();
+  }
+}

package/src/llm/promptCache.js

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