signal-layer-labs/workflow-failure-library

# Workflow 失败库 一个关于 AI workflow、自动化和生产系统中失败模式的实用库。 本仓库记录了运维 workflow 在真实世界运行后，出现的那些可识别的失败方式。它旨在帮助构建者诊断故障、改进系统设计，并分享实用经验，而无需将每个问题都转化为一个新框架。 ## 适用人群 本库面向正在构建包含以下内容的系统的工程师、运维人员、产品团队、支持团队和技术创始人： - AI workflow 和 agentic flow - 自动化和编排 - tool-calling 系统 - human-in-the-loop 运维 - 生产级 API 和外部提供商 - 可靠性和可观测性实践 重点关注运维层面的清晰度：什么出错了、它是如何表现的、为什么会发生，以及团队可以采取什么应对措施。 ## 为什么 workflow 失败很重要 现代 workflow 通常跨越模型、工具、队列、数据库、用户界面、审批和外部服务。当某个步骤中的小错误被重试、隐藏、延迟，或被后续步骤错误解释时，就会变得难以诊断。 失败模式为团队提供了用于故障回顾和设计讨论的通用语言。它们有助于将诸如“agent 失败了”这类模糊的表述，转化为具体的观察结果，例如“workflow 在没有幂等性的情况下重试了一个超时的 tool call，并创建了重复的下游操作”。 ## 这与 Production AI Checklists 有何不同 - Checklist 帮助你在发布前做好准备。 - 失败模式帮助你在系统运行后识别并诊断问题。 - 这两个代码库应该随着时间的推移互相建立链接。 `production-ai-checklists` 关注的是就绪性、预防以及在发布前需要验证的内容。本仓库关注的是诊断、故障经验教训，以及系统面对真实用户、真实数据和真实依赖后出现的运维模式。 ## 如何使用本库 在以下场景中，请使用 [`failures/`](failures/) 目录中的条目： - 架构审查 - 故障分析 - workflow 设计 - 可观测性规划 - 支持和升级审查 - 复盘 - 生产就绪度讨论 每种失败模式都包含摘要、症状、原因、示例场景、运维影响、缓解措施、预防清单、可观测性信号以及相关失败模式。 从看起来与你所遇情况最接近的失败模式开始，然后跟随相关链接。许多真实的故障往往涉及多种失败模式。 ## 挑战 挑战是一些简短的运维场景，旨在帮助构建者练习故障分析、可观测性思维和 workflow 可靠性设计。 利用它们在生产环境发生故障前练习诊断 workflow 失败： - [001 - Retry 风暴](challenges/001-retry-storms.md) - [002 - 人工交接失败](challenges/002-human-handoff-failure.md) - [003 - 缺失审计追踪](challenges/003-missing-audit-trail.md) ## 当前的失败模式 | 失败模式 | 主题 | 简短描述 | 链接 | | --- | --- | --- | --- | | Context 漂移 | 上下文与状态 | Workflow 决策使用了陈旧的、累积的或已更改的上下文。 | [查看](failures/context-drift.md) | | 状态不同步 | 上下文与状态 | UI、数据库、队列、工具或外部系统对状态的认识不一致。 | [查看](failures/state-desynchronization.md) | | Retry 风暴 | 重试与超时 | 不受控的重试导致重复工作、成本激增或下游压力。 | [查看](failures/retry-storms.md) | | 工具超时级联 | 重试与超时 | 超时的 tool call 触发重试或导致跨步骤的依赖性失败。 | [查看](failures/tool-timeout-cascades.md) | | 人工交接失败 | 人工审查 | 向人工的升级流程不明确、延迟、缺失或结构不合理。 | [查看](failures/human-handoff-failures.md) | | 审批循环崩溃 | 人工审查 | 审批流程被跳过、卡住、重复或被误解。 | [查看](failures/approval-loop-breakdowns.md) | | 缺失审计追踪 | 可观测性 | 团队无法重现发生了什么、为什么发生，或是触发了什么操作。 | [查看](failures/missing-audit-trail.md) | | 静默失败传播 | 可观测性 | 隐藏的失败导致后续步骤基于错误的假设执行。 | [查看](failures/silent-failure-propagation.md) | | 模糊的工具选择 | 提供商与依赖 | Agent 或 workflow 由于边界不清而选择了错误的工具。 | [查看](failures/ambiguous-tool-selection.md) | | 提供商不稳定 | 提供商与依赖 | 外部 AI、API 或服务的不稳定降低了 workflow 的表现。 | [查看](failures/provider-instability.md) | ## Signal Layer Labs 理念 Signal Layer Labs 专注于运维 AI：workflow、编排、自动化、可靠性、可观测性，以及将真实系统推向生产所需的系统思维。 我们相信，实用的文档应该帮助团队在真实的约束条件下做出更好的决策。本库避免了炒作和模糊的警告。它旨在为构建者实际遇到的失败命名，描述它们是如何表现出来的，并让缓解措施的讨论变得更加容易。

标签：AI工程, API集成, 事故复盘, 可观测性, 故障诊断, 生产环境运维, 系统可靠性, 网络安全研究, 防御加固