当 workflow 进入生产，最大的风险不是“当前版本不够好”，而是“改版时把在跑任务切断”。
生产环境里最危险的不是发布失败，而是“看起来发布成功，实际把一部分在跑任务切断”。
版本迁移的核心原则
- 新旧版本并存，不做瞬时替换
- 在跑任务按原版本收敛
- 新任务按灰度策略进入新版本
这三条是底线，不是最佳实践可选项。
迁移策略对比
| 策略 | 优点 | 风险 | 适用阶段 |
|---|---|---|---|
| big bang | 操作简单 | 风险最高 | 仅早期低风险系统 |
| dual-run | 对比充分 | 成本较高 | 关键升级前验证 |
| traffic-split | 渐进稳定 | 需完善观测 | 生产默认方案 |
对 agent workflow，默认应优先 traffic-split + rollback。
迁移窗口设计
建议引入“兼容窗口”概念：
- T0-T7：新旧并行，旧版本可创建新 run。
- T7-T14：旧版本只允许在跑任务收敛，不再接新 run。
- T14+：确认清空后执行硬废弃。
这样能避免“版本切换日就是事故日”。
节点变更规则
| 变更类型 | 建议动作 |
|---|---|
| 新增节点 | 向后兼容，默认可选 |
| 字段重命名 | 保留映射层，附回归样本 |
| 删除节点 | 先软废弃，再硬删除 |
| 策略变更 | 灰度发布并监控命中率 |
删除节点时最容易忽略的是在跑任务的恢复链路。
失败案例：节点删除导致在跑任务中断
某团队删除旧节点并上线新图，结果旧版本 run 在恢复时找不到节点定义，任务全部失败重试，主队列瞬间拥堵。
修复动作：
- 节点进入软废弃状态，保留恢复能力。
- 为旧版本 run 提供兼容适配层。
- 新增“在跑任务数”为发布门禁指标。
回滚机制应提前演练
回滚不是“发布失败后再想方案”。建议每次重大迁移前演练：
- 配置回滚
- 路由回滚
- 数据兼容回滚
没有演练过的回滚，线上通常回不去。
关键指标
- 新旧版本成功率差异
- 在跑任务跨版本恢复成功率
- 迁移期回滚触发次数
- 兼容适配层命中率
适配层命中率长期高，说明迁移进程卡住，应主动清理而非长期拖延。
迁移前必须盘点的内容
| 盘点项 | 为什么重要 |
|---|---|
| 在跑 run 数量 | 决定兼容窗口长度 |
| 节点依赖关系 | 判断删除或替换影响范围 |
| 策略命中率 | 评估新旧规则差异 |
| 人工节点负载 | 避免迁移期积压 |
| 回滚数据路径 | 确认真的能回退 |
没有这张盘点表，迁移计划基本是在赌。
Dual-run 应该比较什么
双跑不是看“结果是否一样”这么简单。建议比较：
- 节点路径是否变化
- 工具调用次数是否变化
- 高风险策略命中是否变化
- 成本是否变化
- 人工接管点是否变化
有些新版本结果更好，但成本翻倍；有些成本更低，但人工接管率上升。这些都要在放量前看见。
对业务方的变更沟通
工作流迁移通常会影响业务预期。上线前至少说明：
- 哪些任务会进入新版本
- 哪些任务仍按旧版本收敛
- 可能出现的行为变化
- 出问题时回退需要多久
这不是形式主义。业务方提前知道迁移边界，才能在异常反馈时给出有效信息，而不是只说“今天 agent 变奇怪了”。
Checklist
- workflow 配置有明确版本号
- 在跑任务绑定固定版本并可恢复
- 迁移期间支持双版本观测
- 回滚策略可分钟级执行并已演练
- 节点废弃遵循软删除窗口
- 迁移门禁包含在跑任务指标
延伸阅读：
