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。

38.2 KB
Raw Blame
/**
 * 目录运行时校验(parseCatalog)+ presets 清洗排序。
 *
 * 2026-07-19 起 bundled 目录由 `builtin.ts` 组装:内置供应商身份卡是 TS 常量,
 * `catalog/providers.json`(v2)承载 xAI 的离线 fallback 元数据 + presets 模板,是随包
 * 目录与 dev 直读的仓库文件。旧 OSS `cfg/providers.json` 自 2026-07 起冻结、不再由本文件
 * 发布;本文件的预设是源格式(顶层单一推荐清单),旧客户端读不懂,不能直接发布到 OSS。anthropic/openai/xd
 * 的模型清单运行时动态注入(见 apps/desktop maker-host active-catalog),不再进目录文件。
 * xAI 登录后同样由账号 `/v1/models` 决定成员;此处静态段只在尚无成功账号快照时救急,
 * 并为已发现成员补上下文、价格、能力与路由。
 * 所有跨端模型元数据统一进入严格版本化的 `modelRegistry`;目录顶层不接受旁路元数据块。
 */

import { expandPresetModels } from './presetModels.js';
import { projectProviderMediaModels } from './providerMediaModels.js';
import { mimoPresetName } from './mimoPresentation.js';
import { validModelMetadata } from './modelMetadataLayers.js';
import { parseModelRegistry } from './modelAccessValidator.js';

import { PI_MODEL_APIS, PI_REASONING_EFFORTS } from './types.js';
import type {
  Catalog,
  Provider,
  CatalogModel,
  AgentKind,
  Effort,
  ProviderPreset,
  PresetSortRegion,
  ProviderModelRouteConfig,
} from './types.js';
import { withVerifiedStaticWindows } from './builtin.js';
import { findReservedOAuthExtraParam } from './provider-oauth.js';
import { isProviderRequestPath } from './provider-url.js';

export { BUNDLED_CATALOG, BUILTIN_PROVIDERS, claudeSubscriptionOnlyForClaudeCode } from './builtin.js';

const AGENT_KINDS: readonly AgentKind[] = ['claude-code', 'codex', 'pi'];
const EFFORTS: readonly Effort[] = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
const WIRE_PROTOCOLS = ['anthropic-messages', 'openai-responses', 'openai-chat', 'google-generative-ai'] as const;

function isWireProtocol(value: unknown): value is (typeof WIRE_PROTOCOLS)[number] {
  return typeof value === 'string' && (WIRE_PROTOCOLS as readonly string[]).includes(value);
}

function isWireProtocolAllowedForAgent(
  _agent: AgentKind,
  value: unknown,
): value is (typeof WIRE_PROTOCOLS)[number] {
  return isWireProtocol(value);
}

function isValidModelRoute(
  agent: AgentKind,
  runtimeBaseUrl: unknown,
  value: unknown,
): value is ProviderModelRouteConfig {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
  const route = value as Record<string, unknown>;
  if (
    typeof route.baseUrl !== 'string' ||
    route.baseUrl.trim().length === 0 ||
    !isWireProtocolAllowedForAgent(agent, route.wireProtocol)
  ) return false;
  try {
    const runtimeUrl = new URL(String(runtimeBaseUrl));
    const routeUrl = new URL(route.baseUrl);
    if (
      (runtimeUrl.protocol !== 'http:' && runtimeUrl.protocol !== 'https:') ||
      (routeUrl.protocol !== 'http:' && routeUrl.protocol !== 'https:') ||
      runtimeUrl.username ||
      runtimeUrl.password ||
      routeUrl.username ||
      routeUrl.password ||
      routeUrl.origin !== runtimeUrl.origin
    ) return false;
  } catch {
    return false;
  }
  return route.requestPath === undefined || isProviderRequestPath(route.requestPath);
}

function isAgentKind(v: unknown): v is AgentKind {
  return typeof v === 'string' && (AGENT_KINDS as readonly string[]).includes(v);
}

function isEffort(v: unknown): v is Effort {
  return typeof v === 'string' && (EFFORTS as readonly string[]).includes(v);
}

function isPiModelApi(v: unknown): boolean {
  return typeof v === 'string' && (PI_MODEL_APIS as readonly string[]).includes(v);
}

function hasValidPresetReasoningCapability(
  agent: AgentKind,
  model: Record<string, unknown>,
): boolean {
  const hasCapability =
    model.reasoning !== undefined
    || model.reasoningEfforts !== undefined
    || model.reasoningDefaultEffort !== undefined;
  if (!hasCapability) return true;
  if (agent !== 'pi' || typeof model.reasoning !== 'boolean') return false;
  if (model.reasoning !== true) {
    return model.reasoningEfforts === undefined && model.reasoningDefaultEffort === undefined;
  }
  if (!Array.isArray(model.reasoningEfforts) || model.reasoningEfforts.length === 0) return false;
  const efforts = model.reasoningEfforts;
  const effortsValid = (
    efforts.every(
      (effort) =>
        typeof effort === 'string' && (PI_REASONING_EFFORTS as readonly string[]).includes(effort),
    ) && new Set(efforts).size === efforts.length
  );
  if (!effortsValid) return false;
  return (
    model.reasoningDefaultEffort === undefined
    || (
      typeof model.reasoningDefaultEffort === 'string'
      && efforts.includes(model.reasoningDefaultEffort)
    )
  );
}

