Cindy 模型配置与下发全链路:Registry V6 维护手册与源码级实践
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
└─ 媒体 → 对应媒体通道
三个关键事实需要先建立:
- 聊天调用目标不是"模型名",而是三元组:连接 ID + 上游模型 ID + 引擎。同品牌多账号共用资料,但凭证、发现结果、用量与覆盖按连接隔离。
- Mobile / device-link 使用执行端目录,本地安装状态来自执行机器;控制端不会重新选路。目录声明也不等于账号准入或协议已实现。
- 目录存在 ≠ 可用。成员资格、鉴权、网络、真实推理是四道独立闸门,任一道没过都不构成"已支持"。
客户端侧真正发起请求的 URL 由 source.ts 固定拼接:
export const CATALOG_API_PATH =
"/api/model-catalog/catalog?registrySchemaVersion=6®istryMedia=1®istryLocalRuntimes=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 是唯一的枚举入口,规则如下:
- Registry 低于 V6、条目
retired、或同一(providerId, modelId)命中多条 route → 返回空集(不做猜测)。 - 显式绑定优先;没有显式绑定时按
modelIds与端点同源规则自动匹配模板。 api必须属于PI_MODEL_APIS;requires+compatibility中任一能力未知 → 该候选被排除。- 排序按
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-servermodel/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/*)与自定义连接的兼容引擎默认关闭,RegistryperAgent可显式打开。 - 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)
-
在 Server 正本修改模型绑定/通道能力/优先级,增加
updatedAt,运行pnpm --filter model-access-server catalog:generate。 -
更新离线副本时,在客户端运行:
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与客户端硬编码接口表已删除。 -
发布范围判定:新型号绑定已有模板可以只发目录;新增/改变模板端点、鉴权边界或兼容行为走常规服务发布;新执行行为还必须发布客户端。发布门比较组装后的模板,不能通过换分片绕过。
-
回撤用新的完整 revision 和
retired,不回发旧日期快照。顺序是:先部署可兼容投影的 Server → 再发布客户端 → 最后调整目录默认;目录发布与真实上游推理验收分别记录。
六步验收清单
- 确认目标:记下 Server/客户端 commit、部署环境、实际目录源、当前 schema/revision、要改的 provider/model/引擎;核实官方资料与该通道实报。文档不是线上状态台账。
- 修改责任侧:在授权范围内先维护 Server 正本,再协调客户端离线 Registry。遇到尚未上线的协议配套,分别记录工作分支、已合并和已部署状态,不混成"已支持"。
- 整表同步:将审阅后的 Server
modelRegistry整体同步到客户端catalog/model-registry.json,保持同updatedAt、同内容。不要复制 Server 整份providers.json,也不能只复制localModels造成悬空引用。新 revision 必须递增且不可变;价格effectiveFrom/verifiedAt保留真实日期。 - 先验证兼容再发布:完整结构过
parseModelRegistry/parseCatalog;确认旧客户端投影。尤其先读 媒体扩展发布前置条件:同为 V4 并不证明认识新增媒体字段。LKG/内置回退不能代替兼容方案。 - 核对真实下发:当前 Server 源码仅加载制品内生成目录,已不读取
MODEL_CATALOG_URL;必须核对目标环境版本。部署后读取/api/model-catalog/catalog,核对目标与旧版响应、ETag 和有效 revision。仅改文件、合并 PR、通过 CI 不算下发完成。同步回归须核对原有直连 route 与历史参考价区间未丢失,覆盖标准/Fast、缓存读写、长输入分档。离线默认档与已发布 Server 有差异时逐项披露。原生协议校验须遍历全部 route 和活动目录中的订阅 wire 别名,不能仅统计字段填写率,也不能从供应商兼容 API 反推未知型号的原生协议。 - 验收到运行时:确认客户端实际接受目标快照、保留用户覆盖;检查选择器、发出的上游 ID/参数及新旧任务。覆盖离线、坏快照、同 revision 冲突与回退版本;刷新不改用户显式型号/档位。
版本协商与同 revision 判定
V6 客户端请求 registrySchemaVersion=6®istryMedia=1®istryLocalRuntimes=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 不会因为离线数据而被绕开。维护模型目录时,把每一步都拆成"改了数据 / 合并了代码 / 部署了服务 / 实测了推理"四栏分别记录,就不会出现"文档写了但线上没生效"这类最难排查的问题。