第4章：模型调用与缓存经济学

[system prompt] [tool schemas] [message 1] [message 2] … [message N]
 ~5-15K token    ~10-40K token   ← 每轮追加

export type CacheScope = 'global' | 'org'
export type SystemPromptBlock = {
  text: string
  cacheScope: CacheScope | null
}

if (useGlobalCacheFeature) {
  const boundaryIndex = systemPrompt.findIndex(s => s === SYSTEM_PROMPT_DYNAMIC_BOUNDARY)
  if (boundaryIndex !== -1) {
    let attributionHeader, systemPromptPrefix
    const staticBlocks: string[] = []
    const dynamicBlocks: string[] = []

    for (let i = 0; i < systemPrompt.length; i++) {
      const block = systemPrompt[i]
      if (!block || block === SYSTEM_PROMPT_DYNAMIC_BOUNDARY) continue
      if (block.startsWith('x-anthropic-billing-header')) attributionHeader = block
      else if (CLI_SYSPROMPT_PREFIXES.has(block)) systemPromptPrefix = block
      else if (i < boundaryIndex) staticBlocks.push(block)     // ← 边界前
      else dynamicBlocks.push(block)                            // ← 边界后
    }

    const result: SystemPromptBlock[] = []
    if (attributionHeader) result.push({ text: attributionHeader, cacheScope: null })
    if (systemPromptPrefix) result.push({ text: systemPromptPrefix, cacheScope: null })
    const staticJoined = staticBlocks.join('\n\n')
    if (staticJoined) result.push({ text: staticJoined, cacheScope: 'global' })   // ★
    const dynamicJoined = dynamicBlocks.join('\n\n')
    if (dynamicJoined) result.push({ text: dynamicJoined, cacheScope: null })

    logEvent('tengu_sysprompt_boundary_found', {
      blockCount: result.length,
      staticBlockLength: staticJoined.length,
      dynamicBlockLength: dynamicJoined.length,
    })
    return result
  } else {
    logEvent('tengu_sysprompt_missing_boundary_marker', { promptBlockCount: systemPrompt.length })
  }
}

// IMPORTANT: Do not add any more blocks for caching or you will get a 400

// Exactly one message-level cache_control marker per request. Mycro's
// turn-to-turn eviction (page_manager/index.rs: Index::insert) frees
// local-attention KV pages at any cached prefix position NOT in
// cache_store_int_token_boundaries. With two markers the second-to-last
// position is protected and its locals survive an extra turn even though
// nothing will ever resume from there — with one marker they're freed
// immediately.
const markerIndex = skipCacheWrite ? messages.length - 2 : messages.length - 1

function should1hCacheTTL(querySource?: QuerySource): boolean {
  // 3P Bedrock users get 1h TTL when opted in via env var
  if (getAPIProvider() === 'bedrock' && isEnvTruthy(process.env.ENABLE_PROMPT_CACHING_1H_BEDROCK)) return true

  // Latch eligibility in bootstrap state for session stability — prevents
  // mid-session overage flips from changing the cache_control TTL, which
  // would bust the server-side prompt cache (~20K tokens per flip).
  let userEligible = getPromptCache1hEligible()
  if (userEligible === null) {
    userEligible = process.env.USER_TYPE === 'ant'
      || (isClaudeAISubscriber() && !currentLimits.isUsingOverage)
    setPromptCache1hEligible(userEligible)
  }
  if (!userEligible) return false

  // Cache allowlist in bootstrap state for session stability — prevents mixed
  // TTLs when GrowthBook's disk cache updates mid-request
  let allowlist = getPromptCache1hAllowlist()
  if (allowlist === null) { … }

  return querySource !== undefined && allowlist.some(pattern =>
    pattern.endsWith('*') ? querySource.startsWith(pattern.slice(0, -1)) : querySource === pattern)
}

