# @antasphere/cli-core 中文文档

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

版本：0\.6\.0
npm 元数据更新时间：2026-10-12T20:40:40.915Z
中文译文更新时间：2026-11-06T16:19:29.760Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：196 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-07-11T20:38:49.174Z
- 最新版本发布：2026-10-12T20:40:40.675Z
- 近 30 天下载量：2755（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Antasphere 工具 CLI 的共享 CLI 基础: ~/.config/antasphere config home, profile 是实例(带有隐含的云剖面),旗 env profile 云 URL 分辨率,每个命令组织覆盖,实例 电子邮件

## 安装

```sh
npm install @antasphere/cli-core
```

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

## README

# @antasphere/cli-core (英语)

每个Antasphere工具CLI都建立在共同的基础上。 一个配置的家 整个生态系统,每个工具配置的命名空间 例如:旗帜 / env / profile / 云 URL 解析顺序 每个命令组织覆盖,实例 电子邮件-OTP 认证客户端 中心 + 工具 与其连接-需求接合和 被困钥匙恢复,以及 `CliIo` 即时接合。 工具命令,电线类型, 而 API 表面活在工具中 —— 此软件包只包含配置/ login 管道,从不秘密.

型号:中枢的一个身份(`antasphere login`,用户范围 `ant_` 按键);每台工具的证书由交换机制作 (单位:千美元)`POST {hub}/api/v1/sso/tool-token`,则 `POST {tool}/api/v1/sso/cli-connect` 交换名称无组织,ADR 014中枢 每个请求参数(中心服务器侧默认组织,或 `--org <hub org id or name>` 一个命令,工具将它映射到自己的 工作空间通过 `central_account_id`) (中文(简体) ). 每个工具CLI都载着它的云URL和 最终解决,所以 `antasphere login` 接下来 `slideless list` 干干净净 机器。 机器。 .

今天的消费者: `antasphere` 账户 CLI(中心) `packages/cli`页:1 `slideless` CLI 和 英国 `hackathon` CLI(英语:CLI). 设计决定就住在中心 架构简介(`hub-architecture.md` §8, CLI 家族; §4c, CLI 符号 ) (中文(简体) ).

## 设计家

`$XDG_CONFIG_HOME/antasphere/` (默认) `~/.config/antasphere/`),目录 `0700`,文件 `0600`。每个工具命名空间有一个文件——工具永远不会碰撞,以及 新工具是一个新文件, 永远不会改变计划 :

```
antasphere/                     0700
├── config.json                 0600   the `hub` tool — the `antasphere`
│                                      account CLI (its pre-extraction
│                                      location, kept for compatibility)
└── tools/                      0700
    └── <tool>.json             0600   every other tool, e.g. tools/slideless.json
```

每个文件都持有一个工具的配置文件. 一个工具文件,例如:. `tools/slideless.json`数字 :

```json
{
  "activeProfile": "cloud",
  "profiles": {
    "cloud": {
      "baseUrl": "https://slideless.antasphere.com",
      "connectKeys": {
        "default": {
          "apiKey": "slk_…",
          "email": "you@example.com",
          "mintedAt": "2026-09-30T09:12:44.000Z"
        }
      }
    },
    "share.antasphere.com": {
      "baseUrl": "https://share.antasphere.com",
      "apiKey": "slk_…"
    },
    "localhost:3400": {
      "baseUrl": "http://localhost:3400",
      "apiKey": "slk_…"
    }
  }
}
```

`baseUrl` 是配置文件为实例; 配置文件为无 `baseUrl` 已经到了 工具的云URL. `apiKey` 工具本身的登录; `connectKeys` 拿着钥匙 中枢交换器被铸造,每个中枢配置文件一个(槽名,这里) `default`,为 (原始内容存档于2017-10-11). the culture profile's name.

这个中心 `config.json`数字 :

```json
{
  "activeProfile": "default",
  "profiles": {
    "default": {
      "apiKey": "ant_…",
      "baseUrl": "https://account.antasphere.com",
      "email": "you@example.com",
      "workspaceId": "…"
    }
  }
}
```

`workspaceId` 是登录时的默认组织——信息;中枢的 服务器侧默认是适用的。 所有配置 I/O 已嵌入( 无) `process.env` ——测试将整个配置世界指向一个临时目录通过 `XDG_CONFIG_HOME`。 。 。 .

## 简介

配置文件是一个实例, 默认以其主机命名( P)`cloud` 用于工具的 云层 URL, `share.antasphere.com`, (中文(简体) ), `localhost:3400`) (中文(简体) ). `selectProfile` 应用 一条规则,按此顺序:

