集异璧之大成

[译] 使用 Claude Code：会话管理与 100 万上下文

Shelven Zhou — Thu, 16 Apr 2026 00:00:00 GMT

原文：Using Claude Code: Session Management & 1M Context 原作者：Thariq（@trq212）— Claude Code 工程师。曾就职 YC W20、MIT Media Lab。

今天，我们为 /usage 命令推出了一项全新更新，旨在帮助你更清晰地了解自己在 Claude Code 中的使用情况。这个决定的背后，是我们近期与用户进行的多次深入交流。

在这些交流中，一个反复浮现的话题是：不同用户管理会话的方式差异极大，尤其是在 Claude Code 新增 100 万上下文之后。

你是只在终端里保持一两个会话常驻？还是每次提示词都开一个新会话？什么时候该用 compact、rewind 或 subagents？什么会导致一次糟糕的 compact？

这里面的门道比想象中多得多，而且会切实影响你使用 Claude Code 的体验。而几乎所有这些问题，本质上都归结为对上下文窗口的管理。

上下文、压缩与上下文腐化速览

上下文窗口是模型在生成下一次回复时能一次性"看见"的全部内容，包括系统提示词、到目前为止的对话、每一次工具调用及其输出，以及所有被读取过的文件。Claude Code 的上下文窗口为 100 万 token。

不过，使用上下文本身是有代价的——这种现象通常被称为上下文腐化（context rot）。简单来说，随着上下文不断膨胀，模型的注意力被摊薄到更多 token 上，早期那些不再相关的内容开始干扰当前任务，性能因此下降。

上下文窗口存在硬性上限。当你快要触顶时，就需要将当前工作浓缩为一段更精简的描述，然后在新的上下文窗口中继续——这就是压缩（compaction）。你也可以手动触发压缩。

每一轮都是一个分岔点

假设你刚让 Claude 做了一件事，它也已经完成了。此时你的上下文里已经有了一些信息：工具调用、工具输出、你的指令。接下来你其实有相当多的选择：

继续：在同一个会话里再发一条消息
/rewind（Esc Esc）：跳回到之前某条消息，从那里重新尝试
/clear：开启新会话，通常附上一段你从刚才的工作中提炼出的简要说明
Compact：总结到目前为止的会话，然后基于这份总结继续
Subagents：把下一段工作委派给一个拥有干净上下文的代理，只把它的结果带回当前会话

最自然的做法当然是继续发消息，但另外四个选项存在的目的，都是帮助你管理上下文。

什么时候该开始新会话

什么时候该保留一个长会话，什么时候又该另起炉灶？我们的经验法则是：新任务，新会话。

100 万上下文窗口确实意味着你现在可以更可靠地完成更长的任务，比如从零开始构建一个完整的全栈应用。

但有时你会处理一些相关任务，其中一部分上下文仍然必要，但并非全部。例如，为你刚实现的功能编写文档。虽然你可以开启新会话，但 Claude 需要重新读取你刚实现的那些文件，这会更慢，也更贵。

用回退代替纠正

如果只能推荐一个体现良好上下文管理的习惯，那就是 rewind。

在 Claude Code 中，双击 Esc（或运行 /rewind）可以让你跳回任意一条之前的消息，并从那里重新输入提示词。该时间点之后的消息会从上下文中移除。

相比直接纠正，rewind 往往是更好的选择。举个例子：Claude 读取了五个文件，尝试了一种方案，但没有成功。你的直觉可能是输入"这不行，换成 X 试试"。但更好的做法是回退到刚读完文件之后的位置，然后带着你刚学到的信息重新提示："不要用方案 A，foo 模块没有暴露那个接口，直接走 B。"

你也可以使用 "summarize from here"，让 Claude 总结它的发现并创建一条交接消息——有点像未来的 Claude 给过去的自己留了张纸条："我试过了，这条路走不通。"

压缩与全新会话

当一个会话变得很长时，你有两种方式可以减负：/compact 或 /clear（然后重新开始）。它们感觉相似，但行为非常不同。

Compact 会让模型总结到目前为止的对话，然后用这份总结替换掉历史记录。这是一个有损过程——你把"什么值得保留"的判断权交给了 Claude。好处是你不需要动手写任何东西，而且 Claude 在纳入关键发现和文件方面可能比你更全面。你也可以通过传入指令来引导它，例如：/compact focus on the auth refactor, drop the test debugging。

