三方上下文压缩机制对比 · 金字塔结构 + 完整源码

// 来源: claude-code · src/utils/forkedAgent.ts:46-103(节选)
/**
 * Parameters that must be identical between the fork and parent API requests
 * to share the parent's prompt cache. The Anthropic API cache key is composed of:
 * system prompt, tools, model, messages (prefix), and thinking config.
 */
export type CacheSafeParams = {
  systemPrompt: SystemPrompt
  userContext: { [k: string]: string }
  systemContext: { [k: string]: string }
  toolUseContext: ToolUseContext
  forkContextMessages: Message[]
}
// maxOutputTokens 文档警告:
//   CAUTION: setting this changes both max_tokens AND budget_tokens (via clamping
//   in claude.ts). If the fork uses cacheSafeParams to share the parent's prompt
//   cache, a different budget_tokens will invalidate the cache — thinking config
//   is part of the cache key. Only set this when cache sharing is not a goal.

// 来源: claude-code · src/services/api/promptCacheBreakDetection.ts:684-698
/**
 * Call after compaction to reset the cache read baseline.
 * Compaction legitimately reduces message count, so cache read tokens
 * will naturally drop on the next call — that's not a break.
 */
export function notifyCompaction(querySource: QuerySource, agentId?: AgentId): void {
  const key = getTrackingKey(querySource, agentId)
  const state = key ? previousStateBySource.get(key) : undefined
  if (state) {
    state.prevCacheReadTokens = null
  }
}

// 来源: codex · codex-rs/core/src/compact.rs:309-324
Err(e) if matches!(e.details(), CodexErrorDetails::ContextWindowExceeded) => {
    if turn_input_len > 1 {
        // Trim from the beginning to preserve cache (prefix-based) and keep recent messages intact.
        error!("Context window exceeded while compacting; removing oldest history item. Error: {e}");
        history.remove_first_item();
        retries = 0;
        continue;
    }
    // ... 只剩一项仍超限则报错 ...
}

// 来源: codex · codex-rs/core/src/compact.rs:260-264
let mut client_session = sess.services.model_client.new_session();
// Reuse one client session so turn-scoped state (sticky routing, websocket incremental
// request tracking)
// survives retries within this compact turn.

// 来源: pi · packages/coding-agent/src/core/compaction/compaction.ts:562-581
export async function completeSummarization(
	model: Model<any>, context: Context, options: SimpleStreamOptions,
	streamFn?: StreamFn, retry?: RetryPolicy, callbacks?: RetryCallbacks,
): Promise<AssistantMessage> {
	// Summaries are standalone requests, so isolate routing and avoid cache writes that cannot be reused.
	const requestOptions: SimpleStreamOptions = {
		...options,
		cacheRetention: "none",
		sessionId: uuidv7(),
	};
	const produce = async (): Promise<AssistantMessage> =>
		streamFn
			? (await streamFn(model, context, requestOptions)).result()
			: completeSimple(model, context, requestOptions);
	return retryAssistantCall(produce, retry, requestOptions.signal, callbacks);
}

// 来源: pi · compaction.ts:308-321
function isCutPointMessage(message: AgentMessage): boolean {
	switch (message.role) {
		case "user":
		case "assistant":
		case "bashExecution":
		case "custom":
		case "branchSummary":
		case "compactionSummary":
			return true;
		case "toolResult":
			return false; // must follow their tool call
	}
	return false;
}

// 来源: pi · compaction.ts:403-461
export function findCutPoint(
	entries: SessionEntry[], startIndex: number, endIndex: number, keepRecentTokens: number,
): CutPointResult {
	const cutPoints = findValidCutPoints(entries, startIndex, endIndex);
	if (cutPoints.length === 0) {
		return { firstKeptEntryIndex: startIndex, turnStartIndex: -1, isSplitTurn: false };
	}
	// Walk backwards from newest, accumulating estimated message sizes
	let accumulatedTokens = 0;
	let cutIndex = cutPoints[0];
	for (let i = endIndex - 1; i >= startIndex; i--) {
		const entry = entries[i];
		const messageTokens = sessionEntryToContextMessages(entry).reduce(
			(sum, message) => sum + estimateTokens(message), 0);
		if (messageTokens === 0) continue;
		accumulatedTokens += messageTokens;
		if (accumulatedTokens >= keepRecentTokens) {
			for (let c = 0; c < cutPoints.length; c++) {
				if (cutPoints[c] >= i) { cutIndex = cutPoints[c]; break; }
			}
			break;
		}
	}
	// Scan backwards to include adjacent metadata entries that do not affect context.
	while (cutIndex > startIndex) {
		const prevEntry = entries[cutIndex - 1];
		if (prevEntry.type === "compaction" || sessionEntryToContextMessages(prevEntry).length > 0) break;
		cutIndex--;
	}
	const cutEntry = entries[cutIndex];
	const startsTurn = isTurnStartEntry(cutEntry);
	const turnStartIndex = startsTurn ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
	return { firstKeptEntryIndex: cutIndex, turnStartIndex, isSplitTurn: !startsTurn && turnStartIndex !== -1 };
}

// 来源: pi · branch-summarization.ts:108-146
export function collectEntriesForBranchSummary(
	session: ReadonlySessionManager, oldLeafId: string | null, targetId: string,
): CollectEntriesResult {
	if (!oldLeafId) return { entries: [], commonAncestorId: null };
	// Find common ancestor (deepest node that's on both paths)
	const oldPath = new Set(session.getBranch(oldLeafId).map((e) => e.id));
	const targetPath = session.getBranch(targetId);
	let commonAncestorId: string | null = null;
	for (let i = targetPath.length - 1; i >= 0; i--) {
		if (oldPath.has(targetPath[i].id)) { commonAncestorId = targetPath[i].id; break; }
	}
	// Collect entries from old leaf back to common ancestor
	const entries: SessionEntry[] = [];
	let current: string | null = oldLeafId;
	while (current && current !== commonAncestorId) {
		const entry = session.getEntry(current);
		if (!entry) break;
		entries.push(entry);
		current = entry.parentId;
	}
	entries.reverse(); // chronological
	return { entries, commonAncestorId };
}

