zen-gitsync 2.18.26 → 2.19.1

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

@@ -31,6 +31,7 @@ import { normalizeAgentEngine, isExternalEngine, engineLabel } from './agentEngi
 import { saveAgentAttachments, MAX_ATTACHMENTS } from '../../utils/agentAttachments.js';
 import { registerAgentMarketplaceRoutes } from './agentMarketplace.js';
 import { createProjectListProvider } from './projectTool.js';
+import { askPeerByRef, listPeerStatus } from '../../../../peer/client.js';
 import { createDispatcher } from './dispatchInstruction.js';
 import { createWorkspaceSnapshotter } from '../aiContext/wiring.js';
 // 用户固定提示词（g ai 默认提示词 + 派发提示词）的解析 —— 两条引擎链路共用同一份
@@ -205,6 +206,12 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager,
   // 不给它加缓存:agent 一轮里最多问一两次,而"项目状态"本来就要现读才准。
   const listProjects = createProjectListProvider({ configManager, getCurrentProjectPath });
 
+  // ask_peer 的两半：对端清单（实时探活）与"问一句"。数据源是 <DATA_DIR>/peers.json，
+  // 与本机项目无关，所以直接复用 src/peer/ 的实现 —— 这里不做二次包装。
+  // 工具在 CLI（g ai）下没有 peers 上下文，见 tools.js 的 toolAskPeer 兜底说明。
+  const askPeer = askPeerByRef;
+  const listPeers = () => listPeerStatus({ probe: true });
+
   // 把目录登记进「常用目录」(config.json 的 recentDirectories)。register_project 工具
   // 与 run_command 里"建了仓库就顺手登记"那一步共用它 —— 智能体建/克隆完新项目,
   // 用户下次在「切换工作目录」弹窗里就能直接看到,不必重启 GUI 或自己翻路径。