1.  `--profile <name>` 胜出, 配置文件必须存在 .
2.  `--api-url`,否则该工具的 URL env var 将选择此选项的配置 实例; 当数个名称时, 活动者先命名, 然后 `cloud`,然后是 初宣说. 如果没有,则在记忆中制作一个描述文件,以 东道主 - `cloud` 当它是云 URL 时—— 名称为磁盘上无配置文件 有(取名归宿主,然后) `<host>-2`, (中文(简体) ), `<host>-3`) (中文(简体) ). 这个 底盘通行证 `apiUrl: firstSet(flags.apiUrl, env[URL_VAR])`,同样的 合并 `resolveBaseUrl` 所以一面空白的旗子 永远藏不起来.
3.  活性简介——个人选择 `<tool> use <profile>`。 。 。 .
4.  工具云URL的简介, `cloud` 默认: 磁盘上的 实例,无论名称(一个名为 `cloud` 住在这里的人 另一个例子不是它),其他是用自由的名字在记忆中制作的—— `cloud`,或主机(当时 `<host>-2`, ) 当 `cloud` 被带去别的地方.

`created: true` 表示所选配置文件尚未在磁盘上( 在内存中制作 ) 用于实例 URL,或隐含 `cloud` profile)及其名称为免费. A 类 没有配置文件 `baseUrl` 位于云端 URL,用于选择和 连接等同的接合(底盘手) `connectOnDemand` 同样的 `cloudUrl`) (中文(简体) ). 选择从不写; `storeConnectKey` 首先,这是唯一能写出这样的简介的东西 联系人,并只在工具完全没有配置时才使其生效。 从来没有 重命名或重指定一个已存在的配置文件, 绝不更改哪个配置文件 一旦工具有一个, 将激活.

以无法接触的实例为指针的动态剖面图仍然是选择 没有沉默的回落到 `cloud`。该工具的错误名称为配置文件和 表示中心登录存在;该措辞是工具的. `default` 是一个普通的 现在的档案名称,没有钉它.

说明一个工具可以为上述三个简介打印什么(a) `slideless profiles`\- 样式上市, 不是这个软件包提供的命令 :

```
  PROFILE               INSTANCE                          SIGNS IN WITH
* cloud                 https://slideless.antasphere.com  hub
  share.antasphere.com  https://share.antasphere.com      key
  localhost:3400        http://localhost:3400             key
```

最后一栏是 `profileCredential`数字 : `key` (简介本身) `apiKey`,则 工具的登录,否则 `hub` (交换铸造的钥匙),否则 `none`。 。 。 .

## 表面

