# @epistola\.app/epistola-catalog 中文文档 规范地址：https://npmcn.com/package/%40epistola.app/epistola-catalog/ 版本：2\.0\.0 npm 元数据更新时间：2026-11-12T10:54:55.040Z 中文译文更新时间：2026-11-14T05:21:26.045Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40epistola.app/epistola-catalog 原文对照：https://npmcn.com/package/%40epistola.app/epistola-catalog/?lang=original 项目主页：https://github.com/epistola-app/epistola-contract#readme 源码仓库：https://github.com/epistola-app/epistola-contract ## 关键信息（来自 npm 元数据） - 包体积（解压后）：848 kB，151 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：0 个 - 首次发布：2026-07-28T20:15:01.898Z - 最新版本发布：2026-11-12T10:54:54.680Z - 近 30 天下载量：2285（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：23（近 12 个月 23 个） ## 中文简介 该目录合同界定了Epistola Suite、Exchange和其他消费者之间移动的便携式内容。 它是编目线条格式、模板模型、注册、符合性装置、验证、犬科化、偏头痛的真相来源 ## 安装 ```sh npm install @epistola.app/epistola-catalog ``` 也可以使用：`pnpm add @epistola.app/epistola-catalog`、`yarn add @epistola.app/epistola-catalog`、`bun add @epistola.app/epistola-catalog` ## README # Epistola目录合同 该目录合同定义了在Epistola之间移动的可移植内容 套房 交易所 以及其他消费者 它是目录的真相来源 电线格式、模板模型、登记册、符合装置、验证、, 移民 和档案处理. ## 权威来源 | 关切 | 来源 | | --- | --- | | 模板和主题形状 | [`schemas/`](https://npmcn.com/package/%40epistola.app/epistola-catalog/schemas/) | | 组件和样式词汇 | [`registry/`](https://npmcn.com/package/%40epistola.app/epistola-catalog/registry/) | | 便携式相容性示例 | [`fixtures/`](https://npmcn.com/package/%40epistola.app/epistola-catalog/fixtures/) | | 语义验证和归档行为 | [`src/main/kotlin/`](https://npmcn.com/package/%40epistola.app/epistola-catalog/src/main/kotlin/) | | 类型脚本公用外观 | [`ts/`](https://npmcn.com/package/%40epistola.app/epistola-catalog/ts/) 并生成源 [`generated/`](https://npmcn.com/package/%40epistola.app/epistola-catalog/generated/) | 该目录目前写有线 `schemaVersion: 8`,移动版本 4 到 7,并使用 模板 `modelVersion: 1`已出版的Maven和npm的文物在 仓库协调放行列车. 版本为v5通过v8显示并被资源解析的图案保存了每个被接受的线形. 其未转录的对应方指向 v8, Npm 包根输出类型Script 声明 由当前计划生成. `template-document.schema.json` 是当前(v8)模板 文档; 有线 v5 至 v7 解析它们的 `template-document-v7.schema.json`,保留 主题参考文件 `themeId`。 。 。 . Wire v8用三个独立的部分识别一个目录, **登记**, (中文(简体) ), **命名空间** 和钥匙,以及 版本目录整体 : - `catalog.registry` 财务报告和审定财务报表 `catalog.namespace` 两者都需要。 登记处是交易所 (单位:千美元)`exchange.epistola.app`)或发布自己目录的域名(`acme.com`),总是 完全写入:一个归档没有默认的注册,这是安装配置. 这个 命名空间是该登记簿中的弹片 (`acme-corp`);两个登记册中的同名是两个 名称空间。 (这个注册是目录的一部分,与组件和样式无关) (a) 登记册(见下文) - `catalogDependencies` 声明每个目录, 该目录取决于一次 : **别名** (单位:千美元)`alias`,目录密钥规则,在列表中独一无二,从不包含目录自己的密钥,默认情况下 该目录本身的密钥),以其名称命名(`registry`, (中文(简体) ), `namespace` 财务报告和审定财务报表 `catalogKey`,哪个 发现它释放的较新, 并且随着释放的开始 `releaseFingerprint`,从中复制 释放的 `release.fingerprint` 用于命名算法的窗体(`v6:`,所以一个副本 可从任何登记册或镜像中取出 `releaseVersion`,其数字(即: 编目与该发布并被剪接;声明名称无范围)。 两者都是 只对从线 v7 迁移的目录无效 . - 内容用此命名另一个目录 **别名**,从未按登记或命名空间(合同ADR) 0003):一个主题覆盖,一个stencil或图像节点,一个字体引用和代码列表 绑定 `catalogKey`,模板的 `themeCatalogKey`,目录的 `defaultTheme.catalogKey`, (中文(简体) ), 变量属性密钥的修饰符( q)`system.locale`)和每个资源依赖 `catalogKey`。必须宣布每个别名;不命名别名的参考物,或目录本身的 键,是目录本身。 将依赖性移到另一个发布会更改一个声明, 并重新命名或镜像它不会改变任何内容(`CatalogAliases`, (中文(简体) ), `CATALOG_ALIAS_PATTERN`) (中文(简体) ). - 一个发布是编号的 `MAJOR.MINOR.PATCH` 由目录名称空间的持有人 只发布贴有命名空间标签的补丁释放, `1.3.1-gemeente-x.1`,哪种类型 低于持有者的下一个编号(`CatalogReleaseVersions`, (中文(简体) ), `CATALOG_RELEASE_VERSION_PATTERN`页:1 大部分128个字符,这样每个命名空间都可以标出一个. 格式检查形状,而不是谁 拥有一个命名空间. - 发布内容为: `release.fingerprint` 为 V6 (`v6:`),涵盖 资源,内容设置(`defaultTheme`, (中文(简体) ), `presets`, (中文(简体) ), `license`),由 化名和被钉住的花草 `compatibility`,但目录的名称, 释放块,它的 列报(`name`, (中文(简体) ), `description`, (中文(简体) ), `keywords`, (中文(简体) ), `presentation`, (中文(简体) ), `attributes`, (中文(简体) ), `publisher`, (中文(简体) ), `includes`),或电线版本(`schemaVersion`),所以只有重新编码内容的有线版本 保持每个 V6 值。 演示是名称信息:可以更改 并且最近获得的胜利 这个名字, `release.version` 财务报告和审定财务报表 `release.fingerprint` 是一个名称和数字对散列的归档;见 [强化](https://npmcn.com/package/%40epistola.app/epistola-catalog/docs/catalog-canonicalization.md) 财务报告和审定财务报表 [存档格式](https://npmcn.com/package/%40epistola.app/epistola-catalog/docs/catalog-archive.md)。 。 。 . - Stencils 无版本 : `StencilResource.version` 一个尖端节点没有 `version` 或者说 `draftVersion`。一个表解 通过其目录的依赖. - 资源的公共地址是: `key`; 一个 `id` 仅是一个生成的标识符 不是一个地址。 因此,电线v8说 `key` v7说 `slug` (目录,资源条目, 资源依赖性,每个资源,变体,代码列表绑定), `themeKey` 页:1 `themeId`, (中文(简体) ), 在内容上, `stencilKey` 财务报告和审定财务报表 `imageKey` 用于刻度或图像节点的 `stencilId` 财务报告和审定财务报表 `assetId`, (中文(简体) ), `key` (单位:千美元) `fontFamily` 字体参考 `slug`, (中文(简体) ), `iconImageKey` 财务报告和审定财务报表 `imageKeys` 页:1 介绍 `iconAssetSlug` 财务报告和审定财务报表 `imageAssetSlugs`,以及 `catalogKey` 属性 任务 `catalog`。迁移重新命名它们 沉默;拒绝使用旧名的v8文档. 克特林模型仍然把旧的捆绑起来 名称,使保存在先前版本下的文档继续加载. - 每个资源键都遵循一个规则, `^[a-z0-9]+(-[a-z0-9]+)*$` 有3到50个字符(a) 每种类型允许的主位数字:模板、变体、stencils、主题、, 属性、代码列表、字体、图像和数据示例,以及命名一个的每个位置 (内容引用、资源依赖、代码列表绑定、属性任务、a) 变体的属性密钥,演示文稿的图像密钥). 该目录自己的钥匙 保持它的规则 (一首领信,3-50). v7到v8的迁移垫 右侧有一个更短的 v7 键 `0` (单位:千美元)`nl` 变成 `nl0`并切出一个到50个字符, 重写每一个引用它 同一方式,每个密钥有一个通知(`CATALOG_RESOURCE_KEY_PADDED`, (中文(简体) ), `CATALOG_RESOURCE_KEY_TRUNCATED`) (中文(简体) ). 重写只取决于密钥, 所以目录迁移 两者之间仍然一致; 重写后键与 其范围的另一部分被拒绝(`CATALOG_RESOURCE_KEY_PADDING_COLLISION`, (中文(简体) ), `CATALOG_RESOURCE_KEY_TRUNCATION_COLLISION`而不是给一个不同的钥匙. - 一个模板的数据示例各有一个 `key`,在模板中的地址,旁边 显示 `name`v7到v8的迁移来源于名称,并附有通知 (单位:千美元)`CATALOG_DATA_EXAMPLE_KEY_ASSIGNED`) (中文(简体) ). 模板可能带有纯文本 `description` (最多为 2000 个字符),其表列条目的来源 `description`。 。 。 . - 每个资源都可以携带 `metadata`: 由反向 DNS 键入的生产者专用 JSON 对象 制作人拥有的命名空间( n)`{"com.example.authoring": {"reviewedBy": "design"}}`),该词 合同不提供口译,每个读者都保留。 没有指纹. - 一个清单 `detailUrl`,二进制已贬值 `contentUrl`,是位于 显示目录( e)`./resources/template/letter.json`, (中文(简体) ), `bin/`)),解决 归档根或列表的 URL; 参见 [存档格式](https://npmcn.com/package/%40epistola.app/epistola-catalog/docs/catalog-archive.md)。 。 。 . V7 归档名称没有注册或命名空间, 因此需要同时从进口商移出: pass `CatalogMigrationOptions(namespace, registry)` 改为 `CatalogSchemaMigrator.migrateManifest`, (中文(简体) ), `CatalogArchiveReader.read`,或 `CatalogValidationPolicy(migration = ...)`. 没有他们,移徙 失败 `CATALOG_REGISTRY_MISSING` 或者说 `CATALOG_NAMESPACE_MISSING`。其他目录 a v7 归档名称,在其资源依赖性或(读取全)其内容中,在其中宣告 它的密钥下作为别名的注册和命名空间,所以它的引用保留它们的值. 目录关键词规则定义一次: `CatalogKeywords` 以克特林计算(限制、图案和 和(或) `MAX_CATALOG_KEYWORD_LENGTH`, (中文(简体) ), `MAX_CATALOG_KEYWORDS`,以及 `CATALOG_KEYWORD_PATTERN` 在 TypeScript 中,全部被绑入当前方案。 书记官处和命名空间 规则的定义相同: `CatalogNamespaces` 在克特林,和 `CATALOG_REGISTRY_PATTERN`, (中文(简体) ), `MAX_CATALOG_REGISTRY_LENGTH`, (中文(简体) ), `CATALOG_NAMESPACE_PATTERN`, (中文(简体) ), `MIN_CATALOG_NAMESPACE_LENGTH`, (中文(简体) ), 财务报告和审定财务报表 `MAX_CATALOG_NAMESPACE_LENGTH` 在类型脚本中;和别名规则, `CatalogAliases` 财务报告和审定财务报表 `CATALOG_ALIAS_PATTERN`, (中文(简体) ), `MIN_CATALOG_ALIAS_LENGTH` 财务报告和审定财务报表 `MAX_CATALOG_ALIAS_LENGTH`。 。 。 . 输入目录的路径是 `CatalogArchivePaths` 财务报告和审定财务报表 `CATALOG_ARCHIVE_PATH_PATTERN`; 资源 并发布元数据 `CatalogMetadata` 编辑 `…CATALOG_METADATA…` 常数; 释放 id 是 `CatalogReleaseIds` 财务报告和审定财务报表 `CATALOG_RELEASE_ID_PATTERN`, (中文(简体) ), `MIN_CATALOG_RELEASE_ID_LENGTH` 财务报告和审定财务报表 `MAX_CATALOG_RELEASE_ID_LENGTH`页:1 释放基数( e)`ReleaseBase`)遵循发行号码和指纹规则 (单位:千美元)`ReleaseBase.FINGERPRINT_PATTERN` 财务报告和审定财务报表 `isValidFingerprint`; 资源密钥、数据 其中的示例键为 `CatalogKeys` (单位:千美元)`PATTERN`, (中文(简体) ), `MIN_LENGTH`, (中文(简体) ), `MAX_LENGTH`, (中文(简体) ), `RESOURCE`, (中文(简体) ), `isValid`迁移 `migrate`,以及 `deriveDataExampleKey`和 `CATALOG_RESOURCE_KEY_PATTERN`, (中文(简体) ), `MIN_CATALOG_RESOURCE_KEY_LENGTH` 财务报告和审定财务报表 `MAX_CATALOG_RESOURCE_KEY_LENGTH`;模板描述限制为 `TemplateResource.MAX_DESCRIPTION_LENGTH` 财务报告和审定财务报表 `MAX_TEMPLATE_DESCRIPTION_LENGTH`; 档案 带一个释放它针是 `CatalogDependencyArchivePaths` 财务报告和审定财务报表 `CATALOG_DEPENDENCY_ARCHIVE_PATH_PATTERN`, (中文(简体) ), `parseCatalogDependencyArchivePath` 财务报告和审定财务报表 `catalogDependencyArchivePath`。 。 。 . 制作人应使用这些拷贝,而不是自己的拷贝. ## 构建 ```bash ./gradlew build sourcesJar dokkaJavadocJar pnpm install --frozen-lockfile pnpm generate:types pnpm build npm pack --dry-run ``` 从寄存器根运行相同的检查 : ```bash make build-epistola-catalog ``` ## 文档 - [存档格式](https://npmcn.com/package/%40epistola.app/epistola-catalog/docs/catalog-archive.md) - [标记和指纹](https://npmcn.com/package/%40epistola.app/epistola-catalog/docs/catalog-canonicalization.md) - [兼容性](https://npmcn.com/package/%40epistola.app/epistola-catalog/docs/catalog-compatibility.md) - [目录许可](https://npmcn.com/package/%40epistola.app/epistola-catalog/docs/catalog-licensing.md) - [书记官处](https://npmcn.com/package/%40epistola.app/epistola-catalog/docs/catalog-registry.md) - [便携式验证](https://npmcn.com/package/%40epistola.app/epistola-catalog/docs/portable-catalog-validation.md) - [质量简介](https://npmcn.com/package/%40epistola.app/epistola-catalog/docs/quality-profiles.md) ## 常见问题 ### @epistola\.app/epistola-catalog 是什么？ 该目录合同界定了Epistola Suite、Exchange和其他消费者之间移动的便携式内容。 它是编目线条格式、模板模型、注册、符合性装置、验证、犬科化、偏头痛的真相来源 ### 如何安装 @epistola\.app/epistola-catalog？ 在项目目录运行 npm install @epistola\.app/epistola-catalog，或使用 pnpm add / yarn add / bun add。 ### @epistola\.app/epistola-catalog 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @epistola\.app/epistola-catalog 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @epistola\.app/epistola-catalog 可以商用吗？ @epistola\.app/epistola-catalog 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @epistola\.app/epistola-catalog 的下载量有多少？ 根据 npm 官方下载统计，@epistola\.app/epistola-catalog 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,285 次，日均约 76 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @epistola\.app/epistola-catalog 还在维护吗？ 最新版本 2\.0\.0 发布于 2026/11/12（1 天前）；至今共发布 23 个版本，其中过去 12 个月发布了 23 个；首次发布于 2026/07/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。