Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

11.5 KB
Raw Blame
/**
 * modelList —— 「从供应商目录派生模型清单」的**唯一标准入口**(纯逻辑,跨端共享)。
 *
 * 背景(2026-07 全仓盘点): 同一个「取某 agent 的模型清单」语义在 desktop/mobile/main 里被独立
 * 实现了 8+ 份(deriveAvailableModels / deriveModelsFromProviders / selectVisibleModels /
 * visibleModelUnion / buildProviderSections / selectWorkerModels / IM slashCommands / hook
 * session-runner),连接态过滤、可见性过滤、去重三条规则排列组合出 ≥4 种口径,直接导致
 * 「设置页看到的清单 ≠ 会话选择器 ≠ IM /model 卡」一类线上事故。
 *
 * 本模块把三条规则收成**显式 options**,所有派生统一走 `deriveModelList` /
 * `deriveModelSections`;既有共享函数(visibleModelUnion / buildProviderSections)改写为本模块
 * 的薄壳,签名与输出逐字节不变(有 parity 测试锁),消费方无感收口。
 *
 * 设计约束:
 *   - 纯函数、零依赖(包不变量),mobile 与 main 均可直接消费;
 *   - 不做隐式默认的「聪明行为」: 供应商范围/可见性/去重全部由调用方显式声明,
 *     每个旧口径都能被一组 options 精确表达(映射表见各薄壳注释)。
 */

import type { AgentKind, CatalogModel, ProviderAccess } from './types.js';
import {
  connectedProvidersForAgent,
  providersForAgent,
  type ProviderView,
} from './registry.js';
import {
  isAgentSelectableModel,
  isModelSelectableForNewRoute,
} from './classification.js';

/**
 * 标准派生的**内建准入过滤**(两条,先于 isVisible 判定):
 *   1. 非 agent 分组(image / audio / video / embedding / other)—— 网关多返回的能力
 *      模型,不能当 agent 用,**无条件**不进对话清单,keepSelected 豁免也不放行:
 *      豁免是给「运行中的会话别丢选中行」用的,而能力模型作为选中项只可能来自
 *      历史坑(旧 UI 把图像模型漏进了选择器)遗留的草稿/记忆,正是本过滤要修的
 *      对象,豁免它等于把坑重新打开(PR #744 review)。
 *   2. `m.disabled` —— 用户停用的模型(buildRegistry 按停用 override(disableOverrides)
 *      烘焙的视图层标志)。停用 = 不可被任何新路由选中,与「隐藏」(isVisible,仅陈列)
 *      不同;keepSelected 豁免**保留**(正在用它的会话不打断、选中行不消失)。
 *   3. `m.status === 'retired'` —— 远端 tombstone(registry 判死,active-catalog 合并期
 *      烘焙,含 discovery 回补的同名条目)。语义与停用同型:新选择禁止、keepSelected
 *      豁免;唯一复活通道是完整 local addition(见 model-plane/localCatalogOverrides)。
 * 本模块所有消费方(选择器 / IM / worker / hook 兜底)都是「可路由对话模型」语境,
 * 故直接内建,不做 opt-out。
 */

/**
 * 清单条目的来源溯源 —— flat(拍平去重)清单里「订阅」「立省85%」等来源徽章的**真实依据**。
 *
 * 历史问题: 拍平清单丢掉了 provider 上下文,`provider?.access?.kind === 'subscription'` 判定
 * 恒 false,订阅标签整个消失 —— 用户误以为订阅绑定失效(2026-07 实测)。派生时每一行的来源
 * 供应商是确定已知的(first-wins 首见者 / 分段模式的段供应商),附上即是溯源不是猜测。
 * 拿不到目录、只有拍平 capabilities 的场景(device-link 旧被控端)没有这份元数据 → 渲染层
 * 不显示来源徽章,诚实降级。
 */
export interface ModelSourceMeta {
  /** 该行来源供应商 id。 */
  sourceProviderId: string;
  /** 来源供应商的 access(订阅/API/托管);custom provider 可能缺省。 */
  sourceAccess?: ProviderAccess;
  /** 派生时该来源是否已连接(providerScope 非 connected 的清单才有区分意义)。 */
  sourceConnected: boolean;
}