-   `configPath / loadConfig / saveConfig / clearConfig (env, tool)` - 那个 工具名称空间商店. `HUB_TOOL` 命名中心命名空间. `redactKey` 为终端安全制作密钥. `parseConfig(raw)` 是宽容的剖析 (阴道或外形 − 空配置); `assertToolNamespace(tool)` 拒绝任何东西,但小写弹丸.
-   `resolveProfile(config, requested, { unknownHint })` ——被命名(或活动) profile; 明确名称的缺少 profile 抛出 `CliUsageError`。 。 。 .
-   `selectProfile({ config, requested, apiUrl, cloudUrl, unknownHint })` - 那个 筛选规则 [简介](https://npmcn.com/package/%40antasphere/cli-core/#readme-profiles); 返回 `{ name, profile, source, created }`, (中文(简体) ), `source` 状态 `flag`, (中文(简体) ), `url`, (中文(简体) ), `active` 或者说 `cloud`。没有文字,也没有重新指定配置.
-   `CLOUD_PROFILE` —— 说 `'cloud'`,工具云URL中的隐含描述.
-   `normalizeUrl(url) / sameInstance(a, b) / profileNameFor(url, cloudUrl)` —— 说 实例 URL 的可比较形式( 有端口的主机, 路径; 否) 后面有斜线、查询或片段),其上平等,名称为 实例的配置文件会获得( e)`cloud`,否则东道主的端口. `profileUrl(profile, cloudUrl)` 是一个配置文件所在的实例(其 `baseUrl`空白的,等于无,否则就是云URL); `firstSet(...values)` 第一种非空白值, 修饰—— 一条规则 每个解析器都适用于旗子,阴道和剖面场,中枢 简介 `apiKey` 财务报告和审定财务报表 `baseUrl` 包含.
-   `resolveBaseUrl({ flag, env, envVar, profile, cloudUrl, missingMessage })` —— 说 · 云URL,被剥去;a 空白值计为未设置( e)`SLIDELESS_URL=""` 永不隐藏云URL); 掷出 `missingMessage` 作为 `CliUsageError` 只有一无所有 该工具没有云URL.
-   `resolveApiKey({ flag, env, envVar, profile })` - 旗帜-掩体-简介,空白 数值跳过.
-   `resolveOrg({ flag, env, envVar })` ——组织推翻一个 命令 : `--org`,否则工具的 org env var, 否则 `undefined` (中枢的) 服务器侧默认适用;空值跳过。 无所存 从来没有达到交换.
-   `CliUsageError(message, { exitCode })` ——一个用法级错误;运行器打印 打开并退出 `exitCode` (默认一).
-   `CliAuthClient({ baseUrl, fetch? })` – 无浏览器的电子邮件- OTP 流出每个实例 说: `request({ email })`, (中文(简体) ), `complete({ email, otp, keyName?, expiresInDays?, workspaceId? })` (整个密钥出现一次), `revoke(apiKey)` (自退=停用). 错误是 `CliAuthError` 与 `status`编号 :`code`编号 :`message`。 。 。 .
-   `CliIo` + 键 `ask` + 键 `printJson` 注射式I/O接合器(env, 溪流,取取, 交互快取),所以工具CLI在测试中运行在进程中.
-   `CliConnectClient({ hubBaseUrl, toolBaseUrl, fetch? })` - 交叉工具连接 交换(绑定模式§7、gcloud模型——每个中心登录服务) 联合工具 : `toolToken(hubApiKey, { resource })` 问中枢 120 s USER 范围 JWT + 该工具的一次性离线赠款 (单位:千美元)`hubRefreshToken`; 交换名称 NO org — 中枢 AR 014 , `cliConnect(token, hubRefreshToken?)` 将工具中的对换成 用户范围的工具本地密钥( 无认证头 —— JWT 是证书 赠款被转发到新用户的连接 `hub_grant_missing`, (中文(简体) ), `exchange(hubApiKey, body)` 两者兼而有之; 中心键 永远不能到达工具, 赠款永远不能到达 除了工具 两者都从未在这里坚持过。 错误是 `CliConnectError` 联合国 `CliAuthError`标记为失败 `stage` 加四种补救办法: `needsHubLogin` (立方圆401或403) `insufficient_scope` 从a 预`sso:exchange` 键), `needsReExchange` (过期/重放的401工具) 页:1, `refusal` (a) 范围不在此列,来自任何一方—— 被拒绝的不是钥匙)和 `exitCode` (3个拒绝,另1个).
-   `lookupConnectKey / storeConnectKey / removeConnectKey / profileCredential` —— 说 切换的用户范围密钥缓存, 保存在配置文件上 他们曾被用它来铸造 `connectKeys` 映射( slot = 中枢) 配置文件名称; `selectHubProfile(env)` 解决它。 每个中心账户一键 服务于每个兽群——兽群从来不是证书或槽的一部分. `storeConnectKey(env, tool, profileName, hubProfileName, entry, { baseUrl })` 写入 `baseUrl` 仅存于一个没有的相册上,一个空白的相册计为 无( 配置文件从不重新定位) , 创建尚未在磁盘上配置文件, 并且仅在 该工具根本没有配置文件. `removeConnectKey` 永远不要碰工具的 拥有 `apiKey`。 。 。 . `profileCredential(profile, hubProfileName?)` 答题 `key` 编号 : `hub` 编号 : `none`。 。 。 . `cachedConnectKey(profile, hubProfileName, hubEmail)` 这是 插槽读取连接服务:只有在电子邮件和电子邮件都存在时才使用该密钥 相匹配的。 匹配的.
-   `connectOnDemand({ tool, toolBaseUrl, cloudUrl?, hubCloudUrl?, profileName, env, resource?, fetch?, notify?, messages?, cached? })` ——接上一个工具CLI运行于NO时 直接的证书解决. `profileName` 是必需的:配置文件 `selectProfile` 选择; `cloudUrl` 是一个没有 `baseUrl` 已经是, 与选择获得的数值相同。 缓存是先读的, 在那个配置文件上 只有在出现这种情况时(冲击成本为零网络); `cached: false` 跳过它。 错过了 匿名 `GET /api/v1/instance` 探测器将流量(自主机或 无法获取实例解答 `{ outcome: 'not_cloud' }` 和工具的生成 其经典的无键错误, 中心证书从 `HUB_TOOL` 简介, `exchange` 运行时在已死亡的 JWT 上重试一次( 缺失) 或拒绝的中枢登录 被引导的 `antasphere login` `CliUsageError`打开 任何企图;拒绝即为传播 `CliConnectError`)和键 保存在选中的配置文件上 举个例子 交换使用的中枢配置是其中之一 `ANTASPHERE_URL` 名称(该实例中的配置、 方式) `antasphere login` 选择它; `hubCloudUrl` 让 URL 命名为 `cloud` 插槽,设置一个没有的枢纽配置文件 `baseUrl` 在中枢,是中枢的 URL 它的交换去; 一个 profile 自己的 `baseUrl` 总是赢,否则是活的 当没有运行中枢配置文件时, 无( 账户 CLI 将用它的云) profile; 工具 CLI 请求 `antasphere login`A级 缓存工具密钥仅在中心配置文件的电子邮件和缓存时服务 密钥的电子邮件匹配, 永远不要错过。 成功 : `{ outcome: 'connected', key, cached, result?, stored? }` —— 说 `cached: true` =: 从缓存服务. `notify` 收到"连接到..."通知 (c) 交换(缓存点击是沉默的); `messages` 覆盖副本. `probeToolInstance(toolBaseUrl, fetch?)` 发现探测器本身; `selectHubProfile(env, { cloudUrl? })` 中心简介, 他的名字是 缓存插槽( e)`HUB_URL_ENV` 实值 `ANTASPHERE_URL`· ; `activeHubProfile(env)` 实值 保存、折旧 `selectHubProfile(env)`) (中文(简体) ).
-   `refreshConnectKey(opts)` ——被搁浅的钥匙回收,与 `connectOnDemand`。当请求以密钥回答401时 `cached: true`,底盘称它一次:它驱逐了那个键(只从一个 在此实例中配置; 从未触碰过另一个实例的密钥)和 与缓存再次交换已跳过 。 底盘重复了一次请求 带有新密钥, 且第二个 401 失败 ; `not_cloud` 没有意义 与恢复.
-   `migrateLegacyConfig(env, { tool, legacyDir })` - 一发,无损 导入工具的 cli- 核心 `$XDG_CONFIG_HOME/<legacyDir>/config.json` 进入共享的家。 仅在工具中没有配置文件时导入 共享家园, 遗留文件至少持有一个; 遗留文件是 离开原地.

