clack-kit

[!WARNING]

Powered by AI and reviewed by humans

主要代码均由 AI 生成，并由我来审核，但仍然可能存在遗漏的地方

clack-kit 是一个对 @clack/prompts 进行二次封装的库，旨在快速搭建终端交互流程（workflow）

@clack/prompts 文档 | clack-kit 文档

Features

• 支持结构化的 workflow 定义
• 支持历史记录、断点恢复、日志保存

它适合什么场景

• 把一整条终端流程写成可复用的 workflow
• 把 prompt、条件分支、命令执行放到同一条流程里
• 在交互步骤和 CLI 参数之间做映射
• 在需要的时候，再补上历史、checkpoint 和日志

默认行为

clack-kit 默认不会自动启用下面这三类持久化能力：

• 历史记录
• 断点恢复
• 日志保存

也就是说，不做额外配置时，它更像一个专门用来搭终端交互工作流的工具

只有显式开启时，才会写入 .clack-kit/

安装与开发

bun install

常用命令：

bun run lint # 含 tsc --noEmit 与 biome check
CI=1 bun run test
bun run build
bun run docs:dev
bun run docs:build

先跑一个最小 workflow

import { defineStep, runWorkflowSafely } from 'clack-kit';

const result = await runWorkflowSafely({
  id: 'hello-workflow',
  steps: [
    defineStep.text({
      id: 'name',
      message: '名字',
      required: true,
    }),
    defineStep.autocomplete({
      id: 'framework',
      message: '框架',
      options: ['react', 'vue', 'svelte'],
    }),
  ],
});

if (!result) return;

console.log(result.values.name);
console.log(result.values.framework);

这个例子故意很短

先把交互流程跑通，抓住 workflow -> steps -> result 这条主线就够了

开启历史、断点和日志

import {
  createWorkflowKit,
  defineStep,
  defineSteps,
  defineWorkflow,
} from 'clack-kit';

const kit = createWorkflowKit({
  asciiArt: {
    font: 'Standard',
  },
  checkpoints: true,
  history: true,
  id: 'create-project',
  logs: true,
  taskLog: {
    limit: 20,
  },
});

const workflow = defineWorkflow({
  id: 'create-project',
  intro: '创建项目',
  log: {
    completion: {
      initialValue: true,
      mode: 'confirm',
      message: '保存这次运行日志吗？',
    },
  },
  steps: defineSteps([
    defineStep.text({
      id: 'name',
      message: '项目名',
      required: true,
    }),
    defineStep.confirm({
      id: 'install',
      message: '现在安装依赖吗？',
    }),
  ]),
});

const result = await kit.runSafely(workflow, {
  checkpoint: {
    resume: 'ask',
    save: true,
  },
  history: {
    reuse: 'ask',
    saveSnapshot: true,
  },
});

if (!result) return;

console.log(result.savedLogPath);

这时候库才会开始保存快照、恢复中断流程、落盘运行日志

如果需要自定义 ASCII banner，可以在 createWorkflowKit() 里设置 asciiArt

• asciiArt.title 会把原始标题交给 figlet 生成 banner
• asciiArt.artTitle 会直接输出现成的 ASCII banner
• 未提供 title 和 artTitle 时，会回退到 createWorkflowKit().id
• asciiArt.font 用来控制自动生成 banner 时的 figlet 字体

当前内置并打包的常用字体有 Standard、Slant、Small、Big、Block、Doom、Larry 3D、Banner、Colossal、Bubble、Digital、Shadow、Script

运行时也接受小写别名，例如 standard、slant、small、doom、larry3d

阅读顺序

第一次接触这个库时，建议按这个顺序看：

1. docs/getting-started.md
2. docs/core-concepts.md
3. docs/examples.md
4. docs/workflows.md
5. docs/step-types-reference.md
6. docs/commands.md
7. docs/cli-integration.md
8. docs/best-practices.md
9. docs/persistence.md
10. docs/runtime-context.md
11. docs/templates-and-plugins.md
12. docs/api-reference.md
13. docs/troubleshooting.md
14. docs/architecture.md

想看完整文档地图时，可直接从 docs/README.md 开始

示例

可直接查看 examples/，或者先读 examples/README.md

比较常用的几个示例：

• examples/create-project.ts
• examples/command-modes.ts
• examples/docker-build.ts
• examples/release-workflow.ts
• examples/plugin-step.ts

更完整的示例阅读路线见 docs/examples.md