// 来源: codex · codex-rs/core/src/compact.rs:56, 624-685(节选)
const COMPACT_USER_MESSAGE_MAX_TOKENS: usize = 20_000;

fn build_compacted_history_with_limit(
    mut history: Vec<ResponseItem>,
    user_messages: &[CompactedUserMessage],
    summary_text: &str,
    max_tokens: usize,
) -> Vec<ResponseItem> {
    let mut selected_messages: Vec<CompactedUserMessage> = Vec::new();
    if max_tokens > 0 {
        let mut remaining = max_tokens;
        for message in user_messages.iter().rev() {          // 从新往旧
            if remaining == 0 { break; }
            let tokens = approx_token_count(&message.message);
            if tokens <= remaining {
                selected_messages.push(message.clone());
                remaining = remaining.saturating_sub(tokens);
            } else {
                let truncated = truncate_text(&message.message, TruncationPolicy::Tokens(remaining));
                selected_messages.push(CompactedUserMessage { message: truncated, .. });
                break;
            }
        }
        selected_messages.reverse();
    }
    for message in &selected_messages {
        history.push(ResponseItem::Message { role: "user".to_string(), /* ... */ });
    }
    // 末尾追加摘要(空则 "(no summary available)")
    history.push(ResponseItem::Message { role: "user".to_string(),
        content: vec![ContentItem::InputText { text: summary_text.into() }], /* ... */ });
    history
}

// 来源: claude-code · src/services/compact/compact.ts:243-291(节选)
export function truncateHeadForPTLRetry(
  messages: Message[], ptlResponse: AssistantMessage,
): Message[] | null {
  const groups = groupMessagesByApiRound(input);
  if (groups.length < 2) return null;
  const tokenGap = getPromptTooLongTokenGap(ptlResponse);
  let dropCount: number;
  if (tokenGap !== undefined) {
    let acc = 0; dropCount = 0;
    for (const g of groups) { acc += roughTokenCountEstimationForMessages(g); dropCount++; if (acc >= tokenGap) break; }
  } else {
    dropCount = Math.max(1, Math.floor(groups.length * 0.2)); // 丢 20%
  }
  dropCount = Math.min(dropCount, groups.length - 1); // 至少留 1 组
  const sliced = groups.slice(dropCount).flat();
  if (sliced[0]?.type === 'assistant') {
    return [createUserMessage({ content: PTL_RETRY_MARKER, isMeta: true }), ...sliced];
  }
  return sliced;
}

// 来源: codex · codex-rs/core/src/tasks/compact.rs:36-78
if ctx.config.features.enabled(Feature::TokenBudget) {
    crate::compact_token_budget::run_manual_compact_task(session, ctx).await?;   // 纯丢弃
    return Ok(None);
}
let result = if crate::compact::should_use_remote_compact_task(ctx.provider.info()) {
    if ctx.config.features.enabled(codex_features::Feature::RemoteCompactionV2) {
        crate::compact_remote_v2::run_remote_compact_task(session.clone(), ctx).await   // 服务端流式
    } else {
        crate::compact_remote::run_remote_compact_task(session.clone(), ctx).await       // 服务端 endpoint
    }
} else {
    let input = vec![UserInput::Text {
        text: ctx.config.compact_prompt.as_deref()
            .unwrap_or(crate::compact::SUMMARIZATION_PROMPT).to_string(),          // 本地摘要
        text_elements: Vec::new(),
    }];
    crate::compact::run_compact_task(session.clone(), ctx, input).await
};

// 来源: pi · compaction.ts:622-668(节选,展示可注入的模型/prompt/自定义指令)
export async function generateSummaryWithUsage(
	currentMessages: AgentMessage[],
	model: Model<any>,                    // ← 可换成任意便宜模型
	reserveTokens: number,
	apiKey: string | undefined,
	/* ... */ customInstructions?: string,
	previousSummary?: string,             // ← 有则走 UPDATE 增量 prompt
	/* ... */ streamFn?: StreamFn,        // ← 可注入自定义流式函数
): Promise<{ text: string; usage: Usage }> {
	const maxTokens = Math.min(Math.floor(0.8 * reserveTokens), model.maxTokens > 0 ? model.maxTokens : Infinity);
	let basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;
	if (customInstructions) basePrompt = `${basePrompt}\n\nAdditional focus: ${customInstructions}`;
	const conversationText = serializeConversation(convertToLlm(currentMessages));
	let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
	if (previousSummary) promptText += `<previous-summary>\n${previousSummary}\n</previous-summary>\n\n`;
	promptText += basePrompt;
	/* ... completeSummarization(...) ... */
}

// 来源: claude-code · src/services/compact/prompt.ts:19-26
const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.

- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
- You already have all the context you need in the conversation above.
- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
- Your entire response must be plain text: an <analysis> block followed by a <summary> block.
`

// 来源: pi · compaction.ts:202-230 —— 尾部真实 usage + 其后粗估
export function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate {
	const usageInfo = getLastAssistantUsageInfo(messages);
	if (!usageInfo) { /* 全部估算 */ }
	const usageTokens = calculateContextTokens(usageInfo.usage);
	let trailingTokens = 0;
	for (let i = usageInfo.index + 1; i < messages.length; i++) {
		trailingTokens += estimateTokens(messages[i]);   // char/4
	}
	return { tokens: usageTokens + trailingTokens, /* ... */ };
}