# @clidoc/yargs 中文文档

规范地址：https://npmcn.com/package/%40clidoc/yargs/

版本：1\.1\.3
npm 元数据更新时间：2026-11-06T18:50:42.952Z
中文译文更新时间：2026-11-10T01:47:43.123Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40clidoc/yargs
原文对照：https://npmcn.com/package/%40clidoc/yargs/?lang=original
项目主页：https://clidoc.ben3d.ca/docs/frameworks
源码仓库：https://github.com/bhouston/clidoc

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

- 包体积（解压后）：63.5 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-09-22T14:19:44.818Z
- 最新版本发布：2026-11-06T18:50:42.522Z
- 近 30 天下载量：2548（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

通过 OpenCLI 从 Yargs 命令定义生成 CLI 参考文件

## 安装

```sh
npm install @clidoc/yargs
```

也可以使用：`pnpm add @clidoc/yargs`、`yarn add @clidoc/yargs`、`bun add @clidoc/yargs`

## README

[![clidoc logo](https://raw.githubusercontent.com/bhouston/clidoc/main/packages/docs/static/img/icon-512.png)](https://clidoc.ben3d.ca/)

  

[![npm package](https://img.shields.io/npm/v/@clidoc/yargs.svg)](https://npmjs.com/package/@clidoc/yargs) [![npm downloads](https://img.shields.io/npm/dw/@clidoc/yargs.svg)](https://www.npmtrends.com/@clidoc/yargs) [![coverage](https://codecov.io/gh/bhouston/clidoc/branch/main/graph/badge.svg)](https://codecov.io/gh/bhouston/clidoc) [![discord chat](https://img.shields.io/badge/chat-discord-blue?style=flat&logo=discord)](https://discord.gg/vSYc5CfRWH) [![documentation](https://img.shields.io/badge/docs-read-blue?style=flat)](https://clidoc.ben3d.ca/)

  

# @clidoc/亚尔格

> 从 Yargs 命令定义中生成 CLI 参考文件 .

-   来自您的命令的文档
-   \*
-   QQ 构建器支持
-   只有元数据, 没有处理器运行
-   通过 opencli 发现机器

停止手写 CLI 参考文件 。 从你那里产生 [驴子](https://yargs.js.org/) 命令定义,所以它们不会从 `--help`。 。 。 .

`@clidoc/yargs` 将命令转换为 [打开CLI](https://github.com/bcdxn/opencli) 文档,您可以验证、渲染给Markdown,并发布到 Docusaurus 或 VitePress.

[读取 Docs 以学习更多](https://clidoc.ben3d.ca/)。 。 。 .

## 开始

```sh
npm install @clidoc/yargs @clidoc/core yargs
```

## 为什么/与替代品相比

-   **手写参考页** 随着旗帜的改变而漂移; 这里读取您已运行的 CLI 定义 .
-   **`--help` 仅限** 是每次一个命令的终端文本。 OpenCLI 文档结构化并经过验证,并可以使 Markdown 完全引用, shell 完成和 MCP 工具定义.
-   它只读取元数据:没有处理器运行,所以生成docs没有副作用. 并非元数据(海关验证,强制,中间软件)的鼠标行为没有记录;参见"限制".

## 相关软件包

-   [`@clidoc/core`](https://www.npmjs.com/package/@clidoc/core): 验证、解析和渲染文档,加 `mergeDocument`。 。 。 .
-   [`@clidoc/cli`](https://www.npmjs.com/package/@clidoc/cli)数字 : `clidoc validate`, (中文(简体) ), `markdown`, (中文(简体) ), `completion` 财务报告和审定财务报表 `mcp` 命令.
-   以 [`@clidoc/docusaurus`](https://www.npmjs.com/package/@clidoc/docusaurus) 或者说 [`@clidoc/vitepress`](https://www.npmjs.com/package/@clidoc/vitepress)。 。 。 .
-   其他国家行动倡议框架: [`@clidoc/commander`](https://www.npmjs.com/package/@clidoc/commander), (中文(简体) ), [`@clidoc/oclif`](https://www.npmjs.com/package/@clidoc/oclif)。 。 。 .
-   [文档](https://clidoc.ben3d.ca/docs/frameworks) 财务报告和审定财务报表 [演示](https://github.com/bhouston/clidoc/tree/main/demos)。 。 。 .

## 添加 `docgen` 给您的 CLI

`createDocgenCommand` 建立一个随时可以注册的 `docgen` 命令模块 : `-o`编号 :`--output <file>` (默认退出)和 `--format <json|yaml|markdown>` (默认) `json`) (中文(简体) ). `infoFromPackageJson` 文档的标题、 二进制名称和版本来源于您的 `package.json`。 。 。 .

```ts
import { readFileSync } from 'node:fs';
import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';
import { createDocgenCommand, fromYargs } from '@clidoc/yargs';
import { infoFromPackageJson } from '@clidoc/core';

const greet = {
  command: 'greet <name>',
  describe: 'Print a greeting',
  builder: (y) =>
    y
      .positional('name', { type: 'string', describe: 'Who to greet' })
      .option('loud', { type: 'boolean', describe: 'Shout the greeting' }),
  handler: (argv) => console.log(argv.loud ? `HELLO, ${argv.name}!` : `Hello, ${argv.name}.`),
};

const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
const info = infoFromPackageJson(pkg);

const parser = yargs(hideBin(process.argv)).command(greet);

let document;
parser.command(createDocgenCommand(() => document)).demandCommand();
// generate the document once every command, including docgen, is registered
document = fromYargs(parser, info);

parser.parse();
```

运行 `mycli docgen --output cli.json` jSON(默认),或 `mycli docgen --format markdown --output reference.md` 直接使 Markdown 化; 省略 `--output` 打印到 stdout。 安装验证器 `npm install -g @clidoc/cli` 运行 `clidoc validate cli.json`见 [Yargs 演示](https://github.com/bhouston/clidoc/tree/main/demos/yargs) 对于一个可运行的例子.

## 可选 : `__opencli` 用于机器发现

对于机器的发现, 匹配 [上游 OpenCLI 的 Go 库](https://github.com/bcdxn/opencli)中,检查隐藏的参数 `__opencli` yargs 前面的子命令解析参数而不是调用 `.parse()` 直接 : `handleOpenCliRequest` 打印一个 JSON 文档到 stdout( 或将其写入上游文件) `-o`编号 :`--out <file>` 命令处理器从不运行.

```ts
import { handleOpenCliRequest } from '@clidoc/core';

if (!(await handleOpenCliRequest(hideBin(process.argv), () => document))) {
  parser.parse();
}
```

消费者可以跑步 `mycli __opencli > mycli.opencli.json` 或者说 `mycli __opencli --out mycli.opencli.json` 为发现.

## 限制

-   `.check()` 财务报告和审定财务报表 `.middleware()` 从未援引过召回.
-   构建器回调运行以收集元数据,因此使用可信赖的模块. `fromYargs` 拒绝同步构建器; 使用 [`fromYargsAsync`](https://github.com/bhouston/clidoc/tree/main/packages/yargs#asynchronous-builders) 这些.
-   自定义解析、强迫、验证和中间软件行为.
-   不支持的构建者方法报告其名称并给出建议 `.option()` 或扩展 `fromYargs`。 。 。 .
-   需要的数组选项( E)`demandOption: true`发射 `variadic: true, required: true`。 。 。 .
-   数组类型选项 `default` 既不能表示 —— OpenCLI 旗下默认是单个字符串,数字,也不能表示布尔——所以 `fromYargs` 扔出一个诊断性选项,而不是释放无效文档。 在您的处理器中应用默认值( 例如) . `argv.rules ?? ['basic']`) (中文(简体) ).

## 同步构建器

`fromYargs` 同步运行构建器 。 如果一个建筑师 `async`,例如,一个懒惰地导入其子命令作为 [雅格文件命令](https://github.com/bhouston/yargs-file-commands) 对,使用 `fromYargsAsync`。它需要相同的参数,等待每个构建者,并包括一个 `await`。 。 。 . `createDocgenCommand` 接受一个同步 `getDocument`,因此文档只有在 `docgen` 运行和正常启动保持懒惰 :

```ts
import { createDocgenCommand, fromYargsAsync } from '@clidoc/yargs';
import { fileCommands } from 'yargs-file-commands';

const commands = await fileCommands({ commandDirs });
const docgen = createDocgenCommand(() => fromYargsAsync([...commands, docgen], info));

await yargs(hideBin(process.argv)).command(commands).command(docgen).parseAsync();
```

在此传递命令模块而不是解析器: Yargs 在操作器运行时不会暴露其已注册的命令.

## 高级: 通过一个明确的命令模块阵列

`fromYargs` 接受代替活实例的一系列命令模块,供想要从从未在解析器上注册的模块构建文档的呼叫者使用,在不同的时间运行转换,或者跳过 `package.json` 完全为:

```ts
import { fromYargs } from '@clidoc/yargs';

const document = fromYargs([greet], { title: 'My CLI', binary: 'mycli', version: '1.0.0' });
```

`fromYargs` 将 Yargs 命令元数据转换为 OpenCLI `1.0.0-alpha.14` 文档中,从一个活实例中,或从同一模块的显式数组中,记录您的命令,加上CLI标题、可执行名称和版本. `fromYargs` 只读元数据;它不分析参数或运行处理器.

## 添加示例和退出代码

`fromYargs` 只知道Yargs指挥元数据暴露了什么 所以 `examples`, (中文(简体) ), `exitCodes`,以及 元数据类 `info.license` 从未出现在生成的文档中。 加入它们 `@clidoc/core`是因为 `mergeDocument`,替换平原 `fromYargs(parser, info)` 以上调用:

```ts
import { mergeDocument } from '@clidoc/core';

document = mergeDocument(fromYargs(parser, info), {
  info: { license: { name: 'MIT', spdxId: 'MIT' } },
  commands: {
    'mycli greet': {
      examples: [{ title: 'Basic', content: 'mycli greet Ada' }],
      exitCodes: [{ code: 1, status: 'BAD_USER_INPUT_ERROR', summary: 'Missing name' }],
    },
  },
});
```

使用全部生成的命令密钥( E)`mycli greet`)将元数据添加到现有的命令中.

见 [`@clidoc/core` 读取](https://github.com/bhouston/clidoc/tree/main/packages/core#adding-author-supplied-metadata) 为合并规则.

## 捐款

见 [贡献指南](https://github.com/bhouston/clidoc/blob/main/CONTRIBUTING.md)。 。 。 .

## 许可证

麻省理工学院

## 作者

[本·休斯顿](https://ben3d.ca/),赞助人 [资产土地](https://landofassets.com/)。 。 。 .

## 常见问题

### @clidoc/yargs 是什么？

通过 OpenCLI 从 Yargs 命令定义生成 CLI 参考文件

### 如何安装 @clidoc/yargs？

在项目目录运行 npm install @clidoc/yargs，或使用 pnpm add / yarn add / bun add。

### @clidoc/yargs 支持 TypeScript 吗？

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

### @clidoc/yargs 支持 ESM 还是 CommonJS？

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

### @clidoc/yargs 需要什么版本的 Node\.js？

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

### @clidoc/yargs 可以商用吗？

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

### @clidoc/yargs 的下载量有多少？

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

### @clidoc/yargs 还在维护吗？

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