clack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clack CLI Skill

Clack CLI 开发指南

Use this skill to implement reliable interactive CLIs with

@clack/core

and

@clack/prompts

使用本指南，你可以基于

@clack/core

和

@clack/prompts

实现可靠的交互式CLI。

Workflow

工作流程

Decide whether to use
```
@clack/prompts
```
or
```
@clack/core
```
.
Read only the minimum reference files needed for the task.
Start from the closest example in
```
references/examples/
```
.
Implement cancellation handling after every prompt.

Add UX polish (

intro

outro

spinner

progress

tasks

log

taskLog

stream

) when useful.

Verify imports against export maps in

references/docs/prompts-exports.ts

and

references/docs/core-exports.ts

确定使用
```
@clack/prompts
```
还是
```
@clack/core
```
。
仅阅读完成任务所需的最少参考文件。
从
```
references/examples/
```
中最贴近需求的示例开始。
在每个提示后实现取消处理逻辑。
按需添加用户体验优化（
```
intro
```
、
```
outro
```
、
```
spinner
```
、
```
progress
```
、
```
tasks
```
、
```
log
```
、
```
taskLog
```
、
```
stream
```
）。

对照

references/docs/prompts-exports.ts

和

references/docs/core-exports.ts

中的导出映射验证导入语句。

Pick the Right Layer

选择合适的层级

Use

@clack/prompts

by default.

Choose it for production-ready styling and quick delivery.
Use it when the request maps to standard prompt types: text, confirm, select, multiselect, grouped prompts, logs, spinners, progress, tasks, or streaming logs.

Use

@clack/core

when lower-level control is required.

Choose it for custom rendering, custom prompt behavior, or unstyled primitives.
Use it when the request needs direct prompt classes (
```
TextPrompt
```
,
```
SelectPrompt
```
,
```
ConfirmPrompt
```
,
```
Prompt
```
) or deep customization.

默认使用

@clack/prompts

。

当你需要生产就绪的样式和快速交付时，选择它。
当需求对应标准提示类型时使用：文本输入、确认选择、单选、多选、分组提示、日志、加载动画、进度条、任务流或流式日志。

当需要底层控制时使用

@clack/core

。

适用于自定义渲染、自定义提示行为或无样式原语的场景。
当需求涉及直接使用提示类（
```
TextPrompt
```
、
```
SelectPrompt
```
、
```
ConfirmPrompt
```
、
```
Prompt
```
）或深度自定义时使用。

Mandatory Safety Patterns

强制安全模式

Handle cancellation on every prompt result.

import * as p from '@clack/prompts';

const value = await p.text({ message: 'Your name?' });
if (p.isCancel(value)) {
  p.cancel('Operation cancelled.');
  process.exit(0);
}

Start and close sessions cleanly for user-facing CLIs.

p.intro('create-app');
// prompts
p.outro('Done');

在每个提示结果中处理取消操作。

import * as p from '@clack/prompts';

const value = await p.text({ message: 'Your name?' });
if (p.isCancel(value)) {
  p.cancel('Operation cancelled.');
  process.exit(0);
}

为面向用户的CLI干净地启动和关闭会话。

p.intro('create-app');
// prompts
p.outro('Done');

Prompt Design Guidance

提示设计指南

Use these defaults unless the user asks otherwise.

```
text
```
: provide
```
validate
```
for required or constrained input.
```
confirm
```
: use for binary decisions; avoid coercing free-form text.
```
select
```
: use for mutually exclusive choices.
```
multiselect
```
or
```
groupMultiselect
```
: use for multi-choice and hierarchical multi-choice flows.
```
group
```
: gather structured answers while preserving dependencies between steps.
```
spinner
```
and
```
progress
```
: wrap long-running tasks and update status clearly.
```
tasks
```
: execute sequential task blocks with spinner status.
```
taskLog
```
: stream subprocess output and finish with success/failure.
```
stream
```
: render async or tokenized output (for LLM-style streaming).

除非用户另有要求，否则使用以下默认设置。

```
text
```
：为必填或受约束的输入提供
```
validate
```
验证逻辑。
```
confirm
```
：用于二元选择；避免强制转换自由格式文本。
```
select
```
：用于互斥选项选择。
```
multiselect
```
或
```
groupMultiselect
```
：用于多选和层级多选流程。
```
group
```
：收集结构化答案，同时保留步骤间的依赖关系。
```
spinner
```
和
```
progress
```
：包装长时间运行的任务并清晰更新状态。
```
tasks
```
：执行带有加载动画状态的顺序任务块。
```
taskLog
```
：流式传输子进程输出，并在结束时显示成功/失败状态。
```
stream
```
：渲染异步或令牌化输出（适用于LLM风格的流式输出）。

