zen-gitsync 2.18.26 → 2.18.27

package/src/ui/server/routes/recentDirectoriesAiSummary.js

@@ -37,6 +37,7 @@ import express from 'express';
 import { callLlmStream } from './workbench/llmClient.js';
 import { createThinkFilter } from '../../../cli/ai/streamFilter.js';
 import { normalizeDirKey } from '../utils/directoryGitState.js';
+import { buildModelFallbackChain, modelLabel, runWithModelFallback } from '../../../utils/aiModelFallback.js';
 import logger from '../utils/logger.js';
 
 /** 一次最多解读多少个目录,与 /api/recent_directories/git-state 的上限保持一致 */
@@ -276,18 +277,18 @@ export function registerRecentDirectoriesSummaryRoutes({ app, configManager }) {
         return res.end();
       }
 
-      // 取默认模型(isDefault 优先,否则第一个),与提交信息生成同一口径
-      let model;
+      // 候选链 = 默认模型打头,其余已配置模型跟上(默认模型额度用完也不会整块不可用)
+      let chain;
       try {
         const rawConfig = await configManager.readRawConfigFile();
         const models = Array.isArray(rawConfig.models) ? rawConfig.models : [];
-        model = models.find(m => m.isDefault) || models[0];
+        chain = buildModelFallbackChain(models);
       } catch (err) {
         send({ type: 'error', error: '读取 AI 配置失败: ' + err.message, code: 'CONFIG_ERR' });
         finished = true;
         return res.end();
       }
