Error Recovery - 错误恢复机制

三种错误类型#

恢复路径对比#

恢复优先级：max_tokens → prompt_too_long → connection error → fail gracefully。

为什么这个顺序？

• max_tokens 最容易恢复（只需继续输出），成本最低
• prompt_too_long 需要压缩（改变历史），成本较高
• connection error 是外部问题，等待可能恢复
• 优雅失败是最后兜底

验证你的理解#

Q1：为什么 max_tokens 恢复优先级最高？

:::details 答案 成本最低，最容易恢复。

max_tokens 只需注入续写消息，不改变历史，不丢失信息。

prompt_too_long 需要压缩历史，丢失细节，成本较高。

connection error 需要等待，时间成本中等。

恢复优先级原则：低成本优先恢复，高成本最后尝试。 :::

续写消息设计#

1
CONTINUATION_MESSAGE = (
2
    "Output limit hit. Continue directly from where you stopped -- "
3
    "no recap, no repetition. Pick up mid-sentence if needed."
4
)
5

6
def handle_max_tokens(messages: list) -> list:
7
    max_output_recovery_count += 1
8

9
    if max_output_recovery_count <= 3:
10
        messages.append({"role": "user", "content": CONTINUATION_MESSAGE})
11
        return messages  # 继续循环
12
    else:
13
        print("Max output recovery attempts exhausted")
14
        return None  # 停止

设计要点：

• 不重述：“no recap, no repetition”——不让模型浪费时间复述已输出内容
• 直接续写：“Continue directly from where you stopped”——从中断处接着写
• 中断点续写：“Pick up mid-sentence if needed”——允许句子中间继续

为什么不重述？#

类比：笔写到一半没墨了，换笔继续写——不是从头重写。

验证你的理解#

Q2：CONTINUATION_MESSAGE 为什么强调”no recap”？

:::details 答案 防止模型浪费时间重述已输出内容。

如果让模型重述：

1. 已输出内容再次输出 → token 浪费
2. 可能再次触发 max_tokens → 进入恶性循环
3. 用户看到重复内容 → 体验差

直接续写设计：从中断点继续，不浪费 token，高效恢复。 :::

auto_compact 实现#

1
def auto_compact(messages: list) -> list:
2
    # 1. 提取对话历史（截断到80000字符）
3
    conversation_text = json.dumps(messages)[:80000]
4

5
    # 2. 调用LLM生成摘要
6
    prompt = """Summarize this conversation for continuity. Include:
7
    1) Task overview and success criteria
8
    2) Current state: completed work, files touched
9
    3) Key decisions and failed approaches
10
    4) Remaining next steps"""
11

12
    summary = call_llm(prompt + conversation_text)
13

14
    # 3. 返回续接消息
15
    return [{"role": "user", "content": f"Compacted.\n{summary}"}]

摘要四要素#

复用 L06 设计：auto_compact 的摘要四要素与 L06 连续性5要素一致——复用已有机制。

优雅降级#

1
# 失败时优雅降级
2
except Exception:
3
    return [{"role": "user", "content": "Previous context lost. Please restate your current task."}]

设计原则：即使摘要失败，也不崩溃——告诉用户上下文丢失，让用户重新陈述。

验证你的理解#

Q3：auto_compact 摘要为什么要包含”失败尝试”？

:::details 答案 防止模型重复错误方向。

如果摘要丢失”失败尝试”：

1. 模型恢复后不知道哪些方向已失败
2. 可能重复尝试错误方向
3. 时间浪费，效率下降

摘要包含”失败尝试”：让模型知道哪些路不通，避免重复错误。 :::

指数退避设计#

1
def backoff_delay(attempt: int) -> float:
2
    delay = min(1.0 * (2 ** attempt), 30.0)  # 指数增长，上限30秒
3
    jitter = random.uniform(0, 1)            # 加入随机抖动
4
    return delay + jitter

退避序列#

设计要点：

• 指数增长：1s → 2s → 4s，避免短时间大量重试
• 上限30秒：防止等待过长
• 随机抖动：防止多客户端同步重试

为什么需要 jitter？#

问题：多客户端同时遇到错误 → 同时重试 → 同时冲击服务器 → 惊群效应。

解决：jitter 让每个客户端等待时间不同 → 错开重试时间 → 避免同步冲击。

类比：缓存击穿防护——多个请求同时发现缓存失效 → 同时查询数据库 → 数据库压力爆炸。jitter 错开请求时间。

验证你的理解#

Q4：为什么 jitter 能防止惊群效应？完整链条是什么？

:::details 答案 jitter 错开多客户端重试时间，避免同步冲击服务器。

没有 jitter 的链条：

1. 多客户端同时遇到错误
2. 同时计算 backoff_delay（attempt相同 → delay相同）
3. 同时等待相同时间
4. 同时重试 → 服务器压力爆炸

有 jitter 的链条：

1. 多客户端同时遇到错误
2. 同时计算 backoff_delay
3. 但 jitter 不同（随机0-1s）
4. 等待时间错开（1-2s, 1.5-2.5s, 0.8-1.8s）
5. 重试时间错开 → 服务器压力分散

类比：缓存击穿防护——随机过期时间错开请求。 :::

与后续课程的关系#

核心洞察：Error Recovery 是”错误可恢复”的机制。理解 L11，就理解了 Agent 如何”分类错误再恢复”。后续课程都在扩展恢复机制——保护长任务、注入提示。

L11 核心概念的理解升级路径#

如何检验你达到了 L2？#

用这个问题自测：

为什么恢复机制要有预算限制（最多3次），而不是无限重试？

:::details L2 层级回答 有限重试是设计决策——不是无限循环。

理由：

1. 资源预算：无限重试会消耗 token 和时间，可能永远无法完成
2. 用户反馈：重试3次后仍失败，说明问题可能需要用户介入
3. 优雅失败：暴露失败原因，让用户决定下一步（修改配置、换模型、简化任务）

类比：TCP 重传上限——不是无限重传，超过上限就放弃连接。网络协议同样采用有限重试策略。 :::

本章目标：让每个核心概念都从 L0 升级到 L2。理解 L11，不只是记住三种恢复路径，而是掌握”如何分类错误再恢复”的设计原则。

Error Recovery 主流程#

恢复状态机#

choose_recovery 决策树#

三种恢复策略对比#