. 概述

truncateHeadForPTLRetry 是压缩流程中的最终逃生口。当压缩请求本身因为长度超限返回 prompt‑too‑long 时这个函数会从头部丢弃最旧的消息，让重试得以继续。

为什么需要它 —— 使用者痛点

• 对话卡死：如果不丢掉旧消息。使用者会看到“对话太长，无法继续”的错误提示，整个会话陷入死循环。
• 无限重试循环：未移除上一次插入的标记会导致 groupMessagesByApiRound 把标记单独分组，重试时根本没有实际削减消息体积。
• 上下文关键性：使用者最关心的是最近的对话内容。老旧历史应当被安全舍弃，而不是让整个请求失败。

// compact.ts:- 注释 This is last‑resort escape hatch for CC—when compact request itself hits prompt‑too‑long,user is orwise stuck. Dropping oldest context is lossy but unblocks m. The reactive‑compact path has proper retry loop that peels from tail;this helper is dumb‑but‑safe fallback for proactive/manual path that wasn't migrated in bfdb472f's unification.

两种压缩方法的区别

方法	retry 机制	策略
Reactive compact	compactMessages.ts 中的完善 retry loop 从尾部逐层剥离	-
Proactive / Manual compact	调用 truncateHeadForPTLRetry 从头部丢弃最旧消息

. 函数签名

export function truncateHeadForPTLRetry(
messages: Message。// 要发给 LLM 的消息列表
ptlResponse: AssistantMessage,// 错误响应
): Message | null // null = 无法再丢弃了

. 完整执行流程

truncateHeadForPTLRetry
│ ├─ 步骤 1：移除上一次的 PTL_RETRY_MARKER ← 防循环
│ ├─ 步骤 2：groupMessagesByApiRound
│ │ └─ 若分组不足 → return null
│ ├─ 步骤 3：计算丢弃数量
│ │ ├─ 有 token gap → 精确计算
│ │ └─ 无 token gap → 丢 %
│ ├─ 步骤 4：至少保留 M 组 ← 保护底线
│ └─ 步骤 5：处理 role 顺序
│ ├─ 剩余以 assistant 开头 → 插入 PTL_RETRY_MARKER
│ └─ 否则 → 直接返回

. 各步骤详解 & 痛点对应方法

步骤 1：移除重试标记

const PTL_RETRY_MARKER = '';const input = messages?.，.type === 'user' &&
messages?.，.isMeta &&
messages?.，.message.content === PTL_RETRY_MARKER
messages.slice // 去掉旧标记
: messages.slice;// 保持原样复制一份

Pain point：If marker isn’t removed,each retry would only discard marker itself。leading to a zero‑progress loop.

步骤 2：按 API Round 分组

const groups = groupMessagesByApiRound;if return null;

The grouping logic ):

export function groupMessagesByApiRound: Message {
const groups: Message =;let current: Message =;let lastAssistantId: string | undefined;for {
if (
msg.type === 'assistant' &&
msg.message.id!== lastAssistantId &&
current.length> 0
) {
groups.push;current =，} else {
current.push;}
if lastAssistantId = msg.message.id;}
if groups.push;return groups;老实说，}

• Pain point：If groups are split mid‑tool chain,dropping a partial round would leave dangling {tool_use}/{tool_result}。 causing API validation errors.
• The round‑based grouping guarantees we only drop whole “conversation turns”,preserving tool integrity.

步骤 3：计算要丢弃的组数

A. 精确计算——有 token gap 时

const tokenGap = getPromptTooLongTokenGap;let dropCount = 0;if {
let accTokens = 0;for {
accTokens += roughTokenCountEstimationForMessages;// 粗略估算每组 token 数
dropCount++;if break，// 累计已覆盖缺口，即可停止
}
}

The helper ) extracts .

B. 保守比例——无 token gap 时

if {
const MINDROPPERCENT = .25;// 至少丢掉25%
const MINGROUPSTO_DROP = Math.max);其实，dropCount = Math.max;}

• Pain point：If we only drop a tiny fraction without concrete size info,we may need many retries before finally fitting under limit.
• The fallback drops a reasonable percentage to reduce retry count while staying safe.

步骤 4：保底 – 至少保留 M 组

const MINREMAININGGROUPS = 1;// 必须留下至少一轮完整上下文

dropCount = Math.min;

if return null;// 已经没有可保留的组，终止重试

This protects against completely wiping out conversation history。which would orwise render summarisation impossible and leave users with an opaque error.

步骤 5：处理 role 顺序 & 插入标记

const sliced = groups.slice.flat;

if { return;} return sliced;

• The OpenAI API requires first message to be a {role:'user'}. After dropping whole rounds,it’s possible new first element is an assistant reply – causing a validation error.
• The inserted meta user message both satisfies API contract and serves as a visible hint that older context was trimmed.
• This also solves “assistant‑first” pain point that developers often encounter during debugging.

. 完整调用上下文 & 重试循环

调用位置

The function appears in two places inside compactConversation。handling both proactive and manual compaction paths:

// proactive compact 方法 if ) { const truncated = truncateHeadForPTLRetry;if { messagesToSummarize = truncated;continue，// 重试一次新的请求 } }

整体重试流程图

compactConversation │── 发起 LLM 请求 │ ├── 成功 → 使用摘要并结束 │ └── PromptTooLong → │ truncateHeadForPTLRetry │ ├── 返回 Message → 发起请求 │ └── 返回 null → 抛出 ERRORMESSAGEPROMPTTOOLONG 给前端使用者 └── 最终返回错误提示或成功摘要

. 主要常量表

值用途 PTL_RETRY_MARKER作为元信息插入到消息列表中。以标记已裁剪的历史" ERROR_MESSAGE_PROMPT_TOO_LONG当所有可裁剪组都已用尽仍无法通过时向使用者展示的错误信息" MIN_REMAINING_GROUPS保证至少保留一轮完整对话，以免摘要失效" MIN_DROP_PERCENT在缺乏 token gap 信息时保守删除的比例" "

. 主要设计要点 & 痛点对应说明

为什么从头部删而不是尾部？

• User Pain Point – “我想保留最近几条对话，因为它们决定当前上下文”。说起来，从头部删除最旧记录符合这一需求。
• The reactive path drops from tail because it aims to find * minimal* subset that fits by halving – suitable when you can afford losing recent context but want to keep as much as possible. Proactive/manual paths prioritize recency over completeness.

有损但安全的兜底方案

• ✔ 有损：Losing old messages means y won’t appear in summary – accepted trade‑off when orwise stuck.
• ✔ 安全：No scenario where all messages are removed;at least one group remains ensuring a valid request.
• ✔ Pain point mitigation:
  • If you repeatedly see “conversation too long” despite retries – check wher `MIN_REMAINING_GROUPS` or `MIN_DROP_PERCENT` need tuning for your model’s token limits.
  • If summaries miss crucial historical context – consider persisting old rounds elsewhere instead of discarding permanently.

  }

  为何使用最低 % 丢弃策略？

  The percentage acts as a safety net when precise token counts are unavailable. Dropping too little may cause many rapid retries and degrade performance;dropping too much could erase valuable recent context. A quarter of groups strikes a pragmatic balance for typical OpenAI models .

  If your model’s limit differs dramatically,you can adjust #MIN_DROP_PERCENT#​\=​0.​10​\)

  ---

常量名
''			'Conversation too long. Press esc twice...'			1			0.25

---