Implementation Sequence

实现步骤

Inspect user requirements and identify required prompt primitives.
Read the nearest example under
```
references/examples/
```
.

Confirm function/class availability from:

```
references/docs/prompts-exports.ts
```
```
references/docs/core-exports.ts
```

If behavior is unclear, inspect source under:

```
references/source/prompts/
```
```
references/source/core/
```

Implement with cancellation guards and clear terminal messaging.
Keep fallback behavior for non-interactive contexts when requested (see spinner and CI-oriented examples).

检查用户需求并确定所需的提示原语。
查看
```
references/examples/
```
中最贴近的示例。

从以下文件确认函数/类的可用性：

```
references/docs/prompts-exports.ts
```
```
references/docs/core-exports.ts
```

如果行为不明确，查看以下源码文件：

```
references/source/prompts/*.ts
```
```
references/source/core/prompts/*.ts
```

实现时添加取消保护和清晰的终端消息。
当用户要求时，为非交互式上下文保留回退行为（请参考加载动画和面向CI的示例）。

Reference Loading Strategy

参考文件加载策略

Start with these files.

```
references/docs/prompts-readme.md
```
```
references/docs/core-readme.md
```
```
references/INDEX.md
```

Load specific source files only as needed.

Prompts wrapper internals:
```
references/source/prompts/*.ts
```
Core prompt primitives:
```
references/source/core/prompts/*.ts
```
Core utility behavior:
```
references/source/core/utils/*.ts
```

从以下文件开始阅读。

```
references/docs/prompts-readme.md
```
```
references/docs/core-readme.md
```
```
references/INDEX.md
```

仅在需要时加载特定源码文件。

Prompts包装器内部实现：
```
references/source/prompts/*.ts
```
核心提示原语：
```
references/source/core/prompts/*.ts
```
核心工具函数实现：
```
references/source/core/utils/*.ts
```

Example-First Mapping

优先参考示例

Use this quick mapping to avoid re-inventing flows.

General prompt suite:
```
references/examples/basic/index.ts
```

Validation:

references/examples/basic/text-validation.ts

Autocomplete:

references/examples/basic/autocomplete.ts

Autocomplete multi-select:

references/examples/basic/autocomplete-multiselect.ts

Defaults:

references/examples/basic/default-value.ts

Filesystem path prompt:
```
references/examples/basic/path.ts
```
Spinner basics:
```
references/examples/basic/spinner.ts
```

Spinner cancellation:

references/examples/basic/spinner-cancel.ts

Advanced spinner cancellation:

references/examples/basic/spinner-cancel-advanced.ts

CI-oriented spinner behavior:
```
references/examples/basic/spinner-ci.ts
```

Timer-style spinner updates:

references/examples/basic/spinner-timer.ts

Progress bar:
```
references/examples/basic/progress.ts
```
Task log streaming:
```
references/examples/basic/task-log.ts
```
Stream utility:
```
references/examples/basic/stream.ts
```
Changesets integration flow:
```
references/examples/changesets/index.ts
```

使用以下快速映射避免重复造轮子。

通用提示套件：
```
references/examples/basic/index.ts
```

验证逻辑：

references/examples/basic/text-validation.ts

自动补全：

references/examples/basic/autocomplete.ts

自动补全多选：

references/examples/basic/autocomplete-multiselect.ts

默认值设置：

references/examples/basic/default-value.ts

文件系统路径提示：
```
references/examples/basic/path.ts
```
基础加载动画：
```
references/examples/basic/spinner.ts
```

加载动画取消：

references/examples/basic/spinner-cancel.ts

高级加载动画取消：

references/examples/basic/spinner-cancel-advanced.ts

面向CI的加载动画行为：
```
references/examples/basic/spinner-ci.ts
```

计时器风格加载动画更新：

references/examples/basic/spinner-timer.ts

进度条：
```
references/examples/basic/progress.ts
```
任务日志流式传输：
```
references/examples/basic/task-log.ts
```
流工具：
```
references/examples/basic/stream.ts
```
Changesets集成流程：
```
references/examples/changesets/index.ts
```

Quality Bar

质量标准

Before finalizing any clack implementation:

Confirm every import exists in the current exports file.
Ensure cancellation flow always exits safely.
Ensure prompt wording is short and unambiguous.
Ensure long-running operations provide visible status.
Ensure selected layer (
```
core
```
vs
```
prompts
```
) matches customization needs.

在完成任何Clack实现之前，请确认：

每个导入的模块都存在于当前导出文件中。
取消流程始终能安全退出。
提示文字简短且无歧义。
长时间运行的操作提供可见的状态反馈。
所选层级（
```
core
```
或
```
prompts
```
）与自定义需求匹配。