@@ -812,6 +819,8 @@ export function registerAgentRoutes({ app, getCurrentProjectPath, configManager,
           dispatchTask,
           listProjects,
           registerProject,
+          askPeer,
+          listPeers,
           getContextBlock,
           // 每轮请求的上下文预算（解析结果）。agentChat 拿它调 prepareRequestMessages，
           // 与 CLI turn.js 同一条口径。

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/ui/server/utils/ensureHub.js

@@ -0,0 +1,101 @@
+// 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.
+//
+// 「开机就有 hub」：项目窗口起来时，发现这台机器上没有活着的 hub，就顺手拉一个。
+//
+// 为什么不要求用户手动先起 hub：拆成两个角色之后，工作台 / 项目管理 / 系统监控 /
+// 思维导图只存在于 hub 进程里。如果每次都得先记得「先开 hub 再开项目窗口」，
+// 这套拆分就是个负担而不是改进。
+//
+// 三段式（顺序很重要）：
+//   1. 查实例注册表 —— 有 role=hub 且心跳新鲜的，直接复用（不重复拉进程）；
+//   2. 没有才 spawn 一个 detached 的 `g ui --role=hub --port=<固定端口>`；
+//   3. 无论哪种结果都把「hub 在哪个端口」返回给调用方打日志。
+//
+// 为什么端口固定：它要长期被别的窗口/脚本按固定地址访问。hub 那边 maxTries=1，
+// 被占就直接失败 —— 所以两个窗口同时启动时，后起那个只是抢不到端口并退出，
+// 不会出现"hub 悄悄跑到 5601 而没人知道"。
+
+import { spawn } from 'node:child_process';
+import { openSync, closeSync, promises as fsPromises } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import os from 'node:os';
+
+import { createInstanceRegistry, getRegistryPath } from './instanceRegistry.js';
+import { DATA_DIR } from '../../../paths.js';
+
+/** hub 的默认固定端口。peer 默认用 5600（见 src/peer/store.js），两者不重叠。 */
+export const HUB_DEFAULT_PORT = 5599;
+
+/** 自动拉起的 hub 的日志（stdio 走 ignore 的话，端口冲突这类失败会彻底静默）。 */
+export const HUB_LOG_FILE = path.join(DATA_DIR, 'hub.log');
+
+/** 从模块位置定位 CLI 入口，不依赖调用方怎么被启动（g ui / node server.js / nodemon）。 */
+function resolveCliEntry() {
+  return fileURLToPath(new URL('../../../gitCommit.js', import.meta.url));
+}
+
+/**
+ * 确保本机有活着的 hub。
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.port] 期望的 hub 端口（默认 HUB_DEFAULT_PORT）
+ * @param {string} [opts.cwd]  hub 进程的工作目录（默认继承当前进程）
+ * @returns {Promise<{reused:boolean, port:number, pid:number|null}>}
+ */
+export async function ensureHubRunning({ port = HUB_DEFAULT_PORT, cwd } = {}) {
+  const registry = createInstanceRegistry({
+    fs: fsPromises,
+    path,
+    os,
+    registryPath: getRegistryPath()
+  });
+
+  // ① 已经有一个活着的 hub（心跳新鲜 + pid 存活由 list() 统一裁剪）
+  try {
+    const instances = await registry.list();
+    const live = instances.find((i) => i.role === 'hub');
+    if (live) return { reused: true, port: live.port, pid: live.pid };
+  } catch {
+    // 注册表读挂了不该挡住主流程，继续往下走去 spawn
+  }
+
+  // ② 拉一个新的
+  let fd = null;
+  try {
+    fd = openSync(HUB_LOG_FILE, 'a');
+  } catch {
+    // 日志都开不了就退化成 ignore —— hub 照起，只是失败信息看不到
+  }
+
+  // 浏览器要开：hub 是"另一扇窗"，只在**新拉起**时开一次（复用已有 hub 时不开 ——
+  // 否则每开一个项目窗口都多蹦一个标签页，而那个页面本来就在）。
+  // ZEN_NO_OPEN=1 可以关掉（CI / 无头环境）。
+  const args = [resolveCliEntry(), 'ui', '--role=hub', `--port=${port}`];
+  if (process.env.ZEN_NO_OPEN === '1') args.push('--no-open');
+
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    // 关键：不继承 stdout，否则父窗口退出时管道断开会把 hub 一起带走
+    stdio: fd === null ? 'ignore' : ['ignore', fd, fd],
+    cwd: cwd || process.cwd(),
+    windowsHide: true,
+    env: { ...process.env, ZEN_HUB_AUTOSTART: '1' }
+  });
+  child.unref();
+  if (fd !== null) { try { closeSync(fd); } catch {} }
+
+  return { reused: false, port, pid: child.pid ?? null };
+}

package/src/ui/server/utils/instanceRegistry.js