function assert(cond: unknown, msg: string): asserts cond {
  if (!cond) throw new Error(`[model-providers] invalid catalog: ${msg}`);
}

/** access 是产品展示契约:旧目录可缺省,提供了就必须是完整的判别联合。 */
function validateAccess(p: Provider): void {
  const access = p.access;
  if (access === undefined) return;
  assert(access && typeof access === 'object' && !Array.isArray(access), `provider '${p.id}' access must be an object`);
  assert(
    access.kind === 'subscription' || access.kind === 'api' || access.kind === 'managed',
    `provider '${p.id}' access.kind invalid`,
  );
  if (access.kind === 'subscription') {
    assert(
      typeof access.product === 'string' && access.product.trim().length > 0,
      `provider '${p.id}' subscription access.product missing`,
    );
  }
}

/** 轻量校验一个 model 条目的必需字段。 */
function validateModel(
  m: CatalogModel,
  providerId: string,
  agent: AgentKind,
  runtimeBaseUrl: unknown,
): void {
  assert(typeof m.id === 'string' && m.id.length > 0, `model.id missing in provider '${providerId}'`);
  assert(typeof m.name === 'string' && m.name.length > 0, `model.name missing for '${m.id}'`);
  if (m.nativeApi !== undefined && m.nativeApi !== null) {
    assert(isPiModelApi(m.nativeApi) || validModelMetadata({ nativeApi: m.nativeApi }), `model.nativeApi invalid for '${m.id}'`);
  }
  if (m.api !== undefined) {
    assert(isPiModelApi(m.api), `model.api invalid for '${m.id}'`);
  }
  if (m.fastModelId !== undefined && m.fastModelId !== null) {
    assert(typeof m.fastModelId === 'string' && m.fastModelId.trim().length > 0 && m.fastModelId !== m.id,
      `model.fastModelId invalid for '${m.id}'`);
  }
  if (m.piApi !== undefined) {
    assert(isPiModelApi(m.piApi), `model.piApi invalid for '${m.id}'`);
  }
  if (m.route !== undefined) {
    assert(
      isValidModelRoute(agent, runtimeBaseUrl, m.route),
      `model.route invalid for '${m.id}' in provider '${providerId}'`,
    );
  }
  assert(typeof m.contextWindow === 'number' && m.contextWindow > 0, `model.contextWindow invalid for '${m.id}'`);
  assert(Array.isArray(m.efforts), `model.efforts must be array for '${m.id}'`);
  assert(m.efforts.every(isEffort), `model.efforts has invalid value for '${m.id}'`);
  if (m.defaultEffort !== null) {
    assert(isEffort(m.defaultEffort), `model.defaultEffort invalid for '${m.id}'`);
    assert(m.efforts.includes(m.defaultEffort), `model.defaultEffort not listed in efforts for '${m.id}'`);
  }
  // icon 是可选展示字段:只校验形态,不校验取值(未知值由渲染层回落来源供应商标,
  // 见 sections.ts resolveModelIconKind)——网关先于客户端登记新图标时不至于 parse 失败。
  if (m.icon !== undefined) {
    assert(typeof m.icon === 'string' && m.icon.trim().length > 0, `model.icon must be a non-empty string for '${m.id}'`);
  }
}

/** 校验 oauth 描述符(提供了就必须完整——它驱动登录与路由,坏数据必须在 parse 期暴露)。 */
function validateOAuthDescriptor(p: Provider): void {
  const d = p.auth?.oauth;
  if (d === undefined) return;
  assert(d && typeof d === 'object' && !Array.isArray(d), `provider '${p.id}' auth.oauth must be an object`);
  const raw = d as unknown as Record<string, unknown>;
  const flow = raw.flow ?? 'authorization-code';
  assert(
    flow === 'authorization-code' || flow === 'device-code',
    `provider '${p.id}' auth.oauth.flow invalid`,
  );
  for (const field of ['tokenUrl', 'clientId', 'scopes'] as const) {
    assert(typeof raw[field] === 'string' && (field === 'scopes' || raw[field].length > 0), `provider '${p.id}' auth.oauth.${field} missing`);
  }
  const requireHttpsUrl = (field: string): void => {
    const value = raw[field];
    let valid = false;
    if (typeof value === 'string') {
      try {
        const url = new URL(value);
        valid = url.protocol === 'https:' && !url.username && !url.password;
      } catch {
        valid = false;
      }
    }
    assert(valid, `provider '${p.id}' auth.oauth.${field} must be https`);
  };
  requireHttpsUrl('tokenUrl');
  if (flow === 'authorization-code') {
    requireHttpsUrl('authorizeUrl');
    assert(
      raw.deviceAuthorizationUrl === undefined && raw.extraDeviceParams === undefined,
      `provider '${p.id}' auth.oauth device-code fields not allowed for authorization-code`,
    );
  } else {
    requireHttpsUrl('deviceAuthorizationUrl');
    assert(
      raw.authorizeUrl === undefined
        && raw.extraAuthParams === undefined
        && raw.redirectPort === undefined,
      `provider '${p.id}' auth.oauth authorization-code fields not allowed for device-code`,
    );
  }
  if (raw.redirectPort !== undefined) {
    assert(
      flow === 'authorization-code'
        && typeof raw.redirectPort === 'number'
        && Number.isInteger(raw.redirectPort)
        && raw.redirectPort > 0
        && raw.redirectPort < 65536,
      `provider '${p.id}' auth.oauth.redirectPort invalid`,
    );
  }
  const validateParams = (field: 'extraAuthParams' | 'extraDeviceParams'): void => {
    if (raw[field] === undefined) return;
    assert(
      raw[field] && typeof raw[field] === 'object' && !Array.isArray(raw[field]),
      `provider '${p.id}' auth.oauth.${field} invalid`,
    );
    assert(
      Object.values(raw[field] as Record<string, unknown>).every((value) => typeof value === 'string'),
      `provider '${p.id}' auth.oauth.${field} invalid`,
    );
    const collision = findReservedOAuthExtraParam(
      raw[field] as Record<string, unknown>,
      flow,
    );
    assert(
      collision === null,
      `provider '${p.id}' auth.oauth.${field} cannot override '${String(collision)}'`,
    );
  };
  if (flow === 'authorization-code') validateParams('extraAuthParams');
  else validateParams('extraDeviceParams');
  if (raw.modelsDiscoveryUrl !== undefined) {
    let valid = false;
    if (typeof raw.modelsDiscoveryUrl === 'string') {
      try {
        const url = new URL(raw.modelsDiscoveryUrl);
        valid = url.protocol === 'https:' && !url.username && !url.password;
      } catch {
        valid = false;
      }
    }
    assert(
      valid,
      `provider '${p.id}' auth.oauth.modelsDiscoveryUrl must be https`,
    );
  }
}

