状态与持久化

返回总览

这一页把 values、results、history、checkpoint 和 logs 放回同一张图里讲

默认行为先讲清楚

clack-kit 默认不会自动启用持久化能力

• history 默认关闭
• checkpoints 默认关闭
• logs 默认关闭

不显式开启时，运行仍然可以完成，只是不会向 .clack-kit 写入持久化文件

运行时的三份核心状态

状态	作用
values	保存输入值和最终配置
results	保存步骤返回值
events	保存运行事件流

history 更偏向 values，checkpoint 同时关心 values、results 和已完成步骤，logs 则围绕 events 组织

如何启用

const kit = createWorkflowKit({
  checkpoints: true,
  history: true,
  logs: true,
});

默认目录如下

.clack-kit/
  checkpoints.json
  history.json
  logs/

history 负责复用输入快照

history 保存的是 workflow 级输入快照

只要 saveSnapshot 没被关闭，workflow 成功结束和失败结束都会写入 history，这样失败后可以直接复用上一轮输入重新执行

await kit.run(workflow, {
  history: {
    reuse: 'ask',
    saveSnapshot: true,
  },
});

reuse 支持四种模式

• ask
• history
• latest
• off

如果已经传入 initialValues，而 reuse 没有显式指定，运行时默认不会再弹历史复用，避免外部传值与旧快照打架

历史复用列表和“复用快照”提示会优先用当前 workflow.snapshot.label 重新计算标签，只有当前没提供或返回 undefined 时才回退到 history.json 里的 label

checkpoint 负责恢复中断现场

checkpoint 解决的是“上次没跑完，这次从哪里继续”

await kit.run(workflow, {
  checkpoint: {
    resume: 'ask',
    save: true,
  },
});

resume 支持三种模式

• ask
• always
• never

workflow 成功结束后，checkpoint 会自动清理

失败或取消时，会保留现场供下一次恢复

logs 负责留档、分析和回看

只要 logs 已开启，单次运行就会维护一份事件会话

成功结束后，这份会话是否保存，由 workflow.log.completion 决定

const workflow = defineWorkflow({
  id: 'release',
  log: {
    completion: {
      initialValue: true,
      mode: 'confirm',
      message: '保存本次运行日志吗',
    },
    saveOnFailure: true,
  },
  steps,
});

completion

• mode: 'confirm' 表示完成后询问
• mode: 'save' 表示完成后直接保存

saveOnFailure

只要 logs 能力已启用，失败时默认会自动保存日志

日志文件格式

文件日志默认使用 pretty 格式，扩展名为 .log

如果 log store 配置 format: 'ecs-ndjson'，则会输出 .jsonl 文件，便于后续接入日志平台

pretty 日志不再单独输出 timeZone，startedAt、endedAt 和事件时间也都会去掉 (.../UTC) 这类时区尾巴，避免单行过长

其中 meta、analysis、values、results 会压成单行 JSON，command-output 事件会按实际输出行展开，避免重复的 data= 与大量转义字符把失败日志撑得太吵

savedLogPath、saveLog 和 confirmSaveLog

运行结果里和日志相关的常用入口有三个

字段	作用
savedLogPath	最近一次成功保存的日志路径
saveLog()	直接保存当前日志
confirmSaveLog()	交互确认后保存

这组接口让“运行结束立即保存”和“稍后再保存”可以共存

一个常用组合

const kit = createWorkflowKit({
  checkpoints: true,
  history: true,
  logs: true,
});

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

这套组合适合长流程和重复流程

• 有历史时能复用配置
• 中断时能从现场继续
• 结束后有日志可回看

下一步建议

• 想进一步理解运行时能读到哪些状态，看 运行时上下文
• 想针对持久化问题直接排查，看 排障