使用 /clear 时，你需要亲手写下重要内容："我们正在重构 auth middleware，约束是 X，相关文件是 A 和 B，我们已经排除了方案 Y"——然后干净地重新开始。这更费事，但最终上下文中保留的内容完全由你决定。

什么会导致糟糕的 Compact？

如果你经常跑长会话，可能已经遇到过压缩效果特别差的情况。我们发现，糟糕的压缩往往发生在模型无法预判你接下来要做什么的时候。

比如，自动压缩在一次漫长的调试会话之后触发，总结了这次排查过程。而你的下一条消息是："现在修一下我们在 bar.ts 里看到的另一个 warning。"

但由于这个会话之前聚焦在调试上，那个"另一个 warning"可能已经从总结中被丢掉了。

这尤其棘手——受上下文腐化影响，模型在执行压缩时恰好处于它最不聪明的状态。好在有了 100 万上下文之后，你会有更充裕的时间主动使用 /compact，并附带说明你接下来想做什么。

Subagents 与全新的上下文窗口

Subagents 本质上也是一种上下文管理手段，适用于你提前知道某段工作会产生大量中间输出、而这些输出之后不再需要的场景。

当 Claude 通过 Agent 工具派生出一个 subagent 时，这个 subagent 会获得自己的全新上下文窗口。它可以按需完成大量工作，然后综合结果，只将最终报告返回给父会话。

我们的判断标准很简单：之后还需要这些工具输出本身，还是只需要结论？

虽然 Claude Code 会自动调用 subagents，但你也可以主动要求它这样做。例如：

"启动一个 subagent，根据下面这个 spec 文件验证这项工作的结果"
"派生一个 subagent，阅读另一个代码库并总结它是如何实现 auth flow 的，然后你自己用同样方式实现"
"派生一个 subagent，根据我的 git changes 为这个功能编写文档"

总结

总之，每当 Claude 结束一轮回复、而你准备发送下一条消息时，你就站在了一个决策点上。

未来，我们预期 Claude 能自主处理这些决策。但就目前而言，主动管理上下文仍然是你引导 Claude 产出更好结果的重要手段。

Claude Code Context Engineering 拆解: Snip、MicroCompact 与 AutoCompact

Shelven Zhou — Tue, 14 Apr 2026 00:00:00 GMT

目前 Agent 的能力天花板往往不是模型本身，而是 context window 的管理质量。一个百万 token 的窗口看似宽裕，但在真实的 coding agent 场景下——动辄几十次 tool call、成百上千行的文件读取和 shell 输出——填满它只是时间问题。填满之后怎么办？粗暴截断会丢失关键上下文，导致 agent "失忆"；放任不管又会让模型淹没在噪音中，注意力被稀释，决策质量下降。

Claude Code 对此做了三层递进式压缩：Snip → MicroCompact → AutoCompact。这套机制不仅在省 token，降低模型端的服务压力，更直接提升了 agent 的任务完成质量——更少的噪音意味着更精准的注意力分配。本文基于 2026 年 3 月 31 日泄露的 Claude Code 源码（文末可免费下载）和开源社区项目，拆解这三层机制的设计与实现。

全局视角：三层压缩的执行链路

在 Claude Code 的 query 主循环中，三层压缩按以下顺序执行：

// 1. Snip: 在输出进入 context 之前拦截
const snipResult = snipModule.snipCompactIfNeeded(messagesForQuery)
messagesForQuery = snipResult.messages
snipTokensFreed = snipResult.tokensFreed

// 2. MicroCompact: 精准清理旧的 tool results
const microcompactResult = await microcompactMessages(messagesForQuery, ...)
messagesForQuery = microcompactResult.messages

// 3. AutoCompact: 超过阈值时，用 LLM 总结整个对话
const shouldCompact = await shouldAutoCompact(
  messages, model, querySource, snipTokensFreed
)

三者不是互斥的，而是逐级递进——Snip 做源头拦截，MicroCompact 做存量清理，AutoCompact 是最后防线。整体设计哲学是：能不调 LLM 就不调 LLM。Snip 和 MicroCompact 都是纯本地操作，零额外成本；只有当前两层都不够用时，才启动代价最高的 LLM 总结。

