Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { withClaudeProviderRuntime } from "./piProviderPresets.js";
/**
* 目录源解析与加载(纯逻辑,IO 由 host 注入,零 Electron / node 依赖)。
*
* - release / dev:优先从 Model Access 公共匿名接口拉取完整 Catalog;失败时回退旧 OSS 目录。
* - dev:仓库本地文件(`localPath`)优先,改了即时生效;否则同样走远端。
* - 兜底优先级:本地(dev) → 公共 API → 上次有效快照(LKG) → 旧 OSS → 内置 bundled。
*
* 目录每进程加载一次、存内存、**无 TTL**(由 host 的 active-catalog 在启动期 await 一次)。
* host 可注入按源隔离的 LKG 读写:启动仍先请求最新远端,只有远端失败才读缓存,所以不会
* 引入“新鲜窗口”;坏 JSON / 坏 schema 永不覆盖最后一份有效快照。
*
* 本模块不碰文件系统 / 网络 / userData——这些能力由 host 通过 `CatalogIO` 注入,
* 保证包可独立单测,也保证跨平台路径 / CORS 等细节留在 host。
*/
import { BUNDLED_CATALOG, parseCatalog } from "./catalog.js";
import {
compareModelRegistryRevisions,
decideModelRegistrySnapshot,
} from "./modelRegistry.js";
import type { AgentKind, Catalog, Provider, ProviderPreset } from "./types.js";
/** 公共模型目录 API 路径。发布版由 model-access-server 匿名提供完整 Catalog。 */
export const CATALOG_API_PATH =
"/api/model-catalog/catalog?registrySchemaVersion=6®istryMedia=1®istryLocalRuntimes=1";
/** 旧客户端目录的 OSS 相对路径。迁移期作为公共 API 失败后的兼容回退。 */
export const CATALOG_CFG_PATH = "/cfg/providers.json";
/** 整条远端 Catalog fallback 链共享的默认启动等待预算。 */
export const DEFAULT_REMOTE_CATALOG_BUDGET_MS = 15_000;
/** Only numeric catalog snapshots older than v3 predate the Pi preset metadata contract. */
const PI_RUNTIME_METADATA_CATALOG_VERSION = 3;
export interface CatalogSourceConfig {
/** 完整覆盖源 URL(env XDT_MODELS_URL);缺省使用公共 catalog API。 */
url?: string;
/** 公共 catalog API 基址(modelAccessApiBaseUrl)。 */
baseUrl?: string;
/** 迁移期旧 OSS/CDN 基址;公共 API 失败后读取 `${fallbackBaseUrl}/cfg/providers.json`。 */
fallbackBaseUrl?: string;
/** dev 本地文件路径(env XDT_MODELS_PATH);命中则只读它、不联网。 */
localPath?: string;
/** 整条远端 fallback 链共享的等待预算;缺省 15 秒。 */
remoteBudgetMs?: number;
/** 注入单调时钟(测试用);缺省 Date.now。 */
now?: () => number;
/** 关闭远端拉取(env XDT_DISABLE_MODELS_FETCH);不影响 localPath 覆盖。 */
disableFetch?: boolean;
}
export interface CatalogIO {
/** 拉取远端文本(host 用 electron net.request 绕 CORS;timeoutMs 为本次剩余共享预算)。 */
fetchText?: (url: string, timeoutMs: number) => Promise<string>;
/** 读本地文件(dev / localPath);不存在返回 null。 */
readFile?: (path: string) => Promise<string | null>;
/** 读取某远端 scope 的上次有效完整快照;不存在返回 null。 */
readCache?: (scope: string) => Promise<string | null>;
/**
* 原子保存某远端 scope 的完整有效快照。实现可在串行区内保留磁盘上的更新快照,
* 并返回最终胜出的文本,使调用方内存态与 LKG 使用同一版本。
*/
writeCache?: (scope: string, text: string) => Promise<string | void>;
/** 诊断日志(可选)。 */
log?: (
level: "info" | "warn" | "error",
msg: string,
meta?: Record<string, unknown>,
) => void;
}
export type CatalogLoadSource = "local" | "remote" | "cache" | "bundled";
export type CatalogCapabilityEvidence = "current" | "fallback";
export type CatalogXdMediaKind = "image" | "video" | "embedding";
const ALL_XD_MEDIA_KINDS: readonly CatalogXdMediaKind[] = [
"image",
"video",
"embedding",
];
export interface CatalogLoadResult {
catalog: Catalog;
/**
* Exact validated source snapshot before bundled compatibility backfill. `null` means no Cindy
* Server/local/LKG snapshot was accepted. Consumers must use this field, never `catalog`, when
* they need to distinguish an explicit source declaration from a bundled supplement.
*/
authorityCatalog: Catalog | null;
source: CatalogLoadSource;
/**
* `current` means this exact snapshot came from the configured current catalog source
* (or an explicit local override). `fallback` covers LKG, legacy OSS and bundled data,
* which may keep compatibility metadata but cannot prove current regional availability.
*/
capabilityEvidence: CatalogCapabilityEvidence;
/**
* XD media fields inherited from the bundled compatibility catalog rather than
* explicitly supplied by the current source. These fields still need the regional
* fallback projection even when the rest of the snapshot has current evidence.
*/
unverifiedXdMediaKinds: readonly CatalogXdMediaKind[];
}
function unverifiedXdMediaKindsForPrimary(
primary: Catalog,
): readonly CatalogXdMediaKind[] {
const xd = primary.providers.find((provider) => provider.id === "xd");
if (!xd) return ALL_XD_MEDIA_KINDS;
return xd.embeddingModels === undefined ? ["embedding"] : [];
}
// 去尾部斜杠。不用 /\/+$/ 正则——超长 '/' 串上会 O(n²) 回溯(CodeQL js/polynomial-redos)。
function trimTrailingSlashes(s: string): string {
let end = s.length;
while (end > 0 && s.charCodeAt(end - 1) === 0x2f) end -= 1;
return s.slice(0, end);
}
/** 解析主 catalog URL:显式 url 优先,否则 `${baseUrl}${CATALOG_API_PATH}`。 */
export function resolveCatalogUrl(cfg: CatalogSourceConfig): string | null {
if (cfg.url && cfg.url.trim()) {
const explicit = cfg.url.trim();
try {
const url = new URL(explicit);
if (url.pathname.endsWith("/api/model-catalog/catalog")) {
url.searchParams.set("registrySchemaVersion", "6");
url.searchParams.set("registryMedia", "1");
url.searchParams.set("registryLocalRuntimes", "1");
return url.toString();
}
} catch {
/* Existing fetch/error path reports malformed custom URLs. */
}
return explicit;
}
if (cfg.baseUrl && cfg.baseUrl.trim()) {
return trimTrailingSlashes(cfg.baseUrl.trim()) + CATALOG_API_PATH;
}
return null;
}
/** 解析迁移期旧 OSS 回退 URL。 */
export function resolveFallbackCatalogUrl(
cfg: CatalogSourceConfig,
): string | null {
if (!cfg.fallbackBaseUrl?.trim()) return null;
return trimTrailingSlashes(cfg.fallbackBaseUrl.trim()) + CATALOG_CFG_PATH;
}
/**
* The migration-only OSS snapshot used to carry cindyModelMeta beside the provider
* catalog. Strip that one retired block only at the legacy source boundary; canonical
* API, local dev files, and parseCatalog itself remain strict about unknown fields.
*/
function parseRemoteCatalog(
input: string,
allowLegacyModelMeta: boolean,
): Catalog {
if (!allowLegacyModelMeta) return parseCatalog(input);
const raw: unknown = JSON.parse(input);
if (!raw || typeof raw !== "object" || Array.isArray(raw))
return parseCatalog(raw);
// Keep every unknown field so parseCatalog can reject it; only the retired legacy block is
// exempt. A null-prototype destination makes special JSON keys such as `__proto__` ordinary
// own properties instead of invoking an inherited setter during the compatibility copy.
const migrated = Object.create(null) as Record<string, unknown>;
for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
if (key !== "cindyModelMeta") migrated[key] = value;
}
return parseCatalog(migrated);
}
/** Strip credentials and request-only URL parts before diagnostics leave this package. */
function catalogUrlForLog(value: string): string {
try {
const parsed = new URL(value);
parsed.username = "";
parsed.password = "";
parsed.search = "";
parsed.hash = "";
return parsed.toString();
} catch {
return "[redacted invalid catalog URL]";
}
}
function remoteErrorForLog(
error: unknown,
remoteUrl: string,
logUrl: string,
): string {
return String(error).split(remoteUrl).join(logUrl);
}
function numericCatalogVersion(version: string): number | null {
return /^\d+$/.test(version) ? Number(version) : null;
}
function allowsLegacyPiRuntimeBackfill(primary: Catalog): boolean {
const version = numericCatalogVersion(primary.version);
return version !== null && version < PI_RUNTIME_METADATA_CATALOG_VERSION;
}
/** 只给仍保持 bundled 鉴权与上游路由形状的旧条目迁移 access,不能仅凭 provider id 猜计费。 */
function allowsBundledAccessInheritance(
primaryAccess: Provider["access"],
bundledAccess: Provider["access"],
): boolean {
if (primaryAccess === undefined) return true;
if (bundledAccess === undefined || primaryAccess.kind !== bundledAccess.kind)
return false;
return (
primaryAccess.kind !== "subscription" ||
(bundledAccess.kind === "subscription" &&
primaryAccess.product === bundledAccess.product)
);
}
function legacyAccessFor(
primary: Provider,
bundled: Provider,
): Provider["access"] {
if (primary.auth.method !== bundled.auth.method) return undefined;
if (!allowsBundledAccessInheritance(primary.access, bundled.access))
return undefined;
const sharedAgents = primary.agents.filter((agent) =>
bundled.agents.includes(agent),
);
if (sharedAgents.length === 0) return undefined;
const sameRoutes = sharedAgents.every((agent) => {
const current = primary.routing[agent];
const baseline = bundled.routing[agent];
return (
current !== undefined &&
baseline !== undefined &&
current.upstream === baseline.upstream &&
current.authStrategy === baseline.authStrategy
);
});
return sameRoutes ? bundled.access : undefined;
}
/**
* 回填新增的 Responses custom-tool capability 只认同一条官方 Codex 路由。
* 旧远端快照没有这个 append-only 字段;同 id 但改变了鉴权或 upstream 的供应商可能具备
* 完全不同的协议能力,不能因为名字相同就套用 bundled 结论。
*/
function bundledResponsesCustomToolCapabilityFor(
primary: Provider,
bundled: Provider,
): boolean | undefined {
const current = primary.routing.codex;
const baseline = bundled.routing.codex;
if (
current === undefined ||
baseline === undefined ||
current.supportsResponsesCustomTools !== undefined ||
baseline.supportsResponsesCustomTools === undefined ||
primary.auth.method !== bundled.auth.method ||
current.upstream !== baseline.upstream ||
current.authStrategy !== baseline.authStrategy
) {
return undefined;
}
return baseline.supportsResponsesCustomTools;
}
/** 图片能力只可沿用到未声明 access,或仍明确属于同一 bundled 订阅的旧条目。 */
function allowsBundledImageInheritance(
primaryAccess: Provider["access"],
bundledAccess: Provider["access"],
): boolean {
if (primaryAccess === undefined) return true;
if (bundledAccess === undefined || primaryAccess.kind !== bundledAccess.kind)
return false;
return (
primaryAccess.kind !== "subscription" ||
(bundledAccess.kind === "subscription" &&
primaryAccess.product === bundledAccess.product)
);
}
/**
* 同 id preset 仍以远端为主;bundled 给远端仍保留的同 runtime / 同 model 回填缺失的
* contextWindow,并为旧 schema 中完全缺席的 Pi runtime 回填已核实能力。这样旧远端不会
* 把长上下文或 Pi 能力降级;已有 Pi runtime 与显式窗口仍完整由远端优先。
*/
function backfillPresetMetadata(
primary: ProviderPreset,
bundled: ProviderPreset,
allowLegacyPiBackfill: boolean,
): ProviderPreset {
let changed =
primary.nameZhTW === undefined && bundled.nameZhTW !== undefined;
const runtimes: ProviderPreset["runtimes"] = { ...primary.runtimes };
for (const [agent, runtime] of Object.entries(primary.runtimes) as [
AgentKind,
NonNullable<ProviderPreset["runtimes"][AgentKind]>,
][]) {
const bundledRuntime = bundled.runtimes[agent];
if (!bundledRuntime) {
runtimes[agent] = runtime;
continue;
}
const bundledModels = new Map(
bundledRuntime.models.map((model) => [model.id, model]),
);
let runtimeChanged = false;
const models = runtime.models.map((model) => {
const bundledContextWindow = bundledModels.get(model.id)?.contextWindow;
if (
model.contextWindow !== undefined ||
bundledContextWindow === undefined
)
return model;
runtimeChanged = true;
changed = true;
return { ...model, contextWindow: bundledContextWindow };
});
runtimes[agent] = runtimeChanged ? { ...runtime, models } : runtime;
}
// Pi runtime 是 2026-08 后新增的预设能力槽。旧远端目录没有表达“显式禁用 Pi”的
// 字段,缺席只代表旧 schema;对随包已核实的官方预设回填整段,避免远端 LKG 把
// DeepSeek/Kimi 的推理档位与视觉能力遮掉。远端一旦自行提供 Pi,仍完整优先。
if (
allowLegacyPiBackfill &&
primary.runtimes.pi === undefined &&
bundled.runtimes.pi !== undefined
) {
runtimes.pi = bundled.runtimes.pi;
changed = true;
}
return changed
? {
...primary,
...(primary.nameZhTW === undefined && bundled.nameZhTW !== undefined
? { nameZhTW: bundled.nameZhTW }
: {}),
runtimes,
}
: primary;
}
/**
* 把远端 / 本地目录与内置 bundled 合并:以输入目录为主,bundled 补它缺失的
* provider(按 id),并给旧目录中同 id provider 补缺失的 access 与媒体能力元数据。
* primary 明确提供的值(包括显式空媒体清单)永远优先,不被 bundled 覆盖。
*
* **顺序契约**:结果按 bundled 数组序稳定排列(anthropic → openai → xai → xd),
* bundled 之外的远端新增供应商按远端原序追加在后。v2 远端目录只承载 xai 段,
* 不排序的话 xai 会窜到首位,选择器分段顺序漂移。
*/
export function mergeWithBundled(primary: Catalog): Catalog {
const bundledById = new Map(BUNDLED_CATALOG.providers.map((p) => [p.id, p]));
const allowLegacyPiBackfill = allowsLegacyPiRuntimeBackfill(primary);
const withBundledMetadata = primary.providers.map((p) => {
const bundled = bundledById.get(p.id);
const bundledAccess = bundled ? legacyAccessFor(p, bundled) : undefined;
const bundledResponsesCustomToolCapability = bundled
? bundledResponsesCustomToolCapabilityFor(p, bundled)
: undefined;
if (!bundled) return p;
// Pi became a first-class provider runtime in catalog v3. Production may still serve a v2
// xAI block that is otherwise the same SuperGrok subscription provider; whole-provider
// primary precedence would hide the newer bundled Pi route and models. Backfill the runtime
// only for a proven legacy snapshot with the unchanged subscription identity. Any partial Pi
// declaration or changed auth/upstream remains authoritative and is never guessed through.
const inheritPiRuntime =
allowLegacyPiBackfill &&
p.id === "xai" &&
bundledAccess !== undefined &&
!p.agents.includes("pi") &&
p.routing.pi === undefined &&
p.models.pi === undefined &&
bundled.agents.includes("pi") &&
bundled.routing.pi !== undefined &&
bundled.models.pi !== undefined;
const inheritImage =
p.id === "xai" &&
p.imageModels === undefined &&
bundled.imageModels !== undefined &&
bundledAccess !== undefined &&
allowsBundledImageInheritance(p.access, bundledAccess);
const inheritVideo =
p.id === "xai" &&
p.videoModels === undefined &&
bundled.videoModels !== undefined &&
bundledAccess !== undefined &&
allowsBundledImageInheritance(p.access, bundledAccess);
// 向量清单与 xai 的图像清单同一个道理(PR #1707 review):xd 段的向量能力是
// 客户端新增的 bundled 元数据,而远端 / 本地目录里同 id 的 xd 可能还是升级前
// 的结构、根本没有 embeddingModels 这个字段。primary 整体优先的规则会让那份
// 旧结构把 bundled 的新字段整段遮掉 —— 结果是目录派生出空清单,设置页显示
// "无可用模型",所有 embed_text 直接 NO_CANDIDATE,能力等于没上线。
//
// 只在字段**缺席**时补,显式 `[]` 仍然是"这个供应商不提供向量"的停用语义,
// 与图像清单的既有契约一致。
const inheritEmbedding =
p.id === "xd" &&
p.embeddingModels === undefined &&
bundled.embeddingModels !== undefined &&
bundledAccess !== undefined &&
allowsBundledImageInheritance(p.access, bundledAccess);
const inheritResponsesCustomToolCapability =
bundledResponsesCustomToolCapability !== undefined;
if (
!(p.access === undefined && bundledAccess !== undefined) &&
!inheritPiRuntime &&
!inheritImage &&
!inheritVideo &&
!inheritEmbedding &&
!inheritResponsesCustomToolCapability
) {
return p;
}
return {
...p,
...(p.access === undefined && bundledAccess !== undefined
? { access: bundledAccess }
: {}),
...(inheritPiRuntime
? {
agents: [...p.agents, "pi" as const],
models: { ...p.models, pi: bundled.models.pi },
}
: {}),
...(inheritPiRuntime || inheritResponsesCustomToolCapability
? {
routing: {
...p.routing,
...(inheritPiRuntime ? { pi: bundled.routing.pi } : {}),
...(inheritResponsesCustomToolCapability
? {
codex: {
...p.routing.codex!,
supportsResponsesCustomTools:
bundledResponsesCustomToolCapability,
},
}
: {}),
},
}
: {}),
...(inheritImage
? {
imageModels: bundled.imageModels,
...(p.imageDefaults === undefined &&
bundled.imageDefaults !== undefined
? { imageDefaults: bundled.imageDefaults }
: {}),
}
: {}),
...(inheritVideo
? {
videoModels: bundled.videoModels,
...(p.videoDefaults === undefined &&
bundled.videoDefaults !== undefined
? { videoDefaults: bundled.videoDefaults }
: {}),
}
: {}),
...(inheritEmbedding
? {
embeddingModels: bundled.embeddingModels,
...(p.embeddingDefaults === undefined &&
bundled.embeddingDefaults !== undefined
? { embeddingDefaults: bundled.embeddingDefaults }
: {}),
}
: {}),
};
});
const primaryById = new Map(withBundledMetadata.map((p) => [p.id, p]));
// bundled 序在前(同 id 取 primary 内容),远端独有的追加在后(保持远端原序)。
const merged: Provider[] = BUNDLED_CATALOG.providers.map(
(bundled) => primaryById.get(bundled.id) ?? bundled,
);
for (const p of withBundledMetadata) {
if (!bundledById.has(p.id)) merged.push(p);
}
// presets 与 providers 同样按 id 合并:bundled 保序兜底,同 id 远端内容优先,
// 远端独有项按远端原序追加。避免旧远端的非空 presets 整段遮掉新版客户端内置条目。
const primaryPresets = primary.presets ?? [];
const bundledPresets = BUNDLED_CATALOG.presets ?? [];
const primaryPresetsById = new Map(
primaryPresets.map((preset) => [preset.id, preset]),
);
const bundledPresetIds = new Set(bundledPresets.map((preset) => preset.id));
const presets = bundledPresets.map((bundled) => {
const remote = primaryPresetsById.get(bundled.id);
return remote
? withClaudeProviderRuntime(
backfillPresetMetadata(remote, bundled, allowLegacyPiBackfill),
)
: bundled;
});
for (const preset of primaryPresets) {
if (!bundledPresetIds.has(preset.id)) presets.push(preset);
}
// modelRegistry 是带 updatedAt 的完整快照,不做逐字段拼接。远端比 bundled 旧时
// 保留新版客户端随包快照,避免复现 presets 曾出现的“旧远端遮掉新本地能力”;
// 远端较新时整份生效,继续支持 status=retired、route 删除和价格纠错。
const selectedRegistry = selectNewerModelRegistry(primary, BUNDLED_CATALOG);
return {
version: primary.version,
providers: merged,
...(presets && presets.length > 0 ? { presets } : {}),
...(selectedRegistry.modelRegistry
? { modelRegistry: selectedRegistry.modelRegistry }
: {}),
};
}
function log(
io: CatalogIO,
level: "info" | "warn" | "error",
msg: string,
meta?: Record<string, unknown>,
): void {
io.log?.(level, `[model-providers] ${msg}`, meta);
}
function registryUpdatedAt(catalog: Catalog): number | null {
const value = catalog.modelRegistry?.updatedAt;
if (!value) return null;
const timestamp = Date.parse(value);
return Number.isFinite(timestamp) ? timestamp : null;
}
function selectNewerModelRegistry(
primary: Catalog,
fallback: Catalog,
): { modelRegistry: Catalog["modelRegistry"]; fromFallback: boolean } {
if (primary.modelRegistry && fallback.modelRegistry) {
const relation = compareModelRegistryRevisions(
primary.modelRegistry,
fallback.modelRegistry,
);
if (
relation === "older" ||
relation === "conflict" ||
relation === "invalid-incoming"
) {
// 同 revision 异内容是非法重发;fallback 是已经随客户端发布/缓存验证过的
// LKG,启动期也必须保它,不能只在在线 refresh 路径防守。
return { modelRegistry: fallback.modelRegistry, fromFallback: true };
}
return { modelRegistry: primary.modelRegistry, fromFallback: false };
}
if (primary.modelRegistry) {
return { modelRegistry: primary.modelRegistry, fromFallback: false };
}
return {
modelRegistry: fallback.modelRegistry,
fromFallback: fallback.modelRegistry !== undefined,
};
}
/**
* modelRegistry is the only monotonic revision carried by the Catalog today. If it proves the
* LKG is newer, preserve that complete snapshot: combining its registry with older remote xAI
* providers/presets would create a catalog version that never existed and can reintroduce retired
* models. A future top-level Catalog revision may allow finer-grained arbitration.
*
* Equal `updatedAt` with different canonical registry content is an illegal republish
* (corrections must forward-fix with a higher updatedAt): keep the LKG snapshot so a
* quietly mutated remote revision can never win a tie. Callers log the conflict.
*/
function preserveNewerCachedCatalog(
remote: Catalog,
cached: Catalog,
): { catalog: Catalog; tieConflict: boolean } {
const decision = decideModelRegistrySnapshot(
remote.modelRegistry,
cached.modelRegistry,
);
if (decision === "preserve-current-conflict") {
return { catalog: cached, tieConflict: true };
}
if (decision === "preserve-current") {
return { catalog: cached, tieConflict: false };
}
return { catalog: remote, tieConflict: false };
}
/**
* 加载目录并返回实际命中的来源。返回值永远包含一个合法 Catalog(最差也回退内置
* bundled),不抛错。来源标记让手动刷新可以把 bundled fallback 视为失败并保留上次
* 有效快照;启动加载仍可通过 loadCatalog 接受 bundled 兜底。
*
* 顺序:
* 1. dev:cfg.localPath + io.readFile → 读本地、合并 bundled、直接返回(不联网)。
* 2. 远端依次尝试公共 API、迁移期旧 OSS;每个远端失败后先尝试它自己的 LKG。
* 3. 任意上述来源均不可用 → 内置 bundled。
*/
export async function loadCatalogWithSource(
cfg: CatalogSourceConfig,
io: CatalogIO,
): Promise<CatalogLoadResult> {
// 1) dev 本地文件优先(命中即用,不联网)。
if (cfg.localPath && io.readFile) {
try {
const text = await io.readFile(cfg.localPath);
if (text != null) {
const parsed = parseCatalog(text);
log(io, "info", "loaded catalog from local path", {
path: cfg.localPath,
});
return {
catalog: mergeWithBundled(parsed),
authorityCatalog: parsed,
source: "local",
capabilityEvidence: "current",
unverifiedXdMediaKinds: unverifiedXdMediaKindsForPrimary(parsed),
};
}
} catch (err) {
log(io, "warn", "local catalog read/parse failed, falling back", {
err: String(err),
});
}
}
// 2) 公共 model-access catalog API;迁移期失败后尝试旧 OSS 目录。
const url = resolveCatalogUrl(cfg);
const fallbackUrl = resolveFallbackCatalogUrl(cfg);
if (!cfg.disableFetch && io.fetchText) {
const remoteSources = cfg.url?.trim()
? url
? [{ url, allowLegacyModelMeta: false }]
: []
: [
...(url ? [{ url, allowLegacyModelMeta: false }] : []),
...(fallbackUrl
? [{ url: fallbackUrl, allowLegacyModelMeta: true }]
: []),
];
const now = cfg.now ?? Date.now;
const configuredBudget =
cfg.remoteBudgetMs ?? DEFAULT_REMOTE_CATALOG_BUDGET_MS;
const budgetMs = Number.isFinite(configuredBudget)
? Math.max(0, configuredBudget)
: 0;
const deadline = now() + budgetMs;
for (const source of remoteSources) {
let remoteUrl = source.url;
const { allowLegacyModelMeta } = source;
const logUrl = catalogUrlForLog(remoteUrl);
const remainingMs = Math.max(0, deadline - now());
if (remainingMs > 0) {
try {
let text = await io.fetchText(remoteUrl, remainingMs);
let parsed = parseRemoteCatalog(text, allowLegacyModelMeta);
// Older servers map an unknown schema to frozen V2. Negotiate V5 once
// within the same deadline and keep caches scoped to the actual response.
if (new URL(remoteUrl).searchParams.get('registrySchemaVersion') === '6' &&
(parsed.modelRegistry?.schemaVersion ?? 0) < 6) {
const legacyUrl = new URL(remoteUrl);
legacyUrl.searchParams.set('registrySchemaVersion', '5');
remoteUrl = legacyUrl.toString();
const retryBudget = Math.max(0, deadline - now());
if (!retryBudget) throw new Error('catalog negotiation budget exhausted');
text = await io.fetchText(remoteUrl, retryBudget);
parsed = parseRemoteCatalog(text, allowLegacyModelMeta);
}
let capabilityEvidence: CatalogCapabilityEvidence =
allowLegacyModelMeta ? "fallback" : "current";
// Never propagate the retired compatibility block into a newly written LKG.
let cacheText = allowLegacyModelMeta ? JSON.stringify(parsed) : text;
const remoteRegistryUpdatedAt = registryUpdatedAt(parsed);
if (io.readCache) {
for (const cacheUrl of new Set([remoteUrl, source.url])) {
try {
const cachedText = await io.readCache(cacheUrl);
if (cachedText !== null) {
const cached = parseRemoteCatalog(
cachedText,
allowLegacyModelMeta,
);
const selected = preserveNewerCachedCatalog(parsed, cached);
if (selected.catalog !== parsed) {
parsed = selected.catalog;
if (parsed.modelRegistry?.schemaVersion === 6) remoteUrl = source.url;
cacheText = JSON.stringify(selected.catalog);
capabilityEvidence = "fallback";
log(
io,
"warn",
selected.tieConflict
? "remote registry republished the same updatedAt with different content; keeping LKG"
: "remote catalog registry is older than LKG; preserving complete newer snapshot",
{
url: logUrl,
remoteUpdatedAt: remoteRegistryUpdatedAt,
cachedUpdatedAt: registryUpdatedAt(cached),
},
);
}
}
} catch (err) {
log(
io,
"warn",
"cached catalog could not be compared with remote snapshot",
{
url: logUrl,
err: remoteErrorForLog(err, remoteUrl, logUrl),
},
);
}
}
}
if (io.writeCache) {
try {
const committedText = await io.writeCache(remoteUrl, cacheText);
if (typeof committedText === "string") {
const committed = parseRemoteCatalog(
committedText,
allowLegacyModelMeta,
);
const selected = preserveNewerCachedCatalog(
parsed,
committed,
).catalog;
if (selected !== parsed) {
parsed = selected;
capabilityEvidence = "fallback";
log(
io,
"warn",
"serialized LKG commit preserved a newer catalog snapshot",
{
url: logUrl,
remoteUpdatedAt: remoteRegistryUpdatedAt,
committedUpdatedAt: registryUpdatedAt(committed),
},
);
}
}
} catch (err) {
log(
io,
"warn",
"valid remote catalog loaded but LKG write failed",
{
url: logUrl,
err: remoteErrorForLog(err, remoteUrl, logUrl),
},
);
}
}
log(io, "info", "loaded catalog from remote", { url: logUrl });
return {
catalog: mergeWithBundled(parsed),
// The migration OSS fallback is compatibility data, not the daily Cindy Server source.
authorityCatalog: allowLegacyModelMeta ? null : parsed,
source: "remote",
capabilityEvidence,
unverifiedXdMediaKinds:
capabilityEvidence === "current"
? unverifiedXdMediaKindsForPrimary(parsed)
: ALL_XD_MEDIA_KINDS,
};
} catch (err) {
log(io, "warn", "remote catalog read/parse failed, trying fallback", {
url: logUrl,
err: remoteErrorForLog(err, remoteUrl, logUrl),
});
}
} else {
log(
io,
"warn",
"remote catalog fallback budget exhausted, trying cache",
{
url: logUrl,
},
);
}
if (io.readCache) {
for (const cacheUrl of new Set([source.url, remoteUrl, source.url.replace('registrySchemaVersion=6', 'registrySchemaVersion=5')])) {
try {
const cached = await io.readCache(cacheUrl);
if (cached !== null) {
const parsed = parseRemoteCatalog(cached, allowLegacyModelMeta);
log(io, "info", "loaded last-known-good catalog snapshot", {
url: logUrl,
});
return {
catalog: mergeWithBundled(parsed),
// A cached legacy OSS snapshot stays below the local Pi protocol authorities.
authorityCatalog: allowLegacyModelMeta ? null : parsed,
source: "cache",
capabilityEvidence: "fallback",
unverifiedXdMediaKinds: ALL_XD_MEDIA_KINDS,
};
}
} catch (err) {
log(io, "warn", "cached catalog read/parse failed, trying fallback", {
url: logUrl,
err: remoteErrorForLog(err, remoteUrl, logUrl),
});
}
}
}
}
}
// 3) 兜底:内置 bundled。
log(io, "info", "using bundled catalog");
return {
catalog: BUNDLED_CATALOG,
authorityCatalog: null,
source: "bundled",
capabilityEvidence: "fallback",
unverifiedXdMediaKinds: ALL_XD_MEDIA_KINDS,
};
}
/** 启动期兼容入口:接受最终 bundled fallback,只返回目录快照。 */
export async function loadCatalog(
cfg: CatalogSourceConfig,
io: CatalogIO,
onResolved?: (result: CatalogLoadResult) => void,
): Promise<Catalog> {
const result = await loadCatalogWithSource(cfg, io);
try {
onResolved?.(result);
} catch {
// Compatibility callers expect this helper to return a valid catalog unconditionally.
// Hosts that need the metadata must default to fallback-safe behavior if observation fails.
}
return result.catalog;
}