@@ -317,7 +317,7 @@ export function createInstanceRegistry({
   //
   // 关键点:register / heartbeat / unregister 都只读写 *自己* 的 entry 文件,
   // 跨进程并发时不同 PID 的写入互不干扰,从根本上消除 read-modify-write 覆盖。
-  async function register({ pid, port, projectPath, projectName, hostname } = {}) {
+  async function register({ pid, port, projectPath, projectName, hostname, role } = {}) {
     if (!Number.isInteger(pid) || pid <= 0) throw new Error('register: pid 必填');
     if (!Number.isInteger(port) || port <= 0) throw new Error('register: port 必填');
     if (!projectPath) throw new Error('register: projectPath 必填');
@@ -333,7 +333,10 @@ export function createInstanceRegistry({
       projectPath,
       startedAt: Date.now(),
       lastHeartbeat: Date.now(),
-      hostname: hostname || osMod.hostname()
+      hostname: hostname || osMod.hostname(),
+      // 运行角色（project | hub | full）。用来回答"这台机器上有没有活着的 hub"——
+      // 没有就由新起的项目窗口拉一个（见 utils/ensureHub.js）。
+      role: role === 'hub' ? 'hub' : (role === 'full' ? 'full' : 'project')
     };
 
     await enqueueWrite(async () => {
@@ -383,7 +386,8 @@ export function createInstanceRegistry({
           projectPath: updates.projectPath,
           startedAt: Date.now(),
           lastHeartbeat: Date.now(),
-          hostname: updates.hostname || osMod.hostname()
+          hostname: updates.hostname || osMod.hostname(),
+          role: updates.role === 'hub' ? 'hub' : (updates.role === 'full' ? 'full' : 'project')
         };
         logger.info(
           `[instanceRegistry] 心跳检测到本实例条目丢失，已自愈重建 pid=${pid} port=${updates.port}`
@@ -394,6 +398,7 @@ export function createInstanceRegistry({
           ...(updates.projectPath ? { projectPath: updates.projectPath } : {}),
           ...(updates.projectName ? { projectName: updates.projectName } : {}),
           ...(Number.isInteger(updates.port) && updates.port > 0 ? { port: updates.port } : {}),
+          ...(updates.role ? { role: updates.role } : {}),
           lastHeartbeat: Date.now()
         };
       }

package/src/ui/server/utils/peerRuntime.js

@@ -0,0 +1,77 @@
+// 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.
+//
+// peer 监听的生命周期（进程内单例）。
+//
+// 为什么要有这一层：设置面板上「允许其他机器提问」是个开关，如果它只在启动时读一次，
+// 用户改完还得重启 g ui —— 那这个开关就等于摆设。这里把"读配置 → 起/停监听"收成
+// 一个函数，启动时调一次，开关一改再调一次，行为完全一致。
+//
+// 单例的必要性：同一进程只能绑同一个端口。重复 apply 必须先停旧的再起新的，
+// 否则改端口会留下一个"还在旧端口上回答"的幽灵实例。
+
+import { startPeerServer } from '../../../peer/server.js';
+import logger from './logger.js';
+
+/** @type {import('node:http').Server|null} */
+let handle = null;
+/** 本机 g ui 的端口（peer 服务端收到提问后要环回调用它）。 */
+let localPort = 0;
+
+/** g ui 真正就绪后由 index.js 注入。 */
+export function setPeerLocalPort(port) {
+  localPort = Number(port) || 0;
+}
+
+/** 当前是否在监听。 */
+export function isPeerRunning() {
+  return !!handle;
+}
+
+/** 停掉监听（幂等）。 */
+export async function stopPeerRuntime() {
+  if (!handle) return;
+  const h = handle;
+  handle = null;
+  await new Promise((resolve) => {
+    try {
+      h.close(() => resolve());
+    } catch {
+      resolve();
+    }
+  });
+}
+
+/**
+ * 按当前身份配置应用 peer 监听：enabled=true 就起，false 就停。
+ *
+ * @param {object} self peers.json 里的 self
+ * @param {{getVersion?: () => string}} [opts]
+ * @returns {Promise<{running:boolean, port:number|null}>}
+ */
+export async function applyPeerRuntime(self, { getVersion } = {}) {
+  await stopPeerRuntime();
+  if (!self?.enabled || !self.token) return { running: false, port: null };
+  if (!localPort) {
+    logger.warn('[peer] 本机端口未知，暂时无法开启（主服务还没 listening）');
+    return { running: false, port: null };
+  }
+
+  handle = await startPeerServer({
+    self,
+    getLocalPort: () => localPort,
+    getVersion
+  });
+  return { running: true, port: self.port };
+}

package/src/ui/server/utils/startServerOnAvailablePort.js

@@ -252,6 +252,12 @@ export async function startServerOnAvailablePort({
     }
   }
 
+  // 固定端口模式（maxTries=1）：把"被谁占 / 为什么不让绑"说清楚，别让用户去猜
+  if (maxTries <= 1) {
+    logger.error(`固定端口 ${startPort} 不可用（${lastErrorCode || '未知原因'}）。固定端口模式不会顺延。`);
+    logger.error('处理办法：换一个 --port，或先关掉占用该端口的进程（netstat -ano | findstr :' + startPort + '）。');
+    process.exit(1);
+  }
   logger.error(`无法找到可用端口 (尝试范围: ${startPort}-${maxPort - 1})`);
   if (process.platform === 'win32' && getExcludedPortRanges().length) {
     logger.error(

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,
+};