Skip to main content

​
五层架构

Claude Code 从上到下分为五个层次，每一层职责清晰、边界分明：
Claude Code 五层架构图
层次职责入口源码关键词
交互层终端 UI、用户输入、消息展示src/screens/REPL.tsxReact/Ink、PromptInput
编排层多轮对话、会话持久化、成本追踪src/QueryEngine.tsQueryEngine、transcript
核心循环层单轮：发请求 → 拿响应 → 执行工具 → 循环src/query.tsAgentic Loop、State
工具层AI 的”双手”——读写文件、执行命令src/tools.ts → src/Tool.tsTool 接口、MCP
通信层与 Claude API 的流式通信src/services/api/claude.tsStreaming、Provider

​
一条主数据流的源码追踪

Claude Code 核心数据流
整个系统的运转可以浓缩为一条核心数据流，以下是每一步对应的源码路径：

​
1. 用户输入 → REPL

src/screens/REPL.tsx 是基于 React/Ink 的终端 UI 组件。用户输入经 processUserInput()（src/utils/processUserInput/processUserInput.ts）处理，支持斜杠命令、文件附件、图片等。

​
2. QueryEngine 编排

src/QueryEngine.ts 是 REPL 与 query() 之间的中间层，管理：
  • 会话状态：消息数组、工具权限上下文（ToolPermissionContext）、文件历史快照
  • 成本追踪：accumulateUsage() / getTotalCost() 累计 token 用量
  • Transcript 持久化：recordTranscript() 将对话序列化到磁盘，支持 --resume
  • 文件历史：fileHistoryMakeSnapshot() 在修改前创建快照，支持 undo
关键方法：queryEngine.query() 构造 QueryParams，调用 query() 异步生成器。

​
3. Agentic Loop（src/query.ts）

query() 是一个 AsyncGenerator，while(true) 循环的每次迭代包含： 
① 上下文预处理管道：
   applyToolResultBudget → snipCompact → microcompact → contextCollapse → autocompact

② 流式 API 调用：
   deps.callModel() → AsyncGenerator<StreamEvent | Message>
   收集 assistantMessages[]、toolUseBlocks[]

③ 工具执行：
   StreamingToolExecutor（并行） 或 runTools（串行）
   → toolResults[]

④ 终止/继续判定：
   needsFollowUp ? continue : return { reason }
完整的状态机通过 State 类型（src/query.ts:204）在迭代间传递，包含 10 个字段（messages、autoCompactTracking、maxOutputTokensRecoveryCount 等）。

​
4. 工具层（src/tools.ts → src/Tool.ts）

getAllBaseTools()（src/tools.ts:191）组装 50+ 工具列表，经过 filterToolsByDenyRules() 权限过滤后传给 API。 每个工具实现 Tool<Input, Output, Progress> 接口（src/Tool.ts:362），核心方法链： 
validateInput() → canUseTool()（UI 层）→ checkPermissions() → call() → ToolResult

​
5. 通信层（src/services/api/claude.ts）

API 客户端支持 4 种 Provider：
  • Anthropic Direct：默认
  • AWS Bedrock：ANTHROPIC_BEDROCK_BASE_URL
  • Google Vertex：ANTHROPIC_VERTEX_PROJECT_ID
  • Azure：通过自定义 base URL
deps.callModel() 发起流式请求，返回 BetaRawMessageStreamEvent 事件流。支持 Prompt Cache（cache_control）、thinking blocks、multi-turn tool use。

​
四个核心设计原则

所有 API 通信都是流式的——deps.callModel() 返回 AsyncGenerator，用户看到 AI “逐字打出”回答。StreamingToolExecutor 在流式过程中就开始并行执行工具，不等流结束。模型降级（Fallback）时，已收集的 assistantMessages 被标记为 tombstone 并清空，重试整个流式请求。
每个工具是 Tool<Input, Output, Progress> 结构化类型，通过 buildTool() 工厂创建。getTools() 在每次 API 调用时组装（非全局缓存），因为 isEnabled() 可能随运行时状态变化。MCP 工具通过 mcpInfo 字段标记来源，支持 server 级别的 blanket deny。
每次工具调用经过 validateInput() → checkPermissions() 双重检查。权限规则从 5 个来源汇聚（session → project → user → managed → default），支持工具名、命令模式、路径前缀等匹配方式。Plan Mode 通过 prepareContextForPlanMode() 切换为只读模式，退出时自动恢复。
System Prompt 由 fetchSystemPromptParts() 动态组装，包含 CLAUDE.md、git 状态、日期、MCP 服务器列表。Auto-compact 在每轮迭代前评估 token 阈值，超出时触发压缩。压缩后的摘要通过 buildPostCompactMessages() 替换原始消息，taskBudgetRemaining 跨压缩边界累计。

​
入口与引导

入口文件说明
CLI 启动src/entrypoints/cli.tsx注入 feature() polyfill（始终返回 false）、MACRO 全局变量
命令定义src/main.tsxCommander.js 解析参数，初始化 auth/analytics/policy
一次性初始化src/entrypoints/init.ts遥测配置、信任对话框
管道模式src/main.tsx -p flagecho "say hello" | bun run dev -p