# @dlazy/cli 中文文档

规范地址：https://npmcn.com/package/%40dlazy/cli/

版本：1\.2\.3
npm 元数据更新时间：2026-07-21T01:28:42.629Z
中文译文更新时间：2026-11-12T12:37:55.419Z
软件包许可：AGPL-3\.0-or-later

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

原始 npm 页面：https://www.npmjs.com/package/%40dlazy/cli
原文对照：https://npmcn.com/package/%40dlazy/cli/?lang=original

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

- 包体积（解压后）：180 kB，6 个文件
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2026-04-10T01:28:51.933Z
- 最新版本发布：2026-07-21T01:28:42.459Z
- 近 30 天下载量：5136（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

DLazy AI工作流程的命令行界面,允许直接引用终端中的各种大型模型

## 安装

```sh
npm install @dlazy/cli
```

也可以使用：`pnpm add @dlazy/cli`、`yarn add @dlazy/cli`、`bun add @dlazy/cli`

## README

# @dlazy/cli

[English](https://npmcn.com/package/%40dlazy/cli/README.md) · **中文**

`@dlazy/cli` 提供 **`dlazy`** 终端命令，方便在 Shell 管道中运行 dLazy 的 AI 工具。

每条命令输出统一的 **ToolResult** 信封，一个工具的输出可直接管道喂给下一个。

> 访问 **[https://dlazy.com/docs\*](https://dlazy.com/docs*)\* 获取更多信息。**

* * *

## 安装

```bash
# 全局安装（把 `dlazy` 加入 PATH）
npm install -g @dlazy/cli

# 项目内（通过 `npx dlazy ...` 调用）
npm install @dlazy/cli
# 或：pnpm add @dlazy/cli   |   yarn add @dlazy/cli
```

## 登录认证

```bash
dlazy login                 # 设备码流程，浏览器扫码授权后保存到 ~/.dlazy/config.json
dlazy login --local         # 使用 http://localhost:3000，便于本地服务端联调
dlazy auth set sk-xxxx      # 直接写入 Token
dlazy auth get              # 查看当前 Token（已脱敏）
dlazy auth get --show       # 显示完整 Token
dlazy logout                # 从配置中清除 Token
```

运行时的 API Key 解析顺序：`--api-key` 参数 → `DLAZY_API_KEY` 环境变量 → `~/.dlazy/config.json` → 交互式登录（仅在 TTY 下触发）。

* * *

## CLI 快速上手

```bash
# 单图生成
dlazy gpt-image-2 --prompt "雨夜赛博朋克猫"

# 两个工具串成管道（自动解析上游产物）
dlazy gpt-image-2 --prompt "侦探侧脸" \
  | dlazy veo-3.1 --image - --prompt "雨夜镜头推进"

# 列出 / 详查工具
dlazy tools list
dlazy tools describe gpt-image-2

# 异步任务：先提交，后查询
dlazy veo-3.1 --image hero.png --prompt "..." --no-wait
dlazy status gen_abc123 --wait
```

### 全局参数

| 参数 | 作用 |
| --- | --- |
| `--api-key <key>` | 覆盖本次运行的 API Key |
| `--base-url <url>` | 覆盖服务端地址（默认 `DLAZY_BASE_URL` 或 `https://dlazy.com`） |
| `--verbose` | 在 stderr 输出调试日志 |
| `--format <mode>` | 控制 stdout 形态：`json`（默认） / `url` / `text` |
| `-l, --lang <locale>` | 帮助 / 输出语言：`en-US` 或 `zh-CN` |

语言也会按 `DLAZY_LANG` → `LC_ALL` → `LANG` 顺序回退识别。

### 单次运行参数（每个工具命令通用）

| 参数 | 作用 |
| --- | --- |
| `--dry-run` | 解析所有引用并回显 payload，不做鉴权 / 上传 / 联网 |
| `--no-wait` | 异步工具：立刻返回 `{ generateId, status }` |
| `--timeout <seconds>` | 异步任务的轮询超时（默认 1800 秒） |
| `--input <jsonOrFile>` | 内联 JSON 对象，或 `@path/to/file.json`；与 flag 合并，flag 值优先 |
| `--save <path>` | 将结果素材下载到该本地路径（自动 mkdir + 重试） |
| `--batch <n>` | 同 input 并行执行 N 次，outputs 合并（仅对 image / video / audio / text / auto 类工具有效） |

### 输出模式 `--format`

stderr 始终是给人看的进度提示；stdout 由 `--format` 决定。

| 模式 | stdout 内容 |
| --- | --- |
| `json`（默认） | 完整信封 `{ ok, result }` 或 `{ ok: false, code, message }` |
| `url` | 每行一个 URL（仅媒体类 output） |
| `text` | 每行一段文本（仅 text 类 output） |

要保存生成的素材，用 `--save`（自动下载、建目录、重试）：

```bash
dlazy gpt-image-2 --prompt "logo" --save logo.png

# script 输出结构化分镜 JSON；用 jq 提取 markdown 渲染
dlazy script --prompt "6 个流浪猫的电影分镜" \
  | jq -r '.result.outputs[0].value.texts[0]' > script.md

# 默认 JSON 模式 + jq，直接取信封字段
dlazy gpt-image-2 --prompt "..." | jq -r '.result.outputs[0].url'
dlazy veo-3.1 --image hero.png --prompt "..." \
  | jq 'if .ok then .result else .message end'
```

### 管道引用语法

CLI flag 值可使用引用语法，从上游 stdin 信封里取数据。所有引用在网络请求前替换完成。

| 语法 | 含义 |
| --- | --- |
| `-` | 自动选取 —— 标量字段取首个 output 的 url/text/value，数组字段取全部 |
| `@<n>` | 第 n 个 output 的 primary value（`@0` 为第一个） |
| `@<n>.<path>` | 进入 output 内部字段（如 `@0.url`、`@1.meta.fps`、`@0.text`） |
| `@*` | 所有 outputs 的 primary value 数组 |
| `@stdin` | 整个 stdin 信封 |
| `@stdin:<path>` | 对整个信封做 jsonpath（如 `@stdin:result.usage.creditsCost`） |

示例：

```bash
# 1) 单图自动接到视频
dlazy gpt-image-2 --prompt "..." \
  | dlazy veo-3.1 --image - --prompt "雨夜推进"

# 2) 取 4 张图里第 2 张
dlazy gpt-image-2 --batch 4 --prompt "..." \
  | dlazy veo-3.1 --image @1.url --prompt "缓推"

# 3) 数组字段：上游全部 url 自动展开
dlazy gpt-image-2 --batch 4 --prompt "..." \
  | dlazy merge --videos -

# 4) script 输出的分镜文本驱动下一个 prompt
dlazy script --prompt "6 个流浪猫的电影分镜" \
  | dlazy gpt-image-2 --prompt @stdin:result.outputs[0].value.storyboards[0].firstFramePrompt
```

引用对所有 flag 都生效（prompt、url、id 都可以）。`--dry-run` 可以查看引用替换后的 input，不真正调用 API。

### 本地文件与 Data URL

媒体字段（`--image`、`--video`、`--audio` 等）支持三种值：

-   `https://...` —— 原样传入
-   `data:image/png;base64,...` —— 自动上传到对象存储后替换为公开 URL
-   `./path/to/file.png` —— 自动上传到对象存储后替换为公开 URL

```bash
dlazy gpt-image-2 --image ./hero.png --prompt "油画风格"
```

文件大于 100 MB 会有警告日志；大于 500 MB 会被直接拒绝。

### 批量生成

所有生成类工具（`image` / `video` / `audio` / `text` / `auto`）都支持 `--batch <n>`，CLI 会用同一份输入**并行执行 N 次**，并把每次的 outputs 合并到同一个信封：

```bash
# 一次出 4 张图（并行），合并到 outputs[0..3]
dlazy gpt-image-2 --prompt "雨夜赛博朋克猫" --batch 4

# 配合管道引用：4 张图直接喂给下一个工具
dlazy gpt-image-2 --prompt "..." --batch 4 \
  | dlazy veo-3.1 --image @0.url --prompt "镜头推进"
```

`usage.creditsCost` / `tokenIn` / `tokenOut` 会跨子任务求和；`durationMs` 取并行墙钟（最大值）。配合 `--no-wait` 时，每个子任务的 `task` 会以 json 类型 output 的形式落到 outputs 数组里，方便下游管道继续读取所有 `generateId`。

### 异步任务

视频类工具大多是异步任务，CLI 默认会轮询直到完成。手动控制：

```bash
dlazy veo-3.1 --image hero.png --no-wait                  # 立即返回 generateId
dlazy status gen_abc123 --wait --tool veo-3.1             # 阻塞直到完成（按工具的 outputSchema 解析）
dlazy status gen_abc123                                    # 单次查询
```

`--timeout <seconds>` 控制轮询超时（默认 30 分钟）。`status` 命令传 `--tool <cli_name>` 可按对应工具的 outputSchema 解析结果；不传则按原始 JSON 输出。

### 工具发现

```bash
dlazy <tool> --help            # 该工具所有参数 / 默认值 / 依赖关系
dlazy tools list               # 注册表概览
dlazy tools describe <tool>    # 完整 input / output JSON Schema
```

CLI 会把 manifest 缓存到 `~/.dlazy/manifest-<locale>.json`，TTL 24 小时，并在后台静默刷新。这样 `--help` 在弱网 / 离线下依然秒开。

* * *

## ToolResult —— 统一输出契约

CLI 在 stdout 把结果包成 `{ ok: true, result }`：

```ts
type ToolResult = {
  tool: string // cli_name，如 "seedream-4.5"
  modelId: string // 服务端模型 id
  outputs: Output[] // 始终是数组，永远不是标量
  usage?: {
    creditsCost?: number
    durationMs?: number
    tokenIn?: number
    tokenOut?: number
  }
  task?: {
    // wait=false 或异步任务时存在
    generateId: string
    status: 'pending' | 'running'
  }
}
```

CLI 默认 `--format json` 的成功信封：

```json
{
  "ok": true,
  "result": {
    "tool": "gpt-image-2",
    "modelId": "gpt-image-2",
    "outputs": [
      {
        "type": "image",
        "id": "o_8a1f3b7d",
        "url": "https://cdn.dlazy.com/...png",
        "mimeType": "image/png"
      }
    ]
  }
}
```

失败信封：

```json
{ "ok": false, "code": "insufficient_balance", "message": "...", "details": {} }
```

退出码：成功 `0`；运行时 / 网络错误 `1`；输入 / 配置错误 `2`（缺字段、JSON 解析失败、未知工具、引用错误等）。

* * *

## 支持的工具

下表为快照，请用 `dlazy tools list` 查看实时注册表，用 `dlazy tools describe <name>` 查看完整 schema。

| 命令 | 类型 | 说明 |
| --- | --- | --- |
| `seedream-4.5` | 图片 | 豆包 Seedream 4.5 高质量文生图 / 参考图生图 |
| `seedream-5.0-lite` | 图片 | 豆包 Seedream 5.0 轻量高速生成 |
| `banana2` / `banana-pro` | 图片 | Gemini Banana 通用 / Pro 文生图 |
| `gpt-image-2` | 图片 | GPT Image 2（文 + 参考图编辑） |
| `grok-4.2` | 图片 | 极简文生图 |
| `recraft-v3` / `recraft-v3-svg` / `recraft-v4*` | 图片 | 风格化 / 矢量 / Pro 系列 |
| `kling-image-o1` | 图片 | 可灵图像（多图占位约束） |
| `mj-imagine` | 图片 | Midjourney 风格 |
| `viduq2-t2i` / `jimeng-t2i` | 图片 | Vidu / 即梦文生图 |
| `imageseg` / `superres` | 工具 | 抠图 / 超分辨率 |
| `veo-3.1` / `veo-3.1-fast` | 视频 | Veo 高质量 / 极速版文生视频 |
| `seedance-2.0` / `seedance-2.0-fast` / `seedance-1.5-pro` | 视频 | 字节 Seedance 视频 |
| `kling-v3` / `kling-v3-omni` | 视频 | 可灵 V3 / 全控版 |
| `wan2.6-r2v` / `wan2.6-r2v-flash` / `wan2.7` | 视频 | 通义万相视频 |
| `pixverse-c1` | 视频 | PixVerse C1（动作 / 特效） |
| `viduq2-i2v` | 视频 | Vidu 图生视频 |
| `jimeng-i2v-first` / `jimeng-i2v-first-tail` / `jimeng-dream-actor` / `jimeng-omnihuman-1.5` | 视频 | 即梦视频系列 |
| `video-replicate` / `image-replicate` | 视频 / 图片 | Replicate 桥接模型 |
| `video-scenes` / `merge` | 视频 | 分镜切割 / 多片段合并 |
| `gemini-2.5-tts` | 音频 | Gemini 2.5 Pro TTS |
| `keling-tts` / `doubao-tts` | 音频 | 可灵 / 豆包语音合成 |
| `keling-sfx` | 音频 | 音效 / 拟音 |
| `suno-music` | 音频 | Suno 音乐生成 |
| `vidu-audio-clone` / `kling-audio-clone` | 音频 | 声音克隆 |
| `plan` / `execute` | 文本 | 工作流规划 / 执行 |
| `script` | 文本 | 分镜脚本生成：从自由文本简介（可选参考图）产出结构化的 subjects 主体 + storyboards 分镜 |

* * *

## 运行环境

-   Node.js ≥ 18（构建目标 `node18`，依赖 `fetch` 和异步迭代器）。
-   CLI 打包为单个 CJS bundle。

## 常见问题

### @dlazy/cli 是什么？

DLazy AI工作流程的命令行界面,允许直接引用终端中的各种大型模型

### 如何安装 @dlazy/cli？

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

### @dlazy/cli 支持 TypeScript 吗？

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

### @dlazy/cli 可以商用吗？

@dlazy/cli 使用 AGPL-3\.0-or-later 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @dlazy/cli 的下载量有多少？

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

### @dlazy/cli 还在维护吗？

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