/** 轻量校验一个 provider。 */
function validateProvider(p: Provider, allowEmptyModalities = false): void {
  assert(typeof p.id === 'string' && p.id.length > 0, 'provider.id missing');
  // id 会被 host 直接拼进 safeStorage 键名/文件名(provider_oauth_<id> 等),
  // 必须限定 slug 字符集,防被投毒目录用 `../` 之类字符把凭证写出存储目录。
  assert(/^[a-zA-Z0-9_-]+$/.test(p.id), `provider.id has illegal characters: '${p.id}'`);
  assert(typeof p.name === 'string' && p.name.length > 0, `provider.name missing for '${p.id}'`);
  assert(
    p.auth
      && (
        p.auth.method === 'oauth'
        || p.auth.method === 'apiKey'
        || p.auth.method === 'managed'
        || p.auth.method === 'none'
    ),
    `provider.auth.method invalid for '${p.id}'`,
  );
  assert(
    p.auth.method === 'oauth' || p.auth.oauth === undefined,
    `provider '${p.id}' auth.oauth not allowed for ${p.auth.method} method`,
  );
  // agents 允许为空**当且仅当**声明了媒体清单(媒体-only 供应商,如 Gemini 图像
  // API key 来源,2026-07 图像多来源):图像/视频模型不经 agent runtime,由主机
  // 图像通道直调,不需要任何 agent 路由;没有媒体清单的空 agents 仍是无效数据。
  const hasMediaModels =
    (Array.isArray(p.imageModels) && p.imageModels.length > 0) ||
    (Array.isArray(p.videoModels) && p.videoModels.length > 0) ||
    (Array.isArray(p.audioModels) && p.audioModels.length > 0) ||
    (Array.isArray(p.embeddingModels) && p.embeddingModels.length > 0);
  assert(
    Array.isArray(p.agents) && (p.agents.length > 0 || hasMediaModels),
    `provider.agents missing for '${p.id}'`,
  );
  assert(p.agents.every(isAgentKind), `provider.agents has invalid kind for '${p.id}'`);
  assert(p.routing && typeof p.routing === 'object', `provider.routing missing for '${p.id}'`);
  assert(
    p.models !== null && typeof p.models === 'object' && !Array.isArray(p.models),
    `provider.models must be a per-agent map for '${p.id}'`,
  );
  // 约束:供应商声明支持的每个 agent,都必须有对应路由描述符 + per-agent 模型数组。
  for (const agent of p.agents) {
    const routing = p.routing[agent];
    assert(routing, `provider '${p.id}' declares agent '${agent}' but no routing[${agent}]`);
    if (routing.upstream !== undefined) {
      let valid = false;
      try {
        const url = new URL(routing.upstream);
        valid = (
          (url.protocol === 'http:' || url.protocol === 'https:')
          && !url.username
          && !url.password
        );
      } catch {
        valid = false;
      }
      assert(valid, `provider '${p.id}' routing[${agent}].upstream invalid`);
    }
    if (routing.wireProtocol !== undefined) {
      assert(
        isWireProtocol(routing.wireProtocol),
        `provider '${p.id}' routing[${agent}].wireProtocol invalid`,
      );
      if (agent === 'claude-code') {
        assert(
          routing.wireProtocol !== 'openai-chat',
          `provider '${p.id}' routing[${agent}] cannot use openai-chat`,
        );
      }
      // Codex supports native Responses, Responses→Chat and Responses→Anthropic local
      // bridges. The latter is deliberately a local handler path; transparent forwarding
      // must never be used for an Anthropic Messages runtime.
    }
    if (routing.requestPath !== undefined) {
      assert(
        isProviderRequestPath(routing.requestPath),
        `provider '${p.id}' routing[${agent}].requestPath invalid`,
      );
    }
    if (routing.supportsResponsesCustomTools !== undefined) {
      assert(
        typeof routing.supportsResponsesCustomTools === 'boolean',
        `provider '${p.id}' routing[${agent}].supportsResponsesCustomTools must be boolean`,
      );
    }
    // modelPrefixes(路由服务范围)提供了就必须是命名空间前缀形态(`xai/` 这类,以 `/` 结尾)——
    // 结构上保证 claude-* 等裸 wire model 永远不会命中,防止把 scope 声明成误伤辅助请求的形状。
    if (routing.modelPrefixes !== undefined) {
      assert(
        Array.isArray(routing.modelPrefixes) && routing.modelPrefixes.length > 0,
        `provider '${p.id}' routing[${agent}].modelPrefixes must be a non-empty array`,
      );
      for (const prefix of routing.modelPrefixes) {
        assert(
          typeof prefix === 'string' && /^[a-zA-Z0-9_-]+\/$/.test(prefix),
          `provider '${p.id}' routing[${agent}].modelPrefixes entry '${String(prefix)}' must be a namespace prefix ending with '/'`,
        );
      }
    }
    const list = p.models[agent];
    assert(Array.isArray(list), `provider '${p.id}' declares agent '${agent}' but no models[${agent}]`);
    for (const m of list) validateModel(m, p.id, agent, routing.upstream);
  }
  // 约束:若声明了 titleModel(标题 oneShot 用的最经济模型),它必须存在于本供应商任一
  // agent 的模型清单里 —— 防把不存在 / 拼错的 id 配进去导致运行时静默起不出标题。
  // 豁免:Claude/Codex 动态清单供应商在这两个 harness 下都为空时无静态清单可校验;
  // 独立的 Pi 原生名单不应把它误判为静态 root,也不要求沿用同一 model id 命名空间。
  if (p.titleModel !== undefined) {
    assert(typeof p.titleModel === 'string' && p.titleModel.length > 0, `provider '${p.id}' titleModel must be a non-empty string`);
    const hasStaticModels = p.agents.some(
      (agent) => agent !== 'pi' && (p.models[agent] ?? []).length > 0,
    );
    if (hasStaticModels) {
      const known = p.agents.some((agent) => (p.models[agent] ?? []).some((m) => m.id === p.titleModel));
      assert(known, `provider '${p.id}' titleModel '${p.titleModel}' not found in any agent's models`);
    }
  }
  // 媒体模型清单与默认选型(图像/视频同一套规则):
  // 清单 id/name 非空、id 不重复,不参与 agent/routing 约束(媒体模型不经
  // agent runtime);默认选型必须与清单配套且每个值指向在册 id。
  validateMediaModels(p.id, 'imageModels', p.imageModels, 'imageDefaults', p.imageDefaults, allowEmptyModalities);
  validateMediaModels(p.id, 'videoModels', p.videoModels, 'videoDefaults', p.videoDefaults, allowEmptyModalities);
  // 向量清单同一套规则(PR #1707 review):不校验的话,远端把 embeddingModels 写成
  // 对象、给重复/空 id、或让 embeddingDefaults 指向清单外型号,都能通过
  // parseCatalog();前一种随后在 deriveCindyMediaConfig 的 for...of 里抛错,被上层
  // 降级成空清单 —— 表现是所有插件向量请求变 NO_CANDIDATE,而真正的坏数据在目录里。
  validateMediaModels(
    p.id,
    'embeddingModels',
    p.embeddingModels,
    'embeddingDefaults',
    p.embeddingDefaults,
    allowEmptyModalities,
  );
  validateMediaModels(p.id, 'audioModels', p.audioModels, 'audioDefaults', undefined, allowEmptyModalities);
  for (const m of p.audioModels ?? []) {
    assert(['audio_speech', 'audio_transcription', 'audio_generation', 'realtime'].includes(m.mode ?? ''), `provider '${p.id}' audio model '${m.id}' requires an audio mode`);
  }
  validateAccess(p);
  validateOAuthDescriptor(p);
}