type PreviousState = {
  systemHash: number
  toolsHash: number
  /** Hash of system blocks WITH cache_control intact. Catches scope/TTL flips
   *  (global↔org, 1h↔5m) that stripCacheControl erases from systemHash. */
  cacheControlHash: number
  toolNames: string[]
  /** Per-tool schema hash. Diffed to name which tool's description changed
   *  when toolSchemasChanged but added=removed=0 (77% of tool breaks per
   *  BQ 2026-03-22). AgentTool/SkillTool embed dynamic agent/command lists. */
  perToolHashes: Record<string, number>
  systemCharCount: number
  model: string
  fastMode: boolean
  /** 'tool_based' | 'system_prompt' | 'none' — flips when MCP tools are
   *  discovered/removed. */
  globalCacheStrategy: string
  /** Sorted beta header list. Diffed to show which headers were added/removed. */
  betas: string[]
  /** AFK_MODE_BETA_HEADER presence — should NOT break cache anymore
   *  (sticky-on latched in claude.ts). Tracked to verify the fix. */
  autoModeActive: boolean
  …
}

function getCacheBreakDiffPath(): string {
  // → ~/.claude/tmp/cache-break-<4位随机>.diff
}

function getNonstreamingFallbackTimeoutMs(): number
export async function* executeNonStreamingRequest(…)

if (streamingFallbackOccured) {
  // Yield tombstones for orphaned messages so they're removed from UI and transcript.
  // These partial messages (especially thinking blocks) have invalid signatures
  // that would cause "thinking blocks cannot be modified" API errors.
  for (const msg of assistantMessages) {
    yield { type: 'tombstone' as const, message: msg }
  }
  logEvent('tengu_orphaned_messages_tombstoned', { orphanedMessageCount: assistantMessages.length })
  …
}

if (innerError instanceof FallbackTriggeredError && fallbackModel) {
  currentModel = fallbackModel
  attemptWithFallback = true
  yield* yieldMissingToolResultBlocks(assistantMessages, 'Model fallback triggered')
  …
  // Thinking signatures are model-bound: replaying a protected-thinking
  // block (e.g. capybara) to an unprotected fallback (e.g. opus) 400s.
  // Strip before retry so the fallback model gets clean history.
  if (process.env.USER_TYPE === 'ant') messagesForQuery = stripSignatureBlocks(messagesForQuery)

  yield createSystemMessage(
    `Switched to ${renderModelName(innerError.fallbackModel)} due to high demand for ${renderModelName(innerError.originalModel)}`,
    'warning',
  )
  continue
}

const DEFAULT_MAX_RETRIES = 10
const MAX_529_RETRIES = 3

// 529 = overloaded. Only foreground sources (the ones a human is waiting on)
// retry on 529. Everything else (summaries, titles, suggestions, classifiers)
const FOREGROUND_529_RETRY_SOURCES = new Set<QuerySource>([…])

数据层   —— 哨兵常量把边界写进数据本身
API 层   —— DANGEROUS_ 前缀 + 强制理由参数，让危险操作难写
观测层   —— 727 行的断裂检测，逐维度 hash + 逐工具 hash + 可读 diff

cd claude-code-deep-dive/extracted-source

# 1. 三种缓存作用域与块拆分
grep -n -A5 'export type CacheScope' src/utils/api.ts
grep -n -A45 'export function splitSysPromptPrefix' src/utils/api.ts

# 2. 「不要再加块了否则 400」
grep -n -B2 -A8 'or you will get a 400' src/services/api/claude.ts

# 3. 那段引用推理服务源码的注释
grep -n -B2 -A16 "Mycro's" src/services/api/claude.ts

# 4. 两处 latch 及其代价
grep -n -B4 -A6 '20K tokens per flip\|mixed\s*$' src/services/api/claude.ts

# 5. 缓存断裂取证系统
sed -n '1,120p' src/services/api/promptCacheBreakDetection.ts
grep -n '77% of tool breaks\|should NOT break cache anymore' src/services/api/promptCacheBreakDetection.ts

# 6. 529 只在前台重试
sed -n '50,95p' src/services/api/withRetry.ts

# 7. 墓碑与孤儿补丁
grep -n -B4 -A10 'tombstone\|yieldMissingToolResultBlocks' src/query.ts | head -60

# 缓存断裂 diff 文件（如果开了检测且真的断过）
ls ~/.claude/tmp/cache-break-*.diff 2>/dev/null

# 关掉缓存看看成本差别（不建议长期开）
DISABLE_PROMPT_CACHING=1 claude -p "hi"