Claude Code 是如何把
「你是谁、用户在哪、系统怎样」
装进一次 API 调用的？

01为什么需要三个上下文？

当 Claude Code 调用 Anthropic API 时，需要让模型同时知道三件事 —— 你是谁、用户在哪、系统当前如何。 这三条信息职责不同、变化频率不同、缓存策略也不同，因此必须分三路独立管理。

02四阶段总览

从用户敲下回车的那一刻，到 HTTPS 请求离开你的网卡，三个上下文要经过 4 个阶段、7 次转换。 下图标出每个阶段的入口函数与产出。

图 2.1 · 完整数据流（四阶段全景）

阶段速览表

03阶段一 · 数据创建

当用户回车后，QueryEngine.submitMessage() 第一件事是调用 fetchSystemPromptParts()。 这是一次三路并行的"启动取数"，目的是压缩首包等待时间。

// src/utils/queryContext.ts:64-75
const [defaultSystemPrompt, userContext, systemContext] = await Promise.all([
  // 第一路：系统提示词（有自定义则跳过）
  customSystemPrompt !== undefined
    ? Promise.resolve([])
    : getSystemPrompt(tools, mainLoopModel, additionalWorkingDirectories, mcpClients),

  // 第二路：用户侧上下文（始终执行）
  getUserContext(),

  // 第三路：系统侧上下文（有自定义则跳过）
  customSystemPrompt !== undefined ? Promise.resolve({}) : getSystemContext(),
])

3.1 第一路：defaultSystemPrompt 怎么生成

由 getSystemPrompt() 在 src/constants/prompts.ts 生成。返回 string[]，每个元素是一个段落。 根据环境变量与 feature flag 选择三种模式之一：

标准模式的内部结构

图 3.1 · defaultSystemPrompt 标准模式的段落结构

3.2 第二路：baseUserContext 怎么生成

getUserContext() 在 src/context.ts，返回键值对：

{
  claudeMd: "<AGENTS.md / MEMORY.md 拼接后的全文>",  // 可选
  currentDate: "Today's date is 2026-04-29.",           // 始终
}

claudeMd 的生成步骤：

1. 检查是否禁用：CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 或 --bare 模式跳过；
2. getMemoryFiles() 递归扫描工作目录，找出全部 AGENTS.md 和 MEMORY.md；
3. filterInjectedMemoryFiles() 过滤已经通过其他路径注入的；
4. getClaudeMds() 读取并按层级拼接所有文件内容；
5. 结果缓存到 setCachedClaudeMdContent()，供 auto-mode 分类器复用。

缓存策略：使用 memoize 缓存，同一会话内只算一次。setSystemPromptInjection()（调试用）会清空缓存强制重算。

3.3 第三路：systemContext 怎么生成

getSystemContext() 在 src/context.ts。结构：

{
  gitStatus: "This is the git status at the start of the conversation.\nCurrent branch: main\n...",
  cacheBreaker: "[CACHE_BREAKER: ...]",  // 仅调试模式
}

gitStatus 的生成 —— 5 个 git 命令并行执行：

3.4 阶段一末尾：初步包装与合并

三路结果回到 QueryEngine 后，会做两次轻量转换：

const userContext = {
  ...baseUserContext,
  ...getCoordinatorUserContext(
    mcpClients, scratchpadDir
  ),
}

const systemPrompt = asSystemPrompt([
  ...(customPrompt !== undefined
    ? [customPrompt]
    : defaultSystemPrompt),
  ...(memoryMechanicsPrompt
    ? [memoryMechanicsPrompt] : []),
  ...(appendSystemPrompt
    ? [appendSystemPrompt] : []),
])

asSystemPrompt() 是品牌类型（branded type）包装函数，把 string[] 标记为 SystemPrompt 类型，防止与其他字符串数组混淆。本质仍是 string[]。

04阶段二 · 传入查询

阶段二非常薄。query() 是一个异步生成器，不修改三个上下文值， 只做两件事：建 Langfuse trace，然后 yield* 委托给 queryLoop()。