/** 标准清单条目 = 目录条目全字段 + 来源溯源。对按 CatalogModel 形状消费的代码是协变加宽。 */
export interface ModelListEntry extends CatalogModel, ModelSourceMeta {}

/**
 * 供应商范围 —— 三种历史口径的显式化:
 *   - 'all-for-agent'(默认): 该 agent 兼容的全部供应商,不看连接(capabilities 快照口径);
 *   - 'connected-for-agent': 已连接且兼容该 agent(选择器 / IM /model 卡口径);
 *   - 'as-given': 完全按传入数组遍历、不做任何收窄 —— buildProviderSections 的历史语义
 *     (它假设调用方已自行收窄;薄壳必须保持,否则「调用方传了未收窄列表」时行为漂移)。
 */
export type ProviderScope = 'all-for-agent' | 'connected-for-agent' | 'as-given';

export interface DeriveModelListOptions {
  providers: readonly ProviderView[];
  agent: AgentKind;
  /** 供应商范围,默认 'all-for-agent'。 */
  providerScope?: ProviderScope;
  /**
   * 可见性过滤(用户「设置 → 模型供应商」的显隐 override);决策统一走 isModelVisible,
   * 数据源由调用方按自己进程能读到的存储注入。缺省 = 不过滤。
   */
  isVisible?: (providerId: string, model: CatalogModel) => boolean;
  /**
   * 'first-wins'(默认): 同 id 跨供应商去重,按供应商序 + 目录序首见胜出 —— 拍平单列清单;
   * 'none': 不去重,同 id 在每个提供它的供应商下各出一行 —— 分段清单。
   */
  dedupe?: 'first-wins' | 'none';
  /** 整供应商排除(如 SSH 远程排除 chat-bridged Codex 源);被排除者**不占** first-wins 的 seen。 */
  excludeProvider?: (provider: ProviderView) => boolean;
  /** 单模型排除(如 SSH 远程排除订阅直连前缀);被排除者同样不占 seen。 */
  excludeModel?: (model: CatalogModel, provider: ProviderView) => boolean;
  /**
   * 选中豁免: 该 (供应商, 模型) 即便被 isVisible 隐藏也保留 —— 避免「当前选中项不在列表」
   * 的空选态(分段选择器契约)。providerId 为 null 时按 model id 匹配任意供应商行。
   */
  keepSelected?: { providerId: string | null; modelId: string };
  /** UI-only catalog rows may include paid-locked models; execution callers must keep false. */
  includePaymentRequired?: boolean;
}

function resolveRail(
  providers: readonly ProviderView[],
  agent: AgentKind,
  scope: ProviderScope,
): readonly ProviderView[] {
  switch (scope) {
    case 'connected-for-agent':
      return connectedProvidersForAgent([...providers], agent);
    case 'as-given':
      return providers;
    default:
      return providersForAgent([...providers], agent);
  }
}

function matchesSelected(
  keep: DeriveModelListOptions['keepSelected'],
  providerId: string,
  modelId: string,
): boolean {
  if (!keep) return false;
  if (keep.modelId !== modelId) return false;
  return keep.providerId === null || keep.providerId === providerId;
}

/**
 * 标准清单派生。输出顺序契约与历史一致: 供应商按 rail 序(= catalog 序),
 * 供应商内模型按目录序,**绝不二次排序**(展示层的分组排序另走 groupModelsForDisplay)。
 */