/** 图像/视频模型清单 + 默认选型的共用校验(字段名只用于报错定位)。 */
function validateMediaModels(
  providerId: string,
  modelsField: string,
  models: Array<{
    id: string;
    name: string;
    modalities?: { input: string[]; output: string[] };
    officialDocs?: string;
    mode?: string;
  }> | undefined,
  defaultsField: string,
  defaults: { standard: string; draft?: string; best?: string } | undefined,
  allowEmptyModalities = false,
): void {
  if (models !== undefined) {
    assert(Array.isArray(models), `provider '${providerId}' ${modelsField} must be an array`);
    const seen = new Set<string>();
    for (const m of models) {
      assert(m && typeof m === 'object', `provider '${providerId}' ${modelsField} entry must be an object`);
      assert(typeof m.id === 'string' && m.id.length > 0, `provider '${providerId}' ${modelsField} entry missing id`);
      assert(typeof m.name === 'string' && m.name.length > 0, `provider '${providerId}' ${modelsField} '${m.id}' missing name`);
      assert(!seen.has(m.id), `provider '${providerId}' ${modelsField} has duplicate id '${m.id}'`);
      seen.add(m.id);
      assert(m.mode === undefined || validModelMetadata({ mode: m.mode }), `model '${m.id}' mode invalid`);
      if (m.modalities !== undefined) {
        assert(
          m.modalities && typeof m.modalities === 'object' && !Array.isArray(m.modalities),
          `provider '${providerId}' ${modelsField} '${m.id}' modalities must be an object`,
        );
        for (const key of ['input', 'output'] as const) {
          const values = m.modalities[key];
          assert(
            Array.isArray(values) && (allowEmptyModalities || values.length > 0) && values.length <= 16,
            `provider '${providerId}' ${modelsField} '${m.id}' modalities.${key} must be a non-empty bounded array`,
          );
          assert(
            values.every(
              (value) =>
                typeof value === 'string' &&
                value.length > 0 &&
                value.length <= 64 &&
                value.trim() === value,
            ) && new Set(values).size === values.length,
            `provider '${providerId}' ${modelsField} '${m.id}' modalities.${key} contains invalid values`,
          );
        }
      }
      if (m.officialDocs !== undefined) {
        let valid = false;
        if (typeof m.officialDocs === 'string' && m.officialDocs.length <= 2_048) {
          try {
            const url = new URL(m.officialDocs);
            valid = url.protocol === 'https:' && !url.username && !url.password;
          } catch {
            valid = false;
          }
        }
        assert(
          valid,
          `provider '${providerId}' ${modelsField} '${m.id}' officialDocs must be https`,
        );
      }
    }
  }
  if (defaults !== undefined) {
    assert(defaults && typeof defaults === 'object', `provider '${providerId}' ${defaultsField} must be an object`);
    assert(Array.isArray(models) && models.length > 0, `provider '${providerId}' ${defaultsField} requires ${modelsField}`);
    const ids = new Set((models ?? []).map((m) => m.id));
    for (const key of ['standard', 'draft', 'best'] as const) {
      const v = defaults[key];
      if (key === 'standard') assert(typeof v === 'string' && v.length > 0, `provider '${providerId}' ${defaultsField}.standard missing`);
      if (v !== undefined) assert(ids.has(v), `provider '${providerId}' ${defaultsField}.${key} '${v}' not in ${modelsField}`);
    }
  }
}

