# @docspack/cmdspec 中文文档

规范地址：https://npmcn.com/package/%40docspack/cmdspec/

版本：0\.2\.0
npm 元数据更新时间：2026-10-03T08:54:47.009Z
中文译文更新时间：2026-11-12T14:05:03.754Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40docspack/cmdspec
原文对照：https://npmcn.com/package/%40docspack/cmdspec/?lang=original
项目主页：https://docspack.dev/cmdspec
源码仓库：https://github.com/docspack/docspack

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

- 包体积（解压后）：645 kB，89 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.5\.0
- 运行依赖：3 个
- 首次发布：2026-10-03T05:55:19.804Z
- 最新版本发布：2026-10-03T08:54:46.816Z
- 近 30 天下载量：24365（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

cmdspec:一个命令行接口的机器可读描述. 验证它, 转换它从使用和OpenCLI, 并为代理制作一个每个命令摘要 .

## 安装

```sh
npm install @docspack/cmdspec
```

也可以使用：`pnpm add @docspack/cmdspec`、`yarn add @docspack/cmdspec`、`bun add @docspack/cmdspec`

## README

# @ docspack/ cmdspec

**cmdspec:一个命令行接口的机器可读描述.**

OpenAPI说HTTP API取取回. 连CLI都没说过 状态 : [打开CLI](https://opencli.org/) 是一个没有值类型的0.1草案 [使用量](https://usage.jdx.dev/) 富贵但没有自己的文件计划。 cmdspec是一种格式 两者兼而有之,无论说什么,都不加损失地转换成它 说:命令是否安全运行,其退出状态意味着什么,它打印什么,以及哪些 选项适用于哪个操作.

-   **规格:** [`SPEC.md`](https://npmcn.com/package/%40docspack/cmdspec/SPEC.md) (CC BY 4. 0) (中文(简体) )
-   **计划:** [`schema/v0.1.json`](https://npmcn.com/package/%40docspack/cmdspec/schema/v0.1.json)JSON Schema 2020-12 (英语)
-   **实例:** 文档包装、 t、 ku和 ffmpeg [`examples/`](https://npmcn.com/package/%40docspack/cmdspec/examples)
-   **为什么它存在,是什么被测量:** [`docs/design/cmdspec.md`](https://npmcn.com/package/docs/design/cmdspec.md)

```yaml
cmdspec: "0.1"
info: { name: greet, version: 1.0.0 }
arguments:
  - { name: who, required: true }
options:
  - { name: --shout, aliases: [-s], summary: Print in capitals }
effects: []
examples:
  - run: greet world --shout
```

## 国家行动倡议

```bash
npx @docspack/cmdspec validate cmdspec.yaml
npx @docspack/cmdspec convert mise.usage.kdl --to cmdspec --program-version 2026.10.0
npx @docspack/cmdspec convert cmdspec.yaml --to opencli -o opencli.json
npx @docspack/cmdspec digest cmdspec.yaml remote add
npx @docspack/cmdspec map cmdspec.yaml
```

`validate` 报告每个问题,而不是第一个问题,并列出每个问题所在的命令和选项. CLI本身由CMdspec文档定义—— [`cmdspec.yaml`](https://npmcn.com/package/%40docspack/cmdspec/cmdspec.yaml):它的解析器,它的 `--help` 财务报告和审定财务报表 `cmdspec --cmdspec` 都来自那个档案.

## 文摘——代理人的读取

一个命令,一切需要运行它, 在帮助页面的形状:

```text
docspack ask <question>... [options]
  Answer from the local index — the command to give an agent
  <question>...  words are joined with spaces
  -p, --package <s>  only packages whose name contains this text
  --limit <n>  maximum chunks to return (integer; at least 1; default 3)
  --max-tokens <n>  token ceiling for the result set (integer; at least 1; default 3000)
  --all  search the whole store, not just this project
  also accepts: --store <path>, --cwd <dir>, --json, -q, --quiet, -h, --help
  effects: read; idempotent
  stdout: text/markdown, the answer; application/json, the chunks and their scores with --json
  exit: 0 success; 1 the command failed; 2 the command was used wrongly; 3 nothing matched, and a docs package is installed but not indexed; 4 nothing matched, and everything installed is already indexed
  $ docspack ask "how do I verify a webhook signature"
  $ docspack ask "webhook signature" --package stripe --limit 5  # Look in one package only, and return more
```

这不是一个注解:每个注解都是一个词,因为帮助页是模型的格式 并且设计文件测量到 字比标记要贵3.2% 老师 它在帮助页面中添加的是帮助页面所遗漏的内容——类型,默认,效果, 产出和退出状况。 四个例子中最大的文摘是544个符号.

## 转换

| 从...到.. | 损失 |
| --- | --- |
| 使用量 ~ cmdspec | 无: 未映射属性和节点被保存 `x-usage` 写回 |
| OpenCLI — cmdspec | 无:未映射的字段被保存为 `x-opencli-*` |
| cmdspec – OpenCLI 光谱 | 无: OpenCLI 无法在其中表达的 `metadata` |
| (cmdspec-使用量) | 用法不能说——列出,从不悄悄地下降 |

测试真实文件而不是承诺:Mise自己的使用规格(290个命令)存活下来 用法 – cmdspec – 用法 – cmdspec 不变并转换为有效文档,和 dotnet的 已发布 OpenCLI 文档 (813 KB) 来源于 OpenCLI → cmdspec → OpenCLI 作为同名 JSON .

## 作为图书馆

```ts
import {
  commandDigest,
  fromOpenCli,
  mergeOverlay,
  parseArgsConfig,
  resolveDocument,
  toOpenCli,
} from "@docspack/cmdspec";
import { validate, validateOverlay } from "@docspack/cmdspec/validate";
import { readFile } from "@docspack/cmdspec/read";
import { fromUsage, toUsage } from "@docspack/cmdspec/usage";
import { fromCitty, fromCommander, fromYargs } from "@docspack/cmdspec/emit";
```

| 条目 | 包含 | 依赖性 |
| --- | --- | --- |
| `@docspack/cmdspec` | 类型, `resolveDocument`,摘要和地图, OpenCLI 转换, `parseArgsConfig`规则, `mergeOverlay` | 无 |
| `@docspack/cmdspec/validate` | `validate` 计划,然后是规则; `validateOverlay` | `ajv` |
| `@docspack/cmdspec/read` | `readFile`, (中文(简体) ), `readText` - JSON或YAML,经验证 | `yaml` |
| `@docspack/cmdspec/usage` | `fromUsage`, (中文(简体) ), `toUsage` | `@bgotink/kdl` |
| `@docspack/cmdspec/emit` | `fromCommander`, (中文(简体) ), `fromCitty`, (中文(简体) ), `fromYargs` | 无 |
| `@docspack/cmdspec/builder` | `mountCommandBuilders` — 命令构建器, 在浏览器中 | 无 |

`parseArgsConfig(command)` 给 `node:util`是因为 `parseArgs` 命令文档中的选项, 因此一个节点CLI可以从它所记录的同一份文件中解析它的命令行.

## 读者选择的命令行

`commandLine(builderTarget(command), values)` 写入一组值生成的命令行.. 附加文档的值 `syntax` 说,引用 POSIX 外壳,放 `--` 并列出仍然缺少的必要投入. `@docspack/sheaf-react`是因为 `CliBuilder` 把它变成一种形式 `@docspack/cmdspec/builder` 运行在 浏览器作为读者类型 .

## 从指挥官,城堡或烤肉计划

一个已经用其中一个框架构建的程序有它的命令行在内存中. 发射者 阅读并写入文档,所以描述它从它实际描述的内容开始:

```ts
import { fromCommander } from "@docspack/cmdspec/emit";
import { program } from "./cli.js"; // the commander program, not yet parsed

const document = fromCommander(program);
```

`fromCitty(command)` 解决每一个懒惰的子命令,所以是aync. `fromYargs(build)` 拿着 函数用于构建程序,因为 yargs 只在运行时构建命令的选项, 在程序本身上;每个命令称为一次,版本来自 `fromYargs(build, { version })`。没有导入框架:每个排放方读取其少数字段 需要,条目没有依赖关系.

一个框架不知道的是,该文件没有说:效果、退出状况、产出和 实例。 故你们应当以他们为表率,以免后世失去他们; `docspack build` 警告每个仍然失踪的人.

## 保持一个框架所不能知道

重叠是程序旁边的文件—— [`schema/overlay-v0.1.json`](https://npmcn.com/package/%40docspack/cmdspec/schema/overlay-v0.1.json) 将它产生的每份文件合并:

```yaml
cmdspecOverlay: "0.1"
exits:
  "0": { meaning: success }
commands:
  serve:
    effects: [network]
    options:
      --port: { value: { minimum: 1024 } }
  db drop:
    effects: [destructive]
```

```ts
import { mergeOverlay } from "@docspack/cmdspec";

const result = mergeOverlay(fromCommander(program), overlay);
if (!result.merged) throw new Error(result.problems.map((p) => `${p.at}: ${p.message}`).join("\n"));
```

命令按其程序下方的路径键取,用拼写选项和用名参数键取. 每个条目必须给程序命名 所以重新命名 `db drop` 做一个覆盖 而不是一个静静地停止应用的补丁。 内容覆盖文档 退出; 如果程序表示一个值, 覆盖必须商定或列出 `override`。 。 。 . `validateOverlay` 对照其计划检查一个复数 `mergeOverlay` 报告 每一个问题,不是第一个。 为什么会这样 [`docs/design/cmdspec-adapters.md`](https://npmcn.com/package/docs/design/cmdspec-adapters.md)。 。 。 .

## 查找程序文档

一个软件包将其文档命名于 `package.json` —— 说 `"cmdspec": "./dist/cmdspec.json"`,作为这个 执行 —— 当运行时, 一个程序会打印它 `--cmdspec`两者都载于SPEC第13节.

## 许可证

代码,计划以及例子都是MIT. 规格文本, `SPEC.md`,为 [CC BY 4.0 (英语)](https://creativecommons.org/licenses/by/4.0/)固定装置由麻省理工学院颁发许可证 来自 mise 和 OpenCLI 的文档;见 [`tests/fixtures/README.md`](https://npmcn.com/package/%40docspack/cmdspec/tests/fixtures/README.md)。 。 。 .

## 常见问题

### @docspack/cmdspec 是什么？

cmdspec:一个命令行接口的机器可读描述\. 验证它, 转换它从使用和OpenCLI, 并为代理制作一个每个命令摘要 \.

### 如何安装 @docspack/cmdspec？

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

### @docspack/cmdspec 支持 TypeScript 吗？

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

### @docspack/cmdspec 支持 ESM 还是 CommonJS？

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

### @docspack/cmdspec 需要什么版本的 Node\.js？

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

### @docspack/cmdspec 可以商用吗？

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

### @docspack/cmdspec 的下载量有多少？

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

### @docspack/cmdspec 还在维护吗？

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