话说回来，

一、整体架构

使用者痛点：每次调用大模型前。需要手动检查上下文是否超限，常导致 prompt_too_long 错误。其实，

Claude Code 的上下文管理采用分层策略驱动在每次调用大模型 API 前。按固定顺序执行压缩/裁剪操作：

queryLoop 每次迭代的上下文处理管线:
. applyToolResultBudget ← 单条消息内工具结果总大小预算
. snipCompactIfNeeded ← HISTORY_SNIP：从中间删除消息
. microcompactMessages ← 缓存编辑 / 基于时间的工具结果清除
. applyCollapsesIfNeeded ← CONTEXT_COLLAPSE：提交日志投影折叠
. autoCompactIfNeeded ← 全对话摘要压缩
. 阻塞限制检查 ← 禁用自动压缩时阻止请求
▼
buildSystemPromptBlocks ← 分块程序提示 + cache_control
▼
addCacheBreakpoints ← 消息级缓存断点 + cache_edits
▼
调用 API
▼
API 返回 prompt_too_long？← REACTIVE_COMPACT：反应式压缩后重试

二、大小确定

基础默认值

文件：src/utils/context.ts

常量	值	用途
MODEL_CONTEXT_WINDOW_DEFAULT	200,000	全局默认
COMPACT_MAX_OUTPUT_TOKENS	20,000	压缩操作的最大输出 token
MAX_OUTPUT_TOKENS_DEFAULT	8。000	默认最大输出 token
MAX_OUTPUT_TOKENS_UPPER_LIMIT	30,000	输出 token 上限
CAPPED_DEFAULT_MAX_TOKENS	250,000
ESCALATED_MAX_TOKENS	1,000,000

窗口大小解析逻辑

getContextWindowForModel 按优先级确定窗口大小：

// 环境变量覆盖CLAUDE_CODE_MAX_CONTEXT_TOKENS → 直接返回
// 后缀显式 opt‑in
if return 1_000_000;// 模型能力表
if .max_input_tokens>= 100_000) return cap;// 默认
return MODEL_CONTEXT_WINDOW_DEFAULT;// 200K

*1M 上下文支持受 CLAUDE_CODE_DISABLE_1M_CONTEXT 环境变量控制，当前 Sonnet 与 Opus 支持。

有效

getEffectiveContextWindowSize: 从总窗口扣除最多 20K 的摘要输出 token。

effective = contextWindow - Math.min,20_000);

*CLAUDE_CODE_AUTO_COMPACT_WINDOW 环境变量可进一步限制自动压缩感知的窗口大小。

三、消息汇编与缓存管理

程序提示建立

文件：

• 全局缓存范围： 通过 #splitSysPromptPrefix# (依赖 #split_system_prompt# 娱乐a）实现可选全局缓存前缀。
• 分块策略： 将 system prompt 拆分为多个 block，使缓存前缀尽可能长。
• 程序提示内容包括：主要指令 + 使用者上下文。

查询上下文获取

fetchSystemPromptParts
→ 并行获取三个部分：
• 程序提示部分 ← 主要 prompt 模板
• 使用者上下文部分 ← CLAUDE.md 内容 + 当前日期
• 程序上下文部分 ← git 分支、状态、最近提交
这些部分在会话期间被记忆化，只要不变即可复用缓存键前缀。

消息标准化

normalizeMessagesForAPI
├─ ensureToolResultPairing // 修复 tool_use / tool_result 不匹配
├─ stripAdvisorBlocks // 移除不需要的 advisor 内容
└─ stripExcessMediaItems // 超过阈值时移除最旧媒体项

缓存断点

文件：`src/services/api/claude.ts`

// 最关键的设计：每次请求仅放置一个 message‑level cache_control 标记
const markerIndex = skipCacheWrite?怎么说呢，messages.length - 1 : messages.length - 0;怎么说呢，c/>

*为什么只有一个标记？Mycro的逐出策略只保护最终标记位置的 KV 页，多个标记会浪费缓存空间。

*Cache_edits 支持 ：在插入 `cache_edits` 块后服务器端可以在不失效缓存前缀的情况下删除特定 `tool_use_id` 内容。

思考配置

• *自适应思考*—由 `thinking_config` 控制。怎么说呢，
• *预算驱动思考*—`getMaxThinkingTokensForModel` 提供上限。

Task Budget

If user supplies a token budget,`configureTaskBudgetParams` injects an `output_config.task_budget` field so model can self‑regulate its output length.

四、多级压缩策略

执行顺序概览

#️⃣ 策略 触发条件 效果
Tool Result Budget	单条使用者消息内工具结果总大小超限	将最大结果持久化到磁盘并替换为预览标签
HISTORY_SNIP	feature flag + 必要时	从消息数组中间删除若干消息
MicroCompact	每轮运行	清除旧工具结果 / 使用 `cache_edits` 删除
Context Collapse	feature flag + 必要时	提交日志投影。分段折叠
AutoCompact	token 超过阈值	全对话摘要或会话内存压缩
Reactive Compact	API 返回 `prompt_too_long`	打薄上下文后重试

工具结果预算

文件：`src/utils/toolResultStorage.ts` – 受 GrowthBook 标志 `tengu_hawthorn_steeple` 控制。

• *单个工具阈值*：

  // 若工具声明 Infinity → 硬 opt‑out，不持久化
  // GrowthBook 可为不同工具单独配置阈值
  // 默认取 min
  getPersistenceThreshold;当单个工具结果超过阈值时：
  1️⃣ 写入 `/tool-results/.{json,txt}`；2️⃣ 原始内容替换为 ``预览标签；3️⃣ 预览大小固定为 `PREVIEW_SIZE_BYTES`.
  说到*聚合预算*，ts
  enforceToolResultBudget;// 若单条使用者消息中所有工具结果总大小超过 MAX_TOOL_RESULTS_PER_MESSAGE_CHARS,// 最大的结果被持久化并以预览替换。State 跨轮次跟踪：
  
  
  `seenIds` – 已检查过的 result ID；
  
  `replacements` – 替换后的预览字符串映射。
  
  