/** 模型派生相关字段的稳定签名(用于跨供应商一致性校验,固定 key 序)。
 *  注:**不含** `supportsFastMode` —— Fast 能力是 per-(provider, agent) 的(见 CatalogModel
 *  文档),同一 model id 在不同供应商下可显式分叉(如某网关剥掉 fast 字段 ⇒ 该来源配 false),
 *  故意排除出一致性校验以放行这种分叉。同理**不含** `icon`(展示图标 per-provider 可分叉)
 *  与 `defaultEnabled`。其余派生字段仍要求跨供应商一致。 */
function modelSignature(m: CatalogModel): string {
  return JSON.stringify({
    name: m.name,
    description: m.description ?? null,
    contextWindow: m.contextWindow,
    efforts: m.efforts,
    effortDisplayNames: m.effortDisplayNames ?? null,
    defaultEffort: m.defaultEffort,
    group: m.group ?? null,
    sortOrder: m.sortOrder ?? null,
  });
}

/**
 * 同一 agent 下、同一 model id 跨多个供应商(如 gpt-5.5 同时由 openai 与 xd 提供)
 * 必须承载一致的元数据。host 派生 availableModels 时按 provider 序 first-wins 去重,
 * 元数据分叉会导致「选了同名模型但 ctx / effort 不同」的静默漂移。
 * 注:跨 agent 不约束(gpt-5.5 在 cc=1M / codex=272k 本就分叉,正是 per-agent 拆分的意义)。
 */
function validateModelConsistency(catalog: Catalog): void {
  const sigByKey = new Map<string, string>();
  for (const p of catalog.providers) {
    for (const agent of p.agents) {
      for (const m of p.models[agent] ?? []) {
        const key = `${agent}\u0000${m.id}`;
        const sig = modelSignature(m);
        const prev = sigByKey.get(key);
        if (prev === undefined) sigByKey.set(key, sig);
        else assert(prev === sig, `model '${m.id}' has inconsistent metadata across providers for agent '${agent}'`);
      }
    }
  }
}

