# @dbx-tools/cli-service 中文文档

规范地址：https://npmcn.com/package/%40dbx-tools/cli-service/

版本：0\.9\.206
npm 元数据更新时间：2026-11-10T19:18:20.076Z
中文译文更新时间：2026-11-11T17:35:00.869Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：415 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-10-05T22:24:12.933Z
- 最新版本发布：2026-11-10T19:18:19.762Z
- 近 30 天下载量：9089（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：99（近 12 个月 99 个）

## 中文简介

跨平台服务寿命周期、 uv Python 运行时间和用于 CLIs 的系统托盘菜单

## 安装

```sh
npm install @dbx-tools/cli-service
```

也可以使用：`pnpm add @dbx-tools/cli-service`、`yarn add @dbx-tools/cli-service`、`bun add @dbx-tools/cli-service`

## README

# @dbx-tools/cli-服务

添加当前用户服务安装、 生命周期命令、 可选的 UV 管理 Python 依赖性,以及一个指挥官CLI的托盘菜单. 管理命令 在它的终端关闭于macOS,Linux和Windows后继续.

## 添加服务命令

```ts
import { buildServiceCommand } from "@dbx-tools/cli-service/cli";
import { defineService } from "@dbx-tools/cli-service/definition";
import { Command } from "commander";

const program = new Command("example");
program.addCommand(
  buildServiceCommand(
    defineService(import.meta.url, {
      command: { arguments: ["serve"] },
      menu: [{ type: "url", label: "Open App", url: "http://127.0.0.1:4400" }],
    }),
  ),
);
await program.parseAsync(process.argv);
```

`defineService` 使用自有软件包的名称、版本和默认可执行文件. 使用 `command.binName` 当软件包有多个可执行条目时。 设定 `command.executable` 来运行一个已有的外部程序,而不是编译一个 软件包条目。 管理命令默认 `NODE_ENV` 改为 `production`。一个 明确 `command.environment.NODE_ENV` 超过它.

设定 `pythonPackage` 当编译的服务命令需要 Python 运行时间时 :

```ts
defineService(import.meta.url, {
  pythonPackage: { name: "example-runtime" },
  command: { arguments: ["serve"] },
});
```

在安装过程中,服务在其下方形成了一个孤立的uv环境 数据目录,在服务版本安装 Python 分布,以及 套装 `PYTHON` 到那个环境的翻译. `pythonPackage.python` 选择 python 版本 uv 管理和默认为 `3.11`.v必须可用于 `PATH` 安装期间。 卸载此服务会删除环境 与服务拥有的其他数据.

当地项目设施保存了套件的额外和配套依赖性. 离线装置只从 uv 的缓存中解析, 当 a 所需文物没有.

`command.options` 接受具体选项对象或 Zod 对象 计划 对象序列化其当前值 。 Schemas 剖析 `{}` 序列化 他们的默认。 布尔值变为正或否定的旗帜,数组变为 重复的旗帜,以及 `undefined` 数值省略 :

```ts
defineService(import.meta.url, {
  command: {
    arguments: ["serve"],
    options: {
      host: "127.0.0.1",
      port: 4400,
      telemetry: false,
    },
  },
});
```

## 安装和管理服务

例如,上述程序:

```sh
example service install
example service status
example service logs -- tail -f
example service uninstall
```

参数后 `--` 以附加的服务日志路径运行为命令, 所以 `logs -- cat` 打印日志和 `logs -- tail -f` 跟着它.

该服务属于当前用户. 登录启动使用启动代理 macOS,Linux上的一个XDG自动启动条目,而Windows上的一个启动命令. 软件包 输入点用 Bun 编译成版本,每代安装 `~/.dbx-tools/bin`; Python 环境使用相同的版本生成 服务数据目录,每个主机一代都携带匹配的托盘 可执行文件 。 在 macOS 上安装任何 stale 启动定义, 清除 并启动当前世代,通过 发射完毕 同时期服务安装了服务替换和序列 更新共享运行时间依赖目录.

