# @jakobm/cmdabra 中文文档

规范地址：https://npmcn.com/package/%40jakobm/cmdabra/

版本：0\.8\.0
npm 元数据更新时间：2026-11-01T11:46:32.089Z
中文译文更新时间：2026-11-01T12:57:30.418Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：69.4 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-10-23T06:35:01.625Z
- 最新版本发布：2026-11-01T11:46:31.931Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

cmdabra TypeScript库

## 安装

```sh
npm install @jakobm/cmdabra
```

也可以使用：`pnpm add @jakobm/cmdabra`、`yarn add @jakobm/cmdabra`、`bun add @jakobm/cmdabra`

## README

# Cmdabra

从声明性YAML和实现处理程序或方法对象构建命令行接口。

```yaml
# cmdabra.yaml
name: project
description: Manage a project
commands:
  dependencies:
    description: Manage dependencies
    commands:
      update:
        description: Update one package
        aliases: [up]
        examples: [project dependencies update --package-name yaml]
        named-options:
          package-name:
            type: string
            required: true
            short: p
```

```js
import { runCli } from '@jakobm/cmdabra';

await runCli('./cmdabra.yaml', {
  dependencies: {
    async update(namedOptions) {
      // The application owns behavior and output.
    },
  },
});
```

平面命令和嵌套命令映射到实现对象中的相同形状。Kebab-case命令名变成camelCase方法名和命名空间名，而Kebab-case选项名变成camelCase属性。叶子方法按照声明顺序接收位置参数，当声明命名选项时，后跟一个命名选项对象。字符串、布尔值、枚举和文件选项支持必需值、默认值、重复值、短标志、别名、环境回退和示例。 枚举选项要求非空 `choices` 列表。

使用 `description` 对于命令清单中显示的短文本。根或命令也可以声明多行 `details`;Cmdabra仅在可执行文件的帮助中显示这些详细信息，在其描述之后，在其参数和选项之前：

```yaml
commands:
  report:
    description: Build a report
    details: |
      Reports include all matching records.

      Use filters to narrow the result.
```

没有子命令的CLI直接在根目录下声明其输入，并使用一个函数作为其实现：

```yaml
name: search
description: Search files
named-options:
  pattern: { type: string, required: true, short: p }
  ignore-case: { type: boolean, short: i }
```

```js
await runCli('./cmdabra.yaml', async (namedOptions) => {
  // namedOptions.pattern and namedOptions.ignoreCase
});
```

无命令配置可以声明 `positional-arguments`， `named-options`, `examples`;它的处理程序接收与其他叶子相同的位置参数优先、命名选项最后签名。具有子命令的配置或命令组可以声明 `named-options`，这是每一个后代叶子所继承的。位置参数仍然只有叶子，选择没有叶子的组仍然显示不完整组的帮助，而不是调用处理程序。

继承选项在完整的命令路径之后提供，与特定于叶子的选项一起：

```yaml
name: project
named-options:
  config: { type: string, env-var: PROJECT_CONFIG }
commands:
  dependencies:
    named-options:
      format: { type: enum, choices: [text, json], default: text }
    commands:
      audit: {}
```

```sh
project dependencies audit --config project.yaml --format json
```

继承的选项名或短别名不得与同一命令路径上的另一个输入冲突。

每个选项名至少包含两个字符。任何选项类型都可以有一个可选的单字母 `short` 别名;别名在命令中是唯一的， `-h` 和 `--help` 为生成的帮助保留，以及 `--cmdabra-complete`， `--cmdabra-completion`, `--cmdabra-install-completion` 为shell完成保留。布尔短选项可以按任何顺序分组，因此 `-Nap` 等于 `-N -a -p`． 一个组只能包含布尔标志。字符串和枚举短选项使用单独的值，例如 `-N -f data.json`;附加的值，例如 `-fdata.json` 不支持。

命令声明有序输入 `positional-arguments` 和命名的输入 `named-options`． 位置参数总是必需的，并且必须声明 `type: string`， `type: enum`，或者 `type: file`． 枚举参数要求 `choices`.

所有位置参数必须位于所有选项之前。选项值是单独的令牌： `--file data.json` 支持，而 `--file=data.json` 不是。值可以以 `-`． 重复一个选项是错误的，除非它声明 `repeatable: true`。这个 `--` 不支持选项结束标记。

### 环境退

一个非布尔的、不可重复的命名选项可以声明一个环境变量fallback：