/** 单条预设是否合法(结构完整、至少一个合法 runtime)。 */
function isValidPreset(v: unknown): v is ProviderPreset {
  if (!v || typeof v !== 'object') return false;
  const p = v as Record<string, unknown>;
  if (typeof p.id !== 'string' || p.id.length === 0) return false;
  if (typeof p.name !== 'string' || p.name.length === 0) return false;
  if (p.docsUrl !== undefined && typeof p.docsUrl !== 'string') return false;
  if (
    p.authMethod !== undefined
    && p.authMethod !== 'apiKey'
    && p.authMethod !== 'none'
  ) return false;
  if (!p.runtimes || typeof p.runtimes !== 'object' || Array.isArray(p.runtimes)) return false;
  const entries = Object.entries(p.runtimes as Record<string, unknown>);
  if (entries.length === 0) return false;
  for (const [agent, rt] of entries) {
    if (!isAgentKind(agent)) return false;
    if (!rt || typeof rt !== 'object') return false;
    const r = rt as Record<string, unknown>;
    if (typeof r.baseUrl !== 'string' || r.baseUrl.length === 0) return false;
    if (!Array.isArray(r.models)) return false;
    for (const m of r.models) {
      if (!m || typeof m !== 'object') return false;
      const mm = m as Record<string, unknown>;
      if (typeof mm.id !== 'string' || mm.id.length === 0) return false;
      if (typeof mm.name !== 'string' || mm.name.length === 0) return false;
      if (mm.api !== undefined && !isPiModelApi(mm.api)) return false;
      if (mm.piApi !== undefined && !isPiModelApi(mm.piApi)) return false;
      if (
        mm.contextWindow !== undefined
        && (typeof mm.contextWindow !== 'number' || !Number.isFinite(mm.contextWindow) || mm.contextWindow <= 0)
      ) return false;
      if (mm.supportsImageInput !== undefined && typeof mm.supportsImageInput !== 'boolean') {
        return false;
      }
      if (!hasValidPresetReasoningCapability(agent, mm)) return false;
    }
    if (r.wireProtocol !== undefined && !isWireProtocol(r.wireProtocol)) return false;
    if (
      r.supportsImageGeneration !== undefined &&
      typeof r.supportsImageGeneration !== 'boolean'
    ) {
      return false;
    }
    if (r.supportsImageGeneration === true && agent !== 'codex') return false;
    const defaultWireProtocol = r.wireProtocol ?? (agent === 'codex' ? 'openai-responses' : undefined);
    const hasResponsesRoute =
      defaultWireProtocol === 'openai-responses' ||
      r.models.some((model) => {
        if (!model || typeof model !== 'object') return false;
        const route = (model as Record<string, unknown>).route;
        return route && typeof route === 'object' && !Array.isArray(route)
          ? (route as Record<string, unknown>).wireProtocol === 'openai-responses'
          : false;
      });
    if (r.supportsImageGeneration === true && !hasResponsesRoute) return false;
    if (r.headers !== undefined) {
      if (!r.headers || typeof r.headers !== 'object' || Array.isArray(r.headers)) return false;
      if (Object.values(r.headers as Record<string, unknown>).some((x) => typeof x !== 'string')) return false;
    }
    if (r.baseUrlEditable !== undefined && typeof r.baseUrlEditable !== 'boolean') return false;
    if (
      r.piCatalogProviderId !== undefined
      && (agent !== 'pi' || typeof r.piCatalogProviderId !== 'string' || !/^[a-z0-9-]+$/.test(r.piCatalogProviderId))
    ) return false;
    // modelsUrl / requestPath 不在此淘汰整条——非法值由 sanitizePresets 剥字段。
  }
  return true;
}

/** 是否为不含内嵌凭据的 http(s) URL(模型发现地址归一化用)。 */
function isHttpUrl(v: unknown): boolean {
  if (typeof v !== 'string' || v.length === 0) return false;
  try {
    const u = new URL(v);
    return (u.protocol === 'https:' || u.protocol === 'http:') && !u.username && !u.password;
  } catch {
    return false;
  }
}

function httpUrl(v: unknown): URL | null {
  if (!isHttpUrl(v)) return null;
  return new URL(v as string);
}

function normalizedEndpointUrl(value: unknown): string | null {
  const url = httpUrl(value);
  if (!url) return null;
  url.hash = '';
  url.pathname = url.pathname.replace(/\/+$/, '') || '/';
  return url.toString();
}

/**
 * Compatibility for catalog data generated before explicit Pi wireProtocol was shipped.
 * Those entries copied the exact Claude/Anthropic endpoint into runtimes.pi. Equality with the
 * Claude runtime is the authority here; a different Pi URL remains unconfigured and fail-closed.
 */
function isLegacyAnthropicPiRuntime(
  preset: ProviderPreset,
  agent: AgentKind,
  runtime: NonNullable<ProviderPreset['runtimes'][AgentKind]>,
): boolean {
  if (agent !== 'pi' || runtime.wireProtocol !== undefined) return false;
  const claudeRuntime = preset.runtimes['claude-code'];
  if (
    !claudeRuntime ||
    (claudeRuntime.wireProtocol !== undefined &&
      claudeRuntime.wireProtocol !== 'anthropic-messages')
  ) return false;
  const piEndpoint = normalizedEndpointUrl(runtime.baseUrl);
  return piEndpoint !== null && piEndpoint === normalizedEndpointUrl(claudeRuntime.baseUrl);
}

/**
 * runtime.modelsUrl 非法(非 http(s) URL 或含内嵌凭据)时剥掉该字段、保留预设本体——OSS 推错一个
 * 不可见字段不该让整条预设消失,更不该让用户保存时撞 main 侧 URL 校验无法自助修复。
 */
