Cindy 模型配置与下发全链路:Registry V6 维护手册与源码级实践

原创2026-10-27 07:03:582,902 阅读
文章标签:人工智能AI Agent代码智能体大模型AI 技能Agent 记忆工具调用MCP Clients多智能体浏览器控制GUI 自动化本地部署插件系统桌面应用移动开发前端跨平台语音任务调度交互助手

Cindy 模型配置与下发全链路:Registry V6 维护手册与源码级实践

本文以 docs/dev-rules/model-catalog-maintenance.md 为骨架,系统梳理 Cindy 的模型目录(Catalog)与模型注册表(Registry)从服务端正本到执行端活动目录的完整链路:数据流、字段归属、多接口模板、覆盖顺序、账号排序、预设格式、参考价与发布验收,并结合 packages/model-providers 的真实解析代码说明每条规则是如何被强制执行的。

读完后你应能独立完成这些工作:判断一个模型字段该写在哪个层级、安全地新增或撤回一条接入、在本地验证 V6 目录而不破坏用户配置,以及区分"客户端已实现""服务已部署""账号真实推理通过"这三个互不等价的状态。

一、数据流:一份目录如何变成一次可执行调用

模型配置的源头在独立的 Model Access Server 仓库(本文所述规则以当前 Cindy 仓库为准,不代表 Server 已部署)。服务端把随包目录与远程目录组装后由 /api/model-catalog/catalog 下发,执行端(Desktop 主机)加载并缓存,再合并连接实报与用户覆盖,得到"活动目录",最后分发给三类消费方:

Server 随包 / 远程目录 → /api/model-catalog/catalog
    → 执行端加载与缓存 → 合并连接实报、用户覆盖 → 活动目录
    ├─ 选择器 / 管理页
    ├─ 聊天 → Claude Code / Codex / Pi
    └─ 媒体 → 对应媒体通道

三个关键事实需要先建立:

  1. 聊天调用目标不是"模型名",而是三元组:连接 ID + 上游模型 ID + 引擎。同品牌多账号共用资料,但凭证、发现结果、用量与覆盖按连接隔离。
  2. Mobile / device-link 使用执行端目录,本地安装状态来自执行机器;控制端不会重新选路。目录声明也不等于账号准入或协议已实现。
  3. 目录存在 ≠ 可用。成员资格、鉴权、网络、真实推理是四道独立闸门,任一道没过都不构成"已支持"。

客户端侧真正发起请求的 URL 由 source.ts 固定拼接:

export const CATALOG_API_PATH =
  "/api/model-catalog/catalog?registrySchemaVersion=6&registryMedia=1&registryLocalRuntimes=1";
export const CATALOG_CFG_PATH = "/cfg/providers.json";

这三个查询参数不是装饰:registrySchemaVersion=6 请求 V6 注册表,registryMedia=1 请求媒体字段,registryLocalRuntimes=1 请求本地运行时(llama.cpp)字段。老服务端会返回更低版本,客户端在同一时间预算内重试一次 V5:

if (new URL(remoteUrl).searchParams.get('registrySchemaVersion') === '6' &&
    (parsed.modelRegistry?.schemaVersion ?? 0) < 6) {
  const legacyUrl = new URL(remoteUrl);
  legacyUrl.searchParams.set('registrySchemaVersion', '5');
  ...
}

来源回退顺序

loadCatalogWithSource 的回退链是严格有序的(见 source.ts):

开发本地文件(XDT_MODELS_PATH)→ 公共 API / 对应最后有效缓存(LKG)
  → 旧 OSS / 对应缓存 → 内置 bundled 目录
  • 开发本地文件命中即用,不联网,改了即时生效。
  • 整条远端链共享默认 15 秒预算(DEFAULT_REMOTE_CATALOG_BUDGET_MS),预算耗尽直接转缓存。
  • 缓存按实际 URL 变体隔离,因此 V6 与 V5 协商结果不会互相污染。
  • 远端 Registry 比 LKG 旧、或同 updatedAt 内容不同(非法重发)时,保留整份 LKG 快照,而不是把新 providers 与旧 registry 拼接:
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 };

这条"整份保留"策略很关键:Registry 是 Catalog 中唯一单调递增的 revision,混层会造出一个从未存在过的目录版本,从而把已退役的模型重新引入。

二、目录里到底有什么:三层逻辑结构

配置被拆成三个职责不同的块,理解它们的分工是后续所有维护动作的前提:

Catalog (version)
├─ providers[]                 内置接入、授权、routing、各引擎 models
├─ presets[].runtimes          新建连接的地址、协议和默认资料
└─ modelRegistry (schemaVersion / updatedAt)
   ├─ interfaceProfiles[]      V6:产品作用域内的接口模板
   ├─ baseModels[]             公共型号
   ├─ models[]                 接入条目:modelRef → baseModels;perAgent 与 routes 同级
   ├─ nativeApiRules[]         原生协议判定
   └─ localModels              候选包装 models[].variants[] + 推荐 featuredIds[]

当前仓库随包的离线文件是两个独立制品,注意不要混淆责任:

文件 承载内容 典型用途
catalog/providers.json providers / presets 内置供应商身份、routing、预设连接模板
catalog/model-registry.json modelRegistry 公共型号资料、接入条目、接口模板、价格、本地候选

以当前随包数据为例(catalog/model-registry.json)可以看到真实的规模与形状:schemaVersion: 6,包含 64 个 interfaceProfiles、146 个 baseModels、130 个 models、28 条 nativeApiRules,以及 localModels 本地域。一个 interfaceProfiles 条目大致如此:

{
  "id": "openrouter-anthropic-messages",
  "providerId": "openrouter",
  "api": "anthropic-messages",
  "baseUrl": "https://openrouter.ai/api",
  "inputBaseUrls": ["https://openrouter.ai/api", "https://openrouter.ai/api/v1"],
  "defaultFor": ["claude-code"],
  "legacyApis": ["openai-completions"]
}

而一条接入条目通过 modelRef 继承公共型号,通过 routes[] 声明接入目标,通过 perAgent 声明引擎差异:

{
  "id": "openai/gpt-6.1-sol",
  "name": "GPT-6.1 Sol",
  "status": "active",
  "sortOrder": 14,
  "modelRef": "openai/gpt-6.1-sol",
  "nativeApi": "openai-responses",
  "routes": [{
    "providerId": "openai",
    "modelId": "gpt-6.1-sol",
    "agents": ["claude-code", "codex"],
    "defaults": { "supportsFastMode": true, "contextWindow": 500000 },
    "referencePriceGroup": "global"
  }],
  "perAgent": {
    "codex": { "contextWindow": 500000, "efforts": ["low","medium","high","xhigh","max","ultra"] },
    "claude-code": { "contextWindow": 500000, "efforts": ["low","medium","high","xhigh","max"] }
  }
}

结构例外必须记住:条目本身没有 models[].defaults;Registry 的 agents / perAgent 只接受 claude-code 与 codex,Pi 走 providers[].models.pi(用户侧补丁 perAgent.pi 是另一套合法 schema);媒体 route 使用空的 agents: []。此外 contextWindowMax 是客户端容量投影,不允许写进 Registry —— 校验器里有一行专门的防线:

// Capacity is connection-local metadata, never a public Registry default.
function validRegistryMetadata(value: unknown): value is ModelMetadata {
  return validModelMetadata(value) && !("contextWindowMax" in value);
}

三、改哪里:责任侧与字段归属对照

这张表是整篇文档的操作核心。左列是"要改什么",中列是唯一合法的写入位置,右列是"不能顺带改变什么"——右边通常比左边更容易出错。

要改什么 写入位置 / 责任侧 不能顺带改变什么
型号公共名称、说明、窗口、输出、思考能力 Registry baseModels[].defaults 价格、账号权限、地址和凭证不在公共继承内
接入条目状态、排序、默认开启标记 Registry models[] 顶层 显示开关不等于成员资格;订阅账号排序以账号为准
某供应商的上游 ID、支持路由、普通默认 models[].routes[] / routes[].defaults 普通默认不能压过实报
Claude Code / Codex 的工作默认 models[].perAgent,引擎必须被该条目 route 声明 不把工作预算当供应商承诺容量
Pi 公共成员和 Pi 默认资料 providers[].models.pi;订阅账号发现另补新型号 复用已实现的订阅传输,不复制其他引擎的专属能力
经核实的错误实报 匹配 route 的 forceOverrides + overrideReason 不影响其他供应商,也不压过用户配置
厂商官方参考价及历史价区间 baseModels[].referencePriceGroups[].prices[](V5) 按市场分组,保留币种、标准/Fast、输入区间及生效日期
接入供应商参考报价 routes[].referencePrices[];referencePriceGroup 指向公共价组 Gateway 实价/折扣仍归其计费控制面
内置接入或新增连接模板 providers[] 或 presets[].runtimes 不在公共目录保存真实账号密钥
本地候选、包装、门槛、推荐 localModels.models / featuredIds 不自动安装、卸载、切换用户模型
某个用户的显式设置 本机 model-catalog-overrides.json 等既有偏好 不写回 Server;刷新保留,恢复默认删除 override
新执行协议、SDK 参数、token 计量 本仓对应 host / harness / bridge 加目录字段不会自动获得执行能力

最后一行是维护中最常见的误判:目录是数据,执行能力是代码。给目录加一个 api 或 requires 字段,只会在运行时被"能力未知"过滤掉,不会凭空长出适配器。V6 的接口模板把这一点写死成了设计约束:

/** Executable behaviors are versioned code; directory data can only select these. */
export const MODEL_INTERFACE_CAPABILITIES = [
  ...PI_MODEL_APIS.map(api => `api:${api}`), 'kimi-tool-ids-v1', 'chat-image-v1',
] as const;

requires / compatibility 只能引用这些已实现的具名能力,未知能力等于不可执行。

四、Registry V6:把"模型身份"和"接口绑定"拆开

V6 最重要的结构变化是引入了 interfaceProfiles:一个模型的身份与其可达接口分离维护。正本位于 Server 的 source/registry/interface-profiles.json,客户端侧类型定义在 modelAccessBean.ts:

字段 含义 约束
id 模板标识 全局唯一;重复即整份快照被拒
providerId 归属产品/供应商 绑定它的 route 必须同 providerId
api 通道语言 必须是客户端已实现的 PI_MODEL_APIS 之一才可执行
baseUrl 精确端点 不能带 query/hash/内嵌凭证
inputBaseUrls[] 允许进入该凭证作用域的输入地址 必须与 baseUrl 同源,不能借目录把密钥换域发送
legacyApis[] 已声明的旧导入修正规则 仅用于修复历史生成的 API 字段
requestPath 可选相对路径 不能是 //、..、非法百分号编码
modelIds[] 限制旧配置自动采用该模板的成员 显式 routes[].interfaces 可为新模型绑定已有模板
defaultFor[] 引擎默认优先级 值只能是 claude-code / codex / pi
defaults 通道能力 与公共资料分属不同层,见下一节
compatibility / requires 具名能力声明 未知能力使该绑定不可执行
retired 撤回标记 撤回后不能靠离线数据复活

同源约束在校验器中被显式实现(modelInterfaceContract.ts):

const url = endpoint(profile.baseUrl);
if (!url || profile.inputBaseUrls.some(input => endpoint(input)?.origin !== url.origin))
  return 'interface profile crosses credential origin';