服务可提供在管理前运行的认证前飞行 命令。 安装时间 `waitForAuth` 模式默认为 `auto`:拥有的CLI 决定是否存在适用的认证来源, `true` 需要飞行前, 财务报告和审定财务报表 `false` 跳过它。 主机保持对状态的响应并停止请求,同时 飞行前等待.

启动条目不监督主机, 因此主机重新启动飞行前 或管理指挥 当它独自离开,等待 1,2,5,10,30, 然后在连续失败的60分之间。 每次重启都记录在 `host.log`。 。 。 . 从托盘退出或运行 `stop` 不重启结束主机.

`restart` 停止并启动已安装的可执行文件。 它不会重建它. 重新运行 `install` 更新一个耗用软件包以替换已编译的软件包 可执行文件并更新已保存的配置 .

## 自定义托盘菜单

默认托盘菜单显示程序名称、版本和要约 `Quit`。 。 。 . 通过服务定义添加 URL,命令,或分隔项. 自定义 命令项可以在同一处选择软件包二进制或外部可执行文件 作为主要服务指挥.

在向另一个 CLI 添加服务支持时使用此软件包, 这样用户可以得到 同样的安装,生命周期命令,和托盘行为。 生成的 参考用途 `<cli>` 作为消费程序名称的占地符.

## 命令参考

### `<cli> service`

安装和管理桌面服务

```sh
<cli> service [command]
```

#### 图标

| 命令 | 说明 |
| --- | --- |
| `install [options]` | 为当前用户安装并启动服务 |
| `start` | 启动已安装的服务 |
| `stop` | 停止运行服务 |
| `restart` | 重新启动已安装的服务 |
| `status` | 打印服务安装和处理状态为 JSON |
| `logs [command...]` | 打印服务日志路径或将其附加到命令中 |
| `uninstall` | 停止并删除当前用户的服务 |

### `<cli> service install`

为当前用户安装并启动服务

```sh
<cli> service install [options]
```

#### 选项

| 选项 | 说明 |
| --- | --- |
| `--start` | 安装后启动服务 。 (默认:真实) |
| `--no-start` | 安装后禁用服务 . |
| `--python-project <value>` | 本地 Python 项目已安装, 而不是注册包 . |
| `--offline` | 从 uv 缓存中安装 Python 包而无需网络访问 。 (默认:虚假) |
| `--no-offline` | 禁用从 uv 缓存中安装 python 包而无需网络访问 . |
| `--wait-for-auth <value>` | 认证准备模式:当服务提供适用的认证前飞行时,自动等待,真实需要,而假跳过. (选择:"自发","真","假",默认:"自发") |

### `<cli> service start`

启动已安装的服务

```sh
<cli> service start
```

### `<cli> service stop`

停止运行服务

```sh
<cli> service stop
```

### `<cli> service restart`

重新启动已安装的服务

```sh
<cli> service restart
```

### `<cli> service status`

打印服务安装和处理状态为 JSON

```sh
<cli> service status
```

### `<cli> service logs`

打印服务日志路径或将其附加到命令中

```sh
<cli> service logs [command...]
```

#### 参数

| 参数 | 说明 |
| --- | --- |
| `command` | 在服务日志路径前运行的命令和参数 |

### `<cli> service uninstall`

停止并删除当前用户的服务

```sh
<cli> service uninstall
```

## 常见问题

### @dbx-tools/cli-service 是什么？

跨平台服务寿命周期、 uv Python 运行时间和用于 CLIs 的系统托盘菜单

### 如何安装 @dbx-tools/cli-service？

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

### @dbx-tools/cli-service 支持 TypeScript 吗？

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

### @dbx-tools/cli-service 支持 ESM 还是 CommonJS？

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

### @dbx-tools/cli-service 可以商用吗？

@dbx-tools/cli-service 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @dbx-tools/cli-service 的下载量有多少？

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

### @dbx-tools/cli-service 还在维护吗？

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