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。

45.5 KB
Raw Blame
import type { ModelDisplayPricing } from './modelDisplayPricing.js';
import type { ModelMetadata } from "./modelMetadataLayers.js";
/**
 * @cindy/model-providers — 类型定义。
 *
 * 形状对齐 models.dev(OpenCode 同源):provider 为单位、每个 model 带
 * cost / limit / modalities / 能力 / release_date / status。在此之上加两处
 * **provider 级多 agent 扩展**(因为 xdt-maker 不直连模型、而是把请求透过 Claude
 * Code / Codex 二进制 + 本地代理路由,与 OpenCode 的直连 SDK `npm`/`api` 不同):
 *   - provider 级 `agents`:这家供应商能用在哪些 agent runtime;直接决定它的
 *     模型出现在哪个 agent 的模型列表里。
 *   - provider 级 `routing`:按 runtime 的「路由描述符」——决定请求最终发去哪个
 *     上游、用哪种钥匙、model id 是否需要还原。这是给通用路由器(host 侧,见
 *     apps/desktop maker-host)消费的数据,替代过去硬编码的 decideXxxRoute。
 *
 * model 按 agent 分组挂在 `Provider.models[agent]` 下:目录是 per-agent 模型清单的
 * 唯一来源(SSoT),host 从中派生 maker-core 的 capabilities.availableModels。
 *
 * 本包零运行时依赖:`AgentKind` / `Effort` 在此就地定义(与 maker-core 的同名
 * 联合保持一致),不 import maker-core,保证可作为独立能力复用。
 */
import type { ModelRegistry } from "./modelAccessBean.js";

/** 承载模型的 agent runtime —— 与 maker-core AgentKind 对齐。 */
export type AgentKind = "claude-code" | "codex" | "pi";

/** 推理强度档位 —— 与 maker-core Effort 对齐。 */
export type Effort =
  "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra";

/** Pi 原生支持的 reasoning/thinking 档位(Pi 不支持 Cindy 的 ultra 档)。 */
export const PI_REASONING_EFFORTS = [
  "minimal",
  "low",
  "medium",
  "high",
  "xhigh",
  "max",
] as const;
export type PiReasoningEffort = (typeof PI_REASONING_EFFORTS)[number];

/**
 * PI models.json understands these native inference APIs. The
 * provider-level wireProtocol remains the default for an endpoint; piApi is a
 * sparse per-model override for newly released models or protocol corrections.
 */
export const PI_MODEL_APIS = [
  "anthropic-messages",
  "openai-responses",
  "openai-completions",
  "google-generative-ai",
  "bedrock-converse-stream",
  "azure-openai-responses",
  "google-vertex",
  "mistral-conversations",
] as const;
export type PiModelApi = (typeof PI_MODEL_APIS)[number];

/**
 * Cindy 自带鉴权的订阅账号家族(ChatGPT / Claude / SuperGrok)。新增订阅家族只在这里加一项:
 * 各端按家族读取账号余量的入口都以 `Record<NativeSubscriptionAuth, …>` 声明,漏接会直接
 * 编译失败(mobile 任务菜单见 readSessionMenuAccountUsage)。
 */
export const NATIVE_SUBSCRIPTION_AUTHS = ["codex", "claude", "xai"] as const;
export type NativeSubscriptionAuth = (typeof NATIVE_SUBSCRIPTION_AUTHS)[number];
/** 每个订阅家族的内置默认账号 providerId(独立账号另有自己的 id,以 auth.native 标识家族)。 */
export const NATIVE_SUBSCRIPTION_DEFAULT_PROVIDER_IDS = {
  codex: "openai",
  claude: "anthropic",
  xai: "xai",
} as const satisfies Record<NativeSubscriptionAuth, string>;

/** Provider runtime 上游实际接受的推理 wire protocol。 */
export type ProviderWireProtocol =
  "anthropic-messages" | "openai-responses" | "openai-chat" | "google-generative-ai";

/** Codex 通过本地 bridge 兼容的两种非原生 Responses wire protocol。 */
export type CodexCompatibilityWireProtocol = Extract<
  ProviderWireProtocol,
  "anthropic-messages" | "openai-chat"
>;

/** 供应商来源:内置 / 用户自定义 / 企业下发。企业连接走自定义路由,但不能当个人连接编辑。 */
export type ProviderSource = "builtin" | "user" | "organization";

/** 用户连接该供应商的鉴权方式(决定设置页的连接 UI)。
 *  - oauth   : 走 OAuth 登录(Claude.ai 订阅 / Codex 订阅)
 *  - apiKey  : 用户手填 API key
 *  - managed : 由平台托管 / 自动下发(XD 网关 key 登录后自动同步)
 *  - none    : 上游不要求客户端鉴权(本机 LiteLLM / Ollama 等受信代理)
 */
export type AuthMethod = "oauth" | "apiKey" | "managed" | "none";

/**
 * 模型额度的来源(展示 / 产品语义),与 `auth` 的连接协议刻意分开:
 * OAuth 不必然代表订阅,API key 也不应靠模型名或图标推断。
 */
export type ProviderAccess =
  | { kind: "subscription"; product: string }
  | { kind: "api" }
  | { kind: "managed" };

/**
 * 通用路由器消费的「钥匙策略」——决定一笔请求到达上游时的鉴权头怎么处理。
 * 具体到某 runtime 的 header 落地(x-api-key vs Bearer、是否删 anthropic-beta、
 * 是否透传 chatgpt-account-id)由该 runtime 的代理实现,本字段只表达意图:
 *   - oauth-passthrough : 直连供应商自家上游,透传二进制已带的 OAuth bearer。
 *   - provider-oauth-header : 直连供应商自家上游,但用 host 保存的该供应商 OAuth token
 *     覆盖 Authorization;用于子进程 OAuth 不属于目标供应商的场景
 *     (如 Codex → xAI / Claude.ai subscription)。
 *   - api-key-header    : 直连供应商自家上游,用该供应商自己的 API key 覆盖鉴权头。
 *   - gateway-key       : 走 XD 共享网关,把鉴权头换成网关 key。
 *   - oauth-token       : 直连供应商自家上游,用 host 侧通用 OAuth Runner 持有的
 *                         access_token 覆盖鉴权头(`Authorization: Bearer`)。与
 *                         oauth-passthrough 的区别:token 不来自 agent 二进制自带凭证,
 *                         而来自目录 `auth.oauth` 描述符驱动的登录(见 OAuthProviderDescriptor)。
 *   - none              : 直连无需鉴权的受信上游;代理必须剥掉 agent 自带的鉴权与账号头,
 *                         防把 Claude.ai / ChatGPT 订阅凭证泄漏给本地或自托管服务。
 */
