MailUI4Agents/plugins/dsh-mail-bridge/lib/model-scope.js

/**
 * 平台模型目录的整理与降级选择 —— 所有平台插件共用。
 *
 * 两个职责：
 *   1. 把各平台的 provider/model 结构整理成统一的上报格式（随心跳发给 Gateway）
 *   2. 按管理员划定的范围决定「先试哪个、再试哪个」
 *
 * 为什么随心跳上报而不是只在注册时报一次：模型清单会在运行中变（换 provider
 * 配置、上游上下线、换 API key）。只在注册时报的话目录会静静变陈，而管理员
 * 在配置页上看到的是上次重启时的快照 —— 选中一个平台已经调不到的模型，
 * 失败要到真发邮件时才暴露。
 */

/** 单次上报的模型数上限。与服务端的 maxCatalogModels 一致。 */
export const MAX_CATALOG = 300;

/**
 * 把 opencode 的 `/config/providers` 响应整理成上报格式。
 *
 * @param {any} config `client.config.providers()` 的结果
 * @returns {object[]} `[{ provider, model, display_name }]`
 */
export function snapshotOpencodeModels(config) {
  const providers = Array.isArray(config?.providers) ? config.providers : [];
  const out = [];
  for (const p of providers) {
    const provider = typeof p?.id === 'string' ? p.id : '';
    if (!provider) continue;
    // models 是对象而非数组：键是 model id，值是元数据
    const models = p?.models && typeof p.models === 'object' ? p.models : {};
    for (const [id, meta] of Object.entries(models)) {
      if (!id) continue;
      out.push({
        provider,
        model: id,
        display_name: typeof meta?.name === 'string' ? meta.name : '',
      });
    }
  }
  return dedupeAndCap(out);
}

/**
 * 把 DSH 的 provider/model 列表整理成上报格式。
 *
 * DSH 侧要先 `ctx.llm.listProviders()` 再对每个 provider `listModels()`，
 * 因此这里收的是已经拍平的结果。
 *
 * @param {any[]} entries `[{ provider, id, name }]`
 * @returns {object[]}
 */
export function snapshotDshModels(entries) {
  const list = Array.isArray(entries) ? entries : [];
  const out = [];
  for (const m of list) {
    const provider = typeof m?.provider === 'string' ? m.provider : '';
    const model = typeof m?.id === 'string' ? m.id : '';
    if (!provider || !model) continue;
    out.push({
      provider,
      model,
      display_name: typeof m?.name === 'string' ? m.name : '',
    });
  }
  return dedupeAndCap(out);
}

/**
 * 把 pi 的模型列表整理成上报格式。
 *
 * pi 侧的取法是 `await modelRuntime.getAvailable()` —— **不是** `getModels()`。
 * 两者差别很大：本机实测目录里有 1221 个模型，而带凭证、真能调起来的只有 1 个。
 * 上报 `getModels()` 的结果会让管理员在配置页选中一个注定失败的路由，
 * 而失败要到真发邮件时才暴露（模型目录上报的全部意义就是避免这件事）。
 *
 * pi 的 Model 对象上，provider 在 `provider` 字段、模型 id 在 `id` 字段，
 * 展示名在 `name`。形状与 DSH 侧一致，但语义来源不同，因此单独一个函数
 * ——照抄 snapshotDshModels 会让「必须用 getAvailable」这条约束无处记录。
 *
 * @param {any[]} models `await modelRuntime.getAvailable()` 的结果
 * @returns {object[]}
 */
export function snapshotPiModels(models) {
  const list = Array.isArray(models) ? models : [];
  const out = [];
  for (const m of list) {
    const provider = typeof m?.provider === 'string' ? m.provider : '';
    const model = typeof m?.id === 'string' ? m.id : '';
    if (!provider || !model) continue;
    out.push({
      provider,
      model,
      display_name: typeof m?.name === 'string' ? m.name : '',
    });
  }
  return dedupeAndCap(out);
}

/**
 * 决定这一轮按什么顺序尝试模型。
 *
 * 三种情形：
 *
 * 1. **管理员划定了范围** → 按 rank 顺序（服务端已排好），逐个降级
 * 2. **没划定范围**（`allowed` 为空）→ 返回 `[undefined]`，
 *    表示「用平台自己的默认模型试一次」。**不是**空数组：
 *    空数组会让调用方一次都不试，等于让 Agent 彻底哑掉，
 *    而「管理员没配」的正确含义是不限定。
 * 3. **插件配了 `AGENTMAIL_REPLY_PROVIDER`/`MODEL`** → 那是部署方的显式指定，
 *    优先于「平台默认」，但**不优先于管理员划定的范围**：
 *    范围是运行时可改的策略，环境变量是部署时的兜底。
 *
 * @param {readonly {provider: string, model: string}[]} allowed 管理员划定的范围（按 rank）
 * @param {{provider?: string, model?: string}|undefined} envDefault 环境变量指定的模型
 * @returns {(({provider: string, model: string})|undefined)[]} 依次尝试的候选；
 *          `undefined` 表示这一次不指定模型、交给平台
 */
