失败分流、降级与人工接管¶
- 沉淀时间：2026-09-09
- 来源：IJZKZE / PR #2；IK37HX / PR #5 与补丁
8aab330 - 成熟度：
confirmed - 适用范围：包含模型调用、环境检查、数据库执行和自动验证的 Agent 工作流
先按失败类型分流¶
不同失败不能共用一个 fallback：
| 失败 | 自动动作 | 原因 |
|---|---|---|
| 主模型连接、超时、非 200 或异常响应 | 请求已配置的备用模型 | 输入与验证链未改变，替换执行服务仍可保持调用契约 |
| Python 运行环境缺失 | 暂停并让用户提供可用解释器或修复环境 | Agent 猜 venv、联网安装或改软链会扩大破坏面 |
| SQL baseline / execute 超时 | 进入人工处理终态 | EXPLAIN-only 不能替代真实性能与结果一致性验证 |
| 结果不一致或证据缺失 | 标记功能风险，禁止正优化 | 性能收益不能覆盖语义风险 |
| 主模型和备用模型都失败 | 返回明确错误并终止 | 继续生成会制造无来源结论 |
环境契约¶
运行时只接受明确的解释器路径，例如系统 python3 或用户配置的 SQL_OPT_PYTHON。环境检查脚本返回结构化诊断和下一动作；Agent 不扫描任意 venv、不联网安装、不修改 pyvenv.cfg 或软链。
人工接管要带完整信息¶
人工接管输出至少包含：
- case 与停止阶段；
- 错误类别和最后一次失败；
- 已生成、未生成的证据文件；
- 是否执行过数据库写操作；
- 可以安全继续的选项；
- 明确说明当前没有产生可交付优化结论。
反模式¶
- 环境失败后自动退化成“模型优化但未验证”，仍输出正式 result。
- SQL 超时后用 EXPLAIN 结果冒充性能验证。
- 无限重试同一 provider 或重复派发子 Agent。
- 把所有异常归入同一个“失败”状态，导致无法恢复或审计。
限制¶
自动切换备用模型要求主备接口兼容，并应记录实际使用的模型。硬编码模型和超时阈值是已知技术债，应迁移到配置层。