Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
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>>;
}