> 本文是我开源项目 codeAgent（终端 AI 编程智能体）的系列第 2 篇，每天讲一个里面真实用到的技术点，全部附源码。
> 仓库：https://github.com/Harvil1/codeAgent

![请添加图片描述](https://developer.qcloudimg.com/http-save/yehe-11433786/28bfa2feb91e53864fec4b109daf8de8.png)

## 场景：最猝不及防的一种死法

长任务跑到第 30 轮，一个大工具结果塞进来，下一轮请求直接被 API 拒了：

> Error: prompt_too_long / maximum context length exceeded ...

此时最不能做的就是**把异常抛给用户**——前面 30 轮的工作全卡在半空。我的做法是修一条"紧急逃生通道"：识别它 → 立刻瘦身 → 马上重发，任务自己缓过来。

## 第一关：四家服务商，四种报错措辞

DeepSeek 说 `prompt_too_long`，OpenAI 说 `maximum context length`，还有 `context_length`、`too long` 各种变体。如果识别口径不统一，OpenAI 风格的错误会走普通失败重试——白烧一次熔断次数。

所以我全项目只认一个判定函数，源码在 `agent/context_compressor.py`：

```python
# PTL 错误识别的统一口径（四家服务商措辞全认）。此前三处各写各的
# 子集（摘要重试认 2 种、主循环认 3 种、丢条数计算认 4 种）——OpenAI
# 风格的 "maximum context length ..." 在摘要重试路径会被当普通失败，
# 白计一次熔断还降级规则总结。全项目判定一律走 is_prompt_too_long_error
_PTL_MARKERS = (
    "prompt_too_long", "context_length", "too long", "maximum context",
)


def is_prompt_too_long_error(err_str: str) -> bool:
    """判断一段错误文本是不是「输入超长」（PTL）。四家措辞口径统一。"""
    s = (err_str or "").lower()
    return any(kw in s for kw in _PTL_MARKERS)
```

教训藏在注释里：**错误分类这类"知识"必须收敛到一处**，三个地方各写一个子集版本，迟早有人只改一处。

## 第二关：紧急压缩函数（核心源码）

识别出来之后立刻瘦身重发。做法简单粗暴：**只留 system + 一条边界占位 + 最近 5 条消息**，其余的靠落盘的 transcript 快照找回。源码在 `agent/context_pipeline.py`：

```python
# 紧急压缩的两道保险默认值（config 可覆盖）：冷却窗口秒数 / 单会话次数上限
REACTIVE_COOLDOWN_SECONDS = 60
REACTIVE_MAX_PER_SESSION = 5


def reactive_compact(
    messages: list,
    *,
    session_state: CompressionSessionState,
    keep_recent: int = 5,
    cooldown_seconds: float = REACTIVE_COOLDOWN_SECONDS,
    max_per_session: int = REACTIVE_MAX_PER_SESSION,
    now_fn=time.time,
) -> Tuple[list, bool]:
    """紧急通道：API 报「对话超长」（prompt_too_long）时立刻调用。

    做法简单粗暴：只留 system + 一条说明占位 + 最后 keep_recent 条消息，
    其余全靠 transcript 文件找回。
    **可多次触发**：每次报错都可以再压，但有两道保险：
      1. 冷却窗口：距上次触发不足 cooldown_seconds 秒（默认 60s）→ 跳过
      2. 单会话上限：本场已触发 max_per_session 次（默认 5）→ 跳过
    """
    # 保护 1：冷却窗口
    now = now_fn()
    elapsed = now - session_state.reactive_last_at
    if session_state.reactive_count > 0 and elapsed < cooldown_seconds:
        logger.info(
            "reactive_compact 冷却中（距上次 %ds < %ds），跳过",
            int(elapsed), int(cooldown_seconds),
        )
        return messages, False

    # 保护 2：单会话上限
    if session_state.reactive_count >= max_per_session:
        logger.warning(
            "reactive_compact 达到单会话上限 %d 次，跳过",
            session_state.reactive_count,
        )
        return messages, False

    system, conv = _split_system(messages)
    keep = conv[-keep_recent:] if len(conv) > keep_recent else conv[:]
    placeholder = {
        "role": "user",
        "content": (
            # 边界前缀和大写统一：恢复侧 _truncate_at_last_compact_boundary
            # 只认 [COMPACT_BOUNDARY] 开头，reactive 的占位也得能被裁剪定位
            "[COMPACT_BOUNDARY]\n"
            "[紧急上下文压缩：API 返回 prompt_too_long，"
            f"已只保留最近 {len(keep)} 条消息。"
            "如 .transcripts/ 下有快照（latest.txt 指向最新一份）可 "
            "read_file 分段找回；无快照则被裁原文已不可恢复]"
        ),
    }
    new_conv = [placeholder] + keep
    new_conv = _fix_tool_call_pairs(new_conv)
    new_messages = _reassemble(system, new_conv)

    session_state.reactive_last_at = now
    session_state.reactive_count += 1
    return new_messages, True
```

## 这 60 行里藏了四个细节

**1. 为什么允许触发 5 次而不是 1 次？** 砍到只剩 5 条后，下一轮又来一个巨型工具结果，还会再超——所以留了多次触发的余地。但必须有冷却窗口（60 秒）+ 次数上限（5 次）两道闸，否则会陷入"压了又超、超了又压"的死亡循环，日志和账单一起爆炸。

**2. 占位消息以 `[COMPACT_BOUNDARY]` 开头。** 会话恢复时只认这个前缀来定位"历史上次压到哪"，紧急压缩和常规压缩共用同一套边界标记——**逃生通道也得上户口**，不然恢复逻辑找不到断点。

**3. `_fix_tool_call_pairs` 不能省。** 从中间砍消息，很容易把"模型要调工具"和"工具结果"切成两半——孤儿 tool_call 会让下一次请求直接被 API 拒掉（400）。砍完必须对账补配。

**4. 被砍的内容给了一条活路。** 压缩前完整对话已落盘 `.transcripts/`，占位消息里明确告诉模型：可以去读快照找回上下文。**丢的是上下文窗口里的位置，不是信息本身。**

## 小结

三句话带走：

1. 错误识别统一口径：四家服务商措辞全收进一个函数，全项目只认它
2. 紧急压缩 = 保 system + 边界占位 + 最近 5 条，立刻重发不断线
3. 两道保险（冷却 60s / 上限 5 次）防死亡循环，砍完修 tool_call 配对

下一篇讲它的上游：**四级上下文压缩怎么分层**——目标是让任务压根走不到"报超长"这一步（照样附源码）。

---

仓库在这，注释全中文，欢迎 Star ⭐：https://github.com/Harvil1/codeAgent

本文是我开源项目 codeAgent（终端 AI 编程智能体）的系列第 2 篇，每天讲一个里面真实用到的技术点，全部附源码。 仓库：https://github.com/Harvil1/codeAgent

任务跑一半，API 突然报“对话超长“断流：我给 Agent 修的紧急逃生通道

人工智能

编程语言

开发工具

codeAgent开源项目实战解析：应对API上下文超长错误，实现紧急压缩逃生通道。统一识别四家服务商报错，保留核心消息并重发，附完整源码与冷却保护机制。

代码解释

智能体

AI编程

DeepSeek

2026上云采购 | AI焕新·智启新局

tione

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

任务跑一半，API 突然报“对话超长“断流：我给 Agent 修的紧急逃生通道-腾讯云开发者社区-腾讯云

任务跑一半，API 突然报“对话超长“断流：我给 Agent 修的紧急逃生通道

任务跑一半，API 突然报“对话超长“断流：我给 Agent 修的紧急逃生通道

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