export type AuthStrategy =
  | "oauth-passthrough"
  | "provider-oauth-header"
  | "api-key-header"
  | "gateway-key"
  | "oauth-token"
  | "none";

/**
 * 授权(OAuth)供应商描述符 —— 让「接一家标准 OAuth 供应商」退化成目录数据。
 *
 * 承载标准 authorization-code + PKCE 或 OAuth 2.0 Device Authorization Grant 的同构参数;
 * 深度定制(spawn CLI 登录、auth.json reconcile、JWT claim 提头等)保持 host 侧 bespoke
 * 实现,不进描述符(规则 9:确定性逻辑写代码,描述符只承载真正同构的部分)。host 的
 * 通用 OAuth Runner(generic-oauth)消费本描述符完成授权、safeStorage 存储与单飞刷新;
 * 路由侧配合 `authStrategy: 'oauth-token'` 注入 Bearer。
 */
interface OAuthProviderDescriptorBase {
  /** token 交换端点(token_endpoint,form-encoded POST)。 */
  tokenUrl: string;
  /** OAuth client id(公共客户端,PKCE 保护,无 secret)。 */
  clientId: string;
  /** 请求的 scopes(空格分隔)。 */
  scopes: string;
  /**
   * 动态模型发现端点(可选)。登录成功后 host 带 Bearer GET 此 URL,响应按 OpenAI
   * `GET /models` 形状(`{data:[{id}]}` 或 `{models:[...]}`)解析,additions-only
   * merge 进 active-catalog(静态条目 first-wins,发现条目只增不改删)。
   */
  modelsDiscoveryUrl?: string;
}

export interface OAuthAuthorizationCodeDescriptor extends OAuthProviderDescriptorBase {
  /** 缺省保持历史目录兼容;等价于 `authorization-code`。 */
  flow?: "authorization-code";
  /** 授权端点(authorization_endpoint)。 */
  authorizeUrl: string;
  /**
   * 回环回调端口。多数供应商注册的 redirect_uri 是固定端口
   * (`http://127.0.0.1:<port>/callback`);缺省 = 随机高位端口(供应商允许通配端口时用)。
   */
  redirectPort?: number;
  /** 追加到授权 URL 的额外 query 参数(如厂商自定义的 plan / referrer)。 */
  extraAuthParams?: Record<string, string>;
  deviceAuthorizationUrl?: never;
  extraDeviceParams?: never;
}

export interface OAuthDeviceCodeDescriptor extends OAuthProviderDescriptorBase {
  flow: "device-code";
  /** 申请 device_code / user_code 的端点(device_authorization_endpoint)。 */
  deviceAuthorizationUrl: string;
  /** 追加到设备授权 POST body 的厂商参数。 */
  extraDeviceParams?: Record<string, string>;
  authorizeUrl?: never;
  redirectPort?: never;
  extraAuthParams?: never;
}

export type OAuthProviderDescriptor =
  OAuthAuthorizationCodeDescriptor | OAuthDeviceCodeDescriptor;

/**
 * 路由描述符(per provider × runtime)。喂给 host 侧通用路由器,决定请求的
 * 真实上游 + 鉴权 + model id 还原。加新供应商 = 加这份数据,不改路由器代码。
 */
export interface RoutingDescriptor {
  modelInterface?: ModelInterfaceSnapshot;
  /**
   * 上游 wire protocol。Claude Code / Codex 缺省保持历史语义;Pi 必须显式声明。
   * Codex 的 openai-chat / anthropic-messages 会分别进入对应的本地 Responses bridge。
   */
  wireProtocol?: ProviderWireProtocol;
  /**
   * 此 Codex Responses 上游是否原生接受 `type: "custom"` 工具。
   * `false` 时 Desktop 可把选定的 custom tool 对称转换为普通 function tool;
   * 未声明表示没有足够能力信息,调用方不得按模型名猜测。
   */
  supportsResponsesCustomTools?: boolean;
  /**
   * 该自定义 Provider 的 Codex Responses runtime 是否支持原生图片生成与编辑。
   * 缺省按 false 处理;它与模型图片输入能力独立,也不得从模型名推断。
   */
  supportsImageGeneration?: boolean;
  /** Explicit standalone image API; independent of chat wire and Codex hosted tools. */
  imageApi?: "openai-images";
  /** Explicit standalone async video API, independent of the chat protocol. */
  videoApi?: "xai-videos";
  /** Enterprise BYOK image model binding used by the Codex Images route. */
  imageModel?: { wireModel: string; litellmModel: string; supportsEdit: boolean };
  /** 真实上游 base URL(direct 时是供应商自家;gateway 时是 XD 网关 base)。 */
  upstream: string;
  /**
   * 推理请求的精确相对路径(可选,必须以单个 `/` 开头)。
   *
   * 缺省时沿用 agent 发来的标准路径(Claude `/v1/messages`、Codex `/responses`);
   * 提供后只覆盖带 model 的推理请求,GET `/models` 等控制面请求不受影响。
   * `openai-chat` 本地桥也消费同一字段,替代缺省 `/chat/completions`。
   */
  requestPath?: string;
  /** 鉴权策略(见 AuthStrategy)。 */
  authStrategy: AuthStrategy;
  /**
   * 配置保留用于展示/修复,但运行时不得向该上游路由。用于把升级前不再满足安全边界的
   * 历史配置留在设置页,同时让所有路由解析 fail closed。
   */
  disabled?: boolean;
  /** 转发上游前还原 model id(如剥掉 `codex/` 前缀)。缺省 = 原样。 */
  modelIdRewrite?: { stripPrefix: string };
  /** 转发上游前需删除的请求头(如 gateway 路由删 `anthropic-beta`)。 */
  headerDelete?: string[];
  /** 额外固定请求头覆盖(少数特例用;多数由 authStrategy 隐含)。 */
  headerOverride?: Record<string, string>;
  headerOverrideState?: "configured" | "unknown";
  /** 可选 quirk 适配钩子名(对齐 OpenCode custom loader,承接无法纯数据表达的特例)。 */
  adapter?: string;
  /**
   * 自定义供应商的「列模型」端点回带(可选)。路由器**不消费**本字段——它只是把
   * `CustomProviderRuntimeConfig.modelsUrl` 带进 Provider/ProviderView,让编辑表单
   * (providerViewToConfig 从 routing 重建配置)不丢这个持久化字段。
   */
  modelsUrl?: string;
  /** Pi 官方模型目录的 provider id;仅供 Pi 原生 provider 复用上游核实的模型协议/能力。 */
  piCatalogProviderId?: string;
  /**
   * 该路由能服务的 wire model id 命名空间前缀白名单(每项形如 `xai/`,必须以 `/` 结尾)。
   *
   * 声明后,per-session 路由只捕获命中前缀的请求;未命中的请求(典型:agent CLI 内部
   * 用 claude-* 小模型发起的辅助调用,如权限 auto 模式的安全分类器)返回 null,由调用方
   * 回落 spawn 默认路由(网关 / Anthropic 直连),而不是被误送到无法服务它的上游。
   *
   * 缺省 = 不限(universal):网关、Anthropic 直连、自定义供应商等「上游本身能服务任意
   * 模型」的路由不声明本字段,行为与历史版本字节级一致。
   *
   * 硬约束(catalog.test.ts 契约测试强制):凡供应商在某 agent 下的模型清单**整体**活在
   * `<ns>/` 命名空间(桥接型订阅直连,如 xai/ / chatgpt/),该 agent 的路由必须声明本字段,
   * 且前缀集合覆盖全部声明的模型 id —— 新增这类供应商时忘声明会被测试直接拦下。
   */
  modelPrefixes?: string[];
}

