# @agentproto/catalog-sync 中文文档

规范地址：https://npmcn.com/package/%40agentproto/catalog-sync/

版本：0\.9\.1
npm 元数据更新时间：2026-11-05T17:46:18.665Z
中文译文更新时间：2026-11-08T11:07:55.607Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40agentproto/catalog-sync
原文对照：https://npmcn.com/package/%40agentproto/catalog-sync/?lang=original
项目主页：https://agentproto.sh/
源码仓库：https://github.com/agentproto/ts

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

- 包体积（解压后）：6.5 MB，45 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.9\.0
- 运行依赖：2 个
- 首次发布：2026-06-30T00:12:40.196Z
- 最新版本发布：2026-11-05T17:46:18.096Z
- 近 30 天下载量：1795（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 37 个）

## 中文简介

用于 @ agentproto/ model- catalog 的构建时间生成器框架 。 由被绑定的提供者来源(LLM,图像,视频,音频,语音)生成 \*.

## 安装

```sh
npm install @agentproto/catalog-sync
```

也可以使用：`pnpm add @agentproto/catalog-sync`、`yarn add @agentproto/catalog-sync`、`bun add @agentproto/catalog-sync`

## README

# @ agentproto/ catalog- sync

构建时间生成框架 [`@agentproto/model-catalog`](https://npmcn.com/package/%40agentproto/model-catalog)。 。 。 . 数据目录(价格,模型列表)是 **生成** 从被钉住的提供者 来源,而不是手动承诺 `*.generated.ts` 可复制自 和CI捕捉漂流经过 `--check`。 。 。 .

## 合同

```ts
// src/types.ts — FROZEN
interface CatalogSource { id: string; url: string }
interface GeneratorContext {
  fetchSource(src: CatalogSource): Promise<unknown>  // snapshot-first; refresh fetches + writes
  refresh: boolean
}
type GeneratedFiles = Record<string, string>  // repo-relative path → TS source text
interface CatalogGenerator {
  name: string                 // "llm:openrouter"
  modality: "llm" | "image" | "video" | "audio" | "voice"
  sources: CatalogSource[]
  generate(ctx: GeneratorContext): Promise<GeneratedFiles>
}
function defineGenerator(g: CatalogGenerator): CatalogGenerator
```

一只兄弟会的毒剂在这个地表上建造了供货发电机。 添加新内容 生成器是扩展路径; 编辑 `types.ts` 没有.

## 流动

```
provider API ──(generate --refresh)──▶ snapshots/<id>.json   ← committed, deterministic
                                              │
                            generate (offline) ▼
                                          *.generated.ts   ← drop-in for model-catalog
```

-   **默认下线.** `generate` 读取 `snapshots/<id>.json`测试和CI 从来没有打过网络.
-   **网络只落在后面 `--refresh`**,它获取每个源被绑定的 URL 并写下线下运行的快照 .

## 国 际

```
pnpm --filter @agentproto/catalog-sync generate          # write changed files
pnpm --filter @agentproto/catalog-sync generate --check  # diff vs committed; exit 1 on drift (CI)
pnpm --filter @agentproto/catalog-sync generate --refresh  # re-fetch pinned sources
```

## `addedAt` 公约

一些发电机(目前) `llm:openrouter` 财务报告和审定财务报表 `llm:requesty` - 两个 生产 `LLMPricing` 条目) `addedAt?: string` 字段( ISO) `YYYY-MM-DD`)在每条目录条目上:首次看到模型代号的日期 通过同步运行.

-   **后充规则.** 当提供者源本身带有一个创建 标识的时标( Open Router's 和 Requerty ) `/v1/models` 都带着 a 离子秒数 `created` 字段),一个全新的代号被回填 日期,转换为 `YYYY-MM-DD`当来源没有这样的领域时 代之以同步运行日期的标识.
-   **从来无常相.** 一旦一个ID有 `addedAt` 邮票,它是 从未被后来的运行所覆盖——即使源头是自己的 `created` 对这个ID的价值,后来解决了不同的东西。 模型标识 消失和后来再现的印章 正在寻找新添加.
-   **机制:每个生成者分类账文件**发生于 `packages/catalog-sync/ledger/<generator-id>.json` (例如:. `ledger/llm-openrouter.json`)——一平房 `{ "model/id": "YYYY-MM-DD", ... }` 映射, 排序的密钥, 决定序列化 。 每个发电机读取它的 直接关闭磁盘的自有分类账( 平面) `node:fs` 改为: `GeneratorContext` 故意没有一般的复读能力;分类账是 发电机内部问题,不是被冻结的部分 `types.ts` 合同, 合并当前运行的 ids 通过 `computeAddedAtLedger` (见 `src/added-at.ts`),并将更新的分类账作为第二个条目返回 联合国 `GeneratedFiles` 这样啊 `runner.ts`已存在的 diff/ 写入逻辑(和 `--check`漂移检测)免费覆盖分类账文件,与任何 其它生成的文件.
-   编辑器条目是 **从未下降**即使对于身份证明 不再存在在一个 运行——分类账记录"第一次见到",而不是"目前在场".

见 `src/added-at.ts` 执行进展情况 `src/generators/llm-openrouter.ts` 编号 : `src/generators/llm-requesty.ts` 因为它是发电机的电线.

## `CATALOG-CHANGELOG.md`

`packages/model-catalog/CATALOG-CHANGELOG.md` 是人可读的"什么" 模型已更改“ 日志 —— 而非由更改器驱动 `CHANGELOG.md` 旁边 (一个是包版历史,每个出版一个条目). 它会回答的 "什么是目录同步添加或去除,以及何时",通过从上到下地读取.

-   **自动写入** 以 `runGenerators` (单位:千美元)`src/runner.ts`),不通过 手给我 收集每个生成器的输出后, 运行器 diff 每个 已更改 `*.generated.ts` 文件的顶级 id 密钥( 前 vs 后 --) 见 `src/changelog.ts`是因为 `extractRecordIds` 编号 : `diffModelIds`和,何时 至少一个生成器实际添加或删除了模型 id, 附加一个 日期:
    
    ```
    ## 2026-08-31
    
    ### llm:requesty
    - Added: alibaba/qwen3.8-flash, alibaba/qwen3.8-max, ...
    - Removed: anthropic/claude-opus-4-1, ...
    ```
    
