minimal-agent 0.9.0 → 0.10.0

package/src/llm/client.js

@@ -1,45 +1,45 @@
 /**
  * ============================================================
- *  src/llm/client.ts —— OpenAI 兼容 LLM 客户端（流式）
+ *  src/llm/client.ts —— LLM 客户端（流式，双协议）
  * ------------------------------------------------------------
  *  这个文件做一件事：把"消息历史 + 可用工具"发给 LLM，把"流式响应"逐 chunk
  *  yield 回上层。它是整个 agent 系统里唯一会 fetch() 远端 API 的地方。
  *
- *  我们用 OpenAI 的 Chat Completions 协议，因为：
- *    - DeepSeek、月之暗面、智谱、火山、OpenRouter 都按它兼容
- *    - 协议简单：POST 一个 JSON，回 SSE
+ *  支持两种协议格式（`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"，
- *    最后用 "data: [DONE]\n\n" 表示结束。
+ *    OpenAI 用 "data: [DONE]\n\n" 表示结束；Anthropic 用一个 data payload 里
+ *    `type:"message_stop"` 的事件表示结束（两者的 data 载荷都自解释，行拆分逻辑
+ *    不需要为格式差异特殊处理，见 anthropicFormat.ts 头注）。
  *
  *  本文件不依赖任何 npm 包（fetch 是 Bun/Node 20+ 内置）。
  * ============================================================
  */
 import { dlog } from '../utils/debugLog.js';
+import { buildOpenAIRequest, createOpenAISSEParser, isImageInputRejected, isMaxTokensRejected, isResponseFormatUnsupported, } from './providers/openaiFormat.js';
+import { buildAnthropicRequest, createAnthropicSSEParser } from './providers/anthropicFormat.js';
 /**
  * 记住"这个 baseURL::model 不支持 response_format.json_schema"，避免每次都先撞 400。
  * 单进程内有效；每个 -p 子进程是全新进程 → 首个结构化调用吃一次 400 再退化，可接受。
+ * 只对 openai 格式有意义（anthropic 无此就地退化概念，见下）。
  */
 const rfUnsupported = new Set();
-/** 调试日志用的请求自增号（vote 并发多 voter 时靠它在日志里区分是哪一路）。 */
-let reqCounter = 0;
 /**
- * 判断一个 400 是否在抱怨 response_format（json_schema）不被支持。
- * 各 provider 文案不一（火山 GLM：`json_schema is not supported by this model`），
- * 故宽松匹配："提到 response_format" 且 "出现 not support / unsupported / not valid / invalid"。
+ * 记住"这个 baseURL::model 拒绝我们发的 max_tokens"，避免每次都先撞 400。
+ * 与 rfUnsupported 同理，单进程内有效。绝大多数 provider 接受 max_tokens（实测豆包到
+ * ≥131072 仍正常），这只是给个别挑剔 provider 的兜底，命中后该进程不再发 max_tokens。
  */
-function isResponseFormatUnsupported(status, errText) {
-    if (status !== 400)
-        return false;
-    const t = errText.toLowerCase();
-    if (!t.includes('response_format'))
-        return false;
-    return (t.includes('not support') || // 命中 "not supported"
-        t.includes('unsupported') ||
-        t.includes('not valid') ||
-        t.includes('invalid'));
-}
+const maxTokensUnsupported = new Set();
+/** 调试日志用的请求自增号（vote 并发多 voter 时靠它在日志里区分是哪一路）。 */
+let reqCounter = 0;
 // ============================================================
 //  重试 + 超时（无网络重试 → 整条 IM 链卡死；这是 P0-1 的根治）
 // ------------------------------------------------------------
