# @effected/schemastore-cli 中文文档

规范地址：https://npmcn.com/package/%40effected/schemastore-cli/

版本：0\.29\.0
npm 元数据更新时间：2026-11-02T18:38:36.829Z
中文译文更新时间：2026-11-14T00:30:44.001Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40effected/schemastore-cli
原文对照：https://npmcn.com/package/%40effected/schemastore-cli/?lang=original
项目主页：https://github.com/spencerbeggs/effected/tree/main/packages/schemastore-cli#readme
源码仓库：https://github.com/spencerbeggs/effected

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

- 包体积（解压后）：104 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.11\.0
- 运行依赖：8 个
- peer 依赖：effect ~4\.1\.0，@effected/schemastore 0\.29\.0
- 首次发布：2026-09-14T04:56:04.501Z
- 最新版本发布：2026-11-02T18:38:36.453Z
- 近 30 天下载量：2714（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

Schemastore 命令:从 schemastore.config.ts 来建立和检查 SchemaStore-形状的 JSON Schema 文档,并有每schema 公布的旗帜和漂移政策.

## 安装

```sh
npm install @effected/schemastore-cli
```

也可以使用：`pnpm add @effected/schemastore-cli`、`yarn add @effected/schemastore-cli`、`bun add @effected/schemastore-cli`

## README

# @ effected/ schemastore-cli

