Appearance
最佳实践
这页不讲功能清单，只讲更稳的写法
先用最小模型起步
第一版 workflow 只保留必要步骤
- 少量输入
- 明确顺序
- 简单返回值
history、checkpoint、logs、plugins 都在确认收益后再加
step id 要稳定、可读、可长期维护
推荐把 id 当成长期接口来命名
- 用业务词，不用临时缩写
- 避免今天叫 svc，明天改成 service
- 同名步骤只在 when 互斥时使用
输入和值快照尽量分层
经验上更稳的做法是
- values 保存会参与摘要和复用的输入
- results 保存命令或步骤产物
不要把所有中间态都塞进 values，否则快照和历史会越来越脏
command 步骤尽量单一职责
一条 command 步骤里只处理一类动作，后续维护最轻
- 安装依赖是一条
- 构建产物是一条
- 发布镜像是一条
只有在上下文共享价值明显时，才把多条命令收进同一个 run(context, io)
并行只用于真正独立的任务
parallel 组适合彼此无依赖、互不覆盖结果的步骤
如果三条命令之间存在前后顺序或共享产物，串行会更安全
把 CLI 参数映射和步骤定义放在一起
这样最不容易出现字段漂移
当 step id、option 名和 parse 逻辑分散在多个文件里时，维护成本会明显上升
把模板和插件职责分开
- 模板解决结构复用
- 插件解决运行时能力复用
这两个维度混在一起后，调试通常会变慢
让日志有足够上下文
开启 logs 后，适当使用 meta、workflow.log 和结构化事件，回看价值会高很多
日志不是越多越好，而是要能回答“这次运行为什么这样结束”