-   **段落在文件的末尾( 最新最后一页) 附加** - 一个平地, 非破坏性 `+=`这是对"最新第一"的刻意选择; 意思是作家永远不必 分析并重现过去的历史,只是 结会.
    
-   **没有ID级漂流的跑步什么也没有发出** 没有空的,没有 触摸的文件,没有diff。 仅定价的改变(模型的价格移动了但没有) id被添加/删除)不在此登录;它们可见于 已生成文件的 git 历史 .
    
-   添加分类账文件( A)`ledger/*.json`)被故意排除在此范围之外 diff——他们从未丢失过一个id(见上文),所以没有携带"被撤销" 并且每个"添加"的id 已经覆盖在 自有发电机 `*.generated.ts` d.
    

## 发电机

### `llm:openrouter`

资料来源: `https://openrouter.ai/api/v1/models` (标注快照: `snapshots/llm-openrouter.json`) (中文(简体) ). 输出 `packages/model-catalog/src/llm/openrouter-routes.generated.ts` ——一来一来 `OPENROUTER_ROUTES: Record<string, LLMPricing>` 加上导出 `OPENROUTER_PROVIDERS` 列表中选择一个选项.

-   美元价格 − `inputPer1M` 编号 : `outputPer1M` (每100兆令牌美元).
-   `cache_read` 编号 : `cache_write` (当在时) `cacheReadMultiplier` 编号 : `cacheWriteMultiplier` (ratio vs 碱性输入). 承诺的模型目录 文件省略了这些; 当源文件携带时, 此生成器会释放它们 (P3 spec:"如果来源有附加缓存字段")——添加和 `LLMPricing`\- 兼容.
-   `pricing.overrides` 仅按键于 `min_prompt_tokens` − a 个 `tiers` 数组( r)`{ aboveInputTokens, inputPer1M, outputPer1M, … }`)在行上,所以,(笑声) 长期促销的账单 利率较高。 时间折扣被忽略.
-   无价路线(`openrouter/auto`)被跳过.
-   `addedAt` (ISO 日期,先看后看,从未变异)通过 `ledger/llm-openrouter.json` 分类账 -- -- 见 "`addedAt` 《公约》,上文.

### `llm:requesty`

资料来源: `https://router.requesty.ai/v1/models` (标注快照: `snapshots/llm-requesty.json`) (中文(简体) ). 输出 `packages/model-catalog/src/llm/requesty-routes.generated.ts` ——一来一来 `REQUESTY_ROUTES: Record<string, LLMPricing>` 加上导出 `REQUESTY_PROVIDERS` 列表中选择一个选项.

-   按美元计的价格(JSON数字) `inputPer1M` 编号 : `outputPer1M`。 。 。 .
-   `cached_price` 以 `cacheReadMultiplier` 只当来源也 标记 `supports_caching: true`; 请求没有缓存写价, 所以 `cacheWriteMultiplier` 永远不会被释放.
-   需要实时刷新 `REQUESTY_API_KEY` 要设置; 没有它, 生成器 重用承诺的快照.
-   `addedAt` (ISO 日期,先看后看,从未变异)通过 `ledger/llm-requesty.json` 分类账 -- -- 见 "`addedAt` 《公约》,上文.

### `llm:context-windows`

资料来源:Anthropic、Groq、xAI和月球相机模型列表终点 快照 : `snapshots/llm-anthropic.json`, (中文(简体) ), `snapshots/llm-groq.json`, (中文(简体) ), `snapshots/llm-xai.json`, (中文(简体) ), `snapshots/llm-moonshot.json`) (中文(简体) ). 输出 `packages/model-catalog/src/llm/context-windows.generated.ts` ——一来一来 `CONTEXT_WINDOWS: Record<string, ContextWindowEntry>`。 。 。 .

-   `contextWindow` 每个提供者的最大输入/文本长字段的地图.
-   `maxOutput` 当来源发布时被捕获.
-   这是 **非定价**;计费数据仍来自 `llm:openrouter` 财务报告和审定财务报表 手动维护的定价条目 `model-catalog`。 。 。 .
-   OpenAI和ZAI/Zhipu被排除在外,因为他们不发表一个马厩, 机器可读上下文窗口列表.

## 常见问题

### @agentproto/catalog-sync 是什么？

用于 @ agentproto/ model- catalog 的构建时间生成器框架 。 由被绑定的提供者来源\(LLM,图像,视频,音频,语音\)生成 \*\.

### 如何安装 @agentproto/catalog-sync？

在项目目录运行 npm install @agentproto/catalog-sync，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 catalog-sync，可以用 npx catalog-sync 直接运行。

### @agentproto/catalog-sync 支持 TypeScript 吗？

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

### @agentproto/catalog-sync 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agentproto/catalog-sync 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.9\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agentproto/catalog-sync 可以商用吗？

@agentproto/catalog-sync 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agentproto/catalog-sync 的下载量有多少？

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

### @agentproto/catalog-sync 还在维护吗？

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