设计与实现

返回总览

这一页只看已经写进源码的设计图与流程图

先把功能面摊开，再顺着一次运行走到底

覆盖范围

“覆盖率 100%” 在这页里的含义，是覆盖当前仓库已经对外成立的核心能力面，而不是去画尚未实现的未来规划

功能面	关键入口	对应图表
工作流 DSL	defineWorkflow defineSteps defineStep.*	总览图、分层设计图
kit 组装与运行时	createWorkflowKit executeWorkflow	总览图、分层设计图、主流程图
步骤调度与节点执行	graph/scheduler nodes/*	分层设计图、主流程图
CLI 参数桥接	createWorkflowCliBridge	CLI 桥接流程图
命令步骤集成	command scriptFile run(context, io)	命令步骤流程图
运行时上下文	context.values context.results context.tools	分层设计图、状态与持久化图、扩展图
持久化	history checkpoint logs	主流程图、状态与持久化图
中断恢复与失败处理	checkpoint saveOnFailure confirmSaveLog	主流程图、恢复流程图
扩展能力	templates plugins context.tools	扩展图
国际化与时区	locale timeZone log timestamps	主流程图、扩展图

1. 总览图

先看全景

clack-kit 到底把哪些能力接到了一条终端 workflow 里

flowchart LR
  A[业务作者<br/>定义 workflow] --> B[Authoring DSL<br/>defineWorkflow defineSteps defineStep]
  B --> C[Workflow Definition]
  C --> D[createWorkflowKit]
  D --> E[Runtime Engine]

  E --> F[Scheduler<br/>遍历步骤与分组]
  F --> G[Input Steps<br/>text date select confirm path]
  F --> H[Command Steps<br/>command scriptFile run]
  F --> I[Display Steps<br/>note log box]
  F --> J[Plugin Steps<br/>registerStepHandler]

  E --> K[Runtime Context<br/>values results tools t]
  E --> L[Renderer]
  E --> M[Executor]
  E --> N[Persistence]

  C --> O[CLI Bridge]
  O --> P[initialValues]
  P --> E

  N --> Q[history]
  N --> R[checkpoint]
  N --> S[logs]

  D --> T[i18n]
  D --> U[timeZone]
  D --> V[templates]
  D --> W[plugins]

Loading diagram…

整条线压缩后，其实就是一句话

先用 DSL 定义 workflow，再由 kit 组装运行时，把交互步骤、命令步骤、状态留存和扩展点挂到同一条执行链路里

2. 分层设计图

源码入口适合从这张图开始

flowchart TB
  subgraph PublicAPI[对外稳定入口]
    API[src/index.ts]
  end

  subgraph Authoring[authoring]
    CLI[cli.ts]
    WF[workflow.ts]
    TMPL[templates.ts]
    STEPS[step-builders]
  end

  subgraph Runtime[runtime]
    KIT[kit.ts]
    ENGINE[engine.ts]
    RENDERER[renderer.ts]
    COMMAND[command.ts]
    INTRO[intro.ts]
    SUMMARY[summary.ts]
    HISTORYSTATE[history-state.ts]
    CHECKPOINTSTATE[checkpoint-state.ts]
  end

  subgraph Graph[graph]
    SCHEDULER[scheduler.ts]
  end

  subgraph Nodes[nodes]
    INPUT[input handlers]
    TASK[task command-handler]
    DISPLAY[display handlers]
  end

  subgraph Session[session]
    CONTEXT[run-session.ts]
    TYPES[session/types.ts]
  end

  subgraph Storage[storage]
    HISTORY[history.ts]
    CHECKPOINT[checkpoint.ts]
    LOG[log.ts]
  end

  subgraph Shared[shared]
    SHARED[types errors i18n timezone helpers files]
  end

  API --> Authoring
  API --> Runtime
  API --> Storage
  API --> Shared

  Authoring --> KIT
  KIT --> ENGINE
  KIT --> RENDERER
  KIT --> COMMAND
  KIT --> HISTORY
  KIT --> CHECKPOINT
  KIT --> LOG
  KIT --> SHARED

  ENGINE --> INTRO
  ENGINE --> SUMMARY
  ENGINE --> HISTORYSTATE
  ENGINE --> CHECKPOINTSTATE
  ENGINE --> SCHEDULER
  ENGINE --> CONTEXT

  SCHEDULER --> INPUT
  SCHEDULER --> TASK
  SCHEDULER --> DISPLAY
  SCHEDULER --> CONTEXT

  CONTEXT --> Storage
  CONTEXT --> SHARED
  Nodes --> SHARED
  Runtime --> SHARED
  Storage --> SHARED

Loading diagram…

边界并不绕，按职责记就够了

• authoring 负责声明 DSL，不负责执行
• runtime 负责组装 renderer executor stores，并驱动整次运行
• graph 只负责调度顺序、并行分组、跳过与 checkpoint 节点推进
• nodes 负责具体步骤实现
• session 负责 context、values、results 和 context.tools
• storage 负责 history checkpoint logs 三类持久化
• shared 放跨层类型、错误、国际化、时区和文件工具

3. 一次运行的主流程图

createWorkflowKit().run() 之后，主链路大致按这个顺序推进

flowchart TD
  A[调用 kit.run workflow] --> B[resolve locale and timeZone]
  B --> C[创建 log session]
  C --> D[create runtime context]
  D --> E[渲染 intro 和 ASCII banner]
  E --> F{history.reuse 生效吗}
  F -- 是 --> G[读取 history 快照并合并 values]
  F -- 否 --> H[跳过 history]
  G --> I{checkpoint.resume 生效吗}
  H --> I
  I -- 是 --> J[读取 checkpoint 恢复 values results completedStepIds]
  I -- 否 --> K[从头开始执行]
  J --> L[onStart hook]
  K --> L
  L --> M[Scheduler 遍历 steps]
  M --> N[执行 input command display plugin 节点]
  N --> O[累计 values results events]
  O --> P{全部成功}
  P -- 是 --> Q[onComplete 或默认 summary]
  Q --> R[按配置保存 history snapshot]
  R --> S[清理 checkpoint]
  S --> T[渲染 outro]
  T --> U{workflow.log.completion}
  U -- confirm 或 save --> V[保存日志或交互确认]
  U -- 关闭 --> W[直接返回 result]
  V --> W
  P -- 否 --> X{取消还是失败}
  X -- 取消 --> Y[保存 checkpoint reason=cancelled]
  X -- 失败 --> Z[保存 checkpoint reason=failed]
  Z --> AA{saveOnFailure}
  AA -- 是 --> AB[自动保存失败日志]
  AA -- 否 --> AC[直接抛错]
  Y --> AC
  AB --> AC

Loading diagram…

这里最要紧的是三条支线

1. history 解决“以前填过什么”
2. checkpoint 解决“上次停在哪”
3. logs 解决“这次发生了什么”

4. 恢复与失败处理流程图

主流程图已经带到失败分支，这里把恢复链路单独拆开

flowchart TD
  A[运行开始] --> B{存在 initialValues}
  B -- 是 --> C[跳过 history 复用与 checkpoint 恢复]
  B -- 否 --> D{history.reuse 开启}
  D -- 是 --> E[查询历史快照并决定是否复用]
  D -- 否 --> F[继续检查 checkpoint]
  E --> F
  F --> G{checkpoint.resume 开启}
  G -- 是 --> H[读取 latest checkpoint]
  G -- 否 --> I[从头运行]
  H --> J{resume mode}
  J -- ask --> K[交互确认是否恢复]
  J -- always --> L[直接恢复 values results completedStepIds]
  J -- never --> I
  K -- 恢复 --> L
  K -- 放弃 --> I
  L --> M[继续剩余步骤]
  I --> M
  M --> N{运行结果}
  N -- completed --> O[清理 checkpoint]
  O --> P{log.completion}
  P -- save 或 confirm --> Q[完成后保存日志]
  P -- 关闭 --> R[结束]
  N -- cancelled --> S[保存 checkpoint reason=cancelled]
  N -- failed --> T[保存 checkpoint reason=failed]
  T --> U{saveOnFailure}
  U -- 是 --> V[自动保存失败日志]
  U -- 否 --> W[直接抛错]
  S --> W
  V --> W

Loading diagram…

这一段真正解决的是两件事

• 下次运行要不要接着上次走
• 这次失败后要不要把现场完整留下来

5. CLI 参数桥接流程图

这一段只讲 createWorkflowCliBridge

flowchart LR
  A[输入类步骤定义<br/>text select confirm multiselect] --> B[collectCliBindableSteps]
  B --> C[按 step id 生成 kebab-case option]
  C --> D[bridge.apply cli]
  D --> E[CLI 解析 options]
  E --> F[bridge.getInitialValues]
  F --> G[按字段 parse 值]
  G --> H[生成 initialValues]
  H --> I[kit.run workflow]
  I --> J[已有值的步骤直接跳过]
  I --> K[缺失值的步骤继续交互]

Loading diagram…

它的重点不在“再造一套参数系统”，而在复用同一份步骤定义

• workflow 仍然只维护一套 step DSL
• CLI 只是把部分输入步骤提前填进 initialValues
• 交互式运行和脚本式运行因此共享同一个执行核心

6. 命令步骤流程图

命令步骤最容易变复杂，所以单独拆一张图

flowchart TD
  A[遇到 command step] --> B{入口类型}
  B -- command --> C[标准化 shell 文本]
  B -- scriptFile --> D[读取脚本并推断解释器]
  B -- run context io --> E[进入自定义执行函数]

  C --> F[解析 tty renderer shell cwd env]
  D --> F
  E --> F

  F --> G[创建 presenter 与输出缓冲]
  G --> H[executor.execute]
  H --> I{renderer 模式}
  I -- task-log --> J[按步骤输出 stdout stderr]
  I -- quiet --> K[只保留结果]
  I -- inherit --> L[直接写回当前终端]

  J --> M{退出码成功}
  K --> M
  L --> M

  M -- 是 --> N[result 映射到 results.stepId]
  M -- 否且允许重试 --> O[记录 step-retried 并按 backoff 等待]
  O --> H
  M -- 否且 allowFailure --> P[记录失败但继续 workflow]
  M -- 否且不允许失败 --> Q[抛出 WorkflowExecutionError]
  N --> R[写入 events 与 commandExecutions]
  P --> R

Loading diagram…

这一层把几件原本容易散开的事情收在一起

• command 适合一条 shell 文本
• scriptFile 适合仓库里已有脚本
• run(context, io) 适合多步控制和上下文联动
• renderer 与 tty 决定输出呈现
• retry parallel allowFailure 决定执行策略

7. 状态与持久化关系图

这一张只看状态，不碰 UI

flowchart LR
  subgraph Memory[单次运行内存态]
    VALUES[values<br/>输入值与最终配置]
    RESULTS[results<br/>步骤返回值]
    EVENTS[events<br/>结构化运行事件]
    COMPLETED[completedStepIds]
  end

  subgraph HistoryStore[history]
    HS[workflow snapshots]
  end

  subgraph CheckpointStore[checkpoint]
    CS[latest checkpoint]
  end

  subgraph LogStore[logs]
    LS[pretty log 或 ecs-ndjson]
  end

  VALUES --> HS
  VALUES --> CS
  VALUES --> LS

  RESULTS --> CS
  RESULTS --> LS

  EVENTS --> LS
  COMPLETED --> CS

  HS --> REUSE[下次运行复用输入]
  CS --> RESUME[下次运行恢复现场]
  LS --> REVIEW[运行回看 审计 分析]

Loading diagram…

三类持久化各管一件事

类型	保存什么	典型用途
history	values 快照	重跑相似 workflow
checkpoint	values + results + completedStepIds	从失败或取消处恢复
logs	events 以及收尾后的 values results analysis	留档、排障、审计

8. 模板、插件、国际化扩展图

这一张把“复用”和“扩展”放到一起看

flowchart TB
  A[Workflow Template] --> B[create input-specific workflow]
  B --> C[defineWorkflow]

  D[Plugin.setup] --> E[registerStepHandler]
  D --> F[wrapRenderer]
  D --> G[wrapExecutor]
  D --> H[extendContextTools]

  C --> I[createWorkflowKit]
  E --> I
  F --> I
  G --> I
  H --> I

  I --> J[Runtime Context]
  J --> K[context.tools 原生能力]
  H --> L[context.tools 扩展能力]

  I --> M[i18n locale resolution]
  I --> N[timeZone resolution]
  M --> O[交互文案与日志语言]
  N --> P[日志时间与快照时区]

Loading diagram…

这一层的取舍很直接

• 模板解决“流程骨架复用”
• 插件解决“运行时能力复用”
• 国际化和时区不改变调度结构，但会影响交互文案、日志落盘和快照元数据

9. 读图顺序

第一次读源码时，按问题推进会比按目录硬读顺很多

1. 先看总览图，知道仓库把哪些功能接到了一起
2. 再看分层设计图，知道各目录职责落点
3. 然后看主流程图，理解一次运行的生命周期
4. 接着按需要进入 CLI、命令、持久化、扩展四张专题图

10. 结论

clack-kit 的核心设计不是把终端流程做成一个通用图引擎，而是围绕“终端 workflow”这个对象，稳定地接入五类能力

• DSL 定义
• 交互与命令执行
• 运行时上下文
• 可选持久化
• 可控扩展点

因此最值得记住的不是某一个模块名，而是这条总链路

workflow definition -> kit -> engine -> scheduler -> nodes -> values/results/events -> history/checkpoint/logs