function normalizePresetRuntimeOptions(p: ProviderPreset): ProviderPreset {
  let changed = false;
  const runtimes: ProviderPreset['runtimes'] = {};
  for (const [agent, rt] of Object.entries(p.runtimes) as [AgentKind, ProviderPreset['runtimes'][AgentKind] & object][]) {
    let next = rt;
    if (isLegacyAnthropicPiRuntime(p, agent, next)) {
      next = { ...next, wireProtocol: 'anthropic-messages' };
      changed = true;
    }
    const models = next.models.map((model) => {
      if (model.route === undefined || isValidModelRoute(agent, next.baseUrl, model.route)) {
        return model;
      }
      const { route: _drop, ...rest } = model;
      changed = true;
      return rest;
    });
    if (models.some((model, index) => model !== next.models[index])) {
      next = { ...next, models };
    }
    if (next.modelsUrl !== undefined && !isHttpUrl(next.modelsUrl)) {
      const { modelsUrl: _drop, ...rest } = next;
      next = rest;
      changed = true;
    }
    if (next.requestPath !== undefined && !isProviderRequestPath(next.requestPath)) {
      const { requestPath: _drop, ...rest } = next;
      next = rest;
      changed = true;
    }
    if (next.modelDiscovery !== undefined) {
      const runtimeUrl = httpUrl(next.baseUrl);
      const sources = Array.isArray(next.modelDiscovery)
        ? next.modelDiscovery.filter((candidate) => {
            if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) return false;
            const source = candidate as unknown as Record<string, unknown>;
            const sourceUrl = httpUrl(source.baseUrl);
            if (!runtimeUrl || !sourceUrl || sourceUrl.origin !== runtimeUrl.origin) return false;
            if (!isWireProtocol(source.wireProtocol)) return false;
            if (
              source.modelsUrl !== undefined &&
              (!isHttpUrl(source.modelsUrl) ||
                httpUrl(source.modelsUrl)?.origin !== sourceUrl.origin)
            ) {
              return false;
            }
            return (
              source.requestPath === undefined || isProviderRequestPath(source.requestPath)
            );
          })
        : [];
      if (
        !Array.isArray(next.modelDiscovery) ||
        sources.length !== next.modelDiscovery.length
      ) {
        changed = true;
      }
      if (sources.length > 0) {
        next = { ...next, modelDiscovery: sources };
      } else {
        const { modelDiscovery: _drop, ...rest } = next;
        next = rest;
      }
    }
    runtimes[agent] = next;
  }
  return changed ? { ...p, runtimes } : p;
}

/**
 * 预设段容错清洗:逐条校验、坏条目丢弃 + 按 id 去重(first-wins)。
 *
 * 刻意**不走 assert**:预设是纯 UI 模板数据,不参与路由;OSS 推错一条预设不应让
 * 整份远端目录 parse 失败回退 bundled(那会连带丢掉远端的模型/路由更新)。
 */
export function sanitizePresets(input: unknown): ProviderPreset[] {
  if (!Array.isArray(input)) return [];
  const out: ProviderPreset[] = [];
  const seen = new Set<string>();
  for (const raw of input) {
    const v = expandPresetModels(raw);
    // 展开成功会删掉顶层 `models`;仍留着说明引擎字段畸形或清单不是数组,整条拒绝——
    // 即使 runtimes 另带了旧格式清单,也不能让它以同 id 覆盖随包版本。
    if (v && typeof v === 'object' && 'models' in v) continue;
    if (!isValidPreset(v) || seen.has(v.id)) continue;
    seen.add(v.id);
    // 可选呈现字段逐项归一化,**不许分支 continue**:多个字段同时非法时早退会漏清洗
    // (如 regionHint + nameEn 都坏,坏 nameEn 会原样流出——Codex P2,2026-07-24)。
    let preset = v as ProviderPreset;
    // regionHint 非法值不淘汰整条预设(它只是呈现提示),归一化为缺省(区域中立)。
    if (preset.regionHint !== undefined && preset.regionHint !== 'cn' && preset.regionHint !== 'global') {
      const { regionHint: _drop, ...rest } = preset as ProviderPreset & { regionHint: unknown };
      preset = rest as ProviderPreset;
    }
    // nameEn 非法值(非字符串/空白串)同容错语义:剥字段不淘汰整条。
    if (preset.nameEn !== undefined && (typeof preset.nameEn !== 'string' || preset.nameEn.trim().length === 0)) {
      const { nameEn: _drop, ...rest } = preset as ProviderPreset & { nameEn: unknown };
      preset = rest as ProviderPreset;
    }
    // 繁中展示名非法时只剥掉该字段,保留预设本体并回落到 name。
    if (preset.nameZhTW !== undefined && (typeof preset.nameZhTW !== 'string' || preset.nameZhTW.trim().length === 0)) {
      const { nameZhTW: _drop, ...rest } = preset as ProviderPreset & { nameZhTW: unknown };
      preset = rest as ProviderPreset;
    }
    out.push(normalizePresetRuntimeOptions(preset));
  }
  return out;
}

/**
 * 预设展示名:中文 UI 用目录 `name`(国内厂商为中文原名),其它语言优先 `nameEn`
 * (缺省回落 `name`)。纯呈现选择,不影响预设 id / 创建后的供应商命名语义。
 */
