Appearance
API 参考
这一页不重复讲教程，只收口最常查的导出、配置和结果结构
根入口导出了什么
根入口围绕四组能力展开
workflow 定义与执行
- createWorkflowKit
- runWorkflow
- runWorkflowSafely
- defineWorkflow
- defineSteps
- defineStep
CLI、模板与扩展
- createWorkflowCliBridge
- defineWorkflowTemplate
- createWorkflowTemplateCatalog
renderer、executor 与存储
- createClackRenderer
- createCommandExecutor
- createNodeCommandExecutor
- createTinyexecCommandExecutor
- createFileCheckpointStore
- createMemoryCheckpointStore
- createFileHistoryStore
- createMemoryHistoryStore
- createFileLogStore
- createMemoryLogStore
工具与辅助类型
- createWorkflowI18n
- createI18nLocales
- commandExists
- runCommand
- readTextFile、writeTextFile
- readJson、writeJson、patchJson
- globFiles、sleep
- isPromptCancelledError
- isWorkflowExecutionError
createWorkflowKit 常用选项
| 字段 | 默认值 | 说明 |
|---|---|---|
| id | 无 | kit 唯一 ID，也是 asciiArt 的最后回退来源 |
| asciiArt | true | ASCII banner 开关或配置，优先尝试 title，再尝试 artTitle，最后回退 id |
| checkpoints | false | checkpoint 配置或开关 |
| executor | 无 | 自定义命令执行器实例 |
| history | false | history 配置或开关 |
| logs | false | log store 配置或开关 |
| taskLog | 无 | command 步骤的全局 task-log 默认配置 |
| executorType | node | 内置命令执行器类型 |
| cwd | process.cwd() | 相对路径解析根目录，会映射到运行时的 projectRoot |
| locale | 自动推断 | 默认语言 |
| locales | 无 | 自定义 locale 资源目录 |
| resolveLocale | 无 | 动态解析语言 |
| resolveTimeZone | 无 | 动态解析时区 |
| timeZone | 自动推断 | 默认时区 |
| renderer | 默认 Clack renderer | 自定义渲染器 |
| rendererOptions | 无 | 默认 renderer 的选项 |
| plugins | [] | 运行时插件 |
| showCancelMessage | true | 取消时是否显示提示 |
createWorkflowKit({ asciiArt }) 里支持这几个字段
asciiArt.title会把原始标题交给 figlet 生成 bannerasciiArt.artTitle会原样输出 ASCII bannerasciiArt.font控制自动生成 banner 时使用的字体
当前内置字体限定为 Standard、Slant、Small、Big、Block、Doom、Larry 3D、Banner、Colossal、Bubble、Digital、Shadow、Script
运行时也接受对应的小写别名，例如 slant、small、doom、larry3d
WorkflowRunOptions 常用字段
| 字段 | 说明 |
|---|---|
| initialValues | 预填值，常用于跳过交互 |
| history | 本次运行的快照复用和保存行为 |
| checkpoint | 本次运行的恢复和保存行为 |
| logs | 本次运行是否启用日志能力 |
| locale | 覆盖本次运行语言 |
| timeZone | 覆盖本次运行时区 |
| meta | 进入日志快照的元数据 |
WorkflowRunResult 常用字段
| 字段 | 说明 |
|---|---|
| status | 当前实现里完成态为 completed |
| values | 最终输入和值快照 |
| results | 步骤返回结果 |
| events | 结构化事件流 |
| savedLogPath | 最近一次保存日志的路径，未保存时为 null |
| saveLog | 直接保存日志 |
| confirmSaveLog | 交互确认后保存日志 |
| confirmSaveLogSafely | 安全确认保存日志 |
| snapshot | 读取完整运行快照 |
| workflowId | workflow 唯一标识 |
| runId | 当前运行唯一标识 |
Step helper 一览
输入类
- defineStep.text
- defineStep.password
- defineStep.path
- defineStep.date
- defineStep.select
- defineStep.selectKey
- defineStep.autocomplete
- defineStep.multiselect
- defineStep.autocompleteMultiselect
- defineStep.groupMultiselect
- defineStep.confirm
展示类
- defineStep.note
- defineStep.box
- defineStep.log
执行类
- defineStep.command
常用类型名
| 类型 | 说明 |
|---|---|
| WorkflowRuntimeContext | 回调与 resolver 的上下文 |
| WorkflowRunOptions | 单次运行配置 |
| WorkflowRunResult | 单次运行结果 |
| WorkflowPlugin | 插件定义 |
| WorkflowStepDefinition | 标准化后的步骤定义 |
| WorkflowCommandExecutionResult | 命令执行结果 |
| WorkflowCommandResult | 命令步骤结果类型别名 |