Context Recovery

上下文保护与恢复

Token 预算

预算不只统计 messages[].content，还包括 system、tools、嵌套工具结果和预留输出。图片 Base64 使用有界占位估算，避免图片编码本身把 Token 估算撑爆。

safe output budget = hardLimit - safetyMargin - estimated input

默认发布配置使用较保守的阈值：

• compactThreshold: 90,000
• hardLimit: 130,000
• responseReserve: 12,000
• safetyMargin: 8,000
• toolResultClearTrigger: 80,000
• toolResultClearTarget: 65,000

这些值是代理的安全阈值，不代表模型真实 context window 只有 130k。

Agent 请求为什么不能通用压缩

Agent 请求含有 tools、tool_use、tool_result、function_call 或对应输出。通用摘要会改变角色、消息位置和 ID 配对，所以 Agent 请求只允许：

1. 保持所有消息位置和工具 ID。
2. 将旧 tool_result.content 替换成明确占位文本。
3. 保留最近配置数量的工具结果。
4. 交给 Claude 原生 compact。

上游 400 救援

flowchart TD
    Error[上游 context limit 400] --> Parse[解析 limit input output]
    Parse --> Type{Agent 请求}
    Type -->|否| Compact[压缩普通消息]
    Compact --> Reduce[重新计算并降低输出预算]
    Reduce --> Retry[重试一次]

    Type -->|是| ClearOld[阶段一 清除旧工具结果 保留最新一条]
    ClearOld --> Fit{已达到目标预算}
    Fit -->|是| Retry
    Fit -->|否| TrimLatest[阶段二 裁剪最新结果中段]
    TrimLatest --> Preserve[保留头部 尾部 tool use id 和位置]
    Preserve --> Retry
    Retry --> Done{成功}
    Done -->|是| Return[返回恢复后的响应]
    Done -->|否| Replay[返回上游错误 不再循环]

Loading

最新结果中的提示明确要求模型利用保留的头尾，不要仅因为中段被裁剪就重复调用同一工具。

Stateless 分块

只有不含 Agent 工具协议的请求可以通用分块。每个块都必须低于 hard cap；所有块完成后生成一个不重新注入完整原始消息的 synthesis request。综合阶段同样支持一次上下文错误恢复。

Compact 提醒

compactMode=warn 会在支持的 JSON 或 SSE 响应末尾加入 /compact 提醒。当前 SSE 实现会先读取完整流再改写，功能正确但会损失实时输出，这是生产级路线图中的待改进项。