Layer 1: Snip — 在输出进入 context 之前就拦截

Claude Code 内部有一个 snipCompact 模块，由 feature('HISTORY_SNIP') 控制，其代码并未包含在公开的源码中。但从调用方式可以看出它的定位：在 MicroCompact 之前执行，返回 tokensFreed 供后续阈值判断使用。

由于原始代码不可用，这里参考 edouard-claude/snip 的实现来分析 snip 的设计思路。该项目是社区基于 Claude Code hook 机制构建的独立 shell 输出过滤工具，Claude Code 内部的 snip 逻辑在策略和细节上可能有所不同。

代理与拦截模式

Snip 的核心思想是在 AI Agent 和操作系统 Shell 之间建立一个拦截层：

Claude Code → [PreToolUse Hook] → snip → Shell → [过滤输出] → Claude Code

通过 Claude Code 的 PreToolUse 钩子，当 Claude 准备执行 bash 工具时，hook 脚本会将命令改写为 snip -- <original_command>，让 snip 代理执行并过滤输出。

命令变换与参数注入

Snip 不只是被动过滤，还会主动改造命令以获得更好的结构化输出。例如，对于 go test，snip 会自动注入 -json 参数，强制产生 JSON 格式的输出，便于后续精确过滤：

- action: "aggregate"
  patterns:
    passed: '"Action":"pass"'
    failed: '"Action":"fail"'
  format: "{{.passed}} passed, {{.failed}} failed"

原本几百行的测试日志，经过 aggregate action 聚合后，变成一行 12 passed, 0 failed。

各类命令的压缩效果

命令	过滤策略	压缩率
`git status`	分类统计文件状态，仅显示摘要	~85%
`git log`	提交信息重写为单行摘要	~85%
`go test`	注入 JSON 参数，聚合 Pass/Fail	~97%
`cargo test`	捕获进度条，仅保留失败堆栈	~99%
`git diff`	仅保留统计信息，截断超长 diff	~80%

优雅降级

Snip 的一个重要设计原则是绝不破坏主链路。如果过滤器内部出错、找不到匹配的过滤器、或环境配置不全，它会自动退化为 passthrough 模式，原样返回输出。这确保了它作为黑盒代理的安全性。

Layer 2: MicroCompact — 外科手术式清理 tool results

如果说 Snip 是在源头减少输入，MicroCompact 则是对已经进入 context 的历史消息做精准清理。它只针对特定工具的结果进行处理：

const COMPACTABLE_TOOLS = new Set([
  FILE_READ_TOOL_NAME,    // 文件读取
  ...SHELL_TOOL_NAMES,    // Shell 命令
  GREP_TOOL_NAME,         // 搜索
  GLOB_TOOL_NAME,         // 文件匹配
  WEB_SEARCH_TOOL_NAME,   // 网页搜索
  WEB_FETCH_TOOL_NAME,    // 网页获取
  FILE_EDIT_TOOL_NAME,    // 文件编辑
  FILE_WRITE_TOOL_NAME,   // 文件写入
])

关键设计：清理时保留 tool_use 的 ID 和结构，只移除 content。这确保模型知道「曾经执行过这个操作」，但不再为其内容占据 token 空间。

双轨机制：Cold Cache vs Warm Cache

要理解 MicroCompact 为什么要分两条路径，需要先了解 Prompt Caching 的工作方式。

Prompt Caching 快速回顾

当你向 Claude API 发送请求时，模型需要对 prompt 中的每个 token 计算 KV（Key-Value）对。Prompt Caching 的核心思想是：如果两次请求的 prompt 共享相同的前缀，那么这些前缀 token 的 KV 对可以被缓存和复用，无需重新计算。

对于 Claude Code 这种多轮对话场景，每一轮新请求都会携带完整的对话历史作为前缀，只要前缀不变，后续请求就能享受 cache read 的低成本——cache read 的价格仅为 cache write（首次写入）的 1/10。但反过来，任何对历史消息的修改都会破坏前缀匹配，导致修改位置之后的所有缓存失效。

理解了这个约束，MicroCompact 的双轨设计就顺理成章了——本质上就是在回答一个问题：当前的 prompt cache 是热的还是冷的？

Time-based 路径（Cold Cache）