## 退出代码

-   `1` ——用法或电线出错.
-   `3` - 拒绝:非范围交易的403 信件是服务器自己的句子, 按原样打印 .

运行者已读取 `exitCode` 关 `CliUsageError` 财务报告和审定财务报表 `CliConnectError`。 。 。 .

## 说完了

```json
"dependencies": { "@antasphere/cli-core": "^0.6.0" }
```

登记册所装的柏油丸 `dist/`,没有构建脚本运行在安装上.

## 释放

释放通过 npm 无符号 **值得信赖的出版** (OIDC): (英语: `.github/workflows/publish.yml` 着火了 `vX.Y.Z` 标记, 验证标记 匹配 `package.json#version`,运行 lint/类型检查/测试/建设,并发布 没有npm令牌——npm直接认证工作流程的OIDC身份.

```bash
# bump package.json#version, commit, then:
git tag v0.6.0 && git push origin v0.6.0
```

第一次出版是手工完成的,信任的出版商被配置在 npmjs.com;每个发行都是标记.

| 外地 | 数值 |
| --- | --- |
| 组织或用户 | `antasphere` |
| 仓库 | `cli-core` |
| 工作流程文件名 | `publish.yml` |
| 环境 | _(离开空地)_ |

## 发展

```bash
pnpm install
pnpm lint && pnpm typecheck && pnpm test && pnpm build
```

工作空间规则中的分支 : `prod` (违约、释放/立方)+ `dev` (日常工作). 许可证:MIT(故意允许——这是管道) (b) 由公共中央供资机构消费).

## 常见问题

### @antasphere/cli-core 是什么？

Antasphere 工具 CLI 的共享 CLI 基础: ~/\.config/antasphere config home, profile 是实例\(带有隐含的云剖面\),旗 env profile 云 URL 分辨率,每个命令组织覆盖,实例 电子邮件

### 如何安装 @antasphere/cli-core？

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

### @antasphere/cli-core 支持 TypeScript 吗？

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

### @antasphere/cli-core 支持 ESM 还是 CommonJS？

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

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

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

### @antasphere/cli-core 可以商用吗？

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

### @antasphere/cli-core 的下载量有多少？

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

### @antasphere/cli-core 还在维护吗？

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