/**
 * 同一 runtime 内单个模型的上游覆盖。
 *
 * 鉴权与固定 headers 仍继承 runtime 级 `RoutingDescriptor`;这里只允许切换同源端点、
 * wire protocol 与可选请求路径,避免为一个 API key 再造第二套 provider/runtime。
 */
export interface ProviderModelRouteConfig {
  /** 该模型的兼容上游 base URL。 */
  baseUrl: string;
  /** 该模型实际使用的 wire protocol。 */
  wireProtocol: ProviderWireProtocol;
  /** 非标准推理端点的相对路径;缺省按 wire protocol 推导。 */
  requestPath?: string;
}

/** 绑定向导追加拉取的模型目录;发现到的模型会携带对应模型级路由。 */
export interface ProviderModelDiscoverySource extends ProviderModelRouteConfig {
  /** 可选精确列模型端点;缺省由 `baseUrl` 推导。 */
  modelsUrl?: string;
}

/** 模型计费($/1M tokens)。可选——OSS 目录可后补,缺值 UI 不展示价格。 */
export interface ModelCost {
  input?: number;
  output?: number;
  cacheRead?: number;
  cacheWrite?: number;
  /** Pi-compatible rates used when input tokens strictly exceed this threshold. */
  tiers?: Array<{
    inputTokensAbove: number;
    input?: number;
    output?: number;
    cacheRead?: number;
    cacheWrite?: number;
  }>;
}

/**
 * 单个模型条目 —— **目录是 per-agent 模型清单的唯一来源(SSoT)**。
 *
 * 模型按 agent 分组挂在 `Provider.models[agent]` 下(见 Provider.models)。host 从本目录
 * 派生 maker-core 的 `capabilities.availableModels`(per-agent),不再有写死的 CLAUDE_MODELS /
 * CODEX_MODELS。因此本结构承载该模型在**该 agent 下**的全部权威元数据。
 *
 * 注:同一 id 在不同 agent 下元数据可不同 —— 典型 gpt-5.5(cc=1M / codex=272k 上下文)。
 * per-agent 拆分正是为了表达这种分歧:各 agent 列表里各写各的值。同一 agent 内、同一 id
 * 跨 provider(如 gpt-5.5 同时由 openai 与 xd 提供)则必须元数据一致(见 catalog.ts 校验)。
 */
/** Non-sensitive, atomic execution selection. Stored with a running task. */
export interface ModelInterfaceSnapshot {
  profileId: string;
  providerId: string;
  revision: string;
  api: PiModelApi;
  wireModelId: string;
  route: ProviderModelRouteConfig;
  defaults: ModelMetadata;
  compatibility: string[];
  preferred: boolean;
  nativeApis?: import('./modelAccessBean.js').ModelNativeApi[] | null;
}
export interface CatalogModel {
  interfaceUnavailable?: boolean;
  selectedInterface?: ModelInterfaceSnapshot;
  availableInterfaces?: ModelInterfaceSnapshot[];
  nativeApis?: import("./modelAccessBean.js").ModelNativeApi[] | null;
  /** Same-provider display-only pricing; never inherited through public model metadata. */
  displayPricing?: ModelDisplayPricing;
  currency?: 'USD' | 'CNY';
  costDiscount?: number;