-      if (!model) {
+      if (chain.length === 0) {
         send({ type: 'error', error: '未配置 AI 模型', code: 'NO_MODEL' });
         finished = true;
         return res.end();
@@ -302,18 +303,30 @@ export function registerRecentDirectoriesSummaryRoutes({ app, configManager }) {
         send({ type: 'delta', content });
       });
 
-      const { aborted } = await callLlmStream(
-        model,
-        prompt,
-        (delta) => {
-          if (delta.content) contentStream.feed(delta.content);
-        },
+      // 已经往 SSE 里推过内容就不能换模型（会重复输出半截说明），只有「一个字都还没吐」
+      // 时才允许重试下一个
+      const { result } = await runWithModelFallback(
+        chain,
+        (candidate) => callLlmStream(
+          candidate,
+          prompt,
+          (delta) => {
+            if (delta.content) contentStream.feed(delta.content);
+          },
+          {
+            maxTokens: MAX_SUMMARY_TOKENS,
+            systemPrompt: zh ? SYSTEM_PROMPT_ZH : SYSTEM_PROMPT_EN,
+            signal: abortController.signal,
+          }
+        ),
         {
-          maxTokens: MAX_SUMMARY_TOKENS,
-          systemPrompt: zh ? SYSTEM_PROMPT_ZH : SYSTEM_PROMPT_EN,
-          signal: abortController.signal,
+          isFatal: () => summaryText.length > 0,
+          onFallback: ({ from, to, error }) => logger.warn(
+            `[recent_directories/summary] 模型 ${modelLabel(from)} 调用失败(${error?.message || error}),改用 ${modelLabel(to)}`
+          ),
         }
       );
+      const aborted = Boolean(result?.aborted);
 
       if (aborted) {
         // 前端主动断开(关弹窗/切目录):不是错误,也不必补一条 error 事件

package/src/ui/server/routes/workbench/imageDescribe.js

@@ -44,6 +44,7 @@ import path from 'node:path';
 import { logger, readJson, CONFIG_FILE } from './shared.js';
 import { isImageExt } from './attachmentUtils.js';
 import { callLlmStream } from './llmClient.js';
+import { buildModelFallbackChain, modelLabel, runWithModelFallback } from '../../../../utils/aiModelFallback.js';
 
 /** 单张图片大小上限：超过就不送去描述（base64 之后还要再涨 1/3） */
 export const MAX_DESCRIBE_IMAGE_BYTES = 6 * 1024 * 1024;
@@ -84,6 +85,22 @@ export async function resolveDescribeModel() {
   }
 }
 
+/**
+ * 图片描述用的候选模型链：默认模型打头，其余已配置模型兜底（默认模型没额度时
+ * 还能用别的模型把图转成文字）。
+ *
+ * @returns {Promise<Array<object>>}
+ */
+export async function resolveDescribeModelChain() {
+  try {
+    const raw = await readJson(CONFIG_FILE, {});
+    return buildModelFallbackChain(Array.isArray(raw?.models) ? raw.models : []);
+  } catch (err) {
+    logger.warn('[imageDescribe] 读取 AI 配置失败，跳过图片转文字:', err?.message || err);
+    return [];
+  }
+}
+
 /** 附件里的图片（按 isImageExt 判，与附件白名单同一份口径） */
 export function pickImageAttachments(attachments) {
   if (!Array.isArray(attachments)) return [];
@@ -94,7 +111,7 @@ export function pickImageAttachments(attachments) {
  * 描述一张图片。
  *
  * @param {string} filePath 本机绝对路径
- * @param {object} model    config.json 里的模型条目
+ * @param {object|object[]} model config.json 里的模型条目（数组 = 候选链，前一个失败换下一个）
  * @param {object} [opts]
  * @param {string} [opts.fileName] 给模型的文件名提示（不含目录，别泄漏本地路径）
  * @returns {Promise<string|null>} 描述文本；失败/超限/空回答一律 null
@@ -121,19 +138,34 @@ export async function describeImage(filePath, model, opts = {}) {
 
   let text = '';
   try {
-    const { content, aborted } = await callLlmStream(
-      model,
-      `这张图片的文件名是 ${name}，请按系统提示把它转成文字描述。`,
-      (delta) => { if (delta?.content) text += delta.content; },
-      {
-        images: [dataUrl],
-        systemPrompt: SYSTEM_PROMPT,
-        maxTokens: MAX_DESCRIBE_CHARS * 2,
-        timeoutMs: DESCRIBE_TIMEOUT_MS,
+    const chain = Array.isArray(model) ? model : [model];
+    // 已经吐过文字就不能换模型（会把两段描述拼在一起）；一张图重试几次都失败就
+    // 由外层 anyFailed 熔断，不继续烧额度
+    const { result: streamResult } = await runWithModelFallback(
+      chain,
+      (candidate) => {
+        text = '';
+        return callLlmStream(
+          candidate,
+          `这张图片的文件名是 ${name}，请按系统提示把它转成文字描述。`,
+          (delta) => { if (delta?.content) text += delta.content; },
+          {
+            images: [dataUrl],
+            systemPrompt: SYSTEM_PROMPT,
+            maxTokens: MAX_DESCRIBE_CHARS * 2,
+            timeoutMs: DESCRIBE_TIMEOUT_MS,
+          },
+        );
       },
+      {
+        isFatal: () => text.length > 0,
+        onFallback: ({ from, to, error }) => logger.warn(
+          `[imageDescribe] 模型 ${modelLabel(from)} 描述图片失败(${error?.message || error}),改用 ${modelLabel(to)}`
+        ),
+      }
     );
-    if (aborted) return null;
-    const out = String(content || text || '').trim();
+    if (streamResult?.aborted) return null;
+    const out = String(streamResult?.content || text || '').trim();
     if (!out) return null;
     return out.length > MAX_DESCRIBE_CHARS
       ? out.slice(0, MAX_DESCRIBE_CHARS) + '…'
@@ -161,7 +193,9 @@ export async function describeImage(filePath, model, opts = {}) {
  */
 export async function createImageDescriber(opts = {}) {
   const maxImages = Number.isFinite(opts.maxImages) ? opts.maxImages : MAX_DESCRIBE_IMAGES;
-  const model = opts.model || await resolveDescribeModel();
+  const chain = opts.model
+    ? (Array.isArray(opts.model) ? opts.model : [opts.model])
+    : await resolveDescribeModelChain();
   const runDescribe = typeof opts.describe === 'function' ? opts.describe : describeImage;
   const cache = new Map();
   let done = 0;
@@ -169,15 +203,17 @@ export async function createImageDescriber(opts = {}) {
 
   return async function describe(att) {
     const filePath = att && att.absolutePath;
-    if (!filePath || !model) return null;
+    if (!filePath || chain.length === 0) return null;
     if (cache.has(filePath)) return cache.get(filePath);
     if (done >= maxImages || anyFailed) return null;
     done++;
-    const text = await runDescribe(filePath, model, { fileName: att.originalName || '' });
+    const text = await runDescribe(filePath, chain.length === 1 ? chain[0] : chain, {
+      fileName: att.originalName || '',
+    });
     if (!text) anyFailed = true;
     cache.set(filePath, text);
     return text;
   };
 }
 
-export default { describeImage, createImageDescriber, resolveDescribeModel, pickImageAttachments };
+export default { describeImage, createImageDescriber, resolveDescribeModel, resolveDescribeModelChain, pickImageAttachments };

package/src/utils/aiModelFallback.js

@@ -0,0 +1,180 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// ─────────────────────────────────────────────────────────────
+// 默认模型失败时的「换模型重试」层
+//
+// 背景：本项目里所有 AI 驱动的内容（AI 启动建议 / 差异说明 / 目录解读 /
+// 代码分析 / 提交信息）以前都写死「取 isDefault 的那一个，失败就报错」。
+// 默认模型这个月的额度用完之后，这些功能会**整块不可用** —— 明明设置里还配着
+// 好几个能用的模型。
+//
+// 这一层的口径：
+//   1) 候选来源就是 config.json 的 models[]，默认模型排第一，其余按配置顺序跟在后面；
+//   2) 同一个 baseURL+model 只算一个（重复添加的条目不该被重试两次）；
+//   3) 最多试 MAX_FALLBACK_MODELS 个 —— 候选多了会让「全都失败」变成 3×超时的等待；
+//   4) 用户主动取消（AbortError）不算失败，不该被下一个模型悄悄续上；
+//   5) 已经往外吐过内容的流式调用不能换模型（会重复输出半截内容），由调用方通过
+//      isFatal 判定，本层只负责「能不能继续」这件事的分发。
+// ─────────────────────────────────────────────────────────────
+
+/** 一次请求最多尝试几个模型（默认 + 备用） */
+export const MAX_FALLBACK_MODELS = 3;
+
+/**
+ * 归一化 baseURL：去尾部斜杠 + 小写，只用于去重。
+ * 用户可能把 `.../v1/` 和 `.../v1` 各配一遍，那是同一个端点。
+ * @param {unknown} value
+ * @returns {string}
+ */
+function normalizedBase(value) {
+  return String(value || '').trim().replace(/\/+$/, '').toLowerCase();
+}
+
+/** 只认非空字符串 */
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/**
+ * 模型的展示名：优先用户起的名字，其次模型名。
+ * @param {{name?: string, model?: string}} model
+ * @returns {string}
+ */
+export function modelLabel(model) {
+  return text(model?.name) || text(model?.model) || '未命名模型';
+}
+
+/**
+ * 判断一个错误是不是「用户取消」。
+ * node-fetch 抛 AbortError，axios 风格是 CanceledError / ERR_CANCELED。
+ * @param {any} err
+ * @returns {boolean}
+ */
+export function isAbortLikeError(err) {
+  if (!err) return false;
+  const name = String(err.name || '');
+  const code = String(err.code || '');
+  return name === 'AbortError' || name === 'CanceledError'
+    || code === 'ABORT_ERR' || code === 'ERR_CANCELED';
+}
+
+/** 错误文案：空错误也得有个能看的说法，否则界面上就是一行空白 */
+function errorMessage(err) {
+  return String(err?.message || err || '').trim() || '未知错误';
+}
+
+/**
+ * 把 config.json 的 models[] 整理成「默认模型优先」的候选链。
+ *
+ * @param {Array<object>} models
+ * @param {object} [opts]
+ * @param {number} [opts.limit=MAX_FALLBACK_MODELS] 最多返回几个（<=0 表示不限）
+ * @param {boolean} [opts.defaultFirst=true] 是否把 isDefault 提到第一位。
+ *        调用方已经排好序（例如用户显式指定的模型要打头）时传 false。
+ * @returns {Array<object>}
+ */
+export function buildModelFallbackChain(models, { limit = MAX_FALLBACK_MODELS, defaultFirst = true } = {}) {
+  const list = Array.isArray(models) ? models : [];
+  const seen = new Set();
+  const usable = [];
+
+  for (const model of list) {
+    if (!model || typeof model !== 'object') continue;
+    // 缺 endpoint / 缺模型名的条目发出去也只能报错，直接跳过
+    if (!text(model.baseURL) || !text(model.model)) continue;
+    const key = `${normalizedBase(model.baseURL)}\u0000${text(model.model).toLowerCase()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    usable.push(model);
+  }
+
+  const defaultIndex = defaultFirst ? usable.findIndex(m => m.isDefault) : -1;
+  const ordered = defaultIndex > 0
+    ? [usable[defaultIndex], ...usable.slice(0, defaultIndex), ...usable.slice(defaultIndex + 1)]
+    : usable;
+
+  const cap = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : ordered.length;
+  return ordered.slice(0, cap);
+}
+
+/**
+ * 给「全都失败」的错误补上每个模型各自的报错，否则界面上只剩最后那个模型的文案，
+ * 用户看不出到底试过谁、前一个为什么不行。
+ */
+function decorateError(err, attempts) {
+  // 只试了一个（没发生切换）→ 原样抛，保持各调用点此前的错误文案与错误类型
+  if (attempts.length <= 1) return err;
+  const detail = attempts.map(a => `${a.label}（${a.message}）`).join('；');
+  const wrapped = new Error(`所有 AI 模型都调用失败：${detail}`);
+  wrapped.attempts = attempts;
+  wrapped.cause = err;
+  // 保留最后一次的错误码：路由层靠 code 区分 TIMEOUT / NO_JSON 等分支
+  if (err && typeof err === 'object' && err.code !== undefined) wrapped.code = err.code;
+  return wrapped;
+}
+
+/**
+ * 依次用候选模型执行 run(model)，前一个失败才换下一个。
+ *
+ * @param {Array<object>} chain - buildModelFallbackChain 的结果
+ * @param {(model: object, index: number) => Promise<any>} run
+ * @param {object} [opts]
+ * @param {(err: any, model: object, index: number) => boolean} [opts.isFatal]
+ *        返回 true = 这个错误不该换模型（用户取消 / 流里已经吐过内容）
+ * @param {(info: {error: any, from: object, to: object, index: number}) => void} [opts.onFallback]
+ *        发生切换时的回调（调用方拿去打日志 / 提示）
+ * @returns {Promise<{result: any, model: object, attempts: Array<object>}>}
+ *          result 是 run 的返回值，model 是**真正成功**的那个模型
+ * @throws {Error} 全部失败时抛出（带 attempts），或首个致命错误原样抛出
+ */
+export async function runWithModelFallback(chain, run, opts = {}) {
+  const list = Array.isArray(chain) ? chain.filter(Boolean) : [];
+  const { isFatal, onFallback } = opts;
+  if (list.length === 0) throw new Error('未配置 AI 模型');
+
+  const attempts = [];
+  for (let i = 0; i < list.length; i += 1) {
+    const model = list[i];
+    try {
+      const result = await run(model, i);
+      return { result, model, attempts };
+    } catch (err) {
+      attempts.push({ model, label: modelLabel(model), message: errorMessage(err), error: err });
+      let fatal = isAbortLikeError(err);
+      if (!fatal && typeof isFatal === 'function') {
+        try {
+          fatal = Boolean(isFatal(err, model, i));
+        } catch {
+          fatal = false;
+        }
+      }
+      if (fatal || i === list.length - 1) throw decorateError(err, attempts);
+      try {
+        onFallback?.({ error: err, from: model, to: list[i + 1], index: i });
+      } catch { /* 日志回调自己出错不该影响重试 */ }
+    }
+  }
+
+  // 循环正常结束只可能是 list 为空（已在上面拦掉），这里只是给 TS / 读者一个明确出口
+  throw decorateError(attempts[attempts.length - 1]?.error || new Error('AI 调用失败'), attempts);
+}
+
+export default {
+  MAX_FALLBACK_MODELS,
+  buildModelFallbackChain,
+  isAbortLikeError,
+  modelLabel,
+  runWithModelFallback,
+};

package/src/utils/aiModelFallback.test.js

@@ -0,0 +1,166 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// src/utils/aiModelFallback.js 单元测试（node:test 内置）。
+//
+// 这一层是为了修「默认模型额度用完，AI 启动建议 / 差异说明 / 提交信息全不可用」
+// 而抽出来的，所以把口径钉死：
+//   1) 候选链默认模型排第一，其余按配置顺序；同一 baseURL+model 只算一个
+//   2) 前一个失败才换下一个；用户取消（Abort）和 isFatal 判定的失败不换
+//   3) 全都失败时错误里要能看到每个模型各自的报错，而不是只剩最后一条
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  MAX_FALLBACK_MODELS,
+  buildModelFallbackChain,
+  isAbortLikeError,
+  modelLabel,
+  runWithModelFallback,
+} from './aiModelFallback.js'
+
+const A = { id: 'a', name: '模型 A', model: 'a-model', baseURL: 'https://a.test/v1', apiKey: 'k' }
+const B = { id: 'b', name: '模型 B', model: 'b-model', baseURL: 'https://b.test/v1', apiKey: 'k' }
+const C = { id: 'c', name: '模型 C', model: 'c-model', baseURL: 'https://c.test/v1', apiKey: 'k' }
+const D = { id: 'd', name: '模型 D', model: 'd-model', baseURL: 'https://d.test/v1', apiKey: 'k' }
+const DEFAULT = { ...B, isDefault: true }
+
+test('buildModelFallbackChain: 默认模型排第一，其余按配置顺序', () => {
+  const chain = buildModelFallbackChain([A, DEFAULT, C])
+  assert.deepEqual(chain.map(m => m.id), ['b', 'a', 'c'])
+})
+
+test('buildModelFallbackChain: 没有默认模型时保持原顺序', () => {
+  const chain = buildModelFallbackChain([A, B])
+  assert.deepEqual(chain.map(m => m.id), ['a', 'b'])
+})
+
+test('buildModelFallbackChain: defaultFirst=false 时不重排（用户显式指定打头）', () => {
+  const chain = buildModelFallbackChain([A, DEFAULT], { defaultFirst: false })
+  assert.deepEqual(chain.map(m => m.id), ['a', 'b'])
+})
+
+test('buildModelFallbackChain: 同一端点+模型只保留一条，缺字段的条目被丢掉', () => {
+  const dup = { id: 'a2', name: 'A 重复', model: 'a-model', baseURL: 'https://a.test/v1/' }
+  const noKey = { id: 'x', model: 'x-model' }
+  const noModel = { id: 'y', baseURL: 'https://y.test/v1' }
+  const chain = buildModelFallbackChain([A, dup, noKey, noModel, B])
+  assert.deepEqual(chain.map(m => m.id), ['a', 'b'])
+})
+
+test(`buildModelFallbackChain: 默认最多 ${MAX_FALLBACK_MODELS} 个候选`, () => {
+  const chain = buildModelFallbackChain([A, B, C, D])
+  assert.equal(chain.length, MAX_FALLBACK_MODELS)
+  // limit<=0 表示不限
+  assert.equal(buildModelFallbackChain([A, B, C, D], { limit: 0 }).length, 4)
+})
+
+test('runWithModelFallback: 第一个就成功时不调用后面的，也不触发 onFallback', async () => {
+  const calls = []
+  const fallbacks = []
+  const { result, model } = await runWithModelFallback(
+    [A, B],
+    async (m) => { calls.push(m.id); return `ok-${m.id}` },
+    { onFallback: (info) => fallbacks.push(info) }
+  )
+  assert.equal(result, 'ok-a')
+  assert.equal(model.id, 'a')
+  assert.deepEqual(calls, ['a'])
+  assert.deepEqual(fallbacks, [])
+})
+
+test('runWithModelFallback: 默认模型失败后换下一个，并把失败原因传出去', async () => {
+  const calls = []
+  const fallbacks = []
+  const { result, model } = await runWithModelFallback(
+    [A, B],
+    async (m) => {
+      calls.push(m.id)
+      if (m.id === 'a') throw new Error('HTTP 429 额度不足')
+      return `ok-${m.id}`
+    },
+    { onFallback: (info) => fallbacks.push(info) }
+  )
+  assert.equal(result, 'ok-b')
+  assert.equal(model.id, 'b')
+  assert.deepEqual(calls, ['a', 'b'])
+  assert.equal(fallbacks.length, 1)
+  assert.equal(fallbacks[0].from.id, 'a')
+  assert.equal(fallbacks[0].to.id, 'b')
+  assert.match(fallbacks[0].error.message, /429/)
+})
+
+test('runWithModelFallback: 全都失败时错误里带上每个模型的报错', async () => {
+  await assert.rejects(
+    () => runWithModelFallback(
+      [A, B],
+      async (m) => { throw new Error(`${m.id} 挂了`) }
+    ),
+    (err) => {
+      assert.match(err.message, /模型 A/)
+      assert.match(err.message, /模型 B/)
+      assert.match(err.message, /a 挂了/)
+      assert.match(err.message, /b 挂了/)
+      assert.equal(err.attempts.length, 2)
+      return true
+    }
+  )
+})
+
+test('runWithModelFallback: 只试了一个模型时原样抛（保持各调用点原有文案）', async () => {
+  const boom = new Error('HTTP 401')
+  await assert.rejects(
+    () => runWithModelFallback([A], async () => { throw boom }),
+    (err) => err === boom
+  )
+})
+
+test('runWithModelFallback: 用户取消不换模型', async () => {
+  const abort = new Error('aborted')
+  abort.name = 'AbortError'
+  const calls = []
+  await assert.rejects(
+    () => runWithModelFallback(
+      [A, B],
+      async (m) => { calls.push(m.id); throw abort }
+    ),
+    (err) => err === abort
+  )
+  assert.deepEqual(calls, ['a'], 'Abort 之后不该再用下一个模型续上')
+})
+
+test('runWithModelFallback: isFatal 返回 true 时立刻收手', async () => {
+  const calls = []
+  await assert.rejects(
+    () => runWithModelFallback(
+      [A, B],
+      async (m) => { calls.push(m.id); throw new Error('stream 中途断了') },
+      { isFatal: () => true }
+    ),
+    /stream 中途断了/
+  )
+  assert.deepEqual(calls, ['a'])
+})
+
+test('runWithModelFallback: 空候选链抛「未配置 AI 模型」', async () => {
+  await assert.rejects(() => runWithModelFallback([], async () => 'x'), /未配置 AI 模型/)
+})
+
+test('isAbortLikeError / modelLabel 的基本口径', () => {
+  assert.equal(isAbortLikeError({ name: 'AbortError' }), true)
+  assert.equal(isAbortLikeError({ code: 'ERR_CANCELED' }), true)
+  assert.equal(isAbortLikeError(new Error('HTTP 500')), false)
+  assert.equal(modelLabel({ name: '自动分类', model: 'x' }), '自动分类')
+  assert.equal(modelLabel({ model: 'x' }), 'x')
+  assert.equal(modelLabel({}), '未命名模型')
+})