```yaml
named-options:
  file:
    type: file
    env-var: LEDLIGHT_FILE
```

显式命令行值优先，然后是非空的自动stdin `default-stdin` 文件选项，环境变量，最后 `default`． 环境值使用该选项的普通枚举验证和文件加载。声明的环境变量存在但为空是使用错误。不支持布尔和可重复选项 `env-var` 因为它们的字符串表示是不明确的。环境回退由shell工具组成，如direnv；Cmdabra本身不搜索或加载环境文件。

### 文件输入

一、 `file` 输入接受文件系统路径或 `-` stdin。Cmdabra在调用处理程序之前打开文件系统路径，因此丢失或不可读的文件是运行时错误。空文件和空显式stdin是有效的。 `read-as` 控制是否 `content` text（默认值）是 `Buffer`，或者 `Readable` 流:

```yaml
named-options:
  input:
    type: file
    read-as: text # text, buffer, or stream
    default-stdin: true
```

处理程序接收内容及其来源：

```ts
export type FileInput<T> =
  | { source: 'file'; path: string; content: T }
  | { source: 'stdin'; content: T };
```

`default-stdin: true` 当未显式提供该选项且没有其他文件输入使用时，分配非空重定向stdin `-`． 每个可执行文件最多只能启用一个文件选项。目前支持自动stdin `read-as: text` 和 `read-as: buffer`； `read-as: stream` 必须使用explicit `-` 因为 `stream` 与 `default-stdin: true` 暂不支持。显式的 `-` 总是选择stdin，包括空的stdin，并且一次调用只能将stdin分配给一个文件输入。文件支持的流归Cmdabra所有，并且在处理程序确定之前保持可用。

## 过程的行为

`runCli` 从 `process.argv`． 对于带有命令的配置，空命令行显示root帮助；选择不带子命令的命令组将显示该命令组的帮助。当声明的输入允许时，无命令配置将一个空命令行传递给它的根处理程序。使用错误和生成的帮助被写入stderr并设置 `process.exitCode` 2。其他错误是与它们的堆栈和集合一起写入的 `process.exitCode` 为1。关闭的标准输出管道成功退出，而不是报告 `EPIPE`.

对于受控的进程内执行，传递 `CliProcess` 的第三个可选参数 `runCli`． 这个狭窄的、进程形的契约只涵盖命令参数、环境、标准流、退出代码和Cmdabra使用的立即退出行为；在node . js `process` 对象直接满足它。省略参数使用的是实际过程。

## 壳完成

每个Cmdabra CLI都提供全局 `--cmdabra-complete` 选择。Shell适配器传递一个以零为基础的当前单词索引，后面跟着所有标记的命令行单词，包括作为单词零的可执行文件。Cmdabra读取当前的YAML配置，并将匹配的候选者写入标准输出，每行一个。它完成嵌套命令和别名、位置和选项枚举选择、文件输入的文件系统路径以及继承和本地选项；不可重复的选项在使用后被省略。

每个Cmdabra CLI还提供了两个独立的选项，不需要额外的YAML或应用程序处理程序：

```sh
project --cmdabra-completion bash          # Print a Bash completion script.
project --cmdabra-install-completion bash  # Install it for the current user.
project --cmdabra-completion zsh           # Print a Zsh autoload completion file.
project --cmdabra-install-completion zsh   # Install it for the current user.
project --cmdabra-completion fish          # Print a Fish completion script.
project --cmdabra-install-completion fish  # Install it for the current user.
```