  supportsToolCalls?: boolean;
  reasoningRequired?: boolean;
  userModelConfig?: ProviderRuntimeModelConfig;
  catalogPresetId?: string;
  discoveredMetadata?: ModelMetadata;
  discoveredCost?: ModelCost;
  nameExplicit?: boolean;
  /** Canonical model API from the accepted Registry; null explicitly means unverified. */
  nativeApi?: PiModelApi | import('./modelAccessBean.js').ModelNativeApi | null;
  /** 与 maker-core 现有 model id 一致(如 'claude-opus-4-8' / 'gpt-5.5' / 'codex/gpt-5.5')。 */
  id: string;
  /** Server entitlement state. Paid-locked models remain present for UI but are never routable. */
  availability?: "available" | "requires_payment";
  /** Explicit Pi serializer; missing fields may use the matching native transport fallback. */
  /** Upstream execution API, shared by Claude Code, Codex and Pi. */
  api?: PiModelApi;
  piApi?: PiModelApi;
  /** 同一 provider/runtime 内该模型的上游覆盖;缺省使用 provider 级路由。 */
  route?: ProviderModelRouteConfig;
  /** 展示名(= maker-core ModelDescriptor.displayName)。 */
  name: string;
  description?: string;
  family?: string;
  /**
   * 厂商分组 id —— 决定模型在选择器右栏的分组归属(替代渲染层按 id 前缀硬猜)。
   * 当前取值与渲染层 ModelCategory 对齐:'anthropic' | 'gpt' | 'gpt-budget' | 'grok' |
   * 'google' | 'china' | 'ungrouped' | 'image' | 'video' | 'tts' | 'stt' | 'realtime' |
   * 'embedding' | 'decision' | 'compression' | 'other'。
   * 缺省时渲染层回退到 id 前缀归类(categorize)。新增未知分组需在渲染层补 i18n 标签。
   */
  group?: string;
  /**
   * Gateway 原生模型能力类型(issue #882:'chat' / 'embedding' / 'image_generation' /
   * 'audio_speech' / ... ,字段值不改名,原样透传)。是否为聊天模型、进哪个
   * ModelMode 展示分类均以此为权威;缺省时回退 id 正则兜底
   * (`classification.ts` classifyModel)。只有 XD 网关来源目前会填充,静态
   * 内置目录留空。
   */
  mode?: string;
  /**
   * 展示排序权重(升序)。渲染层按它对模型排序、并据每个分组的最小 sortOrder 决定分组先后。
   * 缺省排到末尾。仅影响选择器展示顺序,不影响 host 派生的 availableModels 数组序(后者保序)。
   */
  sortOrder?: number;
  /** 上下文窗口(tokens)。该 agent 下的权威值(host 派生进 ModelDescriptor.contextWindow)。 */
  contextWindow: number;
  /** Provider-declared maximum before a per-harness recommended window is applied. */
  contextWindowMax?: number;
  /**
   * `contextWindow` 是否为**显式声明**的真实上限,而非派生时补的兜底值。
   *
   * 目录条目的窗口可能来自产品目录写定 / 上游明示 / 用户填写(都算显式),也可能是
   * 上游不给元数据时补的常量(codex `model/list` 一律 272K、自定义 provider 未填时的
   * 200K、Anthropic 未知模型启发式)。两者数值上无法区分,但只有前者能用来收敛
   * 运行期上报的窗口 —— 拿兜底值当上限会把真实窗口压小。
   *
   * 缺省(undefined)一律按未核实处理。
   *
   * **这份 provenance 只活在 host 侧的目录里,刻意不进跨端 `ModelDescriptor`**
   * (host 的 `toDescriptor` 不透传它)。原因:`availableModels` 是跨 provider union +
   * 首见去重的扁平表,同一 model id 由多个 provider 提供时归属已丢,按 id 回查会命中
   * 另一条路由的元数据 —— 拿错路由的上限去收敛比不收敛更糟。收敛统一走
   * maker-core 的 `AgentDeps.resolveVerifiedContextWindow`,由 host 按
   * (providerId, modelId) 解析。
   */
  contextWindowVerified?: boolean;
  /**
   * 该窗口值是否来自用户/预设**显式配置**(仅 buildUserProvider 生成;内置目录不设)。
   * 编辑表单回转配置时据此区分「显式填了 200K」与「缺省物化成的 200K」——不能靠与
   * 当前默认值等值判断:显式覆盖必须在未来默认升级后原样保留(PR review P1)。
   * 故意不纳入 modelSignature 一致性校验(固定 key 序里没有它)。与
   * `contextWindowVerified` 是两份独立的 provenance:后者只活在 host 目录里、供
   * `resolveVerifiedContextWindow` 收敛运行期窗口用,不进跨端 `ModelDescriptor`;
   * 这个字段专供 desktop 自定义 Provider 编辑表单的回转判定用。
   */
  contextWindowExplicit?: boolean;
  maxOutput?: number;
  /** 支持的 effort 档;空数组 = 不支持切换(如 Haiku / 部分 provider-managed 模型)。 */
  efforts: Effort[];
  /** Display-only known tiers. Runtime admission always uses efforts; absent tiers render disabled. */
  displayEfforts?: Effort[];
  /** 独立 Pi 远端目录的显式能力;缺席时保留旧目录兼容行为。 */
  reasoning?: boolean;
  reasoningEfforts?: PiReasoningEffort[];
  reasoningDefaultEffort?: PiReasoningEffort;
  /**
   * Model-specific effort 显示名覆盖(= maker-core ModelDescriptor.effortDisplayNames)。
   * 缺省时回退统一档名词表(桌面 i18n `effortLevels.*` / 手机 MOBILE_EFFORT_LABELS)→
   * agent 级 effortLevels。当前 catalog 无覆盖项(2026-07 档名统一后清空),机制保留。
   */
  effortDisplayNames?: Partial<Record<Effort, string>>;
  /** 默认 effort;null = 不支持。 */
  defaultEffort: Effort | null;
  /**
   * true = 该 (provider, agent) 下没有任何来源声明过推理档位:用户/运行时没填 reasoning,
   * 目录、发现元数据与用户元数据也都没有 efforts。此时 `efforts: []` 只是占位,不等于
   * 「明确无档位」(reasoning:false 或已声明空列表);准入校验不得据此把显式档位判成
   * valid: none(#5535)。Pi 不标记:Pi 运行时按 efforts 物化 reasoning,自定义 Pi 模型
   * 在显式开启前就是非推理模型,放行的档位不会生效。
   */
  effortsUnknown?: boolean;
  /** 思考只有开/关两档时,选择器显示开关而不是档位列表。 */
  thinkingToggle?: boolean;
  /**
   * 该模型在**该 (provider, agent) 下**是否支持 Fast Mode —— Fast 能力的**唯一真相**。
   *
   * 因为模型按 (provider, agent) 嵌套(见 Provider.models),本字段天然 per-provider:
   * **同一 model id 在不同 provider 下取值可以不同**,用来表达「这个来源能不能真正交付 fast」。
   * 典型:opus 走官方 Anthropic 直连可 fast ⇒ 该条目 `true`;某网关会剥掉承载 fast 的请求字段
   * (cc 的 `anthropic-beta` 头 / codex 的 `serviceTier`)⇒ 那个 provider 下的同名条目应配 `false`。
   * 故意**不纳入** catalog.ts 的跨供应商一致性校验(`modelSignature`),正是为放行这种分叉。
   *
   * **是否真的显示开关还要叠上 agent 运行时粗粒度 gate**:
   * 实际可用 = `model.supportsFastMode && agent.capabilities.hasFastMode`。UI 取实际可用性时
   * 必须按「当前生效来源」现查本字段(见 registry.ts `sessionModelSupportsFastMode`),
   * 不能读跨 provider 拍平去重后的列表(那只保留首个 provider 的值,会错)。
   */
  supportsFastMode?: boolean;
  /** Account-discovered Ultrafast access. Never inferred from a model name or plan label. */
  supportsUltrafastMode?: boolean;
  /** Same-provider, same-harness catalog model used for Fast. null explicitly disables mapping.
   * Unlike a service tier, this changes the upstream model; availability must be checked per account.
   */
  fastModelId?: string | null;
  /**
   * 该模型在 Codex 下使用的模型级兼容 bridge 协议。
   *
   * 通常 wire protocol 由 Provider.routing.codex 决定;只有同一 Provider 内不同模型
   * 需要走不同 Codex wire 时才写本字段。典型是 XD:服务端原生声明 Codex 的模型走
   * Responses,只声明 Claude Code 的模型投影进 Codex 后走 Anthropic Messages bridge。
   *
   * 这是按 agent 嵌套的目录元数据,不代表模型能力;缺省时回落 Provider 级路由。
   */
  codexCompatibilityWireProtocol?: CodexCompatibilityWireProtocol;
  /**
   * 展示图标 id —— 模型行 / composer 药丸上显示什么图标,**以 AI Gateway / 目录设定为准**
   * (XD 模型经 model-access-server GET /models 下发,其它供应商可由 OSS 目录配置)。
   * 已知取值见 sections.ts `resolveModelIconKind`('claude' | 'codex' | 'cindy' 及别名);
   * 缺省或未知值 ⇒ 客户端回落该行来源供应商标(ProviderMark),桌面与手机同一套规则。
   * 故意**不纳入** `modelSignature` 跨供应商一致性校验:同一 model id 在不同供应商下
   * 允许配不同图标(与 supportsFastMode / defaultEnabled 同理)。
   */
  icon?: string;
  cost?: ModelCost;
  modalities?: { input: string[]; output: string[] };
  capabilities?: {
    reasoning?: boolean;
    toolCall?: boolean;
    attachment?: boolean;
    temperature?: boolean;
  };
  releaseDate?: string;
  /**
   * 生命周期状态。'retired' 是**客户端本地**取值:wire(服务端 Catalog/CatalogModel)
   * 永远不下发它——registry 的 retired 条目由服务端投影时剔除、由客户端在合并期把
   * 「discovery 仍能发现但远端已判死」的条目标记为 'retired',供 modelList 准入过滤
   * (新选择禁止,keepSelected 运行会话豁免;完整 local addition 可显式复活)。
   */
  status?: "active" | "alpha" | "deprecated" | "retired";
  /**
   * 该模型在「设置 → 模型供应商」展开列表里**默认是否开启显示**(缺省 ⇒ true,即默认开)。
   *
   * 这是**系统默认值**,不是用户选择:用户在设置页的开关是本地 override(见 renderer 的
   * modelVisibilityPrefs),未被用户显式 override 的模型跟随本字段。语义天然 per-agent ——
   * 模型已按 agent 嵌套在 `Provider.models[agent]` 下,同名模型(如 gpt-5.5 在 cc / codex)
   * 各写各的默认。设为 false = 该模型默认不出现在模型选择器,用户可在设置页手动打开。
   *
   * 故意**不纳入** catalog.ts 的 `modelSignature` 跨供应商一致性校验:同一 model id 在不同
   * 供应商下可有不同默认(如某来源默认隐藏长尾模型),与「运行时元数据必须一致」是两回事。
   * 新增模型缺省 = 默认开,符合「未自定义用户随版本吃到新默认」(CLAUDE.md 规则 20)。
   */
  defaultEnabled?: boolean;
  /**
   * 该模型是哪些 agent 的**新对话默认种子**(cold-start seed),与 `sortOrder`(只管选择器
   * 陈列顺序)和 `defaultEnabled`(只管可见性)独立。桌面运行时只从**区域门控后的**
   * model-access `/models` v2 响应写入本字段;公共 Registry 的同名策略字段由 server 消费,
   * `modelPlanePolicy` 刻意不把它投影进 CatalogModel,避免 Global 绕过区域门。
   *
   * 渲染层优先取被标记、当前可用且默认可见的模型;无标记时回退 `sortOrder` 第一。
   * v3 可显式标记 'claude-code'、'codex' 或 'pi';客户端不跨 Agent 投影。缺省 = 不作为默认。
   * 故意**不纳入** `modelSignature` 跨供应商一致性校验:同一 id 在不同供应商下可各自表态。
   */
  newSessionDefault?: AgentKind[];
  /**
   * 该来源下的模型是否已由用户确认支持图片输入。目前只供 Pi 自定义 provider 使用;
   * 缺省按 false 处理,避免把纯文本端点误报成视觉模型。它是 per-provider 能力,不参与
   * `modelSignature` 的同 id 跨供应商一致性校验。
   */
  supportsImageInput?: boolean;
  /**
   * **视图层字段**:该 (供应商, 模型) 已被用户「停用」(准入关,与 `defaultEnabled` 的
   * 「显示」轴正交)。由 `buildRegistry` 按 host 注入的 ModelDisableOverrides 填充,
   * 目录数据本身**不携带**本字段,也不参与 `modelSignature` 一致性校验。
   *
   * 语义:停用 = 不可被任何新路由选中(选择器 / worker 创建 / MCP 点名 / IM 兜底),
   * 由 modelList.ts 的标准派生统一过滤;已在运行的会话不受影响(keepSelected 豁免)。
   * 与「隐藏」(defaultEnabled/visibility override,仅陈列过滤、点名与兜底仍可用)不同。
   */
  disabled?: boolean;
}

