Appearance
排障
这一页按常见症状组织，不按模块组织
步骤没有出现
优先检查四件事
- initialValues 是否已经让该步骤被跳过
- when 是否返回了 false
- 是否存在更早命中的同名步骤
- 是否从 checkpoint 恢复后把该步骤标记为已完成
select 或 autocomplete 的 initialValues 报错
这类错误通常意味着预填值不在 options 范围内
处理方式很直接
- 校对 initialValues
- 校对 options 的 value 类型
- 如果值来自 CLI，检查 parse 是否把字符串转成了预期类型
history 没有生效
先检查这几项
- createWorkflowKit 是否开启了 history
- 本次 run 是否把 history 显式关掉了
- workflow 是否成功运行到保存快照阶段
- 是否已经传入 initialValues 且没有显式要求 reuse
最后一种情况最容易误判，因为运行时会优先尊重本次外部传值
checkpoint 没有恢复
优先检查
- createWorkflowKit 是否开启了 checkpoints
- 上次运行是否在失败或取消时留下 checkpoint
- 本次 checkpoint.resume 是否为 never
- 本次是否传入 initialValues 且没有显式要求恢复
成功完成的 workflow 会自动清理 checkpoint，这不是丢失，而是预期行为
日志没有落盘
优先检查
- createWorkflowKit 是否开启了 logs
- 本次 run 的 logs.enabled 是否被关掉
- workflow.log.completion 是否配置为 false
- 保存目录是否可写
如果只是想临时保存，也可以直接调用 result.saveLog()
命令输出看不到
通常是 renderer 选择问题
- task-log 只展示结构化输出与保留日志
- quiet 不实时展开 stdout 和 stderr
- renderer=inherit 会把输出写回当前终端
如果是 docker build、交互式进度条或依赖真实 TTY 的命令，还要再配 tty: 'passthrough'
设置 tty: 'passthrough' 后，这次命令会自动按 renderer=inherit 的语义处理，所以通常不用再额外写一遍 renderer
先确认 command 步骤的 renderer 配置，再确认是否真的往 io.stdout 或 io.stderr 写了内容
像 git clone --progress 这类命令会把进度写到 stderr，这不代表失败 clack-kit 会在执行结果里保留原始 stdout 和 stderr，但 live task-log 会按可见日志展示它们
CLI 参数没有映射到步骤
依次检查
- createWorkflowCliBridge 是否接收了正确的 steps
- bridge.apply(cli) 是否执行了
- bridge.getInitialValues(parsed.options) 是否传给了 run
- 字段是否被 optionKey 或 parse 改名、改形
workflow 在取消时抛错
这是 run 和 runSafely 的行为差异
- run 在取消时抛错
- runSafely 在取消时返回 null
需要安静处理取消时，优先选 runSafely
相对路径解析不对
相对路径默认基于 projectRoot 解析，而 createWorkflowKit 用来设置它的字段现在叫 cwd
检查点包括
- createWorkflowKit 的 cwd
- command 的 cwd
- scriptFile 是否以项目根目录为基准书写