来源：Claude Code 技术文档 - v2.1.88 源码分析
架构概览
1.1 项目定位
Claude Code 是 Anthropic 官方的 AI 编程助手命令行工具，允许用户通过终端与 Claude AI 模型进行交互式对话，执行代码编辑、文件操作、命令运行等编程任务。v2.1.88 是一个功能成熟的版本，包含完整的工具链、远程通信、多模型支持等企业级特性。
1.2 技术栈详情
运行时与构建
层级
技术
详情
运行时
Bun
高性能 JavaScript/TypeScript 运行时，直接执行 .ts/.tsx，原生支持 ESM
编译时
bun:bundle
编译时 Feature Flag (feature()) 实现死代码消除
运行时特性
GrowthBook
运行时 Feature Gate，通过远程配置动态控制功能
堆内存
8GB
CCR 模式下通过 --max-old-space-size=8192 配置
前端/UI
层级
技术
详情
框架
React 19
组件化 UI 开发
终端渲染
Ink
React → 终端 ANSI 输出的调和器
布局引擎
Yoga
Facebook 的跨平台 Flexbox 布局引擎
性能优化
React Compiler Runtime
react/compiler-runtime 自动记忆化，全局应用
渲染帧率
60 FPS
自定义 Ink 渲染器，含 FPS 计量
数据验证与通信
层级
技术
详情
Schema 验证
Zod v4
所有工具输入/输出的运行时类型验证
AI 协议
MCP (Model Context Protocol)
Stdio/SSE/WebSocket/HTTP 四种传输方式
LSP
Language Server Protocol
代码智能分析集成
API SDK
@anthropic-ai/sdk
官方 SDK 封装
状态管理
层级
技术
详情
Store
自研轻量 Store
类 Zustand 的 getState/setState/subscribe 模式
React 集成
useSyncExternalStore
React 18+ 外部 Store 订阅标准 API
不可变性
DeepImmutable<T>
编译期确保状态不可变
1.3 核心架构层次
┌──────────────────────────────────────────────────────────────────────┐
│ 入口层 (Entrypoints) │
│ cli.tsx │ mcp.ts │ agentSdkTypes.ts │ init.ts │
│ 快速路径优化 │ MCP Server │ Agent SDK │ 初始化链 │
└──────────────────────────┬───────────────────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────────────────┐
│ 屏幕层 (Screens) │
│ REPL.tsx │ Doctor.tsx │ ResumeConversation.tsx │
│ 主交互循环 │ 环境诊断 │ 会话恢复 │
└──────────────────────────┬───────────────────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────────────────┐
│ 组件层 (Components) │
│ App.tsx(FpsMetrics→Stats→AppState Provider 组合) │
│ StatusLine.tsx │ VirtualMessageList.tsx │ ToolUseLoader.tsx │
│ 200+ 组件 │ 虚拟滚动 │ 动画加载器 │
└──────────────────────────┬───────────────────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────────────────┐
│ 引擎层 (Query Engine) │
│ QueryEngine.ts │ query/config.ts │ query/tokenBudget.ts │
│ 核心 AI 对话循环 │ 会话配置 │ Token 预算管理 │
│ │ │
│ query() → processUserInput() → API Call → 消息流处理 → SDK 消息 │
│ 成本跟踪 │ 历史记录 │ 中断支持 │ 结构化输出重试 │
└──┬───────────────┬───────────────────┬──────────────────────────────┘
│ │ │
┌──▼──────┐ ┌─────▼──────┐ ┌────────▼──────────────────────────────┐
│工具系统 │ │ 命令系统 │ │ 服务层 (Services) │
│Tool.ts │ │commands.ts │ │ claude.ts │ 500+ 行模型查询 │
│tools.ts │ │60+命令目录 │ │ withRetry.ts│ 700+ 行重试逻辑 │
│45+工具 │ │120+命令 │ │ client.ts │ 多提供商 API 工厂 │
│+MCP扩展 │ │+技能命令 │ │ mcp/ │ MCP 客户端/配置/类型 │
└──┬──────┘ └─────┬──────┘ └────────┬──────────────────────────────┘
│ │ │
┌──▼───────────────▼───────────────────▼──────────────────────────────┐
│ 状态管理层 (State) │
│ Store<T>: getState/setState/subscribe │
│ AppState: 50+ DeepImmutable 字段 │
│ ToolPermissionContext: 权限模式 + 规则层 │
│ selectors.ts: 派生计算 │ onChangeAppState.ts: 变更监听 │
└──┬──────────────────────────────────────────────────────────────────┘
│
┌──▼──────────────────────────────────────────────────────────────────┐
│ 基础设施层 (Infrastructure) │
│ bridge/ 远程通信 │ hooks/ 90+ React Hook │
│ plugins/ 插件系统 │ skills/ 技能加载 │
│ utils/ 150+ 工具 │ constants/ 提示词/系统/工具常量 │
│ types/ 完整类型定义 │ tasks/ 任务执行框架 │
└─────────────────────────────────────────────────────────────────────┘1.4 核心设计理念
1.4.1 编译时死代码消除
// bun:bundle 编译时标志 — 未启用的路径在编译时被移除
import { feature } from 'bun:bundle'
if (feature('OVERLAP_TEST_TOOL')) {
// 此代码块仅在 OVERLAP_TEST_TOOL 启用时编译到产物中
tools.push(OverlapTestTool)
}这种模式贯穿整个代码库，控制功能的条件编译：
CONTEXT_COLLAPSE— 上下文折叠功能TERMINAL_PANEL— 终端面板功能WORKFLOWS— 工作流引擎REPL— REPL 工具MONITOR_TOOL— 监控 MCP 任务
1.4.2 Memoization 策略
项目广泛使用 lodash.memoize 和自定义 memoize 函数：
// 单次计算缓存 — 避免重复初始化
const COMMANDS = memoize(() => { /* 120+ commands assembly */ })
const builtInCommandNames = memoize(() => { /* name set */ })
const loadAllCommands = memoize(async (cwd) => { /* skill+plugin+builtin */ })关键 memoized 函数包括：
getSystemContext()— Git 状态（会话级缓存）getUserContext()— CLAUDE.md + 日期getGitStatus()— Git 分支/状态/日志loadAllCommands(cwd)— 按 cwd memoizedgetSkillToolCommands(cwd)— 技能命令缓存
1.4.3 DeepImmutable 类型安全
// 所有 AppState 字段使用 DeepImmutable 包装
type AppState = DeepImmutable<{
mcp: MCPState
plugins: PluginState
fileHistory: FileHistoryState
// ... 50+ 字段
}>状态中有两种容器：
- 不可变对象 —
mcp,plugins,fileHistory等业务状态 - 可变容器 —
tasks,agentNameRegistry等需要频繁修改的引用
1.4.4 异步生成器消息流
// QueryEngine 核心是 AsyncGenerator
async *submitMessage(prompt): AsyncGenerator<SDKMessage, void, unknown> {
// 1. processUserInput(prompt)
// 2. yield* from query() generator
// 3. yield SDK messages (assistant/user/progress/stream_event)
// 4. check budget limits
}整个消息处理链使用 AsyncGenerator 模式：
ask()— 顶级便利包装器QueryEngine.submitMessage()— 核心查询循环query()— API 调用与流式处理- 通过
yield向上游传递 SDK 消息
1.4.5 工具排序保持 Prompt 缓存稳定
// assembleToolPool() 中按名称排序
// 确保工具列表在不同请求间保持相同顺序
// 从而最大化 Anthropic API 的 prompt 缓存命中率
const sorted = [...tools].sort((a, b) => a.name.localeCompare(b.name))
return uniqBy(sorted, t => t.name)1.5 多 AI 提供商支持
提供商
协议
认证
Anthropic Direct
HTTPS
API Key
AWS Bedrock
Bedrock SDK
AWS Credentials
Azure Foundry
Azure OpenAI 协议
Azure AD Token
Google Vertex AI
Vertex SDK
GCP Credentials
通过 getAnthropicClient() 工厂统一创建，共享相同的查询/重试/成本跟踪逻辑。
1.6 安全架构概述
┌─────────────────────────────────────────────┐
│ 权限决策链 │
│ │
│ policySettings (企业策略，最高优先级) │
│ ↓ │
│ alwaysDenyRules (拒绝规则) │
│ ↓ │
│ alwaysAllowRules (允许规则) │
│ ↓ │
│ alwaysAskRules (询问规则) │
│ ↓ │
│ PermissionMode 默认行为 │
│ - default (提示用户) │
│ - acceptEdits (接受编辑) │
│ - bypassPermissions (跳过权限) │
│ - plan (规划模式，只读) │
│ - auto (自动分类器判断) │
│ - dontAsk (不询问) │
│ - bubble (冒泡到父级) │
└─────────────────────────────────────────────┘规则来源优先级（从高到低）：
policySettings— 企业管理策略flagSettings— Feature Flag 控制cliArg— 命令行参数localSettings— 本地项目.claude/settings.jsonprojectSettings— 项目级CLAUDE.mduserSettings— 用户级~/.claude/settings.jsonsession— 会话内交互command— 命令级覆盖
1.7 数据流总览
用户输入
│
▼
processUserInput() ─── 解析斜杠命令/图片/URL
│
▼
QueryEngine.submitMessage()
│
├─ fetchSystemPromptParts() ─── 组装系统提示词
│ ├─ getSimpleIntroSection() // 基本介绍
│ ├─ getSimpleSystemSection() // 系统信息
│ ├─ getActionsSection() // 行为指南
│ ├─ getUsingYourToolsSection() // 工具使用
│ ├─ getSessionSpecificGuidance() // 会话特定
│ ├─ getLanguageSection() // 语言偏好
│ └─ getOutputStyleSection() // 输出样式
│
▼
query() ─── 调用 claude.ts 的 API 查询
│
├─ 构造请求：model + messages + tools + system prompt
├─ 缓存策略：1h TTL (3600s)，thinking config，effort params
├─ Zod schema → API schema 转换
│
▼
API 流式响应
│
├─ message_start → 重置 currentMessageUsage
├─ content_block → 文本/工具调用/thinking
├─ message_delta → 累加使用量
├─ message_stop → 合并 totalUsage
│
▼
工具调用分发
│
├─ checkPermissions(input, context) → allow/ask/deny
├─ validateInput(input, context) → ValidationResult
├─ tool.call(input, context, canUseTool, ...) → ToolResult
│
▼
结果处理
│
├─ 成本跟踪：addToTotalSessionCost()
├─ 历史记录：recordTranscript()
├─ 预算检查：checkTokenBudget() (90% 阈值 + 递减检测)
│
▼
yield SDKMessage → UI 渲染