# @cherrystudio/provider-registry 中文文档

规范地址：https://npmcn.com/package/%40cherrystudio/provider-registry/

版本：0\.4\.0
npm 元数据更新时间：2026-11-08T19:30:10.534Z
中文译文更新时间：2026-11-09T12:37:46.938Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cherrystudio/provider-registry
原文对照：https://npmcn.com/package/%40cherrystudio/provider-registry/?lang=original
项目主页：https://github.com/CherryHQ/cherry-studio#readme
源码仓库：https://github.com/CherryHQ/cherry-studio

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：7.9 MB，50 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：zod ^4\.4\.3
- 首次发布：2026-10-12T04:38:28.230Z
- 最新版本发布：2026-11-08T19:30:10.347Z
- 近 30 天下载量：4482（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

跨平台的 AI 供应商和模型目录、 计划, 和查询公用事业

## 安装

```sh
npm install @cherrystudio/provider-registry
```

也可以使用：`pnpm add @cherrystudio/provider-registry`、`yarn add @cherrystudio/provider-registry`、`bun add @cherrystudio/provider-registry`

## README

# @cherrystudio/ 提供者- 注册

跨平台AI提供商和模型目录,Zod schemas,以及取景公用事业. 核心工作没有文件系统访问,网络,定时器,或应用程序服务. 节点文件加载可单独通过 `/node`。 。 。 .

## 安装

```bash
pnpm add @cherrystudio/provider-registry zod@^4.4.3
```

第一次发行版本为 `0.1.0` 通过更改器并使用 `latest` 标签. Zod是一个对等依赖,所以应用程序可以 用同样的 Zod 安装来组成输出计划.

## 包装目录

```typescript
import { createRegistry } from '@cherrystudio/provider-registry'
import { bundledCatalog } from '@cherrystudio/provider-registry/data'

const registry = createRegistry(bundledCatalog)
const provider = registry.findProvider('openai')
const model = registry.findModel('gpt-6.1-sol')
const override = registry.findOverride('cherryin', 'qwen/qwen3.5-9b')
```

捆绑包中包含所有三个经过验证的目录,可离线使用,包括: 在第一次发射。 仅导入核心不会装入任何目录 JSON.

| 条目 | 出口 |
| --- | --- |
| `@cherrystudio/provider-registry` | `createRegistry`, (中文(简体) ), `parseModelSnapshot`计划、类型、清单、合同和纯公用事业 |
| `@cherrystudio/provider-registry/data` | `bundledCatalog` |
| `@cherrystudio/provider-registry/data/providers` | `bundledProviders` |
| `@cherrystudio/provider-registry/data/models` | `bundledModels` |
| `@cherrystudio/provider-registry/data/provider-models` | `bundledProviderModels` |
| `@cherrystudio/provider-registry/node` | 文件阅读器, `RegistryLoader` 和桌面显示相容性策略 |

Raw JSON 也导出为 `/data/providers.json`, (中文(简体) ), `/data/models.json`,以及 `/data/provider-models.json`。每个文件保留其内容-hash `version`。 。 。 . JavaScript数据条目避免了平台专用的JSON导入语法.

## 查询合同

`createRegistry(catalog)` 接受验证 `RegistryCatalog`。处理其投入 记录和返回的记录为只读;核心不深克隆或被冻结. 查询列表按只读数组键入.

| 方法 | 结果 |
| --- | --- |
| `listProviders()` | 受托提供者定义 |
| `listModels()` | 此快照中的基准模型 |
| `getOverridesForProvider(providerId)` | 特定供应商的覆盖,而不是完整的服务型号清单 |
| `findProvider(providerId)` | 精确提供者匹配,或 `null` |
| `findModel(modelId)` | 精确的模型匹配,然后保持大小的回落,或者 `null` |
| `findOverride(providerId, modelId)` | 在恢复正常倒计时前精确的划线/API ID匹配,或 `null` |

缺失的模型大小从不回落到另一个大小. Canonic 供应商查询 偏好在日期相近的 API 变体共存时使用自变体;每个日期相近的变体仍保留 可用自己的 API ID 地址 。 规范化只定位元数据:保留 API ID 通过模型发现返回,或用户在提出请求时明确提供. 普通目录密钥不是替换请求ID .

现有 `lookupRegistryModel()` 方便功能使用相同的匹配 规则和解决一个API的别名 通过其覆盖的 Cononical 模型ID.

## 下载快照

应用程序拥有下载、验证和激活功能. 在创建替换注册前分析两个模型文件 :

```typescript
import { createRegistry, parseModelSnapshot } from '@cherrystudio/provider-registry'
import { bundledProviders } from '@cherrystudio/provider-registry/data/providers'

const snapshot = parseModelSnapshot({
  models: JSON.parse(modelsText),
  providerModels: JSON.parse(providerModelsText)
})
const replacement = createRegistry({ ...snapshot, providers: bundledProviders })
```

`modelsText` 财务报告和审定财务报表 `providerModelsText` 上述是应用程序提供的字符串. `parseModelSnapshot` 验证其结构并应用每入计数器 向前兼容。 它不检查显示的散列、运行时间支持或新鲜度. 丢弃无效的信封; 不兼容的条目和未知的列表词汇被省略 根据共同计划。 提供者的路由不属于此输入.