/** Provider 自己执行的媒体模型;modalities 是能力判断的唯一依据。 */
export interface ProviderMediaModel extends Pick<
  ModelMetadata,
  "mode" | "description" | "group"
> {
  nativeApi?: import("./modelAccessBean.js").ModelNativeApi | null;
  discoveredMetadata?: ModelMetadata;
  /** Local projection provenance; not part of the public Registry metadata. */
  sourceAgent?: AgentKind;
  /** Same-provider display-only pricing; never inherited through public model metadata. */
  displayPricing?: ModelDisplayPricing;
  currency?: 'USD' | 'CNY';
  costDiscount?: number;
  id: string;
  name: string;
  availability?: "available" | "requires_payment";
  modalities?: { input: string[]; output: string[] };
  officialDocs?: string;
  disabled?: boolean;
  /** Follows the chat display axis: omitted/true is shown, false waits for an explicit switch. */
  defaultEnabled?: boolean;
}

/** 供应商定义。 */
export interface Provider {
  /** 'anthropic' | 'openai' | 'xd' | 未来自定义 id。 */
  id: string;
  /** 展示名。 */
  name: string;
  /** 内置 / 用户自定义 / 企业下发。企业连接走自定义路由,但不能当个人连接编辑。 */
  source: ProviderSource;
  /** ★这家能用在哪些 agent;决定它出现在哪个 agent 的来源列表里 + 路由按哪个 agent 取。 */
  agents: AgentKind[];
  /**
   * 用户连接方式(连接 UI 用)。`method: 'oauth'` 且带 `oauth` 描述符 = 走 host 通用
   * OAuth Runner(generic-oauth);不带描述符的 oauth 供应商 = host bespoke 鉴权
   * (anthropic / openai / xai 现状)。
   */
  auth: { method: AuthMethod; oauth?: OAuthProviderDescriptor; native?: NativeSubscriptionAuth };
  /** 用户使用该供应商时的额度来源;旧目录可缺省,由 source 从 bundled 同 id 条目补齐。 */
  access?: ProviderAccess;
  /**
   * 该供应商用于「起会话标题」一次性轻任务的最经济模型 id(须存在于本供应商任一 agent 的
   * `models` 里)。host 侧标题 oneShot(见 apps/desktop title-one-shot)按本字段选模型、取该
   * 模型在目录里的最低 effort 档、走单次 HTTP 请求生成标题。缺省 = 该供应商不参与智能起名
   * (调用方回落到「消息前 N 字」启发式)。
   */
  titleModel?: string;
  /** ★路由描述符,按 agent 索引(供应商可同时供多个 agent)。 */
  routing: Partial<Record<AgentKind, RoutingDescriptor>>;
  /**
   * ★该供应商提供的模型清单,**按 agent 分组**(同 id 在不同 agent 下元数据可不同,
   * 如 gpt-5.5 cc=1M / codex=272k)。`agents` 里声明的每个 agent 都应有对应数组(见 catalog.ts 校验)。
   */
  models: Partial<Record<AgentKind, CatalogModel[]>>;
  /**
   * 该供应商提供的**图像生成/编辑模型**清单(不挂 agent——图像模型不经
   * agent runtime,由主机图像通道直调)。与聊天模型同一目录同一热更机制:
   * 消费方为意识 cindy 槽(白名单 + 详情页下拉)。
   * 可选字段,additions-only,老版本 App 忽略之。
   * `disabled` 是视图层字段(与 CatalogModel.disabled 同语义):buildRegistry 按用户
   * 停用 override 烘焙,设置页据此渲染专属媒体条目的停用状态;目录数据本身不携带。
   */
  imageModels?: ProviderMediaModel[];
  /**
   * 图像能力的默认选型(与 imageModels 配套;值必须是 imageModels 里的 id):
   * - standard:未指定任何偏好时的默认模型(意识 cindy 槽"默认"档的真身);
   * - draft / best:档位意图的翻译表(缺省回落 standard)。
   * 默认选型是主机资产:改这里(OSS 热更)即可整体切换所有"跟随默认"的
   * 消费方,代码零模型字面量。
   */
  imageDefaults?: { standard: string; draft?: string; best?: string };
  /**
   * 该供应商提供的**视频生成/编辑模型**清单(与 imageModels 同地位:
   * 不挂 agent,由主机视频通道直调,id 即 video provider 层的 alias)。
   * 消费方为意识 cindy 槽(白名单 + 详情页下拉)。可选,additions-only。
   * `disabled` 同 imageModels:视图层停用标志,buildRegistry 烘焙。
   */
  videoModels?: ProviderMediaModel[];
  /** Speech, transcription and realtime audio; each entry retains its explicit mode. */
  audioModels?: ProviderMediaModel[];
  /**
   * 视频能力的默认选型(与 videoModels 配套;值必须是 videoModels 里的 id;
   * 语义同 imageDefaults:standard 必填,draft/best 缺省回落 standard)。
   */
  videoDefaults?: { standard: string; draft?: string; best?: string };
  /**
   * 该供应商提供的**文本向量(embedding)模型**清单(与 imageModels 同地位:
   * 不挂 agent,由主机 embedding 通道直调)。消费方为意识 cindy 槽的向量代办
   * (白名单 + 详情页下拉)。可选,additions-only。
   *
   * 与聊天模型清单里被 `classifyModel` 归到 `'embedding'` 的条目**不是同一回事**:
   * 那些是网关多返回的、不能当 agent 用的条目(设置页折叠在「向量」分组里供
   * 用户停用);本字段是"哪些型号可以被当作向量能力的后端派单",要显式声明。
   * `disabled` 同 imageModels:视图层停用标志,buildRegistry 烘焙。
   */
  embeddingModels?: ProviderMediaModel[];
  /**
   * 向量能力的默认选型(与 embeddingModels 配套;值必须是 embeddingModels 里的
   * id;语义同 imageDefaults:standard 必填,draft/best 缺省回落 standard)。
   *
   * 注意向量与图像/视频的一处本质差异:**换模型 = 换向量空间**。跟随默认的
   * 消费方在这里被热更换掉型号后,它此前存下的向量与新向量不可比 —— 所以
   * 改这个值不像改 imageDefaults 那样无痛,消费方必须自己记住"这批向量是哪个
   * 模型算的"并在不一致时重嵌(主机侧 chat-history-embedder 就是钉死常量而
   * 不跟随默认的)。
   */
  embeddingDefaults?: { standard: string; draft?: string; best?: string };
}

