CLI 集成

返回总览

workflow 的交互步骤和 CLI 参数不是两套体系，clack-kit 提供了桥接层把它们接到一起

createWorkflowCliBridge 解决什么问题

它负责两件事

• 把一组可绑定的步骤映射成 CLI option
• 把解析后的 CLI options 还原成 initialValues

这样一来，命令行参数和终端交互可以共用同一份步骤定义

一个完整例子

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

const steps = defineSteps([
  defineStep.text({
    id: 'tag',
    message: '镜像标签',
    required: true,
  }),
  defineStep.confirm({
    id: 'plainProgress',
    message: '使用 plain 进度吗',
  }),
  defineStep.multiselect({
    id: 'checks',
    message: '检查项',
    options: ['lint', 'test', 'build'],
  }),
]);

const cli = cac('docker-build');
const bridge = createWorkflowCliBridge(steps);

bridge.apply(cli);
const parsed = cli.parse();

await createWorkflowKit().run(
  defineWorkflow({
    id: 'docker-build',
    steps,
  }),
  {
    initialValues: bridge.getInitialValues(parsed.options as Record<string, unknown>),
  },
);

默认映射规则

步骤	默认 option 形态
text、password、path、date、select、autocomplete	--field [value] 或 --field required-value
confirm	--field
multiselect、groupMultiselect、autocompleteMultiselect	--field value1,value2

默认情况下，step id 会被转换成 kebab-case

例如 plainProgress 会映射成 --plain-progress

哪些步骤会自动映射

当前适合自动映射到 CLI 的是输入类步骤

• text
• password
• path
• date
• select
• selectKey
• autocomplete
• multiselect
• autocompleteMultiselect
• groupMultiselect
• confirm

展示类步骤和 command 步骤不会自动映射成 CLI 参数

自定义单字段映射

createWorkflowCliBridge 支持在 fields 中覆盖默认规则

const bridge = createWorkflowCliBridge(steps, {
  fields: {
    checks: {
      option: '--checks <items>',
      parse(value) {
        return typeof value === 'string' ? value.split(',').map((item) => item.trim()) : undefined;
      },
    },
  },
});

常用覆盖点有四个

• option，直接改 option 定义
• optionKey，指定解析结果里的字段名
• optionConfig，透传给 CLI 库
• parse，自定义值解析方式

initialValues 和 CLI 的关系

bridge.getInitialValues 返回的是一份 initialValues

这意味着已提供参数的步骤通常会直接跳过交互，未提供的步骤继续询问

这种行为很适合

• CI 场景，用参数跳过标准输入
• 本地场景，只传关键值，其余继续交互
• 示例场景，既能脚本运行，也能手动试用

建议的组织方式

把 steps、bridge 和 workflow 放在同一个文件里维护，通常最清楚

这样做的好处是

• 步骤定义和参数映射不容易漂移
• CLI 参数名始终围绕步骤命名
• 后续需要扩展 parse 时，修改点集中

下一步建议

• 想理解 initialValues 与 defaultValue 的区别，看 核心概念
• 想看更完整的业务组织方式，看 定义工作流