智能工作流故障的定位证据
工作流失败时，只保存最后一条报错通常不够。一个“调用失败”可能来自用户输入不符合约束、提示词版本变更、模型响应无法解析、工具权限不足，或外部服务超时。排查要能回答三个问题：问题发生在哪个节点，输入和配置处于什么状态，是否可以在安全环境中复现。没有这些信息，团队往往只能反复猜测和重试。
为每次运行建立最小证据链
每次执行应有运行标识，并记录开始与结束时间、工作流版本、节点名称、节点耗时、工具状态和最终结果类别。对需要排队的任务，额外记录等待时间；否则很容易把队列拥堵归到模型或检索上。输入本身不必完整存储：可以保存长度、格式、来源类型、经过脱敏的摘要或可受控访问的加密引用。授权头、Cookie、完整个人内容和密钥不应出现在普通日志里。
配置版本也很重要。模型标识、提示词模板、schema、检索索引版本和工具版本只要有一项变化，结果就可能不同。把它们与运行标识关联，才能比较发布前后的失败模式。对于人工介入步骤，记录操作者采取的是重试、修改参数、跳过节点还是撤销结果，而不是把人的行为当成不可见的补丁。
运行标识 → 版本信息 → 节点事件 → 工具结果 → 脱敏诊断材料 → 处理结论证据链不等于无限收集。应根据故障排查需要设定字段、访问权限和保留期限。调试开关只能在受控范围内开启，过期后自动关闭；若需要将材料交给外部支持人员，先去除用户标识和内部地址。这样既能复查，也不会把可观测性变成新的数据风险。
先分类，再用最小样本重放
收到失败报告后，先看它是否集中在某类输入、某个租户、某次部署或某个工具版本。接着选择最小的脱敏样本重放，而不是把生产会话原样搬到开发环境。重放时固定工作流版本、模型设置和依赖替身，逐节点确认差异从哪里开始出现。若问题无法复现，也要记录已验证的条件和缺失的证据，避免下一位排查者重复相同尝试。
外部工具不可用时，模拟返回应覆盖超时、权限拒绝、格式错误和部分成功等情况。不要只为“成功路径”准备 mock，否则故障一到线上才会发现编排没有处理异常。对写入型工具，重放环境必须使用隔离账户和可清理数据，防止排查本身制造新的业务记录。
修复需要可验证的退出条件
修复前先定义要改变的现象，例如某类解析错误应给出明确提示、某个工具超时后应停止后续步骤、或重试不再产生重复写入。补上对应的单元、集成或端到端测试，并让测试使用真实的失败边界，而非只断言函数被调用。若涉及提示词或模型调整，比较一组固定样本，检查是否同时伤害了其他任务。
上线时记录变更范围、灰度方式和回滚入口。配置开关、旧版本工件和数据迁移的限制都应写清楚；不能回滚的状态操作需先做额外确认。发布后观察一段时间的失败类型与人工接管情况，确认问题确实减少，而不是被新的兜底逻辑隐藏。
好的故障记录最终会变成团队的工作资料：哪些字段足以定位、哪些信息不能留、哪种边界应自动测试、何时需要人工处理。它不保证每次都能迅速找到答案，但能让每一次排查留下下一次可用的证据。