取代 `project` 配置了可执行文件 `name`，必须在 `PATH`． 在命令行开头使用一个shell参数传递任一管理选项(`bash`， `zsh`，或者 `fish`）. 这些框架选项适用于有或没有子命令的cli；否 `completion` 命令是保留的。

默认情况下，三个完成选项显示在生成的帮助中。要隐藏它们，设置 `show-completion-options-in-help: false` 在YAML配置的根目录下：

```yaml
name: project
show-completion-options-in-help: false
commands:
  status:
    description: Show project status
```

这个布尔设置适用于根、命令组和叶子帮助，包括为使用错误打印的帮助。它只控制帮助可见性：所有三个选项都保留并可用，shell完成仍然建议使用它们。省略该设置或将其设置为 `true` 来展示它们。这个设置只允许在根目录下进行。

安装将创建父目录，并报告安装路径和shell设置说明。重新安装一个未修改的脚本不会改变它；标记为Cmdabra为该可执行文件和shell生成的脚本可以更新。现有的外部文件、目录和符号链接将被拒绝。安装过程不会编辑shell启动文件，也不会在安装npm包时自动运行。

### Bash

Bash脚本安装为 `<directory>/<name>`，其中目录为：

-   `$BASH_COMPLETION_USER_DIR/completions` 当 `BASH_COMPLETION_USER_DIR` 非空。
-   `$XDG_DATA_HOME/bash-completion/completions` 当 `XDG_DATA_HOME` 非空。
-   `$HOME/.local/share/bash-completion/completions` 否则。

与现代 `bash-completion` 在交互式shell中安装并启用，它的加载器根据需要发现这个文件。安装程序没有安装或激活 `bash-completion`，并且无法验证父shell的状态。打开一个新shell来获取集成。另外, `source` 安装的文件立即注册完成，包括在Bash设置中没有 `bash-completion`． 生成的适配器使用与Bash 3.2兼容的语法。

### Zsh

Zsh脚本安装为 `_<name>` 在 `$XDG_DATA_HOME/zsh/site-functions`，或者 `$HOME/.local/share/zsh/site-functions` 当 `XDG_DATA_HOME` 为空或未设置。Zsh默认不搜索此目录。添加到 `fpath` **之前** 现有的 `compinit` 把你的 `.zshrc` （使用安装程序打印的实际路径）：

```zsh
fpath=("${XDG_DATA_HOME:-$HOME/.local/share}/zsh/site-functions" $fpath)
autoload -Uz compinit
compinit
```

如果shell框架已经调用 `compinit`，把 `fpath` 初始化前的加法。然后打开一个新的shell。如果现有的完成缓存缺少新命令，则使用 `compinit -D`.

生成的Zsh脚本是一个自动加载的完成文件 `#compdef` 头;把它放在 `fpath` 目录 `_<name>` 手动安装时。它不是一个可以直接从中获取源代码的脚本 `.zshrc`.

### 鱼

Fish脚本安装为 `<name>.fish` 在 `$XDG_CONFIG_HOME/fish/completions`，或者 `$HOME/.config/fish/completions` 当 `XDG_CONFIG_HOME` 为空或未设置。Fish通过它的默认值自动发现这个目录 `fish_complete_path`;不需要更改启动文件或额外的完成包。如果你自定义 `fish_complete_path`请把这个目录保存在里面。

安装后打开一个新shell，或者 `source` 安装程序显示的已安装文件，以便立即注册。对于手动安装，将生成的脚本保存为 `<name>.fish` 在同一个目录下。适配器使用Fish的令牌化命令行，并将候选生成委托给可执行程序，包括文件系统候选。它禁用了Fish的备用文件名建议，因此不相关的文件不会出现在命令或枚举补全中。

### 完成协议

完成引擎仍然是独立于shell的。所有三个适配器都将其shell的单词和当前单词索引转换为 `--cmdabra-complete` 请求。Zsh的集中 `CURRENT` 转换为从零开始的索引；Bash使用 `COMP_CWORD`． 鱼用 `commandline` 对光标之前的单词进行标记，并从当前标记之前的单词计算索引。保留包含空格的参数和候选参数。包含换行符的候选文件系统不能用基于行的协议表示，因此将被省略。

可执行文件在每次请求时读取其当前的YAML配置，因此配置更改在下一次完成时生效，而无需重新安装shell脚本。没有命令树嵌入到适配器中。所有配置的安装目录必须是绝对路径；空的环境变量被视为未设置。

## 打印稿合同

从YAML的真实源生成实现接口：

```sh
cmdabra generate-types cmdabra.yaml --output src/cmdabra.generated.ts
```

使用上下文类型和实现它 `satisfies CmdabraImplementation`． 当配置包含文件输入时，生成的模块也会导出 `FileInput` 对于需要命名运行时值的帮助程序。CI可以在运行前检测漂移 `tsc`：

```sh
cmdabra generate-types cmdabra.yaml --output src/cmdabra.generated.ts --check
```

## 常见问题

### @jakobm/cmdabra 是什么？

cmdabra TypeScript库

### 如何安装 @jakobm/cmdabra？

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

### @jakobm/cmdabra 支持 TypeScript 吗？

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

### @jakobm/cmdabra 支持 ESM 还是 CommonJS？

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

### @jakobm/cmdabra 需要什么版本的 Node\.js？

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

### @jakobm/cmdabra 可以商用吗？

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

### @jakobm/cmdabra 还在维护吗？

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