/**
 * 供应商预设 / 用户自定义 runtime 的模型配置。
 *
 * contextWindow 缺省时由 `buildUserProvider` 使用保守默认;预设可显式携带厂商文档确认的值,
 * 并随用户配置持久化,避免已知长上下文模型被错误降级。
 */
export interface ProviderRuntimeModelConfig extends ModelMetadata {
  /** User override; absent follows the directory. Never persist derived snapshots. */
  interfaceId?: string;
  interfaceUnavailable?: boolean;
  selectedInterface?: ModelInterfaceSnapshot;
  availableInterfaces?: ModelInterfaceSnapshot[];
  /** Current account discovery only; deliberately excluded from inheritable ModelMetadata. */
  supportsUltrafastMode?: boolean;
  discoveredMetadata?: ModelMetadata;
  discoveredCost?: ModelCost;
  nameExplicit?: boolean;
  id: string;
  name: string;
  /** Per-model PI protocol override; provider wireProtocol remains the fallback. */
  /** Upstream execution API, shared by Claude Code, Codex and Pi. */
  api?: PiModelApi;
  piApi?: PiModelApi;
  /** 同一 runtime 内该模型的上游覆盖;缺省使用 runtime 级路由。 */
  route?: ProviderModelRouteConfig;
  contextWindow?: number;
  /** 模型未被用户显式开关时的可见性;缺省保持历史行为(默认可见)。 */
  defaultEnabled?: boolean;
  /** Pi 自定义模型是否支持原生图片输入;缺省保守视为不支持。 */
  supportsImageInput?: boolean;
  /** 该 runtime 模型是否支持 reasoning;缺省表示未声明(由投影层决定 fallback)。 */
  reasoning?: boolean;
  /**
   * 该 runtime 模型明确支持的推理强度。仅在 `reasoning: true` 时有效;不从模型名、协议或
   * provider 类型猜测,避免把 UI 可选档位导出给实际不支持 reasoning 的端点。
   */
  reasoningEfforts?: PiReasoningEffort[];
  /** 该 runtime 模型的推荐默认推理强度;必须包含在 reasoningEfforts 中。 */
  reasoningDefaultEffort?: PiReasoningEffort;
  /** 思考只有开/关时走开关 UI。 */
  thinkingToggle?: boolean;
}