export function deriveModelList(opts: DeriveModelListOptions): ModelListEntry[] {
  const {
    providers,
    agent,
    providerScope = 'all-for-agent',
    isVisible,
    dedupe = 'first-wins',
    excludeProvider,
    excludeModel,
    keepSelected,
    includePaymentRequired = false,
  } = opts;

  // first-wins 的占坑表直接记「id → 首见行在 out 里的下标」,选中行替换时 O(1) 定位
  // (findIndex 线性扫在大目录下会让派生退化 O(n²),Greptile review)。
  const seenIndex = new Map<string, number>();
  const out: ModelListEntry[] = [];
  for (const provider of resolveRail(providers, agent, providerScope)) {
    if (excludeProvider?.(provider)) continue;
    for (const m of provider.models[agent] ?? []) {
      if (excludeModel?.(m, provider)) continue;
      const selected = matchesSelected(keepSelected, provider.id, m.id);
      // entry 构造延后到确定要用时(push / 替换):被 first-wins 丢弃的重复行不做无谓 spread。
      const makeEntry = (): ModelListEntry => {
        const entry: ModelListEntry = {
          ...m,
          sourceProviderId: provider.id,
          sourceConnected: provider.connected,
        };
        if (provider.access !== undefined) entry.sourceAccess = provider.access;
        return entry;
      };
      const userProvider = provider.source === 'user';
      const selectable = selected || (includePaymentRequired && m.availability === 'requires_payment')
        ? isAgentSelectableModel(m, { userProvider })
        : isModelSelectableForNewRoute(m, { userProvider });
      if (!selectable) continue;
      if (dedupe === 'first-wins' && seenIndex.has(m.id)) {
        // 首见行已占坑。keepSelected 点名 provider 且选中行排在后面时,首见行必须让位——
        // 否则选中 (provider, model) 被去重丢弃,flat 列表带着错误来源/徽章(codex review):
        // 用选中行**原位替换**首见行(位置守首见槽,输出顺序契约不变;选中行豁免
        // isVisible,与 push 路径同规则)。普通重复行直接丢弃。
        if (selected) {
          const i = seenIndex.get(m.id)!;
          if (!matchesSelected(keepSelected, out[i].sourceProviderId, out[i].id)) {
            out[i] = makeEntry();
          }
        }
        continue;
      }
      if (!selected && isVisible && !isVisible(provider.id, m)) continue;
      if (dedupe === 'first-wins') seenIndex.set(m.id, out.length);
      out.push(makeEntry());
    }
  }
  return out;
}

/** 分段清单条目: 段供应商 + 该段下的标准条目(溯源即段供应商)。 */
export interface ModelListSection {
  provider: ProviderView;
  models: ModelListEntry[];
}

/**
 * 分段派生(dedupe:'none' 的分桶形状)。与 deriveModelList 同一套过滤规则,逐供应商独立出段
 * (不经「拍平再分桶」—— 保证与历史 buildProviderSections 在任意输入下同构,含病态的重复
 * provider id);`query` 命中 name / id(大小写不敏感)。只返回有 ≥1 个模型的段;段顺序 = rail 序。
 * sections.ts 的 buildProviderSections 是本函数的投影薄壳(SectionModel 字段裁剪)。
 */
export function deriveModelSections(
  opts: Omit<DeriveModelListOptions, 'dedupe'> & { query?: string },
): ModelListSection[] {
  const {
    providers,
    agent,
    providerScope = 'all-for-agent',
    isVisible,
    excludeProvider,
    excludeModel,
    keepSelected,
    includePaymentRequired = false,
  } = opts;
  const q = (opts.query ?? '').trim().toLowerCase();

  const sections: ModelListSection[] = [];
  for (const provider of resolveRail(providers, agent, providerScope)) {
    if (excludeProvider?.(provider)) continue;
    const models: ModelListEntry[] = [];
    for (const m of provider.models[agent] ?? []) {
      if (excludeModel?.(m, provider)) continue;
      const selected = matchesSelected(keepSelected, provider.id, m.id);
      const userProvider = provider.source === 'user';
      const selectable = selected || (includePaymentRequired && m.availability === 'requires_payment')
        ? isAgentSelectableModel(m, { userProvider })
        : isModelSelectableForNewRoute(m, { userProvider });
      if (!selectable) continue;
      if (!selected && isVisible && !isVisible(provider.id, m)) continue;
      if (q && !m.name.toLowerCase().includes(q) && !m.id.toLowerCase().includes(q)) continue;
      const entry: ModelListEntry = {
        ...m,
        sourceProviderId: provider.id,
        sourceConnected: provider.connected,
      };
      if (provider.access !== undefined) entry.sourceAccess = provider.access;
      models.push(entry);
    }
    if (models.length > 0) sections.push({ provider, models });
  }
  return sections;
}