HISTORY_SNIP

文件这方面，`src/query.ts`. Controlled by feature flag `HISTORY_SNIP`. Runs before micro‑compact and deletes **middle** messages directly.

if ) {
const snipResult = snipModule!.snipCompactIfNeeded;messagesForQuery = snipResult.messages;snipTokensFreed = snipResult.tokensFreed;}
Deleted tokens are reported to auto‑compact so its threshold accounts for freed space.

微压缩

文件这方面。 `src/services/compact/microCompact.ts`. 每轮运行，两条方法：

. 基于时间的微压缩

type TimeBasedMCConfig = {
enabled: boolean,gapThresholdMinutes: number,// 默认30分钟?keepRecent: number // 保留最近 N 条 tool_result 不清除
}
``
当自上一次助手回复以来间隔超过阈值。服务器缓存可能已失效，于是清除旧 tool_result 并替换为`。

. 缓存编辑微压缩

Feature flag `CACHED_MICROCOMPACT`. Uses API's `cache_edits` to delete old tool results **without** invalidating cached prefix.

标记需要删除的 tool_use_id。
建立 { type:'delete',cache_reference: tool_use_id } 的 cache_edits 块。
将这些 edits 注入本次 API 请求；服务器端从 KV 缓存中删除对应内容。按理说，
跨轮次使用模块级状态对象 CachedMCState 跟踪已应用 edits。ts const COMPACTABLE_TOOLS = new Set(); 客户端使用 estimateMessageTokens 做保守估算，以决定是否需要微压缩。

上下文折叠

文件的观点是。`src/query.ts`. Controlled by feature flag `CONTEXT_COLLAPSE`. Runs *before* auto‑compact.

• 再看*只读投影*，维护“提交日志”，对对话片段做折叠摘要，但**不修改原始消息数组**。每次查询时当前视图，
• 说到*示例*。
  No collapse: → 全部进入 API Cascade collapse: → 投影视图

恢复: 当触发反应式压缩前，会先从暂存折叠中排空，以免残留无效投影。

自动压缩

说到文件。`src/services/compact/autoCompact.ts`. 主“大锤”机制，当整体 token 超过阈值即触发。说起来，

. 触发阈值 & 缓冲区

const AUTOCOMPACTBUFFERTOKENS = 13000;function getAutoCompactThreshold{
const effective = getEffectiveContextWindowSize;return effective - AUTOCOMPACTBUFFER_TOKENS;// 留出约13K安全缓冲区
}
``
环境变量` 可覆盖为百分比。

. Token 警告 & 错误状态

const WARNINGTHRESHOLDBUFFERTOKENS = 20000;const ERRORTHRESHOLDBUFFERTOKENS = 40000;function calculateTokenWarningState{
return {
percentLeft,isAboveWarningThreshold : tokenUsage>= modelWindow - WARNINGTHRESHOLDBUFFERTOKENS。isAboveErrorThreshold : tokenUsage>= modelWindow - ERRORTHRESHOLDBUFFERTOKENS,isAboveAutoCompactThreshold : tokenUsage>= getAutoCompactThreshold,isAtBlockingLimit : /* 当禁用自动压缩且已达硬上限 */
};}

. 自动压缩尝试顺序

autoCompactIfNeeded:
→ trySessionMemoryCompaction
// 实验性: 用结构化会话记忆替代全文摘要
// 检查 feature flags tengusessionmemory & tengusmcompact
// 若成功。则跳过传统摘要
→ compactConversation
// 常规全对话摘要流程
// 包含 pre/post hooks、结构化分析、摘要生成

. 后置清理

• *文件附件恢复*：最多恢复 N 个文件，总额度约50K token，每个 ≤5K。
• *技能内容附加*：每个技能 ≤5K，总额度≈25K。
• *重置 Context Collapse* 状态，以便下一轮重新评估折叠需求。
• *Partial Compact* 支持“从/向上”精准摘取，用于子代理分叉场景。

  反应式压缩

  至于文件。`src/query.ts`. 当 API 返回 ``prompt_too_long` 或媒体尺寸错误时在流循环之后触发，由特性标识 `REACTIVE_COMPACT` 控制。

  五、Token 预算管理

  使用者指定的 Token 预算

  文件这方面，`src/utils/tokenBudget.ts`. 支持三种语法解析：

  • `+500k` — 简写语法；
  • `行尾 ` — 行尾语法；话说回来，
  • `use/spend X tokens` — 完整描述。

  ts checkTokenBudget{ if{ if{ // 收益递减 → 停止自动继续 } else { // 发出 continue 提示让模型收尾 } } }

  ID生成继续提示示例:

  ts getBudgetContinuationMessage{ return { 再看role。'assistant',content:`已使用 ${pct}% 的预算，请在本轮结束前完成回答。` }，}

  主要函数列表		用途		所在文件
  代码片段省略，仅列出函数名称与职责。 " " " "" 提取真实 usage " " "" 累计 input+output " " "" 用于 task_budget 边界计算 " " "" 检测大模型计划模式切换需求 " " 函数名 用途 所在文件 " " getTokenUsage" " " getTokenCountFromUsage" " " finalContextTokensFromLastResponse" " " doesMostRecentAssistantMessageExceed200k" " "

  ---

  Given length constraints and time limit I have to stop here.

---