[![npm](https://img.shields.io/npm/v/@effected%2Fschemastore-cli?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/schemastore-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT) [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/) [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)

这个 `schemastore` 命令: 从 a 创建并检查 SchemaStore 形状的 JSON Schema 文档 `schemastore.config.ts`,并对照已公布的文件验证有效载荷。 这是同伴 [`@effected/schemastore`](https://www.npmjs.com/package/@effected/schemastore),它拥有管道和各种类型的配置需要; 这个包将每个消费者用手书写的管道—— 配置加载器、漂移政策、被冻结的标签检查、目录文件、退出代码、一个 GitHub 步骤摘要—— 一次作为 `bin`。它也是验证引擎所居住的地方: `AjvValidator` (文件)和 `AjvInstanceValidator` (活塞),在严格模式下,ajv都在一个共享设置之上,由命令组成,并为驱动管道或验证有效载荷本身的程序而输出出,所以库中保留了ajv.

> **预`1.0.0`。 。 。 .** 此软件包是 `@effected/*` 在稳定基础上建造的工具包 效应v4(`effect` `~4.1.0`) 并仍在 `0.x` 发展。 稳定效果 制作一个工具箱 `1.0.0` 可能,不是自动的。 为了保持你的 `effect` 财务报告和审定财务报表 `@effect/*` 该工具包在线上构建和测试、安装 [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected)。 。 。 .
> 
> **稳定:不稳定.** 此软件包的 API 表面尚未考虑 完成并可能改变 `0.x` 释放 定一个确切的版本——甚至 标记软件包 _稳定_ 在此之前 `1.0.0` 可以引入突破性更改 和精确的针 变成一个类型检查错误 而不是一个 跑步时间惊喜。 完全政策: [释放策略](https://github.com/spencerbeggs/effected#release-strategy)。 。 。 .

## 安装

两个软件包在一个版本一起发行. 库是一个常规的依赖(应用程序在运行时从它读取其schema的身份);命令是devDependency.

```bash
pnpm add @effected/schemastore effect
pnpm add -D @effected/schemastore-cli
```

`effect` 财务报告和审定财务报表 `@effected/schemastore` 是命令的同伴,所以您的配置和管道各分享一个实例.

## 配置

在申请中 `$schema` 从它,而配置 将同样的值交到 `defineConfig` 所以,没有拼写两次:

```ts
// src/schema/output.ts
import { HostedSchema } from "@effected/schemastore";
import { Schema } from "effect";

export const OUTPUT_SCHEMA_VERSION = "5.2";

export const OutputSchemaIdentity = HostedSchema.github({
  repo: "savvy-web/silk-release-action",
  path: "schemas",
  name: "silk-release-action.output",
  versions: [OUTPUT_SCHEMA_VERSION],
});

export const ReleaseOutput = Schema.Struct({
  $schema: Schema.Literal(OutputSchemaIdentity.$id),
  status: Schema.Literals(["released", "skipped"]),
});
```

```ts
// schemastore.config.ts (also .mts, .js, .mjs; found by walking upward, or passed as the positional argument)
import { defineConfig } from "@effected/schemastore";
import { OutputSchemaIdentity, ReleaseOutput } from "./src/schema/output.js";

export default defineConfig({
  // This config's identity: its catalog slice is catalogs/<name>.json.
  name: "silk-release-action",
  // Relative paths resolve against this file's directory.
  outputDir: "schemas",
  schemas: {
    [OutputSchemaIdentity.name]: { schema: ReleaseOutput, hosted: OutputSchemaIdentity },
  },
});
```

```json
{
  "scripts": {
    "schema:build": "schemastore build",
    "schema:check": "schemastore check"
  }
}
```

`schema:build` 写入 `schemas/5.2/silk-release-action.output-5.2.json`· ; `schema:check` 在 CI 中失败, 只要一个建筑会写任何东西。 跳出版本是一个常数,一旦一个标签被运出,它就留在 `versions` 作为被冻结的文件,命令进行验证,但永远不会再生.

出版给SchemaStore本身使用的计划 `HostedSchema.schemastore` 并声明其目录条目; 命令集合了配置目录片和合并的每个条目 `catalog.json`数字 :

```ts
export default defineConfig({
  name: "okfit",
  outputDir: "schemas",
  schemas: {
    okfit: {
      schema: OkfitConfig,
      hosted: HostedSchema.schemastore({ name: "okfit", versions: ["1.0"] }),
      published: true,
      catalog: { description: "okfit configuration", fileMatch: ["okfit.toml", ".okfit.toml"] },
    },
  },
});
```

### 入境合同

-   关键是计划 `name`· ; `$id`,写 `path` 而每个目录 URL 来源于它和身份。 没有 `$id` 超过。 与 `hosted`,键必须平等 `hosted.name` 财务报告和审定财务报表 `baseUrl` 编号 : `versions` 编号 : `current` 编号 : `layout` 决不能用拼写来形容它 `hosted`,拼写这些字段(和顶层) `baseUrl` 默认)和命令为您构建身份.
-   `versions` 列出目录广告的每个标签; `current` (默认:最新)是生成于 `path` 编号 : `$id`。其他标签是 **冻结**: 它必须存在于磁盘上并声明 `$id` 或者在写出任何内容之前就失败了`FrozenVersionMissingError`, (中文(简体) ), `FrozenVersionIdMismatchError`A级 `repo` 编号 : `branch` 编号 : `path` 编号 : `baseUrl` 因此,改变是每个被冻结的标签的重现事件。 在第一次运行时宣布一个单一的标签; 仅在第一次发货后附加下一个标签 .
-   `appendVersion` (默认) `true`保持SchemaStore的状态 `-<version>` 文件后缀; `false` 允许版本目录单独命名文件( e)`schemas/6.0/output.json`并且要求 `"versioned"` 设置。 喜欢 `baseUrl`属于 `hosted` 当它被赋予, 翻转它是一个重现事件 每个被冻结的标签.
-   `published` (默认) `false`)标记其他已经依赖的版本:通过任何变化而实现的未发表的计划再生,出版的则坚持漂移政策.
-   `drift` (单位:千美元)`strict` 编号 : `semantic` 编号 : `allow`默认值 `semantic`和 `onDrift` (单位:千美元)`error` 编号 : `warn`)是顶层默认值; `drift`, (中文(简体) ), `published`, (中文(简体) ), `jsonSchema` 财务报告和审定财务报表 `rootAnnotations` 每个条目可设定。 物体发射关闭(`additionalProperties: false`(三); `jsonSchema: { onExcessProperty: "ignore" }` 打开一个文档.
-   `name` (需要,上层)是配置的身份:一个简单的文件基名,在配置中区别于共享 a `catalogDir` 案件不敏感,因为案件不敏感 `docs` 财务报告和审定财务报表 `Docs` 是每个构建覆盖的切片文件。 何时 `<name>.json` 在列表中缺失,但卷解为一个文件,仅在大小写不敏感的情况下(一个大小写不敏感卷),该文件作为配置的切片被请求,并被标记在报告行上;在大小写不敏感卷中,文件是另一个切片,所以只有大小写才能重命名所剩的合并,直到被删除,就像任何重命名所剩的.
-   `catalog` 在 SchemaStore 主机下需要,在自定义主机下需要可选。 每个条目的配置 宣布土地在一个切片文件中, `<catalogDir>/<name>.json` (单位:千美元)`catalogDir` 默认为 `<outputDir>/catalogs`),命令维持合并 `catalog.json` 内 `catalogDir`父母亲 `<outputDir>/catalog.json` 默认情况下 `url`因此,几个配置可以共享一个 `outputDir`: 每一个只重写自己的切片, 而哪个建筑最后写相同的合并文件, 所以 `check` 对所有人都是绿色的. `catalogDir` 只持有切片 : `defineConfig` 拒绝一个是 `outputDir`,这就是合并目录本身的路径,或者一个衍生文档坐落在其中。 每个共享合并目录的配置必须共享相同的目录 `catalogDir` 将兄弟目录合并为一个目录 `catalog.json` 互相覆盖,没有单一的配置可以看见.
-   在配置中任何地方的打字"d"密钥都是被命名并拒绝的,永远不会被忽略,一个条目上的每个问题都会同时被报告.

## 图标

```text
schemastore build [config] [--drift=strict|semantic|allow] [--on-drift=error|warn] [--force] [--format=human|json]
schemastore check [config] [--drift=strict|semantic|allow] [--on-drift=error|warn] [--force] [--format=human|json]
schemastore validate <payload.json> [config] [--schema <path|$id|url>] [--format=human|json]
```

-   在生成任何东西之前,每个被冻结的标签都经过验证——在磁盘上显示,并由衍生物自我识别 `$id`。 。 。 .
-   `build` 生成每个图案, 运行门( 结构 lint 和 ajv 严格模式) , 应用漂移策略, 并写出通过的内容—— 内容对比, 因此一个不变的文件没有被更改—— 加上任何条目宣布一个时的 catalog 片段, 以及每个片段的合并目录 .
-   `check` 是相同的行走,没有写: 它报告什么 `build` 将在同一旗帜下进行,并以同样的方式退出,而且失败(退出) `1`) 每当建筑物会写出任何东西时——陈旧或缺失的文件通过运行固定 `schemastore build` 并做出结果。 上次配置后留下的目录片 `catalog` 报告已删除块 `orphaned` 失败 `check` 同样的方式,但 `build` 永远不删除它——合并目录一直发布其条目,直到它消失:手动删除文件,或恢复一个 `catalog` 块; 合并 `catalog.json` 没有了切片就成了孤儿 遗留在旧的衍生名称下的文档也是这样 `appendVersion` 翻转或一个 `layout` 更改移动了它的路径,没有东西再声称旧文件了: 两个命令都探测到兄弟会的形状(`<name>.json`, (中文(简体) ), `<name>-<v>.json`, (中文(简体) ), `<v>/<name>.json`, (中文(简体) ), `<v>/<name>-<v>.json`) 每一个标签中, 配置仍然宣布并报告每个作为孤儿文件存在的标签, 失败于 `check`,从不删除 `build`没有其他 `outputDir` 被查看,所以与另一个配置共享,一个部署文件夹,或者寄存器根是安全的(除非两个配置在不同的布局下得出相同的计划名和版本); a `name` 更改或丢弃的标签会留下命令无法知道的文件——用手删除。 多个切片广告的目录 URL 或条目名称, 或无法读取或不是目录条目数组( 包含一个未宣布的密钥) , 封锁合并目录: 两个命令都失败( 退出) `1`)命名 URL 或名称及其切片或无效切片,合并后的文件按原样保留到配置或切片固定为止.
-   `validate` 回答出版物故事中存在的问题:该有效载荷是否与其所命名的已公布文件相一致? 参考文献是 `--schema` 旗帜或有效载荷本身 `$schema`,先解析文件,然后针对每个身份,一个配置图源(目标) `$id`一个冷冻的版本 `$id`编号 :`url`,目录 `url`)——CI验证一个动作的输出相对于承诺的文件,没有第三方工具,也没有网络取取. 载荷的 `$schema` 自引用是指定文档名称的指针:只有在解析的文档未声明时,在确认前会被剥去 `$schema` 作为根属性,因为生成的文档 `additionalProperties: false` 否则会拒绝给它起名字的自我参照。 有声明的文件 `$schema` - 那个 `HostedSchema` 上方图案,其中源结构带 `$schema: Schema.Literal(...)` 生成的文件需要并制约关键——逐字验证有效载荷。 不符合要求的有效载荷失败(出局) `1`每个问题都有一个发现,每个都携带JSON指针进入实例和关键词; `--format=json` 写出一个报告文档,将人行移动到 stderr .
-   `--drift` 财务报告和审定财务报表 `--on-drift` 覆盖一次运行的配置 ; `--force` 这是糖 `--drift=allow` (与不同的明示合并) `--drift` 这是使用错误.
-   `--format=json` 发布了一份关于 " 标准结果 " 的JSON文件(每一份结果和有效耐受性、目录片和合并目录结果、 `orphaned` 文档路径时, `drift: { onDrift, policy? }`; 人文文字移动到 stderr. 何时 `GITHUB_STEP_SUMMARY` 设置,两个命令都附加一个下标表.

## 引擎作为库输出

命令在严格模式下以 ajv 验证 – SchemaStore 自己的大门 – 注册关键字家族 `@effected/schemastore` 声明和标准 `ajv-formats` 词汇表(仅格式,从不) `formatMaximum` 每个文件一个新实例,通过一个共享的设置,两个引擎都使用这样一个文件 `check` 门也承认在实例引擎中总是编译. 这两个发动机层是这个包的唯一出口,因为一个直接编组管道或验证有效载荷的程序:

```ts
import { SchemaFile, SchemaPipeline } from "@effected/schemastore";
import { AjvValidator } from "@effected/schemastore-cli";
import { NodeServices } from "@effect/platform-node";
import { Effect, Layer } from "effect";

const AppLayer = Layer.mergeAll(SchemaFile.layer, AjvValidator.layer).pipe(Layer.provide(NodeServices.layer));

const program = SchemaPipeline.run(targets).pipe(Effect.provide(AppLayer));
```

```ts
import { InstanceValidator } from "@effected/schemastore";
import { AjvInstanceValidator } from "@effected/schemastore-cli";
import { Effect } from "effect";

const program = Effect.gen(function* () {
  const validator = yield* InstanceValidator;
  return yield* validator.validate(document, payload);
}).pipe(Effect.provide(AjvInstanceValidator.layer));
```

调查结果以价值形式出现 `ValidationFinding` 在文档中指向 `AjvValidator`, (中文(简体) ), `InstanceFinding` 指入有效载荷 `AjvInstanceValidator`; 错误频道携带 `SchemaValidatorError` 编号 : `InstanceValidatorError` 只有在引擎作为机制失败时.

## 退出代码

报告在 `@effected/cli-kit` 标准窗体:一个指定错误及其消息的状态行,消息的再行,当失败发生在命令的某个跨度之内时,一个 `in: …` 线条命名它们(缺失的配置,在任何跨度前提出,不打印)。 它被画在一个终端,平地为代理,并为GitHub Actions下的日志所写. 读出出站码,不是行形.

| 代码 | 含义 |
| --- | --- |
| 0 个 | 成功,包括漂移 `onDrift: warn` |
| 1个 | 飘入海底 `onDrift: error` (每漂流计一行: `$id`、更改、当前和下一个版本)、闸门故障、缺少或错误识别的被冻结版本、被两次广告的URL或名称所屏蔽的合并目录或无效切片,用于 `check` - 任何东西 `build` 将不写或输出任何索赔(孤儿目录片或合并目录,或以衍生路径的兄弟姐妹形状的孤儿文件),或 `validate` 不符合已解决文件的有效载荷(每个问题一个发现,每个指针和关键词) |
| 2个 | 未找到配置, 装入失败, 失败 `defineConfig` 审定,a `catalogDir` 是文件或无法列出的(在撰写任何文件之前核对),或 `validate` - 无法读取或分析的有效载荷,或 `--schema`编号 :`$schema` 引用既非现有文件,也非身份 任何配置图,或命名无法读取或解析的文档 |
| 3个 | 基础设施故障 `validate`,引擎机制失败——实例引擎无法编译的文档——包含) |
| 64国道 | 使用错误(用于 `validate`,无有效载荷 `$schema` 没有 `--schema` (b) 提供,包括); `--wizard` 是工具箱的即时标出,所以一个不交互的跑步(管子,CI,代理)将其抛出帮助而拒绝 `64` (当时已接受) `0` 在命令移动之前 `CliRuntime.main`(中文(简体) ) |

## 许可证

麻省理工学院

## 常见问题

### @effected/schemastore-cli 是什么？

Schemastore 命令:从 schemastore\.config\.ts 来建立和检查 SchemaStore-形状的 JSON Schema 文档,并有每schema 公布的旗帜和漂移政策\.

### 如何安装 @effected/schemastore-cli？

在项目目录运行 npm install @effected/schemastore-cli，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（~4\.1\.0）、@effected/schemastore（0\.29\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 schemastore，可以用 npx schemastore 直接运行。

### @effected/schemastore-cli 支持 TypeScript 吗？

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

### @effected/schemastore-cli 支持 ESM 还是 CommonJS？

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

### @effected/schemastore-cli 需要什么版本的 Node\.js？

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

### @effected/schemastore-cli 可以商用吗？

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

### @effected/schemastore-cli 的下载量有多少？

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

### @effected/schemastore-cli 还在维护吗？

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