export async function* query(params: QueryParams): AsyncGenerator<...> {
  // 复用上游 trace（如果是子代理）或新建
  const langfuseTrace = params.toolUseContext.langfuseTrace
    ?? (isLangfuseEnabled() ? createTrace({...}) : null)

  const paramsWithTrace = langfuseTrace
    ? { ...params, toolUseContext: { ...params.toolUseContext, langfuseTrace } }
    : params

  let terminal: Terminal | undefined
  try {
    terminal = yield* queryLoop(paramsWithTrace, consumedCommandUuids)
  } finally {
    if (ownsTrace) endTrace(langfuseTrace, ...)
  }
  return terminal!
}

queryLoop 的不可变参数 vs 可变状态

{
  systemPrompt,    // 阶段一产出
  userContext,     // 阶段一产出
  systemContext,   // 阶段一产出
  canUseTool,
  fallbackModel,
  querySource,
  maxTurns,
}

{
  messages,                  // 每轮追加 assistant + tool_result
  toolUseContext,
  autoCompactTracking,
  pendingToolUseSummary,
  turnCount,                 // 每轮 +1
  transition,
}

05阶段三 · 循环内转换

每轮迭代代表一次"模型调用 → 工具执行 → 附件注入"的完整回合。 消息预处理管线先对 messages 做收敛，然后两次关键合并： appendSystemContext 拼系统提示词、prependUserContext 注入用户上下文。

5.1 消息预处理管线

每轮开始时，state.messages 经过六道工序，不影响三个上下文值，但会改变最终发送的消息内容：

图 5.1 · 消息预处理六道管线

5.2 关键合并 ① — appendSystemContext

// src/utils/api.ts:435-445
export function appendSystemContext(
  systemPrompt: SystemPrompt,
  context: { [k: string]: string },
): string[] {
  return [
    ...systemPrompt,
    Object.entries(context)
      .map(([key, value]) => `${key}: ${value}`)
      .join('\n'),
  ].filter(Boolean)
}

5.3 关键合并 ② — prependUserContext