当对话停顿超过一定时间（Claude Code 默认阈值为 60 分钟），系统判定 prompt cache 已失效（注：Anthropic API 的标准 cache TTL 为 5 分钟，这里的 60 分钟是 Claude Code 自定义的触发阈值，采用更保守的策略来决定何时执行 time-based 清理）。既然下次请求注定要完整重发所有 token，不如趁机"瘦身"：

function maybeTimeBasedMicrocompact(messages, querySource) {
  const trigger = evaluateTimeBasedTrigger(messages, querySource)
  if (!trigger) return null

  // 保留最近 N 个 tool results，清理其余
  const keepSet = new Set(compactableIds.slice(-keepRecent))
  const clearSet = new Set(compactableIds.filter(id => !keepSet.has(id)))

  // 直接替换内容为占位符
  return messages.map(message => {
    // ...
    if (clearSet.has(block.tool_use_id)) {
      return { ...block, content: '[Old tool result content cleared]' }
    }
    // ...
  })
}

逻辑直白：cache 反正冷了，直接改消息内容，物理减少发送的 token 量。

Cached MC 路径（Warm Cache）

活跃对话中，cache 仍然有效。如果此时直接修改历史消息，会破坏前缀匹配，导致之前所有 cache 失效——代价太大。

Cached MC 的解法是将「缓存存储」与「模型可见性」解耦：

发送完整的历史消息到 API（保持 cache 命中）
附带 cache_edits 指令，告诉模型在推理时忽略特定 tool result 的内容

async function cachedMicrocompactPath(messages, querySource) {
  // 注册和追踪 tool results
  const toolsToDelete = mod.getToolResultsToDelete(state)

  if (toolsToDelete.length > 0) {
    // 创建 cache_edits 指令（不修改本地消息！）
    const cacheEdits = mod.createCacheEditsBlock(state, toolsToDelete)
    pendingCacheEdits = cacheEdits

    // 消息原样返回，cache_edits 在 API 层注入
    return { messages, compactionInfo: { pendingCacheEdits: { ... } } }
  }
  return { messages }
}

这实现了一个看似矛盾的目标：在不破坏已有 cache 的前提下，减少模型实际处理的 token 数量。

cache_edits 支持两类操作：

clear_tool_uses：屏蔽特定 tool call 的输入或输出
clear_thinking：清除旧的思维链（除最近 1-2 次外，早期推理过程通常已无必要）

cache_edits：Agent 与 Model 的协同优化

值得注意的是，cache_edits 不是纯客户端的技巧——它要求模型推理引擎在底层配合，能够在保持 KV cache 完整的前提下，根据客户端指令在推理时跳过特定内容。这是一个 agent 端和 model 端协同优化的典型案例，也是 Anthropic 作为同时掌控模型和 agent 产品的厂商的核心竞争力之一。目前 cache_edits 是 Claude Code 内部使用的能力，尚未作为公开 API 提供。

横向对比来看，各家在缓存管理上的深度差异很大：

提供商	缓存触发方式	是否支持缓存编辑	缓存失效机制
Anthropic	显式标记 (`cache_control`)	是 (`cache_edits`)	按 TTL 或手动覆盖
Google	显式创建 (`CachedContent`)	仅管理（TTL/删除）	固定 TTL（默认 1h）
DeepSeek	自动触发	否（仅前缀匹配）	动态过期（硬盘存储）
OpenAI	自动触发	否	精确匹配失效

大多数提供商的 prompt cache 是"只读"的——你只能通过保持前缀不变来利用它，一旦中间有修改就全部失效。Anthropic 的 cache_edits 打破了这个限制，允许在不破坏缓存的前提下对 context 做"外科手术式"编辑。这使得 Claude Code 能在活跃对话中实现 MicroCompact，而其他提供商上的 agent 只能等 cache 过期后才能清理。

Token 估算的保守策略

由于无法在发送前获得精确的 API token 计数，MicroCompact 对本地估算的 token 数做了 4/3 的加权处理：

export function estimateMessageTokens(messages: Message[]): number {
  // ... 遍历所有 block 累加 token
  // 4/3 加权，确保在接近上限时提前触发压缩
  return Math.ceil(totalTokens * (4 / 3))
}

宁可多压缩一点，也不能让请求因溢出而失败。

Layer 3: AutoCompact — 最后防线