@@ -49,21 +49,86 @@ function isResponseFormatUnsupported(status, errText) {
 //  子进程挂起会整条 IM 通道 dir 锁卡死。
 //
 //  设计：
-//   - 指数退避 200ms → 400 → 800 → 1600 → 3200（封顶 5 次）
+//   - 自适应退避（拥塞控制式）：进程级档位 0.5→1→2→5→10→30→60s，失败逐级抬高、
+//     成功（拿到 200）立即回落到最小值；封顶 60s（超 1min 就不是拥塞、是真死，无谓再等）。
+//     跨请求记忆当前拥塞程度——连续失败不会从头傻试，刚成功又不会被旧拥塞拖慢。
 //   - 5xx / 408 / 425 / 429 / 网络错误全部重试
 //   - 401 / 403 / 404 等 4xx 不重试（重试无意义）+ 给清晰"key 失效"提示
 //   - 429 优先解析 Retry-After 头（秒），封顶 60s
-//   - AbortSignal.timeout 120s 兜底单次 fetch 时长
+//   - 空闲 watchdog 兜底卡死（语义见 IDLE_TIMEOUT_MS 注释——是【空闲】不是【总时长】）
 //   - 用户 signal 触发的 abort 立即退出，不重试
 //   - 流式响应中途中断（reader.read reject）走同一个错误路径
 // ============================================================
-/** 单一 fetch 请求的超时（毫秒）。流式响应中途不发新 chunk 也算超时。 */
-const FETCH_TIMEOUT_MS = 120_000;
+/**
+ * 流式空闲超时（毫秒）：自上一个字节到达起算，超过仍无任何新数据才判死。
+ * 可用 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;
+})();
+/**
+ * 网络/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 = {
-    maxAttempts: 5,
-    baseDelayMs: 200,
-    maxDelayMs: 3200,
+    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) {
+    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() {
+    backoffTier = 0;
+}
+/** 仅供测试：读取/重置进程级档位（生产代码勿调）。 */
+export function _getBackoffTier() {
+    return backoffTier;
+}
+export function _resetBackoffTier() {
+    backoffTier = 0;
+}
+/** 仅供测试：暴露纯退避计算，供单测验证档位曲线/封顶/Retry-After（不触网）。 */
+export function _nextRetryDelayMs(retryAfterMs) {
+    return nextRetryDelayMs(retryAfterMs);
+}
 /** 可重试的 HTTP 状态码。4xx 除 408/425/429 外不重试（重试无意义）。 */
 function isRetryableStatus(status) {
     return status === 408 || status === 425 || status === 429 || (status >= 500 && status < 600);
@@ -82,11 +147,25 @@ function parseRetryAfter(resp) {
         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') {
+    const err = new Error(message);
+    err.name = 'AbortError';
+    return err;
+}
 /** 可中断的 sleep：用户 signal 触发 abort 立刻 reject，不阻塞退出。 */
 function sleep(ms, signal) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
-            reject(new Error('aborted'));
+            reject(makeAbortError());
             return;
         }
         const timer = setTimeout(() => {
@@ -95,7 +174,7 @@ function sleep(ms, signal) {
         }, ms);
         const onAbort = () => {
             clearTimeout(timer);
-            reject(new Error('aborted'));
+            reject(makeAbortError());
         };
         signal?.addEventListener('abort', onAbort, { once: true });
     });
