# @centient/cli-utils 中文文档

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

版本：0\.2\.0
npm 元数据更新时间：2026-09-13T13:35:38.809Z
中文译文更新时间：2026-11-09T09:07:25.083Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：30 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- 首次发布：2026-06-16T15:30:08.719Z
- 最新版本发布：2026-09-13T13:35:38.618Z
- 近 30 天下载量：3143（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

无依赖的 CLI 原始:终端能力检测,ANSI 色彩辅助器,和 semver-lite (parse/compare/satisfies)

## 安装

```sh
npm install @centient/cli-utils
```

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

## README

# @ entient/ cli- utils

由百度命令行工具共享的无依赖性CLI原始:

-   **终端能力检测** —— 说 `NO_COLOR` 编号 : `FORCE_COLOR` 编号 : `TERM` 优先使用可注射嵌入记录,因此检测为单位可测试.
-   **ANSI 颜色助手** ——色后降解为身份(空字符串)代码 不支持.
-   **闪光灯** —— 说 `parse` 编号 : `compare` 编号 : `satisfies` 页:1 `major.minor.patch[-prerelease]`无外部 `semver` 依赖性.

零运行时间依赖关系. 仅限无害环境管理.

## 安装

```bash
npm install @centient/cli-utils
```

或作为单体中的工作空间依赖:

```bash
pnpm add @centient/cli-utils --workspace
```

## 终端能力与颜色

检测被拆分为 a **纯核** (注射器) `env` 记录和a 流描述符 — read no globals)和薄 **活程序包装器** 页:1 人类基因组CLI呼叫网站.

### 颜色优先排序

`resolveColorSupport(env, isTTY)` 按此精确度确定颜色支持 优先( 最高胜 ) :

1.  **`FORCE_COLOR` 当前** (任何价值,包括 `""`) 颜色 **打开**
2.  **`NO_COLOR` 当前** (任何价值,包括 `""`) 颜色 **关闭**
3.  **`TERM === "dumb"`** • 颜色 **关闭**, (中文(简体) ), `isDumb = true`
4.  **流为 TTY** • 颜色 **打开**
5.  **否则** • 颜色 **关闭**