export function presetDisplayName(
  preset: Pick<ProviderPreset, 'name' | 'nameEn' | 'nameZhTW'> & { id?: string },
  locale: string,
): string {
  const normalizedLocale = locale.toLowerCase().replaceAll('_', '-');
  const mimoName = mimoPresetName(preset.id, normalizedLocale);
  if (mimoName) return mimoName;
  if (normalizedLocale === 'zh-tw' || normalizedLocale.startsWith('zh-hant')) {
    return preset.nameZhTW ?? preset.name;
  }
  return normalizedLocale.startsWith('zh') ? preset.name : (preset.nameEn ?? preset.name);
}

/** 预设的厂商分组键:id 去掉区域后缀(`zhipu-glm-cn`/`zhipu-glm-global` → `zhipu-glm`)。 */
function presetVendorKey(p: ProviderPreset): string {
  const key = p.id.replace(/-(cn|global)$/, '');
  // 智谱国内品牌沿用 zhipu,海外品牌使用 zai,但仍是同一厂商的区域渠道。
  return key === 'zai-coding-plan' ? 'zhipu-coding-plan' : key;
}

/**
 * 预设列表排序(稳定,纯呈现层):
 *   - 按**厂商分组**(id 去区域后缀),厂商间按分组键首字母升序;
 *   - 同一厂商的国内/国际条目**相邻**,组内按客户端构建区域排先后(cn/dev → cn 在前,global → global 在前);
 *   - 组内无 regionHint 的条目居中,保持目录原始顺序。
 * 只排序不过滤 —— 所有预设对所有用户可见可选,可达性由「测试连接」实测裁决。
 */
export function sortPresetsForRegion(
  presets: ProviderPreset[],
  region: PresetSortRegion,
): ProviderPreset[] {
  const cnFirst = region !== 'global';
  const regionRank = (p: ProviderPreset): number => {
    if (p.regionHint === undefined) return 1;
    if (p.regionHint === 'cn') return cnFirst ? 0 : 2;
    return cnFirst ? 2 : 0; // 'global'
  };
  return [...presets].sort((a, b) => {
    const vendor = presetVendorKey(a).localeCompare(presetVendorKey(b), 'en');
    if (vendor !== 0) return vendor;
    return regionRank(a) - regionRank(b);
  });
}

/**
 * 把任意来源(远端 / 本地文件文本 / 对象)解析校验成 Catalog。
 * 失败抛错——调用方决定回退兜底。
 */
export function parseCatalog(input: string | unknown): Catalog {
  const obj: unknown = typeof input === 'string' ? JSON.parse(input) : input;
  assert(obj && typeof obj === 'object', 'root is not an object');
  const allowedRootFields = new Set(['version', 'providers', 'presets', 'modelRegistry']);
  const unknownRootField = Object.keys(obj).find((field) => !allowedRootFields.has(field));
  assert(!unknownRootField, `catalog.${unknownRootField} is not allowed`);
  const catalog = obj as Catalog;
  assert(typeof catalog.version === 'string', 'catalog.version missing');
  assert(Array.isArray(catalog.providers) && catalog.providers.length > 0, 'catalog.providers missing/empty');
  // presets 容错清洗(坏条目丢弃,不让预设错误拖垮整份目录)。
  const presets = sanitizePresets((catalog as { presets?: unknown }).presets);
  if (presets.length > 0) catalog.presets = presets;
  else delete catalog.presets;
  if ((catalog as { modelRegistry?: unknown }).modelRegistry !== undefined) {
    const registry = parseModelRegistry((catalog as { modelRegistry: unknown }).modelRegistry);
    assert(registry.ok, registry.ok ? '' : registry.error);
    catalog.modelRegistry = registry.value;
  }
  // Validate authored lists before projection so malformed input cannot be repaired or crash mapping.
  for (const provider of catalog.providers) {
    for (const field of ['imageModels', 'videoModels', 'audioModels', 'embeddingModels'] as const)
      validateMediaModels(provider.id, field, provider[field], field === 'audioModels' ? '' : field.replace('Models', 'Defaults'),
        field === 'imageModels' ? provider.imageDefaults : field === 'videoModels' ? provider.videoDefaults : field === 'embeddingModels' ? provider.embeddingDefaults : undefined, (catalog.modelRegistry?.schemaVersion ?? 0) >= 4);
  }
  const projected = { ...catalog, providers: catalog.providers.map((provider) =>
    projectProviderMediaModels(provider, catalog.modelRegistry, { addDeclared: true })) };
  for (const provider of projected.providers) validateProvider(provider, (catalog.modelRegistry?.schemaVersion ?? 0) >= 4);
  validateModelConsistency(projected);
  // 远端下发目录与 bundled 同格式:静态条目的窗口是产品侧写定的真实上限,标记为已核实
  // (幂等;条目自己表过态时尊重原值)。动态发现的模型不经这里 —— 见 withVerifiedStaticWindows。
  //
  // 刻意**不**原地替换 catalog.providers:入参可能就是 BUNDLED_CATALOG(共享的 import 对象),
  // 原地改会把标记悄悄写回那份共享目录 —— 既是跨调用方的副作用,也会让「bundled 自己有没有
  // 标记」这类断言变成假通过。
  return { ...projected, providers: projected.providers.map(withVerifiedStaticWindows) };
}