clack-kit 0.0.1-beta.1

package/dist/index.d.mts

@@ -0,0 +1,2976 @@
+import * as _$_clack_prompts0 from "@clack/prompts";
+import { AutocompleteMultiSelectOptions, AutocompleteOptions, BoxAlignment, BoxOptions, CommonOptions, ConfirmOptions, GroupMultiSelectOptions, LimitOptionsParams, LogMessageOptions, MultiSelectOptions, NoteOptions, PasswordOptions, PathOptions, ProgressOptions, ProgressResult, SelectKeyOptions, SelectOptions, SpinnerOptions, SpinnerResult, Task, TaskLogOptions, TextOptions, autocomplete, autocompleteMultiselect, box, cancel, confirm, group, groupMultiselect, intro, isCI, isCancel, isTTY, limitOptions, log, multiselect, note, outro, password, path, progress, select, selectKey, spinner, stream, symbol, symbolBar, taskLog, tasks, text, unicode, unicodeOr } from "@clack/prompts";
+import * as _$node_stream0 from "node:stream";
+
+//#region node_modules/picocolors/types.d.ts
+type Formatter = (input: string | number | null | undefined) => string;
+interface Colors {
+  isColorSupported: boolean;
+  reset: Formatter;
+  bold: Formatter;
+  dim: Formatter;
+  italic: Formatter;
+  underline: Formatter;
+  inverse: Formatter;
+  hidden: Formatter;
+  strikethrough: Formatter;
+  black: Formatter;
+  red: Formatter;
+  green: Formatter;
+  yellow: Formatter;
+  blue: Formatter;
+  magenta: Formatter;
+  cyan: Formatter;
+  white: Formatter;
+  gray: Formatter;
+  bgBlack: Formatter;
+  bgRed: Formatter;
+  bgGreen: Formatter;
+  bgYellow: Formatter;
+  bgBlue: Formatter;
+  bgMagenta: Formatter;
+  bgCyan: Formatter;
+  bgWhite: Formatter;
+  blackBright: Formatter;
+  redBright: Formatter;
+  greenBright: Formatter;
+  yellowBright: Formatter;
+  blueBright: Formatter;
+  magentaBright: Formatter;
+  cyanBright: Formatter;
+  whiteBright: Formatter;
+  bgBlackBright: Formatter;
+  bgRedBright: Formatter;
+  bgGreenBright: Formatter;
+  bgYellowBright: Formatter;
+  bgBlueBright: Formatter;
+  bgMagentaBright: Formatter;
+  bgCyanBright: Formatter;
+  bgWhiteBright: Formatter;
+}
+//#endregion
+//#region node_modules/picocolors/picocolors.d.ts
+declare const picocolors: Colors & {
+  createColors: (enabled?: boolean) => Colors;
+};
+//#endregion
+//#region node_modules/@clack/core/dist/index.d.mts
+/**
+ * The state of the prompt
+ */
+type ClackState = 'initial' | 'active' | 'cancel' | 'submit' | 'error';
+/**
+ * Typed event emitter for clack
+ */
+//#endregion
+//#region src/runtime/clack.d.ts
+/** 默认的 Clack runtime，供渲染器复用 */
+declare const defaultPromptRuntime: {
+  autocomplete: <Value>(opts: _$_clack_prompts0.AutocompleteOptions<Value>) => Promise<Value | symbol>;
+  autocompleteMultiselect: <Value>(opts: _$_clack_prompts0.AutocompleteMultiSelectOptions<Value>) => Promise<Value[] | symbol>;
+  box: (message?: string, title?: string, opts?: _$_clack_prompts0.BoxOptions) => void;
+  cancel: (message?: string, opts?: _$_clack_prompts0.CommonOptions) => void;
+  confirm: (opts: _$_clack_prompts0.ConfirmOptions) => Promise<boolean | symbol>;
+  group: <T>(prompts: _$_clack_prompts0.PromptGroup<T>, opts?: _$_clack_prompts0.PromptGroupOptions<T>) => Promise<{ [P in keyof _$_clack_prompts0.PromptGroupAwaitedReturn<T>]: _$_clack_prompts0.PromptGroupAwaitedReturn<T>[P] }>;
+  groupMultiselect: <Value>(opts: _$_clack_prompts0.GroupMultiSelectOptions<Value>) => Promise<Value[] | symbol>;
+  intro: (title?: string, opts?: _$_clack_prompts0.CommonOptions) => void;
+  isCancel: typeof isCancel;
+  isCI: () => boolean;
+  isTTY: (output: _$node_stream0.Writable) => boolean;
+  limitOptions: <TOption>({
+    cursor,
+    options,
+    style,
+    output,
+    maxItems,
+    columnPadding,
+    rowPadding
+  }: _$_clack_prompts0.LimitOptionsParams<TOption>) => string[];
+  log: {
+    message: (message?: string | string[], {
+      symbol,
+      secondarySymbol,
+      output,
+      spacing,
+      withGuide
+    }?: _$_clack_prompts0.LogMessageOptions) => void;
+    info: (message: string, opts?: _$_clack_prompts0.LogMessageOptions) => void;
+    success: (message: string, opts?: _$_clack_prompts0.LogMessageOptions) => void;
+    step: (message: string, opts?: _$_clack_prompts0.LogMessageOptions) => void;
+    warn: (message: string, opts?: _$_clack_prompts0.LogMessageOptions) => void;
+    warning: (message: string, opts?: _$_clack_prompts0.LogMessageOptions) => void;
+    error: (message: string, opts?: _$_clack_prompts0.LogMessageOptions) => void;
+  };
+  multiselect: <Value>(opts: _$_clack_prompts0.MultiSelectOptions<Value>) => Promise<Value[] | symbol>;
+  note: (message?: string, title?: string, opts?: _$_clack_prompts0.NoteOptions) => void;
+  outro: (message?: string, opts?: _$_clack_prompts0.CommonOptions) => void;
+  password: (opts: _$_clack_prompts0.PasswordOptions) => Promise<string | symbol>;
+  path: (opts: _$_clack_prompts0.PathOptions) => Promise<string | symbol>;
+  progress: typeof progress;
+  select: <Value>(opts: _$_clack_prompts0.SelectOptions<Value>) => Promise<Value | symbol>;
+  selectKey: <Value extends string>(opts: _$_clack_prompts0.SelectKeyOptions<Value>) => Promise<Value | symbol>;
+  spinner: ({
+    indicator,
+    onCancel,
+    output,
+    cancelMessage,
+    errorMessage,
+    frames,
+    delay,
+    signal,
+    ...opts
+  }?: _$_clack_prompts0.SpinnerOptions) => _$_clack_prompts0.SpinnerResult;
+  stream: {
+    message: (iterable: Iterable<string> | AsyncIterable<string>, {
+      symbol
+    }?: _$_clack_prompts0.LogMessageOptions) => Promise<void>;
+    info: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
+    success: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
+    step: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
+    warn: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
+    warning: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
+    error: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
+  };
+  symbol: (state: ClackState) => string;
+  symbolBar: (state: ClackState) => string;
+  taskLog: (opts: _$_clack_prompts0.TaskLogOptions) => {
+    message(msg: string, mopts?: _$_clack_prompts0.TaskLogMessageOptions): void;
+    group(name: string): {
+      message(msg: string, mopts?: _$_clack_prompts0.TaskLogMessageOptions): void;
+      error(message: string): void;
+      success(message: string): void;
+    };
+    error(message: string, opts?: _$_clack_prompts0.TaskLogCompletionOptions): void;
+    success(message: string, opts?: _$_clack_prompts0.TaskLogCompletionOptions): void;
+  };
+  tasks: (tasks: _$_clack_prompts0.Task[], opts?: _$_clack_prompts0.CommonOptions) => Promise<void>;
+  text: (opts: _$_clack_prompts0.TextOptions) => Promise<string | symbol>;
+  unicode: boolean;
+  unicodeOr: (c: string, fallback: string) => string;
+};
+/** Clack runtime 的形状定义 */
+type PromptRuntime = typeof defaultPromptRuntime;
+//#endregion
+//#region src/shared/types.d.ts
+type MaybePromise<TValue> = Promise<TValue> | TValue;
+type WorkflowColors = Omit<typeof picocolors, 'createColors'>;
+/** 支持的内置语言标识 */
+type WorkflowLocale = 'en-US' | 'zh-CN' | (string & {});
+/** 时区标识，通常使用 IANA Time Zone 名称 */
+type WorkflowTimeZone = string;
+/** 统一的日志级别 */
+type WorkflowLogLevel = 'error' | 'info' | 'message' | 'step' | 'success' | 'warn' | 'warning';
+/** 工作流运行的最终状态 */
+type WorkflowRunStatus = 'cancelled' | 'completed' | 'failed' | 'running';
+/** 历史复用策略 */
+type WorkflowHistoryReuseMode = 'ask' | 'history' | 'latest' | 'off';
+/** Checkpoint 恢复策略 */
+type WorkflowCheckpointResumeMode = 'always' | 'ask' | 'never';
+/** Checkpoint 保留时的中断原因 */
+type WorkflowCheckpointReason = 'cancelled' | 'failed';
+/** 结构化消息模板的插值参数 */
+type WorkflowMessageValues = Record<string, boolean | null | number | string | undefined>;
+/** 单个 locale 的嵌套资源结构 */
+interface WorkflowLocaleResource {
+  [key: string]: string | WorkflowLocaleResource;
+}
+/** 国际化 locale 资源目录 */
+type WorkflowLocaleCatalog = Record<string, WorkflowLocaleResource>;
+/** 选择类步骤的选项结构 */
+interface WorkflowSelectOption<TValue> {
+  /** 是否禁用当前选项 */
+  disabled?: boolean;
+  /** 展示在终端中的补充说明 */
+  hint?: string;
+  /** 选项标签 */
+  label: string;
+  /** 选项值 */
+  value: TValue;
+}
+/** 工作流运行时暴露给回调和 resolver 的上下文 */
+interface WorkflowRuntimeContext<TValues extends Record<string, unknown> = Record<string, unknown>, TResults extends Record<string, unknown> = Record<string, unknown>> {
+  /** 输出结构化 box */
+  box: (message?: string, title?: string, options?: WorkflowRendererBoxOptions) => void;
+  /** picocolors 颜色工具，可直接拿来拼装彩色输出 */
+  colors: WorkflowColors;
+  /** 当前运行语言 */
+  locale: WorkflowLocale;
+  /** 输出一条带级别的消息 */
+  log: (level: WorkflowLogLevel, message: string | string[], options?: WorkflowRendererLogOptions) => void;
+  /** 输出结构化说明块 */
+  note: (message?: string, title?: string, options?: WorkflowRendererNoteOptions) => void;
+  /** 当前运行 ID */
+  runId: string;
+  /** 读取本次运行中可用的辅助函数 */
+  tools: WorkflowContextTools;
+  /** 翻译消息 */
+  t: (key: string, params?: WorkflowMessageValues) => string;
+  /** 当前运行时区 */
+  timeZone: WorkflowTimeZone;
+  /** 当前步骤执行结果；读取命令步骤返回值时优先使用这里 */
+  results: Partial<TResults>;
+  /** 当前已解析的 values */
+  values: Partial<TValues>;
+  /** 当前工作流 ID */
+  workflowId: string;
+}
+/** 工作流上下文中可直接复用的辅助函数 */
+interface WorkflowContextTools {
+  /** 允许插件向 tools 挂载额外能力 */
+  [key: string]: unknown;
+  /** 暴露原始 @clack/prompts runtime，便于直接复用内置组件 */
+  clack: PromptRuntime;
+  /** 当前项目根目录 */
+  projectRoot: string;
+  /** 读取文本文件 */
+  readFile: (filePath: string) => Promise<string>;
+  /** 读取 JSON 文件 */
+  readJson: <TValue = unknown>(filePath: string) => Promise<TValue>;
+  /** 执行简单 glob 查询 */
+  globFiles: (pattern: string, options?: WorkflowGlobOptions) => Promise<string[]>;
+  /** 合并并写回 JSON 文件 */
+  patchJson: <TValue extends Record<string, unknown>>(filePath: string, updater: (current: TValue) => MaybePromise<TValue>) => Promise<TValue>;
+  /** 休眠指定毫秒数 */
+  sleep: (milliseconds: number) => Promise<void>;
+  /** 写入文本文件 */
+  writeFile: (filePath: string, content: string) => Promise<void>;
+  /** 写入 JSON 文件 */
+  writeJson: (filePath: string, value: unknown) => Promise<void>;
+}
+/** 允许用常量或 resolver 提供动态值 */
+type WorkflowValueResolver<TValue, TValues extends Record<string, unknown> = Record<string, unknown>, TResults extends Record<string, unknown> = Record<string, unknown>> = TValue | ((context: WorkflowRuntimeContext<TValues, TResults>) => MaybePromise<TValue>);
+/** 步骤是否执行的判定函数 */
+type WorkflowPredicate<TValues extends Record<string, unknown> = Record<string, unknown>, TResults extends Record<string, unknown> = Record<string, unknown>> = (context: WorkflowRuntimeContext<TValues, TResults>) => MaybePromise<boolean>;
+/** 步骤值校验函数 */
+type WorkflowValidator<TValue, TValues extends Record<string, unknown> = Record<string, unknown>, TResults extends Record<string, unknown> = Record<string, unknown>> = (value: TValue, context: WorkflowRuntimeContext<TValues, TResults>) => MaybePromise<Error | string | undefined>;
+/** 所有可执行步骤共有的基础配置 */
+interface WorkflowBaseStep<TId extends string, TValue, TKind extends string> {
+  /** 步骤在 values 中对应的 key */
+  id: TId;
+  /** 为交互输入提供默认值；不同于运行参数里的 `initialValues` */
+  defaultValue?: WorkflowValueResolver<TValue | undefined>;
+  /** 步骤类型 */
+  kind: TKind;
+  /** 控制步骤是否执行 */
+  when?: WorkflowPredicate<Record<string, unknown>>;
+}
+/** 文本输入步骤 */
+interface WorkflowTextStep<TId extends string> extends WorkflowBaseStep<TId, string, 'text'> {
+  /** 提示文案 */
+  message: WorkflowValueResolver<TextOptions['message']>;
+  /** 占位提示 */
+  placeholder?: WorkflowValueResolver<TextOptions['placeholder']>;
+  /** 是否必填；当为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<string>;
+}
+/** 单选步骤 */
+interface WorkflowSelectStep<TId extends string, TValue> extends WorkflowBaseStep<TId, TValue, 'select'> {
+  /** 提示文案 */
+  message: WorkflowValueResolver<SelectOptions<TValue>['message']>;
+  /** 最多显示多少项 */
+  maxItems?: WorkflowValueResolver<SelectOptions<TValue>['maxItems']>;
+  /** 可选项列表 */
+  options: WorkflowValueResolver<readonly TValue[]> | WorkflowValueResolver<readonly WorkflowSelectOption<TValue>[]>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue>;
+}
+/** 自动补全步骤，表现为带筛选能力的单选 */
+interface WorkflowAutocompleteStep<TId extends string, TValue> extends WorkflowBaseStep<TId, TValue, 'autocomplete'> {
+  /** 自定义筛选函数 */
+  filter?: (search: string, option: WorkflowSelectOption<TValue>) => boolean;
+  /** 首次打开时的搜索词 */
+  initialUserInput?: WorkflowValueResolver<AutocompleteOptions<TValue>['initialUserInput']>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<AutocompleteOptions<TValue>['message']>;
+  /** 最多显示多少项 */
+  maxItems?: WorkflowValueResolver<AutocompleteOptions<TValue>['maxItems']>;
+  /** 可搜索选项列表 */
+  options: WorkflowValueResolver<readonly TValue[]> | WorkflowValueResolver<readonly WorkflowSelectOption<TValue>[]>;
+  /** 搜索输入占位提示 */
+  placeholder?: WorkflowValueResolver<AutocompleteOptions<TValue>['placeholder']>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue>;
+}
+/** 多选步骤 */
+interface WorkflowMultiSelectStep<TId extends string, TValue> extends WorkflowBaseStep<TId, TValue[], 'multiselect'> {
+  /** 初始光标所在的选项值 */
+  cursorAt?: WorkflowValueResolver<MultiSelectOptions<TValue>['cursorAt']>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<MultiSelectOptions<TValue>['message']>;
+  /** 最多显示多少项 */
+  maxItems?: WorkflowValueResolver<MultiSelectOptions<TValue>['maxItems']>;
+  /** 可选项列表 */
+  options: WorkflowValueResolver<readonly TValue[]> | WorkflowValueResolver<readonly WorkflowSelectOption<TValue>[]>;
+  /** 是否至少要选中一项；为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue[]>;
+}
+/** 自动补全多选步骤 */
+interface WorkflowAutocompleteMultiSelectStep<TId extends string, TValue> extends WorkflowBaseStep<TId, TValue[], 'autocomplete-multiselect'> {
+  /** 自定义筛选函数 */
+  filter?: (search: string, option: WorkflowSelectOption<TValue>) => boolean;
+  /** 提示文案 */
+  message: WorkflowValueResolver<AutocompleteMultiSelectOptions<TValue>['message']>;
+  /** 最多显示多少项 */
+  maxItems?: WorkflowValueResolver<AutocompleteMultiSelectOptions<TValue>['maxItems']>;
+  /** 可搜索选项列表 */
+  options: WorkflowValueResolver<readonly TValue[]> | WorkflowValueResolver<readonly WorkflowSelectOption<TValue>[]>;
+  /** 搜索输入占位提示 */
+  placeholder?: WorkflowValueResolver<AutocompleteMultiSelectOptions<TValue>['placeholder']>;
+  /** 是否至少要选中一项；为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue[]>;
+}
+/** 分组多选步骤 */
+interface WorkflowGroupMultiSelectStep<TId extends string, TValue> extends WorkflowBaseStep<TId, TValue[], 'group-multiselect'> {
+  /** 初始光标所在的选项值 */
+  cursorAt?: WorkflowValueResolver<GroupMultiSelectOptions<TValue>['cursorAt']>;
+  /** 分组间距 */
+  groupSpacing?: WorkflowValueResolver<GroupMultiSelectOptions<TValue>['groupSpacing']>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<GroupMultiSelectOptions<TValue>['message']>;
+  /** 分组选项列表 */
+  options: WorkflowValueResolver<Record<string, readonly TValue[] | readonly WorkflowSelectOption<TValue>[]>>;
+  /** 是否至少要选中一项；为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 是否允许直接选中整组 */
+  selectableGroups?: WorkflowValueResolver<GroupMultiSelectOptions<TValue>['selectableGroups']>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue[]>;
+}
+/** 密码输入步骤 */
+interface WorkflowPasswordStep<TId extends string> extends WorkflowBaseStep<TId, string, 'password'> {
+  /** 校验失败时是否清空输入 */
+  clearOnError?: WorkflowValueResolver<PasswordOptions['clearOnError']>;
+  /** 掩码字符 */
+  mask?: WorkflowValueResolver<PasswordOptions['mask']>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<PasswordOptions['message']>;
+  /** 是否必填；当为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<string>;
+}
+/** 文件路径输入步骤 */
+interface WorkflowPathStep<TId extends string> extends WorkflowBaseStep<TId, string, 'path'> {
+  /** 是否要求选择目录 */
+  directory?: WorkflowValueResolver<PathOptions['directory']>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<PathOptions['message']>;
+  /** 是否必填；当为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 根目录 */
+  root?: WorkflowValueResolver<PathOptions['root']>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<string>;
+}
+/** 带快捷键的单选步骤 */
+interface WorkflowSelectKeyStep<TId extends string, TValue extends string> extends WorkflowBaseStep<TId, TValue, 'select-key'> {
+  /** 是否区分大小写 */
+  caseSensitive?: WorkflowValueResolver<SelectKeyOptions<TValue>['caseSensitive']>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<SelectKeyOptions<TValue>['message']>;
+  /** 可选项列表 */
+  options: WorkflowValueResolver<readonly TValue[]> | WorkflowValueResolver<readonly WorkflowSelectOption<TValue>[]>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue>;
+}
+/** 布尔确认步骤 */
+interface WorkflowConfirmStep<TId extends string> extends WorkflowBaseStep<TId, boolean, 'confirm'> {
+  /** “确认”文案 */
+  active?: WorkflowValueResolver<ConfirmOptions['active']>;
+  /** “取消”文案 */
+  inactive?: WorkflowValueResolver<ConfirmOptions['inactive']>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<ConfirmOptions['message']>;
+  /** 是否垂直排列选项 */
+  vertical?: WorkflowValueResolver<ConfirmOptions['vertical']>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<boolean>;
+}
+/** 结构化说明步骤 */
+interface WorkflowNoteStep<TId extends string> extends WorkflowBaseStep<TId, undefined, 'note'> {
+  /** 每一行的格式化函数 */
+  format?: NoteOptions['format'];
+  /** 提示内容 */
+  message?: WorkflowValueResolver<string | undefined>;
+  /** 标题 */
+  title?: WorkflowValueResolver<string | undefined>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+}
+/** 带边框的说明步骤 */
+interface WorkflowBoxStep<TId extends string> extends WorkflowBaseStep<TId, undefined, 'box'> {
+  /** 内容对齐方式 */
+  contentAlign?: WorkflowValueResolver<BoxOptions['contentAlign']>;
+  /** 内容内边距 */
+  contentPadding?: WorkflowValueResolver<BoxOptions['contentPadding']>;
+  /** 自定义边框格式化 */
+  formatBorder?: BoxOptions['formatBorder'];
+  /** 提示内容 */
+  message?: WorkflowValueResolver<string | undefined>;
+  /** 是否使用圆角 */
+  rounded?: WorkflowValueResolver<BoxOptions['rounded']>;
+  /** 标题对齐方式 */
+  titleAlign?: WorkflowValueResolver<BoxOptions['titleAlign']>;
+  /** 标题内边距 */
+  titlePadding?: WorkflowValueResolver<BoxOptions['titlePadding']>;
+  /** 标题 */
+  title?: WorkflowValueResolver<string | undefined>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+  /** 宽度 */
+  width?: WorkflowValueResolver<BoxOptions['width']>;
+}
+/** 语义化日志步骤 */
+interface WorkflowLogStep<TId extends string> extends WorkflowBaseStep<TId, undefined, 'log'> {
+  /** 日志级别 */
+  level?: WorkflowValueResolver<WorkflowLogLevel | undefined>;
+  /** 日志内容 */
+  message?: WorkflowValueResolver<string | string[] | undefined>;
+  /** 次级符号 */
+  secondarySymbol?: WorkflowValueResolver<LogMessageOptions['secondarySymbol']>;
+  /** 行间距 */
+  spacing?: WorkflowValueResolver<LogMessageOptions['spacing']>;
+  /** 主符号 */
+  symbol?: WorkflowValueResolver<LogMessageOptions['symbol']>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<CommonOptions['withGuide']>;
+}
+/** 命令步骤最终结果类型；具体结构由步骤作者决定 */
+type WorkflowCommandResult<TValue = unknown> = TValue;
+/** 外部命令执行器返回的标准执行记录 */
+interface WorkflowCommandExecutionResult {
+  /** 退出码 */
+  code: number;
+  /** 合并后的 stdout + stderr 文本 */
+  combined: string;
+  /** stderr 文本 */
+  stderr: string;
+  /** stdout 文本 */
+  stdout: string;
+}
+/** 命令步骤失败后的重试配置 */
+interface WorkflowCommandRetryOptions {
+  /** 退避策略 */
+  backoff?: 'exponential' | 'fixed' | 'linear';
+  /** 每次重试前的基础等待毫秒数 */
+  delayMs?: number;
+  /** 最大尝试次数，包含首次执行 */
+  maxAttempts?: number;
+}
+/** shell 模式下执行脚本时用到的解释器配置 */
+interface WorkflowCommandShellOptions {
+  /** shell 可执行文件；未提供时按当前平台选择默认值 */
+  command?: WorkflowValueResolver<string | undefined>;
+  /** 传给 shell 的前置参数；运行时会自动把脚本文本追加到最后 */
+  args?: WorkflowValueResolver<string[] | undefined>;
+}
+/** 在 command 步骤内部直接执行命令时可传的选项 */
+interface WorkflowCommandExecOptions {
+  /** 工作目录；相对路径会基于项目根目录解析 */
+  cwd?: string;
+  /** 额外环境变量 */
+  env?: NodeJS.ProcessEnv;
+  /** shell 解释器配置；未提供时自动检测或回退到平台默认值 */
+  shell?: WorkflowCommandShellOptions;
+  /** stdin 处理策略 */
+  stdin?: 'ignore' | 'inherit';
+}
+/** task-log 展示器的配置 */
+interface WorkflowCommandTaskLogOptions {
+  /** 保留的日志行数上限 */
+  limit?: number;
+  /** 任务结束后是否保留日志内容 */
+  retainLog?: boolean;
+}
+/** 命令步骤中可用的输出工具 */
+interface WorkflowCommandTaskIO {
+  /** 输出结构化 box */
+  box: (message?: string, title?: string, options?: WorkflowRendererBoxOptions) => void;
+  /** 暴露原始 @clack/prompts runtime，便于直接使用 taskLog、spinner 等能力 */
+  clack: PromptRuntime;
+  /** picocolors 颜色工具，可直接给 stdout / stderr / note 上色 */
+  colors: WorkflowColors;
+  /** 直接执行一条完整命令字符串；命令会通过 shell 运行，并同步当前步骤的退出码 */
+  exec: (command: string, options?: WorkflowCommandExecOptions) => Promise<WorkflowCommandExecutionResult>;
+  /** 直接执行一个脚本文件；路径相对项目根目录解析 */
+  execScriptFile: (scriptFile: string, options?: WorkflowCommandExecOptions) => Promise<WorkflowCommandExecutionResult>;
+  /** 输出一条带级别的消息 */
+  log: (level: WorkflowLogLevel, message: string | string[], options?: WorkflowRendererLogOptions) => void;
+  /** 输出结构化说明块 */
+  note: (message?: string, title?: string, options?: WorkflowRendererNoteOptions) => void;
+  /** 当前项目根目录 */
+  projectRoot: string;
+  /** 显式设置当前命令步骤的退出码 */
+  setExitCode: (code: number) => void;
+  /** 休眠指定毫秒数 */
+  sleep: (milliseconds: number) => Promise<void>;
+  /** 当前命令步骤的 task-log 配置 */
+  taskLog?: WorkflowCommandTaskLogOptions;
+  /** 写入 stderr */
+  stderr: (chunk: string) => void;
+  /** 写入 stdout */
+  stdout: (chunk: string) => void;
+}
+/** 异步命令处理函数 */
+type WorkflowCommandHandler<TValues extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = (context: WorkflowRuntimeContext<TValues>, io: WorkflowCommandTaskIO) => MaybePromise<TResult | undefined> | Promise<void>;
+/** 将命令执行记录映射成步骤最终结果 */
+type WorkflowCommandResultResolver<TResult = unknown, TValues extends Record<string, unknown> = Record<string, unknown>, TResults extends Record<string, unknown> = Record<string, unknown>> = (execution: WorkflowCommandExecutionResult, context: WorkflowRuntimeContext<TValues, TResults>) => MaybePromise<TResult>;
+/** 外部命令步骤 */
+interface WorkflowExternalCommandStep<TId extends string, TResult = unknown> extends WorkflowBaseStep<TId, WorkflowCommandResult<TResult>, 'command'> {
+  /** 非零退出码是否允许继续工作流 */
+  allowFailure?: boolean;
+  /** 要执行的完整命令字符串；支持直接传字符串，也支持用函数动态返回 */
+  command: WorkflowValueResolver<string>;
+  /** 命令执行目录 */
+  cwd?: WorkflowValueResolver<string | undefined>;
+  /** 命令环境变量 */
+  env?: WorkflowValueResolver<NodeJS.ProcessEnv | undefined>;
+  /**
+   * 输出渲染方式
+   *
+   * @default 'task-log'
+   */
+  renderer?: 'inherit' | 'quiet' | 'task-log';
+  /** shell 解释器配置；未提供时按平台默认值执行 `command` */
+  shell?: WorkflowCommandShellOptions;
+  /** 当前命令步骤的 task-log 配置；会覆盖 renderer 上的全局默认值 */
+  taskLog?: WorkflowCommandTaskLogOptions;
+  /** 命令失败后的重试策略 */
+  retry?: boolean | WorkflowCommandRetryOptions;
+  /** 并行分组；同层连续且 group 相同的 command 步骤会并行执行 */
+  parallel?: string;
+  /** 将执行记录映射成最终写入 results 的值 */
+  result?: WorkflowCommandResultResolver<TResult>;
+  /** stdin 处理策略 */
+  stdin?: 'ignore' | 'inherit';
+  /** 展示标题 */
+  title?: WorkflowValueResolver<string | undefined>;
+}
+/** 脚本文件步骤 */
+interface WorkflowScriptFileCommandStep<TId extends string, TResult = unknown> extends WorkflowBaseStep<TId, WorkflowCommandResult<TResult>, 'command'> {
+  /** 非零退出码是否允许继续工作流 */
+  allowFailure?: boolean;
+  /** 命令执行目录 */
+  cwd?: WorkflowValueResolver<string | undefined>;
+  /** 命令环境变量 */
+  env?: WorkflowValueResolver<NodeJS.ProcessEnv | undefined>;
+  /**
+   * 输出渲染方式
+   *
+   * @default 'task-log'
+   */
+  renderer?: 'inherit' | 'quiet' | 'task-log';
+  /** shell 解释器配置；未提供时优先根据 shebang / 扩展名自动检测 */
+  shell?: WorkflowCommandShellOptions;
+  /** 要执行的脚本文件路径；支持直接传字符串，也支持用函数动态返回 */
+  scriptFile: WorkflowValueResolver<string>;
+  /** 当前命令步骤的 task-log 配置；会覆盖 renderer 上的全局默认值 */
+  taskLog?: WorkflowCommandTaskLogOptions;
+  /** 命令失败后的重试策略 */
+  retry?: boolean | WorkflowCommandRetryOptions;
+  /** 并行分组；同层连续且 group 相同的 command 步骤会并行执行 */
+  parallel?: string;
+  /** 将执行记录映射成最终写入 results 的值 */
+  result?: WorkflowCommandResultResolver<TResult>;
+  /** stdin 处理策略 */
+  stdin?: 'ignore' | 'inherit';
+  /** 展示标题 */
+  title?: WorkflowValueResolver<string | undefined>;
+}
+/** 内联异步任务步骤 */
+interface WorkflowInlineCommandStep<TId extends string, TResult = unknown> extends WorkflowBaseStep<TId, WorkflowCommandResult<TResult>, 'command'> {
+  /** 非零退出码是否允许继续工作流 */
+  allowFailure?: boolean;
+  /**
+   * 输出渲染方式
+   *
+   * @default 'task-log'
+   */
+  renderer?: 'inherit' | 'quiet' | 'task-log';
+  /** 当前命令步骤的 task-log 配置；会覆盖 renderer 上的全局默认值 */
+  taskLog?: WorkflowCommandTaskLogOptions;
+  /** 命令失败后的重试策略 */
+  retry?: boolean | WorkflowCommandRetryOptions;
+  /** 并行分组；同层连续且 group 相同的 command 步骤会并行执行 */
+  parallel?: string;
+  /** 内联异步任务 */
+  run: WorkflowCommandHandler<Record<string, unknown>, TResult>;
+  /** 展示标题 */
+  title?: WorkflowValueResolver<string | undefined>;
+}
+/** 命令步骤 */
+type WorkflowCommandStep<TId extends string, TResult = unknown> = WorkflowExternalCommandStep<TId, TResult> | WorkflowScriptFileCommandStep<TId, TResult> | WorkflowInlineCommandStep<TId, TResult>;
+/** 当前版本支持的会写入 values 的内置步骤 */
+type WorkflowBuiltinValueStep = WorkflowAutocompleteMultiSelectStep<string, any> | WorkflowConfirmStep<string> | WorkflowGroupMultiSelectStep<string, any> | WorkflowMultiSelectStep<string, any> | WorkflowPasswordStep<string> | WorkflowPathStep<string> | WorkflowAutocompleteStep<string, any> | WorkflowSelectKeyStep<string, string> | WorkflowSelectStep<string, any> | WorkflowTextStep<string>;
+/** 当前版本支持的展示类步骤 */
+type WorkflowBuiltinDisplayStep = WorkflowBoxStep<string> | WorkflowLogStep<string> | WorkflowNoteStep<string>;
+/** 当前版本支持的会写入 results 的内置步骤 */
+type WorkflowBuiltinResultStep = WorkflowBuiltinValueStep | WorkflowCommandStep<string, unknown>;
+/** 当前版本支持的可执行步骤 */
+type WorkflowBuiltinExecutableStep = WorkflowBuiltinResultStep | WorkflowBuiltinDisplayStep;
+/** 插件注册的自定义步骤 */
+interface WorkflowPluginStep<TId extends string = string, TValue = unknown, TKind extends string = string> extends WorkflowBaseStep<TId, TValue, TKind> {
+  /** 允许插件步骤挂载任意自定义字段 */
+  [key: string]: unknown;
+}
+/** 当前版本支持的可执行步骤 */
+type WorkflowExecutableStep = WorkflowBuiltinExecutableStep | WorkflowPluginStep;
+/** 当前版本支持的步骤联合类型 */
+type WorkflowStepDefinition = WorkflowExecutableStep;
+/** 从步骤定义中提取指定步骤集合对应的对象形状 */
+type StepRecordFor<TStep, TAllowed> = TStep extends TAllowed ? TStep extends WorkflowBaseStep<infer TId, infer TValue, string> ? { [TKey in TId]: TValue } : never : never;
+/** 从步骤定义中提取结果对象形状 */
+type StepValueRecord<TStep extends WorkflowStepDefinition> = StepRecordFor<TStep, WorkflowBuiltinValueStep | WorkflowPluginStep>;
+/** 从步骤定义中提取 results 对象形状 */
+type StepResultRecord<TStep extends WorkflowStepDefinition> = StepRecordFor<TStep, WorkflowBuiltinResultStep | WorkflowPluginStep>;
+/** 将联合类型转换成交叉类型，便于组装步骤结果 */
+type UnionToIntersection<TValue> = (TValue extends unknown ? (value: TValue) => void : never) extends ((value: infer TResult) => void) ? TResult : never;
+/** 让交叉类型以对象字面量形式显示 */
+type Simplify<TValue> = { [TKey in keyof TValue]: TValue[TKey] } & {};
+/** 从步骤列表推导最终的 values 类型 */
+type WorkflowValuesFromSteps<TSteps extends readonly WorkflowStepDefinition[]> = Simplify<UnionToIntersection<StepValueRecord<TSteps[number]>>>;
+/** 从步骤列表推导最终的 results 类型 */
+type WorkflowResultsFromSteps<TSteps extends readonly WorkflowStepDefinition[]> = Simplify<UnionToIntersection<StepResultRecord<TSteps[number]>>>;
+/** 工作流级 ASCII banner 定义 */
+type WorkflowAsciiArtDefinition<TValues extends Record<string, unknown> = Record<string, unknown>> = WorkflowValueResolver<boolean | string | undefined, TValues>;
+/** 工作流快照的定义 */
+interface WorkflowSnapshotOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /** 是否启用完整工作流快照保存 */
+  enabled?: boolean;
+  /** 自定义快照标签 */
+  label?: (context: WorkflowRuntimeContext<TValues, Record<string, unknown>>) => MaybePromise<string>;
+}
+/** 默认 summary 的格式预设 */
+type WorkflowSummaryPreset = 'json' | 'key-value';
+/** 工作流完成后自动输出 summary 的配置 */
+interface WorkflowSummaryOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * 是否启用默认 summary
+   *
+   * @default true
+   */
+  enabled?: boolean;
+  /** summary 格式预设 */
+  preset?: WorkflowValueResolver<WorkflowSummaryPreset | undefined, TValues>;
+  /** summary 标题 */
+  title?: WorkflowValueResolver<string | undefined, TValues>;
+}
+/** 工作流级日志策略 */
+interface WorkflowLogOptions {
+  /** 工作流成功完成后的日志处理方式 */
+  completion?: false | WorkflowLogCompletionOptions;
+  /**
+   * 工作流失败时是否自动保存日志
+   *
+   * @default true
+   */
+  saveOnFailure?: boolean;
+}
+/** `intro` 支持的 authoring 形态 */
+type WorkflowIntroDefinition<TValues extends Record<string, unknown> = Record<string, unknown>> = false | string | ((context: WorkflowRuntimeContext<TValues>) => MaybePromise<string | undefined>);
+/** 工作流定义 */
+interface WorkflowDefinition<TSteps extends readonly WorkflowStepDefinition[] = readonly WorkflowStepDefinition[]> {
+  /**
+   * ASCII 文字内容；传字符串时直接打印，传 `true` 时会基于标题自动生成
+   *
+   * @default true
+   */
+  asciiArt?: WorkflowAsciiArtDefinition<WorkflowValuesFromSteps<TSteps>>;
+  /** 工作流唯一 ID，同时也是历史和日志的命名空间 */
+  id: string;
+  /** 开场信息；可传字符串、函数或 `false` */
+  intro?: WorkflowIntroDefinition<WorkflowValuesFromSteps<TSteps>>;
+  /** 工作流完成后的自定义回调；未提供时会默认打印 `key=value` 摘要 */
+  onComplete?: (context: WorkflowRuntimeContext<WorkflowValuesFromSteps<TSteps>, WorkflowResultsFromSteps<TSteps>>) => MaybePromise<void>;
+  /** 工作流开始前执行的回调 */
+  onStart?: (context: WorkflowRuntimeContext<WorkflowValuesFromSteps<TSteps>, WorkflowResultsFromSteps<TSteps>>) => MaybePromise<void>;
+  /** 工作流级日志策略 */
+  log?: WorkflowLogOptions;
+  /** 结束语；既可以直接传字符串，也可以按运行时上下文动态生成 */
+  outro?: WorkflowValueResolver<string | undefined, WorkflowValuesFromSteps<TSteps>>;
+  /** 工作流级历史快照配置 */
+  snapshot?: WorkflowSnapshotOptions<WorkflowValuesFromSteps<TSteps>>;
+  /**
+   * 默认 summary 输出配置
+   *
+   * @default true
+   */
+  summary?: false | WorkflowSummaryOptions<WorkflowValuesFromSteps<TSteps>>;
+  /** 工作流步骤列表；支持分支嵌套 */
+  steps: TSteps;
+  /** `intro` 的简写标题；当未提供 `intro` 时会自动回退到这里 */
+  title?: WorkflowValueResolver<string | undefined, WorkflowValuesFromSteps<TSteps>>;
+}
+/** 工作流模板定义 */
+interface WorkflowTemplate<TInput = void, TSteps extends readonly WorkflowStepDefinition[] = readonly WorkflowStepDefinition[]> {
+  /** 模板创建函数 */
+  create: (input: TInput) => MaybePromise<WorkflowDefinition<TSteps> | WorkflowDefinition<readonly WorkflowStepDefinition[]>>;
+  /** 模板说明 */
+  description?: string;
+  /** 模板唯一 ID */
+  id: string;
+  /** 模板展示名称 */
+  title?: string;
+}
+/** 工作流模板目录接口 */
+interface WorkflowTemplateCatalog<TTemplates extends readonly WorkflowTemplate[] = readonly WorkflowTemplate[]> {
+  /** 根据 ID 判断模板是否存在 */
+  has: (id: TTemplates[number]['id']) => boolean;
+  /** 根据 ID 读取模板定义 */
+  get: (id: TTemplates[number]['id']) => TTemplates[number] | null;
+  /** 生成目录中的全部模板 */
+  list: () => TTemplates;
+}
+/** 插件步骤执行器入参 */
+interface WorkflowPluginStepExecutionOptions<TStep extends WorkflowPluginStep = WorkflowPluginStep, TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /** 当前运行上下文 */
+  context: WorkflowRuntimeContext<TValues>;
+  /** 事件记录器 */
+  record: (event: Omit<WorkflowRunEvent, 'runId' | 'timestamp' | 'workflowId'>) => void;
+  /** 当前插件步骤定义 */
+  step: TStep;
+  /** 可变 values 容器 */
+  values: Partial<TValues>;
+}
+/** 插件步骤处理函数 */
+type WorkflowPluginStepHandler<TStep extends WorkflowPluginStep = WorkflowPluginStep, TValues extends Record<string, unknown> = Record<string, unknown>> = (options: WorkflowPluginStepExecutionOptions<TStep, TValues>) => MaybePromise<unknown>;
+/** 暴露给插件的注册接口 */
+interface WorkflowPluginAPI {
+  /** 注册某个自定义步骤 kind 的执行器 */
+  registerStepHandler: (kind: string, handler: WorkflowPluginStepHandler) => void;
+}
+/** 工作流插件定义 */
+interface WorkflowPlugin {
+  /** 向 context.tools 挂载额外工具 */
+  extendContextTools?: (tools: WorkflowContextTools) => Record<string, unknown> | undefined;
+  /** 插件名称 */
+  name: string;
+  /** 注册自定义步骤处理器 */
+  setup?: (api: WorkflowPluginAPI) => void;
+  /** 包裹命令执行器 */
+  wrapExecutor?: (executor: WorkflowCommandExecutor) => WorkflowCommandExecutor;
+  /** 包裹渲染器 */
+  wrapRenderer?: (renderer: WorkflowRenderer) => WorkflowRenderer;
+}
+/** 单条工作流快照记录 */
+interface WorkflowSnapshotEntry<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /** 快照标签 */
+  label: string;
+  /** 记录语言 */
+  locale: WorkflowLocale;
+  /** 记录时区 */
+  timeZone: WorkflowTimeZone;
+  /** 保存时间 */
+  timestamp: string;
+  /** 整个工作流输入值 */
+  values: Partial<TValues>;
+  /** 工作流 ID */
+  workflowId: string;
+}
+/** 工作流快照查询条件 */
+interface WorkflowSnapshotQuery {
+  /** 返回条数上限 */
+  limit?: number;
+  /** 工作流 ID */
+  workflowId: string;
+}
+/** 历史存储接口 */
+interface WorkflowHistoryStore {
+  /** 查询工作流快照 */
+  listSnapshots: <TValues extends Record<string, unknown>>(query: WorkflowSnapshotQuery) => Promise<WorkflowSnapshotEntry<TValues>[]>;
+  /** 保存工作流快照 */
+  saveSnapshot: <TValues extends Record<string, unknown>>(entry: WorkflowSnapshotEntry<TValues>, options?: {
+    maxSnapshotsPerWorkflow?: number;
+  }) => Promise<void>;
+}
+/** 单次 workflow 的 checkpoint 记录 */
+interface WorkflowCheckpointEntry<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /** 已完成的步骤 ID */
+  completedStepIds: string[];
+  /** 记录语言 */
+  locale: WorkflowLocale;
+  /** 记录时区 */
+  timeZone: WorkflowTimeZone;
+  /** 当前运行结果 */
+  results: Partial<Record<string, unknown>>;
+  /** 最近一次中断原因 */
+  reason?: WorkflowCheckpointReason;
+  /** 运行 ID */
+  runId: string;
+  /** 更新时间 */
+  timestamp: string;
+  /** 当前工作流值 */
+  values: Partial<TValues>;
+  /** 工作流 ID */
+  workflowId: string;
+}
+/** checkpoint 存储接口 */
+interface WorkflowCheckpointStore {
+  /** 清理某个 workflow 的 checkpoint；传入 runId 时仅清理指定运行 */
+  clear: (workflowId: string, runId?: string) => Promise<void>;
+  /** 读取最近一次 checkpoint */
+  getLatest: <TValues extends Record<string, unknown>>(workflowId: string) => Promise<WorkflowCheckpointEntry<TValues> | null>;
+  /** 保存 checkpoint */
+  save: <TValues extends Record<string, unknown>>(entry: WorkflowCheckpointEntry<TValues>) => Promise<void>;
+}
+/** 单次运行中的事件记录 */
+interface WorkflowRunEvent {
+  /** 结构化附加数据 */
+  data?: Record<string, unknown>;
+  /** 事件级别 */
+  level?: WorkflowLogLevel;
+  /** 事件消息 */
+  message?: string;
+  /** 运行 ID */
+  runId: string;
+  /** 关联步骤 ID */
+  stepId?: string;
+  /** 发生时间 */
+  timestamp: string;
+  /** 事件类型 */
+  type: 'box' | 'command-output' | 'checkpoint-cleared' | 'checkpoint-loaded' | 'checkpoint-skipped' | 'checkpoint-saved' | 'message' | 'note' | 'snapshot-loaded' | 'snapshot-saved' | 'step-completed' | 'step-retried' | 'step-skipped' | 'step-started' | 'workflow-cancelled' | 'workflow-completed' | 'workflow-failed' | 'workflow-started';
+  /** 工作流 ID */
+  workflowId: string;
+}
+/** 日志快照格式 */
+type WorkflowLogFormat = 'ecs-ndjson' | 'pretty';
+/** 单个步骤的运行分析信息 */
+interface WorkflowStepAnalysis {
+  /** 实际尝试次数，包含首次执行 */
+  attempts: number;
+  /** 步骤耗时，单位毫秒 */
+  durationMs: number;
+  /** 步骤最终状态 */
+  status: 'completed' | 'skipped';
+}
+/** 一次 workflow 运行的分析摘要 */
+interface WorkflowRunAnalysis {
+  /** 各步骤的分析信息 */
+  steps: Record<string, WorkflowStepAnalysis>;
+  /** 总耗时，单位毫秒 */
+  totalDurationMs: number;
+}
+/** 保存到日志存储的运行快照 */
+interface WorkflowRunSnapshot<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /** 运行分析摘要 */
+  analysis: WorkflowRunAnalysis;
+  /** 结束时间 */
+  endedAt?: string;
+  /** 事件列表 */
+  events: WorkflowRunEvent[];
+  /** 运行语言 */
+  locale: WorkflowLocale;
+  /** 自定义元数据 */
+  meta?: Record<string, unknown>;
+  /** 运行 ID */
+  runId: string;
+  /** 开始时间 */
+  startedAt: string;
+  /** 运行状态 */
+  status: WorkflowRunStatus;
+  /** 运行时区 */
+  timeZone: WorkflowTimeZone;
+  /** 最终 results */
+  results: Partial<Record<string, unknown>>;
+  /** 最终 values */
+  values: Partial<TValues>;
+  /** 工作流 ID */
+  workflowId: string;
+}
+/** 日志存储接口 */
+interface WorkflowLogStore {
+  /** 保存运行快照 */
+  save: <TValues extends Record<string, unknown>>(snapshot: WorkflowRunSnapshot<TValues>, options?: {
+    path?: string;
+  }) => Promise<string>;
+}
+/** 工作流完成后的日志处理策略 */
+interface WorkflowLogCompletionOptions {
+  /** 处理完成后的回调；`confirm` 模式下会带上用户选择结果 */
+  afterComplete?: (context: WorkflowConfirmSaveLogContext<Record<string, unknown>>) => MaybePromise<void>;
+  /**
+   * `confirm` 模式下的默认选择
+   *
+   * @default false
+   */
+  initialValue?: boolean;
+  /** `confirm` 模式下的提示文案 */
+  message?: string;
+  /**
+   * 完成后采用的处理模式
+   *
+   * @default 'confirm'
+   */
+  mode?: 'confirm' | 'save';
+  /** 自定义保存路径 */
+  path?: string;
+}
+/** note 渲染参数 */
+interface WorkflowRendererNoteOptions {
+  /** 每一行的格式化函数 */
+  format?: NoteOptions['format'];
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** box 渲染参数 */
+interface WorkflowRendererBoxOptions {
+  /** 内容对齐方式 */
+  contentAlign?: BoxOptions['contentAlign'];
+  /** 内容内边距 */
+  contentPadding?: BoxOptions['contentPadding'];
+  /** 自定义边框格式化 */
+  formatBorder?: BoxOptions['formatBorder'];
+  /** 是否使用圆角 */
+  rounded?: BoxOptions['rounded'];
+  /** 标题对齐方式 */
+  titleAlign?: BoxOptions['titleAlign'];
+  /** 标题内边距 */
+  titlePadding?: BoxOptions['titlePadding'];
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+  /** 宽度 */
+  width?: BoxOptions['width'];
+}
+/** log 渲染参数 */
+interface WorkflowRendererLogOptions {
+  /** 次级符号 */
+  secondarySymbol?: LogMessageOptions['secondarySymbol'];
+  /** 行间距 */
+  spacing?: LogMessageOptions['spacing'];
+  /** 主符号 */
+  symbol?: LogMessageOptions['symbol'];
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 文本输入渲染参数 */
+interface WorkflowRendererTextOptions {
+  /** 初始值 */
+  initialValue?: string;
+  /** 提示文案 */
+  message: string;
+  /** 占位提示 */
+  placeholder?: string;
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 密码输入渲染参数 */
+interface WorkflowRendererPasswordOptions {
+  /** 校验失败时是否清空输入 */
+  clearOnError?: boolean;
+  /** 提示文案 */
+  message: string;
+  /** 掩码字符 */
+  mask?: string;
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 路径输入渲染参数 */
+interface WorkflowRendererPathOptions {
+  /** 是否要求选择目录 */
+  directory?: boolean;
+  /** 初始值 */
+  initialValue?: string;
+  /** 提示文案 */
+  message: string;
+  /** 根目录 */
+  root?: string;
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 确认输入渲染参数 */
+interface WorkflowRendererConfirmOptions {
+  /** “确认”文案 */
+  active?: string;
+  /** “取消”文案 */
+  inactive?: string;
+  /** 初始值 */
+  initialValue?: boolean;
+  /** 提示文案 */
+  message: string;
+  /** 是否垂直排列选项 */
+  vertical?: boolean;
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 单选输入渲染参数 */
+interface WorkflowRendererSelectOptions<TValue> {
+  /** 初始值 */
+  initialValue?: TValue;
+  /** 最多显示多少项 */
+  maxItems?: number;
+  /** 提示文案 */
+  message: string;
+  /** 选项列表 */
+  options: WorkflowSelectOption<TValue>[];
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 自动补全输入渲染参数 */
+interface WorkflowRendererAutocompleteOptions<TValue> {
+  /** 自定义筛选函数 */
+  filter?: (search: string, option: WorkflowSelectOption<TValue>) => boolean;
+  /** 初始值 */
+  initialValue?: TValue;
+  /** 首次打开时的搜索词 */
+  initialUserInput?: string;
+  /** 最多显示多少项 */
+  maxItems?: number;
+  /** 提示文案 */
+  message: string;
+  /** 选项列表 */
+  options: WorkflowSelectOption<TValue>[];
+  /** 搜索输入占位提示 */
+  placeholder?: string;
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 自动补全多选渲染参数 */
+interface WorkflowRendererAutocompleteMultiSelectOptions<TValue> {
+  /** 自定义筛选函数 */
+  filter?: (search: string, option: WorkflowSelectOption<TValue>) => boolean;
+  /** 初始值 */
+  initialValues?: TValue[];
+  /** 最多显示多少项 */
+  maxItems?: number;
+  /** 提示文案 */
+  message: string;
+  /** 选项列表 */
+  options: WorkflowSelectOption<TValue>[];
+  /** 搜索输入占位提示 */
+  placeholder?: string;
+  /** 是否至少选择一项 */
+  required?: boolean;
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 多选输入渲染参数 */
+interface WorkflowRendererMultiSelectOptions<TValue> {
+  /** 初始光标所在的选项值 */
+  cursorAt?: TValue;
+  /** 初始值 */
+  initialValues?: TValue[];
+  /** 最多显示多少项 */
+  maxItems?: number;
+  /** 提示文案 */
+  message: string;
+  /** 选项列表 */
+  options: WorkflowSelectOption<TValue>[];
+  /** 是否至少选择一项 */
+  required?: boolean;
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 分组多选渲染参数 */
+interface WorkflowRendererGroupMultiSelectOptions<TValue> {
+  /** 初始光标所在的选项值 */
+  cursorAt?: TValue;
+  /** 分组间距 */
+  groupSpacing?: number;
+  /** 初始值 */
+  initialValues?: TValue[];
+  /** 提示文案 */
+  message: string;
+  /** 分组选项列表 */
+  options: Record<string, WorkflowSelectOption<TValue>[]>;
+  /** 是否至少选择一项 */
+  required?: boolean;
+  /** 是否允许直接选中整组 */
+  selectableGroups?: boolean;
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 带快捷键的单选渲染参数 */
+interface WorkflowRendererSelectKeyOptions<TValue extends string> {
+  /** 是否区分大小写 */
+  caseSensitive?: boolean;
+  /** 初始值 */
+  initialValue?: TValue;
+  /** 提示文案 */
+  message: string;
+  /** 选项列表 */
+  options: WorkflowSelectOption<TValue>[];
+  /** 是否显示 Clack guide */
+  withGuide?: CommonOptions['withGuide'];
+}
+/** 命令展示器接口 */
+interface WorkflowCommandPresenter {
+  /** 结束展示 */
+  finish: (code: number) => void;
+  /** 写入 stderr */
+  stderr: (chunk: string) => void;
+  /** 写入 stdout */
+  stdout: (chunk: string) => void;
+}
+/** 命令展示器创建参数 */
+interface WorkflowCommandPresenterOptions {
+  /** 命令参数；仅外部命令步骤会提供 */
+  args?: string[];
+  /** 要执行的命令；仅外部命令步骤会提供 */
+  command?: string;
+  /** 用户声明的完整命令字符串；仅 command 字符串模式会提供 */
+  commandLine?: string;
+  /** 命令工作目录；仅外部命令步骤会提供 */
+  cwd?: string;
+  /** 脚本文件路径；仅脚本文件模式会提供 */
+  scriptFile?: string;
+  /** 当前命令步骤的 task-log 配置 */
+  taskLog?: WorkflowCommandTaskLogOptions;
+  /** 输出呈现模式：`streaming` 代表实时展示，`buffered` 代表先缓存后统一回放 */
+  outputMode: 'buffered' | 'streaming';
+  /** 当前命令步骤使用的渲染器类型 */
+  renderer: 'inherit' | 'quiet' | 'task-log';
+  /** 当前运行 ID */
+  runId: string;
+  /** 当前命令步骤 ID */
+  stepId: string;
+  /** 当前命令步骤来源：`inline` 表示 `run()`，`shell` 表示命令字符串 / 脚本文件 */
+  source: 'inline' | 'shell';
+  /** 展示标题 */
+  title: string;
+  /** 当前工作流 ID */
+  workflowId: string;
+}
+/** 终端渲染器接口 */
+interface WorkflowRenderer {
+  /** 渲染自动补全多选输入 */
+  autocompleteMultiselect?: <TValue>(options: WorkflowRendererAutocompleteMultiSelectOptions<TValue>) => Promise<TValue[] | symbol>;
+  /** 渲染结构化 box */
+  box?: (message?: string, title?: string, options?: WorkflowRendererBoxOptions) => void;
+  /** 在工作流最开始输出 ASCII Banner */
+  banner?: (message: string) => void;
+  /** 渲染取消提示 */
+  cancel?: (message: string) => void;
+  /** 渲染确认输入 */
+  confirm: (options: WorkflowRendererConfirmOptions) => Promise<boolean | symbol>;
+  /** 创建命令输出展示器 */
+  createCommandPresenter?: (options: WorkflowCommandPresenterOptions) => WorkflowCommandPresenter | null;
+  /** 渲染开场信息 */
+  intro?: (message?: string) => void;
+  /** 判断值是否是取消符号 */
+  isCancel?: (value: unknown) => boolean;
+  /** 当前环境是否支持交互 */
+  isInteractive: () => boolean;
+  /** 输出消息 */
+  log: (level: WorkflowLogLevel, message: string | string[], options?: WorkflowRendererLogOptions) => void;
+  /** 渲染分组多选输入 */
+  groupMultiselect?: <TValue>(options: WorkflowRendererGroupMultiSelectOptions<TValue>) => Promise<TValue[] | symbol>;
+  /** 渲染多选输入 */
+  multiselect: <TValue>(options: WorkflowRendererMultiSelectOptions<TValue>) => Promise<TValue[] | symbol>;
+  /** 渲染说明块 */
+  note: (message?: string, title?: string, options?: WorkflowRendererNoteOptions) => void;
+  /** 渲染结束语 */
+  outro?: (message?: string) => void;
+  /** 渲染密码输入 */
+  password?: (options: WorkflowRendererPasswordOptions) => Promise<string | symbol>;
+  /** 渲染路径输入 */
+  path?: (options: WorkflowRendererPathOptions) => Promise<string | symbol>;
+  /** 渲染自动补全输入 */
+  autocomplete: <TValue>(options: WorkflowRendererAutocompleteOptions<TValue>) => Promise<TValue | symbol>;
+  /** 渲染带快捷键的单选输入 */
+  selectKey?: <TValue extends string>(options: WorkflowRendererSelectKeyOptions<TValue>) => Promise<TValue | symbol>;
+  /** 渲染单选输入 */
+  select: <TValue>(options: WorkflowRendererSelectOptions<TValue>) => Promise<TValue | symbol>;
+  /** 渲染文本输入 */
+  text: (options: WorkflowRendererTextOptions) => Promise<string | symbol>;
+}
+/** 命令执行参数 */
+interface WorkflowCommandExecutionOptions {
+  /** 命令参数 */
+  args?: string[];
+  /** 要执行的命令 */
+  command: string;
+  /** 执行目录 */
+  cwd?: string;
+  /** 环境变量 */
+  env?: NodeJS.ProcessEnv;
+  /** stderr 输出回调 */
+  onStderr?: (chunk: string) => void;
+  /** stdout 输出回调 */
+  onStdout?: (chunk: string) => void;
+  /** 输出渲染方式 */
+  renderer?: 'inherit' | 'quiet' | 'task-log';
+  /** stdin 策略 */
+  stdin?: 'ignore' | 'inherit';
+  /** 展示标题 */
+  title?: string;
+}
+/** 内置命令执行器类型 */
+type WorkflowCommandExecutorType = 'node' | 'tinyexec';
+/** 命令执行器接口 */
+interface WorkflowCommandExecutor {
+  /** 执行命令 */
+  execute: (options: WorkflowCommandExecutionOptions) => Promise<WorkflowCommandExecutionResult>;
+}
+/** 直接执行命令时的参数 */
+interface WorkflowRunCommandOptions extends WorkflowCommandExecutionOptions {
+  /** 内置命令执行器类型 */
+  executorType?: WorkflowCommandExecutorType;
+}
+/** 历史存储的全局配置 */
+interface WorkflowKitHistoryOptions {
+  /**
+   * 是否启用历史存储
+   *
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * 历史文件路径
+   *
+   * @default '.clack-kit/history.json'
+   */
+  filePath?: string;
+  /**
+   * workflow 快照最大条数
+   *
+   * @default 20
+   */
+  maxSnapshotsPerWorkflow?: number;
+  /** 自定义历史存储实现 */
+  store?: WorkflowHistoryStore;
+}
+/** 日志存储的全局配置 */
+interface WorkflowKitLogOptions {
+  /**
+   * 日志目录
+   *
+   * @default '.clack-kit/logs'
+   */
+  directory?: string;
+  /**
+   * 是否启用日志
+   *
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * 日志格式
+   *
+   * @default 'pretty'
+   */
+  format?: WorkflowLogFormat;
+  /** 自定义日志存储实现 */
+  store?: WorkflowLogStore;
+}
+/** Checkpoint 存储的全局配置 */
+interface WorkflowKitCheckpointOptions {
+  /**
+   * 是否启用 checkpoint
+   *
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * checkpoint 文件路径
+   *
+   * @default '.clack-kit/checkpoints.json'
+   */
+  filePath?: string;
+  /** 自定义 checkpoint 存储实现 */
+  store?: WorkflowCheckpointStore;
+}
+/** 默认 Clack renderer 的配置 */
+interface WorkflowClackRendererOptions {
+  /** 覆盖交互环境判定逻辑 */
+  interactive?: () => boolean;
+  /** 覆盖底层 @clack/prompts runtime */
+  prompts?: Partial<PromptRuntime>;
+  /** task-log 的全局默认配置 */
+  taskLogOptions?: WorkflowCommandTaskLogOptions;
+}
+/** 国际化接口 */
+interface WorkflowI18n {
+  /** 回退语言 */
+  fallbackLocale: WorkflowLocale;
+  /** 当前语言 */
+  locale: WorkflowLocale;
+  /** 完整 locale 资源目录 */
+  locales: WorkflowLocaleCatalog;
+  /** 用当前语言翻译消息 */
+  t: (key: string, params?: WorkflowMessageValues) => string;
+  /** 用指定语言翻译消息 */
+  translate: (locale: WorkflowLocale, key: string, params?: WorkflowMessageValues) => string;
+}
+/** 创建 kit 的配置 */
+interface CreateWorkflowKitOptions {
+  /**
+   * 是否启用 intro 中的 ASCII 文字
+   *
+   * @default true
+   */
+  asciiArt?: boolean;
+  /**
+   * checkpoint 配置；`true` 表示使用默认路径启用
+   *
+   * @default false
+   */
+  checkpoints?: boolean | WorkflowKitCheckpointOptions;
+  /** 自定义命令执行器 */
+  executor?: WorkflowCommandExecutor;
+  /**
+   * 内置命令执行器类型；仅在未显式传入 `executor` 时生效
+   *
+   * @default 'node'
+   */
+  executorType?: WorkflowCommandExecutorType;
+  /**
+   * 历史配置；`true` 表示使用默认路径启用
+   *
+   * @default false
+   */
+  history?: boolean | WorkflowKitHistoryOptions;
+  /**
+   * 默认语言；不传时会尽量根据系统环境变量自动推断
+   *
+   * @default 自动解析
+   */
+  locale?: WorkflowLocale;
+  /**
+   * 日志配置；`true` 表示使用默认路径启用
+   *
+   * @default false
+   */
+  logs?: boolean | WorkflowKitLogOptions;
+  /** 自定义 locale 资源目录 */
+  locales?: WorkflowLocaleCatalog;
+  /** 运行时插件 */
+  plugins?: readonly WorkflowPlugin[];
+  /**
+   * 项目根目录；command 的相对路径会基于它解析
+   *
+   * @default process.cwd()
+   */
+  projectRoot?: string;
+  /** 默认 Clack renderer 的配置；只在未显式传入 `renderer` 时生效 */
+  rendererOptions?: WorkflowClackRendererOptions;
+  /** 自定义渲染器 */
+  renderer?: WorkflowRenderer;
+  /** 动态解析语言 */
+  resolveLocale?: () => WorkflowLocale;
+  /** 动态解析时区 */
+  resolveTimeZone?: () => WorkflowTimeZone;
+  /**
+   * 用户取消时是否显示取消提示
+   *
+   * @default true
+   */
+  showCancelMessage?: boolean;
+  /** 固定时区 */
+  timeZone?: WorkflowTimeZone;
+}
+/** 单次运行的历史选项 */
+interface WorkflowRunHistoryOptions {
+  /**
+   * 启动时如何处理工作流级历史快照
+   *
+   * @default 'ask'
+   */
+  reuse?: WorkflowHistoryReuseMode;
+  /**
+   * 本次运行完成后是否保存 workflow 快照
+   *
+   * @default true
+   */
+  saveSnapshot?: boolean;
+}
+/** 单次运行的 checkpoint 选项 */
+interface WorkflowRunCheckpointOptions {
+  /**
+   * 本次运行是否保存 checkpoint
+   *
+   * @default true
+   */
+  save?: boolean;
+  /**
+   * 启动时是否恢复未完成的 checkpoint
+   *
+   * @default 交互环境下为 'ask'，否则为 'never'
+   */
+  resume?: WorkflowCheckpointResumeMode;
+}
+/** 单次运行的日志选项 */
+interface WorkflowRunLogOptions<_TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * 是否启用本次运行的日志保存能力
+   *
+   * @default true
+   */
+  enabled?: boolean;
+}
+/** 单次运行的配置 */
+interface WorkflowRunOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /** 本次运行的 checkpoint 行为 */
+  checkpoint?: false | WorkflowRunCheckpointOptions;
+  /** 本次运行的历史行为 */
+  history?: false | WorkflowRunHistoryOptions;
+  /** 用来跳过交互的预填值 */
+  initialValues?: Partial<TValues>;
+  /** 本次运行语言 */
+  locale?: WorkflowLocale;
+  /** 本次运行的日志行为 */
+  logs?: false | WorkflowRunLogOptions<TValues>;
+  /** 需要进入日志快照的元数据 */
+  meta?: Record<string, unknown>;
+  /** 本次运行时区 */
+  timeZone?: WorkflowTimeZone;
+}
+/** 保存日志确认完成后的上下文 */
+interface WorkflowConfirmSaveLogContext<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /** 用户是否确认保存 */
+  confirmed: boolean;
+  /** 最终保存路径；未保存时为 null */
+  path: string | null;
+  /** 当前运行的 results */
+  results: Record<string, unknown>;
+  /** 当前运行的 values */
+  values: TValues;
+  /** 工作流 ID */
+  workflowId: string;
+}
+/** 手动确认保存日志时可传入的配置 */
+interface WorkflowConfirmSaveLogOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /** 用户完成确认后的回调 */
+  afterConfirm?: (context: WorkflowConfirmSaveLogContext<TValues>) => MaybePromise<void>;
+  /** confirm 组件的初始值 */
+  initialValue?: boolean;
+  /** confirm 组件展示的消息 */
+  message?: string;
+  /** 指定保存路径 */
+  path?: string;
+}
+/** 单次运行的结果 */
+interface WorkflowRunResult<TValues extends Record<string, unknown> = Record<string, unknown>> {
+  /** 询问是否保存日志，并允许在结束后执行钩子；禁用日志时返回 null */
+  confirmSaveLog: (options?: WorkflowConfirmSaveLogOptions<TValues>) => Promise<string | null>;
+  /** 与 confirmSaveLog 相同，但用户取消时不会抛错，直接返回 null */
+  confirmSaveLogSafely: (options?: WorkflowConfirmSaveLogOptions<TValues>) => Promise<string | null>;
+  /** 运行事件列表 */
+  events: WorkflowRunEvent[];
+  /** 运行语言 */
+  locale: WorkflowLocale;
+  /** 运行 ID */
+  runId: string;
+  /** 最近一次成功保存的日志路径；未保存时为 `null` */
+  savedLogPath: string | null;
+  /** 直接保存日志；当本次运行禁用日志时返回空字符串 */
+  saveLog: (options?: {
+    path?: string;
+  }) => Promise<string>;
+  /** 获取当前运行快照 */
+  snapshot: () => WorkflowRunSnapshot<TValues>;
+  /** 运行状态 */
+  status: 'completed';
+  /** 最终 results；读取命令步骤或中间步骤产物时优先使用这里 */
+  results: Record<string, unknown>;
+  /** 最终 values */
+  values: TValues;
+  /** 工作流 ID */
+  workflowId: string;
+}
+/** 对外暴露的 kit 接口 */
+interface WorkflowKit {
+  /** checkpoint 存储实例 */
+  checkpointStore: WorkflowCheckpointStore | null;
+  /** 命令执行器 */
+  executor: WorkflowCommandExecutor;
+  /** 历史存储实例 */
+  historyStore: WorkflowHistoryStore | null;
+  /** 日志存储实例 */
+  logStore: WorkflowLogStore | null;
+  /** 渲染器实例 */
+  renderer: WorkflowRenderer;
+  /** 运行一个工作流 */
+  run: (workflow: WorkflowDefinition<readonly WorkflowStepDefinition[]>, options?: WorkflowRunOptions<Record<string, unknown>>) => Promise<WorkflowRunResult<Record<string, unknown>>>;
+  /** 运行一个工作流；当用户取消时返回 null，而不是抛出 PromptCancelledError */
+  runSafely: (workflow: WorkflowDefinition<readonly WorkflowStepDefinition[]>, options?: WorkflowRunOptions<Record<string, unknown>>) => Promise<WorkflowRunResult<Record<string, unknown>> | null>;
+  /** 使用默认语言翻译消息 */
+  t: (key: string, params?: WorkflowMessageValues) => string;
+}
+/** glob 辅助函数的配置 */
+interface WorkflowGlobOptions {
+  /** 是否返回绝对路径 */
+  absolute?: boolean;
+  /** 搜索根目录 */
+  cwd?: string;
+}
+//#endregion
+//#region src/authoring/cli.d.ts
+/** 只要求实现 `option()` 的最小 CLI 接口 */
+interface WorkflowCliOptionRegistrar {
+  /** 注册一条 CLI option */
+  option: (definition: string, description: string, config?: WorkflowCliOptionConfig) => WorkflowCliOptionRegistrar;
+}
+/** 常见 CLI `option()` 第三个参数的最小兼容类型 */
+interface WorkflowCliOptionConfig {
+  /** 与常见 CLI 库一致的默认值配置 */
+  default?: unknown;
+  /** 与常见 CLI 库一致的类型转换配置 */
+  type?: unknown[];
+  /** 透传给具体 CLI 实现的其他字段 */
+  [key: string]: unknown;
+}
+/** 单个字段的 CLI 桥接配置 */
+interface WorkflowCliFieldOptions<TValue = unknown> {
+  /** 覆盖自动生成的说明文案 */
+  description?: string;
+  /** 自定义完整 option 定义，例如 `--plain-progress [plainProgress]` */
+  option?: string;
+  /** 透传给 `cli.option()` 的第三个参数 */
+  optionConfig?: WorkflowCliOptionConfig;
+  /** 当 option 名与 step id 不一致时，指定解析后的 options key */
+  optionKey?: string;
+  /** 自定义值解析函数 */
+  parse?: (value: unknown) => TValue | undefined;
+}
+/** workflow / steps 接入 CLI 时的桥接配置 */
+interface WorkflowCliBridgeOptions {
+  /** 按 step id 定义单字段覆盖规则 */
+  fields?: Record<string, WorkflowCliFieldOptions>;
+}
+/** workflow / steps 映射到 CLI 后的结果 */
+interface WorkflowCliBridge {
+  /** 把步骤映射成 CLI options */
+  apply: <TRegistrar extends WorkflowCliOptionRegistrar>(cli: TRegistrar) => TRegistrar;
+  /** 从解析后的 CLI options 提取 workflow initialValues */
+  getInitialValues: (options: Record<string, unknown>) => Partial<Record<string, unknown>>;
+}
+/** 解析 CLI 里的布尔值 */
+declare function parseWorkflowCliBoolean(value: unknown): boolean | undefined;
+/** 解析 CLI 列表值，默认按逗号分隔 */
+declare function parseWorkflowCliList(value: unknown): string[] | undefined;
+type WorkflowCliBridgeSource = readonly WorkflowStepDefinition[] | {
+  steps: readonly WorkflowStepDefinition[];
+};
+/** 创建 workflow / steps 到 CLI 的 bridge */
+declare function createWorkflowCliBridge(source: WorkflowCliBridgeSource, options?: WorkflowCliBridgeOptions): WorkflowCliBridge;
+//#endregion
+//#region src/authoring/templates.d.ts
+/** 显式声明一个工作流模板，便于复用和类型推导 */
+declare function defineWorkflowTemplate<const TTemplate extends WorkflowTemplate>(template: TTemplate): TTemplate;
+/** 创建一个按模板 ID 检索的目录 */
+declare function createWorkflowTemplateCatalog<const TTemplates extends readonly WorkflowTemplate[]>(templates: TTemplates): WorkflowTemplateCatalog<TTemplates>;
+//#endregion
+//#region src/authoring/workflow-types.d.ts
+/** 供 authoring DSL 复用的基础步骤字段 */
+interface WorkflowStepConfigBase<TKey extends string, TValue> {
+  /** 步骤在 values 中对应的 key */
+  id: TKey;
+  /** 为交互输入提供默认值；不同于运行参数里的 `initialValues` */
+  defaultValue?: WorkflowValueResolver<TValue | undefined>;
+  /** 控制步骤是否执行 */
+  when?: WorkflowPredicate<Record<string, unknown>>;
+}
+/** 选择类步骤在 authoring 层共享的选项结构 */
+type WorkflowChoiceOptions<TValue> = WorkflowValueResolver<readonly TValue[]> | WorkflowValueResolver<readonly WorkflowSelectOption<TValue>[]>;
+/** 分组多选在 authoring 层共享的分组选项结构 */
+type WorkflowGroupedChoiceOptions<TValue> = WorkflowValueResolver<Record<string, readonly TValue[] | readonly WorkflowSelectOption<TValue>[]>>;
+/** `defineSteps()` 支持的文本步骤 DSL */
+interface WorkflowTextStepConfig<TKey extends string> extends WorkflowStepConfigBase<TKey, string> {
+  /** 提示文案 */
+  message: WorkflowValueResolver<string>;
+  /** 占位提示 */
+  placeholder?: WorkflowValueResolver<string | undefined>;
+  /** 是否必填；当为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 声明式步骤类型 */
+  type: 'text';
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<string>;
+}
+/** `defineSteps()` 支持的单选步骤 DSL */
+interface WorkflowSelectStepConfig<TKey extends string, TValue> extends WorkflowStepConfigBase<TKey, TValue> {
+  /** 提示文案 */
+  message: WorkflowValueResolver<string>;
+  /** 可选项列表 */
+  options: WorkflowChoiceOptions<TValue>;
+  /** 声明式步骤类型 */
+  type: 'select';
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue>;
+}
+/** `defineSteps()` 支持的自动补全步骤 DSL */
+interface WorkflowAutocompleteStepConfig<TKey extends string, TValue> extends WorkflowStepConfigBase<TKey, TValue> {
+  /** 自定义筛选函数 */
+  filter?: (search: string, option: WorkflowSelectOption<TValue>) => boolean;
+  /** 首次打开时的搜索词 */
+  initialUserInput?: WorkflowValueResolver<string | undefined>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<string>;
+  /** 最多显示多少项 */
+  maxItems?: WorkflowValueResolver<number | undefined>;
+  /** 可搜索选项列表 */
+  options: WorkflowChoiceOptions<TValue>;
+  /** 搜索输入占位提示 */
+  placeholder?: WorkflowValueResolver<string | undefined>;
+  /** 声明式步骤类型 */
+  type: 'autocomplete';
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+}
+/** `defineSteps()` 支持的多选步骤 DSL */
+interface WorkflowMultiSelectStepConfig<TKey extends string, TValue> extends WorkflowStepConfigBase<TKey, TValue[]> {
+  /** 初始光标所在的选项值 */
+  cursorAt?: WorkflowValueResolver<TValue | undefined>;
+  /** 最多显示多少项 */
+  maxItems?: WorkflowValueResolver<number | undefined>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<string>;
+  /** 可选项列表 */
+  options: WorkflowChoiceOptions<TValue>;
+  /** 是否至少要选中一项；为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 声明式步骤类型 */
+  type: 'multiselect';
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue[]>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+}
+/** `defineSteps()` 支持的自动补全多选步骤 DSL */
+interface WorkflowAutocompleteMultiSelectStepConfig<TKey extends string, TValue> extends WorkflowStepConfigBase<TKey, TValue[]> {
+  /** 自定义筛选函数 */
+  filter?: (search: string, option: WorkflowSelectOption<TValue>) => boolean;
+  /** 最多显示多少项 */
+  maxItems?: WorkflowValueResolver<number | undefined>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<string>;
+  /** 可搜索选项列表 */
+  options: WorkflowChoiceOptions<TValue>;
+  /** 搜索输入占位提示 */
+  placeholder?: WorkflowValueResolver<string | undefined>;
+  /** 是否至少要选中一项；为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 声明式步骤类型 */
+  type: 'autocompleteMultiselect';
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue[]>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+}
+/** `defineSteps()` 支持的分组多选步骤 DSL */
+interface WorkflowGroupMultiSelectStepConfig<TKey extends string, TValue> extends WorkflowStepConfigBase<TKey, TValue[]> {
+  /** 初始光标所在的选项值 */
+  cursorAt?: WorkflowValueResolver<TValue | undefined>;
+  /** 分组间距 */
+  groupSpacing?: WorkflowValueResolver<number | undefined>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<string>;
+  /** 分组选项列表 */
+  options: WorkflowGroupedChoiceOptions<TValue>;
+  /** 是否至少要选中一项；为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 是否允许直接选中整组 */
+  selectableGroups?: WorkflowValueResolver<boolean | undefined>;
+  /** 声明式步骤类型 */
+  type: 'groupMultiselect';
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue[]>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+}
+/** `defineSteps()` 支持的确认步骤 DSL */
+interface WorkflowConfirmStepConfig<TKey extends string> extends WorkflowStepConfigBase<TKey, boolean> {
+  /** “确认”文案 */
+  active?: WorkflowValueResolver<string | undefined>;
+  /** “取消”文案 */
+  inactive?: WorkflowValueResolver<string | undefined>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<string>;
+  /** 声明式步骤类型 */
+  type: 'confirm';
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<boolean>;
+  /** 是否垂直排列选项 */
+  vertical?: WorkflowValueResolver<boolean | undefined>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+}
+/** `defineSteps()` 支持的密码步骤 DSL */
+interface WorkflowPasswordStepConfig<TKey extends string> extends WorkflowStepConfigBase<TKey, string> {
+  /** 校验失败时是否清空输入 */
+  clearOnError?: WorkflowValueResolver<boolean | undefined>;
+  /** 掩码字符 */
+  mask?: WorkflowValueResolver<string | undefined>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<string>;
+  /** 是否必填；当为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 声明式步骤类型 */
+  type: 'password';
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<string>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+}
+/** `defineSteps()` 支持的路径步骤 DSL */
+interface WorkflowPathStepConfig<TKey extends string> extends WorkflowStepConfigBase<TKey, string> {
+  /** 是否要求选择目录 */
+  directory?: WorkflowValueResolver<boolean | undefined>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<string>;
+  /** 是否必填；当为 `true` 时默认文案为 `<Key> is required` */
+  required?: boolean | string;
+  /** 根目录 */
+  root?: WorkflowValueResolver<string | undefined>;
+  /** 声明式步骤类型 */
+  type: 'path';
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<string>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+}
+/** `defineSteps()` 支持的快捷键单选步骤 DSL */
+interface WorkflowSelectKeyStepConfig<TKey extends string, TValue extends string> extends WorkflowStepConfigBase<TKey, TValue> {
+  /** 是否区分大小写 */
+  caseSensitive?: WorkflowValueResolver<boolean | undefined>;
+  /** 提示文案 */
+  message: WorkflowValueResolver<string>;
+  /** 可选项列表 */
+  options: WorkflowChoiceOptions<TValue>;
+  /** 声明式步骤类型 */
+  type: 'selectKey';
+  /** 自定义校验函数 */
+  validate?: WorkflowValidator<TValue>;
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+}
+/** `defineSteps()` 支持的外部命令步骤 DSL */
+interface WorkflowExternalCommandStepConfig<TKey extends string, TResult = unknown> extends WorkflowStepConfigBase<TKey, WorkflowCommandResult<TResult>> {
+  /** 非零退出码是否允许继续工作流 */
+  allowFailure?: boolean;
+  /** 要执行的完整命令字符串；支持直接传字符串，也支持用函数动态返回 */
+  command: WorkflowValueResolver<string>;
+  /** 命令执行目录 */
+  cwd?: WorkflowValueResolver<string | undefined>;
+  /** 命令环境变量 */
+  env?: WorkflowValueResolver<NodeJS.ProcessEnv | undefined>;
+  /** 并行分组；同层连续且 group 相同的 command 步骤会并行执行 */
+  parallel?: string;
+  /** 将执行记录映射成最终写入 results 的值 */
+  result?: WorkflowCommandResultResolver<TResult>;
+  /** 输出渲染方式 */
+  renderer?: 'inherit' | 'quiet' | 'task-log';
+  /** shell 解释器配置；未提供时按平台默认值执行 `command` */
+  shell?: {
+    args?: WorkflowValueResolver<string[] | undefined>;
+    command?: WorkflowValueResolver<string | undefined>;
+  };
+  /** 当前命令步骤的 task-log 配置 */
+  taskLog?: {
+    limit?: number;
+    retainLog?: boolean;
+  };
+  /** 命令失败后的重试策略 */
+  retry?: boolean | WorkflowCommandRetryOptions;
+  /** stdin 处理策略 */
+  stdin?: 'ignore' | 'inherit';
+  /** 展示标题 */
+  title?: WorkflowValueResolver<string | undefined>;
+  /** 声明式步骤类型 */
+  type: 'command';
+}
+/** `defineSteps()` 支持的 note 步骤 DSL */
+interface WorkflowNoteStepConfig<TKey extends string> extends WorkflowStepConfigBase<TKey, undefined> {
+  /** 每一行的格式化函数 */
+  format?: (line: string) => string;
+  /** 提示内容 */
+  message?: WorkflowValueResolver<string | undefined>;
+  /** 标题 */
+  title?: WorkflowValueResolver<string | undefined>;
+  /** 声明式步骤类型 */
+  type: 'note';
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+}
+/** `defineSteps()` 支持的 box 步骤 DSL */
+interface WorkflowBoxStepConfig<TKey extends string> extends WorkflowStepConfigBase<TKey, undefined> {
+  /** 内容对齐方式 */
+  contentAlign?: WorkflowValueResolver<'left' | 'center' | 'right' | undefined>;
+  /** 内容内边距 */
+  contentPadding?: WorkflowValueResolver<number | undefined>;
+  /** 自定义边框格式化 */
+  formatBorder?: (text: string) => string;
+  /** 提示内容 */
+  message?: WorkflowValueResolver<string | undefined>;
+  /** 是否使用圆角 */
+  rounded?: WorkflowValueResolver<boolean | undefined>;
+  /** 标题对齐方式 */
+  titleAlign?: WorkflowValueResolver<'left' | 'center' | 'right' | undefined>;
+  /** 标题内边距 */
+  titlePadding?: WorkflowValueResolver<number | undefined>;
+  /** 标题 */
+  title?: WorkflowValueResolver<string | undefined>;
+  /** 声明式步骤类型 */
+  type: 'box';
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+  /** 宽度 */
+  width?: WorkflowValueResolver<number | 'auto' | undefined>;
+}
+/** `defineSteps()` 支持的 log 步骤 DSL */
+interface WorkflowLogStepConfig<TKey extends string> extends WorkflowStepConfigBase<TKey, undefined> {
+  /** 日志级别 */
+  level?: WorkflowValueResolver<WorkflowLogLevel | undefined>;
+  /** 提示内容 */
+  message?: WorkflowValueResolver<string | string[] | undefined>;
+  /** 次级符号 */
+  secondarySymbol?: WorkflowValueResolver<string | undefined>;
+  /** 行间距 */
+  spacing?: WorkflowValueResolver<number | undefined>;
+  /** 主符号 */
+  symbol?: WorkflowValueResolver<string | undefined>;
+  /** 声明式步骤类型 */
+  type: 'log';
+  /** 是否显示 Clack guide */
+  withGuide?: WorkflowValueResolver<boolean | undefined>;
+}
+/** `defineSteps()` 支持的内联命令步骤 DSL */
+interface WorkflowInlineCommandStepConfig<TKey extends string, TResult = unknown> extends WorkflowStepConfigBase<TKey, WorkflowCommandResult<TResult>> {
+  /** 非零退出码是否允许继续工作流 */
+  allowFailure?: boolean;
+  /** 并行分组；同层连续且 group 相同的 command 步骤会并行执行 */
+  parallel?: string;
+  /** 输出渲染方式 */
+  renderer?: 'inherit' | 'quiet' | 'task-log';
+  /** 当前命令步骤的 task-log 配置 */
+  taskLog?: {
+    limit?: number;
+    retainLog?: boolean;
+  };
+  /** 命令失败后的重试策略 */
+  retry?: boolean | WorkflowCommandRetryOptions;
+  /** 内联异步任务 */
+  run: WorkflowCommandHandler<Record<string, unknown>, TResult>;
+  /** 展示标题 */
+  title?: WorkflowValueResolver<string | undefined>;
+  /** 声明式步骤类型 */
+  type: 'command';
+}
+/** `defineSteps()` 支持的脚本文件步骤 DSL */
+interface WorkflowScriptFileCommandStepConfig<TKey extends string, TResult = unknown> extends WorkflowStepConfigBase<TKey, WorkflowCommandResult<TResult>> {
+  /** 非零退出码是否允许继续工作流 */
+  allowFailure?: boolean;
+  /** 命令执行目录 */
+  cwd?: WorkflowValueResolver<string | undefined>;
+  /** 命令环境变量 */
+  env?: WorkflowValueResolver<NodeJS.ProcessEnv | undefined>;
+  /** 并行分组；同层连续且 group 相同的 command 步骤会并行执行 */
+  parallel?: string;
+  /** 将执行记录映射成最终写入 results 的值 */
+  result?: WorkflowCommandResultResolver<TResult>;
+  /** 输出渲染方式 */
+  renderer?: 'inherit' | 'quiet' | 'task-log';
+  /** shell 解释器配置；未提供时优先根据 shebang / 扩展名自动检测 */
+  shell?: {
+    args?: WorkflowValueResolver<string[] | undefined>;
+    command?: WorkflowValueResolver<string | undefined>;
+  };
+  /** 要执行的脚本文件路径；支持直接传字符串，也支持用函数动态返回 */
+  scriptFile: WorkflowValueResolver<string>;
+  /** 当前命令步骤的 task-log 配置 */
+  taskLog?: {
+    limit?: number;
+    retainLog?: boolean;
+  };
+  /** 命令失败后的重试策略 */
+  retry?: boolean | WorkflowCommandRetryOptions;
+  /** stdin 处理策略 */
+  stdin?: 'ignore' | 'inherit';
+  /** 展示标题 */
+  title?: WorkflowValueResolver<string | undefined>;
+  /** 声明式步骤类型 */
+  type: 'command';
+}
+/** `defineSteps()` 支持的命令步骤 DSL */
+type WorkflowCommandStepConfig<TKey extends string, TResult = unknown> = WorkflowExternalCommandStepConfig<TKey, TResult> | WorkflowScriptFileCommandStepConfig<TKey, TResult> | WorkflowInlineCommandStepConfig<TKey, TResult>;
+/** typed helper 入参会由方法名隐式确定 `type`，因此无需重复书写 */
+type WorkflowStepConfigInput<TStep> = TStep extends {
+  type: string;
+} ? Omit<TStep, 'type'> : TStep;
+/** `defineSteps()` 支持的步骤类型字符串 */
+type WorkflowStepType = 'autocompleteMultiselect' | 'autocomplete' | 'box' | 'command' | 'confirm' | 'groupMultiselect' | 'log' | 'multiselect' | 'note' | 'password' | 'path' | 'select' | 'selectKey' | 'text';
+/** 按 `type` 精确提取某一类声明式步骤配置 */
+type WorkflowStepConfigByType<TType extends WorkflowStepType> = TType extends 'text' ? WorkflowTextStepConfig<string> : TType extends 'select' ? WorkflowSelectStepConfig<string, any> : TType extends 'autocomplete' ? WorkflowAutocompleteStepConfig<string, any> : TType extends 'multiselect' ? WorkflowMultiSelectStepConfig<string, any> : TType extends 'autocompleteMultiselect' ? WorkflowAutocompleteMultiSelectStepConfig<string, any> : TType extends 'groupMultiselect' ? WorkflowGroupMultiSelectStepConfig<string, any> : TType extends 'confirm' ? WorkflowConfirmStepConfig<string> : TType extends 'note' ? WorkflowNoteStepConfig<string> : TType extends 'box' ? WorkflowBoxStepConfig<string> : TType extends 'log' ? WorkflowLogStepConfig<string> : TType extends 'password' ? WorkflowPasswordStepConfig<string> : TType extends 'path' ? WorkflowPathStepConfig<string> : TType extends 'selectKey' ? WorkflowSelectKeyStepConfig<string, string> : TType extends 'command' ? WorkflowCommandStepConfig<string, unknown> : never;
+/** `defineSteps()` 支持的声明式步骤联合类型 */
+type WorkflowStepConfigDefinition = WorkflowStepConfigByType<WorkflowStepType>;
+/** `defineSteps()` 同时接受标准化步骤和声明式 DSL */
+type WorkflowStepAuthoringDefinition = WorkflowStepConfigDefinition | WorkflowStepDefinition;
+/** `defineWorkflow()` 使用的轻量 authoring 结构 */
+interface WorkflowAuthoringDefinition<TSteps extends readonly WorkflowStepDefinition[] = readonly WorkflowStepDefinition[]> {
+  /** ASCII 文字内容 */
+  asciiArt?: WorkflowAsciiArtDefinition<Record<string, unknown>>;
+  /** 工作流唯一 ID */
+  id: string;
+  /** 开场信息 */
+  intro?: WorkflowIntroDefinition<Record<string, unknown>>;
+  /** 工作流完成回调 */
+  onComplete?: (context: WorkflowRuntimeContext<Record<string, unknown>, Record<string, unknown>>) => MaybePromise<void>;
+  /** 工作流开始回调 */
+  onStart?: (context: WorkflowRuntimeContext<Record<string, unknown>, Record<string, unknown>>) => MaybePromise<void>;
+  /** 工作流级日志策略 */
+  log?: WorkflowLogOptions;
+  /** 结束语 */
+  outro?: WorkflowValueResolver<string | undefined, Record<string, unknown>>;
+  /** 历史快照配置 */
+  snapshot?: WorkflowSnapshotOptions<Record<string, unknown>>;
+  /** 默认 summary 输出配置 */
+  summary?: false | WorkflowSummaryOptions<Record<string, unknown>>;
+  /** 工作流步骤列表 */
+  steps: TSteps;
+  /** `intro` 的简写标题 */
+  title?: WorkflowValueResolver<string | undefined, Record<string, unknown>>;
+}
+//#endregion
+//#region src/authoring/step-builders.d.ts
+/** 创建文本输入步骤 */
+declare function createTextStep<TKey extends string>(key: TKey, step: Omit<WorkflowTextStep<TKey>, 'id' | 'kind'>): WorkflowTextStep<TKey>;
+/** 创建单选步骤 */
+declare function createSelectStep<TKey extends string, TValue>(key: TKey, step: Omit<WorkflowSelectStep<TKey, TValue>, 'id' | 'kind'>): WorkflowSelectStep<TKey, TValue>;
+/** 创建自动补全步骤 */
+declare function createAutocompleteStep<TKey extends string, TValue>(key: TKey, step: Omit<WorkflowAutocompleteStep<TKey, TValue>, 'id' | 'kind'>): WorkflowAutocompleteStep<TKey, TValue>;
+/** 创建多选步骤 */
+declare function createMultiSelectStep<TKey extends string, TValue>(key: TKey, step: Omit<WorkflowMultiSelectStep<TKey, TValue>, 'id' | 'kind'>): WorkflowMultiSelectStep<TKey, TValue>;
+/** 创建自动补全多选步骤 */
+declare function createAutocompleteMultiSelectStep<TKey extends string, TValue>(key: TKey, step: Omit<WorkflowAutocompleteMultiSelectStep<TKey, TValue>, 'id' | 'kind'>): WorkflowAutocompleteMultiSelectStep<TKey, TValue>;
+/** 创建分组多选步骤 */
+declare function createGroupMultiSelectStep<TKey extends string, TValue>(key: TKey, step: Omit<WorkflowGroupMultiSelectStep<TKey, TValue>, 'id' | 'kind'>): WorkflowGroupMultiSelectStep<TKey, TValue>;
+/** 创建确认步骤 */
+declare function createConfirmStep<TKey extends string>(key: TKey, step: Omit<WorkflowConfirmStep<TKey>, 'id' | 'kind'>): WorkflowConfirmStep<TKey>;
+/** 创建 note 步骤 */
+declare function createNoteStep<TKey extends string>(key: TKey, step: Omit<WorkflowNoteStep<TKey>, 'id' | 'kind'>): WorkflowNoteStep<TKey>;
+/** 创建 box 步骤 */
+declare function createBoxStep<TKey extends string>(key: TKey, step: Omit<WorkflowBoxStep<TKey>, 'id' | 'kind'>): WorkflowBoxStep<TKey>;
+/** 创建 log 步骤 */
+declare function createLogStep<TKey extends string>(key: TKey, step: Omit<WorkflowLogStep<TKey>, 'id' | 'kind'>): WorkflowLogStep<TKey>;
+/** 创建密码输入步骤 */
+declare function createPasswordStep<TKey extends string>(key: TKey, step: Omit<WorkflowPasswordStep<TKey>, 'id' | 'kind'>): WorkflowPasswordStep<TKey>;
+/** 创建路径输入步骤 */
+declare function createPathStep<TKey extends string>(key: TKey, step: Omit<WorkflowPathStep<TKey>, 'id' | 'kind'>): WorkflowPathStep<TKey>;
+/** 创建带快捷键的单选步骤 */
+declare function createSelectKeyStep<TKey extends string, TValue extends string>(key: TKey, step: Omit<WorkflowSelectKeyStep<TKey, TValue>, 'id' | 'kind'>): WorkflowSelectKeyStep<TKey, TValue>;
+/** 创建命令步骤 */
+declare function createCommandStep<TKey extends string, TResult = unknown>(key: TKey, step: Omit<WorkflowExternalCommandStep<TKey, TResult>, 'id' | 'kind'> | Omit<WorkflowScriptFileCommandStep<TKey, TResult>, 'id' | 'kind'> | Omit<WorkflowInlineCommandStep<TKey, TResult>, 'id' | 'kind'>): WorkflowCommandStep<TKey, TResult>;
+/** `defineStep` 的可调用接口，同时暴露按类型分发的方法 */
+interface DefineStep {
+  /** 显式定义单个 DSL 步骤 */
+  <const TStep extends WorkflowStepConfigDefinition>(step: TStep): WorkflowStepDefinition;
+  /** 透传已经标准化过的步骤 */
+  <const TStep extends WorkflowStepDefinition>(step: TStep): WorkflowStepDefinition;
+  /** 定义自动补全步骤 */
+  autocomplete: <TKey extends string, TValue>(step: WorkflowStepConfigInput<WorkflowAutocompleteStepConfig<TKey, TValue>>) => WorkflowAutocompleteStep<TKey, TValue>;
+  /** 定义自动补全多选步骤 */
+  autocompleteMultiselect: <TKey extends string, TValue>(step: WorkflowStepConfigInput<WorkflowAutocompleteMultiSelectStepConfig<TKey, TValue>>) => WorkflowAutocompleteMultiSelectStep<TKey, TValue>;
+  /** 定义 box 步骤 */
+  box: <TKey extends string>(step: WorkflowStepConfigInput<WorkflowBoxStepConfig<TKey>>) => WorkflowBoxStep<TKey>;
+  /** 定义命令步骤 */
+  command: <TKey extends string, TResult = unknown>(step: WorkflowStepConfigInput<WorkflowCommandStepConfig<TKey, TResult>>) => WorkflowCommandStep<TKey, TResult>;
+  /** 定义确认步骤 */
+  confirm: <TKey extends string>(step: WorkflowStepConfigInput<WorkflowConfirmStepConfig<TKey>>) => WorkflowConfirmStep<TKey>;
+  /** 定义分组多选步骤 */
+  groupMultiselect: <TKey extends string, TValue>(step: WorkflowStepConfigInput<WorkflowGroupMultiSelectStepConfig<TKey, TValue>>) => WorkflowGroupMultiSelectStep<TKey, TValue>;
+  /** 定义 log 步骤 */
+  log: <TKey extends string>(step: WorkflowStepConfigInput<WorkflowLogStepConfig<TKey>>) => WorkflowLogStep<TKey>;
+  /** 定义多选步骤 */
+  multiselect: <TKey extends string, TValue>(step: WorkflowStepConfigInput<WorkflowMultiSelectStepConfig<TKey, TValue>>) => WorkflowMultiSelectStep<TKey, TValue>;
+  /** 定义 note 步骤 */
+  note: <TKey extends string>(step: WorkflowStepConfigInput<WorkflowNoteStepConfig<TKey>>) => WorkflowNoteStep<TKey>;
+  /** 定义密码步骤 */
+  password: <TKey extends string>(step: WorkflowStepConfigInput<WorkflowPasswordStepConfig<TKey>>) => WorkflowPasswordStep<TKey>;
+  /** 定义路径步骤 */
+  path: <TKey extends string>(step: WorkflowStepConfigInput<WorkflowPathStepConfig<TKey>>) => WorkflowPathStep<TKey>;
+  /** 定义快捷键单选步骤 */
+  selectKey: <TKey extends string, TValue extends string>(step: WorkflowStepConfigInput<WorkflowSelectKeyStepConfig<TKey, TValue>>) => WorkflowSelectKeyStep<TKey, TValue>;
+  /** 定义单选步骤 */
+  select: <TKey extends string, TValue>(step: WorkflowStepConfigInput<WorkflowSelectStepConfig<TKey, TValue>>) => WorkflowSelectStep<TKey, TValue>;
+  /** 定义文本步骤 */
+  text: <TKey extends string>(step: WorkflowStepConfigInput<WorkflowTextStepConfig<TKey>>) => WorkflowTextStep<TKey>;
+}
+/** 显式定义单个步骤；当编辑器对数组字面量提示不稳定时可用它拿到精确类型 */
+declare const defineStep: DefineStep;
+/** 显式定义纯 DSL 步骤数组，优先保留编辑器字段提示 */
+declare function defineSteps<const TSteps extends readonly WorkflowStepConfigDefinition[]>(steps: TSteps): readonly WorkflowStepDefinition[];
+/** 显式定义纯标准化步骤数组 */
+declare function defineSteps<const TSteps extends readonly WorkflowStepDefinition[]>(steps: TSteps): readonly WorkflowStepDefinition[];
+/** 显式定义混合步骤数组；同时接受标准化步骤和声明式 DSL */
+declare function defineSteps<const TSteps extends readonly WorkflowStepAuthoringDefinition[]>(steps: TSteps): readonly WorkflowStepDefinition[];
+//#endregion
+//#region src/authoring/workflow.d.ts
+/** 定义一个工作流，并保留步骤元数据给后续类型推导使用 */
+declare function defineWorkflow(workflow: WorkflowAuthoringDefinition): WorkflowDefinition<readonly WorkflowStepDefinition[]>;
+//#endregion
+//#region src/runtime/command.d.ts
+/** 创建默认的 Node 子进程命令执行器 */
+declare function createNodeCommandExecutor(): WorkflowCommandExecutor;
+/** 创建基于 tinyexec 的命令执行器 */
+declare function createTinyexecCommandExecutor(): WorkflowCommandExecutor;
+/** 直接执行一条外部命令，适合作为底层工具函数单独使用 */
+declare function runCommand(options: WorkflowRunCommandOptions): Promise<WorkflowCommandExecutionResult>;
+/** 根据类型选择内置命令执行器 */
+declare function createCommandExecutor(executorType?: WorkflowCommandExecutorType): WorkflowCommandExecutor;
+//#endregion
+//#region src/runtime/kit.d.ts
+/** 创建一个以 workflow 为中心的 clack-kit 实例 */
+declare function createWorkflowKit(options?: CreateWorkflowKitOptions): WorkflowKit;
+/** 不显式创建 kit，直接运行 workflow */
+declare function runWorkflow(workflow: WorkflowDefinition<readonly WorkflowStepDefinition[]>, options?: WorkflowRunOptions<Record<string, unknown>>): Promise<WorkflowRunResult<Record<string, unknown>>>;
+/** 不显式创建 kit，安全运行 workflow；用户取消时返回 null */
+declare function runWorkflowSafely(workflow: WorkflowDefinition<readonly WorkflowStepDefinition[]>, options?: WorkflowRunOptions<Record<string, unknown>>): Promise<WorkflowRunResult<Record<string, unknown>> | null>;
+//#endregion
+//#region src/runtime/renderer.d.ts
+/** Clack 渲染器的创建选项 */
+interface CreateClackRendererOptions extends WorkflowClackRendererOptions {}
+/** 创建默认的 Clack 渲染器适配器 */
+declare function createClackRenderer(options?: CreateClackRendererOptions): WorkflowRenderer;
+//#endregion
+//#region src/shared/errors.d.ts
+/** 用户主动取消交互时抛出的错误 */
+declare class PromptCancelledError extends Error {
+  readonly key?: string;
+  readonly scope?: string;
+  constructor(message?: string, options?: {
+    key?: string;
+    scope?: string;
+  });
+}
+/** 标识工作流执行过程中出现的业务级失败 */
+declare class WorkflowExecutionError extends Error {
+  readonly stepId: string;
+  readonly workflowId: string;
+  constructor(message: string, options: {
+    cause?: unknown;
+    stepId: string;
+    workflowId: string;
+  });
+}
+/** 判断未知错误是否来自用户取消 */
+declare function isPromptCancelledError(error: unknown): error is PromptCancelledError;
+/** 判断未知错误是否是工作流执行错误 */
+declare function isWorkflowExecutionError(error: unknown): error is WorkflowExecutionError;
+//#endregion
+//#region src/shared/files.d.ts
+/** 读取文本文件 */
+declare function readTextFile(filePath: string): Promise<string>;
+/** 写入文本文件，并自动创建父目录 */
+declare function writeTextFile(filePath: string, content: string): Promise<void>;
+/** 读取 JSON 文件并解析成对象 */
+declare function readJson<TValue = unknown>(filePath: string): Promise<TValue>;
+/** 写入 JSON 文件，并使用稳定缩进与换行 */
+declare function writeJson(filePath: string, value: unknown): Promise<void>;
+/** 读取、更新并回写 JSON 文件 */
+declare function patchJson<TValue extends Record<string, unknown>>(filePath: string, updater: (current: TValue) => Promise<TValue> | TValue): Promise<TValue>;
+/** 基于 `fast-glob` 提供高性能 glob helper */
+declare function globFiles(pattern: string, options?: WorkflowGlobOptions): Promise<string[]>;
+//#endregion
+//#region src/shared/helpers.d.ts
+type PromptValidator<TValue> = (value: TValue | undefined) => Error | string | undefined;
+/** 按顺序运行多个校验函数，命中第一个错误后立即返回 */
+declare function composeValidators<TValue>(...validators: Array<PromptValidator<TValue> | undefined>): PromptValidator<TValue>;
+/** 生成一个“非空字符串”校验器 */
+declare function createRequiredTextValidator(message?: string): PromptValidator<string>;
+/** 把工作流里的任意值转成便于展示和记录的文本 */
+declare function formatPromptValue(value: unknown): string;
+/** 把 `project-name` 这类 key 转成人看得懂的标题 */
+declare function formatFieldLabel(key: string): string;
+/** 把任意字符串整理成更适合文件系统的文件名 */
+declare function sanitizeFileName(value: string): string;
+/** 休眠指定毫秒数 */
+declare function sleep(milliseconds: number): Promise<void>;
+/** 用 figlet 生成 ASCII Art；多行输入会直接视为现成内容返回 */
+declare function renderAsciiArt(value: string): string;
+/** 把原始值列表映射成选择组件能直接用的 options */
+declare function toOptions<TValue>(values: readonly TValue[], mapper?: (value: TValue, index: number) => {
+  disabled?: boolean;
+  hint?: string;
+  label?: string;
+  value?: TValue;
+}): Array<{
+  disabled?: boolean;
+  hint?: string;
+  label?: string;
+  value: TValue;
+}>;
+//#endregion
+//#region node_modules/i18next/typescript/helpers.d.ts
+// Types
+type $Dictionary<T = unknown> = {
+  [key: string]: T;
+};
+type $MergeBy<T, K> = Omit<T, keyof K> & K;
+type $PreservedValue<Value, Fallback> = [Value] extends [never] ? Fallback : Value;
+//#endregion
+//#region node_modules/i18next/typescript/options.d.ts
+/**
+ * This interface can be augmented by users to add types to `i18next` default TypeOptions.
+ *
+ * Usage:
+ * ```ts
+ * // i18next.d.ts
+ * import 'i18next';
+ * declare module 'i18next' {
+ *   interface CustomTypeOptions {
+ *     defaultNS: 'custom';
+ *     returnNull: false;
+ *     returnObjects: false;
+ *     nsSeparator: ':';
+ *     keySeparator: '.';
+ *     compatibilityJSON: 'v4';
+ *     allowObjectInHTMLChildren: false;
+ *     resources: {
+ *       custom: {
+ *         foo: 'foo';
+ *       };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+interface CustomTypeOptions {}
+/**
+ * This interface can be augmented by users to add types to `i18next` default PluginOptions.
+ */
+interface CustomPluginOptions {}
+type TypeOptions = $MergeBy<{
+  /** @see {InitOptions.returnNull} */returnNull: false; /** @see {InitOptions.returnEmptyString} */
+  returnEmptyString: true; /** @see {InitOptions.returnObjects} */
+  returnObjects: false; /** @see {InitOptions.keySeparator} */
+  keySeparator: '.'; /** @see {InitOptions.nsSeparator} */
+  nsSeparator: ':'; /** @see {InitOptions.pluralSeparator} */
+  pluralSeparator: '_'; /** @see {InitOptions.contextSeparator} */
+  contextSeparator: '_'; /** @see {InitOptions.defaultNS} */
+  defaultNS: 'translation'; /** @see {InitOptions.fallbackNS} */
+  fallbackNS: false; /** @see {InitOptions.compatibilityJSON} */
+  compatibilityJSON: 'v4'; /** @see {InitOptions.resources} */
+  resources: object;
+  /**
+   * Flag that allows HTML elements to receive objects. This is only useful for React applications
+   * where you pass objects to HTML elements so they can be replaced to their respective interpolation
+   * values (mostly with Trans component)
+   */
+  allowObjectInHTMLChildren: false;
+  /**
+   * Flag that enables strict key checking even if a `defaultValue` has been provided.
+   * This ensures all calls of `t` function don't accidentally use implicitly missing keys.
+   */
+  strictKeyChecks: false;
+  /**
+   * Prefix for interpolation
+   */
+  interpolationPrefix: '{{';
+  /**
+   * Suffix for interpolation
+   */
+  interpolationSuffix: '}}'; /** @see {InterpolationOptions.unescapePrefix} */
+  unescapePrefix: '-'; /** @see {InterpolationOptions.unescapeSuffix} */
+  unescapeSuffix: '';
+  /**
+   * Use a proxy-based selector to select a translation.
+   *
+   * Enables features like go-to definition, and better DX/faster autocompletion
+   * for TypeScript developers.
+   *
+   * If you're working with an especially large set of translations and aren't
+   * using context, you set `enableSelector` to `"optimize"` and i18next won't do
+   * any type-level processing of your translations at all.
+   *
+   * With `enableSelector` set to `"optimize"`, i18next is capable of supporting
+   * arbitrarily large/deep translation sets without causing any IDE slowdown
+   * whatsoever.
+   *
+   * @default false
+   */
+  enableSelector: false;
+  /**
+   * Maps interpolation format specifiers to their expected value types.
+   *
+   * By default, i18next infers types from built-in formatter names:
+   * - `number`, `currency` → `number`
+   * - `datetime` → `Date`
+   * - `relativetime` → `number`
+   * - `list` → `readonly string[]`
+   * - No format specifier → `string`
+   *
+   * Use this option to add mappings for custom formatters or to override
+   * the built-in defaults.
+   *
+   * @default {} (empty — built-in defaults apply)
+   *
+   * @example
+   * ```ts
+   * interface CustomTypeOptions {
+   *   interpolationFormatTypeMap: {
+   *     // custom formatter
+   *     uppercase: string;
+   *     // override built-in
+   *     currency: string;
+   *   };
+   * }
+   * ```
+   */
+  interpolationFormatTypeMap: {};
+}, CustomTypeOptions>;
+type PluginOptions<T> = $MergeBy<{
+  /**
+   * Options for language detection - check documentation of plugin
+   * @default undefined
+   */
+  detection?: object;
+  /**
+   * Options for backend - check documentation of plugin
+   * @default undefined
+   */
+  backend?: T;
+  /**
+   * Options for cache layer - check documentation of plugin
+   * @default undefined
+   */
+  cache?: object;
+  /**
+   * Options for i18n message format - check documentation of plugin
+   * @default undefined
+   */
+  i18nFormat?: object;
+}, CustomPluginOptions>;
+interface InterpolationOptions {
+  /**
+   * Used to separate format from interpolation value
+   * @default ','
+   */
+  formatSeparator?: string;
+  /**
+   * Escape function
+   * @default str => str
+   */
+  escape?(str: string): string;
+  /**
+   * Always format interpolated values.
+   * @default false
+   */
+  alwaysFormat?: boolean;
+  /**
+   * Escape passed in values to avoid xss injection
+   * @default true
+   */
+  escapeValue?: boolean;
+  /**
+   * If true, then value passed into escape function is not casted to string, use with custom escape function that does its own type check
+   * @default false
+   */
+  useRawValueToEscape?: boolean;
+  /**
+   * Prefix for interpolation
+   * @default '{{'
+   */
+  prefix?: string;
+  /**
+   * Suffix for interpolation
+   * @default '}}'
+   */
+  suffix?: string;
+  /**
+   * Escaped prefix for interpolation (regexSafe)
+   * @default undefined
+   */
+  prefixEscaped?: string;
+  /**
+   * Escaped suffix for interpolation (regexSafe)
+   * @default undefined
+   */
+  suffixEscaped?: string;
+  /**
+   * Suffix to unescaped mode
+   * @default undefined
+   */
+  unescapeSuffix?: string;
+  /**
+   * Prefix to unescaped mode
+   * @default '-'
+   */
+  unescapePrefix?: string;
+  /**
+   * Prefix for nesting
+   * @default '$t('
+   */
+  nestingPrefix?: string;
+  /**
+   * Suffix for nesting
+   * @default ')'
+   */
+  nestingSuffix?: string;
+  /**
+   * Escaped prefix for nesting (regexSafe)
+   * @default undefined
+   */
+  nestingPrefixEscaped?: string;
+  /**
+   * Escaped suffix for nesting (regexSafe)
+   * @default undefined
+   */
+  nestingSuffixEscaped?: string;
+  /**
+   * Separates options from key
+   * @default ','
+   */
+  nestingOptionsSeparator?: string;
+  /**
+   * Global variables to use in interpolation replacements
+   * @default undefined
+   */
+  defaultVariables?: {
+    [index: string]: any;
+  };
+  /**
+   * After how many interpolation runs to break out before throwing a stack overflow
+   * @default 1000
+   */
+  maxReplaces?: number;
+  /**
+   * If true, it will skip to interpolate the variables
+   * @default true
+   */
+  skipOnVariables?: boolean;
+}
+interface FallbackLngObjList {
+  [language: string]: readonly string[];
+}
+type FallbackLng = string | readonly string[] | FallbackLngObjList | ((code: string) => string | readonly string[] | FallbackLngObjList);
+interface ReactOptions {
+  /**
+   * Set it to fallback to let passed namespaces to translated hoc act as fallbacks
+   * @default 'default'
+   */
+  nsMode?: 'default' | 'fallback';
+  /**
+   * Set it to the default parent element created by the Trans component.
+   * @default 'div'
+   */
+  defaultTransParent?: string;
+  /**
+   * Set which events trigger a re-render, can be set to false or string of events
+   * @default 'languageChanged'
+   */
+  bindI18n?: string | false;
+  /**
+   * Set which events on store trigger a re-render, can be set to false or string of events
+   * @default ''
+   */
+  bindI18nStore?: string | false;
+  /**
+   * Set fallback value for Trans components without children
+   * @default undefined
+   */
+  transEmptyNodeValue?: string;
+  /**
+   * Set it to false if you do not want to use Suspense
+   * @default true
+   */
+  useSuspense?: boolean;
+  /**
+   * Function to generate an i18nKey from the defaultValue (or Trans children)
+   * when no key is provided.
+   * By default, the defaultValue (Trans text) itself is used as the key.
+   * If you want to require keys for all translations, supply a function
+   * that always throws an error.
+   * @default undefined
+   */
+  hashTransKey?(defaultValue: TOptionsBase['defaultValue']): TOptionsBase['defaultValue'];
+  /**
+   * Convert eg. <br/> found in translations to a react component of type br
+   * @default true
+   */
+  transSupportBasicHtmlNodes?: boolean;
+  /**
+   * Which nodes not to convert in defaultValue generation in the Trans component.
+   * @default ['br', 'strong', 'i', 'p']
+   */
+  transKeepBasicHtmlNodesFor?: readonly string[];
+  /**
+   * Wrap text nodes in a user-specified element.
+   * @default ''
+   */
+  transWrapTextNodes?: string;
+  /**
+   * Default props to apply to all Trans components.
+   * Component-level props will override these defaults.
+   */
+  transDefaultProps?: {
+    tOptions?: TOptions;
+    values?: object;
+    shouldUnescape?: boolean;
+    components?: readonly unknown[] | {
+      readonly [tagName: string]: unknown;
+    }; // Use `unknown` (or `any`) to be permissive without importing React.
+  };
+  /**
+   * Optional keyPrefix that will be automatically applied to returned t function in useTranslation for example.
+   * Accepts a string or a selector function (e.g. `$ => $.deeply.nested`).
+   * @default undefined
+   */
+  keyPrefix?: string | (($: any) => any);
+  /**
+   * Unescape function
+   * by default it unescapes some basic html entities
+   */
+  unescape?(str: string): string;
+}
+type ResourceKey = string | {
+  [key: string]: any;
+};
+interface ResourceLanguage {
+  [namespace: string]: ResourceKey;
+}
+interface Resource {
+  [language: string]: ResourceLanguage;
+}
+interface InitOptions<T = object> extends PluginOptions<T> {
+  /**
+   * Logs info level to console output. Helps finding issues with loading not working.
+   * @default false
+   */
+  debug?: boolean;
+  /**
+   * Resources to initialize with (if not using loading or not appending using addResourceBundle)
+   * @default undefined
+   */
+  resources?: Resource;
+  /**
+   * Allow initializing with bundled resources while using a backend to load non bundled ones.
+   * @default false
+   */
+  partialBundledLanguages?: boolean;
+  /**
+   * Language to use (overrides language detection)
+   * @default undefined
+   */
+  lng?: string;
+  /**
+   * Language to use if translations in user language are not available.
+   * @default 'dev'
+   */
+  fallbackLng?: false | FallbackLng;
+  /**
+   * Array of allowed languages
+   * @default false
+   */
+  supportedLngs?: false | readonly string[];
+  /**
+   * If true will pass eg. en-US if finding en in supportedLngs
+   * @default false
+   */
+  nonExplicitSupportedLngs?: boolean;
+  /**
+   * Language codes to lookup, given set language is 'en-US':
+   * 'all' --> ['en-US', 'en', 'dev'],
+   * 'currentOnly' --> 'en-US',
+   * 'languageOnly' --> 'en'
+   * @default 'all'
+   */
+  load?: 'all' | 'currentOnly' | 'languageOnly';
+  /**
+   * Array of languages to preload. Important on server-side to assert translations are loaded before rendering views.
+   * @default false
+   */
+  preload?: false | readonly string[];
+  /**
+   * Language will be lowercased eg. en-US --> en-us
+   * @default false
+   */
+  lowerCaseLng?: boolean;
+  /**
+   * Language will be lowercased EN --> en while leaving full locales like en-US
+   * @default false
+   */
+  cleanCode?: boolean;
+  /**
+   * String or array of namespaces to load
+   * @default 'translation'
+   */
+  ns?: string | readonly string[];
+  /**
+   * Default namespace used if not passed to translation function
+   * @default 'translation'
+   */
+  defaultNS?: string | false | readonly string[];
+  /**
+   * String or array of namespaces to lookup key if not found in given namespace.
+   * @default false
+   */
+  fallbackNS?: false | string | readonly string[];
+  /**
+   * Calls save missing key function on backend if key not found.
+   * @default false
+   */
+  saveMissing?: boolean;
+  /**
+   * Calls save missing key function on backend if key not found also for plural forms.
+   * @default false
+   */
+  saveMissingPlurals?: boolean;
+  /**
+   * Experimental: enable to update default values using the saveMissing
+   * (Works only if defaultValue different from translated value.
+   * Only useful on initial development or when keeping code as source of truth not changing values outside of code.
+   * Only supported if backend supports it already)
+   * @default false
+   */
+  updateMissing?: boolean;
+  /**
+   * @default 'fallback'
+   */
+  saveMissingTo?: 'current' | 'all' | 'fallback';
+  /**
+   * Used to not fallback to the key as default value, when using saveMissing functionality.
+   * i.e. when using with i18next-http-backend this will result in having a key with an empty string value.
+   * @default false
+   */
+  missingKeyNoValueFallbackToKey?: boolean;
+  /**
+   * Used for custom missing key handling (needs saveMissing set to true!)
+   * @default false
+   */
+  missingKeyHandler?: false | ((lngs: readonly string[], ns: string, key: string, fallbackValue: string, updateMissing: boolean, options: any) => void);
+  /**
+   * Receives a key that was not found in `t()` and returns a value, that will be returned by `t()`
+   * @default noop
+   */
+  parseMissingKeyHandler?(key: string, defaultValue?: string, options?: any): any;
+  /**
+   * Appends namespace to missing key
+   * @default false
+   */
+  appendNamespaceToMissingKey?: boolean;
+  /**
+   * Gets called in case a interpolation value is undefined. This method will not be called if the value is empty string or null
+   * @default noop
+   */
+  missingInterpolationHandler?: (text: string, value: any, options: InitOptions) => any;
+  /**
+   * String or array of postProcessors to apply per default
+   * @default false
+   */
+  postProcess?: false | string | readonly string[];
+  /**
+   * passthrough the resolved object including 'usedNS', 'usedLang' etc into options object of postprocessors as 'i18nResolved' property
+   * @default false
+   */
+  postProcessPassResolved?: boolean;
+  /**
+   * Allows null values as valid translation
+   * @default false
+   */
+  returnNull?: boolean;
+  /**
+   * Allows empty string as valid translation
+   * @default true
+   */
+  returnEmptyString?: boolean;
+  /**
+   * Allows objects as valid translation result
+   * @default false
+   */
+  returnObjects?: boolean;
+  /**
+   * Returns an object that includes information about the used language, namespace, key and value
+   * @default false
+   */
+  returnDetails?: boolean;
+  /**
+   * Gets called if object was passed in as key but returnObjects was set to false
+   * @default noop
+   */
+  returnedObjectHandler?(key: string, value: string, options: any): void;
+  /**
+   * Char, eg. '\n' that arrays will be joined by
+   * @default false
+   */
+  joinArrays?: false | string;
+  /**
+   * Sets defaultValue
+   * @default args => ({ defaultValue: args[1] })
+   */
+  overloadTranslationOptionHandler?(args: string[]): TOptions;
+  /**
+   * @see https://www.i18next.com/translation-function/interpolation
+   */
+  interpolation?: InterpolationOptions;
+  /**
+   * Options for react - check documentation of plugin
+   * @default undefined
+   */
+  react?: ReactOptions;
+  /**
+   * Triggers resource loading in init function inside a setTimeout (default async behaviour).
+   * Set it to false if your backend loads resources sync - that way calling i18next.t after
+   * init is possible without relaying on the init callback.
+   * @default true
+   */
+  initAsync?: boolean;
+  /**
+   * Char to separate keys
+   * @default '.'
+   */
+  keySeparator?: false | string;
+  /**
+   * Char to split namespace from key
+   * @default ':'
+   */
+  nsSeparator?: false | string;
+  /**
+   * Char to split plural from key
+   * @default '_'
+   */
+  pluralSeparator?: string;
+  /**
+   * Char to split context from key
+   * @default '_'
+   */
+  contextSeparator?: string;
+  /**
+   * Prefixes the namespace to the returned key when using `cimode`
+   * @default false
+   */
+  appendNamespaceToCIMode?: boolean;
+  /**
+   * Compatibility JSON version
+   * @warning only `v4` is available and supported by typescript
+   * @default 'v4'
+   */
+  compatibilityJSON?: 'v4';
+  /**
+   * Options for https://github.com/locize/locize-lastused
+   * @default undefined
+   */
+  locizeLastUsed?: {
+    /**
+     * The id of your locize project
+     */
+    projectId: string;
+    /**
+     * An api key if you want to send missing keys
+     */
+    apiKey?: string;
+    /**
+     * The reference language of your project
+     * @default 'en'
+     */
+    referenceLng?: string;
+    /**
+     * Version
+     * @default 'latest'
+     */
+    version?: string;
+    /**
+     * Debounce interval to send data in milliseconds
+     * @default 90000
+     */
+    debounceSubmit?: number;
+    /**
+     * Hostnames that are allowed to send last used data.
+     * Please keep those to your local system, staging, test servers (not production)
+     * @default ['localhost']
+     */
+    allowedHosts?: readonly string[];
+  };
+  /**
+   * Automatically lookup for a flat key if a nested key is not found an vice-versa
+   * @default true
+   */
+  ignoreJSONStructure?: boolean;
+  /**
+   * Limit parallelism of calls to backend
+   * This is needed to prevent trying to open thousands of
+   * sockets or file descriptors, which can cause failures
+   * and actually make the entire process take longer.
+   * @default 10
+   */
+  maxParallelReads?: number;
+  /**
+   * The maximum number of retries to perform.
+   * Note that retries are only performed when a request has no response
+   * and throws an error.
+   * The default value is used if value is set below 0.
+   * @default 5
+   */
+  maxRetries?: number;
+  /**
+   * Set how long to wait, in milliseconds, between retries of failed requests.
+   * This number is compounded by a factor of 2 for subsequent retry.
+   * The default value is used if value is set below 1ms.
+   * @default 350
+   */
+  retryTimeout?: number;
+  /**
+   * Initializes the internal formatter for the in-built formats as cached version.
+   * Can be set to false for this type of issues: https://github.com/i18next/i18next/issues/2227
+   * @default true
+   */
+  cacheInBuiltFormats?: boolean;
+}
+interface TOptionsBase {
+  /**
+   * Default value to return if a translation was not found
+   */
+  defaultValue?: unknown;
+  /**
+   * Count value used for plurals
+   */
+  count?: number;
+  /**
+   * Ordinal flag for ordinal plurals
+   */
+  ordinal?: boolean;
+  /**
+   * Used for contexts (eg. male\female)
+   */
+  context?: unknown;
+  /**
+   * Object with vars for interpolation - or put them directly in options
+   */
+  replace?: any;
+  /**
+   * Override language to use
+   */
+  lng?: string;
+  /**
+   * Override languages to use
+   */
+  lngs?: readonly string[];
+  /**
+   * Override language to lookup key if not found see fallbacks for details
+   */
+  fallbackLng?: false | FallbackLng;
+  /**
+   * Override namespaces (string or array)
+   */
+  ns?: Namespace;
+  /**
+   * Override char to separate keys
+   */
+  keySeparator?: false | string;
+  /**
+   * Override char to split namespace from key
+   */
+  nsSeparator?: false | string;
+  /**
+   * Accessing an object not a translation string (can be set globally too)
+   */
+  returnObjects?: boolean;
+  /**
+   * Returns an object that includes information about the used language, namespace, key and value
+   */
+  returnDetails?: boolean;
+  /**
+   * Char, eg. '\n' that arrays will be joined by (can be set globally too)
+   */
+  joinArrays?: string;
+  /**
+   * String or array of postProcessors to apply see interval plurals as a sample
+   */
+  postProcess?: string | readonly string[];
+  /**
+   * Override interpolation options
+   */
+  interpolation?: InterpolationOptions;
+  /**
+   * Optional keyPrefix that will be applied to the key before resolving.
+   * Accepts a string or a selector function (e.g. `$ => $.deeply.nested`).
+   * Only supported on the TFunction returned by getFixedT().
+   */
+  keyPrefix?: string | (($: any) => any);
+}
+type TOptions<TInterpolationMap extends object = $Dictionary> = TOptionsBase & TInterpolationMap;
+type FlatNamespace = $PreservedValue<keyof TypeOptions['resources'], string>;
+type Namespace<T = FlatNamespace> = T | readonly T[];
+//#endregion
+//#region src/shared/i18n.d.ts
+/** 根据环境变量推断默认语言 */
+declare function detectLocaleFromEnv(): WorkflowLocale;
+/** 创建一个国际化实例，供 kit 和运行时共享使用 */
+declare function createWorkflowI18n(options?: {
+  fallbackLocale?: WorkflowLocale;
+  locale?: WorkflowLocale;
+  locales?: WorkflowLocaleCatalog;
+  resolveLocale?: () => WorkflowLocale;
+}): WorkflowI18n;
+/** 方便调用方显式构建 locale 资源目录 */
+declare function createI18nLocales<TCatalog extends WorkflowLocaleCatalog>(catalog: TCatalog): TCatalog;
+/** 导出内置 locale 资源目录，便于增量覆盖 */
+declare const builtinWorkflowLocales: {
+  'en-US': {
+    log: {
+      confirmSave: string;
+      saveFailed: string;
+      saved: string;
+      savedOnFailure: string;
+    };
+    prompt: {
+      cancelled: string;
+    };
+    workflow: {
+      checkpoint: {
+        applied: string;
+        appliedCancelled: string;
+        appliedFailed: string;
+        message: string;
+        restoredSteps: string;
+        skippedInitialValues: string;
+      };
+      parallel: {
+        completedNoOutput: string;
+        started: string;
+      };
+      reuse: {
+        applied: string;
+        choose: string;
+        chooseHint: string;
+        empty: string;
+        latest: string;
+        latestHint: string;
+        message: string;
+        new: string;
+        newHint: string;
+      };
+      savedAt: string;
+      step: {
+        duplicateSkipped: string;
+        invalidChoice: string;
+        overwritten: string;
+      };
+    };
+  };
+  'zh-CN': {
+    log: {
+      confirmSave: string;
+      saveFailed: string;
+      saved: string;
+      savedOnFailure: string;
+    };
+    prompt: {
+      cancelled: string;
+    };
+    workflow: {
+      checkpoint: {
+        applied: string;
+        appliedCancelled: string;
+        appliedFailed: string;
+        message: string;
+        restoredSteps: string;
+        skippedInitialValues: string;
+      };
+      parallel: {
+        completedNoOutput: string;
+        started: string;
+      };
+      reuse: {
+        applied: string;
+        choose: string;
+        chooseHint: string;
+        empty: string;
+        latest: string;
+        latestHint: string;
+        message: string;
+        new: string;
+        newHint: string;
+      };
+      savedAt: string;
+      step: {
+        duplicateSkipped: string;
+        invalidChoice: string;
+        overwritten: string;
+      };
+    };
+  };
+};
+/** 导出 i18next 基础配置，供工具链和外部集成复用 */
+declare const workflowI18nextOptions: InitOptions<object>;
+//#endregion
+//#region src/shared/timezone.d.ts
+/** 根据环境变量或运行时信息推断默认时区 */
+declare function detectTimeZone(): WorkflowTimeZone;
+//#endregion
+//#region src/storage/checkpoint.d.ts
+interface FileCheckpointStoreOptions {
+  filePath: string;
+}
+/** 创建一个基于本地 JSON 文件的 checkpoint 存储 */
+declare function createFileCheckpointStore(options: FileCheckpointStoreOptions): WorkflowCheckpointStore;
+/** 创建一个仅保存在内存中的 checkpoint 存储 */
+declare function createMemoryCheckpointStore(): WorkflowCheckpointStore & {
+  checkpoints: WorkflowCheckpointEntry[];
+};
+//#endregion
+//#region src/storage/history.d.ts
+interface FileHistoryStoreOptions {
+  filePath: string;
+  maxSnapshotsPerWorkflow?: number;
+}
+/** 创建一个基于本地 JSON 文件的历史存储 */
+declare function createFileHistoryStore(options: FileHistoryStoreOptions): WorkflowHistoryStore;
+/** 创建一个仅保存在内存中的历史存储，适合测试和短生命周期脚本 */
+declare function createMemoryHistoryStore(): WorkflowHistoryStore;
+//#endregion
+//#region src/storage/log.d.ts
+interface FileLogStoreOptions {
+  directory: string;
+  fileName?: (snapshot: WorkflowRunSnapshot) => string;
+  format?: WorkflowLogFormat;
+}
+interface WorkflowLogSession<TValues extends Record<string, unknown>> {
+  complete: (status: WorkflowRunStatus, values: Partial<TValues>, results: Partial<Record<string, unknown>>) => void;
+  record: (event: Omit<WorkflowRunEvent, 'runId' | 'timestamp' | 'workflowId'>) => void;
+  save: (options?: {
+    path?: string;
+  }) => Promise<string>;
+  snapshot: () => WorkflowRunSnapshot<TValues>;
+}
+/** 计算单次运行的分析摘要 */
+declare function analyzeWorkflowRun(snapshot: WorkflowRunSnapshot): WorkflowRunAnalysis;
+/** 将运行快照渲染成指定日志格式 */
+declare function renderWorkflowLog(snapshot: WorkflowRunSnapshot, format?: WorkflowLogFormat): string;
+/** 创建一个写入本地文件的日志存储 */
+declare function createFileLogStore(options: FileLogStoreOptions): WorkflowLogStore;
+/** 创建一个空实现的日志存储 */
+declare function createNoopLogStore(): WorkflowLogStore;
+/** 创建一个仅保存在内存中的日志存储 */
+declare function createMemoryLogStore(): WorkflowLogStore & {
+  snapshots: WorkflowRunSnapshot[];
+};
+/** 创建一次运行对应的日志会话对象 */
+declare function createWorkflowLogSession<TValues extends Record<string, unknown>>(options: {
+  locale: string;
+  meta?: Record<string, unknown>;
+  runId: string;
+  store: WorkflowLogStore;
+  timeZone: string;
+  workflowId: string;
+}): WorkflowLogSession<TValues>;
+//#endregion
+export { type AutocompleteMultiSelectOptions, type AutocompleteOptions, type BoxAlignment, type BoxOptions, type CommonOptions, type ConfirmOptions, CreateClackRendererOptions, CreateWorkflowKitOptions, DefineStep, type GroupMultiSelectOptions, type LimitOptionsParams, type LogMessageOptions, MaybePromise, type MultiSelectOptions, type NoteOptions, type PasswordOptions, type PathOptions, type ProgressOptions, type ProgressResult, PromptCancelledError, PromptRuntime, PromptValidator, type SelectKeyOptions, type SelectOptions, Simplify, type SpinnerOptions, type SpinnerResult, StepResultRecord, StepValueRecord, type Task, type TaskLogOptions, type TextOptions, UnionToIntersection, WorkflowAsciiArtDefinition, WorkflowAuthoringDefinition, WorkflowAutocompleteMultiSelectStep, WorkflowAutocompleteMultiSelectStepConfig, WorkflowAutocompleteStep, WorkflowAutocompleteStepConfig, WorkflowBaseStep, WorkflowBoxStep, WorkflowBoxStepConfig, WorkflowBuiltinDisplayStep, WorkflowBuiltinExecutableStep, WorkflowBuiltinResultStep, WorkflowBuiltinValueStep, WorkflowCheckpointEntry, WorkflowCheckpointReason, WorkflowCheckpointResumeMode, WorkflowCheckpointStore, WorkflowChoiceOptions, WorkflowClackRendererOptions, WorkflowCliBridge, WorkflowCliBridgeOptions, WorkflowCliFieldOptions, WorkflowCliOptionConfig, WorkflowCliOptionRegistrar, WorkflowColors, WorkflowCommandExecOptions, WorkflowCommandExecutionOptions, type WorkflowCommandExecutionResult, WorkflowCommandExecutor, WorkflowCommandExecutorType, WorkflowCommandHandler, WorkflowCommandPresenter, WorkflowCommandPresenterOptions, type WorkflowCommandResult, WorkflowCommandResultResolver, WorkflowCommandRetryOptions, WorkflowCommandShellOptions, WorkflowCommandStep, WorkflowCommandStepConfig, WorkflowCommandTaskIO, WorkflowCommandTaskLogOptions, WorkflowConfirmSaveLogContext, WorkflowConfirmSaveLogOptions, WorkflowConfirmStep, WorkflowConfirmStepConfig, WorkflowContextTools, WorkflowDefinition, WorkflowExecutableStep, WorkflowExecutionError, WorkflowExternalCommandStep, WorkflowExternalCommandStepConfig, WorkflowGlobOptions, WorkflowGroupMultiSelectStep, WorkflowGroupMultiSelectStepConfig, WorkflowGroupedChoiceOptions, WorkflowHistoryReuseMode, WorkflowHistoryStore, WorkflowI18n, WorkflowInlineCommandStep, WorkflowInlineCommandStepConfig, WorkflowIntroDefinition, WorkflowKit, WorkflowKitCheckpointOptions, WorkflowKitHistoryOptions, WorkflowKitLogOptions, WorkflowLocale, WorkflowLocaleCatalog, WorkflowLocaleResource, WorkflowLogCompletionOptions, WorkflowLogFormat, WorkflowLogLevel, WorkflowLogOptions, WorkflowLogStep, WorkflowLogStepConfig, WorkflowLogStore, WorkflowMessageValues, WorkflowMultiSelectStep, WorkflowMultiSelectStepConfig, WorkflowNoteStep, WorkflowNoteStepConfig, WorkflowPasswordStep, WorkflowPasswordStepConfig, WorkflowPathStep, WorkflowPathStepConfig, WorkflowPlugin, WorkflowPluginAPI, WorkflowPluginStep, WorkflowPluginStepExecutionOptions, WorkflowPluginStepHandler, WorkflowPredicate, WorkflowRenderer, WorkflowRendererAutocompleteMultiSelectOptions, WorkflowRendererAutocompleteOptions, WorkflowRendererBoxOptions, WorkflowRendererConfirmOptions, WorkflowRendererGroupMultiSelectOptions, WorkflowRendererLogOptions, WorkflowRendererMultiSelectOptions, WorkflowRendererNoteOptions, WorkflowRendererPasswordOptions, WorkflowRendererPathOptions, WorkflowRendererSelectKeyOptions, WorkflowRendererSelectOptions, WorkflowRendererTextOptions, WorkflowResultsFromSteps, WorkflowRunAnalysis, WorkflowRunCheckpointOptions, WorkflowRunCommandOptions, WorkflowRunEvent, WorkflowRunHistoryOptions, WorkflowRunLogOptions, WorkflowRunOptions, WorkflowRunResult, WorkflowRunSnapshot, WorkflowRunStatus, WorkflowRuntimeContext, WorkflowScriptFileCommandStep, WorkflowScriptFileCommandStepConfig, WorkflowSelectKeyStep, WorkflowSelectKeyStepConfig, WorkflowSelectOption, WorkflowSelectStep, WorkflowSelectStepConfig, WorkflowSnapshotEntry, WorkflowSnapshotOptions, WorkflowSnapshotQuery, WorkflowStepAnalysis, WorkflowStepAuthoringDefinition, WorkflowStepConfigBase, WorkflowStepConfigByType, WorkflowStepConfigDefinition, WorkflowStepConfigInput, WorkflowStepDefinition, WorkflowStepType, WorkflowSummaryOptions, WorkflowSummaryPreset, WorkflowTemplate, WorkflowTemplateCatalog, WorkflowTextStep, WorkflowTextStepConfig, WorkflowTimeZone, WorkflowValidator, WorkflowValueResolver, WorkflowValuesFromSteps, analyzeWorkflowRun, autocomplete, autocompleteMultiselect, box, builtinWorkflowLocales, cancel, composeValidators, confirm, createAutocompleteMultiSelectStep, createAutocompleteStep, createBoxStep, createClackRenderer, createCommandExecutor, createCommandStep, createConfirmStep, createFileCheckpointStore, createFileHistoryStore, createFileLogStore, createGroupMultiSelectStep, createI18nLocales, createLogStep, createMemoryCheckpointStore, createMemoryHistoryStore, createMemoryLogStore, createMultiSelectStep, createNodeCommandExecutor, createNoopLogStore, createNoteStep, createPasswordStep, createPathStep, createRequiredTextValidator, createSelectKeyStep, createSelectStep, createTextStep, createTinyexecCommandExecutor, createWorkflowCliBridge, createWorkflowI18n, createWorkflowKit, createWorkflowLogSession, createWorkflowTemplateCatalog, defaultPromptRuntime, defineStep, defineSteps, defineWorkflow, defineWorkflowTemplate, detectLocaleFromEnv, detectTimeZone, formatFieldLabel, formatPromptValue, globFiles, group, groupMultiselect, intro, isCI, isCancel, isPromptCancelledError, isTTY, isWorkflowExecutionError, limitOptions, log, multiselect, note, outro, parseWorkflowCliBoolean, parseWorkflowCliList, password, patchJson, path, progress, readJson, readTextFile, renderAsciiArt, renderWorkflowLog, runCommand, runWorkflow, runWorkflowSafely, sanitizeFileName, select, selectKey, sleep, spinner, stream, symbol, symbolBar, taskLog, tasks, text, toOptions, unicode, unicodeOr, workflowI18nextOptions, writeJson, writeTextFile };
+//# sourceMappingURL=index.d.mts.map