Claude Code 源码学习 – Prompt Cache

输入 tokens: [x1, x2, x3, x4]  (提示词，如 "今天天气")         │    ┌────▼─────┐    │ Token    │    │ Embedding│    └────┬─────┘         │    ┌────▼─────────────────────────────────────┐    │            Transformer Block (×N)         │    │  ┌────────────────────────────────────┐   │    │  │   Multi-Head Self-Attention        │   │    │  │   (带因果掩码 + KV 缓存机制)          │   │    │  └────────────────┬───────────────────┘   │    │         Add & Norm                        │    │  ┌────────────────────────────────────┐   │    │  │   Feed-Forward Network (FFN)       │   │    │  └────────────────┬───────────────────┘   │    │         Add & Norm                       │    └────────────────┬────────────────────────┘                     │                ┌────▼────┐                │   LM    │                │  Head   │                └────┬────┘                     │                next token logits → 采样得到 x5

"usage": {  "input_tokens": 100,                // 未命中的token数（全价）  "cache_creation_input_tokens": 8000, // 新建缓存的token数（全价，但只付一次，下次复用）  "cache_read_input_tokens": 50000    // 命中缓存的token数（便宜，具体看折扣）}

"usage": {  "prompt_tokens": 2006,  "prompt_tokens_details": {    "cached_tokens": 1920 // 关键字段，显示命中的token数  },  "completion_tokens": 300,  "total_tokens": 2306}

"usage": {  "prompt_tokens": 28,  "completion_tokens": 4,  "total_tokens": 32,  "prompt_tokens_details": {    "cached_tokens": 18 // 关键字段，显示命中的token数  },  "completion_tokens_details": {    "reasoning_tokens": 0  }}

{    "model": "claude-opus-4-6",    "max_tokens": 1024,    "cache_control": {"type": "ephemeral"},    "system": "You are a helpful assistant that remembers our conversation.",    "messages": [      {"role": "user", "content": "My name is Alex. I work on machine learning."},      {"role": "assistant", "content": "Nice to meet you, Alex! How can I help with your ML work today?"},      {"role": "user", "content": "What did I say I work on?"}    ]  }

{  "model": "claude-opus-4-6",  "max_tokens": 1024,  "cache_control": { "type": "ephemeral" },  "system": [    {      "type": "text",      "text": "You are a helpful assistant.",      "cache_control": { "type": "ephemeral" }    }  ],  "messages": [{ "role": "user", "content": "What are the key terms?" }]}

{  "model": "claude-opus-4-6",  "system": [...],          // 可以在这里设置缓存断点  "tools": [...],           // 可以在这里设置缓存断点  "messages": [          // 可以在这里设置缓存断点    { "role": "user", "content": "..." },    { "role": "assistant", "content": "..." }  ]}

token 位置:  0 ──────── 15K ──────── 80K            │           │            │            │     标记 A (global)    标记 B (org)            │           │            │            │   缓存条目 A           缓存条目 B            │   scope = global       scope = org            │   KV[0..15K]           KV[0..80K]

位置 0 ─── 15K ─── 30K ─── 80K     │       │       │       │     │   标记A     标记B      │     │       │       │       │     │   KV[0..15K]  KV[0..80K]服务端计算过程：  位置 0..15K：   命中全局缓存条目 A → 跳过计算，直接加载 KV 矩阵 ✓  位置 15K..80K： 从缓存 A 的 KV 矩阵继续往后计算 → 得到 KV[0..80K]                  → 存为缓存条目 B（scope=org）

位置 0 ─── 15K ─── 30K ─── 80K ─── 85K     │       │       │       │       │     │   标记A              标记B'    │     │       │               │       │     │   KV[0..15K]         KV[0..85K]服务端计算过程：  位置 0..15K：   命中全局缓存条目 A → 跳过 ✓  位置 15K..80K： 命中 org 缓存条目 B → 跳过 ✓（新增对话前缀匹配）  位置 80K..85K： 全新计算（新增的 5K tokens）                  → 更新缓存条目 B' 为 KV[0..85K]

POST /v1/messages 请求体 (JSON body)││  服务端缓存键计算方向 ──────────────────────────────►│├─ model: "claude-opus-4-6"│├─ system[] ──────────────────────────────────── cache_control│  ├─ [0] "x-anthropic-billing-header: ..."     →  无（含设备指纹，每用户不同）│  ├─ [1] "You are Claude Code, ..."            →  无│  ├─ [2] 静态规则（doing tasks / tools / ...）   →  {type:'ephemeral', scope:'global'}│  └─ [3] 动态上下文（memory / MCP / env / ...）  →  无│├─ tools[] ───────────────────────────────────── 服务端按配置自动设断点│  ├─ BashTool { name, description, input_schema }│  ├─ FileReadTool { ... }│  ├─ FileEditTool { ... }│  ├─ ...（按 name 字典序排列）│  └─ mcp__xxx__yyy { ... }（MCP 工具排在内置工具之后）│├─ messages[] ────────────────────────────────── cache_control│  ├─ [0] user: "帮我看看这个 bug"│  ├─ [1] assistant: [text, tool_use, ...]│  ├─ [2] user: [tool_result, ...]│  ├─ ...│  └─ [N] 最后一条消息（user 或 assistant）        →  {type:'ephemeral', ttl:'1h'}│                                                  唯一的消息级标记│├─ betas: [ ──────────────────────────────────── 隐式参与缓存键│    "claude-code-20250219",│    "interleaved-thinking-2025-05-14",│    "prompt-caching-scope-2026-01-05",│    "redact-thinking-2026-02-12",│    ...（latch 机制保证会话内不变）│  ]│├─ tool_choice: { type: "auto" }├─ metadata: { user_id: "..." }├─ max_tokens: 16384├─ thinking: { type: "enabled", budget_tokens: ... }├─ context_management: { ... }        ← 仅 betas 包含对应 header 时才发├─ output_config: { ... }└─ speed: "fast"                      ← 仅 fast mode 实际生效时才发

┌─────────────────────┐│ tools[]（内置工具）   │  ← 服务端在最后一个内置工具后设 global 缓存断点├─────────────────────┤│ tools[]（MCP 工具）   │  ← 用户特有，不参与 global 缓存├─────────────────────┤│ system[0] billing    │  ← 服务端识别并跳过│ system[1] CLI prefix │  ← 已知锚点│ system[2] 静态规则    │  ← cache_control: scope:'global'│ system[3] 动态上下文  │  ← cache_control: scope:'org' 或无├─────────────────────┤│ betas[]              │  ← 隐式参与缓存键├─────────────────────┤│ messages[0]          ││ messages[1]          ││ ...                  ││ messages[N]          │  ← cache_control: ephemeral└─────────────────────┘

queryModel()                           ← API 请求入口  ├─ getSystemPrompt()                 ← 组装系统提示词数组（静态 + 动态边界）  │    └─ resolveSystemPromptSections() ← 区分可缓存/不可缓存 Section  ├─ toolToAPISchema()                  ← 渲染工具 schema（会话级缓存）  ├─ buildSystemPromptBlocks()          ← 将系统提示词拆分为带 cache_scope 的块  │    └─ splitSysPromptPrefix()        ← 核心拆分逻辑：静态块→global，动态块→null  ├─ addCacheBreakpoints()              ← 在消息层添加唯一的 cache_control 标记  │    ├─ userMessageToMessageParam()  │    └─ assistantMessageToMessageParam()  └─ recordPromptState()               ← 缓存断裂检测（前置快照）       └─ checkResponseForCacheBreak() ← 缓存断裂检测（后置对比）

export const SYSTEM_PROMPT_DYNAMIC_BOUNDARY =  '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'

getSystemPrompt()return [  // --- Static content (cacheable) ---  getSimpleIntroSection(outputStyleConfig),  getSimpleSystemSection(),  getSimpleDoingTasksSection(),   // 如果 outputStyleConfig 允许  getActionsSection(),  getUsingYourToolsSection(enabledTools),  getSimpleToneAndStyleSection(),  getOutputEfficiencySection(),  // === BOUNDARY MARKER - DO NOT MOVE OR REMOVE ===  ...(shouldUseGlobalCacheScope() ? [SYSTEM_PROMPT_DYNAMIC_BOUNDARY] : []),  // --- Dynamic content (registry-managed) ---  ...resolvedDynamicSections,].filter(s => s !== null)

// 可缓存的 section——计算一次后在整个会话中复用export function systemPromptSection(  name: string,  compute: ComputeFn,): SystemPromptSection {  return { name, compute, cacheBreak: false }}// 不可缓存的 section——每轮都重新计算，会破坏前缀缓存export function DANGEROUS_uncachedSystemPromptSection(  name: string,  compute: ComputeFn,  _reason: string,   // 必须解释为什么需要破坏缓存): SystemPromptSection {  return { name, compute, cacheBreak: true }}

[  { text: attributionHeader, cacheScope: null },  { text: systemPromptPrefix, cacheScope: 'org' },  { text: restJoined,         cacheScope: 'org' },]

export function shouldUseGlobalCacheScope(): boolean {  return (    getAPIProvider() === 'firstParty' &&    !isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS)  )}

[  { text: attributionHeader, cacheScope: null },      // 计费头  { text: systemPromptPrefix, cacheScope: null },     // CLI 前缀  { text: staticJoined,       cacheScope: 'global' }, // 静态内容（跨用户共享！）  { text: dynamicJoined,      cacheScope: null },     // 动态内容]

[  { text: attributionHeader, cacheScope: null },  { text: systemPromptPrefix, cacheScope: 'org' },  { text: restJoined,         cacheScope: 'org' },]

export function buildSystemPromptBlocks(  systemPrompt: SystemPrompt,  enablePromptCaching: boolean,  options?,): TextBlockParam[] {  return splitSysPromptPrefix(systemPrompt, {    skipGlobalCacheForSystemPrompt: options?.skipGlobalCacheForSystemPrompt,  }).map(block => ({    type: 'text' as const,    text: block.text,    ...(enablePromptCaching &&      block.cacheScope !== null && {        cache_control: getCacheControl({          scope: block.cacheScope,          querySource: options?.querySource,        }),      }),  }))}

export function getPromptCachingEnabled(model: string): boolean {  // Global disable takes precedence  if (isEnvTruthy(process.env.DISABLE_PROMPT_CACHING)) return false  // Check if we should disable for small/fast model  if (isEnvTruthy(process.env.DISABLE_PROMPT_CACHING_HAIKU)) {    const smallFastModel = getSmallFastModel()    if (model === smallFastModel) return false  }  // Check if we should disable for default Sonnet  if (isEnvTruthy(process.env.DISABLE_PROMPT_CACHING_SONNET)) {    const defaultSonnet = getDefaultSonnetModel()    if (model === defaultSonnet) return false  }  // Check if we should disable for default Opus  if (isEnvTruthy(process.env.DISABLE_PROMPT_CACHING_OPUS)) {    const defaultOpus = getDefaultOpusModel()    if (model === defaultOpus) return false  }  return true}

// 每个请求恰好一个消息级 cache_control 标记const markerIndex = skipCacheWrite   ? messages.length - 2    // fork：倒数第二条（共享前缀点）  : messages.length - 1    // 主线程：最后一条const result = messages.map((msg, index) => {  const addCache = index === markerIndex  // 只有 markerIndex 处的消息会加上 cache_control  ...})

const markerIndex = skipCacheWrite ? messages.length - 2 : messages.length - 1

export function getCacheControl({  scope,  querySource,}: {  scope?: CacheScope  querySource?: QuerySource} = {}): { type: 'ephemeral'; ttl?: '1h'; scope?: CacheScope } {  return {    type: 'ephemeral',    ...(should1hCacheTTL(querySource) && { ttl: '1h' }),    ...(scope === 'global' && { scope }),  }}

function should1hCacheTTL(querySource?: QuerySource): boolean {  // Bedrock 3P 用户通过环境变量 opt-in  if (getAPIProvider() === 'bedrock' &&       isEnvTruthy(process.env.ENABLE_PROMPT_CACHING_1H_BEDROCK)) {    return true  }  // 资格锁存——防止会话中途 overage 状态翻转导致 TTL 变化  // TTL 变化会破坏服务端提示缓存（~20K tokens 每次翻转）  let userEligible = getPromptCache1hEligible()  if (userEligible === null) {    userEligible =       process.env.USER_TYPE === 'ant' ||      (isClaudeAISubscriber() && !currentLimits.isUsingOverage)    setPromptCache1hEligible(userEligible)  }  if (!userEligible) return false  // 查询源必须匹配 GrowthBook 白名单  let allowlist = getPromptCache1hAllowlist()  ...  return querySource !== undefined &&     allowlist.some(pattern => pattern.endsWith('*')       ? querySource.startsWith(pattern.slice(0, -1))      : querySource === pattern)}

// 会话范围的渲染工具 schema 缓存// 工具 schema 在服务端位置 2（系统提示词之前），// 所以任何字节变化都会破坏整个 ~11K token 的工具块及下游所有内容const TOOL_SCHEMA_CACHE = new Map<string, CachedSchema>()

// 按 name 字典序排序每个分区，保持内置工具作为连续前缀// 服务端的 claude_code_system_cache_policy 在最后一个前缀匹配的内置工具后// 放置全局缓存断点；扁平排序会把 MCP 工具交错到内置工具之间，// 每当 MCP 工具排在现有内置工具之间时就会使所有下游缓存键失效const byName = (a: Tool, b: Tool) => a.name.localeCompare(b.name)return uniqBy(  [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),  'name',)

// Global-scope 提示缓存仅限 firstParty。Foundry 被排除，因为 GrowthBook// 从未将 Foundry 用户纳入推出实验——实验数据是 firstParty-only 的。export function shouldUseGlobalCacheScope(): boolean {  return (    getAPIProvider() === 'firstParty' &&    !isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS)  )}

// 总是发送 beta header 以便 1P 使用。没有 scope 字段时 header 是空操作if (includeFirstPartyOnlyBetas) {  betaHeaders.push(PROMPT_CACHING_SCOPE_BETA_HEADER)}

recordPromptState({  system,                    // 系统提示词块  toolSchemas,               // 工具 schema  querySource,               // 查询来源  model,                     // 模型 ID  fastMode,                  // fast mode header（锁存值）  globalCacheStrategy,       // global 缓存策略  betas,                     // beta headers  autoModeActive,            // AFK 模式 header（锁存值）  isUsingOverage,            // 超量使用状态  cachedMCEnabled,           // 缓存编辑 header（锁存值）  effortValue,               // effort 值  extraBodyParams,           // 额外请求体参数})

const tokenDrop = prevCacheRead - cacheReadTokensif (cacheReadTokens >= prevCacheRead * 0.95 || tokenDrop < MIN_CACHE_MISS_TOKENS) {  // 没有断裂  return}// 断裂了！用 pending changes 解释原因

// 一旦开启就锁存，会话中途切换不会改变服务端缓存键// 锁存在 /clear 和 /compact 时通过 clearBetaHeaderLatches() 清除let afkHeaderLatched = getAfkModeHeaderLatched() === trueif (!afkHeaderLatched && isAgenticQuery && shouldIncludeFirstPartyOnlyBetas() &&    (autoModeStateModule?.isAutoModeActive() ?? false)) {  afkHeaderLatched = true  setAfkModeHeaderLatched(true)}