@@ -106,25 +185,46 @@ function buildChatError(resp, body) {
     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 的 MINIMAL_AGENT_API_KEY 与 provider 配置。\n` +
+            `请检查 .env / ~/.minimal-agent/config.json 的模型配置。\n` +
             `原始错误：${body.slice(0, 500)}`);
     }
     return new Error(`LLM 请求失败 ${head}：${body.slice(0, 500)}`);
 }
 /**
- * 把用户 signal 与超时 signal 组合，任一触发即 abort。
- * AbortSignal.any 是 Node 20.3+ / Bun 内置，project engines.node=">=20" 满足。
+ * 空闲 watchdog：kick() 重置计时；IDLE_TIMEOUT_MS 内没有任何 kick 才 abort。
+ * 与用户 signal 组合（AbortSignal.any，Node 20.3+/Bun 内置），任一触发即中断。
+ * 调用方契约：fetch 等待期自动计时；流式期间每收到一个 chunk 调一次 kick()；
+ * 结束（无论成败）调 dispose() 清掉定时器。
  */
-function combinedSignal(userSignal) {
-    const timeout = AbortSignal.timeout(FETCH_TIMEOUT_MS);
-    if (!userSignal)
-        return timeout;
-    return AbortSignal.any([userSignal, timeout]);
+export function createIdleWatchdog(userSignal, timeoutMs = IDLE_TIMEOUT_MS) {
+    const ctrl = new AbortController();
+    let timer = null;
+    const arm = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            ctrl.abort(new Error(`LLM 流式响应空闲超时：${timeoutMs}ms 内未收到任何新数据（总时长不限，只判空闲；可用 MINIMAL_AGENT_IDLE_TIMEOUT_MS 调整）`));
+        }, timeoutMs);
+        // 不阻止进程退出（Bun/Node 均支持 unref）
+        timer.unref?.();
+    };
+    arm();
+    return {
+        signal: userSignal ? AbortSignal.any([userSignal, ctrl.signal]) : ctrl.signal,
+        kick: arm,
+        dispose: () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+        },
+    };
 }
 /**
- * 调用 LLM 并以流的形式 yield 事件。
+ * 调用 LLM 并以流的形式 yield 事件。协议格式由 `provider.apiFormat` 决定
+ * （缺省 'openai'）；两种格式共用本函数的重试/退避/看门狗骨架，请求体构造和
+ * SSE 解析分别委托给 providers/openaiFormat.ts / providers/anthropicFormat.ts。
  *
- * @param provider 选好的 provider（含 baseURL / apiKey / model）
+ * @param provider 选好的 provider（含 baseURL / apiKey / model / apiFormat）
  * @param messages 完整的对话历史
  * @param tools    工具列表（每个工具需要带 jsonSchema 才能给 LLM）
  * @param signal   AbortSignal，UI 按 Ctrl+C 时中断
@@ -140,104 +240,115 @@ function combinedSignal(userSignal) {
  */
 export async function* chat(args) {
     const { provider, messages, tools, signal, responseFormat } = args;
-    // 1. 把 Tool 数组转成 OpenAI 协议的 tools 字段
-    const openaiTools = tools.map((t) => ({
-        type: 'function',
-        function: {
-            name: t.name,
-            description: typeof t.description === 'function' ? t.description() : t.description,
-            parameters: t.parameters,
-        },
-    }));
-    // 2. 过滤并清洁 messages 数组，剥离 timestamp, id, _ephemeral 等本地渲染元数据
-    const cleanedMessages = messages
-        .filter((m) => {
-        // 过滤掉 _ephemeral=true 的临时 UI 提示消息，防止其污染 LLM 核心上下文
-        if (m.role === 'system' && m._ephemeral === true) {
-            return false;
-        }
-        return true;
-    })
+    const format = 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 = messages
+        .filter((m) => !(m.role === 'system' && m._ephemeral === true))
         .map((m) => {
-        // 结构解构以去除本地专属渲染元数据
-        const { id, timestamp, ...rest } = m;
+        const { id, timestamp, attachments, display_metadata, ...rest } = m;
         return rest;
     });
-    // 3. 构造请求体
-    // 逃生开关：极个别 provider 不认 stream_options 会 400，可用 MINIMAL_AGENT_DISABLE_USAGE=1 关掉。
     const includeUsage = process.env.MINIMAL_AGENT_DISABLE_USAGE !== '1';
-    const url = `${provider.baseURL.replace(/\/$/, '')}/chat/completions`;
-    // response_format 能力探测：部分 OpenAI 兼容 provider（如火山 GLM 系）不支持
-    // response_format.type=json_schema，会回 400。已知不支持的 model 直接跳过，
-    // 撞到 400 则退化重试（去掉 response_format，靠 prompt 内嵌 schema + 上层 extractJsonPayload 容错解析）。
     const rfKey = `${provider.baseURL}::${provider.model}`;
-    let wantResponseFormat = responseFormat !== undefined && !rfUnsupported.has(rfKey);
-    const postChat = (withResponseFormat) => fetch(url, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${provider.apiKey}`,
-        },
-        body: JSON.stringify({
-            model: provider.model,
-            messages: cleanedMessages,
-            tools: openaiTools.length > 0 ? openaiTools : undefined,
-            stream: true,
-            // 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,
-        }),
-        // 用组合 signal：用户 signal 触发的 abort + 120s fetch 超时，任意一个先到即中断。
-        // （之前裸传 signal，fetch 永远不超时，gateway 桥接子进程挂死时 IM 链卡死——P0-1 根因）
-        signal: combinedSignal(signal),
+    // 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;
+    const stripImagesFromMessages = (msgs) => msgs.map((m) => {
+        const c = m.content;
+        if (!Array.isArray(c))
+            return m;
+        const textOnly = c.filter((p) => p.type === 'text');
+        const newContent = textOnly.length > 0
+            ? textOnly.map((p) => ({ type: 'text', text: p.text }))
+            : [{ type: 'text', text: '[图片内容未发送：当前模型不支持图片输入]' }];
+        return { ...m, content: newContent };
     });
