11 - 错误处理：弹性与降级

概述

智能体比普通应用更容易失败，因为它们编排了多个不可靠的步骤：

• LLM 调用（超时、资源限制、格式错误的输出、运行时异常）
• 工具执行（网络故障、无效输入、服务不可用）
• 工作流逻辑（策略拦截、部分完成、跨工具的依赖链）

标准化的错误分类体系

使用一小组带有稳定错误码和一致字段的错误类：

每个错误包含

• code：机器可读的稳定标识符（适合指标和告警）
• userMessage：展示给用户的安全、非技术性消息
• retryable：是否适合自动重试
• details：用于日志的结构化数据
• cause：原始错误（保留根本原因链）

分类与恢复策略

先标准化，再分类。 normalizeUnknownError 将任意抛出的值转换为 AppError。classifyError 添加 retryable 和 type。

典型的阶梯式恢复策略

将用户消息与调试信息分离

确定性演示与 SIMULATION

为了保持教学运行的可预测性，用户 ID u_999 和 u_777 由一个小的 SIMULATION 映射驱动：

• 文本中的 u_demo_workflow 触发 policy_guard
• SKIP_LLM_DEGRADED u_777 跳过 LLM，进入降级模式，并使用 u_777 使主工具和备用工具都以可复现的方式失败

为什么这种模式可扩展