/**
 * 预设推荐模型:三个引擎共用一份清单,数组顺序即推荐顺序(见 `expandPresetModels`)。
 * 引擎间确有差异时用 `engines` / `engineOverrides` 显式声明,不再为每个引擎各写一份。
 */
export interface ProviderPresetModel extends ProviderRuntimeModelConfig {
  /** 只在这些引擎可用(如协议限制);缺省 = 预设声明的全部引擎。 */
  engines?: AgentKind[];
  /** 引擎专属字段(如 Pi 的推理档位、按模型路由),展开时覆盖共用字段。 */
  engineOverrides?: Partial<Record<AgentKind, Partial<ProviderRuntimeModelConfig>>>;
}

/**
 * 供应商预设的单 runtime 预填数据(「从模板创建自定义供应商」用)。
 * 形状对齐 `CustomProviderRuntimeConfig`:选中预设 = 把这段数据灌进创建表单,用户只补 API key。
 */
export interface ProviderPresetRuntime {
  /** 上游 wire protocol;缺省由 runtime agent 推导(Codex=Responses,Claude=Messages)。 */
  wireProtocol?: ProviderWireProtocol;
  /** 该 runtime 的兼容端点 base URL(cc=Anthropic 兼容 / codex=OpenAI Responses 兼容)。 */
  baseUrl: string;
  /** 非标准推理端点的相对路径;缺省由 wire protocol 推导。 */
  requestPath?: string;
  /** Codex Responses runtime 是否支持原生图片生成与编辑;缺省为 false。 */
  supportsImageGeneration?: boolean;
  /** 推荐模型清单(预填进表单,用户可增删改)。 */
  models: ProviderRuntimeModelConfig[];
  /** 可选预填请求头。 */
  headers?: Record<string, string>;
  /**
   * 可选的「列模型」端点(表单「获取模型列表」用;缺省由 baseUrl 推导 `…/v1/models`)。
   * 用于推理 baseUrl 与列模型端点不同源的厂商——如 Moonshot 的 cc baseUrl 是
   * `…/anthropic`,但列模型接口只在 `https://api.moonshot.cn/v1/models`(同一 key 可用)。
   */
  modelsUrl?: string;
  /** 绑定时除 runtime 主目录外追加拉取的模型目录。 */
  modelDiscovery?: ProviderModelDiscoverySource[];
  /**
   * 允许添加向导编辑预填 base URL。仅用于本机 / 自托管网关类预设;普通官方渠道保持只读,
   * 防用户无意改坏已核验端点。
   */
  baseUrlEditable?: boolean;
  /** 对应 `pi.dev/api/models/providers/<id>`;创建连接时快照,旧连接不自动补。 */
  piCatalogProviderId?: string;
}

/**
 * 供应商预设 —— 降低自定义供应商接入摩擦的**纯 UI 模板数据**(不参与路由 / 不是 Provider)。
 *
 * 与 `Provider` 的区别:预设只在「创建自定义供应商」对话框里消费,选中即快照进用户自己的
 * `CustomProviderConfig`,地址与用户修改保持不变;新建连接可通过 catalogPresetId 继承当前模型默认资料。
 * 数据随目录走 OSS 热更:各家 baseUrl / 模型 id 变化只需推数据,无需发版。
 */
export interface ProviderPreset {
  /** 预设 id(小写 slug,仅用于 UI 去重 / 埋点,不占用 provider id 命名空间)。 */
  id: string;
  /** 展示名(如 "OpenRouter" / "DeepSeek")。 */
  name: string;
  /**
   * 国际化展示名(可选):`name` 为中文的国内厂商预设(如「智谱 GLM(中国大陆)」)
   * 在非中文 UI 用它展示,缺省回落 `name`。展示选择见 `presetDisplayName`。
   */
  nameEn?: string;
  /** 繁体中文展示名(可选):仅 `zh-TW` UI 使用,缺省回落 `name`。 */
  nameZhTW?: string;
  /** 官方接入文档链接(表单里展示可点)。 */
  docsUrl?: string;
  /**
   * 区域提示(可选):'cn' = 中国大陆端点,'global' = 国际端点。
   *
   * **只影响呈现排序,不是过滤开关**:UI 按客户端构建区域智能排序(cn/dev 版本 cn 靠前,
   * global 版本 global 靠前,见 `sortPresetsForRegion`),两边始终都可见可选——用户永远
   * 不需要回答「你在哪个地区」,可达性由「测试连接」实测裁决。缺省 = 区域中立
   * (单端点全球服务的厂商,如 OpenRouter / DeepSeek),排序时居中。
   */
  regionHint?: "cn" | "global";
  /**
   * 预设的鉴权形态。缺省 = API key;`none` 用于明确不要求客户端凭证的本机 / 自托管代理。
   * 创建后会快照进 CustomProviderConfig,不随预设后续更新。
   */
  authMethod?: "apiKey" | "none";
  /**
   * 目录源数据里的共用推荐模型清单。加载时由 `expandPresetModels` 展开进各
   * `runtimes[agent].models` 并删除本字段;下游始终只读展开后的形状,旧格式照常可用。
   */
  models?: ProviderPresetModel[];
  /** per-runtime 预填数据(至少一个)。 */
  runtimes: Partial<Record<AgentKind, ProviderPresetRuntime>>;
}

