# @adlc/preflight 中文文档

规范地址：https://npmcn.com/package/%40adlc/preflight/

版本：1\.12\.0
npm 元数据更新时间：2026-10-10T03:03:45.780Z
中文译文更新时间：2026-11-06T00:37:04.132Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：24 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-06-13T21:12:41.788Z
- 最新版本发布：2026-10-10T03:03:45.405Z
- 近 30 天下载量：8138（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

在扇出(D2相0)前进行许可和环境飞行前检查.

## 安装

```sh
npm install @adlc/preflight
```

也可以使用：`pnpm add @adlc/preflight`、`yarn add @adlc/preflight`、`bun add @adlc/preflight`

## README

# @adlc/ 飞行前

在扇出前进行权限和环境飞行前检查(ADLC D2相 0).

进行隔离检查,以验证代理机队需要的每个操作类别 实际上在目前的环境中工作——所以许可提示和 配置失败前装入一批,而不是延后中空.

从ADLC D2字段注释:

> 许可提示中途飞行是一个隐藏序列点: 一个被屏蔽 代理 × N 队友 = N 摊位,赛事兄弟姐妹,半起步状态. 环境决定论是平行的时钟数学的先决条件.

## 使用量

```
preflight [--dir <path>] [--test-cmd "..."] [--gh] [--llm] [--worktrees] [--json]
```

### 没有旗帜——只需检查

```
preflight
```

运行所需的4个检查( bash, git, write, 分支) 并打印表格加 一个判决线。 0号出口,如果全部通过;2号出口,如果有任何失败.

### 带有可选检查

```
preflight --dir .sdlc/.adlc --test-cmd "npm test" --gh --llm --worktrees
```

## 旗帜

| 旗帜 | 类型 | 说明 |
| --- | --- | --- |
| `--dir <path>` | 字符串 | 用于写入检查和临时文件的 ADLC 目录( 默认 ): `.adlc` 或者说 `$ADLC_DIR`) (中文(简体) ). |
| `--test-cmd "CMD"` | 字符串 | 通过 CMD 运行 `sh -c`,预计出口0。 失败时显示输出尾端 。 传入但空值( 如未设置) `$TEST_CMD`)以1号出口被拒绝 `--test-cmd requires a non-empty command` 从来没有默默地跳过. |
| `--gh` | 布尔 | 运行 `gh auth status`; 期望退出 0. |
| `--llm` | 布尔 | 打电话 `detectProvider()` 并说它是无核的。 没有API的电话。 找到了提供的报告. |
| `--worktrees` | 布尔 | `git worktree add --detach .worktrees/preflight-test HEAD` 然后删除. |
| `--json` | 布尔 | 机器可读输出 : `{ checks, verdict, failedNames }`。 。 。 . |

## 检查

### 需要( 总是运行)

| 名称 | 测试什么 |
| --- | --- |
| `bash` | `echo preflight-ok` 继承 |
| `git` | `git status` cwd 中成功( cwd 必须是 git repo) |
| `write` | 写入 + 删除 `.adlc/tmp/preflight-test` (按需要为mkdir-p) |
| `branch` | 创建和删除 `preflight-test-branch`总是在最后清理 |

### 可选( 仅在给定旗帜时运行)

| 名称 | 旗帜 | 测试什么 |
| --- | --- | --- |
| `worktrees` | `--worktrees` | `git worktree add/remove` 循环; 总是在最后清理 |
| `test-cmd` | `--test-cmd "CMD"` | 通过 sh 运行 CMD, 期望退出 0 |
| `gh` | `--gh` | `gh auth status` 出口 0 |
| `llm` | `--llm` | `detectProvider()` 返回非无效( 无 API 调用) |

## 退出代码

| 代码 | 含义 |
| --- | --- |
| 0 个 | 出入口——通过所有检查(需要+明确要求可选) |
| 1个 | 操作/内部出错 |
| 2个 | 门失败——一次或多次要求或明确要求的检查失败 |

注:不要求的可选检查不运行,不能失败. 当国旗像 `--gh` 通过, 需要检查 . A 类 `--test-cmd` 被通过但为空或仅为空白(什么 `preflight --test-cmd "$TEST_CMD"` 当变量未设置时, 生成 CI 既不跳过也不运行:这是一个操作错误——飞行前打印 `error: --test-cmd requires a non-empty command …` 到 stderr 时,没有打印 stdout(没有桌子,没有判决,没有) `--json` 1. 请求的A 检查不能运行时, 决不能看起来像通行证 .

## 产出

### 可读( 默认)

```
──────────────────────
check      status  detail
──────────────────────
bash       ✓ PASS    echo preflight-ok succeeded
git        ✓ PASS    git status succeeded
write      ✓ PASS    .adlc/tmp/preflight-test written and removed
branch     ✓ PASS    branch 'preflight-test-branch' created and removed
worktrees  ✓ PASS    worktree add/remove succeeded
test-cmd   ✓ PASS    exited 0
──────────────────────

verdict: ALL CHECKS PASSED — environment is ready.
```

### 贾森(JSON)`--json`(中文(简体) )

```json
{
  "checks": [
    { "name": "bash",   "status": "pass", "detail": "echo preflight-ok succeeded", "required": true },
    { "name": "git",    "status": "pass", "detail": "git status succeeded",          "required": true },
    { "name": "write",  "status": "pass", "detail": ".adlc/tmp/preflight-test written and removed", "required": true },
    { "name": "branch", "status": "pass", "detail": "branch 'preflight-test-branch' created and removed", "required": true }
  ],
  "verdict": "pass",
  "failedNames": []
}
```

## 已进入ADLC阶段

**D2阶段 0** (fan-out前环境门). 在产卵前跑一次 平行的代理舰队,以确保每个操作级都成功. 与 `team-develop` 作为平行建设管线的第0阶段.

## 清理保障

创建副作用( 分支、 工作树、 tmp 文件) 的检查 在a中进行清理 `finally` 区块 - 清除残余物,不论检查通过与否 失败.

## 与兄弟姐妹工具的关系

-   `merge-forecast` ——飞行前使用确认环境已就绪;验证出票DAG并预测出出票前相冲突概率.
-   `gate-manifest` ——将出入口通过事件记录入ADLC运单分类账;飞行前应以有条不紊的流程记录通过.

## 核心差距

无。 所有要求的核心API(`detectProvider`, (中文(简体) ), `git`, (中文(简体) ), `parseArgs`, (中文(简体) ), `printJson`(中文(简体) ) 可在 `@adlc/core`。 。 。 .

## 常见问题

### @adlc/preflight 是什么？

在扇出\(D2相0\)前进行许可和环境飞行前检查\.

### 如何安装 @adlc/preflight？

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

### @adlc/preflight 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/adlc\_\_preflight 是否存在。

### @adlc/preflight 支持 ESM 还是 CommonJS？

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

### @adlc/preflight 需要什么版本的 Node\.js？

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

### @adlc/preflight 可以商用吗？

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

### @adlc/preflight 的下载量有多少？

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

### @adlc/preflight 还在维护吗？

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