-    // 3. 发请求（fetch 在 Bun/Node 20+ 内置），带重试 + 超时
+    // 空闲 watchdog：每个 attempt 一只（重试前换新）；fetch 等待期自动计时，
+    // 流式期间每个 chunk kick 一次。用户 signal 与 watchdog 任一触发即中断。
+    let watchdog = createIdleWatchdog(signal);
+    const postChat = () => {
+        const req = format === 'anthropic'
+            ? buildAnthropicRequest({ provider, cleanedMessages, tools })
+            : buildOpenAIRequest({
+                provider,
+                cleanedMessages,
+                tools,
+                withResponseFormat: wantResponseFormat,
+                withMaxTokens: wantMaxTokens,
+                includeUsage,
+                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: openaiTools.length,
+        tools: tools.length,
     });
-    // 3a. 重试循环：每个 attempt 内部可能触发"response_format 不支持 → 去掉"的本地退化
-    //     （本地退化不算重试，仍属同一 attempt 的"拿到 200"路径的一部分）
-    //     只有"网络/超时/5xx/429"才跨 attempt 重试，4xx 业务错误直接抛
+    // 重试循环：每个 attempt 内部可能触发"response_format 不支持 → 去掉"的本地退化
+    //     （本地退化不算重试，仍属同一 attempt 的"拿到 200"路径的一部分；只 openai 分支会真的
+    //     进入这两个退化 if）。只有"网络/超时/5xx/429"才跨 attempt 重试，4xx 业务错误直接抛
     //     （401/403 走 buildChatError 的专属文案，不浪费 5 次重试）
     let resp;
     let lastErr;
+    // 网络错误统一收尾（主路径 + 两条退化路径共用，防退避策略三处漂移）：
+    // 用户 abort → 抛；置 lastErr + dlog；额度用尽 → 'break'；否则退避后 'retry'。
+    const handleNetworkError = async (e, attempt, label) => {
+        if (signal?.aborted)
+            throw makeAbortError();
+        const err = e;
+        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 new Error('aborted');
+            throw makeAbortError();
         }
+        // 每个 attempt 换一只新 watchdog（上一只可能已超时 abort，不能复用）
+        watchdog.dispose();
+        watchdog = createIdleWatchdog(signal);
         try {
-            resp = await postChat(wantResponseFormat);
+            resp = await postChat();
+            watchdog.kick(); // 响应头到达 = 有进展
         }
         catch (e) {
-            // 1) 用户主动 abort（signal.aborted 触发 AbortError）→ 立刻抛
-            if (signal?.aborted)
-                throw new Error('aborted');
-            // 2) AbortSignal.timeout 触发的超时（Fetch 120s 还没回）
+            // 1) 用户主动 abort → handleNetworkError 里立刻抛
+            // 2) AbortSignal.timeout 触发的超时（Fetch 空闲超时还没回）
             // 3) 其它网络错误（ECONNRESET / fetch failed / DNS 失败）→ 全部按"可重试"处理
-            const err = e;
-            lastErr = new Error(`LLM 网络错误 [${err.name ?? 'NetworkError'}]：${err.message}`);
-            dlog('llm', `req#${reqId} attempt ${attempt} failed (network):`, err.message);
-            if (attempt >= DEFAULT_RETRY.maxAttempts)
+            if ((await handleNetworkError(e, attempt, 'failed (network)')) === 'break')
                 break;
-            const delay = Math.min(DEFAULT_RETRY.baseDelayMs * 2 ** (attempt - 1), DEFAULT_RETRY.maxDelayMs);
-            dlog('llm', `req#${reqId} retry in ${delay}ms (attempt ${attempt + 1}/${DEFAULT_RETRY.maxAttempts})`);
-            await sleep(delay, signal);
             continue;
         }
         // resp.ok = true 直接跳出循环
         if (resp.ok)
             break;
-        // resp !ok：先看是不是 json_schema 不支持（本地退化路径，不算重试）
-        const errText = await resp.text().catch(() => '');
+        // resp !ok：本地退化路径（response_format / max_tokens 不被支持 → 去掉重发，不算重试；
+        // 仅 openai 分支——wantResponseFormat/wantMaxTokens 在 anthropic 分支恒为 false）
+        let errText = await resp.text().catch(() => '');
+        // 退化①：response_format.json_schema 不支持
         if (wantResponseFormat && isResponseFormatUnsupported(resp.status, errText)) {
             // 记住该 model 不支持，单进程内后续结构化调用直接跳过 response_format（不再撞 400）。
             rfUnsupported.add(rfKey);
@@ -246,25 +357,64 @@ export async function* chat(args) {
             wantResponseFormat = false; // 本 attempt 内继续，关闭 response_format
             // 在同一 attempt 内再发一次（不计重试）
             try {
-                resp = await postChat(false);
+                resp = await postChat();
+                watchdog.kick();
             }
             catch (e) {
                 // 退化二次 fetch 也网络错：把错误外提到外层重试循环
-                const err = e;
-                lastErr = new Error(`LLM 网络错误 [${err.name ?? 'NetworkError'}]：${err.message}`);
-                dlog('llm', `req#${reqId} attempt ${attempt} fallback fetch failed:`, err.message);
-                if (signal?.aborted)
-                    throw new Error('aborted');
-                if (attempt >= DEFAULT_RETRY.maxAttempts)
+                if ((await handleNetworkError(e, attempt, 'fallback fetch failed')) === 'break')
                     break;
-                const delay = Math.min(DEFAULT_RETRY.baseDelayMs * 2 ** (attempt - 1), DEFAULT_RETRY.maxDelayMs);
-                dlog('llm', `req#${reqId} retry in ${delay}ms (attempt ${attempt + 1}/${DEFAULT_RETRY.maxAttempts})`);
-                await sleep(delay, signal);
                 continue;
             }
-            // 退化后 OK 或 仍 !ok 都走下面统一判断
             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.content;
+                return Array.isArray(c) && c.some((p) => 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)) {
@@ -275,32 +425,31 @@ export async function* chat(args) {
         dlog('llm', `req#${reqId} attempt ${attempt} failed [${resp.status}]:`, errText.slice(0, 200));
         if (attempt >= DEFAULT_RETRY.maxAttempts)
             break;
-        // 429 优先用 Retry-After 头，否则走指数退避
+        // 429 优先用 Retry-After 头，否则走自适应档位退避
         const retryAfterMs = parseRetryAfter(resp);
-        const delay = retryAfterMs !== undefined
-            ? retryAfterMs
-            : Math.min(DEFAULT_RETRY.baseDelayMs * 2 ** (attempt - 1), DEFAULT_RETRY.maxDelayMs);
-        dlog('llm', `req#${reqId} retry in ${delay}ms (attempt ${attempt + 1}/${DEFAULT_RETRY.maxAttempts}, retryAfter=${retryAfterMs ?? 'exp'})`);
+        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);
     }
-    // 5 次都没拿到 200：把最后一次的 Error 抛出去
+    // 重试预算用尽仍没拿到 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})`);
-    // 5. SSE 解析：把 ReadableStream 切成一行行 "data: ..." 然后 JSON.parse
+    // 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 = '';
-    /** 累积的 stop_reason，最后 yield done 时用 */
-    let stopReason = 'unknown';
-    /** 真实 prompt_tokens（从 usage chunk 读取）；provider 不返回时保持 undefined */
-    let usagePromptTokens;
+    const parser = format === 'anthropic' ? createAnthropicSSEParser() : createOpenAISSEParser();
     try {
         while (true) {
             // 每次 read 前检查 abort：用户按 ESC/Ctrl+C 时 signal.aborted 为 true。
@@ -310,6 +459,7 @@ export async function* chat(args) {
                 return;
             }
             const { value, done } = await reader.read();
+            watchdog.kick(); // 有新数据（reasoning/text/心跳都算进展）→ 重置空闲计时
             if (done)
                 break;
             // 每个 chunk 处理完后也检查 abort，让快速连按能及时退出。
@@ -326,87 +476,24 @@ export async function* chat(args) {
                 if (!line || !line.startsWith('data:'))
                     continue;
                 const dataStr = line.slice(5).trim(); // 去掉 "data:" 前缀
-                if (dataStr === '[DONE]') {
-                    // 流结束标记；带出真实 prompt_tokens（provider 不返回时为 undefined，上层 fallback 本地估算）
-                    dlog('llm', `req#${reqId} done [DONE]`, { stopReason, promptTokens: usagePromptTokens });
-                    yield { type: 'done', stopReason, promptTokens: usagePromptTokens };
-                    return;
-                }
-                // 解析一个 chunk JSON
-                let chunk;
-                try {
-                    chunk = JSON.parse(dataStr);
-                }
-                catch {
-                    // 罕见：某些 provider 会发空行或心跳，忽略
-                    continue;
-                }
-                // usage chunk：include_usage 开启时，provider 通常在流末单独发一帧，
-                // 此帧 choices 为空（没有 delta），必须在 `if (!delta) continue` 之前读取，
-                // 否则会被 continue 跳过，永远拿不到真实 prompt_tokens。
-                if (chunk.usage && typeof chunk.usage.prompt_tokens === 'number') {
-                    usagePromptTokens = chunk.usage.prompt_tokens;
-                }
-                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)
-                    continue;
-                // 5a. 文本增量
-                //   注意：MiniMax 等模型默认会把 <think>...</think> 标签直接放在
-                //   content 字段里 —— 我们原样累积，不剥离，确保下一轮工具调用时
-                //   思维链完整回传。
-                if (typeof delta.content === 'string' && delta.content.length > 0) {
-                    yield { type: 'text_delta', delta: delta.content };
-                }
-                // 5b. tool_calls 增量（OpenAI 协议下 tool_calls 也是分片的）
-                if (Array.isArray(delta.tool_calls)) {
-                    for (const tc of delta.tool_calls) {
-                        yield {
-                            type: 'tool_call_delta',
-                            index: tc.index ?? 0,
-                            id: tc.id,
-                            name: tc.function?.name,
-                            argumentsDelta: tc.function?.arguments,
-                        };
+                const events = parser.handleData(dataStr);
+                for (const ev of events) {
+                    yield ev;
+                    if (ev.type === 'done') {
+                        dlog('llm', `req#${reqId} done`, ev);
+                        return;
                     }
                 }
-                // 5c. 思维链增量（DeepSeek-R1 / MiniMax reasoning_split / OpenRouter）
-                //   三种字段名都见过：reasoning_content / reasoning / reasoning_details
-                //   reasoning_details 是数组，每片是个对象；其它两个是字符串增量。
-                if (typeof delta.reasoning_content === 'string' && delta.reasoning_content.length > 0) {
-                    yield {
-                        type: 'reasoning_delta',
-                        field: 'reasoning_content',
-                        delta: delta.reasoning_content,
-                    };
-                }
-                if (typeof delta.reasoning === 'string' && delta.reasoning.length > 0) {
-                    yield {
-                        type: 'reasoning_delta',
-                        field: 'reasoning',
-                        delta: delta.reasoning,
-                    };
-                }
-                if (Array.isArray(delta.reasoning_details) && delta.reasoning_details.length > 0) {
-                    yield {
-                        type: 'reasoning_delta',
-                        field: 'reasoning_details',
-                        items: delta.reasoning_details,
-                    };
-                }
             }
         }
-        // 如果流没显式发 [DONE]，也补一个 done；同样带出 promptTokens
-        dlog('llm', `req#${reqId} done (stream end, no [DONE])`, { stopReason, promptTokens: usagePromptTokens });
-        yield { type: 'done', stopReason, promptTokens: usagePromptTokens };
+        // 流没有显式发终止事件（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?.();
     }
 }