存在通过关键存在测试 [NO COLOR 公约](https://no-color.org/): 变量的单纯存在是信号,无论价值如何. 一个钥匙 值为 `undefined` 计数为 **缺席**。 。 。 .

```typescript
import {
  detectCapabilities,
  makeAnsiColors,
  colorize,
} from "@centient/cli-utils";

// Pure / testable: pass an env record and a stream descriptor.
const caps = detectCapabilities(process.env, process.stdout);
// caps -> { isTTY, hasColor, isDumb, width }

const colors = makeAnsiColors(caps.hasColor);
console.log(colorize(colors, "green", "ok"));
// "ok" is wrapped in ANSI green when color is enabled, returned unchanged when not.
```

### 现场处理便利包装器

```typescript
import { detectTerminalCapabilities, createAnsiColors } from "@centient/cli-utils";

const caps = detectTerminalCapabilities("stdout"); // reads process.env + process.stdout
const colors = createAnsiColors();                 // colors for the live stdout
```

### 结构错误

```typescript
import { writeError } from "@centient/cli-utils";

writeError("config not found", "a path to engram.json", "pass --config <path>");
// [ERROR] config not found
//   Expected: a path to engram.json
//   Recovery: pass --config <path>
```

水槽可以注射(`writeError(what, expected, recovery, write?)`, (中文(简体) ), 默认为 `process.stderr`返回无效;退出代码处理是 电话员的责任.

## 闪光灯

参数 `major.minor.patch` 带有可选预释标识符并构建 元数据。 构建元数据解析并忽略命令( SemVer 2. 0) §10. 按SemVer 2.0 §11订出预放行——一种预放行种类 _下级_ 它的释放.

```typescript
import {
  parseSemver,
  tryParseSemver,
  formatSemver,
  compareSemver,
  compareVersions,
  satisfies,
} from "@centient/cli-utils";

parseSemver("1.2.3-rc.1");
// { major: 1, minor: 2, patch: 3, prerelease: ["rc", 1] }

tryParseSemver("v1.2.3"); // parsed tuple
tryParseSemver("not-a-version"); // null (diagnostic/fail-open paths)

const actual = tryParseSemver("v1.5.0");
const minimum = tryParseSemver("1.2.0");
const meetsMinimum =
  actual === null || minimum === null
    ? null // caller chooses whether to warn, skip, or fail open
    : compareSemver(actual, minimum) >= 0;

formatSemver(parseSemver("1.2.3-rc.1")); // "1.2.3-rc.1" (round-trips)

compareVersions("1.0.0-rc.1", "1.0.0"); // -1 (pre-release < release)

satisfies("1.5.3", "^1.2.0"); // true
```

### 支持范围表单

没有复合范围,没有 `||`,没有连字符范围.

| 范围 | 含义 |
| --- | --- |
| `1.2.3` | 准确匹配 |
| `>=1.2.3` | 包含下限 |
| `>1.2.3` | 唯一下限 |
| `<=1.2.3` | 包含上限 |
| `<1.2.3` | 绝对上限 |
| `^1.2.3` | 护理:相同大、高或高(`>=1.2.3 <2.0.0`(中文(简体) ) |
| `~1.2.3` | 平面: 同一主要. minor, 水平或以上 (`>=1.2.3 <1.3.0`(中文(简体) ) |
| `*` 编号 : `""` | 任何版本 |

`parseSemver`, (中文(简体) ), `compareVersions`,以及 `satisfies` 保持严格:缺陷 版本或区域抛出 `SemverError` (载运) `expected` 财务报告和审定财务报表 `input` 字段) 而不是无声地羞辱. `tryParseSemver` 是明显的非抛掷 外部报告版本的边界; 它返回 `null` 无效输入 并接受一个常规小写 `v` 就在数字核心之前.

## API 密码

| 导出 | 说明 |
| --- | --- |
| `resolveColorSupport(env, isTTY)` | 纯色支持解析器(优先核心). |
| `detectCapabilities(env, stream)` | 纯能检测从一个嵌入记录 + 流描述符. |
| `detectTerminalCapabilities(stream?)` | 直播进程包装器结束 `detectCapabilities`。 。 。 . |
| `makeAnsiColors(enabled)` | 纯 ANSI 颜色设置; 禁用时为空字符串 . |
| `createAnsiColors()` | 活程序包装; stdout 的颜色 . |
| `colorize(colors, code, text)` | 在代码 + 重置中环绕文字,或禁用时的身份. |
| `writeError(what, expected, recovery, write?)` | 三段结构错误到可注射槽. |
| `parseSemver(input)` | 解析到 `SemverTuple`; 抛出 `SemverError`。 。 。 . |
| `tryParseSemver(input)` | 解析外部版本而不丢出; 接受领导 `v` 返回时 `null` 输入无效. |
| `formatSemver(v)` | 格式回到字符串( 回合) `parseSemver`) (中文(简体) ). |
| `compareSemver(a, b)` 编号 : `compareVersions(a, b)` | 总订单比较`-1` 编号 : `0` 编号 : `1`) (中文(简体) ). |
| `satisfies(version, range)` | 对一个范围进行测试. |

## 许可证

麻省理工学院

## 常见问题

### @centient/cli-utils 是什么？

无依赖的 CLI 原始:终端能力检测,ANSI 色彩辅助器,和 semver-lite \(parse/compare/satisfies\)

### 如何安装 @centient/cli-utils？

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

### @centient/cli-utils 支持 TypeScript 吗？

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

### @centient/cli-utils 支持 ESM 还是 CommonJS？

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

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

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

### @centient/cli-utils 可以商用吗？

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

### @centient/cli-utils 的下载量有多少？

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

### @centient/cli-utils 还在维护吗？

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