在激活前,应用程序必须验证清单,两个文件版本, 它的运行时间支持语义学。 切换完整的快照一起。 一个 应用程序可以从捆绑后的数据开始,恢复相容的新保存快照, 并检查背景中的远程更新。 更新失败离开当前视图 可用 。 建立替换登记册不会改变现有的登记册.

内容散列证明身份,而不是时间顺序. 工作流程修订只是 在其出版物流中具有可比性。 应用程序必须保留源/源代码 决定保存或远程数据是否取代捆绑快照时的出处; 此软件包不会从散列或 npm 版本中创建命令 .

未签名的远程数据可能更新模型和提供者-模型覆盖,但不得 替换信任的提供者连接、目的地或证书。 应用程序 继续拥有自定义提供者、用户覆盖、产品排除和运行时间 能力预测。 在计划中承认一种推理方言并不意味着 应用程序的 Pi 或 AI SDK 适配器可以执行 .

## 节点文件加载

```typescript
import { createRequire } from 'node:module'
import { RegistryLoader } from '@cherrystudio/provider-registry/node'

const require = createRequire(import.meta.url)
const loader = new RegistryLoader({
  models: require.resolve('@cherrystudio/provider-registry/data/models.json'),
  providers: require.resolve('@cherrystudio/provider-registry/data/providers.json'),
  providerModels: require.resolve('@cherrystudio/provider-registry/data/provider-models.json')
})

const model = loader.findModel('gpt-4o')
loader.invalidate()
```

节点加载器读取懒散,共享可移植的搜索索引,并释放缓存 数据在闲置超时后. `readModelRegistry`, (中文(简体) ), `readProviderRegistry`,以及 `readProviderModelRegistry` 仍可读取一发.

## 兼容性和平台界限

-   套件版本描述公共JavaScript/TypeScript API.
-   `REGISTRY_SCHEMA_VERSION` 描述遥远的JSON出版道.
-   `REGISTRY_MIN_APP_VERSION` 是该道的桌面语义地板,而不是 移动应用程序版本或证明另一个运行时间支持每个字段.
-   `CatalogManifestSchema` 和文件/schema常数可从核心中获取. 现有桌面 `isCatalogManifestCompatible(manifest, appVersion)` 政策 保留在 `/node`; Mobile 拥有下载录用和旧cache修复.
-   根和数据条目支持无害环境管理、共同JS和反应原生出口条件. 它们包含无节点文件系统或Electron导入. 实际的博览会/设备验收 仍然是消耗性应用程序整合检查的一部分.

## 发展

三个 `data/*.json` 文件生成。 编辑 `src/creators/` 或者说 `src/providers/` 运行生成器; 永远不要手动编辑目录数据 。 贡献者指示和 架构文档存在于此软件包的源文件库中.

对于提供者连接或服务器工具选择器更改, `--providers-only` 重建 从承诺的模型目录中获取供应商配置和工具资格 提供者拥有的独立模型,而不获取上游目录 :

```bash
pnpm --filter @cherrystudio/provider-registry exec tsx scripts/generate-catalog.ts --write --providers-only
pnpm exec oxfmt --write packages/provider-registry/data/providers.json packages/provider-registry/src/patterns/server-tool-models.gen.ts
```

刷新一个犬科模型及其提供者的报价,同时保留无关 目录行, 使用 `--model` (重复它为多个模型). 这也是再生 来源自有的提供者配置和能力指数:

```bash
pnpm --filter @cherrystudio/provider-registry exec tsx scripts/generate-catalog.ts --write --model gemini-4-argon
pnpm exec oxfmt --write packages/provider-registry/data/*.json packages/provider-registry/src/patterns/*.gen.ts
```

选中的模型必须存在于新生成的目录中; 未知的ID失败 没有写文物。 奥米 `--model` 用于正常的全上游新鲜.

从单列波根:

```bash
pnpm --filter @cherrystudio/provider-registry build
pnpm --filter @cherrystudio/provider-registry test:package
pnpm --filter @cherrystudio/provider-registry compat:check
```

`test:package` 在工作空间外建造并安装一个柏油球,检查两个模块 格式和声明,为浏览器构建可移植的表面,并练习 反应本地导出分辨率 。 它要求访问 npm 注册.

在发布新的不兼容远程方案之前, 递增 `REGISTRY_SCHEMA_VERSION` 内 `src/catalog.ts` 乘以一个并运行 `pnpm --filter @cherrystudio/provider-registry compat:baseline`。 。 。 . 冻结基线 `compat/` 不得重写。 运行时语义添加 提高桌面版底需要新流;现有流保留其流.

## 许可证

麻省理工学院. 见 [自由主义](https://npmcn.com/package/%40cherrystudio/provider-registry/LICENSE)。 。 。 .

## 常见问题

### @cherrystudio/provider-registry 是什么？

跨平台的 AI 供应商和模型目录、 计划, 和查询公用事业

### 如何安装 @cherrystudio/provider-registry？

在项目目录运行 npm install @cherrystudio/provider-registry，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.4\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cherrystudio/provider-registry 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cherrystudio/provider-registry 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cherrystudio/provider-registry 可以商用吗？

@cherrystudio/provider-registry 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cherrystudio/provider-registry 的下载量有多少？

根据 npm 官方下载统计，@cherrystudio/provider-registry 在 2026/10/10 – 2026/11/08 这 30 天内被下载 4,482 次，日均约 149 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cherrystudio/provider-registry 还在维护吗？

最新版本 0\.4\.0 发布于 2026/11/09（今天）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/10/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。