export function modelAttemptOrder(allowed, envDefault) {
  const list = Array.isArray(allowed) ? allowed.filter(m => m?.provider && m?.model) : [];
  if (list.length > 0) return list.map(m => ({ provider: m.provider, model: m.model }));
  if (envDefault?.provider && envDefault?.model) {
    return [{ provider: envDefault.provider, model: envDefault.model }];
  }
  return [undefined];
}

/**
 * 把「目录里根本没有的路由」从尝试序列里剔掉。
 *
 * # 为什么需要它（2026-09-28 实测）
 *
 * 线上 opencode 的允许清单 rank=0 是 `opencode/mimo-v2.5-free`，而**上游已改名**
 * 为 `mimo-v2.6-flash-free`。于是每一封邮件的第一轮尝试都是：
 *
 *     [mail-bridge] 模型 opencode/mimo-v2.5-free 失败:
 *       Model not found. Did you mean: mimo-v2.6-flash-free, ...?
 *     [mail-bridge] llmsproxy/AUTO 成功（前 1 个失败）
 *
 * 降级逻辑救了它（信还是回了），但代价是**每轮白烧一次 + 延迟翻倍 + 一条永久错误日志**。
 *
 * # 为什么 pi 桥早就有、这里没有
 *
 * `pi-mail-bridge/src/worker.mjs` 里同一件事已经做了，注释写着
 * 「目录里根本没有这个路由：**同步就能判定，不必起一轮**」。
 * 本函数就是把那条纪律搬到共用层，让 opencode/dsh/zcode 也拿到。
 *
 * ★ 关键：**剔不掉时必须原样保留**。
 *   拿不到目录（心跳还没跑过 / 拉取失败）时返回**全部路由** ——
 *   宁可真去试一次（失败会走既有的降级与故障报告），
 *   也不能因为「我们不知道」就让人收不到回信。
 *   这是与 `reportModels` 拉取失败时**省略字段而不是传空数组**同一个方向。
 *
 * @param {readonly ({provider: string, model: string}|undefined)[]} order 尝试序列
 * @param {readonly {provider: string, model: string}[]|undefined} catalog 最近一次上报的模型目录
 * @returns {{kept: ({provider: string, model: string}|undefined)[], skipped: {provider: string, model: string, reason: string}[]}}
 */
export function partitionByCatalog(order, catalog) {
  const seq = Array.isArray(order) ? order : [];
  const cat = Array.isArray(catalog) ? catalog.filter(m => m?.provider && m?.model) : [];

  // ★ 拿不到目录 = 不做任何判断，把全部放行。
  //   「我不知道」与「它不存在」必须分得开，否则一次心跳失败就会让 Agent 彻底哑掉。
  if (cat.length === 0) {
    return { kept: seq, skipped: [] };
  }

  const have = new Set(cat.map(m => `${m.provider}/${m.model}`));
  const kept = [];
  const skipped = [];
  for (const r of seq) {
    // undefined = 不指定模型、交给平台自己选 —— 它不经过目录，不归我们管。
    if (!r) { kept.push(r); continue; }
    if (have.has(`${r.provider}/${r.model}`)) {
      kept.push(r);
    } else {
      skipped.push({
        provider: r.provider,
        model: r.model,
        reason: `平台目录里没有 ${r.provider}/${r.model}（上游可能已改名或下线）`,
      });
    }
  }
  return { kept, skipped };
}

/**
 * 把多次尝试的失败原因整理成一封邮件正文。
 *
 * 全部失败时必须发这封信：模型一次都没跑起来，会话里没有任何 assistant 消息，
 * 自动转发因此什么也不会发 —— 发件人只会看到邮件发出去后再无音讯。
 *
 * @param {{provider?: string, model?: string, error: string}[]} failures 每次尝试的失败
 * @param {string} subject 原邮件主题
 * @returns {string} Markdown 正文
 */
export function renderFailureReport(failures, subject) {
  const list = Array.isArray(failures) ? failures : [];
  const lines = [
    `本次未能处理「${subject || '(无主题)'}」：划定范围内的模型全部调用失败。`,
    '',
    `已尝试 ${list.length} 个：`,
    '',
  ];
  list.forEach((f, i) => {
    const route = f?.provider && f?.model ? `${f.provider}/${f.model}` : '(平台默认模型)';
    lines.push(`${i + 1}. **${route}**`);
    // 缩进四格让报错原文成为代码块，避免其中的 Markdown 字符影响排版
    lines.push(`    ${String(f?.error ?? '未知错误').replace(/\n/g, '\n    ')}`);
  });
  lines.push('');
  lines.push('可能的原因：模型已下线、API key 失效、上游限流，或该 provider 未在平台侧配置。');
  lines.push('调整可用模型范围：配置页 → Agent 模型范围。');
  return lines.join('\n');
}

/** 去重（provider/model 组合）并截断。 */
function dedupeAndCap(list) {
  const seen = new Set();
  const out = [];
  for (const m of list) {
    const key = `${m.provider}/${m.model}`;
    if (seen.has(key)) continue;
    seen.add(key);
    out.push(m);
    if (out.length >= MAX_CATALOG) break;
  }
  return out;
}