/** 客户端实际构建区域;模型预设排序只看该版本身份,不看 UI 语言。 */
export type PresetSortRegion = "cn" | "global" | "dev";

/** 完整目录(OSS / 本地 / 内置 三处都是这个形状)。 */
export interface Catalog {
  /** 目录版本号(语义随意,仅用于诊断 / 缓存比对)。 */
  version: string;
  providers: Provider[];
  /**
   * 自定义供应商创建模板(可选)。容错语义:解析时逐条校验、坏条目丢弃(见 catalog.ts
   * `sanitizePresets`),绝不因预设数据错误导致整份远端目录回退 bundled。
   */
  presets?: ProviderPreset[];
  /**
   * Cindy 公共模型注册表:统一承载 canonical id、runtime 路由别名、能力元数据与
   * 厂商公开参考价。它不决定某个账号实际可用哪些模型,也不覆盖 Cindy AI Gateway
   * 的实时售卖价;动态发现与 `/api/model-access/models` 仍分别是两类事实的权威。
   */
  modelRegistry?: ModelRegistry;
}

/**
 * 用户自定义供应商在**单个 runtime(agent)下**的配置(不含密钥)。
 *
 * 一个 baseURL 通常只说一种协议:Claude Code↔Anthropic / Codex↔OpenAI。某厂商若同时提供
 * 两种端点,则两个 runtime 各有独立的 baseURL / 模型 / headers(见 CustomProviderConfig.runtimes)。
 */
export interface CustomProviderRuntimeConfig {
  /** Follow current model defaults from this preset while its endpoint/protocol still match. */
  catalogPresetId?: string;
  /** 上游 wire protocol;缺省由 runtime agent 推导(Codex=Responses,Claude=Messages)。 */
  wireProtocol?: ProviderWireProtocol;
  /** 该 runtime 的兼容上游 base URL(cc=Anthropic 端点 / codex=OpenAI 端点)。 */
  baseUrl: string;
  /** 非标准推理端点的相对路径;缺省由 wire protocol 推导。 */
  requestPath?: string;
  /** Codex Responses runtime 是否支持原生图片生成与编辑;缺省为 false。 */
  supportsImageGeneration?: boolean;
  /** Opt-in to standalone OpenAI Images generation/edits on this runtime's connection. */
  imageApi?: "openai-images";
  videoApi?: "xai-videos";
  /** 用户模型;contextWindow 可由预设带入,缺省时由 `buildUserProvider` 补保守默认。 */
  models: ProviderRuntimeModelConfig[];
  /**
   * 可选自定义请求头。运行时配置会从 main-only safeStorage 临时 hydrate;值不写
   * custom_providers SQLite,也不通过非可信 / 远程 provider:list 返回。
   */
  headers?: Record<string, string>;
  /** Transient non-secret state; main normalization strips it before persistence. */
  headersState?: "configured" | "unknown";
  /**
   * 可选的「列模型」端点(「获取模型列表」按钮用;缺省由 baseUrl 推导 `…/v1/models`)。
   * 从预设创建时随 `ProviderPresetRuntime.modelsUrl` 快照进来并持久化,编辑态仍可再拉。
   */
  modelsUrl?: string;
  /** Pi 官方模型目录 provider id;缺省保持历史手填/BYOM 行为。 */
  piCatalogProviderId?: string;
}

/**
 * 用户自定义供应商配置。runtime headers 仅在可信 main 运行期 hydrate,持久化时值在
 * safeStorage;其余字段写 localDb。
 *
 * 由 host 持久化(desktop: localDb `custom_providers` 表,按账号隔离),加载时经
 * `buildUserProvider`(见 user-provider.ts)展开成标准 `Provider`,与内置厂商同形状、
 * 进同一 active-catalog,供下游(路由 / 选择器 / listProviders)**统一消费**。
 *
 * **per-runtime 独立配置**:`runtimes` 按 agent 索引,每个 runtime 各有独立的 baseUrl /
 * 模型 / headers;用户在表单 Tab 里只配需要的那个,也可两个都配(该来源同时供两端)。至少一个。
 *
 * API key 与 headers 值都不进 SQLite:按 runtime 分别存 safeStorage。host 路由 resolve
 * 时按 (id, agent) hydrate;只有可信本机设置页可拿到 headers 以便编辑,远程和不可信
 * renderer 投影一律剥离。
 */
export interface CustomProviderConfig {
  /** 供应商 id,小写 slug(/^[a-z0-9_-]+$/),同账号内唯一,不撞内置 `anthropic|openai|xd`。 */
  id: string;
  /** 展示名。 */
  name: string;
  /**
   * 鉴权形态(可选,缺省 = API key,向后兼容历史配置)。
   * `method: 'oauth'` 时必须带完整 `oauth` 描述符——该供应商走 host 通用 OAuth Runner
   * 登录(凭证存 safeStorage `provider_oauth_<id>`),路由用 `oauth-token` 策略注入
   * Bearer;此形态下不再使用 per-runtime API key。
   */
  auth?:
    | { method: "apiKey"; oauth?: never; native?: never }
    | { method: "oauth"; oauth: OAuthProviderDescriptor; native?: never }
    | { method: "oauth"; native: NativeSubscriptionAuth; oauth?: never }
    | { method: "none"; oauth?: never; native?: never };
  /** per-runtime 独立配置(键为 agent,只含已配置的 runtime;至少一个)。 */
  runtimes: Partial<Record<AgentKind, CustomProviderRuntimeConfig>>;
}