# @cli-schema/spec 中文文档

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

版本：0\.2\.0
npm 元数据更新时间：2026-07-13T18:41:57.060Z
中文译文更新时间：2026-11-10T01:26:49.219Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：42.5 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-13T16:32:33.445Z
- 最新版本发布：2026-07-13T18:41:56.706Z
- 近 30 天下载量：9043（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

TypeScript 类型, meta-schema, 和 CLI Schema 规格的验证符( )[https://github.com/cli-schema/cli-schema (中文(简体) )](https://github.com/cli-schema/cli-schema)(中文(简体) )

## 安装

```sh
npm install @cli-schema/spec
```

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

## README

# @cli-schema/ spec

TypeScript 类型、 供应商的元解析器和验证器 [CLI Schema 规格](https://github.com/cli-schema/cli-schema) v1 — 打开标准 以语言不可知、机器可读的方式描述命令行界面.

这是唯一的软件包 [`cli-schema-js`](https://github.com/cli-schema/cli-schema-js) c. 单体,不依赖CLI框架。 它定义 _形状_ 使用 CLI Schema 文件; [`@cli-schema/commander`](https://www.npmjs.com/package/@cli-schema/commander) 其实是这样的 产生一个真正的CLI.

## 快速启动

```sh
npm install @cli-schema/spec
```

```ts
import { validate, SCHEMA_VERSION, type CliSchema } from '@cli-schema/spec'

const doc: CliSchema = {
  schemaVersion: SCHEMA_VERSION,
  name: 'mytool',
  version: '1.0.0',
}

const result = validate(doc)
if (!result.valid) throw new Error(JSON.stringify(result.errors, null, 2))
```

这是最起码的: 文件只需要 `schemaVersion`, (中文(简体) ), `name`,以及 `version` 有效 -- -- 其他一切(命令,参数,环境,意图,.)都是可选的浓缩.

## 目的

CLI 帮助文本为人类编写,完成脚本由每个外壳手写,AI 特工猜测旗子。 CLI Schema 通过定义一个描述一个的 JSON 文档格式来修正它 程序的命令、参数、意图、认证要求、环境依赖和输出 因此,代理、IDE、 shell 补全生成器和文件工具都能够读取 同一文件,而不是重新编号.

`@cli-schema/spec` 是该格式的编译时间和运行时间合同:您构建的类型 与文档相对的文档,以及您在信任它之前查看的验证符.

## 特征

-   **全面 v1 类型覆盖** ——光谱中的每个对象都有相应的TypeScript接口: `CliSchema` (基层), `Command`, (中文(简体) ), `Namespace`, (中文(简体) ), `Parameter`, (中文(简体) ), `Constraint`, (中文(简体) ), `Intent`, (中文(简体) ), `Output`, (中文(简体) ), `Environment`, (中文(简体) ), `EnvVar`, (中文(简体) ), `ConfigFile`, (中文(简体) ), `DefaultHandler`, (中文(简体) ), `Shortcut`, (中文(简体) ), `Deprecation`。 。 。 .
-   **规范元模型,销售商** —— 说 `schema/cli-schema.meta-schema.json` 从光谱 repo, 于 `@cli-schema/spec/meta-schema.json` 用于想要原始 JSON 的工具 直接的Schema(例如在非JS管道中验证,或向编码工具提供).
-   **即用验证器** —— 说 `validate()` 编号 : `assertValid()`,由 [页:1](https://ajv.js.org/)'"2020-12方言支持. 没必要自找麻烦.
-   **`inferIntentFromHttp`** 用于 CLI 的小型纯辅助工具, 将 HTTP API 包起来: group a 合理 QQlink intent} 从一个 HTTP 动词(`GET`编号 :`HEAD` · 安全并具有能力, `PUT` → 有本事的人, `DELETE` 具有破坏性和独能性, `POST`编号 :`PATCH` ——没有设定,因为他们的语义 )),为特定终点.
-   **供应商扩展键入** - 每一个允许的物体 `x-` 前缀字段( spec §14) 是 输入以接受它们(`[extension: \`x- ${ string} : 未知`), so` x-我的工具:{...}`type-checks without`和任何一个.

## 使用量

### 手写文件

作为格式文档的双倍类型——达到 [光谱 本身](https://github.com/cli-schema/cli-schema/blob/main/spec/v1/README.md) 用于完整字段 语义学,但一个人口众多的文档看起来像:

```ts
import type { CliSchema } from '@cli-schema/spec'

const doc: CliSchema = {
  schemaVersion: 1,
  name: 'gh',
  version: '2.45.0',
  description: 'GitHub CLI — bring GitHub to your terminal',
  requiresAuth: true,
  authCommands: ['auth login', 'auth logout'],
  reservedMetaCommands: ['__schema'],
  commands: [
    {
      name: 'status',
      summary: 'Print information about relevant issues, pull requests, and notifications',
      intent: { destructive: false, idempotent: true, requiresAuth: true },
    },
  ],
  namespaces: [
    {
      segment: 'repo',
      commands: [
        {
          name: 'delete',
          path: ['repo'],
          parameters: [
            { role: 'positional', name: 'repository', type: 'string', required: true },
            { role: 'confirmationSkip', name: 'yes', type: 'boolean', required: false },
          ],
          intent: { destructive: true, idempotent: true, scope: 'global', requiresConfirmation: true },
        },
      ],
    },
  ],
}
```

在实际操作中,你通常会从一个活的CLI产生这个,而不是用手写出来——看 [`@cli-schema/commander`](https://www.npmjs.com/package/@cli-schema/commander)。 。 。 .

### 验证未信任的文档

根据第15节,消费者应将计划文件视为不可信的输入:

```ts
import { validate, assertValid } from '@cli-schema/spec'

const { valid, errors } = validate(untrustedDoc)
// errors is an ajv ErrorObject[] — empty when valid

assertValid(untrustedDoc) // throws with a formatted message if invalid
```

### 读取原始元数据

```ts
import metaSchema from '@cli-schema/spec/meta-schema.json' with { type: 'json' }
```

如果您想要用自己的 ajv 实例验证文档, 则使用不同的验证符 完全,或非JS工具.

### HTTP 动词的衍生意图

```ts
import { inferIntentFromHttp } from '@cli-schema/spec'

inferIntentFromHttp('DELETE') // { destructive: true, idempotent: true, scope: 'global' }
inferIntentFromHttp('POST')   // undefined — annotate explicitly, semantics vary per endpoint
```

## 相关软件包

-   [`@cli-schema/zod`](https://www.npmjs.com/package/@cli-schema/zod) - 从 `Parameter`s来自Zod计划
-   [`@cli-schema/commander`](https://www.npmjs.com/package/@cli-schema/commander) - 产生一个完整的 `CliSchema` 从活生生的指挥树上

## 许可证

麻省理工学院

## 常见问题

### @cli-schema/spec 是什么？

TypeScript 类型, meta-schema, 和 CLI Schema 规格的验证符\( \)https://github\.com/cli-schema/cli-schema \(中文\(简体\) \)\(中文\(简体\) \)

### 如何安装 @cli-schema/spec？

在项目目录运行 npm install @cli-schema/spec，或使用 pnpm add / yarn add / bun add。

### @cli-schema/spec 支持 TypeScript 吗？

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

### @cli-schema/spec 支持 ESM 还是 CommonJS？

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

### @cli-schema/spec 可以商用吗？

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

### @cli-schema/spec 的下载量有多少？

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

### @cli-schema/spec 还在维护吗？

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