routes<a href="https://link.gitcode.com/i/7c0d39f17d014674a6a0d955e583f97f" target="_blank">].interfaces[] 通过 profileId 绑定模板,并可声明 wireModelId / defaults / compatibility / requires / retired;preferredInterfaces 按 Claude Code、Codex、Pi 分别列优先级。下面是一个最小的 V6 骨架,仅用于说明字段关系(可执行的完整示例见 [docs/examples/model-catalog.md,那 5 段 JSON 已被 documentedModelCatalog.test.ts 直接提取并通过生产解析器验证):

{
  "schemaVersion": 6,
  "updatedAt": "2026-10-01T00:00:00.000Z",
  "interfaceProfiles": [{
    "id": "example-anthropic",
    "providerId": "example-provider",
    "api": "anthropic-messages",
    "baseUrl": "https://api.example.com",
    "inputBaseUrls": ["https://api.example.com"],
    "defaultFor": ["claude-code"]
  }],
  "baseModels": [{
    "id": "example/model",
    "aliases": ["model"],
    "defaults": { "name": "Example Model", "contextWindow": 128000 }
  }],
  "models": [{
    "id": "example-entry",
    "name": "Example Model",
    "modelRef": "example/model",
    "routes": [{
      "providerId": "example-provider",
      "modelId": "model",
      "agents": ["claude-code"],
      "interfaces": [{ "profileId": "example-anthropic" }],
      "preferredInterfaces": { "claude-code": ["example-anthropic"] }
    }]
  }]
}

运行时如何在多个接口间选路

providerInterfaceRoutes.ts 的 availableModelInterfaces 是唯一的枚举入口,规则如下:

  1. Registry 低于 V6、条目 retired、或同一 (providerId, modelId) 命中多条 route → 返回空集(不做猜测)。
  2. 显式绑定优先;没有显式绑定时按 modelIds 与端点同源规则自动匹配模板。
  3. api 必须属于 PI_MODEL_APIS;requires + compatibility 中任一能力未知 → 该候选被排除。
  4. 排序按 preferredInterfaces[agent] 的位置,其次 defaultFor 命中,最后排在末尾。

providerInterfaceModelRoute 在此之上做选择:interfaceId: "auto" 跟随目录默认,显式 profile ID 固定用户选择;若用户选了已撤回/不可用的模板,结果是 interfaceUnavailable: true 并清空可用列表,而不是静默回退到另一个协议:

if (model.interfaceId && !automatic && !selected)
  return { ...model, interfaceUnavailable: true, availableInterfaces: choices };

界面展示当前接口的能力;输入不被支持时不会自动重放到另一协议。旧字段 api / piApi / route / requestPath 全部保留,只有 legacyApis 中已声明的旧导入规则才允许迁移。用户配置只保存原始选择,不保存解析后的 API、模板或完整快照。

任务级接口快照

任务首次派发把非敏感接口、模型 ID 与能力快照存入 owner-scoped 的 model-interface-snapshots/,使同一任务/来源/引擎/型号在目录刷新与重启后仍保留接口;旧任务首次恢复按保存的 transport 迁移。

边界同样明确:鉴权、来源是否存在、暂停与撤回仍实时检查;快照不存 Key 或 headers;删除任务清理其快照,归档和关闭不清理;SSH 由执行宿主复用选路结果,新接口若不能被既有远端协议表达,沿用启动前的明确报错,而不是降级。

五、覆盖顺序:字段级继承的唯一正本

模型资料的优先级是单向链,右侧覆盖左侧:

公共 defaults → 匹配的预设默认(适用时)→ 条目顶层默认
             → route.defaults → 条目 perAgent[引擎]
             → 供应商明确实报 → route.forceOverrides → 用户显式覆盖

这条链不是文档愿景,而是可读的代码。registryEntryDefaults 决定了"目录内"的合成顺序:

export function registryEntryDefaults(registry, entry, route?, agent?, providerDefaults?) {
  return mergeModelMetadata(
    entry.modelRef ? findBaseModel(registry, entry.modelRef)?.defaults : undefined,
    providerDefaults,
    pickModelMetadata(entry),
    route?.defaults,
    agent ? pickModelMetadata(entry.perAgent?.[agent]) : undefined,
  );
}

resolveModelMetadata 则把运行时实报、接口默认与用户覆盖接在它后面(modelMetadataLayers.ts),顺序为:代际能力兜底 → 公共预设 → 目录默认 → 接口默认 → perAgent → 实报 → 显式 defaultEffort → forceOverrides → 用户覆盖。

合并语义:不要让"假值"吞掉空值

mergeModelMetadata 的合同只有四条,但每一条都在实践中被违反过:

/** Undefined inherits; false, null and [] remain explicit values. Arrays replace. */
  • 缺字段(undefined)才继承,false 是明确的"关闭",null 按字段合同处理,[] 是明确的空数组。
  • 数组整体替换,不做元素级合并。
  • 一个特殊联动:supportsImageInput: false 且本层未声明 modalities 时,会从已合并的输入模态中移除 image,同时保留无关的输出能力,且不修改源目录对象。

字段合法性由 validModelMetadata 逐项校验,主要上限值得记住:name ≤ 256、group ≤ 128、description ≤ 2000 字符;officialDocs 必须是无凭证的 HTTPS URL;contextWindow / contextWindowMax / maxOutputTokens 必须是正的 Number.isSafeInteger;efforts 只能取 minimal|low|medium|high|xhigh|max|ultra 且不重复;mode 必须匹配 ^[a-z][a-z0-9_]{0,63}$。

forceOverrides 的门槛

forceOverrides 是"经核实修正实报"的专用通道,因此校验器强制要求给出理由:

if (value.forceOverrides !== undefined &&
    (typeof value.overrideReason !== "string" || !value.overrideReason.trim() ||
     value.overrideReason.length > 1000))
  return `${path}.overrideReason is required for forceOverrides`;

overrideVerifiedAt 若存在,必须是合法的 YYYY-MM-DD。这两条把"临时改个数"和"已核实的纠错"在数据结构上区分开,也便于未来清理。

用仓库示例验证继承效果

docs/examples/model-catalog.md 的 5 个示例不是装饰,documentedModelCatalog.test.ts 会把它们提取出来跑生产解析器,并断言窗口解析结果:

expect(windowFor("base-model")).toBe(128000);
expect(windowFor("route-default")).toBe(64000);
expect(windowFor("agent-default")).toBe(32000);
expect(windowFor("route-default", 80000)).toBe(80000);   // 实报优先于 route 默认
expect(windowFor("forced-correction", 80000)).toBe(72000); // forceOverrides 压过实报
expect(windowFor("forced-correction", 80000, 16000)).toBe(16000); // 用户仍然最高

运行这条回归:

pnpm --filter @cindy/model-providers test -- src/__tests__/documentedModelCatalog.test.ts

六、排序与成员:订阅以账号为准

OpenAI(Codex 订阅)与 Anthropic(Claude 订阅)的 root 成员只来自账号清单:Registry 只给已返回的型号补资料、标退役,绝不补入账号没返回的型号;没有账号清单时名单为空。

sortOrder 以账号返回顺序为准:

  • Codex 取 models_cache.json 的 priority 或 app-server model/list 的返回位置;
  • Claude 取 SDK supportedModels() 的返回位置;
  • 用户本地 addition 按 Registry / 本地 sortOrder 接在其后;
  • 装配时重写为连续 sortOrder,选择器、设置页、新对话默认与 Claude Code bridge 共用这一顺序。

Claude 订阅没有 HTTP 清单接口,清单来自内置 Claude Code 的 SDK supportedModels():会话启动时捕获;此外 maker 就绪、登录/认领 Claude 登录以及手动刷新时,用本机 CLI 起一个空闲 Query 只读清单(不发消息、不产生模型调用)。SDK 对当前型号常只给简称(opus / sonnet / default)并把版本写在说明里;简称按说明拼成 claude-<系列>-<主>-<次>。Registry 尚未登记的新版本照样显示(资料用未知模型默认值并记日志提示补登记),绝不映射到相邻旧版本;说明里读不出版本时才跳过。

第三方 API key 连接(MiMo、Kimi Code 等预设及自定义端点)没有 sortOrder,按连接配置里的顺序排:首次添加用接口返回的顺序;之后刷新发现的新型号排在已有型号之前,已有型号位置不动。这正是 mergeDiscoveredRuntimeModels 的行为:

// 新发现的型号排在已有型号之前(保持接口返回的相对顺序),已有型号位置不动。
return [...added, ...models];

出厂默认与 Auto 跟随

未手动选择模型时,出厂来源顺序为:Codex 订阅 GPT-6.1 Sol(Codex)→ Claude 订阅 Opus 5.5(Claude Code)→ 服务端指定的 Cindy Auto(Pi)→ 保留 xAI 回退。该策略落在 newMakerDefaultTuple.ts:

const DEFAULT_POLICIES: readonly ProviderDefaultPolicy[] = [
  { providerId: 'openai', accessKind: 'subscription', agents: ['codex'],
    modelIds: ['gpt-6.1-sol', 'chatgpt/gpt-6.1-sol'] },
  { providerId: 'anthropic', accessKind: 'subscription', agents: ['claude-code'],
    modelIds: ['claude-opus-5-5', 'anthropic/claude-opus-5-5'] },
  ...
];

Cindy Auto 由服务端决定:在 Cindy AI 与企业号池供应商(source: organization)中跟随被标为 Pi 新任务默认的 Auto 系列模型(预设 auto 或模型组 Auto auto/<组ID>),没有标记时(旧服务端)回退 Cindy AI 的预设 auto。服务端保证每个引擎只标一个默认;管理员恰在两次拉取之间改配置、两类来源短暂各标一个时,以 Cindy AI 为准。

Auto 只按模型 ID 识别(isCindyAutoModelId)。服务端可以把同一个 Auto 在 Cindy AI 与企业号池之间挪动;记住的来源是这两类之一且已不再提供它时,effectiveSourceIdForModel 改用当前提供它的另一家,新建任务提交与手机端 resolveRecentModelAndProvider 复用同一规则。记忆的来源仍列着它(只是断连或停用)、或用户自己接的供应商时不改道。

目录刷新后,仍记着旧来源的进行中任务登记一次"下一条消息前切换":引擎与模型 ID 不变,只换供应商与 Key。用户点选、跨引擎或跨电脑的切换、等待生效的换凭证、运行时选择都不覆盖;只有故障切换中(fallbackHop > 0)的任务不跟随。远程主机与另一台电脑上运行的任务不在本机改道。

设置页列表的同序规则

设置页管理列表组内与选择器同序:组内每项都带 sortOrder 时按它排;只要有一项缺失,退回按系列名 A–Z、同系列版本号降序,避免局部权重把新型号压到旧策展位置之后。

七、第三方预设:只写一份推荐清单

providers.json 的每个预设只在顶层写一份 models 推荐清单,数组顺序即推荐顺序;runtimes[引擎] 只放地址、协议、模型目录等连接信息,不再按引擎各写一份模型。加载时由 expandPresetModels 展开回各引擎清单,下游与服务端下发的旧格式形状一致。

{
  "id": "openrouter",
  "name": "OpenRouter",
  "models": [
    { "id": "z-ai/glm-5.2", "name": "GLM-5.2", "contextWindow": 1048576, "supportsImageInput": false },
    { "id": "deepseek/deepseek-v4-pro", "name": "DeepSeek V4 Pro", "contextWindow": 1048576,
      "engines": ["claude-code", "pi"] }
  ],
  "runtimes": {
    "claude-code": { "baseUrl": "https://openrouter.ai/api" },
    "codex": { "baseUrl": "https://openrouter.ai/api/v1" },
    "pi": { "baseUrl": "https://openrouter.ai/api/v1", "wireProtocol": "openai-chat" }
  }
}

规则细节(实现见 presetModels.ts):

  • 协议限制导致某模型只在部分引擎可用时写 engines(如 OpenCode Go 的 Anthropic 协议模型、GLM Coding Plan 只给 Claude Code 的 [1m] 变体)。
  • 引擎专属字段写 engineOverrides[引擎]:Pi 的推理档位、按模型路由,以及确有差异的窗口。
  • engines 的每一项与 engineOverrides 的每个键都只能是本预设已声明的引擎;拼错或写成其它形状时整条预设被拒绝,不静默丢模型或忽略覆盖:
if (models.some((model) => hasMalformedEngineFields(model, declaredRuntimes)))
  return preset; // 保留顶层 models,由 sanitizePresets 整条拒绝
  • 该文件是源格式。旧客户端读不懂顶层清单,不能直接发布到已冻结的旧 OSS cfg/providers.json;旧客户端经公共 API 与服务端投影拿到展开后的形状。
  • 名称与参数以厂商官方文档为准;未列入推荐清单的型号由 Pi 模型资料补入并默认隐藏。
  • presetModels.test.ts 校验随包预设不再出现按引擎的清单;服务端分片同样只写一份推荐清单,由 generateCatalog.mjs 展开后下发。同 id 的服务端预设整体覆盖随包版本,所以推荐清单与参数两边必须保持一致。

值得单独强调的是预设段的容错边界与 providers 段不同:sanitizePresets 对坏预设是"逐条丢弃 + 按 id 去重(first-wins)",而不是让整份目录解析失败。理由写在代码注释里:预设是纯 UI 模板数据、不参与路由,一条坏预设不该连带丢掉远端的模型与路由更新。

八、默认可见性:产品合同与实现差异

产品合同只有一句:用户开关优先,否则跟随目录 defaultEnabled(见 configuration-and-overrides.md)。

  • 不默认显示的型号只写在目录里:条目标 defaultEnabled: false;未标的一律默认显示,因此新出的型号一定可见。客户端发现代码不按具体型号写死隐藏例外。
  • 保留的是按状态或引擎的规则,不针对具体型号:deprecated、requires_payment 默认关闭;跨 Harness bridge(如 Claude Code 里的 chatgpt/*)与自定义连接的兼容引擎默认关闭,Registry perAgent 可显式打开。
  • XD 路由一律使用独立的 xd/* 条目,不与订阅或其他供应商共用条目:服务端生成 Gateway /models 时读取 XD 路由所在条目的名称、排序与 defaultEnabled,共用会让订阅侧调整连带改动 XD。型号规格经 modelRef 继承同一公共型号,不重复维护。xdRegistryEntries.test.ts 校验离线 Registry 不出现混用条目。

排查可见性问题时,必须同时检查三处:上游返回值、活动目录值、用户 override。只看其中一层几乎必然误判。

九、参考价 V5 与 Gateway 复杂价目

厂商参考价

公共型号的 referencePriceGroups 使用市场标识(当前为 global / cn),不是供应商 ID。每组 prices 沿用官方证据:币种(CNY / USD)、每百万 tokens 单价、缓存读/写及 1h 写入、standard|priority|batch|fast 变体、输入区间 [minInputTokens, maxInputTokens)、生效日期区间,以及带 kind: "provider-official"、url、verifiedAt 的 source。

解析函数 resolveBaseModelReferencePrice 按公共 ID 或唯一 alias 读取,不依赖供应商名单:

// Market/currency ambiguity is unknown, never array order or a currency conversion.
return matches.length === 1 ? matches[0] : undefined;

多市场/币种必须明确选择到唯一有效价格;无匹配或有歧义返回未知。三个容易写错的语义:

  • 缺字段保持未知,明确的 0 才表示零单价;
  • 缓存存储每小时费用不能写成缓存写入单价;
  • 区间是半开的:day < effectiveFrom 或 day >= effectiveUntil 都不匹配。

路由用 referencePriceGroup 明确选择所属公共型号的价格组;供应商自己的 referencePrices 优先于该组,且整组替换、不逐字段补齐。订阅价值估算指定 officialOnly,只取厂商参考价;用户显式价格覆盖仍优先。XD 计费继续只读 Gateway 实报。

校验器还会拒绝同一 currency + variant 下相互重叠的价格区间:

if (referencePriceRangesOverlap(previous, price))
  return `${path}[${index}] overlaps referencePrices[${previousIndex}] for the same currency and variant`;

Gateway 复杂价目展示

Model Access V5 通过 X-Cindy-Model-Capabilities: display_pricing 协商可选 displayPricing。聊天和媒体目录都保留该字段与同一连接快照的 currency、costDiscount;它不进入公共 Registry/defaults、ModelPriceQuote 或 token 成本估算,也不跨供应商补价。

容错策略是分级降级:

  • 成功刷新但缺字段或价目不可解析 → 清除旧价目,模型仍正常更新;
  • 新增属性忽略,未知单位保留;
  • 展示字段变化不构成整份目录失败;网络或核心模型协议失败仍沿用既有目录恢复语义。

displayPricing 的结构限制在 modelDisplayPricing.ts 中实现:items 必须 1–128 条、notes ≤ 32 条、每段 price 有限且非负、quantity 为正、unit ≤ 128 字符;summary 每个角色允许 1–4 段,priceType 仅允许缺省、exact 或 estimated,任一段为 starting_at 时整份 summary 无效(只丢摘要,保留价目表);maxPrice 必须大于 price,同一角色内 unit + quantity 不得重复。

Desktop 设置页模型详情有 displayPricing.summary 时优先按输入、输出、缓存读取、缓存写入展示主报价,区间统一用 maxPrice 表示。补充价目表仅在以下条件全部满足时隐藏:有 summary 且没有 notes;所有 item 都没有 tier、priceType 缺省或 exact;item 总数等于所有角色报价段数,且每个 item 能按 unit、quantity、price 一一匹配不同的摘要报价,匹配报价没有 maxPrice 或 tier。其余情况保留在摘要下方。设置页列表对带 displayPricing 的模型不显示价格;选择器、浮层和聊天价格档位逻辑保持原样。解析与展示回归见 modelDisplayPricing.test.ts、DisplayPricingDetails.test.tsx 与 ModelAdvancedDrawer.test.tsx。

十、更新、下发与验收

维护步骤(V6)

  1. 在 Server 正本修改模型绑定/通道能力/优先级,增加 updatedAt,运行 pnpm --filter model-access-server catalog:generate。

  2. 更新离线副本时,在客户端运行:

    node packages/model-providers/scripts/sync-registry.mjs <Server生成的providers.json>
    

    sync-registry.mjs 的语义很严格:只取 providers.json 的 modelRegistry,要求 schemaVersion === 6 且 interfaceProfiles 是数组,否则直接抛错;写入是原子的(临时文件 + rename);旧文件只影响呈现顺序,每个值、每个删除、每个数组顺序都来自 Server,绝不合并成员:

    // Presentation order only: every value, deletion and array order comes from Server.
    if (!incoming || incoming.schemaVersion !== 6 || !Array.isArray(incoming.interfaceProfiles)) {
      throw new Error('Expected a complete V6 registry');
    }
    

    随后运行解析、目录一致性及受影响路由回归。旧 provider-interface-models.json 与客户端硬编码接口表已删除。

  3. 发布范围判定:新型号绑定已有模板可以只发目录;新增/改变模板端点、鉴权边界或兼容行为走常规服务发布;新执行行为还必须发布客户端。发布门比较组装后的模板,不能通过换分片绕过。

  4. 回撤用新的完整 revision 和 retired,不回发旧日期快照。顺序是:先部署可兼容投影的 Server → 再发布客户端 → 最后调整目录默认;目录发布与真实上游推理验收分别记录。

六步验收清单

  1. 确认目标:记下 Server/客户端 commit、部署环境、实际目录源、当前 schema/revision、要改的 provider/model/引擎;核实官方资料与该通道实报。文档不是线上状态台账。
  2. 修改责任侧:在授权范围内先维护 Server 正本,再协调客户端离线 Registry。遇到尚未上线的协议配套,分别记录工作分支、已合并和已部署状态,不混成"已支持"。
  3. 整表同步:将审阅后的 Server modelRegistry 整体同步到客户端 catalog/model-registry.json,保持同 updatedAt、同内容。不要复制 Server 整份 providers.json,也不能只复制 localModels 造成悬空引用。新 revision 必须递增且不可变;价格 effectiveFrom / verifiedAt 保留真实日期。
  4. 先验证兼容再发布:完整结构过 parseModelRegistry / parseCatalog;确认旧客户端投影。尤其先读 媒体扩展发布前置条件:同为 V4 并不证明认识新增媒体字段。LKG/内置回退不能代替兼容方案。
  5. 核对真实下发:当前 Server 源码仅加载制品内生成目录,已不读取 MODEL_CATALOG_URL;必须核对目标环境版本。部署后读取 /api/model-catalog/catalog,核对目标与旧版响应、ETag 和有效 revision。仅改文件、合并 PR、通过 CI 不算下发完成。同步回归须核对原有直连 route 与历史参考价区间未丢失,覆盖标准/Fast、缓存读写、长输入分档。离线默认档与已发布 Server 有差异时逐项披露。原生协议校验须遍历全部 route 和活动目录中的订阅 wire 别名,不能仅统计字段填写率,也不能从供应商兼容 API 反推未知型号的原生协议。
  6. 验收到运行时:确认客户端实际接受目标快照、保留用户覆盖;检查选择器、发出的上游 ID/参数及新旧任务。覆盖离线、坏快照、同 revision 冲突与回退版本;刷新不改用户显式型号/档位。

版本协商与同 revision 判定

V6 客户端请求 registrySchemaVersion=6&registryMedia=1&registryLocalRuntimes=1;旧服务端返回低版本时在同一时间预算内重试一次 V5。缓存按实际 URL 变体隔离;同 revision 的 V5→V6 只有旧形状完全相等才视为升级,反向不覆盖 V6:

if (incoming.schemaVersion === 6 && current.schemaVersion === 5 &&
    modelRegistryCanonicalJson({ ...projectRegistryV5(incoming), updatedAt: canonicalUpdatedAt }) ===
    modelRegistryCanonicalJson({ ...current, updatedAt: canonicalUpdatedAt })) return 'newer';

projectRegistryV5 会剥掉 interfaceProfiles、nativeApis、interfaces、preferredInterfaces 后比较,因此"V5→V6 只是多了模板"能被识别为升级;而同一 schema 内的内容差异一律判为 conflict,保留 LKG。服务端 V5/V4/冻结 legacy 投影不泄漏新字段或新默认接口。

三个独立结论

这是本套流程最需要守住的纪律:

结论 证据来源 不能替代什么
客户端已实现 本仓代码 + 单测通过 服务已部署
服务已部署 目标环境响应 + revision/ETag 账号真实推理通过
账号真实推理通过 真实上游调用验收记录 全量兼容性

回归入口:providerInterfaceRoutes、source-registry、modelAccessValidator、Desktop providerRoute(真实 HTTP 目录→解析→三接口出站、快照冷恢复)、codexProxyHost、piProviderTransport。

十一、llama.cpp 托管接入与本地模型域

客户端的「添加供应商」有两个 llama.cpp 入口,互不影响:

  • 托管入口(cindy-local-llamacpp):点击立即保存并进入详情,不等待安装或连接,安装与下载在详情中进行。
  • 目录预设 llamacpp:用于连接用户已运行的服务(默认 http://127.0.0.1:8080/v1,地址可改),出现在「检测到本机服务」或「更多本机服务」,走普通预设连接流程,不调用托管安装或启动。

托管实现位于 apps/desktop/src/main/local-model-runtime/(llamaCppDownloads.ts、llamaCppService.ts、llamaCppIpc.ts 等)。运行环境从 llama.cpp 官方 Releases 安装到 userData 下的 llamacpp-runtime;macOS 使用对应架构构建,Windows / Linux 先使用 CPU 构建;下载校验官方 SHA-256,不调用系统包管理器。

模型下载支持两种来源:共用清单一键下载,或用户指定公开 Hugging Face 仓库并选择 GGUF 文件。下载固定到仓库 revision,校验大小与 LFS SHA-256,自动补齐分片,全部完成后才移入已安装列表;取消或失败清理本次暂存文件;磁盘不足在下载前提示。当前支持文本模型,不自动下载视觉 projector。下载清单复用 Server Registry 的 localModels.models<a href="https://link.gitcode.com/i/0abb5bc58a0a0d3892ad1235d8eb1f03" target="_blank">].llamacpp[],只增加 repo / file / quantization / sizeBytes / verifiedAt 下载资料,不维护第二份模型名单。对应类型定义见 [localModelCatalog.ts:

export interface LocalGgufVariant {
  repo: string;
  file: string;
  quantization: string;
  sizeBytes: number;
  verifiedAt: string;
}

服务与端口边界:

  • 托管服务只绑定 127.0.0.1:11435,与原手动预设的 8080 分开;端口被占用时不接管。
  • router 按请求加载模型,最多同时加载一个模型,默认上下文 32,768、单并发。
  • 按模型生成原生 INI preset,不用全局 CLI 窗口覆盖其它模型;发布模型资料时同步升级旧的托管默认值。
  • 下载完成后自动同步供应商模型列表并广播刷新。服务运行时保留当前模型清单和上下文;下载模型或修改上下文后,由拥有方在「管理服务」中手动重启生效;停止后的下次使用自动启动并应用最新配置。
  • 会话启动和 Pi provider 装配均复用 preflight;下载不依赖服务运行。Cindy 退出时停止自有子进程。

能力声明要克制:这不代表任意 GGUF 都支持工具调用。verifiedAt 只表示文件存在与大小核验日期,不能解释为运行验证;分片大小为总和。明确空的 llamacpp: <a href="https://link.gitcode.com/i/3390c0373876d5da11267057ff14fb74" target="_blank">] 撤下该模型的 GGUF 候选,旧快照缺字段也不按型号猜下载地址。试验范围与维护记录见 [llama.cpp 试验清单。

安装与下载管理只在执行端 Desktop 设置页开放,不新增远程 privileged IPC 白名单;手机仍可通过已有执行端模型目录使用已连接模型;SSH 执行路径跳过本机启动,不会把本机模型安装到远端。客户端请求增加 registryLocalRuntimes=1,服务端仅向同时声明 media 和本能力的 V4/V5 客户端下发 llamacpp,旧端剥离该字段并重新计算 ETag;未知能力值等同未声明。

回归测试为 llamaCppDownloads.test.ts、llamaCppService.test.ts、llamaCppIpc.test.ts、managedLlamaCppProvider.test.ts 与 LlamaCppProviderDetail.test.tsx。

十二、通用供应商导入与 SSH Codex 目录

通用供应商导入

Pi 上游生成资料统一转换为客户端 catalog/provider-models.json,供各引擎和设置页补缺,不另存 Pi 原始表。目录的 Pi API 是该渠道的执行协议,不冒充 Registry 的厂商原生协议。维护命令、覆盖顺序和验收见 通用供应商目录;渠道多协议与逐模型接口证据见 供应商接口核查。

SSH Codex 模型目录

SSH Codex 的创建入口(含 Orca Worker)、任务内选择器与 main 的新建/切换准入,读取所选主机 app-server 的完整 model/list,不使用控制端 OpenAI 登录或网关目录作为远端可用性的依据。

  • 沿用已有远端安装与 daemon 连接流程;分页有界,读取失败或空清单显示重试,不回退到本机。
  • 结果只用于该主机;断连、换主机或换账号后的迟到结果丢弃,不发布到本机公共目录。
  • 新任务从远端清单解析默认模型及推理强度/Fast;已有任务保留原模型和历史,由用户改选。
  • 设置页及普通 SSH 创建入口不继承控制端草稿的模型、推理强度或 Fast 记忆,即使型号同名;采用远端默认模型及推荐推理强度,Fast 初始关闭。
  • 原样恢复只有在持久化的主机、原生线程、引擎、模型及来源均匹配时才豁免新建目录校验,允许恢复后来被隐藏的原模型;模型是否仍可推理由远端 Codex 决定。SSH 模型及档位选择不写入控制端本地模型偏好。
  • 首次连接成功会补偿挂载时因尚未就绪而失败的目录读取;重复 ready 快照不清空已成功读取的目录。
  • 升级远端 Codex 包前先停止旧 daemon;有正在执行的回合或无法确认停机时,升级失败并提示稍后重试。
  • model/list 不提供的真实窗口保持未知;未知窗口允许切换且不主动重建,已核实的高风险缩窗在远端拒绝,回合中延期。不能因前端尚无用量报告而静默丢弃点击;未知窗口也不代表已证明切换安全。

实现:maker-host/ssh-codex-models.ts、remote-ssh/codex-model-list.ts、useSshCodexProviders.ts;回归:codex-model-list.test.ts、sshCodexModels.test.tsx、chatInputModelLoading.test.tsx。新增读取 IPC 属于本机 SSH 管理面,与既有 SSH 管理 channel 一样不开放 device-link。

十三、用户本地覆盖:唯一不该写回 Server 的一层

用户显式设置保存在本机 owner-scoped 文件中,路径由 model-catalog-override-store.ts 固定:

const store = createOverrideSettingsFile<ModelCatalogOverrides>({
  filePath: () => ownerScopedUserDataPath('model-catalog-overrides.json'),
  defaults: EMPTY_MODEL_CATALOG_OVERRIDES,
  normalize,
  maxBytes: MAX_MODEL_CATALOG_OVERRIDE_FILE_BYTES, // 1 MiB
  preserveUnreadableFile: true,
});

合并语义在 localCatalogOverrides.ts 中,要点:

  • 形状 v1,key = ${providerId}:${modelId}(不含 agent),跨引擎差异用 base + perAgent 一次表达。
  • additions 是完整新实体,同 key 整条压过 remote/discovery,且显式复活远端 retired。
  • patches 是稀疏逐字段覆盖,可 dormant(宿主尚不存在时静置,出现即生效);patch.status 禁止 retired——本地没有 tombstone,想隐藏请走 visibility / disable 轴。
  • local 永远最高优先级:远端刷新只换 remote 层,绝不覆盖本地修改;支持"直接手改文件即生效"(mtime 守卫)。
  • 单条 invalid 隔离(保留原文、告警、不参与合并),整文件其余条目继续生效;坏 JSON 或超限文件原样保留,修正后下一次同步自动恢复。
  • 账号切换由 ownerScopedUserDataPath 的路径失效自动换文件,旧 owner 数据不泄漏。

这条模块明确禁止触碰四根正交轴:显示/隐藏(modelVisibilityPrefs,defaultEnabled 不可 override)、准入/停用(model-disable-store)、本地参考价(modelPriceOverrideStore)、routing / auth / upstream。理解这一点,才能解释为什么"目录里改了窗口,用户界面没变"——用户 override 永远在链尾。

十四、维护速查:字段、校验与回归入口

常见错误与对应校验

现象 很可能的原因 校验位置
整份 Registry 被拒:modelRef is unresolved 只同步了 models 未带 baseModels parseModelRegistry
整份 Registry 被拒:baseModels identity is ambiguous alias 与另一个型号的 id/alias 冲突 parseModelRegistry
整份 Registry 被拒:route.referencePriceGroup is unresolved referencePriceGroup 指向的组不在该 modelRef 上 parseModelRegistry
接口全部不可用 requires/compatibility 引用了未实现能力,或 profile 被 retired availableModelInterfaces
界面提示接口不可用而非回退 用户显式 interfaceId 指向的模板被撤回 providerInterfaceModelRoute
预设整条消失 engines / engineOverrides 写了未声明的引擎 expandPresetModels + sanitizePresets
改了目录但界面数值不变 存在用户 override 或连接实报 resolveModelMetadata 覆盖链
同 updatedAt 未生效 被判为 conflict,保留 LKG compareModelRegistryRevisions

关键命令

# 校验文档中的 5 个 Registry 示例(生产解析器 + 窗口解析断言)
pnpm --filter @cindy/model-providers test -- src/__tests__/documentedModelCatalog.test.ts

# 把 Server 生成的 V6 Registry 同步进客户端离线副本(原子写入,不合并成员)
node packages/model-providers/scripts/sync-registry.mjs <Server生成的providers.json>

# 目录源、缓存与回退
pnpm --filter @cindy/model-providers test -- src/__tests__/source-registry.test.ts

# 校验器与资料层
pnpm --filter @cindy/model-providers test -- src/__tests__/modelAccessValidator.test.ts
pnpm --filter @cindy/model-providers test -- src/__tests__/modelMetadataLayers.test.ts

# V6 接口模板与选路
pnpm --filter @cindy/model-providers test -- src/__tests__/providerInterfaceRoutes.test.ts

# 预设单一清单与 XD 条目隔离
pnpm --filter @cindy/model-providers test -- src/__tests__/presetModels.test.ts
pnpm --filter @cindy/model-providers test -- src/__tests__/xdRegistryEntries.test.ts

按问题继续阅读

按需阅读 入口
资料、账号、覆盖、空名单 模型资料优先级
窗口、压缩、价格与展示 运行时与展示细则
本地包装、内存、推荐证据与更新 本地模型筛选
图片/视频/音频/向量字段与发布兼容 V4 全类型规范
供应商界面、账号状态、用量呈现 供应商设置
历史型号与同步记录 历史记录(不可当作当前状态)
字段写法及可执行校验 五个示例
改代码与定位测试 从需求找到代码
xAI 双接口同步与导入验收 同步说明

最后回到那条最容易被忽略的原则:目录是声明,不是能力。availableModelInterfaces 只在本产品已实现的传输中选择,requires 只能引用已发布的具名能力,retired 与 modelIds 不会因为离线数据而被绕开。维护模型目录时,把每一步都拆成"改了数据 / 合并了代码 / 部署了服务 / 实测了推理"四栏分别记录,就不会出现"文档写了但线上没生效"这类最难排查的问题。

登录后查看全文
cindy