// src/utils/api.ts:447-472
export function prependUserContext(
  messages: Message[],
  context: { [k: string]: string },
): Message[] {
  if (process.env.NODE_ENV === 'test') return messages
  if (Object.entries(context).length === 0) return messages

  return [
    createUserMessage({
      content: `<system-reminder>
As you answer the user's questions, you can use the following context:
${Object.entries(context).map(([key, value]) => `# ${key}\n${value}`).join('\n')}

      IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.
</system-reminder>`,
      isMeta: true,  // ← 标记为元消息，不在 UI 显示
    }),
    ...messages,
  ]
}

5.4 调用 deps.callModel — 阶段三的出口

// src/query.ts:627
for await (const message of deps.callModel({
  messages: prependUserContext(messagesForQuery, userContext),  // ← 注入
  systemPrompt: fullSystemPrompt,                                // ← 已合并
  thinkingConfig: toolUseContext.options.thinkingConfig,
  tools: toolUseContext.options.tools,
  signal: toolUseContext.abortController.signal,
  options: { ... },
})) { ... }

06阶段四 · API 层最终转换

最后一站。deps.callModel() 进入 src/services/api/claude.ts， 在这里完成归一化、追加归因、分块、缓存标记，最终通过 Anthropic SDK 发送 HTTPS 请求。

6.1 消息归一化

let messagesForAPI = normalizeMessagesForAPI(messages, filteredTools)

处理四件事：

• tool_use / tool_result 配对一致性 —— 检查每个 tool_use 都有对应 tool_result。
• 剥离不支持字段 —— 如 tool_reference、caller 等内部字段。
• 修复孤立消息 —— 为无配对的 tool_use 注入合成错误 tool_result（API 协议要求）。
• 裁剪超量媒体块 —— API 限制每条消息最多 100 个媒体块。

6.2 系统提示词最终拼装

在 fullSystemPrompt 之上，再追加 API 层需要的额外内容：

// src/services/api/claude.ts:1377-1392
systemPrompt = asSystemPrompt([
  getAttributionHeader(fingerprint),       // ① 归因头（计费追踪）
  getCLISyspromptPrefix({...}),            // ② CLI 标识前缀
  ...systemPrompt,                          // ③ fullSystemPrompt 全部
  ...(advisorModel ? [ADVISOR_TOOL_INSTRUCTIONS] : []),       // ④ Advisor 指令（条件）
  ...(injectChromeHere ? [CHROME_TOOL_SEARCH_INSTRUCTIONS] : []), // ⑤ Chrome 指令（条件）
].filter(Boolean))

6.3 分块 + 缓存标记 — splitSysPromptPrefix

这一步把 string[] 转为 API 需要的 TextBlockParam[]，并为每块标记缓存作用域。三种策略：

图 6.1 · splitSysPromptPrefix 的三种分块策略

每个 Block 转为如下结构：

{
  type: 'text',
  text: block.text,
  ...(enablePromptCaching && block.cacheScope !== null && {
    cache_control: {
      type: 'ephemeral',
      scope: block.cacheScope,  // 'global' or 'org'
    }
  }),
}

6.4 最终 API 请求结构

anthropic.beta.messages.create({
  model: normalizedModel,
  system,                    // ← 分块后的 TextBlockParam[]
  messages: messagesForAPI,  // ← 归一化后的消息（含 prependUserContext 注入）
  tools: allTools,           // ← 工具 schema
  thinking: thinkingConfig,
  betas,                     // ← beta headers
  ...
})

07完整实例 · 用户输入"帮我分析这个文件"

来跟一条真实消息走完全程。场景：Mac 上使用 Claude Code REPL，工作目录 /Users/fanhui/Desktop/github/claude-code， 模型 claude-sonnet-4，项目里有 AGENTS.md，是 git 仓库，无 MCP 服务器，无自定义系统提示词。

7.1 阶段一产出：三个原始值

defaultSystemPrompt（部分省略）

[
  // ━━━ 静态段落（可 global 缓存）━━━
  "You are an interactive agent that helps users with software engineering tasks...",
  "# System\n - All text you output outside of tool use is displayed...",
  "# Doing tasks\n - The user will primarily request you to perform...",
  "# Executing actions with care\n\nCarefully consider the reversibility...",
  "# Using your tools\n - Do not use tools when...",
  "# Tone and style\n - Only use emojis if the user explicitly requests...",
  "# Communicating with the user\n...",

  "SYSTEM_PROMPT_DYNAMIC_BOUNDARY",  // 边界标记

  // ━━━ 动态段落（不缓存或 org 缓存）━━━
  "# Session-specific guidance\n...",
  "# Memory\n\nThis is the content of the project's memory file...",
  "# Environment\n - Primary working directory: /Users/fanhui/...\n - Is a git repository: Yes\n - Platform: darwin...",
  "# Language\n\nWhen responding to the user, use the language...",
  "# Function result clearing\n...",
  "# Summarize tool results\n...",
]

baseUserContext

{
  claudeMd: "# AGENTS.md\n\nThis file provides guidance to Codex...\n## Commands\n```bash\nbun install\n...\n```\n...",
  currentDate: "Today's date is 2026-04-29.",
}

systemContext

{
  gitStatus: `This is the git status at the start of the conversation.
Current branch: main
Main branch: main
Git user: fanhui
Status:
M src/query.ts
M src/QueryEngine.ts

Recent commits:
1173a62 refactor: 统一 log.ts/debug.ts 的测试 mock
7ea69ca fix: 修复 build 过程中的问题`,
}

7.2 阶段三产出：合并后的 fullSystemPrompt 与消息列表

appendSystemContext 把 systemContext 拼为单个字符串追加：

fullSystemPrompt = [
  // ... 前面所有段落保持不变 ...
  "# Summarize tool results\n...",

  // ↓↓↓ 新增：systemContext 单字符串追加 ↓↓↓
  "gitStatus: This is the git status at the start of the conversation.\nCurrent branch: main\nMain branch: main\nGit user: fanhui\nStatus:\nM src/query.ts\nM src/QueryEngine.ts\n\nRecent commits:\n1173a62 refactor: ...\n7ea69ca fix: ...",
]

prependUserContext 在消息列表最前面注入元消息：

// 转换前
[ { role: "user", content: "帮我分析这个文件" } ]

// 转换后
[
  {
    role: "user",
    content: `<system-reminder>
As you answer the user's questions, you can use the following context:
# claudeMd
# AGENTS.md

This file provides guidance to Codex...
[...AGENTS.md 全文...]

# currentDate
Today's date is 2026-04-29.

      IMPORTANT: this context may or may not be relevant to your tasks...
</system-reminder>`,
    isMeta: true,
  },
  { role: "user", content: "帮我分析这个文件" },
]

7.3 阶段四产出：API 请求最终结构

"x-anthropic-billing-header: cc_version=2.1.888; ..."

"You are Claude Code, Anthropic's official CLI for Claude."

"You are an interactive agent that helps users...

# System
...

# Doing tasks
...

# Executing actions with care
...

# Using your tools
...

# Tone and style
...

# Communicating with the user
..."

"# Session-specific guidance
...

# Memory
...

# Environment
 - Primary working directory: /Users/fanhui/Desktop/github/claude-code
 - Is a git repository: Yes
 - Platform: darwin
 - You are powered by claude-sonnet-4...

# Language
...

# Function result clearing
...

# Summarize tool results
...

gitStatus: Current branch: main
M src/query.ts
M src/QueryEngine.ts
Recent commits: ..."

[
  {
    role: "user",
    content: "<system-reminder>
As you answer the user's questions, you can use the following context:
# claudeMd
# AGENTS.md
[...AGENTS.md 全文...]
# currentDate
Today's date is 2026-04-29.
IMPORTANT: this context may or may not be relevant...
</system-reminder>"
  },
  {
    role: "user",
    content: "帮我分析这个文件"
  }
]

7.4 模型视角：它到底"看到"了什么？

从模型的视角，信息分两条独立通道：

08缓存策略 · 为什么这样切块

Anthropic API 的 prompt cache 有三种作用域：global（跨组织）、org（组织内）、不缓存。 命中缓存可以把 token 成本降低 90%、首字节延迟降到 ~30%。三层切分背后的考量：

SYSTEM_PROMPT_DYNAMIC_BOUNDARY 的作用

这个边界标记的作用是清晰划分静态/动态，让 splitSysPromptPrefix 准确知道在哪一刀切开。 它是字符串字面量 "SYSTEM_PROMPT_DYNAMIC_BOUNDARY"，作为数组的一个元素插在静态段落和动态段落之间， 在分块时被识别并移除（不会真的发给模型）。

图 8.1 · 边界标记切分静态/动态

MCP 工具对缓存的影响

09多轮对话 · 不变性与变化性

当模型回复包含 tool_use 块时，queryLoop 不会结束，而是进入下一轮迭代。 理解什么变、什么不变，是看懂多轮对话内存模型的关键。

9.1 跨轮不变性矩阵

9.2 下一轮消息构成

// src/query.ts:1700
const next: State = {
  messages: [...messagesForQuery, ...assistantMessages, ...toolResults],
  ...
}

图 9.1 · 双轮 tool_use 流程示意

9.3 compact 后的上下文恢复

当 token 接近上限时，autoCompactIfNeeded 会触发压缩：

// 压缩前
[user1, assistant1, tool_result1, ..., userN, assistantN, tool_resultN]

// 压缩后
[compact_summary, compact_boundary, ...新消息]

9.4 附件注入（在 tool_result 之后）

工具执行完成后，进入下一轮前会注入多种附件：

10设计要点总结

核心数据流（一图回顾）

图 10.1 · 一图概括：从三路并行取数到 API 调用的全部链路