当 Snip 和 MicroCompact 都不够用时，AutoCompact 作为最后一道防线介入。它的触发条件是 token 使用量超过 effectiveContextWindow - 13K buffer：

export const AUTOCOMPACT_BUFFER_TOKENS = 13_000

export function getAutoCompactThreshold(model: string): number {
  const effectiveContextWindow = getEffectiveContextWindowSize(model)
  return effectiveContextWindow - AUTOCOMPACT_BUFFER_TOKENS
}

优先级：Session Memory > LLM Summarization

AutoCompact 并不直接调用 LLM 总结。它先尝试一个更轻量的方案：

export async function autoCompactIfNeeded(messages, ...) {
  // 优先尝试 Session Memory Compaction
  const sessionMemoryResult = await trySessionMemoryCompaction(
    messages, agentId, autoCompactThreshold
  )
  if (sessionMemoryResult) {
    return { wasCompacted: true, compactionResult: sessionMemoryResult }
  }

  // fallback: 传统 LLM 总结
  const compactionResult = await compactConversation(messages, ...)
  return { wasCompacted: true, compactionResult }
}

Session Memory Compaction 利用 Claude Code 在对话过程中持续维护的 session memory（一个结构化的会话记忆文件）。当需要压缩时，直接用这个已有的记忆作为摘要，保留最近 10K-40K tokens 的原始消息，无需额外 LLM 调用。

只有当 session memory 不可用（未启用、内容为空、或压缩后仍超阈值）时，才 fallback 到传统的 LLM 总结。

传统 Compaction：fork agent 做总结

传统路径会 fork 一个 agent，用专门设计的 prompt 总结对话。这个 prompt 要求生成 9 个结构化 section：

1. Primary Request and Intent
2. Key Technical Concepts
3. Files and Code Sections（含代码片段）
4. Errors and fixes
5. Problem Solving
6. All user messages（完整保留用户原话）
7. Pending Tasks
8. Current Work
9. Optional Next Step（含原文引用，防止任务漂移）

其中两个设计值得注意：

analysis + summary 两阶段：prompt 要求先在 <analysis> 标签中整理思路，再在 <summary> 中给出最终总结。<analysis> 部分在使用时会被 formatCompactSummary 函数剥离——它只是用来提升总结质量的 "草稿纸"，不会进入后续 context
Partial Compact：支持只总结旧消息、保留近期消息原文。这比全量总结保留了更多细节

安全机制

AutoCompact 有两个关键的安全设计：

Circuit Breaker：连续 3 次压缩失败后，停止重试。这防止了 context 不可恢复地超限时，无意义的 API 调用风暴：

const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3
// BQ 2026-03-10: 1,279 sessions had 50+ consecutive failures (up to 3,272)
// in a single session, wasting ~250K API calls/day globally.

PTL Retry：当 compact 请求本身因为 prompt 过长而失败时，逐步从最旧的消息组开始截断，直到请求能通过：

export function truncateHeadForPTLRetry(messages, ptlResponse) {
  const groups = groupMessagesByApiRound(messages)
  // 根据 token gap 计算需要丢弃的组数，或 fallback 到 20%
  const dropCount = tokenGap !== undefined
    ? /* 精确计算 */ ...
    : Math.max(1, Math.floor(groups.length * 0.2))
  return groups.slice(dropCount).flat()
}

总结

对于 agent 开发者来说，这篇文章的核心 takeaway 不只是"怎么压缩 context"，而是 context 管理本身就是 agent 能力的一部分。具体来说：

分层设计优于单一策略——零成本的本地操作（Snip、MicroCompact）覆盖绝大多数场景，LLM 总结只是最后防线。不是每次都需要动用最重的工具
Cache-aware 是关键约束——在有 prompt cache 的系统中，"压缩 context"和"保持 cache 命中"是一对张力。MicroCompact 的双轨设计展示了如何在这个约束下做工程权衡
精心管理的 context = 更好的任务完成质量——更少的噪音意味着更精准的注意力分配，这直接影响 agent 的决策质量，而不仅仅是省钱

本文所引用的 Claude Code 源码包含在下方附件中，欢迎自行探索更多细节。

附件：claude-code-main.zip — 2026 年 3 月 31 日泄露的 Claude Code 源码（用于本文分析）