Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* 供应商登记表(registry)—— 纯逻辑:合并连接状态、按 agent 算可见性、解析路由素材。
*
* 连接状态由 host 注入(XD: api_key 是否存在 / Anthropic: 是否有 claude.ai OAuth /
* OpenAI: codex 是否 OAuth 登录),本模块不读任何存储。
*
* SSoT:**目录就是 per-agent 模型清单的唯一来源**。模型按 agent 分组挂在
* `Provider.models[agent]` 下;host 从目录派生 maker-core 的 per-agent availableModels
* (不再有写死的 CLAUDE_MODELS / CODEX_MODELS)。因此本模块的查询都带 `agent` 维度:
* - 哪些供应商支持某 agent(来源栏可见性)
* - 某 (model, agent) 由哪些供应商提供(source 选择)
* - 解析 (provider, model, agent) → 路由素材(供 host 通用路由器落地)
*/
import type { Catalog, Provider, CatalogModel, AgentKind, RoutingDescriptor } from './types.js';
import {
isAgentSelectableModel,
isModelSelectableForNewRoute,
} from './classification.js';
import type { ProviderLogoKind } from './providerBranding.js';
import { isCindyAutoModelId, isCindyDistributedProvider } from './provider-identity.js';
import {
isModelDisabled,
isProviderDisabled,
type ModelDisableOverrides,
} from './disableOverrides.js';
/** 各供应商是否已连接,由 host 注入。 */
export type ConnectionState = Record<string, boolean>;
/**
* 动态清单发现的失败归因。
*
* 只有 live entitlement 证据依赖动态发现的供应商才会有(如 Anthropic 订阅)。
* Registry presence 可能仍让目录展示模型,但发现失败意味着当前账号尚未得到可用性
* 证明;UI 若继续说「已连接,正在发现模型」就是在骗用户。`kind` 决定 UI 说什么,
* `detail` 只进日志与诊断,不直接展示(可能含上游原始错误文本)。
*/
export interface ProviderModelDiscoveryFailure {
/**
* 归因分两类,决定 host 该不该自动重试(判定在 host 侧,见各供应商的 discovery 实现):
*
* **可能是暂时的 —— 值得重试**
* network —— 连不上(DNS 失败 / 连接被拒 / 链路不通)
* timeout —— 连上了但超时
* upstream —— 上游 5xx / 429 等服务端侧故障
*
* **确定性拒绝 —— 重试没有意义,只会把「被拒绝」拖成「一直在发现中」**
* regionBlocked —— 供应商不向当前所在地区提供服务(Anthropic 的
* `unsupported_country_region_territory`,400 / 403 都出现过,
* 必须读响应体判定而不是只看状态码)
* unauthorized —— 凭证被拒(401)
* forbidden —— 请求被拒但不是地域原因(如 Cloudflare 对代理 / VPN 出口的拦截)
* rejected —— 其它 4xx
* empty —— 正常答复但没有任何可用模型
*/
kind:
| 'network'
| 'timeout'
| 'upstream'
| 'regionBlocked'
| 'unauthorized'
| 'forbidden'
| 'rejected'
| 'empty';
/**
* 诊断用原文(上游响应体片段、errno、异常消息等),**只留在 Main 侧的日志与内存**。
* 绝不下发:见 ProviderModelDiscoveryFailureView。
*/
detail?: string;
/** ISO 时间戳,用于展示「最近一次尝试」。 */
at: string;
}
/**
* 跨进程 / device-link 下发的失败投影 —— 刻意剥掉 `detail`。
*
* `ProviderView` 会经 `maker:provider:list` 到达 renderer,并由 device-link 投影给配对的
* 控制端;而 `detail` 里可能是最多 2KB 的上游原始响应体(代理错误页、请求元数据等)。
* UI 只按 `kind` 渲染分类文案,没有任何理由把这些原文送出 Main。
*/
export type ProviderModelDiscoveryFailureView = Omit<ProviderModelDiscoveryFailure, 'detail'>;
/**
* 各供应商最近一次的清单发现失败,由 host 注入;成功即清除。
*
* 稀疏 map:只有 live entitlement 证据依赖动态发现且当前确实失败的供应商才有键,
* 缺省是 `{}`。
* 因此必须是 `Partial` —— 写成全量 `Record` 会让 `state[id]` 的类型谎称不可能是
* `undefined`,读 `.kind` 的调用方迟早在运行时炸。
*/
export type ModelDiscoveryFailureState = Partial<
Record<string, ProviderModelDiscoveryFailure | null>
>;
/** 供应商 + 连接状态。 */
export interface ProviderView extends Provider {
/** Host-owned subscription speed policy; absence means an unrelated provider or older host. */
subscriptionFastPolicy?: { allowFast: boolean; groupAllowsFast: boolean };
/** 本机是否允许同账号另一台电脑调用该供应商;缺省等同关闭。 */
remoteInvocationEnabled?: boolean;
/** Exact model IDs offered to remote Agents. Absent preserves the legacy unrestricted scope. */
remoteModelIds?: string[];
/** Definition remains available for adding a removed local connection again. */
removed?: boolean;
subscriptionAccount?: { source: 'local' | 'oauth' | 'unknown'; identity?: string; reconnectRequired?: boolean };
/** Public account identity and credential origin, never credential material. */
openAiAccount?: { source: 'local' | 'oauth' | 'unknown'; identity?: string; reconnectRequired?: boolean };
connected: boolean;
/** Ready media execution channels, independent of chat authorization. Absent on older hosts. */
availableMediaModelIds?: string[];
/** Non-secret presentation metadata resolved before routing details cross device-link. */
logoKind?: ProviderLogoKind;
/** 动态清单发现的最近一次失败(已剥掉 detail);成功或从未失败时缺席。 */
modelDiscoveryFailure?: ProviderModelDiscoveryFailureView;
/**
* 用户把该供应商整体「停用」(凭证保留;见 disableOverrides.ts)。`connected` 保持真实
* 连接态(设置页要如实展示凭证状态),但 `connectedProvidersForAgent` /
* `sourcesForModel` 会把 suspended 供应商从一切可路由集合里剔除 —— 对所有
* 选择器 / 路由 / IM / device-link 消费方,停用 ≙ 不可用。
*/
suspended?: boolean;
/**
* 该供应商名下的停用 override 总数(供应商级标志 + 全部逐模型条目)。与烘进模型
* 条目的 `disabled` 标志不同,它**包含指向已下架模型的陈旧条目**。设置页据此在
* 「目录里已无对应行」时仍展示组级「全部启用」恢复入口(configuration-and-
* overrides.md §4;PR #744 review 第二十六轮)。0 时缺席(纯附加字段,老端忽略)。
*/
disableOverrideCount?: number;
}
/**
* 失败态 → 可下发投影:显式丢弃 `detail`。
*
* 用解构而不是 `{ kind, at }` 手抄字段:将来给 failure 加新字段时,默认行为是「跟着下发」
* 而不是「被静默丢掉」,只有明确判定为敏感的才需要在这里追加剥离。
*/
function stripDiscoveryFailureDetail(
failure: ProviderModelDiscoveryFailure,
): ProviderModelDiscoveryFailureView {
const { detail: _detail, ...view } = failure;
return view;
}
/** 把目录与连接状态合成 registry。`access` = 用户的停用 override(见 disableOverrides.ts)。 */
export function buildRegistry(
catalog: Catalog,
connected: ConnectionState,
discoveryFailures: ModelDiscoveryFailureState = {},
access?: ModelDisableOverrides,
): ProviderView[] {
const disabledKeys = access?.disabledModels ? Object.keys(access.disabledModels) : [];
return catalog.providers.map((p) => {
const failure = discoveryFailures[p.id];
// 剥掉 detail 再下发:它可能是上游原始响应体,而这份视图会过 IPC 到 renderer、
// 再经 device-link 投影给配对控制端。UI 只用 kind。
const failureView = failure ? stripDiscoveryFailureDetail(failure) : null;
const suspended = isProviderDisabled(access, p.id);
// 该供应商名下的停用 override 总数(供应商级标志 + 全部逐模型条目)。与烘进
// 模型条目的 disabled 标志不同,它**包含指向已下架模型的陈旧条目** —— 设置页
// 据此决定是否展示「全部启用」组级恢复入口:目录漂移后 override 仍在、却没有
// 任何行可渲染时,恢复入口不能消失(PR #744 review 第二十六轮)。
const disableOverrideCount =
(suspended ? 1 : 0) + disabledKeys.filter((k) => k.startsWith(`${p.id}:`)).length;
// 停用标志烘焙进模型条目(视图层字段,见 CatalogModel.disabled):renderer 与
// device-link 控制端直接消费,不需要各自再查一份 override 表。**只有确实带停用
// 条目的供应商**才重建 models(按 key 前缀判;listProviders 是热路径,其余供应商
// 原引用透传零分配 —— PR #744 review)。前缀误命中(如 'a:' 命中 'a:b:model')只
// 多做一次无害映射,不影响正确性。
let models = p.models;
let mediaOverrides: Pick<Provider, 'imageModels' | 'videoModels' | 'audioModels' | 'embeddingModels'> = {};
if (disabledKeys.length > 0 && disabledKeys.some((k) => k.startsWith(`${p.id}:`))) {
const mapped: Provider['models'] = {};
for (const agent of Object.keys(p.models) as AgentKind[]) {
mapped[agent] = (p.models[agent] ?? []).map((m) =>
isModelDisabled(access, p.id, m.id) ? { ...m, disabled: true } : m,
);
}
models = mapped;
// 专属媒体清单(imageModels/videoModels/embeddingModels,不挂 agent)同样烘焙
// 停用标志:设置页据此渲染/切换只经这些清单下发的图像、视频、向量型号
// (PR #744 review;向量于 PR #1707 review 补入 —— 派生侧一直在读
// isModelDisabled,但设置页没有对应的行,等于停用轴有实现无入口,
// 用户没法单独拦住某个向量型号的付费调用)。
const mapMedia = (list: NonNullable<Provider['imageModels']>) =>
list.map((m) => (isModelDisabled(access, p.id, m.id) ? { ...m, disabled: true } : m));
mediaOverrides = {
...(p.imageModels ? { imageModels: mapMedia(p.imageModels) } : {}),
...(p.videoModels ? { videoModels: mapMedia(p.videoModels) } : {}),
...(p.audioModels ? { audioModels: mapMedia(p.audioModels) } : {}),
...(p.embeddingModels ? { embeddingModels: mapMedia(p.embeddingModels) } : {}),
};
}
return {
...p,
models,
...mediaOverrides,
connected: connected[p.id] ?? false,
...(suspended ? { suspended: true } : {}),
...(disableOverrideCount > 0 ? { disableOverrideCount } : {}),
...(failureView ? { modelDiscoveryFailure: failureView } : {}),
};
});
}
/** 该供应商的指定 runtime 是否可参与选择 / 路由。 */
function hasEnabledAgentRuntime(provider: Provider, agent: AgentKind): boolean {
const routing = provider.routing?.[agent];
return provider.agents.includes(agent) && routing !== undefined && routing.disabled !== true;
}
/** 该 agent 兼容的所有供应商(不论连接与否)—— 供应商页「可用」列表用。 */
export function providersForAgent(views: ProviderView[], agent: AgentKind): ProviderView[] {
return views.filter((p) => hasEnabledAgentRuntime(p, agent));
}
/**
* 该 agent 已连接的供应商 —— 模型选择器「来源栏」用。停用(suspended)的供应商不可
* 作为新路由,默认一并剔除。`includeSuspended` 保留 suspended 来源 —— 给**已建会话**
* 的鉴权/发送门禁用(运行中会话不因停用打断,门禁只回答「凭证还连着吗」,把停用当
* 未鉴权会误禁发送;PR #744 review 第十轮)。新路由消费方不要传。
*/
export function connectedProvidersForAgent(
views: ProviderView[],
agent: AgentKind,
opts: { includeSuspended?: boolean } = {},
): ProviderView[] {
// 两道正交的剔除:runtime 级 disabled(目录 routing 声明,上游 #526)与用户的
// 供应商级停用(suspended,model-disable-store)—— 任一命中都不可路由。
return views.filter(
(p) =>
p.connected &&
(opts.includeSuspended === true || !p.suspended) &&
hasEnabledAgentRuntime(p, agent),
);
}
/** 该供应商是否在某 agent 下提供某 model id。 */
export function providerOffersModel(provider: Provider, modelId: string, agent: AgentKind): boolean {
return (provider.models[agent] ?? []).some((m) => m.id === modelId);
}
/** 取某供应商在某 agent 下的模型元数据(找不到返回 undefined)。 */
export function getModel(
provider: Provider,
modelId: string,
agent: AgentKind,
): CatalogModel | undefined {
return (provider.models[agent] ?? []).find((m) => m.id === modelId);
}
/**
* 某个模型在某 agent 会话下的「可选来源」:支持该 agent 且提供该模型的供应商。
* `onlyConnected` 默认 true(选择器场景);false 则含未连接(用于"去连接"引导)。
* 注意:调用方应只对"对该 agent 有效"的模型(来自 maker-core availableModels)查询。
*/
export function sourcesForModel(
views: ProviderView[],
modelId: string,
agent: AgentKind,
opts: { onlyConnected?: boolean; includeDisabled?: boolean } = {},
): ProviderView[] {
const onlyConnected = opts.onlyConnected ?? true;
// suspended 供应商与**该来源下被停用的模型条目**默认出局:本函数的产出是
// 「可路由来源」(选择器 activeSourceId / effectiveSourceIdForModel / Fast 门控),
// 停用的那份拷贝即便凭证在场也不允许被路由到 —— 同 id 模型在 A 家停用、B 家
// 启用时,默认来源解析必须落到 B,而不是继续把 A 当候选(PR #744 review)。
// `includeDisabled` 保留停用条目(suspended / model.disabled)—— 给准入守卫
// (model-route-guard)推演「不考虑停用时会路由到谁」用,普通消费方不要传。
const includeDisabled = opts.includeDisabled === true;
return views.filter(
(p) =>
(includeDisabled || !p.suspended) &&
(!onlyConnected || p.connected) &&
hasEnabledAgentRuntime(p, agent) &&
providerOffersModel(p, modelId, agent) &&
(includeDisabled || getModel(p, modelId, agent)?.disabled !== true),
);
}
/**
* 同 sourcesForModel,但只保留该来源上**这个模型条目本身确实是聊天模型**的来源
* (issue #882 第 3 点,2026-07 review)。所有"这个来源能不能真的把这个模型发出去"
* 的判断——路由解析、发送前置校验(空来源拦截)、"选中来源已断连"提示——必须走
* 同一份口径,否则会出现 UI 说"能发"、resolveRoute 却解析不出可用来源的分裂状态。
* 只在裸 `sourcesForModel`(仅看 id 是否存在,不看 mode)不够用的场景才需要这个;
* 纯展示/设置页场景仍应直接用 sourcesForModel,不要在那里过度收紧。
*/
export function chatEligibleSourcesForModel(
views: ProviderView[],
modelId: string,
agent: AgentKind,
opts: { onlyConnected?: boolean; includeDisabled?: boolean } = {},
): ProviderView[] {
return sourcesForModel(views, modelId, agent, opts).filter((provider) => {
const model = getModel(provider, modelId, agent);
// provider-aware 谓词而非裸 isChatEligible:用户自定义供应商显式配置的模型带未知
// group,id 撞上能力启发式(如 flux-image-x)时不能被误杀(2026-07 review 第 25 轮)。
return (
model !== undefined &&
isAgentSelectableModel(model, { userProvider: provider.source === 'user' })
);
});
}
/**
* 某 agent 在已连接来源列表(rail)里的「原生默认来源 id」。
* 与模型选择器 activeSourceId 的 nativeDefault 口径一致:
* codex → 优先 openai,其次 xd,再兜底 rail 首项。
* cc + 其余 → 优先 xd,兜底 rail 首项。
* rail 为空(零已连接来源)→ null。
*/
export function nativeDefaultSourceId(rail: ProviderView[], agent: AgentKind | null): string | null {
if (rail.length === 0) return null;
const has = (id: string) => rail.some((p) => p.id === id);
if (agent === 'codex') return has('openai') ? 'openai' : has('xd') ? 'xd' : rail[0].id;
return has('xd') ? 'xd' : rail[0].id;
}
/**
* 解析某个会话当前 `(agent, model)` 真正可用的来源 id。
*
* 来源选择必须先收窄到「已连接且确实提供当前模型」的集合,再应用显式选择 / 原生默认:
* 否则当 XD key 被清除、但 OpenAI 仍连接时,Claude 会话会把 OpenAI 当成 agent 级兜底,
* 拼出「OpenAI 图标 + Opus」这种不可能路由。显式来源失效时返回 null,不替换账号;
* 唯一例外是 Auto(见 relocatedAutoSourceId)。当前模型没有任何已连接且可用于新路由的
* 来源时返回 null。retired tombstone 与本地 disabled 都不参与本函数;运行中会话的真实
* 来源展示必须改用 actualSourceIdForModel。
*/
export function effectiveSourceIdForModel(
views: ProviderView[],
providerId: string | null | undefined,
modelId: string,
agent: AgentKind,
): string | null {
const sources = chatEligibleSourcesForModel(views, modelId, agent).filter((provider) => {
const model = getModel(provider, modelId, agent);
return (
model !== undefined &&
isModelSelectableForNewRoute(model, { userProvider: provider.source === 'user' })
);
});
if (providerId) {
return sources.some((provider) => provider.id === providerId)
? providerId
: relocatedAutoSourceId(views, providerId, modelId, agent, sources);
}
return nativeDefaultSourceId(sources, agent);
}
/**
* Auto(isCindyAutoModelId)只按模型 ID 认:服务端可以把同一个 Auto 在 Cindy AI 与
* 企业号池供应商之间挪动(平台模型 ↔ 号池模型)。记住的来源是这两类之一、且已不再提供
* 该 Auto 时,改用当前提供它的那一家(同样限于这两类),不判失效。记住的来源仍列着该
* 模型(只是断连 / 停用)或是用户自己接的供应商时不改道,仍按显式来源失效处理。
*/
function relocatedAutoSourceId(
views: readonly ProviderView[],
providerId: string,
modelId: string,
agent: AgentKind,
sources: ProviderView[],
): string | null {
if (!isCindyAutoModelId(modelId)) return null;
const remembered = views.find((provider) => provider.id === providerId);
if (!remembered || !isCindyDistributedProvider(remembered)) return null;
if (providerOffersModel(remembered, modelId, agent)) return null;
return nativeDefaultSourceId(sources.filter(isCindyDistributedProvider), agent);
}
/**
* 已保存或运行中的路由(任务、伙伴模型链、IM 默认):服务端把其中的 Auto 挪到另一家
* Cindy 来源后,现在该走的来源;没挪动或不适用时返回 null。只在使用时解析,不改写保存的值。
* Pi 的 providerId=null 就是 Cindy AI 网关;其它引擎的 null 不一定落在 Cindy AI,不推断。
*/
export function movedCindyAutoSourceId(
views: readonly ProviderView[],
route: { agent: AgentKind; model: string; providerId: string | null },
): string | null {
if (!isCindyAutoModelId(route.model)) return null;
const remembered = route.providerId ?? (route.agent === 'pi' ? 'xd' : null);
if (!remembered) return null;
const effective = effectiveSourceIdForModel([...views], remembered, route.model, route.agent);
return effective && effective !== remembered ? effective : null;
}
/**
* 「实际路由口径」的来源解析:选择规则与 effectiveSourceIdForModel 相同,但**不**
* 剔除停用拷贝(includeDisabled rail)。给「展示一个已在运行的会话」用:运行中的
* 会话不因停用打断,实际路由层对隐式来源仍落原生默认、对显式来源仍用会话存的值 ——
* 图标 / 价格 / Fast / 选中行豁免必须跟实际路由一致,不能显示成准入过滤后的替代
* 来源(PR #744 review 第五轮)。**新路由选择**(新会话 / 切模型 / worker / schedule)
* 一律用 effectiveSourceIdForModel,不要用本函数。
*/
export function actualSourceIdForModel(
views: ProviderView[],
providerId: string | null | undefined,
modelId: string,
agent: AgentKind,
): string | null {
// Resume keeps disabled/retired copies, but never relaxes the agent/chat capability boundary:
// a catalog correction that reclassifies an id as image/audio must not make a running agent
// session dispatch into a non-chat endpoint.
const sources = chatEligibleSourcesForModel(views, modelId, agent, { includeDisabled: true });
if (providerId) return sources.some((provider) => provider.id === providerId) ? providerId : null;
return nativeDefaultSourceId(sources, agent);
}
/**
* 某 (provider, model, agent) 是否支持 Fast 模式 —— 纯函数,**Fast 能力的唯一真相**。
* 直接读该供应商在该 agent 下那个模型条目的 `supportsFastMode`(per-provider,见 CatalogModel)。
* 缺省 / 取不到 provider / 该来源不提供此模型 ⇒ false(不显示开关)。
*
* 实际可用 = `agent.hasFastMode && modelSupportsFastMode(...)`(agent 粗粒度 gate 由调用方叠加)。
* 注意:必须传入**具体某个 provider**的条目,不能用跨 provider 拍平去重后的模型(那只保留首个
* 供应商的值,遇到 per-provider 分叉会错)。
*/
export function modelSupportsFastMode(
provider: ProviderView | Provider | undefined,
modelId: string,
agent: AgentKind,
): boolean {
if (!provider) return false;
return !!getModel(provider, modelId, agent)?.supportsFastMode;
}
/**
* 会话维度的 Fast 门控:解析「当前生效来源」后,查该来源下这个模型的 `supportsFastMode`。
* 生效来源口径与模型选择器 activeSourceId 一致(显式 providerId 若已连接则用它,否则取该 agent 的
* nativeDefaultSourceId)。这样 providerId 为 null(未显式选源)时也能命中真实默认来源
* —— 例如 cc 默认源是 xd 网关(见 nativeDefaultSourceId),若该来源把某模型 fast 配为 false
* ⇒ 默认不显示,只有用户显式选到 fast 可用的来源(如官方 Anthropic)才显示。
*/
export function sessionModelSupportsFastMode(
views: ProviderView[],
providerId: string | null | undefined,
modelId: string,
agent: AgentKind,
): boolean {
const sourceId = effectiveSourceIdForModel(views, providerId, modelId, agent);
const effective = sourceId ? views.find((provider) => provider.id === sourceId) : undefined;
return modelSupportsFastMode(effective, modelId, agent);
}
/** 路由解析结果(喂给 host 通用路由器)。 */
export interface ResolvedRoute {
provider: ProviderView;
model: CatalogModel;
routing: RoutingDescriptor;
}
/**
* 解析 `{providerId, modelId, agent}` → 路由素材。
* 校验:provider 存在、该 agent ∈ provider.agents、provider 提供该 model、且声明了
* 该 agent 的 routing。任一不满足返回 null(调用方走兜底 / 报错)。
*/
export function resolveRoute(
views: ProviderView[],
providerId: string,
modelId: string,
agent: AgentKind,
): ResolvedRoute | null {
const provider = views.find((p) => p.id === providerId);
if (!provider) return null;
if (!provider.agents.includes(agent)) return null;
const model = getModel(provider, modelId, agent);
if (!model) return null;
const routing = provider.routing[agent];
if (!routing || routing.disabled) return null;
return { provider, model, routing };
}